@sanning/proof 0.16.0 → 0.17.0

package/dist/compose.js

@@ -51,6 +51,27 @@ function normalizeAttestation(rec) {
     cloned.signature = attestationSignatureToHex(cloned.signature);
     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) {
+    const stack = [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).
@@ -73,6 +94,17 @@ export async function composeExport(sourceBundle, attestations, exporterKey, opt
     if (typeof exporterKey?.privateKey !== "string" || exporterKey.privateKey.length === 0) {
         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/dist/evidence.js

@@ -21,6 +21,7 @@ import { deriveOperatorAddress, ed25519Verify, hexToBytes,
 // body: two copies of one rule is how two kernels drift apart one edit at a
 // time, which is the whole defect class this fix is about.
 isHexField, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
+import { safeInteger, signedLeafCount } from "./grading.js";
 import { isConformantHandoffRecord, isHandoffNamespace } from "./handoff.js";
 import { leafHash, verifyInclusion } from "./merkle.js";
 import { DuplicateKeyError, MAX_CANONICAL_DEPTH, contentHashes, exceedsDepth, isRfc3339UtcInstant, jcs, jcsParse, verifyEnvelope, } from "./verifier.js";
@@ -683,6 +684,7 @@ async function verifyAnchorTrace(b, specVersionOk, assertedStatus, errors, optio
         const cpErrors = [];
         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.
         let eventBytes;
@@ -770,6 +772,15 @@ async function verifyAnchorTrace(b, specVersionOk, assertedStatus, errors, optio
                     cpErrors.push(`checkpoint merkle_root mismatch: claimed=${jsonStr(cp.merkle_root)} ` +
                         `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) !== null;
+                if (!leafCountOk)
+                    cpErrors.push("checkpoint record leaf_count is not an integer");
             }
             catch (e) {
                 cpErrors.push(`checkpoint record is not JSON${thrownDetail(e)}`);
@@ -788,7 +799,7 @@ async function verifyAnchorTrace(b, specVersionOk, assertedStatus, errors, optio
             // 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) {
@@ -919,30 +930,61 @@ async function verifyAnchorTrace(b, specVersionOk, assertedStatus, errors, optio
         }
         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) : 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));
-                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))`);
-                }
+            const statedCount = safeInteger(incl.leaf_count);
+            const statedIndex = safeInteger(incl.leaf_index);
+            if (statedCount === null) {
+                evErrors.push("inclusion leaf_count is not an integer");
             }
-            catch (e) {
-                evErrors.push(`inclusion verify error${thrownDetail(e)}`);
+            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}`);
+            }
+            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));
+                    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)}`);
+                }
             }
         }
         // Content (raw-log) binding — shared with every other event-carrying body.
@@ -1143,8 +1185,16 @@ function isLowerHex(s, nibbles) {
         return false;
     return /^[0-9a-f]+$/.test(s);
 }
-function isNonNegInt(n) {
-    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) {
+    const v = safeInteger(n);
+    return v !== null && v >= 0 ? v : null;
 }
 /**
  * Parse and check one stamp's witnessed bytes.
@@ -1382,12 +1432,13 @@ async function verifyStampEntry(raw, seen) {
     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 --------------------------------------------------
     base.subtreesOk = checkSubtrees(body, base, errors);
@@ -1426,14 +1477,16 @@ function checkSubtrees(body, out, errors) {
             continue;
         }
         const s = v;
-        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;
         }
@@ -1445,8 +1498,8 @@ function checkSubtrees(body, out, errors) {
             continue;
         subtrees.push({
             ref,
-            firstLeaf: s.first_leaf,
-            leafCount: s.leaf_count,
+            firstLeaf: firstLeaf,
+            leafCount: subCount,
             root: s.root,
         });
     }
@@ -1454,11 +1507,14 @@ function checkSubtrees(body, out, errors) {
     out.subtrees = subtrees;
     if (!shapeOk)
         return false;
-    const total = body.leaf_count;
-    if (!isNonNegInt(total))
+    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}`);
         return false;
     }
@@ -1715,13 +1771,27 @@ async function verifyStampEvidence(b, specVersionOk, assertedStatus, errors, opt
             // 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) {
-                evErrors.push(`inclusion leaf_count ${incl.leaf_count} does not equal the stamp's committed ` +
+            //
+            // 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 ${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, (incl.audit_path ?? []).map((h) => hexToBytes(h)), hexToBytes(st.merkleRoot ?? ""));
+                    inclusionOk = await verifyInclusion(hexToBytes(incl.leaf_hash), statedIndex, statedCount, (incl.audit_path ?? []).map((h) => hexToBytes(h)), hexToBytes(st.merkleRoot ?? ""));
                     if (!inclusionOk) {
                         evErrors.push("RFC 9162 inclusion proof did not reconstruct the stamp root");
                     }

package/dist/file-match.d.ts

@@ -47,6 +47,13 @@ export declare const FILE_MATCH_SCOPE: string;
 /** Why a record's commitments could not be read, in the order they are tested. */
 export declare const NOT_READ_REASONS: readonly ["no_records", "record_unreadable", "record_not_verified", "record_withheld", "no_content_hash", "handoff_record_malformed", "message_withheld"];
 export type NotReadReason = (typeof NOT_READ_REASONS)[number];
+/**
+ * Why a file was named in the report and never hashed (5.7.5). A skipped file
+ * is listed, never dropped: every file a command found is matched, unmatched or
+ * skipped, so "no match" is never read as "no file was there".
+ */
+export declare const SKIPPED_REASONS: readonly ["symbolic_link", "not_regular", "unreadable", "too_large", "refused"];
+export type SkippedReason = (typeof SKIPPED_REASONS)[number];
 /** One commitment a signed record makes to a file's bytes. */
 export interface FileCommitment {
     packRef: string | null;
@@ -56,6 +63,14 @@ export interface FileCommitment {
     contentHash: string;
     signer: string;
     signedAt: string | null;
+    /**
+     * The pack, by its position in the packs `matchCaseFiles` was handed (the
+     * same position the case reading's `packIndex` names), or `null` from
+     * `matchFiles`, which reads one pack (A43).
+     */
+    packIndex: number | null;
+    /** The record, by its position in the events the pack presents (A43). */
+    recordIndex: number;
 }
 export interface MatchedFile {
     name: string;
@@ -66,10 +81,24 @@ export interface UnmatchedFile {
     name: string;
     sha256: string;
 }
+/** A file a command found and did not hash, named with the reason. */
+export interface SkippedFile {
+    name: string;
+    reason: SkippedReason;
+    /** The reader's own words, for a `.zip` entry it refused (`refused`). */
+    detail?: string;
+}
 export interface NotRead {
     packRef: string | null;
     eventId: string | null;
     reason: NotReadReason;
+    /** As on `FileCommitment` (A43). */
+    packIndex: number | null;
+    /**
+     * As on `FileCommitment`, or `null` where the pack presents no events at all
+     * (`no_records`).
+     */
+    recordIndex: number | null;
 }
 export interface FileMatchReading {
     offered: number;
@@ -78,12 +107,27 @@ export interface FileMatchReading {
     notOffered: FileCommitment[];
     notRead: NotRead[];
     scope: string;
+    /**
+     * Files found and not hashed. The matching functions leave it empty: it is
+     * the caller's, because only a caller that reads a folder knows a link.
+     */
+    skipped?: SkippedFile[];
 }
-/** A file handed in beside a pack. `name` is a label and is never compared. */
-export interface OfferedFile {
+/**
+ * A file handed in beside a pack. `name` is a label and is never compared. The
+ * file is its `bytes`, or its `sha256` (64 lowercase hex characters) where the
+ * caller has already hashed it: a command streams a file of any size rather
+ * than hold it.
+ */
+export type OfferedFile = {
     name: string;
     bytes: Uint8Array;
-}
+    sha256?: undefined;
+} | {
+    name: string;
+    sha256: string;
+    bytes?: undefined;
+};
 /** One pack of a case, for `matchCaseFiles`. */
 export interface FileMatchPack {
     ref: string;
@@ -101,5 +145,20 @@ export declare function matchFiles(bundle: unknown, files: readonly OfferedFile[
 export declare function matchCaseFiles(packs: readonly FileMatchPack[], files: readonly OfferedFile[]): Promise<FileMatchReading>;
 /** The reading as the `files` member of `--json`, identical in both kernels. */
 export declare function fileMatchToJson(reading: FileMatchReading): Record<string, unknown>;
-/** The text report's lines for the reading, identical in both kernels. */
-export declare function renderFileMatch(reading: FileMatchReading): string[];
+/**
+ * The commitments no offered file matched and no disclosed log answers.
+ *
+ * `contents` is each pack's side content by `pack_ref`. A record whose own pack
+ * discloses bytes that hash to its `content_hash` is accounted for by the pack,
+ * and is not returned. Only the text report's count reads this; the reading, and
+ * `--json`, still list every commitment no file matched.
+ */
+export declare function notAccountedFor(reading: FileMatchReading, contents: ReadonlyMap<string, SideContentMap | null | undefined>): Promise<FileCommitment[]>;
+/**
+ * The text report's lines for the reading, identical in both kernels.
+ *
+ * By default every commitment no file matched is a line. `notAmong` is the case
+ * command's report when no `--files` was given: one count line for the recorded
+ * files no loose file matched, and no line for each (A41).
+ */
+export declare function renderFileMatch(reading: FileMatchReading, notAmong?: number): string[];