feat(crypto)!: scope keys to file identity and name open failures

The AEAD nonce for a file is `file_id[0..6] ‖ counter48`, so a key's
nonce space is only as isolated as the leading 6 bytes of the identity
that issues into it. A shared per-realm key made two files with a
colliding prefix a birthday problem over 2^48 rather than an
impossibility. `derive_dek`/`derive_ik` now fold the full 16-byte file
identity into the HKDF info alongside the realm, so every file gets
its own key and nonce reuse is ruled out by construction. The DEK/IK
LRU cache is keyed the same way so it can't hand one file the cipher
state derived for another.

Opening a store also now tells a caller *which* parameter is wrong
instead of reporting every open failure as corruption:

- The realm is recorded and HK-MAC'd in the main.db header, so a
  mismatched realm is refused up front (`RealmMismatch`) rather than
  surfacing as an unreadable page later — including the case where the
  store was still empty and would otherwise have silently taken writes
  under the wrong realm.
- Page size and on-disk format version are cleartext and checked
  before any key is derived (`PageSizeMismatch`,
  `FormatVersionUnsupported`), so those mistakes are never mistaken for
  a bad key or for damage.
- Once both header slots fail to verify, the framing is inspected to
  tell a wrong key (`KeyMismatch`) from a genuinely corrupt header,
  since only the former is safe to retry.

`pagedb-fsck` drops its all-zero default KEK to match: a tool for
inspecting a store should never silently assume a key.

Author: farhan-syah

src/bin/pagedb-fsck/cli.rs

@@ -36,7 +36,7 @@ usage: pagedb-fsck <path> [--deep] [--page-size <bytes>] [--realm <hex16>] [<hex
   --deep               authenticate and walk every page, not just the header
   --page-size <bytes>  page size the store was created with (default 4096)
   --realm <hex16>      32 hex characters; default all-ones, nodedb-lite uses all-zeros
-  <hex-kek>            64 hex characters; also read from PAGEDB_KEK, default all-zeros
+  <hex-kek>            64 hex characters; required, or supply it in PAGEDB_KEK
   -h, --help           print this message
 
 No option may be repeated, and a path beginning with '-' must be written as

src/bin/pagedb-fsck/run.rs

@@ -51,16 +51,26 @@ async fn check(args: CliArgs) -> ExitCode {
         kek_hex,
     } = args;
 
-    // An explicit positional key wins over the environment, which wins over
-    // the all-zero default.
+    // An explicit positional key wins over the environment. There is no
+    // default: a tool that silently assumes a key encourages treating that key
+    // as a real one, and an all-zero fallback turns "you did not supply the
+    // key" into "this store will not open", which is the one distinction this
+    // tool exists to preserve.
     let kek_hex = kek_hex.or_else(|| std::env::var("PAGEDB_KEK").ok());
     let kek = match kek_hex.as_deref().map(pagedb::hex::parse_hex::<32>) {
         Some(Some(kek)) => kek,
         Some(None) => {
             eprintln!("pagedb-fsck: invalid hex KEK (must be 64 hex chars / 32 bytes)");
             return ExitCode::from(EXIT_USAGE);
         }
-        None => [0u8; 32],
+        None => {
+            eprintln!(
+                "pagedb-fsck: a KEK is required; pass it as the trailing positional \
+                 argument or in PAGEDB_KEK"
+            );
+            eprintln!("{}", cli::USAGE);
+            return ExitCode::from(EXIT_USAGE);
+        }
     };
 
     let realm = match realm_hex.as_deref().map(pagedb::hex::parse_hex::<16>) {

src/compaction/helpers.rs

@@ -176,7 +176,7 @@ pub(super) async fn replace_segment_compact<V: Vfs + Clone>(
     catalog_root_bytes[8..].copy_from_slice(&new_commit_id.to_le_bytes());
 
     let fields = MainDbHeaderFields {
-        format_version: 1,
+        format_version: crate::pager::structural_header::MAIN_FORMAT_VERSION,
         cipher_id: db.cipher_id.as_byte(),
         page_size_log2: page_size_log2(db.page_size)?,
         flags: 0,
@@ -198,6 +198,7 @@ pub(super) async fn replace_segment_compact<V: Vfs + Clone>(
         next_page_id: new_next,
         commit_retain_policy_tag: 0,
         commit_retain_policy_value: 0,
+        realm_id: db.realm_id,
     };
 
     let hk_clone = { db.hk.read().clone() };
@@ -268,7 +269,7 @@ pub(super) fn make_header_fields<V: Vfs + Clone>(
     catalog_root_bytes[..8].copy_from_slice(&new_cat_root.to_le_bytes());
     catalog_root_bytes[8..].copy_from_slice(&new_commit_id.to_le_bytes());
     MainDbHeaderFields {
-        format_version: 1,
+        format_version: crate::pager::structural_header::MAIN_FORMAT_VERSION,
         cipher_id: db.cipher_id.as_byte(),
         page_size_log2: page_size_log2(db.page_size).unwrap_or(12),
         flags: 0,
@@ -290,6 +291,7 @@ pub(super) fn make_header_fields<V: Vfs + Clone>(
         next_page_id: new_next,
         commit_retain_policy_tag: 0,
         commit_retain_policy_value: 0,
+        realm_id: db.realm_id,
     }
 }
 

src/crypto/cipher.rs

@@ -195,8 +195,9 @@ mod tests {
 
     fn fixture() -> (Cipher, Cipher, Cipher, Aad, Nonce) {
         let mk = derive_mk(&[7u8; 32], &[0xAB; 16], 0).unwrap();
-        let dek = derive_dek(&mk, RealmId([1; 16])).unwrap();
-        let ik = derive_ik(&mk).unwrap();
+        let file_id = [0x5A; 16];
+        let dek = derive_dek(&mk, RealmId([1; 16]), &file_id).unwrap();
+        let ik = derive_ik(&mk, RealmId([1; 16]), &file_id).unwrap();
         let aes = Cipher::new_aes_gcm(&dek);
         let cc = Cipher::new_chacha20(&dek);
         let pt = Cipher::new_plaintext_mac(ik);

src/crypto/kdf.rs

@@ -11,10 +11,39 @@ use super::keys::{DerivedKey, MasterKey};
 
 const INFO_MASTER_PREFIX: &[u8] = b"pagedb/master/v1/";
 const INFO_REALM_PREFIX: &[u8] = b"pagedb/realm/";
-const INFO_REALM_SUFFIX: &[u8] = b"/v1";
-const INFO_INTEGRITY: &[u8] = b"pagedb/integrity/v1";
+const INFO_INTEGRITY_PREFIX: &[u8] = b"pagedb/integrity/";
+const INFO_FILE_INFIX: &[u8] = b"/file/";
+const INFO_V2_SUFFIX: &[u8] = b"/v2";
 const INFO_HEADER_MAC: &[u8] = b"pagedb/header-mac/v1";
 
+/// Build `prefix ‖ realm_id ‖ "/file/" ‖ file_id ‖ "/v2"`.
+///
+/// The realm and the file identity are both fixed-width, and the literals
+/// around them are constant, so the encoding is unambiguous without a length
+/// prefix: no two distinct `(realm, file)` pairs can produce the same bytes.
+fn scoped_info<const N: usize>(prefix: &[u8], realm_id: RealmId, file_id: &[u8; 16]) -> [u8; N] {
+    let mut info = [0u8; N];
+    let mut off = 0;
+    info[off..off + prefix.len()].copy_from_slice(prefix);
+    off += prefix.len();
+    info[off..off + 16].copy_from_slice(&realm_id.0);
+    off += 16;
+    info[off..off + INFO_FILE_INFIX.len()].copy_from_slice(INFO_FILE_INFIX);
+    off += INFO_FILE_INFIX.len();
+    info[off..off + 16].copy_from_slice(file_id);
+    off += 16;
+    info[off..off + INFO_V2_SUFFIX.len()].copy_from_slice(INFO_V2_SUFFIX);
+    info
+}
+
+/// Width of a `scoped_info` buffer for a given prefix.
+const fn scoped_info_len(prefix_len: usize) -> usize {
+    prefix_len + 16 + INFO_FILE_INFIX.len() + 16 + INFO_V2_SUFFIX.len()
+}
+
+const DEK_INFO_LEN: usize = scoped_info_len(INFO_REALM_PREFIX.len());
+const IK_INFO_LEN: usize = scoped_info_len(INFO_INTEGRITY_PREFIX.len());
+
 /// Derive the master key from the embedder-supplied KEK.
 ///
 /// `info` = `INFO_MASTER_PREFIX ‖ mk_epoch.to_le_bytes()` (17 + 8 = 25 bytes).
@@ -30,24 +59,47 @@ pub fn derive_mk(kek: &[u8; 32], kek_salt: &[u8; 16], mk_epoch: u64) -> Result<M
     Ok(MasterKey::from_bytes(out))
 }
 
-/// Derive the per-realm Data Encryption Key (used by AEAD modes).
+/// Derive the Data Encryption Key for one realm **within one file** (used by
+/// AEAD modes).
 ///
-/// `info` = `"pagedb/realm/" ‖ realm_id ‖ "/v1"` (13 + 16 + 3 = 32 bytes).
-pub fn derive_dek(mk: &MasterKey, realm_id: RealmId) -> Result<DerivedKey> {
-    let mut info = [0u8; INFO_REALM_PREFIX.len() + 16 + INFO_REALM_SUFFIX.len()];
-    let mut off = 0;
-    info[off..off + INFO_REALM_PREFIX.len()].copy_from_slice(INFO_REALM_PREFIX);
-    off += INFO_REALM_PREFIX.len();
-    info[off..off + 16].copy_from_slice(&realm_id.0);
-    off += 16;
-    info[off..off + INFO_REALM_SUFFIX.len()].copy_from_slice(INFO_REALM_SUFFIX);
-
+/// `info` = `"pagedb/realm/" ‖ realm_id ‖ "/file/" ‖ file_id ‖ "/v2"`.
+///
+/// # Why the file identity is part of the key
+///
+/// An AEAD nonce here is `file_id[0..6] ‖ counter48` (see
+/// [`crate::crypto::nonce`]), so a key's nonce space is partitioned only by
+/// the leading 6 bytes of the identity that issues into it. `main.db`, every
+/// segment, and every apply journal in a realm are separate identities, and
+/// those identities are random — which makes a shared per-realm key a birthday
+/// problem over 2^48, not a guarantee. Two files whose identities happen to
+/// share a 6-byte prefix would issue the same nonce under the same key, and
+/// GCM nonce reuse leaks the plaintext XOR and exposes the authentication key.
+///
+/// Scoping the key by the full 16-byte identity removes the question instead of
+/// making it unlikely: each file gets its own key, so its 48-bit counter is the
+/// *whole* nonce space for that key and reuse is impossible by construction
+/// rather than improbable by measure.
+///
+/// `file_id` must be the same identity that seeds the file's nonce generator:
+/// the header's `file_id` for `main.db`, the `segment_id` for a segment, the
+/// journal id for an apply journal.
+pub fn derive_dek(mk: &MasterKey, realm_id: RealmId, file_id: &[u8; 16]) -> Result<DerivedKey> {
+    let info: [u8; DEK_INFO_LEN] = scoped_info(INFO_REALM_PREFIX, realm_id, file_id);
     expand(mk.as_bytes(), &info)
 }
 
-/// Derive the Integrity Key (used by plaintext+MAC mode, shared across realms).
-pub fn derive_ik(mk: &MasterKey) -> Result<DerivedKey> {
-    expand(mk.as_bytes(), INFO_INTEGRITY)
+/// Derive the Integrity Key for one realm within one file (used by the
+/// plaintext+MAC mode).
+///
+/// `info` = `"pagedb/integrity/" ‖ realm_id ‖ "/file/" ‖ file_id ‖ "/v2"`.
+///
+/// An HMAC needs no nonce, so this mode has no reuse hazard to avoid. It is
+/// scoped identically to [`derive_dek`] anyway so that "one key per (realm,
+/// file, epoch, cipher)" is a single rule with no exception to remember — a
+/// mode added later inherits the safe shape by default.
+pub fn derive_ik(mk: &MasterKey, realm_id: RealmId, file_id: &[u8; 16]) -> Result<DerivedKey> {
+    let info: [u8; IK_INFO_LEN] = scoped_info(INFO_INTEGRITY_PREFIX, realm_id, file_id);
+    expand(mk.as_bytes(), &info)
 }
 
 /// Derive the Header Key (used to MAC main.db headers and segment headers/footers).
@@ -165,22 +217,74 @@ mod tests {
         assert_ne!(a.as_bytes(), b.as_bytes());
     }
 
+    const FILE_A: [u8; 16] = [0x5A; 16];
+    const FILE_B: [u8; 16] = [0xA5; 16];
+
     #[test]
     fn dek_isolates_per_realm() {
         let mk = derive_mk(&fixed_kek(), &[0; 16], 0).unwrap();
-        let a = derive_dek(&mk, RealmId([0x11; 16])).unwrap();
-        let b = derive_dek(&mk, RealmId([0x22; 16])).unwrap();
+        let a = derive_dek(&mk, RealmId([0x11; 16]), &FILE_A).unwrap();
+        let b = derive_dek(&mk, RealmId([0x22; 16]), &FILE_A).unwrap();
         assert_ne!(a.as_bytes(), b.as_bytes());
     }
 
+    /// The property the whole per-file scoping exists for: two files in one
+    /// realm never share a key, so neither can issue a nonce the other has
+    /// already used.
+    #[test]
+    fn dek_isolates_per_file_within_one_realm() {
+        let mk = derive_mk(&fixed_kek(), &[0; 16], 0).unwrap();
+        let realm = RealmId([0x11; 16]);
+        let a = derive_dek(&mk, realm, &FILE_A).unwrap();
+        let b = derive_dek(&mk, realm, &FILE_B).unwrap();
+        assert_ne!(a.as_bytes(), b.as_bytes());
+    }
+
+    /// Identities that collide in the 6 bytes the nonce is built from are
+    /// exactly the case a per-realm key could not survive. They must still
+    /// derive different keys, so a prefix collision costs nothing.
+    #[test]
+    fn dek_isolates_files_sharing_a_nonce_prefix() {
+        let mk = derive_mk(&fixed_kek(), &[0; 16], 0).unwrap();
+        let realm = RealmId([0x11; 16]);
+        let mut shared_prefix = FILE_A;
+        shared_prefix[15] ^= 0xFF;
+        assert_eq!(FILE_A[..6], shared_prefix[..6]);
+        let a = derive_dek(&mk, realm, &FILE_A).unwrap();
+        let b = derive_dek(&mk, realm, &shared_prefix).unwrap();
+        assert_ne!(a.as_bytes(), b.as_bytes());
+    }
+
+    #[test]
+    fn ik_isolates_per_realm_and_file() {
+        let mk = derive_mk(&fixed_kek(), &[0; 16], 0).unwrap();
+        let base = derive_ik(&mk, RealmId([0x11; 16]), &FILE_A).unwrap();
+        let other_realm = derive_ik(&mk, RealmId([0x22; 16]), &FILE_A).unwrap();
+        let other_file = derive_ik(&mk, RealmId([0x11; 16]), &FILE_B).unwrap();
+        assert_ne!(base.as_bytes(), other_realm.as_bytes());
+        assert_ne!(base.as_bytes(), other_file.as_bytes());
+    }
+
     #[test]
     fn ik_hk_are_distinct_from_dek() {
         let mk = derive_mk(&fixed_kek(), &[0; 16], 0).unwrap();
-        let dek = derive_dek(&mk, RealmId([0x11; 16])).unwrap();
-        let ik = derive_ik(&mk).unwrap();
+        let realm = RealmId([0x11; 16]);
+        let dek = derive_dek(&mk, realm, &FILE_A).unwrap();
+        let ik = derive_ik(&mk, realm, &FILE_A).unwrap();
         let hk = derive_hk(&mk).unwrap();
         assert_ne!(dek.as_bytes(), ik.as_bytes());
         assert_ne!(dek.as_bytes(), hk.as_bytes());
         assert_ne!(ik.as_bytes(), hk.as_bytes());
     }
+
+    /// The realm/file boundary must not be forgeable by shifting bytes across
+    /// it. Fixed-width fields plus constant literals make that structural, and
+    /// this pins it: swapping the two 16-byte fields is a different key.
+    #[test]
+    fn realm_and_file_fields_are_not_interchangeable() {
+        let mk = derive_mk(&fixed_kek(), &[0; 16], 0).unwrap();
+        let a = derive_dek(&mk, RealmId(FILE_A), &FILE_B).unwrap();
+        let b = derive_dek(&mk, RealmId(FILE_B), &FILE_A).unwrap();
+        assert_ne!(a.as_bytes(), b.as_bytes());
+    }
 }