@coproduct_inc/verify 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to `@coproduct_inc/verify`.
+
+## 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

@@ -68,6 +68,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/dist/index.d.ts

@@ -94,3 +94,4 @@ 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";

package/dist/index.js

@@ -67,3 +67,6 @@ 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";

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/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@coproduct_inc/verify",
-  "version": "0.1.0",
+  "version": "0.2.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"
   },
   "exports": {
     ".": {
@@ -17,6 +18,10 @@
     "./attestation": {
       "types": "./dist/attestation.d.ts",
       "import": "./dist/attestation.js"
+    },
+    "./toolproxy": {
+      "types": "./dist/toolproxy.d.ts",
+      "import": "./dist/toolproxy.js"
     }
   },
   "files": [
@@ -27,7 +32,8 @@
     "wasm/nodejs/nucleus_wasm_bg.wasm",
     "wasm/nodejs/nucleus_wasm_bg.wasm.d.ts",
     "examples/openclaw-replay.mjs",
-    "README.md"
+    "README.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",