@sanning/proof 0.15.0 → 0.17.0

package/src/agent-proof.ts

@@ -15,6 +15,7 @@
 //   5. (optional) Re-fetch checkpoint_tx_id from a gateway and byte-compare.
 
 import { hexToBytes, utf8 } from "./crypto.js";
+import { safeInteger } from "./grading.js";
 import { leafHash, verifyInclusion } from "./merkle.js";
 import { MAX_CANONICAL_DEPTH, exceedsDepth, jcs, jcsParse, verifyEnvelope } from "./verifier.js";
 import type { Envelope } from "./types.js";
@@ -51,9 +52,8 @@ export interface VerifyAgentProofOptions {
   fetchImpl?: typeof fetch;
 }
 
-function stringifyErr(e: unknown): string {
-  return e instanceof Error ? e.message : String(e);
-}
+/** The sentence `agent_proof.py` writes when the proof's own fields are not usable. */
+const MALFORMED_PROOF = "merkle_root / audit_path / leaf_index malformed";
 
 function toHex(bytes: Uint8Array): string {
   let out = "";
@@ -83,28 +83,30 @@ export async function verifyAgentProof(
   });
 
   if (bundle === null || typeof bundle !== "object" || Array.isArray(bundle)) {
-    return fail("agent proof bundle is not a JSON object");
+    return fail("bundle is not a JSON object");
   }
   // Bound nesting before any canonicalization (checkpoint envelope + Merkle
   // leaves are canonicalized recursively) — a fixed shared limit keeps this a
   // `malformed` verdict in every kernel. See MAX_CANONICAL_DEPTH.
   if (exceedsDepth(bundle, MAX_CANONICAL_DEPTH)) {
     return fail(
-      `agent proof bundle nesting exceeds the ${MAX_CANONICAL_DEPTH}-level canonicalization depth bound`,
+      `bundle nesting exceeds the ${MAX_CANONICAL_DEPTH}-level canonicalization depth bound`,
     );
   }
   const b = bundle as AgentProofBundle;
   if (!isAgentProofSpec(b.spec_version)) {
-    return fail(`unsupported agent-proof spec_version: ${JSON.stringify(b.spec_version)}`);
+    // An absent one reads `null`, as in `agent_proof.py` (`dict.get` gives
+    // None); `JSON.stringify(undefined)` would write the word `undefined`.
+    return fail(`unsupported bundle spec_version: ${JSON.stringify(b.spec_version ?? null)}`);
   }
   if (b.checkpoint_envelope === null || typeof b.checkpoint_envelope !== "object") {
-    return fail("agent proof bundle missing checkpoint_envelope");
+    return fail("bundle missing checkpoint_envelope");
   }
   if (b.leaf === null || typeof b.leaf !== "object") {
-    return fail("agent proof bundle missing leaf");
+    return fail("bundle missing leaf");
   }
   if (!Array.isArray(b.audit_path)) {
-    return fail("agent proof bundle missing audit_path[]");
+    return fail(MALFORMED_PROOF);
   }
 
   const errors: string[] = [];
@@ -126,28 +128,50 @@ export async function verifyAgentProof(
       leaf_count?: unknown;
     };
     if (typeof payload.merkle_root === "string") merkleRoot = payload.merkle_root;
-    if (typeof payload.leaf_count === "number") leafCount = payload.leaf_count;
+    // `leaf_count` and `leaf_index` are read BY VALUE, the rule every
+    // inclusion reader in both kernels follows (evidence-bundle A38): `3.0` is
+    // 3, and a fraction, a value past 2**53 - 1, a string or a boolean is not
+    // an integer. `agent_proof.py` reads them through `_safe_integer`.
+    leafCount = safeInteger(payload.leaf_count) ?? undefined;
     if (merkleRoot === undefined) errors.push("checkpoint payload missing merkle_root");
-    if (leafCount === undefined) errors.push("checkpoint payload missing leaf_count");
-  } catch (e) {
-    errors.push(`checkpoint verify error: ${stringifyErr(e)}`);
+    if (leafCount === undefined) errors.push("checkpoint payload leaf_count is not an integer");
+  } catch {
+    // The sentence `agent_proof.py` writes for the same failure. The thrown
+    // text is the host's, and a public result carries the kernel's words only
+    // (proof#150).
+    errors.push("checkpoint envelope verification failed");
   }
 
   // Steps 2-4: leaf hash, audit-path walk, root match.
   let inclusionOk = false;
   if (merkleRoot !== undefined && leafCount !== undefined) {
+    let lh: Uint8Array | undefined;
     try {
-      const lh = await leafHash(utf8(jcs(b.leaf)));
-      inclusionOk = await verifyInclusion(
-        lh,
-        b.leaf_index,
-        leafCount,
-        b.audit_path.map((h) => hexToBytes(h)),
-        hexToBytes(merkleRoot),
-      );
-      if (!inclusionOk) errors.push("RFC 9162 inclusion proof did not reconstruct merkle_root");
-    } catch (e) {
-      errors.push(`inclusion verify error: ${stringifyErr(e)}`);
+      lh = await leafHash(utf8(jcs(b.leaf)));
+    } catch {
+      errors.push("leaf is not JCS-canonicalizable");
+    }
+    const leafIndex = safeInteger(b.leaf_index);
+    if (lh !== undefined && leafIndex === null) {
+      // `agent_proof.py` refuses a leaf_index that is not an integer with this
+      // sentence. Without the check a string, `null` or `1.5` reaches the walk
+      // and reads as a failed inclusion proof instead (proof#150).
+      errors.push(MALFORMED_PROOF);
+    } else if (lh !== undefined) {
+      try {
+        inclusionOk = await verifyInclusion(
+          lh,
+          leafIndex as number,
+          leafCount,
+          b.audit_path.map((h) => hexToBytes(h)),
+          hexToBytes(merkleRoot),
+        );
+        if (!inclusionOk) errors.push("audit_path does not reconstruct merkle_root");
+      } catch {
+        // `agent_proof.py`'s sentence for the same failure; the thrown text is
+        // the host's (proof#150).
+        errors.push(MALFORMED_PROOF);
+      }
     }
   }
 
@@ -184,7 +208,9 @@ export async function verifyAgentProof(
     inclusionOk,
     onChainOk,
     onChainChecked,
-    leafIndex: typeof b.leaf_index === "number" ? b.leaf_index : -1,
+    // Read by value, as the walk above read it: a `2.5` or `1e+21` index is
+    // reported as no index, never printed beside a verdict that refused it.
+    leafIndex: safeInteger(b.leaf_index) ?? -1,
     leafCount: leafCount ?? null,
     checkpointTxId: typeof b.checkpoint_tx_id === "string" ? b.checkpoint_tx_id : null,
     errors,
@@ -200,8 +226,8 @@ async function refetch(
   let expectedHex: string;
   try {
     expectedHex = toHex(utf8(jcs(envelope)));
-  } catch (e) {
-    return { ok: false, unavailable: false, error: `cannot canonicalize checkpoint envelope: ${stringifyErr(e)}` };
+  } catch {
+    return { ok: false, unavailable: false, error: "checkpoint envelope is not JCS-canonicalizable" };
   }
   let anyReachable = false;
   for (const gw of gateways) {

package/src/case-file.ts

@@ -58,6 +58,7 @@ export const CASE_FILE_FINDING_KINDS = [
   "case_index_file_missing",
   "case_index_file_unlisted",
   "case_index_file_differs",
+  "case_index_file_too_large",
   "case_index_names_absent",
 ] as const;
 export type CaseFileFindingKind = (typeof CASE_FILE_FINDING_KINDS)[number];
@@ -275,17 +276,56 @@ function readIndex(raw: Uint8Array): ReadIndex {
   return { caseId, packs: listedPacks, absent: listedAbsent, report };
 }
 
+/**
+ * The reading of an index the caller could not hold at all (it is over the
+ * run's whole-read total, or it cannot be read): one `case_index_unreadable`
+ * finding with the caller's `reason`, and no comparison. The index is never an
+ * input to the verdict, so a file that cannot be read keeps nothing from it.
+ */
+export function unreadableCaseFileIndex(reason: string): CaseFileIndexReading {
+  return {
+    index: "unreadable",
+    caseId: null,
+    findings: [{ kind: "case_index_unreadable", reason }],
+  };
+}
+
+/**
+ * Every path the index lists (each pack's files and `report`), or `null` where
+ * the index is unreadable. A caller that charges a budget for hashing charges
+ * these files first, so a file the index does not list, which needs no digest,
+ * cannot turn a real mismatch into `too_large`.
+ */
+export function caseFileListedPaths(index: Uint8Array): ReadonlySet<string> | null {
+  let read: ReadIndex;
+  try {
+    read = readIndex(index);
+  } catch (e) {
+    if (!(e instanceof Unreadable)) throw e;
+    return null;
+  }
+  const paths = new Set<string>();
+  for (const [, packFiles] of read.packs) for (const [path] of packFiles) paths.add(path);
+  for (const [path] of read.report) paths.add(path);
+  return paths;
+}
+
 /**
  * Compare a case file's index with the folder it sits at the root of.
  *
  * `index` is the bytes of `contents.json`, or `null` where the folder holds
  * none. `files` is every regular file in the folder, as `{ path, sha256 }`
- * with `path` from the folder's root, `/`-separated; only the files under
+ * with `path` from the folder's root, `/`-separated, or `{ path, too_large: true }`
+ * for a file the caller did not hash because it is over its cap (reported as
+ * `case_index_file_too_large` where the index lists it, never as a match or as
+ * absent); only the files under
  * `packs/` and `report/` are compared, so a caller may list the rest or not. A
  * folder with no index is a folder of packs, with no finding.
  *
  * Findings come in the order of `CASE_FILE_FINDING_KINDS`, and within a kind in
- * the order of their `ref` or `path` by UTF-8 bytes; `case_index_names_absent`
+ * the order of their `ref` or `path` by UTF-8 bytes (the order a caller charges
+ * its hashing budget in is another, UTF-16 code units: evidence-bundle 5.6.3);
+ * `case_index_names_absent`
  * is in the index's own order, one per `absent[]` entry. An unreadable index is
  * one finding and no other comparison runs.
  *
@@ -293,7 +333,7 @@ function readIndex(raw: Uint8Array): ReadIndex {
  */
 export function readCaseFileIndex(
   index: Uint8Array | null,
-  files: readonly { path: string; sha256: string }[],
+  files: readonly { path: string; sha256?: string; too_large?: boolean }[],
 ): CaseFileIndexReading {
   if (index === null || index === undefined) {
     return { index: "absent", caseId: null, findings: [] };
@@ -310,13 +350,17 @@ export function readCaseFileIndex(
     };
   }
 
-  const here = new Map<string, string>();
+  // `null` is a file that is here and was too large to hash (a file entry of
+  // `{ path, too_large: true }`): neither a match nor absent, reported as
+  // neither.
+  const here = new Map<string, string | null>();
   for (const entry of files) {
     const path = isObject(entry) ? own(entry, "path") : undefined;
     const digest = isObject(entry) ? own(entry, "sha256") : undefined;
-    if (typeof path === "string" && typeof digest === "string" && !here.has(path)) {
-      here.set(path, digest);
-    }
+    const tooLarge = isObject(entry) && own(entry, "too_large") === true;
+    if (typeof path !== "string" || here.has(path)) continue;
+    if (typeof digest === "string") here.set(path, digest);
+    else if (tooLarge) here.set(path, null);
   }
 
   const listedRefs = new Set(read.packs.map(([ref]) => ref));
@@ -365,7 +409,7 @@ export function readCaseFileIndex(
 
   for (const path of listedPaths) {
     const actual = here.get(path);
-    if (actual !== undefined && actual !== listed.get(path)) {
+    if (actual !== undefined && actual !== null && actual !== listed.get(path)) {
       findings.push({
         kind: "case_index_file_differs",
         path,
@@ -375,6 +419,10 @@ export function readCaseFileIndex(
     }
   }
 
+  for (const path of listedPaths) {
+    if (here.get(path) === null) findings.push({ kind: "case_index_file_too_large", path });
+  }
+
   for (const [reason, key] of read.absent) {
     findings.push(
       key === null
@@ -408,6 +456,11 @@ export function renderCaseFileFinding(finding: CaseFileFinding): string {
         `the index lists ${finding.path} with SHA-256 ${finding.listedSha256}; ` +
         `the file here hashes to ${finding.sha256}`
       );
+    case "case_index_file_too_large":
+      return (
+        `the index lists ${finding.path}; hashing the file here would take case ` +
+        "past the 1 GiB it hashes in one run, so it was not compared"
+      );
     case "case_index_names_absent":
       if (finding.publicKey !== undefined) {
         return (