@sanning/proof 0.4.0

package/dist/evidence.js

@@ -0,0 +1,1049 @@
+// Evidence-bundle verification (sanning-io/proof specs/evidence-bundle.md).
+//
+// A `sanning.evidence/v1` bundle is a SIGNED wrapper around a producer-specific
+// `body`. This module verifies the `sanning.anchor.trace/v1` body — the
+// @ar.io/anchor SDK trace: a self-verifying serialization of InclusionReceipt[]
+// (per-event signed envelopes + their checkpoints + RFC 9162 inclusion proofs).
+//
+// The algorithm is the kernel discipline applied one level up (evidence-bundle
+// §1, §4): inherit-don't-invent (same JCS, SHA-256, Ed25519), wrap-don't-merge
+// (the body is opaque to the wrapper), recompute-don't-trust-the-verdict
+// (every claim is re-derived from `body`, never read off `verdict.status`),
+// reject-unknown-major. No Sanning service is in the trust path: the bundle is
+// self-verifying offline against the embedded `public_key`; the optional
+// gateway re-fetch only confirms the checkpoints are anchored on-chain.
+//
+// Scope: this verifies a SINGLE evidence bundle. Chain walking over
+// `previous_hash` across successive exports is consumer-layer logic above it.
+import { deriveOperatorAddress, ed25519Verify, hexToBytes, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
+import { leafHash, verifyInclusion } from "./merkle.js";
+import { MAX_CANONICAL_DEPTH, contentHashes, exceedsDepth, jcs, verifyEnvelope, } from "./verifier.js";
+// Only the evidence-bundle major(s) this kernel verifies. A new major is a
+// deliberate one-entry addition HERE — same fail-closed discipline as the
+// envelope verifier's ACCEPTED_SPEC_MAJORS.
+const ACCEPTED_EVIDENCE_MAJORS = ["sanning.evidence/v1"];
+// The body_type this module knows how to verify structurally. An unknown
+// body_type is not a hard failure of the WRAPPER (the signature + body_hash
+// still verify), but its body cannot be re-derived, so the per-body verdict is
+// "undetermined" rather than "verified".
+export const ANCHOR_TRACE_BODY_TYPE = "sanning.anchor.trace/v1";
+// The issuer-composed attested-evidence-export body (specs/evidence-export.md
+// §2). The wrapper is unchanged (`sanning.evidence/v1`, Ed25519-signed); this body
+// carries a cached verdict + the inline source bundle + embedded RSA-PSS
+// operator attestations. verifyEvidenceBundle dispatches on it to
+// verifyExportBody (§5).
+export const EXPORT_BODY_TYPE = "sanning.evidence.export/v1";
+function isEvidenceMajorAccepted(specVersion) {
+    if (typeof specVersion !== "string" || specVersion === "")
+        return false;
+    return ACCEPTED_EVIDENCE_MAJORS.some((m) => {
+        if (specVersion === m)
+            return true;
+        if (!specVersion.startsWith(`${m}.`))
+            return false;
+        const minor = specVersion.slice(m.length + 1);
+        return minor.length > 0 && /^[0-9]+$/.test(minor);
+    });
+}
+function malformed(error, specVersionOk = false) {
+    return {
+        status: "malformed",
+        specVersionOk,
+        bodyHashOk: false,
+        signatureOk: false,
+        bodyType: null,
+        onChainChecked: false,
+        checkpoints: [],
+        events: [],
+        assertedStatus: null,
+        errors: [error],
+    };
+}
+function stringifyErr(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+// Verify a `sanning.evidence/v1` bundle carrying a `sanning.anchor.trace/v1` body.
+//
+// Returns a structured per-checkpoint + per-event result and a recomputed
+// rollup `status`. The producer's asserted `verdict.status` is surfaced
+// (`assertedStatus`) but NEVER trusted — the displayed status is the one this
+// function recomputes (evidence-bundle §1 principle 3 / §4 step 4).
+export async function verifyEvidenceBundle(bundle, options = {}) {
+    // --- Step 1: parse + reject unknown spec_version major ---------------------
+    if (bundle === null || typeof bundle !== "object" || Array.isArray(bundle)) {
+        return malformed("evidence bundle is not a JSON object");
+    }
+    // Reject a pathologically deep bundle BEFORE any canonicalization (which
+    // recurses). A fixed shared bound keeps this a `malformed` verdict in every
+    // kernel rather than a stack-limit-dependent split verdict — see
+    // MAX_CANONICAL_DEPTH.
+    if (exceedsDepth(bundle, MAX_CANONICAL_DEPTH)) {
+        return malformed(`evidence bundle nesting exceeds the ${MAX_CANONICAL_DEPTH}-level canonicalization depth bound`);
+    }
+    const b = bundle;
+    const specVersionOk = isEvidenceMajorAccepted(b.spec_version);
+    if (!specVersionOk) {
+        return malformed(`unsupported evidence spec_version: ${JSON.stringify(b.spec_version)}`, false);
+    }
+    if (typeof b.signature_alg === "string" && b.signature_alg !== "ed25519") {
+        // The reference verifier implements ed25519 only (evidence-bundle §2 +
+        // decision #2); other algs are a deliberate future addition.
+        return malformed(`unsupported signature_alg: ${JSON.stringify(b.signature_alg)}`, true);
+    }
+    if (typeof b.public_key !== "string" || typeof b.signature !== "string") {
+        return malformed("evidence bundle is missing public_key/signature", true);
+    }
+    if (typeof b.body_hash !== "string") {
+        return malformed("evidence bundle is missing body_hash", true);
+    }
+    if (b.body === undefined || b.body === null) {
+        // body_ref (out-of-line body) is a defined growth hook but not part of the
+        // anchor-trace use case — refuse rather than silently pass.
+        return malformed("evidence bundle has no inline body (body_ref unsupported here)", true);
+    }
+    // --- Step 2: verify the wrapper signature + recompute body_hash ------------
+    const errors = [];
+    let bodyHashOk = false;
+    try {
+        const recomputed = await sha256Hex(utf8(jcs(b.body)));
+        bodyHashOk = recomputed === b.body_hash;
+        if (!bodyHashOk) {
+            errors.push(`body_hash mismatch: bundle=${b.body_hash} recomputed=${recomputed}`);
+        }
+    }
+    catch (e) {
+        errors.push(`body canonicalization failed: ${stringifyErr(e)}`);
+    }
+    let signatureOk = false;
+    try {
+        const { signature: _sig, co_signatures: _co, ...bundleForSig } = b;
+        signatureOk = await ed25519Verify(b.signature, utf8(jcs(bundleForSig)), b.public_key);
+        if (!signatureOk)
+            errors.push("wrapper Ed25519 signature verification failed");
+    }
+    catch (e) {
+        errors.push(`wrapper signature verification error: ${stringifyErr(e)}`);
+    }
+    const assertedStatus = typeof b.verdict?.status === "string" ? b.verdict.status : null;
+    // A broken wrapper (bad signature or tampered body) is a hard failure — the
+    // body is untrustworthy, so we do not pretend to verify its contents.
+    if (!signatureOk || !bodyHashOk) {
+        return {
+            status: "failed",
+            specVersionOk,
+            bodyHashOk,
+            signatureOk,
+            bodyType: typeof b.body_type === "string" ? b.body_type : null,
+            onChainChecked: false,
+            checkpoints: [],
+            events: [],
+            assertedStatus,
+            errors,
+        };
+    }
+    // --- Body dispatch ---------------------------------------------------------
+    const bodyType = typeof b.body_type === "string" ? b.body_type : null;
+    // Attested-evidence-export body (evidence-export.md §5). The wrapper is
+    // authentic (Ed25519 issuer signature + body_hash verified above, §5 step 2);
+    // hand off to the export verifier for steps 3–9.
+    if (bodyType === EXPORT_BODY_TYPE) {
+        return verifyExportBody(b, specVersionOk, assertedStatus, errors, options);
+    }
+    if (bodyType !== ANCHOR_TRACE_BODY_TYPE) {
+        // The wrapper is authentic but we don't know this body's structure. Per
+        // wrap-don't-merge, that is "partial" (cryptographically sound wrapper,
+        // body verdict undetermined) — not a failure.
+        errors.push(`body_type ${JSON.stringify(bodyType)} is not verifiable by this kernel ` +
+            `(only ${ANCHOR_TRACE_BODY_TYPE}); wrapper verified, body undetermined`);
+        return {
+            status: "partial",
+            specVersionOk,
+            bodyHashOk,
+            signatureOk,
+            bodyType,
+            onChainChecked: false,
+            checkpoints: [],
+            events: [],
+            assertedStatus,
+            errors,
+        };
+    }
+    return verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, errors, options);
+}
+async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, errors, options) {
+    const body = b.body;
+    if (!Array.isArray(body.checkpoints) || !Array.isArray(body.events)) {
+        return malformed("sanning.anchor.trace/v1 body must have checkpoints[] and events[]", true);
+    }
+    const gateways = options.gateways ?? [];
+    const onChainChecked = gateways.length > 0;
+    // --- Step 3: per-checkpoint -------------------------------------------------
+    const byTxId = new Map();
+    const checkpointResults = [];
+    for (const cp of body.checkpoints) {
+        const cpErrors = [];
+        let envelopeOk = false;
+        let merkleRootOk = false;
+        if (typeof cp.tx_id !== "string") {
+            cpErrors.push("checkpoint missing tx_id");
+        }
+        else if (byTxId.has(cp.tx_id)) {
+            cpErrors.push(`duplicate checkpoint tx_id ${cp.tx_id}`);
+        }
+        else {
+            byTxId.set(cp.tx_id, cp);
+        }
+        // Verify the checkpoint envelope against its committed record (external
+        // commitment — the record is the payload these external envelopes bind to).
+        let recordBytes;
+        try {
+            if (typeof cp.record_bytes === "string")
+                recordBytes = hexToBytes(cp.record_bytes);
+        }
+        catch (e) {
+            cpErrors.push(`checkpoint record_bytes is not hex: ${stringifyErr(e)}`);
+        }
+        try {
+            const res = await verifyEnvelope(cp.envelope, recordBytes !== undefined ? { payloadBytes: recordBytes } : {});
+            // A checkpoint must fully bind: signature + the committed record matching
+            // payload_hash. An undetermined binding (no record) is not enough to
+            // anchor the events' inclusion claims to a trustworthy root.
+            envelopeOk = res.ok && res.payloadHashOk === true;
+            if (!res.signatureOk)
+                cpErrors.push("checkpoint envelope signature failed");
+            if (res.payloadHashOk === false)
+                cpErrors.push("checkpoint record does not bind to payload_hash");
+            if (res.payloadHashOk === null)
+                cpErrors.push("checkpoint record_bytes missing — root untrusted");
+        }
+        catch (e) {
+            cpErrors.push(`checkpoint envelope verify error: ${stringifyErr(e)}`);
+        }
+        // The committed record's merkle_root must equal the checkpoint's claimed
+        // merkle_root (recompute, don't trust the bundle's top-level claim).
+        if (recordBytes !== undefined) {
+            try {
+                const record = JSON.parse(new TextDecoder().decode(recordBytes));
+                const committedRoot = record.event?.merkle_root;
+                merkleRootOk = typeof committedRoot === "string" && committedRoot === cp.merkle_root;
+                if (!merkleRootOk) {
+                    cpErrors.push(`checkpoint merkle_root mismatch: claimed=${cp.merkle_root} committed=${String(committedRoot)}`);
+                }
+            }
+            catch (e) {
+                cpErrors.push(`checkpoint record is not JSON: ${stringifyErr(e)}`);
+            }
+        }
+        checkpointResults.push({
+            txId: typeof cp.tx_id === "string" ? cp.tx_id : "",
+            envelopeOk,
+            merkleRootOk,
+            onChainOk: null, // filled in step 5 if a gateway re-fetch was requested
+            onChain: null, // per-gateway (§4.2), filled in step 5
+            ok: envelopeOk && merkleRootOk,
+            errors: cpErrors,
+        });
+    }
+    // --- Step 4: per-event ------------------------------------------------------
+    const eventResults = [];
+    for (const ev of body.events) {
+        const evErrors = [];
+        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; // 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)}`);
+        }
+        // Bind the event to exactly one checkpoint in the bundle, then verify
+        // RFC 9162 inclusion against THAT checkpoint's merkle_root.
+        const incl = ev.inclusion;
+        const cp = incl && typeof incl.checkpoint_tx_id === "string" ? byTxId.get(incl.checkpoint_tx_id) : undefined;
+        const checkpointBound = cp !== undefined;
+        if (!incl || typeof incl !== "object") {
+            evErrors.push("event missing inclusion proof");
+        }
+        else if (!checkpointBound) {
+            evErrors.push(`event inclusion.checkpoint_tx_id ${JSON.stringify(incl.checkpoint_tx_id)} resolves to no checkpoint`);
+        }
+        let inclusionOk = false;
+        if (incl && checkpointBound && cp) {
+            try {
+                inclusionOk = await verifyInclusion(hexToBytes(incl.leaf_hash), incl.leaf_index, incl.leaf_count, (incl.audit_path ?? []).map((h) => hexToBytes(h)), hexToBytes(cp.merkle_root));
+                if (!inclusionOk)
+                    evErrors.push("RFC 9162 inclusion proof did not reconstruct the checkpoint root");
+                // Defense in depth: the claimed leaf_hash MUST be the hash of the
+                // event's own signed envelope bytes (profile §6) — otherwise a valid
+                // inclusion proof for an UNRELATED leaf could be smuggled in.
+                const expectedLeaf = await leafHash(utf8(jcs(ev.envelope)));
+                const expectedLeafHex = toHex(expectedLeaf);
+                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)}`);
+            }
+        }
+        // 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.
+            let inBody;
+            if (typeof ev.content === "string") {
+                try {
+                    inBody = hexToBytes(ev.content);
+                }
+                catch (e) {
+                    evErrors.push(`event content is not hex: ${stringifyErr(e)}`);
+                }
+            }
+            let side;
+            const sideRaw = options.content?.[eventId];
+            if (sideRaw instanceof Uint8Array) {
+                side = sideRaw;
+            }
+            else if (typeof sideRaw === "string") {
+                try {
+                    side = hexToBytes(sideRaw);
+                }
+                catch (e) {
+                    evErrors.push(`supplied content for ${eventId} is not hex: ${stringifyErr(e)}`);
+                }
+            }
+            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("|")}`);
+                    }
+                }
+            }
+        }
+        eventResults.push({
+            eventId,
+            envelopeOk,
+            payloadBindingOk,
+            inclusionOk,
+            checkpointBound,
+            contentOk,
+            // An event is "ok" when its envelope is authentic (signature + binding
+            // not-failed), its inclusion proof reconstructs the root, it binds to a
+            // present checkpoint, and its disclosed content did not MISMATCH. A
+            // withheld record or undisclosed content (binding/content null) does not
+            // fail it.
+            ok: envelopeOk && inclusionOk && checkpointBound && contentOk !== false,
+            errors: evErrors,
+        });
+    }
+    // --- Step 5: optional on-chain re-fetch ------------------------------------
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    let gatewayUnavailable = false;
+    if (onChainChecked) {
+        if (typeof fetchImpl !== "function") {
+            gatewayUnavailable = true;
+            errors.push("on-chain re-fetch requested but no fetch implementation is available");
+        }
+        else {
+            for (const cpr of checkpointResults) {
+                const cp = byTxId.get(cpr.txId);
+                if (!cp)
+                    continue;
+                const outcome = await refetchCheckpoint(cp, gateways, fetchImpl);
+                cpr.onChain = outcome.onChain;
+                cpr.onChainOk = outcome.onChain.onChainOk;
+                if (outcome.unavailable)
+                    gatewayUnavailable = true;
+                if (outcome.error)
+                    cpr.errors.push(outcome.error);
+                // Fold the on-chain dimension in: a MISMATCH (false) fails the
+                // checkpoint — the proof was not anchored as claimed. An UNREACHABLE
+                // gateway (null) leaves the offline-sound checkpoint ok; the run
+                // downgrades to "partial" (exit 3) via gatewayUnavailable, not a hard
+                // failure. A match (true) keeps it ok.
+                cpr.ok = cpr.envelopeOk && cpr.merkleRootOk && cpr.onChainOk !== false;
+            }
+        }
+    }
+    // --- Rollup ----------------------------------------------------------------
+    const allCheckpointsOk = checkpointResults.length > 0 && checkpointResults.every((c) => c.ok);
+    const allEventsOk = eventResults.every((e) => e.ok);
+    const anyHardFailure = checkpointResults.some((c) => !c.ok) || eventResults.some((e) => !e.ok);
+    const anyWithheldRecord = eventResults.some((e) => e.payloadBindingOk === null);
+    let status;
+    if (anyHardFailure) {
+        status = "failed";
+    }
+    else if (gatewayUnavailable) {
+        // Every offline check passed and nothing MISMATCHED, but a requested
+        // on-chain confirmation could not be made — the bundle is offline-sound,
+        // its anchored state unconfirmed. "partial" + a note the CLI maps to exit 3.
+        status = "partial";
+        errors.push("one or more checkpoints could not be re-fetched from the supplied gateways");
+    }
+    else if (anyWithheldRecord) {
+        // Everything that COULD be checked passed; some record bytes were withheld
+        // so their semantic binding is undetermined (not a failure) — "partial".
+        status = "partial";
+    }
+    else if (allCheckpointsOk && allEventsOk) {
+        status = "verified";
+    }
+    else {
+        status = "partial";
+    }
+    return {
+        status,
+        specVersionOk,
+        bodyHashOk: true,
+        signatureOk: true,
+        bodyType,
+        onChainChecked,
+        checkpoints: checkpointResults,
+        events: eventResults,
+        assertedStatus,
+        errors,
+    };
+}
+// ===========================================================================
+// Attested-evidence-export verification (evidence-export.md §5, steps 3–9).
+// Reached from verifyEvidenceBundle AFTER the wrapper (Ed25519 issuer signature
+// + body_hash) has already verified (steps 1–2). This composes the existing
+// evidence path (recompute the inline source verdict) with the one new
+// primitive (embedded RSA-PSS operator attestations, verifyRsaPssSha256).
+// ===========================================================================
+async function verifyExportBody(b, specVersionOk, assertedStatus, errors, options) {
+    // Malformed-as-an-export (§5 exit 2): a required field is missing or a key is
+    // unparseable — the wrapper verified, but no verdict can be rendered. The
+    // wrapper fields stay true (they DID verify) for any consumer that inspects
+    // them; the CLI's malformed branch shows the errors and exits 2.
+    const exportMalformed = (error) => ({
+        status: "malformed",
+        specVersionOk,
+        bodyHashOk: true,
+        signatureOk: true,
+        bodyType: EXPORT_BODY_TYPE,
+        onChainChecked: false,
+        checkpoints: [],
+        events: [],
+        assertedStatus,
+        errors: [...errors, error],
+    });
+    const body = b.body;
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        return exportMalformed("export body is not a JSON object");
+    }
+    if (typeof body.source_bundle_hash !== "string") {
+        return exportMalformed("export body missing source_bundle_hash");
+    }
+    if (!Array.isArray(body.attestations)) {
+        return exportMalformed("export body missing attestations[]");
+    }
+    if (body.kernel_verdict === null ||
+        typeof body.kernel_verdict !== "object" ||
+        Array.isArray(body.kernel_verdict)) {
+        return exportMalformed("export body missing kernel_verdict");
+    }
+    // --- Step 3: source-bundle linkage ----------------------------------------
+    const inline = body.source_bundle;
+    if (inline === undefined || inline === null) {
+        // source_bundle_ref (out-of-line) is not verifiable on a network-isolated
+        // machine unless the referenced bytes are co-delivered — the source-
+        // dependent checks are UNDETERMINED (exit 3), NOT a failure (§5 step 3).
+        return {
+            status: "partial",
+            specVersionOk,
+            bodyHashOk: true,
+            signatureOk: true,
+            bodyType: EXPORT_BODY_TYPE,
+            onChainChecked: false,
+            checkpoints: [],
+            events: [],
+            assertedStatus,
+            errors: [
+                ...errors,
+                "source_bundle is not inline (source_bundle_ref) — bytes unavailable offline; " +
+                    "source-dependent checks undetermined",
+            ],
+        };
+    }
+    let sourceLinkageOk = false;
+    try {
+        const recomputed = await sha256Hex(utf8(jcs(inline)));
+        sourceLinkageOk = recomputed === body.source_bundle_hash;
+        if (!sourceLinkageOk) {
+            errors.push(`source_bundle_hash mismatch: body=${body.source_bundle_hash} recomputed=${recomputed}`);
+        }
+    }
+    catch (e) {
+        errors.push(`source_bundle canonicalization failed: ${stringifyErr(e)}`);
+    }
+    // --- Step 4: recompute the source verdict ---------------------------------
+    // The existing evidence path over the inline source bundle — same primitives
+    // (Ed25519 envelopes, payload binding, RFC 9162 inclusion, merkle roots,
+    // content_ok, and the optional per-gateway on-chain re-fetch, §4.2 / step 7).
+    const sourceResult = await verifyEvidenceBundle(inline, options);
+    // Map source checkpoints by tx_id for attestation data_hash binding (§5 6c).
+    const sourceCheckpoints = new Map();
+    const sb = inline.body;
+    if (sb && typeof sb === "object" && Array.isArray(sb.checkpoints)) {
+        for (const cp of sb.checkpoints) {
+            if (cp && typeof cp.tx_id === "string")
+                sourceCheckpoints.set(cp.tx_id, cp);
+        }
+    }
+    // --- Step 6: embedded attestation records ---------------------------------
+    const attestations = [];
+    for (const rec of body.attestations) {
+        const r = await verifyAttestation(rec, sourceCheckpoints);
+        if (r.malformed !== undefined)
+            return exportMalformed(r.malformed);
+        attestations.push(r.result);
+    }
+    // --- Build the recomputed §4 verdict object -------------------------------
+    const verdict = buildVerdictObject(sourceResult, attestations);
+    if (typeof b.generated_at === "string")
+        verdict.as_of = b.generated_at;
+    // --- Step 5: verdict agreement (DETERMINISTIC dimensions only) ------------
+    // The cached body.kernel_verdict is recompute-don't-trust (principle 3). But
+    // agreement compares ONLY the deterministic, offline-recomputable dimensions:
+    // per-event signature/payload-binding/inclusion/content, per-checkpoint
+    // merkle roots, and per-attestation signature/operator-address/data_hash
+    // binding. The on-chain per-gateway dimension is environment/time-dependent —
+    // the issuer observed it online at compose time; an offline verifier
+    // legitimately sees `null` — so it is INFORMATIONAL and MUST NOT by itself
+    // trigger an exit-1 tamper verdict (the verifier's own on-chain outcomes fold
+    // in at step 7 only if it re-fetches). Advisory rollups (status / counts /
+    // summary / as_of / custody_chain) are derived, not compared. See the §5
+    // step-5 erratum flagged in the slice report.
+    let verdictAgreementOk = false;
+    try {
+        const cachedProjection = jcs(projectVerdictForAgreement(body.kernel_verdict));
+        const freshProjection = jcs(projectVerdictForAgreement(verdict));
+        verdictAgreementOk = cachedProjection === freshProjection;
+        if (!verdictAgreementOk) {
+            errors.push("recomputed verdict disagrees with the cached kernel_verdict " +
+                "(deterministic dimensions) — recompute-don't-trust");
+        }
+    }
+    catch (e) {
+        errors.push(`verdict agreement comparison failed: ${stringifyErr(e)}`);
+    }
+    // --- Step 7 already folded in by the source recompute ---------------------
+    // (verifyEvidenceBundle merged per-gateway outcomes into sourceResult.status:
+    // a checkpoint `mismatch` made it "failed"; an all-`unreachable` checkpoint
+    // made it "partial" + an unreachable note → exit 3.)
+    // Propagate the source recompute's notes so the auditor — and the CLI's
+    // exit-3 detection (which keys off "unreachable") — see them.
+    for (const e of sourceResult.errors)
+        errors.push(`source: ${e}`);
+    // --- Step 9: export rollup + exit -----------------------------------------
+    const anyAttestationFailed = attestations.some((a) => !a.ok);
+    let status;
+    if (!sourceLinkageOk ||
+        !verdictAgreementOk ||
+        sourceResult.status === "failed" ||
+        sourceResult.status === "malformed" ||
+        anyAttestationFailed) {
+        status = "failed";
+    }
+    else if (sourceResult.status === "partial") {
+        // Undetermined source (withheld record → exit 0; gateway-unreachable →
+        // exit 3 via the propagated "unreachable" note). Never a failure.
+        status = "partial";
+    }
+    else {
+        status = "verified";
+    }
+    // The DISPLAYED verdict reflects the full recompute (incl. attestations).
+    verdict.status = status;
+    verdict.summary = summarizeExport(status, sourceResult, attestations);
+    return {
+        status,
+        specVersionOk,
+        bodyHashOk: true,
+        signatureOk: true,
+        bodyType: EXPORT_BODY_TYPE,
+        onChainChecked: sourceResult.onChainChecked,
+        // The top-level per-checkpoint / per-event results ARE the recomputed source
+        // results, so the CLI's existing rendering shows them unchanged.
+        checkpoints: sourceResult.checkpoints,
+        events: sourceResult.events,
+        assertedStatus,
+        export: {
+            sourceLinkageOk,
+            sourceStatus: sourceResult.status,
+            verdictAgreementOk,
+            attestations,
+            verdict,
+            status,
+        },
+        errors,
+    };
+}
+export async function recomputeExportVerdict(sourceBundle, attestationRecords, generatedAt, options = {}) {
+    const sourceResult = await verifyEvidenceBundle(sourceBundle, options);
+    // Map source checkpoints by tx_id for attestation data_hash binding (§5 6c) —
+    // identical to verifyExportBody's map construction.
+    const sourceCheckpoints = new Map();
+    const sb = sourceBundle.body;
+    if (sb && typeof sb === "object" && Array.isArray(sb.checkpoints)) {
+        for (const cp of sb.checkpoints) {
+            if (cp && typeof cp.tx_id === "string")
+                sourceCheckpoints.set(cp.tx_id, cp);
+        }
+    }
+    const attestations = [];
+    for (const rec of attestationRecords) {
+        const r = await verifyAttestation(rec, sourceCheckpoints);
+        if (r.malformed !== undefined) {
+            throw new Error(`attestation record is malformed: ${r.malformed}`);
+        }
+        attestations.push(r.result);
+    }
+    const verdict = buildVerdictObject(sourceResult, attestations);
+    verdict.as_of = generatedAt;
+    // Export rollup (§5 step 9). Source linkage and verdict agreement are always
+    // satisfied at compose time (the composer computes the source hash itself and
+    // there is no prior cached verdict to disagree with), so the only failure
+    // inputs here are the recomputed source status and any failed attestation.
+    const anyAttestationFailed = attestations.some((a) => !a.ok);
+    let status;
+    if (sourceResult.status === "failed" ||
+        sourceResult.status === "malformed" ||
+        anyAttestationFailed) {
+        status = "failed";
+    }
+    else if (sourceResult.status === "partial") {
+        status = "partial";
+    }
+    else {
+        status = "verified";
+    }
+    verdict.status = status;
+    verdict.summary = summarizeExport(status, sourceResult, attestations);
+    return { verdict, sourceStatus: sourceResult.status, status, attestations };
+}
+// Verify one embedded attestation record (§5 step 6a–d). Returns `malformed`
+// (→ exit 2) for an unparseable RSA key / signature hex or a missing required
+// field; otherwise a per-dimension AttestationResult whose `ok` gates on the
+// three binding checks (sig / operator-address / data_hash). subject_ref is
+// undetermined-tolerant and never gates.
+async function verifyAttestation(rec, sourceCheckpoints) {
+    const errs = [];
+    const result = {
+        checkpointTxId: rec && typeof rec.checkpoint_tx_id === "string" ? rec.checkpoint_tx_id : "",
+        operator: "",
+        gateway: null,
+        signatureOk: false,
+        operatorAddressBound: false,
+        dataHashBound: false,
+        checkpointResolved: false,
+        level: null,
+        subjectRefOk: null,
+        ok: false,
+        errors: errs,
+    };
+    if (rec === null || typeof rec !== "object" || Array.isArray(rec)) {
+        return { result, malformed: "attestation record is not a JSON object" };
+    }
+    const payload = rec.payload;
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+        return { result, malformed: "attestation record missing payload" };
+    }
+    if (rec.signature_alg !== "rsa-pss-sha256") {
+        return {
+            result,
+            malformed: `unsupported attestation signature_alg: ${JSON.stringify(rec.signature_alg)}`,
+        };
+    }
+    const pub = rec.public_key;
+    if (pub === null ||
+        typeof pub !== "object" ||
+        pub.kty !== "RSA" ||
+        typeof pub.n !== "string" ||
+        typeof pub.e !== "string") {
+        return { result, malformed: "attestation record missing/invalid RSA public_key JWK" };
+    }
+    if (typeof rec.signature !== "string") {
+        return { result, malformed: "attestation record missing signature" };
+    }
+    const rsaKey = { kty: "RSA", n: pub.n, e: pub.e };
+    result.operator = typeof payload.operator === "string" ? payload.operator : "";
+    result.gateway = typeof payload.gateway === "string" ? payload.gateway : null;
+    result.level = typeof payload.level === "number" ? payload.level : null;
+    // (a) RSA-PSS-SHA-256 signature over JCS(payload). A malformed sig hex or
+    // unimportable key THROWS (malformed → exit 2); a well-formed key that simply
+    // fails to verify returns false (→ exit 1).
+    let payloadBytes;
+    try {
+        payloadBytes = utf8(jcs(payload));
+    }
+    catch (e) {
+        return { result, malformed: `attestation payload canonicalization failed: ${stringifyErr(e)}` };
+    }
+    try {
+        result.signatureOk = await verifyRsaPssSha256(payloadBytes, rec.signature, rsaKey);
+        if (!result.signatureOk)
+            errs.push("attestation RSA-PSS signature verification failed");
+    }
+    catch (e) {
+        return { result, malformed: `attestation ${stringifyErr(e)}` };
+    }
+    // (b) operator-address binding: base64url(SHA-256(modulus)) == payload.operator.
+    try {
+        const derived = await deriveOperatorAddress(pub.n);
+        result.operatorAddressBound = result.operator !== "" && derived === result.operator;
+        if (!result.operatorAddressBound) {
+            errs.push(`operator-address binding failed: derived=${derived} payload.operator=${result.operator}`);
+        }
+    }
+    catch (e) {
+        return { result, malformed: `attestation operator key: ${stringifyErr(e)}` };
+    }
+    // (c) checkpoint resolution + data_hash binding. The checkpoint tx data IS the
+    // uploaded JCS(envelope) bytes (the same bytes the on-chain re-fetch compares
+    // against, §4.2), so the checkpoint's committed content hash is
+    // SHA-256(JCS(checkpoint.envelope)).
+    const cp = sourceCheckpoints.get(result.checkpointTxId);
+    result.checkpointResolved = cp !== undefined;
+    if (!cp) {
+        errs.push(`attestation checkpoint_tx_id ${JSON.stringify(result.checkpointTxId)} resolves to no source checkpoint`);
+    }
+    else {
+        try {
+            const committed = await sha256Hex(utf8(jcs(cp.envelope)));
+            const dataHash = typeof payload.data_hash === "string" ? payload.data_hash.toLowerCase() : "";
+            result.dataHashBound = dataHash !== "" && dataHash === committed;
+            if (!result.dataHashBound) {
+                errs.push(`data_hash does not bind to the checkpoint's committed content hash: ` +
+                    `data_hash=${dataHash} committed=${committed}`);
+            }
+        }
+        catch (e) {
+            errs.push(`cannot recompute checkpoint content hash: ${stringifyErr(e)}`);
+        }
+    }
+    // (d) subject_ref (§3.2) — well-formedness only (no side-input subject channel
+    // in v1); undetermined (null), never a hard failure.
+    result.subjectRefOk = evaluateSubjectRef(payload.subject_ref, errs);
+    result.ok =
+        result.signatureOk &&
+            result.operatorAddressBound &&
+            result.dataHashBound &&
+            result.checkpointResolved;
+    return { result };
+}
+// subject_ref (§3.2): absent → null (unbound). Present + well-formed but no
+// side-input subject supplied → null (undetermined, mirrors disclosed-content).
+// Present + malformed → null + a surfaced note (never gates the attestation).
+function evaluateSubjectRef(subjectRef, errs) {
+    if (subjectRef === undefined || subjectRef === null)
+        return null;
+    if (typeof subjectRef !== "object" || Array.isArray(subjectRef)) {
+        errs.push("subject_ref is present but is not an object");
+        return null;
+    }
+    const sr = subjectRef;
+    const hashOk = typeof sr.hash === "string" && /^[0-9a-f]{64}$/.test(sr.hash);
+    const typeOk = typeof sr.type === "string" && /^[a-z0-9.:-]+$/.test(sr.type);
+    if (!hashOk || !typeOk) {
+        errs.push("subject_ref is present but not well-formed ({hash: sha256-hex, type: token})");
+        return null;
+    }
+    return null; // well-formed, no side input → undetermined
+}
+// Build the §4 verdict object (snake_case, spec-canonical) from the recomputed
+// source result + the attestation results. This is the recomputed copy the
+// renderer/verify-API display; it is compared (over its deterministic subset)
+// to the cached body.kernel_verdict in step 5.
+function buildVerdictObject(source, attestations) {
+    const attByCheckpoint = new Map();
+    for (const a of attestations) {
+        const list = attByCheckpoint.get(a.checkpointTxId) ?? [];
+        list.push({
+            operator: a.operator,
+            ...(a.gateway ? { gateway: a.gateway } : {}),
+            signature_ok: a.signatureOk,
+            operator_address_bound: a.operatorAddressBound,
+            data_hash_bound: a.dataHashBound,
+            ...(a.level !== null ? { level: a.level } : {}),
+            subject_ref_ok: a.subjectRefOk,
+        });
+        attByCheckpoint.set(a.checkpointTxId, list);
+    }
+    const events = source.events.map((e) => ({
+        event_id: e.eventId,
+        signature_ok: e.envelopeOk,
+        payload_bound: e.payloadBindingOk,
+        inclusion_ok: e.inclusionOk,
+        content_ok: e.contentOk,
+        status: eventVerdictStatus(e),
+    }));
+    const checkpoints = source.checkpoints.map((c) => ({
+        checkpoint_tx_id: c.txId,
+        merkle_root_ok: c.merkleRootOk,
+        on_chain: c.onChain ? toVerdictOnChain(c.onChain) : null,
+        attestations: attByCheckpoint.get(c.txId) ?? [],
+    }));
+    let verified = 0;
+    let failed = 0;
+    let undetermined = 0;
+    for (const e of events) {
+        if (e.status === "failed")
+            failed++;
+        else if (e.status === "verified")
+            verified++;
+        else
+            undetermined++;
+    }
+    for (const a of attestations) {
+        if (a.ok)
+            verified++;
+        else
+            failed++;
+    }
+    return {
+        schema_version: "sanning.evidence.verdict/v1",
+        status: source.status === "malformed" ? "failed" : source.status,
+        counts: { verified, failed, undetermined },
+        events,
+        checkpoints,
+        custody_chain: null,
+    };
+}
+function toVerdictOnChain(o) {
+    return {
+        rollup: o.rollup,
+        on_chain_ok: o.onChainOk,
+        // The kernel emits {gateway, outcome}; block_height is issuer-side
+        // enrichment (optional in the §4.4 schema) the offline verifier does not
+        // recompute.
+        per_gateway: o.perGateway.map((g) => ({ gateway: g.gateway, outcome: g.outcome })),
+    };
+}
+function eventVerdictStatus(e) {
+    if (!e.ok)
+        return "failed";
+    if (e.payloadBindingOk === null)
+        return "partial"; // withheld record — undetermined
+    return "verified";
+}
+// The §5 step-5 agreement projection: strip every environment/time-dependent
+// and derived dimension, leaving only what an offline verifier deterministically
+// recomputes. Tolerant of a hostile/garbled cached verdict (optional chaining +
+// nullish normalization) — a structural difference surfaces as disagreement,
+// which is the correct tamper signal. Works on both the cached snake_case JSON
+// and the freshly built VerdictObject.
+function projectVerdictForAgreement(v) {
+    const o = (v ?? {});
+    const events = Array.isArray(o.events) ? o.events : [];
+    const checkpoints = Array.isArray(o.checkpoints) ? o.checkpoints : [];
+    return {
+        schema_version: typeof o.schema_version === "string" ? o.schema_version : null,
+        events: events.map((e) => {
+            const ev = (e ?? {});
+            return {
+                event_id: ev.event_id ?? null,
+                signature_ok: ev.signature_ok ?? null,
+                payload_bound: ev.payload_bound ?? null,
+                inclusion_ok: ev.inclusion_ok ?? null,
+                content_ok: ev.content_ok ?? null,
+            };
+        }),
+        checkpoints: checkpoints.map((c) => {
+            const cp = (c ?? {});
+            const atts = Array.isArray(cp.attestations) ? cp.attestations : [];
+            return {
+                checkpoint_tx_id: cp.checkpoint_tx_id ?? null,
+                merkle_root_ok: cp.merkle_root_ok ?? null,
+                // on_chain DELIBERATELY OMITTED — environment/time-dependent (see step 5).
+                attestations: atts.map((a) => {
+                    const at = (a ?? {});
+                    return {
+                        operator: at.operator ?? null,
+                        signature_ok: at.signature_ok ?? null,
+                        operator_address_bound: at.operator_address_bound ?? null,
+                        data_hash_bound: at.data_hash_bound ?? null,
+                        subject_ref_ok: at.subject_ref_ok ?? null,
+                    };
+                }),
+            };
+        }),
+    };
+}
+function summarizeExport(status, source, attestations) {
+    const attOk = attestations.filter((a) => a.ok).length;
+    return (`Export ${status}: source bundle ${source.status} ` +
+        `(${source.events.length} event(s) across ${source.checkpoints.length} checkpoint(s)); ` +
+        `${attOk}/${attestations.length} operator attestation(s) valid.`);
+}
+// Re-fetch a checkpoint's raw bytes from EACH gateway and classify every
+// gateway's individual outcome (evidence-export.md §4.2), then roll them up
+// worst-finding-wins. Unlike the pre-§4.2 first-responsive-wins collapse, this
+// records a per-gateway array so a confirm/mismatch/unreachable MIX across
+// gateways is preserved; the derived collapsed `onChainOk` reproduces the old
+// single-boolean exactly for a single gateway.
+async function refetchCheckpoint(cp, gateways, fetchImpl) {
+    let expectedHex;
+    try {
+        expectedHex = toHex(utf8(jcs(cp.envelope)));
+    }
+    catch {
+        // Cannot canonicalize the checkpoint envelope — every gateway is a mismatch
+        // (we can never confirm bytes we cannot compute).
+        expectedHex = undefined;
+    }
+    const perGateway = [];
+    for (const gw of gateways) {
+        perGateway.push({ gateway: gw, outcome: await probeGateway(cp, gw, expectedHex, fetchImpl) });
+    }
+    const onChain = rollupOnChain(perGateway);
+    let error;
+    if (onChain.rollup === "mismatch") {
+        error = `on-chain bytes at ${cp.tx_id} do not match the bundle's checkpoint envelope`;
+    }
+    else if (onChain.rollup === "unreachable") {
+        error = `checkpoint ${cp.tx_id} unreachable on all gateways`;
+    }
+    return { onChain, unavailable: onChain.rollup === "unreachable", error };
+}
+// One gateway's outcome for one checkpoint tx: confirm (bytes match), mismatch
+// (bytes disagree), or unreachable (no response / !ok / network error).
+async function probeGateway(cp, gateway, expectedHex, fetchImpl) {
+    const url = `${gateway.replace(/\/+$/, "")}/${cp.tx_id}`;
+    let resp;
+    try {
+        resp = await fetchImpl(url);
+    }
+    catch {
+        return "unreachable"; // network error / timeout
+    }
+    if (!resp.ok)
+        return "unreachable"; // no such tx / gateway error
+    let onChainBytes;
+    try {
+        onChainBytes = new Uint8Array(await resp.arrayBuffer());
+    }
+    catch {
+        return "unreachable";
+    }
+    if (expectedHex === undefined)
+        return "mismatch";
+    // The on-chain bytes are the uploaded envelope bytes (JCS-canonical, per the
+    // family upload invariant). Compare structurally too, so a gateway that
+    // re-pretty-prints does not spuriously fail — but the canonical re-hash is
+    // the load-bearing check.
+    if (toHex(onChainBytes) === expectedHex)
+        return "confirm";
+    try {
+        const parsed = JSON.parse(new TextDecoder().decode(onChainBytes));
+        if (toHex(utf8(jcs(parsed))) === expectedHex)
+            return "confirm";
+    }
+    catch {
+        // not JSON / not parseable — a genuine mismatch
+    }
+    return "mismatch";
+}
+// Rollup rule (§4.2): mismatch if ANY gateway is mismatch; else confirm if ANY
+// is confirm; else unreachable. The collapsed `onChainOk`: false on mismatch,
+// true on confirm, null on all-unreachable. An empty gateway list is treated as
+// all-unreachable (no signal).
+function rollupOnChain(perGateway) {
+    let rollup = "unreachable";
+    if (perGateway.some((g) => g.outcome === "mismatch"))
+        rollup = "mismatch";
+    else if (perGateway.some((g) => g.outcome === "confirm"))
+        rollup = "confirm";
+    const onChainOk = rollup === "mismatch" ? false : rollup === "confirm" ? true : null;
+    return { rollup, onChainOk, perGateway };
+}
+function getEventId(env) {
+    if (env && typeof env === "object" && typeof env.event_id === "string") {
+        return env.event_id;
+    }
+    return "<unknown>";
+}
+function toHex(bytes) {
+    let out = "";
+    for (const x of bytes)
+        out += x.toString(16).padStart(2, "0");
+    return out;
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}