@sanning/proof 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanning Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# @sanning/proof
+
+Verify Sanning evidence-plane provenance records — **with no Sanning code or service in the trust path**.
+
+This is the TypeScript verification kernel for the *Verifiable Event Envelope* family: the signed JSON records that producers such as the verification agent daemon and the MLflow plugin anchor permanently to Arweave. Given an envelope (fetched from any Arweave gateway), this package answers: *is it authentic, and does it commit to the bytes I'm holding?*
+
+- **RFC 8785 (JCS)** canonicalization
+- **SHA-256** payload binding (WebCrypto)
+- **Ed25519** signature verification ([`@noble/ed25519`](https://github.com/paulmillr/noble-ed25519))
+- **RFC 9162** binary Merkle inclusion proofs (checkpoint leaves)
+- Zero config, two small dependencies, ESM, browser + Node ≥ 20
+
+## Install
+
+```bash
+npm install @sanning/proof
+```
+
+## Verify an envelope
+
+Fetch the raw transaction from any Arweave gateway and verify it client-side:
+
+```ts
+import { verifyEnvelope } from "@sanning/proof";
+
+const env = await (await fetch("https://arweave.net/raw/<tx_id>")).json();
+const result = await verifyEnvelope(env);
+
+result.ok;            // spec_version + payload_hash + Ed25519 all passed
+result.signatureOk;   // Ed25519 over the signed scope, against env.public_key
+result.payloadHashOk; // SHA-256(JCS(payload)) === env.payload_hash
+result.errors;        // [] when ok — machine-readable reasons otherwise
+```
+
+`verifyEnvelope` never throws on hostile input — a malformed envelope (or a lying gateway) yields `ok: false` with reasons, not an exception.
+
+## Bind an envelope to bytes you hold (reverse provenance)
+
+The check that defeats a lying gateway: Arweave *tags* are unsigned search hints, so after finding a candidate envelope, confirm it actually commits to your artifact's hash:
+
+```ts
+import { sha256Hex, verifyEnvelope, contentHashes } from "@sanning/proof";
+
+const myHash = await sha256Hex(fileBytes); // 64-char lowercase hex
+
+const result = await verifyEnvelope(env, myHash);
+result.contentHashOk; // true ⇔ the envelope commits to exactly these bytes
+result.contentRole;   // how it commits: e.g. the registered baseline,
+                      // an observed (tampered) hash, …
+
+contentHashes(env);   // all content hashes an envelope commits to, by event type
+```
+
+## Verify a whole trace bundle — one command
+
+The `@ar.io/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:
+
+```bash
+npx @sanning/proof verify trace-bundle.json
+# also re-fetch each checkpoint on-chain to confirm it's anchored:
+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.
+
+> The `verify` CLI is live in `@sanning/proof` ≥ 0.2.2 — `npx @sanning/proof verify <bundle> [gateways]`. `verifyEvidenceBundle` is the programmatic API.
+
+Programmatically:
+
+```ts
+import { verifyEvidenceBundle } from "@sanning/proof";
+
+const bundle = JSON.parse(await fs.readFile("trace-bundle.json", "utf8"));
+const result = await verifyEvidenceBundle(bundle, { gateways: ["https://arweave.net"] });
+
+result.status;       // "verified" | "partial" | "failed" | "malformed" (recomputed)
+result.signatureOk;  // wrapper Ed25519 signature
+result.bodyHashOk;   // body_hash === SHA-256(JCS(body))
+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).
+
+### …including the raw logs, when the holder discloses them
+
+The checks above prove the *stamps*. To also confirm a holder's **raw logs are the bytes whose hash was anchored**, the verifier closes the final `rawLog → content_hash` link: `SHA-256(disclosed bytes)` must equal the `content_hash` the event's record committed to.
+
+A bundle a producer built with disclosure carries the bytes **in the signed body** (`events[].content`), so they're checked automatically — no flag, and the disclosure is itself covered by the wrapper signature:
+
+```bash
+npx @sanning/proof verify trace-bundle.json          # in-body content verified inline
+```
+
+If the logs travel **alongside** a minimal bundle instead, pass them with `--logs` — a JSON object mapping `event_id` → bytes, where an even-length lowercase-hex string is read as hex and anything else as UTF-8 text:
+
+```bash
+npx @sanning/proof verify trace-bundle.json --logs logs.json
+```
+
+Either way each event gains a `contentOk`: **`true`** match · **`false`** mismatch (the event *and* the rollup fail, exit `1`) · **`null`** undetermined — nothing disclosed, or no committed `content_hash` (a withheld record); never a failure, mirroring the payload-binding rule. The CLI prints a `logs ✓/✗/~` mark per event and a `logs: N/M disclosed verified` line.
+
+Programmatically the same side input is `content`, keyed by `event_id` — a `Uint8Array` is used as-is, a `string` is hex:
+
+```ts
+const result = await verifyEvidenceBundle(bundle, {
+  content: { [eventId]: rawLogBytes }, // Uint8Array, or a hex string
+});
+result.events[0].contentOk; // true | false | null
+```
+
+In-body `events[].content` (signed) takes precedence over the side input; if both are present for an event and disagree, the event fails.
+
+## Verify a Merkle inclusion proof
+
+Agents close daily checkpoints over per-cycle leaves (RFC 9162, §2.1 domain separation — not the Bitcoin duplicate-leaf variant). Verify a leaf's inclusion against an anchored root:
+
+```ts
+import { leafHash, verifyInclusion, hexToBytes } from "@sanning/proof";
+
+const ok = await verifyInclusion(
+  await leafHash(leafBytes), // Uint8Array leaf hash
+  leafIndex,                 // 0-based position
+  totalLeaves,
+  auditPath.map(hexToBytes), // sibling hashes, leaf → root
+  hexToBytes(expectedRootHex),
+);
+```
+
+## API
+
+| 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. |
+| `verifyAgentProofBundle(bundle, { gateways?, fetchImpl? })` / `isAgentProofSpec(v)` | Verify the agent producer's `sanning.agent.proof/v1` inclusion bundle. |
+| `contentHashes(env)` | The content hash(es) an envelope commits to, by event type — the reverse-provenance join keys. |
+| `specVersionSupported(v)` | Fail-closed accept-check: `sanning.agent/v1` and additive minors (`sanning.agent/v1.<n>`). Unknown majors/profiles are rejected. |
+| `jcs(value)` | RFC 8785 canonical JSON bytes. |
+| `sha256Hex(bytes)` / `sha256Bytes(bytes)` | SHA-256 via WebCrypto. |
+| `ed25519Verify(sig, msg, pubKey)` | Raw Ed25519 verification. |
+| `leafHash` / `nodeHash` / `merkleRoot` / `auditPath` / `verifyInclusion` / `EMPTY_TREE_ROOT_HEX` | RFC 9162 binary Merkle tree primitives. |
+| `utf8` / `bytesToHex` / `hexToBytes` | Encoding helpers. |
+| `Envelope` / `VerificationResult` / `ContentRole` / `Subject` | Types. |
+
+### Signed scope
+
+The primary signature covers `JCS(envelope minus signature minus co_signatures)` ([envelope-spec](https://github.com/sanning-io/proof/blob/main/specs/envelope-spec.md) §2/§7.1). The reserved `co_signatures` carve-out lets countersignatures be added later without invalidating the primary signature.
+
+## 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 the MIT-licensed Go reference, vendored into this repo under [`cross-kernel/vendor-agent/`](https://github.com/sanning-io/proof/tree/main/cross-kernel/vendor-agent) so anyone can build and run it. The TypeScript and Python kernels are conformance-gated **byte-for-byte** in CI against the shared [`test-vectors` corpus](https://github.com/sanning-io/proof/tree/main/test-vectors) (per-file SHA-256 pins; current cut tag `test-vectors-v2.0`), and the [cross-kernel agreement gate](https://github.com/sanning-io/proof/tree/main/cross-kernel) 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 [public specs](https://github.com/sanning-io/proof/tree/main/specs) and the corpus will tell you if it's conformant.
+
+## What this package deliberately does NOT do
+
+- **Single-envelope scope.** Chain walking (`previous_hash`), checkpoint reconciliation, and gateway/transport logic are consumer-layer concerns composed above the kernel.
+- **Provenance is history, not endorsement.** A verified envelope proves *these bytes have this signed, anchored history* — never "safe," "approved," or "currently in production."
+- **Key identity is out-of-band.** The kernel proves the signature matches `env.public_key`; binding that key to a real-world identity is yours to establish.
+
+## Requirements
+
+ESM-only. Needs WebCrypto (`globalThis.crypto.subtle`): any modern browser, Node.js ≥ 20 (≥ 19 works), Deno, Bun, workers.
+
+## License
+
+MIT — verification must be open.

package/dist/agent-proof.d.ts

@@ -0,0 +1,28 @@
+import type { Envelope } from "./types.js";
+export declare const AGENT_PROOF_SPEC_PREFIX = "sanning.agent.proof/v1";
+export interface AgentProofBundle {
+    spec_version: string;
+    checkpoint_envelope: Envelope;
+    checkpoint_tx_id: string;
+    leaf: Record<string, unknown>;
+    leaf_index: number;
+    audit_path: string[];
+    [k: string]: unknown;
+}
+export interface AgentProofResult {
+    status: "verified" | "failed" | "partial" | "malformed";
+    checkpointOk: boolean;
+    inclusionOk: boolean;
+    onChainOk: boolean | null;
+    onChainChecked: boolean;
+    leafIndex: number;
+    leafCount: number | null;
+    checkpointTxId: string | null;
+    errors: string[];
+}
+export interface VerifyAgentProofOptions {
+    gateways?: string[];
+    fetchImpl?: typeof fetch;
+}
+export declare function isAgentProofSpec(specVersion: unknown): boolean;
+export declare function verifyAgentProofBundle(bundle: unknown, options?: VerifyAgentProofOptions): Promise<AgentProofResult>;

package/dist/agent-proof.js

@@ -0,0 +1,188 @@
+// Agent inclusion-proof bundle verification.
+//
+// The `sanning.agent.proof/v1` bundle is the agent's ~1.4 KB self-contained
+// inclusion proof: a signed checkpoint envelope (sanning.agent/v1, INLINE payload)
+// plus a single leaf object and its RFC 9162 audit path. Verifying it is the
+// inverse of `sanningd proof`. The CLI sniffs `spec_version` and routes here so
+// ONE verifier covers both the agent (this) and the anchor SDK (evidence.ts).
+//
+// Algorithm:
+//   1. Verify the checkpoint envelope (signature + inline payload_hash bind).
+//   2. leaf_hash = SHA-256(0x00 || JCS(leaf)).
+//   3. Walk audit_path with leaf_index + leaf_count (from the checkpoint
+//      payload) to reconstruct the root.
+//   4. Confirm the reconstructed root == checkpoint_envelope.payload.merkle_root.
+//   5. (optional) Re-fetch checkpoint_tx_id from a gateway and byte-compare.
+import { hexToBytes, utf8 } from "./crypto.js";
+import { leafHash, verifyInclusion } from "./merkle.js";
+import { MAX_CANONICAL_DEPTH, exceedsDepth, jcs, verifyEnvelope } from "./verifier.js";
+export const AGENT_PROOF_SPEC_PREFIX = "sanning.agent.proof/v1";
+function stringifyErr(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function toHex(bytes) {
+    let out = "";
+    for (const x of bytes)
+        out += x.toString(16).padStart(2, "0");
+    return out;
+}
+export function isAgentProofSpec(specVersion) {
+    if (typeof specVersion !== "string")
+        return false;
+    return specVersion === AGENT_PROOF_SPEC_PREFIX || specVersion.startsWith(`${AGENT_PROOF_SPEC_PREFIX}.`);
+}
+export async function verifyAgentProofBundle(bundle, options = {}) {
+    const fail = (error) => ({
+        status: "malformed",
+        checkpointOk: false,
+        inclusionOk: false,
+        onChainOk: null,
+        onChainChecked: false,
+        leafIndex: -1,
+        leafCount: null,
+        checkpointTxId: null,
+        errors: [error],
+    });
+    if (bundle === null || typeof bundle !== "object" || Array.isArray(bundle)) {
+        return fail("agent proof bundle is not a JSON object");
+    }
+    // Bound nesting before any canonicalization (checkpoint envelope + Merkle
+    // leaves are canonicalized recursively) — a fixed shared limit keeps this a
+    // `malformed` verdict in every kernel. See MAX_CANONICAL_DEPTH.
+    if (exceedsDepth(bundle, MAX_CANONICAL_DEPTH)) {
+        return fail(`agent proof bundle nesting exceeds the ${MAX_CANONICAL_DEPTH}-level canonicalization depth bound`);
+    }
+    const b = bundle;
+    if (!isAgentProofSpec(b.spec_version)) {
+        return fail(`unsupported agent-proof spec_version: ${JSON.stringify(b.spec_version)}`);
+    }
+    if (b.checkpoint_envelope === null || typeof b.checkpoint_envelope !== "object") {
+        return fail("agent proof bundle missing checkpoint_envelope");
+    }
+    if (b.leaf === null || typeof b.leaf !== "object") {
+        return fail("agent proof bundle missing leaf");
+    }
+    if (!Array.isArray(b.audit_path)) {
+        return fail("agent proof bundle missing audit_path[]");
+    }
+    const errors = [];
+    // Step 1: verify the checkpoint envelope (inline payload — no payloadBytes).
+    let checkpointOk = false;
+    let merkleRoot;
+    let leafCount;
+    try {
+        const res = await verifyEnvelope(b.checkpoint_envelope);
+        checkpointOk = res.ok && res.payloadHashOk === true;
+        if (!res.signatureOk)
+            errors.push("checkpoint envelope signature failed");
+        if (res.payloadHashOk !== true)
+            errors.push("checkpoint envelope payload binding failed");
+        const payload = (b.checkpoint_envelope.payload ?? {});
+        if (typeof payload.merkle_root === "string")
+            merkleRoot = payload.merkle_root;
+        if (typeof payload.leaf_count === "number")
+            leafCount = payload.leaf_count;
+        if (merkleRoot === undefined)
+            errors.push("checkpoint payload missing merkle_root");
+        if (leafCount === undefined)
+            errors.push("checkpoint payload missing leaf_count");
+    }
+    catch (e) {
+        errors.push(`checkpoint verify error: ${stringifyErr(e)}`);
+    }
+    // Steps 2-4: leaf hash, audit-path walk, root match.
+    let inclusionOk = false;
+    if (merkleRoot !== undefined && leafCount !== undefined) {
+        try {
+            const lh = await leafHash(utf8(jcs(b.leaf)));
+            inclusionOk = await verifyInclusion(lh, b.leaf_index, leafCount, b.audit_path.map((h) => hexToBytes(h)), hexToBytes(merkleRoot));
+            if (!inclusionOk)
+                errors.push("RFC 9162 inclusion proof did not reconstruct merkle_root");
+        }
+        catch (e) {
+            errors.push(`inclusion verify error: ${stringifyErr(e)}`);
+        }
+    }
+    // Step 5: optional on-chain re-fetch.
+    const gateways = options.gateways ?? [];
+    const onChainChecked = gateways.length > 0;
+    let onChainOk = null;
+    let gatewayUnavailable = false;
+    if (onChainChecked) {
+        const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        if (typeof fetchImpl !== "function") {
+            gatewayUnavailable = true;
+            errors.push("on-chain re-fetch requested but no fetch implementation is available");
+        }
+        else {
+            const outcome = await refetch(b.checkpoint_envelope, b.checkpoint_tx_id, gateways, fetchImpl);
+            onChainOk = outcome.ok;
+            if (outcome.unavailable)
+                gatewayUnavailable = true;
+            if (outcome.error)
+                errors.push(outcome.error);
+        }
+    }
+    let status;
+    if (!checkpointOk || !inclusionOk || onChainOk === false) {
+        status = "failed";
+    }
+    else if (gatewayUnavailable) {
+        status = "partial";
+    }
+    else {
+        status = "verified";
+    }
+    return {
+        status,
+        checkpointOk,
+        inclusionOk,
+        onChainOk,
+        onChainChecked,
+        leafIndex: typeof b.leaf_index === "number" ? b.leaf_index : -1,
+        leafCount: leafCount ?? null,
+        checkpointTxId: typeof b.checkpoint_tx_id === "string" ? b.checkpoint_tx_id : null,
+        errors,
+    };
+}
+async function refetch(envelope, txId, gateways, fetchImpl) {
+    let expectedHex;
+    try {
+        expectedHex = toHex(utf8(jcs(envelope)));
+    }
+    catch (e) {
+        return { ok: false, unavailable: false, error: `cannot canonicalize checkpoint envelope: ${stringifyErr(e)}` };
+    }
+    let anyReachable = false;
+    for (const gw of gateways) {
+        const url = `${gw.replace(/\/+$/, "")}/${txId}`;
+        try {
+            const resp = await fetchImpl(url);
+            if (!resp.ok)
+                continue;
+            anyReachable = true;
+            const onChain = new Uint8Array(await resp.arrayBuffer());
+            if (toHex(onChain) === expectedHex)
+                return { ok: true, unavailable: false };
+            try {
+                const parsed = JSON.parse(new TextDecoder().decode(onChain));
+                if (toHex(utf8(jcs(parsed))) === expectedHex)
+                    return { ok: true, unavailable: false };
+            }
+            catch {
+                // fall through
+            }
+            return {
+                ok: false,
+                unavailable: false,
+                error: `on-chain bytes at ${txId} do not match the checkpoint envelope`,
+            };
+        }
+        catch {
+            // try next gateway
+        }
+    }
+    if (anyReachable)
+        return { ok: false, unavailable: false, error: `checkpoint ${txId} mismatched on every gateway` };
+    return { ok: null, unavailable: true, error: `checkpoint ${txId} unreachable on all gateways` };
+}

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+interface Cli {
+    out: (s: string) => void;
+    err: (s: string) => void;
+    fetchImpl?: typeof fetch;
+}
+export declare function runCli(argv: string[], io: Cli): Promise<number>;
+export {};