@sanning/proof 0.12.0 → 0.14.0

package/README.md

@@ -43,7 +43,7 @@ import { sha256Hex, verifyEnvelope, contentHashes } from "@sanning/proof";
 
 const myHash = await sha256Hex(fileBytes); // 64-char lowercase hex
 
-const result = await verifyEnvelope(env, myHash);
+const result = await verifyEnvelope(env, { expectedContentHash: myHash });
 result.contentHashOk; // true ⇔ the envelope commits to exactly these bytes
 result.contentRole;   // how it commits: e.g. the registered baseline,
                       // an observed (tampered) hash, …
@@ -53,17 +53,19 @@ contentHashes(env);   // all content hashes an envelope commits to, by event typ
 
 ## Verify a whole trace bundle: one command
 
+`npm install -g @sanning/proof` puts `sanning-proof` on your path, the same name `pip install sanning-proof` does (it was `proof` until 0.13.0). `npx @sanning/proof <command>` runs it without installing.
+
 The `@sanning/anchor` SDK hands a producer a set of `InclusionReceipt`s and can serialize them into one portable, self-verifying `sanning.evidence/v1` bundle (`body_type: sanning.anchor.trace/v3`). Verify the entire bundle (every event's signature + payload binding + Merkle inclusion, all offline) with the bundled CLI:
 
 ```bash
 npx @sanning/proof verify trace-bundle.json
 # also re-fetch each checkpoint on-chain to confirm it's anchored:
-npx @sanning/proof verify trace-bundle.json https://arweave.net,https://permagate.io
+npx @sanning/proof verify trace-bundle.json --gateways https://arweave.net,https://permagate.io
 ```
 
-It prints a per-event verdict, then the PACK verdict, and exits on a pinned code: `0` verified · `1` a real failure (bad signature / tamper / broken inclusion) · `2` malformed bundle · `3` undetermined, which is either a gateway that could not be reached on an on-chain re-fetch or a pack the grading rule calls `incomplete`. The headline is the pack verdict, the same one `gradePack` gives the browser verify page: a record nobody hashed leaves the pack incomplete even when the signed bundle itself is `verified`, and both verdicts are printed when they differ. Only `arweave` witnesses are re-fetched: a checkpoint or stamp whose `anchor_ref.kind` is anything else is not checked, and with gateways passed the run answers `partial`, exit `3`. The producer's asserted `verdict` is shown but **never trusted**, the displayed verdict is always recomputed from the body. The same CLI also verifies the agent's `sanning.agent.proof/v1` inclusion bundle (it sniffs `spec_version`), so one command covers anchor + agent.
+It prints a per-event verdict, then the PACK verdict, and exits by the one table every verb uses: `0` verified · `1` a real failure (bad signature / tamper / broken inclusion) · `2` usage or malformed · `3` undetermined (`partial`, `pending`, `incomplete` or `not_found`: a gateway that could not be reached, a stamp no witness published, or a pack the grading rule calls `incomplete`) · `4` mixed. Since 0.13.0 `partial` exits `3` whatever caused it; it exited `0` unless a gateway was unreachable. The headline is the pack verdict, the same one `gradePack` gives the browser verify page: a record nobody hashed leaves the pack incomplete even when the signed bundle itself is `verified`, and both verdicts are printed when they differ. Only `arweave` witnesses are re-fetched: a checkpoint or stamp whose `anchor_ref.kind` is anything else is not checked, and with gateways passed the run answers `partial`, exit `3`. The producer's asserted `verdict` is shown but **never trusted**, the displayed verdict is always recomputed from the body. The same CLI also verifies the agent's `sanning.agent.proof/v1` inclusion bundle (it sniffs `spec_version`), so one command covers anchor + agent.
 
-> The `verify` CLI is live in `@sanning/proof` ≥ 0.2.2, `npx @sanning/proof verify <bundle> [gateways]`. `verifyEvidenceBundle` is the programmatic API.
+> The `verify` CLI is live in `@sanning/proof` ≥ 0.2.2, `npx @sanning/proof verify <bundle> [--gateways <url,url>]` (the gateway list was a second positional argument until 0.13.0). `verifyEvidenceBundle` is the programmatic API.
 
 Programmatically:
 
@@ -102,7 +104,7 @@ npx @sanning/proof verify pack/bundle.json --logs pack/logs
 
 Nothing is decoded, re-parsed or re-serialised on the way in: the bytes on disk are the bytes hashed against the committed `content_hash`: the same bytes a verify page hashes from the same files. That is the whole point of the directory form. The alternative (reading the directory and hex-encoding it into a map yourself) is a step that has been got wrong twice in shipped code, once by writing the hex *text* into the log files, so `SHA-256(file)` was the hash of the encoding rather than of the bytes and genuine, untampered evidence failed.
 
-**A side input: a JSON FILE** mapping `event_id` → bytes, where an even-length lowercase-hex value is read as hex and anything else as UTF-8 text:
+**A side input: a JSON FILE** mapping `event_id` → bytes, where an even-length hex value, in either case, is read as hex and anything else as UTF-8 text:
 
 ```bash
 npx @sanning/proof verify trace-bundle.json --logs logs.json
@@ -163,28 +165,39 @@ Every event also appears in `result.events`, in body order, with a status that n
 
 Bytes come back as `Uint8Array`, never a string: the spec commits to **raw bytes**, and a UTF-8 decode is lossy for any payload that is not valid UTF-8, re-encoding such a string would change the bytes and break the hash. Decode to text yourself if you know your payload is text.
 
-## Check a case: several packs, one verdict
+## Read several packs together: a case reading
 
 When a case spans more than one pack (two agents, two organizations, one hand-off between them), check the packs together. This is `readCase` from a terminal, with no page in the way:
 
 ```bash
 npx @sanning/proof case assessor-pack/ challenger-pack/
-unzip decision-file.zip -d case/ && npx @sanning/proof case case/   # a decision file
+unzip packs.zip -d case/ && npx @sanning/proof case case/   # a zip of several packs
 npx @sanning/proof case case/ --json            # the full reading, for a script
 ```
 
-Each argument is a folder: one pack (`bundle.json` plus `logs/`), or a folder that holds several packs, such as an unpacked decision file. `case` does not open archives: given a `.zip`, it exits `2` and says to unzip it first and pass the folder. Packs are found by the verify page's splitting rule, so the page and this command apply the same rule to the same unpacked tree: 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 the folder is a file like any other. Several folders are read as one folder holding them, each under its own name. Each `bundle.json` is read with `verify`'s own reader (`readBundleBytes`), so the two commands classify one bundle the same way.
+Each argument is a folder: one pack (`bundle.json` plus `logs/`), or a folder that holds several packs, such as an unzipped folder of packs. `case` does not open archives: given a `.zip`, it exits `2` and says to unzip it first and pass the folder. Packs are found by the verify page's splitting rule, so the page and this command apply the same rule to the same unpacked tree: 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 the folder is a file like any other. Several folders are read as one folder holding them, each under its own name. Each `bundle.json` is read with `verify`'s own reader (`readBundleBytes`), so the two commands classify one bundle the same way.
 
 The walk is bounded and follows no link. A symbolic link is never followed: it is listed as outside every pack and not read, even under a pack's `logs/`, and a link named on the command line exits `2`. A folder nested more than 32 levels deep, more than 50,000 files and folders in all, or a name that is not valid UTF-8 exits `2`; a bad name is refused rather than escaped, because two different names would then read as one. A `bundle.json` nested more than 512 levels deep exits `2`, from `case` and from `verify` alike. The rules are pinned for both kernels by `vectors/case-split.json`, shipped in this tarball, as directory trees.
 
 Known differences from the verify page: the page opens a dropped `.zip`; the page drops a leading byte-order mark from `bundle.json`, which `verify`'s reader refuses; the page reads whatever the browser hands it for a link, a bad name or a very deep tree; and the page loses a record named `__proto__`, which this command keeps.
 
-The first line is the case verdict, then the kernel's summary and every exception through `renderException`, then the packs, the files outside them, and the on-chain half. Exit codes: `0` verified · `1` failed · `2` malformed, usage, an input that cannot be read as a case, or an unexpected error in the command · `3` incomplete or partial · `4` mixed (more than one outcome: read the exceptions). `verify` never exits `4`.
+The first line is the case verdict, then the kernel's summary and every exception through `renderException`, then the packs, the files outside them, and the on-chain half. Exit codes: `0` verified · `1` failed · `2` malformed, usage, an input that cannot be read as a case, or an unexpected error in the command · `3` incomplete or partial · `4` mixed (more than one outcome: read the exceptions). This is the one table every verb uses (`EXIT_CODES`, exported from the package root), and `verify` exits `3` on `partial` since 0.13.0.
 
 A case reading establishes that every pack verified offline, that every record every pack supplied was read in one pile under envelope-spec §4.1's hand-off rules, and that a hand-off record with no counterpart is always named. It does **not** establish that the case is complete, that a party which presented no pack under the named key recorded nothing, that two organizations are independent, or that any witness was re-fetched on chain: the output says `on-chain NOT CHECKED` unless you pass `--gateways <url,url>`. With gateways, each pack's witnesses are re-fetched pack by pack and reported beside the reading, which they never change; a witness that does not match exits `1`, and an on-chain half that could not be settled turns `0` into `3`.
 
 The Python kernel ships the same command as `sanning-proof case`, and `cross-kernel/run_case_cli.sh` requires the two to print the same bytes, the same `--json` and the same exit code over every `case/` corpus vector and every tree in `vectors/case-split.json`.
 
+## Compose an attested export
+
+An attested export (`sanning.evidence.export/v2`) carries operator attestations over a source bundle, signed with your own Ed25519 key. `composeExport` is the programmatic API:
+
+```bash
+npx @sanning/proof export source.json --attestations attestations.json --key exporter.key --out export.json
+npx @sanning/proof verify export.json
+```
+
+`export` exits `0` when it wrote the export, `1` when the recomputed export is `failed` (it still writes it, so you can inspect it), and `2` on a bad flag or malformed input. The verb was `bundle` until 0.13.0; `bundle` is now the verb that builds a pack, in `@sanning/anchor`. The Python kernel ships the same command as `sanning-proof export`.
+
 ## Verify a Merkle inclusion proof
 
 Agents close daily checkpoints over per-cycle leaves (RFC 9162, §2.1 domain separation, not the Bitcoin duplicate-leaf variant). Verify a leaf's inclusion against an anchored root:
@@ -205,16 +218,16 @@ const ok = await verifyInclusion(
 
 | Export | What it does |
 |---|---|
-| `verifyEnvelope(env, optionsOrContentHash?)` | The three load-bearing checks (spec-version registry, payload-hash recompute, Ed25519 over the signed scope) + optional content bind. Pass `{ payloadBytes }` for external-commitment envelopes. Returns `VerificationResult`. |
+| `verifyEnvelope(env, options?)` | The three load-bearing checks (spec-version registry, payload-hash recompute, Ed25519 over the signed scope) + optional content bind. Pass `{ payloadBytes }` for external-commitment envelopes, `{ expectedContentHash }` for the content bind (a bare string is refused since 0.13.0), and `{ acceptedSpecMajors }` to narrow the accept-set for one call. Returns `VerificationResult`. |
 | `verifyEvidenceBundle(bundle, { gateways?, fetchImpl? })` | Verify a signed `sanning.evidence/v1` bundle (`sanning.anchor.trace/v3`, `sanning.stamp.trace/v1`, `sanning.stamp.evidence/v2` or `sanning.evidence.export/v2`): wrapper signature + `body_hash` + every checkpoint + every event's inclusion, offline (optional on-chain re-fetch). Returns `EvidenceBundleResult`. Powers the `npx @sanning/proof verify` CLI. |
 | `disclosedContent(bundle, { gateways?, content?, fetchImpl? })` | **Ingest:** verify a bundle, then hand back the DECODED raw bytes (`Uint8Array`) of every event whose disclosure bound to its committed `content_hash`, so materializing a received pack never means re-implementing the hex convention. Returns `DisclosedContentResult` (`content` map + per-event `verified` / `not_disclosed` / `undetermined` / `failed`, plus the full `verification`). |
 | `gradePack(result, account, notes)` + `accountDisclosure(bundle, content)` / `completenessNotes(bundle)` / `renderCause(cause)` | **Pack grading:** what a SURFACE may claim about a pack: the bundle plus whatever disclosed bytes travelled with it. Three states, never two: `verified` only when every record's own bytes bound to its own commitment and nothing is missing, unreadable, surplus or omitted; `failed` on a proven mismatch; `incomplete` when a check could not be run. Absent evidence is UNKNOWN, never an accusation. Pure: no I/O; transport stays yours. Conformance table: `vectors/pack-grading.json`, shipped in this tarball. |
-| `verifyAgentProofBundle(bundle, { gateways?, fetchImpl? })` / `isAgentProofSpec(v)` | Verify the agent producer's `sanning.agent.proof/v1` inclusion bundle. |
+| `verifyAgentProof(bundle, { gateways?, fetchImpl? })` / `isAgentProofSpec(v)` | Verify the agent producer's `sanning.agent.proof/v1` inclusion bundle. |
 | `contentHashes(env)` | The content hash(es) an envelope commits to, by event type: the reverse-provenance join keys. |
 | `specVersionSupported(v)` | Fail-closed accept-check: `sanning.agent/v1` and additive minors (`sanning.agent/v1.<n>`). Unknown majors/profiles are rejected. |
 | `jcs(value)` | RFC 8785 canonical JSON bytes. |
 | `sha256Hex(bytes)` / `sha256Bytes(bytes)` | SHA-256 via WebCrypto. |
-| `ed25519Verify(sig, msg, pubKey)` | Raw Ed25519 verification. |
+| `ed25519Verify(message, signatureHex, publicKeyHex)` | Raw Ed25519 verification, strict RFC 8032 (`zip215: false`). The message comes first since 0.13.0, as in the Python `ed25519_verify`. |
 | `leafHash` / `nodeHash` / `merkleRoot` / `auditPath` / `verifyInclusion` / `EMPTY_TREE_ROOT_HEX` | RFC 9162 binary Merkle tree primitives. |
 | `utf8` / `bytesToHex` / `hexToBytes` | Encoding helpers. |
 | `Envelope` / `VerificationResult` / `ContentRole` / `Subject` | Types. |

package/dist/agent-proof.d.ts

@@ -1,5 +1,5 @@
 import type { Envelope } from "./types.js";
-export declare const AGENT_PROOF_SPEC_PREFIX = "sanning.agent.proof/v1";
+export declare const AGENT_PROOF_SPEC_VERSION = "sanning.agent.proof/v1";
 export interface AgentProofBundle {
     spec_version: string;
     checkpoint_envelope: Envelope;
@@ -25,4 +25,4 @@ export interface VerifyAgentProofOptions {
     fetchImpl?: typeof fetch;
 }
 export declare function isAgentProofSpec(specVersion: unknown): boolean;
-export declare function verifyAgentProofBundle(bundle: unknown, options?: VerifyAgentProofOptions): Promise<AgentProofResult>;
+export declare function verifyAgentProof(bundle: unknown, options?: VerifyAgentProofOptions): Promise<AgentProofResult>;

package/dist/agent-proof.js

@@ -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)
@@ -16,7 +16,7 @@
 import { hexToBytes, utf8 } from "./crypto.js";
 import { leafHash, verifyInclusion } from "./merkle.js";
 import { MAX_CANONICAL_DEPTH, exceedsDepth, jcs, jcsParse, verifyEnvelope } from "./verifier.js";
-export const AGENT_PROOF_SPEC_PREFIX = "sanning.agent.proof/v1";
+export const AGENT_PROOF_SPEC_VERSION = "sanning.agent.proof/v1";
 function stringifyErr(e) {
     return e instanceof Error ? e.message : String(e);
 }
@@ -29,9 +29,9 @@ function toHex(bytes) {
 export function isAgentProofSpec(specVersion) {
     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(bundle, options = {}) {
+export async function verifyAgentProof(bundle, options = {}) {
     const fail = (error) => ({
         status: "malformed",
         checkpointOk: false,

package/dist/case-file.d.ts

@@ -0,0 +1,126 @@
+/**
+ * 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.
+ */
+/** 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";
+/** The one command that checks the file, at its root (5.6.4). */
+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.
+ */
+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.
+ */
+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_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.
+ */
+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`.
+ */
+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.
+ */
+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 declare function jsonDepthExceeds(text: string | Uint8Array, limit: number): boolean;
+/**
+ * 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 declare function readCaseFileIndex(index: Uint8Array | null, files: readonly {
+    path: string;
+    sha256: string;
+}[]): 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.
+ */
+export declare function renderCaseFileFinding(finding: CaseFileFinding): string;

package/dist/case-file.js

@@ -0,0 +1,353 @@
+/**
+ * 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 { DuplicateKeyError, 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",
+];
+// `<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) {
+    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) {
+    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");
+}
+/**
+ * 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, limit) {
+    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[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, b) {
+    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 {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}
+const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** An own member, and never one the prototype chain answers for. */
+const own = (o, k) => (has(o, k) ? o[k] : undefined);
+function fileList(value, where) {
+    if (!Array.isArray(value))
+        throw new Unreadable(`${where} is not an array`);
+    const out = [];
+    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"], entry["sha256"]]);
+    });
+    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.
+ */
+function readIndex(raw) {
+    // 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;
+    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).
+        if (e instanceof DuplicateKeyError)
+            throw new Unreadable(e.message);
+        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 = [];
+    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"], 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 = [];
+    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"], has(entry, "public_key") ? key : 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, files) {
+    if (index === null || index === undefined) {
+        return { index: "absent", caseId: null, findings: [] };
+    }
+    let read;
+    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();
+    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();
+    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 = [];
+    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();
+    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) => {
+        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),
+                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) {
+    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.kind;
+    }
+}