@sanning/proof 0.16.0 → 0.17.0

package/src/grading.ts

@@ -476,6 +476,17 @@ export function accountDisclosure(
   return { expected, present, missing, unreadable, extra };
 }
 
+/**
+ * A JSON number read by its value: an integer within 2**53 - 1, or null.
+ * `Number.isSafeInteger`, mirrored by `_js_safe_integer` in
+ * `src/sanning_proof/chain.py`, so `2.0` is 2 in both kernels and
+ * `9007199254740993`, which this parser rounds, is unreadable in both.
+ */
+export function safeInteger(value: unknown): number | null {
+  // `+ 0` folds -0 into 0, which Python's `int(-0.0)` already is.
+  return typeof value === "number" && Number.isSafeInteger(value) ? value + 0 : null;
+}
+
 /** The `leaf_count` a checkpoint's SIGNED record commits to, or null if unreadable. */
 export function signedLeafCount(checkpoint: { event_bytes?: unknown } | null | undefined): number | null {
   const hex = checkpoint?.event_bytes;
@@ -490,8 +501,10 @@ export function signedLeafCount(checkpoint: { event_bytes?: unknown } | null | u
     const record = jcsParse(hexToBytes(hex)) as {
       event?: { leaf_count?: unknown };
     };
-    const n = record?.event?.leaf_count;
-    return Number.isInteger(n) ? (n as number) : null;
+    // Read BY VALUE, the model JCS signs: a record spelling `3.0`, `3e0` or
+    // `30e-1` commits to 3, and since A38 (proof#197) this count decides a
+    // verdict, not only a note. Past 2**53 - 1 it is unreadable, as in Python.
+    return safeInteger(record?.event?.leaf_count);
   } catch {
     return null;
   }

package/src/index.ts

@@ -219,6 +219,7 @@ export {
   CASE_EXCEPTION_KINDS,
   CASE_QUARANTINED_PROFILES,
   CASE_RECORD_PROFILES,
+  CASE_RECORD_STATUSES,
   CASE_NOTE_KINDS,
   CASE_RELIANCE,
   CASE_RELIANCE_HANDOFF_CLAUSE,
@@ -285,6 +286,7 @@ export type {
   CasePackReading,
   CaseReading,
   CaseRecordReading,
+  CaseRecordStatus,
   CaseVerdict,
   WitnessLine,
   WitnessState,
@@ -316,9 +318,11 @@ export type {
 export {
   FILE_MATCH_SCOPE,
   NOT_READ_REASONS,
+  SKIPPED_REASONS,
   fileMatchToJson,
   matchCaseFiles,
   matchFiles,
+  notAccountedFor,
   renderFileMatch,
 } from "./file-match.js";
 export type {
@@ -329,6 +333,8 @@ export type {
   NotRead,
   NotReadReason,
   OfferedFile,
+  SkippedFile,
+  SkippedReason,
   UnmatchedFile,
 } from "./file-match.js";
 

package/src/merkle.ts

@@ -78,25 +78,31 @@ export async function verifyInclusion(
   }
   if (totalLeaves === 1) return auditPath.length === 0 && bytesEqual(leaf, expectedRoot);
 
+  // Arithmetic, not bitwise: JavaScript's `&` and `>>=` truncate to 32 bits,
+  // so a tree past 2**31 leaves walked a different tree here than in the
+  // Python kernel, whose integers are unbounded. `% 2` and a halving floor
+  // are exact for every safe integer, and the stated index and count reach
+  // this walk as safe integers.
   let fn = leafIndex;
   let sn = totalLeaves - 1;
   let r = leaf;
+  const half = (v: number): number => Math.floor(v / 2);
 
   for (const p of auditPath) {
     if (sn === 0) return false; // path longer than the tree depth — malformed
-    if ((fn & 1) === 1 || fn === sn) {
+    if (fn % 2 === 1 || fn === sn) {
       r = await nodeHash(p, r);
-      if ((fn & 1) === 0) {
-        while ((fn & 1) === 0 && fn !== 0) {
-          fn >>= 1;
-          sn >>= 1;
+      if (fn % 2 === 0) {
+        while (fn % 2 === 0 && fn !== 0) {
+          fn = half(fn);
+          sn = half(sn);
         }
       }
     } else {
       r = await nodeHash(r, p);
     }
-    fn >>= 1;
-    sn >>= 1;
+    fn = half(fn);
+    sn = half(sn);
   }
 
   return sn === 0 && bytesEqual(r, expectedRoot);

package/src/verifier.ts

@@ -708,7 +708,7 @@ export async function verifyEnvelope(
   // exotic object.
   try {
     return await verifyEnvelopeChecked(env, opts);
-  } catch (e) {
+  } catch {
     return {
       ok: false,
       specVersionOk: false,
@@ -718,7 +718,7 @@ export async function verifyEnvelope(
       signatureOk: false,
       contentHashOk: opts.expectedContentHash === undefined ? null : false,
       contentRole: null,
-      errors: [`envelope could not be read: ${stringifyErr(e)}`],
+      errors: ["envelope could not be read"],
     };
   }
 }
@@ -761,7 +761,15 @@ async function verifyEnvelopeChecked(
   }
 
   const specVersionOk = specVersionSupported(env.spec_version, opts.acceptedSpecMajors);
-  if (!specVersionOk) errors.push(`unsupported spec_version: ${JSON.stringify(env.spec_version)}`);
+  if (!specVersionOk) {
+    // Absent or null reads "missing", as in the Python kernel. Everything else
+    // is quoted the way both kernels quote a value in a finding.
+    errors.push(
+      env.spec_version === undefined || env.spec_version === null
+        ? "missing spec_version"
+        : `unsupported spec_version: ${JSON.stringify(env.spec_version)}`,
+    );
+  }
 
   // Skeleton field format (envelope-spec §2, proof#95): a present `signed_at`
   // or `environment` that is not what §2 says fails the verdict. There is no
@@ -791,8 +799,8 @@ async function verifyEnvelopeChecked(
   // 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.
+  // the auditor already holds. Neither is the recomputed digest: the reason is
+  // the Python kernel's sentence, word for word (proof#150).
   let payloadHashOk: boolean | null;
   if (typeof env.payload_hash !== "string") {
     payloadHashOk = false;
@@ -803,26 +811,22 @@ async function verifyEnvelopeChecked(
       try {
         const recomputed = await sha256Hex(utf8(jcs(env.payload)));
         checks.push(recomputed === env.payload_hash);
-        if (recomputed !== env.payload_hash) {
-          errors.push(
-            `payload_hash mismatch: the envelope's payload_hash is not SHA-256(JCS(payload)), recomputed=${recomputed}`,
-          );
-        }
-      } catch (e) {
+      } catch {
         checks.push(false);
-        errors.push(`payload canonicalization failed: ${stringifyErr(e)}`);
+        errors.push("payload is not JCS-canonicalizable");
       }
     }
     if (opts.payloadBytes !== undefined) {
       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: bytes=${external}`,
-        );
-      }
     }
     payloadHashOk = checks.length > 0 ? checks.every(Boolean) : null;
+    // One sentence for a mismatch against the inline payload, the supplied
+    // bytes or both, and none when the payload could not be canonicalized: the
+    // Python kernel's rule, word for word (proof#150).
+    if (payloadHashOk === false && !errors.some((e) => e.startsWith("payload is not"))) {
+      errors.push("payload_hash does not match the committed bytes");
+    }
   }
 
   // Check 2 — Signature Confirmed: Ed25519 over the signed scope, which is
@@ -836,8 +840,11 @@ async function verifyEnvelopeChecked(
     const { signature: _signature, co_signatures: _coSignatures, ...envelopeForSig } = env;
     signatureOk = await ed25519Verify(utf8(jcs(envelopeForSig)), env.signature, env.public_key);
     if (!signatureOk) errors.push("Ed25519 signature verification failed");
-  } catch (e) {
-    errors.push(`signature verification error: ${stringifyErr(e)}`);
+  } catch {
+    // The sentence the Python kernel writes for the same failure. What was
+    // thrown is the host's wording (`jcs: input nesting exceeds ...`), and a
+    // public result carries the kernel's own words only (proof#150).
+    errors.push("Ed25519 signature verification failed");
   }
 
   // Check 3 (optional) — Content Bind: the user's bytes match a hash this
@@ -895,6 +902,3 @@ async function verifyEnvelopeChecked(
   };
 }
 
-function stringifyErr(e: unknown): string {
-  return e instanceof Error ? e.message : String(e);
-}

package/src/zip-reader.ts

@@ -32,6 +32,13 @@ import { utf8Strict } from "./verifier.js";
 export const MAX_ZIP_ENTRIES = 50_000;
 /** More uncompressed bytes than this, across every entry, refuse the archive. */
 export const MAX_ZIP_BYTES = 2 ** 30;
+/**
+ * An archive file larger than this is refused before it is read: the
+ * uncompressed cap, and room for the headers, the central directory and the
+ * deflate framing of an archive that holds that much. The caller checks the
+ * size on disk, so the archive is never read whole to find out it is too big.
+ */
+export const MAX_ZIP_ARCHIVE_BYTES = MAX_ZIP_BYTES + 256 * 2 ** 20;
 /** A name nested deeper than this many folders refuses the archive. */
 export const MAX_ZIP_DEPTH = 32;
 

package/vectors/README.md

@@ -173,7 +173,11 @@ matched by its SHA-256 and by nothing else**, and **no match moves a verdict**:
 a surface that matched by name, or took a hash from a field no record's key
 signed, would vouch for a file the pack never committed to. Written by
 `tools/gen-vectors/gen_file_match_vectors.py`, whose expectations are written
-by hand from what it built.
+by hand from what it built. Rule version 2 (A43, proof#204) adds `pack_index`
+and `record_index` to every commitment and every `not_read` entry: the pack's
+position among the row's packs in `mode: case` (`null` in `mode: pack`) and
+the record's position among the events the pack presents, both read off the
+packs the row names.
 
 ## `case-split.json`
 

package/vectors/case-file-index.json

@@ -1,7 +1,7 @@
 {
   "rule": "case-file-index",
-  "ruleVersion": 1,
-  "statement": "How a reader compares a case file's index, contents.json, with the folder it sits at the root of (evidence-bundle.md §5.6.3 v1.20, A25). The index is never an input to the case reading, and no finding here moves a verdict, a note, a contribution or an exit code. Findings come in this order: case_index_unreadable (and nothing else), case_index_pack_missing, case_index_pack_unlisted, case_index_file_missing, case_index_file_unlisted, case_index_file_differs, case_index_names_absent; within a kind by the UTF-8 bytes of the ref or path, and names_absent in the index's own order. Only files under a listed pack's folder or under report/ are reported as unlisted.",
+  "ruleVersion": 2,
+  "statement": "How a reader compares a case file's index, contents.json, with the folder it sits at the root of (evidence-bundle.md §5.6.3 v1.20, A25). The index is never an input to the case reading, and no finding here moves a verdict, a note, a contribution or an exit code. Findings come in this order: case_index_unreadable (and nothing else), case_index_pack_missing, case_index_pack_unlisted, case_index_file_missing, case_index_file_unlisted, case_index_file_differs, case_index_file_too_large, case_index_names_absent; within a kind by the UTF-8 bytes of the ref or path, and names_absent in the index's own order. Only files under a listed pack's folder or under report/ are reported as unlisted.",
   "howToUse": "Call readCaseFileIndex / read_case_file_index with the bytes of index_hex (null: no index in the folder) and `files`, and compare the result with `expected`. A finding lists only the fields it carries.",
   "rows": [
     {
@@ -465,6 +465,92 @@
         ]
       }
     },
+    {
+      "id": "file-too-large",
+      "why": "A file the index lists is here and was too large for the caller to hash (the caller passes {path, too_large: true} in place of a digest). It is neither a match nor missing: one case_index_file_too_large finding, and no differs or missing for it. Every other file is compared as usual.",
+      "index_hex": "7b22616273656e74223a5b5d2c22636173655f6964223a22636173652d346231396465222c22636f6e74656e74735f76657273696f6e223a2273616e6e696e672e636173652d66696c652f7631222c227061636b73223a5b7b2266696c6573223a5b7b2270617468223a227061636b732f612f62756e646c652e6a736f6e222c22736861323536223a2263386261656230383636353834333538646464303634316264353938626239623862383838303935336232613135356366363235303062386338396137333463227d2c7b2270617468223a227061636b732f612f6c6f67732f782e6a736f6e222c22736861323536223a2235303431626631663731336466323034373834333533653832663661346135333539333163623634663166346234613561656166666362373230393138623232227d5d2c22726566223a2261227d2c7b2266696c6573223a5b7b2270617468223a227061636b732f622f62756e646c652e6a736f6e222c22736861323536223a2230653834326632353331333234373838636138353663616264363733306438623432663935373031616535323862313061623165643332343132356231356365227d5d2c22726566223a2262227d5d2c227265706f7274223a5b7b2270617468223a227265706f72742f524541444d452e747874222c22736861323536223a2230316563313839373665373637653831346165653962316361363966366239643331323963343336393063626234623434383463396539323331366362666437227d5d7d",
+      "files": [
+        {
+          "path": "HOW-TO-VERIFY.txt",
+          "sha256": "76b25bc6207548c6bd05b1ab2e364ff8c493f6fb04e6a69d731a6f158482b7d9"
+        },
+        {
+          "path": "contents.json",
+          "sha256": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
+        },
+        {
+          "path": "report/README.txt",
+          "sha256": "01ec18976e767e814aee9b1ca69f6b9d3129c43690cbb4b4484c9e92316cbfd7"
+        },
+        {
+          "path": "packs/b/bundle.json",
+          "sha256": "0e842f2531324788ca856cabd6730d8b42f95701ae528b10ab1ed324125b15ce"
+        },
+        {
+          "path": "packs/a/logs/x.json",
+          "too_large": true
+        },
+        {
+          "path": "packs/a/bundle.json",
+          "sha256": "c8baeb0866584358ddd0641bd598bb9b8b8880953b2a155cf62500b8c89a734c"
+        }
+      ],
+      "expected": {
+        "index": "read",
+        "case_id": "case-4b19de",
+        "findings": [
+          {
+            "kind": "case_index_file_too_large",
+            "path": "packs/a/logs/x.json"
+          }
+        ]
+      }
+    },
+    {
+      "id": "unlisted-file-too-large",
+      "why": "A file under report/ that the index does not list, too large to hash. Unlisted needs no digest, so it is reported as unlisted, exactly as a file of any size would be; nothing else is said of it.",
+      "index_hex": "7b22616273656e74223a5b5d2c22636173655f6964223a22636173652d346231396465222c22636f6e74656e74735f76657273696f6e223a2273616e6e696e672e636173652d66696c652f7631222c227061636b73223a5b7b2266696c6573223a5b7b2270617468223a227061636b732f612f62756e646c652e6a736f6e222c22736861323536223a2263386261656230383636353834333538646464303634316264353938626239623862383838303935336232613135356366363235303062386338396137333463227d2c7b2270617468223a227061636b732f612f6c6f67732f782e6a736f6e222c22736861323536223a2235303431626631663731336466323034373834333533653832663661346135333539333163623634663166346234613561656166666362373230393138623232227d5d2c22726566223a2261227d2c7b2266696c6573223a5b7b2270617468223a227061636b732f622f62756e646c652e6a736f6e222c22736861323536223a2230653834326632353331333234373838636138353663616264363733306438623432663935373031616535323862313061623165643332343132356231356365227d5d2c22726566223a2262227d5d2c227265706f7274223a5b7b2270617468223a227265706f72742f524541444d452e747874222c22736861323536223a2230316563313839373665373637653831346165653962316361363966366239643331323963343336393063626234623434383463396539323331366362666437227d5d7d",
+      "files": [
+        {
+          "path": "HOW-TO-VERIFY.txt",
+          "sha256": "76b25bc6207548c6bd05b1ab2e364ff8c493f6fb04e6a69d731a6f158482b7d9"
+        },
+        {
+          "path": "contents.json",
+          "sha256": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
+        },
+        {
+          "path": "report/README.txt",
+          "sha256": "01ec18976e767e814aee9b1ca69f6b9d3129c43690cbb4b4484c9e92316cbfd7"
+        },
+        {
+          "path": "packs/b/bundle.json",
+          "sha256": "0e842f2531324788ca856cabd6730d8b42f95701ae528b10ab1ed324125b15ce"
+        },
+        {
+          "path": "packs/a/logs/x.json",
+          "sha256": "5041bf1f713df204784353e82f6a4a535931cb64f1f4b4a5aeaffcb720918b22"
+        },
+        {
+          "path": "packs/a/bundle.json",
+          "sha256": "c8baeb0866584358ddd0641bd598bb9b8b8880953b2a155cf62500b8c89a734c"
+        },
+        {
+          "path": "report/huge.bin",
+          "too_large": true
+        }
+      ],
+      "expected": {
+        "index": "read",
+        "case_id": "case-4b19de",
+        "findings": [
+          {
+            "kind": "case_index_file_unlisted",
+            "path": "report/huge.bin"
+          }
+        ]
+      }
+    },
     {
       "id": "no-index",
       "why": "A folder with no contents.json is a folder of packs, with no finding.",