@sanning/proof 0.19.0 → 0.20.0

package/dist/case-file.d.ts

@@ -1,30 +1,18 @@
 /**
- * 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.
  */
-/** 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 declare const CASE_FILE_VERSION = "sanning.case-file/v1";
 /** The index, at the root of the case file. */
 export declare const CASE_FILE_INDEX_NAME = "contents.json";
@@ -32,32 +20,16 @@ export declare const CASE_FILE_INDEX_NAME = "contents.json";
 export declare const HOW_TO_VERIFY_NAME = "HOW-TO-VERIFY.txt";
 /** The first line of `report/README.txt`, exactly (5.6.1). */
 export declare 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 declare 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 declare const CASE_FILE_FINDING_KINDS: readonly ["case_index_unreadable", "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"];
 export type CaseFileFindingKind = (typeof CASE_FILE_FINDING_KINDS)[number];
-/**
- * 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 declare function isPackRef(ref: unknown): boolean;
-/**
- * `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 declare function howToVerifyText(name: string): string;
-/**
- * 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. */
@@ -68,79 +40,50 @@ 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 declare function jsonDepthExceeds(text: string | Uint8Array, limit: number): boolean;
-/**
- * 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 declare 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 declare function caseFileListedPaths(index: Uint8Array): ReadonlySet<string> | null;
 /**
  * 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 declare function readCaseFileIndex(index: Uint8Array | null, files: readonly {
     path: string;
     sha256?: string;
     too_large?: boolean;
 }[]): CaseFileIndexReading;
-/**
- * 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 declare function renderCaseFileFinding(finding: CaseFileFinding): string;

package/dist/case-file.js

@@ -1,31 +1,19 @@
 /**
- * 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. */
 export const CASE_FILE_INDEX_NAME = "contents.json";
@@ -33,16 +21,9 @@ export const CASE_FILE_INDEX_NAME = "contents.json";
 export const HOW_TO_VERIFY_NAME = "HOW-TO-VERIFY.txt";
 /** The first line of `report/README.txt`, exactly (5.6.1). */
 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",
@@ -53,21 +34,13 @@ export const CASE_FILE_FINDING_KINDS = [
     "case_index_file_too_large",
     "case_index_names_absent",
 ];
-// `<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) {
     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) {
     return ("This case file holds evidence packs. Each pack is signed by its own key.\n" +
         "Nobody signed this file, contents.json, or anything under report/.\n" +
@@ -81,21 +54,18 @@ export function howToVerifyText(name) {
         "\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");
 }
 /**
  * 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, limit) {
     let depth = 0;
@@ -164,13 +134,12 @@ function fileList(value, where) {
     return out;
 }
 /**
- * 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) {
-    // 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`);
     }
@@ -179,8 +148,7 @@ function readIndex(raw) {
         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");
@@ -220,12 +188,7 @@ function readIndex(raw) {
     const report = fileList(own(value, "report"), "report");
     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) {
     return {
         index: "unreadable",
@@ -235,9 +198,8 @@ export function unreadableCaseFileIndex(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`.
+ * 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) {
     let read;
@@ -261,22 +223,15 @@ export function caseFileListedPaths(index) {
  * 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.
+ * 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.
  *
- * 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.
- *
- * 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, files) {
     if (index === null || index === undefined) {
@@ -295,9 +250,7 @@ export function readCaseFileIndex(index, files) {
             findings: [{ kind: "case_index_unreadable", reason: e.reason }],
         };
     }
-    // `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();
     for (const entry of files) {
         const path = isObject(entry) ? own(entry, "path") : undefined;
@@ -311,8 +264,7 @@ export function readCaseFileIndex(index, files) {
             here.set(path, null);
     }
     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();
     for (const [, packFiles] of read.packs) {
         for (const [path, digest] of packFiles)
@@ -376,11 +328,7 @@ export function readCaseFileIndex(index, files) {
     }
     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) {
     switch (finding.kind) {
         case "case_index_unreadable":