@sanning/proof 0.12.0 → 0.13.0

package/dist/zip-reader.js

@@ -0,0 +1,220 @@
+/**
+ * The one ZIP reader `case` uses, for a case file named on the command line.
+ *
+ * The TypeScript half of `src/sanning_proof/zip_reader.py`. Node has no ZIP
+ * reader, and Python's `zipfile` is not used, so the two kernels read one
+ * archive by one rule rather than by two libraries that disagree on the edges:
+ * a central directory that contradicts a local header, a name that is not
+ * UTF-8, data after the end of a deflate stream. Where either library would
+ * have made a choice, this module refuses instead.
+ *
+ * What it reads (evidence-bundle.md 5.6.1): the central directory, and each
+ * entry's data through its local header. Stored and deflate only. What it
+ * REFUSES, as a whole archive: no end-of-central-directory record, ZIP64, more
+ * than one disk, an entry the central directory places outside the archive, a
+ * local header that does not match its central entry, a size or CRC-32 that
+ * does not match the data, two entries with one name, a name that is not
+ * UTF-8, more than MAX_ZIP_ENTRIES entries or MAX_ZIP_BYTES bytes in all, and
+ * a name nested deeper than MAX_ZIP_DEPTH folders. What it REPORTS and never
+ * reads, entry by entry: an encrypted entry, a symbolic link, a method other
+ * than stored or deflate, and a name that is absolute, holds a backslash or a
+ * NUL, or has an empty, `.` or `..` segment.
+ *
+ * Pure: bytes in, entries out. The caller turns them into the tree `case`
+ * splits.
+ */
+import { inflateRawSync } from "node:zlib";
+import { utf8Strict } from "./verifier.js";
+/** More entries than this refuse the archive: the walk's own bound on names. */
+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;
+/** A name nested deeper than this many folders refuses the archive. */
+export const MAX_ZIP_DEPTH = 32;
+const EOCD = 0x06054b50;
+const CENTRAL = 0x02014b50;
+const LOCAL = 0x04034b50;
+const S_IFMT = 0o170000;
+const S_IFLNK = 0o120000;
+const UNIX = 3;
+/** The archive cannot be read as a case file. `message` is the whole report, identical in both kernels. */
+export class ZipReadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ZipReadError";
+    }
+}
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(bytes) {
+    let c = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++)
+        c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function refusal(name) {
+    if (name.startsWith("/"))
+        return "an absolute name";
+    if (name.includes("\\"))
+        return "a name with a backslash";
+    if (name.includes("\u0000"))
+        return "a name with a NUL";
+    for (const segment of name.split("/")) {
+        if (segment === "" || segment === "." || segment === "..") {
+            return "a name with an empty, . or .. segment";
+        }
+    }
+    return null;
+}
+function sameBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/**
+ * Every FILE entry of a ZIP archive, in central-directory order. A directory
+ * entry (a name ending in `/`) is not a file and is not returned. Throws
+ * `ZipReadError`.
+ */
+export function readZip(data) {
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const n = data.length;
+    const u32 = (at) => view.getUint32(at, true);
+    const u16 = (at) => view.getUint16(at, true);
+    // The end-of-central-directory record: 22 bytes plus a comment of at most
+    // 65535, searched backwards so the LAST signature wins.
+    let eocd = -1;
+    const lowest = Math.max(0, n - 22 - 0xffff);
+    for (let at = n - 22; at >= lowest; at--) {
+        if (u32(at) === EOCD && at + 22 + u16(at + 20) === n) {
+            eocd = at;
+            break;
+        }
+    }
+    if (eocd < 0)
+        throw new ZipReadError("is not a readable .zip archive");
+    const disk = u16(eocd + 4);
+    const cdDisk = u16(eocd + 6);
+    const hereCount = u16(eocd + 8);
+    const count = u16(eocd + 10);
+    const cdSize = u32(eocd + 12);
+    const cdOffset = u32(eocd + 16);
+    if (count === 0xffff || cdSize === 0xffffffff || cdOffset === 0xffffffff) {
+        throw new ZipReadError("is a ZIP64 archive, which case does not read");
+    }
+    if (disk !== 0 || cdDisk !== 0 || hereCount !== count) {
+        throw new ZipReadError("spans more than one disk, which case does not read");
+    }
+    if (count > MAX_ZIP_ENTRIES) {
+        throw new ZipReadError(`holds more than ${MAX_ZIP_ENTRIES} entries; refusing to read it`);
+    }
+    if (cdOffset + cdSize > eocd)
+        throw new ZipReadError("is not a readable .zip archive");
+    const entries = [];
+    const names = new Set();
+    let total = 0;
+    let at = cdOffset;
+    for (let e = 0; e < count; e++) {
+        if (at + 46 > eocd || u32(at) !== CENTRAL) {
+            throw new ZipReadError("is not a readable .zip archive");
+        }
+        const madeBy = u16(at + 4);
+        const flags = u16(at + 8);
+        const method = u16(at + 10);
+        const crc = u32(at + 16);
+        const csize = u32(at + 20);
+        const usize = u32(at + 24);
+        const nameLen = u16(at + 28);
+        const extraLen = u16(at + 30);
+        const commentLen = u16(at + 32);
+        const external = u32(at + 38);
+        const localAt = u32(at + 42);
+        const rawName = data.subarray(at + 46, at + 46 + nameLen);
+        at += 46 + nameLen + extraLen + commentLen;
+        if (at > eocd)
+            throw new ZipReadError("is not a readable .zip archive");
+        let name;
+        try {
+            name = utf8Strict(rawName);
+        }
+        catch {
+            throw new ZipReadError("holds a name that is not valid UTF-8; rename it, then run case again");
+        }
+        if (names.has(name))
+            throw new ZipReadError(`holds ${name} twice`);
+        names.add(name);
+        if (name.endsWith("/"))
+            continue;
+        if (name.split("/").length - 1 > MAX_ZIP_DEPTH) {
+            throw new ZipReadError(`is nested more than ${MAX_ZIP_DEPTH} folders deep; refusing to read it`);
+        }
+        let refused = refusal(name);
+        if (refused === null && flags & 0x1)
+            refused = "an encrypted entry";
+        if (refused === null &&
+            madeBy >> 8 === UNIX &&
+            ((external >>> 16) & S_IFMT) === S_IFLNK) {
+            refused = "a symbolic link";
+        }
+        if (refused === null && method !== 0 && method !== 8) {
+            refused = "a compression method other than stored or deflate";
+        }
+        if (refused !== null) {
+            entries.push({ name, refused, data: null });
+            continue;
+        }
+        total += usize;
+        if (total > MAX_ZIP_BYTES) {
+            throw new ZipReadError(`holds more than ${MAX_ZIP_BYTES} bytes uncompressed; refusing to read it`);
+        }
+        const unreadable = () => new ZipReadError(`holds ${name}, which cannot be read`);
+        if (localAt + 30 > cdOffset || u32(localAt) !== LOCAL)
+            throw unreadable();
+        const localNameLen = u16(localAt + 26);
+        const localExtraLen = u16(localAt + 28);
+        if (!sameBytes(data.subarray(localAt + 30, localAt + 30 + localNameLen), rawName)) {
+            throw unreadable();
+        }
+        const start = localAt + 30 + localNameLen + localExtraLen;
+        if (start + csize > cdOffset)
+            throw unreadable();
+        const packed = data.subarray(start, start + csize);
+        let body;
+        if (method === 0) {
+            body = packed;
+        }
+        else {
+            // `info: true` hands back the engine, whose `bytesWritten` is how many
+            // input bytes the stream consumed. Anything left over is data after the
+            // end of the deflate stream, which Python's `unused_data` refuses too.
+            let result;
+            try {
+                result = inflateRawSync(packed, {
+                    info: true,
+                    maxOutputLength: usize + 1,
+                });
+            }
+            catch {
+                throw unreadable();
+            }
+            if (result.engine.bytesWritten !== packed.length)
+                throw unreadable();
+            body = new Uint8Array(result.buffer.buffer, result.buffer.byteOffset, result.buffer.length);
+        }
+        if (body.length !== usize || crc32(body) !== crc)
+            throw unreadable();
+        entries.push({ name, refused: null, data: body.slice() });
+    }
+    return entries;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanning/proof",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "TypeScript kernel of the Sanning verification stack: RFC 8785 (JCS) canonicalization, SHA-256, and Ed25519 verification for Verifiable Event Envelopes. Full-family verifier (inline + external commitment); accepts sanning.agent/v1 and sanning.events/v2. Conformance-gated byte-for-byte against the test-vectors corpus.",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "proof": "./dist/cli.js"
+    "sanning-proof": "./dist/cli.js"
   },
   "files": [
     "src",

package/src/agent-proof.ts

@@ -1,4 +1,4 @@
-// Agent inclusion-proof bundle verification.
+// Agent inclusion proof verification (`sanning.agent.proof/v1`).
 //
 // The `sanning.agent.proof/v1` bundle is the agent's ~1.4 KB self-contained
 // inclusion proof: a signed checkpoint envelope (sanning.agent/v1, INLINE payload)
@@ -19,7 +19,7 @@ import { leafHash, verifyInclusion } from "./merkle.js";
 import { MAX_CANONICAL_DEPTH, exceedsDepth, jcs, jcsParse, verifyEnvelope } from "./verifier.js";
 import type { Envelope } from "./types.js";
 
-export const AGENT_PROOF_SPEC_PREFIX = "sanning.agent.proof/v1";
+export const AGENT_PROOF_SPEC_VERSION = "sanning.agent.proof/v1";
 
 export interface AgentProofBundle {
   spec_version: string;
@@ -63,10 +63,10 @@ function toHex(bytes: Uint8Array): string {
 
 export function isAgentProofSpec(specVersion: unknown): boolean {
   if (typeof specVersion !== "string") return false;
-  return specVersion === AGENT_PROOF_SPEC_PREFIX || specVersion.startsWith(`${AGENT_PROOF_SPEC_PREFIX}.`);
+  return specVersion === AGENT_PROOF_SPEC_VERSION || specVersion.startsWith(`${AGENT_PROOF_SPEC_VERSION}.`);
 }
 
-export async function verifyAgentProofBundle(
+export async function verifyAgentProof(
   bundle: unknown,
   options: VerifyAgentProofOptions = {},
 ): Promise<AgentProofResult> {

package/src/case-file.ts

@@ -0,0 +1,419 @@
+/**
+ * The case file's index, compared with the drop it describes (A25).
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+import { jcsParse } from "./verifier.js";
+
+/** 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";
+
+/** The one command that checks the file, at its root (5.6.4). */
+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.
+ */
+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.
+ */
+export const CASE_FILE_FINDING_KINDS = [
+  "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_names_absent",
+] 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.
+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.
+ */
+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`.
+ */
+export function howToVerifyText(name: string): string {
+  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" +
+    "\n" +
+    "To check it offline, on your own machine:\n" +
+    "\n" +
+    `  unzip ${name}.zip -d ${name}\n` +
+    `  npx @sanning/proof case ${name}\n` +
+    "\n" +
+    "or, with the Python kernel (pip install sanning-proof):\n" +
+    "\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" +
+    "\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"
+  );
+}
+
+/**
+ * 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.
+ */
+export interface CaseFileFinding {
+  kind: CaseFileFindingKind;
+  /** The pack folder name, for the two pack kinds. */
+  ref?: string;
+  /** The file, from the case file's root, for the three file kinds. */
+  path?: string;
+  /** What the index lists for the file, for `case_index_file_differs`. */
+  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`.
+   */
+  reason?: string;
+  /**
+   * The key the assembler says the absent pack would be signed by, as the index
+   * writes it, 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.
+   */
+  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.
+ */
+export function jsonDepthExceeds(text: string | Uint8Array, limit: number): boolean {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  const n = text.length;
+  for (let i = 0; i < n; i++) {
+    const ch =
+      typeof text === "string" ? text.charCodeAt(i) : (text as Uint8Array)[i];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === 0x5c) escaped = true;
+      else if (ch === 0x22) inString = false;
+    } else if (ch === 0x22) {
+      inString = true;
+    } else if (ch === 0x5b || ch === 0x7b) {
+      depth++;
+      if (depth > limit) return true;
+    } else if (ch === 0x5d || ch === 0x7d) {
+      depth--;
+    }
+  }
+  return false;
+}
+
+const utf8 = new TextEncoder();
+
+/** Sorted by the UTF-8 bytes of the value (5.6.2), never by UTF-16 code unit. */
+function byUtf8(a: string, b: string): number {
+  const x = utf8.encode(a);
+  const y = utf8.encode(b);
+  const n = Math.min(x.length, y.length);
+  for (let i = 0; i < n; i++) {
+    if (x[i] !== y[i]) return x[i] - y[i];
+  }
+  return x.length - y.length;
+}
+
+class Unreadable extends Error {
+  constructor(readonly reason: string) {
+    super(reason);
+  }
+}
+
+const has = (o: object, k: string): boolean => Object.prototype.hasOwnProperty.call(o, k);
+
+const isObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** An own member, and never one the prototype chain answers for. */
+const own = (o: Record<string, unknown>, k: string): unknown => (has(o, k) ? o[k] : undefined);
+
+function fileList(value: unknown, where: string): [string, string][] {
+  if (!Array.isArray(value)) throw new Unreadable(`${where} is not an array`);
+  const out: [string, string][] = [];
+  value.forEach((entry, i) => {
+    if (
+      !(
+        isObject(entry) &&
+        typeof own(entry, "path") === "string" &&
+        typeof own(entry, "sha256") === "string"
+      )
+    ) {
+      throw new Unreadable(`${where}[${i}] is not an object with a string path and sha256`);
+    }
+    out.push([entry["path"] as string, entry["sha256"] as string]);
+  });
+  return out;
+}
+
+interface ReadIndex {
+  caseId: string;
+  packs: [string, [string, string][]][];
+  absent: [string, string | null][];
+  report: [string, string][];
+}
+
+/**
+ * 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.
+ */
+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.
+  if (jsonDepthExceeds(raw, MAX_INDEX_DEPTH)) {
+    throw new Unreadable(`nests deeper than ${MAX_INDEX_DEPTH} levels`);
+  }
+  let value: unknown;
+  try {
+    value = jcsParse(raw);
+  } catch {
+    throw new Unreadable("not readable as JSON");
+  }
+  if (!isObject(value)) throw new Unreadable("not a JSON object");
+  if (own(value, "contents_version") !== CASE_FILE_VERSION) {
+    throw new Unreadable(`contents_version is not ${CASE_FILE_VERSION}`);
+  }
+  const caseId = own(value, "case_id");
+  if (typeof caseId !== "string") throw new Unreadable("case_id is not a string");
+  const packs = own(value, "packs");
+  if (!Array.isArray(packs)) throw new Unreadable("packs is not an array");
+  const listedPacks: [string, [string, string][]][] = [];
+  packs.forEach((entry, i) => {
+    if (!(isObject(entry) && typeof own(entry, "ref") === "string")) {
+      throw new Unreadable(`packs[${i}] is not an object with a string ref`);
+    }
+    listedPacks.push([entry["ref"] as string, fileList(own(entry, "files"), `packs[${i}].files`)]);
+  });
+  const absent = own(value, "absent");
+  if (!Array.isArray(absent)) throw new Unreadable("absent is not an array");
+  const listedAbsent: [string, string | null][] = [];
+  absent.forEach((entry, i) => {
+    if (!(isObject(entry) && typeof own(entry, "reason") === "string")) {
+      throw new Unreadable(`absent[${i}] is not an object with a string reason`);
+    }
+    const key = own(entry, "public_key");
+    if (has(entry, "public_key") && typeof key !== "string") {
+      throw new Unreadable(`absent[${i}].public_key is not a string`);
+    }
+    listedAbsent.push([entry["reason"] as string, has(entry, "public_key") ? (key as string) : null]);
+  });
+  const report = fileList(own(value, "report"), "report");
+  return { caseId, packs: listedPacks, absent: listedAbsent, report };
+}
+
+/**
+ * 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
+ * `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`
+ * 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`.
+ */
+export function readCaseFileIndex(
+  index: Uint8Array | null,
+  files: readonly { path: string; sha256: string }[],
+): CaseFileIndexReading {
+  if (index === null || index === undefined) {
+    return { index: "absent", caseId: null, findings: [] };
+  }
+  let read: ReadIndex;
+  try {
+    read = readIndex(index);
+  } catch (e) {
+    if (!(e instanceof Unreadable)) throw e;
+    return {
+      index: "unreadable",
+      caseId: null,
+      findings: [{ kind: "case_index_unreadable", reason: e.reason }],
+    };
+  }
+
+  const here = new Map<string, string>();
+  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 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.
+  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);
+  }
+  for (const [path, digest] of read.report) if (!listed.has(path)) listed.set(path, digest);
+
+  const findings: CaseFileFinding[] = [];
+
+  for (const ref of [...listedRefs].sort(byUtf8)) {
+    if (!here.has(`packs/${ref}/bundle.json`)) {
+      findings.push({ kind: "case_index_pack_missing", ref });
+    }
+  }
+
+  const presentRefs = new Set<string>();
+  for (const path of here.keys()) {
+    const parts = path.split("/");
+    if (parts.length === 3 && parts[0] === "packs" && parts[2] === "bundle.json") {
+      presentRefs.add(parts[1]);
+    }
+  }
+  for (const ref of [...presentRefs].filter((r) => !listedRefs.has(r)).sort(byUtf8)) {
+    findings.push({ kind: "case_index_pack_unlisted", ref });
+  }
+
+  const listedPaths = [...listed.keys()].sort(byUtf8);
+  for (const path of listedPaths) {
+    if (!here.has(path)) findings.push({ kind: "case_index_file_missing", path });
+  }
+
+  const compared = (path: string): boolean => {
+    if (path.startsWith("report/")) return true;
+    const parts = path.split("/");
+    return parts.length >= 3 && parts[0] === "packs" && listedRefs.has(parts[1]);
+  };
+  for (const path of [...here.keys()].sort(byUtf8)) {
+    if (!listed.has(path) && compared(path)) {
+      findings.push({ kind: "case_index_file_unlisted", path });
+    }
+  }
+
+  for (const path of listedPaths) {
+    const actual = here.get(path);
+    if (actual !== undefined && actual !== listed.get(path)) {
+      findings.push({
+        kind: "case_index_file_differs",
+        path,
+        listedSha256: listed.get(path) as string,
+        sha256: actual,
+      });
+    }
+  }
+
+  for (const [reason, key] of read.absent) {
+    findings.push(
+      key === null
+        ? { kind: "case_index_names_absent", reason }
+        : { kind: "case_index_names_absent", reason, publicKey: key },
+    );
+  }
+
+  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.
+ */
+export function renderCaseFileFinding(finding: CaseFileFinding): string {
+  switch (finding.kind) {
+    case "case_index_unreadable":
+      return `contents.json is not an index this reader can read: ${finding.reason}`;
+    case "case_index_pack_missing":
+      return `the index lists pack ${finding.ref}; it is not here`;
+    case "case_index_pack_unlisted":
+      return `pack ${finding.ref} is here; the index does not list it`;
+    case "case_index_file_missing":
+      return `the index lists ${finding.path}; it is not here`;
+    case "case_index_file_unlisted":
+      return `${finding.path} is here; the index does not list it`;
+    case "case_index_file_differs":
+      return (
+        `the index lists ${finding.path} with SHA-256 ${finding.listedSha256}; ` +
+        `the file here hashes to ${finding.sha256}`
+      );
+    case "case_index_names_absent":
+      if (finding.publicKey !== undefined) {
+        return (
+          "the assembler says a pack signed by key " +
+          `${finding.publicKey} is absent: ${finding.reason}`
+        );
+      }
+      return `the assembler says a pack is absent: ${finding.reason}`;
+    default:
+      return (finding as CaseFileFinding).kind;
+  }
+}