@sanning/proof 0.12.0 → 0.14.0

package/src/verifier.ts

@@ -23,7 +23,7 @@ import type { ContentRole, Envelope, VerificationResult, VerifyOptions } from ".
 // profile-specific dialect (no underscore strip, that is mlflow-only).
 //
 // Exported for parity with the sibling kernels' registries — Python
-// `ACCEPTED_SPEC_VERSIONS`, Go `SupportedSpecMajor` — so the accept-set is
+// `ACCEPTED_SPEC_MAJORS`, Go `SupportedSpecMajor` — so the accept-set is
 // assertable rather than inferable: test/accept-set.test.ts holds it to the
 // ratified §4/§5 set transcribed in cross-kernel/accept-set.json, and the
 // cross-kernel gate probes one signed envelope per identifier. This entry list
@@ -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
@@ -231,14 +233,143 @@ const JCS_BOM = "";
  * Throws for anything that is not conformant; every call site treats a throw as
  * "this reader cannot read these bytes" and names the check that failed.
  */
+/**
+ * Bytes as strict UTF-8, a leading byte-order mark KEPT as a character.
+ * `utf8_strict` in the Python twin's `canonicalize.py` is the same rule, and
+ * `jcsParse` below performs the identical decode. Throws on bytes that are not
+ * UTF-8.
+ */
+export function utf8Strict(bytes: Uint8Array): string {
+  return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+}
+
 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
@@ -311,9 +442,17 @@ function hasLoneSurrogate(s: string): boolean {
 // `<major>.<minor>` where minor is `[0-9]+`. A non-numeric minor suffix is
 // malformed, not a tolerated future version — matching the Python kernel's
 // 0.1.1 semantics (the TS/Go fail-open lenience was closed deliberately).
-export function specVersionSupported(specVersion: string): boolean {
+//
+// `accepted` NARROWS the registry and never widens it, as the Python twin's
+// `spec_version_supported(spec_version, accepted)` does (P-10, 0.13.0).
+export function specVersionSupported(
+  specVersion: string,
+  accepted?: readonly string[],
+): boolean {
   if (typeof specVersion !== "string" || specVersion === "") return false;
-  return ACCEPTED_SPEC_MAJORS.some((m) => {
+  const registry =
+    accepted === undefined ? ACCEPTED_SPEC_MAJORS : ACCEPTED_SPEC_MAJORS.filter((m) => accepted.includes(m));
+  return registry.some((m) => {
     if (specVersion === m) return true;
     if (!specVersion.startsWith(`${m}.`)) return false;
     const minor = specVersion.slice(m.length + 1);
@@ -392,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)
@@ -456,22 +661,26 @@ export function contentHashes(env: Envelope): { role: ContentRole; hash: string
 // signature, so stripping it to fake "external" — or injecting one to fake
 // "inline" — breaks the signature).
 //
-// The second argument accepts the legacy `expectedContentHash` string form
-// or a VerifyOptions object ({ payloadBytes, expectedContentHash }).
+// The second argument is a VerifyOptions object ({ payloadBytes,
+// expectedContentHash, acceptedSpecMajors }). Until 0.13.0 it could also be a
+// bare `expectedContentHash` string; that overload is gone (P-10), so the two
+// kernels take one options shape: write `{ expectedContentHash: hash }`.
 export async function verifyEnvelope(
   env: Envelope,
-  optionsOrContentHash?: string | VerifyOptions,
+  options?: VerifyOptions,
 ): Promise<VerificationResult> {
-  const opts: VerifyOptions =
-    typeof optionsOrContentHash === "string"
-      ? { expectedContentHash: optionsOrContentHash }
-      : (optionsOrContentHash ?? {});
+  if (typeof options === "string") {
+    throw new TypeError(
+      "verifyEnvelope: pass { expectedContentHash } rather than a bare string (0.13.0)",
+    );
+  }
+  const opts: VerifyOptions = options ?? {};
   // REFUSE an unknown option key rather than ignore it. `expected_content_hash`
   // — the Python kernel's spelling — previously fell through as `undefined`, so
   // the content bind silently never ran and the caller got a clean pass with no
   // errors at all. A check that quietly does not happen is worse than one that
   // fails: the caller believes they verified an artifact they never checked.
-  const KNOWN_VERIFY_OPTIONS = new Set(["payloadBytes", "expectedContentHash"]);
+  const KNOWN_VERIFY_OPTIONS = new Set(["payloadBytes", "expectedContentHash", "acceptedSpecMajors"]);
   const unknownOptions = Object.keys(opts).filter((k) => !KNOWN_VERIFY_OPTIONS.has(k));
   if (unknownOptions.length > 0) {
     throw new TypeError(
@@ -551,7 +760,7 @@ async function verifyEnvelopeChecked(
     };
   }
 
-  const specVersionOk = specVersionSupported(env.spec_version);
+  const specVersionOk = specVersionSupported(env.spec_version, opts.acceptedSpecMajors);
   if (!specVersionOk) errors.push(`unsupported spec_version: ${JSON.stringify(env.spec_version)}`);
 
   // Skeleton field format (envelope-spec §2, proof#95): a present `signed_at`
@@ -625,7 +834,7 @@ async function verifyEnvelopeChecked(
   let signatureOk = false;
   try {
     const { signature: _signature, co_signatures: _coSignatures, ...envelopeForSig } = env;
-    signatureOk = await ed25519Verify(env.signature, utf8(jcs(envelopeForSig)), env.public_key);
+    signatureOk = await ed25519Verify(utf8(jcs(envelopeForSig)), env.signature, env.public_key);
     if (!signatureOk) errors.push("Ed25519 signature verification failed");
   } catch (e) {
     errors.push(`signature verification error: ${stringifyErr(e)}`);

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;
+}