@decidio/sdk 0.1.11 → 0.1.12

package/README.md

@@ -413,6 +413,7 @@ manager for production.
   the fix. Anything else is transient, and retrying is safe because a retry creates a *new* request
   and can never double-execute.
 - `DecidioNetworkError` — the gate was unreachable. Nothing executed locally.
+- `DecidioUnsafeArgumentsError` — your call arguments cannot survive JSON with their meaning intact, so nothing was routed and nothing ran. The message names the field and the fix. Most often: `NaN`/`Infinity`, `-0`, a `Date`, `Map` or class instance, a `BigInt`, or a sparse array — anything whose serialized form would differ from the value the approval and signature cover. Pass the already-serialized form.
 
 ```js
 try { await payInvoice(inv); }

package/dist/adapters/_gate.js

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { DecidioBlockedError, DecidioRejectedError, DecidioHttpError, signBoundProof, signConfirm, assertSafeTransport, canonicalize, readConfirmResponse, buildConfirmBody } from "../index.js";
+import { DecidioBlockedError, DecidioRejectedError, DecidioHttpError, signBoundProof, signConfirm, assertSafeTransport, carriesCredential, canonicalize, readConfirmResponse, buildConfirmBody } from "../index.js";
 export const AUTHORIZE_VERDICTS = ["proceed", "route", "block"];
 export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
     const a = auth;
@@ -7,11 +7,14 @@ export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
     if (!a || !AUTHORIZE_VERDICTS.includes(a.decision)) {
         throw new DecidioBlockedError(`unrecognised authorization verdict ${JSON.stringify(a?.decision ?? null)} — refusing to execute. The gate answers ${AUTHORIZE_VERDICTS.join(" | ")}; anything else means this SDK version does not understand the decision (upgrade @decidio/sdk), and an answer you do not understand is never permission.`, decisionId);
     }
+    if (typeof a.decisionId !== "string" || !a.decisionId) {
+        throw new DecidioBlockedError(`the gate answered "${a.decision}" with no usable decisionId (${JSON.stringify(a.decisionId ?? null)}) — refusing to execute. Every authorized action must be addressable: without an id it cannot be polled, resumed, confirmed or audited.`, decisionId);
+    }
     return a;
 }
 export async function gateAuthorize(config, ctx) {
     canonicalize(ctx, "describe(...)");
-    assertSafeTransport(config.apiUrl, !!config.apiToken);
+    assertSafeTransport(config.apiUrl, carriesCredential(config));
     const f = config.fetchImpl ?? fetch;
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;
     const requesterIdentity = (config.agentKey && config.agentDid)
@@ -40,17 +43,25 @@ export async function gateAuthorize(config, ctx) {
 export async function gateConfirm(config, decisionId, result) {
     const f = config.fetchImpl ?? fetch;
     try {
-        assertSafeTransport(config.apiUrl, !!config.apiToken);
+        assertSafeTransport(config.apiUrl, carriesCredential(config));
     }
     catch (e) {
         console.warn(`[decidio] confirm failed (action succeeded): ${e.message}`);
         return;
     }
+    let reported = null;
+    let evidenceProblem;
+    try {
+        reported = canonicalize(result ?? null, "result");
+    }
+    catch (e) {
+        evidenceProblem = String(e?.message ?? e);
+        console.warn(`[decidio] ${decisionId}: the action SUCCEEDED but its result could not be reported as evidence (${evidenceProblem}). Reporting an empty captured response so the execution is still recorded — map the return value with the \`evidence\` option to earn a confirming tier. The action was NOT re-run.`);
+    }
     try {
         const requesterIdentity = signConfirm(decisionId, config);
         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.`);
-        const reported = canonicalize(result ?? null, "result");
         const res = await f(config.apiUrl.replace(/\/$/, "") + "/agent/confirm", {
             method: "POST",
             headers: { "content-type": "application/json", ...(config.apiToken ? { authorization: `Bearer ${config.apiToken}` } : {}) },
@@ -63,8 +74,10 @@ export async function gateConfirm(config, decisionId, result) {
         const ev = readConfirmResponse(await res.json().catch(() => null), { signed: !!requesterIdentity, capturedResponse: reported });
         if (!ev.reportRecorded)
             console.warn(`[decidio] ${decisionId}: ${ev.diagnostic}`);
-        else if (!ev.executionConfirmed)
+        else if (!ev.executionConfirmed || ev.executionReportVerified === false)
             console.warn(`[decidio] execution evidence for ${decisionId} recorded as ${ev.evidenceTier} — ${ev.diagnostic}`);
+        if (evidenceProblem)
+            console.warn(`[decidio] ${decisionId}: the execution IS recorded, but with an empty captured response — see the evidence note above.`);
     }
     catch (e) {
         console.warn(`[decidio] confirm failed (action succeeded): ${e.message}`);

package/dist/canonical.js

@@ -10,6 +10,22 @@ const NOT_ROUTED = "The decision was NOT routed; nothing reached Decidio.";
 function refuse(path, what, fix) {
     throw new DecidioUnsafeArgumentsError(`[decidio] ${path} ${what} — the approval payload must be plain JSON so that what a human approves is exactly what executes; ${fix} ${NOT_ROUTED}`);
 }
+function assertNoLoneSurrogate(s, p) {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff) {
+            const n = s.charCodeAt(i + 1);
+            if (n >= 0xdc00 && n <= 0xdfff) {
+                i++;
+                continue;
+            }
+            refuse(p, `contains an unpaired surrogate (U+${c.toString(16).toUpperCase()})`, "it cannot be encoded as UTF-8, so no wire or seal can carry it — repair the string (it is usually a split emoji or truncated UTF-16).");
+        }
+        else if (c >= 0xdc00 && c <= 0xdfff) {
+            refuse(p, `contains an unpaired surrogate (U+${c.toString(16).toUpperCase()})`, "it cannot be encoded as UTF-8, so no wire or seal can carry it — repair the string (it is usually a split emoji or truncated UTF-16).");
+        }
+    }
+}
 export function canonicalize(value, path = "args") {
     return walk(value, path, new Set());
 }
@@ -17,8 +33,12 @@ function walk(v, p, seen) {
     if (v === null)
         return null;
     const t = typeof v;
-    if (t === "boolean" || t === "string")
+    if (t === "boolean")
+        return v;
+    if (t === "string") {
+        assertNoLoneSurrogate(v, p);
         return v;
+    }
     if (t === "number") {
         const n = v;
         if (!Number.isFinite(n))
@@ -72,7 +92,11 @@ function walk(v, p, seen) {
                 refuse(`${p}.${key}`, "is a getter/setter", "an accessor is evaluated at serialization time, so the approved value could differ from the executed one — pass a plain data property.");
             if (!d.enumerable)
                 refuse(`${p}.${key}`, "is a non-enumerable property", "JSON drops it, so the approver would never see it — make it enumerable or remove it.");
-            out[key] = walk(d.value, `${p}.${key}`, seen);
+            assertNoLoneSurrogate(key, `${p}.${key}`);
+            Object.defineProperty(out, key, {
+                value: walk(d.value, `${p}.${key}`, seen),
+                writable: true, enumerable: true, configurable: true,
+            });
         }
         return out;
     }

package/dist/cli.js

@@ -6,7 +6,7 @@ import { createServer } from "node:http";
 import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline";
 import { createRequire } from "node:module";
-import { generateKeypair } from "./signing.js";
+import { generateKeypair, assertSafeTransport } from "./signing.js";
 import { withApproval, DecidioRateLimitError, didFromPrivateKey } from "./index.js";
 import { verifyReceipt, runVerify } from "@decidio/verify";
 const VERSION = (() => {
@@ -65,9 +65,14 @@ async function api(path, init = {}, bearer) {
         err(`  Fix the file's permissions, or set DECIDIO_API_URL explicitly for this command. Nothing was sent.`);
         process.exit(1);
     }
-    if (auth && /^http:[/][/]/i.test(API) && !/^http:[/][/](localhost|127.0.0.1|.::1.)([:/]|$)/i.test(API)) {
-        err(`✘ refusing to send credentials over plaintext http to ${API} — use https, or localhost for local dev. Nothing was sent.`);
-        process.exit(1);
+    if (auth) {
+        try {
+            assertSafeTransport(API, true);
+        }
+        catch (e) {
+            err(`✘ ${String(e?.message ?? e).replace(/^\[decidio\] /, "")}`);
+            process.exit(1);
+        }
     }
     let res;
     try {
@@ -189,7 +194,10 @@ function ask(question, mute = false) {
     });
 }
 async function acquireSession(purpose) {
-    if (/^http:\/\//i.test(API) && !/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])([:/]|$)/i.test(API)) {
+    try {
+        assertSafeTransport(API, true);
+    }
+    catch {
         err(`✘ refusing to send workspace credentials over plaintext http to ${API}.`);
         err(`  Use https (the hosted sandbox is https://decidio-api.onrender.com) or localhost for local dev.`);
         return null;
@@ -404,12 +412,13 @@ async function cmdDoctor() {
                 const msLeft = payload.exp * 1000 - Date.now();
                 const days = Math.floor((msLeft + 60_000) / 86_400_000);
                 const left = msLeft < 86_400_000 ? `${Math.max(1, Math.floor(msLeft / 3_600_000))} hour(s)` : `${days} day(s)`;
+                const daysRounded = Math.round(msLeft / 86_400_000);
                 if (msLeft < 0)
                     line(false, `agent token: EXPIRED ${-days} day(s) ago — re-run \`npx @decidio/sdk init ${env.DECIDIO_AGENT_ID ?? "<agent>"}\` to mint a fresh one.`);
                 else if (days <= 14)
                     warn(`agent token: expires in ${left} — mint a fresh one before it does: npx @decidio/sdk init ${env.DECIDIO_AGENT_ID ?? "<agent>"}`);
                 else
-                    log(`✔ agent token: unexpired for another ${days} days (validity is decided by the server — see the token-scope check below)`);
+                    log(`✔ agent token: unexpired for another ${daysRounded} days (validity is decided by the server — see the token-scope check below)`);
             }
         }
         catch { }
@@ -647,12 +656,27 @@ async function cmdQuickstart(opts = {}) {
     const session = await acquireSession("The quickstart");
     if (!session)
         return 1;
-    const agentId = `quickstart-${randomBytes(2).toString("hex")}`;
-    log(`① Registering agent "${agentId}" (fresh name each run — no collisions)…`);
+    let agentId = `quickstart-${randomBytes(5).toString("hex")}`;
+    log(`① Registering agent "${agentId}"…`);
     const { did, privateKeyBase64 } = generateKeypair();
-    const reg = await api("/api/agents/register", { method: "POST", body: JSON.stringify({ agentId, did }) }, session);
+    let reg = await api("/api/agents/register", { method: "POST", body: JSON.stringify({ agentId, did }) }, session);
+    for (let attempt = 0; reg.status === 409 && attempt < 3; attempt++) {
+        agentId = `quickstart-${randomBytes(5).toString("hex")}`;
+        reg = await api("/api/agents/register", { method: "POST", body: JSON.stringify({ agentId, did }) }, session);
+        if (reg.status >= 200 && reg.status < 300)
+            log(`  (that name was taken — using "${agentId}" instead)`);
+    }
     if (!(reg.status >= 200 && reg.status < 300)) {
-        err(`✘ registration failed (${reg.status}): ${JSON.stringify(reg.body)}`);
+        err(`✘ could not register the tour's agent (${reg.status}): ${JSON.stringify(reg.body)}`);
+        if (reg.status === 409) {
+            err(`  Every generated name collided, which should be almost impossible — something is likely`);
+            err(`  wrong with this workspace's agent list rather than with your setup.`);
+            err(`  See what is registered: npx @decidio/sdk tokens list`);
+        }
+        else {
+            err(`  Check the target and your sign-in, then re-run: npx @decidio/sdk doctor`);
+        }
+        err(`  Nothing was written to this directory.`);
         return 1;
     }
     const mint = await api("/api/workspace/agent-token", { method: "POST", body: JSON.stringify({ agentId, label: "quickstart", expiresInDays: 7 }) }, session);
@@ -749,7 +773,10 @@ async function cmdQuickstart(opts = {}) {
         log("   Then re-run the quickstart interactively to watch the whole loop — or, for CI, re-run");
         log("   with --auto-approve-demo to let the tour approve itself under that explicit label.");
         log(`   Tidy up this tour's agent + token any time: npx @decidio/sdk quickstart cleanup`);
-        process.exit(0);
+        log("");
+        log("   (exit 3 = the tour stopped at the human moment. Nothing executed and no receipt was");
+        log("    written, so this run is deliberately not reported as a completed tour.)");
+        process.exit(3);
     }
     const ap = await api(`/api/decisions/${encodeURIComponent(decisionId)}/approve`, { method: "POST", body: JSON.stringify({ reason: opts.autoApproveDemo && !interactive ? "quickstart --auto-approve-demo (automated)" : "quickstart" }) }, session);
     if (!(ap.status >= 200 && ap.status < 300)) {
@@ -777,7 +804,13 @@ async function cmdQuickstart(opts = {}) {
     writeFileSync(fname, JSON.stringify(rec.body.credential, null, 2) + "\n");
     const issuer = rec.body?.issuer;
     const v = verifyReceipt(rec.body.credential, issuer);
-    log(`  ${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? `, PINNED to your workspace issuer ${issuer}` : "; issuer unpinned"})`);
+    log(`  ${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? `, PINNED to your workspace issuer ${issuer}` : ""})`);
+    if (!issuer) {
+        err(`  ⚠ the server did not return an issuer DID, so this check ran UNPINNED — it proves the`);
+        err(`    receipt is internally consistent, NOT who issued it (a self-signed forgery also passes).`);
+        err(`    Get your workspace's issuer DID from the app's record-verify panel, then re-check:`);
+        err(`      npx @decidio/sdk verify --issuer <did:key:...> ${fname}`);
+    }
     if (issuer)
         log(`    Keep that DID: it is your trust anchor — npx @decidio/sdk verify --issuer ${issuer} <receipt.json>`);
     const detail = await api(`/api/records/${encodeURIComponent(decisionId)}`, {}, session);
@@ -834,7 +867,12 @@ async function quickstartCleanup(session, envFile) {
         }
     }
     else {
-        log(`  ⚠ no DECIDIO_TOKEN_JTI in ${envFile} (older tour) — revoke by hand: npx @decidio/sdk tokens list, then tokens revoke <jti>. It expires on its own within 7 days.`);
+        err(`✘ no DECIDIO_TOKEN_JTI in ${envFile} (older tour) — this tour's token is STILL LIVE and this`);
+        err(`  command cannot revoke it. Nothing was deleted. Find and revoke it, then re-run cleanup:`);
+        err(`    npx @decidio/sdk tokens list`);
+        err(`    npx @decidio/sdk tokens revoke <jti>`);
+        err(`  (it also expires on its own within 7 days)`);
+        return 1;
     }
     if (existsSync(envFile)) {
         const TOUR_KEYS = new Set(["DECIDIO_API_URL", "DECIDIO_AGENT_ID", "DECIDIO_AGENT_DID", "DECIDIO_AGENT_KEY", "DECIDIO_API_TOKEN", "DECIDIO_WORKSPACE_ID", "DECIDIO_TOKEN_JTI"]);
@@ -984,8 +1022,10 @@ const USAGE = `decidio — the Decidio SDK command line
   npx @decidio/sdk approvals [--json] [--mine]   list pending agent approvals
   npx @decidio/sdk approvals approve <id> [reason]
   npx @decidio/sdk approvals reject <id> [reason]
-                                       the reason is FREE TEXT and is sealed verbatim. If it
-                                       starts with a dash, put it after -- or use --reason:
+                                       the reason is FREE TEXT, sent exactly as typed. It seals
+                                       immutably; personal or sensitive values are tokenized at
+                                       rest, so the STORED text can differ (see: receipt <id>).
+                                       If it starts with a dash, put it after -- or use --reason:
                                          ... approve <id> -- "-50% cut, per the board"
                                          ... approve <id> --reason "-50% cut, per the board"
   npx @decidio/sdk receipt <id>        download a sealed decision's Authority Receipt (.json)
@@ -996,7 +1036,9 @@ const USAGE = `decidio — the Decidio SDK command line
 Every NETWORK command talks to the hosted sandbox (https://decidio-api.onrender.com) unless
 DECIDIO_API_URL says otherwise; the target host is announced on stderr each run. "verify" is
 fully offline — it touches no network and reads no .env.
-Exit codes: 0 success · 1 failure or honest no-op (e.g. replay refused) · 2 usage error.
+Exit codes: 0 success · 1 failure or honest no-op (e.g. replay refused) · 2 usage error ·
+3 quickstart stopped at the human moment (headless: routed, but nothing executed and no
+receipt written — pass --auto-approve-demo for a run that completes unattended).
 Errors, and usage shown on ERROR paths, go to stderr; stdout carries results only (safe to
 pipe). Asked-for help — including this bare invocation — IS a result, so it prints here.
 Docs: the README that shipped with this package — node_modules/@decidio/sdk/README.md
@@ -1037,6 +1079,13 @@ async function main(argv) {
                 positionals.push(...argsIn.slice(i + 1));
                 break;
             }
+            const inFreeTextTail = cmd === "approvals"
+                && (positionals[0] === "approve" || positionals[0] === "reject")
+                && positionals.length >= 2;
+            if (!inFreeTextTail && a.startsWith("-") && !a.startsWith("--")) {
+                err(`✘ unknown option "${a}" for \`${cmd}\` — refusing to guess (a flag you meant to matter must never be silently ignored). Short flags are not supported; use the long form.\n\n${USAGE}`);
+                return 2;
+            }
             if (!a.startsWith("--")) {
                 positionals.push(a);
                 continue;
@@ -1108,12 +1157,15 @@ async function main(argv) {
             const head = dashdash >= 0 ? argsIn.slice(0, dashdash) : argsIn;
             const literal = dashdash >= 0 ? argsIn.slice(dashdash + 1) : [];
             const rIdx = head.indexOf("--reason");
+            const rEq = head.find((x) => x.startsWith("--reason="));
             const flagless = head.filter((x, i) => !x.startsWith("-") && !(rIdx >= 0 && i === rIdx + 1));
             const sub = flagless[0];
             const id = flagless[1];
             let reason;
             if (rIdx >= 0)
                 reason = head[rIdx + 1];
+            else if (rEq !== undefined)
+                reason = rEq.slice("--reason=".length);
             else if (literal.length)
                 reason = literal.join(" ");
             else if (sub && id) {
@@ -1121,10 +1173,14 @@ async function main(argv) {
                 const rest = head.slice(after).filter((x) => x !== "--json" && x !== "--mine");
                 reason = rest.length ? rest.join(" ") : undefined;
             }
-            if (rIdx >= 0 && (reason === undefined || reason.startsWith("-"))) {
+            if ((rIdx >= 0 || rEq !== undefined) && (reason === undefined || reason === "" || (rIdx >= 0 && reason.startsWith("--")))) {
                 err(`✘ --reason needs the text to record (quote it if it contains spaces): npx @decidio/sdk approvals ${sub ?? "approve"} <id> --reason "over budget -50% cut required"`);
                 return 2;
             }
+            if (reason !== undefined && sub !== "approve" && sub !== "reject") {
+                err(`✘ --reason only applies to approve/reject (a sealed reason needs a decision to seal onto): npx @decidio/sdk approvals approve <id> --reason "..."`);
+                return 2;
+            }
             return cmdApprovals(sub, id, reason, { json: head.includes("--json"), mine: head.includes("--mine") });
         }
         case "receipt": return cmdReceipt(argsIn.find((x) => !x.startsWith("-")), argsIn.includes("--json"));

package/dist/evidence.d.ts

@@ -13,6 +13,10 @@ export interface EvidenceOutcome {
     /** Present when the outcome is worth explaining (why a signed report did not confirm, or why
      *  a report was not recorded at all) — always actionable, never a shrug. */
     diagnostic?: string;
+    /** Present when the gate reported on the SIGNED execution report: whether the attestation
+     *  proof VERIFIED (C3, 0.1.12 — this field used to be read off the wire and discarded, so a
+     *  failed attestation was invisible to every client door). */
+    executionReportVerified?: boolean;
 }
 /** The SERVER's rule for `application_confirmed`, restated here exactly as implemented so this
  *  explanation can never drift from it: the captured response must carry a RECORD ID

package/dist/evidence.js

@@ -37,6 +37,14 @@ export function readConfirmResponse(body, opts) {
         outcome.diagnostic = describeTierGap(opts.capturedResponse);
     else if (!executionConfirmed)
         outcome.diagnostic = "no signing key is configured, so the gate capped this report at an unproven agent assertion. Run `npx @decidio/sdk init` to generate the agent's key and earn a confirming tier.";
+    const rpt = body?.executionReport;
+    if (rpt && typeof rpt === "object" && typeof rpt.verified === "boolean") {
+        outcome.executionReportVerified = rpt.verified;
+        if (!rpt.verified) {
+            const why = typeof rpt.reason === "string" && rpt.reason ? ` (${rpt.reason})` : "";
+            outcome.diagnostic = `${outcome.diagnostic ? outcome.diagnostic + " " : ""}The signed execution report did NOT verify${why} — the report was recorded without a proven attestation. Check the agent's key/DID/registration (npx @decidio/sdk doctor).`;
+        }
+    }
     return outcome;
 }
 import { signExecutionReport, resultDigest } from "./signing.js";

package/dist/guard.d.ts

@@ -65,7 +65,7 @@ export declare class Guard {
     /** Register a raw fn under its action name so a COLD process (one that never made the original
      *  call) can resume it. Call this at startup beside `guard.worker()` — or pass
      *  `{ action }` to `protect(...)`, which does it for you at wrap time. */
-    register(action: string, fn: (...a: any[]) => Promise<any>): void;
+    register(action: string, fn: (...a: any[]) => Promise<any>, evidence?: (result: any) => unknown): void;
     /** Mount on a node/Express/Fastify route: `app.post("/decidio/resume", guard.resumeHandler())`. */
     resumeHandler(): import("http").RequestListener;
     /** Mount on a Next.js/Hono/CF/Bun route: `export const POST = (req) => guard.resumeFetchHandler()(req)`. */

package/dist/guard.js

@@ -1,5 +1,6 @@
 import { withApproval } from "./index.js";
 import { createDecidioResume, FilePendingStore } from "./resume.js";
+import { join } from "node:path";
 export class Guard {
     config;
     _resume;
@@ -24,7 +25,7 @@ export class Guard {
             appUrl: process.env.DECIDIO_APP_URL,
         });
     }
-    register(action, fn) { this.ensureResume().register(action, fn); }
+    register(action, fn, evidence) { this.ensureResume().register(action, fn, evidence); }
     resumeHandler() { return this.ensureResume().webhookHandler(); }
     resumeFetchHandler() { return this.ensureResume().fetchHandler(); }
     worker(opts) {
@@ -37,6 +38,7 @@ export class Guard {
             this._resume = createDecidioResume({
                 apiUrl: c.apiUrl, apiToken: c.apiToken, webhookSecret: c.webhookSecret,
                 resumeUrl: c.resumeUrl, store: new FilePendingStore(c.pendingDir ?? ".decidio-pending"),
+                reportDir: join(c.pendingDir ?? ".decidio-pending", "reports"),
                 agentId: c.agentId, agentKey: c.agentKey, agentDid: c.agentDid, workspaceId: c.workspaceId,
                 fetchImpl: c.fetchImpl,
             });
@@ -72,9 +74,7 @@ export class Guard {
         }
         const resume = this.ensureResume();
         if (opts?.action)
-            resume.register(opts.action, fn);
-        if (opts?.evidence)
-            resume.evidence = opts.evidence;
+            resume.register(opts.action, fn, opts?.evidence);
         return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume }, opts?.evidence ? { evidence: opts.evidence } : undefined);
     }
 }

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export type { PendingAction, PendingStore, ResumeController, ResumeOutcome } fro
 export { guard, Guard } from "./guard.js";
 export type { GuardFacadeConfig, ProtectOptions } from "./guard.js";
 export { DecidioHttpError } from "./errors.js";
-export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport } from "./signing.js";
+export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential } from "./signing.js";
 export { canonicalize, canonicalizeArgs, canonicalJson, DecidioUnsafeArgumentsError } from "./canonical.js";
 export type { JsonValue, JsonPrimitive } from "./canonical.js";
 export { readConfirmResponse, buildConfirmBody, describeTierGap, EVIDENCE_TIERS } from "./evidence.js";

package/dist/index.js

@@ -1,12 +1,12 @@
 import { DecidioSuspendedError } from "./resume.js";
-import { signBoundProof, signConfirm, assertSafeTransport } from "./signing.js";
+import { signBoundProof, signConfirm, assertSafeTransport, carriesCredential } from "./signing.js";
 import { canonicalize, canonicalizeArgs } from "./canonical.js";
 import { readConfirmResponse, buildConfirmBody } from "./evidence.js";
 export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 export { guard, Guard } from "./guard.js";
 export { DecidioHttpError } from "./errors.js";
 import { DecidioHttpError } from "./errors.js";
-export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport } from "./signing.js";
+export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential } 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 {
@@ -80,7 +80,7 @@ async function reach(f, url, op, init) {
 }
 async function post(cfg, path, body) {
     const f = cfg.fetchImpl ?? fetch;
-    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
+    assertSafeTransport(cfg.apiUrl, carriesCredential(cfg));
     const res = await reach(f, cfg.apiUrl.replace(/\/$/, "") + path, `POST ${path}`, {
         method: "POST",
         headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
@@ -103,7 +103,7 @@ async function post(cfg, path, body) {
 }
 async function get(cfg, path) {
     const f = cfg.fetchImpl ?? fetch;
-    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
+    assertSafeTransport(cfg.apiUrl, carriesCredential(cfg));
     const res = await reach(f, cfg.apiUrl.replace(/\/$/, "") + path, `GET ${path}`, {
         headers: { ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
     });
@@ -151,6 +151,8 @@ export function withApproval(fn, describe, config, opts) {
         });
         if (auth.decision !== "proceed" && auth.decision !== "route" && auth.decision !== "block")
             throw new DecidioBlockedError(`unrecognized gate verdict: ${String(auth.decision)}`, auth.decisionId);
+        if (typeof auth.decisionId !== "string" || !auth.decisionId)
+            throw new DecidioBlockedError(`the gate answered "${auth.decision}" with no usable decisionId (${JSON.stringify(auth.decisionId ?? null)}) — refusing to execute. Every authorized action must be addressable: without an id it cannot be polled, resumed, confirmed or audited.`, auth.decisionId);
         if (auth.decision === "block")
             throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
         if (auth.decision === "route") {
@@ -163,7 +165,7 @@ export function withApproval(fn, describe, config, opts) {
                 config.resume.agentId ??= config.agentId;
                 config.resume.agentKey ??= config.agentKey;
                 config.resume.agentDid ??= config.agentDid;
-                config.resume.register(ctx.action, fn);
+                config.resume.register(ctx.action, fn, opts?.evidence);
                 await config.resume.park({
                     decisionId: auth.decisionId, receiptId: auth.receiptId,
                     action: ctx.action, amount: ctx.amount, scope: ctx.scope, args,
@@ -187,16 +189,26 @@ export function withApproval(fn, describe, config, opts) {
             }
         }
         const result = await fn(...args);
+        let reported = null;
+        let evidenceProblem;
         try {
-            const confirmIdentity = signConfirm(auth.decisionId, config);
             const evidenceOf = (opts?.evidence ?? ((r) => r));
-            const reported = canonicalize(evidenceOf(result) ?? null, "evidence(result)");
+            reported = canonicalize(evidenceOf(result) ?? null, "evidence(result)");
+        }
+        catch (e) {
+            evidenceProblem = String(e?.message ?? e);
+            console.warn(`[decidio] ${auth.decisionId}: the action SUCCEEDED but its result could not be reported as evidence (${evidenceProblem}). Reporting an empty captured response so the execution is still recorded — map the return value with the \`evidence\` option (e.g. evidence: (r) => ({ recordId: String(r.id), success: true })) to earn a confirming tier. The action was NOT re-run.`);
+        }
+        try {
+            const confirmIdentity = signConfirm(auth.decisionId, config);
             const confirmBody = await post(config, "/agent/confirm", buildConfirmBody(config, auth.decisionId, reported, confirmIdentity));
             const ev = readConfirmResponse(confirmBody, { signed: !!confirmIdentity, capturedResponse: reported });
             if (!ev.reportRecorded)
                 console.warn(`[decidio] ${auth.decisionId}: ${ev.diagnostic}`);
-            else if (!ev.executionConfirmed)
+            else if (!ev.executionConfirmed || ev.executionReportVerified === false)
                 console.warn(`[decidio] execution evidence for ${auth.decisionId} recorded as ${ev.evidenceTier} — ${ev.diagnostic}`);
+            if (evidenceProblem)
+                console.warn(`[decidio] ${auth.decisionId}: the execution IS recorded, but with an empty captured response — see the evidence note above.`);
         }
         catch (e) {
             console.warn(`[decidio] confirmation post failed (action succeeded): ${e.message}`);

package/dist/resume.d.ts

@@ -142,6 +142,9 @@ export interface ResumeOutcome {
     executionConfirmed?: boolean;
     /** executed only: the evidence tier Decidio recorded, verbatim. */
     evidenceTier?: EvidenceTier;
+    /** executed only, when the gate reported on the SIGNED execution report: whether the
+     *  attestation proof VERIFIED (C3, 0.1.12). */
+    executionReportVerified?: boolean;
     /** executed only: why the evidence landed where it did, when that is worth explaining. */
     diagnostic?: string;
 }
@@ -191,7 +194,7 @@ export interface ResumeController extends ResumeConfig {
     /** 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;
+    register(action: string, fn: (...args: any[]) => Promise<any>, evidence?: (result: any) => unknown): 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>;

package/dist/resume.js

@@ -3,7 +3,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync
 import { join } from "node:path";
 import { userInfo } from "node:os";
 import { execFileSync } from "node:child_process";
-import { signConfirm, canonicalize as jcs, assertSafeTransport } from "./signing.js";
+import { signConfirm, canonicalize as jcs, assertSafeTransport, carriesCredential } from "./signing.js";
 import { canonicalize as toCanonical, DecidioUnsafeArgumentsError } from "./canonical.js";
 import { readConfirmResponse, buildConfirmBody } from "./evidence.js";
 import { DecidioHttpError } from "./errors.js";
@@ -172,9 +172,9 @@ function buildResumeConfirmRequest(cfg, decisionId, canonicalResult) {
         console.warn(`[decidio] execution evidence for ${decisionId} will be recorded as an unproven agent assertion — no signing key configured. Set DECIDIO_AGENT_KEY/DID to earn a confirming tier.`);
     return buildConfirmBody({ agentId: cfg.agentId ?? "agent", agentKey: cfg.agentKey, agentDid: cfg.agentDid, workspaceId: cfg.workspaceId }, decisionId, canonicalResult, requesterIdentity);
 }
-async function postConfirm(cfg, decisionId, body) {
+async function postConfirm(cfg, decisionId, body, journalled = true) {
     const f = cfg.fetchImpl ?? fetch;
-    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
+    assertSafeTransport(cfg.apiUrl, carriesCredential(cfg));
     const r = await f(cfg.apiUrl.replace(/\/$/, "") + "/agent/confirm", {
         method: "POST",
         headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
@@ -190,11 +190,11 @@ async function postConfirm(cfg, decisionId, body) {
         throw new DecidioHttpError(r.status, "/agent/confirm", parsed);
     }
     const parsed = await r.json().catch(() => null);
-    return readConfirmResponse(parsed, { signed: !!body.requesterIdentity, capturedResponse: body.capturedResponse, journalled: true });
+    return readConfirmResponse(parsed, { signed: !!body.requesterIdentity, capturedResponse: body.capturedResponse, journalled });
 }
 async function statusOf(cfg, decisionId) {
     const f = cfg.fetchImpl ?? fetch;
-    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
+    assertSafeTransport(cfg.apiUrl, carriesCredential(cfg));
     const r = await f(cfg.apiUrl.replace(/\/$/, "") + "/agent/status/" + encodeURIComponent(decisionId), {
         headers: { ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
     });
@@ -210,13 +210,21 @@ class ReportJournal {
             mkdirSync(dir, { recursive: true });
             hardenDir(dir);
         }
-        catch { }
+        catch (e) {
+            console.error(`[decidio] could not create the execution-report journal directory ${dir} (${e?.message ?? e}) — reports will NOT be locally recoverable until this is fixed. Point it somewhere writable with reportDir (or DECIDIO_PENDING_DIR).`);
+        }
     }
     p(id) { return join(this.dir, `${id.replace(/[^\w.-]/g, "_")}.json`); }
-    write(e) { try {
-        writeFileSync(this.p(e.decisionId), JSON.stringify(e, null, 2), { mode: 0o600 });
+    write(e) {
+        try {
+            writeFileSync(this.p(e.decisionId), JSON.stringify(e, null, 2), { mode: 0o600 });
+            return true;
+        }
+        catch (err) {
+            console.error(`[decidio] ${e.decisionId}: the action RAN but its execution report could NOT be journalled to ${this.dir} (${err?.message ?? err}). If the report also fails to send, this execution is NOT locally recoverable — record the outcome from your own system. Fix the journal location with reportDir (or DECIDIO_PENDING_DIR).`);
+            return false;
+        }
     }
-    catch { } }
     read(id) { try {
         return existsSync(this.p(id)) ? JSON.parse(readFileSync(this.p(id), "utf8")) : null;
     }
@@ -256,8 +264,9 @@ export function createDecidioResume(opts) {
         let reported;
         let haveReported = false;
         let buildProblem;
+        const evidenceMapper = registry.get(pending.action)?.evidence ?? ctrl.evidence;
         try {
-            reported = toCanonical((ctrl.evidence ? ctrl.evidence(result) : result) ?? null, "evidence(result)");
+            reported = toCanonical((evidenceMapper ? evidenceMapper(result) : result) ?? null, "evidence(result)");
             haveReported = true;
         }
         catch (e) {
@@ -265,8 +274,7 @@ export function createDecidioResume(opts) {
             reported = null;
             haveReported = true;
         }
-        if (haveReported)
-            journal.write({ decisionId, action: pending.action, reported, at: new Date().toISOString() });
+        const journalled = haveReported && journal.write({ decisionId, action: pending.action, reported, at: new Date().toISOString() });
         let confirmRequest;
         try {
             confirmRequest = buildResumeConfirmRequest(ctrl, decisionId, reported);
@@ -274,19 +282,32 @@ export function createDecidioResume(opts) {
         catch {
             confirmRequest = undefined;
         }
+        const deletePending = async () => {
+            try {
+                await ctrl.store.delete(decisionId);
+            }
+            catch (e) {
+                console.error(`[decidio] ${decisionId}: the action RAN but its pending entry could NOT be deleted (${e?.message ?? e}) — the entry SURVIVED. Remove it from the pending store by hand before another process or a restart can see it, or the committed action may be executed again.`);
+            }
+        };
         if (!confirmRequest) {
-            await ctrl.store.delete(decisionId).catch(() => { });
+            await deletePending();
             const diagnostic = `"${pending.action}" EXECUTED, but no execution report could be built (${buildProblem ?? "unknown"}). Nothing will re-run it; record the outcome from your own system.`;
             console.warn(`[decidio] ${decisionId}: ${diagnostic}`);
             return { ...base, reportRecorded: false, executionConfirmed: false, diagnostic };
         }
-        await ctrl.store.delete(decisionId).catch(() => { });
+        await deletePending();
         let ev;
         try {
-            ev = await postConfirm(ctrl, decisionId, confirmRequest);
+            ev = await postConfirm(ctrl, decisionId, confirmRequest, journalled);
         }
         catch (e) {
-            ev = { reportRecorded: false, executionConfirmed: false, diagnostic: `the execution report did not reach Decidio (${e?.message ?? e}). Your action DID run and the report is journalled - re-send it with reconfirm("${decisionId}").` };
+            ev = {
+                reportRecorded: false, executionConfirmed: false,
+                diagnostic: journalled
+                    ? `the execution report did not reach Decidio (${e?.message ?? e}). Your action DID run and the report is journalled - re-send it with reconfirm("${decisionId}").`
+                    : `the execution report did not reach Decidio (${e?.message ?? e}) AND could not be journalled locally, so nothing here can re-send it. Your action DID run - record the outcome from your own system.`,
+            };
         }
         if (ev.reportRecorded)
             journal.clear(decisionId);
@@ -295,9 +316,9 @@ export function createDecidioResume(opts) {
             : ev.diagnostic;
         if (!ev.reportRecorded)
             console.warn(`[decidio] ${decisionId}: ${diagnostic}`);
-        else if (!ev.executionConfirmed)
+        else if (!ev.executionConfirmed || ev.executionReportVerified === false)
             console.warn(`[decidio] execution evidence for ${decisionId} recorded as ${ev.evidenceTier} - ${diagnostic}`);
-        return { ...base, reportRecorded: ev.reportRecorded, executionConfirmed: ev.executionConfirmed, ...(ev.evidenceTier ? { evidenceTier: ev.evidenceTier } : {}), ...(diagnostic ? { diagnostic } : {}) };
+        return { ...base, reportRecorded: ev.reportRecorded, executionConfirmed: ev.executionConfirmed, ...(ev.evidenceTier ? { evidenceTier: ev.evidenceTier } : {}), ...(ev.executionReportVerified !== undefined ? { executionReportVerified: ev.executionReportVerified } : {}), ...(diagnostic ? { diagnostic } : {}) };
     }
     const refusalWarned = new Set();
     const refuseOnce = (decisionId, msg) => {
@@ -314,11 +335,13 @@ export function createDecidioResume(opts) {
         workspaceId: opts.workspaceId ?? process.env.DECIDIO_WORKSPACE_ID,
         webhookSecret: secret,
         store: opts.store,
-        register(action, fn) {
+        register(action, fn, evidence) {
             const prev = registry.get(action);
-            if (prev && prev !== fn)
+            if (prev && prev.fn !== 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);
+            if (prev && prev.evidence && evidence && prev.evidence !== evidence)
+                console.warn(`[decidio] action "${action}" is being registered again with a DIFFERENT evidence mapper — the latest one wins, and a resumed decision's record would carry ITS output. Give each protected function its own action name.`);
+            registry.set(action, { fn, evidence: evidence ?? prev?.evidence });
         },
         async park(p) {
             try {
@@ -368,7 +391,7 @@ export function createDecidioResume(opts) {
             }
             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);
+            const fn = registry.get(pending.action)?.fn;
             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:`);
@@ -386,13 +409,11 @@ export function createDecidioResume(opts) {
                 return finish(await reportAfterExecution(pending, decisionId, result));
             }
             catch (e) {
+                inFlight.delete(decisionId);
                 if (ctrl.store.release)
                     await ctrl.store.release(decisionId).catch(() => { });
                 throw e;
             }
-            finally {
-                inFlight.delete(decisionId);
-            }
         },
         webhookHandler() {
             return (req, res) => {

package/dist/signing.d.ts

@@ -68,6 +68,14 @@ export declare function assertJsonSafe(value: unknown, path?: string): void;
  *  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;
+/** The ONE answer to "does this request carry a credential worth protecting?" (A6, 0.1.12).
+ *  A signed identity proof is a credential too: sending it over remote plaintext disclosed
+ *  request context and replay/front-run material even with no bearer configured. */
+export declare const carriesCredential: (c: {
+    apiToken?: string;
+    agentKey?: string;
+    agentDid?: string;
+}) => boolean;
 /** A signed, DOMAIN-SEPARATED, versioned attestation that THIS agent reported THIS captured
  *  response for THIS decision. Distinct from the identity proof (`signConfirm`) in every field
  *  that matters, so a report can never be lifted from one decision onto another: the decision id,

package/dist/signing.js

@@ -113,10 +113,26 @@ export function assertJsonSafe(value, path = "args") {
 export function assertSafeTransport(url, hasCredential) {
     if (!hasCredential)
         return;
-    if (/^http:\/\//i.test(url) && !/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])([:/]|$)/i.test(url)) {
-        throw new Error(`[decidio] refusing to send credentials over plaintext http to ${url.replace(/^(https?:\/\/[^/]+).*$/i, "$1")} — use https, or localhost for local dev. Nothing was sent.`);
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        const spelled = url.replace(/[\t\r\n]/g, "").replace(/^[\s\u0000-\u001f\u0085\ufeff]+/, "");
+        if (/^http:/i.test(spelled)) {
+            throw new Error(`[decidio] refusing to send credentials over plaintext http to ${JSON.stringify(url)} — that is not a complete absolute URL, so where the request would actually connect is undefined (the path is appended to it, which can turn it into a remote host). Set a full https URL, or http://localhost for local dev. Nothing was sent.`);
+        }
+        return;
     }
+    if (u.protocol !== "http:")
+        return;
+    const host = u.hostname.toLowerCase();
+    const local = host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "::1";
+    if (local && !u.username && !u.password)
+        return;
+    throw new Error(`[decidio] refusing to send credentials over plaintext http to ${u.origin} — use https, or localhost for local dev. Nothing was sent.`);
 }
+export const carriesCredential = (c) => !!c.apiToken || !!(c.agentKey && c.agentDid);
 export function signExecutionReport(privateKeyBase64, fields) {
     const key = createPrivateKey({ key: Buffer.from(privateKeyBase64, "base64"), format: "der", type: "pkcs8" });
     const nonce = fields.nonce ?? randomUUID();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "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",