@sanning/proof 0.13.0 → 0.14.0

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanning/proof",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "TypeScript kernel of the Sanning verification stack: RFC 8785 (JCS) canonicalization, SHA-256, and Ed25519 verification for Verifiable Event Envelopes. Full-family verifier (inline + external commitment); accepts sanning.agent/v1 and sanning.events/v2. Conformance-gated byte-for-byte against the test-vectors corpus.",
   "license": "MIT",
   "type": "module",

package/src/case-file.ts

@@ -25,7 +25,7 @@
  * network. How the files were listed and hashed is the caller's.
  */
 
-import { jcsParse } from "./verifier.js";
+import { DuplicateKeyError, jcsParse } from "./verifier.js";
 
 /** The index's dispatch key (5.6.2). An absent or unknown value makes the index unreadable. */
 export const CASE_FILE_VERSION = "sanning.case-file/v1";
@@ -237,7 +237,10 @@ function readIndex(raw: Uint8Array): ReadIndex {
   let value: unknown;
   try {
     value = jcsParse(raw);
-  } catch {
+  } catch (e) {
+    // Named, because an index that lists one pack twice under one member name
+    // reads as whichever copy came last (I-JSON, proof#144).
+    if (e instanceof DuplicateKeyError) throw new Unreadable(e.message);
     throw new Unreadable("not readable as JSON");
   }
   if (!isObject(value)) throw new Unreadable("not a JSON object");

package/src/case.ts

@@ -260,7 +260,7 @@ import {
   readHandoffs,
   recordIsMalformed,
 } from "./handoff.js";
-import { verifyEvidenceBundle } from "./evidence.js";
+import { coSignaturesPresent, verifyEvidenceBundle } from "./evidence.js";
 import type { EvidenceBundleResult } from "./evidence.js";
 import {
   type PackGrade,
@@ -271,6 +271,7 @@ import {
   gradePack,
 } from "./grading.js";
 import type { SideContentMap } from "./side-content.js";
+import { renderWitnessTime } from "./witness-cache.js";
 
 // ---- The vocabulary ---------------------------------------------------------
 
@@ -727,13 +728,25 @@ export const RECORD_PROFILE_QUARANTINED = "record_profile_quarantined";
 export const CASE_HOLDS_NO_PACKS = "case_holds_no_packs";
 
 /**
- * The two NOTEs (5.5.3 v1.20): findings on the reading with no contribution,
- * printed in the scope sentence so a clean verdict never hides either.
- * `pack_undeclared` is a note only where the reading holds no hand-off record;
- * where it holds one, it is the exception of that name.
+ * The three NOTEs (5.5.3 v1.20, extended proof#148): findings on the reading
+ * with no contribution, printed in the scope sentence so a clean verdict
+ * never hides any of them. `pack_undeclared` is a note only where the
+ * reading holds no hand-off record; where it holds one, it is the exception
+ * of that name.
  */
 export const CONTENT_WITHHELD_BY_DECLARATION = "content_withheld_by_declaration";
-export const CASE_NOTE_KINDS = [PACK_UNDECLARED, CONTENT_WITHHELD_BY_DECLARATION] as const;
+/**
+ * A pack's wrapper carries a present `co_signatures` (evidence-bundle.md §2,
+ * decided by Phil 2026-09-24 on proof#148). The field verifies nothing and
+ * sits outside the wrapper's signed scope, so the case reading names it
+ * rather than presenting it as evidence, and it contributes no verdict.
+ */
+export const CO_SIGNATURES_PRESENT = "co_signatures_present";
+export const CASE_NOTE_KINDS = [
+  PACK_UNDECLARED,
+  CONTENT_WITHHELD_BY_DECLARATION,
+  CO_SIGNATURES_PRESENT,
+] as const;
 export type CaseNoteKind = (typeof CASE_NOTE_KINDS)[number];
 
 /**
@@ -1330,6 +1343,16 @@ export async function readCase(
     }
     holderKeys.add(holder);
 
+    if (coSignaturesPresent(pack.bundle)) {
+      // A NOTE, with no contribution (5.5.3 v1.20, proof#148): the wrapper's
+      // co_signatures verifies nothing and sits outside its signed scope, so
+      // the case reading names it rather than moving anything on its account.
+      caseNotes.push({
+        position,
+        note: { kind: CO_SIGNATURES_PRESENT, packRef: pack.ref },
+      });
+    }
+
     const bodyType = bodyTypeOf(pack.bundle);
     const records = packRecords(pack.bundle, pack.content);
     // The per-record gradings below are joined to `records` BY INDEX, so a
@@ -1939,6 +1962,11 @@ export function renderCaseNote(note: CaseNote): string {
       );
     case PACK_UNDECLARED:
       return `${note.packRef} does not say what it holds`;
+    case CO_SIGNATURES_PRESENT:
+      return (
+        `${note.packRef} carries unverified co-signatures in its wrapper; ` +
+        "they are not part of the evidence"
+      );
     default:
       return (note as CaseNote).kind;
   }
@@ -1998,17 +2026,18 @@ export const VERDICT_DISPLAY_TITLES: Readonly<Record<string, string>> = {
 
 /**
  * What a reader may rely on, for each of the six words a case reading reaches
- * (5.5.6 v1.20, A26), the same for every drop. `pending` and `not_found`
- * never head a case reading: they are witness states.
+ * (5.5.6 v1.20, A26; the `verified` text at v1.28, A35), the same for every
+ * drop. `pending` and `not_found` never head a case reading: they are
+ * witness states. `verified` is the base sentence, printed alone where the
+ * drop holds no hand-off record; a caller reads `caseReliance` for
+ * `verified`, never this mapping directly.
  */
 export const CASE_RELIANCE: Readonly<Record<CaseVerdict, string>> = {
   verified:
-    "Every pack in this drop is genuine and unaltered and agrees with its " +
-    "own signed declaration. Every hand-off with both sides here is " +
-    "intact. Every other record is one its holder signed as a step. " +
-    "Nothing here could not be checked. This was read offline, on this " +
-    "device. It does not say these packs are everything the parties " +
-    "recorded.",
+    "Every pack in this drop is genuine, unaltered, and matches its own " +
+    "signed declaration. Every record in it was signed by its holder's " +
+    "key. This was read offline, on this device. It does not say this " +
+    "drop holds everything that was recorded.",
   partial:
     "Nothing here was proven wrong, and a check could not be completed: a " +
     "pack names no witness, or a pack in a hand-off reading does not say " +
@@ -2031,6 +2060,37 @@ export const CASE_RELIANCE: Readonly<Record<CaseVerdict, string>> = {
     "exception before relying on any of it.",
 };
 
+/**
+ * The clause a `verified` drop that holds a hand-off record gains, inserted
+ * after `CASE_RELIANCE`'s first sentence (5.5.6, A35). Never printed alone,
+ * and never where `handoffRecords` is zero: most drops hold one agent's
+ * pack and no hand-off to say anything about.
+ */
+export const CASE_RELIANCE_HANDOFF_CLAUSE =
+  "Every hand-off with both sides in this drop is intact.";
+
+/**
+ * What a reader may rely on for one case reading (5.5.6 v1.28, A35), byte
+ * for byte the text `case_reliance`'s Python sibling returns.
+ *
+ * For every word but `verified` this is `CASE_RELIANCE` unchanged. For
+ * `verified`, the hand-off clause is inserted after the first sentence
+ * where `handoffRecords` is not zero, and left out where it is zero: the
+ * base sentence never claims a hand-off the drop does not hold.
+ */
+export function caseReliance(verdict: CaseVerdict, handoffRecords: number): string {
+  if (verdict === "verified" && handoffRecords > 0) {
+    return (
+      "Every pack in this drop is genuine, unaltered, and matches its own " +
+      "signed declaration. Every hand-off with both sides in this drop is " +
+      "intact. Every record in it was signed by its holder's key. This " +
+      "was read offline, on this device. It does not say this drop holds " +
+      "everything that was recorded."
+    );
+  }
+  return CASE_RELIANCE[verdict];
+}
+
 /** The three witness states, and how each is printed (5.5.6, D7). No other. */
 export const WITNESS_STATES = {
   confirmed: "Confirmed on the public record",
@@ -2050,6 +2110,18 @@ export interface WitnessLine {
   state: WitnessState;
   reasons: string[];
   services: string[];
+  /**
+   * Witness times a pack caches that no lookup settled, as `[blockHeight,
+   * blockTime]`, distinct and in time order (5.6.6, v1.25, A30). Printed labelled
+   * not checked, and never as a time a reader may rely on. Absent reads as none.
+   */
+  cached?: [number, number][];
+  /**
+   * Witness times the public record returned where they matched a pack's
+   * cache, distinct and in time order. The gateway's answer, named with the
+   * service, never the cache's value. Absent reads as none.
+   */
+  recorded?: [number, number][];
 }
 
 /** The line printed where no lookup ran, which is every reading this kernel produces on its own. */
@@ -2060,9 +2132,23 @@ export const WITNESS_NOT_LOOKED_UP: Readonly<WitnessLine> = Object.freeze({
 });
 
 /** The witness line as both kernels print it. */
+/** How a witness time a pack caches is printed where nothing checked it (5.5.6, 5.6.6, v1.25, A30). */
+export const WITNESS_TIME_CACHED = "the pack dates the witness, not checked";
+/** How a witness time the public record returned is printed where it matched the cache. */
+export const WITNESS_TIME_RECORDED = "the public record dates the witness";
+
+function witnessTimes(times: readonly [number, number][]): string {
+  return times.map(([h, t]) => renderWitnessTime(h, t)).join(", ");
+}
+
 export function renderWitnessLine(line: WitnessLine): string {
   let text = `Witness: ${WITNESS_STATES[line.state]}`;
-  if (line.reasons.length > 0) text += `: ${line.reasons.join("; ")}`;
+  const parts = [...line.reasons];
+  if (line.cached && line.cached.length > 0) parts.push(`${WITNESS_TIME_CACHED}: ${witnessTimes(line.cached)}`);
+  if (line.recorded && line.recorded.length > 0) {
+    parts.push(`${WITNESS_TIME_RECORDED}: ${witnessTimes(line.recorded)}`);
+  }
+  if (parts.length > 0) text += `: ${parts.join("; ")}`;
   if (line.services.length > 0) text += ` (answered: ${line.services.join(", ")})`;
   return text;
 }