@sanning/proof 0.4.1 → 0.6.0

package/src/index.ts

@@ -51,9 +51,20 @@ export type { ContentRole, Envelope, Subject, VerificationResult, VerifyOptions
 // issuer-composed sanning.evidence.export/v1 body (specs/evidence-export.md) to
 // verifyExportBody (embedded RSA-PSS operator attestations + a recomputed §4
 // verdict object with per-gateway on-chain outcomes).
+//
+// `disclosedContent` is the INGEST half of the same path (evidence-bundle
+// §5.1). A received bundle carries its disclosed raw bytes as lowercase hex, so
+// materializing them was, until now, every consumer re-implementing the
+// encoding convention — and a consumer that copied the field VERBATIM wrote
+// files that failed verification on genuine evidence. This hands back DECODED
+// bytes, and only for events whose verification bound them to the committed
+// content_hash. Additive; verifyEvidenceBundle's behavior is unchanged.
 export {
   ANCHOR_TRACE_BODY_TYPE,
+  ANCHOR_TRACE_BODY_TYPE_V1,
+  ANCHOR_TRACE_BODY_TYPES,
   EXPORT_BODY_TYPE,
+  disclosedContent,
   recomputeExportVerdict,
   verifyEvidenceBundle,
 } from "./evidence.js";
@@ -64,6 +75,9 @@ export type {
   AttestationResult,
   CheckpointResult,
   ComposeVerdictResult,
+  DisclosedContentResult,
+  DisclosedEventContent,
+  DisclosureStatus,
   EvidenceBundle,
   EvidenceBundleResult,
   EvidenceIssuer,
@@ -75,7 +89,9 @@ export type {
   OnChainOutcome,
   OnChainResult,
   PerGatewayOutcome,
+  AnchorRef,
   TraceCheckpoint,
+  TraceCheckpointV1,
   TraceEvent,
   TraceInclusion,
   VerdictAttestation,
@@ -87,6 +103,39 @@ export type {
   VerifyEvidenceOptions,
 } from "./evidence.js";
 
+// Pack grading (src/grading.ts): what a verification SURFACE may claim about a
+// pack — the signed bundle PLUS whatever disclosed bytes travelled beside it.
+//
+// The rule is already normative in evidence-bundle.md §5.1 (absent disclosure is
+// undetermined, not failed) and §6 (no status ever means "safe"); what the
+// surfaces added on top was a sharper word for undetermined and an account of
+// what the pack failed to disclose. It lived twice, in two repos and two
+// languages, and the two derivations had already diverged once. It lives here.
+//
+// Pure — data in, data out, no I/O, so the kernel's scope boundary
+// (specs/architecture.md §3) is unchanged. `vectors/pack-grading.json` is the
+// conformance statement of the rule and ships in the published tarball, so a
+// consumer that cannot yet import `gradePack` can vendor the table, hold its own
+// derivation to it, and diff its copy against ours. Additive — no existing
+// export changes.
+export {
+  accountDisclosure,
+  completenessNotes,
+  gradeCauses,
+  gradePack,
+  renderCause,
+  signedLeafCount,
+} from "./grading.js";
+export type {
+  CompletenessNote,
+  DisclosureAccount,
+  GradeInput,
+  PackGrade,
+  PackGradeCause,
+  PackGradeCauseKind,
+  PackVerdict,
+} from "./grading.js";
+
 // The `proof export` composer (specs/evidence-export.md §5, phase 2): produce a
 // signed, offline-verifiable sanning.evidence.export/v1 artifact from a source
 // anchor-trace bundle + operator attestations + an exporter Ed25519 key. The

package/src/side-content.ts

@@ -0,0 +1,119 @@
+// ONE answer to "did the holder actually supply bytes for this event_id?"
+//
+// 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.
+//
+// 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.
+//
+// ── 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.
+
+/** 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. */
+export interface SideEntry {
+  /** An entry EXISTS for this id. Never inferred from the value. */
+  offered: boolean;
+  /** What it held, read without ever 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. */
+export function sideContentEntry(
+  content: SideContentMap | null | undefined,
+  eventId: string,
+): SideEntry {
+  if (content === undefined || content === null) return ABSENT;
+  if (content instanceof Map) {
+    const value = content.get(eventId);
+    return value === undefined || value === null ? ABSENT : { offered: true, value };
+  }
+  const desc = Object.getOwnPropertyDescriptor(content, eventId);
+  if (desc === undefined || !desc.enumerable || !("value" in desc)) return ABSENT;
+  const value = desc.value as Uint8Array | string | undefined;
+  return value === undefined || value === null ? ABSENT : { offered: true, value };
+}
+
+/** Whether the map carries a usable entry for this id. The same rule. */
+export function hasSideContent(
+  content: SideContentMap | null | undefined,
+  eventId: string,
+): boolean {
+  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.
+ */
+export function sideContentKeys(content: SideContentMap | null | undefined): string[] {
+  if (content === undefined || content === null) return [];
+  const keys = content instanceof Map ? [...content.keys()] : Object.keys(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.
+ */
+export function inBodyContentOffered(content: unknown): boolean {
+  return content !== undefined && content !== null;
+}

package/vectors/README.md

@@ -0,0 +1,66 @@
+# `vectors/` — conformance tables that ship to consumers
+
+Unlike [`../../test-vectors/`](../../test-vectors/) — the tagged, vendored corpus
+for the kernel primitives — everything here is **inside the published package**
+(`files: ["vectors", …]`) and reaches downstream surfaces through npm.
+
+That distinction is the whole point. A rule that consumers must agree with needs
+a statement they can *fetch*, not one they have to be trusted to have copied
+correctly.
+
+## `pack-grading.json`
+
+The rule that decides whether a **pack** — a signed bundle plus whatever
+disclosed bytes travelled beside it — is `verified`, `failed` or `incomplete`.
+Implemented by [`../src/grading.ts`](../src/grading.ts) and asserted against this
+table by [`../test/grading.test.ts`](../test/grading.test.ts).
+
+**If an implementation disagrees with this table, the implementation is wrong.**
+
+### For a consumer that can import the kernel
+
+Don't vendor anything. Call `gradePack`:
+
+```ts
+import { accountDisclosure, completenessNotes, gradePack, verifyEvidenceBundle } from "@sanning/proof"
+
+const result  = await verifyEvidenceBundle(bundle, { content })
+const account = accountDisclosure(bundle, content)
+const grade   = gradePack(result, account, completenessNotes(bundle))
+```
+
+One implementation, no table to keep in step, no drift to guard against.
+
+### For a consumer that cannot yet
+
+An older pinned kernel, another language, a surface that adapts a result from
+somewhere else. Then, and only then:
+
+1. **Vendor this file byte-for-byte.** Not "equivalent" — identical. A vendored
+   copy that is not byte-identical to this one is a defect, not a variant.
+2. **Assert your derivation against it** in your own suite, so an implementation
+   that drifts from the rule goes red in your repo.
+3. **Run a drift check in CI** that compares your copy against the copy in
+   `node_modules/@sanning/proof/vectors/pack-grading.json` and fails on any
+   difference — *and fails when it cannot find a copy to compare against.* A
+   drift check that skips when its source is missing is not a check.
+
+Step 3 is the one people skip, and it is the one that matters. Steps 1 and 2
+catch an implementation drifting from its own table. Only step 3 catches the
+table itself being edited on one side — which is the failure that actually
+happened, and the reason this file moved here.
+
+### Shape
+
+| Key | Meaning |
+|---|---|
+| `ruleVersion` | Bumped when a case's expectation changes **or a case is added**. An implementation asserts the version it was written against, so a table it does not understand fails loudly rather than passing vacuously. Currently **2**. |
+| `kernelEventClasses` | The four per-event outcome classes a verification result can carry, named so a case can be written as counts rather than as a hand-built bundle. |
+| `cases[].kernel` | The verification result to grade, as class counts. |
+| `cases[].logs` | The disclosure account: how many records the bundle presents, and how many disclosed usable bytes. |
+| `cases[].omissions` | Completeness notes — a checkpoint's signed `leaf_count` against the records the pack presents for it. |
+| `cases[].expect` | The verdict, the three counts, and how many causes the grade must carry. |
+
+Nothing in a case names a transport. A directory read and a browser drop produce
+the same account and must produce the same verdict; a table that encoded one
+surface's mechanism would let the other one drift while staying green.

package/vectors/pack-grading.json

@@ -0,0 +1,136 @@
+{
+  "rule": "pack-grading",
+  "ruleVersion": 2,
+  "statement": "What a verification surface may CLAIM about a pack it was handed. verified is reachable ONLY when every record's own bytes bound to its own commitment and nothing is missing, unreadable, surplus or omitted. Absent or unreadable evidence is incomplete (UNKNOWN), never failed and never verified. A hard kernel verdict wins: malformed > failed > incomplete > the kernel's own headline.",
+  "home": "@sanning/proof — ts/vectors/pack-grading.json. This file is the RULE, not a test fixture of one implementation. The kernel implements it in ts/src/grading.ts and is held to it by ts/test/grading.test.ts.",
+  "consumers": "A surface that grades packs SHOULD call the kernel's gradePack rather than derive the rule again. A surface that cannot yet (an older pinned kernel, another language) vendors this file byte-for-byte, asserts its own derivation against it, and runs a drift check that compares its copy against the copy shipped in the @sanning/proof tarball at vectors/pack-grading.json. A vendored copy that is not byte-identical to this one is a defect, not a variant.",
+  "howToUse": "Adapt a kernel verification result and a disclosure account into the shapes below, call gradePack, and assert the expectations. `kernel` gives the per-event outcome classes the kernel returns; `logs` gives the account of which records disclosed bytes; `omissions` gives the signed-leaf_count completeness notes. Nothing here depends on how the bytes were transported — a directory read and a browser drop produce the same account and must produce the same verdict.",
+  "kernelEventClasses": {
+    "okBound": "{ ok: true, contentOk: true } — the record's own bytes hashed to its own commitment",
+    "okUnknown": "{ ok: true, contentOk: null } — structurally fine, but no bytes were disclosed",
+    "mismatched": "{ ok: false, contentOk: false } — the bytes disagree with the commitment",
+    "brokenNoContent": "{ ok: false, contentOk: null } — the record itself does not verify"
+  },
+  "cases": [
+    {
+      "id": "clean-pack",
+      "why": "a real, untouched pack: every record's own bytes bound to its own commitment",
+      "kernel": { "status": "verified", "okBound": 26, "okUnknown": 0, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 26, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "expect": { "verdict": "verified", "recordsVerified": 26, "recordsFailed": 0, "recordsUndetermined": 0, "causeCount": 0 }
+    },
+    {
+      "id": "one-log-tampered",
+      "why": "the scripted decision-word tamper — one record's bytes disagree",
+      "kernel": { "status": "failed", "okBound": 25, "okUnknown": 0, "mismatched": 1, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 26, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "expect": { "verdict": "failed", "recordsVerified": 25, "recordsFailed": 1, "recordsUndetermined": 0, "causeCount": 0 }
+    },
+    {
+      "id": "two-logs-swapped",
+      "why": "the case a set-membership check passes: both digests are still in the set, but each is now bound to the wrong record",
+      "kernel": { "status": "failed", "okBound": 24, "okUnknown": 0, "mismatched": 2, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 26, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "expect": { "verdict": "failed", "recordsVerified": 24, "recordsFailed": 2, "recordsUndetermined": 0, "causeCount": 0 }
+    },
+    {
+      "id": "one-log-deleted",
+      "why": "absent bytes are UNKNOWN — never verified, never failed (P-10)",
+      "kernel": { "status": "verified", "okBound": 25, "okUnknown": 1, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 25, "missing": 1, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "expect": { "verdict": "incomplete", "recordsVerified": 25, "recordsFailed": 0, "recordsUndetermined": 1, "causeCount": 1 }
+    },
+    {
+      "id": "every-log-deleted",
+      "why": "the silent-catch regression: zero bytes hashed must never read as a verified pack",
+      "kernel": { "status": "verified", "okBound": 0, "okUnknown": 26, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 0, "missing": 26, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "expect": { "verdict": "incomplete", "recordsVerified": 0, "recordsFailed": 0, "recordsUndetermined": 26, "causeCount": 1 }
+    },
+    {
+      "id": "one-log-unreadable",
+      "why": "a file we could not read is our fault, not the record's — UNKNOWN",
+      "kernel": { "status": "verified", "okBound": 25, "okUnknown": 1, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 25, "missing": 0, "unreadable": 1, "extra": 0 },
+      "omissions": [],
+      "expect": { "verdict": "incomplete", "recordsVerified": 25, "recordsFailed": 0, "recordsUndetermined": 1, "causeCount": 1 }
+    },
+    {
+      "id": "unaccounted-file",
+      "why": "a log no record in the bundle accounts for: the pack is not the pack it claims to be",
+      "kernel": { "status": "verified", "okBound": 26, "okUnknown": 0, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 26, "missing": 0, "unreadable": 0, "extra": 1 },
+      "omissions": [],
+      "expect": { "verdict": "incomplete", "recordsVerified": 26, "recordsFailed": 0, "recordsUndetermined": 0, "causeCount": 1 }
+    },
+    {
+      "id": "records-omitted",
+      "why": "every surviving record verifies perfectly; only the checkpoint's signed leaf_count sees the gap",
+      "kernel": { "status": "verified", "okBound": 24, "okUnknown": 0, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 24, "present": 24, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [{ "kind": "omitted", "checkpointRef": "TX", "signed": 26, "presented": 24 }],
+      "expect": { "verdict": "incomplete", "recordsVerified": 24, "recordsFailed": 0, "recordsUndetermined": 0, "causeCount": 1 }
+    },
+    {
+      "id": "records-surplus",
+      "why": "more records than the signed tree accounts for is equally not-verified",
+      "kernel": { "status": "verified", "okBound": 26, "okUnknown": 0, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 26, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [{ "kind": "surplus", "checkpointRef": "TX", "signed": 24, "presented": 26 }],
+      "expect": { "verdict": "incomplete", "recordsVerified": 26, "recordsFailed": 0, "recordsUndetermined": 0, "causeCount": 1 }
+    },
+    {
+      "id": "leaf-count-unreadable",
+      "why": "a completeness check we could not run is UNKNOWN, not a pass",
+      "kernel": { "status": "verified", "okBound": 26, "okUnknown": 0, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 26, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [{ "kind": "unreadable", "checkpointRef": "TX", "signed": null, "presented": null }],
+      "expect": { "verdict": "incomplete", "recordsVerified": 26, "recordsFailed": 0, "recordsUndetermined": 0, "causeCount": 1 }
+    },
+    {
+      "id": "malformed-wins",
+      "why": "an unreadable bundle is named for what it is, whatever else is true",
+      "kernel": { "status": "malformed", "okBound": 0, "okUnknown": 0, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 0, "present": 0, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "expect": { "verdict": "malformed", "recordsVerified": 0, "recordsFailed": 0, "recordsUndetermined": 0, "causeCount": 0 }
+    },
+    {
+      "id": "tamper-beats-absence",
+      "why": "a proven mismatch is still a failure even when other records were withheld — absence never masks tamper",
+      "kernel": { "status": "failed", "okBound": 24, "okUnknown": 1, "mismatched": 1, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 25, "missing": 1, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "expect": { "verdict": "failed", "recordsVerified": 24, "recordsFailed": 1, "recordsUndetermined": 1, "causeCount": 1 }
+    },
+    {
+      "id": "broken-record-is-failure-not-unknown",
+      "why": "a record that does not verify is a failure even with no content disclosed for it",
+      "kernel": { "status": "failed", "okBound": 25, "okUnknown": 0, "mismatched": 0, "brokenNoContent": 1 },
+      "logs": { "expected": 26, "present": 26, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "expect": { "verdict": "failed", "recordsVerified": 25, "recordsFailed": 1, "recordsUndetermined": 0, "causeCount": 0 }
+    },
+    {
+      "id": "kernel-headline-passes-through",
+      "why": "this rule downgrades a verdict; it never invents one",
+      "kernel": { "status": "partial", "okBound": 26, "okUnknown": 0, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 26, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "expect": { "verdict": "partial", "recordsVerified": 26, "recordsFailed": 0, "recordsUndetermined": 0, "causeCount": 0 }
+    },
+    {
+      "id": "unknown-headline-is-not-repeated",
+      "why": "a headline this rule cannot interpret is a check it could not run — UNKNOWN, never repeated verbatim. The status a surface prints must not be attacker-chosen: passing an uninterpreted string through is how a pack could be headlined with the one word the trust model forbids",
+      "kernel": { "status": "SAFE", "okBound": 26, "okUnknown": 0, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 26, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "expect": { "verdict": "incomplete", "recordsVerified": 26, "recordsFailed": 0, "recordsUndetermined": 0, "causeCount": 0 }
+    }
+  ]
+}