@sanning/proof 0.5.0 → 0.7.0

package/dist/index.js

@@ -34,7 +34,44 @@ export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyI
 // 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, EXPORT_BODY_TYPE, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
+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, } 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";
+// 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";
 // 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/dist/side-content.d.ts

@@ -0,0 +1,36 @@
+/** 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;
+}
+/** Look up one event's out-of-band disclosure. The rule, stated once. */
+export declare function sideContentEntry(content: SideContentMap | null | undefined, eventId: string): SideEntry;
+/** Whether the map carries a usable entry for this id. The same rule. */
+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.
+ */
+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.
+ */
+export declare function inBodyContentOffered(content: unknown): boolean;

package/dist/side-content.js

@@ -0,0 +1,98 @@
+// 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.
+const ABSENT = { offered: false, value: undefined };
+/** Look up one event's out-of-band disclosure. The rule, stated once. */
+export function sideContentEntry(content, eventId) {
+    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;
+    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, 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.
+ */
+export function sideContentKeys(content) {
+    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) {
+    return content !== undefined && content !== null;
+}

package/dist/verifier.js

@@ -215,6 +215,18 @@ export async function verifyEnvelope(env, optionsOrContentHash) {
     const opts = 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 = [];
     // Guard a malformed input (null / non-object / array) up front — every field
@@ -296,18 +308,45 @@ export async function verifyEnvelope(env, optionsOrContentHash) {
     let contentHashOk = null;
     let contentRole = 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanning/proof",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "TypeScript kernel of the Sanning verification stack: RFC 8785 (JCS) canonicalization, SHA-256, and Ed25519 verification for Verifiable Event Envelopes. Full-family verifier (inline + external commitment); accepts sanning.agent/v1, sanning.mlflow/v1, sanning.events/v1. Conformance-gated byte-for-byte against the test-vectors corpus.",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "dist",
+    "vectors",
     "README.md",
     "LICENSE"
   ],