@sanning/proof 0.8.3 → 0.9.0

package/README.md

@@ -203,7 +203,7 @@ The primary signature covers `JCS(envelope minus signature minus co_signatures)`
 
 ## Why you can trust it (without trusting us)
 
-Three **independent implementations** of this kernel exist: this package, the Python [`sanning-proof`](https://pypi.org/project/sanning-proof/) (PyPI), and and the MIT-licensed Go reference. The TypeScript and Python kernels are conformance-gated **byte-for-byte** in CI against one shared corpus, pinned per file by SHA-256 at cut tag `test-vectors-v3.3`, and a cross-kernel agreement gate re-runs the corpus plus adversarial negatives through both, asserting identical verdicts on identical bytes. The Go reference runs as a third leg of that same gate, built at the commit its vendoring pins.
+Three **independent implementations** of this kernel exist: this package, the Python [`sanning-proof`](https://pypi.org/project/sanning-proof/) (PyPI), and and the MIT-licensed Go reference. The TypeScript and Python kernels are conformance-gated **byte-for-byte** in CI against one shared corpus, pinned per file by SHA-256 at cut tag `test-vectors-v3.4`, and a cross-kernel agreement gate re-runs the corpus plus adversarial negatives through both, asserting identical verdicts on identical bytes. The Go reference runs as a third leg of that same gate, built at the commit its vendoring pins.
 
 That mutual gate is the point: anyone can verify these provenance records with **no Sanning code in the trust path**, write your own verifier against the specs that ship inside the [`sanning-proof`](https://pypi.org/project/sanning-proof/) sdist, and the corpus will tell you if it is conformant.
 

package/dist/cli.js

@@ -639,14 +639,25 @@ function reportEvidence(result, path, gateways, io, chains) {
         io.out("");
         io.out(paint("  Events", DIM));
         for (const ev of result.events) {
+            // `~` is "not determined", and the words after it must say only that.
+            // This read "record withheld", which is a statement about the PRODUCER:
+            // it says the customer chose minimum disclosure and kept these bytes
+            // back, which is legitimate and expected. An event whose envelope was
+            // never an envelope produces the same `null` on this dimension, and
+            // there the sentence is simply untrue: the record may be sitting in the
+            // bundle, and nothing about the producer has been established either
+            // way. A renderer cannot tell the two apart from a tri-state, so it
+            // states what the verifier did and leaves WHY to the error lines below,
+            // which now name the malformed envelope instead of a signature check
+            // that never ran (proof#76).
             const binding = ev.payloadBindingOk === null
-                ? paint("~ record withheld", Y)
+                ? paint("~ record not checked", Y)
                 : `record ${mark(ev.payloadBindingOk)}`;
             // Show the content (logs) segment only when content was disclosed and
             // evaluated (non-null) — undisclosed content is the default and would just
             // be noise on every line.
             const logs = ev.contentOk === null ? "" : `  logs ${mark(ev.contentOk)}`;
-            io.out(`    ${mark(ev.ok)} ${shortId(ev.eventId)}  sig ${mark(ev.envelopeOk)}  ${binding}  inclusion ${mark(ev.inclusionOk)}${logs}`);
+            io.out(`    ${mark(ev.ok)} ${shortId(ev.eventId)}  envelope ${mark(ev.envelopeOk)}  ${binding}  inclusion ${mark(ev.inclusionOk)}${logs}`);
             for (const e of ev.errors)
                 io.out(paint(`        - ${e}`, R));
         }

package/dist/evidence.js

@@ -103,6 +103,19 @@ function malformed(error, specVersionOk = false) {
 function stringifyErr(e) {
     return e instanceof Error ? e.message : String(e);
 }
+/**
+ * Spell a value inside a finding the way the Python kernel spells it.
+ *
+ * `JSON.stringify(undefined)` is `undefined` (the value, not a string), so an
+ * absent field interpolates as the word `undefined` where Python writes `null`.
+ * One word, and a real difference in what an auditor reads: someone comparing
+ * the two CLIs on one bundle sees two different sentences for one fact. Both
+ * kernels route every quoted value through this spelling, and the cross-kernel
+ * anchor-trace leg byte-compares them.
+ */
+function jsonStr(value) {
+    return JSON.stringify(value === undefined ? null : value) ?? "null";
+}
 // Verify a `sanning.evidence/v1` bundle carrying a `sanning.anchor.trace/v1` body.
 //
 // Returns a structured per-checkpoint + per-event result and a recomputed
@@ -279,7 +292,7 @@ async function resolveCheckpointKey(cp, recordBytes, isV1) {
     const errors = [];
     if (isV1) {
         if (cp.checkpoint_ref !== undefined || cp.anchor_ref !== undefined) {
-            errors.push("sanning.anchor.trace/v1 checkpoint carries v2 fields (checkpoint_ref/anchor_ref) — " +
+            errors.push("sanning.anchor.trace/v1 checkpoint carries v2 fields (checkpoint_ref/anchor_ref) -- " +
                 "one bundle speaks one vocabulary");
             return { key: null, anchorRef: null, errors };
         }
@@ -293,7 +306,7 @@ async function resolveCheckpointKey(cp, recordBytes, isV1) {
         return { key: cp.tx_id, anchorRef: { kind: "arweave", id: cp.tx_id }, errors };
     }
     if (cp.tx_id !== undefined) {
-        errors.push("sanning.anchor.trace/v2 checkpoint carries legacy tx_id — one bundle speaks one vocabulary");
+        errors.push("sanning.anchor.trace/v2 checkpoint carries legacy tx_id -- one bundle speaks one vocabulary");
         return { key: null, anchorRef: null, errors };
     }
     if (typeof cp.checkpoint_ref !== "string" || cp.checkpoint_ref === "") {
@@ -302,7 +315,7 @@ async function resolveCheckpointKey(cp, recordBytes, isV1) {
     }
     if (recordBytes === undefined) {
         // Without the bytes the key cannot be recomputed, so it cannot be trusted.
-        errors.push("checkpoint_ref cannot be verified — record_bytes missing or not hex");
+        errors.push("checkpoint_ref cannot be verified -- record_bytes missing or not hex");
         return { key: null, anchorRef: null, errors };
     }
     const derived = await sha256Hex(recordBytes);
@@ -377,7 +390,29 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
     const byKey = new Map();
     const anchorByKey = new Map();
     const checkpointResults = [];
-    for (const cp of body.checkpoints) {
+    for (const rawCp of body.checkpoints) {
+        // `checkpoints[]` is attacker-shaped, and a verifier must never raise on
+        // adversarial input: a null entry used to reach `cp.tx_id` and hand the
+        // caller a TypeError instead of a verdict, which an auditor cannot tell
+        // apart from a broken tool. Graded and reported as "not a checkpoint"
+        // rather than coerced into an empty one: probing the envelope layer with
+        // nothing asks it a question about an object that was never an envelope.
+        // Same treatment, same words, as the §5.3 path's `events[] entry is not an
+        // object`.
+        if (rawCp === null || typeof rawCp !== "object" || Array.isArray(rawCp)) {
+            checkpointResults.push({
+                checkpointRef: "",
+                anchorRef: null,
+                envelopeOk: false,
+                merkleRootOk: false,
+                onChainOk: null,
+                onChain: null,
+                ok: false,
+                errors: ["checkpoints[] entry is not an object"],
+            });
+            continue;
+        }
+        const cp = rawCp;
         const cpErrors = [];
         let envelopeOk = false;
         let merkleRootOk = false;
@@ -421,12 +456,26 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
             // 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)
+            // See the event loop below: a degenerate envelope is a malformed input,
+            // not a failed check (proof#76).
+            if (!isJsonObject(cp.envelope)) {
+                cpErrors.push("checkpoint envelope is not a JSON object");
+            }
+            else 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");
+            // WHY the binding is undetermined decides which sentence is true.
+            // record_bytes really absent is one thing; record_bytes present and
+            // unbindable (a degenerate envelope, unreadable hex) is another, and
+            // naming the wrong cause sends a reader to look for a field that is
+            // sitting right there (proof#76).
+            if (res.payloadHashOk === null) {
+                cpErrors.push(recordBytes === undefined
+                    ? "checkpoint record_bytes missing -- root untrusted"
+                    : "checkpoint record binding not checked: root untrusted");
+            }
         }
         catch (e) {
             cpErrors.push(`checkpoint envelope verify error: ${stringifyErr(e)}`);
@@ -439,7 +488,8 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
                 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)}`);
+                    cpErrors.push(`checkpoint merkle_root mismatch: claimed=${jsonStr(cp.merkle_root)} ` +
+                        `committed=${jsonStr(committedRoot)}`);
                 }
             }
             catch (e) {
@@ -465,7 +515,24 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
     }
     // --- Step 4: per-event ------------------------------------------------------
     const eventResults = [];
-    for (const ev of body.events) {
+    for (const rawEv of body.events) {
+        // Same rule as `checkpoints[]` above, and the same words the §5.3 path
+        // already uses: a null or non-object entry is graded as not an event,
+        // never raised on.
+        if (rawEv === null || typeof rawEv !== "object" || Array.isArray(rawEv)) {
+            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 evErrors = [];
         const eventId = getEventId(ev.envelope);
         let envelopeOk = false;
@@ -482,8 +549,19 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
             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)
+            // P-10: report what could not be determined, never a fault that was never
+            // observed. There is no envelope here, so no signature was checked and no
+            // binding was attempted. "signature failed" named a check that never ran,
+            // and it was the only thing said about an event whose undetermined
+            // binding then rendered as a WITHHELD record, a claim about the
+            // producer's disclosure choice out of an input that says nothing about
+            // the producer at all (proof#76).
+            if (!isJsonObject(ev.envelope)) {
+                evErrors.push("event envelope is not a JSON object");
+            }
+            else if (!res.signatureOk) {
                 evErrors.push("event envelope signature failed");
+            }
             if (res.payloadHashOk === false)
                 evErrors.push("event record does not bind to payload_hash");
         }
@@ -507,7 +585,7 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
             evErrors.push("event missing inclusion proof");
         }
         else if (strayKey !== undefined) {
-            evErrors.push(`event inclusion carries ${wrongField} in a ${bodyType} body — one bundle speaks one vocabulary`);
+            evErrors.push(`event inclusion carries ${wrongField} in a ${bodyType} body -- one bundle speaks one vocabulary`);
         }
         else if (typeof rawKey !== "string") {
             evErrors.push(`event inclusion missing ${keyField}`);
@@ -522,7 +600,14 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
         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 ?? ""));
+                inclusionOk = await verifyInclusion(hexToBytes(incl.leaf_hash), incl.leaf_index, incl.leaf_count, (incl.audit_path ?? []).map((h) => hexToBytes(h)), 
+                // No `?? ""` fallback. A checkpoint that claims NO root must not be
+                // handed an invented empty one: the Python kernel refuses the same
+                // value and reports the decode failure, so substituting "" here had
+                // the two kernels say different things about one bundle (TS: "the
+                // proof did not reconstruct the checkpoint root", which is not what
+                // happened: there was no claimed root to reconstruct).
+                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
@@ -586,7 +671,7 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
                         onChainOk: null,
                     };
                     cpr.onChainOk = null;
-                    cpr.errors.push("checkpoint has no anchor_ref — not yet witnessed, nothing to re-fetch");
+                    cpr.errors.push("checkpoint has no anchor_ref -- not yet witnessed, nothing to re-fetch");
                     continue;
                 }
                 const outcome = await refetchCheckpoint(cp, cpr.anchorRef, gateways, fetchImpl);
@@ -690,6 +775,14 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
 // slice claim resting on them is unfounded — and unlike a bad signature,
 // nothing else in the stack would ever notice.
 // ===========================================================================
+// A JSON object, as opposed to null, an array, a string or a number. Used at
+// every point where a nested field MUST be an object before any check of it
+// means anything: probing a verifier with a non-object asks a question about
+// something that was never the thing, and the answer must say so rather than
+// name a check that never ran (proof#76).
+function isJsonObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
 /** Lowercase hex, even length, non-empty. The family's serialization rule. */
 function isLowerHex(s, nibbles) {
     if (typeof s !== "string" || s.length === 0 || s.length % 2 !== 0)
@@ -761,7 +854,7 @@ async function verifyDisclosedContent(ev, eventId, recordBytes, sideContent) {
             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");
+                    "(record withheld or record has no event.content_hash) -- undetermined");
             }
         }
         else {
@@ -1126,8 +1219,19 @@ async function verifyStampEvidence(b, specVersionOk, assertedStatus, errors, opt
             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)
+            // P-10: report what could not be determined, never a fault that was never
+            // observed. There is no envelope here, so no signature was checked and no
+            // binding was attempted. "signature failed" named a check that never ran,
+            // and it was the only thing said about an event whose undetermined
+            // binding then rendered as a WITHHELD record, a claim about the
+            // producer's disclosure choice out of an input that says nothing about
+            // the producer at all (proof#76).
+            if (!isJsonObject(ev.envelope)) {
+                evErrors.push("event envelope is not a JSON object");
+            }
+            else if (!res.signatureOk) {
                 evErrors.push("event envelope signature failed");
+            }
             if (res.payloadHashOk === false)
                 evErrors.push("event record does not bind to payload_hash");
         }
@@ -1356,7 +1460,8 @@ export async function disclosedContent(bundle, options = {}) {
     });
     const traceEvents = resolveTraceEvents(bundle);
     if (traceEvents === undefined) {
-        errors.push(`no ${ANCHOR_TRACE_BODY_TYPES.join(" / ")} body to materialize content from ` +
+        errors.push(`no ${[...ANCHOR_TRACE_BODY_TYPES, STAMP_EVIDENCE_BODY_TYPE].join(" / ")} ` +
+            `body to materialize content from ` +
             `(body_type ${JSON.stringify(verification.bodyType)})`);
         return empty();
     }
@@ -1435,10 +1540,15 @@ export async function disclosedContent(bundle, options = {}) {
     }
     return { status: verification.status, verification, events, content, errors };
 }
-// The anchor-trace events a bundle carries, unwrapping any evidence-export
-// wrapper(s) to the inline source bundle — mirroring how verifyEvidenceBundle
-// recurses into `source_bundle`, so the events line up with its results.
-// `undefined` when there is no anchor-trace body to materialize from.
+// The events a bundle carries, unwrapping any evidence-export wrapper(s) to
+// the inline source bundle — mirroring how verifyEvidenceBundle recurses into
+// `source_bundle`, so the events line up with its results.
+// `undefined` when the bundle carries no events this reader understands, which
+// a caller must distinguish from a body that has events and no links.
+//
+// BOTH event-carrying bodies, not just anchor-trace (proof#73): §5.3's
+// `sanning.stamp.evidence/v1` is the hand-over pack, and it presents the same
+// event shape.
 //
 // Exported for `chain.ts`, which needs the same descent and must not derive it
 // again: two answers to "which events is this bundle actually about" inside one
@@ -1452,7 +1562,17 @@ export function resolveTraceEvents(bundle) {
             return undefined;
         const b = cur;
         const bodyType = typeof b.body_type === "string" ? b.body_type : null;
-        if (bodyType === ANCHOR_TRACE_BODY_TYPE || bodyType === ANCHOR_TRACE_BODY_TYPE_V1) {
+        // Both event-carrying bodies, not just anchor-trace (proof#73). §5.3's
+        // `sanning.stamp.evidence/v1` presents the SAME event shape (a
+        // producer-signed envelope, optional `record_bytes`, an inclusion proof),
+        // and it is the HAND-OVER PACK: the only artifact an auditor is ever
+        // handed. Dispatching on anchor-trace alone meant `readChains` reported
+        // zero chains on every pack, however well-formed the links inside its
+        // records were, so "is it in order?" read as NOT CHECKED on the one shape
+        // that matters. The writers have been emitting those links the whole time.
+        if (bodyType === ANCHOR_TRACE_BODY_TYPE ||
+            bodyType === ANCHOR_TRACE_BODY_TYPE_V1 ||
+            bodyType === STAMP_EVIDENCE_BODY_TYPE) {
             const body = b.body;
             if (body === null || typeof body !== "object" || !Array.isArray(body.events))
                 return undefined;

package/dist/verifier.js

@@ -51,25 +51,81 @@ export const ACCEPTED_SPEC_MAJORS = Object.freeze([
 // safely under the tightest kernel recursion limit, with headroom for the JCS
 // library's own frames-per-level. Mirrors the Python kernel's MAX_CANONICAL_DEPTH.
 export const MAX_CANONICAL_DEPTH = 128;
-// Iteratively test whether `value` nests JSON containers deeper than `max`
-// levels; short-circuits `true` on the first over-deep path. Deliberately NOT
-// recursive: this guard runs on already-parsed, possibly-hostile input, so it
-// must never itself overflow the call stack — it walks an explicit heap stack
-// instead. The root container is depth 1; each nested array/object is one
-// deeper; scalars have no children and never increase depth.
-export function exceedsDepth(value, max) {
-    const stack = [[value, 1]];
+// Returned by `boundedInput` in place of a value that nests past the bound.
+// A symbol, so no input can forge it.
+const OVER_DEEP = Symbol("canonicalization input nests past the bound");
+// The serializer's own test (`object.toJSON instanceof Function`), on an object.
+function hasToJSON(node) {
+    return (node !== null &&
+        typeof node === "object" &&
+        node.toJSON instanceof Function);
+}
+// Follow `node.toJSON()` until the value has none, which is what the serializer
+// does (`serialize(object.toJSON())`: in place, at the same depth). Bounded,
+// because the serializer burns a stack frame per hop: a `toJSON` that keeps
+// returning another `toJSON` object is over-deep, not something to follow
+// forever.
+function resolveToJSON(node, max) {
+    let resolved = node;
+    for (let hops = 0; hasToJSON(resolved); hops++) {
+        if (hops >= max)
+            return OVER_DEEP;
+        resolved = resolved.toJSON();
+    }
+    return resolved;
+}
+// Bound nesting AND resolve `toJSON`, in one pass, returning the value the rest
+// of `jcs` must use: a structure with every `toJSON` already resolved, so
+// `canonicalize` never calls one itself. `OVER_DEEP` if any container nests
+// deeper than `max` levels. The root container is depth 1; each nested
+// array/object is one deeper; scalars have no children and never increase depth.
+//
+// Deliberately NOT recursive: this runs on already-parsed, possibly-hostile
+// input, so it must never itself overflow the call stack — it walks an explicit
+// heap stack instead.
+//
+// It returns a resolved COPY rather than checking the caller's value in place,
+// and that is the load-bearing part. `canonicalize` serializes `object.toJSON()`
+// IN PLACE OF the object and recurses into the result, so a guard that only
+// LOOKS at what `toJSON` returns and then lets the serializer ask again calls it
+// twice, and the two answers need not match: an unstable `toJSON` hands the
+// guard a shallow value and the serializer a deep one, which is the overflow the
+// bound exists to prevent, reached through the bound (proof#71 review). Copying
+// what was measured is what makes check and use the same value. It also settles
+// a getter, which is read once here and never re-read.
+function boundedInput(value, max) {
+    const root = resolveToJSON(value, max);
+    if (root === OVER_DEEP || root === null || typeof root !== "object")
+        return root;
+    const copy = Array.isArray(root) ? [] : {};
+    const stack = [[root, copy, 1]];
     while (stack.length > 0) {
-        const [node, depth] = stack.pop();
-        if (node === null || typeof node !== "object")
-            continue; // scalar — always fine
-        if (depth > max)
-            return true; // a container nested past the bound
-        const children = Array.isArray(node) ? node : Object.values(node);
-        for (const child of children)
-            stack.push([child, depth + 1]);
+        const [src, dst, depth] = stack.pop();
+        // `Object.entries` is what `canonicalize` walks for an object, and for an
+        // array it yields the same index keys its `reduce` visits.
+        for (const [key, rawChild] of Object.entries(src)) {
+            const child = resolveToJSON(rawChild, max);
+            if (child === OVER_DEEP)
+                return OVER_DEEP;
+            if (child === null || typeof child !== "object") {
+                dst[key] = child;
+                continue;
+            }
+            if (depth + 1 > max)
+                return OVER_DEEP; // a container nested past the bound
+            const childCopy = Array.isArray(child) ? [] : {};
+            dst[key] = childCopy;
+            stack.push([child, childCopy, depth + 1]);
+        }
     }
-    return false;
+    return copy;
+}
+// Test whether `value` nests JSON containers deeper than `max` levels. Same walk
+// `jcs` runs, so the predicate and the serialization agree by construction.
+// Callers holding a value with a `toJSON` pay for it once per call: this runs it,
+// and so does the `jcs` that usually follows. Within `jcs` itself it runs once.
+export function exceedsDepth(value, max) {
+    return boundedInput(value, max) === OVER_DEEP;
 }
 // RFC 8785 (JCS) canonicalization. The `canonicalize` package is the reference
 // JS implementation; correctness is pinned by the conformance vectors.
@@ -79,6 +135,11 @@ export function exceedsDepth(value, max) {
 // input, so neither can overflow, and a too-deep input is a caller/input error
 // that the callers bucket as malformed (same contract as a malformed key).
 //
+// Both of them then see `boundedInput`'s output, never the caller's value. That
+// is what makes the two checks below true of what actually gets serialized: the
+// bound holds against an unstable `toJSON`, and a lone surrogate behind a
+// `toJSON` is seen rather than emitted (proof#71 and its review).
+//
 // Lone (unpaired) UTF-16 surrogates are REJECTED, never passed through: RFC
 // 8785 requires well-formed UTF-8 output, JS strings can carry lone
 // surrogates that `canonicalize` would emit as-is, and the sibling kernels
@@ -86,11 +147,12 @@ export function exceedsDepth(value, max) {
 // them). Reject-only is the one behavior all three kernels can share —
 // pinned here and by the corpus lone-surrogate negative.
 export function jcs(value) {
-    if (exceedsDepth(value, MAX_CANONICAL_DEPTH)) {
+    const input = boundedInput(value, MAX_CANONICAL_DEPTH);
+    if (input === OVER_DEEP) {
         throw new Error(`jcs: input nesting exceeds the ${MAX_CANONICAL_DEPTH}-level canonicalization depth bound`);
     }
-    rejectLoneSurrogates(value);
-    const canonical = canonicalize(value);
+    rejectLoneSurrogates(input);
+    const canonical = canonicalize(input);
     if (typeof canonical !== "string") {
         throw new Error("jcs: canonicalize returned a non-string (input not JSON-serializable?)");
     }

package/package.json

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

package/src/cli.ts

@@ -730,16 +730,27 @@ function reportEvidence(
     io.out("");
     io.out(paint("  Events", DIM));
     for (const ev of result.events) {
+      // `~` is "not determined", and the words after it must say only that.
+      // This read "record withheld", which is a statement about the PRODUCER:
+      // it says the customer chose minimum disclosure and kept these bytes
+      // back, which is legitimate and expected. An event whose envelope was
+      // never an envelope produces the same `null` on this dimension, and
+      // there the sentence is simply untrue: the record may be sitting in the
+      // bundle, and nothing about the producer has been established either
+      // way. A renderer cannot tell the two apart from a tri-state, so it
+      // states what the verifier did and leaves WHY to the error lines below,
+      // which now name the malformed envelope instead of a signature check
+      // that never ran (proof#76).
       const binding =
         ev.payloadBindingOk === null
-          ? paint("~ record withheld", Y)
+          ? paint("~ record not checked", Y)
           : `record ${mark(ev.payloadBindingOk)}`;
       // Show the content (logs) segment only when content was disclosed and
       // evaluated (non-null) — undisclosed content is the default and would just
       // be noise on every line.
       const logs = ev.contentOk === null ? "" : `  logs ${mark(ev.contentOk)}`;
       io.out(
-        `    ${mark(ev.ok)} ${shortId(ev.eventId)}  sig ${mark(ev.envelopeOk)}  ${binding}  inclusion ${mark(ev.inclusionOk)}${logs}`,
+        `    ${mark(ev.ok)} ${shortId(ev.eventId)}  envelope ${mark(ev.envelopeOk)}  ${binding}  inclusion ${mark(ev.inclusionOk)}${logs}`,
       );
       for (const e of ev.errors) io.out(paint(`        - ${e}`, R));
     }

package/src/evidence.ts

@@ -675,6 +675,20 @@ function stringifyErr(e: unknown): string {
   return e instanceof Error ? e.message : String(e);
 }
 
+/**
+ * Spell a value inside a finding the way the Python kernel spells it.
+ *
+ * `JSON.stringify(undefined)` is `undefined` (the value, not a string), so an
+ * absent field interpolates as the word `undefined` where Python writes `null`.
+ * One word, and a real difference in what an auditor reads: someone comparing
+ * the two CLIs on one bundle sees two different sentences for one fact. Both
+ * kernels route every quoted value through this spelling, and the cross-kernel
+ * anchor-trace leg byte-compares them.
+ */
+function jsonStr(value: unknown): string {
+  return JSON.stringify(value === undefined ? null : value) ?? "null";
+}
+
 // Verify a `sanning.evidence/v1` bundle carrying a `sanning.anchor.trace/v1` body.
 //
 // Returns a structured per-checkpoint + per-event result and a recomputed
@@ -876,7 +890,7 @@ async function resolveCheckpointKey(
   if (isV1) {
     if (cp.checkpoint_ref !== undefined || cp.anchor_ref !== undefined) {
       errors.push(
-        "sanning.anchor.trace/v1 checkpoint carries v2 fields (checkpoint_ref/anchor_ref) — " +
+        "sanning.anchor.trace/v1 checkpoint carries v2 fields (checkpoint_ref/anchor_ref) -- " +
           "one bundle speaks one vocabulary",
       );
       return { key: null, anchorRef: null, errors };
@@ -893,7 +907,7 @@ async function resolveCheckpointKey(
 
   if (cp.tx_id !== undefined) {
     errors.push(
-      "sanning.anchor.trace/v2 checkpoint carries legacy tx_id — one bundle speaks one vocabulary",
+      "sanning.anchor.trace/v2 checkpoint carries legacy tx_id -- one bundle speaks one vocabulary",
     );
     return { key: null, anchorRef: null, errors };
   }
@@ -903,7 +917,7 @@ async function resolveCheckpointKey(
   }
   if (recordBytes === undefined) {
     // Without the bytes the key cannot be recomputed, so it cannot be trusted.
-    errors.push("checkpoint_ref cannot be verified — record_bytes missing or not hex");
+    errors.push("checkpoint_ref cannot be verified -- record_bytes missing or not hex");
     return { key: null, anchorRef: null, errors };
   }
   const derived = await sha256Hex(recordBytes);
@@ -991,7 +1005,29 @@ async function verifyAnchorTrace(
   const byKey = new Map<string, AnyTraceCheckpoint>();
   const anchorByKey = new Map<string, AnchorRef | null>();
   const checkpointResults: CheckpointResult[] = [];
-  for (const cp of body.checkpoints as AnyTraceCheckpoint[]) {
+  for (const rawCp of body.checkpoints as unknown[]) {
+    // `checkpoints[]` is attacker-shaped, and a verifier must never raise on
+    // adversarial input: a null entry used to reach `cp.tx_id` and hand the
+    // caller a TypeError instead of a verdict, which an auditor cannot tell
+    // apart from a broken tool. Graded and reported as "not a checkpoint"
+    // rather than coerced into an empty one: probing the envelope layer with
+    // nothing asks it a question about an object that was never an envelope.
+    // Same treatment, same words, as the §5.3 path's `events[] entry is not an
+    // object`.
+    if (rawCp === null || typeof rawCp !== "object" || Array.isArray(rawCp)) {
+      checkpointResults.push({
+        checkpointRef: "",
+        anchorRef: null,
+        envelopeOk: false,
+        merkleRootOk: false,
+        onChainOk: null,
+        onChain: null,
+        ok: false,
+        errors: ["checkpoints[] entry is not an object"],
+      });
+      continue;
+    }
+    const cp = rawCp as AnyTraceCheckpoint;
     const cpErrors: string[] = [];
     let envelopeOk = false;
     let merkleRootOk = false;
@@ -1038,9 +1074,26 @@ async function verifyAnchorTrace(
       // 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");
+      // See the event loop below: a degenerate envelope is a malformed input,
+      // not a failed check (proof#76).
+      if (!isJsonObject(cp.envelope)) {
+        cpErrors.push("checkpoint envelope is not a JSON object");
+      } else 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");
+      // WHY the binding is undetermined decides which sentence is true.
+      // record_bytes really absent is one thing; record_bytes present and
+      // unbindable (a degenerate envelope, unreadable hex) is another, and
+      // naming the wrong cause sends a reader to look for a field that is
+      // sitting right there (proof#76).
+      if (res.payloadHashOk === null) {
+        cpErrors.push(
+          recordBytes === undefined
+            ? "checkpoint record_bytes missing -- root untrusted"
+            : "checkpoint record binding not checked: root untrusted",
+        );
+      }
     } catch (e) {
       cpErrors.push(`checkpoint envelope verify error: ${stringifyErr(e)}`);
     }
@@ -1056,7 +1109,8 @@ async function verifyAnchorTrace(
         merkleRootOk = typeof committedRoot === "string" && committedRoot === cp.merkle_root;
         if (!merkleRootOk) {
           cpErrors.push(
-            `checkpoint merkle_root mismatch: claimed=${cp.merkle_root} committed=${String(committedRoot)}`,
+            `checkpoint merkle_root mismatch: claimed=${jsonStr(cp.merkle_root)} ` +
+              `committed=${jsonStr(committedRoot)}`,
           );
         }
       } catch (e) {
@@ -1084,7 +1138,24 @@ async function verifyAnchorTrace(
 
   // --- Step 4: per-event ------------------------------------------------------
   const eventResults: EventResult[] = [];
-  for (const ev of body.events) {
+  for (const rawEv of body.events as unknown[]) {
+    // Same rule as `checkpoints[]` above, and the same words the §5.3 path
+    // already uses: a null or non-object entry is graded as not an event,
+    // never raised on.
+    if (rawEv === null || typeof rawEv !== "object" || Array.isArray(rawEv)) {
+      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 TraceEvent;
     const evErrors: string[] = [];
     const eventId = getEventId(ev.envelope);
     let envelopeOk = false;
@@ -1103,7 +1174,18 @@ async function verifyAnchorTrace(
       );
       envelopeOk = res.ok; // ok tolerates an undetermined binding (withheld record)
       payloadBindingOk = res.payloadHashOk;
-      if (!res.signatureOk) evErrors.push("event envelope signature failed");
+      // P-10: report what could not be determined, never a fault that was never
+      // observed. There is no envelope here, so no signature was checked and no
+      // binding was attempted. "signature failed" named a check that never ran,
+      // and it was the only thing said about an event whose undetermined
+      // binding then rendered as a WITHHELD record, a claim about the
+      // producer's disclosure choice out of an input that says nothing about
+      // the producer at all (proof#76).
+      if (!isJsonObject(ev.envelope)) {
+        evErrors.push("event envelope is not a JSON object");
+      } else 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)}`);
@@ -1126,7 +1208,7 @@ async function verifyAnchorTrace(
       evErrors.push("event missing inclusion proof");
     } else if (strayKey !== undefined) {
       evErrors.push(
-        `event inclusion carries ${wrongField} in a ${bodyType} body — one bundle speaks one vocabulary`,
+        `event inclusion carries ${wrongField} in a ${bodyType} body -- one bundle speaks one vocabulary`,
       );
     } else if (typeof rawKey !== "string") {
       evErrors.push(`event inclusion missing ${keyField}`);
@@ -1148,7 +1230,13 @@ async function verifyAnchorTrace(
           incl.leaf_index,
           incl.leaf_count,
           (incl.audit_path ?? []).map((h) => hexToBytes(h)),
-          hexToBytes(cp.merkle_root ?? ""),
+          // No `?? ""` fallback. A checkpoint that claims NO root must not be
+          // handed an invented empty one: the Python kernel refuses the same
+          // value and reports the decode failure, so substituting "" here had
+          // the two kernels say different things about one bundle (TS: "the
+          // proof did not reconstruct the checkpoint root", which is not what
+          // happened: there was no claimed root to reconstruct).
+          hexToBytes(cp.merkle_root as string),
         );
         if (!inclusionOk) evErrors.push("RFC 9162 inclusion proof did not reconstruct the checkpoint root");
 
@@ -1215,7 +1303,7 @@ async function verifyAnchorTrace(
             onChainOk: null,
           };
           cpr.onChainOk = null;
-          cpr.errors.push("checkpoint has no anchor_ref — not yet witnessed, nothing to re-fetch");
+          cpr.errors.push("checkpoint has no anchor_ref -- not yet witnessed, nothing to re-fetch");
           continue;
         }
         const outcome = await refetchCheckpoint(cp, cpr.anchorRef, gateways, fetchImpl);
@@ -1319,6 +1407,15 @@ async function verifyAnchorTrace(
 // nothing else in the stack would ever notice.
 // ===========================================================================
 
+// A JSON object, as opposed to null, an array, a string or a number. Used at
+// every point where a nested field MUST be an object before any check of it
+// means anything: probing a verifier with a non-object asks a question about
+// something that was never the thing, and the answer must say so rather than
+// name a check that never ran (proof#76).
+function isJsonObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
 /** Lowercase hex, even length, non-empty. The family's serialization rule. */
 function isLowerHex(s: unknown, nibbles?: number): s is string {
   if (typeof s !== "string" || s.length === 0 || s.length % 2 !== 0) return false;
@@ -1398,7 +1495,7 @@ async function verifyDisclosedContent(
       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",
+            "(record withheld or record has no event.content_hash) -- undetermined",
         );
       }
     } else {
@@ -1828,7 +1925,18 @@ async function verifyStampEvidence(
       );
       envelopeOk = res.ok; // tolerates an undetermined binding (withheld record)
       payloadBindingOk = res.payloadHashOk;
-      if (!res.signatureOk) evErrors.push("event envelope signature failed");
+      // P-10: report what could not be determined, never a fault that was never
+      // observed. There is no envelope here, so no signature was checked and no
+      // binding was attempted. "signature failed" named a check that never ran,
+      // and it was the only thing said about an event whose undetermined
+      // binding then rendered as a WITHHELD record, a claim about the
+      // producer's disclosure choice out of an input that says nothing about
+      // the producer at all (proof#76).
+      if (!isJsonObject(ev.envelope)) {
+        evErrors.push("event envelope is not a JSON object");
+      } else 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)}`);
@@ -2142,7 +2250,8 @@ export async function disclosedContent(
   const traceEvents = resolveTraceEvents(bundle);
   if (traceEvents === undefined) {
     errors.push(
-      `no ${ANCHOR_TRACE_BODY_TYPES.join(" / ")} body to materialize content from ` +
+      `no ${[...ANCHOR_TRACE_BODY_TYPES, STAMP_EVIDENCE_BODY_TYPE].join(" / ")} ` +
+        `body to materialize content from ` +
         `(body_type ${JSON.stringify(verification.bodyType)})`,
     );
     return empty();
@@ -2235,10 +2344,15 @@ export async function disclosedContent(
   return { status: verification.status, verification, events, content, errors };
 }
 
-// The anchor-trace events a bundle carries, unwrapping any evidence-export
-// wrapper(s) to the inline source bundle — mirroring how verifyEvidenceBundle
-// recurses into `source_bundle`, so the events line up with its results.
-// `undefined` when there is no anchor-trace body to materialize from.
+// The events a bundle carries, unwrapping any evidence-export wrapper(s) to
+// the inline source bundle — mirroring how verifyEvidenceBundle recurses into
+// `source_bundle`, so the events line up with its results.
+// `undefined` when the bundle carries no events this reader understands, which
+// a caller must distinguish from a body that has events and no links.
+//
+// BOTH event-carrying bodies, not just anchor-trace (proof#73): §5.3's
+// `sanning.stamp.evidence/v1` is the hand-over pack, and it presents the same
+// event shape.
 //
 // Exported for `chain.ts`, which needs the same descent and must not derive it
 // again: two answers to "which events is this bundle actually about" inside one
@@ -2251,7 +2365,19 @@ export function resolveTraceEvents(bundle: unknown): TraceEvent[] | undefined {
     if (cur === null || typeof cur !== "object" || Array.isArray(cur)) return undefined;
     const b = cur as EvidenceBundle;
     const bodyType = typeof b.body_type === "string" ? b.body_type : null;
-    if (bodyType === ANCHOR_TRACE_BODY_TYPE || bodyType === ANCHOR_TRACE_BODY_TYPE_V1) {
+    // Both event-carrying bodies, not just anchor-trace (proof#73). §5.3's
+    // `sanning.stamp.evidence/v1` presents the SAME event shape (a
+    // producer-signed envelope, optional `record_bytes`, an inclusion proof),
+    // and it is the HAND-OVER PACK: the only artifact an auditor is ever
+    // handed. Dispatching on anchor-trace alone meant `readChains` reported
+    // zero chains on every pack, however well-formed the links inside its
+    // records were, so "is it in order?" read as NOT CHECKED on the one shape
+    // that matters. The writers have been emitting those links the whole time.
+    if (
+      bodyType === ANCHOR_TRACE_BODY_TYPE ||
+      bodyType === ANCHOR_TRACE_BODY_TYPE_V1 ||
+      bodyType === STAMP_EVIDENCE_BODY_TYPE
+    ) {
       const body = b.body as AnchorTraceBody | null | undefined;
       if (body === null || typeof body !== "object" || !Array.isArray(body.events)) return undefined;
       return body.events;

package/src/verifier.ts

@@ -57,22 +57,83 @@ export const ACCEPTED_SPEC_MAJORS: readonly string[] = Object.freeze([
 // library's own frames-per-level. Mirrors the Python kernel's MAX_CANONICAL_DEPTH.
 export const MAX_CANONICAL_DEPTH = 128;
 
-// Iteratively test whether `value` nests JSON containers deeper than `max`
-// levels; short-circuits `true` on the first over-deep path. Deliberately NOT
-// recursive: this guard runs on already-parsed, possibly-hostile input, so it
-// must never itself overflow the call stack — it walks an explicit heap stack
-// instead. The root container is depth 1; each nested array/object is one
-// deeper; scalars have no children and never increase depth.
-export function exceedsDepth(value: unknown, max: number): boolean {
-  const stack: Array<[unknown, number]> = [[value, 1]];
+// Returned by `boundedInput` in place of a value that nests past the bound.
+// A symbol, so no input can forge it.
+const OVER_DEEP = Symbol("canonicalization input nests past the bound");
+
+// The serializer's own test (`object.toJSON instanceof Function`), on an object.
+function hasToJSON(node: unknown): boolean {
+  return (
+    node !== null &&
+    typeof node === "object" &&
+    (node as { toJSON?: unknown }).toJSON instanceof Function
+  );
+}
+
+// Follow `node.toJSON()` until the value has none, which is what the serializer
+// does (`serialize(object.toJSON())`: in place, at the same depth). Bounded,
+// because the serializer burns a stack frame per hop: a `toJSON` that keeps
+// returning another `toJSON` object is over-deep, not something to follow
+// forever.
+function resolveToJSON(node: unknown, max: number): unknown {
+  let resolved = node;
+  for (let hops = 0; hasToJSON(resolved); hops++) {
+    if (hops >= max) return OVER_DEEP;
+    resolved = (resolved as { toJSON: () => unknown }).toJSON();
+  }
+  return resolved;
+}
+
+// Bound nesting AND resolve `toJSON`, in one pass, returning the value the rest
+// of `jcs` must use: a structure with every `toJSON` already resolved, so
+// `canonicalize` never calls one itself. `OVER_DEEP` if any container nests
+// deeper than `max` levels. The root container is depth 1; each nested
+// array/object is one deeper; scalars have no children and never increase depth.
+//
+// Deliberately NOT recursive: this runs on already-parsed, possibly-hostile
+// input, so it must never itself overflow the call stack — it walks an explicit
+// heap stack instead.
+//
+// It returns a resolved COPY rather than checking the caller's value in place,
+// and that is the load-bearing part. `canonicalize` serializes `object.toJSON()`
+// IN PLACE OF the object and recurses into the result, so a guard that only
+// LOOKS at what `toJSON` returns and then lets the serializer ask again calls it
+// twice, and the two answers need not match: an unstable `toJSON` hands the
+// guard a shallow value and the serializer a deep one, which is the overflow the
+// bound exists to prevent, reached through the bound (proof#71 review). Copying
+// what was measured is what makes check and use the same value. It also settles
+// a getter, which is read once here and never re-read.
+function boundedInput(value: unknown, max: number): unknown {
+  const root = resolveToJSON(value, max);
+  if (root === OVER_DEEP || root === null || typeof root !== "object") return root;
+  const copy: Record<string, unknown> | unknown[] = Array.isArray(root) ? [] : {};
+  const stack: Array<[object, Record<string, unknown> | unknown[], number]> = [[root, copy, 1]];
   while (stack.length > 0) {
-    const [node, depth] = stack.pop()!;
-    if (node === null || typeof node !== "object") continue; // scalar — always fine
-    if (depth > max) return true; // a container nested past the bound
-    const children = Array.isArray(node) ? node : Object.values(node);
-    for (const child of children) stack.push([child, depth + 1]);
+    const [src, dst, depth] = stack.pop()!;
+    // `Object.entries` is what `canonicalize` walks for an object, and for an
+    // array it yields the same index keys its `reduce` visits.
+    for (const [key, rawChild] of Object.entries(src)) {
+      const child = resolveToJSON(rawChild, max);
+      if (child === OVER_DEEP) return OVER_DEEP;
+      if (child === null || typeof child !== "object") {
+        (dst as Record<string, unknown>)[key] = child;
+        continue;
+      }
+      if (depth + 1 > max) return OVER_DEEP; // a container nested past the bound
+      const childCopy: Record<string, unknown> | unknown[] = Array.isArray(child) ? [] : {};
+      (dst as Record<string, unknown>)[key] = childCopy;
+      stack.push([child, childCopy, depth + 1]);
+    }
   }
-  return false;
+  return copy;
+}
+
+// Test whether `value` nests JSON containers deeper than `max` levels. Same walk
+// `jcs` runs, so the predicate and the serialization agree by construction.
+// Callers holding a value with a `toJSON` pay for it once per call: this runs it,
+// and so does the `jcs` that usually follows. Within `jcs` itself it runs once.
+export function exceedsDepth(value: unknown, max: number): boolean {
+  return boundedInput(value, max) === OVER_DEEP;
 }
 
 // RFC 8785 (JCS) canonicalization. The `canonicalize` package is the reference
@@ -83,6 +144,11 @@ export function exceedsDepth(value: unknown, max: number): boolean {
 // input, so neither can overflow, and a too-deep input is a caller/input error
 // that the callers bucket as malformed (same contract as a malformed key).
 //
+// Both of them then see `boundedInput`'s output, never the caller's value. That
+// is what makes the two checks below true of what actually gets serialized: the
+// bound holds against an unstable `toJSON`, and a lone surrogate behind a
+// `toJSON` is seen rather than emitted (proof#71 and its review).
+//
 // Lone (unpaired) UTF-16 surrogates are REJECTED, never passed through: RFC
 // 8785 requires well-formed UTF-8 output, JS strings can carry lone
 // surrogates that `canonicalize` would emit as-is, and the sibling kernels
@@ -90,13 +156,14 @@ export function exceedsDepth(value: unknown, max: number): boolean {
 // them). Reject-only is the one behavior all three kernels can share —
 // pinned here and by the corpus lone-surrogate negative.
 export function jcs(value: unknown): string {
-  if (exceedsDepth(value, MAX_CANONICAL_DEPTH)) {
+  const input = boundedInput(value, MAX_CANONICAL_DEPTH);
+  if (input === OVER_DEEP) {
     throw new Error(
       `jcs: input nesting exceeds the ${MAX_CANONICAL_DEPTH}-level canonicalization depth bound`,
     );
   }
-  rejectLoneSurrogates(value);
-  const canonical = canonicalize(value);
+  rejectLoneSurrogates(input);
+  const canonical = canonicalize(input);
   if (typeof canonical !== "string") {
     throw new Error("jcs: canonicalize returned a non-string (input not JSON-serializable?)");
   }