@sanning/proof 0.12.0 → 0.14.0

package/src/file-match.ts

@@ -0,0 +1,461 @@
+/**
+ * Files handed in beside a pack, matched against what its records signed (A29).
+ *
+ * The TypeScript half of `src/sanning_proof/file_match.py`. Both kernels are
+ * held to one table, `vectors/file-match.json`, so neither can pass by agreeing
+ * with the other, and `cross-kernel/run_file_match.sh` holds the two readings,
+ * and the two commands' `--files` output, to the same bytes.
+ *
+ * WHAT THIS ANSWERS (evidence-bundle.md 5.7 v1.24, proof#92, decided by Phil
+ * 2026-09-23 as option 2). A reader holds a pack and some files beside it and
+ * asks whether the pack vouches for them. Each offered file is hashed, SHA-256
+ * over its exact bytes, and the digest is looked for among the commitments the
+ * pack's SIGNED records make. The reading says which offered files a record
+ * commits to (naming the record, its signer and its `signed_at`), which match
+ * no record, and which commitments had no file offered.
+ *
+ * THE RULES THAT CARRY THE WEIGHT:
+ *
+ *   - By hash, and by nothing else. A file's name is carried through as the
+ *     caller's label and is never compared with an `event_id`, a part's name or
+ *     a `logs/` path. There is no layout convention.
+ *   - Unmatched is reported, never guessed.
+ *   - Only what a record's own key signed: a verified envelope whose
+ *     `event_bytes` bind to its `payload_hash`, or a hand-off message whose
+ *     bytes bind to that record's `message_hash`. No wrapper field is read.
+ *   - The verdict does not move. A match proves that a signed record in the
+ *     pack committed to those exact bytes, and nothing more (`FILE_MATCH_SCOPE`).
+ *
+ * WHAT COUNTS AS A COMMITMENT, in record order and then part order:
+ *
+ *   1. `record`: a record outside envelope-spec.md 4.1 commits through
+ *      `event.content_hash`, 64 hex characters in either case.
+ *   2. `file_part`: a record 4.1 governs commits to its MESSAGE through
+ *      `event.message_hash` (5.1, A20), never through a `content_hash` it also
+ *      writes. Where the message's JCS bytes are in hand (in the body, or in
+ *      the side content) and bind to it, each file part of that message (A18)
+ *      commits by its `content_hash`.
+ *
+ * Side content is read for ONE thing, to find a hand-off message that binds to
+ * a signed `message_hash`. It is never an offered file.
+ *
+ * Pure: a bundle, the files and the optional side content in, a reading out.
+ */
+
+import { hexToBytes, isHexField, sha256Hex } from "./crypto.js";
+import { resolveTraceEvents } from "./evidence.js";
+import { isConformantHandoffRecord, isHandoffNamespace } from "./handoff.js";
+import type { HeldRecord } from "./handoff.js";
+import { isFilePart } from "./message-parts.js";
+import { sideContentEntry } from "./side-content.js";
+import type { SideContentMap } from "./side-content.js";
+import type { Envelope } from "./types.js";
+import { jcsParse, verifyEnvelope } from "./verifier.js";
+
+/** The one sentence every surface prints with the reading (5.7). */
+export const FILE_MATCH_SCOPE =
+  "A match proves that a signed record in the pack committed to these exact " +
+  "bytes, and nothing more.";
+
+/** Why a record's commitments could not be read, in the order they are tested. */
+export const NOT_READ_REASONS = [
+  "no_records",
+  "record_unreadable",
+  "record_not_verified",
+  "record_withheld",
+  "no_content_hash",
+  "handoff_record_malformed",
+  "message_withheld",
+] as const;
+
+export type NotReadReason = (typeof NOT_READ_REASONS)[number];
+
+const REASON_TEXT: Record<NotReadReason, string> = {
+  no_records: "this bundle carries no records this reading can read",
+  record_unreadable: "its record bytes cannot be read",
+  record_not_verified: "its envelope does not verify",
+  record_withheld: "its record bytes are withheld",
+  no_content_hash: "it commits to no content_hash",
+  handoff_record_malformed:
+    "it is a hand-off record that commits to no message a reader can bind to",
+  message_withheld: "its message is not in hand, so its file parts cannot be read",
+};
+
+// The accept-set minus the quarantined `sanning.mlflow/v1` (DL-63), the set
+// both kernels read a case under.
+const RECORD_PROFILES = ["sanning.agent/v1", "sanning.events/v2"] as const;
+
+/** One commitment a signed record makes to a file's bytes. */
+export interface FileCommitment {
+  packRef: string | null;
+  eventId: string | null;
+  kind: "record" | "file_part";
+  partIndex: number | null;
+  contentHash: string;
+  signer: string;
+  signedAt: string | null;
+}
+
+export interface MatchedFile {
+  name: string;
+  sha256: string;
+  records: FileCommitment[];
+}
+
+export interface UnmatchedFile {
+  name: string;
+  sha256: string;
+}
+
+export interface NotRead {
+  packRef: string | null;
+  eventId: string | null;
+  reason: NotReadReason;
+}
+
+export interface FileMatchReading {
+  offered: number;
+  matched: MatchedFile[];
+  unmatched: UnmatchedFile[];
+  notOffered: FileCommitment[];
+  notRead: NotRead[];
+  scope: string;
+}
+
+/** A file handed in beside a pack. `name` is a label and is never compared. */
+export interface OfferedFile {
+  name: string;
+  bytes: Uint8Array;
+}
+
+/** One pack of a case, for `matchCaseFiles`. */
+export interface FileMatchPack {
+  ref: string;
+  bundle: unknown;
+  content?: SideContentMap | null;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function strOrNull(v: unknown): string | null {
+  return typeof v === "string" ? v : null;
+}
+
+function own(o: Record<string, unknown>, key: string): unknown {
+  return Object.prototype.hasOwnProperty.call(o, key) ? o[key] : undefined;
+}
+
+// The envelope's key and signature in the hex charset at their lengths, the
+// reading every body verifier applies inside a bundle (proof#142).
+function envelopeSpelled(envelope: Record<string, unknown>): boolean {
+  for (const [name, nibbles] of [
+    ["public_key", 64],
+    ["signature", 128],
+  ] as const) {
+    const value = own(envelope, name);
+    if (typeof value === "string" && !isHexField(value, nibbles)) return false;
+  }
+  return true;
+}
+
+function decode(value: unknown): Uint8Array | undefined {
+  if (value instanceof Uint8Array) return value;
+  if (typeof value === "string") {
+    try {
+      return hexToBytes(value);
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+const ABSENT = Symbol("absent");
+
+async function messageOf(
+  ev: Record<string, unknown>,
+  eventId: string | null,
+  messageHash: string,
+  content: SideContentMap | null | undefined,
+): Promise<unknown> {
+  const candidates = [decode(own(ev, "content"))];
+  if (eventId !== null) candidates.push(decode(sideContentEntry(content, eventId).value));
+  for (const raw of candidates) {
+    if (raw === undefined || (await sha256Hex(raw)) !== messageHash) continue;
+    try {
+      return jcsParse(raw);
+    } catch {
+      continue;
+    }
+  }
+  return ABSENT;
+}
+
+async function readPack(
+  bundle: unknown,
+  content: SideContentMap | null | undefined,
+  packRef: string | null,
+): Promise<{ commitments: FileCommitment[]; notRead: NotRead[] }> {
+  const commitments: FileCommitment[] = [];
+  const notRead: NotRead[] = [];
+  const events = resolveTraceEvents(bundle) as unknown[] | undefined;
+  if (events === undefined) {
+    notRead.push({ packRef, eventId: null, reason: "no_records" });
+    return { commitments, notRead };
+  }
+  for (const ev of events) {
+    if (!isObject(ev)) {
+      notRead.push({ packRef, eventId: null, reason: "record_unreadable" });
+      continue;
+    }
+    const envelope = own(ev, "envelope");
+    const eventId = isObject(envelope) ? strOrNull(own(envelope, "event_id")) : null;
+
+    const rawBytes = own(ev, "event_bytes");
+    let eventBytes: Uint8Array | undefined;
+    if (rawBytes !== undefined && rawBytes !== null) {
+      eventBytes = typeof rawBytes === "string" ? decode(rawBytes) : undefined;
+      if (eventBytes === undefined) {
+        notRead.push({ packRef, eventId, reason: "record_unreadable" });
+        continue;
+      }
+    }
+
+    const result = await verifyEnvelope(envelope as Envelope, {
+      ...(eventBytes !== undefined ? { payloadBytes: eventBytes } : {}),
+      acceptedSpecMajors: RECORD_PROFILES,
+    });
+    if (!result.ok || !isObject(envelope) || !envelopeSpelled(envelope)) {
+      notRead.push({ packRef, eventId, reason: "record_not_verified" });
+      continue;
+    }
+    if (eventBytes === undefined) {
+      notRead.push({ packRef, eventId, reason: "record_withheld" });
+      continue;
+    }
+    if (result.payloadHashOk !== true) {
+      notRead.push({ packRef, eventId, reason: "record_not_verified" });
+      continue;
+    }
+    let record: unknown;
+    try {
+      record = jcsParse(eventBytes);
+    } catch {
+      record = undefined;
+    }
+    if (!isObject(record)) {
+      notRead.push({ packRef, eventId, reason: "record_unreadable" });
+      continue;
+    }
+
+    const key = own(envelope, "public_key");
+    const signer = typeof key === "string" ? key : "";
+    const signedAt = strOrNull(own(envelope, "signed_at"));
+    const section = own(record, "event");
+    const event = isObject(section) ? section : {};
+
+    const held: HeldRecord = {
+      publicKey: signer,
+      record: record as HeldRecord["record"],
+      ref: "",
+    };
+    if (isHandoffNamespace(held)) {
+      const messageHash = own(event, "message_hash");
+      if (!isConformantHandoffRecord(held) || !isHexField(messageHash, 64, true)) {
+        notRead.push({ packRef, eventId, reason: "handoff_record_malformed" });
+        continue;
+      }
+      const message = await messageOf(ev, eventId, messageHash, content);
+      if (message === ABSENT) {
+        notRead.push({ packRef, eventId, reason: "message_withheld" });
+        continue;
+      }
+      const parts = isObject(message) ? own(message, "parts") : undefined;
+      if (Array.isArray(parts)) {
+        parts.forEach((part, index) => {
+          if (!isFilePart(part)) return;
+          commitments.push({
+            packRef,
+            eventId,
+            kind: "file_part",
+            partIndex: index,
+            contentHash: ((part as { content_hash: string }).content_hash).toLowerCase(),
+            signer,
+            signedAt,
+          });
+        });
+      }
+      continue;
+    }
+
+    const contentHash = own(event, "content_hash");
+    if (!isHexField(contentHash, 64)) {
+      notRead.push({ packRef, eventId, reason: "no_content_hash" });
+      continue;
+    }
+    commitments.push({
+      packRef,
+      eventId,
+      kind: "record",
+      partIndex: null,
+      contentHash: contentHash.toLowerCase(),
+      signer,
+      signedAt,
+    });
+  }
+  return { commitments, notRead };
+}
+
+// A malformed file entry is the CALLER's mistake, not the evidence's, so it
+// throws rather than reading as a file that matched nothing.
+async function offeredDigests(files: readonly OfferedFile[]): Promise<[string, string][]> {
+  const out: [string, string][] = [];
+  for (const entry of files) {
+    if (!isObject(entry)) throw new TypeError("matchFiles: each file is an object {name, bytes}");
+    const { name, bytes } = entry as { name?: unknown; bytes?: unknown };
+    if (typeof name !== "string") throw new TypeError("matchFiles: a file's name is a string");
+    if (!(bytes instanceof Uint8Array)) {
+      throw new TypeError("matchFiles: a file's bytes are a Uint8Array");
+    }
+    out.push([name, await sha256Hex(bytes)]);
+  }
+  return out;
+}
+
+async function match(
+  commitments: FileCommitment[],
+  notRead: NotRead[],
+  files: readonly OfferedFile[],
+): Promise<FileMatchReading> {
+  const offered = await offeredDigests(files);
+  const matched: MatchedFile[] = [];
+  const unmatched: UnmatchedFile[] = [];
+  const used = new Set<number>();
+  for (const [name, digest] of offered) {
+    const hits: number[] = [];
+    commitments.forEach((c, i) => {
+      if (c.contentHash === digest) hits.push(i);
+    });
+    if (hits.length > 0) {
+      for (const i of hits) used.add(i);
+      matched.push({ name, sha256: digest, records: hits.map((i) => commitments[i]!) });
+    } else {
+      unmatched.push({ name, sha256: digest });
+    }
+  }
+  return {
+    offered: offered.length,
+    matched,
+    unmatched,
+    notOffered: commitments.filter((_, i) => !used.has(i)),
+    notRead,
+    scope: FILE_MATCH_SCOPE,
+  };
+}
+
+/**
+ * Match each offered file against the commitments one pack's signed records
+ * make. `content` is the side content handed in beside the pack, read only to
+ * find a hand-off message that binds to its record's `message_hash`; it is
+ * never an offered file.
+ */
+export async function matchFiles(
+  bundle: unknown,
+  files: readonly OfferedFile[],
+  content?: SideContentMap | null,
+): Promise<FileMatchReading> {
+  const { commitments, notRead } = await readPack(bundle, content, null);
+  return match(commitments, notRead, files);
+}
+
+/** The same reading over every pack of a case, each commitment naming its pack's `ref`. */
+export async function matchCaseFiles(
+  packs: readonly FileMatchPack[],
+  files: readonly OfferedFile[],
+): Promise<FileMatchReading> {
+  const commitments: FileCommitment[] = [];
+  const notRead: NotRead[] = [];
+  for (const pack of packs) {
+    if (!isObject(pack)) throw new TypeError("matchCaseFiles: each pack is an object {ref, bundle}");
+    if (typeof pack.ref !== "string") throw new TypeError("matchCaseFiles: a pack's ref is a string");
+    const r = await readPack(pack.bundle, pack.content, pack.ref);
+    commitments.push(...r.commitments);
+    notRead.push(...r.notRead);
+  }
+  return match(commitments, notRead, files);
+}
+
+function commitmentJson(c: FileCommitment): Record<string, unknown> {
+  return {
+    pack_ref: c.packRef,
+    event_id: c.eventId,
+    kind: c.kind,
+    part_index: c.partIndex,
+    content_hash: c.contentHash,
+    signer: c.signer,
+    signed_at: c.signedAt,
+  };
+}
+
+/** The reading as the `files` member of `--json`, identical in both kernels. */
+export function fileMatchToJson(reading: FileMatchReading): Record<string, unknown> {
+  return {
+    offered: reading.offered,
+    matched: reading.matched.map((m) => ({
+      name: m.name,
+      sha256: m.sha256,
+      records: m.records.map(commitmentJson),
+    })),
+    unmatched: reading.unmatched.map((u) => ({ name: u.name, sha256: u.sha256 })),
+    not_offered: reading.notOffered.map(commitmentJson),
+    not_read: reading.notRead.map((n) => ({
+      pack_ref: n.packRef,
+      event_id: n.eventId,
+      reason: n.reason,
+      rendered: renderNotRead(n),
+    })),
+    scope: reading.scope,
+  };
+}
+
+function recordName(eventId: string | null): string {
+  return eventId !== null ? `record ${eventId}` : "a record with no event_id";
+}
+
+function renderCommitment(c: FileCommitment): string {
+  const what =
+    c.kind === "record"
+      ? recordName(c.eventId)
+      : `file part ${c.partIndex} of the message in ${recordName(c.eventId)}`;
+  const where = c.packRef !== null ? ` in pack ${c.packRef}` : "";
+  const when = c.signedAt !== null ? c.signedAt : "no stated time";
+  return `${what}${where}, signed by ${c.signer}, signed_at ${when}`;
+}
+
+function renderNotRead(n: NotRead): string {
+  const where = n.packRef !== null ? ` in pack ${n.packRef}` : "";
+  if (n.reason === "no_records") return `no record read${where}: ${REASON_TEXT[n.reason]}`;
+  return `${recordName(n.eventId)}${where} not read: ${REASON_TEXT[n.reason]}`;
+}
+
+/** The text report's lines for the reading, identical in both kernels. */
+export function renderFileMatch(reading: FileMatchReading): string[] {
+  const lines = [
+    `files         ${reading.offered} offered: ${reading.matched.length} vouched for, ` +
+      `${reading.unmatched.length} match no record; ` +
+      `${reading.notOffered.length} commitment(s) had no file offered`,
+  ];
+  for (const m of reading.matched) {
+    lines.push(`  vouched for  ${m.name}  sha256 ${m.sha256}`);
+    for (const c of m.records) lines.push(`    by ${renderCommitment(c)}`);
+  }
+  for (const u of reading.unmatched) lines.push(`  no match     ${u.name}  sha256 ${u.sha256}`);
+  for (const c of reading.notOffered) {
+    lines.push(`  not offered  ${c.contentHash}, ${renderCommitment(c)}`);
+  }
+  for (const n of reading.notRead) lines.push(`  not read     ${renderNotRead(n)}`);
+  lines.push(`  ${reading.scope}`);
+  return lines;
+}