@decidio/sdk 0.1.8 → 0.1.10

package/dist/guard.js

@@ -9,7 +9,7 @@ export class Guard {
     }
     static fromEnv() {
         return new Guard({
-            apiUrl: process.env.DECIDIO_API_URL ?? "http://localhost:4000",
+            apiUrl: process.env.DECIDIO_API_URL ?? "",
             agentId: process.env.DECIDIO_AGENT_ID ?? "agent",
             apiToken: process.env.DECIDIO_API_TOKEN,
             sourceSystem: process.env.DECIDIO_SOURCE_SYSTEM,
@@ -29,6 +29,7 @@ export class Guard {
         return this.ensureResume().worker(opts);
     }
     ensureResume() {
+        this.assertConfigured();
         if (!this.resume) {
             const c = this.config;
             this.resume = createDecidioResume({
@@ -40,14 +41,24 @@ export class Guard {
         }
         return this.resume;
     }
+    assertConfigured() {
+        if (!this.config.apiUrl)
+            throw new Error("[decidio] no gate URL configured — set DECIDIO_API_URL (the hosted sandbox is https://decidio-api.onrender.com) or run `npx @decidio/sdk init`, then start your process with `node --env-file=.env`. Nothing was routed or executed.");
+    }
     protect(fn, describe, opts) {
+        this.assertConfigured();
         if (opts?.adapter && opts.adapter !== "generic") {
-            throw new Error(`[decidio] adapter "${opts.adapter}" must be bound via the @decidio/sdk/${opts.adapter} subpath (it needs the engine handle). See that adapter's exports.`);
+            const REAL = ["langgraph", "openai", "temporal", "inngest"];
+            if (REAL.includes(opts.adapter)) {
+                throw new Error(`[decidio] adapter "${opts.adapter}" must be bound via the @decidio/sdk/${opts.adapter} subpath (it needs the engine handle). See that adapter's exports.`);
+            }
+            throw new Error(`[decidio] unknown adapter "${opts.adapter}" — the available engine adapters are ${REAL.map((a) => `"${a}"`).join(", ")} (each via its @decidio/sdk/<name> subpath), or omit the option for the core gate.`);
         }
         const c = this.config;
         const base = {
             apiUrl: c.apiUrl, agentId: c.agentId, apiToken: c.apiToken,
             sourceSystem: c.sourceSystem, agentKey: c.agentKey, agentDid: c.agentDid, workspaceId: c.workspaceId, appUrl: c.appUrl, fetchImpl: c.fetchImpl,
+            pollTimeoutMs: opts?.pollTimeoutMs, pollIntervalMs: opts?.pollIntervalMs,
         };
         if ((opts?.mode ?? "durable") === "blocking") {
             console.warn("[decidio] WARNING: blocking wait — only safe for short, watched approvals. " +

package/dist/index.d.ts

@@ -1,27 +1,54 @@
 import type { ResumeController } from "./resume.js";
-export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume } from "./resume.js";
+export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 export type { PendingAction, PendingStore, ResumeController, ResumeOutcome } from "./resume.js";
 export { guard, Guard } from "./guard.js";
 export type { GuardFacadeConfig, ProtectOptions } from "./guard.js";
-export { generateKeypair, signBoundProof, signConfirm, canonicalize } from "./signing.js";
+export { generateKeypair, signBoundProof, signConfirm, canonicalize, assertJsonSafe, assertSafeTransport, DecidioUnsafeArgumentsError } from "./signing.js";
 export type { RequesterIdentity } from "./signing.js";
 export interface GuardConfig {
+    /** Base URL of the Decidio gate, e.g. "https://api.decidio.io". */
     apiUrl: string;
+    /** The agent identity registered with Decidio (onboarding wizard), e.g. "salesforce/SalesforceBot". */
     agentId: string;
+    /** Bearer token for the REST floor (a trusted, already-authenticated internal
+     *  caller). Lives ONLY in the agent host's environment — never in client code. */
     apiToken?: string;
+    /** Source system label sealed onto the receipt (e.g. "salesforce"). */
     sourceSystem?: string;
+    /** The agent's PRIVATE signing key (PKCS8 base64), generated locally by `init` and held
+     *  ONLY in the agent host's env as DECIDIO_AGENT_KEY. When set (with `agentDid`), the SDK
+     *  signs a request-bound identity proof on each authorize so the floor PROVES the requester
+     *  instead of trusting the label — required for a registered agent to auto-approve. */
     agentKey?: string;
+    /** The agent's PUBLIC did:key (the one registered with Decidio). Pairs with `agentKey`. */
     agentDid?: string;
+    /** The workspace this agent acts in (DECIDIO_WORKSPACE_ID, from the owner's agent-token mint).
+     *  Bound into the signed proof (D-B3.6) so a captured proof can't be replayed in another tenant.
+     *  For a tester's per-workspace agent token this is the tester's workspace id. */
     workspaceId?: string;
+    /** Poll cadence + ceiling while a routed action awaits human approval. Used ONLY
+     *  by the blocking transport (no `resume` configured). */
     pollIntervalMs?: number;
     pollTimeoutMs?: number;
+    /** Optional async notifier so a long human wait surfaces in your logs/UI. */
     onPending?: (info: {
         decisionId: string;
         receiptId: string;
         url: string | null;
     }) => void;
+    /** Base URL of the Decidio app (DECIDIO_APP_URL). When set, a routed action can say WHERE to
+     *  approve it — `<appUrl>/d/<decisionId>` opens that decision directly, on web or on the phone
+     *  build. This link used to be built only inside our own example, so a developer who pasted the
+     *  env block set DECIDIO_APP_URL and nothing ever read it. */
     appUrl?: string;
+    /** Durable async resume. When set, a routed action SUSPENDS (parks its args in the
+     *  store, throws DecidioSuspendedError) instead of blocking — the process may exit
+     *  and resume later via the controller's webhook handler or poll worker. This is
+     *  the production transport for real (minutes-to-days) human approvals. */
     resume?: ResumeController;
+    /** Callback URL Decidio POSTs the verdict to on approval (webhook transport).
+     *  Sent on /agent/authorize so the decision carries it. Falls back to
+     *  resume.resumeUrl. Omit when using the poll worker. */
     resumeUrl?: string;
     fetchImpl?: typeof fetch;
 }
@@ -29,6 +56,9 @@ export interface ApprovalContext {
     action: string;
     amount: number;
     scope?: string;
+    /** Optional human-facing DETAILS of the action (e.g. { Account, "Lead Source", Stage }) shown to
+     *  the approver as "what you're approving". Display-only — the policy decides on `amount`/`scope`,
+     *  never these. Residual-safe tokenized server-side before persistence. */
     context?: Record<string, string | number>;
 }
 export declare class DecidioBlockedError extends Error {
@@ -45,6 +75,13 @@ export declare class DecidioTimeoutError extends Error {
     decisionId: string;
     constructor(decisionId: string);
 }
+/** A transport failure with GUIDANCE instead of a raw fetch stack. Carries the endpoint, the
+ *  operation, the underlying code, and the safety state a caller cares about most: whether
+ *  anything could have executed. */
+/** The workspace's governed-action allowance is exhausted (HTTP 429, code AGENT_RATE). The
+ *  server says exactly how much and until when — `limit`, `remaining` and `resetAt` relay its
+ *  answer verbatim so automation never has to parse a message. Nothing was routed, recorded,
+ *  or executed; retry after `resetAt`. */
 export declare class DecidioRateLimitError extends Error {
     limit: number | undefined;
     remaining: number | undefined;
@@ -57,5 +94,12 @@ export declare class DecidioNetworkError extends Error {
     code: string | undefined;
     constructor(endpoint: string, op: string, code: string | undefined, cause: unknown);
 }
+/**
+ * Wrap an async action behind the Decidio gate. `describe` extracts the approval
+ * context (action, amount, scope) from the call arguments. Returns a function with
+ * the SAME signature as `fn` — drop-in.
+ */
+/** `<appUrl>/d/<decisionId>` — the deep link that opens this decision directly, on the web app or
+ *  the phone build. Null when DECIDIO_APP_URL is not configured, never a half-built URL. */
 export declare function decisionUrl(appUrl: string | undefined, decisionId: string): string | null;
 export declare function withApproval<A extends any[], R>(fn: (...args: A) => Promise<R>, describe: (...args: A) => ApprovalContext, config: GuardConfig): (...args: A) => Promise<R>;

package/dist/index.js

@@ -1,8 +1,8 @@
-import { DecidioSuspendedError } from "./resume.js";
-import { signBoundProof, signConfirm } from "./signing.js";
-export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume } from "./resume.js";
+import { DecidioSuspendedError, assertConfirmRecorded } from "./resume.js";
+import { signBoundProof, signConfirm, assertJsonSafe, assertSafeTransport, DecidioUnsafeArgumentsError } from "./signing.js";
+export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 export { guard, Guard } from "./guard.js";
-export { generateKeypair, signBoundProof, signConfirm, canonicalize } from "./signing.js";
+export { generateKeypair, signBoundProof, signConfirm, canonicalize, assertJsonSafe, assertSafeTransport, DecidioUnsafeArgumentsError } from "./signing.js";
 export class DecidioBlockedError extends Error {
     reason;
     decisionId;
@@ -74,6 +74,7 @@ async function reach(f, url, op, init) {
 }
 async function post(cfg, path, body) {
     const f = cfg.fetchImpl ?? fetch;
+    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
     const res = await reach(f, cfg.apiUrl.replace(/\/$/, "") + path, `POST ${path}`, {
         method: "POST",
         headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
@@ -89,6 +90,7 @@ async function post(cfg, path, body) {
 }
 async function get(cfg, path) {
     const f = cfg.fetchImpl ?? fetch;
+    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
     const res = await reach(f, cfg.apiUrl.replace(/\/$/, "") + path, `GET ${path}`, {
         headers: { ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
     });
@@ -106,10 +108,22 @@ export function withApproval(fn, describe, config) {
     const pollTimeout = config.pollTimeoutMs ?? 600_000;
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;
     return async (...args) => {
+        try {
+            assertJsonSafe(args, "args");
+        }
+        catch (e) {
+            throw new DecidioUnsafeArgumentsError(`${e?.message ?? e} The decision was NOT routed; nothing reached Decidio.`);
+        }
         const ctx = describe(...args);
         const requesterIdentity = (config.agentKey && config.agentDid)
             ? signBoundProof(config.agentKey, { agentId: config.agentId, did: config.agentDid, action: ctx.action, amount: ctx.amount, scope: ctx.scope, workspaceId: config.workspaceId })
             : undefined;
+        try {
+            assertJsonSafe(ctx, "describe(...)");
+        }
+        catch (e) {
+            throw new DecidioUnsafeArgumentsError(`${e?.message ?? e} The decision was NOT routed; nothing reached Decidio.`);
+        }
         const auth = await post(config, "/agent/authorize", {
             requester: config.agentId, action: ctx.action, amount: ctx.amount,
             scope: ctx.scope, sourceSystem: config.sourceSystem,
@@ -126,7 +140,7 @@ export function withApproval(fn, describe, config) {
             if (config.onPending)
                 config.onPending({ decisionId: auth.decisionId, receiptId: auth.receiptId, url: approvalUrl });
             else
-                console.log(`[decidio] ${ctx.action} is awaiting approval (decision ${auth.decisionId}) — approve it ${approvalUrl ? `at ${approvalUrl}` : `in your Decidio queue, or: npx @decidio/sdk approvals approve ${auth.decisionId}`}`);
+                console.error(`[decidio] ${ctx.action} is awaiting approval (decision ${auth.decisionId}) — approve it ${approvalUrl ? `at ${approvalUrl}` : `in your Decidio queue, or: npx @decidio/sdk approvals approve ${auth.decisionId}`}`);
             if (config.resume) {
                 config.resume.agentId ??= config.agentId;
                 config.resume.agentKey ??= config.agentKey;
@@ -157,12 +171,13 @@ export function withApproval(fn, describe, config) {
         const result = await fn(...args);
         try {
             const confirmIdentity = signConfirm(auth.decisionId, config);
-            await post(config, "/agent/confirm", {
+            const confirmBody = await post(config, "/agent/confirm", {
                 decisionId: auth.decisionId,
                 capturedResponse: result ?? null,
                 source: "wrapper",
                 ...(confirmIdentity ? { requesterIdentity: confirmIdentity } : {}),
             });
+            assertConfirmRecorded(confirmBody, auth.decisionId, !!confirmIdentity);
             if (!confirmIdentity)
                 console.warn(`[decidio] execution evidence for ${auth.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 (npx @decidio/sdk init writes them) to earn application_confirmed.`);
         }

package/dist/inngest.d.ts

@@ -1,7 +1,11 @@
 import type { RequestListener } from "node:http";
 import { verifyResumeSignature } from "./resume.js";
 import type { GuardConfig, ApprovalContext } from "./index.js";
+/** The Inngest event Decidio's verdict is translated into. The waiting function
+ *  correlates on `data.decisionId`. */
 export declare const DECIDIO_RESUME_EVENT = "decidio/decision.resolved";
+/** The minimal slices of the Inngest step + client APIs we use, typed structurally so
+ *  this file doesn't force an `inngest` type dependency on the core build. */
 export interface InngestStepLike {
     run<T>(id: string, fn: () => Promise<T>): Promise<T>;
     waitForEvent(id: string, opts: {
@@ -25,6 +29,16 @@ export type GateStepOutcome<R> = {
     decisionId: string;
     result?: R;
 };
+/**
+ * Gate an action INSIDE an Inngest function, with durable suspend on routing.
+ *   • proceed → run the action (as a step) + confirm.
+ *   • route   → `step.waitForEvent` durably suspends until Decidio's resume event for
+ *               THIS decision arrives; approved → run + confirm; rejected → status.
+ *   • block   → return blocked (the action never runs).
+ * The action runs in YOUR process with YOUR credentials — Decidio only signals.
+ * `config.resumeUrl` must point at the bridge endpoint (createInngestResumeBridge),
+ * so Decidio's webhook is translated into the event this step waits on.
+ */
 export declare function decidioGateStep<R>(args: {
     step: InngestStepLike;
     config: GuardConfig;
@@ -32,6 +46,12 @@ export declare function decidioGateStep<R>(args: {
     run: () => Promise<R>;
     timeout?: string;
 }): Promise<GateStepOutcome<R>>;
+/**
+ * Decidio → Inngest bridge. Mount as an HTTP endpoint and register it as the agent's
+ * `resumeUrl`. It verifies Decidio's signed resume webhook (same HMAC as the core
+ * handler) and emits `DECIDIO_RESUME_EVENT` into Inngest, waking the suspended
+ * `decidioGateStep`. Fails CLOSED without a configured secret (unless allowUnsigned).
+ */
 export declare function createInngestResumeBridge(opts: {
     inngest: InngestClientLike;
     webhookSecret?: string;

package/dist/resume.d.ts

@@ -1,4 +1,6 @@
 import type { RequestListener } from "node:http";
+/** A routed action parked on the agent side, awaiting human approval. The `args`
+ *  are the original call arguments, replayed verbatim when the action resumes. */
 export interface PendingAction {
     decisionId: string;
     receiptId?: string;
@@ -7,17 +9,37 @@ export interface PendingAction {
     scope?: string;
     args: unknown[];
     createdAt: string;
+    /** Integrity binding over {decisionId, action, amount, scope, args} — without it the parked
+     *  payload would be mutable between routing and execution. ed25519 = detached
+     *  signature by the agent's key; hmac = keyed by the webhook secret. Verified before ANY
+     *  re-execution; a mismatch REFUSES and leaves the file for inspection. When the controller
+     *  holds an agent key, a MISSING signature is also refused (a stripped signature is
+     *  indistinguishable from tampering) — including entries parked by pre-0.1.6 versions:
+     *  drain pending approvals before upgrading, or delete + re-run them. Only a keyless
+     *  controller executes unbound entries (with a loud warning). Honest scope: this defends
+     *  against modification by anything lacking the agent's key material — a fully compromised
+     *  agent host can bypass the guard entirely and is out of client-side scope (server-sealed
+     *  args binding is the receipt-v2 design). */
     argsSig?: {
         kind: "ed25519" | "hmac";
         sig: string;
     };
 }
+/** Where suspended actions live between request and approval. The default is a
+ *  file store; swap in Redis/Postgres/your queue for production. AGENT-SIDE only —
+ *  Decidio never sees this. */
 export interface PendingStore {
     put(p: PendingAction): Promise<void>;
     get(decisionId: string): Promise<PendingAction | null>;
     delete(decisionId: string): Promise<void>;
     list(): Promise<PendingAction[]>;
+    /** Atomically take ownership of a parked action for execution. Returns true if THIS
+     *  caller claimed it, false if it's already claimed/gone — the cross-process single-use
+     *  guarantee (a production store backs this with rename/SETNX/SELECT-FOR-UPDATE). A
+     *  claimed entry is excluded from list(). Optional: if absent, the controller falls
+     *  back to an in-process guard (same-process only). */
     claim?(decisionId: string): Promise<boolean>;
+    /** Undo a claim so a failed execution is retryable. */
     release?(decisionId: string): Promise<void>;
 }
 export declare class MemoryPendingStore implements PendingStore {
@@ -30,6 +52,11 @@ export declare class MemoryPendingStore implements PendingStore {
     claim(id: string): Promise<boolean>;
     release(id: string): Promise<void>;
 }
+/** 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 declare class FilePendingStore implements PendingStore {
     private dir;
     constructor(dir: string);
@@ -43,6 +70,10 @@ export declare class FilePendingStore implements PendingStore {
     claim(id: string): Promise<boolean>;
     release(id: string): Promise<void>;
 }
+/** 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 declare class DecidioSuspendedError extends Error {
     decisionId: string;
     action: string;
@@ -55,31 +86,71 @@ export interface ResumeOutcome {
     action?: string;
     result?: unknown;
     reason?: string;
+    /** executed only: did the execution-evidence report reach Decidio AND come back with a recorded
+     *  tier? `status: "executed"` describes the LOCAL run; this describes the record — a lost
+     *  confirmation must never read as recorded evidence. */
+    confirmed?: boolean;
+    /** executed only: the evidence tier the server says it recorded (e.g. application_confirmed). */
+    evidenceTier?: string;
 }
+/** Minimal config the controller needs to confirm outcomes + poll status. Shared
+ *  with GuardConfig (apiUrl/apiToken). */
 export interface ResumeConfig {
     apiUrl: string;
     apiToken?: string;
+    /** Agent identity for SIGNING the confirm call on resume (so the durable path can earn the
+     *  application_confirmed tier, not just the inline path). Default from DECIDIO_AGENT_ID/
+     *  _KEY/_DID env when unset — a cold resume process that has the env signs automatically. */
     agentId?: string;
     agentKey?: string;
     agentDid?: string;
+    /** The workspace the agent acts in (DECIDIO_WORKSPACE_ID) — bound into the cold-resume confirm
+     *  proof (D-B3.6) so it's tenant-scoped too. Default from env when unset. */
     workspaceId?: string;
+    /** Shared secret Decidio signs the resume webhook with (HMAC-SHA256). Defaults to
+     *  the API token if unset. Verified before any re-execution. */
     webhookSecret?: string;
+    /** Escape hatch to accept UNSIGNED resume webhooks (no secret). Off by default:
+     *  with no secret and this unset, the webhook handler rejects every call (fail
+     *  closed) so a misconfigured agent can't be driven by forged callbacks. Setting it
+     *  true REMOVES webhook authenticity — anyone who can reach the endpoint can signal
+     *  work — and the controller says so loudly at startup (an absolute fail-closed
+     *  guarantee must disclose its opt-out). Only behind a trusted network boundary
+     *  (e.g. mTLS / private mesh), never on an internet-reachable endpoint. */
     allowUnsigned?: boolean;
+    /** The callback URL Decidio should POST the verdict to (webhook transport). Sent
+     *  on /agent/authorize so the decision carries it; omit when using the poll worker. */
     resumeUrl?: string;
+    /** Fired after every terminal resolution (executed / rejected / blocked / no_handler),
+     *  via either transport. Use it to log, close a listener, or exit a CLI. */
     onResolved?: (o: ResumeOutcome) => void;
     fetchImpl?: typeof fetch;
 }
+/** Re-execute the agent's own fn on approval, confirm the captured outcome to
+ *  Decidio, and clear the parked entry. Bound to a store + a registry of raw fns. */
 export interface ResumeController extends ResumeConfig {
     store: PendingStore;
+    /** Register a RAW fn under its action name so a (possibly cold) resume can replay
+     *  it. `withApproval` auto-registers on the hot path; a cold worker/service should
+     *  register at startup so it can resume actions it never originated. */
     register(action: string, fn: (...args: any[]) => Promise<any>): void;
+    /** Park a routed action WITH its integrity binding (prefer this over store.put — the
+     *  binding is what lets resolve() refuse a tampered payload). */
     park(p: Omit<PendingAction, "createdAt" | "argsSig">): Promise<void>;
+    /** Drive a parked decision to completion once a verdict is known. Idempotent:
+     *  a second call after success finds nothing parked → "unknown" (no double-write). */
     resolve(input: {
         decisionId: string;
         verdict: "approved" | "rejected" | "blocked";
         reason?: string;
     }): Promise<ResumeOutcome>;
+    /** node:http listener for Decidio's signed approval webhook (Express/Fastify/node). */
     webhookHandler(): RequestListener;
+    /** Web-Fetch handler (Request → Response) for Next.js route handlers, Hono,
+     *  Cloudflare Workers, Bun, Deno. Same fail-closed signature check. */
     fetchHandler(): (req: Request) => Promise<Response>;
+    /** Poll-based resume for hosts with no inbound URL (CLI/laptop). A long-lived
+     *  watcher — this is a durable WORKER, not the request path blocking. */
     worker(opts?: {
         intervalMs?: number;
         timeoutMs?: number;
@@ -89,7 +160,24 @@ export interface ResumeController extends ResumeConfig {
     };
 }
 declare function sign(secret: string, body: string): string;
+/** 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 declare function verifyResumeSignature(secret: string, body: string, header: string | undefined): boolean;
+/** The ONE confirm-body rule, shared by every confirm door (resume, inline withApproval,
+ *  adapter gate). Transport success is not confirmation: a 2xx whose body carries no recorded
+ *  tier is a FAILED confirm; a SIGNED confirm coming back below application_confirmed is
+ *  disclosed, never silent. Returns the recorded tier or throws. */
+export declare function assertConfirmRecorded(body: any, decisionId: string, signed: boolean): string;
+/**
+ * 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 declare function createDecidioResume(opts: ResumeConfig & {
     store: PendingStore;
 }): ResumeController;

package/dist/resume.js

@@ -1,7 +1,9 @@
 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, canonicalize } from "./signing.js";
+import { userInfo } from "node:os";
+import { execFileSync } from "node:child_process";
+import { signConfirm, canonicalize, assertJsonSafe, assertSafeTransport, DecidioUnsafeArgumentsError } 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);
@@ -53,6 +55,18 @@ export class FilePendingStore {
     constructor(dir) {
         this.dir = dir;
         mkdirSync(dir, { recursive: true });
+        if (process.platform === "win32") {
+            try {
+                const user = (() => { try {
+                    return userInfo().username;
+                }
+                catch {
+                    return process.env.USERNAME ?? process.env.USER ?? "";
+                } })();
+                execFileSync("icacls", [dir, "/inheritance:r", "/grant:r", `${user}:(OI)(CI)F`], { stdio: "ignore" });
+            }
+            catch { }
+        }
     }
     key(id) { return id.replace(/[^\w.-]/g, "_"); }
     path(id) { return join(this.dir, `${this.key(id)}.json`); }
@@ -118,20 +132,34 @@ export function verifyResumeSignature(secret, body, header) {
     const a = Buffer.from(expected), b = Buffer.from(header);
     return a.length === b.length && timingSafeEqual(a, b);
 }
+export function assertConfirmRecorded(body, decisionId, signed) {
+    if (!body || body.ok !== true || typeof body.confirmation !== "string") {
+        throw new Error(`confirm answered 2xx but reported no evidence tier — treating the confirmation as NOT recorded`);
+    }
+    if (signed && body.confirmation !== "application_confirmed") {
+        console.warn(`[decidio] execution evidence for ${decisionId} was recorded as "${body.confirmation}", not application_confirmed, despite a signed report — the server did not accept the identity proof (key/DID/registration mismatch?). Run \`npx @decidio/sdk doctor\` and re-init if this persists.`);
+    }
+    return body.confirmation;
+}
 async function confirm(cfg, decisionId, capturedResponse) {
     const f = cfg.fetchImpl ?? fetch;
+    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
     const requesterIdentity = signConfirm(decisionId, cfg);
     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", {
+    const r = await f(cfg.apiUrl.replace(/\/$/, "") + "/agent/confirm", {
         method: "POST",
         headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
         body: JSON.stringify({ decisionId, capturedResponse: capturedResponse ?? null, source: "wrapper", ...(requesterIdentity ? { requesterIdentity } : {}) }),
-    }).then((r) => { if (!r.ok)
-        throw new Error(`confirm ${r.status}`); });
+    });
+    if (!r.ok)
+        throw new Error(`confirm ${r.status}`);
+    const body = await r.json().catch(() => null);
+    return assertConfirmRecorded(body, decisionId, !!requesterIdentity);
 }
 async function statusOf(cfg, decisionId) {
     const f = cfg.fetchImpl ?? fetch;
+    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
     const r = await f(cfg.apiUrl.replace(/\/$/, "") + "/agent/status/" + encodeURIComponent(decisionId), {
         headers: { ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
     });
@@ -143,6 +171,15 @@ export function createDecidioResume(opts) {
     const registry = new Map();
     const inFlight = new Set();
     const secret = opts.webhookSecret ?? opts.apiToken ?? "";
+    if (opts.allowUnsigned)
+        console.warn("[decidio] WARNING: allowUnsigned is ON — this controller will accept UNSIGNED resume webhooks. Anyone who can reach the endpoint can signal work (parked-payload integrity still gates execution). Use this only behind a trusted network boundary, never on an internet-reachable endpoint.");
+    const refusalWarned = new Set();
+    const refuseOnce = (decisionId, msg) => {
+        if (refusalWarned.has(decisionId))
+            return;
+        refusalWarned.add(decisionId);
+        console.error(msg + " (This prints once — the entry stays parked until you act.)");
+    };
     const ctrl = {
         ...opts,
         agentId: opts.agentId ?? process.env.DECIDIO_AGENT_ID,
@@ -158,6 +195,12 @@ export function createDecidioResume(opts) {
             registry.set(action, fn);
         },
         async park(p) {
+            try {
+                assertJsonSafe(p.args, "args");
+            }
+            catch (e) {
+                throw new DecidioUnsafeArgumentsError(`${e?.message ?? e} NOT parked and NOT executable — but decision ${p.decisionId} may already be routed; reject it in your queue: npx @decidio/sdk approvals reject ${p.decisionId}`, p.decisionId);
+            }
             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.`);
@@ -180,21 +223,21 @@ export function createDecidioResume(opts) {
             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.`);
+                refuseOnce(decisionId, `[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.`);
+                refuseOnce(decisionId, `[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.`);
+                refuseOnce(decisionId, `[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.`);
+                refuseOnce(decisionId, `[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")
@@ -215,8 +258,9 @@ export function createDecidioResume(opts) {
             try {
                 const result = await fn(...pending.args);
                 let confirmed = true;
+                let tier;
                 try {
-                    await confirm(ctrl, decisionId, result);
+                    tier = await confirm(ctrl, decisionId, result);
                 }
                 catch (e) {
                     confirmed = false;
@@ -231,7 +275,7 @@ export function createDecidioResume(opts) {
                     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 });
+                return finish({ status: "executed", decisionId, action: pending.action, result, confirmed, ...(tier ? { evidenceTier: tier } : {}) });
             }
             catch (e) {
                 if (ctrl.store.release)
@@ -320,6 +364,14 @@ export function createDecidioResume(opts) {
                             continue;
                         try {
                             const outcome = await ctrl.resolve({ decisionId: p.decisionId, verdict, reason: st.reason });
+                            if (outcome.status === "executed" && outcome.confirmed)
+                                console.error(`[decidio] resumed ${p.decisionId}: approved → "${p.action}" executed, evidence recorded as ${outcome.evidenceTier ?? "confirmed"}.`);
+                            else if (outcome.status === "executed")
+                                console.error(`[decidio] resumed ${p.decisionId}: approved → "${p.action}" executed, but its execution evidence did NOT reach Decidio — see the warning above.`);
+                            else if (outcome.status === "rejected")
+                                console.error(`[decidio] resumed ${p.decisionId}: REJECTED — the parked "${p.action}" was discarded, nothing executed.`);
+                            else if (outcome.status === "blocked")
+                                console.error(`[decidio] resumed ${p.decisionId}: BLOCKED by policy — the parked "${p.action}" was discarded, nothing executed.`);
                             workerOpts?.onResolved?.(outcome);
                         }
                         catch (e) {

package/dist/signing.d.ts

@@ -1,4 +1,8 @@
+/** 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;
@@ -17,12 +21,20 @@ 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;
@@ -34,3 +46,21 @@ export declare function signBoundProof(privateKeyBase64: string, fields: {
     now?: number;
     nonce?: string;
 }): RequesterIdentity;
+/** Refuse values that do not survive `JSON.stringify → JSON.parse` with their meaning intact,
+ *  BEFORE anything is routed, signed, or parked. `NaN` canonicalizes to `null` and a `Map` to
+ *  `{}` — an integrity signature over those bytes would verify while the function executed
+ *  arguments that meant something else, so the gate refuses them instead. Throws naming the
+ *  offending path. The supported data model is plain JSON: null, boolean, string, finite
+ *  number, plain array, plain object. */
+/** Typed refusal for values that cannot survive JSON with their meaning intact. `decisionId`
+ *  is set only when a decision already exists (defense-in-depth refusals after routing). */
+export declare class DecidioUnsafeArgumentsError extends Error {
+    decisionId?: string | undefined;
+    constructor(message: string, decisionId?: string | undefined);
+}
+export declare function assertJsonSafe(value: unknown, path?: string): void;
+/** The wire rule: a credentialed request must never ride plaintext http to a remote host — the
+ *  rule is about the WIRE, not which credential (the interactive sign-in enforced this for
+ *  session tokens while agent-token requests sailed through). localhost/127.0.0.1/[::1] stay
+ *  allowed for local dev; https always allowed. Throws before anything is sent. */
+export declare function assertSafeTransport(url: string, hasCredential: boolean): void;