@sanning/proof 0.19.1 → 0.20.0

package/dist/side-content.d.ts

@@ -1,36 +1,25 @@
 /** A caller-built map of disclosed bytes, in either shape it can take. */
 export type SideContentMap = Readonly<Record<string, Uint8Array | string | undefined>> | ReadonlyMap<string, Uint8Array | string | undefined>;
-/** One event's entry, and — separately — whether an entry existed at all. */
+/** One event's entry, and separately whether an entry existed at all. */
 export interface SideEntry {
-    /** An entry EXISTS for this id. Never inferred from the value. */
+    /** Whether an entry exists for this id. Never inferred from the value. */
     offered: boolean;
-    /** What it held, read without ever invoking an accessor. */
+    /** What it held, read without invoking an accessor. */
     value: Uint8Array | string | undefined;
 }
-/** Look up one event's out-of-band disclosure. The rule, stated once. */
+/** Look up one event's out-of-band disclosure. */
 export declare function sideContentEntry(content: SideContentMap | null | undefined, eventId: string): SideEntry;
-/** Whether the map carries a usable entry for this id. The same rule. */
+/** Whether the map carries an entry for this id. */
 export declare function hasSideContent(content: SideContentMap | null | undefined, eventId: string): boolean;
 /**
- * The ids the map actually carries — the same rule applied to every key, so a
- * key that is not an entry cannot be reported as surplus disclosure either.
+ * The ids the map carries, by the same rule, so a key that is not an entry is
+ * never reported as surplus disclosure.
  */
 export declare function sideContentKeys(content: SideContentMap | null | undefined): string[];
 /**
- * Whether an event's IN-BODY `events[].content` field is a disclosure.
- *
- * The other half of the same question, and it broke the same way. `content`
- * is an OPTIONAL field, so `null` is how a producer's serializer spells its
- * absence — Go's `json.Marshal` on a nil pointer without `omitempty`, Python's
- * `json.dumps(None)`. A bare `!== undefined` marks such an event OFFERED while
- * no bytes are selected (only a `string` decodes), and the kernel then splits
- * against itself: `verifyEvidenceBundle` reports `contentOk: null` and rolls up
- * VERIFIED, while `disclosedContent` reports FAILED — "content was disclosed
- * for this event but is not a decodable lowercase-hex string". One kernel, one
- * bundle, two verdicts, reachable from any conforming producer.
- *
- * Non-nullish and not a string — a number, an object, a hex string that is not
- * hex — remains a real, unusable disclosure and stays a finding, exactly as on
- * the side-input path.
+ * Whether an event's in-body `events[].content` is a disclosure: anything
+ * non-nullish. `null` is how serializers spell an absent optional field, and
+ * treating it as offered would split the bundle verdict from
+ * `disclosedContent`.
  */
 export declare function inBodyContentOffered(content: unknown): boolean;

package/dist/side-content.js

@@ -1,54 +1,22 @@
-// ONE answer to "did the holder actually supply bytes for this event_id?"
+// The one answer to "did the holder supply bytes for this event_id?", shared by
+// the verifier and the grader so the two cannot disagree.
 //
-// WHY THIS IS A MODULE AND NOT TWO PRIVATE HELPERS.
-// The kernel asks that question in two places — the verifier, deciding whether
-// an event's content was offered at all (`evidence.ts`), and the grader,
-// accounting which records a pack disclosed (`grading.ts`). It had two answers.
-// On one and the same content map the grader said PRESENT while the verifier
-// said nothing was offered, so `gradePack` returned `incomplete` with ZERO
-// causes: a surface saying "incomplete" and unable to say why. That is exactly
-// the outcome `grading.ts`'s own comment claims was removed, reappearing
-// because the fix landed on one of the two definitions.
+// An entry exists when the map carries an own, enumerable, data property (or
+// `Map` key) holding something other than `null`/`undefined`:
 //
-// Two implementations of one verification rule is the defect `grading.ts` was
-// extracted into the kernel to end. A rule stated once cannot drift; a rule
-// stated twice already has.
+//   own          `event_id` is producer-chosen, and `constructor` or `__proto__`
+//                must not resolve through the prototype chain.
+//   enumerable   what `Object.keys` shows is the map the caller built.
+//   data         an accessor is never invoked: a getter can throw, and a
+//                verifier does not raise on adversarial input.
+//   non-nullish  `undefined` is how `Object.fromEntries` spells "no entry".
+//                Anything else, even unusable, is a disclosure and a finding.
 //
-// ── THE RULE ────────────────────────────────────────────────────────────────
-//
-// An entry exists for `eventId` when the map carries an OWN, ENUMERABLE, DATA
-// property (or `Map` key) holding something other than `null`/`undefined`.
-// This is the STRICTER of the two definitions that were in the kernel — the
-// verifier's — and it is stricter on purpose. Every clause was paid for:
-//
-//   own         — an `event_id` is PRODUCER-CHOSEN, and every key on
-//                 `Object.prototype` is a legal one: `constructor`,
-//                 `toString`, `valueOf`, `hasOwnProperty`, `isPrototypeOf`,
-//                 `propertyIsEnumerable`, `toLocaleString`, `__proto__`. An
-//                 indexed lookup walks the prototype chain and resolves every
-//                 one of them, so absent evidence read as good evidence.
-//   enumerable  — what a caller means by "the map I built" is what
-//                 `Object.keys` shows; nothing hidden behind it counts.
-//   data        — an accessor is NEVER invoked. A getter can throw, and this
-//                 kernel's standing rule is that a verifier does not raise on
-//                 adversarial input. Not hypothetical: a plain-object map that
-//                 has taken a `__proto__` write carries `Uint8Array.prototype`
-//                 as its prototype, and reading `byteLength`, `length`,
-//                 `buffer` or `byteOffset` off a plain object through it throws
-//                 a TypeError. Reading a descriptor cannot.
-//   non-nullish — `{ [id]: undefined }` is how `Object.fromEntries` and friends
-//                 spell "no entry", and `new Map([[id, undefined]])` is the
-//                 same statement in the other shape. Anything else non-nullish
-//                 — a number, an object, a string that is not hex — IS a real,
-//                 unusable disclosure and stays a finding.
-//
-// `offered` is what separates "nothing was disclosed" (undetermined) from
-// "something was disclosed and is unusable" (a finding), and absent disclosure
-// is undetermined, not failed (evidence-bundle.md §5.1). So it is returned
-// SEPARATELY from the value and is never inferred from it: `value !== undefined`
-// is the conflation this module exists to remove, in both directions.
+// `offered` is returned separately from the value and never inferred from it:
+// nothing disclosed is undetermined, something unusable is a finding
+// (evidence-bundle.md §5.1).
 const ABSENT = { offered: false, value: undefined };
-/** Look up one event's out-of-band disclosure. The rule, stated once. */
+/** Look up one event's out-of-band disclosure. */
 export function sideContentEntry(content, eventId) {
     if (content === undefined || content === null)
         return ABSENT;
@@ -62,13 +30,13 @@ export function sideContentEntry(content, eventId) {
     const value = desc.value;
     return value === undefined || value === null ? ABSENT : { offered: true, value };
 }
-/** Whether the map carries a usable entry for this id. The same rule. */
+/** Whether the map carries an entry for this id. */
 export function hasSideContent(content, eventId) {
     return sideContentEntry(content, eventId).offered;
 }
 /**
- * The ids the map actually carries — the same rule applied to every key, so a
- * key that is not an entry cannot be reported as surplus disclosure either.
+ * The ids the map carries, by the same rule, so a key that is not an entry is
+ * never reported as surplus disclosure.
  */
 export function sideContentKeys(content) {
     if (content === undefined || content === null)
@@ -77,21 +45,10 @@ export function sideContentKeys(content) {
     return keys.filter((id) => hasSideContent(content, id));
 }
 /**
- * Whether an event's IN-BODY `events[].content` field is a disclosure.
- *
- * The other half of the same question, and it broke the same way. `content`
- * is an OPTIONAL field, so `null` is how a producer's serializer spells its
- * absence — Go's `json.Marshal` on a nil pointer without `omitempty`, Python's
- * `json.dumps(None)`. A bare `!== undefined` marks such an event OFFERED while
- * no bytes are selected (only a `string` decodes), and the kernel then splits
- * against itself: `verifyEvidenceBundle` reports `contentOk: null` and rolls up
- * VERIFIED, while `disclosedContent` reports FAILED — "content was disclosed
- * for this event but is not a decodable lowercase-hex string". One kernel, one
- * bundle, two verdicts, reachable from any conforming producer.
- *
- * Non-nullish and not a string — a number, an object, a hex string that is not
- * hex — remains a real, unusable disclosure and stays a finding, exactly as on
- * the side-input path.
+ * Whether an event's in-body `events[].content` is a disclosure: anything
+ * non-nullish. `null` is how serializers spell an absent optional field, and
+ * treating it as offered would split the bundle verdict from
+ * `disclosedContent`.
  */
 export function inBodyContentOffered(content) {
     return content !== undefined && content !== null;

package/dist/types.d.ts

@@ -32,4 +32,21 @@ export interface VerificationResult {
     contentHashOk: boolean | null;
     contentRole: ContentRole | null;
     errors: string[];
+    /**
+     * Why `ok` is false: the worst of `faults`, or `null` where `ok` is true or only the
+     * content bind failed. A caller maps each fault to a claim (`ENVELOPE_FAULT_KINDS`) rather
+     * than reading `ok` alone: a signature or a binding that fails disproves, a key or an
+     * envelope that cannot be read and a version this verifier does not know leave a claim not
+     * proven, and a field that breaks the format under a signature that holds is the
+     * producer's error.
+     */
+    fault: EnvelopeFault | null;
+    /**
+     * Every fault found, in `ENVELOPE_FAULTS` order. A fault that leaves one claim not proven
+     * never hides a disproof found beside it.
+     */
+    faults: EnvelopeFault[];
 }
+/** Why an envelope does not verify, worst first: the disproofs, then what is not proven. */
+export declare const ENVELOPE_FAULTS: readonly ["signature_failed", "payload_unbound", "nonconforming", "not_an_envelope", "key_unreadable", "spec_version_unknown"];
+export type EnvelopeFault = (typeof ENVELOPE_FAULTS)[number];

package/dist/types.js

@@ -1,5 +1,19 @@
-// Wire types for Sanning Verifiable Event Envelopes (sanning-io/proof
-// specs/envelope-spec.md). We model only the fields the verifier consumes;
-// unknown fields are preserved by structural typing (envelopes are verified
-// over their canonical bytes, not this interface).
-export {};
+// Wire types for Sanning Verifiable Event Envelopes (specs/envelope-spec.md).
+// Only the fields the verifier consumes are modelled; envelopes are verified
+// over their canonical bytes, not this interface.
+/** Why an envelope does not verify, worst first: the disproofs, then what is not proven. */
+export const ENVELOPE_FAULTS = [
+    // The Ed25519 signature does not hold.
+    "signature_failed",
+    // `payload_hash` is 64 hex characters that do not match the bytes it commits to.
+    "payload_unbound",
+    // The signature holds over a version this verifier knows, and a field breaks the
+    // envelope format (a missing `payload_hash` included).
+    "nonconforming",
+    // Not an object, or an object with none of the envelope's own members.
+    "not_an_envelope",
+    // `public_key` is not 64 hex characters: no signature can be checked.
+    "key_unreadable",
+    // A `spec_version` this verifier does not know.
+    "spec_version_unknown",
+];

package/dist/verifier.d.ts

@@ -1,144 +1,54 @@
-import type { ContentRole, Envelope, VerificationResult, VerifyOptions } from "./types.js";
+import type { ContentRole, Envelope, EnvelopeFault, VerificationResult, VerifyOptions } from "./types.js";
 export declare const ACCEPTED_SPEC_MAJORS: readonly string[];
 export declare const MAX_CANONICAL_DEPTH = 128;
 export declare function exceedsDepth(value: unknown, max: number): boolean;
 /**
- * The bytes an envelope's inline `payload` commits to: `JCS(payload)`. The ONE
- * place this is spelled: `verifyEnvelope` binds `payload_hash` against these
- * bytes, and the chain links rule 11 reads (`readChainLinks`) read an inline
- * record through them, so the binding rule and the linkage rule cannot
- * disagree about which bytes a record is. Throws where the payload cannot be
- * canonicalized. The twin is Python's `inline_payload_bytes`.
+ * The bytes an envelope's inline `payload` commits to: `JCS(payload)`. The one
+ * place this is defined, so payload binding and chain linkage agree on a
+ * record's bytes. Throws where the payload cannot be canonicalized.
  */
 export declare function inlinePayloadBytes(envelope: {
     payload: unknown;
 }): Uint8Array;
 export declare function jcs(value: unknown): string;
-/**
- * Read bytes that claim to be `jcs(value)` (RFC 8785), strictly. The Python
- * twin is `jcs_loads` in `src/sanning_proof/canonicalize.py`, and every site in
- * either kernel that reads bytes a producer signed goes through one of the two.
- *
- * ONE RULE, SPELLED OUT, BECAUSE TWO BUILT-INS ARE NOT ONE RULE. Five checks
- * carry it, none of them left to a decoder's defaults: strict UTF-8, no leading
- * byte-order mark, no non-finite literal (this kernel's `JSON.parse` rejects
- * `NaN`, `Infinity` and `-Infinity` natively, and Python names them in a
- * `parse_constant` hook), no object that repeats a member name
- * (`DuplicateKeyError`, proof#144), and no unpaired surrogate in the parsed
- * value.
- *
- * THE FOURTH CHECK IS NOT THE FIRST ONE TWICE. The strict decode refuses a
- * surrogate written as raw bytes; it cannot see one written as the ASCII
- * escape `\ud800`, which `JSON.parse` turns into a lone code unit AFTER the
- * decode has passed. `"c\ud800x"` is pure ASCII on the wire, so this reader
- * accepted it while its own text above said it does not, and one poisoned
- * record then deleted the Python kernel's whole chain reading (the gate on
- * proof#154). Both spellings are the same malformed record, and both are
- * refused here.
- *
- * `new TextDecoder()` alone is none of that. It replaces every invalid sequence
- * with U+FFFD and strips a BOM. Python's `json.loads(<bytes>)` is not it
- * either, in the opposite direction: CPython sniffs the encoding and decodes
- * with `errors="surrogatepass"`, so it strips a UTF-8 BOM, accepts a UTF-16 or
- * UTF-32 body, and passes a lone surrogate and a CESU-8 pair through. Both
- * defaults have shipped a split verdict on one pack: a raw `0x80` inside a
- * stamp body read `verified` here and `failed` there (gate 4), and then a
- * `BOM + JCS(record)` checkpoint read `verified` there and `mixed` here (gate
- * 5), both on proof#140. JCS is defined over UTF-8 and I-JSON (RFC 7493)
- * forbids a lone surrogate, so each of those inputs is MALFORMED rather than
- * another spelling of the same record.
- *
- * Throws for anything that is not conformant; every call site treats a throw as
- * "this reader cannot read these bytes" and names the check that failed.
- */
-/**
- * Bytes as strict UTF-8, a leading byte-order mark KEPT as a character.
- * `utf8_strict` in the Python twin's `canonicalize.py` is the same rule, and
- * `jcsParse` below performs the identical decode. Throws on bytes that are not
- * UTF-8.
- */
+/** Bytes as strict UTF-8, a leading byte-order mark kept as a character. Throws on invalid UTF-8. */
 export declare function utf8Strict(bytes: Uint8Array): string;
-export declare function jcsParse(bytes: Uint8Array): unknown;
 /**
- * Whether the bytes nest arrays and objects deeper than `max`, read from the
- * bytes before any parser sees them: the greatest number of `[` and `{` open
- * at once outside strings. A `"` opens a string and the next `"` no `\`
- * escapes closes it; a `]` or `}` outside a string closes one open level, if
- * one is open. Defined for every byte string, JSON or not. The Python twin is
- * `exceeds_text_depth` in `canonicalize.py`.
+ * Read bytes that claim to be `jcs(value)`, strictly: valid UTF-8, no leading
+ * BOM, no non-finite literal, no repeated member name, and no unpaired
+ * surrogate (including one written as a `\ud800` escape). Every site that reads
+ * bytes a producer signed goes through this or its Python twin `jcs_loads`, so
+ * the kernels cannot split on decoder defaults.
  *
- * On the bytes because a parser's own limit is its host's: CPython 3.10
- * stops near 1,000 levels, `JSON.parse` and CPython 3.13 read far deeper, Go's
- * decoder stops at 10,000 (enclave-attestation section 2.1).
- */
-export declare function exceedsTextDepth(bytes: Uint8Array, max: number): boolean;
-/**
- * Whether a parsed value holds a number no IEEE 754 double holds, at any
- * depth. `JSON.parse` reads `1e400`, and an integer of 400 digits, as
- * `Infinity`. Iterative: the value is a producer's. The Python twin is
- * `has_non_finite_number`.
+ * @throws When the bytes are not conformant.
  */
-export declare function hasNonFiniteNumber(value: unknown): boolean;
-/**
- * The deepest a JSON text an enclave reader parses may nest, and the depth
- * every kernel canonicalizes to (`MAX_CANONICAL_DEPTH`).
- */
-export declare const MAX_READ_DEPTH = 128;
-/**
- * `jcsParse`, within the reader limits of enclave-attestation section 2.1:
- * the bytes nest at most `MAX_READ_DEPTH` levels, checked on the bytes first,
- * and every number in the value is a finite double. Throws past either limit,
- * and wherever `jcsParse` throws. The Python twin is `jcs_loads_within_limits`.
- */
-export declare function jcsParseWithinLimits(bytes: Uint8Array): unknown;
+export declare function jcsParse(bytes: Uint8Array): unknown;
 /**
- * A JSON object that names one member twice (I-JSON, RFC 7493 section 2.3).
- * The Python twin is `DuplicateKey` in `canonicalize.py`, and the message is
- * the same kernel wording in both: `duplicate key ` and the name as
- * `renderKey` spells it.
- *
- * JCS (RFC 8785) is defined over I-JSON, and I-JSON forbids duplicate member
- * names, so bytes that repeat a name are MALFORMED rather than another spelling
- * of the last value. `JSON.parse` and Python's `json.loads` both keep the last
- * value and say nothing, which let a bundle carrying `"spec_version":"junk"`
- * before its real `spec_version` read `verified` in both kernels (proof#144).
+ * A JSON object that names one member twice. I-JSON (RFC 7493 §2.3) forbids it,
+ * so the bytes are malformed rather than a spelling of the last value.
  */
 export declare class DuplicateKeyError extends Error {
     readonly key: string;
     constructor(key: string);
 }
 /**
- * A member name as a quoted, pure-ASCII string, identically in both kernels
- * (`render_key` in the Python twin). Printable ASCII other than `"` and `\` is
- * kept; `"` and `\` are backslash-escaped; every other UTF-16 code unit is
- * `\uXXXX` in lower-case hex. A rendering longer than 64 characters is cut
- * there and `...` follows the closing quote.
+ * A member name as a quoted, pure-ASCII string, identical in both kernels.
+ * Printable ASCII is kept (`"` and `\` escaped), every other code unit is
+ * `\uXXXX`, and anything past 64 characters is cut with `...`.
  */
 export declare function renderKey(key: string): string;
 /**
- * `JSON.parse(text)`, refusing an object that repeats a member name. The Python
- * twin is `loads_refusing_duplicates` in `canonicalize.py`.
+ * `JSON.parse(text)`, refusing an object that repeats a member name. Parses
+ * first, so non-JSON fails as JSON, then rescans for repeats.
  *
- * `JSON.parse` cannot see a repeat, because it keeps the last value, so the
- * text is scanned once more AFTER it parsed. The parse runs first, so text
- * that is not JSON at all fails as JSON and never as a duplicate, as it does in
- * the Python twin. Throws `DuplicateKeyError`.
+ * @throws DuplicateKeyError
  */
 export declare function parseRefusingDuplicates(text: string): unknown;
 /**
- * The repeated member name to report for text `JSON.parse` has already
- * accepted, or `undefined` when no object repeats one.
- *
- * WHICH ONE, because both kernels must name the same one. Objects are checked
- * as they CLOSE, innermost first, which is the order Python's
- * `object_pairs_hook` sees them in; inside one object the name reported is the
- * first whose repeat comes earliest. Names compare after unescaping, so `"a"`
- * and `"\u0061"` are one name, as they are to both parsers.
- *
- * ITERATIVE, with an explicit stack, for the reason `rejectUnpairedSurrogates`
- * is: this walks bytes a producer wrote. It relies on the text being valid
- * JSON, which is why it runs only after `JSON.parse` succeeded: outside a
- * string, only `{`, `[`, `}`, `]`, `,` and `"` change what comes next.
+ * The repeated member name to report, or `undefined`. Objects are checked as
+ * they close, innermost first, matching Python's `object_pairs_hook`, so both
+ * kernels name the same key. Iterative, because the text is producer-written;
+ * runs only on text `JSON.parse` accepted.
  */
 export declare function firstDuplicateKey(text: string): string | undefined;
 export declare function specVersionSupported(specVersion: string, accepted?: readonly string[]): boolean;
@@ -148,3 +58,19 @@ export declare function contentHashes(env: Envelope): {
     hash: string;
 }[];
 export declare function verifyEnvelope(env: Envelope, options?: VerifyOptions): Promise<VerificationResult>;
+type FaultChecks = {
+    signatureOk: boolean;
+    payloadHashOk: boolean | null;
+    specVersionOk: boolean;
+    fieldsOk: boolean;
+};
+/**
+ * Every one of `ENVELOPE_FAULTS` that applies, in that order. Each is judged without the
+ * others: a key that cannot be read checks no signature, and still the bytes are checked
+ * against `payload_hash`. A field's form is judged only under a signature that holds over a
+ * version this verifier knows.
+ */
+export declare function envelopeFaults(env: unknown, checks: FaultChecks): EnvelopeFault[];
+/** The worst of `envelopeFaults`, or `null`. */
+export declare function envelopeFault(env: unknown, checks: FaultChecks): EnvelopeFault | null;
+export {};