second-brain-core 0.13.5

Core library for second-brain: SQLite storage with vector and lexical indexes, BGE embeddings, and hybrid retrieval
Documentation
use anyhow::{Result, anyhow, ensure};
use hkdf::Hkdf;
use sha2::Sha256;

use super::KeyGuard;
use super::identity::{Epoch, IdentityKey};

const INFO_DOMAIN: &[u8] = b"second-brain subkey v1 ";

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum Subkey {
    Wire,
    Snapshot,
    ArchiveKek,
    StoreWrap,
}

impl Subkey {
    fn label(self) -> &'static [u8] {
        match self {
            Subkey::Wire => b"wire",
            Subkey::Snapshot => b"snapshot",
            Subkey::ArchiveKek => b"archive-kek",
            Subkey::StoreWrap => b"store-wrap",
        }
    }
}

pub fn derive_subkey(
    key: &IdentityKey,
    epoch: &Epoch,
    purpose: Subkey,
) -> Result<KeyGuard<[u8; 32]>> {
    ensure!(
        key.key_id() == epoch.key_id,
        "the identity key does not belong to epoch {} (key id {})",
        epoch.number,
        epoch.key_id
    );
    ensure!(
        epoch.number != 0 || purpose == Subkey::Wire,
        "epoch 0 derives only the wire subkey, not {purpose:?}"
    );
    let mut salt = [0u8; 12];
    salt[..4].copy_from_slice(&epoch.number.to_be_bytes());
    salt[4..].copy_from_slice(&epoch.key_id.0);
    let hkdf = Hkdf::<Sha256>::new(Some(&salt), key.expose());
    let mut out = KeyGuard::new([0u8; 32]);
    hkdf.expand_multi_info(&[INFO_DOMAIN, purpose.label()], out.expose_mut())
        .map_err(|e| anyhow!("deriving the {purpose:?} subkey: {e}"))?;
    Ok(out)
}

#[cfg(test)]
mod tests {
    use super::*;

    const ALL: [Subkey; 4] = [
        Subkey::Wire,
        Subkey::Snapshot,
        Subkey::ArchiveKek,
        Subkey::StoreWrap,
    ];

    fn key(byte: u8) -> IdentityKey {
        IdentityKey::from_bytes(KeyGuard::new([byte; 32]))
    }

    fn epoch(number: u32, key: &IdentityKey) -> Epoch {
        Epoch {
            number,
            key_id: key.key_id(),
        }
    }

    #[test]
    fn subkeys_are_stable_per_epoch() {
        let k = key(1);
        let e = epoch(1, &k);
        for purpose in ALL {
            let a = derive_subkey(&k, &e, purpose).unwrap();
            let b = derive_subkey(&k, &e, purpose).unwrap();
            assert_eq!(a.expose(), b.expose());
            assert_ne!(a.expose(), &[0u8; 32]);
            assert_ne!(a.expose(), k.expose());
        }
    }

    #[test]
    fn purposes_derive_different_subkeys() {
        let k = key(2);
        let e = epoch(1, &k);
        let derived: Vec<[u8; 32]> = ALL
            .iter()
            .map(|p| *derive_subkey(&k, &e, *p).unwrap().expose())
            .collect();
        for (i, a) in derived.iter().enumerate() {
            for (j, b) in derived.iter().enumerate().skip(i + 1) {
                assert_ne!(a, b, "{:?} vs {:?}", ALL[i], ALL[j]);
            }
        }
    }

    #[test]
    fn epoch_numbers_derive_different_subkeys() {
        let k = key(3);
        for purpose in ALL {
            let one = derive_subkey(&k, &epoch(1, &k), purpose).unwrap();
            let two = derive_subkey(&k, &epoch(2, &k), purpose).unwrap();
            assert_ne!(one.expose(), two.expose(), "{purpose:?}");
        }
        let zero = derive_subkey(&k, &epoch(0, &k), Subkey::Wire).unwrap();
        let one = derive_subkey(&k, &epoch(1, &k), Subkey::Wire).unwrap();
        assert_ne!(zero.expose(), one.expose());
    }

    #[test]
    fn epoch_zero_derives_only_wire() {
        let k = key(4);
        let e = epoch(0, &k);
        assert!(derive_subkey(&k, &e, Subkey::Wire).is_ok());
        for purpose in [Subkey::Snapshot, Subkey::ArchiveKek, Subkey::StoreWrap] {
            let err = derive_subkey(&k, &e, purpose).unwrap_err();
            assert!(err.to_string().contains("epoch 0"), "{err}");
        }
    }

    #[test]
    fn a_key_from_another_epoch_is_refused() {
        let k = key(5);
        let other = epoch(1, &key(6));
        for purpose in ALL {
            assert!(derive_subkey(&k, &other, purpose).is_err(), "{purpose:?}");
        }
    }
}