@sanning/proof 0.7.0 → 0.8.1

package/dist/evidence.js

@@ -61,6 +61,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
  * the `body_type` above, and the two are easy to confuse.
@@ -193,7 +194,11 @@ export async function verifyEvidenceBundle(bundle, options = {}) {
     // 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) {
         // The wrapper is authentic but we don't know this body's structure. Per
@@ -523,75 +528,10 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
                 evErrors.push(`inclusion verify error: ${stringifyErr(e)}`);
             }
         }
-        // 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 = null;
-        {
-            const committed = [];
-            let recordContentHash;
-            if (recordBytes !== undefined) {
-                try {
-                    const record = JSON.parse(new TextDecoder().decode(recordBytes));
-                    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,
             envelopeOk,
@@ -748,6 +688,72 @@ function isNonNegInt(n) {
  * 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, eventId, recordBytes, sideContent) {
+    const evErrors = [];
+    let contentOk = null;
+    const committed = [];
+    let recordContentHash;
+    if (recordBytes !== undefined) {
+        try {
+            const record = JSON.parse(new TextDecoder().decode(recordBytes));
+            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))
+            committed.push(c.hash.toLowerCase());
+    }
+    const selection = selectDisclosedBytes(ev, 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 };
+}
 async function verifyStampEntry(raw, seen) {
     const errors = [];
     const base = {
@@ -762,18 +768,20 @@ async function verifyStampEntry(raw, seen) {
         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;
     // --- 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;
     try {
@@ -781,8 +789,11 @@ async function verifyStampEntry(raw, seen) {
     }
     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 = e.stamp_bytes;
     // --- the derived identity -------------------------------------------------
     const derived = await sha256Hex(bytes);
     if (typeof e.stamp_ref !== "string" || e.stamp_ref === "") {
@@ -812,7 +823,7 @@ async function verifyStampEntry(raw, seen) {
         const parsed = 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;
         // Re-canonicalize and compare. The plane replays these bytes verbatim on
@@ -821,12 +832,12 @@ async function verifyStampEntry(raw, seen) {
         // of the stamp disagree with the one that was witnessed.
         if (jcs(body) !== 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) {
         // A `sanning.stamp.trace/v1` body whose inner version is something else is
@@ -835,7 +846,7 @@ async function verifyStampEntry(raw, seen) {
         // how a reader half-parses a shape it does not know.
         errors.push(`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;
@@ -866,7 +877,7 @@ async function verifyStampEntry(raw, seen) {
     base.anchorRef = parseAnchorRef(e.anchor_ref, errors);
     base.ok =
         base.stampRefOk && base.bodyOk && base.subtreesOk && errors.length === 0;
-    return base;
+    return { result: base, witnessedHex };
 }
 /**
  * The range arithmetic (§5.2), and the reason it is a hard check.
@@ -942,16 +953,27 @@ function checkSubtrees(body, out, errors) {
     }
     return true;
 }
-async function verifyStampTrace(b, specVersionOk, assertedStatus, errors) {
+async function verifyStampTrace(b, specVersionOk, assertedStatus, errors, options) {
     const body = b.body;
     if (!Array.isArray(body?.stamps)) {
         return malformed(`${STAMP_TRACE_BODY_TYPE} body must have stamps[]`, true);
     }
     const seen = new Set();
     const stamps = [];
+    const witnessed = [];
     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);
@@ -966,15 +988,23 @@ async function verifyStampTrace(b, specVersionOk, assertedStatus, errors) {
         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";
@@ -985,7 +1015,7 @@ async function verifyStampTrace(b, specVersionOk, assertedStatus, errors) {
         bodyHashOk: true,
         signatureOk: true,
         bodyType: STAMP_TRACE_BODY_TYPE,
-        onChainChecked: false,
+        onChainChecked,
         checkpoints: [],
         events: [],
         assertedStatus,
@@ -993,6 +1023,285 @@ async function verifyStampTrace(b, specVersionOk, assertedStatus, errors) {
         errors,
     };
 }
+// ===========================================================================
+// `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, specVersionOk, assertedStatus, errors, options) {
+    const body = b.body;
+    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();
+    const stamps = [];
+    const witnessed = [];
+    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();
+    for (const st of stamps) {
+        if (st.stampRef && st.stampRefOk && st.bodyOk)
+            byRef.set(st.stampRef, st);
+    }
+    // --- The event half -------------------------------------------------------
+    const eventResults = [];
+    for (const rawEv of body.events) {
+        const evErrors = [];
+        // 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;
+        const eventId = getEventId(ev.envelope);
+        let envelopeOk = false;
+        let payloadBindingOk = null;
+        let recordBytes;
+        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;
+        let st;
+        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;
+    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, witnessed, options, errors) {
+    const gateways = options.gateways ?? [];
+    const onChainChecked = gateways.length > 0;
+    if (!onChainChecked)
+        return { onChainChecked, gatewayUnavailable: false };
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    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 };
+}
 // How many `sanning.evidence.export/v1` wrappers deep the source bundle may be
 // nested before this path gives up. verifyEvidenceBundle's canonicalization
 // depth bound already rejects a pathological bundle, but the unwrap must be
@@ -1605,6 +1914,10 @@ function summarizeExport(status, source, attestations) {
 async function refetchCheckpoint(cp, anchorRef, gateways, fetchImpl) {
     let expectedHex;
     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 {
@@ -1612,6 +1925,41 @@ async function refetchCheckpoint(cp, anchorRef, gateways, fetchImpl) {
         // (we can never confirm bytes we cannot compute).
         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, anchorRef, gateways, fetchImpl) {
+    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, expectedHex, anchorRef, gateways, fetchImpl) {
     const perGateway = [];
     for (const gw of gateways) {
         perGateway.push({
@@ -1622,10 +1970,13 @@ async function refetchCheckpoint(cp, anchorRef, gateways, fetchImpl) {
     const onChain = rollupOnChain(perGateway);
     let error;
     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 };
 }