@sanning/proof 0.13.0 → 0.14.0

package/dist/cli.js

@@ -48,12 +48,15 @@ import { basename, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isAgentProofSpec, verifyAgentProof } from "./agent-proof.js";
 import { CHAIN_READING_SCOPE, readChains, renderChainFinding } from "./chain.js";
-import { CASE_RELIANCE, VERDICT_DISPLAY_TITLES, WITNESS_NOT_LOOKED_UP, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
+import { VERDICT_DISPLAY_TITLES, WITNESS_NOT_LOOKED_UP, caseReliance, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
 import { CASE_FILE_INDEX_NAME, jsonDepthExceeds, readCaseFileIndex, renderCaseFileFinding, } from "./case-file.js";
 import { ZipReadError, readZip } from "./zip-reader.js";
 import { composeExport } 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 { WITNESS_CACHE_NAME, checkWitnessCache, readWitnessCache, renderWitnessTime, } from "./witness-cache.js";
 import { checkDeclaration, renderDeclarationSummary, renderNote } from "./declaration.js";
 import { completenessNotes, gradePack, renderCause } from "./grading.js";
 import { EXIT_CODES_HELP, EXIT_FAILED, EXIT_MALFORMED, EXIT_UNDETERMINED, EXIT_VERIFIED, exitCodeFor, } from "./exit-codes.js";
@@ -199,6 +202,7 @@ async function runVerify(rest, io, sink) {
     // second positional argument until then, and a second positional is now a
     // usage error). The one positional is the bundle.
     let logsPath;
+    let filePaths;
     let gatewayArg;
     const positional = [];
     for (let i = 0; i < rest.length; i++) {
@@ -225,6 +229,17 @@ async function runVerify(rest, io, sink) {
             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);
     }
     const [bundlePath] = positional;
@@ -251,6 +266,15 @@ async function runVerify(rest, io, sink) {
             io.err(`note: ${n}`);
     }
     const content = logs?.content;
+    let offered;
+    if (filePaths !== undefined) {
+        const read = await readOfferedFiles(filePaths);
+        if (typeof read === "string") {
+            io.err(`verify: ${read}`);
+            return EXIT_MALFORMED;
+        }
+        offered = read;
+    }
     let raw;
     try {
         raw = new Uint8Array(await readFile(bundlePath));
@@ -270,6 +294,9 @@ async function runVerify(rest, io, sink) {
         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)}`);
         }
@@ -284,6 +311,9 @@ async function runVerify(rest, io, sink) {
             // 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 } : {}),
@@ -318,12 +348,48 @@ async function runVerify(rest, io, sink) {
         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, start) {
+    const out = [];
+    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) {
+    const out = [];
+    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
@@ -514,9 +580,13 @@ async function readJson(path, io) {
         return undefined;
     }
     try {
-        return JSON.parse(raw);
+        return parseRefusingDuplicates(raw);
     }
     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;
     }
@@ -598,9 +668,15 @@ async function loadLogsMap(logsPath, io) {
     }
     let logsParsed;
     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;
     }
@@ -775,10 +851,12 @@ function printUsage(io) {
     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,");
@@ -791,6 +869,14 @@ function printUsage(io) {
     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");
@@ -1234,17 +1320,26 @@ 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 {
     tooDeep;
     detail;
-    constructor(tooDeep, detail) {
+    duplicate;
+    constructor(tooDeep, detail, 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 });
@@ -1253,7 +1348,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) {
@@ -1262,9 +1358,11 @@ export function readBundleBytes(bytes) {
         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));
     }
 }
@@ -1332,6 +1430,30 @@ export async function splitCase(tree, read) {
     }
     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, split, pack) {
+    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) {
     try {
@@ -1341,6 +1463,9 @@ export function loadBundle(pack) {
         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`);
     }
 }
@@ -1543,7 +1668,7 @@ async function unzip(arg, prefix, tree, seen) {
 // 5.5.4 v1.16, A17), so it reads `failed` and exits 1.
 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
@@ -1567,6 +1692,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,
@@ -1615,6 +1744,19 @@ function sortKeys(v) {
 function jsonText(v) {
     return JSON.stringify(sortKeys(v), null, 2);
 }
+function witnessTimeRow(t) {
+    return {
+        stamp_ref: t.cached.stampRef,
+        cached: { block_height: t.cached.blockHeight, block_time: t.cached.blockTime },
+        outcome: t.outcome,
+        answers: t.answers.map((a) => ({
+            gateway: a.gateway,
+            outcome: a.outcome,
+            block_height: a.blockHeight,
+            block_time: a.blockTime,
+        })),
+    };
+}
 // 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
@@ -1624,7 +1766,7 @@ async function onChainHalf(packs, gateways, io) {
         return { checked: false, gateways: [], packs: [], verdict: "not_checked" };
     const rows = [];
     const answered = new Set();
-    for (const [ref, bundle] of packs) {
+    for (const [ref, bundle, cached] of packs) {
         const result = await verifyEvidenceBundle(bundle, {
             gateways,
             ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
@@ -1649,6 +1791,12 @@ async function onChainHalf(packs, gateways, io) {
             else
                 row.not_checked++;
         }
+        // The witness times the pack's witness-cache.json gives, looked up where
+        // it gives any (5.6.6, v1.25, A30). A pack with no cache gets no key and
+        // no request.
+        const times = await checkWitnessCache(cached, gateways, io.fetchImpl ?? fetch);
+        if (times.length > 0)
+            row.witness_times = times.map(witnessTimeRow);
         rows.push(row);
         for (const w of witnesses) {
             for (const outcome of w.onChain?.perGateway ?? []) {
@@ -1657,8 +1805,14 @@ async function onChainHalf(packs, gateways, io) {
                 }
             }
         }
+        for (const t of times) {
+            for (const a of t.answers) {
+                if (a.outcome === "matches" || a.outcome === "differs")
+                    answered.add(a.gateway);
+            }
+        }
     }
-    const verdict = rows.some((r) => r.mismatched > 0)
+    const verdict = rows.some((r) => r.mismatched > 0 || (r.witness_times ?? []).some((t) => t.outcome === "differs"))
         ? "failed"
         : rows.some((r) => r.witnesses === 0 || r.unreachable > 0 || r.not_checked > 0)
             ? "undetermined"
@@ -1677,20 +1831,63 @@ async function onChainHalf(packs, gateways, io) {
  * `not_checked` with the reason, and `failed` is `differs`. It never moves the
  * headline.
  */
-export function witnessLine(onChain) {
+// Distinct `[blockHeight, blockTime]` pairs, in time order.
+function distinctTimes(times) {
+    const seen = new Map();
+    for (const [h, t] of times)
+        seen.set(`${h}:${t}`, [h, t]);
+    return [...seen.values()].sort((a, b) => a[1] - b[1] || a[0] - b[0]);
+}
+// Only the keys that carry something: a line with no cached or recorded time
+// is the line 0.13.0 printed, field for field.
+function withTimes(line, cached, recorded) {
+    return {
+        ...line,
+        ...(cached.length > 0 ? { cached } : {}),
+        ...(recorded.length > 0 ? { recorded } : {}),
+    };
+}
+/**
+ * `cached` is every witness time the packs cache (5.6.6, v1.25, A30). Where no
+ * lookup ran, each is printed labelled not checked. Where one ran, each time
+ * the public record matched is printed as the record's, each time no lookup
+ * settled stays labelled not checked, and a time the record contradicts is the
+ * reason the line reads `differs`.
+ */
+export function witnessLine(onChain, cached = []) {
     if (!onChain.checked) {
-        return {
+        return withTimes({
             state: WITNESS_NOT_LOOKED_UP.state,
             reasons: [...WITNESS_NOT_LOOKED_UP.reasons],
             services: [...WITNESS_NOT_LOOKED_UP.services],
-        };
+        }, distinctTimes(cached.map((c) => [c.blockHeight, c.blockTime])), []);
     }
     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 times = rows.flatMap((r) => r.witness_times ?? []);
+    const unsettled = distinctTimes(times
+        .filter((t) => t.outcome === "not_checked")
+        .map((t) => [t.cached.block_height, t.cached.block_time]));
+    const recorded = distinctTimes(times
+        .filter((t) => t.outcome === "matches")
+        .flatMap((t) => t.answers.filter((a) => a.outcome === "matches"))
+        .map((a) => [a.block_height, a.block_time]));
+    const contradicted = [];
+    for (const t of times) {
+        if (t.outcome !== "differs")
+            continue;
+        const a = t.answers.find((x) => x.outcome === "differs");
+        const reason = `a pack dates the witness ${renderWitnessTime(t.cached.block_height, t.cached.block_time)}` +
+            `, and the public record dates it ${renderWitnessTime(a.block_height, a.block_time)}`;
+        if (!contradicted.includes(reason))
+            contradicted.push(reason);
+    }
+    if (onChain.verdict === "failed") {
+        return withTimes({ state: "differs", reasons: contradicted, services }, unsettled, recorded);
+    }
+    if (onChain.verdict === "confirmed") {
+        return withTimes({ state: "confirmed", reasons: [], services }, unsettled, recorded);
+    }
     const reasons = [];
     if (rows.some((r) => r.witnesses === 0))
         reasons.push("a pack names no witness");
@@ -1701,7 +1898,7 @@ export function witnessLine(onChain) {
     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 };
+    return withTimes({ state: "not_checked", reasons, services }, unsettled, recorded);
 }
 /**
  * The case verdict's code, moved only by an on-chain half that was asked for:
@@ -1859,6 +2056,7 @@ async function caseCommand(argv, io) {
     let asJson = false;
     let gateways = [];
     const paths = [];
+    let filePaths;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if ((arg === "--help" || arg === "-h" || arg === "help") && paths.length === 0) {
@@ -1881,6 +2079,16 @@ async function caseCommand(argv, io) {
                 .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);
@@ -1895,6 +2103,13 @@ async function caseCommand(argv, io) {
         outBlock(io, CASE_USAGE);
         return EXIT_MALFORMED;
     }
+    let offered;
+    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;
     let bundles;
@@ -1918,20 +2133,26 @@ async function caseCommand(argv, io) {
             return caseError(e, asJson, io);
         throw e;
     }
-    const onChain = await onChainHalf(bundles.map(([p, bundle]) => [p.ref, bundle]), gateways, io);
-    const witness = witnessLine(onChain);
+    const caches = [];
+    for (const [p, bundle] of bundles) {
+        caches.push(readWitnessCache(bundle, await witnessCacheBytes(tree, split, p)));
+    }
+    const onChain = await onChainHalf(bundles.map(([p, bundle], i) => [p.ref, bundle, caches[i]]), gateways, io);
+    const witness = witnessLine(onChain, caches.flat());
     const code = caseExitCode(reading.verdict, onChain.verdict);
     const nil = (v) => (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,
@@ -1979,10 +2200,20 @@ async function caseCommand(argv, io) {
         case_file: caseFile,
         on_chain: onChain,
     };
+    // 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 = [];
+    const out = 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(data));
+        outJson(io, jsonText(out));
     else
-        for (const line of caseReport(data))
+        for (const line of [...caseReport(data), ...fileLines])
             io.out(noLoneSurrogates(line));
     return code;
 }

package/dist/compose.js

@@ -22,7 +22,7 @@
 // does not invalidate the operator signature.
 import { EXPORT_BODY_TYPE, recomputeExportVerdict, } from "./evidence.js";
 import { base64UrlToBytes, bytesToHex, ed25519PublicKey, ed25519Sign, sha256Hex, utf8, } from "./crypto.js";
-import { jcs } from "./verifier.js";
+import { isRfc3339UtcInstant, jcs } from "./verifier.js";
 const GENESIS = "GENESIS";
 const EXPORT_SCHEMA = EXPORT_BODY_TYPE;
 // Transcode an attestation `signature` to the lowercase hex §2.2 mandates. The
@@ -73,6 +73,11 @@ export async function composeExport(sourceBundle, attestations, exporterKey, opt
     if (typeof exporterKey?.privateKey !== "string" || exporterKey.privateKey.length === 0) {
         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";

package/dist/evidence.d.ts

@@ -318,6 +318,7 @@ export interface EvidenceBundleResult {
     export?: ExportResult;
     stamps?: StampResult[];
     errors: string[];
+    notes?: string[];
 }
 export interface AttestationRecord {
     /** The source checkpoint's derived `checkpoint_ref` this attestation binds to. */
@@ -427,6 +428,41 @@ export interface VerifyEvidenceOptions {
     content?: Record<string, Uint8Array | string> | ReadonlyMap<string, Uint8Array | string>;
     fetchImpl?: typeof fetch;
 }
+/**
+ * A surface MUST NOT present a wrapper's `co_signatures` as evidence
+ * (evidence-bundle.md §2, decided by Phil 2026-09-24 on proof#148): nothing
+ * in either kernel verifies the field, and it sits outside the wrapper's
+ * signed scope (`bundleForSig` below), so anyone holding a pack's bytes can
+ * append it with no key at all. This is the one sentence both kernels attach
+ * as a note, never a verdict, never an exit code.
+ */
+export declare const CO_SIGNATURES_NOTE = "unverified co-signatures are present in this pack's wrapper and are not part of the evidence";
+/**
+ * True iff the wrapper's reserved `co_signatures` field carries at least one
+ * entry.
+ *
+ * Absence and an empty array read the same way here: the field asserts
+ * nothing about a second signer until it holds one, and evidence-bundle.md's
+ * own carve-out language for the analogous envelope field treats "absent"
+ * and "an empty array" as one thing (envelope-spec.md §7.1). A non-array
+ * value (malformed shape, but the field is reserved, not yet specified)
+ * still counts as present: it is not the well-formed absence either rule
+ * describes.
+ */
+export declare function coSignaturesPresent(b: unknown): boolean;
+/**
+ * A bundle this kernel cannot read.
+ *
+ * `wrapperOk` is true only where the wrapper signature and `body_hash` were
+ * CHECKED and held before the body was found unreadable. It is then reported
+ * as held, because it did: `signatureOk` and `bodyHashOk` are statements about
+ * the wrapper, and a body this kernel cannot parse does not unsign it. The
+ * case reader decides whose pack a bundle is on exactly those two fields
+ * (`evidence-bundle.md` 5.5.1), so reporting `false` here let a holder who
+ * broke its own body shape read as a forger.
+ */
+/** evidence-bundle §2 (A31). Byte-identical to the Python kernel's. */
+export declare const GENERATED_AT_MALFORMED = "malformed generated_at: not an RFC 3339 UTC date-time with Z naming a real date and time (evidence-bundle \u00A72)";
 export declare function verifyEvidenceBundle(bundle: unknown, options?: VerifyEvidenceOptions): Promise<EvidenceBundleResult>;
 export type DisclosureStatus = "verified" | "not_disclosed" | "undetermined" | "failed";
 export interface DisclosedEventContent {