@sanning/proof 0.16.0 → 0.18.0

package/src/compose.ts

@@ -105,6 +105,23 @@ function normalizeAttestation(rec: AttestationRecord): AttestationRecord {
   return cloned;
 }
 
+// True when `value` holds a number that is NaN or +-Infinity. Iterative, so a
+// deeply nested input cannot overflow the stack before `jcs` bounds it.
+function hasNonFiniteNumber(value: unknown): boolean {
+  const stack: unknown[] = [value];
+  while (stack.length > 0) {
+    const v = stack.pop();
+    if (typeof v === "number") {
+      if (!Number.isFinite(v)) return true;
+    } else if (Array.isArray(v)) {
+      for (const x of v) stack.push(x);
+    } else if (v !== null && typeof v === "object") {
+      for (const x of Object.values(v)) stack.push(x);
+    }
+  }
+  return false;
+}
+
 // Compose an attested evidence export (evidence-export.md §5).
 //
 // 1. Normalize + transcode the attestation records (boundary hex, above).
@@ -133,6 +150,22 @@ export async function composeExport(
     throw new Error("composeExport: exporterKey.privateKey (32-byte hex seed) is required");
   }
 
+  // An over-long integer reads as Infinity (proof#217), which `jcs` refuses in
+  // the runtime's own words. Say it once, in the kernel's, before any
+  // verification: both kernels write this sentence, with no function-name prefix, so the CLI line is byte-identical.
+  if (hasNonFiniteNumber(sourceBundle)) {
+    throw new Error(
+      "the source bundle carries a number that is not a finite JSON number " +
+        "(an integer past the 1.8e308 range, or too long to read)",
+    );
+  }
+  if (hasNonFiniteNumber(attestations)) {
+    throw new Error(
+      "the attestations carry a number that is not a finite JSON number " +
+        "(an integer past the 1.8e308 range, or too long to read)",
+    );
+  }
+
   if (options.generatedAt !== undefined && !isRfc3339UtcInstant(options.generatedAt)) {
     // The verifier reads this as `malformed generated_at` (evidence-bundle §2,
     // A31), so composing one would sign an export this kernel rejects.

package/src/crypto.ts

@@ -8,8 +8,10 @@ import * as ed from "@noble/ed25519";
 // @noble/ed25519 needs SHA-512 to verify. Wire it to WebCrypto rather than
 // pulling in @noble/hashes. globalThis.crypto.subtle exists in every modern
 // browser and in Node >= 19, so the same code path runs in the app and in tests.
-ed.etc.sha512Async = async (...msgs: Uint8Array[]): Promise<Uint8Array> =>
-  new Uint8Array(await crypto.subtle.digest("SHA-512", asBufferSource(ed.etc.concatBytes(...msgs))));
+// noble 3 ships this provider as its default; it is set here so the kernel
+// says what it hashes with rather than inheriting it.
+ed.hashes.sha512Async = async (message) =>
+  new Uint8Array(await crypto.subtle.digest("SHA-512", asBufferSource(message)));
 
 // WebCrypto's digest() wants a BufferSource backed by a (non-shared) ArrayBuffer.
 // Our byte arrays always are; this keeps TS 5.7's stricter Uint8Array<ArrayBufferLike>
@@ -76,10 +78,125 @@ export async function sha256Hex(bytes: Uint8Array): Promise<string> {
   return bytesToHex(await sha256Bytes(bytes));
 }
 
-// Verify an Ed25519 signature. Inputs are hex (signature, public key) as they
-// appear in the envelope; message is raw bytes. Never throws — a malformed
-// signature or key is "not verified," not an exception, so a hostile envelope
-// can't crash the checker.
+// ---------------------------------------------------------------------------
+// The Ed25519 rule (envelope-spec §7, A44, proof#230)
+//
+// Strict RFC 8032 (`zip215: false`, a frozen invariant), and more: the public
+// key A and the signature's R must each be the canonical encoding of a point
+// in the prime-order subgroup other than the identity, and S below the group
+// order L. Only then is the equation checked.
+//
+// Why more than `zip215: false`: noble checks the equation with the cofactor,
+// 8·S·B = 8·R + 8·k·A, and Go's crypto/ed25519 and libsodium without it, so on
+// their own they disagree when A or R has a small-order component. noble 2.3
+// also could not encode an identity R and hashed nothing for k, so it accepted
+// one signature from a key holder over every message. With A and R in the
+// prime-order subgroup the two equations are the same equation, and every
+// kernel accepts exactly the same signatures.
+//
+// Each clause is checked here, in this order, and named in these words: the
+// Python twin is `ed25519_rule_reason` in `src/sanning_proof/ed25519_rule.py`
+// and the Go kernel's `verifyEd25519Strict` in sanning-io/agent `pkg/proof`.
+// Several clauses are ones noble 3 refuses on its own; they are checked here
+// anyway so the refusal names the clause, which a library's `false` cannot.
+
+/** The sentence a refused signature reads in an envelope result. */
+export const SIGNATURE_FAILED = "Ed25519 signature verification failed";
+
+export const ED25519_RULE_REASONS = [
+  "the public key is not the canonical encoding of a point",
+  "the public key is a point of small order",
+  "the public key is not in the prime-order subgroup",
+  "R is not the canonical encoding of a point",
+  "R is the identity",
+  "R is a point of small order",
+  "R is not in the prime-order subgroup",
+  "S is not below the group order",
+] as const;
+
+const [
+  KEY_NOT_CANONICAL,
+  KEY_SMALL_ORDER,
+  KEY_NOT_IN_SUBGROUP,
+  R_NOT_CANONICAL,
+  R_IDENTITY,
+  R_SMALL_ORDER,
+  R_NOT_IN_SUBGROUP,
+  S_NOT_BELOW_L,
+] = ED25519_RULE_REASONS;
+
+const ED25519_L = 2n ** 252n + 27742317777372353535851937790883648493n;
+
+function bytesToNumberLE(bytes: Uint8Array): bigint {
+  let v = 0n;
+  for (let i = bytes.length - 1; i >= 0; i--) v = (v << 8n) | BigInt(bytes[i]);
+  return v;
+}
+
+// `Point.fromBytes(..., false)` is RFC 8032 decoding with its two strict
+// branches: it throws on y at or above p and on x zero with the sign bit set,
+// the two non-canonical encodings of a point, and on bytes that are no point.
+function decodeStrict(bytes: Uint8Array): ed.Point | null {
+  try {
+    return ed.Point.fromBytes(bytes, false);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The clause of the rule that (`publicKey`, `signature`) breaks, or `null`
+ * when it breaks none and the equation is what is left to check. Lengths are
+ * the caller's (32 and 64 bytes). Never throws.
+ */
+export function ed25519RuleReason(signature: Uint8Array, publicKey: Uint8Array): string | null {
+  const A = decodeStrict(publicKey);
+  if (A === null) return KEY_NOT_CANONICAL;
+  if (A.isSmallOrder()) return KEY_SMALL_ORDER;
+  if (!A.isTorsionFree()) return KEY_NOT_IN_SUBGROUP;
+  const R = decodeStrict(signature.subarray(0, 32));
+  if (R === null) return R_NOT_CANONICAL;
+  if (R.is0()) return R_IDENTITY;
+  if (R.isSmallOrder()) return R_SMALL_ORDER;
+  if (!R.isTorsionFree()) return R_NOT_IN_SUBGROUP;
+  if (bytesToNumberLE(signature.subarray(32, 64)) >= ED25519_L) return S_NOT_BELOW_L;
+  return null;
+}
+
+/**
+ * `null` iff `signatureHex` is a signature of `message` under `publicKeyHex`
+ * by the rule; otherwise the sentence the refusal reads: `SIGNATURE_FAILED`,
+ * with `": "` and the clause of the rule it broke when it broke one. A
+ * malformed field, a wrong length and an equation that does not hold read
+ * the bare sentence. Never throws. The Python twin is `ed25519_refusal`.
+ */
+export async function ed25519Refusal(
+  message: Uint8Array,
+  signatureHex: string,
+  publicKeyHex: string,
+): Promise<string | null> {
+  let signature: Uint8Array;
+  let publicKey: Uint8Array;
+  try {
+    signature = hexToBytes(signatureHex);
+    publicKey = hexToBytes(publicKeyHex);
+  } catch {
+    return SIGNATURE_FAILED;
+  }
+  if (signature.length !== 64 || publicKey.length !== 32) return SIGNATURE_FAILED;
+  const reason = ed25519RuleReason(signature, publicKey);
+  if (reason !== null) return `${SIGNATURE_FAILED}: ${reason}`;
+  try {
+    return (await ed.verifyAsync(signature, message, publicKey, { zip215: false })) ? null : SIGNATURE_FAILED;
+  } catch {
+    return SIGNATURE_FAILED;
+  }
+}
+
+// Verify an Ed25519 signature by the rule above. Inputs are hex (signature,
+// public key) as they appear in the envelope; message is raw bytes. Never
+// throws — a malformed signature or key is "not verified," not an exception,
+// so a hostile envelope can't crash the checker.
 // Arguments in the Python twin's order, `ed25519_verify(message,
 // signature_hex, public_key_hex)` (P-03, 0.13.0). The message came second
 // until 0.13.0; a caller that still passes the signature first gets a compile
@@ -89,22 +206,14 @@ export async function ed25519Verify(
   signatureHex: string,
   publicKeyHex: string,
 ): Promise<boolean> {
-  try {
-    // zip215:false → strict RFC-8032 verification, matching the Go agent's
-    // crypto/ed25519 exactly (noble defaults to the more lenient zip215:true).
-    return await ed.verifyAsync(hexToBytes(signatureHex), message, hexToBytes(publicKeyHex), {
-      zip215: false,
-    });
-  } catch {
-    return false;
-  }
+  return (await ed25519Refusal(message, signatureHex, publicKeyHex)) === null;
 }
 
 // Ed25519 SIGN the raw `message` bytes with a 32-byte private-key seed (lowercase
 // hex). Returns the signature as lowercase hex. The signing counterpart to
 // ed25519Verify — the ONE signing primitive the composer (`proof export`,
 // evidence-export.md §5) needs to Ed25519-sign the export wrapper with the
-// exporter's key ("anyone can export", P-4). The @noble sha512Async hook wired at
+// exporter's key ("anyone can export", P-4). The @noble sha512Async provider wired at
 // module load serves signing and verification alike, so this stays WebCrypto-only.
 export async function ed25519Sign(message: Uint8Array, privateKeyHex: string): Promise<string> {
   return bytesToHex(await ed.signAsync(message, hexToBytes(privateKeyHex)));

package/src/evidence.ts

@@ -29,6 +29,7 @@ import {
   utf8,
   verifyRsaPssSha256,
 } from "./crypto.js";
+import { safeInteger, signedLeafCount } from "./grading.js";
 import { isConformantHandoffRecord, isHandoffNamespace, type HeldRecord } from "./handoff.js";
 import { leafHash, verifyInclusion } from "./merkle.js";
 import {
@@ -1316,6 +1317,7 @@ async function verifyAnchorTrace(
     const cpErrors: string[] = [];
     let envelopeOk = false;
     let merkleRootOk = false;
+    let leafCountOk = false;
 
     // Decode event_bytes first: in v2 the join key is DERIVED from it, so it
     // is an input to identity, not just to the payload binding below.
@@ -1406,6 +1408,14 @@ async function verifyAnchorTrace(
               `committed=${jsonStr(committedRoot)}`,
           );
         }
+        // §5.1, A38 (proof#197), decided by Phil 2026-10-06: fail closed. The
+        // count the record signs is what every inclusion bound to this
+        // checkpoint is held to, so a record that signs no integer count fails
+        // the checkpoint, as a record that signs no merkle_root does. Read by
+        // value through the one reader the inclusion compare and the
+        // completeness notes share, so `3.0` and `3e0` are 3.
+        leafCountOk = signedLeafCount(cp as { event_bytes?: unknown }) !== null;
+        if (!leafCountOk) cpErrors.push("checkpoint record leaf_count is not an integer");
       } catch (e) {
         cpErrors.push(`checkpoint record is not JSON${thrownDetail(e)}`);
       }
@@ -1424,7 +1434,7 @@ async function verifyAnchorTrace(
       // standing rule is that malformed is a failure while absent is
       // undetermined (the same rule disclosed `content` follows). Without
       // this term the vector `trace-v2-malformed-anchor-ref` verified GREEN.
-      ok: envelopeOk && merkleRootOk && keyed.errors.length === 0 && !duplicateKey,
+      ok: envelopeOk && merkleRootOk && leafCountOk && keyed.errors.length === 0 && !duplicateKey,
       errors: cpErrors,
     });
     if (keyed.anchorRefMalformed) {
@@ -1554,36 +1564,66 @@ async function verifyAnchorTrace(
     const checkpointBound = cp !== undefined;
 
     let inclusionOk = false;
+    // §5.1, A38 (proof#197): the tree walked must be the tree the checkpoint
+    // record signed, the same rule and the same sentence as the stamp path's
+    // rule 3. RFC 9162's walk reads one audit path as valid at more than one
+    // (leaf_index, leaf_count), so without this a real proof at (2, 3) also
+    // verified as (1, 2) or (4, 5). A signed count that cannot be read is not
+    // compared here: it has already failed its checkpoint (above), so the
+    // bundle cannot verify. One reader of the signed count, shared with the
+    // completeness notes, so the verdict and the grade never read two
+    // different numbers.
+    //
+    // Every number here is read BY VALUE (`Number.isSafeInteger`), the model
+    // JCS signs, and the Python kernel reads the same way (`_safe_integer`):
+    // JCS writes `3.0` as `3`, so a stated `3.0` is the integer 3 under the
+    // same wrapper signature. A value that is not a safe integer is malformed,
+    // with one sentence that prints no value, because the two kernels cannot
+    // print `2.5`, `1e400` or `9007199254740993` the same way.
+    const signedCount = cp ? signedLeafCount(cp as { event_bytes?: unknown }) : null;
     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)),
-          // 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),
+      const statedCount = safeInteger(incl.leaf_count);
+      const statedIndex = safeInteger(incl.leaf_index);
+      if (statedCount === null) {
+        evErrors.push("inclusion leaf_count is not an integer");
+      } else if (statedIndex === null) {
+        evErrors.push("inclusion leaf_index is not an integer");
+      } else if (signedCount !== null && statedCount !== signedCount) {
+        evErrors.push(
+          `inclusion leaf_count ${statedCount} does not equal ` +
+            `the checkpoint's committed leaf_count ${signedCount}`,
         );
-        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))`,
+      } else {
+        try {
+          inclusionOk = await verifyInclusion(
+            hexToBytes(incl.leaf_hash),
+            statedIndex,
+            statedCount,
+            (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 as string),
           );
+          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${thrownDetail(e)}`);
         }
-      } catch (e) {
-        evErrors.push(`inclusion verify error${thrownDetail(e)}`);
       }
     }
 
@@ -1784,8 +1824,16 @@ function isLowerHex(s: unknown, nibbles?: number): s is string {
   return /^[0-9a-f]+$/.test(s);
 }
 
-function isNonNegInt(n: unknown): n is number {
-  return typeof n === "number" && Number.isInteger(n) && n >= 0;
+/**
+ * A JSON number read BY VALUE as a non-negative safe integer, or null.
+ * `safeInteger`, the reader every leaf count and leaf index in this kernel
+ * goes through (A38), mirrored by `_non_neg_integer` in
+ * `src/sanning_proof/evidence.py`. `Number.isInteger` alone accepted `1e+21`,
+ * JCS's own spelling of a count past 2**53 - 1, which Python refused.
+ */
+function nonNegInteger(n: unknown): number | null {
+  const v = safeInteger(n);
+  return v !== null && v >= 0 ? v : null;
 }
 
 /**
@@ -2060,11 +2108,12 @@ async function verifyStampEntry(
   } else {
     base.merkleRoot = body.merkle_root;
   }
-  if (!isNonNegInt(body.leaf_count)) {
+  const stampCount = nonNegInteger(body.leaf_count);
+  if (stampCount === null) {
     errors.push("stamp body leaf_count is not a non-negative integer");
     base.bodyOk = false;
   } else {
-    base.leafCount = body.leaf_count;
+    base.leafCount = stampCount;
   }
 
   // --- the sub-tree ranges --------------------------------------------------
@@ -2108,14 +2157,16 @@ function checkSubtrees(body: StampBody, out: StampResult, errors: string[]): boo
       continue;
     }
     const s = v as Partial<StampSubtree>;
-    if (!isNonNegInt(s.first_leaf)) {
+    const firstLeaf = nonNegInteger(s.first_leaf);
+    const subCount = nonNegInteger(s.leaf_count);
+    if (firstLeaf === null) {
       errors.push(`sub-tree ${ref} first_leaf is not a non-negative integer`);
       shapeOk = false;
     }
     // A zero-leaf sub-tree is not a slice of anything, and admitting one lets
     // an arbitrary number of empty ranges sit inside a tiling that still adds
     // up.
-    if (!isNonNegInt(s.leaf_count) || s.leaf_count === 0) {
+    if (subCount === null || subCount === 0) {
       errors.push(`sub-tree ${ref} leaf_count is not a positive integer`);
       shapeOk = false;
     }
@@ -2126,8 +2177,8 @@ function checkSubtrees(body: StampBody, out: StampResult, errors: string[]): boo
     if (!shapeOk) continue;
     subtrees.push({
       ref,
-      firstLeaf: s.first_leaf as number,
-      leafCount: s.leaf_count as number,
+      firstLeaf: firstLeaf as number,
+      leafCount: subCount as number,
       root: s.root as string,
     });
   }
@@ -2135,11 +2186,14 @@ function checkSubtrees(body: StampBody, out: StampResult, errors: string[]): boo
   out.subtrees = subtrees;
   if (!shapeOk) return false;
 
-  const total = body.leaf_count;
-  if (!isNonNegInt(total)) return false; // already reported by the caller
+  const total = out.leafCount;
+  if (total === null) return false; // already reported by the caller
 
-  const sum = subtrees.reduce((n, s) => n + s.leafCount, 0);
-  if (sum !== total) {
+  // Summed exactly. Each count is a safe integer but their sum need not be,
+  // and a float sum past 2**53 prints a different number than Python's
+  // unbounded one in the sentence below.
+  const sum = subtrees.reduce((n, s) => n + BigInt(s.leafCount), 0n);
+  if (sum !== BigInt(total)) {
     errors.push(
       `sub-tree leaf_count sum ${sum} does not equal the stamp's leaf_count ${total}`,
     );
@@ -2428,17 +2482,29 @@ async function verifyStampEvidence(
       // Rule 3: the tree walked must be the tree the stamp committed to. A
       // proof walked against a different leaf_count is a proof about a
       // different tree, and RFC 9162's path shape depends on the size.
-      if (st.leafCount !== null && incl.leaf_count !== st.leafCount) {
+      //
+      // Read BY VALUE, as the anchor-trace path reads them (A38), and as the
+      // Python kernel does (`_safe_integer`): the wrapper signs JCS(body),
+      // which writes `3.0` as `3`, so a stated `3.0` is 3 under the same
+      // signature. Anything that is not a safe integer is malformed, with a
+      // sentence that prints no value.
+      const statedCount = safeInteger(incl.leaf_count);
+      const statedIndex = safeInteger(incl.leaf_index);
+      if (statedCount === null) {
+        evErrors.push("inclusion leaf_count is not an integer");
+      } else if (statedIndex === null) {
+        evErrors.push("inclusion leaf_index is not an integer");
+      } else if (st.leafCount !== null && statedCount !== st.leafCount) {
         evErrors.push(
-          `inclusion leaf_count ${incl.leaf_count} does not equal the stamp's committed ` +
+          `inclusion leaf_count ${statedCount} does not equal the stamp's committed ` +
             `leaf_count ${st.leafCount}`,
         );
       } else {
         try {
           inclusionOk = await verifyInclusion(
             hexToBytes(incl.leaf_hash),
-            incl.leaf_index,
-            incl.leaf_count,
+            statedIndex,
+            statedCount,
             (incl.audit_path ?? []).map((h) => hexToBytes(h)),
             hexToBytes(st.merkleRoot ?? ""),
           );