@sanning/proof 0.19.1 → 0.20.0

package/src/side-content.ts

@@ -1,69 +1,37 @@
-// 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).
 
 /** 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;
 }
 
 const ABSENT: SideEntry = { 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: SideContentMap | null | undefined,
   eventId: string,
@@ -79,7 +47,7 @@ export function sideContentEntry(
   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: SideContentMap | null | undefined,
   eventId: string,
@@ -88,8 +56,8 @@ export function hasSideContent(
 }
 
 /**
- * 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: SideContentMap | null | undefined): string[] {
   if (content === undefined || content === null) return [];
@@ -98,21 +66,10 @@ export function sideContentKeys(content: SideContentMap | null | undefined): str
 }
 
 /**
- * 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: unknown): boolean {
   return content !== undefined && content !== null;

package/src/types.ts

@@ -1,7 +1,6 @@
-// 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).
+// 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.
 
 export interface Subject {
   type: string;
@@ -16,62 +15,82 @@ export interface Envelope {
   signed_at: string;
   public_key: string;
   signature: string;
-  // Inline-binding profiles (envelope-spec §3) carry the committed payload in
-  // the envelope; external-commitment profiles do not — the caller supplies
-  // the committed bytes to bind (verifyEnvelope's payloadBytes option).
+  // Inline-binding profiles (envelope-spec §3) carry the committed payload;
+  // external-commitment profiles do not, and the caller supplies the bytes.
   payload?: Record<string, unknown>;
-  // Disclosure fields (§3.1): present on Promoted profiles, absent on Minimal
-  // ones (they live inside the committed payload instead).
+  // Disclosure fields (§3.1): on Promoted profiles, inside the payload on Minimal ones.
   event_type?: string;
   subject?: Subject;
   previous_hash?: string;
-  // Optional v1.1+ fields: dev/production marking inside the signed scope,
-  // and the external-commitment locator.
+  // Optional: dev/production marking inside the signed scope, and the external-commitment locator.
   environment?: string;
   payload_ref?: string;
-  // Reserved, default-absent (envelope-spec §7.1): countersignatures over the
-  // same skeleton. OUTSIDE the signed scope — the primary signature covers the
-  // envelope minus `signature` AND minus `co_signatures`, so a countersignature
-  // can be added without invalidating the primary. Absence implies a single
-  // signer and MUST NOT be treated as a failure.
+  // Reserved (envelope-spec §7.1): countersignatures, outside the signed scope.
+  // The primary signature covers the envelope minus `signature` and
+  // `co_signatures`. Absence implies a single signer and MUST NOT be a failure.
   co_signatures?: unknown[];
 }
 
 // Which payload field a matched content hash came from. tamper_detected commits
-// to both the tampered ("observed") bytes and the known-good ("baseline") bytes.
+// to both the tampered ("observed") and known-good ("baseline") bytes.
 export type ContentRole = "asset" | "baseline" | "observed";
 
 export interface VerifyOptions {
-  // External commitment (§3): the committed canonical payload bytes. When
-  // supplied, SHA-256(payloadBytes) must equal the envelope's payload_hash.
+  // External commitment (§3): the committed canonical payload bytes. SHA-256 of them must equal `payload_hash`.
   payloadBytes?: Uint8Array;
-  // Content bind: the caller's own hash of an artifact (e.g. the in-browser
-  // hash of a user's file) to match against the hashes the envelope commits to.
+  // Content bind: the caller's own hash of an artifact, matched against the hashes the envelope commits to.
   expectedContentHash?: string;
-  // NARROWS the accept-set for this call and never widens it: the set used is
-  // `ACCEPTED_SPEC_MAJORS` intersected with this list, so a caller cannot
-  // admit a profile this kernel does not. The Python twin is
-  // `accepted_spec_majors` (P-10, 0.13.0).
+  // Narrows the accept-set for this call, never widens it: `ACCEPTED_SPEC_MAJORS`
+  // intersected with this list.
   acceptedSpecMajors?: readonly string[];
 }
 
 export interface VerificationResult {
-  // Cryptographic validity: spec_version ok, Ed25519 signature ok, and the
-  // payload binding did not FAIL. payloadHashOk === null (binding not
-  // checkable: external-commitment envelope, no payloadBytes supplied) does
-  // not fail ok — that is the "signature-valid, semantics-undetermined"
-  // outcome of envelope-spec §3.1/§6.2.
+  // Spec_version ok, Ed25519 signature ok, and the payload binding did not fail.
+  // `payloadHashOk === null` (no binding material) does not fail `ok`: the
+  // "signature-valid, semantics-undetermined" outcome of envelope-spec §3.1, §6 item 2.
   ok: boolean;
   specVersionOk: boolean;
-  // true: binding checked and matches (inline recompute, external bytes, or
-  // both when both were available). false: a check failed, or payload_hash is
-  // missing/malformed. null: no binding material to check against.
+  // true: binding checked and matches. false: a check failed, or payload_hash is
+  // missing or malformed. null: no binding material to check against.
   payloadHashOk: boolean | null;
   signatureOk: boolean;
-  // Content bind: did the hash the caller supplied match a hash this envelope
-  // commits to? null when no hash was supplied. This is the check that defeats
-  // a lying gateway — the tag only got us to the candidate.
+  // Content bind: whether the supplied hash matches a hash the envelope commits
+  // to; null when none was supplied. This defeats a lying gateway: the tag only
+  // gets to the candidate.
   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 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",
+] as const;
+export type EnvelopeFault = (typeof ENVELOPE_FAULTS)[number];