@sanning/proof 0.19.1 → 0.20.0

package/dist/merkle.js

@@ -1,16 +1,10 @@
-// RFC 9162 binary Merkle tree — build, audit paths, inclusion verification.
+// RFC 9162 binary Merkle tree: build, audit paths, inclusion verification.
 //
-// A faithful port of the Go reference (the agent producer's pkg/merkle), in lockstep
-// with the Python kernel's sanning_proof.merkle. All hashing is SHA-256 with
-// RFC 9162 §2.1 domain separation: leaves prefixed 0x00, interior nodes 0x01.
-// A tree of n leaves splits into a left subtree of k leaves (the largest
-// power of two < n) and a right subtree of n−k — NOT the Bitcoin
-// duplicate-last-leaf variant, which produces different roots for
-// non-power-of-two leaf counts.
-//
-// The empty tree (zero leaves) hashes to SHA-256("") — EMPTY_TREE_ROOT_HEX.
-// Conformance is byte-for-byte against the 7 merkle-tree-* vectors of
-// test-vectors-v1.0 (test/conformance.test.ts).
+// SHA-256 with RFC 9162 §2.1 domain separation: leaves prefixed 0x00, interior
+// nodes 0x01. A tree of n leaves splits into a left subtree of k leaves (the
+// largest power of two < n) and a right subtree of n-k, not the Bitcoin
+// duplicate-last-leaf variant. The empty tree hashes to SHA-256("")
+// (EMPTY_TREE_ROOT_HEX).
 import { sha256Bytes } from "./crypto.js";
 export const EMPTY_TREE_ROOT_HEX = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
 // SHA-256(0x00 || leafBytes) per RFC 9162 §2.1.
@@ -25,9 +19,8 @@ export async function nodeHash(left, right) {
     buf.set(right, 1 + left.length);
     return sha256Bytes(buf);
 }
-// The RFC 9162 Merkle Tree Hash of already-hashed leaves. Callers pass leaf
-// hashes — the output of leafHash on each leaf's canonical bytes. Zero leaves
-// yields SHA-256("").
+// The RFC 9162 Merkle Tree Hash of already-hashed leaves (the output of
+// `leafHash`). Zero leaves yields SHA-256("").
 export async function merkleRoot(leafHashes) {
     const n = leafHashes.length;
     if (n === 0)
@@ -37,9 +30,8 @@ export async function merkleRoot(leafHashes) {
     const k = largestPow2LessThan(n);
     return nodeHash(await merkleRoot(leafHashes.slice(0, k)), await merkleRoot(leafHashes.slice(k)));
 }
-// The inclusion proof for the leaf at index m, per RFC 9162 §2.1.3: sibling
-// hashes bottom-up; empty for a single-leaf tree (the leaf hash itself is the
-// root). Throws RangeError when m is out of range.
+// The inclusion proof for the leaf at index m (RFC 9162 §2.1.3): sibling hashes
+// bottom-up, empty for a single-leaf tree. Throws RangeError when m is out of range.
 export async function auditPath(m, leafHashes) {
     if (!Number.isInteger(m) || m < 0 || m >= leafHashes.length) {
         throw new RangeError("merkle: leaf index out of range");
@@ -56,28 +48,24 @@ async function path(m, leafHashes) {
     }
     return [...(await path(m - k, leafHashes.slice(k))), await merkleRoot(leafHashes.slice(0, k))];
 }
-// Verify an RFC 9162 §2.1.3 inclusion proof. `leaf` is the leaf hash
-// (leafHash of the canonical leaf bytes); `path` is the audit path bottom-up;
-// `expectedRoot` is the merkleRoot committed by the checkpoint envelope.
-// True iff the path reconstructs the expected root. Never throws.
+// Verify an RFC 9162 §2.1.3 inclusion proof. `leaf` is the leaf hash, `path` the
+// audit path bottom-up, `expectedRoot` the root the checkpoint commits to. Never throws.
 export async function verifyInclusion(leaf, leafIndex, totalLeaves, auditPath, expectedRoot) {
     if (!Number.isInteger(leafIndex) || leafIndex < 0 || totalLeaves <= 0 || leafIndex >= totalLeaves) {
         return false;
     }
     if (totalLeaves === 1)
         return auditPath.length === 0 && bytesEqual(leaf, expectedRoot);
-    // Arithmetic, not bitwise: JavaScript's `&` and `>>=` truncate to 32 bits,
-    // so a tree past 2**31 leaves walked a different tree here than in the
-    // Python kernel, whose integers are unbounded. `% 2` and a halving floor
-    // are exact for every safe integer, and the stated index and count reach
-    // this walk as safe integers.
+    // Arithmetic, not bitwise: `&` and `>>=` truncate to 32 bits, so a tree past
+    // 2**31 leaves would walk a different tree. `% 2` and halving floor are exact
+    // for every safe integer.
     let fn = leafIndex;
     let sn = totalLeaves - 1;
     let r = leaf;
     const half = (v) => Math.floor(v / 2);
     for (const p of auditPath) {
         if (sn === 0)
-            return false; // path longer than the tree depth — malformed
+            return false; // path longer than the tree depth
         if (fn % 2 === 1 || fn === sn) {
             r = await nodeHash(p, r);
             if (fn % 2 === 0) {

package/dist/message-parts.d.ts

@@ -1,157 +1,71 @@
-/**
- * The result of a part whose supplied bytes hash to its `content_hash` AND
- * count to its `content_length`.
- */
+/** The supplied bytes match both `content_hash` and `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.
+ * The supplied bytes miss either value, and no respelling explains the digest.
+ * The held message 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.
- */
+/** Bytes not supplied, or the supply was refused. Not checked, and not clean. */
 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.
+ * A file part with its content inside the message, committed by
+ * `message_hash` itself. Nothing is hashed or substituted.
  */
 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.
+ * An inline part whose `content_hash` or `content_length` disagrees with its
+ * inline content. The raw UTF-8, base64 and hex readings are all tried, but one
+ * reading must satisfy every claim present. Nothing is substituted.
  */
 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.
+ * sender's defect, so it is named rather than refused.
  */
 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.
- */
+/** Any other part: ordinary JSON content, not checked by this rule. */
 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.
+ * Refusal of one supplied entry: it names no part, or a part this rule cannot
+ * check. Carries that part's index when the part exists, else only the entry
+ * position.
  */
 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.
- */
+/** Refusal: two different byte strings were supplied for one part. */
 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.
+ * Refusal of one supplied entry: the bytes miss the descriptor, but a base64
+ * or hex respelling in either direction hashes to it. That is a receiver's
+ * coding defect (an undecoded supply, or a decoded PEM, DER or JWT the sender
+ * committed as text), not a sender's tamper, so it must not produce a tamper
+ * record.
  */
 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.
+ * Message-level: `parts` is present, not null and not an array (proto3 JSON
+ * encodes a map this way). Named, not refused. A `parts` of `null` is absent.
  */
 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`.
- */
+/** Note, not a refusal: one part supplied more than once with identical 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.
- */
+/** The fixed order refusals are reported in. */
 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`.
- */
+/** The fixed order message-level results are reported in. */
 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. Settled at `bytes` alone (envelope-spec §4.1, A31, proof#163): that
- * is A2A's spelling, the one the wedge actually emits, and it is the only
- * inline spelling either reference kernel has read from a real producer.
- * `content` and `data` were added on inference rather than on an observed
- * wire shape, and sanning-io/anchor's `filePart()` and `file_part()` SDK
- * helpers, the only producer this plane ships, confirm the inference was
- * wrong: both emit a descriptor part, `kind: "file"` plus `content_hash` and
- * `content_length`, and neither ever writes a `content` or `data` wire key
- * for inline bytes. None is A2A 1.0.0's either: its `Part` has no `kind` and
- * carries a file as `raw` or `url`, so a literal A2A part reads
- * `part_not_a_file` (envelope-spec §4.1, A19). The one key present with a
- * value that is not `null` is the inline content.
- *
- * 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: a
- * proto3 JSON encoder can write an unset field as `"bytes": null`, and reading
- * that as inline made a conformant DESCRIPTOR part uncheckable
- * (proof#156 gate). Such a part falls through to the descriptor rule, which is
- * what it is.
+ * The key that makes a part carry its content inline (envelope-spec §4.1).
+ * `bytes` is A2A's spelling. A key present with `null` is absent, so a proto3
+ * `"bytes": null` on a descriptor part still reads as a descriptor.
  */
 export declare const INLINE_BYTES_KEYS: readonly ["bytes"];
 /**
- * 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.
+ * The largest exactly representable integer, the bound §4.1 puts on
+ * `event.sequence`. A larger `content_length` is malformed.
  */
 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.
+ * A byte string the receiver holds, keyed by the index of its part. Keyed by
+ * index, not by hash, so a receiver can supply bytes that disagree.
  */
 export interface SuppliedPart {
     part: unknown;
@@ -163,13 +77,9 @@ export interface PartReading {
     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.
+ * A caller error. `part` is the part index where there is one; `entry` is the
+ * position of the supplied entry, recorded rather than the caller's value so
+ * every implementation serializes it the same way.
  */
 export interface Refusal {
     name: string;
@@ -177,28 +87,17 @@ export interface Refusal {
     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.
+ * Reported, but refuses nothing. Kept in its own list so a note is never read
+ * as a refusal by name alone.
  */
 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.
+ * What a receiver commits to, and what it found.
  *
- * `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"`.
+ * `heldMessage` is never null; the caller commits `event.message_hash` as
+ * SHA-256 over its JCS bytes. `messageResults` is in `MESSAGE_RESULT_ORDER`.
+ * `substituted` lists the parts replaced by held bytes; non-empty means the
+ * receiver writes `outcome: "rejected"`.
  */
 export interface HeldMessage {
     parts: PartReading[];
@@ -209,83 +108,28 @@ export interface HeldMessage {
     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`.
+ * Whether bytes beside the message are checked against this part: true only
+ * for a conformant descriptor part, never for an inline one.
  */
 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.
+ * `supplied` names each byte string by its part index. With none, every file
+ * part is `PART_UNCHECKED` and the held message is the message given. Where a
+ * part's bytes miss its hash or length, `heldMessage` carries the held bytes'
+ * own values for that part, so the pair fails on `message_hash`. A refusal is
+ * scoped to its entry; `heldMessage` is always returned.
  */
 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.
+ * The parts the receiver held bytes for and did not check: a refusal names the
+ * part and its result is in `HELD_UNCHECKED_RESULTS`, or the part is a URL part
+ * that reads `PART_NOT_A_FILE` and the refusal is `BYTES_FOR_UNKNOWN_PART`. A
+ * caller writes `accepted` only when this and `substituted` are both empty, and
+ * records the positions and their count when it is not zero.
  *
- * 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.
+ * Not the same as "reads `PART_UNCHECKED`": a receiver holding no bytes reads
+ * every file part that way, which is the common case.
  */
 export declare function uncheckedHeldParts(reading: HeldMessage): number[];