From 7cc8e58ace6d5c9d740c4b47b7811ebd10d5e244 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Wed, 18 Nov 2026 00:00:19 +0100 Subject: [PATCH 01/11] feat(ledger): backfill, daily anchors and package history in process Port the observed-history backfill, daily anchor and package history projection from eb-staged-rebuild's ledger maintenance module into the library, calling ledger::append, ledger::sign_head and ledger::verify directly instead of the eb-stack binary. The manifest format and its SHA-256 pin, the anchor directory layout, lock files and never-replace rule, the projection files and their bytes, and the refusals keep their behaviour. The schema names and backfill event ids keep their eb-staged-rebuild/ spelling, so a rerun over an existing log is acknowledged as already recorded. Dropped because they existed only for a subprocess: the --eb-stack executable check, the per-call timeout, the bounded output reader, the parsing of stdout receipt lines, and the fault injection points. The in-process receipts are checked from the reports the library returns. Log lines are parsed by ledger::parse_log, which also recomputes ids and checks timestamps, so a tampered line is a verification failure at read time. Projection files keep owner and mode across a replace but not extended ACL attributes. tempfile moves from dev-dependencies to dependencies for the private verification and staging directories. --- Cargo.toml | 3 +- src/ledger_maintenance.rs | 2609 +++++++++++++++++++++++++++++++++++++ src/lib.rs | 2 + 3 files changed, 2613 insertions(+), 1 deletion(-) create mode 100644 src/ledger_maintenance.rs diff --git a/Cargo.toml b/Cargo.toml index 036cfbc2..fc3994f9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -119,10 +119,11 @@ ed25519-dalek = { version = "2", features = ["pkcs8", "pem"] } rfc9162 = "=0.8.1" rfc9162-tiles = "=0.8.1" rfc9162-log = "=0.8.1" +# Private directories for verifying copies of a ledger and staging anchors. +tempfile = "3" [target.'cfg(unix)'.dependencies] libc = "0.2" [dev-dependencies] jsonschema = { version = "0.26", default-features = false } -tempfile = "3" diff --git a/src/ledger_maintenance.rs b/src/ledger_maintenance.rs new file mode 100644 index 00000000..729e2592 --- /dev/null +++ b/src/ledger_maintenance.rs @@ -0,0 +1,2609 @@ +//! Maintenance of a ledger: observed-history backfill, daily signed +//! anchors, and per-package history projections. +//! +//! * [`backfill`] appends `finding` records for software observed at an +//! explicit time, from an operator-written manifest pinned by its SHA-256. +//! * [`anchor`] signs the day's head and adds it to a directory of immutable +//! daily anchors once [`ledger::verify`] proves it extends the latest +//! anchor; [`verify_anchors`] proves the whole chain against the log. +//! * [`project`] writes per-package JSON and Markdown history from a log +//! whose signed head covers every record. +//! +//! Every signature comes from [`ledger::append`] or [`ledger::sign_head`] +//! and every proof from [`ledger::verify`]. The log and head files are read +//! once; the bytes read are copied into a private directory, verified there +//! with a tile log built from the copy, and parsed from the same buffer, so +//! what is anchored or projected is what was verified. +//! +//! The manifest schema, the projection schema and the backfill event ids +//! carry `eb-staged-rebuild/` names. Existing manifests, projections and +//! logs use those names, and a backfill rerun over such a log is +//! acknowledged as already recorded only while the event ids stay the same. +//! +//! A refusal is exit status [`REFUSED_EXIT`]. A ledger write that did not +//! finish is [`PENDING_EXIT`]: the record may or may not be in the log, and +//! the same command can be run again, because every backfill record is +//! built from the manifest alone and carries a `build.event_id`. + +use crate::ledger::{self, Entry, SignedHead, VerifyMode, VerifyRequest}; +use anyhow::Result; +use chrono::{DateTime, NaiveDateTime}; +use regex::Regex; +use serde::de::{self, DeserializeSeed, MapAccess, SeqAccess, Visitor}; +use serde_json::{json, Map, Value}; +use sha2::{Digest, Sha256}; +use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet}; +use std::fmt::{self, Display, Write as _}; +use std::fs::{File, OpenOptions}; +use std::io::{Read, Write}; +use std::os::fd::AsRawFd; +use std::os::unix::fs::{MetadataExt, OpenOptionsExt, PermissionsExt}; +use std::path::{Path, PathBuf}; +use std::sync::LazyLock; +use std::time::{Duration, Instant}; + +/// Schema of an observed-history manifest. +pub const MANIFEST_SCHEMA: &str = "eb-staged-rebuild/observed-backfill/1"; +/// Schema of the projection's JSON files. +pub const HISTORY_SCHEMA: &str = "eb-staged-rebuild/ledger-history/1"; +/// `build.kind` of a backfilled record. +pub const BACKFILL_KIND: &str = "observed-backfill"; +/// `build.tool` of a backfilled record. +pub const TOOL: &str = "eb-staged-rebuild/ledger-maintenance"; +/// Exit status of a refusal. +pub const REFUSED_EXIT: i32 = 2; +/// Exit status when a ledger write did not finish; run the same command again. +pub const PENDING_EXIT: i32 = 75; + +/// Seconds `anchor` waits for another anchor run to release the directory. +const LOCK_TIMEOUT: Duration = Duration::from_secs(60); +const LOCK_RETRY: Duration = Duration::from_millis(20); +const STAGING_PREFIX: &str = ".anchor-staging-"; + +/// Fields that name another record by its `id`, in ledger order. +const LINKS: &[&str] = &[ + "supersedes", + "superseded_by", + "moved_from", + "moved_to", + "corrects", +]; +const HEAD_FIELDS: &[&str] = &["domain", "size", "root", "ts", "public_key", "signature"]; + +static HEX64: LazyLock = LazyLock::new(|| Regex::new(r"^[0-9a-f]{64}$").unwrap()); +static HEX128: LazyLock = LazyLock::new(|| Regex::new(r"^[0-9a-f]{128}$").unwrap()); +static HEAD_TS: LazyLock = LazyLock::new(|| { + Regex::new(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]{1,9})?Z$") + .unwrap() +}); +static OBSERVED_TS: LazyLock = LazyLock::new(|| { + Regex::new(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$").unwrap() +}); +static MANIFEST_ID: LazyLock = + LazyLock::new(|| Regex::new(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$").unwrap()); +static ANCHOR_NAME: LazyLock = + LazyLock::new(|| Regex::new(r"^([0-9]{4}-[0-9]{2}-[0-9]{2})\.head\.json$").unwrap()); + +// Errors + +/// How a maintenance command failed. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Failure { + /// The input was refused before anything was written. + Refused, + /// `ledger verify` did not accept the log, a head or a proof. + Verification, + /// The signed head covers fewer records than the log holds. + StaleHead, + /// Two signed heads disagree about the same history. + Equivocation, + /// A ledger write did not finish; the same command can be run again. + Pending, +} + +impl Failure { + /// Every failure except [`Failure::Pending`] is a refusal. + #[must_use] + pub fn is_refusal(self) -> bool { + self != Failure::Pending + } +} + +/// A maintenance command's failure and its message. +#[derive(Debug)] +pub struct MaintenanceError { + /// What kind of failure. + pub failure: Failure, + /// The message printed for it. + pub message: String, +} + +impl Display for MaintenanceError { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter.write_str(&self.message) + } +} + +impl std::error::Error for MaintenanceError {} + +fn fail(failure: Failure, message: impl Into) -> anyhow::Error { + anyhow::Error::new(MaintenanceError { + failure, + message: message.into(), + }) +} + +fn refused(message: impl Into) -> anyhow::Error { + fail(Failure::Refused, message) +} + +fn verification(message: impl Into) -> anyhow::Error { + fail(Failure::Verification, message) +} + +fn equivocation(message: impl Into) -> anyhow::Error { + fail(Failure::Equivocation, message) +} + +fn pending(message: impl Into) -> anyhow::Error { + fail( + Failure::Pending, + format!( + "{}; nothing was acknowledged, retry the same command", + message.into() + ), + ) +} + +/// The failure an error carries, when it is a maintenance error. +#[must_use] +pub fn failure_of(error: &anyhow::Error) -> Option { + error + .chain() + .find_map(|cause| cause.downcast_ref::()) + .map(|error| error.failure) +} + +/// The exit status of a maintenance error: [`PENDING_EXIT`] when a write +/// did not finish, else [`REFUSED_EXIT`]. `None` for any other error. +#[must_use] +pub fn exit_code(error: &anyhow::Error) -> Option { + failure_of(error).map(|failure| match failure { + Failure::Pending => PENDING_EXIT, + _ => REFUSED_EXIT, + }) +} + +/// `error` as a maintenance error: one that already carries a failure is +/// kept, any other (an unreadable file, a failed directory flush) is a +/// refusal. +#[must_use] +pub fn as_maintenance_error(error: anyhow::Error) -> anyhow::Error { + if failure_of(&error).is_some() { + error + } else { + refused(format!("{error:#}")) + } +} + +// Small helpers + +fn sha256_hex(data: &[u8]) -> String { + let digest = Sha256::digest(data); + let mut text = String::with_capacity(64); + for byte in digest { + let _ = write!(text, "{byte:02x}"); + } + text +} + +fn utc(seconds: i64) -> String { + DateTime::from_timestamp(seconds, 0) + .map(|time| time.format("%Y-%m-%dT%H:%M:%SZ").to_string()) + .unwrap_or_else(|| seconds.to_string()) +} + +/// The current time in whole seconds since the epoch. +#[must_use] +pub fn now_seconds() -> i64 { + chrono::Utc::now().timestamp() +} + +fn display(path: &Path) -> String { + path.display().to_string() +} + +fn io_refused(what: &str, path: &Path, error: &std::io::Error) -> anyhow::Error { + refused(format!("cannot {what} {}: {error}", path.display())) +} + +// JSON as the projection writes it + +/// JSON text with keys sorted and every character outside printable ASCII +/// escaped. With `indent`, nested values go on their own lines indented by +/// that many spaces per level and items are separated by `,`; without, the +/// value is one line with `, ` and `: ` separators. +#[must_use] +pub fn dumps(value: &Value, indent: Option) -> String { + let mut out = String::new(); + write_json(value, indent, 0, &mut out); + out +} + +fn write_json(value: &Value, indent: Option, level: usize, out: &mut String) { + let separator = |out: &mut String, at: usize, depth: usize| match indent { + Some(width) => { + if at > 0 { + out.push(','); + } + out.push('\n'); + out.push_str(&" ".repeat(width * depth)); + } + None => { + if at > 0 { + out.push_str(", "); + } + } + }; + let close = |out: &mut String| { + if let Some(width) = indent { + out.push('\n'); + out.push_str(&" ".repeat(width * level)); + } + }; + match value { + Value::Null => out.push_str("null"), + Value::Bool(flag) => out.push_str(if *flag { "true" } else { "false" }), + Value::Number(number) => out.push_str(&number.to_string()), + Value::String(text) => write_ascii_string(text, out), + Value::Array(items) if items.is_empty() => out.push_str("[]"), + Value::Array(items) => { + out.push('['); + for (at, item) in items.iter().enumerate() { + separator(out, at, level + 1); + write_json(item, indent, level + 1, out); + } + close(out); + out.push(']'); + } + Value::Object(map) if map.is_empty() => out.push_str("{}"), + Value::Object(map) => { + out.push('{'); + let mut keys = map.keys().collect::>(); + keys.sort(); + for (at, key) in keys.into_iter().enumerate() { + separator(out, at, level + 1); + write_ascii_string(key, out); + out.push_str(": "); + write_json(&map[key], indent, level + 1, out); + } + close(out); + out.push('}'); + } + } +} + +fn write_ascii_string(text: &str, out: &mut String) { + out.push('"'); + for ch in text.chars() { + match ch { + '"' => out.push_str("\\\""), + '\\' => out.push_str("\\\\"), + '\n' => out.push_str("\\n"), + '\r' => out.push_str("\\r"), + '\t' => out.push_str("\\t"), + '\u{8}' => out.push_str("\\b"), + '\u{c}' => out.push_str("\\f"), + ' '..='~' => out.push(ch), + _ => { + let mut units = [0u16; 2]; + for unit in ch.encode_utf16(&mut units) { + let _ = write!(out, "\\u{unit:04x}"); + } + } + } + } + out.push('"'); +} + +/// JSON that refuses a repeated object key and any non-integer number. +struct Strict; + +impl<'de> DeserializeSeed<'de> for Strict { + type Value = Value; + + fn deserialize>(self, deserializer: D) -> Result { + deserializer.deserialize_any(self) + } +} + +impl<'de> Visitor<'de> for Strict { + type Value = Value; + + fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter.write_str("JSON") + } + + fn visit_bool(self, value: bool) -> Result { + Ok(Value::Bool(value)) + } + + fn visit_i64(self, value: i64) -> Result { + Ok(Value::from(value)) + } + + fn visit_u64(self, value: u64) -> Result { + Ok(Value::from(value)) + } + + fn visit_f64(self, value: f64) -> Result { + Err(E::custom(format!("holds the non-integer number {value}"))) + } + + fn visit_str(self, value: &str) -> Result { + Ok(Value::String(value.to_owned())) + } + + fn visit_string(self, value: String) -> Result { + Ok(Value::String(value)) + } + + fn visit_unit(self) -> Result { + Ok(Value::Null) + } + + fn visit_none(self) -> Result { + Ok(Value::Null) + } + + fn visit_some>(self, deserializer: D) -> Result { + Strict.deserialize(deserializer) + } + + fn visit_seq>(self, mut seq: A) -> Result { + let mut items = Vec::new(); + while let Some(item) = seq.next_element_seed(Strict)? { + items.push(item); + } + Ok(Value::Array(items)) + } + + fn visit_map>(self, mut map: A) -> Result { + let mut object = Map::new(); + while let Some(key) = map.next_key::()? { + if object.contains_key(&key) { + return Err(de::Error::custom(format!("repeats the key {key:?}"))); + } + let value = map.next_value_seed(Strict)?; + object.insert(key, value); + } + Ok(Value::Object(object)) + } +} + +fn strict_json(text: &str, what: &str) -> Result { + let mut deserializer = serde_json::Deserializer::from_str(text); + let value = Strict + .deserialize(&mut deserializer) + .and_then(|value| deserializer.end().map(|()| value)) + .map_err(|error| refused(format!("{what} is not strict JSON: {error}")))?; + Ok(value) +} + +// Paths + +/// `path` as POSIX `normpath` spells it. +fn normpath(path: &str) -> String { + if path.is_empty() { + return ".".to_string(); + } + let initial = if path.starts_with("//") && !path.starts_with("///") { + 2 + } else if path.starts_with('/') { + 1 + } else { + 0 + }; + let mut parts: Vec<&str> = Vec::new(); + for part in path.split('/') { + if part.is_empty() || part == "." { + continue; + } + if part != ".." || (initial == 0 && parts.is_empty()) || parts.last() == Some(&"..") { + parts.push(part); + } else if !parts.is_empty() { + parts.pop(); + } + } + let joined = format!("{}{}", "/".repeat(initial), parts.join("/")); + if joined.is_empty() { + ".".to_string() + } else { + joined + } +} + +/// `path` with every symbolic link in its existing part resolved; a part +/// that does not exist is kept as written. +fn real_path(path: &Path) -> PathBuf { + match path.canonicalize() { + Ok(resolved) => resolved, + Err(_) => match (path.parent(), path.file_name()) { + (Some(parent), Some(name)) => real_path(parent).join(name), + _ => path.to_path_buf(), + }, + } +} + +/// `path` as given, refused unless absolute, normalised and free of +/// symbolic links. +fn plain_path<'a>(path: &'a Path, what: &str) -> Result<&'a str> { + let Some(text) = path.to_str().filter(|text| !text.is_empty()) else { + return Err(refused(format!("{what} must be a path"))); + }; + if !text.starts_with('/') || normpath(text) != text || text.starts_with("//") { + return Err(refused(format!( + "{what} {text:?} must be an absolute, normalised path" + ))); + } + let real = real_path(path); + if real != path { + return Err(refused(format!( + "{what} {text} resolves to {}; path aliases are refused", + real.display() + ))); + } + Ok(text) +} + +fn existing_file(path: &Path, what: &str, single_link: bool) -> Result<()> { + plain_path(path, what)?; + let info = match std::fs::symlink_metadata(path) { + Ok(info) => info, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => { + return Err(refused(format!("{what} {} does not exist", path.display()))) + } + Err(error) => return Err(io_refused(&format!("inspect {what}"), path, &error)), + }; + if !info.file_type().is_file() { + return Err(refused(format!( + "{what} {} is not a regular file", + path.display() + ))); + } + if single_link && info.nlink() != 1 { + return Err(refused(format!( + "{what} {} has {} hard links; aliases are refused", + path.display(), + info.nlink() + ))); + } + Ok(()) +} + +fn lexists(path: &Path) -> bool { + std::fs::symlink_metadata(path).is_ok() +} + +fn new_or_file(path: &Path, what: &str) -> Result<()> { + plain_path(path, what)?; + let parent = path.parent().unwrap_or(Path::new("/")); + let is_dir = std::fs::symlink_metadata(parent).is_ok_and(|info| info.file_type().is_dir()); + if !is_dir { + return Err(refused(format!( + "the directory of {what} {} does not exist", + path.display() + ))); + } + if lexists(path) { + existing_file(path, what, true)?; + } + Ok(()) +} + +fn existing_dir(path: &Path, what: &str) -> Result<()> { + plain_path(path, what)?; + let info = match std::fs::symlink_metadata(path) { + Ok(info) => info, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => { + return Err(refused(format!("{what} {} does not exist", path.display()))) + } + Err(error) => return Err(io_refused(&format!("inspect {what}"), path, &error)), + }; + if !info.file_type().is_dir() { + return Err(refused(format!( + "{what} {} is not a directory", + path.display() + ))); + } + Ok(()) +} + +/// Whether `child` is `parent` or lies under it, by spelling. +fn inside(child: &Path, parent: &Path) -> bool { + let (child, parent) = (display(child), display(parent)); + child == parent || child.starts_with(&format!("{}/", parent.trim_end_matches('/'))) +} + +fn dirname(path: &Path) -> &Path { + path.parent().unwrap_or(Path::new("/")) +} + +/// Refuse two roles that name one file, by path or by inode. +fn distinct_files(named: &[(&str, Option<&Path>)]) -> Result<()> { + #[derive(PartialEq)] + enum Identity { + Inode(u64, u64), + Missing(PathBuf), + } + let mut seen: Vec<(Identity, &str)> = Vec::new(); + for (what, path) in named { + let Some(path) = path else { continue }; + let identity = match std::fs::metadata(path) { + Ok(info) => Identity::Inode(info.dev(), info.ino()), + Err(_) => Identity::Missing(path.to_path_buf()), + }; + if let Some((_, other)) = seen.iter().find(|(known, _)| *known == identity) { + return Err(refused(format!( + "{what} {} is the same file as {other}", + path.display() + ))); + } + seen.push((identity, what)); + } + Ok(()) +} + +fn key_outside(key: &Path, directories: &[(&str, &Path)]) -> Result<()> { + for (what, directory) in directories { + if inside(key, directory) { + return Err(refused(format!( + "signing key {} is inside the {what} {}; keep the key off that tree", + key.display(), + directory.display() + ))); + } + } + Ok(()) +} + +/// The bytes of a regular file opened without following a symbolic link. +fn read_regular(path: &Path, what: &str) -> Result> { + let mut file = match OpenOptions::new() + .read(true) + .custom_flags(libc::O_NOFOLLOW | libc::O_NONBLOCK | libc::O_CLOEXEC) + .open(path) + { + Ok(file) => file, + Err(error) if error.raw_os_error() == Some(libc::ELOOP) => { + return Err(refused(format!( + "{what} {} is a symbolic link", + path.display() + ))) + } + Err(error) => return Err(io_refused(&format!("open {what}"), path, &error)), + }; + let info = file + .metadata() + .map_err(|error| io_refused(&format!("inspect {what}"), path, &error))?; + if !info.is_file() { + return Err(refused(format!( + "{what} {} is not a regular file", + path.display() + ))); + } + let mut data = Vec::new(); + file.read_to_end(&mut data) + .map_err(|error| io_refused(&format!("read {what}"), path, &error))?; + Ok(data) +} + +fn write_private(path: &Path, data: &[u8]) -> Result<()> { + let mut file = OpenOptions::new() + .write(true) + .create_new(true) + .mode(0o600) + .custom_flags(libc::O_NOFOLLOW | libc::O_CLOEXEC) + .open(path) + .map_err(|error| io_refused("create", path, &error))?; + file.write_all(data) + .and_then(|()| file.sync_all()) + .map_err(|error| io_refused("write", path, &error)) +} + +fn pin(directory: &Path, name: &str, data: &[u8]) -> Result { + let path = directory.join(name); + write_private(&path, data)?; + Ok(path) +} + +fn fsync_dir(path: &Path) -> Result<()> { + File::open(path) + .and_then(|directory| directory.sync_all()) + .map_err(|error| io_refused("flush directory", path, &error)) +} + +fn private_dir(prefix: &str) -> Result { + tempfile::Builder::new() + .prefix(prefix) + .tempdir() + .map_err(|error| refused(format!("cannot create a private directory: {error}"))) +} + +// Log and head readers + +/// A signed head file exactly as `ledger head` and `ledger append` write it. +pub fn parse_head(data: &[u8], what: &str) -> Result { + let text = std::str::from_utf8(data).map_err(|_| refused(format!("{what} is not UTF-8")))?; + let value = strict_json(text, what)?; + let exact = || { + refused(format!( + "{what} must hold exactly {}, in that order", + HEAD_FIELDS.join(", ") + )) + }; + let Value::Object(map) = &value else { + return Err(exact()); + }; + let mut keys = map.keys().map(String::as_str).collect::>(); + let mut expected = HEAD_FIELDS.to_vec(); + keys.sort_unstable(); + expected.sort_unstable(); + if keys != expected { + return Err(exact()); + } + if map["domain"] != ledger::DOMAIN { + return Err(refused(format!( + "{what} domain is {}, not {}", + map["domain"], + ledger::DOMAIN + ))); + } + let size = map["size"] + .as_u64() + .and_then(|size| usize::try_from(size).ok()) + .ok_or_else(|| refused(format!("{what} size must be a non-negative integer")))?; + let hex = |field: &str, pattern: &Regex, length: usize| -> Result { + match map[field].as_str() { + Some(text) if pattern.is_match(text) => Ok(text.to_string()), + _ => Err(refused(format!( + "{what} {field} must be {length} lower-case hex characters" + ))), + } + }; + let root = hex("root", &HEX64, 64)?; + let public_key = hex("public_key", &HEX64, 64)?; + let signature = hex("signature", &HEX128, 128)?; + let ts = match map["ts"].as_str() { + Some(ts) if HEAD_TS.is_match(ts) => ts.to_string(), + _ => { + return Err(refused(format!( + "{what} ts must be RFC 3339 UTC ending in Z" + ))) + } + }; + let head = SignedHead { + domain: ledger::DOMAIN.to_string(), + size, + root, + ts, + public_key, + signature, + }; + let form = serde_json::to_string(&head)? + "\n"; + if form != text { + return Err(refused(format!( + "{what} is not in the form eb-stack writes" + ))); + } + Ok(head) +} + +/// Records of a ledger log, every line checked as [`ledger::verify`] reads +/// it. A log ending in a partial line is refused rather than repaired. +pub fn parse_log(data: &[u8], what: &str) -> Result> { + if data.is_empty() { + return Ok(Vec::new()); + } + if !data.ends_with(b"\n") { + return Err(refused(format!( + "the last line of {what} has no newline; it ends in a partial write" + ))); + } + let text = std::str::from_utf8(data).map_err(|_| refused(format!("{what} is not UTF-8")))?; + ledger::parse_log(text).map_err(|error| { + verification(format!( + "{what} is not a log `ledger verify` accepts: {error:#}" + )) + }) +} + +/// The bytes up to the last newline: a concurrent append may be mid-line. +fn committed_prefix(data: &[u8]) -> &[u8] { + match data.iter().rposition(|byte| *byte == b'\n') { + Some(end) => &data[..=end], + None => &[], + } +} + +/// Write the tile log beside a private copy of a log; verify audits it. +fn tiles(log: &Path, entries: &[Entry]) -> Result<()> { + crate::ledger_tiles::sync(entries, &crate::ledger_tiles::tiles_dir(log, None)) + .map_err(|error| verification(format!("`ledger tiles` failed: {error:#}")))?; + Ok(()) +} + +/// [`ledger::verify`] against private copies of the bytes read. +struct Verifier<'a> { + public_key: &'a Path, +} + +impl Verifier<'_> { + /// Run one proof. The receipt must be `expected`, then one tile-log line + /// for `size` and `root`. A size-0 head over an empty log was signed + /// without a checkpoint and no tile log is audited for it, so the + /// receipt stands alone. + fn run( + &self, + log: &Path, + mode: VerifyMode, + expected: &str, + size: usize, + root: &str, + ) -> Result<()> { + let report = ledger::verify(&VerifyRequest { + log: log.to_path_buf(), + public_key: self.public_key.to_path_buf(), + mode, + tiles: None, + origin: None, + }) + .map_err(|error| verification(format!("`ledger verify` refused: {error:#}")))?; + let receipt = if size == 0 { + expected.to_string() + } else { + format!( + "{expected}tile log size {size} root {root} extends the head and holds the same lines\n" + ) + }; + if report.stdout != receipt { + return Err(verification(format!( + "`ledger verify` printed an unexpected receipt: {:?}", + report.stdout + ))); + } + Ok(()) + } + + /// The signed head is the root of the first `head.size` records of `log`. + fn binds( + &self, + log: &Path, + head_path: &Path, + head: &SignedHead, + records: &[Entry], + ) -> Result<()> { + let (size, root) = (head.size, head.root.as_str()); + if size > records.len() { + return Err(verification(format!( + "head covers {size} records but the ledger has {}", + records.len() + ))); + } + if size == 0 { + return self.run( + log, + VerifyMode::Consistency { + from: head_path.to_path_buf(), + to: head_path.to_path_buf(), + }, + &format!("the head of size 0 root {root} extends the head of size 0 root {root}\n"), + size, + root, + ); + } + let last = size - 1; + self.run( + log, + VerifyMode::Inclusion { + record: last, + head: head_path.to_path_buf(), + }, + &format!( + "record {last} id {} is in the head of size {size} root {root}\n", + records[last].id + ), + size, + root, + ) + } + + fn extends( + &self, + log: &Path, + older_path: &Path, + older: &SignedHead, + newer_path: &Path, + newer: &SignedHead, + ) -> Result<()> { + if older.size == newer.size && older.root != newer.root { + return Err(equivocation(format!( + "two signed heads of size {} have roots {} and {}", + older.size, older.root, newer.root + ))); + } + if older.size > newer.size { + return Err(equivocation(format!( + "the head of size {} is older than an anchored head of size {}", + newer.size, older.size + ))); + } + self.run( + log, + VerifyMode::Consistency { + from: older_path.to_path_buf(), + to: newer_path.to_path_buf(), + }, + &format!( + "the head of size {} root {} extends the head of size {} root {}\n", + newer.size, newer.root, older.size, older.root + ), + newer.size, + &newer.root, + ) + .map_err(|error| { + equivocation(format!( + "the head of size {} does not extend the anchored head: {error}", + newer.size + )) + }) + } +} + +/// Records and the signed head [`ledger::verify`] accepted for them. +#[derive(Debug, Clone)] +pub struct VerifiedLog { + /// The signed head, which covers every record. + pub head: SignedHead, + /// The records. + pub records: Vec, +} + +/// Read `log` and `head` once and verify those bytes. +/// +/// The head must be signed by `public_key` and cover every record: a head +/// that covers fewer is stale and refused, so nothing unverified is read. +pub fn read_verified(log: &Path, head: &Path, public_key: &Path) -> Result { + existing_file(log, "ledger", true)?; + existing_file(head, "head", true)?; + existing_file(public_key, "public key", false)?; + distinct_files(&[ + ("ledger", Some(log)), + ("head", Some(head)), + ("public key", Some(public_key)), + ])?; + let log_bytes = read_regular(log, "ledger")?; + let head_bytes = read_regular(head, "head")?; + let signed = parse_head(&head_bytes, &format!("head {}", head.display()))?; + let records = parse_log(&log_bytes, &format!("ledger {}", log.display()))?; + if signed.size > records.len() { + return Err(verification(format!( + "head {} covers {} records but ledger {} has {}", + head.display(), + signed.size, + log.display(), + records.len() + ))); + } + if signed.size < records.len() { + return Err(fail( + Failure::StaleHead, + format!( + "head {} covers {} of the {} records in {}; sign a current head before reading", + head.display(), + signed.size, + records.len(), + log.display() + ), + )); + } + let private = private_dir("eb-ledger-verify-")?; + let copy_log = pin(private.path(), "ledger.jsonl", &log_bytes)?; + let copy_head = pin(private.path(), "head.json", &head_bytes)?; + tiles(©_log, &records)?; + Verifier { public_key }.binds(©_log, ©_head, &signed, &records)?; + Ok(VerifiedLog { + head: signed, + records, + }) +} + +// Observed-history backfill + +fn is_control(ch: char) -> bool { + matches!( + u32::from(ch), + 0x00..=0x1f | 0x7f..=0x9f | 0x2028 | 0x2029 | 0x202a..=0x202e | 0x2066..=0x2069 + ) +} + +fn label(what: &str) -> String { + if what.is_empty() { + "manifest".to_string() + } else { + format!("manifest {what}") + } +} + +fn manifest_text(value: Option<&Value>, what: &str, path: bool) -> Result { + let text = match value { + Some(Value::String(text)) + if !text.is_empty() && text.trim() == text && !text.chars().any(is_control) => + { + text + } + _ => { + return Err(refused(format!( + "manifest {what} must be a non-empty string without control characters or edge spaces" + ))) + } + }; + if path && (!text.starts_with('/') || normpath(text) != *text) { + return Err(refused(format!( + "manifest {what} must be an absolute, normalised path" + ))); + } + Ok(text.clone()) +} + +fn only<'a>(value: &'a Value, allowed: &[&str], what: &str) -> Result<&'a Map> { + let Value::Object(map) = value else { + return Err(refused(format!("{} must be a JSON object", label(what)))); + }; + let extra = map + .keys() + .filter(|key| !allowed.contains(&key.as_str())) + .cloned() + .collect::>(); + if !extra.is_empty() { + return Err(refused(format!( + "{} has unknown fields {}", + label(what), + extra.into_iter().collect::>().join(", ") + ))); + } + Ok(map) +} + +fn hex64(value: Option<&Value>) -> bool { + value + .and_then(Value::as_str) + .is_some_and(|text| HEX64.is_match(text)) +} + +/// An observed-history manifest, refused unless its bytes hash to +/// `expected_sha256` and it holds nothing after `now`. Returns the manifest +/// and its SHA-256. +pub fn load_manifest( + path: &Path, + expected_sha256: &str, + now: i64, +) -> Result<(Map, String)> { + existing_file(path, "backfill manifest", true)?; + if !HEX64.is_match(expected_sha256) { + return Err(refused( + "the manifest SHA-256 must be 64 lower-case hex characters", + )); + } + let data = read_regular(path, "backfill manifest")?; + let digest = sha256_hex(&data); + if digest != expected_sha256 { + return Err(refused(format!( + "manifest {} hashes to {digest}, not the pinned {expected_sha256}", + path.display() + ))); + } + let text = std::str::from_utf8(&data) + .map_err(|_| refused(format!("manifest {} is not UTF-8", path.display())))?; + let value = strict_json(text, &format!("manifest {}", path.display()))?; + let manifest = only( + &value, + &[ + "schema", + "manifest_id", + "observed_at", + "observer", + "stack", + "target", + "observations", + ], + "", + )?; + if manifest.get("schema").and_then(Value::as_str) != Some(MANIFEST_SCHEMA) { + return Err(refused(format!( + "manifest schema must be {MANIFEST_SCHEMA}" + ))); + } + if !manifest + .get("manifest_id") + .and_then(Value::as_str) + .is_some_and(|id| MANIFEST_ID.is_match(id)) + { + return Err(refused( + "manifest manifest_id must be 1-64 of A-Z a-z 0-9 . _ - starting alphanumeric", + )); + } + let observed = match manifest.get("observed_at").and_then(Value::as_str) { + Some(observed) if OBSERVED_TS.is_match(observed) => observed, + _ => return Err(refused("manifest observed_at must be YYYY-MM-DDTHH:MM:SSZ")), + }; + let seconds = NaiveDateTime::parse_from_str(observed, "%Y-%m-%dT%H:%M:%SZ") + .map_err(|_| refused(format!("manifest observed_at {observed} is not a time")))? + .and_utc() + .timestamp(); + if seconds > now { + return Err(refused(format!( + "manifest observed_at {observed} is after the current time {}", + utc(now) + ))); + } + for key in ["observer", "stack", "target"] { + manifest_text(manifest.get(key), key, false)?; + } + let observations = match manifest.get("observations") { + Some(Value::Array(items)) if !items.is_empty() => items, + _ => return Err(refused("manifest observations must be a non-empty list")), + }; + let mut seen = HashSet::new(); + for (number, item) in observations.iter().enumerate() { + let place = format!("observations[{number}]"); + let item = only( + item, + &["module", "location", "modulefile", "provenance", "note"], + &place, + )?; + let module = manifest_text(item.get("module"), &format!("{place}.module"), false)?; + let location = manifest_text(item.get("location"), &format!("{place}.location"), true)?; + if !seen.insert((module.clone(), location.clone())) { + return Err(refused(format!( + "manifest {place} repeats {module} at {location}" + ))); + } + if let Some(note) = item.get("note") { + manifest_text(Some(note), &format!("{place}.note"), false)?; + } + if let Some(modulefile) = item.get("modulefile") { + let where_ = format!("{place}.modulefile"); + let modulefile = only(modulefile, &["path", "sha256"], &where_)?; + manifest_text(modulefile.get("path"), &format!("{where_}.path"), true)?; + if !hex64(modulefile.get("sha256")) { + return Err(refused(format!( + "manifest {where_}.sha256 must be 64 lower-case hex characters" + ))); + } + } + let provenance = match item.get("provenance") { + Some(Value::Array(refs)) if !refs.is_empty() => refs, + _ => { + return Err(refused(format!( + "manifest {place}.provenance must name at least one original reference" + ))) + } + }; + for (ref_number, reference) in provenance.iter().enumerate() { + let where_ = format!("{place}.provenance[{ref_number}]"); + let reference = only(reference, &["ref", "kind", "sha256"], &where_)?; + manifest_text(reference.get("ref"), &format!("{where_}.ref"), false)?; + if let Some(kind) = reference.get("kind") { + manifest_text(Some(kind), &format!("{where_}.kind"), false)?; + } + if reference.contains_key("sha256") && !hex64(reference.get("sha256")) { + return Err(refused(format!( + "manifest {where_}.sha256 must be 64 lower-case hex characters" + ))); + } + } + } + Ok((manifest.clone(), digest)) +} + +/// One `finding` record per observation, stamped with the observation time. +/// +/// Nothing claims an install or a build happened: the record says the +/// software was seen at `observed_at` and names where the evidence is. +#[must_use] +pub fn backfill_records(manifest: &Map, digest: &str) -> Vec { + let field = |name: &str| manifest[name].as_str().unwrap_or_default().to_string(); + let (manifest_id, observed_at) = (field("manifest_id"), field("observed_at")); + let observations = manifest["observations"] + .as_array() + .cloned() + .unwrap_or_default(); + observations + .iter() + .map(|item| { + let module = item["module"].as_str().unwrap_or_default(); + let location = item["location"].as_str().unwrap_or_default(); + let place = &sha256_hex(location.as_bytes())[..16]; + let mut build = json!({ + "event_id": format!("eb-staged-rebuild/backfill/{manifest_id}/{module}@{place}"), + "tool": TOOL, + "kind": BACKFILL_KIND, + "manifest_id": manifest_id, + "manifest_sha256": digest, + "observed_at": observed_at, + "provenance": item["provenance"], + }); + if let Some(note) = item.get("note") { + build["note"] = note.clone(); + } + let mut record = json!({ + "ts": observed_at, + "actor": field("observer"), + "stack": field("stack"), + "target": field("target"), + "module": module, + "location": location, + "action": "finding", + "reason": format!( + "observed by backfill manifest {manifest_id} at {observed_at}; \ + no history before the observation is recorded" + ), + "build": build, + }); + if let Some(modulefile) = item.get("modulefile") { + record["modulefile"] = modulefile.clone(); + } + record + }) + .collect() +} + +/// What `ledger backfill` needs. +#[derive(Debug, Clone)] +pub struct BackfillRequest { + /// The JSON Lines log. Created when absent. + pub log: PathBuf, + /// Ed25519 PKCS#8 PEM key, off the log's and the head's trees. + pub key: PathBuf, + /// File for the signed head after each append. + pub head: PathBuf, + /// The public key the head must verify under. + pub public_key: PathBuf, + /// The observed-history manifest. + pub manifest: PathBuf, + /// The manifest's SHA-256, lower-case hex. + pub manifest_sha256: String, + /// The current time, seconds since the epoch. + pub now: i64, +} + +fn body(record: &Map) -> Value { + let mut body = record.clone(); + for key in ["id", "index", "sig"] { + body.remove(key); + } + Value::Object(body) +} + +/// Append the manifest's observations, each at most once. +/// +/// Every record is built from the manifest alone, so a retry sends the same +/// bytes and the ledger acknowledges it as already recorded. The log is +/// checked first: a manifest id already backfilled from other bytes, or an +/// event id recorded with other content, is refused before anything is +/// appended. Each receipt needs [`ledger::verify`] to prove the record is in +/// the signed head written by the append. +pub fn backfill(request: &BackfillRequest) -> Result { + let (log, key, head) = (&request.log, &request.key, &request.head); + new_or_file(log, "ledger")?; + new_or_file(head, "head")?; + existing_file(key, "signing key", true)?; + existing_file(&request.public_key, "public key", false)?; + distinct_files(&[ + ("ledger", Some(log.as_path())), + ("head", Some(head.as_path())), + ("signing key", Some(key.as_path())), + ("public key", Some(request.public_key.as_path())), + ("backfill manifest", Some(request.manifest.as_path())), + ])?; + key_outside( + key, + &[ + ("ledger directory", dirname(log)), + ("head directory", dirname(head)), + ], + )?; + let (manifest, digest) = + load_manifest(&request.manifest, &request.manifest_sha256, request.now)?; + let records = backfill_records(&manifest, &digest); + let manifest_id = manifest["manifest_id"].as_str().unwrap_or_default(); + let stack = manifest["stack"].as_str().unwrap_or_default(); + // The ledger quarantines an interrupted tail on the next append. + let existing = if lexists(log) { + let data = read_regular(log, "ledger")?; + parse_log( + committed_prefix(&data), + &format!("ledger {}", log.display()), + )? + } else { + Vec::new() + }; + if let Some(first) = existing.first() { + if first.record["stack"] != stack { + return Err(refused(format!( + "manifest stack {stack:?} is not the ledger's stack {}", + first.record["stack"] + ))); + } + } + let mut by_event: HashMap = HashMap::new(); + for entry in &existing { + let Some(build) = entry.record.get("build").and_then(Value::as_object) else { + continue; + }; + if build.get("kind").and_then(Value::as_str) == Some(BACKFILL_KIND) + && build.get("manifest_id").and_then(Value::as_str) == Some(manifest_id) + && build.get("manifest_sha256").and_then(Value::as_str) != Some(digest.as_str()) + { + return Err(refused(format!( + "manifest {manifest_id} was backfilled from bytes hashing to {}, not {digest}; \ + a backfill manifest is immutable", + build.get("manifest_sha256").unwrap_or(&Value::Null) + ))); + } + if let Some(event_id) = build.get("event_id").and_then(Value::as_str) { + by_event.insert(event_id.to_string(), entry); + } + } + for record in &records { + let event_id = record["build"]["event_id"].as_str().unwrap_or_default(); + if let Some(entry) = by_event.get(event_id) { + if body(&entry.record) != *record { + return Err(refused(format!( + "ledger record {} holds {event_id} with other content", + entry.index + ))); + } + } + } + let private = private_dir("eb-ledger-backfill-")?; + let mut receipts = Vec::new(); + for (number, record) in records.iter().enumerate() { + let event_id = record["build"]["event_id"] + .as_str() + .unwrap_or_default() + .to_string(); + let path = private.path().join(format!("{number:06}.json")); + write_private(&path, (dumps(record, None) + "\n").as_bytes())?; + let mut receipt = append_one(request, &path, &event_id)?; + receipt["event_id"] = Value::from(event_id); + receipts.push(receipt); + } + let replayed = receipts + .iter() + .filter(|receipt| receipt["replayed"] == true) + .count(); + Ok(json!({ + "manifest_id": manifest_id, + "manifest_sha256": digest, + "appended": receipts.len() - replayed, + "replayed": replayed, + "receipts": receipts, + })) +} + +/// Append one record and prove it is in the head the append signed. +fn append_one(request: &BackfillRequest, record: &Path, event_id: &str) -> Result { + let report = ledger::append(&ledger::AppendRequest { + log: request.log.clone(), + record: record.to_path_buf(), + expect_head: None, + key: Some(request.key.clone()), + head_out: Some(request.head.clone()), + tiles: None, + origin: None, + }) + .map_err(|error| pending(format!("`ledger append` failed: {error:#}")))?; + let (index, size, root) = (report.index, report.head.size, &report.head.root); + let written = SignedHead::read(&request.head).map_err(|error| { + pending(format!( + "cannot read head {}: {error:#}", + request.head.display() + )) + })?; + if written.size != size || written.root != *root || index >= size { + return Err(pending(format!( + "head {} is size {} root {}, not the reported size {size} root {root} covering record {index}", + request.head.display(), + written.size, + written.root + ))); + } + let log = std::fs::read(&request.log).map_err(|error| { + pending(format!( + "cannot read ledger {}: {error}", + request.log.display() + )) + })?; + let logged = log + .split(|byte| *byte == b'\n') + .nth(index) + .and_then(|line| serde_json::from_slice::(line).ok()) + .and_then(|line| line["build"]["event_id"].as_str().map(str::to_string)); + if logged.as_deref() != Some(event_id) { + return Err(pending(format!( + "ledger record {index} is not event {event_id}" + ))); + } + ledger::verify(&VerifyRequest { + log: request.log.clone(), + public_key: request.public_key.clone(), + mode: VerifyMode::Inclusion { + record: index, + head: request.head.clone(), + }, + tiles: None, + origin: None, + }) + .map_err(|error| pending(format!("`ledger verify` failed: {error:#}")))?; + Ok(json!({ + "index": index, + "id": report.id, + "head_size": size, + "head_root": root, + "replayed": report.replayed, + "verified": true, + })) +} + +// Daily anchors + +/// One anchor file and the head it holds. +#[derive(Debug, Clone)] +struct Anchor { + day: String, + path: PathBuf, + head: SignedHead, + bytes: Vec, +} + +/// Anchors by day, each a single-link regular file whose head is signed +/// that day, each extending the one before it. +fn list_anchors(anchors: &Path) -> Result> { + let mut names = std::fs::read_dir(anchors) + .map_err(|error| io_refused("list anchor directory", anchors, &error))? + .filter_map(|entry| entry.ok()?.file_name().into_string().ok()) + .collect::>(); + names.sort(); + let mut found: Vec = Vec::new(); + for name in names { + let Some(day) = ANCHOR_NAME + .captures(&name) + .map(|groups| groups[1].to_string()) + else { + continue; + }; + let path = anchors.join(&name); + let info = std::fs::symlink_metadata(&path) + .map_err(|error| io_refused("inspect anchor", &path, &error))?; + if !info.file_type().is_file() || info.nlink() != 1 { + return Err(refused(format!( + "anchor {} must be a regular file with one link", + path.display() + ))); + } + let bytes = read_regular(&path, "anchor")?; + let head = parse_head(&bytes, &format!("anchor {}", path.display()))?; + if head.ts[..10] != day { + return Err(refused(format!( + "anchor {} holds a head signed at {}, not on {day}", + path.display(), + head.ts + ))); + } + found.push(Anchor { + day, + path, + head, + bytes, + }); + } + for pair in found.windows(2) { + let (older, newer) = (&pair[0], &pair[1]); + let (a, b) = (&older.head, &newer.head); + if a.public_key != b.public_key { + return Err(equivocation(format!( + "anchors {} and {} are signed by different keys", + older.path.display(), + newer.path.display() + ))); + } + if b.ts < a.ts { + return Err(refused(format!( + "anchor {} is signed before {}", + newer.path.display(), + older.path.display() + ))); + } + if b.size < a.size || (b.size == a.size && b.root != a.root) { + return Err(equivocation(format!( + "anchor {} does not extend {}", + newer.path.display(), + older.path.display() + ))); + } + } + Ok(found) +} + +/// Remove what an interrupted run left in the anchor directory. +fn clear_staging(anchors: &Path) -> Result<()> { + let entries = std::fs::read_dir(anchors) + .map_err(|error| io_refused("list anchor directory", anchors, &error))?; + for entry in entries { + let entry = entry.map_err(|error| io_refused("list anchor directory", anchors, &error))?; + if !entry + .file_name() + .as_encoded_bytes() + .starts_with(STAGING_PREFIX.as_bytes()) + { + continue; + } + let path = entry.path(); + let is_dir = std::fs::symlink_metadata(&path).is_ok_and(|info| info.file_type().is_dir()); + let removed = if is_dir { + std::fs::remove_dir_all(&path) + } else { + std::fs::remove_file(&path) + }; + removed.map_err(|error| io_refused("remove", &path, &error))?; + } + fsync_dir(anchors) +} + +fn anchor_paths(log: &Path, key: Option<&Path>, public_key: &Path, anchors: &Path) -> Result<()> { + existing_file(log, "ledger", true)?; + existing_file(public_key, "public key", false)?; + existing_dir(anchors, "anchor directory")?; + if let Some(key) = key { + existing_file(key, "signing key", true)?; + key_outside( + key, + &[ + ("ledger directory", dirname(log)), + ("anchor directory", anchors), + ], + )?; + } + if anchors == dirname(log) || inside(log, anchors) { + return Err(refused(format!( + "anchor directory {} must not hold the ledger {}", + anchors.display(), + log.display() + ))); + } + distinct_files(&[ + ("ledger", Some(log)), + ("signing key", key), + ("public key", Some(public_key)), + ]) +} + +/// The anchor directory's lock: a `flock` gate on `.lock` and a POSIX +/// record lock on `.lock.posix`, released in the reverse order. +struct DirectoryLock { + gate: Option, + record: Option, +} + +impl DirectoryLock { + fn open(directory: &Path, name: &str) -> Result { + let path = directory.join(name); + let private = |info: &std::fs::Metadata| info.file_type().is_file() && info.nlink() == 1; + if let Ok(info) = std::fs::symlink_metadata(&path) { + if !private(&info) { + return Err(refused(format!( + "lock file must be a private regular file: {}", + path.display() + ))); + } + } + let file = OpenOptions::new() + .read(true) + .write(true) + .create(true) + .truncate(false) + .mode(0o600) + .custom_flags(libc::O_NOFOLLOW | libc::O_NONBLOCK | libc::O_CLOEXEC) + .open(&path) + .map_err(|error| io_refused("open lock", &path, &error))?; + let info = file + .metadata() + .map_err(|error| io_refused("inspect lock", &path, &error))?; + if !private(&info) { + return Err(refused(format!( + "lock file must be a private regular file: {}", + path.display() + ))); + } + file.set_permissions(std::fs::Permissions::from_mode(0o600)) + .map_err(|error| io_refused("set the mode of lock", &path, &error))?; + Ok(file) + } + + /// Retry `take` until it succeeds or `deadline` passes. + fn wait( + path: &Path, + deadline: Instant, + mut take: impl FnMut() -> std::io::Result<()>, + ) -> Result<()> { + loop { + match take() { + Ok(()) => return Ok(()), + Err(error) + if error.raw_os_error() == Some(libc::EWOULDBLOCK) + || error.raw_os_error() == Some(libc::EAGAIN) + || error.raw_os_error() == Some(libc::EACCES) + || error.kind() == std::io::ErrorKind::Interrupted => + { + if Instant::now() >= deadline { + return Err(refused(format!( + "another anchor run holds the lock at {}", + path.display() + ))); + } + std::thread::sleep(LOCK_RETRY); + } + Err(error) => return Err(io_refused("lock", path, &error)), + } + } + } + + fn acquire(directory: &Path, timeout: Duration) -> Result { + let deadline = Instant::now() + timeout; + let mut lock = Self { + gate: None, + record: None, + }; + let gate = Self::open(directory, ".lock")?; + Self::wait(&directory.join(".lock"), deadline, || { + // The descriptor is open for the duration of the call. + let result = unsafe { libc::flock(gate.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) }; + if result == 0 { + Ok(()) + } else { + Err(std::io::Error::last_os_error()) + } + })?; + lock.gate = Some(gate); + let record = Self::open(directory, ".lock.posix")?; + Self::wait(&directory.join(".lock.posix"), deadline, || { + // All-zero offsets cover the whole file; flock's scalar fields + // have valid zero representations on the supported Unix targets. + let mut request: libc::flock = unsafe { std::mem::zeroed() }; + request.l_type = libc::F_WRLCK as _; + request.l_whence = libc::SEEK_SET as _; + // The descriptor stays open and request is fully initialized. + let result = unsafe { libc::fcntl(record.as_raw_fd(), libc::F_SETLK, &request) }; + if result == -1 { + Err(std::io::Error::last_os_error()) + } else { + Ok(()) + } + })?; + lock.record = Some(record); + if let Some(gate) = &mut lock.gate { + let path = directory.join(".lock"); + gate.set_len(0) + .and_then(|()| gate.write_all(format!("{}\n", std::process::id()).as_bytes())) + .map_err(|error| io_refused("write lock", &path, &error))?; + } + Ok(lock) + } +} + +impl Drop for DirectoryLock { + fn drop(&mut self) { + // Closing the record lock's descriptor releases it before the gate. + drop(self.record.take()); + if let Some(gate) = self.gate.take() { + // The descriptor is open until it is dropped below. + unsafe { libc::flock(gate.as_raw_fd(), libc::LOCK_UN) }; + } + } +} + +/// What `ledger anchor` needs. +#[derive(Debug, Clone)] +pub struct AnchorRequest { + /// The JSON Lines log. + pub log: PathBuf, + /// Ed25519 PKCS#8 PEM key, off the log's and the anchors' trees. + pub key: PathBuf, + /// The public key every anchor must verify under. + pub public_key: PathBuf, + /// The directory of daily anchors, outside the log's directory. + pub anchors: PathBuf, + /// The current time, seconds since the epoch. + pub now: i64, +} + +/// Publish today's signed head as `/.head.json`, once. +/// +/// The head is signed now, for the day it is signed on: no anchor is made +/// for another day. It must bind to the log and extend the latest anchor, +/// both proved by [`ledger::verify`], before it is linked into place. An +/// existing file is never replaced: when today's anchor exists the call +/// proves it still extends into the log and reports it. +pub fn anchor(request: &AnchorRequest) -> Result { + let (log, key, anchors) = (&request.log, &request.key, &request.anchors); + anchor_paths(log, Some(key.as_path()), &request.public_key, anchors)?; + let lock = DirectoryLock::acquire(anchors, LOCK_TIMEOUT)?; + clear_staging(anchors)?; + let ts = utc(request.now); + let day = ts[..10].to_string(); + let existing = list_anchors(anchors)?; + if let Some(later) = existing.iter().rev().find(|item| item.day > day) { + return Err(refused(format!( + "anchor {} is for a day after {day}; check the clock", + later.path.display() + ))); + } + let today = existing.iter().find(|item| item.day == day); + let prior = today.or(existing.last()); + let staging = tempfile::Builder::new() + .prefix(STAGING_PREFIX) + .tempdir_in(anchors) + .map_err(|error| io_refused("create a staging directory in", anchors, &error))?; + let result = publish(request, staging.path(), &ts, &day, today, prior); + let _ = staging.close(); + let synced = fsync_dir(anchors); + drop(lock); + let value = result?; + synced?; + Ok(value) +} + +fn publish( + request: &AnchorRequest, + staging: &Path, + ts: &str, + day: &str, + today: Option<&Anchor>, + prior: Option<&Anchor>, +) -> Result { + let (log, anchors) = (&request.log, &request.anchors); + let candidate = staging.join("head.json"); + let report = ledger::sign_head(&ledger::HeadRequest { + log: log.clone(), + key: request.key.clone(), + out: candidate.clone(), + ts: Some(ts.to_string()), + tiles: None, + origin: None, + }) + .map_err(|error| pending(format!("`ledger head` failed: {error:#}")))?; + let signed_bytes = read_regular(&candidate, "signed head")?; + let signed = parse_head(&signed_bytes, "the signed head")?; + // An empty log has no record to derive a checkpoint origin from and is + // signed alone; any other head comes with a checkpoint of the same tree. + let checkpoint_agrees = match &report.checkpoint { + None => signed.size == 0, + Some(checkpoint) => checkpoint.size == signed.size as u64 && checkpoint.root == signed.root, + }; + if report.head != signed || !checkpoint_agrees { + return Err(pending(format!( + "`ledger head` reported size {} root {} but wrote {} with size {} root {}", + report.head.size, + report.head.root, + candidate.display(), + signed.size, + signed.root + ))); + } + if signed.ts != ts { + return Err(pending(format!( + "`ledger head` signed at {}, not {ts}", + signed.ts + ))); + } + let data = read_regular(log, "ledger")?; + let snapshot = committed_prefix(&data); + let records = parse_log(snapshot, &format!("ledger {}", log.display()))?; + let verifier = Verifier { + public_key: &request.public_key, + }; + let private_log = pin(staging, "ledger.jsonl", snapshot)?; + tiles(&private_log, &records)?; + verifier.binds(&private_log, &candidate, &signed, &records)?; + if let Some(prior) = prior { + let prior_path = pin(staging, "prior.json", &prior.bytes)?; + verifier.extends(&private_log, &prior_path, &prior.head, &candidate, &signed)?; + } + if let Some(today) = today { + return Ok(json!({ + "status": "exists", + "day": day, + "path": display(&today.path), + "size": today.head.size, + "root": today.head.root, + })); + } + let target = anchors.join(format!("{day}.head.json")); + std::fs::set_permissions(&candidate, std::fs::Permissions::from_mode(0o444)) + .map_err(|error| io_refused("set the mode of", &candidate, &error))?; + OpenOptions::new() + .read(true) + .custom_flags(libc::O_NOFOLLOW) + .open(&candidate) + .and_then(|file| file.sync_all()) + .map_err(|error| io_refused("flush", &candidate, &error))?; + match std::fs::hard_link(&candidate, &target) { + Ok(()) => {} + Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => { + return Err(refused(format!( + "anchor {} appeared while this one was prepared; rerun to verify it", + target.display() + ))) + } + Err(error) => return Err(io_refused("link", &target, &error)), + } + fsync_dir(anchors)?; + Ok(json!({ + "status": "published", + "day": day, + "path": display(&target), + "size": signed.size, + "root": signed.root, + })) +} + +/// Prove every anchor extends the one before it and the latest binds to +/// the log. +pub fn verify_anchors(log: &Path, public_key: &Path, anchors: &Path) -> Result { + anchor_paths(log, None, public_key, anchors)?; + let found = list_anchors(anchors)?; + let Some(latest) = found.last() else { + return Ok(json!({"anchors": 0})); + }; + let data = read_regular(log, "ledger")?; + let snapshot = committed_prefix(&data); + let records = parse_log(snapshot, &format!("ledger {}", log.display()))?; + let verifier = Verifier { public_key }; + let private = private_dir("eb-ledger-anchors-")?; + let private_log = pin(private.path(), "ledger.jsonl", snapshot)?; + tiles(&private_log, &records)?; + let pinned = found + .iter() + .enumerate() + .map(|(number, item)| pin(private.path(), &format!("{number:06}.json"), &item.bytes)) + .collect::>>()?; + for number in 1..found.len() { + verifier.extends( + &private_log, + &pinned[number - 1], + &found[number - 1].head, + &pinned[number], + &found[number].head, + )?; + } + verifier.binds( + &private_log, + &pinned[found.len() - 1], + &latest.head, + &records, + )?; + Ok(json!({ + "anchors": found.len(), + "latest": display(&latest.path), + "size": latest.head.size, + "root": latest.head.root, + })) +} + +// Package history projections + +/// The package of a module name: the part before the first `/`. +#[must_use] +pub fn package_of(module: &str) -> &str { + module.split('/').next().unwrap_or(module) +} + +struct Effective { + voided: HashSet, + corrected_by: HashMap>, + pending_by: HashMap>, + problems: Vec, +} + +fn problem(index: usize, field: &str, target: &Value, text: &str) -> Value { + json!({"index": index, "field": field, "target": target, "problem": text}) +} + +/// Which records a later applied correction voided, and why. +/// +/// A correction applies when it is stageless or `finished`, names an +/// earlier record, and is not itself voided. Walking from the newest record +/// settles corrections of corrections. +fn effective(records: &[Entry]) -> Effective { + let by_id = records + .iter() + .map(|entry| (entry.id.as_str(), entry.index)) + .collect::>(); + let mut result = Effective { + voided: HashSet::new(), + corrected_by: HashMap::new(), + pending_by: HashMap::new(), + problems: Vec::new(), + }; + for entry in records { + for field in LINKS { + if let Some(target) = entry.record.get(*field) { + if !target.as_str().is_some_and(|id| by_id.contains_key(id)) { + result.problems.push(problem( + entry.index, + field, + target, + "names no record in this log", + )); + } + } + } + } + for entry in records.iter().rev() { + if entry.record["action"] != "correction" { + continue; + } + let corrects = &entry.record["corrects"]; + let Some(&target) = corrects.as_str().and_then(|id| by_id.get(id)) else { + continue; + }; + if target >= entry.index { + result.problems.push(problem( + entry.index, + "corrects", + corrects, + "names a record that is not earlier", + )); + continue; + } + let stage = entry.record.get("stage").and_then(Value::as_str); + if result.voided.contains(&entry.index) || stage == Some("aborted") { + continue; + } + if stage == Some("started") { + result + .pending_by + .entry(target) + .or_default() + .push(entry.index); + continue; + } + result.voided.insert(target); + result + .corrected_by + .entry(target) + .or_default() + .push(entry.index); + } + result +} + +fn state_of(action: &str) -> Option<&'static str> { + Some(match action { + "install" | "rebuild-inplace" | "rebuild-bump" | "unretire" => "installed", + "retire" => "retired", + "remove" => "removed", + "move" => "moved", + _ => return None, + }) +} + +/// The deterministic history model of a verified log, grouped by package. +#[must_use] +pub fn build_history(verified: &VerifiedLog) -> Value { + let records = &verified.records; + let effective = effective(records); + let by_id = records + .iter() + .map(|entry| (entry.id.as_str(), entry.index)) + .collect::>(); + let mut packages: BTreeMap> = BTreeMap::new(); + for entry in records { + let record = &entry.record; + let index = entry.index; + let empty = Map::new(); + let build = record + .get("build") + .and_then(Value::as_object) + .unwrap_or(&empty); + let observed = build.get("kind").and_then(Value::as_str) == Some(BACKFILL_KIND); + let get = + |map: &Map, key: &str| map.get(key).cloned().unwrap_or(Value::Null); + let mut links = Map::new(); + for field in LINKS { + if let Some(target) = record.get(*field) { + let linked = target + .as_str() + .and_then(|id| by_id.get(id)) + .map_or(Value::Null, |index| Value::from(*index)); + links.insert((*field).to_string(), json!({"id": target, "index": linked})); + } + } + let (provenance, manifest_id) = if observed { + (get(build, "provenance"), get(build, "manifest_id")) + } else { + (Value::Null, Value::Null) + }; + let status = if effective.voided.contains(&index) { + "corrected" + } else { + "effective" + }; + let event = json!({ + "index": index, + "id": entry.id, + "ts": record["ts"], + "action": record["action"], + "stage": get(record, "stage"), + "actor": record["actor"], + "target": record["target"], + "module": record["module"], + "location": record["location"], + "event_id": get(build, "event_id"), + "reason": get(record, "reason"), + "modulefile": get(record, "modulefile"), + "links": links, + "observed": observed, + "provenance": provenance, + "manifest_id": manifest_id, + "status": status, + "corrected_by": effective.corrected_by.get(&index).cloned().unwrap_or_default(), + "correction_pending_by": effective.pending_by.get(&index).cloned().unwrap_or_default(), + }); + packages + .entry(package_of(entry.module()).to_string()) + .or_default() + .push(event); + } + let mut model = Vec::new(); + for (name, events) in packages { + let mut modules: BTreeMap = BTreeMap::new(); + for event in &events { + let module = event["module"].as_str().unwrap_or_default().to_string(); + let state = modules.entry(module.clone()).or_insert_with(|| { + json!({ + "module": module, "state": "unknown", "location": null, + "last_change": null, "access": [], "findings": [], + }) + }); + if event["status"] != "effective" + || !(event["stage"].is_null() || event["stage"] == "finished") + { + continue; + } + let action = event["action"].as_str().unwrap_or_default(); + let index = event["index"].clone(); + if action == "access" { + state["access"] + .as_array_mut() + .expect("access list") + .push(index); + } else if action == "finding" { + state["findings"] + .as_array_mut() + .expect("finding list") + .push(index.clone()); + if state["state"] == "unknown" { + state["state"] = Value::from("observed"); + state["location"] = event["location"].clone(); + state["last_change"] = index; + } + } else if let Some(next) = state_of(action) { + state["state"] = Value::from(next); + state["location"] = event["location"].clone(); + state["last_change"] = index; + } + } + let package_problems = effective + .problems + .iter() + .filter(|problem| { + problem["index"] + .as_u64() + .and_then(|index| records.get(usize::try_from(index).ok()?)) + .is_some_and(|entry| package_of(entry.module()) == name) + }) + .cloned() + .collect::>(); + model.push(json!({ + "name": name, + "modules": modules.into_values().collect::>(), + "events": events, + "problems": package_problems, + })); + } + let head = &verified.head; + json!({ + "schema": HISTORY_SCHEMA, + "head": {"size": head.size, "root": head.root, "ts": head.ts, "public_key": head.public_key}, + "stack": records.first().map_or(Value::Null, |entry| entry.record["stack"].clone()), + "packages": model, + "problems": effective.problems, + }) +} + +/// `text` percent-encoded as URL quoting does: letters, digits, `_.-~` and +/// the characters in `safe` are kept, every other UTF-8 byte is `%XX`. +fn quote(text: &str, safe: &str) -> String { + let mut out = String::new(); + for byte in text.bytes() { + let ch = char::from(byte); + if byte.is_ascii_alphanumeric() + || "_.-~".contains(ch) + || (byte.is_ascii() && safe.contains(ch)) + { + out.push(ch); + } else { + let _ = write!(out, "%{byte:02X}"); + } + } + out +} + +/// A file name for a package that cannot leave the output directory. +#[must_use] +pub fn file_stem(name: &str) -> String { + let stem = quote(name, ""); + if stem.is_empty() || stem == "." || stem == ".." || stem.len() > 150 { + let keep = stem.len().min(100); + return format!("{}-{}", &stem[..keep], &sha256_hex(name.as_bytes())[..16]); + } + stem +} + +fn md_text(value: &str) -> String { + let mut out = String::new(); + for ch in value.chars() { + match ch { + '&' => out.push_str("&"), + '<' => out.push_str("<"), + '>' => out.push_str(">"), + _ if is_control(ch) => { + let _ = write!(out, "U+{:04X}", u32::from(ch)); + } + '\\' | '`' | '*' | '_' | '[' | ']' | '(' | ')' | '|' | '~' | '!' | '#' => { + out.push('\\'); + out.push(ch); + } + _ => out.push(ch), + } + } + out +} + +/// Text safe in a Markdown table cell: no markup, HTML, line breaks or +/// bidirectional controls. A value that is not a string is its canonical +/// JSON; `null` is empty. +#[must_use] +pub fn md(value: &Value) -> String { + match value { + Value::Null => String::new(), + Value::String(text) => md_text(text), + other => md_text(&ledger::canonical(other).unwrap_or_else(|_| other.to_string())), + } +} + +fn index_text(value: &Value) -> String { + value + .as_u64() + .map_or_else(|| value.to_string(), |index| index.to_string()) +} + +fn details(event: &Value) -> String { + let mut parts = Vec::new(); + if let Some(links) = event["links"].as_object() { + for (field, link) in links { + let where_ = if link["index"].is_null() { + format!("unknown record {}", link["id"].as_str().unwrap_or_default()) + } else { + format!("#{}", index_text(&link["index"])) + }; + parts.push(format!("{field} {where_}")); + } + } + let indices = |key: &str| { + event[key] + .as_array() + .map(|items| { + items + .iter() + .map(|index| format!("#{}", index_text(index))) + .collect::>() + }) + .unwrap_or_default() + }; + let corrected = indices("corrected_by"); + if !corrected.is_empty() { + parts.push(format!("corrected by {}", corrected.join(", "))); + } + let started = indices("correction_pending_by"); + if !started.is_empty() { + parts.push(format!("correction started by {}", started.join(", "))); + } + if event["observed"] == true { + let refs = event["provenance"] + .as_array() + .map(|refs| { + refs.iter() + .map(|reference| { + let mut text = reference["ref"].as_str().unwrap_or_default().to_string(); + if let Some(sha) = reference.get("sha256").and_then(Value::as_str) { + text.push_str(&format!(" sha256 {sha}")); + } + text + }) + .collect::>() + .join("; ") + }) + .unwrap_or_default(); + parts.push(format!( + "observed by manifest {}; provenance {refs}", + event["manifest_id"].as_str().unwrap_or_default() + )); + } + match &event["reason"] { + Value::Null => {} + Value::String(reason) => parts.push(format!("reason {reason}")), + other => parts.push(format!( + "reason {}", + ledger::canonical(other).unwrap_or_else(|_| other.to_string()) + )), + } + md_text(&parts.join("; ")) +} + +fn head_lines(model: &Value) -> Vec { + let head = &model["head"]; + vec![ + format!("Stack: {}", md(&model["stack"])), + String::new(), + format!( + "Verified head: size {}, root {}, signed {} by {}.", + index_text(&head["size"]), + head["root"].as_str().unwrap_or_default(), + head["ts"].as_str().unwrap_or_default(), + head["public_key"].as_str().unwrap_or_default() + ), + String::new(), + ] +} + +fn plain(value: &Value) -> &str { + value.as_str().unwrap_or_default() +} + +/// The Markdown history page of one package of the model [`build_history`] +/// makes. +#[must_use] +pub fn render_package(model: &Value, package: &Value) -> String { + let mut lines = vec![ + format!("# Package history: {}", md(&package["name"])), + String::new(), + ]; + lines.extend(head_lines(model)); + lines.extend( + [ + "## Modules", + "", + "| Module | State | Last change | Location |", + "| --- | --- | --- | --- |", + ] + .map(String::from), + ); + for module in package["modules"].as_array().into_iter().flatten() { + let change = if module["last_change"].is_null() { + String::new() + } else { + format!("#{}", index_text(&module["last_change"])) + }; + lines.push(format!( + "| {} | {} | {change} | {} |", + md(&module["module"]), + plain(&module["state"]), + md(&module["location"]) + )); + } + lines.extend( + [ + "", + "## Events", + "", + "| # | Time (UTC) | Action | Stage | Module | Actor | Status | Details |", + "| --- | --- | --- | --- | --- | --- | --- | --- |", + ] + .map(String::from), + ); + for event in package["events"].as_array().into_iter().flatten() { + lines.push(format!( + "| {} | {} | {} | {} | {} | {} | {} | {} |", + index_text(&event["index"]), + md(&event["ts"]), + plain(&event["action"]), + plain(&event["stage"]), + md(&event["module"]), + md(&event["actor"]), + plain(&event["status"]), + details(event) + )); + } + let problems = package["problems"].as_array().cloned().unwrap_or_default(); + if !problems.is_empty() { + lines.extend(["", "## Problems", ""].map(String::from)); + for problem in problems { + lines.push(format!( + "* record #{} {} {}: {}", + index_text(&problem["index"]), + plain(&problem["field"]), + md(&problem["target"]), + plain(&problem["problem"]) + )); + } + } + lines.join("\n") + "\n" +} + +fn json_bytes(value: &Value) -> Vec { + (dumps(value, Some(2)) + "\n").into_bytes() +} + +/// Every output file, by path relative to the output directory. +pub fn render(model: &Value) -> Result>> { + let mut files = BTreeMap::new(); + let mut index = Vec::new(); + let mut stems = HashSet::new(); + for package in model["packages"].as_array().into_iter().flatten() { + let name = plain(&package["name"]); + let stem = file_stem(name); + if !stems.insert(stem.clone()) { + return Err(refused(format!("two packages map to the file name {stem}"))); + } + let document = json!({ + "schema": model["schema"], "head": model["head"], "stack": model["stack"], + "package": name, "modules": package["modules"], "events": package["events"], + "problems": package["problems"], + }); + files.insert(format!("packages/{stem}.json"), json_bytes(&document)); + files.insert( + format!("packages/{stem}.md"), + render_package(model, package).into_bytes(), + ); + let count = |key: &str| package[key].as_array().map_or(0, Vec::len); + index.push(json!({ + "name": name, "json": format!("packages/{stem}.json"), + "markdown": format!("packages/{stem}.md"), + "modules": count("modules"), "events": count("events"), + })); + } + let mut lines = vec!["# Ledger package history".to_string(), String::new()]; + lines.extend(head_lines(model)); + lines.push("| Package | Modules | Events |".to_string()); + lines.push("| --- | --- | --- |".to_string()); + for entry in &index { + lines.push(format!( + "| [{}]({}) | {} | {} |", + md(&entry["name"]), + quote(plain(&entry["markdown"]), "/"), + entry["modules"], + entry["events"] + )); + } + files.insert( + "index.json".to_string(), + json_bytes(&json!({ + "schema": model["schema"], "head": model["head"], "stack": model["stack"], + "packages": index, "problems": model["problems"], + })), + ); + files.insert( + "index.md".to_string(), + (lines.join("\n") + "\n").into_bytes(), + ); + Ok(files) +} + +fn list_names(directory: &Path) -> Result> { + Ok(std::fs::read_dir(directory) + .map_err(|error| io_refused("list", directory, &error))? + .filter_map(|entry| Some(entry.ok()?.file_name().to_string_lossy().into_owned())) + .collect()) +} + +fn output_dir(out: &Path, log: &Path, head: &Path, public_key: &Path) -> Result<()> { + plain_path(out, "output directory")?; + for (what, path) in [("ledger", log), ("head", head), ("public key", public_key)] { + if inside(path, out) || out == dirname(path) { + return Err(refused(format!( + "output directory {} must not hold the {what} {}", + out.display(), + path.display() + ))); + } + } + if !lexists(out) { + return Ok(()); + } + existing_dir(out, "output directory")?; + let names = list_names(out)?; + let allowed = [ + "index.json", + "index.md", + ".index.json.new", + ".index.md.new", + "packages", + ]; + let mut foreign = names + .iter() + .filter(|name| !allowed.contains(&name.as_str())) + .cloned() + .collect::>(); + if names.contains("packages") { + let packages = out.join("packages"); + if !std::fs::symlink_metadata(&packages).is_ok_and(|info| info.file_type().is_dir()) { + return Err(refused(format!( + "{} must be a directory", + packages.display() + ))); + } + foreign.extend(list_names(&packages)?.into_iter().filter(|name| { + ![".json", ".md", ".json.new", ".md.new"] + .iter() + .any(|suffix| name.ends_with(suffix)) + })); + } + if !foreign.is_empty() { + return Err(refused(format!( + "output directory {} holds files that are not a ledger history projection: {}", + out.display(), + foreign.into_iter().collect::>().join(", ") + ))); + } + if names.contains("index.json") { + let data = read_regular(&out.join("index.json"), "projection index")?; + let schema = serde_json::from_slice::(&data) + .ok() + .and_then(|index| { + index + .get("schema") + .and_then(Value::as_str) + .map(str::to_string) + }); + if schema.as_deref() != Some(HISTORY_SCHEMA) { + return Err(refused(format!( + "output directory {} holds an index that is not a ledger history projection", + out.display() + ))); + } + } + Ok(()) +} + +fn identity(info: &std::fs::Metadata) -> (u64, u64, u32, u32, u32, i64, i64) { + ( + info.dev(), + info.ino(), + info.uid(), + info.gid(), + info.mode(), + info.ctime(), + info.ctime_nsec(), + ) +} + +/// Replace `path` with `data` only once the bytes are durable. An existing +/// file keeps its owner and mode; a new one gets `0644` less the umask. The +/// bytes go to `..new` beside it first, and a stale one of those is +/// removed when it is a regular file of this user or the file's owner. +fn atomic_write(path: &Path, data: &[u8]) -> Result<()> { + let parent = dirname(path); + std::fs::create_dir_all(parent).map_err(|error| io_refused("create", parent, &error))?; + let existing = match std::fs::symlink_metadata(path) { + Ok(info) if info.file_type().is_symlink() => { + return Err(refused(format!( + "refusing to replace a symlink: {}", + path.display() + ))) + } + Ok(info) if !info.file_type().is_file() => { + return Err(refused(format!( + "cannot read access metadata for {}: not a regular file", + path.display() + ))) + } + Ok(info) => Some(info), + Err(_) => None, + }; + let mode = match &existing { + Some(info) => info.mode() & 0o7777, + None => { + // umask can only be read by setting it; it is restored at once. + let mask = unsafe { libc::umask(0) }; + unsafe { libc::umask(mask) }; + 0o644 & !u32::from(mask) + } + }; + let name = path.file_name().unwrap_or_default().to_string_lossy(); + let temporary = parent.join(format!(".{name}.new")); + if let Ok(stale) = std::fs::symlink_metadata(&temporary) { + // geteuid has no preconditions. + let euid = unsafe { libc::geteuid() }; + let owned = stale.uid() == euid + || existing + .as_ref() + .is_some_and(|info| info.uid() == stale.uid()); + if !stale.file_type().is_file() || !owned || stale.nlink() != 1 { + return Err(refused(format!( + "temporary file must be an owned regular file with one link: {}", + temporary.display() + ))); + } + std::fs::remove_file(&temporary) + .map_err(|error| io_refused("remove", &temporary, &error))?; + } + let written = (|| -> Result<()> { + let mut file = OpenOptions::new() + .write(true) + .create_new(true) + .mode(0o600) + .custom_flags(libc::O_NOFOLLOW) + .open(&temporary) + .map_err(|error| io_refused("create", &temporary, &error))?; + file.write_all(data) + .map_err(|error| io_refused("write", &temporary, &error))?; + if let Some(info) = &existing { + // The descriptor is open for the duration of the call. + if unsafe { libc::fchown(file.as_raw_fd(), info.uid(), info.gid()) } != 0 { + return Err(refused(format!( + "cannot preserve access metadata for {}: {}", + path.display(), + std::io::Error::last_os_error() + ))); + } + } + file.set_permissions(std::fs::Permissions::from_mode(mode)) + .map_err(|error| io_refused("set the mode of", &temporary, &error))?; + file.sync_all() + .map_err(|error| io_refused("flush", &temporary, &error))?; + drop(file); + if let Some(info) = &existing { + let current = std::fs::symlink_metadata(path) + .map_err(|error| io_refused("recheck", path, &error))?; + if identity(¤t) != identity(info) { + return Err(refused(format!( + "access metadata of {} changed before it was replaced", + path.display() + ))); + } + } + std::fs::rename(&temporary, path).map_err(|error| io_refused("replace", path, &error)) + })(); + if written.is_err() { + let _ = std::fs::remove_file(&temporary); + } + written?; + fsync_dir(parent) +} + +/// What `ledger project` needs. +#[derive(Debug, Clone)] +pub struct ProjectRequest { + /// The JSON Lines log. + pub log: PathBuf, + /// A signed head that covers every record. + pub head: PathBuf, + /// The public key the head must verify under. + pub public_key: PathBuf, + /// The output directory, outside the log's, the head's and the key's. + pub out: PathBuf, +} + +/// Write JSON and Markdown history of every package in a verified log. +/// +/// The same verified log and head always give the same bytes. Package files +/// are replaced one at a time and the index last, so an interrupted run +/// leaves the previous index; files of packages no longer listed are +/// removed. +pub fn project(request: &ProjectRequest) -> Result { + let out = &request.out; + output_dir(out, &request.log, &request.head, &request.public_key)?; + let verified = read_verified(&request.log, &request.head, &request.public_key)?; + let files = render(&build_history(&verified))?; + let packages = out.join("packages"); + std::fs::create_dir_all(&packages).map_err(|error| io_refused("create", &packages, &error))?; + if !std::fs::symlink_metadata(&packages).is_ok_and(|info| info.file_type().is_dir()) { + return Err(refused(format!( + "{} must be a directory", + packages.display() + ))); + } + for (relative, data) in &files { + if relative.starts_with("packages/") { + atomic_write(&out.join(relative), data)?; + } + } + let keep = files + .keys() + .filter_map(|relative| relative.strip_prefix("packages/")) + .collect::>(); + for name in list_names(&packages)? { + if !keep.contains(name.as_str()) && (name.ends_with(".json") || name.ends_with(".md")) { + let path = packages.join(&name); + std::fs::remove_file(&path).map_err(|error| io_refused("remove", &path, &error))?; + } + } + fsync_dir(&packages)?; + for relative in ["index.md", "index.json"] { + atomic_write(&out.join(relative), &files[relative])?; + } + Ok(json!({ + "out": display(out), + "size": verified.head.size, + "root": verified.head.root, + "packages": keep.len() / 2, + "files": files.keys().collect::>(), + })) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn dumps_matches_sorted_ascii_json() { + let value = json!({"b": [1, {"y": "é\n", "x": []}], "a": null, "c": {}}); + assert_eq!( + dumps(&value, None), + r#"{"a": null, "b": [1, {"x": [], "y": "é\n"}], "c": {}}"# + ); + assert_eq!( + dumps(&value, Some(2)), + "{\n \"a\": null,\n \"b\": [\n 1,\n {\n \"x\": [],\n \"y\": \"\\u00e9\\n\"\n }\n ],\n \"c\": {}\n}" + ); + assert_eq!(dumps(&json!("\u{1f600}\u{7f}"), None), r#""😀\u007f""#); + } + + #[test] + fn normpath_follows_posix() { + for (path, expected) in [ + ("/a/b", "/a/b"), + ("/a/b/", "/a/b"), + ("/a/./b", "/a/b"), + ("/a/../b", "/b"), + ("//a", "//a"), + ("///a", "/a"), + ("/", "/"), + ("/..", "/"), + ("a/../..", ".."), + ] { + assert_eq!(normpath(path), expected, "{path}"); + } + } + + #[test] + fn strict_json_refuses_repeated_keys_and_floats() { + assert!(strict_json(r#"{"a":1,"a":1}"#, "x").is_err()); + assert!(strict_json(r#"{"a":1.0}"#, "x").is_err()); + assert!(strict_json(r#"{"a":[1,{"b":null}]}"#, "x").is_ok()); + } + + #[test] + fn quote_keeps_unreserved_characters() { + assert_eq!(quote("evil|pkg", ""), "evil%7Cpkg"); + assert_eq!( + quote("packages/evil%7Cpkg.md", "/"), + "packages/evil%257Cpkg.md" + ); + assert_eq!(quote("café~", ""), "caf%C3%A9~"); + } +} diff --git a/src/lib.rs b/src/lib.rs index 40599fac..52323cda 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -51,6 +51,8 @@ pub mod input_hash; mod install_prefix; pub mod jenkins; pub mod ledger; +#[cfg(unix)] +pub mod ledger_maintenance; pub mod ledger_tiles; pub mod luarocks; mod manifest; From df09d82a73da6049c771241edc6ed73c1f21695b Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Wed, 18 Nov 2026 00:00:26 +0100 Subject: [PATCH 02/11] feat(cli): ledger backfill, anchor, verify-anchors and project Each prints its result as one JSON object with sorted keys. A refusal is exit status 2; an append or signature that did not finish is 75, so the same command can be run again. --- src/main.rs | 178 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 176 insertions(+), 2 deletions(-) diff --git a/src/main.rs b/src/main.rs index 97143478..b1d1bd52 100644 --- a/src/main.rs +++ b/src/main.rs @@ -93,9 +93,9 @@ enum Command { #[command(subcommand)] command: ReproCommand, }, - /// Append to, list, and verify a per-stack software ledger. + /// Append to, list, verify, anchor and project a per-stack software ledger. #[command( - after_long_help = "Examples:\n eb-stack ledger append record.json --log ledger/2026.06.jsonl --key ~/keys/ledger.pem --head-out head.json\n eb-stack ledger show --log ledger/2026.06.jsonl --package PETSc\n eb-stack ledger find --log ledger/2026.06.jsonl --public-key ledger.pub --key pkg=PETSc --key route=kvm\n eb-stack ledger verify --log ledger/2026.06.jsonl --public-key ledger.pub --record 3 --head head.json" + after_long_help = "Examples:\n eb-stack ledger append record.json --log ledger/2026.06.jsonl --key ~/keys/ledger.pem --head-out head.json\n eb-stack ledger show --log ledger/2026.06.jsonl --package PETSc\n eb-stack ledger find --log ledger/2026.06.jsonl --public-key ledger.pub --key pkg=PETSc --key route=kvm\n eb-stack ledger verify --log ledger/2026.06.jsonl --public-key ledger.pub --record 3 --head head.json\n eb-stack ledger anchor --log /srv/ledger/2026.06.jsonl --key /etc/eb-stack/ledger.pem --public-key /etc/eb-stack/ledger.pub --anchors /srv/ledger-anchors" )] Ledger { #[command(subcommand)] @@ -620,6 +620,111 @@ enum LedgerCommand { #[arg(long)] origin: Option, }, + /// Append observed history from a manifest pinned by its SHA-256. + /// + /// Each observation in the manifest becomes one `finding` record at the + /// manifest's `observed_at`, with the manifest id, its SHA-256 and the + /// observation's provenance in `build`. A rerun appends nothing: the + /// ledger acknowledges every record as already recorded. A manifest id + /// backfilled from other bytes, or an event id recorded with other + /// content, is refused before anything is appended. Every path is + /// absolute and free of symbolic links. Prints a JSON summary. Exit + /// status 2 on a refusal, 75 when an append did not finish; run the same + /// command again. + #[command( + after_long_help = "Examples:\n eb-stack ledger backfill --log /srv/ledger/2026.06.jsonl --key /etc/eb-stack/ledger.pem --head /srv/heads/2026.06.json --public-key /etc/eb-stack/ledger.pub --manifest /srv/audit/audit-1.json --manifest-sha256 \"$(sha256sum /srv/audit/audit-1.json | cut -d' ' -f1)\"" + )] + Backfill { + /// The JSON Lines log. Created when absent. + #[arg(long)] + log: PathBuf, + /// Ed25519 PKCS#8 PEM key. Refused inside the log's or the head's directory. + #[arg(long)] + key: PathBuf, + /// File for the signed head after each append. + #[arg(long)] + head: PathBuf, + /// Ed25519 public key the head is signed by: PEM, or 64 hex characters. + #[arg(long)] + public_key: PathBuf, + /// The observed-history manifest (schema `eb-staged-rebuild/observed-backfill/1`). + #[arg(long)] + manifest: PathBuf, + /// SHA-256 of the manifest's bytes, 64 lower-case hex characters. + #[arg(long)] + manifest_sha256: String, + }, + /// Sign today's head and add it to a directory of immutable daily anchors. + /// + /// The head is signed now and published as `/.head.json` + /// (UTC) once `ledger verify` proves it binds to the log and extends the + /// latest anchor. A file is never replaced: a second run on the same day + /// proves the day's anchor still extends into the log and reports it + /// with `"status": "exists"`. An anchor dated after today, a rewritten + /// or truncated log, and anchors signed by different keys are refused. + /// Prints a JSON summary. Exit status 2 on a refusal, 75 when signing + /// did not finish; run the same command again. + #[command( + after_long_help = "Examples:\n eb-stack ledger anchor --log /srv/ledger/2026.06.jsonl --key /etc/eb-stack/ledger.pem --public-key /etc/eb-stack/ledger.pub --anchors /srv/ledger-anchors" + )] + Anchor { + /// The JSON Lines log. + #[arg(long)] + log: PathBuf, + /// Ed25519 PKCS#8 PEM key. Refused inside the log's or the anchors' directory. + #[arg(long)] + key: PathBuf, + /// Ed25519 public key every anchor is signed by: PEM, or 64 hex characters. + #[arg(long)] + public_key: PathBuf, + /// Directory of daily anchors, outside the log's directory. + #[arg(long)] + anchors: PathBuf, + }, + /// Prove the chain of daily anchors against the log. + /// + /// Every anchor must extend the one before it, and the latest must bind + /// to the log. Prints a JSON summary. Exit status 2 when a proof does + /// not check. + #[command( + after_long_help = "Examples:\n eb-stack ledger verify-anchors --log /srv/ledger/2026.06.jsonl --public-key /etc/eb-stack/ledger.pub --anchors /srv/ledger-anchors" + )] + VerifyAnchors { + /// The JSON Lines log. + #[arg(long)] + log: PathBuf, + /// Ed25519 public key every anchor is signed by: PEM, or 64 hex characters. + #[arg(long)] + public_key: PathBuf, + /// Directory of daily anchors. + #[arg(long)] + anchors: PathBuf, + }, + /// Write JSON and Markdown history of every package in a verified log. + /// + /// The head must be signed by `--public-key` and cover every record. The + /// output directory gets `index.json`, `index.md`, and + /// `packages/.json` and `packages/.md` for every package + /// (the part of a module name before the first `/`). The same log and + /// head always give the same bytes. Prints a JSON summary. Exit status 2 + /// on a refusal, including a head that covers fewer records than the log. + #[command( + after_long_help = "Examples:\n eb-stack ledger project --log /srv/ledger/2026.06.jsonl --head /srv/heads/2026.06.json --public-key /etc/eb-stack/ledger.pub --out /srv/www/ledger-history" + )] + Project { + /// The JSON Lines log. + #[arg(long)] + log: PathBuf, + /// A signed head that covers every record. + #[arg(long)] + head: PathBuf, + /// Ed25519 public key the head is signed by: PEM, or 64 hex characters. + #[arg(long)] + public_key: PathBuf, + /// Output directory. Holds nothing but a projection. + #[arg(long)] + out: PathBuf, + }, } #[derive(Subcommand, Debug)] @@ -2228,6 +2333,12 @@ fn main() { // Display, not Debug: Debug appends a stack backtrace, which is a // compiler trace and not the reason the command failed. eprintln!("error: {error:#}"); + // A ledger maintenance command is 2 when refused and 75 when a write + // did not finish and the same command can be run again. + #[cfg(unix)] + if let Some(code) = eb_stack::ledger_maintenance::exit_code(&error) { + std::process::exit(code); + } // 2 is a rejected command line. 1 is work that was attempted and failed. let code = if is_usage(&error) { 2 } else { 1 }; std::process::exit(code); @@ -2442,10 +2553,73 @@ fn run_ledger(command: LedgerCommand) -> Result<()> { })?; print!("{}", report.stdout); } + maintenance => run_ledger_maintenance(maintenance)?, } Ok(()) } +/// `ledger backfill`, `anchor`, `verify-anchors` and `project`: print the +/// JSON summary, or fail with status 2 (refused) or 75 (run it again). +#[cfg(unix)] +fn run_ledger_maintenance(command: LedgerCommand) -> Result<()> { + use eb_stack::ledger_maintenance as maintenance; + let result = match command { + LedgerCommand::Backfill { + log, + key, + head, + public_key, + manifest, + manifest_sha256, + } => maintenance::backfill(&maintenance::BackfillRequest { + log, + key, + head, + public_key, + manifest, + manifest_sha256, + now: maintenance::now_seconds(), + }), + LedgerCommand::Anchor { + log, + key, + public_key, + anchors, + } => maintenance::anchor(&maintenance::AnchorRequest { + log, + key, + public_key, + anchors, + now: maintenance::now_seconds(), + }), + LedgerCommand::VerifyAnchors { + log, + public_key, + anchors, + } => maintenance::verify_anchors(&log, &public_key, &anchors), + LedgerCommand::Project { + log, + head, + public_key, + out, + } => maintenance::project(&maintenance::ProjectRequest { + log, + head, + public_key, + out, + }), + other => unreachable!("{other:?} is not a maintenance command"), + }; + let value = result.map_err(maintenance::as_maintenance_error)?; + println!("{}", maintenance::dumps(&value, None)); + Ok(()) +} + +#[cfg(not(unix))] +fn run_ledger_maintenance(_command: LedgerCommand) -> Result<()> { + anyhow::bail!("ledger backfill, anchor, verify-anchors and project need a Unix system") +} + #[derive(clap::Args, Debug)] struct EasyblockReachArgs { /// Easyblock trees. Earlier roots win a class name. From c26b550ed882dc915027dc53a0d2c6aad89c5dc2 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Wed, 18 Nov 2026 00:00:26 +0100 Subject: [PATCH 03/11] feat(mcp): tools for the ledger maintenance commands eb_ledger_backfill, eb_ledger_anchor, eb_ledger_verify_anchors and eb_ledger_project run the same library calls as the CLI and return its JSON summary with the printed text. The catalog grows to 64 tools. --- .../orgmode/explanation/sbom-blast-radius.org | 8 +- docs/orgmode/reference/mcp.org | 6 +- src/mcp.rs | 90 +++++++++++++++++++ tests/mcp_stdio.rs | 2 +- tests/mcp_v1.rs | 14 ++- 5 files changed, 115 insertions(+), 5 deletions(-) diff --git a/docs/orgmode/explanation/sbom-blast-radius.org b/docs/orgmode/explanation/sbom-blast-radius.org index cb4015f2..558fbe90 100644 --- a/docs/orgmode/explanation/sbom-blast-radius.org +++ b/docs/orgmode/explanation/sbom-blast-radius.org @@ -992,7 +992,7 @@ table. ~reverse=0~ again, for the same reason as the CMakeMake run. * The same document over MCP -The Model Context Protocol (MCP) catalog has 60 tools. ~tools/list~ prints +The Model Context Protocol (MCP) catalog has 64 tools. ~tools/list~ prints their names: #+begin_src bash @@ -1062,9 +1062,13 @@ eb_ledger_tiles eb_ledger_find eb_ledger_show eb_ledger_verify +eb_ledger_backfill +eb_ledger_anchor +eb_ledger_verify_anchors +eb_ledger_project #+end_src -That is 60 tools. +That is 64 tools. ~eb_stack_sbom~ writes the CycloneDX file ~stack sbom~ writes. Its ~tools/list~ description reads: "Emit CycloneDX from an existing stack lock, reading dependency edges and source checksums from the easyconfigs the lock names. With backport_list, also write the modules whose reach class justifies a backport." ~eb_stack_sbom~ reads the Cbc lock: diff --git a/docs/orgmode/reference/mcp.org b/docs/orgmode/reference/mcp.org index 9707eb21..154ca1dc 100644 --- a/docs/orgmode/reference/mcp.org +++ b/docs/orgmode/reference/mcp.org @@ -88,7 +88,7 @@ absolute path there. * Tools -The catalog has 60 tools. ~tools/list~ returns one tool for each CLI +The catalog has 64 tools. ~tools/list~ returns one tool for each CLI command in the table, and the recipe and easyblock tools that have no command. ~mcp~ publishes that catalog and has no tool of its own. Each command's tool calls the same runner as that command. The ~text~ field @@ -142,6 +142,10 @@ name in the schema ~tools/list~ returns. The | ~ledger find~ | ~eb_ledger_find~ | | ~ledger show~ | ~eb_ledger_show~ | | ~ledger verify~ | ~eb_ledger_verify~ | +| ~ledger backfill~ | ~eb_ledger_backfill~ | +| ~ledger anchor~ | ~eb_ledger_anchor~ | +| ~ledger verify-anchors~ | ~eb_ledger_verify_anchors~ | +| ~ledger project~ | ~eb_ledger_project~ | | ~easyblock-reach~ | ~eb_easyblock_reach~ | | ~pr-overlap~ | ~eb_pr_overlap~ | | ~rebuild-set~ | ~eb_rebuild_set~ | diff --git a/src/mcp.rs b/src/mcp.rs index 58c65e8e..70438531 100644 --- a/src/mcp.rs +++ b/src/mcp.rs @@ -819,6 +819,47 @@ fn tool_catalog() -> Vec { ("origin", "string"), ], ), + tool( + "eb_ledger_backfill", + "Append one finding record per observation of an observed-history manifest pinned by its SHA-256, each at most once, and prove each is in the signed head. Every path is absolute. Same as `ledger backfill`.", + &[ + ("log", "string"), + ("key", "string"), + ("head", "string"), + ("public_key", "string"), + ("manifest", "string"), + ("manifest_sha256", "string"), + ], + ), + tool( + "eb_ledger_anchor", + "Sign today's ledger head and publish it once as /.head.json after proving it binds to the log and extends the latest anchor; an existing anchor is never replaced. Same as `ledger anchor`.", + &[ + ("log", "string"), + ("key", "string"), + ("public_key", "string"), + ("anchors", "string"), + ], + ), + tool( + "eb_ledger_verify_anchors", + "Prove that every daily anchor extends the one before it and that the latest binds to the ledger. Same as `ledger verify-anchors`.", + &[ + ("log", "string"), + ("public_key", "string"), + ("anchors", "string"), + ], + ), + tool( + "eb_ledger_project", + "Write index.json, index.md and per-package JSON and Markdown history from a ledger whose signed head covers every record. Same as `ledger project`.", + &[ + ("log", "string"), + ("head", "string"), + ("public_key", "string"), + ("out", "string"), + ], + ), ]; if let Some(lint) = tools .iter_mut() @@ -968,6 +1009,10 @@ fn call_tool(name: &str, arguments: &Value) -> Result { "eb_ledger_find" => ledger_find_tool(arguments), "eb_ledger_show" => ledger_show_tool(arguments), "eb_ledger_verify" => ledger_verify_tool(arguments), + "eb_ledger_backfill" => ledger_maintenance_tool(name, arguments), + "eb_ledger_anchor" => ledger_maintenance_tool(name, arguments), + "eb_ledger_verify_anchors" => ledger_maintenance_tool(name, arguments), + "eb_ledger_project" => ledger_maintenance_tool(name, arguments), _ => Err(format!("unknown tool: {name}")), } } @@ -3932,6 +3977,51 @@ fn ledger_verify_tool(arguments: &Value) -> Result { })) } +/// `ledger backfill`, `anchor`, `verify-anchors` and `project`: the JSON +/// summary the command prints, with its text. +#[cfg(unix)] +fn ledger_maintenance_tool(name: &str, arguments: &Value) -> Result { + use crate::ledger_maintenance as maintenance; + let path = |key: &str| required_path(arguments, key); + let result = match name { + "eb_ledger_backfill" => maintenance::backfill(&maintenance::BackfillRequest { + log: path("log")?, + key: path("key")?, + head: path("head")?, + public_key: path("public_key")?, + manifest: path("manifest")?, + manifest_sha256: required_string(arguments, "manifest_sha256")?, + now: maintenance::now_seconds(), + }), + "eb_ledger_anchor" => maintenance::anchor(&maintenance::AnchorRequest { + log: path("log")?, + key: path("key")?, + public_key: path("public_key")?, + anchors: path("anchors")?, + now: maintenance::now_seconds(), + }), + "eb_ledger_verify_anchors" => { + maintenance::verify_anchors(&path("log")?, &path("public_key")?, &path("anchors")?) + } + "eb_ledger_project" => maintenance::project(&maintenance::ProjectRequest { + log: path("log")?, + head: path("head")?, + public_key: path("public_key")?, + out: path("out")?, + }), + other => return Err(format!("{other} is not a ledger maintenance tool")), + }; + let mut value = result.map_err(workflow_error)?; + let text = maintenance::dumps(&value, None); + value["text"] = Value::from(text); + Ok(value) +} + +#[cfg(not(unix))] +fn ledger_maintenance_tool(name: &str, _arguments: &Value) -> Result { + Err(format!("{name} needs a Unix system")) +} + fn pr_overlap(arguments: &Value) -> Result { let kind = match optional_string(arguments, "kind") .as_deref() diff --git a/tests/mcp_stdio.rs b/tests/mcp_stdio.rs index acf8180d..66c0890a 100644 --- a/tests/mcp_stdio.rs +++ b/tests/mcp_stdio.rs @@ -357,7 +357,7 @@ fn mcp_stdio_catalog_lists_the_overlap_and_reach_tools() { ] { assert!(names.contains(&expected), "missing {expected}: {names:?}"); } - assert_eq!(names.len(), 60, "{names:?}"); + assert_eq!(names.len(), 64, "{names:?}"); } fn software_layer_prs() -> Vec { diff --git a/tests/mcp_v1.rs b/tests/mcp_v1.rs index dbe50920..498c25ba 100644 --- a/tests/mcp_v1.rs +++ b/tests/mcp_v1.rs @@ -178,10 +178,14 @@ fn mcp_catalog_matches_the_version_one_workflows() { "eb_ledger_find", "eb_ledger_show", "eb_ledger_verify", + "eb_ledger_backfill", + "eb_ledger_anchor", + "eb_ledger_verify_anchors", + "eb_ledger_project", ] { assert!(names.contains(&expected), "missing {expected}: {names:?}"); } - assert_eq!(names.len(), 60, "unexpected MCP tools: {names:?}"); + assert_eq!(names.len(), 64, "unexpected MCP tools: {names:?}"); let inspect = response["result"]["tools"] .as_array() @@ -2597,6 +2601,10 @@ fn mcp_schemas_cover_cli_flags() { ("eb_ledger_find", "ledger find"), ("eb_ledger_show", "ledger show"), ("eb_ledger_verify", "ledger verify"), + ("eb_ledger_backfill", "ledger backfill"), + ("eb_ledger_anchor", "ledger anchor"), + ("eb_ledger_verify_anchors", "ledger verify-anchors"), + ("eb_ledger_project", "ledger project"), ("eb_component_reach", "component-reach"), ("eb_target_list", "target list"), ("eb_target_doctor", "target doctor"), @@ -3882,6 +3890,10 @@ fn every_cli_subcommand_has_an_mcp_tool() { ("eb_ledger_find", &["ledger", "find"]), ("eb_ledger_show", &["ledger", "show"]), ("eb_ledger_verify", &["ledger", "verify"]), + ("eb_ledger_backfill", &["ledger", "backfill"]), + ("eb_ledger_anchor", &["ledger", "anchor"]), + ("eb_ledger_verify_anchors", &["ledger", "verify-anchors"]), + ("eb_ledger_project", &["ledger", "project"]), ("eb_pr_overlap", &["pr-overlap"]), ("eb_rebuild_set", &["rebuild-set"]), ("eb_component_reach", &["component-reach"]), From 4929a71c7f908ab6c00a866f6528fe6dcf0892d2 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Wed, 18 Nov 2026 00:00:27 +0100 Subject: [PATCH 04/11] test(ledger): port the ledger maintenance cases Every case of eb-staged-rebuild's ledger maintenance suite runs against real logs, heads and anchors written by the library. Cases that crashed a run at a fault injection point now build the state such a crash leaves (a first append only, a staging directory with an unlinked head, half-written package and index temporaries) and check that a rerun completes. Cases that wrapped the eb-stack binary to corrupt its stdout receipts or to hang it past --timeout have no counterpart: there is no subprocess. The command-line case checks status 75 through an append the ledger refuses. --- tests/ledger_maintenance.rs | 1496 +++++++++++++++++++++++++++++++++++ 1 file changed, 1496 insertions(+) create mode 100644 tests/ledger_maintenance.rs diff --git a/tests/ledger_maintenance.rs b/tests/ledger_maintenance.rs new file mode 100644 index 00000000..cd6f5c44 --- /dev/null +++ b/tests/ledger_maintenance.rs @@ -0,0 +1,1496 @@ +//! `ledger backfill`, `ledger anchor`, `ledger verify-anchors` and +//! `ledger project` against real ledgers written by `ledger append` and +//! `ledger head`, through the library and through the binary. +#![cfg(unix)] + +use eb_stack::ledger::{self, SignedHead, VerifyMode, VerifyRequest}; +use eb_stack::ledger_maintenance::{self as lm, Failure}; +use ed25519_dalek::pkcs8::spki::der::pem::LineEnding; +use ed25519_dalek::pkcs8::{EncodePrivateKey, EncodePublicKey}; +use ed25519_dalek::SigningKey; +use serde_json::{json, Map, Value}; +use std::collections::BTreeMap; +use std::os::unix::fs::{MetadataExt, PermissionsExt}; +use std::path::{Path, PathBuf}; +use std::process::{Command, Output}; + +const DAY1: i64 = 1_793_707_200; // 2026-11-03T12:00:00Z +const DAY2: i64 = DAY1 + 86_400; +const DAY3: i64 = DAY2 + 86_400; +const OBSERVED: &str = "2026-11-02T09:30:00Z"; + +/// Pipes in a Markdown table row that are not backslash-escaped. +fn cell_separators(line: &str) -> usize { + let (mut count, mut escaped) = (0, false); + for ch in line.chars() { + if escaped { + escaped = false; + } else if ch == '\\' { + escaped = true; + } else if ch == '|' { + count += 1; + } + } + count +} + +/// Every file under `root` with its bytes, by relative path. +fn tree(root: &Path) -> BTreeMap> { + fn walk(root: &Path, directory: &Path, found: &mut BTreeMap>) { + for entry in std::fs::read_dir(directory).expect("read_dir") { + let path = entry.expect("entry").path(); + if path.is_dir() { + walk(root, &path, found); + } else { + let relative = path + .strip_prefix(root) + .unwrap() + .to_string_lossy() + .into_owned(); + found.insert(relative, std::fs::read(&path).expect("read")); + } + } + } + let mut found = BTreeMap::new(); + walk(root, root, &mut found); + found +} + +fn write_key(key: &Path, public: &Path, seed: u8) { + let signing = SigningKey::from_bytes(&[seed; 32]); + std::fs::write( + key, + signing + .to_pkcs8_pem(LineEnding::LF) + .expect("pem") + .as_bytes(), + ) + .expect("write key"); + std::fs::write( + public, + signing + .verifying_key() + .to_public_key_pem(LineEnding::LF) + .expect("spki"), + ) + .expect("write public key"); + std::fs::set_permissions(key, std::fs::Permissions::from_mode(0o400)).expect("chmod key"); +} + +fn failure(result: &anyhow::Result) -> Failure { + match result { + Ok(value) => panic!("expected a failure, got {value}"), + Err(error) => { + lm::failure_of(error).unwrap_or_else(|| panic!("not a maintenance error: {error:#}")) + } + } +} + +/// `result` is a refusal whose message contains `text`. +fn assert_refused(result: anyhow::Result, text: &str) { + let kind = failure(&result); + let message = format!("{:#}", result.unwrap_err()); + assert!(kind.is_refusal(), "{kind:?}: {message}"); + assert!( + message.contains(text), + "{message:?} does not contain {text:?}" + ); +} + +struct Fixture { + _temp: tempfile::TempDir, + root: PathBuf, + key: PathBuf, + public: PathBuf, + log: PathBuf, + head: PathBuf, + anchors: PathBuf, + out: PathBuf, + count: usize, +} + +impl Fixture { + fn new() -> Self { + let temp = tempfile::tempdir().expect("tempdir"); + let root = temp.path().canonicalize().expect("resolve tempdir"); + for name in ["keys", "ledger", "heads", "anchors", "work"] { + std::fs::create_dir(root.join(name)).expect("mkdir"); + } + let key = root.join("keys/ledger.pem"); + let public = root.join("keys/ledger.pub"); + write_key(&key, &public, 11); + Self { + log: root.join("ledger/stack.jsonl"), + head: root.join("heads/head.json"), + anchors: root.join("anchors"), + out: root.join("out"), + key, + public, + root, + count: 0, + _temp: temp, + } + } + + fn path(&self, relative: &str) -> PathBuf { + self.root.join(relative) + } + + /// Append one record to `log`, signing `head`; return the line written. + fn append_to( + &mut self, + log: &Path, + head: &Path, + module: &str, + action: &str, + extra: Value, + ) -> Map { + self.count += 1; + let mut record = json!({ + "ts": format!("2026-11-03T10:{:02}:{:02}Z", self.count / 60, self.count % 60), + "actor": "site-admin", + "stack": "2026.06", + "target": "x86_64/generic", + "module": module, + "location": format!("/sw/{module}"), + "action": action, + "build": {"event_id": format!("test/{}", self.count)}, + }); + for (key, value) in extra.as_object().cloned().unwrap_or_default() { + record[key] = value; + } + let path = self.path(&format!("work/record-{}.json", self.count)); + std::fs::write(&path, record.to_string()).expect("write record"); + ledger::append(&ledger::AppendRequest { + log: log.to_path_buf(), + record: path, + expect_head: None, + key: Some(self.key.clone()), + head_out: Some(head.to_path_buf()), + tiles: None, + origin: None, + }) + .expect("ledger append"); + records(log).pop().expect("a record") + } + + fn append(&mut self, module: &str, action: &str, extra: Value) -> Map { + let (log, head) = (self.log.clone(), self.head.clone()); + self.append_to(&log, &head, module, action, extra) + } + + fn records(&self) -> Vec> { + records(&self.log) + } + + fn log_bytes(&self) -> Vec { + std::fs::read(&self.log).expect("read log") + } + + fn sign(&self, key: &Path, out: &Path, ts: Option<&str>) { + ledger::sign_head(&ledger::HeadRequest { + log: self.log.clone(), + key: key.to_path_buf(), + out: out.to_path_buf(), + ts: ts.map(str::to_string), + tiles: None, + origin: None, + }) + .expect("ledger head"); + } + + fn verify_record(&self, index: usize, head: &Path) -> bool { + ledger::verify(&VerifyRequest { + log: self.log.clone(), + public_key: self.public.clone(), + mode: VerifyMode::Inclusion { + record: index, + head: head.to_path_buf(), + }, + tiles: None, + origin: None, + }) + .is_ok() + } + + fn default_observations() -> Value { + json!([ + {"module": "legacy/1.0", "location": "/sw/legacy/1.0", + "modulefile": {"path": "/modules/all/legacy/1.0.lua", "sha256": "ab".repeat(32)}, + "provenance": [{"ref": "/archive/easybuild/legacy-1.0.log", "kind": "easybuild-log", + "sha256": "cd".repeat(32)}]}, + {"module": "old/2", "location": "/sw/old/2", + "provenance": [{"ref": "ticket HPC-1234"}], "note": "found during audit"}, + {"module": "old/3", "location": "/sw/old/3", "provenance": [{"ref": "inventory.csv row 9"}]}, + ]) + } + + /// Write a manifest with `overrides` over the default fields; return its path and SHA-256. + fn write_manifest(&self, name: &str, overrides: Value) -> (PathBuf, String) { + let mut manifest = json!({ + "schema": lm::MANIFEST_SCHEMA, "manifest_id": "site-audit-1", "observed_at": OBSERVED, + "observer": "audit/jdoe", "stack": "2026.06", "target": "x86_64/generic", + "observations": Self::default_observations(), + }); + for (key, value) in overrides.as_object().cloned().unwrap_or_default() { + manifest[key] = value; + } + let path = self.path(&format!("work/{name}")); + let data = serde_json::to_string_pretty(&manifest).unwrap() + "\n"; + std::fs::write(&path, &data).expect("write manifest"); + (path, sha256(data.as_bytes())) + } + + fn backfill_at(&self, manifest: &Path, digest: &str, now: i64) -> anyhow::Result { + lm::backfill(&lm::BackfillRequest { + log: self.log.clone(), + key: self.key.clone(), + head: self.head.clone(), + public_key: self.public.clone(), + manifest: manifest.to_path_buf(), + manifest_sha256: digest.to_string(), + now, + }) + } + + fn backfill(&self, manifest: &Path, digest: &str) -> anyhow::Result { + self.backfill_at(manifest, digest, DAY1) + } + + fn anchor_with(&self, now: i64, key: &Path, anchors: &Path) -> anyhow::Result { + lm::anchor(&lm::AnchorRequest { + log: self.log.clone(), + key: key.to_path_buf(), + public_key: self.public.clone(), + anchors: anchors.to_path_buf(), + now, + }) + } + + fn anchor(&self, now: i64) -> anyhow::Result { + self.anchor_with(now, &self.key, &self.anchors) + } + + fn verify_anchors(&self) -> anyhow::Result { + lm::verify_anchors(&self.log, &self.public, &self.anchors) + } + + fn project_with(&self, out: &Path, head: &Path) -> anyhow::Result { + lm::project(&lm::ProjectRequest { + log: self.log.clone(), + head: head.to_path_buf(), + public_key: self.public.clone(), + out: out.to_path_buf(), + }) + } + + fn project(&self) -> anyhow::Result { + self.project_with(&self.out, &self.head) + } + + fn anchor_files(&self) -> Vec { + let mut names = std::fs::read_dir(&self.anchors) + .unwrap() + .map(|entry| entry.unwrap().file_name().to_string_lossy().into_owned()) + .filter(|name| name.ends_with(".head.json")) + .collect::>(); + names.sort(); + names + } + + fn staging(&self) -> Vec { + std::fs::read_dir(&self.anchors) + .unwrap() + .map(|entry| entry.unwrap().file_name().to_string_lossy().into_owned()) + .filter(|name| name.starts_with(".anchor-staging-")) + .collect() + } +} + +fn records(log: &Path) -> Vec> { + std::fs::read_to_string(log) + .expect("read log") + .lines() + .map(|line| { + serde_json::from_str::(line) + .unwrap() + .as_object() + .unwrap() + .clone() + }) + .collect() +} + +fn sha256(data: &[u8]) -> String { + use sha2::Digest; + sha2::Sha256::digest(data) + .iter() + .map(|byte| format!("{byte:02x}")) + .collect() +} + +fn s(path: &Path) -> &str { + path.to_str().expect("utf8 path") +} + +// Backfill + +#[test] +fn observations_become_findings_at_the_observation_time() { + let fixture = Fixture::new(); + let (manifest, digest) = fixture.write_manifest("manifest.json", json!({})); + let result = fixture.backfill(&manifest, &digest).expect("backfill"); + assert_eq!( + (result["appended"].as_u64(), result["replayed"].as_u64()), + (Some(3), Some(0)) + ); + assert!(result["receipts"] + .as_array() + .unwrap() + .iter() + .all(|receipt| receipt["verified"] == true)); + let records = fixture.records(); + let modules = records + .iter() + .map(|record| record["module"].as_str().unwrap()) + .collect::>(); + assert_eq!(modules, ["legacy/1.0", "old/2", "old/3"]); + for record in &records { + assert_eq!(record["action"], "finding"); + assert_eq!(record["ts"], OBSERVED); + assert!(!record.contains_key("stage")); + assert_eq!(record["build"]["kind"], lm::BACKFILL_KIND); + assert_eq!(record["build"]["manifest_sha256"], digest.as_str()); + assert_eq!(record["build"]["observed_at"], OBSERVED); + assert!(record["reason"] + .as_str() + .unwrap() + .contains("no history before the observation")); + } + assert_eq!( + records[0]["build"]["provenance"], + json!([{"ref": "/archive/easybuild/legacy-1.0.log", "kind": "easybuild-log", "sha256": "cd".repeat(32)}]) + ); + assert_eq!( + records[0]["modulefile"], + json!({"path": "/modules/all/legacy/1.0.lua", "sha256": "ab".repeat(32)}) + ); + assert_eq!(records[1]["build"]["note"], "found during audit"); + for index in 0..3 { + assert!(fixture.verify_record(index, &fixture.head)); + } +} + +#[test] +fn repeated_retries_append_nothing() { + let fixture = Fixture::new(); + let (manifest, digest) = fixture.write_manifest("manifest.json", json!({})); + let first = fixture.backfill(&manifest, &digest).expect("backfill"); + let before = fixture.log_bytes(); + let ids = |result: &Value| { + result["receipts"] + .as_array() + .unwrap() + .iter() + .map(|receipt| receipt["id"].clone()) + .collect::>() + }; + for now in [DAY1 + 1, DAY2, DAY3] { + let again = fixture.backfill_at(&manifest, &digest, now).expect("retry"); + assert_eq!( + (again["appended"].as_u64(), again["replayed"].as_u64()), + (Some(0), Some(3)) + ); + assert_eq!(ids(&again), ids(&first)); + assert_eq!(fixture.log_bytes(), before); + } +} + +#[test] +fn an_interrupted_backfill_resumes_without_duplicates() { + let mut fixture = Fixture::new(); + let (manifest, digest) = fixture.write_manifest("manifest.json", json!({})); + // The state a backfill leaves when it stops after its first append. + let (loaded, loaded_digest) = lm::load_manifest(&manifest, &digest, DAY1).expect("manifest"); + let first = lm::backfill_records(&loaded, &loaded_digest).remove(0); + let path = fixture.path("work/first.json"); + std::fs::write(&path, first.to_string()).unwrap(); + ledger::append(&ledger::AppendRequest { + log: fixture.log.clone(), + record: path, + expect_head: None, + key: Some(fixture.key.clone()), + head_out: Some(fixture.head.clone()), + tiles: None, + origin: None, + }) + .expect("first append"); + fixture.count += 1; + assert_eq!(fixture.records().len(), 1); + let result = fixture.backfill(&manifest, &digest).expect("resume"); + assert_eq!( + (result["appended"].as_u64(), result["replayed"].as_u64()), + (Some(2), Some(1)) + ); + let records = fixture.records(); + assert_eq!(records.len(), 3); + let events = records + .iter() + .map(|record| record["build"]["event_id"].as_str().unwrap().to_string()) + .collect::>(); + assert_eq!(events.len(), 3); +} + +#[test] +fn a_torn_tail_is_quarantined_before_the_backfill() { + let mut fixture = Fixture::new(); + fixture.append("demo/1", "install", json!({})); + let mut log = std::fs::OpenOptions::new() + .append(true) + .open(&fixture.log) + .unwrap(); + std::io::Write::write_all(&mut log, br#"{"action":"inst"#).unwrap(); + drop(log); + let (manifest, digest) = fixture.write_manifest("manifest.json", json!({})); + fixture.backfill(&manifest, &digest).expect("backfill"); + assert_eq!(fixture.records().len(), 4); + let quarantined = std::fs::read_dir(fixture.path("ledger")) + .unwrap() + .filter(|entry| { + entry + .as_ref() + .unwrap() + .file_name() + .to_string_lossy() + .contains(".quarantine.") + }) + .count(); + assert_eq!(quarantined, 1); + assert!(fixture.verify_record(3, &fixture.head)); +} + +#[test] +fn changed_manifest_content_is_refused_before_anything_is_appended() { + let fixture = Fixture::new(); + let (manifest, digest) = fixture.write_manifest("manifest.json", json!({})); + fixture.backfill(&manifest, &digest).expect("backfill"); + let before = fixture.log_bytes(); + let (changed, changed_digest) = fixture.write_manifest( + "changed.json", + json!({"observations": [ + {"module": "legacy/1.0", "location": "/sw/legacy/1.0", "provenance": [{"ref": "a different source"}]}, + {"module": "new/9", "location": "/sw/new/9", "provenance": [{"ref": "x"}]}, + ]}), + ); + assert_refused(fixture.backfill(&changed, &changed_digest), "immutable"); + assert_eq!(fixture.log_bytes(), before); + assert_refused(fixture.backfill(&changed, &digest), "not the pinned"); + assert_eq!(fixture.log_bytes(), before); +} + +#[test] +fn an_event_recorded_with_other_content_is_refused_before_anything_is_appended() { + let mut fixture = Fixture::new(); + let (manifest, digest) = fixture.write_manifest("manifest.json", json!({})); + let (loaded, loaded_digest) = lm::load_manifest(&manifest, &digest, DAY1).expect("manifest"); + let record = lm::backfill_records(&loaded, &loaded_digest).remove(2); + fixture.append( + "old/3", + "finding", + json!({"ts": OBSERVED, "build": {"event_id": record["build"]["event_id"]}}), + ); + let before = fixture.log_bytes(); + assert_refused(fixture.backfill(&manifest, &digest), "other content"); + assert_eq!(fixture.log_bytes(), before); +} + +#[test] +fn unpinned_or_guessed_input_is_refused() { + let fixture = Fixture::new(); + let (manifest, _digest) = fixture.write_manifest("manifest.json", json!({})); + assert_refused( + fixture.backfill(&manifest, &"0".repeat(64)), + "not the pinned", + ); + let one = |item: Value| json!({"observations": [item]}); + let cases = [ + ( + json!({"observed_at": "2027-01-01T00:00:00Z"}), + "after the current time", + ), + (json!({"observed_at": "2026-11-02"}), "observed_at"), + ( + json!({"observed_at": "2026-11-02T09:30:00+01:00"}), + "observed_at", + ), + ( + one( + json!({"module": "a/1", "location": "/sw/a/1", "installed_at": "2019-01-01T00:00:00Z", + "provenance": [{"ref": "r"}]}), + ), + "unknown fields installed_at", + ), + ( + one( + json!({"module": "a/1", "location": "/sw/a/1", "action": "install", "provenance": [{"ref": "r"}]}), + ), + "unknown fields action", + ), + ( + one(json!({"module": "a/1", "location": "/sw/a/1", "provenance": []})), + "original reference", + ), + ( + one(json!({"module": "a/1", "location": "sw/a/1", "provenance": [{"ref": "r"}]})), + "absolute", + ), + ( + one( + json!({"module": "a/1", "location": "/sw/a/1", "provenance": [{"ref": "r", "date": "x"}]}), + ), + "unknown fields date", + ), + ( + json!({"observations": [ + {"module": "a/1", "location": "/sw/a/1", "provenance": [{"ref": "r"}]}, + {"module": "a/1", "location": "/sw/a/1", "provenance": [{"ref": "r"}]}, + ]}), + "repeats", + ), + (json!({"stage": "finished"}), "unknown fields stage"), + (json!({"schema": "other"}), "schema"), + ]; + for (overrides, message) in cases { + let (path, digest) = fixture.write_manifest("case.json", overrides); + assert_refused(fixture.backfill(&path, &digest), message); + } + assert!(!fixture.log.exists()); +} + +#[test] +fn path_aliases_and_a_key_beside_the_log_are_refused() { + let fixture = Fixture::new(); + let (manifest, digest) = fixture.write_manifest("manifest.json", json!({})); + let request = |log: PathBuf, key: PathBuf, head: PathBuf| lm::BackfillRequest { + log, + key, + head, + public_key: fixture.public.clone(), + manifest: manifest.clone(), + manifest_sha256: digest.clone(), + now: DAY1, + }; + std::os::unix::fs::symlink(fixture.path("ledger"), fixture.path("alias")).unwrap(); + assert_refused( + lm::backfill(&request( + fixture.path("alias/stack.jsonl"), + fixture.key.clone(), + fixture.head.clone(), + )), + "aliases are refused", + ); + assert_refused( + lm::backfill(&request( + PathBuf::from(format!("{}/ledger/../ledger/stack.jsonl", s(&fixture.root))), + fixture.key.clone(), + fixture.head.clone(), + )), + "normalised", + ); + let beside = fixture.path("ledger/key.pem"); + std::fs::copy(&fixture.key, &beside).unwrap(); + assert_refused( + lm::backfill(&request(fixture.log.clone(), beside, fixture.head.clone())), + "inside the ledger directory", + ); + assert_refused( + lm::backfill(&request( + fixture.log.clone(), + fixture.key.clone(), + fixture.key.clone(), + )), + "same file", + ); + assert!(!fixture.log.exists()); +} + +// Anchors + +#[test] +fn the_first_anchor_is_read_only_single_link_and_verifies() { + let mut fixture = Fixture::new(); + fixture.append("demo/1", "install", json!({})); + let result = fixture.anchor(DAY1).expect("anchor"); + assert_eq!(result["status"], "published"); + assert_eq!(fixture.anchor_files(), ["2026-11-03.head.json"]); + let path = PathBuf::from(result["path"].as_str().unwrap()); + let info = std::fs::symlink_metadata(&path).unwrap(); + assert_eq!((info.mode() & 0o7777, info.nlink()), (0o444, 1)); + let head = lm::parse_head(&std::fs::read(&path).unwrap(), "anchor").expect("head"); + assert_eq!((head.size, head.ts.as_str()), (1, "2026-11-03T12:00:00Z")); + assert!(fixture.verify_record(0, &path)); + assert_eq!(fixture.verify_anchors().expect("verify")["anchors"], 1); + assert!(fixture.staging().is_empty()); +} + +#[test] +fn an_empty_log_can_be_anchored() { + let mut fixture = Fixture::new(); + std::fs::write(&fixture.log, "").unwrap(); + assert_eq!(fixture.anchor(DAY1).expect("empty anchor")["size"], 0); + fixture.append("demo/1", "install", json!({})); + assert_eq!(fixture.anchor(DAY2).expect("second anchor")["size"], 1); + assert_eq!(fixture.verify_anchors().expect("verify")["anchors"], 2); +} + +#[test] +fn a_same_day_retry_never_replaces_the_anchor() { + let mut fixture = Fixture::new(); + fixture.append("demo/1", "install", json!({})); + let first = fixture.anchor(DAY1).expect("anchor"); + let path = PathBuf::from(first["path"].as_str().unwrap()); + let inode = std::fs::symlink_metadata(&path).unwrap().ino(); + let before = std::fs::read(&path).unwrap(); + fixture.append("demo/2", "install", json!({})); + for _ in 0..2 { + let again = fixture.anchor(DAY1 + 3600).expect("retry"); + assert_eq!( + (&again["status"], &again["size"], &again["root"]), + (&json!("exists"), &json!(1), &first["root"]) + ); + } + assert_eq!(std::fs::read(&path).unwrap(), before); + assert_eq!(std::fs::symlink_metadata(&path).unwrap().ino(), inode); + assert_eq!(fixture.anchor_files(), ["2026-11-03.head.json"]); +} + +#[test] +fn daily_anchors_form_a_verified_chain() { + let mut fixture = Fixture::new(); + fixture.append("demo/1", "install", json!({})); + fixture.anchor(DAY1).expect("first"); + fixture.append("demo/2", "install", json!({})); + fixture.append("demo/3", "install", json!({})); + let second = fixture.anchor(DAY2).expect("second"); + assert_eq!( + (&second["status"], &second["size"]), + (&json!("published"), &json!(3)) + ); + let third = fixture.anchor(DAY3).expect("third"); + assert_eq!( + (&third["status"], &third["size"]), + (&json!("published"), &json!(3)) + ); + ledger::verify(&VerifyRequest { + log: fixture.log.clone(), + public_key: fixture.public.clone(), + mode: VerifyMode::Consistency { + from: fixture.anchors.join("2026-11-03.head.json"), + to: PathBuf::from(second["path"].as_str().unwrap()), + }, + tiles: None, + origin: None, + }) + .expect("consistency between anchors"); + let result = fixture.verify_anchors().expect("verify"); + assert_eq!( + (&result["anchors"], &result["size"]), + (&json!(3), &json!(3)) + ); +} + +#[test] +fn a_rewritten_log_is_refused_and_no_anchor_is_added() { + let mut fixture = Fixture::new(); + fixture.append("demo/1", "install", json!({})); + fixture.append("demo/2", "install", json!({})); + fixture.anchor(DAY1).expect("anchor"); + let other = fixture.path("work/rewritten.jsonl"); + let other_head = fixture.path("work/other-head.json"); + fixture.append_to( + &other, + &other_head, + "demo/1", + "install", + json!({"location": "/sw/evil"}), + ); + for number in 0..3 { + fixture.append_to( + &other, + &other_head, + &format!("demo/{}", number + 2), + "install", + json!({}), + ); + } + std::fs::write(&fixture.log, std::fs::read(&other).unwrap()).unwrap(); + assert_eq!(failure(&fixture.anchor(DAY2)), Failure::Equivocation); + assert_eq!(fixture.anchor_files(), ["2026-11-03.head.json"]); + assert_eq!(failure(&fixture.anchor(DAY1 + 60)), Failure::Equivocation); + assert!(failure(&fixture.verify_anchors()).is_refusal()); +} + +#[test] +fn a_truncated_log_is_refused() { + let mut fixture = Fixture::new(); + for number in 0..3 { + fixture.append(&format!("demo/{number}"), "install", json!({})); + } + fixture.anchor(DAY1).expect("anchor"); + let data = fixture.log_bytes(); + let first = data.iter().position(|byte| *byte == b'\n').unwrap(); + std::fs::write(&fixture.log, &data[..=first]).unwrap(); + assert_eq!(failure(&fixture.anchor(DAY2)), Failure::Equivocation); + assert_eq!(fixture.anchor_files(), ["2026-11-03.head.json"]); +} + +#[test] +fn a_tampered_or_malformed_anchor_is_refused_and_kept() { + let mut fixture = Fixture::new(); + fixture.append("demo/1", "install", json!({})); + let published = PathBuf::from( + fixture.anchor(DAY1).expect("anchor")["path"] + .as_str() + .unwrap(), + ); + fixture.append("demo/2", "install", json!({})); + let good = std::fs::read(&published).unwrap(); + let head: SignedHead = serde_json::from_slice(&good).unwrap(); + let flipped = if head.signature.starts_with('0') { + "1" + } else { + "0" + }; + let tampered = [ + SignedHead { + signature: format!("{flipped}{}", &head.signature[1..]), + ..head.clone() + }, + SignedHead { + root: "0".repeat(64), + ..head.clone() + }, + ]; + for case in tampered { + std::fs::set_permissions(&published, std::fs::Permissions::from_mode(0o644)).unwrap(); + std::fs::write(&published, serde_json::to_string(&case).unwrap() + "\n").unwrap(); + assert!(failure(&fixture.anchor(DAY2)).is_refusal()); + assert_eq!(fixture.anchor_files(), ["2026-11-03.head.json"]); + } + let mut extra = good[..good.len() - 2].to_vec(); + extra.extend_from_slice(b",\"x\":1}\n"); + for data in [good[..40].to_vec(), extra] { + std::fs::write(&published, &data).unwrap(); + assert!(failure(&fixture.anchor(DAY2)).is_refusal()); + assert_eq!(std::fs::read(&published).unwrap(), data); + assert_eq!(fixture.anchor_files(), ["2026-11-03.head.json"]); + } +} + +#[test] +fn an_anchor_from_a_later_day_or_another_key_is_refused() { + let mut fixture = Fixture::new(); + fixture.append("demo/1", "install", json!({})); + fixture.anchor(DAY2).expect("anchor"); + assert_refused(fixture.anchor(DAY1), "after 2026-11-03"); + let (other_key, other_public) = ( + fixture.path("keys/other.pem"), + fixture.path("keys/other.pub"), + ); + write_key(&other_key, &other_public, 23); + assert!(failure(&fixture.anchor_with(DAY3, &other_key, &fixture.anchors)).is_refusal()); + assert_eq!(fixture.anchor_files(), ["2026-11-04.head.json"]); +} + +#[test] +fn a_run_killed_before_publication_leaves_no_partial_anchor() { + let mut fixture = Fixture::new(); + fixture.append("demo/1", "install", json!({})); + // A run killed after it signed: its staging directory holds a signed + // head and a copy of the log that were never linked into place. + let leftover = fixture.anchors.join(".anchor-staging-killed"); + std::fs::create_dir(&leftover).unwrap(); + fixture.sign( + &fixture.key, + &leftover.join("head.json"), + Some("2026-11-03T12:00:00Z"), + ); + std::fs::write(leftover.join("ledger.jsonl"), b"{\"partial").unwrap(); + assert!(fixture.anchor_files().is_empty()); + assert_eq!(fixture.verify_anchors().expect("verify")["anchors"], 0); + assert_eq!(fixture.anchor(DAY1).expect("anchor")["status"], "published"); + assert!(fixture.staging().is_empty()); + assert_eq!(fixture.anchor_files(), ["2026-11-03.head.json"]); + assert_eq!(fixture.anchor(DAY1).expect("rerun")["status"], "exists"); + assert_eq!(fixture.verify_anchors().expect("verify")["anchors"], 1); +} + +#[test] +fn a_crash_between_link_and_cleanup_is_recovered() { + let mut fixture = Fixture::new(); + fixture.append("demo/1", "install", json!({})); + let published = PathBuf::from( + fixture.anchor(DAY1).expect("anchor")["path"] + .as_str() + .unwrap(), + ); + let leftover = fixture.anchors.join(".anchor-staging-crashed"); + std::fs::create_dir(&leftover).unwrap(); + std::fs::hard_link(&published, leftover.join("head.json")).unwrap(); + std::fs::write(leftover.join("ledger.jsonl"), b"{\"partial").unwrap(); + assert_refused(fixture.verify_anchors(), "one link"); + assert_eq!(fixture.anchor(DAY1).expect("rerun")["status"], "exists"); + assert!(!leftover.exists()); + assert_eq!(std::fs::symlink_metadata(&published).unwrap().nlink(), 1); +} + +#[test] +fn an_anchor_with_another_name_is_refused() { + let mut fixture = Fixture::new(); + fixture.append("demo/1", "install", json!({})); + let published = PathBuf::from( + fixture.anchor(DAY1).expect("anchor")["path"] + .as_str() + .unwrap(), + ); + let copy = fixture.path("work/copy.json"); + std::fs::hard_link(&published, ©).unwrap(); + assert_refused(fixture.anchor(DAY2), "one link"); + std::fs::remove_file(©).unwrap(); + std::fs::rename(&published, fixture.anchors.join("2026-11-02.head.json")).unwrap(); + assert_refused(fixture.anchor(DAY2), "not on 2026-11-02"); +} + +#[test] +fn anchor_paths_are_checked() { + let mut fixture = Fixture::new(); + fixture.append("demo/1", "install", json!({})); + assert_refused( + fixture.anchor_with(DAY1, &fixture.key, &fixture.path("ledger")), + "must not hold the ledger", + ); + let inside = fixture.anchors.join("key.pem"); + std::fs::copy(&fixture.key, &inside).unwrap(); + assert_refused( + fixture.anchor_with(DAY1, &inside, &fixture.anchors), + "inside the anchor directory", + ); + std::fs::remove_file(&inside).unwrap(); + std::os::unix::fs::symlink(&fixture.anchors, fixture.path("anchors-alias")).unwrap(); + assert_refused( + fixture.anchor_with(DAY1, &fixture.key, &fixture.path("anchors-alias")), + "aliases are refused", + ); + std::fs::hard_link(&fixture.log, fixture.path("work/log-alias")).unwrap(); + assert_refused(fixture.anchor(DAY1), "hard links"); + assert!(fixture.anchor_files().is_empty()); +} + +// Package history + +/// A log with every kind of event the projection interprets; returns the +/// finished rollback record. +fn history(fixture: &mut Fixture) -> Map { + fixture.append("demo/1", "install", json!({"stage": "started"})); + fixture.append("demo/1", "install", json!({"stage": "finished"})); + fixture.append( + "demo/1", + "rebuild-inplace", + json!({"stage": "started", "location": "/sw/demo/1-gen2"}), + ); + let rebuilt = fixture.append( + "demo/1", + "rebuild-inplace", + json!({"stage": "finished", "location": "/sw/demo/1-gen2"}), + ); + fixture.append( + "demo/1", + "correction", + json!({"stage": "started", "corrects": rebuilt["id"], "reason": "rolled back"}), + ); + let rollback = fixture.append( + "demo/1", + "correction", + json!({"stage": "finished", "corrects": rebuilt["id"], "reason": "rolled back"}), + ); + fixture.append( + "demo/1", + "access", + json!({"reason": {"group": "hpc", "change": "granted"}}), + ); + fixture.append("tool/2", "install", json!({})); + let retired = fixture.append("tool/2", "retire", json!({"reason": "published on CVMFS"})); + fixture.append( + "tool/2", + "correction", + json!({"stage": "aborted", "corrects": retired["id"]}), + ); + fixture.append( + "zlib/1.3", + "finding", + json!({"reason": "CVE-2026-0001 reported"}), + ); + let (manifest, digest) = fixture.write_manifest("manifest.json", json!({})); + fixture.backfill(&manifest, &digest).expect("backfill"); + rollback +} + +fn package(out: &Path, name: &str) -> Value { + serde_json::from_slice(&std::fs::read(out.join(format!("packages/{name}.json"))).unwrap()) + .unwrap() +} + +fn events(document: &Value) -> BTreeMap { + document["events"] + .as_array() + .unwrap() + .iter() + .map(|event| (event["index"].as_u64().unwrap(), event.clone())) + .collect() +} + +#[test] +fn history_keeps_correction_retire_access_and_finding_semantics() { + let mut fixture = Fixture::new(); + let rollback = history(&mut fixture); + let result = fixture.project().expect("project"); + assert_eq!( + (&result["size"], &result["packages"]), + (&json!(14), &json!(5)) + ); + let demo = package(&fixture.out, "demo"); + let by_index = events(&demo); + assert_eq!(by_index[&3]["status"], "corrected"); + assert_eq!(by_index[&3]["corrected_by"], json!([5])); + assert_eq!(by_index[&3]["correction_pending_by"], json!([4])); + assert_eq!( + by_index[&5]["links"]["corrects"], + json!({"id": by_index[&3]["id"], "index": 3}) + ); + assert_eq!( + demo["modules"], + json!([{"module": "demo/1", "state": "installed", "location": "/sw/demo/1", + "last_change": 1, "access": [6], "findings": []}]) + ); + assert_eq!( + by_index[&6]["reason"], + json!({"change": "granted", "group": "hpc"}) + ); + let tool = package(&fixture.out, "tool"); + assert_eq!(tool["modules"][0]["state"], "retired"); + assert_eq!(tool["events"][1]["status"], "effective"); + assert_eq!(tool["events"][1]["corrected_by"], json!([])); + let zlib = package(&fixture.out, "zlib"); + assert_eq!( + ( + &zlib["modules"][0]["state"], + &zlib["modules"][0]["findings"] + ), + (&json!("observed"), &json!([10])) + ); + let legacy = package(&fixture.out, "legacy"); + assert_eq!(legacy["modules"][0]["state"], "observed"); + assert_eq!(legacy["events"][0]["observed"], true); + assert_eq!( + legacy["events"][0]["provenance"][0]["ref"], + "/archive/easybuild/legacy-1.0.log" + ); + assert_eq!(legacy["events"][0]["ts"], OBSERVED); + let markdown = std::fs::read_to_string(fixture.out.join("packages/demo.md")).unwrap(); + assert!(markdown.contains("corrected by \\#5"), "{markdown}"); + assert!( + markdown.contains("correction started by \\#4"), + "{markdown}" + ); + let index: Value = + serde_json::from_slice(&std::fs::read(fixture.out.join("index.json")).unwrap()).unwrap(); + let names = index["packages"] + .as_array() + .unwrap() + .iter() + .map(|entry| entry["name"].as_str().unwrap()) + .collect::>(); + assert_eq!(names, ["demo", "legacy", "old", "tool", "zlib"]); + assert_eq!(index["head"]["size"], 14); + + fixture.append( + "demo/1", + "correction", + json!({"corrects": rollback["id"], "reason": "the rollback was itself wrong"}), + ); + fixture.project().expect("project again"); + let demo = package(&fixture.out, "demo"); + let by_index = events(&demo); + assert_eq!( + (&by_index[&5]["status"], &by_index[&3]["status"]), + (&json!("corrected"), &json!("effective")) + ); + assert_eq!(demo["modules"][0]["state"], "installed"); + assert_eq!( + ( + &demo["modules"][0]["last_change"], + &demo["modules"][0]["location"] + ), + (&json!(3), &json!("/sw/demo/1-gen2")) + ); +} + +#[test] +fn projection_is_deterministic() { + let mut fixture = Fixture::new(); + history(&mut fixture); + let (one, two) = (fixture.path("one"), fixture.path("two")); + fixture.project_with(&one, &fixture.head).expect("one"); + fixture.project_with(&two, &fixture.head).expect("two"); + fixture + .project_with(&one, &fixture.head) + .expect("one again"); + let (first, second) = (tree(&one), tree(&two)); + assert_eq!(first, second); + assert_eq!( + first.keys().map(String::as_str).collect::>(), + [ + "index.json", + "index.md", + "packages/demo.json", + "packages/demo.md", + "packages/legacy.json", + "packages/legacy.md", + "packages/old.json", + "packages/old.md", + "packages/tool.json", + "packages/tool.md", + "packages/zlib.json", + "packages/zlib.md", + ] + ); +} + +#[test] +fn untrusted_text_is_escaped() { + let mut fixture = Fixture::new(); + let hostile = "evil|pkg