@sanning/proof 0.9.2 → 0.11.0

package/dist/verifier.d.ts

@@ -3,6 +3,42 @@ export declare const ACCEPTED_SPEC_MAJORS: readonly string[];
 export declare const MAX_CANONICAL_DEPTH = 128;
 export declare function exceedsDepth(value: unknown, max: number): boolean;
 export declare function jcs(value: unknown): string;
+/**
+ * Read bytes that claim to be `jcs(value)` (RFC 8785), strictly. The Python
+ * twin is `jcs_loads` in `src/sanning_proof/canonicalize.py`, and every site in
+ * either kernel that reads bytes a producer signed goes through one of the two.
+ *
+ * ONE RULE, SPELLED OUT, BECAUSE TWO BUILT-INS ARE NOT ONE RULE. Four checks
+ * carry it, none of them left to a decoder's defaults: strict UTF-8, no leading
+ * byte-order mark, no non-finite literal (this kernel's `JSON.parse` rejects
+ * `NaN`, `Infinity` and `-Infinity` natively, and Python names them in a
+ * `parse_constant` hook), and no unpaired surrogate in the parsed value.
+ *
+ * THE FOURTH CHECK IS NOT THE FIRST ONE TWICE. The strict decode refuses a
+ * surrogate written as raw bytes; it cannot see one written as the ASCII
+ * escape `\ud800`, which `JSON.parse` turns into a lone code unit AFTER the
+ * decode has passed. `"c\ud800x"` is pure ASCII on the wire, so this reader
+ * accepted it while its own text above said it does not, and one poisoned
+ * record then deleted the Python kernel's whole chain reading (the gate on
+ * proof#154). Both spellings are the same malformed record, and both are
+ * refused here.
+ *
+ * `new TextDecoder()` alone is none of that. It replaces every invalid sequence
+ * with U+FFFD and strips a BOM. Python's `json.loads(<bytes>)` is not it
+ * either, in the opposite direction: CPython sniffs the encoding and decodes
+ * with `errors="surrogatepass"`, so it strips a UTF-8 BOM, accepts a UTF-16 or
+ * UTF-32 body, and passes a lone surrogate and a CESU-8 pair through. Both
+ * defaults have shipped a split verdict on one pack: a raw `0x80` inside a
+ * stamp body read `verified` here and `failed` there (gate 4), and then a
+ * `BOM + JCS(record)` checkpoint read `verified` there and `mixed` here (gate
+ * 5), both on proof#140. JCS is defined over UTF-8 and I-JSON (RFC 7493)
+ * forbids a lone surrogate, so each of those inputs is MALFORMED rather than
+ * another spelling of the same record.
+ *
+ * Throws for anything that is not conformant; every call site treats a throw as
+ * "this reader cannot read these bytes" and names the check that failed.
+ */
+export declare function jcsParse(bytes: Uint8Array): unknown;
 export declare function specVersionSupported(specVersion: string): boolean;
 export declare function isRfc3339UtcInstant(value: unknown): boolean;
 export declare function contentHashes(env: Envelope): {

package/dist/verifier.js

@@ -7,13 +7,13 @@
 // Conformance is enforced by test/conformance.test.ts, which runs every
 // corpus test vector through this code and asserts byte-for-byte agreement.
 import canonicalize from "canonicalize";
-import { ed25519Verify, sha256Hex, utf8 } from "./crypto.js";
+import { ed25519Verify, isHexField, sha256Hex, utf8 } from "./crypto.js";
 // Fail-closed accepted-profile registry (envelope-spec §2): exactly the
 // accepted profile majors, nothing else. Minors within an accepted
 // major ("sanning.agent/v1.<minor>") are additive and tolerated — matching the Go
 // reference kernel's semantics (pkg/proof isSupportedSpec) so the kernels do
 // not diverge on minors. Accepting a new profile is a deliberate one-entry
-// addition HERE and only here. sanning.events/v1 (external commitment + Minimal
+// addition HERE and only here. sanning.events/v2 (external commitment + Minimal
 // disclosure; envelope-spec §4) is verified through the SAME primitives — the
 // signed scope is still envelope-minus-signature-minus-co_signatures, with no
 // profile-specific dialect (no underscore strip, that is mlflow-only).
@@ -35,9 +35,13 @@ import { ed25519Verify, sha256Hex, utf8 } from "./crypto.js";
 // always strict mode) and the `readonly string[]` type rejects it at compile
 // time. The elements are strings, so a shallow freeze is a deep one. Pinned by
 // test/accept-set.test.ts "the exported registry cannot be widened at runtime".
+//
+// `sanning.events/v2` replaced `sanning.events/v1` in the producer-to-agent cut
+// (envelope-spec A10, governance.md §8 W-3). The old major is rejected like any
+// other unknown one: DL-73 keeps no reader for it.
 export const ACCEPTED_SPEC_MAJORS = Object.freeze([
     "sanning.agent/v1",
-    "sanning.events/v1",
+    "sanning.events/v2",
 ]);
 // Maximum JSON container-nesting depth a verifier will canonicalize. Inputs
 // nested deeper are rejected as malformed BEFORE canonicalization runs. This is
@@ -174,6 +178,85 @@ export function jcs(value) {
     }
     return canonical;
 }
+// The byte-order mark, as a CHARACTER. RFC 8785 output never begins with
+// U+FEFF, so bytes that do are not conformant whatever a JSON reader makes of
+// them.
+const JCS_BOM = "";
+/**
+ * Read bytes that claim to be `jcs(value)` (RFC 8785), strictly. The Python
+ * twin is `jcs_loads` in `src/sanning_proof/canonicalize.py`, and every site in
+ * either kernel that reads bytes a producer signed goes through one of the two.
+ *
+ * ONE RULE, SPELLED OUT, BECAUSE TWO BUILT-INS ARE NOT ONE RULE. Four checks
+ * carry it, none of them left to a decoder's defaults: strict UTF-8, no leading
+ * byte-order mark, no non-finite literal (this kernel's `JSON.parse` rejects
+ * `NaN`, `Infinity` and `-Infinity` natively, and Python names them in a
+ * `parse_constant` hook), and no unpaired surrogate in the parsed value.
+ *
+ * THE FOURTH CHECK IS NOT THE FIRST ONE TWICE. The strict decode refuses a
+ * surrogate written as raw bytes; it cannot see one written as the ASCII
+ * escape `\ud800`, which `JSON.parse` turns into a lone code unit AFTER the
+ * decode has passed. `"c\ud800x"` is pure ASCII on the wire, so this reader
+ * accepted it while its own text above said it does not, and one poisoned
+ * record then deleted the Python kernel's whole chain reading (the gate on
+ * proof#154). Both spellings are the same malformed record, and both are
+ * refused here.
+ *
+ * `new TextDecoder()` alone is none of that. It replaces every invalid sequence
+ * with U+FFFD and strips a BOM. Python's `json.loads(<bytes>)` is not it
+ * either, in the opposite direction: CPython sniffs the encoding and decodes
+ * with `errors="surrogatepass"`, so it strips a UTF-8 BOM, accepts a UTF-16 or
+ * UTF-32 body, and passes a lone surrogate and a CESU-8 pair through. Both
+ * defaults have shipped a split verdict on one pack: a raw `0x80` inside a
+ * stamp body read `verified` here and `failed` there (gate 4), and then a
+ * `BOM + JCS(record)` checkpoint read `verified` there and `mixed` here (gate
+ * 5), both on proof#140. JCS is defined over UTF-8 and I-JSON (RFC 7493)
+ * forbids a lone surrogate, so each of those inputs is MALFORMED rather than
+ * another spelling of the same record.
+ *
+ * Throws for anything that is not conformant; every call site treats a throw as
+ * "this reader cannot read these bytes" and names the check that failed.
+ */
+export function jcsParse(bytes) {
+    const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    if (text.startsWith(JCS_BOM))
+        throw new Error("jcsParse: leading byte-order mark");
+    const value = JSON.parse(text);
+    rejectUnpairedSurrogates(value);
+    return value;
+}
+/**
+ * Refuse a parsed value carrying an unpaired surrogate, in a key or a value, at
+ * any depth. The Python twin is `_reject_unpaired_surrogates`, and the two name
+ * the failure with the same words.
+ *
+ * Deliberately ITERATIVE. `rejectLoneSurrogates` below walks a value this
+ * kernel is about to serialize, which `boundedInput` has already depth-bounded.
+ * This one walks whatever `JSON.parse` returned for a producer's bytes, with no
+ * bound in front of it, so a recursive walk would turn a deeply-nested record
+ * into a `RangeError` out of the reader itself.
+ */
+function rejectUnpairedSurrogates(value) {
+    const stack = [value];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (typeof node === "string") {
+            if (hasLoneSurrogate(node))
+                throw new Error("jcsParse: unpaired surrogate");
+        }
+        else if (Array.isArray(node)) {
+            for (const child of node)
+                stack.push(child);
+        }
+        else if (node !== null && typeof node === "object") {
+            for (const [key, child] of Object.entries(node)) {
+                if (hasLoneSurrogate(key))
+                    throw new Error("jcsParse: unpaired surrogate");
+                stack.push(child);
+            }
+        }
+    }
+}
 // Walk every string in the value (keys and values). The check must run on
 // the INPUT: `canonicalize` escapes a lone surrogate as `\udXXX` text in its
 // output, so the malformed code unit is invisible after serialization.
@@ -264,11 +347,34 @@ export function isRfc3339UtcInstant(value) {
 // present: §2 flags an absent `signed_at` as non-conformant rather than
 // rejecting it, and `environment` is optional in the skeleton.
 //
+// `public_key` AND `signature` ARE CHECKED HERE TOO (proof#146, under
+// proof#135 option B). The strict `hexToBytes` inside `ed25519Verify` is what
+// makes the three kernels agree on the VERDICT; naming the spelling is what
+// makes them agree on the REASON. On its own a respelled key reads `Ed25519
+// signature verification failed`, which sends an auditor looking for a forged
+// signature that is not there. proof#135 was opened against this function's
+// Python twin, for covering `signed_at` and `environment` and not `public_key`.
+//
+// ONLY A STRING IS CHECKED, the same rule `envelopeHexError` follows one layer
+// up: an absent or non-string `public_key` is already a failed signature in all
+// three kernels (Go names it "missing signature or public_key"), and naming it
+// here as a spelling would state one fact twice and in the wrong words. CASE IS
+// NOT CHECKED: proof#135 pinned the charset and left the case open.
+//
 // Own properties only, because those are the members `jcs` signs over.
 function skeletonFieldErrors(env) {
     const fields = env;
     const own = (k) => (Object.prototype.hasOwnProperty.call(fields, k) ? fields[k] : undefined);
     const out = [];
+    for (const [name, nibbles] of [
+        ["public_key", 64],
+        ["signature", 128],
+    ]) {
+        const value = own(name);
+        if (typeof value === "string" && !isHexField(value, nibbles)) {
+            out.push(`malformed ${name}: not ${nibbles} hex characters (envelope-spec §2)`);
+        }
+    }
     const signedAt = own("signed_at");
     if (signedAt !== undefined && !isRfc3339UtcInstant(signedAt)) {
         out.push("malformed signed_at: not an RFC 3339 UTC date-time with Z naming a real date and time (envelope-spec §2)");
@@ -356,6 +462,41 @@ export async function verifyEnvelope(env, optionsOrContentHash) {
             `Did you mean ${[...KNOWN_VERIFY_OPTIONS].join(" / ")}? ` +
             "Option keys are camelCase in the TypeScript kernel; the Python kernel uses snake_case.");
     }
+    // ── A verifier never raises on an input (proof#85 item 3) ──
+    //
+    // The option check above is the one exception and stays OUTSIDE this try: an
+    // unknown option key is the CALLER's mistake, not the envelope's, and turning
+    // a typo into a verdict is how a check silently never runs.
+    //
+    // Below, every field read is a read of attacker-shaped data. `env` is typed
+    // as an `Envelope`, but nothing enforces that at runtime, and an object whose
+    // property reads throw (a `get`-trap `Proxy`, a getter that raises, an
+    // exotic object from another realm) passed the null/non-object guard and then
+    // escaped as a raised exception. An auditor cannot tell a raised exception
+    // apart from a broken tool, which is the one thing this kernel exists not to
+    // hand them. CLAUDE.md states the rule flatly: malformed envelopes return a
+    // failed `VerificationResult`, they do not throw. This closes the class, not
+    // the one `Proxy` case: #77 hardened the anchor-trace path for the same
+    // reason, and a per-input patch would have to be written again for the next
+    // exotic object.
+    try {
+        return await verifyEnvelopeChecked(env, opts);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            specVersionOk: false,
+            // `null`, never `false`: nothing was read, so nothing was determined.
+            // The same rule the not-a-JSON-object branch below follows.
+            payloadHashOk: null,
+            signatureOk: false,
+            contentHashOk: opts.expectedContentHash === undefined ? null : false,
+            contentRole: null,
+            errors: [`envelope could not be read: ${stringifyErr(e)}`],
+        };
+    }
+}
+async function verifyEnvelopeChecked(env, opts) {
     const expectedContentHash = opts.expectedContentHash;
     const errors = [];
     // Guard a malformed input (null / non-object / array) up front — every field
@@ -409,6 +550,16 @@ export async function verifyEnvelope(env, optionsOrContentHash) {
     // inline payload, supplied committed bytes, or both. With neither, the
     // binding is undetermined (null): "signature-valid, semantics-undetermined"
     // (§3.1/§6.2). null does not fail the verdict; absence does.
+    //
+    // THE ENVELOPE'S OWN `payload_hash` IS NOT ECHOED INTO THESE REASONS, and
+    // that is a change (proof#154 F4). It is producer-controlled text of any
+    // length, and it went into an auditor-facing error list verbatim: a producer
+    // could put a newline and a forged `payload_hash: OK  envelope verified`
+    // line, or an ANSI escape that paints `VERIFIED` green, into what the
+    // verifier prints. No other field in this file echoes its value, the Python
+    // twin names the same failure without one, and the value is in the envelope
+    // the auditor already holds. The RECOMPUTED digest stays: this kernel
+    // produced it, so it is 64 characters of lowercase hex by construction.
     let payloadHashOk;
     if (typeof env.payload_hash !== "string") {
         payloadHashOk = false;
@@ -421,7 +572,7 @@ export async function verifyEnvelope(env, optionsOrContentHash) {
                 const recomputed = await sha256Hex(utf8(jcs(env.payload)));
                 checks.push(recomputed === env.payload_hash);
                 if (recomputed !== env.payload_hash) {
-                    errors.push(`payload_hash mismatch: envelope=${env.payload_hash} recomputed=${recomputed}`);
+                    errors.push(`payload_hash mismatch: the envelope's payload_hash is not SHA-256(JCS(payload)), recomputed=${recomputed}`);
                 }
             }
             catch (e) {
@@ -433,7 +584,7 @@ export async function verifyEnvelope(env, optionsOrContentHash) {
             const external = await sha256Hex(opts.payloadBytes);
             checks.push(external === env.payload_hash);
             if (external !== env.payload_hash) {
-                errors.push(`payload_hash does not match the committed bytes: envelope=${env.payload_hash} bytes=${external}`);
+                errors.push(`payload_hash does not match the committed bytes: bytes=${external}`);
             }
         }
         payloadHashOk = checks.length > 0 ? checks.every(Boolean) : null;
@@ -462,7 +613,7 @@ export async function verifyEnvelope(env, optionsOrContentHash) {
         const committed = contentHashes(env);
         if (committed.length === 0) {
             // UNDETERMINED, not failed. An external-commitment envelope
-            // (`sanning.events/v1`) has no inline payload, so it commits to no
+            // (`sanning.events/v2`) has no inline payload, so it commits to no
             // envelope-readable content hash and there is nothing here to compare
             // against. Reporting that as a failure would render "we cannot check
             // this" as "it did not match" — what P-10 and I-5 exist to prevent — and

package/package.json

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

package/src/agent-proof.ts

@@ -16,7 +16,7 @@
 
 import { hexToBytes, utf8 } from "./crypto.js";
 import { leafHash, verifyInclusion } from "./merkle.js";
-import { MAX_CANONICAL_DEPTH, exceedsDepth, jcs, verifyEnvelope } from "./verifier.js";
+import { MAX_CANONICAL_DEPTH, exceedsDepth, jcs, jcsParse, verifyEnvelope } from "./verifier.js";
 import type { Envelope } from "./types.js";
 
 export const AGENT_PROOF_SPEC_PREFIX = "sanning.agent.proof/v1";
@@ -213,7 +213,13 @@ async function refetch(
       const onChain = new Uint8Array(await resp.arrayBuffer());
       if (toHex(onChain) === expectedHex) return { ok: true, unavailable: false };
       try {
-        const parsed = JSON.parse(new TextDecoder().decode(onChain));
+        // `jcsParse`, matching `_probe_gateway` in
+        // `src/sanning_proof/evidence.py`. These bytes arrive from a gateway or
+        // a CDN in front of one, so a lenient decoder is reachable without any
+        // party building a pack: a CDN serving the envelope with a byte-order
+        // mark split this probe from the one in `evidence.ts`, and two honest
+        // readers of ONE transaction disagreed (proof#140 gate 5).
+        const parsed = jcsParse(onChain);
         if (toHex(utf8(jcs(parsed))) === expectedHex) return { ok: true, unavailable: false };
       } catch {
         // fall through