@sanning/proof 0.11.1 → 0.13.0

package/dist/evidence.js

@@ -21,13 +21,15 @@ import { deriveOperatorAddress, ed25519Verify, hexToBytes,
 // body: two copies of one rule is how two kernels drift apart one edit at a
 // time, which is the whole defect class this fix is about.
 isHexField, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
+import { isConformantHandoffRecord, isHandoffNamespace } from "./handoff.js";
 import { leafHash, verifyInclusion } from "./merkle.js";
 import { MAX_CANONICAL_DEPTH, contentHashes, exceedsDepth, jcs, jcsParse, verifyEnvelope, } from "./verifier.js";
 import { inBodyContentOffered, sideContentEntry, } from "./side-content.js";
 // Only the evidence-bundle major(s) this kernel verifies. A new major is a
 // deliberate one-entry addition HERE — same fail-closed discipline as the
 // envelope verifier's ACCEPTED_SPEC_MAJORS.
-const ACCEPTED_EVIDENCE_MAJORS = ["sanning.evidence/v1"];
+/** The accepted `sanning.evidence/v1` wrapper majors; exported in both kernels (P-01, 0.13.0). */
+export const ACCEPTED_EVIDENCE_MAJORS = Object.freeze(["sanning.evidence/v1"]);
 // The body_type this module knows how to verify structurally. An unknown
 // body_type is not a hard failure of the WRAPPER (the signature + body_hash
 // still verify), but its body cannot be re-derived, so the per-body verdict is
@@ -254,12 +256,16 @@ async function verifyBundle(bundle, options, exportSource) {
     const b = bundle;
     const specVersionOk = isEvidenceMajorAccepted(b.spec_version);
     if (!specVersionOk) {
-        return malformed(`unsupported evidence spec_version: ${JSON.stringify(b.spec_version)}`, false);
+        // `?? null`: an ABSENT field is spelled `null`, as the Python twin's
+        // `_json_str` spells it. `JSON.stringify(undefined)` is `undefined`, and
+        // the two kernels printed two different sentences for one bundle until
+        // `verify --json` compared them byte for byte (0.13.0).
+        return malformed(`unsupported evidence spec_version: ${JSON.stringify(b.spec_version ?? null)}`, false);
     }
     if (typeof b.signature_alg === "string" && b.signature_alg !== "ed25519") {
         // The reference verifier implements ed25519 only (evidence-bundle §2 +
         // decision #2); other algs are a deliberate future addition.
-        return malformed(`unsupported signature_alg: ${JSON.stringify(b.signature_alg)}`, true);
+        return malformed(`unsupported signature_alg: ${JSON.stringify(b.signature_alg ?? null)}`, true);
     }
     if (typeof b.public_key !== "string" || typeof b.signature !== "string") {
         return malformed("evidence bundle is missing public_key/signature", true);
@@ -308,7 +314,7 @@ async function verifyBundle(bundle, options, exportSource) {
     if (keyFormOk && signatureFormOk) {
         try {
             const { signature: _sig, co_signatures: _co, ...bundleForSig } = b;
-            signatureOk = await ed25519Verify(b.signature, utf8(jcs(bundleForSig)), b.public_key);
+            signatureOk = await ed25519Verify(utf8(jcs(bundleForSig)), b.signature, b.public_key);
             if (!signatureOk)
                 errors.push("wrapper Ed25519 signature verification failed");
         }
@@ -524,7 +530,7 @@ function parseAnchorRef(raw, errors) {
     }
     const o = raw;
     if (typeof o.kind !== "string" || !/^[a-z0-9][a-z0-9._-]*$/.test(o.kind)) {
-        errors.push(`anchor_ref.kind is missing or malformed: ${JSON.stringify(o.kind)}`);
+        errors.push(`anchor_ref.kind is missing or malformed: ${JSON.stringify(o.kind ?? null)}`);
         return { ref: null, malformed: true };
     }
     if (typeof o.id !== "string" || o.id === "") {
@@ -1076,21 +1082,62 @@ function isNonNegInt(n) {
 async function verifyDisclosedContent(ev, eventId, eventBytes, sideContent) {
     const evErrors = [];
     let contentOk = null;
+    // WHICH hash in the record is decided by the record's STRUCTURE
+    // (evidence-bundle §5.1 v1.19, A20). A record `envelope-spec.md` §4.1
+    // governs (`isHandoffNamespace`) commits to its message through
+    // `event.message_hash`, SHA-256 of `JCS(message object)`, and has no
+    // `content_hash`, so until A20 its disclosure bound to nothing and an honest
+    // hand-off pack could never grade `verified`. For such a record the committed
+    // hash is `event.message_hash` and nothing else: not a `content_hash` it also
+    // carries, and not the envelope's. It binds only when the record is a
+    // CONFORMANT hand-off record under the key that signed it
+    // (`isConformantHandoffRecord`) and the value is 64 characters of lowercase
+    // hex. Anything short of that commits nothing this reader will bind to, so
+    // the reading is undetermined and never true: a record dressed as a hand-off
+    // record gains no binding from the dress, and a record outside §4.1 keeps its
+    // `content_hash` exactly as before, whatever `message_hash` field it writes.
+    // The Python twin is `evidence._evaluate_content`.
     const committed = [];
     let recordContentHash;
+    let governed = false;
+    let handoffHash;
     if (eventBytes !== undefined) {
         try {
-            const record = jcsParse(eventBytes);
-            const ch = record.event?.content_hash;
+            const parsed = jcsParse(eventBytes);
+            const record = parsed;
+            const ch = record?.event?.content_hash;
             if (typeof ch === "string" && ch)
                 recordContentHash = ch.toLowerCase();
+            if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+                const envelope = ev.envelope;
+                const held = {
+                    publicKey: envelope !== null && typeof envelope === "object" && !Array.isArray(envelope)
+                        ? envelope.public_key
+                        : undefined,
+                    record: parsed,
+                    ref: "",
+                };
+                if (isHandoffNamespace(held)) {
+                    governed = true;
+                    const event = parsed.event;
+                    const mh = event !== null && typeof event === "object" && !Array.isArray(event)
+                        ? event.message_hash
+                        : undefined;
+                    if (isConformantHandoffRecord(held) && isLowerHex(mh, 64))
+                        handoffHash = mh;
+                }
+            }
         }
         catch {
             // record not JSON — the payload binding already reflects that; content
             // stays undetermined rather than throwing.
         }
     }
-    if (recordContentHash !== undefined) {
+    if (governed) {
+        if (handoffHash !== undefined)
+            committed.push(handoffHash);
+    }
+    else if (recordContentHash !== undefined) {
         committed.push(recordContentHash);
     }
     else if (ev.envelope && typeof ev.envelope === "object") {
@@ -1112,15 +1159,20 @@ async function verifyDisclosedContent(ev, eventId, eventBytes, sideContent) {
         if (disclosed === undefined || committed.length === 0) {
             contentOk = null;
             if (disclosed !== undefined && committed.length === 0) {
-                evErrors.push("disclosed content present but no committed content_hash to bind to " +
-                    "(record withheld or record has no event.content_hash) -- undetermined");
+                evErrors.push(governed
+                    ? "disclosed content present but this hand-off record commits no " +
+                        "message_hash a reader can bind to (not a conformant hand-off " +
+                        "record, or message_hash is not 64 lowercase hex) -- undetermined"
+                    : "disclosed content present but no committed content_hash to bind to " +
+                        "(record withheld or record has no event.content_hash) -- undetermined");
             }
         }
         else {
             const got = await sha256Hex(disclosed);
             contentOk = committed.includes(got);
             if (!contentOk) {
-                evErrors.push("disclosed content does not match the committed content_hash: " +
+                const fieldName = governed ? "message_hash" : "content_hash";
+                evErrors.push(`disclosed content does not match the committed ${fieldName}: ` +
                     `sha256(disclosed)=${got} committed=${committed.join("|")}`);
             }
         }
@@ -1217,7 +1269,7 @@ async function verifyStampEntry(raw, seen) {
         // two answers to one question inside one signature. The body_type is the
         // reader's dispatch key and it said v1; honouring the other spelling is
         // how a reader half-parses a shape it does not know.
-        errors.push(`unsupported stamp_version ${JSON.stringify(body.stamp_version)} in a ` +
+        errors.push(`unsupported stamp_version ${JSON.stringify(body.stamp_version ?? null)} in a ` +
             `${STAMP_TRACE_BODY_TYPE} body (expected ${STAMP_BODY_VERSION})`);
         return { result: base, witnessedHex };
     }
@@ -1702,8 +1754,8 @@ async function verifyStampEvidence(b, specVersionOk, assertedStatus, errors, opt
  * synthesis exists to drive `gatewayUnavailable`, which is what downgrades that
  * run to `partial`. Here §5.2.4 already downgrades an unwitnessed stamp to
  * `partial` on its own, with a better error. Copying the synthesis would add
- * nothing to the status and would silently move the CLI exit code from 0 to 3
- * for an unwitnessed stamp — changing what an auditor's script does, based on
+ * nothing to the status, which is `partial` either way, and would add an
+ * unreachable-gateway note for a network event that never happened, based on
  * nothing but whether the caller happened to pass a gateway list.
  */
 async function refetchStamps(stamps, witnessed, options, errors) {
@@ -2016,8 +2068,11 @@ async function verifyExportBody(b, specVersionOk, assertedStatus, errors, option
     // step-5 erratum flagged in the slice report.
     let verdictAgreementOk = false;
     try {
-        const cachedProjection = jcs(projectVerdictForAgreement(body.kernel_verdict));
-        const freshProjection = jcs(projectVerdictForAgreement(verdict));
+        const cached = projectVerdictForAgreement(body.kernel_verdict);
+        const fresh = projectVerdictForAgreement(verdict);
+        toleratePreA20Content(cached, fresh, sourceEventsGoverned(inline));
+        const cachedProjection = jcs(cached);
+        const freshProjection = jcs(fresh);
         verdictAgreementOk = cachedProjection === freshProjection;
         if (!verdictAgreementOk) {
             errors.push("recomputed verdict disagrees with the cached kernel_verdict " +
@@ -2046,8 +2101,8 @@ async function verifyExportBody(b, specVersionOk, assertedStatus, errors, option
         status = "failed";
     }
     else if (sourceResult.status === "partial") {
-        // Undetermined source (withheld record → exit 0; gateway-unreachable →
-        // exit 3 via the propagated "unreachable" note). Never a failure.
+        // Undetermined source (a withheld record, or an unreachable gateway):
+        // exit 3 either way since 0.13.0. Never a failure.
         status = "partial";
     }
     else {
@@ -2193,7 +2248,7 @@ async function verifyAttestation(rec, sourceCheckpoints) {
     if (rec.signature_alg !== "rsa-pss-sha256") {
         return {
             result,
-            malformed: `unsupported attestation signature_alg: ${JSON.stringify(rec.signature_alg)}`,
+            malformed: `unsupported attestation signature_alg: ${JSON.stringify(rec.signature_alg ?? null)}`,
         };
     }
     const pub = rec.public_key;
@@ -2421,6 +2476,66 @@ function projectVerdictForAgreement(v) {
         }),
     };
 }
+// Per event of an export's inline `sanning.anchor.trace/v3` source, in order:
+// whether `envelope-spec.md` §4.1 governs its record. Decoded the way the
+// content binding decodes it, so an event whose record is withheld, not hex or
+// not JCS is not governed here either. The Python twin is
+// `evidence._source_events_governed`.
+function sourceEventsGoverned(source) {
+    if (source === null || typeof source !== "object" || Array.isArray(source))
+        return [];
+    const s = source;
+    if (s.body_type !== ANCHOR_TRACE_BODY_TYPE)
+        return [];
+    const body = s.body;
+    const events = body !== null && typeof body === "object" && !Array.isArray(body) ? body.events : undefined;
+    if (!Array.isArray(events))
+        return [];
+    return events.map((raw) => {
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+            return false;
+        const ev = raw;
+        if (typeof ev.event_bytes !== "string")
+            return false;
+        try {
+            const parsed = jcsParse(hexToBytes(ev.event_bytes));
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+                return false;
+            const envelope = ev.envelope;
+            const held = {
+                publicKey: envelope !== null && typeof envelope === "object" && !Array.isArray(envelope)
+                    ? envelope.public_key
+                    : undefined,
+                record: parsed,
+                ref: "",
+            };
+            return isHandoffNamespace(held);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+// The one difference §5 step 5 does not read as a disagreement
+// (evidence-export.md, evidence-bundle.md v1.19, A20): a cached `content_ok` of
+// `null` against a recomputed `true`, on an event whose record §4.1 governs. A
+// kernel before A20 could not bind a hand-off record's disclosed message, so an
+// export it composed claims less than the recompute proves, and reading that
+// as tamper failed an honest export. Only that direction: a cached `true`
+// against a recomputed `false` or `null`, `null` against `false`, and any
+// difference on a record outside §4.1 still disagree. Edits `fresh` in place
+// to match `cached` on those events. The Python twin is
+// `evidence._tolerate_pre_a20_content`.
+function toleratePreA20Content(cached, fresh, governed) {
+    const n = Math.min(cached.events.length, fresh.events.length);
+    for (let i = 0; i < n; i++) {
+        if (governed[i] === true &&
+            cached.events[i].content_ok === null &&
+            fresh.events[i].content_ok === true) {
+            fresh.events[i].content_ok = null;
+        }
+    }
+}
 function summarizeExport(status, source, attestations) {
     const attOk = attestations.filter((a) => a.ok).length;
     return (`Export ${status}: source bundle ${source.status} ` +

package/dist/exit-codes.d.ts

@@ -0,0 +1,17 @@
+export declare const EXIT_VERIFIED = 0;
+export declare const EXIT_FAILED = 1;
+export declare const EXIT_MALFORMED = 2;
+export declare const EXIT_UNDETERMINED = 3;
+export declare const EXIT_MIXED = 4;
+/**
+ * The exit code of each of the eight verdict words (`evidence-bundle.md` §3).
+ * `undetermined` is the name of 3, and never a word here.
+ */
+export declare const EXIT_CODES: Readonly<Record<string, number>>;
+/** What every verb's help prints, identical in both commands. */
+export declare const EXIT_CODES_HELP: string;
+/**
+ * The exit code of a verdict word. A word outside the eight is a verdict
+ * nothing can render, so it exits 2, never 0.
+ */
+export declare function exitCodeFor(verdict: unknown): number;

package/dist/exit-codes.js

@@ -0,0 +1,50 @@
+// One exit-code table for every verb (0.13.0).
+//
+// Both commands, `npx @sanning/proof` and `sanning-proof`, map a verdict word to
+// an exit code through this one table, for `verify`, `case` and `export` alike,
+// and every verb's `--help` prints `EXIT_CODES_HELP` byte for byte. The twin is
+// `src/sanning_proof/exit_codes.py`; the specification is `evidence-export.md`
+// §5.
+//
+// Until 0.13.0 `verify` exited 0 on `partial` unless a gateway was unreachable,
+// while `case` exited 3 on it, so a CI gate reading `verify`'s exit code read a
+// stamp witnessed by nobody as verified. Every word that means "could not be
+// settled" now exits 3, which is the code's name: undetermined.
+export const EXIT_VERIFIED = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_MALFORMED = 2;
+export const EXIT_UNDETERMINED = 3;
+export const EXIT_MIXED = 4;
+/**
+ * The exit code of each of the eight verdict words (`evidence-bundle.md` §3).
+ * `undetermined` is the name of 3, and never a word here.
+ */
+export const EXIT_CODES = Object.freeze({
+    verified: EXIT_VERIFIED,
+    failed: EXIT_FAILED,
+    malformed: EXIT_MALFORMED,
+    partial: EXIT_UNDETERMINED,
+    pending: EXIT_UNDETERMINED,
+    incomplete: EXIT_UNDETERMINED,
+    not_found: EXIT_UNDETERMINED,
+    mixed: EXIT_MIXED,
+});
+/** What every verb's help prints, identical in both commands. */
+export const EXIT_CODES_HELP = [
+    "Exit codes, one table for every verb:",
+    "  0  verified, or the export was written",
+    "  1  failed",
+    "  2  usage or malformed",
+    "  3  undetermined: partial, pending, incomplete or not_found",
+    "  4  mixed: more than one outcome, none failed; read the exceptions",
+].join("\n");
+/**
+ * The exit code of a verdict word. A word outside the eight is a verdict
+ * nothing can render, so it exits 2, never 0.
+ */
+export function exitCodeFor(verdict) {
+    if (typeof verdict === "string" && Object.prototype.hasOwnProperty.call(EXIT_CODES, verdict)) {
+        return EXIT_CODES[verdict];
+    }
+    return EXIT_MALFORMED;
+}

package/dist/grading.d.ts

@@ -1,6 +1,7 @@
 import type { DeclarationCheck, DeclarationContentKind, DeclarationDeviationKind, DeclarationVerdict } from "./declaration.js";
 import { type SideContentMap } from "./side-content.js";
-export type PackVerdict = "verified" | "partial" | "pending" | "not_found" | "mixed" | "failed" | "malformed" | "incomplete";
+export declare const PACK_VERDICTS: readonly ["verified", "partial", "pending", "not_found", "mixed", "failed", "malformed", "incomplete"];
+export type PackVerdict = (typeof PACK_VERDICTS)[number];
 /**
  * The minimum this module reads out of a verification result.
  *
@@ -12,9 +13,16 @@ export type PackVerdict = "verified" | "partial" | "pending" | "not_found" | "mi
  */
 export interface GradeInput {
     status: string | null | undefined;
+    /**
+     * `eventId` and `payloadBindingOk` are read by rule version 6 alone (A22):
+     * an input that does not carry both is never withheld by its declaration,
+     * so an adapter written for rule version 5 keeps the stricter reading.
+     */
     events: {
         ok: boolean;
         contentOk: boolean | null;
+        eventId?: string;
+        payloadBindingOk?: boolean | null;
     }[];
 }
 /**
@@ -56,13 +64,8 @@ export type CompletenessNote = {
     presented: null;
     kind: "unreadable";
 };
-export type PackGradeCauseKind = "records-omitted" | "records-surplus" | "leaf-count-unreadable" | "no-disclosure" | "missing-disclosure" | "unreadable-disclosure" | "unaccounted-disclosure" | "declaration-deviation"
-/**
- * The pack and the UNSIGNED content handed in beside it do not line up
- * (proof#147). A cause, so the pack cannot read clean over it and a reader
- * is told which record; NOT a deviation, so it never reaches `failed`.
- */
- | "declaration-content-dependent";
+export declare const PACK_GRADE_CAUSE_KINDS: readonly ["records_omitted", "records_surplus", "leaf_count_unreadable", "no_disclosure", "missing_disclosure", "unreadable_disclosure", "unaccounted_disclosure", "declaration_deviation", "declaration_content_dependent"];
+export type PackGradeCauseKind = (typeof PACK_GRADE_CAUSE_KINDS)[number];
 /**
  * One reason a pack is not `verified`, as data.
  *
@@ -89,8 +92,8 @@ export interface PackGradeCause {
     reason?: string;
     /**
      * Which deviation from the pack's own declaration, for
-     * `declaration-deviation`, or which content-dependent finding, for
-     * `declaration-content-dependent`.
+     * `declaration_deviation`, or which content-dependent finding, for
+     * `declaration_content_dependent`.
      */
     deviation?: DeclarationDeviationKind | DeclarationContentKind;
 }
@@ -107,6 +110,17 @@ export interface PackGrade {
      * check was passed, which is the pre-§5.4 call.
      */
     declaration?: DeclarationVerdict;
+    /**
+     * Records WITHHELD BY THEIR DECLARATION (rule version 6, evidence-bundle
+     * 5.4.5 v1.20, A22): a readable declaration lists them in
+     * `declaredWithheld`, their `ok` is true, their `contentOk` is `null` and
+     * their `payloadBindingOk` is true. Never counted in `recordsVerified`: no
+     * byte of their content was hashed, and a surface MUST NOT print them as
+     * verified records.
+     */
+    recordsWithheld: number;
+    /** Their `event_id`s, in bundle order. */
+    withheldEventIds: string[];
 }
 /**
  * Account for the disclosed bytes a pack handed us against the records its
@@ -152,13 +166,14 @@ export declare function completenessNotes(bundle: unknown): CompletenessNote[];
  * Every reason this pack is not `verified`, in the order a reader should hear
  * them: what is missing from the whole, then what is missing from the parts.
  */
-export declare function gradeCauses(account: DisclosureAccount, notes: readonly CompletenessNote[], declaration?: DeclarationCheck | null): PackGradeCause[];
+export declare function gradeCauses(account: DisclosureAccount, notes: readonly CompletenessNote[], declaration?: DeclarationCheck | null, withheld?: readonly string[]): PackGradeCause[];
 /**
  * The verdict a surface may print, and the counts it may print beside it.
  *
  * The invariant, stated so a mutation test can kill it: `verified` is reachable
- * ONLY when every record's supplied bytes bound to its own commitment and
- * nothing is missing, unreadable, surplus or omitted.
+ * ONLY when every record's supplied bytes bound to its own commitment, or
+ * (rule version 6) the record is withheld by its declaration, and nothing is
+ * missing, unreadable, surplus or omitted.
  *
  * Precedence: malformed > failed > incomplete > the kernel's own headline.
  * A hard verdict wins — "the bytes are absent" is never reported as failure