@decidio/sdk 0.6.4 → 0.7.0

package/dist/index.js

@@ -1,12 +1,12 @@
-import { DecidioSuspendedError } from "./resume.js";
-import { signBoundProof, signConfirm, assertSafeTransport, carriesCredential } from "./signing.js";
+import { DecidioSuspendedError, checkApproval } from "./resume.js";
+import { signBoundProof, signConfirm, assertSafeTransport, carriesCredential, bindingMaterial, requestCommitment } from "./signing.js";
 import { canonicalize, canonicalizeArgs } from "./canonical.js";
 import { readConfirmResponse, buildConfirmBody } from "./evidence.js";
-export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
+export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded, checkApproval } from "./resume.js";
 export { guard, Guard } from "./guard.js";
 export { DecidioHttpError, decisionIdProblem } from "./errors.js";
 import { DecidioHttpError, decisionIdProblem } from "./errors.js";
-export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential } from "./signing.js";
+export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential, bindingMaterial, requestCommitment, idempotencyKey, committedRequestJson } from "./signing.js";
 export { canonicalize, canonicalizeArgs, canonicalJson, DecidioUnsafeArgumentsError } from "./canonical.js";
 export { readConfirmResponse, buildConfirmBody, describeTierGap, EVIDENCE_TIERS } from "./evidence.js";
 export class DecidioBlockedError extends Error {
@@ -29,6 +29,38 @@ export class DecidioRejectedError extends Error {
         this.name = "DecidioRejectedError";
     }
 }
+export class DecidioRequestChangedError extends DecidioBlockedError {
+    code = "request_changed";
+    constructor(decisionId, detail) {
+        super(detail ?? `the request changed after approval (decision ${decisionId})`, decisionId);
+        this.name = "DecidioRequestChangedError";
+        this.message = `[decidio] the request changed after approval: decision ${decisionId} was approved for a different request than the one about to run. Nothing was executed. ${detail && !/^the request changed after approval/.test(detail) ? `(${detail}) ` : ""}A changed request needs its own approval — reject ${decisionId} and run the action again.`;
+    }
+}
+export class DecidioApprovalUnverifiedError extends DecidioBlockedError {
+    code;
+    constructor(decisionId, code, detail) {
+        super(detail, decisionId);
+        this.code = code;
+        this.name = "DecidioApprovalUnverifiedError";
+        this.message = `[decidio] cannot confirm that decision ${decisionId} approved THIS request: ${detail}. Nothing was executed.`;
+    }
+}
+export function approvalRefusal(check) {
+    const id = check.decisionId;
+    switch (check.code) {
+        case "rejected": return new DecidioRejectedError(check.reason ?? "rejected by approver", id);
+        case "blocked": return new DecidioBlockedError(check.reason ?? "blocked by policy", id);
+        case "request_changed": return new DecidioRequestChangedError(id, check.reason);
+        case "commitment_missing": return new DecidioApprovalUnverifiedError(id, "commitment_missing", check.reason ?? "Decidio answered without the request commitment this SDK sent");
+        case "unverifiable": return new DecidioApprovalUnverifiedError(id, "unverifiable", check.reason ?? "the approval could not be tied to this request");
+        case "pending": return new DecidioBlockedError(`not approved - ${check.reason ?? `Decidio records ${id} as pending`}`, id);
+        default: return new DecidioBlockedError(check.reason ?? `not approved (Decidio answered ${JSON.stringify(check.state)})`, id);
+    }
+}
+export function coreRequest(ctx, args) {
+    return { action: ctx.action, amount: ctx.amount, ...(ctx.scope !== undefined && ctx.scope !== null ? { scope: ctx.scope } : {}), args };
+}
 export class DecidioTimeoutError extends Error {
     decisionId;
     withdrawn;
@@ -153,12 +185,16 @@ export function withApproval(fn, describe, config, opts) {
             ? signBoundProof(config.agentKey, { agentId: config.agentId, did: config.agentDid, action: ctx.action, amount: ctx.amount, scope: ctx.scope, workspaceId: config.workspaceId })
             : undefined;
         assertDescribed(ctx);
+        const material = bindingMaterial(config);
+        const committed = coreRequest(ctx, args);
+        const sentCommitment = material ? requestCommitment(material, committed) : undefined;
         const auth = await post(config, "/agent/authorize", {
             requester: config.agentId, action: ctx.action, amount: ctx.amount,
             scope: ctx.scope, sourceSystem: config.sourceSystem,
             ...(ctx.context ? { context: ctx.context } : {}),
             ...(requesterIdentity ? { requesterIdentity } : {}),
             ...(resumeUrl ? { resumeUrl } : {}),
+            ...(sentCommitment ? { requestCommitment: sentCommitment } : {}),
         });
         if (auth.decision !== "proceed" && auth.decision !== "route" && auth.decision !== "block")
             throw new DecidioBlockedError(`unrecognized gate verdict: ${String(auth.decision)}`, auth.decisionId);
@@ -181,14 +217,18 @@ export function withApproval(fn, describe, config, opts) {
                 await config.resume.park({
                     decisionId: auth.decisionId, receiptId: auth.receiptId,
                     action: ctx.action, amount: ctx.amount, scope: ctx.scope, args,
+                    ...(sentCommitment ? { requestCommitment: sentCommitment } : {}),
                 });
                 throw new DecidioSuspendedError(auth.decisionId, ctx.action);
             }
             const deadline = Date.now() + pollTimeout;
+            let approvedStatus;
             while (true) {
                 const st = await get(config, `/agent/status/${encodeURIComponent(auth.decisionId)}`);
-                if (st.state === "approved" || st.state === "auto_approved")
+                if (st.state === "approved" || st.state === "auto_approved") {
+                    approvedStatus = st;
                     break;
+                }
                 if (st.state === "rejected")
                     throw new DecidioRejectedError(st.reason ?? "rejected by approver", auth.decisionId);
                 if (st.state === "blocked")
@@ -215,6 +255,9 @@ export function withApproval(fn, describe, config, opts) {
                 }
                 await sleep(pollInterval);
             }
+            const check = await checkApproval(config, auth.decisionId, committed, { sent: !!sentCommitment, ...(approvedStatus ? { status: approvedStatus } : {}) });
+            if (!check.ok)
+                throw approvalRefusal(check);
         }
         const result = opts?.withContext
             ? await fn({ decisionId: auth.decisionId, attemptId: null, idempotencyKey: auth.decisionId }, ...args)

package/dist/inngest.d.ts

@@ -1,6 +1,6 @@
 import type { RequestListener } from "node:http";
 import { verifyResumeSignature } from "./resume.js";
-import type { GuardConfig, ApprovalContext, EvidenceOutcome } from "./index.js";
+import { type GuardConfig, type ApprovalContext, type EvidenceOutcome } 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";
@@ -51,7 +51,10 @@ export type GateStepOutcome<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.
+ *               THIS decision arrives - a WAKE-UP (0.7.0): a memoized step then confirms with
+ *               Decidio that THIS request was approved; approved → run + confirm; rejected /
+ *               blocked → status; still pending → wait for the next event; the request changed
+ *               after approval → DecidioRequestChangedError.
  *   • 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),

package/dist/inngest.js

@@ -1,5 +1,6 @@
-import { verifyResumeSignature } from "./resume.js";
-import { gateAuthorize, gateConfirm, assertAuthorizeVerdict, verdictFrom, checkEngineVersion } from "./adapters/_gate.js";
+import { verifyResumeSignature, WEBHOOK_SECRET_REMEDY } from "./resume.js";
+import { gateAuthorize, gateConfirm, assertAuthorizeVerdict, gateCheckApproval, assertApprovalCheckShape, checkEngineVersion } from "./adapters/_gate.js";
+import { approvalRefusal } from "./index.js";
 export const DECIDIO_RESUME_EVENT = "decidio/decision.resolved";
 export async function decidioGateStep(args) {
     const { step, config, ctx } = args;
@@ -8,18 +9,25 @@ export async function decidioGateStep(args) {
     if (auth.decision === "block")
         return { status: "blocked", decisionId: auth.decisionId };
     if (auth.decision === "route") {
-        const ev = await step.waitForEvent("decidio-await-approval", {
-            event: DECIDIO_RESUME_EVENT,
-            timeout: args.timeout ?? "30d",
-            if: `async.data.decisionId == "${auth.decisionId}"`,
-        });
-        if (!ev)
-            throw new Error(`decidio approval timed out (${auth.decisionId})`);
-        const verdict = verdictFrom(ev.data);
-        if (verdict === "rejected")
-            return { status: "rejected", decisionId: auth.decisionId };
-        if (verdict !== "approved" && verdict !== "auto_approved")
-            return { status: "blocked", decisionId: auth.decisionId };
+        for (let n = 0;; n++) {
+            const suffix = n === 0 ? "" : `-${n}`;
+            const ev = await step.waitForEvent(`decidio-await-approval${suffix}`, {
+                event: DECIDIO_RESUME_EVENT,
+                timeout: args.timeout ?? "30d",
+                if: `async.data.decisionId == "${auth.decisionId}"`,
+            });
+            if (!ev)
+                throw new Error(`decidio approval timed out (${auth.decisionId})`);
+            const check = assertApprovalCheckShape(await step.run(`decidio-verify-approval${suffix}`, async () => gateCheckApproval(config, auth.decisionId, ctx)), auth.decisionId);
+            if (check.ok)
+                break;
+            if (check.code === "rejected")
+                return { status: "rejected", decisionId: auth.decisionId };
+            if (check.code === "blocked")
+                return { status: "blocked", decisionId: auth.decisionId };
+            if (check.code !== "pending")
+                throw approvalRefusal(check);
+        }
     }
     const result = await step.run("agent-action", args.run);
     const confirmation = await step.run("decidio-confirm", async () => gateConfirm(config, auth.decisionId, result, args.evidence));
@@ -42,7 +50,7 @@ export function createInngestResumeBridge(opts) {
                 if (!secret) {
                     if (!opts.allowUnsigned) {
                         res.statusCode = 401;
-                        return res.end(JSON.stringify({ error: "resume webhook unsigned and no secret configured" }));
+                        return res.end(JSON.stringify({ error: `resume webhook unsigned and no secret configured. ${WEBHOOK_SECRET_REMEDY}` }));
                     }
                 }
                 else if (!verifyResumeSignature(secret, raw, req.headers["x-decidio-signature"])) {

package/dist/resume.d.ts

@@ -1,4 +1,5 @@
 import type { RequestListener } from "node:http";
+import { type CommittedRequest } from "./signing.js";
 import { type EvidenceOutcome, type EvidenceTier } from "./evidence.js";
 export declare function signEvidence(decisionId: string, attemptId: string | null, evidence: unknown, agentKey?: string, webhookSecret?: string): {
     kind: "ed25519" | "hmac";
@@ -30,6 +31,13 @@ export interface PendingAction {
         kind: "ed25519" | "hmac";
         sig: string;
     };
+    /** The request commitment this SDK SENT with /agent/authorize (0.7.0) — see `requestCommitment`
+     *  in signing.ts. Recorded so `resolve()` can apply the one fail-closed rule that needs to know
+     *  what was sent: a gate that answers with no commitment for a request this SDK bound is refused.
+     *  The value that decides execution is always a FRESH recompute over these parked arguments,
+     *  compared with the commitment Decidio returns. Absent on entries parked before 0.7.0 (and by
+     *  an agent with no key material), which are checked on Decidio's state alone. */
+    requestCommitment?: 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 —
@@ -462,7 +470,17 @@ export declare class DecidioSuspendedError extends Error {
  *  parked for a later signal. It used to read `unknown` (the word for "not ours") for the claim loser and
  *  `no_handler` for the boundary loser although a handler was registered (prodsec V040-01). A loss to a FINAL
  *  answer (a denial, an execution) stays `already_resolved`. Additive, like the two above. */
-export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown" | "indeterminate" | "already_resolved" | "lost_race";
+/** `not_approved` (0.7.0): the signal said "approved" but DECIDIO does not record an approval for this
+ *  decision (it is still pending, or answered a state this SDK does not recognise). Every resume signal
+ *  is a wake-up now, never the authority: the approval is confirmed with GET /agent/status right before
+ *  the action runs. Nothing ran; the entry stays parked and a later signal resolves it. Not a resolution,
+ *  so `onResolved` does not fire (like `unknown`).
+ *  `request_unverified` (0.7.0): Decidio records an approval, but it cannot be tied to THIS parked
+ *  request — the request changed after approval (the commitment Decidio holds does not match a fresh
+ *  recompute over the parked arguments), the gate kept no commitment for a request this SDK bound, or
+ *  this process lacks the key material to recompute it. `reason` says which. Nothing ran; the entry
+ *  stays parked for inspection. Both members are additive, announced in the changelog. */
+export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown" | "indeterminate" | "already_resolved" | "lost_race" | "not_approved" | "request_unverified";
 /** The states a durable action can actually be in — every one of them nameable, including the
  *  one nobody likes. */
 export type RecoveryState = 
@@ -558,8 +576,15 @@ export interface ResumeConfig {
     /** 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. */
+    /** Shared secret Decidio signs the resume webhook with (HMAC-SHA256) — DECIDIO_WEBHOOK_SECRET, the
+     *  dedicated secret your Decidio deployment signs resume webhooks with (never its API_AUTH_TOKEN, the
+     *  admin bearer). NO FALLBACK since 0.7.0: it used to default to
+     *  the API token, so anyone holding a leaked agent token could sign an "approved" callback. With
+     *  no secret (and no `allowUnsigned`) the webhook handlers refuse every call. The poll worker
+     *  (`worker()`) needs no inbound secret. The webhook is only a WAKE-UP either way: the approval
+     *  is confirmed with Decidio (GET /agent/status + the request commitment) before anything runs.
+     *  (The parked-payload integrity HMAC still falls back to the API token when this is unset — that
+     *  key never authenticates a signal.) */
     webhookSecret?: string;
     /** @deprecated Ignored since 0.2.0 and accepted only so existing callers keep compiling.
      *  Execution evidence now lives in the PendingStore's own execution record, beside the state
@@ -604,13 +629,22 @@ export interface ResumeController extends ResumeConfig {
     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 answers `already_resolved` (no double-write); an id this SDK never parked
-     *  answers `unknown`; a call that loses the pre-invocation claim answers `lost_race`. */
+     *  answers `unknown`; a call that loses the pre-invocation claim answers `lost_race`.
+     *
+     *  `verdict: "approved"` is a REQUEST to execute, never the authority (0.7.0): right before the
+     *  action runs, resolve() confirms with Decidio that THIS parked request was approved (GET
+     *  /agent/status + the request commitment — `checkApproval`). Decidio still pending → `not_approved`;
+     *  Decidio says rejected/blocked → recorded as that denial; an approval that cannot be tied to these
+     *  arguments → `request_unverified`. A transport failure during that check throws (nothing ran). A
+     *  `rejected`/`blocked` verdict is applied as given — it can only ever prevent execution. */
     resolve(input: {
         decisionId: string;
         verdict: "approved" | "rejected" | "blocked";
         reason?: string;
     }): Promise<ResumeOutcome>;
-    /** node:http listener for Decidio's signed approval webhook (Express/Fastify/node). */
+    /** node:http listener for Decidio's signed approval webhook (Express/Fastify/node). The webhook is a
+     *  WAKE-UP (0.7.0): after its signature is verified — with `webhookSecret` only, never the API token —
+     *  only its decision id is read; the outcome follows Decidio's own state for that decision. */
     webhookHandler(): RequestListener;
     /** Web-Fetch handler (Request → Response) for Next.js route handlers, Hono,
      *  Cloudflare Workers, Bun, Deno. Same fail-closed signature check. */
@@ -666,6 +700,65 @@ export declare function verifyResumeSignature(secret: string, body: string, head
  *  is never evidence). Its own comment claimed it was "shared by every confirm door", and no door
  *  called it: the claim was what kept anyone from noticing the disagreement. */
 export declare function assertConfirmRecorded(body: any, decisionId: string, signed: boolean): string;
+/** What GET /agent/status answers. `requestCommitment` (0.7.0) is the commitment the decision was
+ *  authorized with, or null for a decision whose request was never bound. */
+export interface DecisionStatus {
+    state: string;
+    reason?: string | null;
+    requestCommitment?: string | null;
+}
+type StatusConfig = {
+    apiUrl: string;
+    apiToken?: string;
+    agentKey?: string;
+    agentDid?: string;
+    fetchImpl?: typeof fetch;
+};
+/** Why an approval check did not pass.
+ *  pending / unrecognized_state — Decidio records no approval (yet): nothing may run.
+ *  rejected / blocked           — Decidio's final answer is no.
+ *  request_changed              — the approval is for a DIFFERENT request than the one about to run.
+ *  commitment_missing           — this SDK bound the request, the gate answered without a commitment.
+ *  unverifiable                 — Decidio holds a commitment this process cannot recompute (no or
+ *                                 unreadable key material), or answered a malformed one. */
+export type ApprovalCheckCode = "pending" | "unrecognized_state" | "rejected" | "blocked" | "request_changed" | "commitment_missing" | "unverifiable";
+/** The outcome of the one check. Plain JSON on purpose: an engine that runs it as an activity or a
+ *  step (Temporal, Inngest) memoizes it across its serialization boundary. */
+export interface ApprovalCheck {
+    ok: boolean;
+    decisionId: string;
+    /** Decidio's derived state, verbatim ("" when it answered none). */
+    state: string;
+    code?: ApprovalCheckCode;
+    /** The server's (tokenized) reason for a rejection, or this SDK's explanation of a refusal. */
+    reason?: string;
+}
+/** CONFIRM WITH DECIDIO THAT *THIS* REQUEST WAS APPROVED — the check every door runs right before it
+ *  executes a routed approval: the inline blocking wait, the durable resume (webhook AND worker), and
+ *  each engine adapter (LangGraph, Temporal, Inngest, OpenAI Agents). A resume signal is a wake-up; it
+ *  is never the authority.
+ *
+ *  Approved means: GET /agent/status/:decisionId answers approved/auto_approved AND the commitment it
+ *  returns equals a FRESH recompute over `request` — the exact request about to run. The fail-closed
+ *  rules:
+ *   - Decidio holds a commitment → it must match; no key material to recompute it → refused.
+ *   - Decidio holds none, but this SDK bound the request (`sent`, default: this config has key
+ *     material, so it would have sent one) → refused: the gate predates request binding.
+ *   - Decidio holds none and nothing was bound (a keyless agent, or an entry parked before 0.7.0) →
+ *     the state alone decides — nothing on either side could say more.
+ *  A transport failure THROWS (it is not an answer); every other outcome is a value.
+ *
+ *  `status` lets a caller that has just read the status (the blocking poll, the worker) pass it in
+ *  instead of reading it twice. */
+export declare function checkApproval(cfg: StatusConfig, decisionId: string, request: CommittedRequest, opts?: {
+    sent?: boolean;
+    status?: DecisionStatus;
+}): Promise<ApprovalCheck>;
+/** The webhook handlers' refusal when no webhook secret is configured - with the remedy. */
+/** The one remedy every webhook-secret refusal names (#4B review W3): the dedicated webhook secret - NEVER the
+ *  server's API_AUTH_TOKEN, the admin bearer, which a refusal that said "the value your deployment signs
+ *  with" used to steer operators into copying onto agent hosts. */
+export declare const WEBHOOK_SECRET_REMEDY = "Set webhookSecret (DECIDIO_WEBHOOK_SECRET) to the dedicated secret your Decidio deployment signs resume webhooks with - never the server's API_AUTH_TOKEN (its admin bearer, which must not be copied onto an agent host) - or use the poll worker (guard.worker()), which needs no inbound secret.";
 export declare function createDecidioResume(opts: ResumeConfig & {
     store: PendingStore;
 }): ResumeController;