@sanning/proof 0.13.0 → 0.15.0

package/src/index.ts

@@ -62,10 +62,12 @@ export type { ContentRole, Envelope, Subject, VerificationResult, VerifyOptions
 export {
   ACCEPTED_EVIDENCE_MAJORS,
   ANCHOR_TRACE_BODY_TYPE,
+  CO_SIGNATURES_NOTE,
   EXPORT_BODY_TYPE,
   STAMP_BODY_VERSION,
   STAMP_TRACE_BODY_TYPE,
   STAMP_EVIDENCE_BODY_TYPE,
+  coSignaturesPresent,
   disclosedContent,
   recomputeExportVerdict,
   verifyEvidenceBundle,
@@ -219,17 +221,61 @@ export {
   CASE_RECORD_PROFILES,
   CASE_NOTE_KINDS,
   CASE_RELIANCE,
+  CASE_RELIANCE_HANDOFF_CLAUSE,
   CASE_VERDICTS,
   CONTENT_WITHHELD_BY_DECLARATION,
+  CO_SIGNATURES_PRESENT,
   VERDICT_DISPLAY_TITLES,
   WITNESS_NOT_LOOKED_UP,
   WITNESS_STATES,
+  WITNESS_TIME_CACHED,
+  WITNESS_TIME_RECORDED,
+  caseReliance,
   readCase,
   renderCaseNote,
   renderCaseSummary,
   renderException,
   renderWitnessLine,
 } from "./case.js";
+// The witnessed-time cache (evidence-bundle 5.6.6, v1.25, A30): read it, look it
+// up, print it. Never an input to a verdict.
+export {
+  MAX_BLOCK_TIME,
+  MAX_WITNESS_CACHE_DEPTH,
+  WITNESS_CACHE_NAME,
+  WITNESS_CACHE_VERSION,
+  checkWitnessCache,
+  formatBlockTime,
+  readWitnessCache,
+  renderWitnessTime,
+  witnessTimeQuery,
+} from "./witness-cache.js";
+export type { CachedWitnessTime, WitnessTimeAnswer, WitnessTimeCheck } from "./witness-cache.js";
+
+// The public-record (witness) lookup the CLI runs with `--gateways`
+// (src/witness-lookup.ts, proof#200): moved out of the CLI so a consumer
+// that is not the CLI, the verify page, calls the SAME implementation
+// rather than keeping its own copy (verify-page#70). Pure kernel scope: the
+// one network call lives in `lookupPublicRecord` and `onChainHalf`, runs
+// only when a caller hands in a gateway, and goes through `options.fetchImpl`
+// where a caller supplies one (a browser page's own `fetch`) or the ambient
+// global `fetch` otherwise, so this export runs in a browser exactly as it
+// runs in Node. `onChainHalf` and `witnessLine` are the CLI's own unchanged
+// building blocks; `lookupPublicRecord` is the new one-call, four-state entry
+// point a page wants, additive over both. `confirmed` from
+// `lookupPublicRecord` is a claim about the BYTES only, never about whether
+// the pack itself verifies, and a caller must never show it apart from the
+// pack's own verdict.
+export { lookupPublicRecord, onChainHalf, witnessLine } from "./witness-lookup.js";
+export type {
+  OnChainHalf,
+  OnChainRow,
+  PublicRecordPack,
+  PublicRecordResult,
+  PublicRecordState,
+  WitnessLookupOptions,
+  WitnessTimeRow,
+} from "./witness-lookup.js";
 export type {
   CaseException,
   CaseExceptionKind,
@@ -264,6 +310,28 @@ export type {
   CaseFileIndexReading,
 } from "./case-file.js";
 
+// Files handed in beside a pack (src/file-match.ts, evidence-bundle.md §5.7,
+// A29, proof#92): each file's SHA-256 matched against the commitments the
+// pack's SIGNED records make, by hash alone. Never moves a verdict.
+export {
+  FILE_MATCH_SCOPE,
+  NOT_READ_REASONS,
+  fileMatchToJson,
+  matchCaseFiles,
+  matchFiles,
+  renderFileMatch,
+} from "./file-match.js";
+export type {
+  FileCommitment,
+  FileMatchPack,
+  FileMatchReading,
+  MatchedFile,
+  NotRead,
+  NotReadReason,
+  OfferedFile,
+  UnmatchedFile,
+} from "./file-match.js";
+
 // Chain reading (src/chain.ts): following the pointer every sanning.events/v2
 // record carries to the record before it, over the records ONE bundle presents.
 //

package/src/message-parts.ts

@@ -278,12 +278,18 @@ const HELD_UNCHECKED_RESULTS: readonly string[] = [
 
 /**
  * The keys that make a part carry its content INLINE, in the order they are
- * read. Named rather than inferred: `bytes`, `data` and `content` are the
- * spellings in the wild. None is A2A 1.0.0's: its `Part` has no `kind` and
+ * read. Settled at `bytes` alone (envelope-spec §4.1, A31, proof#163): that
+ * is A2A's spelling, the one the wedge actually emits, and it is the only
+ * inline spelling either reference kernel has read from a real producer.
+ * `content` and `data` were added on inference rather than on an observed
+ * wire shape, and sanning-io/anchor's `filePart()` and `file_part()` SDK
+ * helpers, the only producer this plane ships, confirm the inference was
+ * wrong: both emit a descriptor part, `kind: "file"` plus `content_hash` and
+ * `content_length`, and neither ever writes a `content` or `data` wire key
+ * for inline bytes. None is A2A 1.0.0's either: its `Part` has no `kind` and
  * carries a file as `raw` or `url`, so a literal A2A part reads
- * `part_not_a_file` (envelope-spec §4.1, A19). The FIRST of them present with
- * a value that is not `null` is the inline content, so a part spelling it
- * twice reads one way in both kernels.
+ * `part_not_a_file` (envelope-spec §4.1, A19). The one key present with a
+ * value that is not `null` is the inline content.
  *
  * A key present with `null` is an ABSENT inline value, on A14's ruling that an
  * absent value and one written as `null` name one thing. That matters: a
@@ -292,11 +298,13 @@ const HELD_UNCHECKED_RESULTS: readonly string[] = [
  * (proof#156 gate). Such a part falls through to the descriptor rule, which is
  * what it is.
  */
-// A conformant DESCRIPTOR part that also carries a `content` or `data` key
-// meaning something else (a filename, a metadata blob) is reclassified by this
-// list and never checked against supplied bytes. That is inside section 4.1's
-// stated rule, and whether these parts ought to fall into it is proof#163.
-export const INLINE_BYTES_KEYS = ["bytes", "content", "data"] as const;
+// Before A31 this list also carried `content` and `data`, and a conformant
+// DESCRIPTOR part that happened to carry either key meaning something else (a
+// filename, a caption) was silently reclassified as inline and never checked
+// against supplied bytes: the swapped-bytes check A18 exists to run
+// (proof#145) never ran on it. proof#163 is resolved by narrowing to `bytes`
+// alone, closing that gap.
+export const INLINE_BYTES_KEYS = ["bytes"] as const;
 
 const HEX64 = /^[0-9a-fA-F]{64}$/;
 const HEX_CHARSET = /^[0-9a-fA-F]+$/;

package/src/verifier.ts

@@ -201,11 +201,13 @@ const JCS_BOM = "";
  * twin is `jcs_loads` in `src/sanning_proof/canonicalize.py`, and every site in
  * either kernel that reads bytes a producer signed goes through one of the two.
  *
- * ONE RULE, SPELLED OUT, BECAUSE TWO BUILT-INS ARE NOT ONE RULE. Four checks
+ * ONE RULE, SPELLED OUT, BECAUSE TWO BUILT-INS ARE NOT ONE RULE. Five checks
  * carry it, none of them left to a decoder's defaults: strict UTF-8, no leading
  * byte-order mark, no non-finite literal (this kernel's `JSON.parse` rejects
  * `NaN`, `Infinity` and `-Infinity` natively, and Python names them in a
- * `parse_constant` hook), and no unpaired surrogate in the parsed value.
+ * `parse_constant` hook), no object that repeats a member name
+ * (`DuplicateKeyError`, proof#144), and no unpaired surrogate in the parsed
+ * value.
  *
  * THE FOURTH CHECK IS NOT THE FIRST ONE TWICE. The strict decode refuses a
  * surrogate written as raw bytes; it cannot see one written as the ASCII
@@ -244,11 +246,130 @@ export function utf8Strict(bytes: Uint8Array): string {
 export function jcsParse(bytes: Uint8Array): unknown {
   const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
   if (text.startsWith(JCS_BOM)) throw new Error("jcsParse: leading byte-order mark");
-  const value: unknown = JSON.parse(text);
+  const value: unknown = parseRefusingDuplicates(text);
   rejectUnpairedSurrogates(value);
   return value;
 }
 
+/**
+ * A JSON object that names one member twice (I-JSON, RFC 7493 section 2.3).
+ * The Python twin is `DuplicateKey` in `canonicalize.py`, and the message is
+ * the same kernel wording in both: `duplicate key ` and the name as
+ * `renderKey` spells it.
+ *
+ * JCS (RFC 8785) is defined over I-JSON, and I-JSON forbids duplicate member
+ * names, so bytes that repeat a name are MALFORMED rather than another spelling
+ * of the last value. `JSON.parse` and Python's `json.loads` both keep the last
+ * value and say nothing, which let a bundle carrying `"spec_version":"junk"`
+ * before its real `spec_version` read `verified` in both kernels (proof#144).
+ */
+export class DuplicateKeyError extends Error {
+  readonly key: string;
+  constructor(key: string) {
+    super(`duplicate key ${renderKey(key)}`);
+    this.key = key;
+  }
+}
+
+// The longest rendered name a message carries, in characters, before it is
+// cut. The rendering is pure ASCII, so the cut lands on the same character in
+// both kernels.
+const RENDERED_KEY_MAX = 64;
+
+/**
+ * A member name as a quoted, pure-ASCII string, identically in both kernels
+ * (`render_key` in the Python twin). Printable ASCII other than `"` and `\` is
+ * kept; `"` and `\` are backslash-escaped; every other UTF-16 code unit is
+ * `\uXXXX` in lower-case hex. A rendering longer than 64 characters is cut
+ * there and `...` follows the closing quote.
+ */
+export function renderKey(key: string): string {
+  let body = "";
+  for (let i = 0; i < key.length; i++) {
+    const c = key.charCodeAt(i);
+    const ch = key[i]!;
+    if (ch === '"' || ch === "\\") body += "\\" + ch;
+    else if (c >= 0x20 && c <= 0x7e) body += ch;
+    else body += "\\u" + c.toString(16).padStart(4, "0");
+  }
+  if (body.length > RENDERED_KEY_MAX) return `"${body.slice(0, RENDERED_KEY_MAX)}"...`;
+  return `"${body}"`;
+}
+
+/**
+ * `JSON.parse(text)`, refusing an object that repeats a member name. The Python
+ * twin is `loads_refusing_duplicates` in `canonicalize.py`.
+ *
+ * `JSON.parse` cannot see a repeat, because it keeps the last value, so the
+ * text is scanned once more AFTER it parsed. The parse runs first, so text
+ * that is not JSON at all fails as JSON and never as a duplicate, as it does in
+ * the Python twin. Throws `DuplicateKeyError`.
+ */
+export function parseRefusingDuplicates(text: string): unknown {
+  const value: unknown = JSON.parse(text);
+  const dup = firstDuplicateKey(text);
+  if (dup !== undefined) throw new DuplicateKeyError(dup);
+  return value;
+}
+
+/**
+ * The repeated member name to report for text `JSON.parse` has already
+ * accepted, or `undefined` when no object repeats one.
+ *
+ * WHICH ONE, because both kernels must name the same one. Objects are checked
+ * as they CLOSE, innermost first, which is the order Python's
+ * `object_pairs_hook` sees them in; inside one object the name reported is the
+ * first whose repeat comes earliest. Names compare after unescaping, so `"a"`
+ * and `"\u0061"` are one name, as they are to both parsers.
+ *
+ * ITERATIVE, with an explicit stack, for the reason `rejectUnpairedSurrogates`
+ * is: this walks bytes a producer wrote. It relies on the text being valid
+ * JSON, which is why it runs only after `JSON.parse` succeeded: outside a
+ * string, only `{`, `[`, `}`, `]`, `,` and `"` change what comes next.
+ */
+export function firstDuplicateKey(text: string): string | undefined {
+  // `names` is null for an array. `expectName` is true where the next string
+  // is a member name rather than a value.
+  const stack: Array<{ names: Set<string> | null; expectName: boolean; dup?: string }> = [];
+  const n = text.length;
+  let i = 0;
+  while (i < n) {
+    const c = text.charCodeAt(i);
+    if (c === 0x22) {
+      let j = i + 1;
+      for (;;) {
+        const d = text.charCodeAt(j);
+        if (d === 0x5c) j += 2;
+        else if (d === 0x22) break;
+        else j++;
+      }
+      const top = stack[stack.length - 1];
+      if (top !== undefined && top.names !== null && top.expectName) {
+        const name = JSON.parse(text.slice(i, j + 1)) as string;
+        if (top.names.has(name)) {
+          if (top.dup === undefined) top.dup = name;
+        } else {
+          top.names.add(name);
+        }
+        top.expectName = false;
+      }
+      i = j + 1;
+      continue;
+    }
+    if (c === 0x7b) stack.push({ names: new Set(), expectName: true });
+    else if (c === 0x5b) stack.push({ names: null, expectName: false });
+    else if (c === 0x7d || c === 0x5d) {
+      const closed = stack.pop();
+      if (closed?.dup !== undefined) return closed.dup;
+    } else if (c === 0x2c) {
+      const top = stack[stack.length - 1];
+      if (top !== undefined && top.names !== null) top.expectName = true;
+    }
+    i++;
+  }
+  return undefined;
+}
+
 /**
  * Refuse a parsed value carrying an unpaired surrogate, in a key or a value, at
  * any depth. The Python twin is `_reject_unpaired_surrogates`, and the two name
@@ -410,9 +531,75 @@ function skeletonFieldErrors(env: Envelope): string[] {
   if (environment !== undefined && environment !== "dev" && environment !== "production") {
     out.push('malformed environment: not "dev" or "production" (envelope-spec §2)');
   }
+  out.push(...identityFieldErrors(own));
+  return out;
+}
+
+// The four fields envelope-spec §2 types and A23 pins (proof#97, proof#155).
+// Every pattern is anchored at both ends with no `m` flag, so `$` never matches
+// before a trailing newline, and uses ASCII classes only.
+//
+// `event_id`: "UUID v4, lowercase", the pattern both SDKs already refuse to
+// sign anything else under (`UUID_V4_RE` in `@sanning/anchor`, `_UUID_V4_RE` in
+// `sanning-anchor`); the Go agent's `uuid.NewString` emits the same.
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+// `payload_hash`: sha256-hex, which invariant 2 defines as lowercase hex with no
+// `0x`. Lower case is pinned here, unlike `public_key`, because every kernel
+// compares the value against a digest it recomputes in lower case: an
+// upper-case `payload_hash` already failed wherever there was material.
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+// `payload_ref`: §2 says "string (URI)" and names no grammar, so this pins what
+// both SDKs emit: an ASCII scheme, a colon, then RFC 3986 unreserved, reserved
+// and percent-encoded characters, at most 2048 of them in all (`REF_RE` and
+// `MAX_REF_LEN` in `@sanning/anchor`'s `ref.ts`).
+const URI_REF = /^[A-Za-z][A-Za-z0-9+.-]*:[A-Za-z0-9\-._~:/?#[\]@!$&'()*+,;=%]*$/;
+const MAX_URI_REF = 2048;
+// `subject`: "string fields <=128 chars matching `^[A-Za-z0-9_.:-]+$`".
+const SUBJECT_FIELD = /^[A-Za-z0-9_.:-]{1,128}$/;
+
+// `event_id`, `payload_hash`, `payload_ref` and `subject` (A23). Each is checked
+// only when present, and present includes a JSON null, as for `signed_at`.
+// `payload_hash` is the exception: only a STRING is checked here, because a
+// missing or non-string one is already `missing payload_hash` below, and naming
+// it twice would state one fact in two sets of words. `subject` fixes only its
+// STRING members: §2 types no other, so a member of another type is left as it
+// was. Own members only, as everywhere in this file. The messages are
+// byte-identical to the Python and Go kernels'.
+function identityFieldErrors(own: (k: string) => unknown): string[] {
+  const out: string[] = [];
+  const eventId = own("event_id");
+  if (eventId !== undefined && !(typeof eventId === "string" && UUID_V4.test(eventId))) {
+    out.push("malformed event_id: not a lowercase UUID v4 (envelope-spec §2)");
+  }
+  const payloadHash = own("payload_hash");
+  if (typeof payloadHash === "string" && !SHA256_HEX.test(payloadHash)) {
+    out.push("malformed payload_hash: not 64 lowercase hex characters (envelope-spec §2)");
+  }
+  const payloadRef = own("payload_ref");
+  if (
+    payloadRef !== undefined &&
+    !(typeof payloadRef === "string" && payloadRef.length <= MAX_URI_REF && URI_REF.test(payloadRef))
+  ) {
+    out.push("malformed payload_ref: not a URI of at most 2048 RFC 3986 characters (envelope-spec §2)");
+  }
+  const subject = own("subject");
+  if (subject !== undefined && !isWellFormedSubject(subject)) {
+    out.push(
+      "malformed subject: not an object whose string fields are 1 to 128 characters of [A-Za-z0-9_.:-] (envelope-spec §2)",
+    );
+  }
   return out;
 }
 
+function isWellFormedSubject(subject: unknown): boolean {
+  if (typeof subject !== "object" || subject === null || Array.isArray(subject)) return false;
+  for (const key of Object.keys(subject)) {
+    const v = (subject as Record<string, unknown>)[key];
+    if (typeof v === "string" && !SUBJECT_FIELD.test(v)) return false;
+  }
+  return true;
+}
+
 // The content hash(es) an envelope commits to, by event type — the values a
 // reverse lookup can match the user's in-browser file hash against.
 //   asset_registered -> payload.hash            (the registered, known-good bytes)

package/src/witness-cache.ts

@@ -0,0 +1,306 @@
+// The witnessed-time cache: what a pack remembers about its witness, unverified
+// (evidence-bundle.md 5.6.6, v1.25, A30, proof#24).
+//
+// The TypeScript half of `src/sanning_proof/witness_cache.py`. Both kernels are
+// held to one table, `ts/vectors/witness-cache.json`, so neither can pass by
+// agreeing with the other.
+//
+// WHAT THE CACHE IS. A file beside the pack's `bundle.json`,
+// `witness-cache.json`, and never a member of the bundle. Its one list today,
+// `witnessed`, gives for each stamp the block height and block time of the
+// witness transaction, as the builder of the pack fetched them. Nobody signs
+// it, and anyone holding the pack can edit it. EVERY MEMBER OF THE FILE IS
+// UNVERIFIED BY CONSTRUCTION, and the name carries that warning to every field
+// added to it later.
+//
+// Because it is a separate file, a reader before v1.25 never opens it: it lists
+// it as a file outside every pack and reads the pack exactly as it would
+// without it. A `cache` member written INSIDE `bundle.json` is an unknown
+// wrapper field, counted in the signed scope by every reader, this one
+// included.
+//
+// WHAT THIS MODULE DOES, AND WHAT IT MUST NEVER DO.
+//
+// - `readWitnessCache` reads the file's bytes against the signed bundle beside
+//   it. It is pure, and it is never an input to the bundle verdict, the pack
+//   grade or the case reading: neither `verifyEvidenceBundle` nor `readCase` is
+//   ever handed the file.
+// - `checkWitnessCache` looks each cached time up on the public record, where a
+//   caller asked for a lookup. A lookup that answers with a different block is
+//   a finding, reported on the witness line as `differs`. A lookup that does
+//   not settle leaves the cached value labelled not checked.
+// - Nothing here returns a time a reader may rely on. The only time this module
+//   ever reports as the public record's is one a gateway returned, and a
+//   gateway is named, never trusted (6).
+//
+// A file that is absent, that is not JSON under the reader's rule, whose
+// `cache_version` is not `WITNESS_CACHE_VERSION`, whose `witnessed` is not a
+// list, or whose entry is not well formed, reads as no cache for what it could
+// not say. It is never a finding and never moves anything.
+
+import { jsonDepthExceeds } from "./case-file.js";
+import { jcs, jcsParse } from "./verifier.js";
+
+/**
+ * The last second a block time can name and still be printed the same way by
+ * both kernels: 9999-12-31T23:59:59Z. A larger value is a cache entry this
+ * reader cannot print, and reads as none.
+ */
+export const MAX_BLOCK_TIME = 253402300799;
+
+/** The file's name, beside `bundle.json` in the pack's folder (5.6.1). */
+export const WITNESS_CACHE_NAME = "witness-cache.json";
+
+/**
+ * The dispatch key: a file whose `cache_version` is absent or any other value
+ * reads as no cache.
+ */
+export const WITNESS_CACHE_VERSION = "sanning.witness-cache/v1";
+
+/**
+ * How deep `[` and `{` may nest in the file before it is refused unread: the
+ * limit `bundle.json` and `contents.json` are read under.
+ */
+export const MAX_WITNESS_CACHE_DEPTH = 512;
+
+// The bodies that carry `stamps[]`, the only witnesses the cache speaks for.
+const STAMP_BODIES = new Set(["sanning.stamp.trace/v1", "sanning.stamp.evidence/v2"]);
+const STAMP_REF = /^[0-9a-f]{64}$/;
+// The one witness kind a time is looked up for, and the only ids the lookup
+// sends: the same rule the byte lookup applies (evidence-bundle 5.1.1, v1.6).
+const ADAPTER_KIND = "arweave";
+const ARWEAVE_ID = /^[A-Za-z0-9_-]{43}$/;
+// A GraphQL answer to one query for one transaction is a few hundred bytes. A
+// deeper answer is not one, and refusing it before any parser recurses keeps
+// the two kernels on one reading of it.
+const MAX_ANSWER_DEPTH = 16;
+
+/**
+ * One `cache.witnessed[]` entry that reads, joined to the stamp it names.
+ * `witnessKind` and `witnessId` are the stamp's own `anchor_ref`, read from the
+ * signed body, never from the cache: the cache says WHEN, and the body alone
+ * says WHICH witness it is about.
+ */
+export interface CachedWitnessTime {
+  stampRef: string;
+  blockHeight: number;
+  blockTime: number;
+  witnessKind: string;
+  witnessId: string;
+}
+
+/**
+ * One gateway's answer for one cached time. `matches`: the gateway named the
+ * cached block height and block time. `differs`: it named a block, and the
+ * block is not the cached one. `unreachable`: it named no block (a transport
+ * failure, a refusal, an answer that is not one, or a witness not yet in a
+ * block).
+ */
+export interface WitnessTimeAnswer {
+  gateway: string;
+  outcome: "matches" | "differs" | "unreachable";
+  blockHeight: number | null;
+  blockTime: number | null;
+}
+
+/**
+ * One cached time, and what the public record said about it: `differs` when
+ * any gateway named a different block, otherwise `matches` when any gateway
+ * named the cached one, otherwise `not_checked`. The same worst-answer-wins
+ * order as the byte lookup.
+ */
+export interface WitnessTimeCheck {
+  cached: CachedWitnessTime;
+  outcome: "matches" | "differs" | "not_checked";
+  answers: WitnessTimeAnswer[];
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+// A member the object itself holds, never one inherited from its prototype.
+function own(o: Record<string, unknown>, key: string): unknown {
+  return Object.prototype.hasOwnProperty.call(o, key) ? o[key] : undefined;
+}
+
+function blockNumber(value: unknown, upper: number): number | null {
+  if (typeof value !== "number" || !Number.isSafeInteger(value)) return null;
+  if (value < 0 || value > upper) return null;
+  return value;
+}
+
+// `stamp_ref` to `[kind, id]` for every stamp in the signed body that names a
+// witness. A `stamp_ref` spelled on two stamps names neither.
+function stampWitnesses(bundle: Record<string, unknown>): Map<string, [string, string]> {
+  const out = new Map<string, [string, string]>();
+  if (typeof bundle.body_type !== "string" || !STAMP_BODIES.has(bundle.body_type)) return out;
+  const body = bundle.body;
+  const stamps = isObject(body) ? body.stamps : undefined;
+  if (!Array.isArray(stamps)) return out;
+  const seen = new Set<string>();
+  for (const stamp of stamps) {
+    if (!isObject(stamp)) continue;
+    const ref = stamp.stamp_ref;
+    if (typeof ref !== "string" || !STAMP_REF.test(ref)) continue;
+    if (seen.has(ref)) {
+      out.delete(ref);
+      continue;
+    }
+    seen.add(ref);
+    const anchor = stamp.anchor_ref;
+    if (!isObject(anchor)) continue;
+    if (typeof anchor.kind === "string" && typeof anchor.id === "string") {
+      out.set(ref, [anchor.kind, anchor.id]);
+    }
+  }
+  return out;
+}
+
+// The file's JSON, read under the rule `contents.json` is read under (5.6.2):
+// strict UTF-8, no byte-order mark, no `NaN` or `Infinity`, no member named
+// twice, and nothing nested past `MAX_WITNESS_CACHE_DEPTH`. `undefined` for
+// anything else.
+function readFile(raw: Uint8Array | null | undefined): unknown {
+  if (!(raw instanceof Uint8Array)) return undefined;
+  if (jsonDepthExceeds(raw, MAX_WITNESS_CACHE_DEPTH)) return undefined;
+  try {
+    return jcsParse(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The cached witness times the `witness-cache.json` bytes `raw` give for the
+ * signed `bundle` beside them, in the order the file lists them. `raw` is
+ * `null` where the pack has no such file. Pure, and never throws. The file
+ * reads only where it is a JSON object whose `cache_version` is
+ * `WITNESS_CACHE_VERSION` and whose `witnessed` is a list. An entry reads only
+ * where it is an object whose `stamp_ref` is 64 lowercase hex characters naming
+ * exactly one stamp of the signed body that has an `anchor_ref`, whose
+ * `block_height` is a non-negative safe integer, and whose `block_time` is a
+ * whole number of seconds since 1970-01-01T00:00:00Z from 0 to
+ * `MAX_BLOCK_TIME`. A `stamp_ref` two entries name reads for neither.
+ * Everything else reads as no cache for the stamp it would have spoken for.
+ */
+export function readWitnessCache(bundle: unknown, raw: Uint8Array | null | undefined): CachedWitnessTime[] {
+  if (!isObject(bundle)) return [];
+  const cache = readFile(raw);
+  if (!isObject(cache)) return [];
+  if (own(cache, "cache_version") !== WITNESS_CACHE_VERSION) return [];
+  const entries = own(cache, "witnessed");
+  if (!Array.isArray(entries)) return [];
+  const witnesses = stampWitnesses(bundle);
+  const read: CachedWitnessTime[] = [];
+  const named = new Map<string, number>();
+  for (const entry of entries) {
+    if (!isObject(entry)) continue;
+    const ref = own(entry, "stamp_ref");
+    if (typeof ref !== "string" || !witnesses.has(ref)) continue;
+    named.set(ref, (named.get(ref) ?? 0) + 1);
+    const height = blockNumber(own(entry, "block_height"), Number.MAX_SAFE_INTEGER);
+    const time = blockNumber(own(entry, "block_time"), MAX_BLOCK_TIME);
+    if (height === null || time === null) continue;
+    const [kind, id] = witnesses.get(ref)!;
+    read.push({ stampRef: ref, blockHeight: height, blockTime: time, witnessKind: kind, witnessId: id });
+  }
+  return read.filter((c) => named.get(c.stampRef) === 1);
+}
+
+/** A block time as RFC 3339 UTC to the second, the way both kernels print it: `2026-09-08T12:10:07Z`. */
+export function formatBlockTime(seconds: number): string {
+  return new Date(seconds * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+/** `block 1996701 at 2026-09-08T12:10:07Z`. */
+export function renderWitnessTime(blockHeight: number, blockTime: number): string {
+  return `block ${blockHeight} at ${formatBlockTime(blockTime)}`;
+}
+
+/**
+ * The request body the lookup sends: one GraphQL query for one transaction's
+ * block, as JCS, so both kernels send the same bytes.
+ */
+export function witnessTimeQuery(witnessId: string): string {
+  return jcs({ query: `query{transaction(id:"${witnessId}"){block{height timestamp}}}` });
+}
+
+function readAnswer(raw: Uint8Array): [number, number] | null {
+  if (jsonDepthExceeds(raw, MAX_ANSWER_DEPTH)) return null;
+  let node: unknown;
+  try {
+    node = jcsParse(raw);
+  } catch {
+    return null;
+  }
+  for (const key of ["data", "transaction", "block"]) {
+    if (!isObject(node)) return null;
+    node = node[key];
+  }
+  if (!isObject(node)) return null;
+  const height = blockNumber(node.height, Number.MAX_SAFE_INTEGER);
+  const time = blockNumber(node.timestamp, Number.MAX_SAFE_INTEGER);
+  if (height === null || time === null) return null;
+  return [height, time];
+}
+
+async function ask(
+  cached: CachedWitnessTime,
+  gateway: string,
+  fetchImpl: typeof fetch,
+): Promise<WitnessTimeAnswer> {
+  const unreachable: WitnessTimeAnswer = { gateway, outcome: "unreachable", blockHeight: null, blockTime: null };
+  const url = `${gateway.replace(/\/+$/, "")}/graphql`;
+  let raw: Uint8Array;
+  try {
+    const resp = await fetchImpl(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: witnessTimeQuery(cached.witnessId),
+    });
+    if (!resp.ok) return unreachable;
+    raw = new Uint8Array(await resp.arrayBuffer());
+  } catch {
+    return unreachable;
+  }
+  const block = readAnswer(raw);
+  if (block === null) return unreachable;
+  const [height, time] = block;
+  const same = height === cached.blockHeight && time === cached.blockTime;
+  return { gateway, outcome: same ? "matches" : "differs", blockHeight: height, blockTime: time };
+}
+
+/**
+ * Look each cached time up on every gateway, in order. With no gateways or no
+ * `fetchImpl`, nothing is looked up and every time is `not_checked`. A witness
+ * that is not `arweave`, or whose id is not a 43-character base64url
+ * transaction id, is never looked up.
+ */
+export async function checkWitnessCache(
+  cached: readonly CachedWitnessTime[],
+  gateways: readonly string[],
+  fetchImpl: typeof fetch | undefined,
+): Promise<WitnessTimeCheck[]> {
+  const out: WitnessTimeCheck[] = [];
+  for (const c of cached) {
+    if (
+      gateways.length === 0 ||
+      fetchImpl === undefined ||
+      c.witnessKind !== ADAPTER_KIND ||
+      !ARWEAVE_ID.test(c.witnessId)
+    ) {
+      out.push({ cached: c, outcome: "not_checked", answers: [] });
+      continue;
+    }
+    const answers: WitnessTimeAnswer[] = [];
+    for (const gw of gateways) answers.push(await ask(c, gw, fetchImpl));
+    const outcome = answers.some((a) => a.outcome === "differs")
+      ? "differs"
+      : answers.some((a) => a.outcome === "matches")
+        ? "matches"
+        : "not_checked";
+    out.push({ cached: c, outcome, answers });
+  }
+  return out;
+}