@sanning/proof 0.9.1 → 0.10.0

package/README.md

@@ -53,7 +53,7 @@ contentHashes(env);   // all content hashes an envelope commits to, by event typ
 
 ## Verify a whole trace bundle: one command
 
-The `@sanning/anchor` SDK hands a producer a set of `InclusionReceipt`s and can serialize them into one portable, self-verifying `sanning.evidence/v1` bundle (`body_type: sanning.anchor.trace/v1`). Verify the entire bundle (every event's signature + payload binding + Merkle inclusion, all offline) with the bundled CLI:
+The `@sanning/anchor` SDK hands a producer a set of `InclusionReceipt`s and can serialize them into one portable, self-verifying `sanning.evidence/v1` bundle (`body_type: sanning.anchor.trace/v3`). Verify the entire bundle (every event's signature + payload binding + Merkle inclusion, all offline) with the bundled CLI:
 
 ```bash
 npx @sanning/proof verify trace-bundle.json
@@ -61,7 +61,7 @@ npx @sanning/proof verify trace-bundle.json
 npx @sanning/proof verify trace-bundle.json https://arweave.net,https://permagate.io
 ```
 
-It prints a per-event + rollup verdict and exits on a pinned code: `0` verified · `1` a real failure (bad signature / tamper / broken inclusion) · `2` malformed bundle · `3` gateway-unavailable when an on-chain re-fetch was requested. The producer's asserted `verdict` is shown but **never trusted**, the displayed verdict is always recomputed from the body. The same CLI also verifies the agent's `sanning.agent.proof/v1` inclusion bundle (it sniffs `spec_version`), so one command covers anchor + agent.
+It prints a per-event + rollup verdict and exits on a pinned code: `0` verified · `1` a real failure (bad signature / tamper / broken inclusion) · `2` malformed bundle · `3` gateway-unavailable when an on-chain re-fetch was requested. Only `arweave` witnesses are re-fetched: a checkpoint or stamp whose `anchor_ref.kind` is anything else is not checked, and with gateways passed the run answers `partial`, exit `3`. The producer's asserted `verdict` is shown but **never trusted**, the displayed verdict is always recomputed from the body. The same CLI also verifies the agent's `sanning.agent.proof/v1` inclusion bundle (it sniffs `spec_version`), so one command covers anchor + agent.
 
 > The `verify` CLI is live in `@sanning/proof` ≥ 0.2.2, `npx @sanning/proof verify <bundle> [gateways]`. `verifyEvidenceBundle` is the programmatic API.
 
@@ -80,7 +80,7 @@ result.checkpoints;  // per-checkpoint envelope / merkle-root / on-chain results
 result.events;       // per-event signature / payload-binding / inclusion results
 ```
 
-A withheld `record_bytes` (external commitment, record not disclosed) leaves that event's payload binding **undetermined**, surfaced, never failed (the bundle stays cryptographically sound).
+A withheld `event_bytes` (external commitment, record not disclosed) leaves that event's payload binding **undetermined**, surfaced, never failed (the bundle stays cryptographically sound).
 
 ### …including the raw logs, when the holder discloses them
 
@@ -184,7 +184,7 @@ const ok = await verifyInclusion(
 | Export | What it does |
 |---|---|
 | `verifyEnvelope(env, optionsOrContentHash?)` | The three load-bearing checks (spec-version registry, payload-hash recompute, Ed25519 over the signed scope) + optional content bind. Pass `{ payloadBytes }` for external-commitment envelopes. Returns `VerificationResult`. |
-| `verifyEvidenceBundle(bundle, { gateways?, fetchImpl? })` | Verify a signed `sanning.evidence/v1` / `sanning.anchor.trace/v1` bundle: wrapper signature + `body_hash` + every checkpoint + every event's inclusion, offline (optional on-chain re-fetch). Returns `EvidenceBundleResult`. Powers the `npx @sanning/proof verify` CLI. |
+| `verifyEvidenceBundle(bundle, { gateways?, fetchImpl? })` | Verify a signed `sanning.evidence/v1` bundle (`sanning.anchor.trace/v3`, `sanning.stamp.trace/v1`, `sanning.stamp.evidence/v2` or `sanning.evidence.export/v2`): wrapper signature + `body_hash` + every checkpoint + every event's inclusion, offline (optional on-chain re-fetch). Returns `EvidenceBundleResult`. Powers the `npx @sanning/proof verify` CLI. |
 | `disclosedContent(bundle, { gateways?, content?, fetchImpl? })` | **Ingest:** verify a bundle, then hand back the DECODED raw bytes (`Uint8Array`) of every event whose disclosure bound to its committed `content_hash`, so materializing a received pack never means re-implementing the hex convention. Returns `DisclosedContentResult` (`content` map + per-event `verified` / `not_disclosed` / `undetermined` / `failed`, plus the full `verification`). |
 | `gradePack(result, account, notes)` + `accountDisclosure(bundle, content)` / `completenessNotes(bundle)` / `renderCause(cause)` | **Pack grading:** what a SURFACE may claim about a pack: the bundle plus whatever disclosed bytes travelled with it. Three states, never two: `verified` only when every record's own bytes bound to its own commitment and nothing is missing, unreadable, surplus or omitted; `failed` on a proven mismatch; `incomplete` when a check could not be run. Absent evidence is UNKNOWN, never an accusation. Pure: no I/O; transport stays yours. Conformance table: `vectors/pack-grading.json`, shipped in this tarball. |
 | `verifyAgentProofBundle(bundle, { gateways?, fetchImpl? })` / `isAgentProofSpec(v)` | Verify the agent producer's `sanning.agent.proof/v1` inclusion bundle. |
@@ -203,7 +203,7 @@ The primary signature covers `JCS(envelope minus signature minus co_signatures)`
 
 ## Why you can trust it (without trusting us)
 
-Three **independent implementations** of this kernel exist: this package, the Python [`sanning-proof`](https://pypi.org/project/sanning-proof/) (PyPI), and and the MIT-licensed Go reference. The TypeScript and Python kernels are conformance-gated **byte-for-byte** in CI against one shared corpus, pinned per file by SHA-256 at cut tag `test-vectors-v3.4`, and a cross-kernel agreement gate re-runs the corpus plus adversarial negatives through both, asserting identical verdicts on identical bytes. The Go reference runs as a third leg of that same gate, built at the commit its vendoring pins.
+Three **independent implementations** of this kernel exist: this package, the Python [`sanning-proof`](https://pypi.org/project/sanning-proof/) (PyPI), and and the MIT-licensed Go reference. The TypeScript and Python kernels are conformance-gated **byte-for-byte** in CI against one shared corpus, pinned per file by SHA-256 at cut tag `test-vectors-v4.0`, and a cross-kernel agreement gate re-runs the corpus plus adversarial negatives through both, asserting identical verdicts on identical bytes. The Go reference runs as a third leg of that same gate, built at the commit its vendoring pins.
 
 That mutual gate is the point: anyone can verify these provenance records with **no Sanning code in the trust path**, write your own verifier against the specs that ship inside the [`sanning-proof`](https://pypi.org/project/sanning-proof/) sdist, and the corpus will tell you if it is conformant.
 

package/dist/agent-proof.js

@@ -77,6 +77,11 @@ export async function verifyAgentProofBundle(bundle, options = {}) {
             errors.push("checkpoint envelope signature failed");
         if (res.payloadHashOk !== true)
             errors.push("checkpoint envelope payload binding failed");
+        // A malformed skeleton field (proof#95) fails the envelope with a valid
+        // signature and binding; name it rather than fail with no reason.
+        for (const m of res.errors)
+            if (m.startsWith("malformed "))
+                errors.push(`checkpoint envelope ${m}`);
         const payload = (b.checkpoint_envelope.payload ?? {});
         if (typeof payload.merkle_root === "string")
             merkleRoot = payload.merkle_root;

package/dist/chain.js

@@ -2,8 +2,8 @@
 // event before it, and reporting what does not line up.
 //
 // WHY THIS LIVES IN THE KERNEL, BESIDE PACK GRADING.
-// `sanning.events/v1` records carry `previous_hash`, and until now nothing we
-// shipped read it. The envelope verifier hashes each event's `record_bytes`
+// `sanning.events/v2` records carry `previous_hash`, and until now nothing we
+// shipped read it. The envelope verifier hashes each event's `event_bytes`
 // and stops — `evidence.ts` says following the link is "consumer-layer logic
 // above it", and it was right that a SINGLE-envelope verifier should not do
 // it. But the consumer layer never did it either, so a bundle with an event
@@ -18,7 +18,7 @@
 // ---- WHAT THIS IS NOT ------------------------------------------------------
 //
 // It is not a completeness statement and it must never be read as one. The
-// profile says so in its own words (`anchor/docs/profile-sanning.events-v1.md`
+// profile says so in its own words (`anchor/docs/profile-sanning.events-v2.md`
 // §5): chain semantics are "deletion/reorder-evidence for the events present
 // ... not a completeness proof." Drop the last N events of a chain and nothing
 // here dangles; the record that would have pointed at them was never written.
@@ -178,7 +178,7 @@ async function groupChains(bundle) {
         // event id an adapter pointer has nothing to resolve against.
         if (eventId === null || publicKey === null)
             continue;
-        const decoded = decodeRecord(entry?.record_bytes);
+        const decoded = decodeRecord(entry?.event_bytes);
         if (decoded === null)
             continue;
         const { record, bytes } = decoded;

package/dist/cli.js

@@ -2,8 +2,9 @@
 // npx @sanning/proof verify <bundle.json> [comma,sep,gateways]
 //
 // One turnkey verifier for both producer bundles in the stack:
-//   - sanning.evidence/v1 (body sanning.anchor.trace/v1)  — the @sanning/anchor SDK trace
-//   - sanning.agent.proof/v1                            — the agent inclusion proof
+//   - sanning.evidence/v1: bodies sanning.anchor.trace/v3, sanning.stamp.trace/v1,
+//     sanning.stamp.evidence/v2 and sanning.evidence.export/v2
+//   - sanning.agent.proof/v1: the agent inclusion proof
 // Dispatch is by sniffed spec_version; no flag tells the CLI which it is.
 //
 // Pinned exit codes (mirror `sanningd verify-status`):
@@ -163,8 +164,8 @@ export async function runCli(argv, io) {
 // `proof bundle <source-bundle.json> --attestations <f> --key <f> [-o <out>]`
 // (`proof export` still reaches this, undocumented — see the dispatch above.)
 //
-// Compose a signed, offline-verifiable sanning.evidence.export/v1 artifact from a
-// source sanning.anchor.trace/v1 bundle + operator attestation records + an exporter
+// Compose a signed, offline-verifiable sanning.evidence.export/v2 artifact from a
+// source sanning.anchor.trace/v3 bundle + operator attestation records + an exporter
 // Ed25519 key (evidence-export.md §5, composer). Writes the export to `-o <out>`
 // (or stdout when omitted, so it can be piped straight into `proof verify`).
 //
@@ -295,8 +296,8 @@ async function runBundle(rest, io) {
 function usageExport(io) {
     io.out("Usage: npx @sanning/proof bundle <source-bundle.json> --attestations <file> --key <file> [-o <out.json>]");
     io.out("");
-    io.out("Compose a signed, offline-verifiable sanning.evidence.export/v1 artifact from an");
-    io.out("sanning.anchor.trace/v1 source bundle + operator attestation records + an exporter");
+    io.out("Compose a signed, offline-verifiable sanning.evidence.export/v2 artifact from an");
+    io.out("sanning.anchor.trace/v3 source bundle + operator attestation records + an exporter");
     io.out("Ed25519 key. The output verifies with `proof verify <out.json>`.");
     io.out("");
     io.out("--attestations <file>  JSON array of attestation records (or {attestations:[...]}).");
@@ -567,10 +568,12 @@ function printUsage(io) {
     io.out("  verify <bundle.json> [gateways] [--logs <path>]        Verify a bundle");
     io.out("  bundle <source.json> --attestations <f> --key <f> [-o] Create an attested bundle");
     io.out("");
-    io.out("Verify a sanning.evidence/v1 (sanning.anchor.trace/v1) bundle, an");
-    io.out("sanning.evidence.export/v1 attested export, or a sanning.agent.proof/v1");
-    io.out("inclusion bundle, fully offline. Supply a comma-separated gateway list");
-    io.out("to also re-fetch each checkpoint on-chain.");
+    io.out("Verify a sanning.evidence/v1 bundle (body sanning.anchor.trace/v3,");
+    io.out("sanning.stamp.trace/v1, sanning.stamp.evidence/v2 or the attested export");
+    io.out("sanning.evidence.export/v2) or a sanning.agent.proof/v1 inclusion bundle,");
+    io.out("fully offline. Supply a comma-separated gateway list to also re-fetch");
+    io.out("each checkpoint and stamp on-chain. Only arweave witnesses are re-fetched;");
+    io.out("a witness of any other kind is not checked and the run exits 3.");
     io.out("");
     io.out("--logs <path>       Bind disclosed raw logs to each event's committed");
     io.out("                    content_hash. Either shape works, and which one you");

package/dist/compose.js

@@ -1,8 +1,8 @@
 // Attested-evidence-export composer (`proof export`, evidence-export.md §5,
 // phase 2). The last-mile issuer/runtime job the kernel does NOT own (§5.1
-// "Out of the kernel"): take a source `sanning.anchor.trace/v1` bundle + a set of
+// "Out of the kernel"): take a source `sanning.anchor.trace/v3` bundle + a set of
 // operator attestation records + an exporter Ed25519 key, and PRODUCE one signed,
-// offline-verifiable `sanning.evidence.export/v1` artifact — exactly the bytes the
+// offline-verifiable `sanning.evidence.export/v2` artifact, exactly the bytes the
 // kernel's verifyExportBody round-trip-verifies.
 //
 // This is the inverse of evidence.ts's verifyExportBody, and it is deliberately
@@ -24,7 +24,7 @@ import { EXPORT_BODY_TYPE, recomputeExportVerdict, } from "./evidence.js";
 import { base64UrlToBytes, bytesToHex, ed25519PublicKey, ed25519Sign, sha256Hex, utf8, } from "./crypto.js";
 import { jcs } from "./verifier.js";
 const GENESIS = "GENESIS";
-const EXPORT_SCHEMA = "sanning.evidence.export/v1";
+const EXPORT_SCHEMA = EXPORT_BODY_TYPE;
 // Transcode an attestation `signature` to the lowercase hex §2.2 mandates. The
 // issuer emits either lowercase-hex or unpadded base64url; §2.2 stores hex, so
 // this is the composer's boundary normalization. Heuristic mirrors the repo's

package/dist/crypto.js

@@ -72,7 +72,7 @@ export async function ed25519PublicKey(privateKeyHex) {
     return bytesToHex(await ed.getPublicKeyAsync(hexToBytes(privateKeyHex)));
 }
 // ---------------------------------------------------------------------------
-// RSA-PSS operator-attestation crypto (sanning.evidence.export/v1)
+// RSA-PSS operator-attestation crypto (sanning.evidence.export/v2)
 //
 // The attested-evidence-export body embeds operator attestations signed with
 // RSA-PSS-SHA-256 over the JCS-canonical attestation payload; the operator key

package/dist/evidence.d.ts

@@ -1,23 +1,20 @@
 import type { Envelope } from "./types.js";
-export declare const ANCHOR_TRACE_BODY_TYPE = "sanning.anchor.trace/v2";
+export declare const ANCHOR_TRACE_BODY_TYPE = "sanning.anchor.trace/v3";
 /**
- * The frozen pre-`anchor_ref` body (evidence-bundle.md §5.1.3).
- *
- * Accepted PERMANENTLY, not for a deprecation window. Every bundle emitted
- * before 2026-09-03 carries this shape, and those bundles are evidence — a
- * reader that stopped accepting them would destroy the record it exists to
- * defend (DL-30). Nothing new emits it.
+ * The name `event_bytes` replaced. Under the new majors a body entry that still
+ * carries it is a hard reject, never an ignored unknown field: ignored, it
+ * would read as a withheld record and the event would verify with nothing
+ * checked, the fail-open the new majors exist to prevent (governance.md §8,
+ * W-3).
  */
-export declare const ANCHOR_TRACE_BODY_TYPE_V1 = "sanning.anchor.trace/v1";
-/** Every anchor-trace body this kernel verifies. Order is newest-first. */
-export declare const ANCHOR_TRACE_BODY_TYPES: readonly ["sanning.anchor.trace/v2", "sanning.anchor.trace/v1"];
-export declare const EXPORT_BODY_TYPE = "sanning.evidence.export/v1";
+export declare const LEGACY_EVENT_BYTES_FIELD = "record_bytes";
+export declare const EXPORT_BODY_TYPE = "sanning.evidence.export/v2";
 /**
  * The Sanning-signed interval stamp body (evidence-bundle.md §5.2, DL-58).
  *
  * Its own `body_type` rather than a widened anchor-trace body, and the reason
  * is the whole decision: an anchor-trace checkpoint carries a PRODUCER-signed
- * `sanning.events/v1` envelope, and a stamp has no producer signature at all —
+ * `sanning.events/v2` envelope, and a stamp has no producer signature at all:
  * Sanning places it, under DL-52, for a customer who holds no chain identity.
  * The two rejected options were making `envelope` optional and synthesising an
  * envelope that Sanning signs; the second would have made a Sanning
@@ -25,7 +22,7 @@ export declare const EXPORT_BODY_TYPE = "sanning.evidence.export/v1";
  * unrecoverable once witnessed.
  */
 export declare const STAMP_TRACE_BODY_TYPE = "sanning.stamp.trace/v1";
-export declare const STAMP_EVIDENCE_BODY_TYPE = "sanning.stamp.evidence/v1";
+export declare const STAMP_EVIDENCE_BODY_TYPE = "sanning.stamp.evidence/v2";
 /**
  * The version string INSIDE a witnessed stamp body — a different string from
  * the `body_type` above, and the two are easy to confuse.
@@ -42,7 +39,6 @@ export interface EvidenceIssuer {
     kind: string;
     tenant_id?: string;
     agent_id?: string;
-    producer_id?: string;
     [k: string]: unknown;
 }
 export interface EvidenceVerdict {
@@ -71,9 +67,8 @@ export interface AnchorRef {
 export interface TraceCheckpoint {
     /**
      * The checkpoint's identity and the join key, DERIVED: hex SHA-256 of the
-     * decoded `record_bytes`. Recomputed by the verifier — in v1 this was an
-     * asserted label matched against another asserted label, so a producer could
-     * relabel a checkpoint and the bundle still verified.
+     * decoded `event_bytes`. Recomputed by the verifier, never taken from the
+     * label.
      */
     checkpoint_ref: string;
     /**
@@ -83,14 +78,7 @@ export interface TraceCheckpoint {
      */
     anchor_ref?: AnchorRef;
     envelope: Envelope;
-    record_bytes: string;
-    merkle_root: string;
-}
-/** The frozen `sanning.anchor.trace/v1` checkpoint (§5.1.3). Read, never written. */
-export interface TraceCheckpointV1 {
-    tx_id: string;
-    envelope: Envelope;
-    record_bytes: string;
+    event_bytes: string;
     merkle_root: string;
 }
 export interface TraceInclusion {
@@ -98,12 +86,12 @@ export interface TraceInclusion {
     leaf_index: number;
     leaf_count: number;
     audit_path: string[];
-    /** Resolves against `checkpoints[].checkpoint_ref`. v1 spells this `checkpoint_tx_id`. */
+    /** Resolves against `checkpoints[].checkpoint_ref`. */
     checkpoint_ref: string;
 }
 export interface TraceEvent {
     envelope: Envelope;
-    record_bytes?: string;
+    event_bytes?: string;
     content?: string;
     inclusion: TraceInclusion;
 }
@@ -174,7 +162,7 @@ export interface StampEvidenceInclusion {
 }
 export interface StampEvidenceEvent {
     envelope: Envelope;
-    record_bytes?: string;
+    event_bytes?: string;
     content?: string;
     inclusion: StampEvidenceInclusion;
 }
@@ -211,23 +199,12 @@ export interface OnChainResult {
     perGateway: PerGatewayOutcome[];
 }
 export interface CheckpointResult {
-    /**
-     * The checkpoint's join key AS THE BUNDLE SPELLS IT — the derived
-     * `checkpoint_ref` for a v2 body, the legacy `tx_id` for a frozen v1 body.
-     * Never re-derived across forms: a v1 bundle's key is its `tx_id`, because
-     * that is what its own events resolve against and what an attestation
-     * written against it carries.
-     */
+    /** The derived `checkpoint_ref`, empty when it could not be derived. */
     checkpointRef: string;
     /**
-     * Where this checkpoint was witnessed, normalised to one shape.
-     *
-     * `null` when a v2 checkpoint carries no `anchor_ref` — placed but not yet
-     * witnessed, which is a normal state and NOT a deficiency. For a frozen v1
-     * checkpoint this is synthesised as `{ kind: "arweave", id: tx_id }`, which
-     * is exactly what v1's spec said the field was ("the Arweave TX the
-     * checkpoint envelope was anchored as"). The synthesis is reader-side only
-     * and never re-enters a signed artifact or a verdict.
+     * Where this checkpoint was witnessed. `null` when the checkpoint carries no
+     * `anchor_ref`: placed but not yet witnessed, which is a normal state and NOT
+     * a deficiency.
      */
     anchorRef: AnchorRef | null;
     envelopeOk: boolean;
@@ -299,12 +276,14 @@ export interface StampResult {
      * ── The four states, and why none of them collapses ──
      *
      * `null` means not checked — no gateways were supplied, or this stamp names
-     * no witness to check. It is a statement about the RUN, never about the
-     * stamp. The other three are statements about the stamp and live in
-     * `onChain.rollup`: `confirm` (a gateway returned the witnessed bytes),
-     * `mismatch` (a gateway returned DIFFERENT bytes — a finding, and the only
-     * one of the four that fails anything), `unreachable` (we asked and nobody
-     * answered — an availability gap, never an accusation).
+     * no witness to check, or its `anchor_ref.kind` has no witness adapter, or
+     * its id is not one the adapter accepts; the witness was not checked. It is
+     * a statement about the RUN, never about the stamp. The other three are
+     * statements about the stamp and live in `onChain.rollup`: `confirm` (a
+     * gateway returned the witnessed bytes), `mismatch` (a gateway returned
+     * DIFFERENT bytes: a finding, and the only one of the four that fails
+     * anything), `unreachable` (we asked and nobody answered: an availability
+     * gap, never an accusation).
      *
      * Keeping "not checked" distinct from "unreachable" is the whole point. A
      * surface handed a collapsed boolean cannot tell "no gateway could be
@@ -339,11 +318,7 @@ export interface EvidenceBundleResult {
     errors: string[];
 }
 export interface AttestationRecord {
-    /**
-     * The source checkpoint this attestation binds to, spelled in the SOURCE
-     * bundle's vocabulary: `checkpoint_ref` for a v2 source, the legacy `tx_id`
-     * for a frozen v1 one. Not re-derived across forms.
-     */
+    /** The source checkpoint's derived `checkpoint_ref` this attestation binds to. */
     checkpoint_ref: string;
     payload: AttestationPayload;
     signature_alg: string;