void_crypto/

vault.rs

//! KeyVault: opaque custodian of repository key material.
//!
//! # Security Architecture
//!
//! This is the **ONLY** struct in the entire codebase that holds key material.
//! The raw bytes never leave this struct — all operations are provided as methods.
//! External crates receive only:
//! - Derived keys (`&SecretKey`) for purpose-specific encryption
//! - Operation handles (`CommitReader`) for per-commit decryption
//! - Encrypted/decrypted data from vault operations
//!
//! # Modes
//!
//! - **RootKey**: Full read/write access. Can seal and open commits, derive keys,
//!   and perform all encryption operations. Created via `KeyVault::new()`.
//! - **ContentKey**: Scoped read-only access to a single commit's objects. Can
//!   open commits and decrypt metadata/shards, but cannot seal new objects or
//!   access derived keyring keys. Created via `KeyVault::from_content_key()`.
//!
//! # ring-inspired pattern
//!
//! Following the `ring` crypto library's approach:
//! - Key material enters the vault once and is **consumed** into an opaque struct
//! - No `as_bytes()`, no `into_inner()`, no escape hatch for key material
//! - The vault provides **operations** (open, seal, derive), never key accessors
//! - `CommitReader` mirrors ring's `OpeningKey` — a per-operation handle

use zeroize::Zeroize;

use crate::aead::{AAD_COMMIT, AAD_METADATA, AAD_SHARD};
use crate::blob_types::{EncryptedCommit, EncryptedMetadata, EncryptedShard};
use crate::envelope::{encrypt_with_envelope, generate_key_nonce};
use crate::kdf::{ContentKey, KeyNonce, KeyRing, SecretKey};
use crate::reader::CommitReader;
use crate::{CryptoError, CryptoResult};

/// Internal mode of the vault — determines which operations are available.
enum VaultMode {
    /// Full access: can seal, open, derive, and access all keyring keys.
    RootKey {
        root_key: [u8; 32],
        keyring: KeyRing,
    },
    /// Scoped read-only: can open a single commit and decrypt its objects.
    ContentKey {
        content_key: ContentKey,
    },
}

/// 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
pub struct KeyVault {
    mode: VaultMode,
}

impl KeyVault {
    /// 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 new(root_key: [u8; 32]) -> CryptoResult<Self> {
        let keyring = KeyRing::from_root(&root_key)?;
        Ok(Self {
            mode: VaultMode::RootKey { root_key, keyring },
        })
    }

    /// 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 from_content_key(content_key: ContentKey) -> Self {
        Self {
            mode: VaultMode::ContentKey { content_key },
        }
    }

    /// Construct a content-key vault from raw bytes.
    ///
    /// Convenience wrapper for SDK consumers who have content key bytes
    /// but not a `ContentKey` type.
    pub fn from_content_key_bytes(bytes: [u8; 32]) -> Self {
        Self::from_content_key(ContentKey::new(bytes))
    }

    /// Returns `true` if this vault is in content-key (read-only) mode.
    pub fn is_content_key_mode(&self) -> bool {
        matches!(self.mode, VaultMode::ContentKey { .. })
    }

    // =========================================================================
    // Helper: require root key
    // =========================================================================

    /// Extract a reference to the root key, or error if in content-key mode.
    fn require_root_key(&self) -> CryptoResult<&[u8; 32]> {
        match &self.mode {
            VaultMode::RootKey { root_key, .. } => Ok(root_key),
            VaultMode::ContentKey { .. } => Err(CryptoError::ReadOnlyVault),
        }
    }

    /// Extract a reference to the keyring, or error if in content-key mode.
    fn require_keyring(&self) -> CryptoResult<&KeyRing> {
        match &self.mode {
            VaultMode::RootKey { keyring, .. } => Ok(keyring),
            VaultMode::ContentKey { .. } => Err(CryptoError::ReadOnlyVault),
        }
    }

    // =========================================================================
    // Commit operations
    // =========================================================================

    /// 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 open_commit(&self, blob: &EncryptedCommit) -> CryptoResult<(Vec<u8>, CommitReader)> {
        match &self.mode {
            VaultMode::RootKey { root_key, .. } => {
                CommitReader::open(root_key, blob.as_bytes())
            }
            VaultMode::ContentKey { content_key } => {
                let reader = CommitReader::from_content_key(*content_key);
                let (plaintext, _nonce) =
                    reader.decrypt_envelope_body(blob.as_bytes(), AAD_COMMIT)?;
                Ok((plaintext, reader))
            }
        }
    }

    /// Encrypt a commit with envelope format (VD01), generating a fresh nonce.
    ///
    /// Requires root-key mode.
    pub fn seal_commit(&self, plaintext: &[u8]) -> CryptoResult<EncryptedCommit> {
        let root_key = self.require_root_key()?;
        let nonce = generate_key_nonce();
        let bytes = encrypt_with_envelope(root_key, &nonce, plaintext, AAD_COMMIT)?;
        Ok(EncryptedCommit::from_bytes(bytes))
    }

    /// Encrypt a commit with envelope format using a pre-derived nonce.
    ///
    /// Requires root-key mode.
    pub fn seal_commit_with_nonce(
        &self,
        plaintext: &[u8],
        nonce: &KeyNonce,
    ) -> CryptoResult<EncryptedCommit> {
        let root_key = self.require_root_key()?;
        let bytes = encrypt_with_envelope(root_key, nonce, plaintext, AAD_COMMIT)?;
        Ok(EncryptedCommit::from_bytes(bytes))
    }

    /// 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 derive_commit_key(&self) -> CryptoResult<(ContentKey, KeyNonce)> {
        let root_key = self.require_root_key()?;
        let nonce = generate_key_nonce();
        let scope = format!("commit:{}", hex::encode(nonce.as_bytes()));
        let derived = crate::kdf::derive_scoped_key(root_key, &scope)?;
        Ok((ContentKey::new(derived), nonce))
    }

    // =========================================================================
    // Derived keys (purpose-specific, handed out to callers)
    // =========================================================================

    /// Key for encrypting/decrypting the index file.
    ///
    /// Requires root-key mode (keyring not available in content-key mode).
    pub fn index_key(&self) -> CryptoResult<&SecretKey> {
        Ok(&self.require_keyring()?.index)
    }

    /// Key for encrypting/decrypting stash entries.
    ///
    /// Requires root-key mode.
    pub fn stash_key(&self) -> CryptoResult<&SecretKey> {
        Ok(&self.require_keyring()?.stash)
    }

    /// Key for encrypting/decrypting staged blobs.
    ///
    /// Requires root-key mode.
    pub fn staged_key(&self) -> CryptoResult<&SecretKey> {
        Ok(&self.require_keyring()?.staged)
    }

    /// Key for encrypting/decrypting commits (used by seal pipeline).
    ///
    /// Requires root-key mode.
    pub fn commits_key(&self) -> CryptoResult<&SecretKey> {
        Ok(&self.require_keyring()?.commits)
    }

    /// Key for encrypting/decrypting metadata bundles.
    ///
    /// Requires root-key mode.
    pub fn metadata_key(&self) -> CryptoResult<&SecretKey> {
        Ok(&self.require_keyring()?.metadata)
    }

    /// Key for encrypting/decrypting content (file data in shards).
    ///
    /// Requires root-key mode.
    pub fn content_key(&self) -> CryptoResult<&SecretKey> {
        Ok(&self.require_keyring()?.content)
    }

    /// Access the full keyring (for operations that need multiple derived keys).
    ///
    /// Requires root-key mode.
    pub fn keyring(&self) -> CryptoResult<&KeyRing> {
        self.require_keyring()
    }

    // =========================================================================
    // Generic decryption (uses root key internally)
    // =========================================================================

    /// Decrypt a blob with VD01 envelope format.
    ///
    /// Requires root-key mode.
    pub fn decrypt_blob(&self, blob: &[u8], aad: &[u8]) -> CryptoResult<Vec<u8>> {
        let root_key = self.require_root_key()?;
        crate::decrypt_envelope(root_key, blob, aad)
            .map(|(plaintext, _nonce)| plaintext)
    }

    /// Decrypt a blob to raw bytes with VD01 envelope format.
    ///
    /// Derives content key from the embedded envelope nonce.
    /// Requires root-key mode.
    pub fn decrypt_blob_raw(
        &self,
        blob: &[u8],
        aad: &[u8],
    ) -> CryptoResult<Vec<u8>> {
        let root_key = self.require_root_key()?;
        use crate::kdf::derive_scoped_key;

        const ENVELOPE_HEADER_SIZE: usize = 4 + KeyNonce::SIZE;

        if blob.len() <= ENVELOPE_HEADER_SIZE || !blob.starts_with(crate::MAGIC_V1) {
            return Err(CryptoError::Decryption(
                "missing VD01 envelope header".into(),
            ));
        }

        let nonce = KeyNonce::from_bytes(&blob[4..ENVELOPE_HEADER_SIZE])
            .ok_or_else(|| CryptoError::Decryption(
                "invalid envelope nonce length".into(),
            ))?;
        let scope = format!("commit:{}", hex::encode(nonce.as_bytes()));
        let derived_key = derive_scoped_key(root_key, &scope)?;
        crate::decrypt(&derived_key, &blob[ENVELOPE_HEADER_SIZE..], aad)
    }

    // =========================================================================
    // Purpose-specific seal/unseal (no raw key parameters)
    // =========================================================================

    /// 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(&self, plaintext: &[u8]) -> CryptoResult<EncryptedMetadata> {
        let root_key = self.require_root_key()?;
        let bytes = crate::encrypt(root_key, plaintext, AAD_METADATA)?;
        Ok(EncryptedMetadata::from_bytes(bytes))
    }

    /// 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_metadata_with_key(&self, key: &ContentKey, plaintext: &[u8]) -> CryptoResult<EncryptedMetadata> {
        let bytes = crate::encrypt(key.as_bytes(), plaintext, AAD_METADATA)?;
        Ok(EncryptedMetadata::from_bytes(bytes))
    }

    /// Encrypt shard data with the root key (AAD_SHARD baked in).
    ///
    /// Requires root-key mode.
    pub fn seal_shard(&self, plaintext: &[u8]) -> CryptoResult<EncryptedShard> {
        let root_key = self.require_root_key()?;
        let bytes = crate::encrypt(root_key, plaintext, AAD_SHARD)?;
        Ok(EncryptedShard::from_bytes(bytes))
    }

    /// Decrypt shard data encrypted with the root key (AAD_SHARD baked in).
    ///
    /// Requires root-key mode.
    pub fn unseal_shard(&self, blob: &EncryptedShard) -> CryptoResult<Vec<u8>> {
        let root_key = self.require_root_key()?;
        crate::decrypt(root_key, blob.as_bytes(), AAD_SHARD)
    }

    /// Decrypt a commit blob returning plaintext and envelope nonce.
    ///
    /// Requires root-key mode.
    pub fn unseal_commit_with_nonce(&self, blob: &[u8]) -> CryptoResult<(Vec<u8>, KeyNonce)> {
        let root_key = self.require_root_key()?;
        crate::decrypt_envelope(root_key, blob, AAD_COMMIT)
    }

    /// Derive a scoped content key from the root key.
    ///
    /// Requires root-key mode.
    pub fn derive_scoped_key(&self, scope: &str) -> CryptoResult<ContentKey> {
        let root_key = self.require_root_key()?;
        let derived = crate::kdf::derive_scoped_key(root_key, scope)?;
        Ok(ContentKey::new(derived))
    }

    /// Derive a deterministic repo secret from the root key via HKDF.
    ///
    /// Requires root-key mode.
    pub fn repo_secret_fallback(&self) -> CryptoResult<SecretKey> {
        let root_key = self.require_root_key()?;
        Ok(SecretKey::new(
            crate::derive_key(root_key, "void-v1-repo-secret")
                .expect("HKDF derivation is infallible")
        ))
    }
}

impl Drop for KeyVault {
    fn drop(&mut self) {
        match &mut self.mode {
            VaultMode::RootKey { root_key, .. } => root_key.zeroize(),
            VaultMode::ContentKey { content_key } => content_key.zeroize(),
        }
    }
}

impl std::fmt::Debug for KeyVault {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match &self.mode {
            VaultMode::RootKey { .. } => {
                f.debug_struct("KeyVault")
                    .field("mode", &"RootKey [REDACTED]")
                    .finish()
            }
            VaultMode::ContentKey { .. } => {
                f.debug_struct("KeyVault")
                    .field("mode", &"ContentKey [REDACTED]")
                    .finish()
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{encrypt, AAD_SHARD};

    #[test]
    fn vault_new_and_derived_keys() {
        let root_key = crate::generate_key();
        let vault = KeyVault::new(root_key).unwrap();

        // Derived keys should all be different
        assert_ne!(vault.index_key().unwrap().as_bytes(), vault.stash_key().unwrap().as_bytes());
        assert_ne!(vault.stash_key().unwrap().as_bytes(), vault.staged_key().unwrap().as_bytes());
        assert_ne!(
            vault.index_key().unwrap().as_bytes(),
            vault.staged_key().unwrap().as_bytes()
        );
    }

    #[test]
    fn vault_open_commit_roundtrip() {
        let root_key = crate::generate_key();
        let vault = KeyVault::new(root_key).unwrap();

        let plaintext = b"commit data";
        let sealed = vault.seal_commit(plaintext).unwrap();

        let (decrypted, reader) = vault.open_commit(&sealed).unwrap();
        assert_eq!(decrypted, plaintext);

        // Content key should differ from root key (envelope format)
        assert_ne!(reader.content_key().as_bytes(), &root_key);
    }

    #[test]
    fn vault_seal_then_decrypt_shard() {
        let root_key = crate::generate_key();
        let vault = KeyVault::new(root_key).unwrap();

        let commit_data = b"commit";
        let sealed = vault.seal_commit(commit_data).unwrap();
        let (_decrypted, reader) = vault.open_commit(&sealed).unwrap();

        // Encrypt a shard with the content key
        let shard_data = b"shard content";
        let shard_blob =
            encrypt(reader.content_key().as_bytes(), shard_data, AAD_SHARD).unwrap();

        let decrypted_shard = reader.decrypt_shard(&shard_blob, None, &[]).unwrap();
        assert_eq!(decrypted_shard, shard_data);
    }

    #[test]
    fn vault_derive_commit_key() {
        let root_key = crate::generate_key();
        let vault = KeyVault::new(root_key).unwrap();

        let (ck1, nonce1) = vault.derive_commit_key().unwrap();
        let (ck2, nonce2) = vault.derive_commit_key().unwrap();

        // Each call produces unique key + nonce
        assert_ne!(nonce1, nonce2);
        assert_ne!(ck1.as_bytes(), ck2.as_bytes());
    }

    #[test]
    fn vault_debug_redacts_key() {
        let root_key = crate::generate_key();
        let vault = KeyVault::new(root_key).unwrap();

        let debug = format!("{:?}", vault);
        assert!(debug.contains("REDACTED"));
        assert!(debug.contains("RootKey"));
    }

    // === Content-key mode tests ===

    #[test]
    fn content_key_vault_open_commit() {
        let root_key = crate::generate_key();
        let root_vault = KeyVault::new(root_key).unwrap();

        // Seal a commit with root vault
        let plaintext = b"test commit payload";
        let sealed = root_vault.seal_commit(plaintext).unwrap();

        // Get the content key from root-vault open
        let (_, root_reader) = root_vault.open_commit(&sealed).unwrap();
        let ck = *root_reader.content_key();

        // Open the same commit with a content-key vault
        let ck_vault = KeyVault::from_content_key(ck);
        let (ck_plaintext, ck_reader) = ck_vault.open_commit(&sealed).unwrap();

        assert_eq!(ck_plaintext, plaintext);
        assert_eq!(ck_reader.content_key(), &ck);
    }

    #[test]
    fn content_key_vault_rejects_seal() {
        let ck = ContentKey::from_hex(&hex::encode([0x42u8; 32])).unwrap();
        let vault = KeyVault::from_content_key(ck);

        assert!(vault.seal_commit(b"test").is_err());
        assert!(vault.seal_metadata(b"test").is_err());
        assert!(vault.seal_shard(b"test").is_err());
    }

    #[test]
    fn content_key_vault_rejects_keyring_access() {
        let ck = ContentKey::from_hex(&hex::encode([0x42u8; 32])).unwrap();
        let vault = KeyVault::from_content_key(ck);

        assert!(vault.index_key().is_err());
        assert!(vault.staged_key().is_err());
        assert!(vault.stash_key().is_err());
    }

    #[test]
    fn content_key_vault_is_content_key_mode() {
        let root_vault = KeyVault::new(crate::generate_key()).unwrap();
        assert!(!root_vault.is_content_key_mode());

        let ck = ContentKey::from_hex(&hex::encode([0x42u8; 32])).unwrap();
        let ck_vault = KeyVault::from_content_key(ck);
        assert!(ck_vault.is_content_key_mode());
    }

    #[test]
    fn content_key_vault_debug_redacts() {
        let ck = ContentKey::from_hex(&hex::encode([0x42u8; 32])).unwrap();
        let vault = KeyVault::from_content_key(ck);
        let debug = format!("{:?}", vault);
        assert!(debug.contains("REDACTED"));
        assert!(debug.contains("ContentKey"));
    }

    #[test]
    fn root_seal_then_content_key_open_roundtrip() {
        let root_key = crate::generate_key();
        let root_vault = KeyVault::new(root_key).unwrap();

        // Seal commit + metadata with root vault
        let commit_data = b"commit payload";
        let sealed = root_vault.seal_commit(commit_data).unwrap();
        let (_, root_reader) = root_vault.open_commit(&sealed).unwrap();
        let ck = *root_reader.content_key();

        let metadata = b"metadata payload";
        let enc_metadata = root_vault.seal_metadata_with_key(&ck, metadata).unwrap();

        // Open with content-key vault
        let ck_vault = KeyVault::from_content_key(ck);
        let (ck_plaintext, ck_reader) = ck_vault.open_commit(&sealed).unwrap();
        assert_eq!(ck_plaintext, commit_data);

        // Decrypt metadata with both readers
        let dec_root: Vec<u8> = root_reader.decrypt_metadata_raw(enc_metadata.as_bytes()).unwrap();
        let dec_ck: Vec<u8> = ck_reader.decrypt_metadata_raw(enc_metadata.as_bytes()).unwrap();
        assert_eq!(dec_root, metadata);
        assert_eq!(dec_ck, metadata);
    }
}