Struct KeyVault 

pub struct KeyVault { /* private fields */ }

Holds repository key material and provides all key-dependent operations.

Security

This is the ONLY struct that holds key material. The raw bytes never leave this struct — all operations are provided as methods. External crates receive only derived keys (SecretKey) or operation handles (CommitReader).

Two modes:

• RootKey (new): full read/write, can seal new commits
• ContentKey (from_content_key): scoped read-only, single commit

Implementations

impl KeyVault

pub fn new(root_key: [u8; 32]) -> CryptoResult<Self>

Construct a root-key vault from raw key bytes.

Security

The root key grants full read/write access to the entire repository history. After this call, the caller should zero the raw bytes. The vault takes ownership of key material from this point forward.

pub fn from_content_key(content_key: ContentKey) -> Self

Construct a content-key vault for scoped read-only access.

The content key grants access to a single commit’s objects (metadata, shards, manifest) but cannot seal new commits or access derived keyring keys. Used for --content-key clone/fork paths.

pub fn is_content_key_mode(&self) -> bool

Returns true if this vault is in content-key (read-only) mode.

pub fn open_commit( &self, blob: &EncryptedCommit, ) -> CryptoResult<(Vec<u8>, CommitReader)>

Decrypt a commit blob, returning plaintext and a session handle.

Works in both modes:

• RootKey: decrypts the VD01 envelope and derives the content key
• ContentKey: decrypts the envelope body using the content key directly

The returned CommitReader holds a per-commit derived content key for decrypting the commit’s metadata and shards.

pub fn seal_commit(&self, plaintext: &[u8]) -> CryptoResult<EncryptedCommit>

Encrypt a commit with envelope format (VD01), generating a fresh nonce.

Requires root-key mode.

pub fn seal_commit_with_nonce( &self, plaintext: &[u8], nonce: &KeyNonce, ) -> CryptoResult<EncryptedCommit>

Encrypt a commit with envelope format using a pre-derived nonce.

Requires root-key mode.

pub fn derive_commit_key(&self) -> CryptoResult<(ContentKey, KeyNonce)>

Derive the per-commit content key for a new commit (used during seal).

Returns (ContentKey, KeyNonce) — the nonce is embedded in the envelope. Requires root-key mode.

pub fn index_key(&self) -> CryptoResult<&SecretKey>

Key for encrypting/decrypting the index file.

Requires root-key mode (keyring not available in content-key mode).

pub fn stash_key(&self) -> CryptoResult<&SecretKey>

Key for encrypting/decrypting stash entries.

Requires root-key mode.

pub fn staged_key(&self) -> CryptoResult<&SecretKey>

Key for encrypting/decrypting staged blobs.

Requires root-key mode.

pub fn commits_key(&self) -> CryptoResult<&SecretKey>

Key for encrypting/decrypting commits (used by seal pipeline).

Requires root-key mode.

pub fn metadata_key(&self) -> CryptoResult<&SecretKey>

Key for encrypting/decrypting metadata bundles.

Requires root-key mode.

pub fn content_key(&self) -> CryptoResult<&SecretKey>

Key for encrypting/decrypting content (file data in shards).

Requires root-key mode.

pub fn keyring(&self) -> CryptoResult<&KeyRing>

Access the full keyring (for operations that need multiple derived keys).

Requires root-key mode.

pub fn decrypt_blob(&self, blob: &[u8], aad: &[u8]) -> CryptoResult<Vec<u8>>

Decrypt a blob with VD01 envelope format.

Requires root-key mode.

pub fn decrypt_blob_raw(&self, blob: &[u8], aad: &[u8]) -> CryptoResult<Vec<u8>>

Decrypt a blob to raw bytes with VD01 envelope format.

Derives content key from the embedded envelope nonce. Requires root-key mode.

pub fn seal_metadata(&self, plaintext: &[u8]) -> CryptoResult<EncryptedMetadata>

Encrypt metadata with the root key (AAD_METADATA baked in).

Used as the fallback when no per-commit content key is available (e.g., merge commits). Requires root-key mode.

pub fn seal_metadata_with_key( &self, key: &ContentKey, plaintext: &[u8], ) -> CryptoResult<EncryptedMetadata>

Encrypt metadata with a content key (AAD_METADATA baked in).

Used when a per-commit content key is available (normal commit path). Works in both root-key and content-key modes (uses the provided key, not the vault’s root key).

pub fn seal_shard(&self, plaintext: &[u8]) -> CryptoResult<EncryptedShard>

Encrypt shard data with the root key (AAD_SHARD baked in).

Requires root-key mode.

pub fn unseal_shard(&self, blob: &EncryptedShard) -> CryptoResult<Vec<u8>>

Decrypt shard data encrypted with the root key (AAD_SHARD baked in).

Requires root-key mode.

pub fn unseal_commit_with_nonce( &self, blob: &[u8], ) -> CryptoResult<(Vec<u8>, KeyNonce)>

Decrypt a commit blob returning plaintext and envelope nonce.

Requires root-key mode.

pub fn derive_scoped_key(&self, scope: &str) -> CryptoResult<ContentKey>

Derive a scoped content key from the root key.

Requires root-key mode.

pub fn repo_secret_fallback(&self) -> CryptoResult<SecretKey>

Derive a deterministic repo secret from the root key via HKDF.

Requires root-key mode.

Trait Implementations

impl Debug for KeyVault

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for KeyVault

fn drop(&mut self)

Executes the destructor for this type.