@coproduct_inc/verify 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# @coproduct_inc/verify
+
+Offline, **zero-trust** verification for Nucleus. Two receipt families share one package:
+
+1. **Capability-boundary in-bounds attestation** (headline) — given an agent run's tool-call trace and a *declared* capability boundary, emit and offline-verify an Ed25519-signed, hash-chained receipt that the agent **stayed within bounds**. The boundary is keyed on a **cryptographic principal**, never a mutable display name — which is exactly what rules out OpenClaw-class trust-boundary bypass.
+2. **Auction receipts** — re-run the VCG/Vickrey clearing locally and assert the receipt's price (the package's original use case; documented at the bottom).
+
+---
+
+## In-bounds attestation — the drop-in
+
+```ts
+import { verifyReceipt } from "@coproduct_inc/verify";
+
+const report = verifyReceipt(receipt);          // a parsed Receipt object
+if (!report.ok) throw new Error(report.reason); // refuses to attest
+// report.ok === signatureOk && rootHashOk && verdictConsistentOk && inBounds
+```
+
+…or from JSON / the CLI:
+
+```sh
+nucleus-verify run-receipt.json --expect-principal spiffe://acme/agent/billing
+# exit 0 → verified and in bounds   |   exit 1 → refused / out of bounds
+cat run-receipt.json | nucleus-verify --json
+```
+
+In CI, via the bundled GitHub Action:
+
+```yaml
+- uses: coproduct/nucleus-platform/packages/nucleus-verify@main
+  with:
+    receipt: ./agent-run-receipt.json
+    expect-principal: spiffe://acme/agent/billing-assistant
+```
+
+> The Action resolves the verifier with `npx @coproduct_inc/verify`, so it requires the package to be published to npm (or `package-spec` pointed at a local tarball). Publishing is an operator step.
+
+### The OpenClaw guard, in one example
+
+```ts
+import { makeBoundary, signReceipt, verifyReceipt, generateKeypair } from "@coproduct_inc/verify";
+
+const principal = "spiffe://acme/agent/billing-assistant";
+const boundary  = makeBoundary(principal, ["read_invoice", "list_invoices", "summarize"]);
+const { privateKey } = generateKeypair();
+
+// An injected call wears the allowlisted DISPLAY NAME but a different principal:
+const trace = [
+  { seq: 0, tool: "list_invoices", principal, displayName: "Billing Assistant" },
+  { seq: 1, tool: "read_invoice",  principal: "spiffe://acme/agent/unknown-7f3a", displayName: "Billing Assistant" },
+];
+
+const receipt = signReceipt(boundary, trace, privateKey);
+verifyReceipt(receipt).ok; // → false: "out of bounds at event #1: … principal … but the boundary is bound to …"
+```
+
+Run the full replay (clean attests · bypass refused · forged claim rejected):
+
+```sh
+pnpm build && pnpm demo   # examples/openclaw-replay.mjs
+```
+
+### Why it holds
+
+- **`recomputeVerdict` is the soundness floor.** It is pure and deterministic: an event is in-bounds iff its **`principal`** equals the boundary's principal **and** its `tool` is in `allowedTools`. `displayName` is never consulted. A forged `inBounds: true` cannot survive an independent re-run.
+- **Two independent defenses against a tampered claim.** The verifier recomputes the verdict *and* checks the Ed25519 signature over the canonical body (which commits to the verdict). Flipping `inBounds` breaks both.
+- **The permission fingerprint binds identity to capability.** `permissionFingerprint` is SHA-256 over the sorted, de-duplicated `allowedTools` — mirroring the X.509 permission-fingerprint extension in `nucleus-tool-proxy`/`nucleus-identity` (`identity_fusion`: "who you are" bound to "what you can do"). Widening the tool set changes the fingerprint and invalidates the boundary.
+- **The hash-chain pins trace order.** `rootHash` is `hᵢ = SHA256(hᵢ₋₁ ‖ canonical(eventᵢ))`; reorder or insert and the root changes.
+
+### Honest scope
+
+This attests that the **observed trace** stayed within the **declared boundary** — integrity-axis, model-level evidence (the bar-2 IFC noninterference guarantee). It is **not**:
+
+- an end-to-end proof of arbitrary agent behaviour, nor
+- a guarantee that the trace is a *complete* record of what the agent did — completeness of capture is the instrumented runtime's responsibility.
+
+It is the verifiable **evidence layer** that sits above probabilistic guardrails, not a replacement for them. The proof is the differentiator behind the policy; what you verify is the declared boundary.
+
+### Report fields
+
+| field | meaning |
+| --- | --- |
+| `ok` | `signatureOk && rootHashOk && verdictConsistentOk && inBounds` (plus any pinned-key / pinned-principal checks) |
+| `signatureOk` | Ed25519 signature verified under the receipt's public key |
+| `rootHashOk` | SHA-256 hash-chain over `events` reproduces `receipt.rootHash` |
+| `verdictConsistentOk` | independently recomputed verdict deep-equals the claimed verdict |
+| `inBounds` | the recomputed verdict says every event is in bounds |
+| `recomputed` | the verifier's own verdict (authoritative over the claim) |
+| `reason` | first failing reason, or `null` when `ok` |
+
+---
+
+## Auction receipts
+
+The agent never trusts the hub's clearing price: the bundled WASM core (the same `nucleus-wasm` binary the browser demo runs) **re-runs the auction clearing locally** from the *signed* bid set and asserts the recomputed price equals the price the receipt claims — on top of the Ed25519 signature + BLAKE3 root-hash check.
+
+```ts
+import { verify } from "@coproduct_inc/verify";
+const r = await verify(receiptJson, jwksJson);
+if (!r.ok) throw new Error(r.reason ?? "receipt failed verification");
+// r.ok === signature_ok && root_hash_ok && price_recomputed_ok
+```
+
+A signature proves the issuer signed *those bytes*; it does not prove the price in those bytes is the price the auction rules produce. `verify()` closes that gap by recomputing the clearing from the signed bids in the caller's own process. The committed price is single-good Vickrey (what the hub's receipt route runs), pinned to the real hub by a native parity test; the Pigou-VCG figure is parity-pinned to the 0-sorry Lean theorems and reported as a cross-check. See [`docs/BET-C-VERIFY-RECOMPUTE.md`](../../docs/BET-C-VERIFY-RECOMPUTE.md).
+
+---
+
+## Build
+
+```sh
+pnpm install
+pnpm build        # tsc → dist/ (attestation core + CLI, zero runtime deps)
+pnpm test         # node --test against dist/ (attestation + auction)
+pnpm demo         # OpenClaw replay
+pnpm build:wasm   # regenerate wasm/nodejs from crates/nucleus-wasm (auction path only)
+```
+
+The attestation core and CLI are pure Node (`node:crypto`, no WASM, no npm deps). The WASM artifact under `wasm/nodejs/` (auction path) is committed so the package stays self-contained; `pnpm build:wasm` regenerates it byte-for-byte from the Rust crate.

package/dist/attestation.d.ts

@@ -0,0 +1,182 @@
+/**
+ * `@coproduct_inc/verify` — capability-boundary **in-bounds attestation**.
+ *
+ * The evidence layer ABOVE probabilistic guardrails: given an agent run's
+ * observed tool-call trace and a DECLARED capability boundary, produce and
+ * offline-verify an Ed25519-signed, SHA-256-hash-chained receipt that the
+ * agent stayed within the boundary.
+ *
+ * The boundary is keyed on a **cryptographic principal** (a SPIFFE ID) bound
+ * to a **SHA-256 permission fingerprint** — exactly the binding
+ * `nucleus-tool-proxy::identity_fusion` makes between "who you are" (SPIFFE
+ * ID) and "what you can do" (the permission fingerprint embedded in the
+ * X.509 cert). Trust is NEVER keyed on a mutable display name. That single
+ * discipline is what rules out the OpenClaw-class trust-boundary bypass
+ * (CVE-2026-25253): a call whose human-readable `displayName` matches an
+ * allowlisted agent but whose cryptographic `principal` differs is
+ * out-of-bounds by construction, and the receipt refuses to attest it.
+ *
+ * ## Honest scope
+ *
+ * This attests that the OBSERVED trace stayed within the DECLARED boundary —
+ * it is integrity-axis, model-level evidence (the bar-2 IFC noninterference
+ * guarantee), NOT an end-to-end proof of arbitrary agent behaviour, and it
+ * does not vouch that the trace is a complete record of what the agent did.
+ * It is the verifiable evidence layer; completeness of capture is the
+ * producer's (instrumented runtime's) responsibility.
+ *
+ * Zero runtime dependencies: Ed25519 + SHA-256 come from `node:crypto`.
+ */
+import { type KeyObject } from "node:crypto";
+/** Wire identifiers — bumped on any breaking schema change. */
+export declare const RECEIPT_KIND: "nucleus.capability-boundary.attestation";
+export declare const RECEIPT_VERSION: 1;
+/**
+ * A declared capability boundary: WHICH tools a cryptographic principal is
+ * permitted to invoke.
+ *
+ * `permissionFingerprint` is the SHA-256 (hex) over the canonical, sorted,
+ * de-duplicated `allowedTools` — mirroring the X.509 permission-fingerprint
+ * extension in `nucleus-identity::attestation`. It binds the boundary's
+ * identity to its exact permission set: change the tools, change the
+ * fingerprint.
+ */
+export interface CapabilityBoundary {
+    /** Cryptographic principal identity (SPIFFE ID convention). NOT a name. */
+    principal: string;
+    /** Tools/capabilities this principal is permitted to invoke. */
+    allowedTools: string[];
+    /** SHA-256 hex over the canonical sorted unique `allowedTools`. */
+    permissionFingerprint: string;
+}
+/** One observed tool-call event from an agent run. */
+export interface TraceEvent {
+    /** Monotonic position in the run (0-based). */
+    seq: number;
+    /** Tool / capability actually invoked. */
+    tool: string;
+    /** Cryptographic identity PRESENTED for this call (SPIFFE ID). */
+    principal: string;
+    /**
+     * Human-readable label the call presented (mutable). This is the OpenClaw
+     * attack surface — a naive gate keys on this; we record it but NEVER trust
+     * it for the in-bounds decision.
+     */
+    displayName?: string;
+    /** Optional SHA-256 hex of the call arguments (opaque to the verdict). */
+    argsDigest?: string;
+}
+/** Why a single event is in / out of bounds. */
+export type FindingCode = "ok" | "tool_not_allowed" | "principal_mismatch" | "fingerprint_mismatch";
+export interface EventFinding {
+    seq: number;
+    tool: string;
+    inBounds: boolean;
+    code: FindingCode;
+    detail: string;
+}
+/** The deterministic verdict recomputed from a boundary + events. */
+export interface Verdict {
+    /** AND over `boundaryFingerprintOk` and every event finding. */
+    inBounds: boolean;
+    /** The declared `permissionFingerprint` matches the recomputed one. */
+    boundaryFingerprintOk: boolean;
+    events: EventFinding[];
+}
+/** A signed in-bounds attestation receipt (the wire form). */
+export interface Receipt {
+    version: typeof RECEIPT_VERSION;
+    kind: typeof RECEIPT_KIND;
+    boundary: CapabilityBoundary;
+    events: TraceEvent[];
+    /** The attestor's claimed verdict (re-derived and re-checked on verify). */
+    verdict: Verdict;
+    /** SHA-256 hex hash-chain over the canonical events. */
+    rootHash: string;
+    /** Ed25519 public key (base64url raw 32-byte, JWK `x` form). */
+    publicKey: string;
+    /** Ed25519 signature (base64) over the canonical signing body. */
+    signature: string;
+    /** Informational only — NOT trusted by the verifier. */
+    signedAt?: string;
+}
+/** Deterministic JSON: object keys sorted, no incidental whitespace. */
+export declare function canonicalize(value: unknown): string;
+/** SHA-256 hex over the canonical sorted, de-duplicated tool set. */
+export declare function permissionFingerprint(allowedTools: string[]): string;
+/**
+ * SHA-256 hash-chain over the events, in order:
+ *   h₀ = SHA256(genesis); hᵢ = SHA256(hᵢ₋₁ ‖ canonical(eventᵢ)).
+ * Order-sensitive: reordering or inserting an event changes the root.
+ */
+export declare function rootHash(events: TraceEvent[]): string;
+/**
+ * Recompute the in-bounds verdict. Pure and deterministic — no crypto, no
+ * I/O. This is the soundness floor: a forged `inBounds: true` claim cannot
+ * survive a re-run here.
+ *
+ * An event is in-bounds iff:
+ *   1. its `principal` equals the boundary's `principal` (cryptographic
+ *      identity match — the OpenClaw guard), AND
+ *   2. its `tool` is in the boundary's `allowedTools`.
+ * `displayName` is deliberately never consulted.
+ */
+export declare function recomputeVerdict(boundary: CapabilityBoundary, events: TraceEvent[]): Verdict;
+/** Build a well-formed boundary, computing its permission fingerprint. */
+export declare function makeBoundary(principal: string, allowedTools: string[]): CapabilityBoundary;
+/** Generate an ephemeral Ed25519 keypair (e.g. for tests/demos). */
+export declare function generateKeypair(): {
+    publicKey: KeyObject;
+    privateKey: KeyObject;
+};
+/** Export a public KeyObject to the receipt's base64url raw form (JWK `x`). */
+export declare function exportPublicKey(publicKey: KeyObject): string;
+/**
+ * Attest a trace against a boundary, signing the receipt with `privateKey`.
+ *
+ * The attestor signs the TRUE recomputed verdict — it never fabricates an
+ * `inBounds: true`. For an out-of-bounds trace the receipt faithfully
+ * records `verdict.inBounds === false`; the verifier (and CLI) then treat
+ * that as a refusal-to-attest. "Refuses to attest" = does not issue a
+ * passing receipt, NOT silently signs a green one.
+ */
+export declare function signReceipt(boundary: CapabilityBoundary, events: TraceEvent[], privateKey: KeyObject, opts?: {
+    signedAt?: string;
+}): Receipt;
+/** Structured verification result. `ok` is the single boolean to gate on. */
+export interface VerifyReport {
+    /** `signatureOk && rootHashOk && verdictConsistentOk && inBounds`. */
+    ok: boolean;
+    /** Ed25519 signature verified under the receipt's public key. */
+    signatureOk: boolean;
+    /** Hash-chain over `events` reproduces `receipt.rootHash`. */
+    rootHashOk: boolean;
+    /** Independently recomputed verdict deep-equals the claimed one. */
+    verdictConsistentOk: boolean;
+    /** The recomputed verdict says every event is in bounds. */
+    inBounds: boolean;
+    /** Pinned-key check (only meaningful when `opts.expectPublicKey` given). */
+    publicKeyOk: boolean;
+    /** Pinned-principal check (only meaningful when `opts.expectPrincipal` given). */
+    principalOk: boolean;
+    /** The verifier's own recomputation (authoritative over the claim). */
+    recomputed: Verdict;
+    /** First failing reason, or null when `ok`. */
+    reason: string | null;
+}
+export interface VerifyOptions {
+    /** Pin the expected signer public key (base64url raw form). */
+    expectPublicKey?: string;
+    /** Pin the expected boundary principal (SPIFFE ID). */
+    expectPrincipal?: string;
+}
+/**
+ * Verify an in-bounds attestation receipt fully and offline: signature +
+ * hash-chain + an INDEPENDENT recomputation of the verdict. Never throws on
+ * a malformed receipt — failures surface as `ok: false` with a `reason`.
+ */
+export declare function verifyReceipt(receipt: Receipt, opts?: VerifyOptions): VerifyReport;
+/** Parse a receipt from JSON text, then verify. Convenience for the CLI. */
+export declare function verifyReceiptJson(receiptJson: string, opts?: VerifyOptions): VerifyReport;
+/** Load an Ed25519 private key from PEM text (PKCS#8). */
+export declare function privateKeyFromPem(pem: string): KeyObject;

package/dist/attestation.js

@@ -0,0 +1,295 @@
+/**
+ * `@coproduct_inc/verify` — capability-boundary **in-bounds attestation**.
+ *
+ * The evidence layer ABOVE probabilistic guardrails: given an agent run's
+ * observed tool-call trace and a DECLARED capability boundary, produce and
+ * offline-verify an Ed25519-signed, SHA-256-hash-chained receipt that the
+ * agent stayed within the boundary.
+ *
+ * The boundary is keyed on a **cryptographic principal** (a SPIFFE ID) bound
+ * to a **SHA-256 permission fingerprint** — exactly the binding
+ * `nucleus-tool-proxy::identity_fusion` makes between "who you are" (SPIFFE
+ * ID) and "what you can do" (the permission fingerprint embedded in the
+ * X.509 cert). Trust is NEVER keyed on a mutable display name. That single
+ * discipline is what rules out the OpenClaw-class trust-boundary bypass
+ * (CVE-2026-25253): a call whose human-readable `displayName` matches an
+ * allowlisted agent but whose cryptographic `principal` differs is
+ * out-of-bounds by construction, and the receipt refuses to attest it.
+ *
+ * ## Honest scope
+ *
+ * This attests that the OBSERVED trace stayed within the DECLARED boundary —
+ * it is integrity-axis, model-level evidence (the bar-2 IFC noninterference
+ * guarantee), NOT an end-to-end proof of arbitrary agent behaviour, and it
+ * does not vouch that the trace is a complete record of what the agent did.
+ * It is the verifiable evidence layer; completeness of capture is the
+ * producer's (instrumented runtime's) responsibility.
+ *
+ * Zero runtime dependencies: Ed25519 + SHA-256 come from `node:crypto`.
+ */
+import { createHash, createPublicKey, createPrivateKey, generateKeyPairSync, sign as edSign, verify as edVerify, } from "node:crypto";
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+/** Wire identifiers — bumped on any breaking schema change. */
+export const RECEIPT_KIND = "nucleus.capability-boundary.attestation";
+export const RECEIPT_VERSION = 1;
+// ---------------------------------------------------------------------------
+// Canonicalization & hashing (deterministic, dependency-free)
+// ---------------------------------------------------------------------------
+/** Deterministic JSON: object keys sorted, no incidental whitespace. */
+export function canonicalize(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return "[" + value.map(canonicalize).join(",") + "]";
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return ("{" +
+        keys
+            .filter((k) => obj[k] !== undefined)
+            .map((k) => JSON.stringify(k) + ":" + canonicalize(obj[k]))
+            .join(",") +
+        "}");
+}
+function sha256Hex(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+/** SHA-256 hex over the canonical sorted, de-duplicated tool set. */
+export function permissionFingerprint(allowedTools) {
+    const sorted = [...new Set(allowedTools)].sort();
+    return sha256Hex(canonicalize(sorted));
+}
+const CHAIN_GENESIS = "nucleus-capability-boundary-receipt-v1";
+/**
+ * SHA-256 hash-chain over the events, in order:
+ *   h₀ = SHA256(genesis); hᵢ = SHA256(hᵢ₋₁ ‖ canonical(eventᵢ)).
+ * Order-sensitive: reordering or inserting an event changes the root.
+ */
+export function rootHash(events) {
+    let h = sha256Hex(CHAIN_GENESIS);
+    for (const ev of events) {
+        h = sha256Hex(h + "|" + canonicalize(ev));
+    }
+    return h;
+}
+/** The bytes the signature commits to: kind, version, boundary, root, verdict. */
+function signingBody(receipt) {
+    return canonicalize({
+        kind: receipt.kind,
+        version: receipt.version,
+        boundary: receipt.boundary,
+        rootHash: receipt.rootHash,
+        verdict: receipt.verdict,
+    });
+}
+// ---------------------------------------------------------------------------
+// The SOUND core: recompute the verdict from boundary + events
+// ---------------------------------------------------------------------------
+/**
+ * Recompute the in-bounds verdict. Pure and deterministic — no crypto, no
+ * I/O. This is the soundness floor: a forged `inBounds: true` claim cannot
+ * survive a re-run here.
+ *
+ * An event is in-bounds iff:
+ *   1. its `principal` equals the boundary's `principal` (cryptographic
+ *      identity match — the OpenClaw guard), AND
+ *   2. its `tool` is in the boundary's `allowedTools`.
+ * `displayName` is deliberately never consulted.
+ */
+export function recomputeVerdict(boundary, events) {
+    const recomputedFp = permissionFingerprint(boundary.allowedTools);
+    const boundaryFingerprintOk = recomputedFp === boundary.permissionFingerprint;
+    const allowed = new Set(boundary.allowedTools);
+    const findings = events.map((ev) => {
+        if (!boundaryFingerprintOk) {
+            return {
+                seq: ev.seq,
+                tool: ev.tool,
+                inBounds: false,
+                code: "fingerprint_mismatch",
+                detail: `boundary permissionFingerprint does not match its allowedTools (declared ${boundary.permissionFingerprint.slice(0, 12)}…, computed ${recomputedFp.slice(0, 12)}…)`,
+            };
+        }
+        if (ev.principal !== boundary.principal) {
+            return {
+                seq: ev.seq,
+                tool: ev.tool,
+                inBounds: false,
+                code: "principal_mismatch",
+                detail: `call presented principal ${JSON.stringify(ev.principal)}${ev.displayName ? ` (displayName ${JSON.stringify(ev.displayName)})` : ""} but the boundary is bound to ${JSON.stringify(boundary.principal)}`,
+            };
+        }
+        if (!allowed.has(ev.tool)) {
+            return {
+                seq: ev.seq,
+                tool: ev.tool,
+                inBounds: false,
+                code: "tool_not_allowed",
+                detail: `tool ${JSON.stringify(ev.tool)} is not in the declared boundary`,
+            };
+        }
+        return { seq: ev.seq, tool: ev.tool, inBounds: true, code: "ok", detail: "in bounds" };
+    });
+    const inBounds = boundaryFingerprintOk && findings.every((f) => f.inBounds);
+    return { inBounds, boundaryFingerprintOk, events: findings };
+}
+/** Build a well-formed boundary, computing its permission fingerprint. */
+export function makeBoundary(principal, allowedTools) {
+    return {
+        principal,
+        allowedTools: [...allowedTools],
+        permissionFingerprint: permissionFingerprint(allowedTools),
+    };
+}
+// ---------------------------------------------------------------------------
+// Ed25519 key handling
+// ---------------------------------------------------------------------------
+/** Generate an ephemeral Ed25519 keypair (e.g. for tests/demos). */
+export function generateKeypair() {
+    return generateKeyPairSync("ed25519");
+}
+/** Export a public KeyObject to the receipt's base64url raw form (JWK `x`). */
+export function exportPublicKey(publicKey) {
+    const jwk = publicKey.export({ format: "jwk" });
+    if (!jwk.x)
+        throw new Error("not an Ed25519 public key");
+    return jwk.x;
+}
+function importPublicKey(b64url) {
+    return createPublicKey({
+        key: { kty: "OKP", crv: "Ed25519", x: b64url },
+        format: "jwk",
+    });
+}
+// ---------------------------------------------------------------------------
+// Producer side: sign a receipt
+// ---------------------------------------------------------------------------
+/**
+ * Attest a trace against a boundary, signing the receipt with `privateKey`.
+ *
+ * The attestor signs the TRUE recomputed verdict — it never fabricates an
+ * `inBounds: true`. For an out-of-bounds trace the receipt faithfully
+ * records `verdict.inBounds === false`; the verifier (and CLI) then treat
+ * that as a refusal-to-attest. "Refuses to attest" = does not issue a
+ * passing receipt, NOT silently signs a green one.
+ */
+export function signReceipt(boundary, events, privateKey, opts = {}) {
+    const verdict = recomputeVerdict(boundary, events);
+    const root = rootHash(events);
+    const pub = createPublicKey(privateKey);
+    const body = signingBody({ kind: RECEIPT_KIND, version: RECEIPT_VERSION, boundary, rootHash: root, verdict });
+    const signature = edSign(null, Buffer.from(body, "utf8"), privateKey).toString("base64");
+    return {
+        version: RECEIPT_VERSION,
+        kind: RECEIPT_KIND,
+        boundary,
+        events,
+        verdict,
+        rootHash: root,
+        publicKey: exportPublicKey(pub),
+        signature,
+        ...(opts.signedAt ? { signedAt: opts.signedAt } : {}),
+    };
+}
+/**
+ * Verify an in-bounds attestation receipt fully and offline: signature +
+ * hash-chain + an INDEPENDENT recomputation of the verdict. Never throws on
+ * a malformed receipt — failures surface as `ok: false` with a `reason`.
+ */
+export function verifyReceipt(receipt, opts = {}) {
+    const recomputed = recomputeVerdict(receipt.boundary, receipt.events);
+    // 1. Hash-chain.
+    const recomputedRoot = rootHash(receipt.events);
+    const rootHashOk = recomputedRoot === receipt.rootHash;
+    // 2. Signature over the canonical body (using the verifier's recomputed
+    //    root, so a tampered rootHash field can't smuggle a valid signature).
+    let signatureOk = false;
+    try {
+        const body = signingBody({
+            kind: receipt.kind,
+            version: receipt.version,
+            boundary: receipt.boundary,
+            rootHash: receipt.rootHash,
+            verdict: receipt.verdict,
+        });
+        const pub = importPublicKey(receipt.publicKey);
+        signatureOk = edVerify(null, Buffer.from(body, "utf8"), pub, Buffer.from(receipt.signature, "base64"));
+    }
+    catch {
+        signatureOk = false;
+    }
+    // 3. The claimed verdict must equal an independent recomputation.
+    const verdictConsistentOk = canonicalize(recomputed) === canonicalize(receipt.verdict);
+    // 4. The authoritative (recomputed) verdict must be in-bounds.
+    const inBounds = recomputed.inBounds;
+    const publicKeyOk = opts.expectPublicKey === undefined || opts.expectPublicKey === receipt.publicKey;
+    const principalOk = opts.expectPrincipal === undefined || opts.expectPrincipal === receipt.boundary.principal;
+    let reason = null;
+    if (receipt.kind !== RECEIPT_KIND)
+        reason = `unexpected receipt kind ${JSON.stringify(receipt.kind)}`;
+    else if (receipt.version !== RECEIPT_VERSION)
+        reason = `unsupported version ${receipt.version}`;
+    else if (!publicKeyOk)
+        reason = "signer public key does not match the pinned key";
+    else if (!principalOk)
+        reason = "boundary principal does not match the pinned principal";
+    else if (!rootHashOk)
+        reason = "event hash-chain does not reproduce rootHash (trace tampered)";
+    else if (!signatureOk)
+        reason = "Ed25519 signature did not verify";
+    else if (!verdictConsistentOk)
+        reason = "claimed verdict disagrees with the recomputed verdict";
+    else if (!inBounds) {
+        const first = recomputed.events.find((e) => !e.inBounds);
+        reason = first
+            ? `out of bounds at event #${first.seq}: ${first.detail}`
+            : "boundary fingerprint mismatch";
+    }
+    const ok = receipt.kind === RECEIPT_KIND &&
+        receipt.version === RECEIPT_VERSION &&
+        publicKeyOk &&
+        principalOk &&
+        rootHashOk &&
+        signatureOk &&
+        verdictConsistentOk &&
+        inBounds;
+    return {
+        ok,
+        signatureOk,
+        rootHashOk,
+        verdictConsistentOk,
+        inBounds,
+        publicKeyOk,
+        principalOk,
+        recomputed,
+        reason: ok ? null : reason,
+    };
+}
+/** Parse a receipt from JSON text, then verify. Convenience for the CLI. */
+export function verifyReceiptJson(receiptJson, opts = {}) {
+    let receipt;
+    try {
+        receipt = JSON.parse(receiptJson);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            signatureOk: false,
+            rootHashOk: false,
+            verdictConsistentOk: false,
+            inBounds: false,
+            publicKeyOk: false,
+            principalOk: false,
+            recomputed: { inBounds: false, boundaryFingerprintOk: false, events: [] },
+            reason: `receipt is not valid JSON: ${e.message}`,
+        };
+    }
+    return verifyReceipt(receipt, opts);
+}
+/** Load an Ed25519 private key from PEM text (PKCS#8). */
+export function privateKeyFromPem(pem) {
+    return createPrivateKey(pem);
+}

package/dist/cli.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * `nucleus-verify` — offline verifier for capability-boundary in-bounds
+ * attestation receipts. Exit code is the gate:
+ *   0  → receipt verified AND the agent stayed in bounds
+ *   1  → receipt failed verification, or the agent went out of bounds
+ *   2  → usage / I/O error
+ *
+ * Usage:
+ *   nucleus-verify <receipt.json> [--expect-principal <spiffe-id>]
+ *                                 [--expect-key <base64url>] [--json] [--quiet]
+ *   nucleus-verify --help
+ *
+ * Reads from stdin if `<receipt.json>` is "-" or omitted with piped input.
+ * Designed as a drop-in CI / GitHub Action step.
+ */
+export {};