@sanning/proof 0.12.0 → 0.14.0

package/src/case-file.ts

@@ -0,0 +1,422 @@
+/**
+ * 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",
+] 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 (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: [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;
+  }
+}