Crate revault_vault_api

Expand description

Native Vault and Session Agent support for reVault.

This crate includes the Session Agent, a local service that reduces password prompts by keeping lockbox content keys in a short-lived, in-memory process cache.

The Session Agent is started as a platform-specific local service (Unix socket on Unix, named pipe on Windows), and is used automatically by lockbox operations when a secret-dependent command needs a cached key. Its cache uses secure frames for key-bearing traffic, supports TTL-based expiry, supports explicit session management commands, and automatically clears cache entries during suspend events.

Key public entry points:

serve_agent starts the Session Agent in-process.
get, put, forget, forget_all, list, and stop operate the session cache.
begin_secret_activity and SecretActivityGuard support suspend-protection and optional process termination behavior.
local_vault manages the on-disk vault and metadata outside the agent cache.

For the runtime behavior, command integration, and security settings, see the project documentation in docs/lockbox_session_agent.md.

§Example

use revault_vault_api::{SecretString, VaultDirectory};

let password = SecretString::try_from_slice(b"correct horse")?;
let root = std::env::temp_dir().join("my-revault-profile");
let vault = VaultDirectory::open_or_create(root, &password)?;
println!("vault structure version: {}", vault.structure_version()?);

See the reVault repository README for the project overview, installation instructions, and complete examples.

Structs§

AccessSlotLabel: Local-only label for one access slot in a remembered lockbox.
AgentClient: Content-key store backed by the platform Session Agent.
AgentSleepSupport: Platform sleep and suspend capabilities used by the Session Agent.
CachedLockbox: Metadata describing a lockbox whose content key is cached by the agent.
KnownLockbox: Lockbox path remembered by the local vault for diagnostics and bulk access refresh operations.
NoopStore: Content-key store that never retains keys.
PlatformSecretStoreStatus: Current platform credential store state for the default Vault.
ProfileGeneration: One generation of a vault profile.
ProfileHistory: Versioned profile history for one vault profile.
ReadOnlyVaultDirectory: Read-only view of encrypted vault metadata.
SecretActivityGuard: Registration guard for a command that may hold decrypted secrets in memory.
SecretString: Secure string type re-exported from revault_lockbox_api. UTF-8 secret stored in guarded, zeroizing memory.
SecretVec: Secure string type re-exported from revault_lockbox_api. Variable-length byte sequence stored in guarded, zeroizing memory.
StoredContact: Contact entry stored in a VaultDirectory.
Vault: High-level lockbox helper that integrates open operations with a key cache.
VaultBackupManifest: Metadata stored in an encrypted vault backup archive.
VaultDirectory: Password-protected vault file for native reVault metadata.

Enums§

AutoOpenScope: Scope controlled by the session auto-open setting.
KeyFormat: Supported contact key serialization formats.
ProfileGenerationStatus: Lifecycle state of one Profile key generation.
SecretActivityKind: Category of an operation that temporarily requires secret access.

Constants§

CURRENT_VAULT_STRUCTURE_VERSION: Current on-disk structure version for records stored inside the local vault.
FINGERPRINT_CODE_96_LEN: Number of bytes encoded by the short, human-comparable fingerprint code.
PUBLIC_KEY_FINGERPRINT_LEN: Number of SHA-256 prefix bytes used for a contact public-key fingerprint.

Traits§

ContentKeyStore: Storage backend for opened Lockbox content keys.

Functions§

agent_log_destination: Describes where Session Agent events are currently written.
agent_log_path: Returns the file used when agent events cannot be sent to the platform log.
agent_sleep_support: Returns sleep/suspend capabilities compiled for the current platform.
auto_open_scope: Returns the effective automatic-open scope for the default local vault.
backup_default_vault: Writes a consistent encrypted backup archive for the default local vault.
begin_secret_activity: Registers the current process as running a high-level secret activity.
decode_fingerprint_crockford_96: Decodes a 96-bit lower/upper-case Crockford fingerprint code.
decode_fingerprint_hex: Decodes a public-key fingerprint written as hex, with optional separators.
decode_hex: Decodes hexadecimal text into bytes.
default_vault_dir: Returns the default directory for the local vault.
default_vault_path: Returns the default path to the local vault file.
disable_platform_secret_store: Disables platform credential store lookup for the default Vault.
enable_platform_secret_store: Enables platform credential store lookup for the default Vault.
encode_hex: Encodes bytes as lowercase hexadecimal text.
export_private_key: Exports a contact private key in the requested format.
export_public_key: Exports a contact public key in the requested format.
forget: Removes one content key from the platform agent.
forget_all: Removes all content keys from the platform agent.
forget_owner_signing_key: Removes one cached owner-signing key.
forget_platform_vault_password: Removes the default Vault passphrase from the platform credential store.
forget_vault_unlock_key: Removes the cached vault unlock secret for one vault.
format_fingerprint_crockford_96: Formats the first 96 bits of a fingerprint as lower-case Crockford Base32.
format_fingerprint_crockford_96_reading: Returns a lower-case word reading for a Crockford fingerprint code.
format_fingerprint_hex_pairs: Formats fingerprint bytes as lowercase space-separated hexadecimal pairs.
get: Reads a cached content key from the platform agent.
get_owner_signing_key: Reads one cached owner-signing key for a specific vault profile.
get_platform_vault_password: Loads the default Vault passphrase from the platform credential store.
get_platform_vault_password_for: Loads the passphrase for the Vault directory at path_to.
get_vault_unlock_key: Reads the cached vault unlock secret for a specific vault profile.
import_private_key: Imports a contact private key from PEM, JWK, JWKS-compatible JWK, or hex.
import_private_key_file: Reads and imports a contact private key from a file.
import_public_key: Imports a contact public key from Lockbox PEM, JWK, JWKS, or raw hex.
is_running: Returns true when the platform agent transport is currently reachable.
list: Lists cached lockboxes known to the platform agent.
local_vault: Creates a Vault backed by the default platform agent.
platform_secret_store_disabled: Returns true when platform credential store lookup should not be attempted.
platform_secret_store_status: Returns the platform credential store status for the default Vault.
public_key_fingerprint: Returns the stable fingerprint for a contact public key.
put: Stores a content key in the platform agent.
put_owner_signing_key: Caches an owner-signing key that was already loaded by the normal vault flow. The key remains in secure memory while it crosses the local IPC boundary and inside the agent cache.
put_platform_vault_password: Stores the default Vault passphrase in the platform credential store.
put_vault_unlock_key: Caches a vault unlock secret obtained through the normal vault flow.
restore_default_vault: Restores the default local vault from an encrypted backup archive.
serve_agent: Runs the platform content-key agent in the current process.
session_agent_dir: Returns the platform-specific directory used for Session Agent state.
set_auto_open_scope: Persists the automatic-open scope for the default local vault.
start: Starts the Session Agent if it is not already running.
stop: Stops the platform agent after clearing all cached content keys.
validate_vault_record_name: Validates a profile or contact name used by the native vault.
verify_agent_transport_security: Verifies that the current platform agent transport is configured securely.

Type Aliases§

LocalVault: Vault using the default platform agent as its content-key store.