From 3cb26f9556189023fb23d5746e3a537ba86d1df3 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Tue, 17 Nov 2026 20:53:42 +0000 Subject: [PATCH] feat: add sidecar verify command --- changelog.d/+sidecar-verify.misc.md | 1 + crates/rfc9162-log/src/bin/sidecar.rs | 115 ++++++++++++++++++++-- crates/rfc9162-log/tests/sidecar_cli.rs | 123 +++++++++++++++++++++++- docs/src/howto/rfc9162-log.md | 1 + docs/src/reference/sidecar.md | 3 + 5 files changed, 236 insertions(+), 7 deletions(-) create mode 100644 changelog.d/+sidecar-verify.misc.md diff --git a/changelog.d/+sidecar-verify.misc.md b/changelog.d/+sidecar-verify.misc.md new file mode 100644 index 0000000..305f9e4 --- /dev/null +++ b/changelog.d/+sidecar-verify.misc.md @@ -0,0 +1 @@ +Added `rfc9162-sidecar verify` for offline checkpoint verification against trusted signed-note key lines, with optional inclusion proof verification for a path at the signed checkpoint. diff --git a/crates/rfc9162-log/src/bin/sidecar.rs b/crates/rfc9162-log/src/bin/sidecar.rs index e11a1b3..d59ba17 100644 --- a/crates/rfc9162-log/src/bin/sidecar.rs +++ b/crates/rfc9162-log/src/bin/sidecar.rs @@ -11,6 +11,7 @@ //! rfc9162-sidecar diff --dir DIR FROM TO //! rfc9162-sidecar blob --dir DIR HEX [--out FILE] //! rfc9162-sidecar include --dir DIR PATH --note FILE --trusted KEYLINE... [--meta K=V]... +//! rfc9162-sidecar verify --dir DIR --trusted KEYLINE... [--path REL_PATH] //! ``` //! //! Status 0 is done, 2 is a command line this binary does not take, 1 is a @@ -24,8 +25,8 @@ use std::process::ExitCode; use ed25519_dalek::pkcs8::DecodePrivateKey; use ed25519_dalek::SigningKey; -use rfc9162_log::{Op, Sidecar}; -use rfc9162_tiles::{Checkpoint, Note, PackStore, Signer, Verifier}; +use rfc9162_log::{sidecar::sidecar_keys, store::tiles_keys, Change, Op, Sidecar}; +use rfc9162_tiles::{checkpoint, Checkpoint, Note, PackStore, Reader, Signer, TileStore, Verifier}; const SIDECAR_DIR: &str = ".sidecar"; @@ -63,18 +64,25 @@ enum Command { note: PathBuf, trusted: Vec, }, + Verify { + trusted: Vec, + path: Option, + }, } fn usage(what: &str) -> ExitCode { eprintln!("rfc9162-sidecar: {what}"); - eprintln!("usage: rfc9162-sidecar COMMAND --dir DIR [...]; commands: init sync snapshot history tree diff blob include"); + eprintln!( + "usage: rfc9162-sidecar COMMAND --dir DIR [...]; commands: init sync snapshot history tree diff blob include verify" + ); ExitCode::from(2) } fn parse(argv: Vec) -> Result { let mut it = argv.into_iter(); let name = it.next().ok_or("a command is needed")?; - let (mut dir, mut key, mut origin, mut note, mut out) = (None, None, None, None, None); + let (mut dir, mut key, mut origin, mut note, mut out, mut verify_path) = + (None, None, None, None, None, None); let (mut skip, mut trusted, mut meta, mut rest) = (Vec::new(), Vec::new(), BTreeMap::new(), Vec::new()); while let Some(arg) = it.next() { @@ -85,6 +93,7 @@ fn parse(argv: Vec) -> Result { "--origin" => origin = Some(value("--origin")?), "--note" => note = Some(PathBuf::from(value("--note")?)), "--out" => out = Some(PathBuf::from(value("--out")?)), + "--path" => verify_path = Some(value("--path")?), "--skip" => skip.push(value("--skip")?), "--trusted" => trusted.push(value("--trusted")?), "--meta" => { @@ -141,6 +150,19 @@ fn parse(argv: Vec) -> Result { trusted, } } + "verify" => { + if trusted.is_empty() { + return Err("--trusted KEYLINE is needed at least once".to_string()); + } + let trusted = trusted + .iter() + .map(|line| Verifier::parse(line).map_err(|e| format!("--trusted {line:?}: {e}"))) + .collect::, _>>()?; + Command::Verify { + trusted, + path: verify_path, + } + } other => return Err(format!("unknown command {other}")), }; Ok(Args { @@ -159,10 +181,13 @@ fn open(dir: &Path) -> Result { fn run(args: &Args) -> Result<(), String> { let dir = args.dir.as_path(); - let store = open(dir)?; - let mut sidecar = Sidecar::open(&store).map_err(|e| format!("sidecar: {e}"))?; let out = io::stdout(); let mut out = out.lock(); + if let Command::Verify { trusted, path } = &args.command { + return verify(dir, trusted, path.as_deref(), &mut out); + } + let store = open(dir)?; + let mut sidecar = Sidecar::open(&store).map_err(|e| format!("sidecar: {e}"))?; match &args.command { Command::Init => { writeln!( @@ -269,6 +294,84 @@ fn run(args: &Args) -> Result<(), String> { .map_err(|e| format!("include: {e}"))?; writeln!(out, "included {path} at {index}").ok(); } + Command::Verify { .. } => unreachable!("verify returns early"), + } + Ok(()) +} + +fn verify( + dir: &Path, + trusted: &[Verifier], + path: Option<&str>, + out: &mut impl Write, +) -> Result<(), String> { + let store = open(dir)?; + let checkpoint_bytes = store + .get("checkpoint") + .map_err(|e| format!("verify: read checkpoint: {e}"))? + .ok_or("verify: no signed checkpoint in sidecar pack".to_string())?; + let checkpoint_text = String::from_utf8(checkpoint_bytes) + .map_err(|_| "verify: checkpoint is not UTF-8".to_string())?; + let note = Note::parse(&checkpoint_text).map_err(|e| format!("verify: note: {e}"))?; + let signed = checkpoint::verify(¬e, trusted).map_err(|e| format!("verify: {e}"))?; + let checkpoint = + Checkpoint::parse(¬e.text).map_err(|e| format!("verify: checkpoint: {e}"))?; + let root_hex = rfc9162::hex(&checkpoint.root); + writeln!( + out, + "verified checkpoint {} size {} root {} by {} trusted key(s)", + checkpoint.origin, + checkpoint.size, + root_hex, + signed.len() + ) + .ok(); + + if let Some(path) = path { + let keys = sidecar_keys(); + let reader = Reader::at(&store, checkpoint.size, checkpoint.root, tiles_keys(&keys)) + .map_err(|e| format!("verify: open reader at checkpoint: {e}"))?; + let key = format!("path={path}"); + let hits = reader + .find(key.as_bytes()) + .map_err(|e| format!("verify: find {path}: {e}"))?; + let index = hits.last().copied().ok_or(format!( + "verify: no entry for {path} at checkpoint size {}", + checkpoint.size + ))?; + let bytes = reader + .get(index) + .map_err(|e| format!("verify: read entry {index}: {e}"))? + .ok_or(format!("verify: no entry at index {index}"))?; + let change: Change = serde_json::from_slice(&bytes) + .map_err(|_| format!("verify: entry {index} is not a sidecar change"))?; + let inclusion = reader + .inclusion(index) + .map_err(|e| format!("verify: inclusion {index}: {e}"))? + .ok_or(format!("verify: no inclusion proof for index {index}"))?; + let proves = rfc9162::verify_inclusion( + &rfc9162::leaf_hash(&bytes), + index as usize, + checkpoint.size as usize, + &inclusion, + &root_hex, + ); + if !proves { + return Err(format!( + "verify: inclusion for {path} at index {index} does not verify against checkpoint root" + )); + } + writeln!( + out, + "verified inclusion {path} index {index} op {} steps {}", + match change.op { + Op::Put => "put", + Op::Delete => "delete", + Op::Checkpoint => "checkpoint", + }, + inclusion.len() + ) + .ok(); } Ok(()) } diff --git a/crates/rfc9162-log/tests/sidecar_cli.rs b/crates/rfc9162-log/tests/sidecar_cli.rs index 5eba793..cd7ec2b 100644 --- a/crates/rfc9162-log/tests/sidecar_cli.rs +++ b/crates/rfc9162-log/tests/sidecar_cli.rs @@ -1,9 +1,10 @@ //! The sidecar from the command line: init, sync, snapshot, history, tree, -//! diff and blob over a project directory, with a PEM signing key. +//! diff, blob and verify over a project directory, with a PEM signing key. use ed25519_dalek::pkcs8::spki::der::pem::LineEnding; use ed25519_dalek::pkcs8::EncodePrivateKey; use ed25519_dalek::SigningKey; +use rfc9162_tiles::{PackStore, Signer, TileStore}; use std::path::Path; use std::process::{Command, Output}; @@ -70,6 +71,21 @@ fn a_project_is_synced_snapshotted_and_read_back_from_the_shell() { snap.starts_with("snapshot example.org/etc size 3 root "), "{snap}" ); + let trusted = Signer::new("example.org/etc", SigningKey::from_bytes(&[7u8; 32])) + .unwrap() + .verifier() + .to_text(); + let verify = ok(&cli(&[ + "verify", + "--dir", + p, + "--trusted", + trusted.as_str(), + "--path", + "ssh/sshd_config", + ])); + assert!(verify.contains("verified checkpoint example.org/etc size 3 root ")); + assert!(verify.contains("verified inclusion ssh/sshd_config index 1 op put steps 2")); write(&project, "ssh/sshd_config", b"Port 2222\n"); std::fs::remove_file(project.join("hosts")).unwrap(); @@ -114,6 +130,111 @@ fn a_project_is_synced_snapshotted_and_read_back_from_the_shell() { ); } +#[test] +fn verify_fails_on_a_tampered_checkpoint_note() { + let dir = tempfile::tempdir().unwrap(); + let project = dir.path().join("etc"); + std::fs::create_dir_all(&project).unwrap(); + let p = project.to_str().unwrap(); + write(&project, "hosts", b"127.0.0.1 localhost\n"); + let key = dir.path().join("sidecar.pem"); + std::fs::write( + &key, + SigningKey::from_bytes(&[8u8; 32]) + .to_pkcs8_pem(LineEnding::LF) + .unwrap() + .as_bytes(), + ) + .unwrap(); + let k = key.to_str().unwrap(); + ok(&cli(&["sync", "--dir", p])); + ok(&cli(&[ + "snapshot", + "--dir", + p, + "--key", + k, + "--origin", + "example.org/etc", + ])); + let trusted = Signer::new("example.org/etc", SigningKey::from_bytes(&[8u8; 32])) + .unwrap() + .verifier() + .to_text(); + + { + let store = PackStore::open(project.join(".sidecar/pack")).unwrap(); + let mut tampered = String::from_utf8(store.get("checkpoint").unwrap().unwrap()).unwrap(); + tampered = tampered.replacen("example.org/etc", "example.org/evil", 1); + store.put("checkpoint", tampered.as_bytes()).unwrap(); + } + + let output = cli(&["verify", "--dir", p, "--trusted", trusted.as_str()]); + assert_eq!(output.status.code(), Some(1)); + assert!( + String::from_utf8_lossy(&output.stderr).contains("signature does not verify"), + "{}", + String::from_utf8_lossy(&output.stderr) + ); +} + +#[test] +fn verify_fails_on_a_tampered_inclusion_source() { + let dir = tempfile::tempdir().unwrap(); + let project = dir.path().join("etc"); + std::fs::create_dir_all(&project).unwrap(); + let p = project.to_str().unwrap(); + write(&project, "ssh/sshd_config", b"Port 22\n"); + let key = dir.path().join("sidecar.pem"); + std::fs::write( + &key, + SigningKey::from_bytes(&[9u8; 32]) + .to_pkcs8_pem(LineEnding::LF) + .unwrap() + .as_bytes(), + ) + .unwrap(); + let k = key.to_str().unwrap(); + ok(&cli(&["sync", "--dir", p])); + ok(&cli(&[ + "snapshot", + "--dir", + p, + "--key", + k, + "--origin", + "example.org/etc", + ])); + let trusted = Signer::new("example.org/etc", SigningKey::from_bytes(&[9u8; 32])) + .unwrap() + .verifier() + .to_text(); + + { + let store = PackStore::open(project.join(".sidecar/pack")).unwrap(); + let entry_paths = store.list("tile/entries").unwrap(); + let entry_path = entry_paths.first().expect("one bundle path"); + store.put(entry_path, b"not a bundle").unwrap(); + } + + let output = cli(&[ + "verify", + "--dir", + p, + "--trusted", + trusted.as_str(), + "--path", + "ssh/sshd_config", + ]); + assert_eq!(output.status.code(), Some(1)); + assert!( + String::from_utf8_lossy(&output.stderr).contains("verify: read entry") + || String::from_utf8_lossy(&output.stderr).contains("verify: find ssh/sshd_config"), + "{}", + String::from_utf8_lossy(&output.stderr) + ); +} + #[test] fn a_command_line_it_does_not_take_is_status_2_and_opens_nothing() { let dir = tempfile::tempdir().unwrap(); diff --git a/docs/src/howto/rfc9162-log.md b/docs/src/howto/rfc9162-log.md index 1cd7b77..ee39bd3 100644 --- a/docs/src/howto/rfc9162-log.md +++ b/docs/src/howto/rfc9162-log.md @@ -91,3 +91,4 @@ The second sync appends the new and changed paths and the deletion at indexes 3, `include` reads the child's signed note. `show_checkpoint` in `docs/examples` prints the `checkpoint` record from a pack; a caller that already has the note file skips that step. The trusted line is the child's verifier. The command logs the note at index 0 under `stacks/2026`. The command reference is the [sidecar page](../reference/sidecar.md). +Use `verify --trusted KEYLINE` to check the signed checkpoint offline. Add `--path REL_PATH` to verify an inclusion proof for that path against the same trusted checkpoint. diff --git a/docs/src/reference/sidecar.md b/docs/src/reference/sidecar.md index ed61c1c..fe87436 100644 --- a/docs/src/reference/sidecar.md +++ b/docs/src/reference/sidecar.md @@ -11,6 +11,7 @@ rfc9162-sidecar tree --dir DIR [SIZE] rfc9162-sidecar diff --dir DIR FROM TO rfc9162-sidecar blob --dir DIR HEX [--out FILE] rfc9162-sidecar include --dir DIR PATH --note FILE --trusted KEYLINE... [--meta K=V]... +rfc9162-sidecar verify --dir DIR --trusted KEYLINE... [--path REL_PATH] ``` `--meta` repeats. The value is `K=V` and is stored on the change. `--skip` repeats and names a top-level directory entry that `sync` leaves alone. The binary always skips `.sidecar`. `--key` is a PKCS#8 PEM Ed25519 key (`-----BEGIN PRIVATE KEY-----`). `--trusted` repeats and is a verifier line, `name+keyid+base64`. `--note` is the signed checkpoint text of a child log. @@ -25,6 +26,7 @@ rfc9162-sidecar include --dir DIR PATH --note FILE --trusted KEYLINE... [--meta | `diff` | changes with index in `FROM..TO`, `TO` clamped to the current size | | `blob` | the bytes of blob `HEX` on stdout, or written to `--out` | | `include` | `included PATH at INDEX` | +| `verify` | `verified checkpoint ORIGIN size SIZE root HEX by N trusted key(s)` and, with `--path`, `verified inclusion PATH index INDEX op OP steps N` | A history, tree or diff line for a put is: @@ -35,3 +37,4 @@ INDEX put PATH BLOBHEX SIZE A delete omits the blob and the size. A checkpoint line carries the child's origin. The fields are separated by tabs. The [log how-to](../howto/rfc9162-log.md) includes a transcript of each command. `snapshot` seals the unsealed tail when there is one, then signs the log. `include` verifies the note against the trusted keys. A child note with a smaller size, or the same size and another root, is refused. +`verify` checks the signed checkpoint in `DIR/.sidecar/pack/checkpoint` against `--trusted` keys, then opens the log at that checkpoint size and root. With `--path`, it verifies the latest entry for that path at the checkpoint with the reader's inclusion path.