@decidio/sdk 0.1.9 → 0.1.11

package/dist/inngest.js

@@ -1,48 +1,13 @@
 import { verifyResumeSignature } from "./resume.js";
-import { signBoundProof, signConfirm } from "./signing.js";
-/** The Inngest event Decidio's verdict is translated into. The waiting function
- *  correlates on `data.decisionId`. */
+import { gateAuthorize, gateConfirm, assertAuthorizeVerdict, verdictFrom, checkEngineVersion } from "./adapters/_gate.js";
 export const DECIDIO_RESUME_EVENT = "decidio/decision.resolved";
-/**
- * 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 async function decidioGateStep(args) {
     const { step, config, ctx } = args;
-    const base = config.apiUrl.replace(/\/$/, "");
-    const f = config.fetchImpl ?? fetch;
-    const authHeaders = { "content-type": "application/json", ...(config.apiToken ? { authorization: `Bearer ${config.apiToken}` } : {}) };
-    // 1. authorize (memoized as a step, so a replay doesn't re-ask the gate)
-    const auth = await step.run("decidio-authorize", async () => {
-        // Sign the bound proof so an Inngest-path agent can prove its identity + auto-approve.
-        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;
-        const res = await f(base + "/agent/authorize", {
-            method: "POST", headers: authHeaders,
-            body: JSON.stringify({
-                requester: config.agentId, action: ctx.action, amount: ctx.amount, scope: ctx.scope,
-                sourceSystem: config.sourceSystem,
-                ...(requesterIdentity ? { requesterIdentity } : {}),
-                ...(config.resumeUrl ? { resumeUrl: config.resumeUrl } : {}),
-            }),
-        });
-        if (!res.ok)
-            throw new Error(`decidio authorize ${res.status}`);
-        return res.json();
-    });
+    const auth = await step.run("decidio-authorize", async () => gateAuthorize(config, ctx));
+    assertAuthorizeVerdict(auth, auth?.decisionId);
     if (auth.decision === "block")
         return { status: "blocked", decisionId: auth.decisionId };
     if (auth.decision === "route") {
-        // 2. durably SUSPEND until the resume event for THIS decision arrives. Zero
-        //    compute while waiting; the worker/process may be recycled — Inngest resumes
-        //    from this checkpoint. `if` correlates the awaited event to this decisionId.
         const ev = await step.waitForEvent("decidio-await-approval", {
             event: DECIDIO_RESUME_EVENT,
             timeout: args.timeout ?? "30d",
@@ -50,31 +15,16 @@ export async function decidioGateStep(args) {
         });
         if (!ev)
             throw new Error(`decidio approval timed out (${auth.decisionId})`);
-        const verdict = ev.data?.verdict;
+        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 };
     }
-    // 3. authorized → perform the agent's OWN action (a step), then confirm the captured
-    //    response so Decidio seals application_confirmed (never executes it itself).
     const result = await step.run("agent-action", args.run);
-    await step.run("decidio-confirm", async () => {
-        const requesterIdentity = signConfirm(auth.decisionId, config);
-        await f(base + "/agent/confirm", {
-            method: "POST", headers: authHeaders,
-            body: JSON.stringify({ decisionId: auth.decisionId, capturedResponse: result ?? null, source: "wrapper", ...(requesterIdentity ? { requesterIdentity } : {}) }),
-        });
-        return true;
-    });
+    await step.run("decidio-confirm", async () => { await gateConfirm(config, auth.decisionId, result); return true; });
     return { status: "executed", decisionId: auth.decisionId, result };
 }
-/**
- * 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 function createInngestResumeBridge(opts) {
     const secret = opts.webhookSecret ?? "";
     const eventName = opts.eventName ?? DECIDIO_RESUME_EVENT;
@@ -110,5 +60,5 @@ export function createInngestResumeBridge(opts) {
         });
     };
 }
-// Re-export the signature check so a host can verify the webhook out-of-band if needed.
 export { verifyResumeSignature };
+checkEngineVersion("inngest");

package/dist/resume.d.ts

@@ -1,4 +1,5 @@
 import type { RequestListener } from "node:http";
+import { type EvidenceOutcome, type EvidenceTier } from "./evidence.js";
 /** 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 {
@@ -9,8 +10,8 @@ export interface PendingAction {
     scope?: string;
     args: unknown[];
     createdAt: string;
-    /** Integrity binding over {decisionId, action, amount, scope, args} (round-6 acceptance
-     *  catch: the parked payload was mutable between routing and execution). ed25519 = detached
+    /** 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
@@ -41,6 +42,9 @@ export interface PendingStore {
     claim?(decisionId: string): Promise<boolean>;
     /** Undo a claim so a failed execution is retryable. */
     release?(decisionId: string): Promise<void>;
+    /** Entries currently CLAIMED (excluded from list()). Needed for honest recovery reporting —
+     *  a claimed entry with no journalled result is the indeterminate case. */
+    listClaimed?(): Promise<PendingAction[]>;
 }
 export declare class MemoryPendingStore implements PendingStore {
     private m;
@@ -51,7 +55,13 @@ export declare class MemoryPendingStore implements PendingStore {
     list(): Promise<PendingAction[]>;
     claim(id: string): Promise<boolean>;
     release(id: string): Promise<void>;
+    listClaimed(): Promise<PendingAction[]>;
 }
+/** Restrict a directory to its owner. On Windows POSIX modes are a no-op, so strip inheritance
+ *  and grant only the effective user. A FAILURE IS SAID, never swallowed: these files hold the
+ *  arguments of actions awaiting approval, and "silently kept the directory's inherited
+ *  permissions" is exactly the outcome an operator must not discover from an auditor. */
+export declare function hardenDir(dir: string): 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
@@ -69,6 +79,9 @@ export declare class FilePendingStore implements PendingStore {
     list(): Promise<PendingAction[]>;
     claim(id: string): Promise<boolean>;
     release(id: string): Promise<void>;
+    /** Claimed entries (`.claimed` files) — invisible to list() by design, but a stranded one is
+     *  exactly what recovery must surface. */
+    listClaimed(): Promise<PendingAction[]>;
 }
 /** 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.
@@ -80,18 +93,57 @@ export declare class DecidioSuspendedError extends Error {
     constructor(decisionId: string, action: string);
 }
 export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown";
+/** A durable note that an action ALREADY RAN and what must still be reported. It lives OUTSIDE
+ *  the pending store on purpose: a journal entry carries no handler binding, so replaying it can
+ *  only ever re-send a report — it can never re-run the business action. That is what makes
+ *  recovery safe on stores with and without claim(). */
+export interface ExecutionJournalEntry {
+    decisionId: string;
+    action: string;
+    /** The canonical value that was reported — the durable FACT, journalled before the first
+     *  attempt. Deliberately NOT the signed request: both proofs on a confirm are short-lived (the
+     *  identity proof lives 120s, the execution report 5 minutes), so a replayed envelope is
+     *  refused by the server for any outage longer than that — which is every outage worth
+     *  recovering from. `reconfirm` re-signs at SEND time over these same bytes, so the report
+     *  stays replay-safe (it still cannot re-run anything: no handler is journalled) while staying
+     *  usable a week later. */
+    reported: unknown;
+    at: string;
+}
+/** The states a durable action can actually be in — every one of them nameable, including the
+ *  one nobody likes. */
+export type RecoveryState = 
+/** Parked, waiting on a human. Nothing has executed. */
+"parked"
+/** Claimed for execution and NOT journalled: the process died somewhere between claiming and
+ *  recording the result. The action MAY OR MAY NOT have run — this cannot be resolved locally
+ *  and must never be retried automatically. */
+ | "indeterminate"
+/** Executed, result captured, report not yet accepted by Decidio. Safe to `reconfirm`. */
+ | "executed_unreported";
+export interface RecoveryItem {
+    decisionId: string;
+    action?: string;
+    state: RecoveryState;
+    /** What a human should do about it, in words. */
+    guidance: string;
+}
 export interface ResumeOutcome {
     status: ResumeStatus;
     decisionId: string;
     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 (prodsec F-03:
-     *  the two were conflated, and a lost confirmation read as success). */
-    confirmed?: boolean;
-    /** executed only: the evidence tier the server says it recorded (e.g. application_confirmed). */
-    evidenceTier?: string;
+    /** executed only: Decidio ACCEPTED the execution report and named the tier it recorded.
+     *  `status: "executed"` describes the LOCAL run; this describes the record. */
+    reportRecorded?: boolean;
+    /** executed only: the recorded tier attests a COMMITTED execution. Deliberately a different
+     *  question — and a different name — from `reportRecorded`. */
+    executionConfirmed?: boolean;
+    /** executed only: the evidence tier Decidio recorded, verbatim. */
+    evidenceTier?: EvidenceTier;
+    /** executed only: why the evidence landed where it did, when that is worth explaining. */
+    diagnostic?: string;
 }
 /** Minimal config the controller needs to confirm outcomes + poll status. Shared
  *  with GuardConfig (apiUrl/apiToken). */
@@ -110,13 +162,19 @@ export interface ResumeConfig {
     /** Shared secret Decidio signs the resume webhook with (HMAC-SHA256). Defaults to
      *  the API token if unset. Verified before any re-execution. */
     webhookSecret?: string;
+    /** Where the execution journal lives (default `<pending dir>/reports`). Separate from the
+     *  pending store by design: journal entries can only re-send a report, never re-run an action. */
+    reportDir?: string;
+    /** Map the action's natural return value to the evidence Decidio records — same option, same
+     *  meaning as `protect`'s, so a durable resume reports exactly what the inline path would. */
+    evidence?: (result: any) => unknown;
     /** 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 (prodsec F-07: an absolute
-     *  fail-closed claim must disclose its opt-out). Only behind a trusted network
-     *  boundary (e.g. mTLS / private mesh), never on an internet-reachable endpoint. */
+     *  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. */
@@ -158,27 +216,26 @@ export interface ResumeController extends ResumeConfig {
     }): {
         stop: () => void;
     };
+    /** Re-send a journalled execution report, IDEMPOTENTLY. Replays the exact request built before
+     *  the first attempt — it can never re-run the business action, because the journal holds no
+     *  handler binding. Returns the evidence outcome; a decision with nothing journalled returns
+     *  `reportRecorded: false` with guidance rather than pretending. */
+    reconfirm(decisionId: string): Promise<EvidenceOutcome>;
+    /** Every durable item that needs a human's attention, with its state named — including the one
+     *  state that CANNOT be resolved automatically: `indeterminate`, where a process died between
+     *  claiming an action and journalling its result, so whether the action ran is unknown locally.
+     *  This never executes or retries anything; it reports. */
+    recover(): Promise<RecoveryItem[]>;
 }
 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, used by ALL THREE TS confirm doors (resume, inline withApproval,
- *  adapter gate — guard equivalent-path catch: it lived only on the resume door). Transport
- *  success is not confirmation (prodsec F-03): 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. */
+/** 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;