Skip to content

vox-secrets API Reference (generated)

Crate: vox-secrets · Version: 0.6.0 · Target: Library (lib.rs)

Clavis: central secret resolution and OS-keyring vault, from the Vox project.

Secret resolution + redaction (env, vault, infisical, vox-vault backends).

FeatureDefault / Enables
default—
secrets-infisical—
secrets-vault—
DependencyKind
vox-bounded-fsNormal
vox-cryptoNormal
ModuleDescription
backend—
errors—
lifecycle—
policy—
redact—
resolver—
sources—
spec—
StructDescription
SecretStatusRowA redaction-safe summary row for one managed secret. SECURITY: every field here is non-sensitive presence/metadata. The actual secret value is NEVER included — only the head4…tail2 redacted preview from [ResolvedSecret::redacted]. Safe to serialize across an IPC / GUI boundary.
ImportEnvEntryOne managed secret recognised inside a .env file during import. SECURITY: carries only the source key NAME, the canonical env it maps to, and a head4…tail2 redacted preview of the value — NEVER the raw value.
ImportEnvResultResult of an .env import (dry-run or applied). SECURITY: applied == false means a dry-run that only reports recognised key NAMES; applied == true means the values were written to the vault and only a count is returned. No raw value is ever surfaced.
EnumDescription
BackendMode—
FunctionDescription
from_env—
resolve_secret—
store_secretPersist a managed secret to the Clavis vault at runtime (account/profile-scoped). Writes the plaintext into the cloudless vault keyed by the secret’s canonical env name under the active VOX_ACCOUNT_ID. Pass profile to write a profile-scoped override; None writes the account-level canonical record. # Errors Returns [SecretError] if the vault backend cannot be initialized (e.g. the keyring-backed master key is unavailable) or the write fails.
secret_id_for_canonical_envFind a managed secret by its canonical environment name. This is the shared lookup used by every user-facing secret writer so the CLI and GUI cannot drift from the registry metadata.
delete_secretDelete a managed secret from the active Clavis account. The caller supplies a registry-defined [SecretId], preventing arbitrary vault keys from becoming an alternate secret-management surface. # Errors Returns [SecretError] when the Clavis vault cannot be initialized or the delete operation fails.
resolve_secret_for_cli—
resolve_clavis_uriResolve a portable clavis://<provider>/<key> URI reference (CLAVIS-02).
resolve_secret_with_context—
resolve_env_only—
set_registry_token—
get_registry_token—
get_registry_usernameRead the username (e.g. GitHub login) stored alongside a registry token.
remove_registry_tokenRemove a registry token from both the secure store and auth.json. Returns true if an entry existed. Never returns the token material.
migrate_auth_store_to_secure_store—
list_secret_statusBuild a redaction-safe status row for every real (non config-only) managed secret. Iterates [all_specs], filters out operator-tuning config, and resolves each. The returned rows carry only presence + a redacted preview.
active_resolve_profileThe currently-active secret resolution profile, derived from VOX_SECRETS_PROFILE (mirrors the precedence in [resolve_secret]). Non-sensitive — exposes only the profile selector, never any material.
backend_unavailable_detailProbe whether the active secrets backend is reachable. Resolves managed specs until one reports [ResolutionStatus::BackendUnavailable]; returns the first such backend detail (if any). Mirrors the logic behind the CLI vox secrets backend-status command. Never exposes secret material.
countNumber of managed secrets recognised / imported.
import_env_from_pathParse a .env file and either preview (dry-run) or import its managed secrets into the Clavis vault. Single source of truth shared by the CLI vox secrets import-env command and the GUI import_env Tauri command. Lines are simple KEY=VALUE pairs; comments (#) and blanks are skipped, and surrounding quotes are stripped. Only keys matching a managed [SecretSpec] (canonical, alias, or deprecated alias) are considered. When apply is false the values are read but NEVER stored or returned — only key names + a redacted preview. When apply is true the values are written to the vault and the same redaction-safe entries are returned. # Errors Returns [SecretError] if the file cannot be read, or (when apply is true) if the vault backend cannot be initialized or a write fails.
ConstantDescription
OPERATOR_SECRETS_CUTOVER_PHASE—
OPERATOR_SECRETS_MIGRATION_PHASE—
OPERATOR_SECRETS_HARD_CUT—
OPERATOR_SECRETS_AUTO_PREFER_VAULT—
OPERATOR_SECRETS_KEK_REF—
OPERATOR_SECRETS_KEK_VERSION—
OPERATOR_SECRETS_AUTO_VAULT—
OPERATOR_SECRETS_VAULT_URL—
OPERATOR_SECRETS_VAULT_PATH—
OPERATOR_SECRETS_VAULT_TOKEN—
OPERATOR_ACCOUNT_ID—
OPERATOR_SECRETS_PROFILE—
OPERATOR_SECRETS_BACKEND—
OPERATOR_INFISICAL_TOKEN—
OPERATOR_INFISICAL_SERVICE_TOKEN—
OPERATOR_VAULT_ADDR—
OPERATOR_VAULT_TOKEN—
OPERATOR_TURSO_URL—
OPERATOR_TURSO_TOKEN—
OPERATOR_SCIENTIA_CROSSREF_MAILTO—
OPERATOR_SCHOLARLY_ADAPTER—
OPERATOR_SCHOLARLY_JOB_LOCK_OWNER—
OPERATOR_ZENODO_HTTP_MAX_ATTEMPTS—
OPERATOR_ZENODO_API_BASE—
OPERATOR_OPENREVIEW_HTTP_MAX_ATTEMPTS—
OPERATOR_ZENODO_STAGING_DIR—
OPERATOR_ZENODO_UPLOAD_ALLOWLIST—
OPERATOR_SYNDICATION_TEMPLATE_PROFILE—
OPERATOR_NEWS_PUBLISH_ARMED—
OPERATOR_NEWS_SITE_BASE_URL—
OPERATOR_NEWS_RSS_FEED_PATH—
OPERATOR_SCIENTIA_RESEARCH_MESH_INTAKE_WRITER—
OPERATOR_SCIENTIA_RESEARCH_MESH_CONSUMER_POLL—
OPERATOR_SCIENTIA_RESEARCH_MESH_CONSUMER_POLL_INTERVAL_MS—
OPERATOR_TUNING_ENVSArray of system operator tuning environment variables.
Dependency Topology, diagram 115 nodes, 14 edges: vox-secrets → vox-bounded-fs; vox-secrets → vox-crypto; vox-actor-runtime → vox-secrets; vox-cli → vox-secrets; vox-cli-ci → vox-secrets; vox-cli-core → vox-secrets; vox-cli-research → vox-secrets; vox-cli-review → vox-secrets; vox-code-audit → vox-secrets; vox-codegen → vox-sec…vox-secretsvox-bounded-fsvox-cryptovox-actor-runtimevox-clivox-cli-civox-cli-corevox-cli-researchvox-cli-reviewvox-code-auditvox-codegenvox-codegen-tsvox-compilervox-configvox-db
Diagram source
graph {
direction: right
node vox_secrets: "vox-secrets"
node vox_bounded_fs: "vox-bounded-fs"
vox_secrets -> vox_bounded_fs
node vox_crypto: "vox-crypto"
vox_secrets -> vox_crypto
node vox_actor_runtime: "vox-actor-runtime"
vox_actor_runtime -> vox_secrets
node vox_cli: "vox-cli"
vox_cli -> vox_secrets
node vox_cli_ci: "vox-cli-ci"
vox_cli_ci -> vox_secrets
node vox_cli_core: "vox-cli-core"
vox_cli_core -> vox_secrets
node vox_cli_research: "vox-cli-research"
vox_cli_research -> vox_secrets
node vox_cli_review: "vox-cli-review"
vox_cli_review -> vox_secrets
node vox_code_audit: "vox-code-audit"
vox_code_audit -> vox_secrets
node vox_codegen: "vox-codegen"
vox_codegen -> vox_secrets
node vox_codegen_ts: "vox-codegen-ts"
vox_codegen_ts -> vox_secrets
node vox_compiler: "vox-compiler"
vox_compiler -> vox_secrets
node vox_config: "vox-config"
vox_config -> vox_secrets
node vox_db: "vox-db"
vox_db -> vox_secrets
}
Consumer CrateRole
vox-actor-runtimeDirect workspace dependent
vox-cliDirect workspace dependent
vox-cli-ciDirect workspace dependent
vox-cli-coreDirect workspace dependent
vox-cli-researchDirect workspace dependent
vox-cli-reviewDirect workspace dependent
vox-code-auditDirect workspace dependent
vox-codegenDirect workspace dependent
vox-codegen-tsDirect workspace dependent
vox-compilerDirect workspace dependent
vox-configDirect workspace dependent
vox-dbDirect workspace dependent
vox-gamifyDirect workspace dependent
vox-guiDirect workspace dependent
vox-integration-testsDirect workspace dependent
vox-lspDirect workspace dependent
vox-ml-cliDirect workspace dependent
vox-openclaw-runtimeDirect workspace dependent
vox-orchestratorDirect workspace dependent
vox-orchestrator-dDirect workspace dependent
vox-orchestrator-mcpDirect workspace dependent
vox-orchestrator-modelsDirect workspace dependent
vox-plugin-hostDirect workspace dependent
vox-plugin-mens-candle-cudaDirect workspace dependent
vox-plugin-mens-candle-metalDirect workspace dependent
vox-plugin-populi-meshDirect workspace dependent
vox-plugin-speechDirect workspace dependent
vox-populiDirect workspace dependent
vox-publisherDirect workspace dependent
vox-research-shimDirect workspace dependent
vox-scientiaDirect workspace dependent
vox-searchDirect workspace dependent
vox-speechDirect workspace dependent
vox-sqlDirect workspace dependent
vox-test-harnessDirect workspace dependent
voxupDirect workspace dependent
KindSymbolSignatureSourceDescription
enumBackendModepub enum BackendModecrates/vox-secrets/src/lib.rs#L167-L173—
fnfrom_envpub fn from_env() -> Selfcrates/vox-secrets/src/lib.rs#L218-L230—
fnresolve_secretpub fn resolve_secret(id: SecretId) -> ResolvedSecretcrates/vox-secrets/src/lib.rs#L242-L244—
fnstore_secretpub fn store_secret(crates/vox-secrets/src/lib.rs#L255Persist a managed secret to the Clavis vault at runtime (account/profile-scoped). Writes the plaintext into the cloudless vault keyed by the secret’s canonical env name under the active VOX_ACCOUNT_ID. Pass profile to write a profile-scoped override; None writes the account-level canonical record. # Errors Returns [SecretError] if the vault backend cannot be initialized (e.g. the keyring-backed master key is unavailable) or the write fails.
fnsecret_id_for_canonical_envpub fn secret_id_for_canonical_env(canonical_env: &str) -> Option<SecretId>crates/vox-secrets/src/lib.rs#L279-L284Find a managed secret by its canonical environment name. This is the shared lookup used by every user-facing secret writer so the CLI and GUI cannot drift from the registry metadata.
fndelete_secretpub fn delete_secret(id: SecretId) -> Result<bool, SecretError>crates/vox-secrets/src/lib.rs#L294-L297Delete a managed secret from the active Clavis account. The caller supplies a registry-defined [SecretId], preventing arbitrary vault keys from becoming an alternate secret-management surface. # Errors Returns [SecretError] when the Clavis vault cannot be initialized or the delete operation fails.
fnresolve_secret_for_clipub fn resolve_secret_for_cli(id: SecretId) -> ResolvedSecretcrates/vox-secrets/src/lib.rs#L299-L301—
fnresolve_clavis_uripub fn resolve_clavis_uri(uri: &str) -> Result<ResolvedSecret, String>crates/vox-secrets/src/lib.rs#L304-L307Resolve a portable clavis://<provider>/<key> URI reference (CLAVIS-02).
fnresolve_secret_with_contextpub fn resolve_secret_with_context(id: SecretId, context: &str) -> ResolvedSecretcrates/vox-secrets/src/lib.rs#L310-L329—
fnresolve_env_onlypub fn resolve_env_only(id: SecretId) -> ResolvedSecretcrates/vox-secrets/src/lib.rs#L379-L381—
fnset_registry_tokenpub fn set_registry_token(crates/vox-secrets/src/lib.rs#L464—
fnget_registry_tokenpub fn get_registry_token(registry: &str) -> Option<String>crates/vox-secrets/src/lib.rs#L473-L476—
fnget_registry_usernamepub fn get_registry_username(registry: &str) -> Option<String>crates/vox-secrets/src/lib.rs#L480-L482Read the username (e.g. GitHub login) stored alongside a registry token.
fnremove_registry_tokenpub fn remove_registry_token(registry: &str) -> Result<bool, SecretError>crates/vox-secrets/src/lib.rs#L486-L488Remove a registry token from both the secure store and auth.json. Returns true if an entry existed. Never returns the token material.
fnmigrate_auth_store_to_secure_storepub fn migrate_auth_store_to_secure_store() -> Result<usize, SecretError>crates/vox-secrets/src/lib.rs#L490-L492—
structSecretStatusRowpub struct SecretStatusRowcrates/vox-secrets/src/lib.rs#L574-L592A redaction-safe summary row for one managed secret. SECURITY: every field here is non-sensitive presence/metadata. The actual secret value is NEVER included — only the head4…tail2 redacted preview from [ResolvedSecret::redacted]. Safe to serialize across an IPC / GUI boundary.
fnlist_secret_statuspub fn list_secret_status() -> Vec<SecretStatusRow>crates/vox-secrets/src/lib.rs#L598-L620Build a redaction-safe status row for every real (non config-only) managed secret. Iterates [all_specs], filters out operator-tuning config, and resolves each. The returned rows carry only presence + a redacted preview.
fnactive_resolve_profilepub fn active_resolve_profile() -> ResolveProfilecrates/vox-secrets/src/lib.rs#L627-L629The currently-active secret resolution profile, derived from VOX_SECRETS_PROFILE (mirrors the precedence in [resolve_secret]). Non-sensitive — exposes only the profile selector, never any material.
fnbackend_unavailable_detailpub fn backend_unavailable_detail() -> Option<String>crates/vox-secrets/src/lib.rs#L637-L645Probe whether the active secrets backend is reachable. Resolves managed specs until one reports [ResolutionStatus::BackendUnavailable]; returns the first such backend detail (if any). Mirrors the logic behind the CLI vox secrets backend-status command. Never exposes secret material.
structImportEnvEntrypub struct ImportEnvEntrycrates/vox-secrets/src/lib.rs#L652-L659One managed secret recognised inside a .env file during import. SECURITY: carries only the source key NAME, the canonical env it maps to, and a head4…tail2 redacted preview of the value — NEVER the raw value.
structImportEnvResultpub struct ImportEnvResultcrates/vox-secrets/src/lib.rs#L667-L672Result of an .env import (dry-run or applied). SECURITY: applied == false means a dry-run that only reports recognised key NAMES; applied == true means the values were written to the vault and only a count is returned. No raw value is ever surfaced.
fncountpub fn count(&self) -> usizecrates/vox-secrets/src/lib.rs#L677-L679Number of managed secrets recognised / imported.
fnimport_env_from_pathpub fn import_env_from_path(crates/vox-secrets/src/lib.rs#L698Parse a .env file and either preview (dry-run) or import its managed secrets into the Clavis vault. Single source of truth shared by the CLI vox secrets import-env command and the GUI import_env Tauri command. Lines are simple KEY=VALUE pairs; comments (#) and blanks are skipped, and surrounding quotes are stripped. Only keys matching a managed [SecretSpec] (canonical, alias, or deprecated alias) are considered. When apply is false the values are read but NEVER stored or returned — only key names + a redacted preview. When apply is true the values are written to the vault and the same redaction-safe entries are returned. # Errors Returns [SecretError] if the file cannot be read, or (when apply is true) if the vault backend cannot be initialized or a write fails.
traitbackend::SecretBackendpub trait SecretBackend: Send + Synccrates/vox-secrets/src/backend/mod.rs#L7-L24—
structbackend::NoopBackendpub struct NoopBackendcrates/vox-secrets/src/backend/mod.rs#L26—
structbackend::UnavailableBackendpub struct UnavailableBackendcrates/vox-secrets/src/backend/mod.rs#L52-L54—
enumerrors::SecretErrorpub enum SecretErrorcrates/vox-secrets/src/errors.rs#L4-L15—
enumlifecycle::RotationHealthpub enum RotationHealthcrates/vox-secrets/src/lifecycle.rs#L9-L30Rotation health status computed from [LifecycleMeta] and secret age (CLAVIS-06).
fnlifecycle::evaluate_lifecycle_healthpub const fn evaluate_lifecycle_health(meta: LifecycleMeta, age_days: u32) -> RotationHealthcrates/vox-secrets/src/lifecycle.rs#L34-L66Evaluate [RotationHealth] for a secret given its [LifecycleMeta] and age in days (CLAVIS-06).
structlifecycle::ValidationProbeSpecpub struct ValidationProbeSpeccrates/vox-secrets/src/lifecycle.rs#L70-L77Read-only HTTP validation probe descriptor for vox secrets verify (CLAVIS-06).
fnlifecycle::validation_probe_forpub fn validation_probe_for(id: SecretId) -> Option<ValidationProbeSpec>crates/vox-secrets/src/lifecycle.rs#L81-L98Return the read-only validation probe descriptor for a [SecretId], if supported (CLAVIS-06).
structlifecycle::RotationRunbookpub struct RotationRunbookcrates/vox-secrets/src/lifecycle.rs#L102-L108Structured 3-step emergency/scheduled rotation runbook (revoke -> rotate -> redistribute, CLAVIS-07).
fnlifecycle::rotation_runbook_forpub fn rotation_runbook_for(id: SecretId) -> RotationRunbookcrates/vox-secrets/src/lifecycle.rs#L112-L140Generate the canonical revoke -> rotate -> redistribute runbook for id (CLAVIS-07).
structlifecycle::PullSyncManifestpub struct PullSyncManifestcrates/vox-secrets/src/lifecycle.rs#L144-L147Pull-based vault synchronization manifest descriptor (CLAVIS-08).
fnlifecycle::prepare_pull_sync_manifestpub fn prepare_pull_sync_manifest(profile: Profile) -> PullSyncManifestcrates/vox-secrets/src/lifecycle.rs#L151-L164Enumerate all shareable, persistable account secrets eligible for pull-based encrypted vault sync (CLAVIS-08).
enumpolicy::MissingBehaviorpub enum MissingBehaviorcrates/vox-secrets/src/policy.rs#L2-L6—
structpolicy::SecretPolicypub struct SecretPolicycrates/vox-secrets/src/policy.rs#L9-L12—
fnpolicy::required_failpub const fn required_fail() -> Selfcrates/vox-secrets/src/policy.rs#L16-L21—
fnpolicy::optional_skippub const fn optional_skip() -> Selfcrates/vox-secrets/src/policy.rs#L24-L29—
fnredact::redact_secrets_from_valuepub fn redact_secrets_from_value(value: &Value, patterns: &[&str]) -> Valuecrates/vox-secrets/src/redact.rs#L16-L33Recursively scrub all known secret values from a JSON Value. patterns is a slice of plaintext secret values from the caller. The caller must obtain these from resolved.expose() and is responsible for not retaining them beyond this call’s scope. Returns a new Value with all occurrences replaced by "[REDACTED]". # Panics Does not panic. If AhoCorasick construction fails (empty patterns or pattern too long), returns the input unchanged.
fnredact::contains_secret_materialpub fn contains_secret_material(text: &str, patterns: &[&str]) -> boolcrates/vox-secrets/src/redact.rs#L37-L51Check if a string contains any of the provided known-secret patterns. Used for the audit-log safety check (C1 fix).
enumresolver::ResolveProfilepub enum ResolveProfilecrates/vox-secrets/src/resolver.rs#L6-L12—
fnresolver::is_strictpub const fn is_strict(self) -> boolcrates/vox-secrets/src/resolver.rs#L16-L21—
fnresolver::as_strpub const fn as_str(self) -> &'static strcrates/vox-secrets/src/resolver.rs#L24-L31—
structresolver::ResolveOptionspub struct ResolveOptionscrates/vox-secrets/src/resolver.rs#L35-L41—