@sanning/proof 0.12.0 → 0.14.0

package/dist/verifier.js

@@ -19,7 +19,7 @@ import { ed25519Verify, isHexField, sha256Hex, utf8 } from "./crypto.js";
 // 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
@@ -187,11 +187,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
@@ -217,14 +219,152 @@ 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) {
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+}
 export function jcsParse(bytes) {
     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 = JSON.parse(text);
+    const value = 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 {
+    key;
+    constructor(key) {
+        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) {
+    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) {
+    const value = 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) {
+    // `names` is null for an array. `expectName` is true where the next string
+    // is a member name rather than a value.
+    const stack = [];
+    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));
+                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
@@ -299,10 +439,14 @@ function hasLoneSurrogate(s) {
 // `<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) {
+//
+// `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, accepted) {
     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}.`))
@@ -383,8 +527,69 @@ function skeletonFieldErrors(env) {
     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) {
+    const out = [];
+    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) {
+    if (typeof subject !== "object" || subject === null || Array.isArray(subject))
+        return false;
+    for (const key of Object.keys(subject)) {
+        const v = subject[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)
@@ -444,18 +649,21 @@ export function contentHashes(env) {
 // 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 }).
-export async function verifyEnvelope(env, optionsOrContentHash) {
-    const opts = typeof optionsOrContentHash === "string"
-        ? { expectedContentHash: optionsOrContentHash }
-        : (optionsOrContentHash ?? {});
+// 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, options) {
+    if (typeof options === "string") {
+        throw new TypeError("verifyEnvelope: pass { expectedContentHash } rather than a bare string (0.13.0)");
+    }
+    const opts = 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(`verifyEnvelope: unknown option(s) ${unknownOptions.join(", ")}. ` +
@@ -528,7 +736,7 @@ async function verifyEnvelopeChecked(env, opts) {
             errors: ["envelope is not a JSON object"],
         };
     }
-    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`
@@ -598,7 +806,7 @@ async function verifyEnvelopeChecked(env, opts) {
     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");
     }

package/dist/witness-cache.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 declare const MAX_BLOCK_TIME = 253402300799;
+/** The file's name, beside `bundle.json` in the pack's folder (5.6.1). */
+export declare 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 declare 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 declare const MAX_WITNESS_CACHE_DEPTH = 512;
+/**
+ * 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[];
+}
+/**
+ * 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 declare function readWitnessCache(bundle: unknown, raw: Uint8Array | null | undefined): CachedWitnessTime[];
+/** A block time as RFC 3339 UTC to the second, the way both kernels print it: `2026-09-08T12:10:07Z`. */
+export declare function formatBlockTime(seconds: number): string;
+/** `block 1996701 at 2026-09-08T12:10:07Z`. */
+export declare function renderWitnessTime(blockHeight: number, blockTime: number): string;
+/**
+ * The request body the lookup sends: one GraphQL query for one transaction's
+ * block, as JCS, so both kernels send the same bytes.
+ */
+export declare function witnessTimeQuery(witnessId: string): string;
+/**
+ * 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 declare function checkWitnessCache(cached: readonly CachedWitnessTime[], gateways: readonly string[], fetchImpl: typeof fetch | undefined): Promise<WitnessTimeCheck[]>;

package/dist/witness-cache.js

@@ -0,0 +1,264 @@
+// 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;
+function isObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+// A member the object itself holds, never one inherited from its prototype.
+function own(o, key) {
+    return Object.prototype.hasOwnProperty.call(o, key) ? o[key] : undefined;
+}
+function blockNumber(value, upper) {
+    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) {
+    const out = new Map();
+    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();
+    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) {
+    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, raw) {
+    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 = [];
+    const named = new Map();
+    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) {
+    return new Date(seconds * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** `block 1996701 at 2026-09-08T12:10:07Z`. */
+export function renderWitnessTime(blockHeight, blockTime) {
+    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) {
+    return jcs({ query: `query{transaction(id:"${witnessId}"){block{height timestamp}}}` });
+}
+function readAnswer(raw) {
+    if (jsonDepthExceeds(raw, MAX_ANSWER_DEPTH))
+        return null;
+    let node;
+    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, gateway, fetchImpl) {
+    const unreachable = { gateway, outcome: "unreachable", blockHeight: null, blockTime: null };
+    const url = `${gateway.replace(/\/+$/, "")}/graphql`;
+    let raw;
+    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, gateways, fetchImpl) {
+    const out = [];
+    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 = [];
+        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;
+}