@coproduct_inc/verify 0.3.0 → 0.6.0

package/dist/workflow.js

@@ -0,0 +1,201 @@
+// The DAG cage: compose a multi-agent run into ONE verifiable workflow receipt.
+//
+// A single agent you can eyeball; a DAG of agents you can't. The dangerous
+// failure mode only exists at DAG scale: every node is locally in-bounds, yet a
+// secret laundered from a source node, through an innocent middle, to a sink.
+// Per-node checks ALL pass; only the whole-workflow check catches it. This is
+// that check, at the orchestration layer — a receipt-level analog of the
+// bytecode noninterference proof, that rides on whatever orchestrator you use.
+//
+//   const wf = new Workflow("spiffe://acme/intake-pipeline");
+//   const reader   = wf.node({ id: "reader",   boundary: ["read_secret", "emit"] });
+//   const middle   = wf.node({ id: "middle",   boundary: ["transform", "emit"], after: ["reader"] });
+//   const writer   = wf.node({ id: "writer",   boundary: ["publish"],           after: ["middle"] });
+//   …run your agents, calling these caged tools…
+//   const receipt = wf.attest(privateKey);
+//
+//   // your customer verifies the whole DAG offline, including the flow policy:
+//   verifyWorkflowReceipt(receipt, { sources: ["read_secret"], sinks: ["publish"] });
+//   // → flowOk:false if a secret could reach `publish`, even though every node was in-bounds.
+import { createHash, createPublicKey, sign as edSign, verify as edVerify } from "node:crypto";
+import { Cage } from "./cage.js";
+import { canonicalize, exportPublicKey } from "./attestation.js";
+import { traceEventsFromRecords } from "./toolproxy.js";
+import { ifcDecide } from "./ifc-decide.js";
+const WF_KIND = "nucleus.workflow-receipt.v1";
+function sha256Hex(s) {
+    return createHash("sha256").update(s).digest("hex");
+}
+function importPublicKey(x) {
+    return createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x }, format: "jwk" });
+}
+/** Topological order of the node ids; throws on a cycle. */
+function topoOrder(nodes) {
+    const ids = new Set(nodes.map((n) => n.id));
+    const indeg = new Map();
+    const children = new Map();
+    for (const n of nodes) {
+        indeg.set(n.id, 0);
+        children.set(n.id, []);
+    }
+    for (const n of nodes) {
+        for (const p of n.after) {
+            if (!ids.has(p))
+                throw new Error(`edge from unknown node "${p}"`);
+            indeg.set(n.id, (indeg.get(n.id) ?? 0) + 1);
+            children.get(p).push(n.id);
+        }
+    }
+    const queue = [...indeg].filter(([, d]) => d === 0).map(([id]) => id);
+    const order = [];
+    while (queue.length) {
+        const id = queue.shift();
+        order.push(id);
+        for (const c of children.get(id)) {
+            indeg.set(c, indeg.get(c) - 1);
+            if (indeg.get(c) === 0)
+                queue.push(c);
+        }
+    }
+    if (order.length !== nodes.length)
+        throw new Error("workflow graph has a cycle");
+    return order;
+}
+/**
+ * Recompute the information flow across the DAG, delegating each sink's VERDICT
+ * to the proven model (`ifcDecide`, compiled from nucleus-ifc). The DAG walk
+ * accumulates the declared-input KINDS reaching each node (a `source` tool
+ * declares a `secret` input, an `adversarialSource` declares `web_content`); a
+ * declassifier clears them; at a sink we ask the proven `decide()` whether that
+ * input set may reach that sink. So the topology is ours, the IFC decision is
+ * the one nucleus runs — not a TS mirror.
+ */
+function recomputeFlow(nodes, flow) {
+    const sources = new Set(flow.sources);
+    const adversarial = new Set(flow.adversarialSources ?? []);
+    const sinks = new Set(flow.sinks);
+    const actionSinks = new Set(flow.actionSinks ?? []);
+    const declass = new Set(flow.declassifiers ?? []);
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const inputsAt = new Map();
+    const leaks = [];
+    for (const id of topoOrder(nodes)) {
+        const n = byId.get(id);
+        const tools = new Set(n.events.map((e) => e.tool));
+        const acc = new Set();
+        for (const p of n.after)
+            for (const t of inputsAt.get(p))
+                acc.add(t); // inherit upstream inputs
+        const readsSecret = [...tools].some((t) => sources.has(t));
+        const readsWeb = [...tools].some((t) => adversarial.has(t));
+        if (readsSecret)
+            acc.add("secret");
+        if (readsWeb)
+            acc.add("web_content");
+        if (declass.has(id))
+            acc.clear(); // a declassifier sanitizes incoming + own inputs
+        inputsAt.set(id, acc);
+        const declared = [...acc];
+        const via = (readsSecret || readsWeb) && !declass.has(id) ? "reads-source" : "upstream";
+        for (const t of tools) {
+            if (sinks.has(t) && !ifcDecide(declared, { sinkPublic: true }).allow)
+                leaks.push({ node: id, sink: t, taintedVia: via });
+            if (actionSinks.has(t) && !ifcDecide(declared, { requiresAuthority: true }).allow)
+                leaks.push({ node: id, sink: t, taintedVia: via });
+        }
+    }
+    return leaks;
+}
+function nodesForHash(nodes) {
+    return nodes.map((n) => ({ id: n.id, after: n.after, boundary: n.boundary, events: n.events }));
+}
+/**
+ * A DAG cage. Register nodes (each gets a {@link Cage}), run your agents through
+ * the caged tools, then {@link Workflow.attest} a single signed receipt over the
+ * whole graph — verifiable offline, including the cross-node information flow.
+ */
+export class Workflow {
+    principal;
+    nodes = new Map();
+    constructor(principal) {
+        this.principal = principal;
+    }
+    /** Register a node and return its cage. The cage's tool calls are recorded
+     *  under this node; `after` declares the edges into it. */
+    node(spec) {
+        if (this.nodes.has(spec.id))
+            throw new Error(`duplicate node id "${spec.id}"`);
+        const cage = new Cage({ principal: `${this.principal}#${spec.id}`, allowedTools: spec.boundary });
+        this.nodes.set(spec.id, { id: spec.id, after: spec.after ?? [], boundary: spec.boundary, cage });
+        return cage;
+    }
+    receiptNodes() {
+        return [...this.nodes.values()].map((n) => {
+            const events = traceEventsFromRecords(n.cage.toExport().records);
+            const inBounds = events.every((e) => n.boundary.includes(e.tool));
+            return { id: n.id, after: n.after, boundary: n.boundary, events, inBounds };
+        });
+    }
+    /** Sign one workflow receipt over the whole DAG. */
+    attest(privateKey, opts = {}) {
+        const nodes = this.receiptNodes();
+        const rootHash = sha256Hex(canonicalize(nodesForHash(nodes)));
+        const pub = createPublicKey(privateKey);
+        const body = canonicalize({ kind: WF_KIND, principal: this.principal, rootHash });
+        const signature = edSign(null, Buffer.from(body, "utf8"), privateKey).toString("base64");
+        return {
+            kind: WF_KIND,
+            principal: this.principal,
+            nodes,
+            rootHash,
+            publicKey: exportPublicKey(pub),
+            signature,
+            ...(opts.signedAt ? { signedAt: opts.signedAt } : {}),
+        };
+    }
+}
+/**
+ * Verify a workflow receipt fully and offline: the signature + the per-node
+ * in-bounds recompute + the DAG (acyclic, real edges) + the cross-node
+ * information flow. Never throws — failures surface as `ok:false` + `reason`.
+ */
+export function verifyWorkflowReceipt(wr, flow) {
+    // 1. signature + rootHash (the receipt is bound to its node set).
+    const recomputedRoot = sha256Hex(canonicalize(nodesForHash(wr.nodes)));
+    const rootOk = recomputedRoot === wr.rootHash;
+    let sigOnly = false;
+    try {
+        const body = canonicalize({ kind: wr.kind, principal: wr.principal, rootHash: wr.rootHash });
+        sigOnly = edVerify(null, Buffer.from(body, "utf8"), importPublicKey(wr.publicKey), Buffer.from(wr.signature, "base64"));
+    }
+    catch {
+        sigOnly = false;
+    }
+    const signatureOk = sigOnly && rootOk;
+    // 2. per-node in-bounds, recomputed from the signed events (not trusted).
+    const outOfBoundsNodes = wr.nodes.filter((n) => !n.events.every((e) => n.boundary.includes(e.tool))).map((n) => n.id);
+    const nodesOk = outOfBoundsNodes.length === 0;
+    // 3. DAG well-formed + 4. information flow.
+    let dagOk = true;
+    let leaks = [];
+    try {
+        topoOrder(wr.nodes); // throws on cycle / unknown edge
+        if (flow)
+            leaks = recomputeFlow(wr.nodes, flow);
+    }
+    catch {
+        dagOk = false;
+    }
+    const flowOk = leaks.length === 0;
+    const ok = signatureOk && nodesOk && dagOk && flowOk;
+    let reason = null;
+    if (!signatureOk)
+        reason = rootOk ? "signature did not verify" : "rootHash does not match the node set (tampered)";
+    else if (!dagOk)
+        reason = "workflow graph is cyclic or references an unknown node";
+    else if (!nodesOk)
+        reason = `nodes out of bounds: ${outOfBoundsNodes.join(", ")}`;
+    else if (!flowOk)
+        reason = `information-flow leak: ${leaks.map((l) => `${l.node}→${l.sink}`).join(", ")}`;
+    return { ok, signatureOk, dagOk, nodesOk, flowOk, leaks, outOfBoundsNodes, reason };
+}

package/examples/cage-quickstart.mjs

@@ -0,0 +1,37 @@
+// The 5-minute drop-in, end to end. Run:  node examples/cage-quickstart.mjs
+//
+// You ship an AI agent that takes actions for a customer. They won't take your
+// word that it stayed in bounds. So: cage its tool calls, and hand them a
+// receipt they verify themselves — trust the math, not you.
+import { Cage, generateKeypair, verifyReceipt } from "../dist/index.js";
+
+// 1. Declare the agent's capability boundary (what it's allowed to touch).
+const cage = new Cage({
+  principal: "spiffe://acme/support-agent", // any stable id keyed to a key, not a name
+  allowedTools: ["search", "read_ticket", "send_reply", "refund"],
+});
+
+// 2. Wrap each tool. A guard adds a finer runtime check (never refund over $50).
+const search = cage.tool("search", async (q) => `(results for "${q}")`);
+const reply = cage.tool("send_reply", async (msg) => `sent: ${msg}`);
+const refund = cage.tool("refund", async (cents) => `refunded ${cents}c`, { guard: (c) => c <= 5000 });
+const wire = cage.tool("wire_transfer", async (acct) => `wired to ${acct}`); // NOT granted
+
+// 3. Run your agent — calling ONLY the caged tools.
+await search("refund policy");
+await reply("Here's our policy …");
+try { await refund(999999); } catch (e) { console.log("⛔ guard blocked over-cap refund:", e.message); }
+try { await wire("0xbad"); } catch (e) { console.log("⛔ blocked out-of-boundary tool:", e.message); }
+
+// 4. Emit a signed receipt and hand it to your customer.
+const { privateKey } = generateKeypair();
+const receipt = cage.attest(privateKey);
+
+// 5. THEY verify it — offline, no trust in you. (Or: npx @coproduct_inc/verify receipt.json)
+const report = verifyReceipt(receipt);
+console.log("\nreceipt verified:", report.ok ? "✓ clean run" : "✗ " + report.reason);
+console.log("  signature ok :", report.signatureOk);
+console.log("  in bounds    :", report.inBounds, "(every call was to an allowed tool)");
+console.log("  recorded calls:", receipt.events.map((e) => e.tool).join(", "));
+console.log("\nThe receipt is the wedge: useful to you alone today, more valuable as a");
+console.log("network of recomputable receipts forms. Don't trust the seller — recompute.");

package/examples/workflow-leak.mjs

@@ -0,0 +1,40 @@
+// The DAG cage, end to end — and the failure that only exists at multi-agent
+// scale. Run:  node examples/workflow-leak.mjs
+//
+// A single agent you can eyeball. A DAG of agents you can't: every node passes
+// its OWN check, yet a secret launders through the pipeline to a public write.
+// Per-node review misses it. The workflow receipt catches it.
+import { Workflow, verifyWorkflowReceipt, generateKeypair } from "../dist/index.js";
+
+// A 3-agent intake pipeline: reader → enricher → publisher.
+const wf = new Workflow("spiffe://acme/intake-pipeline");
+const reader = wf.node({ id: "reader", boundary: ["read_secret", "emit"] });
+const enrich = wf.node({ id: "enricher", boundary: ["transform", "emit"], after: ["reader"] });
+const publish = wf.node({ id: "publisher", boundary: ["publish"], after: ["enricher"] });
+
+// Run your agents through the caged tools. Each node only touches tools it's
+// allowed to — locally, everything is in policy.
+reader.tool("read_secret", () => "customer SSN")(); // allowed for the reader
+reader.tool("emit", (x) => x)();
+enrich.tool("transform", (x) => x)(); // an "innocent" pass-through middle
+enrich.tool("emit", (x) => x)();
+publish.tool("publish", (x) => x)(); // allowed for the publisher
+
+const { privateKey } = generateKeypair();
+const receipt = wf.attest(privateKey);
+
+// Your customer verifies the WHOLE DAG offline, with a flow policy:
+//   the secret source must never reach the public sink.
+const report = verifyWorkflowReceipt(receipt, { sources: ["read_secret"], sinks: ["publish"] });
+
+console.log("per-node review (what a code reviewer sees):");
+for (const n of receipt.nodes) console.log(`  ${n.id.padEnd(10)} in-bounds: ${n.inBounds}  (${n.events.map((e) => e.tool).join(", ")})`);
+console.log("\nevery node is in-bounds:", report.nodesOk);
+console.log("signature valid       :", report.signatureOk);
+console.log("\nwhole-workflow verdict:", report.ok ? "✓ ok" : "✗ " + report.reason);
+for (const l of report.leaks) console.log(`  ⛔ leak: a secret reaches "${l.sink}" at node "${l.node}" (${l.taintedVia})`);
+
+console.log("\nThe per-node checks ALL passed. Only the composition catches it.");
+console.log("Add a sanitizer? declare the middle a declassifier:");
+const fixed = verifyWorkflowReceipt(receipt, { sources: ["read_secret"], sinks: ["publish"], declassifiers: ["enricher"] });
+console.log("  with enricher sanitizing →", fixed.ok ? "✓ ok (flow broken)" : "✗ " + fixed.reason);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@coproduct_inc/verify",
-  "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).",
+  "version": "0.6.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) \u2014 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",
@@ -9,13 +9,22 @@
   "bin": {
     "nucleus-verify": "dist/cli.js",
     "nucleus-attest": "dist/producer-cli.js",
-    "nucleus-license": "dist/license-cli.js"
+    "nucleus-license": "dist/license-cli.js",
+    "nucleus-verify-claim": "dist/claim-cli.js"
   },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./workflow": {
+      "types": "./dist/workflow.d.ts",
+      "import": "./dist/workflow.js"
+    },
+    "./ifc": {
+      "types": "./dist/ifc.d.ts",
+      "import": "./dist/ifc.js"
+    },
     "./attestation": {
       "types": "./dist/attestation.d.ts",
       "import": "./dist/attestation.js"
@@ -24,6 +33,10 @@
       "types": "./dist/toolproxy.d.ts",
       "import": "./dist/toolproxy.js"
     },
+    "./cage": {
+      "types": "./dist/cage.d.ts",
+      "import": "./dist/cage.js"
+    },
     "./license": {
       "types": "./dist/license.d.ts",
       "import": "./dist/license.js"
@@ -37,6 +50,8 @@
     "wasm/nodejs/nucleus_wasm_bg.wasm",
     "wasm/nodejs/nucleus_wasm_bg.wasm.d.ts",
     "examples/openclaw-replay.mjs",
+    "examples/cage-quickstart.mjs",
+    "examples/workflow-leak.mjs",
     "examples/converting-demo.sh",
     "examples/sample-toolproxy-trace.clean.json",
     "examples/sample-toolproxy-trace.bypass.json",
@@ -46,11 +61,12 @@
     "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",
+    "build:wasm": "wasm-pack build ../../crates/nucleus-wasm --target nodejs --out-dir ../../packages/nucleus-verify/wasm/nodejs && rm -f wasm/nodejs/.gitignore && printf '%s' '{\"type\":\"commonjs\"}' > wasm/nodejs/package.json",
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "node --test",
-    "demo": "node examples/openclaw-replay.mjs"
+    "demo": "node examples/openclaw-replay.mjs",
+    "build:browser": "esbuild src/attestation.browser.ts --bundle --format=esm --alias:node:crypto=./src/shim/node-crypto.mjs --banner:js=\"globalThis.Buffer||={from:(i,e)=>e==='base64'?Uint8Array.from(atob(i),c=>c.charCodeAt(0)):new TextEncoder().encode(i)};\" --outfile=dist/attestation.browser.js"
   },
   "keywords": [
     "nucleus",
@@ -73,5 +89,9 @@
   "devDependencies": {
     "@types/node": "^25.9.1",
     "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "@noble/ed25519": "3.1.0",
+    "@noble/hashes": "2.2.0"
   }
 }

package/wasm/nodejs/nucleus_wasm.d.ts

@@ -51,6 +51,21 @@ export function compute_dependency_graph(chain_jsonl: string): any;
  */
 export function compute_savings_summary(plan_json: string, cost_map_json: string): any;
 
+/**
+ * **The ONE proven IFC decision, surfaced to JS.** Recomputes the
+ * `FlowDeclaration → IfcVerdict` decision over the Denning lattice from
+ * `nucleus-ifc` (whose lattice laws are Lean-proven in `portcullis-core`) — the
+ * SAME `decide()` the production gate runs. `@coproduct_inc/verify`'s DAG-cage
+ * flow check delegates here instead of a TS mirror, so there is one model.
+ *
+ * `input_tokens_json` is a JSON array of declared-input tokens — one of:
+ * `user_prompt`, `web_content`, `tool_response`, `file_read`, `env_var`,
+ * `secret`, `database_row`, `memory_read`, `http_response`. `requires_authority`
+ * = the action needs directive authority; `sink_public` = the sink is publicly
+ * visible. Returns the recomputable `IfcVerdict` (allow/deny + reason).
+ */
+export function ifc_decide(input_tokens_json: string, requires_authority: boolean, sink_public: boolean): any;
+
 /**
  * Install a browser-friendly panic hook. The hook routes any wasm-side
  * `panic!` into `console.error`, which means failed assertions in the

package/wasm/nodejs/nucleus_wasm.js

@@ -89,6 +89,34 @@ function compute_savings_summary(plan_json, cost_map_json) {
 }
 exports.compute_savings_summary = compute_savings_summary;
 
+/**
+ * **The ONE proven IFC decision, surfaced to JS.** Recomputes the
+ * `FlowDeclaration → IfcVerdict` decision over the Denning lattice from
+ * `nucleus-ifc` (whose lattice laws are Lean-proven in `portcullis-core`) — the
+ * SAME `decide()` the production gate runs. `@coproduct_inc/verify`'s DAG-cage
+ * flow check delegates here instead of a TS mirror, so there is one model.
+ *
+ * `input_tokens_json` is a JSON array of declared-input tokens — one of:
+ * `user_prompt`, `web_content`, `tool_response`, `file_read`, `env_var`,
+ * `secret`, `database_row`, `memory_read`, `http_response`. `requires_authority`
+ * = the action needs directive authority; `sink_public` = the sink is publicly
+ * visible. Returns the recomputable `IfcVerdict` (allow/deny + reason).
+ * @param {string} input_tokens_json
+ * @param {boolean} requires_authority
+ * @param {boolean} sink_public
+ * @returns {any}
+ */
+function ifc_decide(input_tokens_json, requires_authority, sink_public) {
+    const ptr0 = passStringToWasm0(input_tokens_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.ifc_decide(ptr0, len0, requires_authority, sink_public);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.ifc_decide = ifc_decide;
+
 /**
  * Install a browser-friendly panic hook. The hook routes any wasm-side
  * `panic!` into `console.error`, which means failed assertions in the

package/wasm/nodejs/nucleus_wasm_bg.wasm.d.ts

@@ -4,6 +4,7 @@ export const memory: WebAssembly.Memory;
 export const analyze_correction_event: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const compute_dependency_graph: (a: number, b: number) => [number, number, number];
 export const compute_savings_summary: (a: number, b: number, c: number, d: number) => [number, number, number];
+export const ifc_decide: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const parse_claude_code_session: (a: number, b: number) => [number, number, number];
 export const parse_lineage_chain: (a: number, b: number) => [number, number, number];
 export const verify_auction_receipt: (a: number, b: number, c: number, d: number) => [number, number, number];

package/wasm/nodejs/package.json

@@ -1,9 +1 @@
-{
-  "name": "nucleus-wasm-nodejs-core",
-  "version": "0.1.0",
-  "private": true,
-  "type": "commonjs",
-  "main": "nucleus_wasm.js",
-  "types": "nucleus_wasm.d.ts",
-  "comment": "wasm-pack `nodejs` target (CommonJS). This nested package.json pins `type: commonjs` so the CJS `require`/`module.exports`/`__dirname` glue keeps working when imported from the ESM `@nucleus/verify` parent. Regenerated by `pnpm build:wasm`; do not hand-edit the sibling .js/.wasm."
-}
+{"type":"commonjs"}