@sanning/proof 0.7.0 → 0.8.1

package/src/evidence.ts

@@ -86,6 +86,7 @@ export const EXPORT_BODY_TYPE = "sanning.evidence.export/v1";
  * unrecoverable once witnessed.
  */
 export const STAMP_TRACE_BODY_TYPE = "sanning.stamp.trace/v1";
+export const STAMP_EVIDENCE_BODY_TYPE = "sanning.stamp.evidence/v1";
 
 /**
  * The version string INSIDE a witnessed stamp body — a different string from
@@ -245,6 +246,37 @@ export interface StampTraceBody {
   stamps: StampEntry[];
 }
 
+// ---- `sanning.stamp.evidence/v1` wire types (evidence-bundle.md §5.3) -----
+//
+// Both halves of a DL-52 record, bound: the producer signs the envelope, and
+// Sanning signs and witnesses the stamp whose root commits to it. Neither
+// earlier body joins them, and a field added to §5.2 could not — a conformant
+// reader MUST ignore fields it does not know (envelope-spec.md §2), so the
+// join has to live in a body_type readers DISPATCH on. See §5.3.1.
+
+/** §5.3's inclusion: §5.1's shape with `stamp_ref` as the join key. */
+export interface StampEvidenceInclusion {
+  leaf_hash: string; // hex
+  leaf_index: number;
+  leaf_count: number;
+  audit_path: string[]; // hex[]
+  /** Resolves against `stamps[].stamp_ref` in the SAME body. */
+  stamp_ref: string;
+}
+
+export interface StampEvidenceEvent {
+  envelope: Envelope;
+  record_bytes?: string; // hex of JCS(event record); omitted == withheld
+  content?: string; // opt-in disclosed raw bytes, lowercase hex
+  inclusion: StampEvidenceInclusion;
+}
+
+export interface StampEvidenceBody {
+  /** Byte-identical to §5.2.2 — one definition, one place to change. */
+  stamps: StampEntry[];
+  events: StampEvidenceEvent[];
+}
+
 export interface EvidenceBundle {
   spec_version: string;
   body_type: string;
@@ -396,6 +428,35 @@ export interface StampResult {
    * carries it.
    */
   anchorRef: AnchorRef | null;
+  /**
+   * Per-gateway on-chain outcomes for this stamp's `anchor_ref` (§4.2's shape,
+   * `checkpoints[]`'s vocabulary), or `null` when NOTHING WAS CHECKED.
+   *
+   * ── The four states, and why none of them collapses ──
+   *
+   * `null` means not checked — no gateways were supplied, or this stamp names
+   * no witness to check. It is a statement about the RUN, never about the
+   * stamp. The other three are statements about the stamp and live in
+   * `onChain.rollup`: `confirm` (a gateway returned the witnessed bytes),
+   * `mismatch` (a gateway returned DIFFERENT bytes — a finding, and the only
+   * one of the four that fails anything), `unreachable` (we asked and nobody
+   * answered — an availability gap, never an accusation).
+   *
+   * Keeping "not checked" distinct from "unreachable" is the whole point. A
+   * surface handed a collapsed boolean cannot tell "no gateway could be
+   * reached" from "no gateway was tried", and reported the first when the
+   * second was true — a false accusation manufactured by a missing state.
+   */
+  onChain: OnChainResult | null;
+  /**
+   * Derived collapse of `onChain`, mirroring `CheckpointResult.onChainOk` so a
+   * consumer reads one field the same way on both: `false` on mismatch, `true`
+   * on confirm, `null` on unreachable AND on not-checked.
+   *
+   * It is deliberately the LOSSY view — `null` is three-quarters of the state
+   * space here. Anything that needs to tell those apart reads `onChain`.
+   */
+  onChainOk: boolean | null;
   ok: boolean;
   errors: string[];
 }
@@ -717,7 +778,12 @@ export async function verifyEvidenceBundle(
   // wrapper is authentic — and for this body that IS "Sanning signed it", since
   // a stamp carries no second signature of its own inside the bundle.
   if (bodyType === STAMP_TRACE_BODY_TYPE) {
-    return verifyStampTrace(b, specVersionOk, assertedStatus, errors);
+    return verifyStampTrace(b, specVersionOk, assertedStatus, errors, options);
+  }
+
+  // The DL-52 hand-over body (§5.3): stamps AND the customer's events, joined.
+  if (bodyType === STAMP_EVIDENCE_BODY_TYPE) {
+    return verifyStampEvidence(b, specVersionOk, assertedStatus, errors, options);
   }
 
   if (bodyType !== ANCHOR_TRACE_BODY_TYPE && bodyType !== ANCHOR_TRACE_BODY_TYPE_V1) {
@@ -1091,79 +1157,10 @@ async function verifyAnchorTrace(
       }
     }
 
-    // Content (raw-log) binding — the rawLog → content_hash link the rest of
-    // the chain (content_hash → record → payload_hash → signature → leaf →
-    // root) already covers. The committed hash lives in the RECORD
-    // (record.event.content_hash, minimal disclosure); for a promoted-disclosure
-    // envelope it falls back to the envelope's own committed hashes
-    // (contentHashes — NOT verifyEnvelope's path, which reads payload/event_type
-    // and yields nothing for a sanning.events/v1 envelope). Disclosed bytes come
-    // from the signed in-body `ev.content` FIRST, then the out-of-band
-    // options.content side input. Undetermined (null) when nothing is disclosed
-    // or nothing is committed; false ONLY on a real mismatch or an in-body vs
-    // side-input disagreement — mirroring payloadBindingOk's never-fail-on-absent
-    // discipline.
-    let contentOk: boolean | null = null;
-    {
-      const committed: string[] = [];
-      let recordContentHash: string | undefined;
-      if (recordBytes !== undefined) {
-        try {
-          const record = JSON.parse(new TextDecoder().decode(recordBytes)) as {
-            event?: { content_hash?: unknown };
-          };
-          const ch = record.event?.content_hash;
-          if (typeof ch === "string" && ch) recordContentHash = ch.toLowerCase();
-        } catch {
-          // record not JSON — the payload binding already reflects that; content
-          // stays undetermined rather than throwing.
-        }
-      }
-      if (recordContentHash !== undefined) {
-        committed.push(recordContentHash);
-      } else if (ev.envelope && typeof ev.envelope === "object") {
-        // Promoted fallback. Guarded: contentHashes() dereferences env.payload,
-        // which throws on a null/non-object envelope — a verifier must never
-        // raise on adversarial input (such an event already fails via envelopeOk).
-        for (const c of contentHashes(ev.envelope)) committed.push(c.hash.toLowerCase());
-      }
-
-      // Disclosed bytes, precedence: in-body (signed) → side input. A string
-      // side input is hex; a Uint8Array is used as-is. Resolved by the SHARED
-      // selector so `disclosedContent` hands a consumer the very bytes bound
-      // here — one decode, not two that can drift apart.
-      const selection = selectDisclosedBytes(ev, eventId, options.content);
-      const { inBody, side } = selection;
-      evErrors.push(...selection.errors);
-
-      if (inBody !== undefined && side !== undefined && !bytesEqual(inBody, side)) {
-        // Two disclosures that disagree: a genuine conflict, not undetermined.
-        contentOk = false;
-        evErrors.push(
-          "disclosed content disagreement: in-body events[].content and the supplied content differ",
-        );
-      } else {
-        const disclosed = inBody ?? side;
-        if (disclosed === undefined || committed.length === 0) {
-          contentOk = null;
-          if (disclosed !== undefined && committed.length === 0) {
-            evErrors.push(
-              "disclosed content present but no committed content_hash to bind to " +
-                "(record withheld or record has no event.content_hash) — undetermined",
-            );
-          }
-        } else {
-          const got = await sha256Hex(disclosed);
-          contentOk = committed.includes(got);
-          if (!contentOk) {
-            evErrors.push(
-              "disclosed content does not match the committed content_hash: " +
-                `sha256(disclosed)=${got} committed=${committed.join("|")}`,
-            );
-          }
-        }
-      }
-    }
+    // Content (raw-log) binding — shared with every other event-carrying body.
+    const contentRes = await verifyDisclosedContent(ev, eventId, recordBytes, options.content);
+    const contentOk = contentRes.contentOk;
+    evErrors.push(...contentRes.errors);
 
     eventResults.push({
       eventId,
@@ -1320,10 +1317,106 @@ function isNonNegInt(n: unknown): n is number {
  * verifier that stops at the first one turns a second fix into a second
  * round-trip.
  */
+// ===========================================================================
+// Disclosed-content binding, shared by every body that carries events.
+//
+// Extracted for `sanning.stamp.evidence/v1` (§5.3) rather than copied. The
+// rawLog -> content_hash link is the one step the chain
+// (content_hash -> record -> payload_hash -> signature -> leaf -> root) does
+// not otherwise cover, and a second copy of it is a second place for the
+// never-fail-on-absent discipline to drift. The rules are unchanged from the
+// anchor-trace path this came from: undetermined (null) when nothing is
+// disclosed or nothing is committed; false ONLY on a real mismatch or an
+// in-body vs side-input disagreement.
+// ===========================================================================
+async function verifyDisclosedContent(
+  ev: { envelope?: unknown; content?: unknown },
+  eventId: string,
+  recordBytes: Uint8Array | undefined,
+  sideContent: VerifyEvidenceOptions["content"],
+): Promise<{ contentOk: boolean | null; errors: string[] }> {
+  const evErrors: string[] = [];
+  let contentOk: boolean | null = null;
+
+  const committed: string[] = [];
+  let recordContentHash: string | undefined;
+  if (recordBytes !== undefined) {
+    try {
+      const record = JSON.parse(new TextDecoder().decode(recordBytes)) as {
+        event?: { content_hash?: unknown };
+      };
+      const ch = record.event?.content_hash;
+      if (typeof ch === "string" && ch) recordContentHash = ch.toLowerCase();
+    } catch {
+      // record not JSON — the payload binding already reflects that; content
+      // stays undetermined rather than throwing.
+    }
+  }
+  if (recordContentHash !== undefined) {
+    committed.push(recordContentHash);
+  } else if (ev.envelope && typeof ev.envelope === "object") {
+    // Promoted fallback. Guarded: contentHashes() dereferences env.payload,
+    // which throws on a null/non-object envelope — a verifier must never raise
+    // on adversarial input.
+    for (const c of contentHashes(ev.envelope as Envelope)) committed.push(c.hash.toLowerCase());
+  }
+
+  const selection = selectDisclosedBytes(ev as TraceEvent, eventId, sideContent);
+  const { inBody, side } = selection;
+  evErrors.push(...selection.errors);
+
+  if (inBody !== undefined && side !== undefined && !bytesEqual(inBody, side)) {
+    contentOk = false;
+    evErrors.push(
+      "disclosed content disagreement: in-body events[].content and the supplied content differ",
+    );
+  } else {
+    const disclosed = inBody ?? side;
+    if (disclosed === undefined || committed.length === 0) {
+      contentOk = null;
+      if (disclosed !== undefined && committed.length === 0) {
+        evErrors.push(
+          "disclosed content present but no committed content_hash to bind to " +
+            "(record withheld or record has no event.content_hash) — undetermined",
+        );
+      }
+    } else {
+      const got = await sha256Hex(disclosed);
+      contentOk = committed.includes(got);
+      if (!contentOk) {
+        evErrors.push(
+          "disclosed content does not match the committed content_hash: " +
+            `sha256(disclosed)=${got} committed=${committed.join("|")}`,
+        );
+      }
+    }
+  }
+  return { contentOk, errors: evErrors };
+}
+
+/**
+ * One `stamps[]` entry's result, plus the witnessed bytes it was graded on.
+ *
+ * `witnessedHex` is internal and never surfaces on `StampResult`: it is the
+ * whole stamp body again, and putting it back on the result would double every
+ * serialized verdict to carry a copy of what the bundle already holds. It
+ * exists so the optional on-chain re-fetch compares the chain against THE SAME
+ * BYTES this function hashed to derive `stamp_ref`, rather than re-reading
+ * `stamp_bytes` out of the body a second time — one value, so the graded bytes
+ * and the compared bytes cannot come apart.
+ *
+ * Undefined exactly when `stamp_bytes` was unusable, in which case the entry
+ * has already failed and there is nothing a gateway could confirm.
+ */
+interface StampEntryOutcome {
+  result: StampResult;
+  witnessedHex?: string;
+}
+
 async function verifyStampEntry(
   raw: unknown,
   seen: Set<string>,
-): Promise<StampResult> {
+): Promise<StampEntryOutcome> {
   const errors: string[] = [];
   const base: StampResult = {
     stampRef: "",
@@ -1337,28 +1430,33 @@ async function verifyStampEntry(
     subtreesOk: false,
     subtrees: [],
     anchorRef: null,
+    onChain: null,
+    onChainOk: null,
     ok: false,
     errors,
   };
 
   if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
     errors.push("stamp entry is not an object");
-    return base;
+    return { result: base };
   }
   const e = raw as Partial<StampEntry> & Record<string, unknown>;
 
   // --- the witnessed bytes, which are the only authority in this body -------
   if (!isLowerHex(e.stamp_bytes)) {
     errors.push("stamp_bytes is missing or not lowercase hex");
-    return base;
+    return { result: base };
   }
   let bytes: Uint8Array;
   try {
     bytes = hexToBytes(e.stamp_bytes);
   } catch (err) {
     errors.push(`stamp_bytes is not hex: ${stringifyErr(err)}`);
-    return base;
+    return { result: base };
   }
+  // Gated by `isLowerHex` above, so this is already the exact lowercase hex of
+  // the exact witnessed bytes — §5.2.2's "one authority in this body".
+  const witnessedHex: string = e.stamp_bytes;
 
   // --- the derived identity -------------------------------------------------
   const derived = await sha256Hex(bytes);
@@ -1389,7 +1487,7 @@ async function verifyStampEntry(
     const parsed: unknown = JSON.parse(new TextDecoder().decode(bytes));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
       errors.push("stamp body is not a JSON object");
-      return base;
+      return { result: base, witnessedHex };
     }
     body = parsed as StampBody;
     // Re-canonicalize and compare. The plane replays these bytes verbatim on
@@ -1398,11 +1496,11 @@ async function verifyStampEntry(
     // of the stamp disagree with the one that was witnessed.
     if (jcs(body as unknown as Record<string, unknown>) !== new TextDecoder().decode(bytes)) {
       errors.push("stamp_bytes are not JCS-canonical (RFC 8785)");
-      return base;
+      return { result: base, witnessedHex };
     }
   } catch (err) {
     errors.push(`stamp body is not JSON: ${stringifyErr(err)}`);
-    return base;
+    return { result: base, witnessedHex };
   }
 
   if (body.stamp_version !== STAMP_BODY_VERSION) {
@@ -1414,7 +1512,7 @@ async function verifyStampEntry(
       `unsupported stamp_version ${JSON.stringify(body.stamp_version)} in a ` +
         `${STAMP_TRACE_BODY_TYPE} body (expected ${STAMP_BODY_VERSION})`,
     );
-    return base;
+    return { result: base, witnessedHex };
   }
   base.stampVersion = body.stamp_version;
   base.bodyOk = true;
@@ -1448,7 +1546,7 @@ async function verifyStampEntry(
 
   base.ok =
     base.stampRefOk && base.bodyOk && base.subtreesOk && errors.length === 0;
-  return base;
+  return { result: base, witnessedHex };
 }
 
 /**
@@ -1536,6 +1634,7 @@ async function verifyStampTrace(
   specVersionOk: boolean,
   assertedStatus: string | null,
   errors: string[],
+  options: VerifyEvidenceOptions,
 ): Promise<EvidenceBundleResult> {
   const body = b.body as StampTraceBody;
   if (!Array.isArray(body?.stamps)) {
@@ -1544,10 +1643,27 @@ async function verifyStampTrace(
 
   const seen = new Set<string>();
   const stamps: StampResult[] = [];
+  const witnessed: (string | undefined)[] = [];
   for (const entry of body.stamps) {
-    stamps.push(await verifyStampEntry(entry, seen));
+    const outcome = await verifyStampEntry(entry, seen);
+    stamps.push(outcome.result);
+    witnessed.push(outcome.witnessedHex);
   }
 
+  // --- The optional on-chain re-fetch (§5.2.4's "online act") ---------------
+  //
+  // The SAME stamps[] array §5.3 carries, so it gets the same capability. The
+  // alternative — a stamp that can be re-fetched inside one body and not the
+  // other — asks every consumer to remember which wrapper it is holding before
+  // it can trust `onChain: null`, and that is exactly the kind of per-body
+  // exception a reader eventually gets wrong.
+  const { onChainChecked, gatewayUnavailable } = await refetchStamps(
+    stamps,
+    witnessed,
+    options,
+    errors,
+  );
+
   // --- Rollup ----------------------------------------------------------------
   const anyHardFailure = stamps.some((s) => !s.ok);
   const anyUnwitnessed = stamps.some((s) => s.anchorRef === null);
@@ -1561,17 +1677,25 @@ async function verifyStampTrace(
     // does not have.
     status = "partial";
     errors.push(`${STAMP_TRACE_BODY_TYPE} body carries no stamps`);
-  } else if (anyUnwitnessed) {
-    // The honest half of P-10, one layer up. A stamp with no `anchor_ref` is
-    // sealed and unwitnessed: `retained-by-sanning`, which is a statement about
-    // our coverage and never an accusation about their evidence. It is also not
-    // `verified`, because for a stamp the witness is the entire independent
-    // part — unlike an anchor-trace checkpoint, which still carries a producer
-    // signature and an inclusion proof that stand on their own offline.
+  } else if (gatewayUnavailable || anyUnwitnessed) {
+    // Both hold the bundle at `partial`, and both get said — see §5.3's rollup
+    // for why one note is not enough when there are two different gaps.
     status = "partial";
-    errors.push(
-      "one or more stamps carries no anchor_ref — sealed by Sanning, witnessed by nobody",
-    );
+    if (gatewayUnavailable) {
+      errors.push("one or more stamps could not be re-fetched from the supplied gateways");
+    }
+    if (anyUnwitnessed) {
+      // The honest half of P-10, one layer up. A stamp with no `anchor_ref` is
+      // sealed and unwitnessed: `retained-by-sanning`, which is a statement
+      // about our coverage and never an accusation about their evidence. It is
+      // also not `verified`, because for a stamp the witness is the entire
+      // independent part — unlike an anchor-trace checkpoint, which still
+      // carries a producer signature and an inclusion proof that stand on
+      // their own offline.
+      errors.push(
+        "one or more stamps carries no anchor_ref — sealed by Sanning, witnessed by nobody",
+      );
+    }
   } else {
     status = "verified";
   }
@@ -1582,7 +1706,7 @@ async function verifyStampTrace(
     bodyHashOk: true,
     signatureOk: true,
     bodyType: STAMP_TRACE_BODY_TYPE,
-    onChainChecked: false,
+    onChainChecked,
     checkpoints: [],
     events: [],
     assertedStatus,
@@ -1591,6 +1715,320 @@ async function verifyStampTrace(
   };
 }
 
+// ===========================================================================
+// `sanning.stamp.evidence/v1` — the two halves, bound (evidence-bundle.md §5.3)
+//
+// The stamp half is §5.2's code unchanged (`verifyStampEntry`, which carries
+// the sub-tree partition check). The event half reuses the same primitives the
+// anchor-trace path uses — `verifyEnvelope`, `verifyInclusion`, `leafHash`,
+// `verifyDisclosedContent` — because a second copy of Merkle verification is a
+// second place for it to drift.
+//
+// What differs, and only this: the join. An event resolves `inclusion.stamp_ref`
+// to a stamps[] entry and walks its audit path to the root committed INSIDE
+// that stamp's witnessed bytes. There is no `merkle_root` field on the event to
+// read instead — repeating the root beside its own authoritative bytes would be
+// two answers to one question inside one signature (§5.1.2).
+// ===========================================================================
+async function verifyStampEvidence(
+  b: EvidenceBundle,
+  specVersionOk: boolean,
+  assertedStatus: string | null,
+  errors: string[],
+  options: VerifyEvidenceOptions,
+): Promise<EvidenceBundleResult> {
+  const body = b.body as StampEvidenceBody;
+  if (!Array.isArray(body?.stamps) || !Array.isArray(body?.events)) {
+    return malformed(`${STAMP_EVIDENCE_BODY_TYPE} body must have stamps[] and events[]`, true);
+  }
+
+  // --- The stamp half: §5.2's rules, §5.2's code ----------------------------
+  const seen = new Set<string>();
+  const stamps: StampResult[] = [];
+  const witnessed: (string | undefined)[] = [];
+  for (const entry of body.stamps) {
+    const outcome = await verifyStampEntry(entry, seen);
+    stamps.push(outcome.result);
+    witnessed.push(outcome.witnessedHex);
+  }
+
+  // The join table. ONLY a stamp whose derived ref and witnessed bytes both
+  // checked out is joinable: a root read out of bytes that failed their own
+  // verification is not a root anyone should walk a proof to, and admitting one
+  // would let a broken stamp lend its authority to an event.
+  const byRef = new Map<string, StampResult>();
+  for (const st of stamps) {
+    if (st.stampRef && st.stampRefOk && st.bodyOk) byRef.set(st.stampRef, st);
+  }
+
+  // --- The event half -------------------------------------------------------
+  const eventResults: EventResult[] = [];
+  for (const rawEv of body.events) {
+    const evErrors: string[] = [];
+    // A verifier must never RAISE on adversarial input — a caller handed a
+    // stack trace instead of a verdict cannot tell a malformed pack from a
+    // broken tool. `events[]` is attacker-shaped, so a null/non-object entry
+    // is coerced to an empty event and fails through the normal path, exactly
+    // as the Python kernel does. Found by adversarial review, not by the
+    // cross-kernel leg — whose cases did not include one, and now do.
+    if (rawEv === null || typeof rawEv !== "object" || Array.isArray(rawEv)) {
+      // NOT an event. Graded and reported as such rather than coerced to an
+      // empty one: probing verifyEnvelope with nothing asks the envelope layer
+      // a question about an object that was never an envelope, and the two
+      // kernels answer it differently (undetermined vs failed) — a real
+      // divergence, but not this body's to resolve. Reported separately.
+      eventResults.push({
+        eventId: "<unknown>",
+        envelopeOk: false,
+        payloadBindingOk: null,
+        inclusionOk: false,
+        checkpointBound: false,
+        contentOk: null,
+        ok: false,
+        errors: ["events[] entry is not an object"],
+      });
+      continue;
+    }
+    const ev = rawEv as StampEvidenceEvent;
+    const eventId = getEventId(ev.envelope);
+    let envelopeOk = false;
+    let payloadBindingOk: boolean | null = null;
+
+    let recordBytes: Uint8Array | undefined;
+    try {
+      if (typeof ev.record_bytes === "string") recordBytes = hexToBytes(ev.record_bytes);
+    } catch (e) {
+      evErrors.push(`event record_bytes is not hex: ${stringifyErr(e)}`);
+    }
+    try {
+      const res = await verifyEnvelope(
+        ev.envelope,
+        recordBytes !== undefined ? { payloadBytes: recordBytes } : {},
+      );
+      envelopeOk = res.ok; // tolerates an undetermined binding (withheld record)
+      payloadBindingOk = res.payloadHashOk;
+      if (!res.signatureOk) evErrors.push("event envelope signature failed");
+      if (res.payloadHashOk === false) evErrors.push("event record does not bind to payload_hash");
+    } catch (e) {
+      evErrors.push(`event envelope verify error: ${stringifyErr(e)}`);
+    }
+
+    // --- The join (§5.3.3 rule 1) -------------------------------------------
+    const incl = ev.inclusion as (StampEvidenceInclusion & Record<string, unknown>) | undefined;
+    let st: StampResult | undefined;
+    if (!incl || typeof incl !== "object") {
+      evErrors.push("event missing inclusion proof");
+    } else if (incl.checkpoint_ref !== undefined || incl.checkpoint_tx_id !== undefined) {
+      // One bundle speaks one vocabulary. An inclusion carrying an anchor-trace
+      // join key inside this body is a mixed bundle, and resolving it anyway is
+      // how an event silently binds to something nobody meant (§5.1.2).
+      evErrors.push(
+        `event inclusion carries an anchor-trace join key in a ${STAMP_EVIDENCE_BODY_TYPE} body`,
+      );
+    } else if (typeof incl.stamp_ref !== "string") {
+      evErrors.push("event inclusion missing stamp_ref");
+    } else {
+      st = byRef.get(incl.stamp_ref);
+      if (st === undefined) {
+        // Hard reject, never undetermined: without a resolved stamp the
+        // inclusion proof has no root to check against at all.
+        evErrors.push(
+          `event inclusion.stamp_ref ${JSON.stringify(incl.stamp_ref)} resolves to no verified stamp`,
+        );
+      }
+    }
+    const stampBound = st !== undefined;
+
+    let inclusionOk = false;
+    if (incl && stampBound && st) {
+      // Rule 3: the tree walked must be the tree the stamp committed to. A
+      // proof walked against a different leaf_count is a proof about a
+      // different tree, and RFC 9162's path shape depends on the size.
+      if (st.leafCount !== null && incl.leaf_count !== st.leafCount) {
+        evErrors.push(
+          `inclusion leaf_count ${incl.leaf_count} does not equal the stamp's committed ` +
+            `leaf_count ${st.leafCount}`,
+        );
+      } else {
+        try {
+          inclusionOk = await verifyInclusion(
+            hexToBytes(incl.leaf_hash),
+            incl.leaf_index,
+            incl.leaf_count,
+            (incl.audit_path ?? []).map((h) => hexToBytes(h)),
+            hexToBytes(st.merkleRoot ?? ""),
+          );
+          if (!inclusionOk) {
+            evErrors.push("RFC 9162 inclusion proof did not reconstruct the stamp root");
+          }
+
+          // Defense in depth, as §5.1: the claimed leaf MUST be this event's
+          // own signed envelope bytes, or a valid proof for an UNRELATED leaf
+          // could be smuggled in.
+          const expectedLeafHex = toHex(await leafHash(utf8(jcs(ev.envelope))));
+          if (expectedLeafHex !== (incl.leaf_hash ?? "").toLowerCase()) {
+            inclusionOk = false;
+            evErrors.push(
+              "inclusion leaf_hash does not match SHA-256(0x00 || JCS(event envelope))",
+            );
+          }
+        } catch (e) {
+          evErrors.push(`inclusion verify error: ${stringifyErr(e)}`);
+        }
+      }
+    }
+
+    const contentRes = await verifyDisclosedContent(ev, eventId, recordBytes, options.content);
+    const contentOk = contentRes.contentOk;
+    evErrors.push(...contentRes.errors);
+
+    eventResults.push({
+      eventId,
+      envelopeOk,
+      payloadBindingOk,
+      inclusionOk,
+      // Named for §5.1's join; here it reports whether `stamp_ref` resolved.
+      checkpointBound: stampBound,
+      contentOk,
+      ok: envelopeOk && inclusionOk && stampBound && contentOk !== false,
+      errors: evErrors,
+    });
+  }
+
+  // --- The optional on-chain re-fetch (§5.2.4's "online act") ---------------
+  const { onChainChecked, gatewayUnavailable } = await refetchStamps(
+    stamps,
+    witnessed,
+    options,
+    errors,
+  );
+
+  // --- Rollup ---------------------------------------------------------------
+  // Rule 4: a declared event MUST be checked. `events[]` present and unverified
+  // is the false green this body exists to prevent, so an event that did not
+  // verify fails the bundle — it is never rolled up as verified.
+  const anyHardFailure = stamps.some((st) => !st.ok) || eventResults.some((e) => !e.ok);
+  const anyUnwitnessed = stamps.some((st) => st.anchorRef === null);
+
+  let status: EvidenceStatus;
+  if (anyHardFailure) {
+    status = "failed";
+  } else if (stamps.length === 0 && eventResults.length === 0) {
+    status = "partial";
+    errors.push(`${STAMP_EVIDENCE_BODY_TYPE} body carries no stamps and no events`);
+  } else if (gatewayUnavailable || anyUnwitnessed) {
+    // Both hold the bundle at `partial`, and BOTH get said. A stamp nobody
+    // witnessed and a witness we could not reach are different gaps with
+    // different fixes — one waits for the interval, the other for the network —
+    // and an auditor told only about the second would read the first as fine.
+    // The order is fixed so the two kernels emit the same list.
+    status = "partial";
+    if (gatewayUnavailable) {
+      errors.push("one or more stamps could not be re-fetched from the supplied gateways");
+    }
+    if (anyUnwitnessed) {
+      // §5.3.3 rule 6, inherited whole from §5.2.4: for a stamp the witness IS
+      // the independent part, so the events resting on it inherit `partial`.
+      errors.push(
+        "one or more stamps carries no anchor_ref — sealed by Sanning, witnessed by nobody",
+      );
+    }
+  } else {
+    status = "verified";
+  }
+
+  return {
+    status,
+    specVersionOk,
+    bodyHashOk: true,
+    signatureOk: true,
+    bodyType: STAMP_EVIDENCE_BODY_TYPE,
+    onChainChecked,
+    checkpoints: [],
+    events: eventResults,
+    assertedStatus,
+    stamps,
+    errors,
+  };
+}
+
+/**
+ * The optional on-chain re-fetch over `stamps[]`, shared by §5.2 and §5.3.
+ *
+ * ── Why the results land on `stamps[]` and `checkpoints` stays empty ──
+ *
+ * A stamp body carries no checkpoints. Synthesising `CheckpointResult`s to
+ * carry these outcomes would make a stamp indistinguishable from a checkpoint
+ * in every consumer that reads `checkpoints[]` — the exact conflation §5.2.1
+ * and §5.3.1 refused twice, most sharply in "a Sanning attestation
+ * indistinguishable on the wire from a producer's". They are different
+ * artifacts with different signers and different meanings when absent, and a
+ * reader must never have to guess which one it is holding. So the stamp
+ * results go on the stamps, and `checkpoints: []` keeps saying the true thing:
+ * this body has none.
+ *
+ * ── Why an unwitnessed stamp gets `onChain: null` and NOT all-unreachable ──
+ *
+ * The anchor-trace path synthesises an all-`unreachable` result for a
+ * checkpoint with no `anchor_ref`. That is not copied here, for two reasons.
+ *
+ * It would be untrue: nothing was asked of any gateway, so reporting that
+ * every gateway failed to answer invents a network event. "Not checked" and
+ * "we asked and nobody answered" are different facts, and collapsing them is
+ * precisely the defect that had a surface reporting an unreachable gateway
+ * when it had contacted none.
+ *
+ * And it would be load-bearing in the wrong direction. Over there the
+ * synthesis exists to drive `gatewayUnavailable`, which is what downgrades that
+ * run to `partial`. Here §5.2.4 already downgrades an unwitnessed stamp to
+ * `partial` on its own, with a better error. Copying the synthesis would add
+ * nothing to the status and would silently move the CLI exit code from 0 to 3
+ * for an unwitnessed stamp — changing what an auditor's script does, based on
+ * nothing but whether the caller happened to pass a gateway list.
+ */
+async function refetchStamps(
+  stamps: StampResult[],
+  witnessed: (string | undefined)[],
+  options: VerifyEvidenceOptions,
+  errors: string[],
+): Promise<{ onChainChecked: boolean; gatewayUnavailable: boolean }> {
+  const gateways = options.gateways ?? [];
+  const onChainChecked = gateways.length > 0;
+  if (!onChainChecked) return { onChainChecked, gatewayUnavailable: false };
+
+  const fetchImpl = options.fetchImpl ?? (globalThis.fetch as typeof fetch | undefined);
+  if (typeof fetchImpl !== "function") {
+    errors.push("on-chain re-fetch requested but no fetch implementation is available");
+    return { onChainChecked, gatewayUnavailable: true };
+  }
+
+  let gatewayUnavailable = false;
+  for (let i = 0; i < stamps.length; i++) {
+    const st = stamps[i]!;
+    const witnessedHex = witnessed[i];
+    // No witness named, or bytes we could not read: nothing to re-fetch, and
+    // nothing a gateway could confirm or deny. Left as `onChain: null`.
+    if (st.anchorRef === null || witnessedHex === undefined) continue;
+
+    const outcome = await refetchStamp(witnessedHex, st.anchorRef, gateways, fetchImpl);
+    st.onChain = outcome.onChain;
+    st.onChainOk = outcome.onChain.onChainOk;
+    if (outcome.unavailable) gatewayUnavailable = true;
+    if (outcome.error) st.errors.push(outcome.error);
+    // Fold the on-chain dimension in exactly as a checkpoint does: a MISMATCH
+    // (false) fails the stamp — the chain does not hold what the bundle says
+    // was witnessed. UNREACHABLE (null) leaves an offline-sound stamp ok and
+    // downgrades the run to `partial` via gatewayUnavailable. A confirm (true)
+    // changes nothing that was not already true offline.
+    //
+    // `st.ok` is kept and narrowed rather than recomputed: its offline form
+    // includes `errors.length === 0`, and re-evaluating that AFTER pushing an
+    // unreachable note would fail a stamp for a gateway being down.
+    st.ok = st.ok && st.onChainOk !== false;
+  }
+  return { onChainChecked, gatewayUnavailable };
+}
+
 // ===========================================================================
 // Ingest: materializing the disclosed raw bytes (evidence-bundle.md §5.1).
 //
@@ -2362,6 +2800,10 @@ async function refetchCheckpoint(
 ): Promise<{ onChain: OnChainResult; unavailable: boolean; error?: string }> {
   let expectedHex: string | undefined;
   try {
+    // A checkpoint's witnessed bytes are its envelope RE-CANONICALIZED. The
+    // bundle carries the envelope as a JSON object, not as bytes, so what was
+    // uploaded has to be recomputed from it. See `refetchStamp` for the case
+    // where this step is not merely unnecessary but WRONG.
     expectedHex = toHex(utf8(jcs(cp.envelope)));
   } catch {
     // Cannot canonicalize the checkpoint envelope — every gateway is a mismatch
@@ -2369,6 +2811,54 @@ async function refetchCheckpoint(
     expectedHex = undefined;
   }
 
+  return refetchAnchored("checkpoint", expectedHex, anchorRef, gateways, fetchImpl);
+}
+
+// Re-fetch a STAMP's witnessed bytes (evidence-bundle.md §5.2.2 / §5.3.2).
+//
+// ── The one step this path must NOT copy from the checkpoint path ──
+//
+// `refetchCheckpoint` recomputes `JCS(envelope)` because a checkpoint's
+// witnessed bytes are not in the bundle — only the object they were derived
+// from is. A stamp is the opposite case: §5.2.2 defines `stamp_bytes` as
+// "lowercase hex of the exact JCS bytes that were handed to the witness", and
+// §5.3.2 repeats it — *"the EXACT bytes that were witnessed, verbatim"*. They
+// are already the bytes, already hex, already lowercase (`isLowerHex` gated
+// them), and `stamp_ref` is their SHA-256.
+//
+// So the expected hex IS `stamp_bytes`, and re-canonicalizing would be a
+// defect, not a redundancy: it would compare the chain against bytes NOBODY
+// SIGNED. On a canonical body the two agree and the bug hides; on a body that
+// is not canonical — the exact case §5.2.2 makes the kernel check for, because
+// the plane replays these bytes as text precisely so a normalizing serializer
+// cannot alter them — a re-canonicalizing verifier reports `mismatch` against
+// a chain that faithfully holds what it was given. A false accusation, from
+// the verifier, about untampered evidence.
+//
+// The bytes handed here are the SAME value `verifyStampEntry` hashed to derive
+// `stamp_ref`, threaded through rather than re-read from the body, so the bytes
+// graded and the bytes compared cannot drift apart.
+async function refetchStamp(
+  witnessedHex: string,
+  anchorRef: AnchorRef,
+  gateways: string[],
+  fetchImpl: typeof fetch,
+): Promise<{ onChain: OnChainResult; unavailable: boolean; error?: string }> {
+  return refetchAnchored("stamp", witnessedHex, anchorRef, gateways, fetchImpl);
+}
+
+// The part both paths share: probe every gateway, roll the outcomes up under
+// the ONE rule (`rollupOnChain`), and phrase the finding. Extracted rather than
+// copied — a second rollup rule is a second place for "mismatch beats confirm
+// beats unreachable" to drift, and the drifted copy is the one nobody reads.
+// The subject only ever selects wording; it never changes a verdict.
+async function refetchAnchored(
+  subject: "checkpoint" | "stamp",
+  expectedHex: string | undefined,
+  anchorRef: AnchorRef,
+  gateways: string[],
+  fetchImpl: typeof fetch,
+): Promise<{ onChain: OnChainResult; unavailable: boolean; error?: string }> {
   const perGateway: PerGatewayOutcome[] = [];
   for (const gw of gateways) {
     perGateway.push({
@@ -2380,9 +2870,12 @@ async function refetchCheckpoint(
   const onChain = rollupOnChain(perGateway);
   let error: string | undefined;
   if (onChain.rollup === "mismatch") {
-    error = `on-chain bytes at ${anchorRef.id} do not match the bundle's checkpoint envelope`;
+    error =
+      subject === "checkpoint"
+        ? `on-chain bytes at ${anchorRef.id} do not match the bundle's checkpoint envelope`
+        : `on-chain bytes at ${anchorRef.id} do not match the stamp's witnessed bytes`;
   } else if (onChain.rollup === "unreachable") {
-    error = `checkpoint ${anchorRef.id} unreachable on all gateways`;
+    error = `${subject} ${anchorRef.id} unreachable on all gateways`;
   }
   return { onChain, unavailable: onChain.rollup === "unreachable", error };
 }