@sanning/proof 0.15.0 → 0.17.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/declaration.ts

@@ -131,10 +131,15 @@
 // The kernel's one reader for bytes a producer signed: strict UTF-8, no leading
 // byte-order mark, no non-finite literal. `jcs_loads` in
 // `src/sanning_proof/canonicalize.py` is the twin (proof#140 gate 5).
-import { hexToBytes } from "./crypto.js";
-import { jcsParse } from "./verifier.js";
+import { hexToBytes, utf8 } from "./crypto.js";
+import { jcs, jcsParse } from "./verifier.js";
 import { isConformantHandoffRecord, isHandoffNamespace, type HandoffRecord } from "./handoff.js";
-import { hasSideContent, inBodyContentOffered, type SideContentMap } from "./side-content.js";
+import {
+  hasSideContent,
+  inBodyContentOffered,
+  sideContentEntry,
+  type SideContentMap,
+} from "./side-content.js";
 
 /** The first declaration schema, which every earlier reader knows. */
 export const DECLARATION_VERSION = "sanning.declaration/v1";
@@ -278,6 +283,23 @@ export const DECLARATION_NOTE_KINDS = [
    * because its payload binding is undetermined.
    */
   "role_step_withheld",
+  /**
+   * Rule 10 (v1.29, A36). A record whose signed `event_type` is `declaration`
+   * and whose content HANDED IN to this reader is exactly `JCS(object)` of a
+   * declaration object of a version this reader knows, carrying exactly that
+   * version's keys, and not this pack's own. The note names the content handed
+   * in, never the record: whether those bytes bind to the record's
+   * `content_hash` is the bundle verifier's check, and an accuser can hand in
+   * declaration-shaped bytes for an honest record. What the pack holds is what
+   * the declaration in its body says, so this moves no verdict.
+   */
+  "other_declaration_held",
+  /**
+   * Rule 10. A record whose signed `event_type` is `declaration` and whose
+   * content did not reach this reader from either channel, so whether it is a
+   * declaration other than this pack's own is UNKNOWN.
+   */
+  "other_declaration_withheld",
 ] as const;
 export type DeclarationNoteKind = (typeof DECLARATION_NOTE_KINDS)[number];
 
@@ -698,6 +720,149 @@ function roleReading(
   return null;
 }
 
+/**
+ * The `event_type` a declaration record is signed under: a reserved
+ * single-segment name, and the one `@sanning/anchor`'s `bundle` anchors a
+ * declaration as.
+ */
+const DECLARATION_EVENT_TYPE = "declaration";
+
+/**
+ * The keys a declaration object carries, under every version this reader
+ * knows: exactly these, no more and no fewer (5.4.1).
+ */
+const DECLARATION_KEYS = ["declaration_version", "case_id", "agents", "period", "records", "handoffs"];
+
+function hasExactKeys(value: unknown, keys: string[]): value is Record<string, unknown> {
+  if (!isObject(value)) return false;
+  const have = Object.keys(value);
+  return have.length === keys.length && keys.every((k) => Object.prototype.hasOwnProperty.call(value, k));
+}
+
+/**
+ * Whether `obj` is shaped like a declaration this reader knows: one of
+ * `DECLARATION_VERSIONS` compared exactly, exactly the keys that version
+ * defines, and the value types this module reads.
+ *
+ * It is the shape test `@sanning/anchor`'s `isDeclarationShape` makes, and it
+ * checks shape only, not the 5.4.1 rules `readDeclaration` grades: a stale
+ * declaration is somebody else's claim, and this reader does not grade it, it
+ * names it.
+ */
+function isDeclarationShape(obj: unknown): boolean {
+  if (!isObject(obj)) return false;
+  const version = obj["declaration_version"];
+  if (version !== DECLARATION_VERSION && version !== DECLARATION_VERSION_V2) return false;
+  if (!hasExactKeys(obj, DECLARATION_KEYS)) return false;
+  if (!isId(obj["case_id"])) return false;
+  const agents = obj["agents"];
+  if (!Array.isArray(agents) || !agents.every((a) => typeof a === "string")) return false;
+  const period = obj["period"];
+  if (!hasExactKeys(period, ["start", "end"])) return false;
+  if (typeof period["start"] !== "string" || typeof period["end"] !== "string") return false;
+  const recordKeys =
+    version === DECLARATION_VERSION_V2 ? ["event_id", "disclosure", "role"] : ["event_id", "disclosure"];
+  const records = obj["records"];
+  if (!Array.isArray(records)) return false;
+  for (const r of records) {
+    if (!hasExactKeys(r, recordKeys) || typeof r["event_id"] !== "string") return false;
+  }
+  const handoffs = obj["handoffs"];
+  if (!Array.isArray(handoffs)) return false;
+  return handoffs.every((h) => hasExactKeys(h, ["sent_event_id", "received_event_id"]));
+}
+
+/**
+ * The content bytes disclosed for one record, or `null` where none are usable:
+ * `events[].content` first, then the side-content map, chosen the way the
+ * bundle verifier chooses the bytes it binds.
+ */
+function disclosedBytes(
+  ev: unknown,
+  p: PackRecord,
+  content: SideContentMap | null | undefined,
+): Uint8Array | null {
+  const inBody = isObject(ev) ? ev["content"] : undefined;
+  if (typeof inBody === "string") {
+    try {
+      return hexToBytes(inBody);
+    } catch {
+      // falls through to the side channel, as the bundle verifier does
+    }
+  }
+  if (!p.nameable) return null;
+  const side = sideContentEntry(content, p.eventId).value;
+  if (side instanceof Uint8Array) return side;
+  if (typeof side === "string") {
+    try {
+      return hexToBytes(side);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/**
+ * Whether `raw` is exactly `JCS(object)` of a declaration-shaped object.
+ * Canonical bytes, not merely parseable ones: a declaration is anchored as
+ * `JCS(declaration)`, and nothing an agent writes by accident.
+ */
+function isDeclarationBytes(raw: Uint8Array): boolean {
+  try {
+    const obj = jcsParse(raw);
+    return isDeclarationShape(obj) && sameBytes(utf8(jcs(obj)), raw);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Rule 10: every record that is a declaration other than the pack's own, in
+ * bundle order.
+ *
+ * The record's `event_type` is read from its signed `event_bytes`, so a record
+ * whose bytes the pack withholds is not named: the reader cannot see what it
+ * was signed as. Its content is read from either channel; a record whose
+ * content is byte for byte `JCS` of the pack's own declaration is the pack's
+ * own and is never named.
+ */
+function otherDeclarationNotes(
+  bundle: unknown,
+  pack: PackRecord[],
+  declaration: unknown,
+  content: SideContentMap | null | undefined,
+): DeclarationNote[] {
+  const events = pack.length > 0 ? (bodyOf(bundle)?.events ?? []) : [];
+  let own: Uint8Array | null = null;
+  try {
+    own = utf8(jcs(declaration));
+  } catch {
+    own = null;
+  }
+  const notes: DeclarationNote[] = [];
+  pack.forEach((p, i) => {
+    if (p.record === null || p.record.event_type !== DECLARATION_EVENT_TYPE) return;
+    const raw = disclosedBytes(events[i], p, content);
+    if (raw === null) {
+      // Offered and unusable is not withheld: something arrived, it is not a
+      // declaration, and the bundle verifier names what is wrong with it.
+      // Nothing arrived is the reading the reader cannot settle.
+      if (!p.disclosed) notes.push({ kind: "other_declaration_withheld", eventId: p.eventId });
+      return;
+    }
+    if (own !== null && sameBytes(raw, own)) return;
+    if (isDeclarationBytes(raw)) notes.push({ kind: "other_declaration_held", eventId: p.eventId });
+  });
+  return notes;
+}
+
 /**
  * Check a pack against the declaration inside its body.
  *
@@ -915,6 +1080,12 @@ export function checkDeclaration(
     }
   }
 
+  // Rule 10 (5.4.2 v1.29, A36): content handed in for a record signed
+  // `declaration` that is a declaration other than this pack's own. Notes only, in bundle order, after every other note, and
+  // never a deviation: the pack holds what its own declaration says whatever
+  // one of its records says.
+  notes.push(...otherDeclarationNotes(bundle, pack, declaration, content));
+
   // A proven deviation wins: it is a mismatch between what the pack claimed
   // and what its own signed body carries, and a failing check always wins.
   // With no deviation and a content-dependent finding, the pack lines up with
@@ -1120,6 +1291,18 @@ export function renderNote(note: DeclarationNote): string {
         `${note.eventId} is signed as a step and this pack withholds its ` +
         "record bytes, so whether it is one is UNKNOWN"
       );
+    case "other_declaration_held":
+      return (
+        `the content handed in for ${note.eventId} is a declaration that is ` +
+        "not this pack's own: it says what some pack holds, and what this " +
+        "pack holds is what the declaration in its body says"
+      );
+    case "other_declaration_withheld":
+      return (
+        `${note.eventId} is signed as a declaration and no content for it ` +
+        "reached this verifier, so whether it is a declaration other than " +
+        "this pack's own is UNKNOWN"
+      );
   }
 }
 

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 ?? ""),
           );