@sanning/proof 0.4.0

package/src/index.ts

@@ -0,0 +1,105 @@
+// @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";
+export type { ContentRole, Envelope, Subject, VerificationResult, VerifyOptions } from "./types.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";
+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";
+
+// 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";
+export type { ComposeExportOptions, ComposeExportResult, ExporterKey } 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";
+export type {
+  AgentProofBundle,
+  AgentProofResult,
+  VerifyAgentProofOptions,
+} from "./agent-proof.js";

package/src/merkle.ts

@@ -0,0 +1,125 @@
+// 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: Uint8Array): Promise<Uint8Array> {
+  return sha256Bytes(prefixed(0x00, leafBytes));
+}
+
+// SHA-256(0x01 || left || right) per RFC 9162 §2.1.
+export async function nodeHash(left: Uint8Array, right: Uint8Array): Promise<Uint8Array> {
+  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: Uint8Array[]): Promise<Uint8Array> {
+  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: number, leafHashes: Uint8Array[]): Promise<Uint8Array[]> {
+  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: number, leafHashes: Uint8Array[]): Promise<Uint8Array[]> {
+  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: Uint8Array,
+  leafIndex: number,
+  totalLeaves: number,
+  auditPath: Uint8Array[],
+  expectedRoot: Uint8Array,
+): Promise<boolean> {
+  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: number, bytes: Uint8Array): Uint8Array {
+  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: number): number {
+  if (n < 2) return 0;
+  let k = 1;
+  while (k * 2 < n) k *= 2;
+  return k;
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  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/src/types.ts

@@ -0,0 +1,72 @@
+// 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 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;
+  // Inline-binding profiles (envelope-spec §3) carry the committed payload in
+  // the envelope; external-commitment profiles do not — the caller supplies
+  // the committed bytes to bind (verifyEnvelope's payloadBytes option).
+  payload?: Record<string, unknown>;
+  // Disclosure fields (§3.1): present on Promoted profiles, absent on Minimal
+  // ones (they live inside the committed payload instead).
+  event_type?: string;
+  subject?: Subject;
+  previous_hash?: string;
+  // Optional v1.1+ fields: dev/production marking inside the signed scope,
+  // and the external-commitment locator.
+  environment?: string;
+  payload_ref?: string;
+  // Reserved, default-absent (envelope-spec §7.1): countersignatures over the
+  // same skeleton. OUTSIDE the signed scope — the primary signature covers the
+  // envelope minus `signature` AND minus `co_signatures`, so a countersignature
+  // can be added without invalidating the primary. Absence implies a single
+  // signer and MUST NOT be treated as a failure.
+  co_signatures?: unknown[];
+}
+
+// Which payload field a matched content hash came from. tamper_detected commits
+// to both the tampered ("observed") bytes and the known-good ("baseline") bytes.
+export type ContentRole = "asset" | "baseline" | "observed";
+
+export interface VerifyOptions {
+  // External commitment (§3): the committed canonical payload bytes. When
+  // supplied, SHA-256(payloadBytes) must equal the envelope's payload_hash.
+  payloadBytes?: Uint8Array;
+  // Content bind: the caller's own hash of an artifact (e.g. the in-browser
+  // hash of a user's file) to match against the hashes the envelope commits to.
+  expectedContentHash?: string;
+}
+
+export interface VerificationResult {
+  // Cryptographic validity: spec_version ok, Ed25519 signature ok, and the
+  // payload binding did not FAIL. payloadHashOk === null (binding not
+  // checkable: external-commitment envelope, no payloadBytes supplied) does
+  // not fail ok — that is the "signature-valid, semantics-undetermined"
+  // outcome of envelope-spec §3.1/§6.2.
+  ok: boolean;
+  specVersionOk: boolean;
+  // true: binding checked and matches (inline recompute, external bytes, or
+  // both when both were available). false: a check failed, or payload_hash is
+  // missing/malformed. null: no binding material to check against.
+  payloadHashOk: boolean | null;
+  signatureOk: boolean;
+  // Content bind: did the hash the caller supplied match a hash this envelope
+  // commits to? null when no hash was supplied. This is the check that defeats
+  // a lying gateway — the tag only got us to the candidate.
+  contentHashOk: boolean | null;
+  contentRole: ContentRole | null;
+  errors: string[];
+}

package/src/verifier.ts

@@ -0,0 +1,340 @@
+// 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";
+import type { ContentRole, Envelope, VerificationResult, VerifyOptions } from "./types.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: readonly string[] = 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: unknown, max: number): boolean {
+  const stack: Array<[unknown, number]> = [[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: unknown): string {
+  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: unknown): void {
+  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: string): boolean {
+  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: string): boolean {
+  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: Envelope): { role: ContentRole; hash: string }[] {
+  // 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 ?? {}) as {
+    hash?: unknown;
+    baseline?: { hash?: unknown };
+    observed?: { hash?: unknown };
+  };
+  const asStr = (v: unknown): string | undefined => (typeof v === "string" && v ? v : undefined);
+
+  const out: { role: ContentRole; hash: string }[] = [];
+  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: Envelope,
+  optionsOrContentHash?: string | VerifyOptions,
+): Promise<VerificationResult> {
+  const opts: VerifyOptions =
+    typeof optionsOrContentHash === "string"
+      ? { expectedContentHash: optionsOrContentHash }
+      : (optionsOrContentHash ?? {});
+  const expectedContentHash = opts.expectedContentHash;
+  const errors: string[] = [];
+
+  // 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: boolean | null;
+  if (typeof env.payload_hash !== "string") {
+    payloadHashOk = false;
+    errors.push("missing payload_hash (envelope-spec §2: required in every profile)");
+  } else {
+    const checks: boolean[] = [];
+    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: boolean | null = null;
+  let contentRole: ContentRole | null = 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: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}