@sanning/proof 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { ACCEPTED_SPEC_MAJORS, contentHashes, jcs, specVersionSupported, verifyEnvelope, } from "./verifier.js";
+export { bytesToHex, deriveOperatorAddress, ed25519Verify, hexToBytes, sha256Bytes, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
+export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyInclusion, } from "./merkle.js";
+export type { ContentRole, Envelope, Subject, VerificationResult, VerifyOptions } from "./types.js";
+export { ANCHOR_TRACE_BODY_TYPE, EXPORT_BODY_TYPE, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
+export type { AnchorTraceBody, AttestationPayload, AttestationRecord, AttestationResult, CheckpointResult, ComposeVerdictResult, EvidenceBundle, EvidenceBundleResult, EvidenceIssuer, EvidenceStatus, EvidenceVerdict, EventResult, ExportBody, ExportResult, OnChainOutcome, OnChainResult, PerGatewayOutcome, TraceCheckpoint, TraceEvent, TraceInclusion, VerdictAttestation, VerdictCheckpoint, VerdictEvent, VerdictObject, VerdictOnChain, VerdictOnChainGateway, VerifyEvidenceOptions, } from "./evidence.js";
+export { attestationSignatureToHex, composeExport } from "./compose.js";
+export type { ComposeExportOptions, ComposeExportResult, ExporterKey } from "./compose.js";
+export { AGENT_PROOF_SPEC_PREFIX, isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
+export type { AgentProofBundle, AgentProofResult, VerifyAgentProofOptions, } from "./agent-proof.js";

package/dist/index.js

@@ -0,0 +1,38 @@
+// @sanning/proof — TypeScript kernel of the Sanning verification stack.
+//
+// The verification primitives for the Verifiable Event Envelope family
+// (specs/envelope-spec.md), sanning.agent/v1 profile: RFC 8785 (JCS)
+// canonicalization, SHA-256, Ed25519 envelope verification, and the
+// content-hash extraction used for reverse provenance lookup. Sibling of the
+// Python `sanning-proof` kernel and the Go `pkg/proof` reference; conformance
+// is byte-for-byte against the shared `test-vectors/` corpus.
+//
+// Scope boundary (envelope-spec §10 #13): this package verifies a SINGLE
+// envelope. Chain walking (previous_hash), checkpoint reconciliation, and
+// gateway/transport concerns are consumer-layer logic composed above it.
+// ACCEPTED_SPEC_MAJORS is exported for parity with the sibling kernels'
+// registries (Python ACCEPTED_SPEC_VERSIONS, Go SupportedSpecMajor): a consumer
+// can see which profiles this build admits without inferring it from probe
+// calls. It is frozen at its definition (`Object.freeze`, typed
+// `readonly string[]`) because the verifier reads that same array — an exported
+// mutable accept-set would be a runtime-widenable kernel. Additive — no
+// existing export changes.
+export { ACCEPTED_SPEC_MAJORS, contentHashes, jcs, specVersionSupported, verifyEnvelope, } from "./verifier.js";
+export { bytesToHex, deriveOperatorAddress, ed25519Verify, hexToBytes, sha256Bytes, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
+export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyInclusion, } from "./merkle.js";
+// Evidence-bundle verification (specs/evidence-bundle.md): the signed
+// sanning.evidence/v1 wrapper carrying the sanning.anchor.trace/v1 body. The CLI
+// (`npx @sanning/proof verify`) is built on this. The same path dispatches on the
+// issuer-composed sanning.evidence.export/v1 body (specs/evidence-export.md) to
+// verifyExportBody (embedded RSA-PSS operator attestations + a recomputed §4
+// verdict object with per-gateway on-chain outcomes).
+export { ANCHOR_TRACE_BODY_TYPE, EXPORT_BODY_TYPE, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.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
+// inverse of verifyEvidenceBundle's verifyExportBody dispatch.
+export { attestationSignatureToHex, composeExport } from "./compose.js";
+// Agent inclusion-proof bundle verification: the
+// sanning.agent.proof/v1 bundle. The CLI sniffs spec_version and routes here so
+// one verifier covers both agent and anchor bundles.
+export { AGENT_PROOF_SPEC_PREFIX, isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";

package/dist/merkle.d.ts

@@ -0,0 +1,6 @@
+export declare const EMPTY_TREE_ROOT_HEX = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+export declare function leafHash(leafBytes: Uint8Array): Promise<Uint8Array>;
+export declare function nodeHash(left: Uint8Array, right: Uint8Array): Promise<Uint8Array>;
+export declare function merkleRoot(leafHashes: Uint8Array[]): Promise<Uint8Array>;
+export declare function auditPath(m: number, leafHashes: Uint8Array[]): Promise<Uint8Array[]>;
+export declare function verifyInclusion(leaf: Uint8Array, leafIndex: number, totalLeaves: number, auditPath: Uint8Array[], expectedRoot: Uint8Array): Promise<boolean>;

package/dist/merkle.js

@@ -0,0 +1,114 @@
+// RFC 9162 binary Merkle tree — build, audit paths, inclusion verification.
+//
+// A faithful port of the Go reference (the agent producer's pkg/merkle), in lockstep
+// with the Python kernel's sanning_proof.merkle. All hashing is SHA-256 with
+// RFC 9162 §2.1 domain separation: leaves prefixed 0x00, interior nodes 0x01.
+// A tree of n leaves splits into a left subtree of k leaves (the largest
+// power of two < n) and a right subtree of n−k — NOT the Bitcoin
+// duplicate-last-leaf variant, which produces different roots for
+// non-power-of-two leaf counts.
+//
+// The empty tree (zero leaves) hashes to SHA-256("") — EMPTY_TREE_ROOT_HEX.
+// Conformance is byte-for-byte against the 7 merkle-tree-* vectors of
+// test-vectors-v1.0 (test/conformance.test.ts).
+import { sha256Bytes } from "./crypto.js";
+export const EMPTY_TREE_ROOT_HEX = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+// SHA-256(0x00 || leafBytes) per RFC 9162 §2.1.
+export async function leafHash(leafBytes) {
+    return sha256Bytes(prefixed(0x00, leafBytes));
+}
+// SHA-256(0x01 || left || right) per RFC 9162 §2.1.
+export async function nodeHash(left, right) {
+    const buf = new Uint8Array(1 + left.length + right.length);
+    buf[0] = 0x01;
+    buf.set(left, 1);
+    buf.set(right, 1 + left.length);
+    return sha256Bytes(buf);
+}
+// The RFC 9162 Merkle Tree Hash of already-hashed leaves. Callers pass leaf
+// hashes — the output of leafHash on each leaf's canonical bytes. Zero leaves
+// yields SHA-256("").
+export async function merkleRoot(leafHashes) {
+    const n = leafHashes.length;
+    if (n === 0)
+        return sha256Bytes(new Uint8Array(0));
+    if (n === 1)
+        return leafHashes[0];
+    const k = largestPow2LessThan(n);
+    return nodeHash(await merkleRoot(leafHashes.slice(0, k)), await merkleRoot(leafHashes.slice(k)));
+}
+// The inclusion proof for the leaf at index m, per RFC 9162 §2.1.3: sibling
+// hashes bottom-up; empty for a single-leaf tree (the leaf hash itself is the
+// root). Throws RangeError when m is out of range.
+export async function auditPath(m, leafHashes) {
+    if (!Number.isInteger(m) || m < 0 || m >= leafHashes.length) {
+        throw new RangeError("merkle: leaf index out of range");
+    }
+    return path(m, leafHashes);
+}
+async function path(m, leafHashes) {
+    const n = leafHashes.length;
+    if (n === 1)
+        return [];
+    const k = largestPow2LessThan(n);
+    if (m < k) {
+        return [...(await path(m, leafHashes.slice(0, k))), await merkleRoot(leafHashes.slice(k))];
+    }
+    return [...(await path(m - k, leafHashes.slice(k))), await merkleRoot(leafHashes.slice(0, k))];
+}
+// Verify an RFC 9162 §2.1.3 inclusion proof. `leaf` is the leaf hash
+// (leafHash of the canonical leaf bytes); `path` is the audit path bottom-up;
+// `expectedRoot` is the merkleRoot committed by the checkpoint envelope.
+// True iff the path reconstructs the expected root. Never throws.
+export async function verifyInclusion(leaf, leafIndex, totalLeaves, auditPath, expectedRoot) {
+    if (!Number.isInteger(leafIndex) || leafIndex < 0 || totalLeaves <= 0 || leafIndex >= totalLeaves) {
+        return false;
+    }
+    if (totalLeaves === 1)
+        return auditPath.length === 0 && bytesEqual(leaf, expectedRoot);
+    let fn = leafIndex;
+    let sn = totalLeaves - 1;
+    let r = leaf;
+    for (const p of auditPath) {
+        if (sn === 0)
+            return false; // path longer than the tree depth — malformed
+        if ((fn & 1) === 1 || fn === sn) {
+            r = await nodeHash(p, r);
+            if ((fn & 1) === 0) {
+                while ((fn & 1) === 0 && fn !== 0) {
+                    fn >>= 1;
+                    sn >>= 1;
+                }
+            }
+        }
+        else {
+            r = await nodeHash(r, p);
+        }
+        fn >>= 1;
+        sn >>= 1;
+    }
+    return sn === 0 && bytesEqual(r, expectedRoot);
+}
+function prefixed(prefix, bytes) {
+    const buf = new Uint8Array(1 + bytes.length);
+    buf[0] = prefix;
+    buf.set(bytes, 1);
+    return buf;
+}
+// Largest k = 2**a with k < n (0 for n < 2).
+function largestPow2LessThan(n) {
+    if (n < 2)
+        return 0;
+    let k = 1;
+    while (k * 2 < n)
+        k *= 2;
+    return k;
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}

package/dist/types.d.ts

@@ -0,0 +1,34 @@
+export interface Subject {
+    type: string;
+    tenant_id?: string;
+    agent_id?: string;
+}
+export interface Envelope {
+    spec_version: string;
+    event_id: string;
+    payload_hash: string;
+    signed_at: string;
+    public_key: string;
+    signature: string;
+    payload?: Record<string, unknown>;
+    event_type?: string;
+    subject?: Subject;
+    previous_hash?: string;
+    environment?: string;
+    payload_ref?: string;
+    co_signatures?: unknown[];
+}
+export type ContentRole = "asset" | "baseline" | "observed";
+export interface VerifyOptions {
+    payloadBytes?: Uint8Array;
+    expectedContentHash?: string;
+}
+export interface VerificationResult {
+    ok: boolean;
+    specVersionOk: boolean;
+    payloadHashOk: boolean | null;
+    signatureOk: boolean;
+    contentHashOk: boolean | null;
+    contentRole: ContentRole | null;
+    errors: string[];
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+// Wire types for Sanning Verifiable Event Envelopes (sanning-io/proof
+// specs/envelope-spec.md). We model only the fields the verifier consumes;
+// unknown fields are preserved by structural typing (envelopes are verified
+// over their canonical bytes, not this interface).
+export {};

package/dist/verifier.d.ts

@@ -0,0 +1,11 @@
+import type { ContentRole, Envelope, VerificationResult, VerifyOptions } from "./types.js";
+export declare const ACCEPTED_SPEC_MAJORS: readonly string[];
+export declare const MAX_CANONICAL_DEPTH = 128;
+export declare function exceedsDepth(value: unknown, max: number): boolean;
+export declare function jcs(value: unknown): string;
+export declare function specVersionSupported(specVersion: string): boolean;
+export declare function contentHashes(env: Envelope): {
+    role: ContentRole;
+    hash: string;
+}[];
+export declare function verifyEnvelope(env: Envelope, optionsOrContentHash?: string | VerifyOptions): Promise<VerificationResult>;

package/dist/verifier.js

@@ -0,0 +1,321 @@
+// Independent client-side implementation of the envelope verification
+// algorithm (specs/envelope-spec.md). This is deliberately a second
+// implementation of the same algorithm the Go kernel runs — a second,
+// conformance-tested verifier is what demonstrates the product's claim:
+// verification needs no Sanning code in the trust path.
+//
+// Conformance is enforced by test/conformance.test.ts, which runs every
+// corpus test vector through this code and asserts byte-for-byte agreement.
+import canonicalize from "canonicalize";
+import { ed25519Verify, sha256Hex, utf8 } from "./crypto.js";
+// Fail-closed accepted-profile registry (envelope-spec §2): exactly the
+// accepted profile majors, nothing else. Minors within an accepted
+// major ("sanning.agent/v1.<minor>") are additive and tolerated — matching the Go
+// reference kernel's semantics (pkg/proof isSupportedSpec) so the kernels do
+// not diverge on minors. Accepting a new profile is a deliberate one-entry
+// addition HERE and only here. sanning.events/v1 (external commitment + Minimal
+// disclosure; envelope-spec §4) is verified through the SAME primitives — the
+// signed scope is still envelope-minus-signature-minus-co_signatures, with no
+// profile-specific dialect (no underscore strip, that is mlflow-only).
+//
+// Exported for parity with the sibling kernels' registries — Python
+// `ACCEPTED_SPEC_VERSIONS`, Go `SupportedSpecMajor` — so the accept-set is
+// assertable rather than inferable: test/accept-set.test.ts holds it to the
+// ratified §4/§5 set transcribed in cross-kernel/accept-set.json, and the
+// cross-kernel gate probes one signed envelope per identifier. This entry list
+// is NOT the ratified accept-set today: sanning.mlflow/v1 is in the ratified
+// set and absent here, an escalated divergence (cross-kernel/README.md
+// § Known divergences) whose resolution is a founder decision, not an edit.
+//
+// FROZEN, and that is load-bearing, not hygiene: `specVersionSupported` (and
+// therefore `verifyEnvelope`) reads THIS array, so an exported mutable one
+// would let any code sharing the module instance widen the accept-set of a
+// running verifier — `ACCEPTED_SPEC_MAJORS.push("x/v1")` and the kernel starts
+// admitting `x/v1`. `Object.freeze` makes that throw (the package is ESM, so
+// always strict mode) and the `readonly string[]` type rejects it at compile
+// time. The elements are strings, so a shallow freeze is a deep one. Pinned by
+// test/accept-set.test.ts "the exported registry cannot be widened at runtime".
+export const ACCEPTED_SPEC_MAJORS = Object.freeze([
+    "sanning.agent/v1",
+    "sanning.events/v1",
+]);
+// Maximum JSON container-nesting depth a verifier will canonicalize. Inputs
+// nested deeper are rejected as malformed BEFORE canonicalization runs. This is
+// a NORMATIVE cross-kernel invariant (envelope-spec §2 shared-invariant 7): the
+// bound must be the same fixed constant in every kernel. Without it, a
+// deeply-nested body one kernel canonicalizes on its large native stack while
+// another hits its recursion limit (CPython defaults to ~1000 frames) yields a
+// split verdict — the same bytes reported `verified`/`failed` by one kernel and
+// crash/`malformed` by another, on a depth the producer of the bytes fully
+// controls. 128 is >10x any legitimate evidence structure (which nests <15) and
+// safely under the tightest kernel recursion limit, with headroom for the JCS
+// library's own frames-per-level. Mirrors the Python kernel's MAX_CANONICAL_DEPTH.
+export const MAX_CANONICAL_DEPTH = 128;
+// Iteratively test whether `value` nests JSON containers deeper than `max`
+// levels; short-circuits `true` on the first over-deep path. Deliberately NOT
+// recursive: this guard runs on already-parsed, possibly-hostile input, so it
+// must never itself overflow the call stack — it walks an explicit heap stack
+// instead. The root container is depth 1; each nested array/object is one
+// deeper; scalars have no children and never increase depth.
+export function exceedsDepth(value, max) {
+    const stack = [[value, 1]];
+    while (stack.length > 0) {
+        const [node, depth] = stack.pop();
+        if (node === null || typeof node !== "object")
+            continue; // scalar — always fine
+        if (depth > max)
+            return true; // a container nested past the bound
+        const children = Array.isArray(node) ? node : Object.values(node);
+        for (const child of children)
+            stack.push([child, depth + 1]);
+    }
+    return false;
+}
+// RFC 8785 (JCS) canonicalization. The `canonicalize` package is the reference
+// JS implementation; correctness is pinned by the conformance vectors.
+//
+// Nesting is bounded FIRST (MAX_CANONICAL_DEPTH): the depth guard throws before
+// `rejectLoneSurrogates` (recursive) or `canonicalize` (recursive) ever see the
+// input, so neither can overflow, and a too-deep input is a caller/input error
+// that the callers bucket as malformed (same contract as a malformed key).
+//
+// Lone (unpaired) UTF-16 surrogates are REJECTED, never passed through: RFC
+// 8785 requires well-formed UTF-8 output, JS strings can carry lone
+// surrogates that `canonicalize` would emit as-is, and the sibling kernels
+// cannot represent them (Python raises on encode; Go's JSON decoder replaces
+// them). Reject-only is the one behavior all three kernels can share —
+// pinned here and by the corpus lone-surrogate negative.
+export function jcs(value) {
+    if (exceedsDepth(value, MAX_CANONICAL_DEPTH)) {
+        throw new Error(`jcs: input nesting exceeds the ${MAX_CANONICAL_DEPTH}-level canonicalization depth bound`);
+    }
+    rejectLoneSurrogates(value);
+    const canonical = canonicalize(value);
+    if (typeof canonical !== "string") {
+        throw new Error("jcs: canonicalize returned a non-string (input not JSON-serializable?)");
+    }
+    return canonical;
+}
+// Walk every string in the value (keys and values). The check must run on
+// the INPUT: `canonicalize` escapes a lone surrogate as `\udXXX` text in its
+// output, so the malformed code unit is invisible after serialization.
+function rejectLoneSurrogates(value) {
+    if (typeof value === "string") {
+        if (hasLoneSurrogate(value)) {
+            throw new Error("jcs: input contains a lone UTF-16 surrogate (not representable as UTF-8)");
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const v of value)
+            rejectLoneSurrogates(v);
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        for (const [k, v] of Object.entries(value)) {
+            rejectLoneSurrogates(k);
+            rejectLoneSurrogates(v);
+        }
+    }
+}
+function hasLoneSurrogate(s) {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff) {
+            const next = i + 1 < s.length ? s.charCodeAt(i + 1) : 0;
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                i++; // valid pair
+                continue;
+            }
+            return true; // high surrogate without a low
+        }
+        if (c >= 0xdc00 && c <= 0xdfff)
+            return true; // low surrogate without a high
+    }
+    return false;
+}
+// Grammar-strict accept check (envelope-spec §2): `<major>` exactly, or
+// `<major>.<minor>` where minor is `[0-9]+`. A non-numeric minor suffix is
+// malformed, not a tolerated future version — matching the Python kernel's
+// 0.1.1 semantics (the TS/Go fail-open lenience was closed deliberately).
+export function specVersionSupported(specVersion) {
+    if (typeof specVersion !== "string" || specVersion === "")
+        return false;
+    return ACCEPTED_SPEC_MAJORS.some((m) => {
+        if (specVersion === m)
+            return true;
+        if (!specVersion.startsWith(`${m}.`))
+            return false;
+        const minor = specVersion.slice(m.length + 1);
+        return minor.length > 0 && /^[0-9]+$/.test(minor);
+    });
+}
+// The content hash(es) an envelope commits to, by event type — the values a
+// reverse lookup can match the user's in-browser file hash against.
+//   asset_registered -> payload.hash            (the registered, known-good bytes)
+//   asset_missing    -> payload.baseline.hash   (last known-good bytes that vanished)
+//   tamper_detected  -> payload.observed.hash   (the tampered bytes that were flagged)
+//                    -> payload.baseline.hash   (the known-good bytes it diverged from)
+// Other event types commit to no asset content hash.
+export function contentHashes(env) {
+    // Minimal-disclosure / external-commitment envelopes have no inline payload
+    // (and no event_type) — they commit to no envelope-readable content hash.
+    const p = (env.payload ?? {});
+    const asStr = (v) => (typeof v === "string" && v ? v : undefined);
+    const out = [];
+    switch (env.event_type) {
+        case "asset_registered": {
+            const h = asStr(p.hash);
+            if (h)
+                out.push({ role: "asset", hash: h });
+            break;
+        }
+        case "asset_missing": {
+            const h = asStr(p.baseline?.hash);
+            if (h)
+                out.push({ role: "baseline", hash: h });
+            break;
+        }
+        case "tamper_detected": {
+            const obs = asStr(p.observed?.hash);
+            if (obs)
+                out.push({ role: "observed", hash: obs });
+            const base = asStr(p.baseline?.hash);
+            if (base)
+                out.push({ role: "baseline", hash: base });
+            break;
+        }
+    }
+    return out;
+}
+// Verify an envelope — both binding modes (envelope-spec §3), one rule,
+// mirroring the Python reference kernel exactly:
+//
+//   - envelope carries `payload`        → inline check: recompute
+//     SHA-256(JCS(payload)) and compare to payload_hash
+//   - caller supplies `payloadBytes`    → external check:
+//     SHA-256(payloadBytes) must equal payload_hash
+//   - both available                    → both must pass
+//   - neither                           → payloadHashOk = null and the
+//     verdict does NOT fail: "signature-valid, semantics-undetermined"
+//     (§3.1/§6.2). The signature alone still proves who signed what bytes.
+//
+// payload_hash itself MUST be present (a string) in every mode — its
+// absence is rejected per envelope-spec §2, independent of whether there is
+// material to compare it against.
+//
+// Binding-mode detection is structural, not registry-driven: mode confusion
+// is closed by the signed scope itself (an inline payload is INSIDE the
+// signature, so stripping it to fake "external" — or injecting one to fake
+// "inline" — breaks the signature).
+//
+// The second argument accepts the legacy `expectedContentHash` string form
+// or a VerifyOptions object ({ payloadBytes, expectedContentHash }).
+export async function verifyEnvelope(env, optionsOrContentHash) {
+    const opts = typeof optionsOrContentHash === "string"
+        ? { expectedContentHash: optionsOrContentHash }
+        : (optionsOrContentHash ?? {});
+    const expectedContentHash = opts.expectedContentHash;
+    const errors = [];
+    // Guard a malformed input (null / non-object / array) up front — every field
+    // access below assumes an object. A hostile gateway or a hand-edited report
+    // can supply anything; treat it as "not verified," never a thrown exception.
+    if (env === null || typeof env !== "object" || Array.isArray(env)) {
+        return {
+            ok: false,
+            specVersionOk: false,
+            payloadHashOk: false,
+            signatureOk: false,
+            contentHashOk: expectedContentHash === undefined ? null : false,
+            contentRole: null,
+            errors: ["envelope is not a JSON object"],
+        };
+    }
+    const specVersionOk = specVersionSupported(env.spec_version);
+    if (!specVersionOk)
+        errors.push(`unsupported spec_version: ${JSON.stringify(env.spec_version)}`);
+    // Check 1 — Payload binding (both modes; see header).
+    //
+    // payload_hash MUST be present and a string in every mode — envelope-spec
+    // §2: "a verifier cannot proceed without spec_version / public_key /
+    // signature / payload_hash and MUST reject their absence." All three
+    // kernels enforce this (the Python reference's prior compare-only-if-present
+    // lenience was the bug; §2 is binding).
+    //
+    // When present, it is COMPARED only against material that exists — an
+    // inline payload, supplied committed bytes, or both. With neither, the
+    // binding is undetermined (null): "signature-valid, semantics-undetermined"
+    // (§3.1/§6.2). null does not fail the verdict; absence does.
+    let payloadHashOk;
+    if (typeof env.payload_hash !== "string") {
+        payloadHashOk = false;
+        errors.push("missing payload_hash (envelope-spec §2: required in every profile)");
+    }
+    else {
+        const checks = [];
+        if ("payload" in env && env.payload !== undefined) {
+            try {
+                const recomputed = await sha256Hex(utf8(jcs(env.payload)));
+                checks.push(recomputed === env.payload_hash);
+                if (recomputed !== env.payload_hash) {
+                    errors.push(`payload_hash mismatch: envelope=${env.payload_hash} recomputed=${recomputed}`);
+                }
+            }
+            catch (e) {
+                checks.push(false);
+                errors.push(`payload canonicalization failed: ${stringifyErr(e)}`);
+            }
+        }
+        if (opts.payloadBytes !== undefined) {
+            const external = await sha256Hex(opts.payloadBytes);
+            checks.push(external === env.payload_hash);
+            if (external !== env.payload_hash) {
+                errors.push(`payload_hash does not match the committed bytes: envelope=${env.payload_hash} bytes=${external}`);
+            }
+        }
+        payloadHashOk = checks.length > 0 ? checks.every(Boolean) : null;
+    }
+    // Check 2 — Signature Confirmed: Ed25519 over the signed scope, which is
+    // JCS(envelope minus `signature` minus `co_signatures`) per envelope-spec §2.
+    // The co_signatures carve-out (§7.1) lets a countersignature be added without
+    // invalidating the primary signature; the field is reserved/default-absent.
+    // The corpus has no co-signed vectors, so this strip is pinned by an explicit
+    // unit test rather than by conformance.
+    let signatureOk = false;
+    try {
+        const { signature: _signature, co_signatures: _coSignatures, ...envelopeForSig } = env;
+        signatureOk = await ed25519Verify(env.signature, utf8(jcs(envelopeForSig)), env.public_key);
+        if (!signatureOk)
+            errors.push("Ed25519 signature verification failed");
+    }
+    catch (e) {
+        errors.push(`signature verification error: ${stringifyErr(e)}`);
+    }
+    // Check 3 (optional) — Content Bind: the user's bytes match a hash this
+    // envelope commits to. The tag got us here; only this proves the bytes match.
+    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");
+        }
+    }
+    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,
+        specVersionOk,
+        payloadHashOk,
+        signatureOk,
+        contentHashOk,
+        contentRole,
+        errors,
+    };
+}
+function stringifyErr(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@sanning/proof",
+  "version": "0.4.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",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "proof": "./dist/cli.js"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^2.1.0",
+    "canonicalize": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.41",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sanning-io/proof.git",
+    "directory": "ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "sanning",
+    "arweave",
+    "verification",
+    "provenance",
+    "jcs",
+    "rfc8785",
+    "ed25519",
+    "merkle",
+    "rfc9162"
+  ]
+}