@decidio/sdk 0.1.5 → 0.1.7

package/dist/resume.js

@@ -1,26 +1,42 @@
-// @decidio/sdk — durable async resume.
-//
-// The hard problem behind a "one-line" agent gate: a real human approval takes
-// minutes to days. Nobody watches a 60-second polling window. So a routed action
-// must SUSPEND (the requesting process may even exit) and RESUME later when the
-// approval arrives — and the AGENT must perform its own action on resume. Decidio
-// stays the approval layer above: it authorizes, records, and (on approval) SIGNALS
-// the agent. It never holds the agent's downstream credentials and never executes
-// the write itself. This is the same shape as HumanLayer's webhooks, Temporal
-// Signals, Inngest waitForEvent, and Decidio's own A2A `input-required` state.
-//
-// Two resume transports, same core:
-//   • webhookHandler() — production: Decidio POSTs a signed verdict to the agent's
-//     resume URL; the handler re-executes the agent's own fn and confirms.
-//   • worker()         — no inbound URL (laptop/CLI): a long-lived watcher polls
-//     /agent/status for each pending decision, then re-executes on approval.
-// Either way the args are replayed from an AGENT-SIDE store (Decidio holds none of
-// the downstream payload — only the authority decision), and execution is single-use
-// (the pending entry is deleted on completion, so a duplicate signal can't double-write).
-import { createHmac, timingSafeEqual } from "node:crypto";
+import { createHmac, timingSafeEqual, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify } from "node:crypto";
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync, renameSync } from "node:fs";
 import { join } from "node:path";
-import { signConfirm } from "./signing.js";
+import { signConfirm, canonicalize } from "./signing.js";
+const argsBindingBytes = (p) => Buffer.from(canonicalize({ decisionId: p.decisionId, action: p.action, amount: p.amount, ...(p.scope !== undefined ? { scope: p.scope } : {}), args: p.args }), "utf8");
+function signArgs(p, agentKey, webhookSecret) {
+    const bytes = argsBindingBytes(p);
+    if (agentKey) {
+        try {
+            const key = createPrivateKey({ key: Buffer.from(agentKey, "base64"), format: "der", type: "pkcs8" });
+            return { kind: "ed25519", sig: Buffer.from(edSign(null, bytes, key)).toString("base64url") };
+        }
+        catch { }
+    }
+    if (webhookSecret)
+        return { kind: "hmac", sig: createHmac("sha256", webhookSecret).update(bytes).digest("hex") };
+    return undefined;
+}
+function verifyArgs(p, agentKey, webhookSecret) {
+    if (!p.argsSig)
+        return "unbound";
+    const bytes = argsBindingBytes(p);
+    try {
+        if (p.argsSig.kind === "ed25519") {
+            if (!agentKey)
+                return "unverifiable";
+            const pub = createPublicKey(createPrivateKey({ key: Buffer.from(agentKey, "base64"), format: "der", type: "pkcs8" }));
+            return edVerify(null, bytes, pub, Buffer.from(p.argsSig.sig, "base64url")) ? "ok" : "mismatch";
+        }
+        if (!webhookSecret)
+            return "unverifiable";
+        const expected = createHmac("sha256", webhookSecret).update(bytes).digest("hex");
+        const a = Buffer.from(expected), b = Buffer.from(p.argsSig.sig);
+        return a.length === b.length && timingSafeEqual(a, b) ? "ok" : "mismatch";
+    }
+    catch {
+        return "mismatch";
+    }
+}
 export class MemoryPendingStore {
     m = new Map();
     claimed = new Set();
@@ -32,11 +48,6 @@ export class MemoryPendingStore {
         return false; this.claimed.add(id); return true; }
     async release(id) { this.claimed.delete(id); }
 }
-/** File-backed store so a COLD process (the original requester long gone) can still
- *  resume — the proof that nothing is "kept alive". One JSON file per decision. A claim
- *  renames `<id>.json` → `<id>.claimed` atomically (same-volume rename), so two processes
- *  sharing the dir can't both execute. (A stale `.claimed` from a crash mid-execute needs
- *  TTL recovery — tracked in the backlog.) */
 export class FilePendingStore {
     dir;
     constructor(dir) {
@@ -46,7 +57,7 @@ export class FilePendingStore {
     key(id) { return id.replace(/[^\w.-]/g, "_"); }
     path(id) { return join(this.dir, `${this.key(id)}.json`); }
     claimedPath(id) { return join(this.dir, `${this.key(id)}.claimed`); }
-    async put(p) { writeFileSync(this.path(p.decisionId), JSON.stringify(p, null, 2)); }
+    async put(p) { writeFileSync(this.path(p.decisionId), JSON.stringify(p, null, 2), { mode: 0o600 }); }
     async get(id) {
         for (const f of [this.path(id), this.claimedPath(id)])
             if (existsSync(f))
@@ -59,14 +70,22 @@ export class FilePendingStore {
     async list() {
         if (!existsSync(this.dir))
             return [];
-        return readdirSync(this.dir).filter((f) => f.endsWith(".json")) // claimed (.claimed) excluded — in flight
-            .map((f) => JSON.parse(readFileSync(join(this.dir, f), "utf8")));
+        const out = [];
+        for (const f of readdirSync(this.dir).filter((f) => f.endsWith(".json"))) {
+            try {
+                out.push(JSON.parse(readFileSync(join(this.dir, f), "utf8")));
+            }
+            catch (e) {
+                console.error(`[decidio] skipping unreadable parked entry ${f} (${e.message}) — the other parked actions still resume; inspect or delete this file.`);
+            }
+        }
+        return out;
     }
     async claim(id) {
         try {
             renameSync(this.path(id), this.claimedPath(id));
             return true;
-        } // atomic; fails if already claimed/gone
+        }
         catch {
             return false;
         }
@@ -75,13 +94,9 @@ export class FilePendingStore {
         try {
             renameSync(this.claimedPath(id), this.path(id));
         }
-        catch { /* already released/gone */ }
+        catch { }
     }
 }
-/** Thrown by a `withApproval`-wrapped call when the action is routed and configured
- *  for async resume: the action is now SUSPENDED (parked in the store), not failed.
- *  The caller can stop here — the process may even exit; the resume transport will
- *  complete it later. */
 export class DecidioSuspendedError extends Error {
     decisionId;
     action;
@@ -96,8 +111,6 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function sign(secret, body) {
     return "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
 }
-/** Verify Decidio's `x-decidio-signature` over the raw webhook body (HMAC-SHA256).
- *  Exported so engine adapters (e.g. the Inngest bridge) reuse the exact check. */
 export function verifyResumeSignature(secret, body, header) {
     if (!header)
         return false;
@@ -107,11 +120,7 @@ export function verifyResumeSignature(secret, body, header) {
 }
 async function confirm(cfg, decisionId, capturedResponse) {
     const f = cfg.fetchImpl ?? fetch;
-    // Sign the confirm so the DURABLE/resume path can earn application_confirmed too (bound to
-    // {action:"confirm", scope:decisionId}); without a key the server caps it at agent_asserted.
     const requesterIdentity = signConfirm(decisionId, cfg);
-    // Same no-silent-downgrade rule as the inline wrap (guard equivalent-path catch): the durable
-    // path is what production agents run, so it must disclose an agent_asserted cap too.
     if (!requesterIdentity)
         console.warn(`[decidio] execution evidence for ${decisionId} recorded as agent_asserted — no signing key configured, so the report can't be proven to come from this agent. Set DECIDIO_AGENT_KEY/DID to earn application_confirmed.`);
     await f(cfg.apiUrl.replace(/\/$/, "") + "/agent/confirm", {
@@ -130,37 +139,36 @@ async function statusOf(cfg, decisionId) {
         throw new Error(`status ${r.status}`);
     return r.json();
 }
-/**
- * Build the resume controller. Spread it into your GuardConfig as `resume`, then
- * either mount `webhookHandler()` (production) or run `worker()` (CLI/laptop).
- *
- *   const resume = createDecidioResume({ apiUrl, apiToken, store: new FilePendingStore(".decidio-pending"), resumeUrl });
- *   const guard  = { apiUrl, agentId, apiToken, resume };
- *   const createOpportunity = withApproval(createOpportunityRaw, describe, guard);
- *   // production:  http.createServer(resume.webhookHandler()).listen(4100)
- *   // or CLI:      resume.worker()
- */
 export function createDecidioResume(opts) {
     const registry = new Map();
-    const inFlight = new Set(); // concurrent-duplicate guard (same process)
+    const inFlight = new Set();
     const secret = opts.webhookSecret ?? opts.apiToken ?? "";
     const ctrl = {
         ...opts,
-        // Default the signing identity from env so a COLD resume process (a fresh worker that has
-        // the agent's env but wasn't passed config) still signs the confirm and earns the wrapper tier.
         agentId: opts.agentId ?? process.env.DECIDIO_AGENT_ID,
         agentKey: opts.agentKey ?? process.env.DECIDIO_AGENT_KEY,
         agentDid: opts.agentDid ?? process.env.DECIDIO_AGENT_DID,
-        workspaceId: opts.workspaceId ?? process.env.DECIDIO_WORKSPACE_ID, // D-B3.6: tenant-bind the cold-resume confirm proof
+        workspaceId: opts.workspaceId ?? process.env.DECIDIO_WORKSPACE_ID,
         webhookSecret: secret,
         store: opts.store,
-        register(action, fn) { registry.set(action, fn); },
+        register(action, fn) {
+            const prev = registry.get(action);
+            if (prev && prev !== fn)
+                console.warn(`[decidio] action "${action}" is being registered again with a DIFFERENT function — the latest one wins, and a resumed decision would run IT. Give each protected function its own action name.`);
+            registry.set(action, fn);
+        },
+        async park(p) {
+            const argsSig = signArgs(p, ctrl.agentKey, ctrl.webhookSecret);
+            if (!argsSig)
+                console.warn(`[decidio] parking ${p.decisionId} UNBOUND — no agent key or webhook secret to sign the payload with, so a modified pending file could not be detected. Run \`npx @decidio/sdk init\` to configure keys.`);
+            await ctrl.store.put({ ...p, createdAt: new Date().toISOString(), ...(argsSig ? { argsSig } : {}) });
+        },
         async resolve({ decisionId, verdict, reason }) {
             const finish = (o) => { if (o.status !== "unknown")
                 opts.onResolved?.(o); return o; };
             const pending = await ctrl.store.get(decisionId);
             if (!pending)
-                return { status: "unknown", decisionId }; // not ours / already resumed
+                return { status: "unknown", decisionId };
             if (verdict === "rejected") {
                 await ctrl.store.delete(decisionId);
                 return finish({ status: "rejected", decisionId, action: pending.action, reason });
@@ -169,28 +177,59 @@ export function createDecidioResume(opts) {
                 await ctrl.store.delete(decisionId);
                 return finish({ status: "blocked", decisionId, action: pending.action, reason });
             }
-            // Fail CLOSED on any unexpected verdict — never execute on a garbage/unknown value.
             if (verdict !== "approved" && verdict !== "auto_approved")
                 return { status: "unknown", decisionId };
+            if (pending.decisionId !== decisionId) {
+                console.error(`[decidio] REFUSING to execute ${decisionId}: the parked entry in this slot belongs to a DIFFERENT decision (${pending.decisionId}) — the pending file was moved or swapped. Delete it and re-run the action.`);
+                return finish({ status: "no_handler", decisionId, action: pending.action, reason: "parked payload decision-id mismatch" });
+            }
+            const strictBinding = !!ctrl.agentKey;
+            const integrity = verifyArgs(pending, ctrl.agentKey, ctrl.webhookSecret);
+            if (integrity === "mismatch") {
+                console.error(`[decidio] REFUSING to execute ${decisionId}: the parked payload FAILED its integrity check — the arguments on disk are not the arguments that were routed for approval. The pending file is untouched for inspection; delete it and re-run the action to request a fresh approval.`);
+                return finish({ status: "no_handler", decisionId, action: pending.action, reason: "parked payload integrity check failed" });
+            }
+            if (integrity === "unverifiable") {
+                console.error(`[decidio] REFUSING to execute ${decisionId}: the parked payload is signed but this process lacks the key material to verify it (DECIDIO_AGENT_KEY / DECIDIO_WEBHOOK_SECRET). Restore the agent's env and retry.`);
+                return finish({ status: "no_handler", decisionId, action: pending.action, reason: "parked payload unverifiable" });
+            }
+            if (integrity === "unbound" && strictBinding) {
+                console.error(`[decidio] REFUSING to execute ${decisionId}: the parked payload has NO integrity signature, but this agent has keys and would have signed it — a missing signature means the file was tampered with. Delete it and re-run the action.`);
+                return finish({ status: "no_handler", decisionId, action: pending.action, reason: "parked payload unsigned (expected a signature)" });
+            }
+            if (integrity === "unbound")
+                console.warn(`[decidio] executing ${decisionId} from an UNBOUND parked entry (this agent has no key material to bind or verify payloads) — its arguments cannot be integrity-checked. Run \`npx @decidio/sdk init\` to enable binding.`);
             const fn = registry.get(pending.action);
-            if (!fn)
-                return finish({ status: "no_handler", decisionId, action: pending.action, reason: `no fn registered for action "${pending.action}" — call resume.register(...) at startup` });
-            // Atomically CLAIM before executing — the cross-process single-use guarantee. If
-            // the store has no claim primitive, fall back to an in-process guard (same-process).
+            if (!fn) {
+                console.error(`[decidio] cannot resume ${decisionId}: no function is registered for action "${pending.action}" in THIS process.`);
+                console.error(`  A worker only re-executes actions registered where it runs. At startup, either declare the action on the wrapper:`);
+                console.error(`      const doIt = guard.protect(doItRaw, describe, { action: "${pending.action}" });`);
+                console.error(`  or register the raw function directly:`);
+                console.error(`      guard.register("${pending.action}", doItRaw);`);
+                console.error(`  then start the worker. The approved action stays parked until then — nothing is lost.`);
+                return finish({ status: "no_handler", decisionId, action: pending.action, reason: `no fn registered for action "${pending.action}" in this process — declare { action } on protect(), or call guard.register("${pending.action}", fn) at startup` });
+            }
             const claimed = ctrl.store.claim ? await ctrl.store.claim(decisionId) : (!inFlight.has(decisionId) && (inFlight.add(decisionId), true));
             if (!claimed)
-                return { status: "unknown", decisionId }; // another worker owns it
+                return { status: "unknown", decisionId };
             try {
-                // Approved: the AGENT performs its own action FIRST. On SUCCESS clear the parked
-                // entry (single-use) + confirm. If it throws, RELEASE the claim so the entry stays
-                // parked + retryable — an approved action is never lost.
                 const result = await fn(...pending.args);
-                await ctrl.store.delete(decisionId);
+                let confirmed = true;
                 try {
                     await confirm(ctrl, decisionId, result);
                 }
                 catch (e) {
-                    console.warn(`[decidio] resume confirm failed (action succeeded): ${e.message}`);
+                    confirmed = false;
+                    console.warn(`[decidio] resume confirm failed (your action DID succeed): ${e.message}`);
+                }
+                const retainedIsSafe = typeof ctrl.store.claim === "function";
+                if (confirmed || !retainedIsSafe)
+                    await ctrl.store.delete(decisionId);
+                if (!confirmed) {
+                    if (retainedIsSafe)
+                        console.warn(`  The parked entry for ${decisionId} is kept as local evidence that it executed — it stays CLAIMED, so it cannot re-run. Retry the confirmation, then delete it.`);
+                    else
+                        console.warn(`  This store provides no claim() primitive, so the entry was DELETED to guarantee the action cannot execute twice. ${decisionId} executed, but its confirmation never reached Decidio — re-confirm it from your own records.`);
                 }
                 return finish({ status: "executed", decisionId, action: pending.action, result });
             }
@@ -213,9 +252,6 @@ export function createDecidioResume(opts) {
                 req.on("data", (c) => (raw += c));
                 req.on("end", async () => {
                     try {
-                        // Fail CLOSED when no secret is configured: an agent that forgot to set a
-                        // webhookSecret must NOT be drivable by forged callbacks. Opt out only with
-                        // allowUnsigned (trusted network boundary).
                         if (!secret) {
                             if (!opts.allowUnsigned) {
                                 res.statusCode = 401;
@@ -282,8 +318,6 @@ export function createDecidioResume(opts) {
                                 st.state === "blocked" ? "blocked" : null;
                         if (!verdict)
                             continue;
-                        // A throwing resolve (the agent's own fn failed) must NOT kill the watcher —
-                        // the entry stays parked and is retried on the next poll.
                         try {
                             const outcome = await ctrl.resolve({ decisionId: p.decisionId, verdict, reason: st.reason });
                             workerOpts?.onResolved?.(outcome);

package/dist/signing.d.ts

@@ -1,8 +1,4 @@
-/** Sorted-key JCS — must match apps/api/src/canonical.ts byte-for-byte. */
 export declare function canonicalize(v: unknown): string;
-/** Generate a fresh Ed25519 keypair LOCALLY. Returns the public `did:key` (register this)
- *  and the PKCS8 private key base64 (keep this in the agent host's env as DECIDIO_AGENT_KEY —
- *  it never goes back to Decidio). */
 export declare function generateKeypair(): {
     did: string;
     privateKeyBase64: string;
@@ -21,20 +17,12 @@ export interface RequesterIdentity {
         signature: string;
     };
 }
-/** Sign the CONFIRM call (bound to {action:"confirm", scope:decisionId}) so the gate can
- *  prove the caller is the receipt's original requester before granting the wrapper tier
- *  (application_confirmed). Returns undefined when no signing key is configured (the server
- *  then caps the report at agent_asserted). Used by EVERY confirm path — inline, durable
- *  resume, and the engine adapters — so the production paths confirm with a proof too. Also
- *  binds `workspaceId` (D-B3.6) when configured, so the confirm proof is tenant-scoped too. */
 export declare function signConfirm(decisionId: string, cfg: {
     agentId?: string;
     agentKey?: string;
     agentDid?: string;
     workspaceId?: string;
 }): RequesterIdentity | undefined;
-/** Sign a request-bound identity proof. The returned object is sent verbatim as the
- *  `requesterIdentity` field of /agent/authorize. */
 export declare function signBoundProof(privateKeyBase64: string, fields: {
     agentId: string;
     did: string;

package/dist/signing.js

@@ -1,13 +1,4 @@
-// Client-side agent identity (§13 P0-8). The agent generates its Ed25519 keypair LOCALLY
-// (the private key never crosses the wire — `init` registers only the public did:key) and
-// signs a REQUEST-BOUND proof on each authorize: a detached Ed25519 JWS over
-// canonical({agentId,did,action,amount,scope,nonce,exp}). Decidio's floor verifies the
-// signature, binds it to the exact request, burns the single-use nonce, and checks the
-// did against the agent registry — so the gate PROVES who is calling instead of trusting a
-// label. This canonicalize + proof shape is byte-identical to apps/api (canonical.ts +
-// a2a/identity.ts), so a proof signed here verifies there.
 import { generateKeyPairSync, createPrivateKey, sign as edSign, randomUUID } from "node:crypto";
-// base58btc (Bitcoin alphabet) — for the did:key multibase 'z' prefix.
 const B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
 function b58encode(buf) {
     const digits = [0];
@@ -34,7 +25,6 @@ function b58encode(buf) {
         str += B58[digits[i]];
     return str;
 }
-/** Sorted-key JCS — must match apps/api/src/canonical.ts byte-for-byte. */
 export function canonicalize(v) {
     if (v === null || typeof v !== "object")
         return JSON.stringify(v);
@@ -43,9 +33,6 @@ export function canonicalize(v) {
     const o = v;
     return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${canonicalize(o[k])}`).join(",")}}`;
 }
-/** Generate a fresh Ed25519 keypair LOCALLY. Returns the public `did:key` (register this)
- *  and the PKCS8 private key base64 (keep this in the agent host's env as DECIDIO_AGENT_KEY —
- *  it never goes back to Decidio). */
 export function generateKeypair() {
     const { privateKey, publicKey } = generateKeyPairSync("ed25519");
     const jwk = publicKey.export({ format: "jwk" });
@@ -54,27 +41,15 @@ export function generateKeypair() {
     const privateKeyBase64 = privateKey.export({ format: "der", type: "pkcs8" }).toString("base64");
     return { did, privateKeyBase64 };
 }
-/** Sign the CONFIRM call (bound to {action:"confirm", scope:decisionId}) so the gate can
- *  prove the caller is the receipt's original requester before granting the wrapper tier
- *  (application_confirmed). Returns undefined when no signing key is configured (the server
- *  then caps the report at agent_asserted). Used by EVERY confirm path — inline, durable
- *  resume, and the engine adapters — so the production paths confirm with a proof too. Also
- *  binds `workspaceId` (D-B3.6) when configured, so the confirm proof is tenant-scoped too. */
 export function signConfirm(decisionId, cfg) {
     if (!cfg.agentKey || !cfg.agentDid || !cfg.agentId)
         return undefined;
     return signBoundProof(cfg.agentKey, { agentId: cfg.agentId, did: cfg.agentDid, action: "confirm", amount: 0, scope: decisionId, workspaceId: cfg.workspaceId });
 }
-/** Sign a request-bound identity proof. The returned object is sent verbatim as the
- *  `requesterIdentity` field of /agent/authorize. */
 export function signBoundProof(privateKeyBase64, fields) {
     const key = createPrivateKey({ key: Buffer.from(privateKeyBase64, "base64"), format: "der", type: "pkcs8" });
     const nonce = fields.nonce ?? randomUUID();
     const exp = (fields.now ?? Date.now()) + (fields.ttlMs ?? 120_000);
-    // OMIT scope/workspaceId when absent so the canonical bytes match the server + the Python SDK — a key
-    // with an undefined value would serialize as literal "undefined", which Python can't reproduce, and a
-    // legacy (no-workspace) proof must stay byte-identical. The server's bound-payload reconstruction
-    // omits them the same way (a2a/identity.ts).
     const payloadObj = { agentId: fields.agentId, did: fields.did, action: fields.action, amount: fields.amount, ...(fields.scope !== undefined ? { scope: fields.scope } : {}), ...(fields.workspaceId !== undefined ? { workspaceId: fields.workspaceId } : {}), nonce, exp };
     const payload = Buffer.from(canonicalize(payloadObj), "utf8").toString("base64url");
     const protectedHdr = Buffer.from(JSON.stringify({ alg: "EdDSA", kid: fields.did }), "utf8").toString("base64url");

package/openapi.yaml

@@ -5,7 +5,7 @@
 openapi: 3.1.0
 info:
   title: Decidio Agent Gate
-  version: 0.1.5
+  version: 0.1.7
   description: >
     Authorize an AI-agent action (proceed | route | block), confirm the captured outcome, and
     receive the signed resume webhook when a routed action is decided. Every outcome seals a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "One-line approval gate for AI-agent actions. Wrap a risky tool call with guard.protect(); Decidio's policy engine decides proceed | route | block, a human approves routed actions, and every outcome is sealed as a verifiable Authority Receipt.",
   "license": "Apache-2.0",
   "type": "module",
@@ -82,5 +82,9 @@
   },
   "dependencies": {
     "@decidio/verify": "^0.1.3"
+  },
+  "author": "OmniTwin Technologies Inc.",
+  "bugs": {
+    "url": "https://decidioai.com/support/"
   }
 }