fix(fsck): reject ambiguous CLI arguments

presempathy-awb · farhan-syah · commit d624869bed40 · 2026-07-26T23:04:01.000+08:00
diff --git a/README.md b/README.md
@@ -55,6 +55,22 @@ pagedb's answer: **one substrate, two surfaces.** Engines that want their own fo
 └────────────────────────────────────────────────────────────┘
 ```
 
+## Integrity inspection
+
+`pagedb-fsck` opens an existing store in frozen read-only mode. Add `--deep` to
+run a full authenticated structural walk:
+
+```bash
+cargo run --bin pagedb-fsck -- <path> --deep \
+  --realm 00000000000000000000000000000000 <64-hex-character-kek>
+```
+
+The KEK may instead come from `PAGEDB_KEK` and defaults to all zeros. The realm
+defaults to all ones; nodedb-lite stores use the all-zero realm shown above.
+Argument parsing rejects duplicate flags, unknown options, missing realm
+values, and multiple positional KEKs. Inspection disables commit-history
+retention and does not rewrite authoritative `main.db` or segment bytes.
+
 ## Benchmarks
 
 Measured on native NVMe, AES-NI host, single thread, via `fluxbench`. Reproduce the
diff --git a/src/bin/pagedb-fsck.rs b/src/bin/pagedb-fsck.rs
@@ -4,6 +4,7 @@
 //! file, verifying AEAD tags, structural invariants, orphan pages, and
 //! catalog–disk consistency.
 
+#[cfg(not(target_arch = "wasm32"))]
 use std::process::ExitCode;
 
 #[cfg(not(target_arch = "wasm32"))]
@@ -13,37 +14,99 @@ use pagedb::vfs::tokio_backend::TokioVfs;
 #[cfg(not(target_arch = "wasm32"))]
 use pagedb::{Db, RealmId, run_deep_walk};
 
+#[cfg(not(target_arch = "wasm32"))]
+struct CliArgs {
+    path: String,
+    deep: bool,
+    realm_hex: Option<String>,
+    kek_hex: Option<String>,
+}
+
 #[cfg(target_arch = "wasm32")]
 fn main() {
     // pagedb-fsck is a native-only tool; it is not functional on wasm32.
 }
 
 #[cfg(not(target_arch = "wasm32"))]
-#[tokio::main(flavor = "current_thread")]
-async fn main() -> ExitCode {
-    let args: Vec<String> = std::env::args().collect();
-    if args.len() < 2 {
-        eprintln!("usage: pagedb-fsck <path> [--deep] [--realm <hex16>] [<hex-kek>]");
-        eprintln!("(KEK may also be set via PAGEDB_KEK env var; defaults to zeros.");
-        eprintln!(" --realm defaults to all-ones; nodedb-lite stores use all-zeros.)");
-        return ExitCode::from(2);
+fn usage() {
+    eprintln!("usage: pagedb-fsck <path> [--deep] [--realm <hex16>] [<hex-kek>]");
+    eprintln!("(KEK may also be set via PAGEDB_KEK; defaults to zeros.");
+    eprintln!(" --realm defaults to all-ones; nodedb-lite stores use all-zeros.)");
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+fn parse_args(args: &[String]) -> Result<CliArgs, String> {
+    let Some(path) = args.get(1) else {
+        return Err("database path is required".to_string());
+    };
+    if path.starts_with("--") {
+        return Err(format!("unknown option {path}"));
     }
-    let path = &args[1];
 
-    // Parse optional flags and positional KEK.
     let mut deep = false;
-    let mut kek_hex: Option<String> = None;
-    let mut realm_hex: Option<String> = None;
-    let mut it = args.iter().skip(2);
-    while let Some(arg) = it.next() {
-        if arg == "--deep" {
-            deep = true;
-        } else if arg == "--realm" {
-            realm_hex = it.next().cloned();
-        } else if kek_hex.is_none() {
-            kek_hex = Some(arg.clone());
+    let mut realm_hex = None;
+    let mut kek_hex = None;
+    let mut index = 2;
+    while index < args.len() {
+        match args[index].as_str() {
+            "--deep" => {
+                if deep {
+                    return Err("duplicate --deep".to_string());
+                }
+                deep = true;
+                index += 1;
+            }
+            "--realm" => {
+                if realm_hex.is_some() {
+                    return Err("duplicate --realm".to_string());
+                }
+                let value = args
+                    .get(index + 1)
+                    .filter(|value| !value.starts_with("--"))
+                    .ok_or_else(|| "--realm requires a 32-character hex value".to_string())?;
+                realm_hex = Some(value.clone());
+                index += 2;
+            }
+            option if option.starts_with("--") => {
+                return Err(format!("unknown option {option}"));
+            }
+            value => {
+                if kek_hex.is_some() {
+                    return Err("multiple KEK values supplied".to_string());
+                }
+                kek_hex = Some(value.to_string());
+                index += 1;
+            }
         }
     }
+
+    Ok(CliArgs {
+        path: path.clone(),
+        deep,
+        realm_hex,
+        kek_hex,
+    })
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+#[tokio::main(flavor = "current_thread")]
+async fn main() -> ExitCode {
+    let args: Vec<String> = std::env::args().collect();
+    let parsed = match parse_args(&args) {
+        Ok(parsed) => parsed,
+        Err(error) => {
+            eprintln!("pagedb-fsck: {error}");
+            usage();
+            return ExitCode::from(2);
+        }
+    };
+    let CliArgs {
+        path,
+        deep,
+        realm_hex,
+        mut kek_hex,
+    } = parsed;
+
     if kek_hex.is_none() {
         kek_hex = std::env::var("PAGEDB_KEK").ok();
     }
diff --git a/tests/fsck_cli.rs b/tests/fsck_cli.rs
@@ -0,0 +1,141 @@
+#![cfg(not(target_arch = "wasm32"))]
+
+use std::{collections::BTreeMap, path::Path, process::Command};
+
+use pagedb::options::{OpenOptions, RetainPolicy};
+use pagedb::segment::types::SegmentPageKind;
+use pagedb::vfs::tokio_backend::TokioVfs;
+use pagedb::{Db, RealmId, SegmentKind};
+
+const KEK: [u8; 32] = [0xA5; 32];
+const KEK_HEX: &str = "a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5";
+const REALM: RealmId = RealmId::new([0; 16]);
+const REALM_HEX: &str = "00000000000000000000000000000000";
+const PAGE: usize = 4096;
+
+fn fsck() -> Command {
+    let mut command = Command::new(env!("CARGO_BIN_EXE_pagedb-fsck"));
+    command.env_remove("PAGEDB_KEK");
+    command
+}
+
+fn collect_files(root: &Path, current: &Path, files: &mut BTreeMap<String, Vec<u8>>) {
+    if !current.exists() {
+        return;
+    }
+    for entry in std::fs::read_dir(current).unwrap() {
+        let entry = entry.unwrap();
+        let path = entry.path();
+        if path.is_dir() {
+            collect_files(root, &path, files);
+        } else {
+            let relative = path
+                .strip_prefix(root)
+                .unwrap()
+                .to_string_lossy()
+                .into_owned();
+            files.insert(relative, std::fs::read(path).unwrap());
+        }
+    }
+}
+
+fn authoritative_bytes(root: &Path) -> BTreeMap<String, Vec<u8>> {
+    let mut files = BTreeMap::new();
+    files.insert(
+        "main.db".to_string(),
+        std::fs::read(root.join("main.db")).unwrap(),
+    );
+    collect_files(root, &root.join("seg"), &mut files);
+    files
+}
+
+#[tokio::test(flavor = "current_thread")]
+async fn fsck_accepts_explicit_realm_and_preserves_authoritative_bytes() {
+    let dir = tempfile::tempdir().unwrap();
+    {
+        let options = OpenOptions::default().with_commit_history_retain(RetainPolicy::Disabled);
+        let db = Db::open(TokioVfs::new(dir.path()), KEK, PAGE, REALM, options)
+            .await
+            .unwrap();
+        let mut segment = db
+            .create_segment(REALM, SegmentKind::Unspecified)
+            .await
+            .unwrap();
+        segment
+            .append_page(SegmentPageKind::Data, b"fsck-segment")
+            .await
+            .unwrap();
+        let segment_meta = segment.seal().await.unwrap();
+        let mut write = db.begin_write().await.unwrap();
+        write.put(b"fsck-key", b"fsck-value").await.unwrap();
+        write
+            .link_segment("fsck-segment", &segment_meta)
+            .await
+            .unwrap();
+        write.commit().await.unwrap();
+    }
+
+    let before = authoritative_bytes(dir.path());
+    let output = fsck()
+        .arg(dir.path())
+        .args(["--deep", "--realm", REALM_HEX, KEK_HEX])
+        .output()
+        .unwrap();
+    let after = authoritative_bytes(dir.path());
+
+    assert!(
+        output.status.success(),
+        "fsck failed: stdout={} stderr={}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+    assert_eq!(
+        after, before,
+        "fsck changed authoritative main.db or segment bytes"
+    );
+    assert!(
+        String::from_utf8_lossy(&output.stdout).contains("result: CLEAN"),
+        "deep fsck did not emit a clean report: {}",
+        String::from_utf8_lossy(&output.stdout)
+    );
+}
+
+#[test]
+fn fsck_rejects_ambiguous_or_unknown_arguments() {
+    let dir = tempfile::tempdir().unwrap();
+    let cases: &[(&[&str], &str)] = &[
+        (&["--deep", "--deep"], "duplicate --deep"),
+        (
+            &["--realm", REALM_HEX, "--realm", REALM_HEX],
+            "duplicate --realm",
+        ),
+        (&[KEK_HEX, KEK_HEX], "multiple KEK"),
+        (&["--unknown"], "unknown option"),
+        (&["--realm"], "--realm requires"),
+        (&["--realm", "--deep"], "--realm requires"),
+    ];
+
+    for (args, expected) in cases {
+        let output = fsck().arg(dir.path()).args(*args).output().unwrap();
+        assert_eq!(
+            output.status.code(),
+            Some(2),
+            "args {args:?}: stdout={} stderr={}",
+            String::from_utf8_lossy(&output.stdout),
+            String::from_utf8_lossy(&output.stderr)
+        );
+        assert!(
+            String::from_utf8_lossy(&output.stderr).contains(expected),
+            "args {args:?}: expected stderr containing {expected:?}, got {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+    }
+
+    let output = fsck().arg("--deep").output().unwrap();
+    assert_eq!(output.status.code(), Some(2));
+    assert!(
+        String::from_utf8_lossy(&output.stderr).contains("unknown option --deep"),
+        "option used as path was not rejected: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+}
