@sanning/proof 0.13.0 → 0.15.0

package/src/cli.ts

@@ -57,10 +57,8 @@ import { CHAIN_READING_SCOPE, readChains, renderChainFinding } from "./chain.js"
 type ChainOutcome = ChainReading | { unreadable: string };
 import type { ChainReading } from "./chain.js";
 import {
-  CASE_RELIANCE,
   VERDICT_DISPLAY_TITLES,
-  WITNESS_NOT_LOOKED_UP,
-  type WitnessLine,
+  caseReliance,
   readCase,
   renderCaseNote,
   renderCaseSummary,
@@ -78,6 +76,20 @@ import { composeExport } from "./compose.js";
 import type { ComposeExportOptions } from "./compose.js";
 import { isHexField, sha256Hex, utf8 } from "./crypto.js";
 import { verifyEvidenceBundle } from "./evidence.js";
+import { DuplicateKeyError, parseRefusingDuplicates } from "./verifier.js";
+import { fileMatchToJson, matchCaseFiles, matchFiles, renderFileMatch } from "./file-match.js";
+import type { OfferedFile } from "./file-match.js";
+import {
+  type CachedWitnessTime,
+  WITNESS_CACHE_NAME,
+  readWitnessCache,
+} from "./witness-cache.js";
+// The public-record (witness) lookup this command runs with `--gateways`:
+// moved to its own pure module (proof#200) so a consumer that is not this CLI,
+// the verify page, can call the SAME implementation. `onChainHalf` and
+// `witnessLine` are this command's own two building blocks, unchanged; see
+// `./witness-lookup.ts` for the exported entry point, `lookupPublicRecord`.
+import { type OnChainHalf, onChainHalf, witnessLine } from "./witness-lookup.js";
 import type { AttestationRecord, EvidenceBundle, EvidenceBundleResult, ExportResult } from "./evidence.js";
 import { checkDeclaration, renderDeclarationSummary, renderNote } from "./declaration.js";
 import { completenessNotes, gradePack, renderCause } from "./grading.js";
@@ -276,6 +288,7 @@ async function runVerify(rest: string[], io: Cli, sink: JsonSink | null): Promis
   // second positional argument until then, and a second positional is now a
   // usage error). The one positional is the bundle.
   let logsPath: string | undefined;
+  let filePaths: string[] | undefined;
   let gatewayArg: string | undefined;
   const positional: string[] = [];
   for (let i = 0; i < rest.length; i++) {
@@ -302,6 +315,17 @@ async function runVerify(rest: string[], io: Cli, sink: JsonSink | null): Promis
       i++;
       continue;
     }
+    if (a === "--files") {
+      const taken = takeFilePaths(rest, i + 1);
+      if (taken.length === 0) {
+        io.err("verify: --files requires at least one file path");
+        printUsage(io);
+        return EXIT_MALFORMED;
+      }
+      filePaths = [...(filePaths ?? []), ...taken];
+      i += taken.length;
+      continue;
+    }
     positional.push(a);
   }
 
@@ -329,6 +353,16 @@ async function runVerify(rest: string[], io: Cli, sink: JsonSink | null): Promis
   }
   const content = logs?.content;
 
+  let offered: OfferedFile[] | undefined;
+  if (filePaths !== undefined) {
+    const read = await readOfferedFiles(filePaths);
+    if (typeof read === "string") {
+      io.err(`verify: ${read}`);
+      return EXIT_MALFORMED;
+    }
+    offered = read;
+  }
+
   let raw: Uint8Array;
   try {
     raw = new Uint8Array(await readFile(bundlePath));
@@ -346,6 +380,8 @@ async function runVerify(rest: string[], io: Cli, sink: JsonSink | null): Promis
   } catch (e) {
     if (e instanceof BundleReadError && e.tooDeep) {
       io.err(`${bundlePath} ${e.detail}; refusing to read it`);
+    } else if (e instanceof BundleReadError && e.duplicate) {
+      io.err(`${bundlePath} ${NOT_I_JSON}: ${e.detail}`);
     } else {
       io.err(`${bundlePath} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
     }
@@ -363,6 +399,9 @@ async function runVerify(rest: string[], io: Cli, sink: JsonSink | null): Promis
       // has no such per-event content. Say so rather than silently ignoring it.
       io.err("note: --logs has no effect on a sanning.agent.proof/v1 bundle (ignored)");
     }
+    if (offered) {
+      io.err("note: --files has no effect on a sanning.agent.proof/v1 bundle (ignored)");
+    }
     const result = await verifyAgentProof(parsed, {
       gateways,
       ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
@@ -397,12 +436,45 @@ async function runVerify(rest: string[], io: Cli, sink: JsonSink | null): Promis
     chains = { unreadable: errMsg(e) };
   }
   const exit = reportEvidence(result, bundlePath, gateways, io, chains, parsed, logs, sink);
+  // Files handed in beside the pack (evidence-bundle.md 5.7, A29): findings
+  // beside the verdict, never inside it, so `exit` is untouched.
+  if (offered !== undefined) {
+    const reading = await matchFiles(parsed, offered, content);
+    for (const line of renderFileMatch(reading)) io.out(line);
+    if (sink !== null && sink.data !== null) sink.data.files = fileMatchToJson(reading);
+  }
   // 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;
 }
 
+// The paths after `--files`: every argument up to the next option.
+function takeFilePaths(args: readonly string[], start: number): string[] {
+  const out: string[] = [];
+  for (const arg of args.slice(start)) {
+    if (arg.startsWith("--")) break;
+    out.push(arg);
+  }
+  return out;
+}
+
+// Each `--files` path as `{ name, bytes }`, the name exactly as typed, or the
+// one error line when a path is not a readable regular file. The line names the
+// path and not the operating system's words, which differ by kernel.
+async function readOfferedFiles(paths: readonly string[]): Promise<OfferedFile[] | string> {
+  const out: OfferedFile[] = [];
+  for (const path of paths) {
+    try {
+      if (!(await stat(path)).isFile()) return `--files ${path} is not a readable file`;
+      out.push({ name: path, bytes: new Uint8Array(await readFile(path)) });
+    } catch {
+      return `--files ${path} is not a readable file`;
+    }
+  }
+  return out;
+}
+
 // `proof export <source-bundle.json> --attestations <f> --key <f> [--out <out>]`
 //
 // Compose a signed, offline-verifiable sanning.evidence.export/v2 artifact from a
@@ -582,8 +654,12 @@ async function readJson<T>(path: string, io: Cli): Promise<T | undefined> {
     return undefined;
   }
   try {
-    return JSON.parse(raw) as T;
+    return parseRefusingDuplicates(raw) as T;
   } catch (e) {
+    if (e instanceof DuplicateKeyError) {
+      io.err(`${path} ${NOT_I_JSON}: ${e.message}`);
+      return undefined;
+    }
     io.err(`${path} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
     return undefined;
   }
@@ -713,8 +789,14 @@ async function loadLogsMap(logsPath: string, io: Cli): Promise<LoadedLogs | unde
   }
   let logsParsed: unknown;
   try {
-    logsParsed = JSON.parse(logsRaw);
+    logsParsed = parseRefusingDuplicates(logsRaw);
   } catch (e) {
+    if (e instanceof DuplicateKeyError) {
+      // One event id named twice hands the reader two contents for one
+      // record, and the last one silently won (proof#144).
+      io.err(`--logs ${logsPath} ${NOT_I_JSON}: ${e.message}`);
+      return undefined;
+    }
     io.err(`--logs ${logsPath} is not valid JSON: ${errMsg(e)}`);
     return undefined;
   }
@@ -906,10 +988,12 @@ function printUsage(io: Cli): void {
   io.out("       (npx @sanning/proof <command> [args], without installing)");
   io.out("");
   io.out("Commands:");
-  io.out("  verify <bundle.json> [--gateways <urls>] [--logs <path>] [--json]  Verify a bundle");
+  io.out("  verify <bundle.json> [--gateways <urls>] [--logs <path>] [--files <path>...] [--json]");
+  io.out("                                                          Verify a bundle");
   io.out("  export <source.json> --attestations <f> --key <f> [--out <f>] [--json]");
   io.out("                                                          Create an attested export");
-  io.out("  case <folder>... [--gateways <urls>] [--json]          Read several packs as one case");
+  io.out("  case <folder>... [--gateways <urls>] [--files <path>...] [--json]");
+  io.out("                                                          Read several packs as one case");
   io.out("                                                          (`case --help` for its exit codes)");
   io.out("");
   io.out("Verify a sanning.evidence/v1 bundle (body sanning.anchor.trace/v3,");
@@ -922,6 +1006,14 @@ function printUsage(io: Cli): void {
   io.out("--json              Print the verdict, the causes and the exit code as");
   io.out("                    JSON, for a script, instead of the report.");
   io.out("");
+  io.out("--files <path>...   Files handed in beside the pack, every path up to the");
+  io.out("                    next option. Each is hashed and matched, by SHA-256");
+  io.out("                    alone, against what the pack's signed records commit");
+  io.out("                    to; the report lists the files the pack vouches for,");
+  io.out("                    the files that match no record, and the commitments");
+  io.out("                    no file was offered for. Names and folders are never");
+  io.out("                    compared, and the verdict never moves.");
+  io.out("");
   io.out("--logs <path>       Bind disclosed raw logs to each event's committed");
   io.out("                    content_hash, or message_hash for a hand-off record.");
   io.out("                    Either shape works, and which one you");
@@ -1460,18 +1552,28 @@ export class CaseInputError extends Error {
 /**
  * `bundle.json` bytes that `readBundleBytes` will not read. `tooDeep` separates
  * the one refusal that is not a parse error; `detail` is the parser's own words,
- * which differ by kernel and are printed by `verify` only.
+ * which differ by kernel and are printed by `verify` only. `duplicate` marks the
+ * one parse refusal whose `detail` is kernel wording, identical in both kernels
+ * (`duplicate key "<name>"`, proof#144), so both commands print it.
  */
 export class BundleReadError extends Error {
   readonly tooDeep: boolean;
   readonly detail: string;
-  constructor(tooDeep: boolean, detail: string) {
+  readonly duplicate: boolean;
+  constructor(tooDeep: boolean, detail: string, duplicate = false) {
     super(detail);
     this.tooDeep = tooDeep;
     this.detail = detail;
+    this.duplicate = duplicate;
   }
 }
 
+// What both commands say about bytes that repeat a member name, before the
+// kernel's own `duplicate key "<name>"`. RFC 8259 JSON permits a repeat and
+// I-JSON (RFC 7493), which JCS is defined over, does not, so "not valid JSON"
+// would be the wrong sentence. `NOT_I_JSON` in the Python twin.
+export const NOT_I_JSON = "is not I-JSON (RFC 7493)";
+
 // `ignoreBOM: true` KEEPS a byte-order mark in the text, as Node's
 // `readFile(path, "utf8")` did for `verify`, so a leading one is not JSON.
 const bundleDecoder = new TextDecoder("utf-8", { ignoreBOM: true });
@@ -1481,7 +1583,8 @@ const nameDecoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
  * How both `verify` and `case` turn `bundle.json` bytes into JSON, in both
  * kernels (`read_bundle_bytes` in the Python twin). UTF-8 with each ill-formed
  * sequence read as U+FFFD, and a byte-order mark kept; then nesting deeper than
- * MAX_JSON_DEPTH is refused before any parser walks into it; then `JSON.parse`.
+ * MAX_JSON_DEPTH is refused before any parser walks into it; then `JSON.parse`,
+ * refusing an object that repeats a member name (I-JSON, RFC 7493; proof#144).
  * Throws `BundleReadError`.
  */
 export function readBundleBytes(bytes: Uint8Array): unknown {
@@ -1490,8 +1593,9 @@ export function readBundleBytes(bytes: Uint8Array): unknown {
     throw new BundleReadError(true, `nests deeper than ${MAX_JSON_DEPTH} levels`);
   }
   try {
-    return JSON.parse(text);
+    return parseRefusingDuplicates(text);
   } catch (e) {
+    if (e instanceof DuplicateKeyError) throw new BundleReadError(false, e.message, true);
     throw new BundleReadError(false, e instanceof Error ? e.message : String(e));
   }
 }
@@ -1596,6 +1700,32 @@ export async function splitCase(
   return { packs, outside: outside.sort(), notRegular: notRegular.sort() };
 }
 
+/**
+ * The bytes of the `witness-cache.json` beside a pack's `bundle.json`
+ * (evidence-bundle 5.6.6, v1.25, A30), or `null`.
+ *
+ * The split rule is not changed for it: the file stays outside every pack,
+ * listed as such, and is opened here and nowhere else. It is read only where it
+ * is a regular file the split left outside every pack, so a file under another
+ * pack's `logs/` is that pack's, and a link is never followed. A file that
+ * cannot be read is no cache, never a refusal of the drop.
+ */
+async function witnessCacheBytes(
+  tree: Map<string, TreeEntry>,
+  split: SplitCase,
+  pack: SplitPack,
+): Promise<Uint8Array | null> {
+  const path = pack.bundlePath.slice(0, -"bundle.json".length) + WITNESS_CACHE_NAME;
+  const entry = tree.get(path);
+  if (entry === undefined || !entry.regular || !split.outside.includes(path)) return null;
+  try {
+    return await readFileEntry(entry, path);
+  } catch (e) {
+    if (e instanceof CaseInputError) return null;
+    throw e;
+  }
+}
+
 /** `verify`'s reader, with the refusal named by the pack's path. */
 export function loadBundle(pack: SplitPack): unknown {
   try {
@@ -1604,6 +1734,9 @@ export function loadBundle(pack: SplitPack): unknown {
     if (e instanceof BundleReadError && e.tooDeep) {
       throw new CaseInputError(`${pack.bundlePath} nests deeper than ${MAX_JSON_DEPTH} levels`);
     }
+    if (e instanceof BundleReadError && e.duplicate) {
+      throw new CaseInputError(`${pack.bundlePath} ${NOT_I_JSON}: ${e.detail}`);
+    }
     throw new CaseInputError(`${pack.bundlePath} is not valid JSON`);
   }
 }
@@ -1819,7 +1952,7 @@ async function unzip(
 
 export const CASE_USAGE = `sanning-proof case -- a case reading: one verdict over one pack or many, offline
 
-  sanning-proof case <folder or case file>... [--gateways <url,url>] [--json]
+  sanning-proof case <folder or case file>... [--gateways <url,url>] [--files <path>...] [--json]
 
   <folder>    a pack folder (bundle.json plus logs/), a folder that holds
               several packs, or an unzipped case file. Packs are found by the
@@ -1843,6 +1976,10 @@ export const CASE_USAGE = `sanning-proof case -- a case reading: one verdict ove
   --gateways  comma-separated gateway URLs. Each pack's witnesses are then
               looked up on the public record, pack by pack, and reported on
               the witness line. The lookup never changes the verdict word.
+  --files     files handed in beside the packs, every path up to the next
+              option, matched by SHA-256 alone against what every pack's
+              signed records commit to. A file under a pack's logs/ is
+              offered only when it is named here. The verdict never moves.
   --json      the full reading as JSON: the verdict, every exception and note
               with its rendered line, every record, every contribution, the
               packs, the files outside them, the case file index comparison,
@@ -1896,111 +2033,6 @@ function jsonText(v: unknown): string {
   return JSON.stringify(sortKeys(v), null, 2);
 }
 
-interface OnChainRow {
-  ref: string;
-  witnesses: number;
-  confirmed: number;
-  mismatched: number;
-  unreachable: number;
-  not_checked: number;
-}
-
-interface OnChainHalf {
-  /** Present only where a lookup ran: each gateway that answered, in the order given. */
-  answered?: string[];
-  checked: boolean;
-  gateways: string[];
-  packs: OnChainRow[];
-  verdict: "not_checked" | "confirmed" | "failed" | "undetermined";
-}
-
-// Each pack's witnesses, re-fetched through `verifyEvidenceBundle`. Outside the
-// case reading on purpose: `readCase` makes no network call, and neither does
-// the verify page's case reading, so the case verdict stays the one both
-// surfaces compute. This adds the half the reading names as not checked.
-async function onChainHalf(
-  packs: readonly [string, unknown][],
-  gateways: string[],
-  io: Cli,
-): Promise<OnChainHalf> {
-  if (gateways.length === 0) return { checked: false, gateways: [], packs: [], verdict: "not_checked" };
-  const rows: OnChainRow[] = [];
-  const answered = new Set<string>();
-  for (const [ref, bundle] of packs) {
-    const result = await verifyEvidenceBundle(bundle, {
-      gateways,
-      ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
-    });
-    const witnesses = [...result.checkpoints, ...(result.stamps ?? [])];
-    const row: OnChainRow = {
-      ref,
-      witnesses: witnesses.length,
-      confirmed: 0,
-      mismatched: 0,
-      unreachable: 0,
-      not_checked: 0,
-    };
-    for (const w of witnesses) {
-      const rollup = w.onChain?.rollup ?? null;
-      if (rollup === "confirm") row.confirmed++;
-      else if (rollup === "mismatch") row.mismatched++;
-      else if (rollup === "unreachable") row.unreachable++;
-      else row.not_checked++;
-    }
-    rows.push(row);
-    for (const w of witnesses) {
-      for (const outcome of w.onChain?.perGateway ?? []) {
-        if (outcome.outcome === "confirm" || outcome.outcome === "mismatch") {
-          answered.add(outcome.gateway);
-        }
-      }
-    }
-  }
-  const verdict = rows.some((r) => r.mismatched > 0)
-    ? "failed"
-    : rows.some((r) => r.witnesses === 0 || r.unreachable > 0 || r.not_checked > 0)
-      ? "undetermined"
-      : "confirmed";
-  return {
-    answered: gateways.filter((g) => answered.has(g)),
-    checked: true,
-    gateways: [...gateways],
-    packs: rows,
-    verdict,
-  };
-}
-
-/**
- * The witness line (evidence-bundle 5.5.6 v1.20, A24, D7) from the on-chain
- * half: `confirmed` is `confirmed`, `not_checked` and `undetermined` are
- * `not_checked` with the reason, and `failed` is `differs`. It never moves the
- * headline.
- */
-export function witnessLine(onChain: OnChainHalf): WitnessLine {
-  if (!onChain.checked) {
-    return {
-      state: WITNESS_NOT_LOOKED_UP.state,
-      reasons: [...WITNESS_NOT_LOOKED_UP.reasons],
-      services: [...WITNESS_NOT_LOOKED_UP.services],
-    };
-  }
-  const services = [...(onChain.answered ?? [])];
-  if (onChain.verdict === "failed") return { state: "differs", reasons: [], services };
-  if (onChain.verdict === "confirmed") return { state: "confirmed", reasons: [], services };
-  const rows = onChain.packs;
-  const reasons: string[] = [];
-  if (rows.some((r) => r.witnesses === 0)) reasons.push("a pack names no witness");
-  if (rows.some((r) => r.unreachable > 0)) {
-    reasons.push(
-      "a lookup did not settle: the service could not be reached, or it " +
-        "holds no such witness yet",
-    );
-  }
-  if (rows.some((r) => r.not_checked > 0)) {
-    reasons.push("no lookup is made for a witness kind a pack names");
-  }
-  return { state: "not_checked", reasons, services };
-}
 
 /**
  * The case verdict's code, moved only by an on-chain half that was asked for:
@@ -2199,6 +2231,7 @@ async function caseCommand(argv: readonly string[], io: Cli): Promise<number> {
   let asJson = false;
   let gateways: string[] = [];
   const paths: string[] = [];
+  let filePaths: string[] | undefined;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]!;
     if ((arg === "--help" || arg === "-h" || arg === "help") && paths.length === 0) {
@@ -2219,6 +2252,15 @@ async function caseCommand(argv: readonly string[], io: Cli): Promise<number> {
         .map((g) => g.trim())
         .filter((g) => g.length > 0);
       i++;
+    } else if (arg === "--files") {
+      const taken = takeFilePaths(argv, i + 1);
+      if (taken.length === 0) {
+        io.err("case: --files requires at least one file path");
+        outBlock(io, CASE_USAGE);
+        return EXIT_MALFORMED;
+      }
+      filePaths = [...(filePaths ?? []), ...taken];
+      i += taken.length;
     } else if (arg.startsWith("--")) {
       io.err(`case: unknown option ${arg}`);
       outBlock(io, CASE_USAGE);
@@ -2233,6 +2275,13 @@ async function caseCommand(argv: readonly string[], io: Cli): Promise<number> {
     return EXIT_MALFORMED;
   }
 
+  let offered: OfferedFile[] | undefined;
+  if (filePaths !== undefined) {
+    const read = await readOfferedFiles(filePaths);
+    if (typeof read === "string") return caseError(new CaseInputError(read), asJson, io);
+    offered = read;
+  }
+
   let split;
   let tree: Map<string, TreeEntry>;
   let bundles: [SplitPack, unknown][];
@@ -2255,25 +2304,31 @@ async function caseCommand(argv: readonly string[], io: Cli): Promise<number> {
     if (e instanceof CaseInputError) return caseError(e, asJson, io);
     throw e;
   }
+  const caches: CachedWitnessTime[][] = [];
+  for (const [p, bundle] of bundles) {
+    caches.push(readWitnessCache(bundle, await witnessCacheBytes(tree, split, p)));
+  }
   const onChain = await onChainHalf(
-    bundles.map(([p, bundle]): [string, unknown] => [p.ref, bundle]),
+    bundles.map(([p, bundle], i): [string, unknown, CachedWitnessTime[]] => [p.ref, bundle, caches[i]!]),
     gateways,
-    io,
+    { ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}) },
   );
-  const witness = witnessLine(onChain);
+  const witness = witnessLine(onChain, caches.flat());
   const code = caseExitCode(reading.verdict, onChain.verdict);
   const nil = <T>(v: T | undefined): T | null => (v === undefined ? null : v);
 
   const data = {
     verdict: reading.verdict,
     title: titleOf(reading.verdict),
-    reliance: CASE_RELIANCE[reading.verdict],
+    reliance: caseReliance(reading.verdict, reading.handoffRecords),
     exit_code: code,
     summary: renderCaseSummary(reading),
     witness: {
       state: witness.state,
       reasons: witness.reasons,
       services: witness.services,
+      ...(witness.cached ? { cached: witness.cached } : {}),
+      ...(witness.recorded ? { recorded: witness.recorded } : {}),
       rendered: renderWitnessLine(witness),
     },
     handoff_records: reading.handoffRecords,
@@ -2321,8 +2376,21 @@ async function caseCommand(argv: readonly string[], io: Cli): Promise<number> {
     case_file: caseFile,
     on_chain: onChain,
   };
-  if (asJson) outJson(io, jsonText(data));
-  else for (const line of caseReport(data)) io.out(noLoneSurrogates(line));
+  // Files handed in beside the packs (evidence-bundle.md 5.7, A29). A pack's
+  // logs/ is its side content and is never an offered file; only the paths
+  // after --files are. Nothing here moves `code`.
+  let fileLines: string[] = [];
+  const out: Record<string, unknown> = data;
+  if (offered !== undefined) {
+    const fileReading = await matchCaseFiles(
+      bundles.map(([p, bundle]) => ({ ref: p.ref, bundle, content: p.content })),
+      offered,
+    );
+    out.files = fileMatchToJson(fileReading);
+    fileLines = renderFileMatch(fileReading);
+  }
+  if (asJson) outJson(io, jsonText(out));
+  else for (const line of [...caseReport(data), ...fileLines]) io.out(noLoneSurrogates(line));
   return code;
 }
 

package/src/compose.ts

@@ -39,7 +39,7 @@ import {
   sha256Hex,
   utf8,
 } from "./crypto.js";
-import { jcs } from "./verifier.js";
+import { isRfc3339UtcInstant, jcs } from "./verifier.js";
 
 // The exporter's Ed25519 wrapper-signing key. `privateKey` is a 32-byte seed as
 // lowercase hex (the @noble/ed25519 / stack convention, e.g. the fixtures'
@@ -133,6 +133,13 @@ export async function composeExport(
     throw new Error("composeExport: exporterKey.privateKey (32-byte hex seed) is required");
   }
 
+  if (options.generatedAt !== undefined && !isRfc3339UtcInstant(options.generatedAt)) {
+    // The verifier reads this as `malformed generated_at` (evidence-bundle §2,
+    // A31), so composing one would sign an export this kernel rejects.
+    throw new Error(
+      "composeExport: generatedAt is not an RFC 3339 UTC date-time with Z naming a real date and time",
+    );
+  }
   const generatedAt = options.generatedAt ?? new Date().toISOString();
   const previousHash = options.previousHash ?? GENESIS;
   const issuerId = options.issuerId ?? "sanning-verify";