@sanning/proof 0.5.0 → 0.7.0

package/src/index.ts

@@ -61,7 +61,11 @@ export type { ContentRole, Envelope, Subject, VerificationResult, VerifyOptions
 // 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,
+  STAMP_BODY_VERSION,
+  STAMP_TRACE_BODY_TYPE,
   disclosedContent,
   recomputeExportVerdict,
   verifyEvidenceBundle,
@@ -87,7 +91,15 @@ export type {
   OnChainOutcome,
   OnChainResult,
   PerGatewayOutcome,
+  AnchorRef,
+  StampBody,
+  StampEntry,
+  StampResult,
+  StampSubtree,
+  StampSubtreeResult,
+  StampTraceBody,
   TraceCheckpoint,
+  TraceCheckpointV1,
   TraceEvent,
   TraceInclusion,
   VerdictAttestation,
@@ -99,6 +111,73 @@ 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";
+
+// Chain reading (src/chain.ts): following the pointer every sanning.events/v1
+// record carries to the record before it, over the records ONE bundle presents.
+//
+// Every anchored event has carried that pointer since the profile was ratified
+// and nothing we shipped read it, so a bundle with an event removed — and a
+// chain that restarted after a crash and now asserts two beginnings — passed
+// every check we had (proof#43). The verifier was right not to do this: it
+// verifies a single envelope and says so. Nothing above it did it either.
+//
+// Pure — data in, data out, no I/O — so the kernel's scope boundary
+// (specs/architecture.md §3) is unchanged, and the rule ships as
+// `vectors/chain-reading.json` beside the pack-grading table for the same
+// reason: a rule consumers must agree with needs a statement they can fetch.
+//
+// It returns FINDINGS, never a verdict, and it feeds no status. Chain links are
+// deletion/reorder-evidence for the events present and NOT a completeness proof
+// (`anchor/docs/profile-sanning.events-v1.md` §5) — drop the last N events of a
+// chain and nothing dangles. `CHAIN_READING_SCOPE` is that sentence, exported so
+// every surface prints the same limit rather than paraphrasing it into a claim.
+// Additive — no existing export changes.
+export {
+  ADAPTER_CHAIN_NAMESPACES,
+  CHAIN_READING_SCOPE,
+  readChains,
+  renderChainFinding,
+} from "./chain.js";
+export type {
+  ChainFinding,
+  ChainFindingKind,
+  ChainReading,
+  ChainSource,
+  ChainSummary,
+} from "./chain.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/src/verifier.ts

@@ -228,6 +228,20 @@ export async function verifyEnvelope(
     typeof optionsOrContentHash === "string"
       ? { expectedContentHash: optionsOrContentHash }
       : (optionsOrContentHash ?? {});
+  // REFUSE an unknown option key rather than ignore it. `expected_content_hash`
+  // — the Python kernel's spelling — previously fell through as `undefined`, so
+  // the content bind silently never ran and the caller got a clean pass with no
+  // errors at all. A check that quietly does not happen is worse than one that
+  // fails: the caller believes they verified an artifact they never checked.
+  const KNOWN_VERIFY_OPTIONS = new Set(["payloadBytes", "expectedContentHash"]);
+  const unknownOptions = Object.keys(opts).filter((k) => !KNOWN_VERIFY_OPTIONS.has(k));
+  if (unknownOptions.length > 0) {
+    throw new TypeError(
+      `verifyEnvelope: unknown option(s) ${unknownOptions.join(", ")}. ` +
+        `Did you mean ${[...KNOWN_VERIFY_OPTIONS].join(" / ")}? ` +
+        "Option keys are camelCase in the TypeScript kernel; the Python kernel uses snake_case.",
+    );
+  }
   const expectedContentHash = opts.expectedContentHash;
   const errors: string[] = [];
 
@@ -313,19 +327,47 @@ export async function verifyEnvelope(
   let contentHashOk: boolean | null = null;
   let contentRole: ContentRole | null = null;
   if (expectedContentHash !== undefined) {
-    const want = expectedContentHash.toLowerCase();
-    const match = contentHashes(env).find((c) => c.hash.toLowerCase() === want);
-    contentHashOk = match !== undefined;
-    contentRole = match ? match.role : null;
-    if (!contentHashOk) {
-      errors.push("provided content hash does not match any hash this envelope commits to");
+    const committed = contentHashes(env);
+    if (committed.length === 0) {
+      // UNDETERMINED, not failed. An external-commitment envelope
+      // (`sanning.events/v1`) has no inline payload, so it commits to no
+      // envelope-readable content hash and there is nothing here to compare
+      // against. Reporting that as a failure would render "we cannot check
+      // this" as "it did not match" — what P-10 and I-5 exist to prevent — and
+      // would fail every envelope on the DL-52 path.
+      //
+      // The caller is still told the check did not happen; silence would be
+      // worse than either verdict.
+      contentHashOk = null;
+      errors.push(
+        "this envelope commits to no readable content hash (external-commitment " +
+          "profile), so the provided content hash could not be checked — " +
+          "undetermined, not failed",
+      );
+    } else {
+      const want = expectedContentHash.toLowerCase();
+      const match = committed.find((c) => c.hash.toLowerCase() === want);
+      contentHashOk = match !== undefined;
+      contentRole = match ? match.role : null;
+      if (!contentHashOk) {
+        errors.push("provided content hash does not match any hash this envelope commits to");
+      }
     }
   }
 
   return {
     // null (binding not checkable) does not fail the verdict — Python-kernel
     // parity: ok = spec && sig && payloadHashOk is not False.
-    ok: specVersionOk && signatureOk && payloadHashOk !== false,
+    // A supplied `expectedContentHash` that matches nothing this envelope
+    // commits to is a FAILING verdict, not a side note (proof#42). This is the
+    // check an external auditor runs — "does this file match what was
+    // anchored" — and reporting it only in `contentHashOk` meant the top-level
+    // verdict, the field a caller naturally reads, said pass over a file that
+    // does not match.
+    //
+    // Absence stays undetermined: `contentHashOk` is null when no hash was
+    // supplied, and null must not fail (P-10 — absence is not failure).
+    ok: specVersionOk && signatureOk && payloadHashOk !== false && contentHashOk !== false,
     specVersionOk,
     payloadHashOk,
     signatureOk,

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.