@sanning/proof 0.12.0 → 0.14.0

package/dist/file-match.js

@@ -0,0 +1,374 @@
+/**
+ * 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 { isFilePart } from "./message-parts.js";
+import { sideContentEntry } from "./side-content.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",
+];
+const REASON_TEXT = {
+    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"];
+function isObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function strOrNull(v) {
+    return typeof v === "string" ? v : null;
+}
+function own(o, key) {
+    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) {
+    for (const [name, nibbles] of [
+        ["public_key", 64],
+        ["signature", 128],
+    ]) {
+        const value = own(envelope, name);
+        if (typeof value === "string" && !isHexField(value, nibbles))
+            return false;
+    }
+    return true;
+}
+function decode(value) {
+    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, eventId, messageHash, content) {
+    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, content, packRef) {
+    const commitments = [];
+    const notRead = [];
+    const events = resolveTraceEvents(bundle);
+    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;
+        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, {
+            ...(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;
+        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 = {
+            publicKey: signer,
+            record: 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.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) {
+    const out = [];
+    for (const entry of files) {
+        if (!isObject(entry))
+            throw new TypeError("matchFiles: each file is an object {name, bytes}");
+        const { name, bytes } = entry;
+        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, notRead, files) {
+    const offered = await offeredDigests(files);
+    const matched = [];
+    const unmatched = [];
+    const used = new Set();
+    for (const [name, digest] of offered) {
+        const hits = [];
+        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, files, content) {
+    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, files) {
+    const commitments = [];
+    const 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) {
+    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) {
+    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) {
+    return eventId !== null ? `record ${eventId}` : "a record with no event_id";
+}
+function renderCommitment(c) {
+    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) {
+    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) {
+    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;
+}

package/dist/grading.d.ts

@@ -1,6 +1,7 @@
 import type { DeclarationCheck, DeclarationContentKind, DeclarationDeviationKind, DeclarationVerdict } from "./declaration.js";
 import { type SideContentMap } from "./side-content.js";
-export type PackVerdict = "verified" | "partial" | "pending" | "not_found" | "mixed" | "failed" | "malformed" | "incomplete";
+export declare const PACK_VERDICTS: readonly ["verified", "partial", "pending", "not_found", "mixed", "failed", "malformed", "incomplete"];
+export type PackVerdict = (typeof PACK_VERDICTS)[number];
 /**
  * The minimum this module reads out of a verification result.
  *
@@ -12,9 +13,16 @@ export type PackVerdict = "verified" | "partial" | "pending" | "not_found" | "mi
  */
 export interface GradeInput {
     status: string | null | undefined;
+    /**
+     * `eventId` and `payloadBindingOk` are read by rule version 6 alone (A22):
+     * an input that does not carry both is never withheld by its declaration,
+     * so an adapter written for rule version 5 keeps the stricter reading.
+     */
     events: {
         ok: boolean;
         contentOk: boolean | null;
+        eventId?: string;
+        payloadBindingOk?: boolean | null;
     }[];
 }
 /**
@@ -56,13 +64,8 @@ export type CompletenessNote = {
     presented: null;
     kind: "unreadable";
 };
-export type PackGradeCauseKind = "records-omitted" | "records-surplus" | "leaf-count-unreadable" | "no-disclosure" | "missing-disclosure" | "unreadable-disclosure" | "unaccounted-disclosure" | "declaration-deviation"
-/**
- * The pack and the UNSIGNED content handed in beside it do not line up
- * (proof#147). A cause, so the pack cannot read clean over it and a reader
- * is told which record; NOT a deviation, so it never reaches `failed`.
- */
- | "declaration-content-dependent";
+export declare const PACK_GRADE_CAUSE_KINDS: readonly ["records_omitted", "records_surplus", "leaf_count_unreadable", "no_disclosure", "missing_disclosure", "unreadable_disclosure", "unaccounted_disclosure", "declaration_deviation", "declaration_content_dependent"];
+export type PackGradeCauseKind = (typeof PACK_GRADE_CAUSE_KINDS)[number];
 /**
  * One reason a pack is not `verified`, as data.
  *
@@ -89,8 +92,8 @@ export interface PackGradeCause {
     reason?: string;
     /**
      * Which deviation from the pack's own declaration, for
-     * `declaration-deviation`, or which content-dependent finding, for
-     * `declaration-content-dependent`.
+     * `declaration_deviation`, or which content-dependent finding, for
+     * `declaration_content_dependent`.
      */
     deviation?: DeclarationDeviationKind | DeclarationContentKind;
 }
@@ -107,6 +110,17 @@ export interface PackGrade {
      * check was passed, which is the pre-§5.4 call.
      */
     declaration?: DeclarationVerdict;
+    /**
+     * Records WITHHELD BY THEIR DECLARATION (rule version 6, evidence-bundle
+     * 5.4.5 v1.20, A22): a readable declaration lists them in
+     * `declaredWithheld`, their `ok` is true, their `contentOk` is `null` and
+     * their `payloadBindingOk` is true. Never counted in `recordsVerified`: no
+     * byte of their content was hashed, and a surface MUST NOT print them as
+     * verified records.
+     */
+    recordsWithheld: number;
+    /** Their `event_id`s, in bundle order. */
+    withheldEventIds: string[];
 }
 /**
  * Account for the disclosed bytes a pack handed us against the records its
@@ -152,13 +166,14 @@ export declare function completenessNotes(bundle: unknown): CompletenessNote[];
  * Every reason this pack is not `verified`, in the order a reader should hear
  * them: what is missing from the whole, then what is missing from the parts.
  */
-export declare function gradeCauses(account: DisclosureAccount, notes: readonly CompletenessNote[], declaration?: DeclarationCheck | null): PackGradeCause[];
+export declare function gradeCauses(account: DisclosureAccount, notes: readonly CompletenessNote[], declaration?: DeclarationCheck | null, withheld?: readonly string[]): PackGradeCause[];
 /**
  * The verdict a surface may print, and the counts it may print beside it.
  *
  * The invariant, stated so a mutation test can kill it: `verified` is reachable
- * ONLY when every record's supplied bytes bound to its own commitment and
- * nothing is missing, unreadable, surplus or omitted.
+ * ONLY when every record's supplied bytes bound to its own commitment, or
+ * (rule version 6) the record is withheld by its declaration, and nothing is
+ * missing, unreadable, surplus or omitted.
  *
  * Precedence: malformed > failed > incomplete > the kernel's own headline.
  * A hard verdict wins — "the bytes are absent" is never reported as failure