@sanning/proof 0.5.0 → 0.7.0

package/src/cli.ts

@@ -14,12 +14,15 @@
 // `payloadHashOk === null` (a withheld record) is semantics-undetermined and
 // surfaces as a per-event note — it does NOT fail the run.
 
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { realpathSync } from "node:fs";
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
 import type { AgentProofResult } from "./agent-proof.js";
+import { CHAIN_READING_SCOPE, readChains, renderChainFinding } from "./chain.js";
+import type { ChainReading } from "./chain.js";
 import { composeExport } from "./compose.js";
 import type { ComposeExportOptions } from "./compose.js";
 import { utf8 } from "./crypto.js";
@@ -84,7 +87,7 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
     return EXIT_MALFORMED;
   }
 
-  // Pull the optional `--logs <file>` flag out of the args; the rest are
+  // Pull the optional `--logs <path>` flag out of the args; the rest are
   // positional (<bundle> [gateways]). --logs feeds disclosed raw-log bytes for
   // content verification (the evidence-bundle path only).
   let logsPath: string | undefined;
@@ -94,7 +97,7 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
     if (a === "--logs") {
       const next = rest[i + 1];
       if (next === undefined) {
-        io.err("verify: --logs requires a file path");
+        io.err("verify: --logs requires a path (a logs directory, or a JSON map file)");
         printUsage(io);
         return EXIT_MALFORMED;
       }
@@ -116,31 +119,13 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
     .map((g) => g.trim())
     .filter((g) => g.length > 0);
 
-  let content: Record<string, Uint8Array | string> | undefined;
+  let logs: LoadedLogs | undefined;
   if (logsPath !== undefined) {
-    let logsRaw: string;
-    try {
-      logsRaw = await readFile(logsPath, "utf8");
-    } catch (e) {
-      io.err(`cannot read --logs ${logsPath}: ${e instanceof Error ? e.message : String(e)}`);
-      return EXIT_MALFORMED;
-    }
-    let logsParsed: unknown;
-    try {
-      logsParsed = JSON.parse(logsRaw);
-    } catch (e) {
-      io.err(`--logs ${logsPath} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
-      return EXIT_MALFORMED;
-    }
-    if (logsParsed === null || typeof logsParsed !== "object" || Array.isArray(logsParsed)) {
-      io.err(`--logs ${logsPath} must be a JSON object mapping event_id → disclosed bytes`);
-      return EXIT_MALFORMED;
-    }
-    content = {};
-    for (const [k, v] of Object.entries(logsParsed as Record<string, unknown>)) {
-      if (typeof v === "string") content[k] = decodeLogValue(v);
-    }
+    logs = await loadLogs(logsPath, io);
+    if (logs === undefined) return EXIT_MALFORMED;
+    for (const n of logs.notes) io.err(`note: ${n}`);
   }
+  const content = logs?.content;
 
   let raw: string;
   try {
@@ -184,7 +169,16 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
     ...(content ? { content } : {}),
     ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
   });
-  return reportEvidence(result, bundlePath, gateways, io);
+  // Read the chains from the SAME parsed bundle the verifier saw. Findings are
+  // evidence about the records in front of us, not a verdict: they are printed
+  // and they never move `exit`, because a chain is not a completeness proof and
+  // an exit code is exactly the kind of thing people read as one.
+  const chains = await readChains(parsed);
+  const exit = reportEvidence(result, bundlePath, gateways, io, chains);
+  // Coverage is reported only once the bundle parsed far enough to have events
+  // to compare against; over a MALFORMED bundle there is nothing to say.
+  if (logs && result.status !== "malformed") reportLogsCoverage(logs, result, io);
+  return exit;
 }
 
 // `proof bundle <source-bundle.json> --attestations <f> --key <f> [-o <out>]`
@@ -390,10 +384,252 @@ async function readExporterKey(path: string, io: Cli): Promise<string | undefine
   return seed.toLowerCase();
 }
 
-// The --logs side-input lane decides each disclosed value's encoding: a clean,
+// ─── the `--logs` side input ────────────────────────────────────────────────
+//
+// Two shapes, one flag (proof#27):
+//
+//   DIRECTORY  `logs/<event_id>.json`, each file's RAW BYTES being the
+//              disclosure. This is the layout `materializeBundle` writes
+//              (bundle.json + logs/) and the layout the verify page hashes,
+//              so a pack verifies with NO side-input construction step.
+//   JSON MAP   `{ event_id: <even-length lowercase hex | utf8 text> }`, the
+//              original form. Unchanged.
+//
+// **Why the directory form exists at all.** Handing a pack to the CLI used to
+// require the caller to read `logs/` and hex-encode it into a map, and that
+// read-and-encode step has been got wrong twice in shipped code: claims-demo#9
+// wrote the hex TEXT into the log files (SHA-256 of hex text is not SHA-256 of
+// the bytes it encodes, so genuine evidence failed), and a runbook handed the
+// directory straight to `--logs` and got EISDIR, exit 2. The directory form
+// removes the encoding decision from the caller entirely — bytes in, bytes
+// hashed — so that whole class stops being reachable from this direction.
+//
+// **Nothing is re-encoded, re-parsed or re-serialised on the way in.** A log
+// file's bytes are passed to the verifier as a `Uint8Array`, which the verifier
+// uses as-is; only the map form's *strings* go through `decodeLogValue`. That
+// is the invariant this feature exists to hold, and it is what makes the CLI
+// and the verify page agree about one pack.
+interface LoadedLogs {
+  // Keyed by event id. A `Uint8Array` is raw bytes (directory form); a `string`
+  // is lowercase hex (map form). Those are exactly the two the verifier
+  // distinguishes.
+  //
+  // A `Map`, NOT a plain object, and that is load-bearing rather than stylistic.
+  // An event id is producer-chosen — here it arrives as a FILE NAME or a JSON
+  // key — and `content["__proto__"] = <bytes>` on an object literal does not
+  // store anything: it REPLACES the map's prototype with the Uint8Array. The
+  // disclosed bytes are then silently lost (the holder disclosed them and we
+  // report the record undisclosed), and every later lookup on that map resolves
+  // through `Uint8Array.prototype`, so an event named `slice` or `set` finds an
+  // inherited function and an event named `byteLength` or `buffer` THROWS a
+  // TypeError out of the verifier. A Map keys on the string itself and has none
+  // of that.
+  content: Map<string, Uint8Array | string>;
+  // Event ids the side input actually supplied — for the post-verify coverage
+  // cross-check, which needs to know what was offered, not just what bound.
+  suppliedIds: string[];
+  // Advisory lines about the INPUT ITSELF (skipped entries, a directory that
+  // disclosed nothing). None of them moves a verdict or an exit code.
+  notes: string[];
+}
+
+// The suffix the directory form reads, matched exactly — lowercase, which is
+// what `materializeBundle` writes. Anything else is skipped and NAMED rather
+// than guessed at, so a `.JSON` or extensionless file shows up as a note
+// instead of a mysteriously undisclosed event.
+const LOG_SUFFIX = ".json";
+
+// Which shape was passed is decided by `stat`, never by the extension: a pack's
+// log directory can be called anything, and `logs.json` is a legal directory
+// name. `stat` follows symlinks, so a symlinked logs directory works.
+async function loadLogs(logsPath: string, io: Cli): Promise<LoadedLogs | undefined> {
+  let isDirectory: boolean;
+  try {
+    isDirectory = (await stat(logsPath)).isDirectory();
+  } catch (e) {
+    io.err(`cannot read --logs ${logsPath}: ${errMsg(e)}`);
+    return undefined;
+  }
+  return isDirectory ? loadLogsDirectory(logsPath, io) : loadLogsMap(logsPath, io);
+}
+
+// The JSON-map form, unchanged: `{ event_id: <hex | utf8 text> }`.
+async function loadLogsMap(logsPath: string, io: Cli): Promise<LoadedLogs | undefined> {
+  let logsRaw: string;
+  try {
+    logsRaw = await readFile(logsPath, "utf8");
+  } catch (e) {
+    io.err(`cannot read --logs ${logsPath}: ${errMsg(e)}`);
+    return undefined;
+  }
+  let logsParsed: unknown;
+  try {
+    logsParsed = JSON.parse(logsRaw);
+  } catch (e) {
+    io.err(`--logs ${logsPath} is not valid JSON: ${errMsg(e)}`);
+    return undefined;
+  }
+  if (logsParsed === null || typeof logsParsed !== "object" || Array.isArray(logsParsed)) {
+    io.err(
+      `--logs ${logsPath} must be a JSON object mapping event_id → disclosed bytes, ` +
+        `or a directory of <event_id>${LOG_SUFFIX} files`,
+    );
+    return undefined;
+  }
+  const content = new Map<string, Uint8Array | string>();
+  const suppliedIds: string[] = [];
+  for (const [k, v] of Object.entries(logsParsed as Record<string, unknown>)) {
+    if (typeof v !== "string") continue;
+    content.set(k, decodeLogValue(v));
+    suppliedIds.push(k);
+  }
+  return { content, suppliedIds, notes: [] };
+}
+
+// The directory form. Flat, one file per event, `<event_id>.json`.
+//
+// The decisions this pins, none of which is a verification failure — an absent
+// or unusable disclosure is UNDISCLOSED, and absence is not evidence of
+// tampering (evidence-bundle.md §5.1):
+//
+//   - a file whose name is not a known event id  → loaded, binds to nothing,
+//     named in a post-verify note (silence is how a typo'd filename becomes a
+//     mysteriously undisclosed event)
+//   - an event with no corresponding file        → undetermined (`~`), noted
+//   - an empty directory                         → valid; discloses nothing,
+//     noted, exit code unchanged
+//   - a subdirectory                             → skipped, never recursed,
+//     noted (this is the "you pointed at the pack root, not its logs/" case)
+//   - anything not named `<event_id>.json`, and anything that is not a regular
+//     file                                       → skipped, noted
+//
+// The one hard stop is a file we SELECTED but cannot read: we were pointed at
+// it, so a permissions error must not read as minimal disclosure. That exits 2.
+async function loadLogsDirectory(dirPath: string, io: Cli): Promise<LoadedLogs | undefined> {
+  let names: string[];
+  try {
+    names = await readdir(dirPath);
+  } catch (e) {
+    io.err(`cannot read --logs directory ${dirPath}: ${errMsg(e)}`);
+    return undefined;
+  }
+
+  const content = new Map<string, Uint8Array | string>();
+  const suppliedIds: string[] = [];
+  const skippedDirs: string[] = [];
+  const skippedNames: string[] = [];
+
+  for (const name of [...names].sort()) {
+    const p = join(dirPath, name);
+    let isDirectory: boolean;
+    let isFile: boolean;
+    try {
+      // `stat`, not the dirent kind: a symlinked log file is a log file, and a
+      // symlink to a directory is a directory.
+      const s = await stat(p);
+      isDirectory = s.isDirectory();
+      isFile = s.isFile();
+    } catch (e) {
+      io.err(`cannot read --logs entry ${p}: ${errMsg(e)}`);
+      return undefined;
+    }
+    if (isDirectory) {
+      skippedDirs.push(name);
+      continue;
+    }
+    // Not a regular file (device, fifo, socket), or not named
+    // `<event_id>.json` — including a file named exactly `.json`, whose event
+    // id would be the empty string.
+    if (!isFile || !name.endsWith(LOG_SUFFIX) || name.length === LOG_SUFFIX.length) {
+      skippedNames.push(name);
+      continue;
+    }
+    const eventId = name.slice(0, -LOG_SUFFIX.length);
+    try {
+      // No encoding argument: bytes, exactly as they sit on disk. Copied out of
+      // Buffer's shared pool so the array handed to the verifier owns its own
+      // memory rather than a window onto a reused block.
+      content.set(eventId, new Uint8Array(await readFile(p)));
+    } catch (e) {
+      io.err(`cannot read --logs file ${p}: ${errMsg(e)}`);
+      return undefined;
+    }
+    suppliedIds.push(eventId);
+  }
+
+  const notes: string[] = [];
+  if (skippedDirs.length > 0) {
+    notes.push(
+      `--logs ${dirPath}: skipped ${count(skippedDirs.length, "subdirectory", "subdirectories")} ` +
+        `(${sample(skippedDirs)}) — the directory form reads <event_id>${LOG_SUFFIX} files ` +
+        `and does not recurse`,
+    );
+  }
+  if (skippedNames.length > 0) {
+    notes.push(
+      `--logs ${dirPath}: skipped ${count(skippedNames.length, "entry", "entries")} ` +
+        `not named <event_id>${LOG_SUFFIX} (${sample(skippedNames)})`,
+    );
+  }
+  if (suppliedIds.length === 0) {
+    notes.push(
+      `--logs ${dirPath} disclosed nothing (no <event_id>${LOG_SUFFIX} files) — every event ` +
+        `stays undisclosed, which is undetermined, not failed`,
+    );
+  }
+  return { content, suppliedIds, notes };
+}
+
+// What the side input covered, reported once the bundle's own event ids are
+// known. Both directions are ADVISORY — neither moves the verdict or the exit
+// code — and both exist because the silent version of each has already cost
+// somebody an afternoon:
+//
+//   - an entry matching no event binds to nothing. A typo'd id, or a directory
+//     scoped to a different bundle, otherwise looks identical to minimal
+//     disclosure.
+//   - an event whose content stayed undetermined disclosed no usable bytes.
+//     That is UNDISCLOSED, never a failure (evidence-bundle.md §5.1): absence
+//     of a disclosure is not evidence of tampering.
+function reportLogsCoverage(logs: LoadedLogs, result: EvidenceBundleResult, io: Cli): void {
+  const eventIds = new Set(result.events.map((e) => e.eventId));
+  const unmatched = logs.suppliedIds.filter((id) => !eventIds.has(id));
+  if (unmatched.length > 0) {
+    io.err(
+      `note: --logs supplied ${count(unmatched.length, "entry", "entries")} matching no event ` +
+        `in the bundle, ignored: ${sample(unmatched)}`,
+    );
+  }
+  const undetermined = result.events.filter((e) => e.contentOk === null);
+  if (undetermined.length > 0) {
+    io.err(
+      `note: ${undetermined.length} of ${result.events.length} event(s) have undetermined ` +
+        `content — no bytes disclosed, or no committed content_hash to bind them to. ` +
+        `Undisclosed, not failed: ${sample(undetermined.map((e) => e.eventId))}`,
+    );
+  }
+}
+
+function errMsg(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+function count(n: number, one: string, many: string): string {
+  return `${n} ${n === 1 ? one : many}`;
+}
+
+// First few names, quoted, with a tail count — enough to recognise the mistake
+// without pasting a whole directory into the terminal.
+function sample(names: string[], max = 3): string {
+  const shown = names.slice(0, max).map((n) => JSON.stringify(n)).join(", ");
+  return names.length > max ? `${shown}, +${names.length - max} more` : shown;
+}
+
+// The --logs MAP lane decides each disclosed value's encoding: a clean,
 // even-length, lowercase-hex string is hex bytes; anything else is utf8 text.
 // (The verifier itself only distinguishes "string ⇒ hex" from "Uint8Array ⇒
-// raw bytes" — the human-facing encoding choice is made here.)
+// raw bytes" — the human-facing encoding choice is made here. The DIRECTORY
+// lane never reaches this: its bytes are already bytes.)
 function decodeLogValue(v: string): Uint8Array | string {
   if (v.length > 0 && v.length % 2 === 0 && /^[0-9a-f]+$/.test(v)) return v; // hex passthrough
   return utf8(v); // raw utf8 bytes
@@ -403,7 +639,7 @@ function printUsage(io: Cli): void {
   io.out("Usage: npx @sanning/proof <command> [args]");
   io.out("");
   io.out("Commands:");
-  io.out("  verify <bundle.json> [gateways] [--logs <logs.json>]   Verify a bundle");
+  io.out("  verify <bundle.json> [gateways] [--logs <path>]        Verify a bundle");
   io.out("  bundle <source.json> --attestations <f> --key <f> [-o] Create an attested bundle");
   io.out("");
   io.out("Verify a sanning.evidence/v1 (sanning.anchor.trace/v1) bundle, an");
@@ -411,10 +647,21 @@ function printUsage(io: Cli): void {
   io.out("inclusion bundle, fully offline. Supply a comma-separated gateway list");
   io.out("to also re-fetch each checkpoint on-chain.");
   io.out("");
-  io.out("--logs <logs.json>  Bind disclosed raw logs to each event's committed");
-  io.out("                    content_hash. JSON object mapping event_id → bytes");
-  io.out("                    (even-length lowercase hex ⇒ hex, else utf8 text).");
-  io.out("                    In-body events[].content is verified automatically.");
+  io.out("--logs <path>       Bind disclosed raw logs to each event's committed");
+  io.out("                    content_hash. Either shape works, and which one you");
+  io.out("                    passed is decided by stat(), not by the extension:");
+  io.out("");
+  io.out("                      a DIRECTORY of <event_id>.json files — the file's");
+  io.out("                      raw bytes ARE the content, nothing is decoded.");
+  io.out("                      This is a materialized pack's logs/ directory:");
+  io.out("                        proof verify <pack>/bundle.json --logs <pack>/logs");
+  io.out("");
+  io.out("                      a JSON FILE mapping event_id → bytes (an");
+  io.out("                      even-length lowercase-hex value ⇒ hex, else utf8).");
+  io.out("");
+  io.out("                    In-body events[].content is verified automatically");
+  io.out("                    and takes precedence. An event with no disclosed");
+  io.out("                    bytes is undetermined (~), never a failure.");
   io.out("");
   io.out("Exit codes: 0 verified · 1 failed · 2 malformed · 3 gateway-unavailable");
 }
@@ -424,6 +671,7 @@ function reportEvidence(
   path: string,
   gateways: string[],
   io: Cli,
+  chains: ChainReading,
 ): number {
   if (result.status === "malformed") {
     io.err(paint("MALFORMED", R) + `  ${path}`);
@@ -443,7 +691,7 @@ function reportEvidence(
     for (const cp of result.checkpoints) {
       const onChain = cp.onChainOk === null ? "" : `  on-chain ${mark(cp.onChainOk)}`;
       io.out(
-        `    ${mark(cp.ok)} ${shortTx(cp.txId)}  envelope ${mark(cp.envelopeOk)}  root ${mark(cp.merkleRootOk)}${onChain}`,
+        `    ${mark(cp.ok)} ${shortTx(cp.checkpointRef)}  envelope ${mark(cp.envelopeOk)}  root ${mark(cp.merkleRootOk)}${onChain}`,
       );
       for (const e of cp.errors) io.out(paint(`        - ${e}`, R));
     }
@@ -468,6 +716,8 @@ function reportEvidence(
     }
   }
 
+  reportChains(chains, io);
+
   if (result.export) {
     reportExport(result.export, io);
   }
@@ -485,6 +735,45 @@ function reportEvidence(
   return mapStatusToExit(result.status, result.errors);
 }
 
+/**
+ * The chain block: what following each record's pointer to the record before it
+ * showed, over the records THIS bundle presents.
+ *
+ * Three deliberate choices, all of them about not overclaiming.
+ *
+ * 1. It prints the chains it READ, not just the findings. "3 chains, nothing to
+ *    report" and silence are different statements, and a reader that quietly
+ *    matched no records at all would produce the second one while covering
+ *    nothing.
+ * 2. It prints the scope sentence whenever it read a chain, findings or not.
+ *    "Delete an event and the next pointer dangles" is true; "so the bundle is
+ *    complete" does not follow, and two customer-facing documents had already
+ *    made that leap. The limit travels with the result or it gets dropped.
+ * 3. It does not touch the exit code. Findings are evidence; the exit code is
+ *    the verdict surface, and the pinned 0/1/2/3 contract stays exactly what it
+ *    was. A dangling link is something for a person to look at, not a machine
+ *    decision this check is entitled to make.
+ */
+function reportChains(reading: ChainReading, io: Cli): void {
+  if (reading.chains.length === 0) return;
+
+  io.out("");
+  io.out(paint("  Event chains", DIM));
+  for (const c of reading.chains) {
+    const where = c.namespace === undefined ? "record" : `${c.namespace} metadata`;
+    io.out(
+      paint(
+        `    ${c.chainKey}  ${count(c.events, "record", "records")} present  (linked in ${where})`,
+        DIM,
+      ),
+    );
+  }
+  for (const f of reading.findings) {
+    io.out(paint(`    ! ${renderChainFinding(f, "this bundle")}`, Y));
+  }
+  io.out(paint(`    ${CHAIN_READING_SCOPE}`, DIM));
+}
+
 // Render the export-specific block (evidence-export.md §5): source-bundle
 // linkage, cached-vs-recomputed verdict agreement, and each embedded operator
 // attestation (RSA-PSS sig · operator-address binding · data_hash binding).

package/src/compose.ts

@@ -94,7 +94,7 @@ export function attestationSignatureToHex(signature: string): string {
 
 // Normalize one attestation record for embedding: deep-clone (never mutate the
 // caller's input) and transcode its signature to lowercase hex. Everything else
-// — payload, public_key, signature_alg, checkpoint_tx_id — rides verbatim so the
+// — payload, public_key, signature_alg, checkpoint_ref — rides verbatim so the
 // operator's RSA-PSS signature over JCS(payload) remains valid.
 function normalizeAttestation(rec: AttestationRecord): AttestationRecord {
   const cloned = JSON.parse(JSON.stringify(rec)) as AttestationRecord;