@sanning/proof 0.19.1 → 0.20.0

package/src/case-file.ts

@@ -1,33 +1,21 @@
 /**
- * The case file's index, compared with the drop it describes (A25).
+ * A case file's index compared with the drop it describes (evidence-bundle §5.6).
  *
- * The TypeScript half of `src/sanning_proof/case_file.py`. Both kernels are
- * held to one table, `vectors/case-file-index.json`, so neither can pass by
- * agreeing with the other, and `cross-kernel/run_case_cli.sh` holds the two
- * commands to the same `case_file` output.
+ * A case file is a ZIP of packs, each under `packs/<ref>/`, plus an index
+ * (`contents.json`), `HOW-TO-VERIFY.txt` and an optional `report/` of files no
+ * record commits to. Nobody signs it: each pack is byte for byte what its signer
+ * produced, and a reader reads the packs, never the file.
  *
- * WHAT A CASE FILE IS (evidence-bundle.md 5.6 v1.20). A ZIP archive holding one
- * case's packs, each unpacked under `packs/<ref>/`, an index (`contents.json`),
- * the one command that checks them (`HOW-TO-VERIFY.txt`) and an optional
- * `report/` of files no record commits to. **Nobody signs it.** Each pack in it
- * is byte for byte the pack its signer produced, and a reader reads the packs,
- * never the file.
+ * Trust boundary: the index is never an input to the case reading (`readCase`).
+ * Adding, removing or editing it moves no verdict, exception, note or exit code.
+ * A lie in the index is a finding here and nothing more.
  *
- * WHAT THIS MODULE DOES, AND WHAT IT MUST NEVER DO. It compares the index with
- * the files the reader was handed and returns findings with NO verdict
- * contribution. **The index is never an input to the case reading**
- * (`readCase`): adding, removing or editing `contents.json` moves no verdict,
- * no exception, no note, no contribution and no exit code. An assembler can lie
- * in every member of the index, and each lie is a finding here and nothing
- * more; it can leave the index out, which is no finding at all.
- *
- * Pure: bytes and a file list in, a reading out. No filesystem, no zip, no
- * network. How the files were listed and hashed is the caller's.
+ * Pure: bytes and a file list in, a reading out. No filesystem, zip or network.
  */
 
 import { DuplicateKeyError, jcsParse } from "./verifier.js";
 
-/** The index's dispatch key (5.6.2). An absent or unknown value makes the index unreadable. */
+/** The index's dispatch key (5.6.2); an absent or unknown value makes the index unreadable. */
 export const CASE_FILE_VERSION = "sanning.case-file/v1";
 
 /** The index, at the root of the case file. */
@@ -40,17 +28,10 @@ export const HOW_TO_VERIFY_NAME = "HOW-TO-VERIFY.txt";
 export const REPORT_README_FIRST_LINE =
   "Not evidence: no record in this case file commits to the files in this folder.";
 
-/**
- * How deep `[` and `{` may nest in the index before it is refused unread. The
- * same limit `bundle.json` is read under, so a hostile index cannot make one
- * kernel's parser recurse where the other's does not.
- */
+/** How deep `[` and `{` may nest in the index before it is refused unread (the limit `bundle.json` is read under). */
 export const MAX_INDEX_DEPTH = 512;
 
-/**
- * Every finding this comparison can report, in the order it reports them
- * (5.6.3). None of them is a verdict word and none contributes to one.
- */
+/** Every finding this comparison can report, in report order (5.6.3). None is a verdict word. */
 export const CASE_FILE_FINDING_KINDS = [
   "case_index_unreadable",
   "case_index_pack_missing",
@@ -63,23 +44,15 @@ export const CASE_FILE_FINDING_KINDS = [
 ] as const;
 export type CaseFileFindingKind = (typeof CASE_FILE_FINDING_KINDS)[number];
 
-// `<ref>`: 1 to 128 characters from A-Z, a-z, 0-9, `.`, `_` and `-`, and not
-// `.` or `..` (5.6.1). The class holds no newline, so `$` cannot match before
-// one here.
+// 1 to 128 of A-Z a-z 0-9 `.` `_` `-`, not `.` or `..` (5.6.1). No newline in the class, so `$` is safe.
 const REF = /^[A-Za-z0-9._-]{1,128}$/;
 
-/**
- * Whether `ref` is a legal pack folder name in a case file. For a producer; a
- * reader takes whatever folders it finds and names them.
- */
+/** Whether `ref` is a legal pack folder name. For producers; a reader takes whatever folders it finds. */
 export function isPackRef(ref: unknown): boolean {
   return typeof ref === "string" && REF.test(ref) && ref !== "." && ref !== "..";
 }
 
-/**
- * `HOW-TO-VERIFY.txt`, exactly (5.6.4): ASCII, LF line endings, with `name` the
- * case file's name without `.zip`.
- */
+/** `HOW-TO-VERIFY.txt`, exactly (5.6.4): ASCII, LF endings; `name` is the case file's name without `.zip`. */
 export function howToVerifyText(name: string): string {
   return (
     "This case file holds evidence packs. Each pack is signed by its own key.\n" +
@@ -94,20 +67,17 @@ export function howToVerifyText(name: string): string {
     "\n" +
     `  sanning-proof case ${name}\n` +
     "\n" +
-    "Exit codes: 0 verified, 1 failed, 2 not readable or a usage error,\n" +
-    "3 could not be settled (partial, pending, incomplete, not found), 4 mixed,\n" +
-    "5 sandbox (records signed environment dev, not production evidence).\n" +
+    "Exit codes: 0 verified, 1 failed, 2 incomplete (not everything could be\n" +
+    "checked), 3 verified sandbox evidence (records signed environment dev),\n" +
+    "4 could not run (a bad flag, or an input that is not a case).\n" +
     "\n" +
     "To also look each witness up on the public record, add --gateways <url,url>.\n" +
-    "The lookup is reported on its own line and never changes the verdict word.\n" +
-    "With it, a witness that does not match exits 1.\n"
+    "The lookup is reported on the witness line. A lookup that does not settle\n" +
+    "changes nothing; a witness that does not match fails the case, exit 1.\n"
   );
 }
 
-/**
- * One way the index and the drop disagree, as data. What the index SAYS
- * against what the folder HOLDS, and never a statement about any party.
- */
+/** One way the index and the folder disagree: what the index says against what the folder holds, never a statement about a party. */
 export interface CaseFileFinding {
   kind: CaseFileFindingKind;
   /** The pack folder name, for the two pack kinds. */
@@ -118,36 +88,24 @@ export interface CaseFileFinding {
   listedSha256?: string;
   /** What the file in the folder hashes to, for `case_index_file_differs`. */
   sha256?: string;
-  /**
-   * Why the index is unreadable, or the assembler's reason a pack is absent,
-   * for `case_index_unreadable` and `case_index_names_absent`.
-   */
+  /** Why the index is unreadable, or the assembler's reason a pack is absent. */
   reason?: string;
-  /**
-   * The key the assembler says the absent pack would be signed by, as the index
-   * writes it, for `case_index_names_absent`.
-   */
+  /** The key the assembler says the absent pack is signed by, for `case_index_names_absent`. */
   publicKey?: string;
 }
 
 export interface CaseFileIndexReading {
   /** `absent` (no index was handed in), `unreadable` or `read`. */
   index: "absent" | "unreadable" | "read";
-  /**
-   * The index's `case_id`, a label the assembler wrote and nothing is compared
-   * with, or `null` where the index was not read.
-   */
+  /** The index's `case_id`, a label nothing is compared with; `null` where the index was not read. */
   caseId: string | null;
   findings: CaseFileFinding[];
 }
 
 /**
  * Whether `[` and `{` outside strings ever nest deeper than `limit`. One pass,
- * no recursion; the same scan as `json_depth_exceeds` in the Python twin, so
- * both kernels refuse the same text. Given bytes, it reads each byte as the
- * character of that code, which is the same answer for UTF-8: the six
- * characters it reads are single bytes and no multi-byte sequence holds one.
- * The CLI's `bundle.json` reader uses it too.
+ * no recursion. Bytes are read as character codes, which is exact for UTF-8
+ * because the six characters it reads never occur inside a multi-byte sequence.
  */
 export function jsonDepthExceeds(text: string | Uint8Array, limit: number): boolean {
   let depth = 0;
@@ -226,13 +184,12 @@ interface ReadIndex {
 }
 
 /**
- * The index, read under the JSON rule 5.4.2 rule 7 pins, and checked for every
- * REQUIRED member and its type. JCS is not required and an unknown member is
- * ignored (5.6.2). The FIRST problem is the reason.
+ * The index, read under the JSON rule of 5.4.2 and checked for every required
+ * member and its type. JCS is not required and unknown members are ignored
+ * (5.6.2). The first problem found is the reason.
  */
 function readIndex(raw: Uint8Array): ReadIndex {
-  // Scanned as BYTES, before any decode, so both kernels refuse the same index
-  // in the same order whatever it holds.
+  // Scanned as bytes, before any decode.
   if (jsonDepthExceeds(raw, MAX_INDEX_DEPTH)) {
     throw new Unreadable(`nests deeper than ${MAX_INDEX_DEPTH} levels`);
   }
@@ -240,8 +197,7 @@ function readIndex(raw: Uint8Array): ReadIndex {
   try {
     value = jcsParse(raw);
   } catch (e) {
-    // Named, because an index that lists one pack twice under one member name
-    // reads as whichever copy came last (I-JSON, proof#144).
+    // Named: a duplicated member name would otherwise read as whichever copy came last (I-JSON).
     if (e instanceof DuplicateKeyError) throw new Unreadable(e.message);
     throw new Unreadable("not readable as JSON");
   }
@@ -277,12 +233,7 @@ 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.
- */
+/** The reading of an index the caller could not hold (over the run's read total, or unreadable): one `case_index_unreadable` finding, no comparison. */
 export function unreadableCaseFileIndex(reason: string): CaseFileIndexReading {
   return {
     index: "unreadable",
@@ -293,9 +244,8 @@ export function unreadableCaseFileIndex(reason: string): CaseFileIndexReading {
 
 /**
  * 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`.
+ * the index is unreadable. A caller with a hashing budget charges these first,
+ * so an unlisted file cannot turn a real mismatch into `too_large`.
  */
 export function caseFileListedPaths(index: Uint8Array): ReadonlySet<string> | null {
   let read: ReadIndex;
@@ -315,22 +265,15 @@ export function caseFileListedPaths(index: Uint8Array): ReadonlySet<string> | nu
  * 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, 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 (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.
+ * none (a folder of packs, no finding). `files` is every regular file, as
+ * `{ path, sha256 }` with a `/`-separated path from the root, or
+ * `{ path, too_large: true }` for a file left unhashed over the caller's cap
+ * (reported as `case_index_file_too_large` where listed). Only files under
+ * `packs/` and `report/` are compared.
  *
- * Nothing here is a verdict, and nothing here is ever an input to `readCase`.
+ * Findings follow `CASE_FILE_FINDING_KINDS`, and within a kind sort by UTF-8
+ * bytes of `ref` or `path` (5.6.3); `case_index_names_absent` keeps the index's
+ * order. An unreadable index is one finding and no other comparison runs.
  */
 export function readCaseFileIndex(
   index: Uint8Array | null,
@@ -351,9 +294,7 @@ export function readCaseFileIndex(
     };
   }
 
-  // `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.
+  // `null`: present but too large to hash; neither a match nor absent.
   const here = new Map<string, string | null>();
   for (const entry of files) {
     const path = isObject(entry) ? own(entry, "path") : undefined;
@@ -365,8 +306,7 @@ export function readCaseFileIndex(
   }
 
   const listedRefs = new Set(read.packs.map(([ref]) => ref));
-  // The first listing of a path wins, in index order: packs in order, each
-  // pack's files in order, then report/. A path listed twice is compared once.
+  // The first listing of a path wins (packs in order, then report/).
   const listed = new Map<string, string>();
   for (const [, packFiles] of read.packs) {
     for (const [path, digest] of packFiles) if (!listed.has(path)) listed.set(path, digest);
@@ -435,11 +375,7 @@ export function readCaseFileIndex(
   return { index: "read", caseId: read.caseId, findings };
 }
 
-/**
- * The house wording for one finding: what the index says against what the
- * folder holds, and the assembler's own statement for an absent pack. Never a
- * sentence about a party. Both kernels return this text.
- */
+/** The house wording for one finding. Never a sentence about a party. */
 export function renderCaseFileFinding(finding: CaseFileFinding): string {
   switch (finding.kind) {
     case "case_index_unreadable":