@sanning/proof 0.13.0 → 0.15.0

package/src/witness-lookup.ts

@@ -0,0 +1,428 @@
+// The public-record (witness) lookup the CLI runs with `--gateways`
+// (evidence-bundle.md §5.5.6, v1.20, A24, D7): re-fetch each pack's witness on
+// the public record and report what it said. Moved here from `cli.ts`
+// (proof#200) so the CLI and a consumer that is not the CLI, the verify page,
+// a browser app, call the SAME implementation rather than each keeping its
+// own copy that can drift.
+//
+// Pure by the kernel's own rule (specs/architecture.md §3): the network call
+// is the one exception this module exists to hold, and it never runs unless a
+// caller hands in a gateway to ask. `options.fetchImpl` is the seam: where a
+// caller supplies one (a browser page's own `fetch`, or a test's fake), that
+// is the ONE this module calls; where none is given, it falls back to the
+// ambient global `fetch`, the same fallback `cli.ts` already applied at its
+// own call site before this module existed.
+//
+// `onChainHalf` and `witnessLine` are the CLI's own building blocks,
+// UNCHANGED (proof#200 is additive: the CLI's `case` output and exit codes are
+// byte-for-byte what they were). `lookupPublicRecord` is the new export:
+// one pack (or several) in, one four-state result out, with a pack's
+// `witness-cache.json` read as part of the pack rather than as a side file a
+// caller must remember to also pass in.
+
+import { verifyEvidenceBundle } from "./evidence.js";
+import type { WitnessLine, WitnessState } from "./case.js";
+import { WITNESS_NOT_LOOKED_UP, renderWitnessLine } from "./case.js";
+import {
+  type CachedWitnessTime,
+  type WitnessTimeAnswer,
+  type WitnessTimeCheck,
+  checkWitnessCache,
+  readWitnessCache,
+  renderWitnessTime,
+} from "./witness-cache.js";
+
+/** The seam every network call in this module goes through: used where given, else the ambient global `fetch`. */
+export interface WitnessLookupOptions {
+  fetchImpl?: typeof fetch;
+}
+
+export interface OnChainRow {
+  ref: string;
+  witnesses: number;
+  confirmed: number;
+  mismatched: number;
+  unreachable: number;
+  not_checked: number;
+  /** Present only where the pack caches a witness time (5.6.6, v1.25, A30). */
+  witness_times?: WitnessTimeRow[];
+}
+
+export interface WitnessTimeRow {
+  stamp_ref: string;
+  cached: { block_height: number; block_time: number };
+  outcome: WitnessTimeCheck["outcome"];
+  answers: {
+    gateway: string;
+    outcome: WitnessTimeAnswer["outcome"];
+    block_height: number | null;
+    block_time: number | null;
+  }[];
+}
+
+function witnessTimeRow(t: WitnessTimeCheck): WitnessTimeRow {
+  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,
+    })),
+  };
+}
+
+export 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.
+ *
+ * Moved from `cli.ts` unchanged, apart from taking `fetchImpl` directly
+ * instead of a `Cli` stream (`io.fetchImpl ?? fetch`, the same fallback the
+ * CLI already applied at its own call site).
+ */
+export async function onChainHalf(
+  packs: readonly (readonly [string, unknown, readonly CachedWitnessTime[]])[],
+  gateways: readonly string[],
+  options: WitnessLookupOptions = {},
+): Promise<OnChainHalf> {
+  if (gateways.length === 0) return { checked: false, gateways: [], packs: [], verdict: "not_checked" };
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const rows: OnChainRow[] = [];
+  const answered = new Set<string>();
+  for (const [ref, bundle, cached] of packs) {
+    const result = await verifyEvidenceBundle(bundle, { gateways: [...gateways], 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++;
+    }
+    // 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, fetchImpl);
+    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 ?? []) {
+        if (outcome.outcome === "confirm" || outcome.outcome === "mismatch") {
+          answered.add(outcome.gateway);
+        }
+      }
+    }
+    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 || (r.witness_times ?? []).some((t) => t.outcome === "differs"),
+  )
+    ? "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,
+  };
+}
+
+// Distinct `[blockHeight, blockTime]` pairs, in time order.
+function distinctTimes(times: Iterable<[number, number]>): [number, number][] {
+  const seen = new Map<string, [number, number]>();
+  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: WitnessLine,
+  cached: [number, number][],
+  recorded: [number, number][],
+): WitnessLine {
+  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`.
+ *
+ * Moved from `cli.ts` unchanged: same inputs, same three states
+ * (`WitnessState`), same rendering. The CLI's `case` command still calls this
+ * exact function, so its witness line is unchanged.
+ */
+export function witnessLine(onChain: OnChainHalf, cached: readonly CachedWitnessTime[] = []): WitnessLine {
+  if (!onChain.checked) {
+    return withTimes(
+      {
+        state: WITNESS_NOT_LOOKED_UP.state,
+        reasons: [...WITNESS_NOT_LOOKED_UP.reasons],
+        services: [...WITNESS_NOT_LOOKED_UP.services],
+      },
+      distinctTimes(cached.map((c): [number, number] => [c.blockHeight, c.blockTime])),
+      [],
+    );
+  }
+  const services = [...(onChain.answered ?? [])];
+  const rows = onChain.packs;
+  const times = rows.flatMap((r) => r.witness_times ?? []);
+  const unsettled = distinctTimes(
+    times
+      .filter((t) => t.outcome === "not_checked")
+      .map((t): [number, number] => [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): [number, number] => [a.block_height as number, a.block_time as number]),
+  );
+  const contradicted: string[] = [];
+  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 as number, a.block_time as number)}`;
+    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: 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 withTimes({ state: "not_checked", reasons, services }, unsettled, recorded);
+}
+
+// ─── The public-entry-point export (proof#200) ─────────────────────────────
+//
+// `onChainHalf` and `witnessLine` above are the CLI's own two-step shape:
+// gateways in, an `OnChainHalf` (every row, every gateway) out, then a
+// `WitnessLine` (three states: `confirmed`, `not_checked`, `differs`) rendered
+// from it. A second caller, the verify page, does not want the CLI's
+// internal row shape and does want a fourth state the CLI's three-state
+// `WitnessLine` cannot name: a pack that carries NO witness at all yet is not
+// "not checked" (a lookup that could have found something and didn't), it is
+// "there is nothing on the public record to check". Folding that pack into
+// `not_checked` is not wrong for the CLI (`case` already says so in the
+// reason text: "a pack names no witness"), but a tag that only ever reads
+// "Not checked" hides the one distinction an auditor most wants: did we look
+// and find nothing, or is there nothing to look for yet.
+//
+// `lookupPublicRecord` is additive over the two functions above: it calls
+// them, never reimplements them, so there is exactly one place the network
+// call and the verdict arithmetic live. It never throws: the underlying
+// primitives (`verifyEvidenceBundle`, `checkWitnessCache`) already treat a
+// gateway's answer as untrusted input and report `unreachable`/`differs`
+// rather than raise, and this function adds no new path to the network or the
+// parser.
+
+/** The four states this export's result can carry. The CLI's own `WitnessState` plus `no_public_record`. */
+export type PublicRecordState = WitnessState | "no_public_record";
+
+/**
+ * One pack, as this lookup needs it: the parsed `bundle.json` and, where the
+ * pack carries one, the RAW BYTES of its `witness-cache.json`, read as part
+ * of the pack, per proof#200's acceptance criteria, rather than as a
+ * separately-loaded side file. `null` and `undefined` both mean "this pack has
+ * no witness-cache.json", the same reading `readWitnessCache` gives a missing
+ * file.
+ */
+export interface PublicRecordPack {
+  /** How this pack is named in the result; carries no meaning beyond that. */
+  ref: string;
+  bundle: unknown;
+  witnessCache?: Uint8Array | null;
+}
+
+export interface PublicRecordResult {
+  state: PublicRecordState;
+  reasons: string[];
+  services: string[];
+  /** Witness times a pack caches that no lookup settled (5.6.6, v1.25, A30). */
+  cached?: [number, number][];
+  /** Witness times the public record returned that matched a pack's cache. */
+  recorded?: [number, number][];
+  /** The line as both the CLI and a page print it, one string, kernel words. */
+  rendered: string;
+}
+
+/**
+ * The public-record lookup the CLI runs with `--gateways`, exported so a
+ * consumer that is not the CLI can run the SAME lookup rather than copy it
+ * (proof#200; the copy this closes is verify-page#70's `src/lib/verify.ts`).
+ *
+ * `packs` is every pack in the drop being read; `gateways` is empty for an
+ * offline reading, which never makes a network call and always answers
+ * `not_checked` or `no_public_record`. `options.fetchImpl` is the one seam a
+ * network call goes through, a browser page supplies its own `fetchImpl`;
+ * with none given this falls back to the ambient global `fetch`, so a
+ * browser page and a test can each supply their own and Node's `fetch` is
+ * never assumed where a caller passed something else.
+ *
+ * `state` is `confirmed` only about the BYTES: the public record holds what a
+ * pack names. It says nothing about whether the pack itself verifies (its
+ * wrapper signature, its `body_hash`), and a caller must never show
+ * `confirmed` apart from the pack's own verdict (proof#201).
+ *
+ * Never throws. Every input, including a malformed pack, a non-string
+ * gateway, or a `fetchImpl` that itself misbehaves, is read as untrusted, and
+ * anything this function or what it calls cannot make sense of settles as
+ * `not_checked` rather than escape as an exception.
+ */
+export async function lookupPublicRecord(
+  packs: readonly PublicRecordPack[],
+  gateways: readonly string[],
+  options: WitnessLookupOptions = {},
+): Promise<PublicRecordResult> {
+  try {
+    // Nothing to look up: zero packs means the CALLER handed in nothing to
+    // check, which is not the same claim as "the packs it handed in name no
+    // witness" (`no_public_record`, below). Checked first, and unconditionally,
+    // so a caller than mishandles an empty drop never reads it as confirmed.
+    if (packs.length === 0) {
+      const reasons = [...WITNESS_NOT_LOOKED_UP.reasons];
+      return {
+        state: "not_checked",
+        reasons,
+        services: [],
+        rendered: renderWitnessLine({ state: "not_checked", reasons, services: [] }),
+      };
+    }
+
+    const caches = packs.map((p) => readWitnessCache(p.bundle, p.witnessCache ?? null));
+    const rows: [string, unknown, readonly CachedWitnessTime[]][] = packs.map((p, i) => [
+      p.ref,
+      p.bundle,
+      caches[i]!,
+    ]);
+    const onChain = await onChainHalfForWitnessCount(rows, gateways, options);
+    const line = witnessLine(onChain.half, caches.flat());
+
+    // "No public record yet": every pack this lookup was handed names ZERO
+    // witnesses, so there is nothing the public record could confirm or
+    // contradict. This holds independently of whether a lookup ran, an
+    // offline reading of a fresh, unstamped pack is exactly as much "nothing to
+    // check yet" as an online one, and it is computed from the SAME witness
+    // count `onChainHalf` derives from `verifyEvidenceBundle`'s own parse, never
+    // a second reading of the bundle.
+    //
+    // A pack that does NOT verify (a broken wrapper signature, `bundle: null`,
+    // garbage, an unrecognised body type) also names zero witnesses, by
+    // construction: `verifyEvidenceBundle` never reports a checkpoint or a
+    // stamp for a bundle it could not authenticate. That is not "nothing to
+    // check yet", it is a pack this lookup could not read, so `no_public_record`
+    // is reserved for a pack whose wrapper genuinely verifies
+    // (`signatureOk && bodyHashOk && status !== "failed"`) and that carries no
+    // cached witness time either (a cache entry names something to check).
+    // Anything else that would otherwise qualify reads `not_checked` instead.
+    const noWitnesses = onChain.witnessCounts.every((n) => n === 0);
+    const everyPackVerifies = onChain.verifies.every((v) => v);
+    const noCacheRead = caches.every((c) => c.length === 0);
+    const canBeNoPublicRecord = noWitnesses && everyPackVerifies && noCacheRead;
+    const state: PublicRecordState =
+      line.state === "not_checked" && canBeNoPublicRecord ? "no_public_record" : line.state;
+
+    return {
+      state,
+      reasons: line.reasons,
+      services: line.services,
+      ...(line.cached ? { cached: line.cached } : {}),
+      // `recorded` is a claim about the public record confirming a cached
+      // time; it never rides alongside anything but a `confirmed` verdict, so
+      // a pack whose wrapper does not verify can never surface a cached time
+      // as though the record had confirmed it.
+      ...(state === "confirmed" && line.recorded ? { recorded: line.recorded } : {}),
+      rendered: renderWitnessLine({ ...line, state: state === "no_public_record" ? "not_checked" : state }),
+    };
+  } catch (e) {
+    // Untrusted input all the way down: a gateway's answer, a pack's shape, a
+    // caller's `fetchImpl`. Anything this function or what it calls cannot
+    // make sense of settles `not_checked` rather than throw out of an export a
+    // browser page calls directly.
+    const reason =
+      e instanceof Error ? `the lookup did not settle: ${e.message}` : "the lookup did not settle";
+    const reasons = [reason];
+    return {
+      state: "not_checked",
+      reasons,
+      services: [],
+      rendered: renderWitnessLine({ state: "not_checked", reasons, services: [] }),
+    };
+  }
+}
+
+// `onChainHalf` short-circuits to `{ checked: false, packs: [] }` with no
+// gateways, which is right for the CLI (nothing to print per pack) but leaves
+// `lookupPublicRecord` unable to tell "no gateways" from "no witnesses" for an
+// OFFLINE reading. This wrapper reads each pack's witness count, and whether
+// its wrapper verifies, the same way `onChainHalf` does, via
+// `verifyEvidenceBundle`: an OFFLINE parse (`gateways: []`), so it costs no
+// extra request whether or not a lookup runs, and `verifies` is never itself
+// a statement about the public record, only about the pack's own signature
+// and `body_hash`.
+async function onChainHalfForWitnessCount(
+  packs: readonly (readonly [string, unknown, readonly CachedWitnessTime[]])[],
+  gateways: readonly string[],
+  options: WitnessLookupOptions,
+): Promise<{ half: OnChainHalf; witnessCounts: number[]; verifies: boolean[] }> {
+  const witnessCounts: number[] = [];
+  const verifies: boolean[] = [];
+  for (const [, bundle] of packs) {
+    const result = await verifyEvidenceBundle(bundle, { gateways: [] });
+    witnessCounts.push(result.checkpoints.length + (result.stamps?.length ?? 0));
+    verifies.push(result.signatureOk && result.bodyHashOk && result.status !== "failed");
+  }
+  if (gateways.length > 0) {
+    const half = await onChainHalf(packs, gateways, options);
+    return { half, witnessCounts, verifies };
+  }
+  return { half: { checked: false, gateways: [], packs: [], verdict: "not_checked" }, witnessCounts, verifies };
+}

package/vectors/README.md

@@ -26,12 +26,33 @@ on a run that contacted none — a false accusation manufactured by a missing
 state, and the defect this table was written after. Vendoring rules are the same
 three steps as below, against `vectors/stamp-on-chain.json`.
 
+## `witness-cache.json`
+
+The rule that decides what a reader does with the witnessed-time cache, the
+unsigned `witness-cache.json` beside a pack's `bundle.json` (`evidence-bundle.md`
+§5.5.6 and §5.6.6, v1.25, A30). Implemented by [`../src/witness-cache.ts`](../src/witness-cache.ts)
+and the `case` command in [`../src/cli.ts`](../src/cli.ts), and asserted against
+this table by
+[`../test/witness-cache-vectors.test.ts`](../test/witness-cache-vectors.test.ts)
+**and by the Python kernel against the same bytes**, in
+`tests/test_witness_cache_vectors.py`. Every expectation is written by hand in
+`tools/gen-vectors/gen_witness_cache_table.py`, which writes this file.
+
+**The one thing a consumer must not do with it: print a cached time as
+anything but not checked.** Nobody signs the file, and anyone holding the pack
+can write it. The only time a surface may print as the public record's is one a
+gateway returned; a cached time the record contradicts is a finding, and one no
+lookup settled stays labelled not checked.
+
 ## `jcs-reader.json`
 
 The rule that decides how a kernel reads bytes that claim to be `JCS(value)`
-(RFC 8785). Four checks, none of them left to a built-in decoder's defaults:
-**strict UTF-8**, **no leading byte-order mark**, **no non-finite literal**, and
-**no unpaired surrogate in the parsed value**. The fourth is not the first one
+(RFC 8785). Five checks, none of them left to a built-in decoder's defaults:
+**strict UTF-8**, **no leading byte-order mark**, **no non-finite literal**,
+**no object that names one member twice** (I-JSON, RFC 7493; rule version 3,
+proof#144), and **no unpaired surrogate in the parsed value**. A duplicate is
+refused with the same message in both kernels, `duplicate key "<name>"`, and a
+case that carries `error` pins that exact string. The fourth is not the first one
 twice: a surrogate written as the ASCII escape `\ud800` survives every
 byte-level check, because the bytes are ASCII, and the parser produces the
 malformed code unit afterwards (proof#154).
@@ -135,6 +156,25 @@ whoever assembled the drop. Written by
 `tools/gen-vectors/gen_case_file_index_vectors.py`, whose expectations are
 literals.
 
+## `file-match.json`
+
+How a reader matches files handed in beside a pack against the commitments its
+signed records make (`evidence-bundle.md` §5.7, v1.24 A29, proof#92). One pure
+reading in both kernels, `matchFiles` and `matchCaseFiles` in
+[`../src/file-match.ts`](../src/file-match.ts) and `match_files` and
+`match_case_files` in `src/sanning_proof/file_match.py`, asserted against this
+table by [`../test/file-match.test.ts`](../test/file-match.test.ts) **and by the
+Python kernel against the same bytes**, in `tests/test_file_match.py`. `packs`
+holds real signed packs, keyed by name, with any side content beside them as
+`content_hex`; each row names the packs it reads (one for `mode: pack`, several
+for `mode: case`), the files it offers as names and bytes, and the reading it
+expects, with each `not_read` entry's rendered line left out. **A file is
+matched by its SHA-256 and by nothing else**, and **no match moves a verdict**:
+a surface that matched by name, or took a hash from a field no record's key
+signed, would vouch for a file the pack never committed to. Written by
+`tools/gen-vectors/gen_file_match_vectors.py`, whose expectations are written
+by hand from what it built.
+
 ## `case-split.json`
 
 How `case` turns the folders it was handed into packs: the verify page's