@sanning/proof 0.10.0 → 0.11.1

package/dist/index.js

@@ -51,6 +51,40 @@ export { ANCHOR_TRACE_BODY_TYPE, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRA
 // derivation to it, and diff its copy against ours. Additive — no existing
 // export changes.
 export { accountDisclosure, completenessNotes, gradeCauses, gradePack, renderCause, signedLeafCount, } from "./grading.js";
+// The declaration (src/declaration.ts): what a pack SAYS it holds, checked
+// against what it does (evidence-bundle.md §5.4).
+//
+// Every other check in this kernel checks a record that is PRESENT, so a pack
+// with half its records dropped verifies perfectly and an auditor cannot tell
+// a full hand-over from a trimmed one. The declaration is the pack's own
+// statement of what it was meant to contain, inside `body` and therefore under
+// the bundle's signature. Any deviation FAILS and every deviation is NAMED; a
+// pack that carries no declaration is `partial`, never `verified`; and a
+// reading that rests on the UNSIGNED content handed in beside the pack is
+// named on its own and carries the weaker word, because whoever assembles a
+// case chose those bytes (proof#147).
+//
+// Pure: data in, data out, no I/O. `gradePack` takes the result as an
+// optional fourth argument, so a surface gets one verdict; omitting it is the
+// pre-§5.4 behavior, unchanged. Additive: no existing export changes.
+export { DECLARATION_VERSION, checkDeclaration, declarationClaims, packRecords, renderContentFinding, renderDeclarationSummary, renderDeviation, renderNote, } from "./declaration.js";
+// The case (src/case.ts): one verdict over SEVERAL packs, across organizations
+// (anchor#198). The layer above the declaration, and the closure for what a
+// declaration cannot reach.
+//
+// A pack a party assembles about itself is not self-proving about what that
+// party LEFT OUT (envelope-spec.md §4.1 A15, evidence-bundle.md §5.4.2 rule 7),
+// because the omission happens before any reader runs. Reading several parties'
+// packs at once is what closes it: a `handoff.sent` with no counterpart is
+// always named, and where a pack signed by the key it names is in the case, the
+// reading says that pack holds no counterpart. Whether a party that presented
+// no such pack recorded anything is not established (proof#143). `readCase`
+// verifies every pack itself, offline, so it is async. Matching is on keys and hashes alone and NEVER on tenancy, so a pair from two
+// organizations verifies (DL-60).
+//
+// Pure: data in, data out, no I/O. Additive: a new module, no existing export
+// changes, and no new verdict word anywhere.
+export { CASE_BODY_TYPES, CASE_EXCEPTION_KINDS, CASE_QUARANTINED_PROFILES, CASE_RECORD_PROFILES, CASE_VERDICTS, readCase, renderCaseSummary, renderException, } from "./case.js";
 // Chain reading (src/chain.ts): following the pointer every sanning.events/v2
 // record carries to the record before it, over the records ONE bundle presents.
 //
@@ -81,3 +115,19 @@ export { attestationSignatureToHex, composeExport } from "./compose.js";
 // sanning.agent.proof/v1 bundle. The CLI sniffs spec_version and routes here so
 // one verifier covers both agent and anchor bundles.
 export { AGENT_PROOF_SPEC_PREFIX, isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
+// The hand-off pairing rule (src/handoff.ts): which records are candidates to
+// be the counterpart of a hand-off record, how a candidate set of more than one
+// is ordered, and what a formed pair grades to (specs/envelope-spec.md §4.1
+// v1.9, proof#132 and proof#136). The Python half is src/sanning_proof/handoff.py and the two
+// answer identically on identical bytes. Additive: a new module, and no
+// existing export changes.
+export { CANDIDATE_NAMESPACE, DEFINED_EVENT_TYPES, NOT_A_HANDOFF_FINDING, isConformantHandoffRecord, readHandoff, readHandoffs, recordIsMalformed, } from "./handoff.js";
+// A file part's BYTES (src/message-parts.ts): what a file part is, and what a
+// receiver that HOLDS a part's bytes commits to (envelope-spec.md section 4.1
+// v1.13, A18, proof#145). A receiver that holds the bytes hashes them and, on a
+// mismatch, commits to the message AS IT HELD IT, so the pair fails on
+// `message_hash` rather than verifying over bytes nobody checked. The Python
+// half is src/sanning_proof/message_parts.py and the two are held together by
+// cross-kernel/run_parts.sh. Pure: it neither canonicalizes nor hashes the
+// message.
+export { BYTES_FOR_UNKNOWN_PART, CONFLICTING_PART_BYTES, INLINE_BYTES_KEYS, MESSAGE_RESULT_ORDER, PARTS_NOT_AN_ARRAY, PART_ENCODING_MISMATCH, PART_INLINE_BYTES, PART_INLINE_MISMATCHED, PART_MALFORMED_DESCRIPTOR, PART_MATCHED, PART_MISMATCHED, PART_NOT_A_FILE, PART_SUPPLIED_TWICE, PART_UNCHECKED, REFUSAL_ORDER, commitHeldMessage, isFilePart, uncheckedHeldParts, } from "./message-parts.js";

package/dist/message-parts.d.ts

@@ -0,0 +1,283 @@
+/**
+ * The result of a part whose supplied bytes hash to its `content_hash` AND
+ * count to its `content_length`.
+ */
+export declare const PART_MATCHED = "part_matched";
+/**
+ * The result of a part whose supplied bytes miss either of those, with no
+ * respelling of them that explains the digest. The held-message substitution
+ * applies to this part, and it replaces BOTH values with the held bytes' own.
+ */
+export declare const PART_MISMATCHED = "part_mismatched";
+/**
+ * A file part whose bytes were not supplied, or whose supply was REFUSED. It is
+ * not checked and it is not clean: section 4.1 forbids a reader treating it as
+ * checked.
+ */
+export declare const PART_UNCHECKED = "part_unchecked";
+/**
+ * A `kind: "file"` part carrying its content inside the message, and ACCEPTED
+ * (proof#157, ratified by Phil 2026-09-22). It is committed by the MESSAGE
+ * ITSELF: `message_hash` is SHA-256 over the canonical bytes of the message
+ * object, so altering that content changes the message, changes the hash, and
+ * fails the pair. Nothing is hashed against it here and nothing is substituted,
+ * because there is nothing travelling beside the message for the message to
+ * disagree with. That is why the swapped-bytes attack cannot reach this shape.
+ */
+export declare const PART_INLINE_BYTES = "part_inline_bytes";
+/**
+ * An inline part whose `content_hash`, `content_length` or both DISAGREE with
+ * its inline content: no single reading of that content satisfies every claim
+ * the part writes beside it. The message's own commitment still governs and
+ * nothing is substituted; this names the SECOND claim that disagrees with it,
+ * which is a finding in its own right (proof#157).
+ *
+ * ONE name for both claims, exactly as `PART_MISMATCHED` is one name for both
+ * on a descriptor part. It was `part_inline_hash_mismatch` for one round of
+ * this unmerged PR, when only the hash was compared; a name that says "hash"
+ * about a result that also covers a length asserts more than its body does, so
+ * the name was re-cut with the rule (proof#156 second gate, F4).
+ *
+ * The check is deliberately permissive ACROSS readings: the raw UTF-8 of the
+ * value, its base64 decoding and its hex decoding are all tried, so this fires
+ * only where no reading agrees at all. It is not permissive BETWEEN claims: one
+ * reading has to satisfy all of them, because a hash that agrees under the
+ * base64 decoding beside a length that agrees under the raw text describes no
+ * blob that exists.
+ */
+export declare const PART_INLINE_MISMATCHED = "part_inline_mismatched";
+/**
+ * `kind: "file"` without a conformant `content_hash` and `content_length`. A
+ * sender's defect rather than a receiver's, so it is named rather than refused:
+ * the receiver did nothing wrong by holding it.
+ */
+export declare const PART_MALFORMED_DESCRIPTOR = "part_malformed_descriptor";
+/**
+ * Any other part. It is committed as ordinary JSON content and this rule checks
+ * nothing about it.
+ */
+export declare const PART_NOT_A_FILE = "part_not_a_file";
+/**
+ * REFUSAL of ONE supplied entry. Bytes were supplied for no part of the
+ * message, or for a part this rule cannot check. The caller and the message
+ * disagree about what was sent, and hashing bytes against a part that is not
+ * there establishes nothing. Where the entry names a part that EXISTS but is
+ * not checkable, the refusal carries that part's index and the part keeps the
+ * result it classified to; where it names no part at all, the refusal carries
+ * the entry position and no part. Neither stops the record being written.
+ */
+export declare const BYTES_FOR_UNKNOWN_PART = "bytes_for_unknown_part";
+/**
+ * REFUSAL. Two DIFFERENT byte strings were supplied for one part. A receiver
+ * holding two answers has not established which one it held.
+ */
+export declare const CONFLICTING_PART_BYTES = "conflicting_part_bytes";
+/**
+ * REFUSAL of ONE supplied entry. The supplied bytes miss the descriptor, but a
+ * base64 or hex RESPELLING of them in EITHER direction hashes to it: either the
+ * bytes DECODE to the part (the receiver's stack never decoded what it was
+ * handed) or they ENCODE to it (the receiver's stack decoded bytes the sender
+ * committed in their encoded spelling, which is what a single-line DER
+ * attachment, a PEM body and a JWT all are). That is a coding defect in the
+ * receiver, not a tamper by the sender: a proto3 JSON transcoder re-encodes
+ * base64 URL-safe and unpadded while behaving honestly, and under the silence
+ * this amendment removes it produced a permanent tamper record against a sender
+ * who did nothing. Recording evidence out of a receiver's own bug is the one
+ * outcome worse than recording nothing, so BOTH directions are guarded
+ * (proof#156 gate): guarding only the decoding direction left the other half of
+ * one honest stack's behavior reading as a tamper.
+ */
+export declare const PART_ENCODING_MISMATCH = "part_encoding_mismatch";
+/**
+ * A MESSAGE-LEVEL result. The message carries a `parts` key whose value is
+ * present and is not an array, which is how proto3 JSON encodes a map and so is
+ * reachable from the same transport family the motivating example comes from.
+ * Section 4.1 asks for one result per part; a message shaped like this has
+ * part-shaped content and no parts, and before proof#156's gate it produced
+ * zero readings and an accepted record. It is named rather than refused: the
+ * receiver did nothing wrong by holding it, and nothing in it is checked. A
+ * `parts` written as `null` is an ABSENT `parts` and is not this, on A14's
+ * ruling that an absent value and one written as `null` name one thing.
+ */
+export declare const PARTS_NOT_AN_ARRAY = "parts_not_an_array";
+/**
+ * NOTE, not a refusal. One part supplied more than once with IDENTICAL bytes is
+ * one supply stated twice, and the part is checked normally. Different bytes for
+ * one part are `CONFLICTING_PART_BYTES`.
+ */
+export declare const PART_SUPPLIED_TWICE = "part_supplied_twice";
+/**
+ * The order refusals are reported in, fixed so two kernels report one list
+ * rather than two orderings of it.
+ */
+export declare const REFUSAL_ORDER: readonly ["bytes_for_unknown_part", "conflicting_part_bytes", "part_encoding_mismatch"];
+/**
+ * The order message-level results are reported in, for the same reason as
+ * `REFUSAL_ORDER`.
+ */
+export declare const MESSAGE_RESULT_ORDER: readonly ["parts_not_an_array"];
+/**
+ * The keys that make a part carry its content INLINE, in the order they are
+ * read. Named rather than inferred: `bytes` is A2A's spelling of an inline file
+ * part, and `data` and `content` are the two other spellings in the wild. The
+ * FIRST of them present with a value that is not `null` is the inline content,
+ * so a part spelling it twice reads one way in both kernels.
+ *
+ * A key present with `null` is an ABSENT inline value, on A14's ruling that an
+ * absent value and one written as `null` name one thing. That matters: an A2A
+ * `FilePart` with `uri` set carries `"bytes": null`, and so does proto3 JSON,
+ * and reading those as inline made a conformant DESCRIPTOR part uncheckable
+ * (proof#156 gate). They fall through to the descriptor rule, which is what
+ * they are.
+ */
+export declare const INLINE_BYTES_KEYS: readonly ["bytes", "content", "data"];
+/**
+ * The largest integer a double carries exactly, the same bound section 4.1 puts
+ * on `event.sequence`: a `content_length` outside it is a value the two kernels
+ * would read as two numbers.
+ */
+export declare const MAX_SAFE_INTEGER: number;
+/**
+ * One byte string a receiver holds, and the part it holds it for.
+ *
+ * `part` is an INDEX into the message's `parts` array. It is an index rather
+ * than a content hash on purpose: keying the supply by the value the check is
+ * about to grade would mean a receiver could only supply bytes it had already
+ * agreed with, which is the whole defect stated backwards.
+ */
+export interface SuppliedPart {
+    part: unknown;
+    data: Uint8Array;
+}
+/** What the receiver reports for one part of the message, one per part. */
+export interface PartReading {
+    index: number;
+    result: string;
+}
+/**
+ * A caller error. Nothing is written, nothing is signed, no record made.
+ *
+ * `part` is the part index where the refusal is about a part of the message,
+ * and `entry` is the POSITION of the offending supplied entry in the sequence
+ * the caller passed. The position is recorded rather than the value the caller
+ * named, so a caller that names a part with a float or a string cannot make two
+ * kernels serialize one reading two ways.
+ */
+export interface Refusal {
+    name: string;
+    part: number | null;
+    entry: number | null;
+}
+/**
+ * Something worth reporting that refuses nothing and checks nothing out. Same
+ * shape as a `Refusal` and carried in its own list, so no caller can read a
+ * note as a refusal by looking only at a name.
+ */
+export type Note = Refusal;
+/**
+ * The message a receiver commits to, and everything it found on the way.
+ *
+ * `heldMessage` is ALWAYS the message the receiver commits to and is never
+ * null: a refusal is scoped to the supply it is about and never denies the
+ * receiver a record (proof#156 gate). The caller commits `event.message_hash`
+ * as SHA-256 over its JCS (RFC 8785) canonical bytes, which is the rule section
+ * 4.1 already states and the reason this module does not hash anything itself.
+ *
+ * `messageResults` carries the message-level named results, in
+ * `MESSAGE_RESULT_ORDER`. It is empty for every message whose shape the rule
+ * reads.
+ *
+ * `substituted` carries the indexes of the parts whose descriptor the receiver
+ * replaced with the held bytes' own hash and length. It is empty for an honest
+ * hand-off, and where it is not empty the receiving side writes
+ * `outcome: "rejected"`.
+ */
+export interface HeldMessage {
+    parts: PartReading[];
+    messageResults: string[];
+    refusals: Refusal[];
+    notes: Note[];
+    heldMessage: unknown | null;
+    substituted: number[];
+}
+/**
+ * Whether this part is one this rule CHECKS against bytes travelling BESIDE the
+ * message: a conformant descriptor part. Exactly the three conditions section
+ * 4.1 states, in the order that keeps inline content out. An INLINE part is
+ * accepted and committed by the message itself (proof#157), so there is nothing
+ * here for supplied bytes to be checked against and this answers `false`.
+ */
+export declare function isFilePart(part: unknown): boolean;
+/**
+ * What a receiver commits to, given the message and the bytes it holds.
+ *
+ * `supplied` is the bytes the receiver actually holds, each named by the index
+ * of the part it belongs to. An empty list is the common case, a receiver that
+ * holds no part's bytes, and it reads exactly as section 4.1 read before this
+ * amendment: every file part is `PART_UNCHECKED` and the message a receiver
+ * commits to is the message it was given.
+ *
+ * Where a part's bytes hash to something other than its `content_hash`, or
+ * where their count is not its `content_length`, the returned `heldMessage`
+ * carries that part's `content_hash` and `content_length` replaced by the held
+ * bytes' own. The receiver commits `event.message_hash` over THAT, so its
+ * record and the sender's disagree and the pair fails on `message_hash`.
+ *
+ * A refusal is scoped to the supplied entry it is about: the part it names is
+ * not checked and not substituted, every other part reads as it would have, and
+ * `heldMessage` is returned either way. Nothing a caller or a sender can do
+ * denies the receiver a record.
+ */
+export declare function commitHeldMessage(message: unknown, supplied?: readonly SuppliedPart[]): Promise<HeldMessage>;
+/**
+ * The parts the receiver HELD bytes for and did NOT check.
+ *
+ * The gap between "nothing was substituted" and "every part is clean", named
+ * so a caller does not have to re-derive it from the refusal list (proof#156
+ * second gate, F5). A part is in here where a refusal NAMES it and its reading
+ * is one of `HELD_UNCHECKED_RESULTS`: the receiver had bytes for that part,
+ * the rule declined to grade them, and NOTHING about that reaches the
+ * committed record.
+ *
+ * THE RULE, in one sentence, because a filter is not a rule. A part is in here
+ * where the receiver held bytes for it AND the message itself does not commit
+ * its content. `PART_UNCHECKED` is a refused supply;
+ * `PART_MALFORMED_DESCRIPTOR` is a part whose content travels BESIDE the
+ * message under a claim no receiver can use, so the receiver's bytes are
+ * exactly as ungraded and the record says as little. The first cut of this
+ * function omitted the second, which the third gate measured: a `kind: "file"`
+ * part with a non-conformant `content_hash` or `content_length`, bytes held,
+ * read `[]` here, so a caller following the rule this module prescribes wrote
+ * `accepted` over a part it held bytes for and never checked. That is the
+ * class the mechanism exists to close, and Phil named it in proof#162's
+ * ratification as the gap that decision inherits unless it is closed here.
+ *
+ * Three results are excluded ON PURPOSE. An inline part (`PART_INLINE_BYTES`,
+ * `PART_INLINE_MISMATCHED`) and a non-file part (`PART_NOT_A_FILE`) carry
+ * their content INSIDE the message, and `message_hash` commits it on both
+ * sides: bytes supplied beside one of those grade nothing and hide nothing,
+ * because a reader of either pack reads the content itself. Naming them would
+ * fire the caller's obligation on parts the swapped-bytes attack cannot reach
+ * at all.
+ *
+ * Why it is worth a function rather than a note. Delivering a tampered copy of
+ * a part alone is `part_mismatched`, is substituted, and fails the pair on
+ * `message_hash`. Delivering the tampered copy AND the true one is
+ * `conflicting_part_bytes`, is never substituted, and the pair VERIFIES, so
+ * adding data suppresses detection and the only trace is a refusal the
+ * receiving side publishes at its own discretion.
+ *
+ * NOT the same as "this part reads `PART_UNCHECKED`". A receiver that holds no
+ * bytes at all reads every file part that way, and that is the COMMON CASE,
+ * unchanged by A18 and not a reason to withhold `accepted`. Only a part whose
+ * bytes the receiver actually held and could not grade is in here.
+ *
+ * What this does NOT do: it cannot stop a caller writing `accepted` anyway.
+ * This module reads and does not write the record. proof#162 ratified what the
+ * record layer does instead (Phil, 2026-09-22): `accepted` keeps its meaning
+ * and the COUNT of these parts rides in an additive `context` key, REQUIRED
+ * when it is not zero, enforced against SDKs through conformance vectors. So a
+ * part missing from this list is a part no record built on that rule will ever
+ * mention.
+ */
+export declare function uncheckedHeldParts(reading: HeldMessage): number[];