@coproduct_inc/verify 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to `@coproduct_inc/verify`.
+
+## 0.3.0
+
+### Added
+- **Offline Ed25519 license keys** (`./license` export + `nucleus-license` bin) —
+  entitlement with no user database and no callback: the vendor signs a tiny
+  claims payload; the Pro path verifies it against a pinned public key.
+  `keygen` / `issue` / `verify`; expiry enforced; tamper-evident.
+- **Converting demo** (`examples/converting-demo.sh`) — recordable 4-beat demo
+  (clean attests · OpenClaw impersonation refused · forged verdict caught two
+  ways · CI gate), runs against the published package or `LOCAL=1`.
+- **`WHY-VERIFY.md`** — positioning one-pager (the independent-recompute
+  differentiator + honest Microsoft-AGT contrast) and a static `site/` landing
+  page (zero-JS, zero-backend) wired for a Merchant-of-Record checkout.
+
+## 0.2.0
+
+### Added
+- **Producer-side instrumentation** — turn a nucleus-tool-proxy trace into a
+  signed in-bounds attestation receipt.
+  - `./toolproxy` export: `attestToolProxyRun`, `boundaryFromExport`,
+    `traceEventsFromRecords`, `parseExport`. Maps the tool-proxy's verdict
+    records (`actor`/`operation`/`verdict`/`subject`/`deny_reason`, mirroring
+    the `verdict_sink` `tool_call` span) into the receipt schema and signs it.
+    Includes a cross-check that the proxy's own allow/deny agrees with the
+    receipt's independently recomputed verdict (surfaces boundary drift).
+  - `nucleus-attest` bin: read a trace export (stdin or file), sign a receipt.
+    With `--key <pkcs8.pem>` uses a real key; otherwise an ephemeral in-memory
+    key (no custody), printing the public key to stderr.
+- Release workflow: OIDC trusted publishing to npm (no stored token).
+
+## 0.1.0
+
+### Added
+- **Capability-boundary in-bounds attestation** — the headline evidence layer.
+  - `verifyReceipt` / `verifyReceiptJson`: offline, zero-trust verification of
+    an Ed25519-signed, SHA-256-hash-chained receipt that an agent run stayed
+    within a declared capability boundary, keyed on a cryptographic principal
+    (SPIFFE id + permission fingerprint), never a mutable display name.
+  - `signReceipt`, `recomputeVerdict` (the pure soundness floor), `makeBoundary`.
+  - `nucleus-verify` CLI (exit 0 in-bounds / 1 refused / 2 usage) and a
+    composite GitHub Action.
+- **Auction receipts** (original use case): `verify`, `recomputeClearing`,
+  `verifySignature` over the bundled `nucleus-wasm` core.

package/README.md

@@ -1,5 +1,10 @@
 # @coproduct_inc/verify
 
+> **New here?** Read [WHY-VERIFY.md](./WHY-VERIFY.md) ("verify, don't trust" — the
+> one-pager + Microsoft-AGT contrast), or run the 90-second demo:
+> `bash examples/converting-demo.sh` (clean attests · OpenClaw bypass refused ·
+> forged verdict caught · CI gate).
+
 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.
@@ -68,6 +73,30 @@ pnpm build && pnpm demo   # examples/openclaw-replay.mjs
 - **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.
 
+### Producer-side: from a real nucleus-tool-proxy trace
+
+The receipt is emitted from the tool-proxy's actual authorization output, not a hand-authored fixture. A trace export pairs the **declared boundary** (a SPIFFE principal + the task-shield allowlist — `portcullis_core::task_shield::TaskWitness`'s allow-set) with one record per observed call mirroring the `verdict_sink` `tool_call` span fields (`actor`, `operation`, `verdict`, `subject`, `deny_reason`):
+
+```jsonc
+{
+  "boundary": { "principal": "spiffe://acme/agent/billing", "allowedTools": ["read_files","glob_search","grep_search"] },
+  "records": [
+    { "actor": "spiffe://acme/agent/billing", "operation": "read_files", "verdict": "allow", "subject": "invoices/2026-06.pdf" }
+  ]
+}
+```
+
+Pipe it through the `nucleus-attest` producer to get a signed receipt, then verify:
+
+```sh
+# emit a REAL trace from portcullis (TaskWitness::permits decides each verdict):
+cargo run -q -p nucleus-policy --example emit_toolproxy_trace -- clean \
+  | nucleus-attest \
+  | nucleus-verify -          # exit 0: in bounds · exit 1: refused
+```
+
+`nucleus-attest` also runs a **cross-check**: the proxy's own `allow`/`deny` per call must agree with the receipt's independently recomputed in-bounds verdict — a mismatch surfaces boundary drift. The producer never asserts in-bounds itself; it only records what happened (`attestToolProxyRun`/`./toolproxy`). The Rust emitter lives at `crates/nucleus-policy/examples/emit_toolproxy_trace.rs`.
+
 ### 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**:

package/WHY-VERIFY.md

@@ -0,0 +1,81 @@
+# Verify, don't trust.
+
+**`@coproduct_inc/verify`** turns an agent run into **verifiable evidence** that it
+stayed inside a declared capability boundary — evidence a third party can check
+**offline, without trusting the agent or the platform that produced it.**
+
+```sh
+npx @coproduct_inc/verify nucleus-verify run-receipt.json
+#  exit 0 → in bounds   ·   exit 1 → refused
+```
+
+## The problem everyone now has
+
+97% of security leaders expect a material AI-agent incident in the next 12 months;
+6% of budgets address it. The dominant failure mode has a name: the **lethal
+trifecta** — an agent with private data + untrusted content + an exfiltration sink
+gets turned into a *confused deputy*, exercising its authority for an attacker
+(OpenClaw, CVE-2026-25253; Invariant Labs' GitHub-MCP exploit). Regulators are
+arriving too: the EU AI Act's high-risk regime (Aug 2, 2026) demands **productized
+evidence tied to real runs and operator identity** — not a dashboard, an artifact.
+
+The runtime's job is to make that trifecta safe by *non-interference*. This
+package's job is to **prove it happened**: an offline-verifiable receipt that the
+agent stayed inside its declared boundary — i.e. was *not* a confused deputy.
+
+## The one thing that's different: we recompute the verdict
+
+Most "agent receipts" — including Microsoft's Agent Governance Toolkit — are a
+**signed record of what the platform's own engine decided.** You trust the engine.
+
+`@coproduct_inc/verify` is a **second, independent check.** Given the declared
+boundary and the observed trace, it **re-derives** the in-bounds verdict and
+confirms it matches the receipt — then checks an Ed25519 signature and a SHA-256
+hash-chain. A **forged or mistaken** verdict is caught two ways: the recompute
+disagrees, *and* the signature (taken over the honest verdict) breaks.
+
+> A platform vendor is structurally incentivized to be *trusted*. A neutral
+> verifier is incentivized to be *checkable*. That's the wedge.
+
+| | Microsoft Agent Governance Toolkit | `@coproduct_inc/verify` |
+|---|---|---|
+| Capability manifest / policy | ✅ (denies outside the manifest) | relies on yours (any runtime) |
+| Signed, hash-chained receipts | ✅ Ed25519 decision receipts | ✅ Ed25519 + SHA-256 chain |
+| **Independent verdict recompute** | ❌ (trust the engine's decision) | ✅ **soundness floor — catches a forged claim** |
+| Keyed on cryptographic principal, not display name | partial | ✅ rules out OpenClaw by construction |
+| Verdict logic backed by machine-checked theorems | ❌ | ✅ (IFC noninterference, leanchecker-rechecked) |
+| Footprint | a governance framework | one `npx` / one GitHub Action, **zero runtime deps** |
+| Position | the platform | the **neutral verifier above any platform** (incl. AGT) |
+
+We don't compete with the guardrail. We're the evidence layer **above** it — and
+we verify *their* agents too.
+
+## See it (90 seconds)
+
+```sh
+npx @coproduct_inc/verify --help          # or: bash examples/converting-demo.sh
+```
+
+1. **Clean run → attests** (exit 0). Auditor-grade evidence the agent stayed in bounds.
+2. **OpenClaw bypass** — a call wearing an allowlisted *display name* but a different
+   cryptographic principal → **refused** (exit 1). The CVE class, ruled out by construction.
+3. **Forge the verdict** (claim `inBounds:true`) → **caught** by the independent recompute
+   *and* the broken signature. This is the difference between a signed log and verifiable evidence.
+4. **CI gate** — drop the Action in a PR; an out-of-bounds run **fails the build.** A merge gate, not a dashboard.
+
+## Who it's for
+
+- **AppSec** — a 30-second drop-in CI/PR gate, no platform migration, works above your existing guardrails.
+- **GRC / SOC 2 / EU AI Act** — the receipt **is** the exportable audit artifact: offline-verifiable, tied to real runs and operator identity.
+
+## Honest scope
+
+It attests that the **observed trace** stayed within the **declared boundary** —
+integrity-axis, model-level evidence. It is **not** a proof of arbitrary agent
+behavior, and it does not vouch that the trace is a *complete* record of what the
+agent did (completeness of capture is the runtime's job). It's the verifiable
+evidence layer above probabilistic guardrails, not a replacement for them.
+
+---
+
+Sources for the market claims: [VentureBeat / Arkose 2026 agent-security survey](https://venturebeat.com/security/most-enterprises-cant-stop-stage-three-ai-agent-threats-venturebeat-survey-finds), [EU AI Act Art. 16 / Aug 2026](https://artificialintelligenceact.eu/article/16/), [Microsoft Agent Governance Toolkit](https://opensource.microsoft.com/blog/2026/04/02/introducing-the-agent-governance-toolkit-open-source-runtime-security-for-ai-agents/), [PipeLab — mediator receipts / independent attestation](https://pipelab.org/blog/independent-attestation-mediator-receipts/).

package/dist/index.d.ts

@@ -94,3 +94,5 @@ export declare function recomputeClearing(receiptJson: string): Promise<Recomput
  */
 export declare function verifySignature(receiptJson: string, jwksJson: string): Promise<unknown>;
 export * from "./attestation.js";
+export * from "./toolproxy.js";
+export * from "./license.js";

package/dist/index.js

@@ -67,3 +67,9 @@ export async function verifySignature(receiptJson, jwksJson) {
 // Pure Node (`node:crypto`), no WASM — runs in CI, the CLI, and the Action.
 // ---------------------------------------------------------------------------
 export * from "./attestation.js";
+// Producer-side instrumentation: turn a nucleus-tool-proxy trace into a signed
+// in-bounds receipt. See `./toolproxy` and the `nucleus-attest` CLI.
+export * from "./toolproxy.js";
+// Offline Ed25519 license keys: entitlement with no user DB / no callback.
+// See `./license` and the `nucleus-license` CLI.
+export * from "./license.js";

package/dist/license-cli.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * `nucleus-license` — issue + verify offline Ed25519 license keys.
+ *
+ *   nucleus-license keygen [--out-key vendor.pem] [--out-pub vendor.pub]
+ *     → generate a vendor keypair; prints the base64url public key to PIN.
+ *
+ *   nucleus-license issue --key vendor.pem --sub a@b.com --tier pro \
+ *       [--features dashboard,export] [--exp 2027-06-01] [--iat 2026-06-04]
+ *     → prints a license token (deliver this string as the MoR "license key").
+ *
+ *   nucleus-license verify <token> --pubkey <base64url> [--now 2026-06-04]
+ *     → exit 0 if valid, 1 if not.
+ *
+ * No server, no DB: the Merchant of Record holds the customer; this issues and
+ * checks a signature. Keep the vendor private key secret.
+ */
+export {};

package/dist/license-cli.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * `nucleus-license` — issue + verify offline Ed25519 license keys.
+ *
+ *   nucleus-license keygen [--out-key vendor.pem] [--out-pub vendor.pub]
+ *     → generate a vendor keypair; prints the base64url public key to PIN.
+ *
+ *   nucleus-license issue --key vendor.pem --sub a@b.com --tier pro \
+ *       [--features dashboard,export] [--exp 2027-06-01] [--iat 2026-06-04]
+ *     → prints a license token (deliver this string as the MoR "license key").
+ *
+ *   nucleus-license verify <token> --pubkey <base64url> [--now 2026-06-04]
+ *     → exit 0 if valid, 1 if not.
+ *
+ * No server, no DB: the Merchant of Record holds the customer; this issues and
+ * checks a signature. Keep the vendor private key secret.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { generateLicenseKeypair, exportLicensePublicKey, signLicense, verifyLicense, licensePrivateKeyFromPem, } from "./license.js";
+function opt(flag) {
+    const i = process.argv.indexOf(flag);
+    return i >= 0 ? process.argv[i + 1] : undefined;
+}
+function keygen() {
+    const { publicKey, privateKey } = generateLicenseKeypair();
+    const pub = exportLicensePublicKey(publicKey);
+    const pem = privateKey.export({ type: "pkcs8", format: "pem" });
+    const outKey = opt("--out-key");
+    const outPub = opt("--out-pub");
+    if (outKey)
+        writeFileSync(outKey, pem, { mode: 0o600 });
+    if (outPub)
+        writeFileSync(outPub, pub + "\n");
+    process.stdout.write(`vendor public key (PIN this in the verifier):\n${pub}\n`);
+    if (!outKey) {
+        process.stdout.write("\nvendor PRIVATE key (keep SECRET — store in your MoR webhook secret):\n");
+        process.stdout.write(pem);
+    }
+    else {
+        process.stderr.write(`wrote private key → ${outKey} (chmod 600)\n`);
+    }
+    return 0;
+}
+function issue() {
+    const keyPath = opt("--key");
+    const sub = opt("--sub");
+    const tier = (opt("--tier") ?? "pro");
+    if (!keyPath || !sub) {
+        process.stderr.write("error: issue needs --key <vendor.pem> and --sub <id>\n");
+        return 2;
+    }
+    const features = (opt("--features") ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    const claims = {
+        sub,
+        tier,
+        features,
+        iat: opt("--iat") ?? new Date().toISOString().slice(0, 10),
+        ...(opt("--exp") ? { exp: opt("--exp") } : {}),
+    };
+    const key = licensePrivateKeyFromPem(readFileSync(keyPath, "utf8"));
+    process.stdout.write(signLicense(claims, key) + "\n");
+    return 0;
+}
+function verify() {
+    const token = process.argv[3];
+    const pubkey = opt("--pubkey");
+    if (!token || token.startsWith("--") || !pubkey) {
+        process.stderr.write("error: verify needs <token> and --pubkey <base64url>\n");
+        return 2;
+    }
+    const r = verifyLicense(token, pubkey, opt("--now"));
+    if (r.valid) {
+        process.stdout.write(`✓ valid — ${r.license.tier} for ${r.license.sub}` + (r.license.exp ? ` (exp ${r.license.exp})` : "") + `\n`);
+        return 0;
+    }
+    process.stderr.write(`✗ invalid — ${r.reason}\n`);
+    return 1;
+}
+function main() {
+    const cmd = process.argv[2];
+    switch (cmd) {
+        case "keygen":
+            return keygen();
+        case "issue":
+            return issue();
+        case "verify":
+            return verify();
+        default:
+            process.stdout.write("nucleus-license — offline Ed25519 license keys\n\n" +
+                "  nucleus-license keygen [--out-key vendor.pem] [--out-pub vendor.pub]\n" +
+                "  nucleus-license issue  --key vendor.pem --sub a@b.com --tier pro [--features x,y] [--exp ISO]\n" +
+                "  nucleus-license verify <token> --pubkey <base64url> [--now ISO]\n");
+            return cmd ? 2 : 0;
+    }
+}
+process.exit(main());

package/dist/license.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Offline Ed25519 license keys — entitlement without a user database or a
+ * callback. The vendor signs a tiny claims payload with a private key; the CLI
+ * (or a Pro feature path) verifies it against a PINNED public key. No server,
+ * no license API, no phone-home: the Merchant of Record (Polar / Lemon Squeezy)
+ * holds the customer record and delivers the signed string as the "license
+ * key"; this module is the verifier.
+ *
+ * Token format (compact, copy-pasteable):
+ *   nvlic1.<base64url(canonical-json payload)>.<base64url(ed25519 sig)>
+ * The signature is over the payload SEGMENT bytes (the base64url string), so
+ * verification never re-serializes — it checks the exact bytes that were signed.
+ *
+ * On-brand: a verification company gating its own Pro tier by a verifiable,
+ * offline-checkable signature rather than a trust-the-server license call.
+ */
+import { type KeyObject } from "node:crypto";
+export declare const LICENSE_PREFIX: "nvlic1";
+/** The claims a license asserts. Keep it small — it's pasted by hand. */
+export interface LicenseClaims {
+    /** Who the license is for (email / customer id from the MoR). */
+    sub: string;
+    /** Entitlement tier. */
+    tier: "pro" | "team" | "enterprise";
+    /** Unlocked features (free-form; checked by the Pro path). */
+    features: string[];
+    /** Issued-at (ISO date). Informational. */
+    iat: string;
+    /** Optional expiry (ISO date). Absent = perpetual. */
+    exp?: string;
+}
+export interface LicenseReport {
+    valid: boolean;
+    /** The verified claims, when valid. */
+    license: LicenseClaims | null;
+    /** First failing reason, or null when valid. */
+    reason: string | null;
+}
+/** Generate an Ed25519 vendor keypair. Keep the private key secret; ship the public. */
+export declare function generateLicenseKeypair(): {
+    publicKey: KeyObject;
+    privateKey: KeyObject;
+};
+/** Export a public key to the base64url raw form the verifier pins. */
+export declare function exportLicensePublicKey(publicKey: KeyObject): string;
+/** Sign a license token with the vendor private key. */
+export declare function signLicense(claims: LicenseClaims, privateKey: KeyObject): string;
+/** Load an Ed25519 private key from PEM (PKCS#8). */
+export declare function licensePrivateKeyFromPem(pem: string): KeyObject;
+/**
+ * Verify a license token offline against the pinned vendor public key
+ * (base64url raw Ed25519). Checks format + signature + expiry. Never throws.
+ *
+ * @param now optional ISO timestamp for expiry checks (defaults to absent =
+ *   skip expiry; pass an explicit time to enforce it deterministically).
+ */
+export declare function verifyLicense(token: string, vendorPublicKeyB64url: string, now?: string): LicenseReport;
+/** Convenience: does a verified license grant a given feature (or tier-implied)? */
+export declare function licenseGrants(report: LicenseReport, feature: string): boolean;

package/dist/license.js

@@ -0,0 +1,94 @@
+/**
+ * Offline Ed25519 license keys — entitlement without a user database or a
+ * callback. The vendor signs a tiny claims payload with a private key; the CLI
+ * (or a Pro feature path) verifies it against a PINNED public key. No server,
+ * no license API, no phone-home: the Merchant of Record (Polar / Lemon Squeezy)
+ * holds the customer record and delivers the signed string as the "license
+ * key"; this module is the verifier.
+ *
+ * Token format (compact, copy-pasteable):
+ *   nvlic1.<base64url(canonical-json payload)>.<base64url(ed25519 sig)>
+ * The signature is over the payload SEGMENT bytes (the base64url string), so
+ * verification never re-serializes — it checks the exact bytes that were signed.
+ *
+ * On-brand: a verification company gating its own Pro tier by a verifiable,
+ * offline-checkable signature rather than a trust-the-server license call.
+ */
+import { createPublicKey, createPrivateKey, sign as edSign, verify as edVerify, generateKeyPairSync } from "node:crypto";
+import { canonicalize } from "./attestation.js";
+export const LICENSE_PREFIX = "nvlic1";
+function b64url(buf) {
+    return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromB64url(s) {
+    return Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+}
+function importPublicKey(b64urlX) {
+    return createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: b64urlX }, format: "jwk" });
+}
+// ---------------------------------------------------------------------------
+// Issuer side (run once per sale, or from a MoR webhook).
+// ---------------------------------------------------------------------------
+/** Generate an Ed25519 vendor keypair. Keep the private key secret; ship the public. */
+export function generateLicenseKeypair() {
+    return generateKeyPairSync("ed25519");
+}
+/** Export a public key to the base64url raw form the verifier pins. */
+export function exportLicensePublicKey(publicKey) {
+    const jwk = publicKey.export({ format: "jwk" });
+    if (!jwk.x)
+        throw new Error("not an Ed25519 public key");
+    return jwk.x;
+}
+/** Sign a license token with the vendor private key. */
+export function signLicense(claims, privateKey) {
+    const payloadB64 = b64url(Buffer.from(canonicalize(claims), "utf8"));
+    const sig = edSign(null, Buffer.from(payloadB64, "utf8"), privateKey);
+    return `${LICENSE_PREFIX}.${payloadB64}.${b64url(sig)}`;
+}
+/** Load an Ed25519 private key from PEM (PKCS#8). */
+export function licensePrivateKeyFromPem(pem) {
+    return createPrivateKey(pem);
+}
+// ---------------------------------------------------------------------------
+// Verifier side (ships in the CLI / Pro path; pins the vendor public key).
+// ---------------------------------------------------------------------------
+/**
+ * Verify a license token offline against the pinned vendor public key
+ * (base64url raw Ed25519). Checks format + signature + expiry. Never throws.
+ *
+ * @param now optional ISO timestamp for expiry checks (defaults to absent =
+ *   skip expiry; pass an explicit time to enforce it deterministically).
+ */
+export function verifyLicense(token, vendorPublicKeyB64url, now) {
+    const parts = token.trim().split(".");
+    if (parts.length !== 3 || parts[0] !== LICENSE_PREFIX) {
+        return { valid: false, license: null, reason: "malformed license token" };
+    }
+    const [, payloadB64, sigB64] = parts;
+    let sigOk = false;
+    try {
+        const pub = importPublicKey(vendorPublicKeyB64url);
+        sigOk = edVerify(null, Buffer.from(payloadB64, "utf8"), pub, fromB64url(sigB64));
+    }
+    catch {
+        sigOk = false;
+    }
+    if (!sigOk)
+        return { valid: false, license: null, reason: "signature did not verify under the pinned key" };
+    let claims;
+    try {
+        claims = JSON.parse(fromB64url(payloadB64).toString("utf8"));
+    }
+    catch (e) {
+        return { valid: false, license: null, reason: `license payload not valid JSON: ${e.message}` };
+    }
+    if (claims.exp && now && now > claims.exp) {
+        return { valid: false, license: claims, reason: `license expired on ${claims.exp}` };
+    }
+    return { valid: true, license: claims, reason: null };
+}
+/** Convenience: does a verified license grant a given feature (or tier-implied)? */
+export function licenseGrants(report, feature) {
+    return report.valid && !!report.license && report.license.features.includes(feature);
+}

package/dist/producer-cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * `nucleus-attest` — producer-side CLI. Reads a nucleus-tool-proxy trace
+ * export (from the `emit_toolproxy_trace` example, or any equivalent
+ * instrumentation), signs an in-bounds attestation receipt, and writes it to
+ * stdout. The cross-check + signer public key go to stderr.
+ *
+ * Usage:
+ *   nucleus-attest [export.json] [--key <pkcs8.pem>] [--signed-at <iso>]
+ *   emit_toolproxy_trace ... | nucleus-attest > receipt.json
+ *
+ * With no --key, an EPHEMERAL Ed25519 keypair is generated in memory (no key
+ * custody) — fine for demos/CI dry-runs; the public key is printed to stderr
+ * so a verifier can pin it. Exit 0 on a produced receipt, 2 on error.
+ */
+export {};

package/dist/producer-cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * `nucleus-attest` — producer-side CLI. Reads a nucleus-tool-proxy trace
+ * export (from the `emit_toolproxy_trace` example, or any equivalent
+ * instrumentation), signs an in-bounds attestation receipt, and writes it to
+ * stdout. The cross-check + signer public key go to stderr.
+ *
+ * Usage:
+ *   nucleus-attest [export.json] [--key <pkcs8.pem>] [--signed-at <iso>]
+ *   emit_toolproxy_trace ... | nucleus-attest > receipt.json
+ *
+ * With no --key, an EPHEMERAL Ed25519 keypair is generated in memory (no key
+ * custody) — fine for demos/CI dry-runs; the public key is printed to stderr
+ * so a verifier can pin it. Exit 0 on a produced receipt, 2 on error.
+ */
+import { readFileSync } from "node:fs";
+import { generateKeypair, privateKeyFromPem, exportPublicKey } from "./attestation.js";
+import { createPublicKey } from "node:crypto";
+import { parseExport, attestToolProxyRun } from "./toolproxy.js";
+function arg(flag) {
+    const i = process.argv.indexOf(flag);
+    return i >= 0 ? process.argv[i + 1] : undefined;
+}
+function main() {
+    if (process.argv.includes("-h") || process.argv.includes("--help")) {
+        process.stdout.write("nucleus-attest — sign an in-bounds receipt from a tool-proxy trace\n\n" +
+            "Usage: nucleus-attest [export.json] [--key <pkcs8.pem>] [--signed-at <iso>]\n");
+        return 0;
+    }
+    // Positional input path = first non-flag arg after argv[1].
+    const positional = process.argv.slice(2).find((a) => !a.startsWith("--") && a !== arg("--key") && a !== arg("--signed-at"));
+    let exportJson;
+    try {
+        exportJson = positional ? readFileSync(positional, "utf8") : readFileSync(0, "utf8");
+    }
+    catch (e) {
+        process.stderr.write(`error: cannot read export: ${e.message}\n`);
+        return 2;
+    }
+    let exp;
+    try {
+        exp = parseExport(exportJson);
+    }
+    catch (e) {
+        process.stderr.write(`error: ${e.message}\n`);
+        return 2;
+    }
+    // Key: load from PEM, or generate ephemeral.
+    let privateKey;
+    let ephemeral = false;
+    const keyPath = arg("--key");
+    try {
+        if (keyPath) {
+            privateKey = privateKeyFromPem(readFileSync(keyPath, "utf8"));
+        }
+        else {
+            privateKey = generateKeypair().privateKey;
+            ephemeral = true;
+        }
+    }
+    catch (e) {
+        process.stderr.write(`error: cannot load key: ${e.message}\n`);
+        return 2;
+    }
+    const signedAt = arg("--signed-at");
+    const { receipt, crossCheck } = attestToolProxyRun(exp, privateKey, signedAt ? { signedAt } : {});
+    // Receipt → stdout (the artifact).
+    process.stdout.write(JSON.stringify(receipt, null, 2) + "\n");
+    // Diagnostics → stderr.
+    const pub = exportPublicKey(createPublicKey(privateKey));
+    process.stderr.write(`signer publicKey: ${pub}${ephemeral ? " (ephemeral)" : ""}\n` +
+        `recomputed inBounds: ${receipt.verdict.inBounds}\n`);
+    if (crossCheck.length > 0) {
+        process.stderr.write(`cross-check issues (${crossCheck.length}):\n`);
+        for (const c of crossCheck) {
+            process.stderr.write(`  #${c.seq} ${c.operation}: proxy=${c.proxyVerdict} recomputed-inBounds=${c.recomputedInBounds} — ${c.note}\n`);
+        }
+    }
+    else {
+        process.stderr.write("cross-check: proxy decisions agree with recomputed verdict\n");
+    }
+    return 0;
+}
+process.exit(main());

package/dist/toolproxy.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Producer-side instrumentation: turn a **nucleus-tool-proxy trace** into a
+ * signed capability-boundary in-bounds attestation receipt.
+ *
+ * The trace is the real output of the tool-proxy's authorization layer: a
+ * declared boundary (a SPIFFE principal + the task-shield allowlist, i.e.
+ * `TaskWitness`'s allow-set) plus one record per observed tool call mirroring
+ * the `verdict_sink` "tool_call" span fields (`actor`, `operation`,
+ * `verdict`, `subject`, `deny_reason`). See
+ * `crates/nucleus-policy/examples/emit_toolproxy_trace.rs` for the emitter.
+ *
+ * This module maps that export into the {@link Receipt} schema and signs it.
+ * The receipt's verdict is still recomputed independently by the verifier —
+ * the producer never gets to assert in-bounds; it only records what happened.
+ */
+import { type KeyObject } from "node:crypto";
+import { type CapabilityBoundary, type TraceEvent, type Receipt } from "./attestation.js";
+/** A single observed tool call, mirroring the tool-proxy `verdict_sink` span. */
+export interface ToolProxyVerdictRecord {
+    /** SPIFFE id of the actor that made the call (`nucleus.actor`). */
+    actor: string;
+    /** Operation/tool invoked (`nucleus.operation`), canonical serde name. */
+    operation: string;
+    /** The proxy's own decision (`nucleus.verdict`). */
+    verdict: "allow" | "deny" | "error";
+    /** The call's target/argument (`nucleus.subject`), if present. */
+    subject?: string;
+    /** Proxy deny reason (`nucleus.deny_reason`), if any. */
+    deny_reason?: string;
+    /** Human-readable label, if the runtime recorded one (mutable, untrusted). */
+    displayName?: string;
+}
+/** The full trace export the emitter produces. */
+export interface ToolProxyExport {
+    boundary: {
+        principal: string;
+        allowedTools: string[];
+    };
+    records: ToolProxyVerdictRecord[];
+    /** Optional task-shield hash (provenance; not part of the receipt). */
+    taskHashHex?: string;
+}
+/** A disagreement between the proxy's decision and the recomputed verdict. */
+export interface CrossCheckIssue {
+    seq: number;
+    operation: string;
+    proxyVerdict: string;
+    recomputedInBounds: boolean;
+    note: string;
+}
+export interface AttestResult {
+    receipt: Receipt;
+    /**
+     * Sanity cross-check: the proxy's per-call decision should agree with the
+     * receipt's recomputed in-bounds finding (a proxy `deny` of an out-of-policy
+     * op should land out-of-bounds, an `allow` of an in-policy op in-bounds). A
+     * non-empty list means the trace and the declared boundary disagree — worth
+     * surfacing, though the receipt's recomputed verdict remains authoritative.
+     */
+    crossCheck: CrossCheckIssue[];
+}
+/** Build the declared {@link CapabilityBoundary} from a trace export. */
+export declare function boundaryFromExport(exp: ToolProxyExport): CapabilityBoundary;
+/** Map the proxy's verdict records into receipt {@link TraceEvent}s. */
+export declare function traceEventsFromRecords(records: ToolProxyVerdictRecord[]): TraceEvent[];
+/**
+ * Attest a tool-proxy run: build the boundary + events from the export and
+ * sign the receipt. Also runs a cross-check that the proxy's own decisions
+ * agree with the recomputed in-bounds verdict.
+ */
+export declare function attestToolProxyRun(exp: ToolProxyExport, privateKey: KeyObject, opts?: {
+    signedAt?: string;
+}): AttestResult;
+/** Parse a trace export from JSON text. Accepts the emitter's pretty output. */
+export declare function parseExport(json: string): ToolProxyExport;

package/dist/toolproxy.js

@@ -0,0 +1,74 @@
+/**
+ * Producer-side instrumentation: turn a **nucleus-tool-proxy trace** into a
+ * signed capability-boundary in-bounds attestation receipt.
+ *
+ * The trace is the real output of the tool-proxy's authorization layer: a
+ * declared boundary (a SPIFFE principal + the task-shield allowlist, i.e.
+ * `TaskWitness`'s allow-set) plus one record per observed tool call mirroring
+ * the `verdict_sink` "tool_call" span fields (`actor`, `operation`,
+ * `verdict`, `subject`, `deny_reason`). See
+ * `crates/nucleus-policy/examples/emit_toolproxy_trace.rs` for the emitter.
+ *
+ * This module maps that export into the {@link Receipt} schema and signs it.
+ * The receipt's verdict is still recomputed independently by the verifier —
+ * the producer never gets to assert in-bounds; it only records what happened.
+ */
+import { createHash } from "node:crypto";
+import { makeBoundary, signReceipt, recomputeVerdict, } from "./attestation.js";
+function sha256Hex(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+/** Build the declared {@link CapabilityBoundary} from a trace export. */
+export function boundaryFromExport(exp) {
+    return makeBoundary(exp.boundary.principal, exp.boundary.allowedTools);
+}
+/** Map the proxy's verdict records into receipt {@link TraceEvent}s. */
+export function traceEventsFromRecords(records) {
+    return records.map((r, i) => {
+        const ev = { seq: i, tool: r.operation, principal: r.actor };
+        if (r.displayName !== undefined)
+            ev.displayName = r.displayName;
+        // Bind the event to the call's target via a digest (subject is the
+        // tool-proxy's `nucleus.subject`); opaque to the in-bounds verdict.
+        if (r.subject !== undefined && r.subject !== "")
+            ev.argsDigest = sha256Hex(r.subject);
+        return ev;
+    });
+}
+/**
+ * Attest a tool-proxy run: build the boundary + events from the export and
+ * sign the receipt. Also runs a cross-check that the proxy's own decisions
+ * agree with the recomputed in-bounds verdict.
+ */
+export function attestToolProxyRun(exp, privateKey, opts = {}) {
+    const boundary = boundaryFromExport(exp);
+    const events = traceEventsFromRecords(exp.records);
+    const receipt = signReceipt(boundary, events, privateKey, opts);
+    // Cross-check the proxy's decisions against an independent recompute.
+    const recomputed = recomputeVerdict(boundary, events);
+    const crossCheck = [];
+    recomputed.events.forEach((finding, i) => {
+        const proxyVerdict = exp.records[i]?.verdict ?? "error";
+        const proxyAllowed = proxyVerdict === "allow";
+        if (proxyAllowed !== finding.inBounds) {
+            crossCheck.push({
+                seq: finding.seq,
+                operation: finding.tool,
+                proxyVerdict,
+                recomputedInBounds: finding.inBounds,
+                note: proxyAllowed
+                    ? "proxy allowed a call the declared boundary does not permit (boundary drift?)"
+                    : "proxy denied a call the declared boundary permits (extra restriction outside the boundary)",
+            });
+        }
+    });
+    return { receipt, crossCheck };
+}
+/** Parse a trace export from JSON text. Accepts the emitter's pretty output. */
+export function parseExport(json) {
+    const obj = JSON.parse(json);
+    if (!obj || typeof obj !== "object" || !obj.boundary || !Array.isArray(obj.records)) {
+        throw new Error("not a tool-proxy trace export (need { boundary, records })");
+    }
+    return obj;
+}

package/examples/converting-demo.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# converting-demo.sh — the 90-second "verify, don't trust" demo.
+#
+# Four beats: clean attests · OpenClaw bypass refused · FORGED verdict caught ·
+# CI gate. The money beat is #3 — an independent recompute catches a forged
+# claim that a *signed log* would wave through. That is the line between
+# "we have receipts too" and verifiable evidence.
+#
+# Runs against the PUBLISHED package by default (the real install story):
+#   bash examples/converting-demo.sh
+# Use the local build instead (no network):
+#   pnpm build && LOCAL=1 bash examples/converting-demo.sh
+# Pacing for screen-recording (pause between beats):
+#   PAUSE=1 bash examples/converting-demo.sh
+#
+# Requires: node, and (default mode) npx with network. Trace fixtures are the
+# real output of crates/nucleus-policy/examples/emit_toolproxy_trace.rs.
+
+set -u
+HERE="$(cd "$(dirname "$0")" && pwd)"
+CLEAN_TRACE="$HERE/sample-toolproxy-trace.clean.json"
+# Beat 2 uses the OpenClaw impersonation trace (principal mismatch under an
+# allowlisted display name). sample-toolproxy-trace.bypass.json (a tool-not-
+# allowed git_push) is the other refusal mode, gated by verify-gate.yml.
+BYPASS_TRACE="$HERE/sample-toolproxy-trace.openclaw.json"
+PRINCIPAL="spiffe://acme.example/agent/billing-assistant"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+if [ "${LOCAL:-0}" = "1" ]; then
+  DIST="$HERE/../dist"
+  ATTEST=(node "$DIST/producer-cli.js")
+  VERIFY=(node "$DIST/cli.js")
+  SRC="local build ($DIST)"
+else
+  PKG="@coproduct_inc/verify@${VERIFY_VERSION:-latest}"
+  ATTEST=(npx --yes -p "$PKG" nucleus-attest)
+  VERIFY=(npx --yes -p "$PKG" nucleus-verify)
+  SRC="published npm package $PKG"
+fi
+
+bold() { printf "\033[1m%s\033[0m\n" "$*"; }
+dim()  { printf "\033[2m%s\033[0m\n" "$*"; }
+ok()   { printf "\033[32m%s\033[0m\n" "$*"; }
+bad()  { printf "\033[31m%s\033[0m\n" "$*"; }
+beat() { echo; bold "── $* ──"; [ "${PAUSE:-0}" = "1" ] && read -r -p "  (enter)…" _ || true; }
+
+echo
+bold "@coproduct_inc/verify — verify, don't trust"
+dim  "source: $SRC"
+dim  "An agent run's tool-call trace + a declared capability boundary →"
+dim  "a signed, OFFLINE-verifiable in-bounds attestation. We don't trust the"
+dim  "issuer's verdict — we recompute it."
+
+# ── Beat 1: a clean run attests ──────────────────────────────────────────────
+beat "1/4  Clean run → ATTESTS (exit 0)"
+dim "nucleus-attest < clean-trace  →  nucleus-verify"
+"${ATTEST[@]}" "$CLEAN_TRACE" > "$TMP/clean.json" 2> "$TMP/clean.err"
+if "${VERIFY[@]}" "$TMP/clean.json" --expect-principal "$PRINCIPAL"; then
+  ok "  → exit 0. Auditor-grade evidence the agent stayed inside its boundary."
+else
+  bad "  unexpected: clean run did not verify"; exit 1
+fi
+
+# ── Beat 2: the OpenClaw bypass is refused ───────────────────────────────────
+beat "2/4  OpenClaw bypass (display-name match, principal mismatch) → REFUSED (exit 1)"
+dim "An injected call wears the allowlisted display name but a different SPIFFE id."
+"${ATTEST[@]}" "$BYPASS_TRACE" > "$TMP/bypass.json" 2> "$TMP/bypass.err"
+if "${VERIFY[@]}" "$TMP/bypass.json"; then
+  bad "  unexpected: bypass verified (should refuse)"; exit 1
+else
+  ok "  → exit 1. CVE-2026-25253's failure class, ruled out by construction"
+  ok "    (the boundary is keyed on the cryptographic principal, never the name)."
+fi
+
+# ── Beat 3: the money beat — a forged verdict is caught ───────────────────────
+beat "3/4  FORGE the verdict (claim inBounds:true) → CAUGHT"
+dim "A signed LOG would trust this. We recompute the verdict independently."
+node -e '
+  const fs = require("fs");
+  const r = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+  r.verdict.inBounds = true;
+  r.verdict.events = r.verdict.events.map(e => ({...e, inBounds:true, code:"ok", detail:"in bounds"}));
+  fs.writeFileSync(process.argv[2], JSON.stringify(r));
+' "$TMP/bypass.json" "$TMP/forged.json"
+"${VERIFY[@]}" "$TMP/forged.json" --json > "$TMP/forged.report.json" 2>/dev/null || true
+SIG=$(node -e 'console.log(require(process.argv[1]).signatureOk)' "$TMP/forged.report.json")
+CONS=$(node -e 'console.log(require(process.argv[1]).verdictConsistentOk)' "$TMP/forged.report.json")
+OKV=$(node -e 'console.log(require(process.argv[1]).ok)' "$TMP/forged.report.json")
+echo "  signatureOk=$SIG  verdictConsistentOk=$CONS  ok=$OKV"
+if [ "$OKV" = "false" ] && [ "$CONS" = "false" ]; then
+  ok "  → REJECTED two independent ways: the recompute disagrees with the claim,"
+  ok "    AND the signature (taken over the honest verdict) no longer verifies."
+  ok "    THIS is verifiable evidence, not a signed log you have to trust."
+else
+  bad "  unexpected: forged receipt was not caught"; exit 1
+fi
+
+# ── Beat 4: it's a CI merge gate, not a dashboard ────────────────────────────
+beat "4/4  It's a merge gate, not a dashboard"
+dim "Drop the Action in a PR; an out-of-bounds run fails the build:"
+cat <<'YAML'
+  - uses: coproduct-private/spiffy/packages/nucleus-verify@main
+    with:
+      receipt: ./agent-run-receipt.json
+      expect-principal: spiffe://acme/agent/billing-assistant
+YAML
+ok "  clean → check passes · out-of-bounds → check fails. Exit codes are the gate."
+
+echo
+bold "Summary"
+echo "  • Works above ANY runtime/guardrail (incl. Microsoft AGT) — neutral verifier."
+echo "  • Offline, zero runtime deps (node:crypto). 30-second npx drop-in."
+echo "  • The verdict logic is backed by machine-checked theorems (IFC noninterference)."
+echo "  • Honest scope: attests the DECLARED boundary over the OBSERVED trace —"
+echo "    completeness of trace capture is the runtime's job."
+ok "DEMO OK ✓"

package/examples/sample-toolproxy-trace.bypass.json

@@ -0,0 +1,34 @@
+{
+  "boundary": {
+    "allowedTools": [
+      "read_files",
+      "glob_search",
+      "grep_search"
+    ],
+    "principal": "spiffe://acme.example/agent/billing-assistant"
+  },
+  "records": [
+    {
+      "actor": "spiffe://acme.example/agent/billing-assistant",
+      "deny_reason": "",
+      "operation": "glob_search",
+      "subject": "invoices/*.pdf",
+      "verdict": "allow"
+    },
+    {
+      "actor": "spiffe://acme.example/agent/billing-assistant",
+      "deny_reason": "",
+      "operation": "read_files",
+      "subject": "invoices/2026-06.pdf",
+      "verdict": "allow"
+    },
+    {
+      "actor": "spiffe://acme.example/agent/billing-assistant",
+      "deny_reason": "operation outside declared task allowlist",
+      "operation": "git_push",
+      "subject": "refs/heads/main",
+      "verdict": "deny"
+    }
+  ],
+  "taskHashHex": "8aa9199f47bc66272e3a40e87d8ef6daeec2e905e5a723252e615c45c4376888"
+}

package/examples/sample-toolproxy-trace.clean.json

@@ -0,0 +1,41 @@
+{
+  "boundary": {
+    "allowedTools": [
+      "read_files",
+      "glob_search",
+      "grep_search"
+    ],
+    "principal": "spiffe://acme.example/agent/billing-assistant"
+  },
+  "records": [
+    {
+      "actor": "spiffe://acme.example/agent/billing-assistant",
+      "deny_reason": "",
+      "operation": "glob_search",
+      "subject": "invoices/*.pdf",
+      "verdict": "allow"
+    },
+    {
+      "actor": "spiffe://acme.example/agent/billing-assistant",
+      "deny_reason": "",
+      "operation": "read_files",
+      "subject": "invoices/2026-06.pdf",
+      "verdict": "allow"
+    },
+    {
+      "actor": "spiffe://acme.example/agent/billing-assistant",
+      "deny_reason": "",
+      "operation": "grep_search",
+      "subject": "TOTAL",
+      "verdict": "allow"
+    },
+    {
+      "actor": "spiffe://acme.example/agent/billing-assistant",
+      "deny_reason": "",
+      "operation": "read_files",
+      "subject": "invoices/2026-05.pdf",
+      "verdict": "allow"
+    }
+  ],
+  "taskHashHex": "8aa9199f47bc66272e3a40e87d8ef6daeec2e905e5a723252e615c45c4376888"
+}

package/examples/sample-toolproxy-trace.openclaw.json

@@ -0,0 +1,24 @@
+{
+  "boundary": {
+    "principal": "spiffe://acme.example/agent/billing-assistant",
+    "allowedTools": ["read_files", "glob_search", "grep_search"]
+  },
+  "_note": "OpenClaw-class impersonation trace (CVE-2026-25253 shape): event #1 wears the allowlisted displayName 'Billing Assistant' but carries an ATTACKER SPIFFE id. Real export shape; the boundary is keyed on the cryptographic principal, so the receipt refuses to attest it.",
+  "records": [
+    {
+      "actor": "spiffe://acme.example/agent/billing-assistant",
+      "operation": "glob_search",
+      "verdict": "allow",
+      "subject": "invoices/*.pdf",
+      "deny_reason": ""
+    },
+    {
+      "actor": "spiffe://acme.example/agent/unknown-7f3a",
+      "operation": "read_files",
+      "verdict": "deny",
+      "subject": "invoices/2026-06.pdf",
+      "displayName": "Billing Assistant",
+      "deny_reason": "presented identity not bound to the declared principal"
+    }
+  ]
+}

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@coproduct_inc/verify",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Offline, zero-trust verification of agent capability-boundary in-bounds attestation receipts: emit and verify an Ed25519-signed, hash-chained receipt that an agent run stayed within a declared boundary, keyed on a cryptographic principal (not a mutable display name) — the evidence layer above probabilistic guardrails. Also verifies Nucleus auction receipts by re-running the clearing locally. Zero runtime deps for the attestation core (node:crypto).",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "nucleus-verify": "dist/cli.js"
+    "nucleus-verify": "dist/cli.js",
+    "nucleus-attest": "dist/producer-cli.js",
+    "nucleus-license": "dist/license-cli.js"
   },
   "exports": {
     ".": {
@@ -17,6 +19,14 @@
     "./attestation": {
       "types": "./dist/attestation.d.ts",
       "import": "./dist/attestation.js"
+    },
+    "./toolproxy": {
+      "types": "./dist/toolproxy.d.ts",
+      "import": "./dist/toolproxy.js"
+    },
+    "./license": {
+      "types": "./dist/license.d.ts",
+      "import": "./dist/license.js"
     }
   },
   "files": [
@@ -27,7 +37,13 @@
     "wasm/nodejs/nucleus_wasm_bg.wasm",
     "wasm/nodejs/nucleus_wasm_bg.wasm.d.ts",
     "examples/openclaw-replay.mjs",
-    "README.md"
+    "examples/converting-demo.sh",
+    "examples/sample-toolproxy-trace.clean.json",
+    "examples/sample-toolproxy-trace.bypass.json",
+    "examples/sample-toolproxy-trace.openclaw.json",
+    "README.md",
+    "WHY-VERIFY.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build:wasm": "wasm-pack build ../../crates/nucleus-wasm --target nodejs --out-dir ../../packages/nucleus-verify/wasm/nodejs && rm -f wasm/nodejs/.gitignore wasm/nodejs/package.json",