@sanning/proof 0.11.1 → 0.12.0

package/dist/cli.js

@@ -34,12 +34,13 @@
 // surfaces as a per-event note, and it does NOT fail the run. It does hold the
 // PACK at `incomplete`, because a record nobody hashed is a record nobody
 // checked, and exit 3 is how this command says "undetermined".
-import { readFile, readdir, stat, writeFile } from "node:fs/promises";
-import { realpathSync } from "node:fs";
-import { join } from "node:path";
+import { lstat, open, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { constants as fsConstants, realpathSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
 import { CHAIN_READING_SCOPE, readChains, renderChainFinding } from "./chain.js";
+import { readCase, renderCaseSummary, renderException } from "./case.js";
 import { composeExport } from "./compose.js";
 import { isHexField, utf8 } from "./crypto.js";
 import { verifyEvidenceBundle } from "./evidence.js";
@@ -90,6 +91,9 @@ export async function runCli(argv, io) {
     if (command === "bundle" || command === "export") {
         return runBundle(rest, io);
     }
+    if (command === "case") {
+        return runCase(rest, io);
+    }
     if (command !== "verify") {
         io.err(`unknown command: ${command}`);
         printUsage(io);
@@ -136,18 +140,26 @@ export async function runCli(argv, io) {
     const content = logs?.content;
     let raw;
     try {
-        raw = await readFile(bundlePath, "utf8");
+        raw = new Uint8Array(await readFile(bundlePath));
     }
     catch (e) {
         io.err(`cannot read ${bundlePath}: ${e instanceof Error ? e.message : String(e)}`);
         return EXIT_MALFORMED;
     }
+    // The one reader both commands use, in both kernels: `case` reads each pack's
+    // bundle.json through it too, so the two commands classify one bundle the
+    // same way (see `readBundleBytes`).
     let parsed;
     try {
-        parsed = JSON.parse(raw);
+        parsed = readBundleBytes(raw);
     }
     catch (e) {
-        io.err(`${bundlePath} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+        if (e instanceof BundleReadError && e.tooDeep) {
+            io.err(`${bundlePath} ${e.detail}; refusing to read it`);
+        }
+        else {
+            io.err(`${bundlePath} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+        }
         return EXIT_MALFORMED;
     }
     const specVersion = parsed && typeof parsed === "object" && !Array.isArray(parsed)
@@ -621,6 +633,8 @@ function printUsage(io) {
     io.out("Commands:");
     io.out("  verify <bundle.json> [gateways] [--logs <path>]        Verify a bundle");
     io.out("  bundle <source.json> --attestations <f> --key <f> [-o] Create an attested bundle");
+    io.out("  case <folder>... [--gateways <urls>] [--json]          Read several packs as one case");
+    io.out("                                                          (`case --help` for its exit codes)");
     io.out("");
     io.out("Verify a sanning.evidence/v1 bundle (body sanning.anchor.trace/v3,");
     io.out("sanning.stamp.trace/v1, sanning.stamp.evidence/v2 or the attested export");
@@ -942,6 +956,687 @@ function mapStatusToExit(status, errors) {
     // not a failure) also exits 0 — the bundle is cryptographically sound.
     return EXIT_VERIFIED;
 }
+// ─── What `proof case` reads (proof#141) ─────────────────────────────────────
+//
+// Directories on disk, split into packs. This lives in the CLI module, and not
+// in a kernel module, because it is the command's own read of files a person
+// named on the command line, the same class of read as `verify`'s read of
+// `bundle.json`, and it reads `bundle.json` with `verify`'s own reader,
+// `readBundleBytes`.
+//
+// The case READING is `readCase`, and nothing here touches it. This turns the
+// directories a reader typed into a list of packs. Its twin is the same section
+// of `src/sanning_proof/cli.py`, and both are held to one table,
+// `vectors/case-split.json`, whose rows are directory trees.
+//
+// ── Directories only ──
+//
+// `case` reads no archive. A `.zip` argument exits 2 with one line that says to
+// unzip it first and pass the folder, and a `.zip` inside a directory is a file
+// like any other: outside every pack, and never opened. Reading archives in the
+// kernel brought zip bombs, two zip libraries that disagree, and entry names
+// that are not file names, and `unzip` already does that job.
+//
+// ── The walk ──
+//
+// Iterative, never recursive, bytewise-sorted at each level, and bounded:
+//
+//   - A directory nested more than MAX_WALK_DEPTH levels below an argument
+//     refuses the whole input (exit 2).
+//   - More than MAX_WALK_ENTRIES names listed, across every argument, refuses
+//     the whole input (exit 2).
+//   - A name that is not valid UTF-8 refuses the whole input (exit 2). It is
+//     not escaped or replaced: two different names would then read as one.
+//   - A symbolic link is never followed, whatever it points at, and anything
+//     else that is not a regular file or a directory is never opened. Each is
+//     listed as outside every pack and not read, even when it sits under a
+//     pack's `logs/` or is named `bundle.json`.
+//
+// ── The split: the verify page's rule over the tree ──
+//
+// The verify page (`sanning-io/verify-page`, `src/lib/case.ts` `splitCase` and
+// `src/lib/pack.ts` `assemble`) is the other surface that reads a case. Both
+// apply the same splitting rule to the same unpacked tree. The page's rule
+// lives in the page, so neither kernel can call it; it is restated here and in
+// the Python twin, and the shared table pins it:
+//
+//   1. Every regular file whose path ends in `/bundle.json` is a pack, rooted
+//      at the directory that holds it.
+//   2. A file belongs to the pack with the LONGEST root it sits under, and only
+//      if it is that root's `bundle.json` or under that root's `logs/`.
+//   3. A file under no pack is OUTSIDE: listed, and never opened.
+//   4. Roots and outside paths are sorted by UTF-16 code unit (the default
+//      `Array.prototype.sort`).
+//   5. Inside a pack, `logs/<event_id>.json` (one level) is disclosed content,
+//      and any other file under `logs/` is UNACCOUNTED.
+//   6. A pack's `ref` is its root without the trailing slash.
+//   7. No `bundle.json` anywhere refuses.
+//
+// One directory argument is read at `<its name>/<path inside it>`, which is how
+// the page names the files of a dropped folder. Several are read as one folder
+// holding them, each under its own name, and two that would land at one name
+// refuse.
+//
+// Known differences from the page: the page opens a dropped `.zip` and this
+// command does not; the page drops a leading byte-order mark from
+// `bundle.json` and `verify`'s reader refuses one; the page reads whatever the
+// browser hands it for a link, a name that is not UTF-8 or a very deep tree,
+// where this command applies the walk's rules above; and the page keys
+// disclosed content by a plain object, so it loses a record named `__proto__`,
+// which this command keeps.
+/** The error text for an input with no pack in it, word for word the page's. */
+export const NO_BUNDLE = "No bundle.json found. An evidence pack contains bundle.json plus logs/.";
+/** A directory nested deeper than this below an argument refuses the input. */
+export const MAX_WALK_DEPTH = 32;
+/** More names than this, across every argument, refuse the input. */
+export const MAX_WALK_ENTRIES = 50_000;
+/**
+ * `bundle.json` nested deeper than this is refused before it is parsed, by
+ * `verify` and by `case` alike (see `readBundleBytes`).
+ */
+export const MAX_JSON_DEPTH = 512;
+const BUNDLE_PATH = /(?:^|\/)bundle\.json$/;
+const LOG_PATH = /^logs\/([^/]+)\.json$/;
+const ZIP_NAME = /\.zip$/i;
+/** The one line a `.zip` gets, as an argument or as the way through a refusal. */
+const UNZIP_FIRST = "Unzip it first (for example, unzip file.zip -d case/), then pass the folder.";
+/**
+ * The input could not be read as a case. The message is the whole report,
+ * identical in both kernels, and the command exits 2 on it. `hint` is an
+ * optional second line naming a way through.
+ */
+export class CaseInputError extends Error {
+    hint;
+    constructor(message, hint = null) {
+        super(message);
+        this.hint = hint;
+    }
+}
+/**
+ * `bundle.json` bytes that `readBundleBytes` will not read. `tooDeep` separates
+ * the one refusal that is not a parse error; `detail` is the parser's own words,
+ * which differ by kernel and are printed by `verify` only.
+ */
+export class BundleReadError extends Error {
+    tooDeep;
+    detail;
+    constructor(tooDeep, detail) {
+        super(detail);
+        this.tooDeep = tooDeep;
+        this.detail = detail;
+    }
+}
+/**
+ * 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.
+ */
+function jsonDepthExceeds(text, limit) {
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === "\\")
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+        }
+        else if (ch === '"') {
+            inString = true;
+        }
+        else if (ch === "[" || ch === "{") {
+            depth++;
+            if (depth > limit)
+                return true;
+        }
+        else if (ch === "]" || ch === "}") {
+            depth--;
+        }
+    }
+    return false;
+}
+// `ignoreBOM: true` KEEPS a byte-order mark in the text, as Node's
+// `readFile(path, "utf8")` did for `verify`, so a leading one is not JSON.
+const bundleDecoder = new TextDecoder("utf-8", { ignoreBOM: true });
+const nameDecoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+/**
+ * How both `verify` and `case` turn `bundle.json` bytes into JSON, in both
+ * kernels (`read_bundle_bytes` in the Python twin). UTF-8 with each ill-formed
+ * sequence read as U+FFFD, and a byte-order mark kept; then nesting deeper than
+ * MAX_JSON_DEPTH is refused before any parser walks into it; then `JSON.parse`.
+ * Throws `BundleReadError`.
+ */
+export function readBundleBytes(bytes) {
+    const text = bundleDecoder.decode(bytes);
+    if (jsonDepthExceeds(text, MAX_JSON_DEPTH)) {
+        throw new BundleReadError(true, `nests deeper than ${MAX_JSON_DEPTH} levels`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (e) {
+        throw new BundleReadError(false, e instanceof Error ? e.message : String(e));
+    }
+}
+/**
+ * The page's `splitCase` followed by its `assemble` per pack, over the walk's
+ * tree. `read` opens a file; it is called for the files a pack owns and for
+ * nothing else.
+ */
+export async function splitCase(tree, read) {
+    const roots = [...tree]
+        .filter(([p, e]) => e.regular && BUNDLE_PATH.test(p))
+        .map(([p]) => p.slice(0, p.length - "bundle.json".length))
+        .sort();
+    if (roots.length === 0) {
+        const zips = [...tree.keys()].filter((p) => ZIP_NAME.test(p)).sort();
+        const hint = zips.length > 0
+            ? `It holds ${zips.length} .zip file(s) (${zips[0]}` +
+                `${zips.length > 1 ? ", …" : ""}), and case never opens a .zip. ` +
+                UNZIP_FIRST
+            : null;
+        throw new CaseInputError(NO_BUNDLE, hint);
+    }
+    const owned = new Map(roots.map((r) => [r, []]));
+    const outside = [];
+    const notRegular = [];
+    for (const [path, entry] of tree) {
+        if (!entry.regular) {
+            outside.push(path);
+            notRegular.push(path);
+            continue;
+        }
+        let best = null;
+        for (const root of roots) {
+            const mine = path === `${root}bundle.json` || path.startsWith(`${root}logs/`);
+            if (mine && (best === null || root.length > best.length))
+                best = root;
+        }
+        if (best === null)
+            outside.push(path);
+        else
+            owned.get(best).push(path);
+    }
+    const packs = [];
+    for (const root of roots) {
+        const bundlePath = `${root}bundle.json`;
+        const content = new Map();
+        const unaccounted = [];
+        for (const p of owned.get(root).sort()) {
+            if (p === bundlePath)
+                continue;
+            const rel = p.slice(root.length);
+            const m = LOG_PATH.exec(rel);
+            if (m)
+                content.set(m[1], await read(tree.get(p), p));
+            else
+                unaccounted.push(rel);
+        }
+        packs.push({
+            ref: root.slice(0, -1),
+            bundlePath,
+            bundleBytes: await read(tree.get(bundlePath), bundlePath),
+            content,
+            unaccounted: unaccounted.sort(),
+        });
+    }
+    return { packs, outside: outside.sort(), notRegular: notRegular.sort() };
+}
+/** `verify`'s reader, with the refusal named by the pack's path. */
+export function loadBundle(pack) {
+    try {
+        return readBundleBytes(pack.bundleBytes);
+    }
+    catch (e) {
+        if (e instanceof BundleReadError && e.tooDeep) {
+            throw new CaseInputError(`${pack.bundlePath} nests deeper than ${MAX_JSON_DEPTH} levels`);
+        }
+        throw new CaseInputError(`${pack.bundlePath} is not valid JSON`);
+    }
+}
+/**
+ * A regular file's bytes. Opened without following a link and without
+ * blocking, then checked again, so a file swapped for a link or a pipe after
+ * the walk listed it is refused rather than followed or waited on.
+ */
+export async function readFileEntry(entry, key) {
+    const flags = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0);
+    let handle;
+    try {
+        handle = await open(entry.fsPath, flags);
+    }
+    catch {
+        throw new CaseInputError(`cannot read ${key}`);
+    }
+    try {
+        if (!(await handle.stat()).isFile())
+            throw new CaseInputError(`cannot read ${key}`);
+        return new Uint8Array(await handle.readFile());
+    }
+    catch {
+        throw new CaseInputError(`cannot read ${key}`);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Every name under `root`, into `tree` at `<prefix><path inside>`. Breadth
+ * first from an explicit queue, never by recursion. `seen` is the count of
+ * names listed so far, across every argument.
+ */
+async function walk(root, prefix, arg, tree, seen) {
+    const queue = [[root, prefix, 0]];
+    for (let head = 0; head < queue.length; head++) {
+        const [directory, rel, depth] = queue[head];
+        let names;
+        try {
+            names = await readdir(directory, { encoding: "buffer" });
+        }
+        catch {
+            throw new CaseInputError(`cannot read ${rel.slice(0, -1)}`);
+        }
+        names.sort(Buffer.compare);
+        for (const raw of names) {
+            seen.n++;
+            if (seen.n > MAX_WALK_ENTRIES) {
+                throw new CaseInputError(`${arg} holds more than ${MAX_WALK_ENTRIES} files and folders; refusing to read it`);
+            }
+            let name;
+            try {
+                name = nameDecoder.decode(raw);
+            }
+            catch {
+                throw new CaseInputError(`${rel.slice(0, -1)} holds a name that is not valid UTF-8; rename it, then run case again`);
+            }
+            const path = join(directory, name);
+            const key = `${rel}${name}`;
+            let s;
+            try {
+                s = await lstat(path);
+            }
+            catch {
+                throw new CaseInputError(`cannot read ${key}`);
+            }
+            if (s.isDirectory()) {
+                if (depth + 1 > MAX_WALK_DEPTH) {
+                    throw new CaseInputError(`${arg} is nested more than ${MAX_WALK_DEPTH} folders deep; refusing to read it`);
+                }
+                queue.push([path, `${key}/`, depth + 1]);
+            }
+            else {
+                tree.set(key, { fsPath: path, regular: s.isFile() });
+            }
+        }
+    }
+}
+// The name the page would see for a dropped folder: the last segment of the
+// absolute path, so `.` and `pack/` name the directory itself.
+function baseName(path) {
+    return basename(resolve(path));
+}
+/**
+ * Every name under the directories named, keyed `<name>/<path inside>`. Each
+ * argument must be a directory, and not a link to one. A `.zip` is refused
+ * with the way through.
+ */
+export async function treeFromArguments(paths) {
+    if (paths.length === 0)
+        throw new CaseInputError("case: at least one pack is required");
+    for (const arg of paths) {
+        // `link/` resolves the link; the name without the slash does not.
+        let s;
+        try {
+            s = await lstat(arg.replace(/\/+$/, "") || arg);
+        }
+        catch {
+            throw new CaseInputError(`cannot read ${arg}`);
+        }
+        if (s.isSymbolicLink()) {
+            throw new CaseInputError(`${arg} is a symbolic link, which case does not follow; pass the folder it points to`);
+        }
+        if (s.isDirectory())
+            continue;
+        if (ZIP_NAME.test(arg))
+            throw new CaseInputError(`${arg} is a .zip archive. ${UNZIP_FIRST}`);
+        throw new CaseInputError(`${arg} is not a folder. Pass pack folders, or the folder that holds them.`);
+    }
+    const tree = new Map();
+    const claimed = new Map();
+    const seen = { n: 0 };
+    for (const arg of paths) {
+        const name = baseName(arg);
+        const earlier = claimed.get(name);
+        if (earlier !== undefined) {
+            throw new CaseInputError(`${earlier} and ${arg} would both be read as ${name}/; rename one`);
+        }
+        claimed.set(name, arg);
+        await walk(arg, `${name}/`, arg, tree, seen);
+    }
+    return tree;
+}
+// ─── `proof case` (proof#141) ────────────────────────────────────────────────
+//
+// The case reading from a terminal, so an auditor holding several packs does
+// not depend on Sanning's page for the one check the audited party cannot
+// write for itself. The twin is `run_case` in `src/sanning_proof/cli.py`, and
+// the two commands are compared as child processes by
+// `cross-kernel/run_case_cli.sh`: same stdout, same `--json`, same exit code,
+// over every `case/` vector.
+//
+// The reading is `readCase`, entire. This command splits the input into packs
+// (the section above, the verify page's rule) and prints what the kernel said.
+// No color: the two commands print the same bytes.
+// Exit code per case verdict word. The four codes `verify` uses mean what they
+// mean there, and `mixed` gets its own, because each code already in use would
+// say something a mixed case has not established: 0 and 3 would soften a case
+// that holds a failure, and 1 would accuse a case whose outcomes are all
+// undetermined.
+const EXIT_MIXED = 4;
+export const CASE_EXIT_CODES = {
+    verified: EXIT_VERIFIED,
+    failed: EXIT_FAILED,
+    malformed: EXIT_MALFORMED,
+    incomplete: EXIT_UNDETERMINED,
+    partial: EXIT_UNDETERMINED,
+    mixed: EXIT_MIXED,
+};
+export const CASE_USAGE = `sanning-proof case -- one verdict over several evidence packs, offline
+
+  sanning-proof case <folder>... [--gateways <url,url>] [--json]
+
+  <folder>    a pack folder (bundle.json plus logs/), or a folder that holds
+              several packs, such as an unpacked decision file. case reads
+              folders only: given a .zip, it exits 2 and says to unzip it
+              first (for example, unzip file.zip -d case/) and pass the folder.
+              Packs are found by the verify page's splitting rule: every
+              bundle.json is a pack, a file belongs to the deepest pack whose
+              bundle.json or logs/ it sits in, and every other file is listed
+              as outside every pack and never opened. A .zip inside a folder is
+              a file like any other. A symbolic link is never followed: it is
+              listed as outside and not read, even under a pack's logs/.
+              Several folders are read as one folder holding them, each under
+              its own name. A folder nested more than 32 levels deep, more than
+              50000 files and folders in all, or a name that is not valid UTF-8
+              exits 2.
+  --gateways  comma-separated gateway URLs. Each pack's witnesses are then
+              re-fetched on chain, pack by pack, and reported beside the case
+              reading. Without it the on-chain half is NOT checked, and the
+              output says so.
+  --json      the full reading as JSON: the verdict, every exception with its
+              rendered line, every record, every contribution, the packs, the
+              files outside them, and the on-chain half.
+
+Each pack's bundle.json is read as verify reads it, so the two commands
+classify one bundle the same way.
+
+What a case reading establishes: every pack is verified offline by this
+kernel; every record every pack supplied is read, in one pile, under the
+hand-off rules of envelope-spec section 4.1; a hand-off record with no
+counterpart among the case's records is always named, and when a pack signed by
+the key it names is in the case, the reading says that pack holds none, unless
+every candidate it had was accounted for by another record (A20), which reads
+as no counterpart and names no pack.
+
+What it does not establish: that the case is complete (a party can decline to
+hand over a pack); that a party which presented no pack under the named key
+recorded nothing; that two organizations are independent of each other; or
+that any witness was re-fetched on chain, which the reading never does.
+
+Exit codes: 0 verified · 1 failed · 2 malformed, usage, an input that cannot
+be read as a case, or an unexpected error in this command · 3 incomplete or
+partial (undetermined, not failed) · 4 mixed (more than one outcome: read the
+exceptions). With --gateways, a witness that does not match on chain exits 1,
+and an on-chain half that could not be settled turns 0 into 3.`;
+// What Node writes for a lone surrogate on a UTF-8 stream is U+FFFD. Done here
+// rather than left to the stream, so the lines a test captures in process are
+// the lines a reader sees.
+function noLoneSurrogates(text) {
+    return text.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "�");
+}
+// Keys sorted at every depth, arrays left in their order: the Python twin
+// writes `json.dumps(sort_keys=True, indent=2, ensure_ascii=False)` and this is
+// that, byte for byte.
+function sortKeys(v) {
+    if (Array.isArray(v))
+        return v.map(sortKeys);
+    if (v !== null && typeof v === "object") {
+        return Object.fromEntries(Object.keys(v)
+            .sort()
+            .map((k) => [k, sortKeys(v[k])]));
+    }
+    return v;
+}
+function jsonText(v) {
+    return JSON.stringify(sortKeys(v), null, 2);
+}
+// Each pack's witnesses, re-fetched through `verifyEvidenceBundle`. Outside the
+// case reading on purpose: `readCase` makes no network call, and neither does
+// the verify page's case reading, so the case verdict stays the one both
+// surfaces compute. This adds the half the reading names as not checked.
+async function onChainHalf(packs, gateways, io) {
+    if (gateways.length === 0)
+        return { checked: false, gateways: [], packs: [], verdict: "not_checked" };
+    const rows = [];
+    for (const [ref, bundle] of packs) {
+        const result = await verifyEvidenceBundle(bundle, {
+            gateways,
+            ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
+        });
+        const witnesses = [...result.checkpoints, ...(result.stamps ?? [])];
+        const row = {
+            ref,
+            witnesses: witnesses.length,
+            confirmed: 0,
+            mismatched: 0,
+            unreachable: 0,
+            not_checked: 0,
+        };
+        for (const w of witnesses) {
+            const rollup = w.onChain?.rollup ?? null;
+            if (rollup === "confirm")
+                row.confirmed++;
+            else if (rollup === "mismatch")
+                row.mismatched++;
+            else if (rollup === "unreachable")
+                row.unreachable++;
+            else
+                row.not_checked++;
+        }
+        rows.push(row);
+    }
+    const verdict = rows.some((r) => r.mismatched > 0)
+        ? "failed"
+        : rows.some((r) => r.witnesses === 0 || r.unreachable > 0 || r.not_checked > 0)
+            ? "undetermined"
+            : "confirmed";
+    return { checked: true, gateways: [...gateways], packs: rows, verdict };
+}
+/**
+ * The case verdict's code, moved only by an on-chain half that was asked for:
+ * a witness that does not match is a failure whatever the reading said, and an
+ * on-chain half that could not be settled is never a clean 0.
+ */
+export function caseExitCode(verdict, onChainVerdict) {
+    const code = CASE_EXIT_CODES[verdict] ?? EXIT_MALFORMED;
+    if (onChainVerdict === "failed")
+        return EXIT_FAILED;
+    if (onChainVerdict === "undetermined" && code === EXIT_VERIFIED)
+        return EXIT_UNDETERMINED;
+    return code;
+}
+function caseReport(data) {
+    const lines = [data.verdict.toUpperCase(), `  ${data.summary}`];
+    for (const e of data.exceptions)
+        lines.push(`  - ${e.rendered}`);
+    lines.push(`packs         ${data.packs.length}`);
+    for (const p of data.packs) {
+        let line = `  ${p.ref}  ${p.log_files} record file(s) under logs/`;
+        if (p.unaccounted.length > 0) {
+            line +=
+                `; ${p.unaccounted.length} file(s) under logs/ that cannot be a ` +
+                    `record: ${p.unaccounted.join(", ")}`;
+        }
+        lines.push(line);
+    }
+    if (data.outside.length > 0) {
+        lines.push(`outside       ${data.outside.length} file(s) sit outside every ` +
+            "pack, so no verdict here is about them");
+        const links = new Set(data.not_regular);
+        for (const path of data.outside) {
+            lines.push(links.has(path) ? `  - ${path} (not a regular file: not followed, not read)` : `  - ${path}`);
+        }
+    }
+    const oc = data.on_chain;
+    if (!oc.checked) {
+        lines.push("on-chain      NOT CHECKED: no gateway was supplied, so no witness " +
+            "any pack names was re-fetched. Name gateways with --gateways to " +
+            "check them.");
+    }
+    else {
+        lines.push(`on-chain      re-fetched against ${oc.gateways.length} gateway(s), ` +
+            "pack by pack; the case reading above is offline and this does not " +
+            "change it");
+        for (const r of oc.packs) {
+            lines.push(`  ${r.ref}  ${r.witnesses} witness(es): ${r.confirmed} ` +
+                `confirmed, ${r.mismatched} mismatched, ${r.unreachable} ` +
+                `unreachable, ${r.not_checked} not checked`);
+        }
+        lines.push(`on-chain      ${oc.verdict.toUpperCase()}`);
+    }
+    return lines;
+}
+function caseError(e, asJson, io) {
+    if (asJson)
+        io.out(jsonText({ error: e.message, exit_code: EXIT_MALFORMED, hint: e.hint }));
+    io.err(noLoneSurrogates(`case: ${e.message}`));
+    if (e.hint)
+        io.err(noLoneSurrogates(`case: ${e.hint}`));
+    return EXIT_MALFORMED;
+}
+/**
+ * `proof case <folder>... [--gateways <urls>] [--json]`. Every path out of the
+ * command is an exit code from the table: an exception nobody expected exits 2,
+ * never 1, because 1 would name the evidence failed over a defect in this
+ * command.
+ */
+export async function runCase(argv, io) {
+    try {
+        return await caseCommand(argv, io);
+    }
+    catch (e) {
+        const name = e instanceof Error ? e.constructor.name : typeof e;
+        try {
+            return caseError(new CaseInputError(`an unexpected error stopped the reading (${name}); this is a defect in the ` +
+                "command, not a verdict on the evidence"), argv.includes("--json"), io);
+        }
+        catch {
+            return EXIT_MALFORMED; // a stream that cannot be written
+        }
+    }
+}
+async function caseCommand(argv, io) {
+    let asJson = false;
+    let gateways = [];
+    const paths = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if ((arg === "--help" || arg === "-h" || arg === "help") && paths.length === 0) {
+            io.out(CASE_USAGE);
+            return EXIT_VERIFIED;
+        }
+        if (arg === "--json") {
+            asJson = true;
+        }
+        else if (arg === "--gateways") {
+            const next = argv[i + 1];
+            if (next === undefined) {
+                io.err("case: --gateways requires a comma-separated list of URLs");
+                io.out(CASE_USAGE);
+                return EXIT_MALFORMED;
+            }
+            gateways = next
+                .split(",")
+                .map((g) => g.trim())
+                .filter((g) => g.length > 0);
+            i++;
+        }
+        else if (arg.startsWith("--")) {
+            io.err(`case: unknown option ${arg}`);
+            io.out(CASE_USAGE);
+            return EXIT_MALFORMED;
+        }
+        else {
+            paths.push(arg);
+        }
+    }
+    if (paths.length === 0) {
+        io.err("case: at least one pack is required");
+        io.out(CASE_USAGE);
+        return EXIT_MALFORMED;
+    }
+    let split;
+    let bundles;
+    try {
+        split = await splitCase(await treeFromArguments(paths), readFileEntry);
+        bundles = split.packs.map((p) => [p, loadBundle(p)]);
+    }
+    catch (e) {
+        if (e instanceof CaseInputError)
+            return caseError(e, asJson, io);
+        throw e;
+    }
+    const reading = await readCase(bundles.map(([p, bundle]) => ({ ref: p.ref, bundle, content: p.content })));
+    const onChain = await onChainHalf(bundles.map(([p, bundle]) => [p.ref, bundle]), gateways, io);
+    const code = caseExitCode(reading.verdict, onChain.verdict);
+    const nil = (v) => (v === undefined ? null : v);
+    const data = {
+        verdict: reading.verdict,
+        exit_code: code,
+        summary: renderCaseSummary(reading),
+        handoff_records: reading.handoffRecords,
+        on_chain_checked: reading.onChainChecked,
+        exceptions: reading.exceptions.map((e) => ({
+            kind: e.kind,
+            pack_ref: nil(e.packRef),
+            event_id: nil(e.eventId),
+            counterparty_key: nil(e.counterpartyKey),
+            failed_checks: e.failedChecks ?? [],
+            count: nil(e.count),
+            status: nil(e.status),
+            reasons: e.reasons ?? [],
+            rendered: renderException(e),
+        })),
+        records: reading.records.map((r) => ({
+            pack_ref: r.packRef,
+            event_id: r.eventId,
+            verdict: nil(r.verdict),
+            findings: r.findings,
+            failed_checks: r.failedChecks,
+            counterparts: r.counterparts,
+        })),
+        contributions: reading.contributions.map(([who, verdict]) => [who, verdict]),
+        packs: bundles.map(([p]) => ({
+            ref: p.ref,
+            bundle_path: p.bundlePath,
+            log_files: p.content.size,
+            unaccounted: p.unaccounted,
+        })),
+        outside: split.outside,
+        not_regular: split.notRegular,
+        on_chain: onChain,
+    };
+    if (asJson)
+        io.out(jsonText(data));
+    else
+        for (const line of caseReport(data))
+            io.out(noLoneSurrogates(line));
+    return code;
+}
 function shortTx(tx) {
     if (tx.length <= 16)
         return tx;