@decidio/sdk 0.1.10 → 0.1.12

package/dist/resume.js

@@ -3,8 +3,11 @@ 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, 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");
+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";
+const argsBindingBytes = (p) => Buffer.from(jcs({ decisionId: p.decisionId, action: p.action, amount: p.amount, ...(p.scope !== undefined ? { scope: p.scope } : {}), args: p.args }), "utf8");
 function signArgs(p, agentKey, webhookSecret) {
     const bytes = argsBindingBytes(p);
     if (agentKey) {
@@ -49,24 +52,32 @@ export class MemoryPendingStore {
     async claim(id) { if (this.claimed.has(id) || !this.m.has(id))
         return false; this.claimed.add(id); return true; }
     async release(id) { this.claimed.delete(id); }
+    async listClaimed() { return [...this.claimed].map((id) => this.m.get(id)).filter(Boolean); }
+}
+export function hardenDir(dir) {
+    if (process.platform !== "win32")
+        return;
+    try {
+        const user = (() => { try {
+            return userInfo().username;
+        }
+        catch {
+            return process.env.USERNAME ?? process.env.USER ?? "";
+        } })();
+        if (!user)
+            throw new Error("could not determine the current user");
+        execFileSync("icacls", [dir, "/inheritance:r", "/grant:r", `${user}:(OI)(CI)F`], { stdio: "ignore" });
+    }
+    catch (e) {
+        console.warn(`[decidio] WARNING: could not restrict ${dir} to owner-only (${e?.message ?? e}). It keeps the directory's inherited permissions, so other accounts on this machine may be able to read parked action arguments. Move the pending store to a protected location, or set DECIDIO_PENDING_DIR to one.`);
+    }
 }
 export class FilePendingStore {
     dir;
     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 { }
-        }
+        hardenDir(dir);
     }
     key(id) { return id.replace(/[^\w.-]/g, "_"); }
     path(id) { return join(this.dir, `${this.key(id)}.json`); }
@@ -110,6 +121,20 @@ export class FilePendingStore {
         }
         catch { }
     }
+    async listClaimed() {
+        if (!existsSync(this.dir))
+            return [];
+        const out = [];
+        for (const name of readdirSync(this.dir)) {
+            if (!name.endsWith(".claimed"))
+                continue;
+            try {
+                out.push(JSON.parse(readFileSync(join(this.dir, name), "utf8")));
+            }
+            catch { }
+        }
+        return out;
+    }
 }
 export class DecidioSuspendedError extends Error {
     decisionId;
@@ -141,38 +166,160 @@ export function assertConfirmRecorded(body, decisionId, signed) {
     }
     return body.confirmation;
 }
-async function confirm(cfg, decisionId, capturedResponse) {
-    const f = cfg.fetchImpl ?? fetch;
-    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
+function buildResumeConfirmRequest(cfg, decisionId, canonicalResult) {
     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.`);
+        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, journalled = true) {
+    const f = cfg.fetchImpl ?? fetch;
+    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}` } : {}) },
-        body: JSON.stringify({ decisionId, capturedResponse: capturedResponse ?? null, source: "wrapper", ...(requesterIdentity ? { requesterIdentity } : {}) }),
+        body: JSON.stringify(body),
     });
-    if (!r.ok)
-        throw new Error(`confirm ${r.status}`);
-    const body = await r.json().catch(() => null);
-    return assertConfirmRecorded(body, decisionId, !!requesterIdentity);
+    if (!r.ok) {
+        const raw = await r.text().catch(() => "");
+        let parsed = raw;
+        try {
+            parsed = raw ? JSON.parse(raw) : undefined;
+        }
+        catch { }
+        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 });
 }
 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}` } : {}) },
     });
     if (!r.ok)
-        throw new Error(`status ${r.status}`);
+        throw new DecidioHttpError(r.status, `/agent/status/${decisionId}`);
     return r.json();
 }
+class ReportJournal {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+        try {
+            mkdirSync(dir, { recursive: true });
+            hardenDir(dir);
+        }
+        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 });
+            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;
+        }
+    }
+    read(id) { try {
+        return existsSync(this.p(id)) ? JSON.parse(readFileSync(this.p(id), "utf8")) : null;
+    }
+    catch {
+        return null;
+    } }
+    clear(id) { try {
+        if (existsSync(this.p(id)))
+            rmSync(this.p(id));
+    }
+    catch { } }
+    list() {
+        try {
+            if (!existsSync(this.dir))
+                return [];
+            return readdirSync(this.dir).filter((f) => f.endsWith(".json")).map((f) => { try {
+                return JSON.parse(readFileSync(join(this.dir, f), "utf8"));
+            }
+            catch {
+                return null;
+            } }).filter(Boolean);
+        }
+        catch {
+            return [];
+        }
+    }
+}
 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 journal = new ReportJournal(opts.reportDir ?? join(process.env.DECIDIO_PENDING_DIR ?? ".decidio-pending", "reports"));
+    async function reportAfterExecution(pending, decisionId, result) {
+        const base = { status: "executed", decisionId, action: pending.action, result };
+        let reported;
+        let haveReported = false;
+        let buildProblem;
+        const evidenceMapper = registry.get(pending.action)?.evidence ?? ctrl.evidence;
+        try {
+            reported = toCanonical((evidenceMapper ? evidenceMapper(result) : result) ?? null, "evidence(result)");
+            haveReported = true;
+        }
+        catch (e) {
+            buildProblem = `${e?.message ?? e}`;
+            reported = null;
+            haveReported = true;
+        }
+        const journalled = haveReported && journal.write({ decisionId, action: pending.action, reported, at: new Date().toISOString() });
+        let confirmRequest;
+        try {
+            confirmRequest = buildResumeConfirmRequest(ctrl, decisionId, reported);
+        }
+        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 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 deletePending();
+        let ev;
+        try {
+            ev = await postConfirm(ctrl, decisionId, confirmRequest, journalled);
+        }
+        catch (e) {
+            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);
+        const diagnostic = buildProblem
+            ? `${ev.diagnostic ? ev.diagnostic + " " : ""}Also: the action's return value was not reportable (${buildProblem}), so an empty response was reported - map it with the \`evidence\` option to earn a confirming tier.`
+            : ev.diagnostic;
+        if (!ev.reportRecorded)
+            console.warn(`[decidio] ${decisionId}: ${diagnostic}`);
+        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 } : {}), ...(ev.executionReportVerified !== undefined ? { executionReportVerified: ev.executionReportVerified } : {}), ...(diagnostic ? { diagnostic } : {}) };
+    }
     const refusalWarned = new Set();
     const refuseOnce = (decisionId, msg) => {
         if (refusalWarned.has(decisionId))
@@ -188,15 +335,17 @@ 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 {
-                assertJsonSafe(p.args, "args");
+                toCanonical(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);
@@ -242,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:`);
@@ -257,34 +406,14 @@ export function createDecidioResume(opts) {
                 return { status: "unknown", decisionId };
             try {
                 const result = await fn(...pending.args);
-                let confirmed = true;
-                let tier;
-                try {
-                    tier = await confirm(ctrl, decisionId, result);
-                }
-                catch (e) {
-                    confirmed = false;
-                    console.warn(`[decidio] resume confirm failed (your action DID succeed): ${e.message}`);
-                }
-                const retainedIsSafe = typeof ctrl.store.claim === "function";
-                if (confirmed || !retainedIsSafe)
-                    await ctrl.store.delete(decisionId);
-                if (!confirmed) {
-                    if (retainedIsSafe)
-                        console.warn(`  The parked entry for ${decisionId} is kept as local evidence that it executed — it stays CLAIMED, so it cannot re-run. Retry the confirmation, then delete it.`);
-                    else
-                        console.warn(`  This store provides no claim() primitive, so the entry was DELETED to guarantee the action cannot execute twice. ${decisionId} executed, but its confirmation never reached Decidio — re-confirm it from your own records.`);
-                }
-                return finish({ status: "executed", decisionId, action: pending.action, result, confirmed, ...(tier ? { evidenceTier: tier } : {}) });
+                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) => {
@@ -342,6 +471,48 @@ export function createDecidioResume(opts) {
                 }
             };
         },
+        async reconfirm(decisionId) {
+            const entry = journal.read(decisionId);
+            if (!entry) {
+                return {
+                    reportRecorded: false, executionConfirmed: false,
+                    diagnostic: `nothing is journalled for ${decisionId}: either its report was already recorded (nothing to do) or this process never executed it. Check the record in Decidio — do NOT re-run the action to find out.`,
+                };
+            }
+            let request;
+            try {
+                request = buildResumeConfirmRequest(ctrl, decisionId, entry.reported);
+            }
+            catch (e) {
+                return { reportRecorded: false, executionConfirmed: false, diagnostic: `the journalled report for ${decisionId} could not be re-signed (${e?.message ?? e}). The entry is kept; fix the agent's signing config (DECIDIO_AGENT_KEY/DID) and retry.` };
+            }
+            const ev = await postConfirm(ctrl, decisionId, request);
+            if (ev.reportRecorded)
+                journal.clear(decisionId);
+            return ev;
+        },
+        async recover() {
+            const items = [];
+            for (const e of journal.list()) {
+                items.push({
+                    decisionId: e.decisionId, action: e.action, state: "executed_unreported",
+                    guidance: `"${e.action}" executed at ${e.at} and its execution report has not been recorded. Re-send it safely: guard.resume.reconfirm("${e.decisionId}") — this replays the saved report and cannot re-run the action.`,
+                });
+            }
+            const claimed = ctrl.store.listClaimed ? await ctrl.store.listClaimed().catch(() => []) : [];
+            for (const p of claimed) {
+                if (journal.read(p.decisionId))
+                    continue;
+                items.push({
+                    decisionId: p.decisionId, action: p.action, state: "indeterminate",
+                    guidance: `"${p.action}" was CLAIMED for execution but no result was ever recorded: a process died mid-flight, so it is unknown locally whether the action ran. Reconcile in the downstream system (or with an idempotency key) before deciding. The SDK will NOT retry it automatically, and neither should a script.`,
+                });
+            }
+            for (const p of await ctrl.store.list().catch(() => [])) {
+                items.push({ decisionId: p.decisionId, action: p.action, state: "parked", guidance: `"${p.action}" is parked awaiting a human decision. Nothing has executed.` });
+            }
+            return items;
+        },
         worker(workerOpts) {
             const interval = workerOpts?.intervalMs ?? 2_500;
             const deadline = workerOpts?.timeoutMs ? Date.now() + workerOpts.timeoutMs : Infinity;
@@ -364,10 +535,10 @@ 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"}.`);
+                            if (outcome.status === "executed" && outcome.reportRecorded)
+                                console.error(`[decidio] resumed ${p.decisionId}: approved → "${p.action}" executed; evidence recorded as ${outcome.evidenceTier}${outcome.executionConfirmed ? "" : " (execution NOT confirmed — see the warning above)"}.`);
                             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.`);
+                                console.error(`[decidio] resumed ${p.decisionId}: approved → "${p.action}" executed, but its execution report did NOT reach Decidio — recover with: guard.resume.reconfirm("${p.decisionId}")`);
                             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")

package/dist/signing.d.ts

@@ -3,6 +3,10 @@ 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). */
+/** Derive the public did:key from a stored private key. Lets `doctor` prove that the key on
+ *  this machine is actually the one registered for this agent — a mismatched restore otherwise
+ *  looks healthy until a signed confirmation quietly fails to earn its tier weeks later. */
+export declare function didFromPrivateKey(privateKeyBase64: string): string;
 export declare function generateKeypair(): {
     did: string;
     privateKeyBase64: string;
@@ -64,3 +68,63 @@ 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,
+ *  the workspace, the agent's did, the source, the response digest, the digest algorithm, the
+ *  canonicalization version, a nonce and an expiry are ALL inside the signed bytes.
+ *
+ *  HONEST SCOPE — say this out loud rather than let a reader assume more: this proves integrity
+ *  and agent attribution of the REPORT. It does not prove the downstream system committed
+ *  anything; only the source system can attest that, and the gate's evidence tier is what
+ *  records how strong that attestation is. */
+export interface ExecutionReport {
+    v: 1;
+    purpose: "decidio.execution-report";
+    decisionId: string;
+    agentId: string;
+    did: string;
+    workspaceId?: string;
+    source: string;
+    resultDigest: string;
+    digestAlg: "sha-256";
+    canonicalization: "decidio-jcs-1";
+    nonce: string;
+    exp: number;
+    proof: {
+        protected: string;
+        signature: string;
+    };
+}
+export declare function signExecutionReport(privateKeyBase64: string, fields: {
+    decisionId: string;
+    agentId: string;
+    did: string;
+    workspaceId?: string;
+    source: string;
+    resultDigest: string;
+    ttlMs?: number;
+    now?: number;
+    nonce?: string;
+}): ExecutionReport;
+/** Verify an ExecutionReport LOCALLY — same rules the server applies before persisting it.
+ *  Returns why it failed rather than a bare false, so a caller can say something useful. */
+export declare function verifyExecutionReport(report: unknown, expect: {
+    decisionId: string;
+    did?: string;
+    now?: number;
+}): {
+    valid: boolean;
+    reason?: string;
+};
+/** sha-256 over the canonical JSON of an already-canonical value — the digest an ExecutionReport
+ *  binds. Both languages produce identical bytes for identical values. */
+export declare function resultDigest(canonicalValue: unknown): string;

package/dist/signing.js

@@ -1,4 +1,4 @@
-import { generateKeyPairSync, createPrivateKey, sign as edSign, randomUUID } from "node:crypto";
+import { generateKeyPairSync, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify, createHash, randomUUID } from "node:crypto";
 const B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
 function b58encode(buf) {
     const digits = [0];
@@ -33,6 +33,11 @@ export function canonicalize(v) {
     const o = v;
     return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${canonicalize(o[k])}`).join(",")}}`;
 }
+export function didFromPrivateKey(privateKeyBase64) {
+    const priv = createPrivateKey({ key: Buffer.from(privateKeyBase64, "base64"), format: "der", type: "pkcs8" });
+    const jwk = createPublicKey(priv).export({ format: "jwk" });
+    return "did:key:z" + b58encode(Buffer.concat([Buffer.from([0xed, 0x01]), Buffer.from(jwk.x, "base64url")]));
+}
 export function generateKeypair() {
     const { privateKey, publicKey } = generateKeyPairSync("ed25519");
     const jwk = publicKey.export({ format: "jwk" });
@@ -108,7 +113,101 @@ 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();
+    const exp = (fields.now ?? Date.now()) + (fields.ttlMs ?? 300_000);
+    const body = {
+        v: 1,
+        purpose: "decidio.execution-report",
+        decisionId: fields.decisionId,
+        agentId: fields.agentId,
+        did: fields.did,
+        ...(fields.workspaceId !== undefined ? { workspaceId: fields.workspaceId } : {}),
+        source: fields.source,
+        resultDigest: fields.resultDigest,
+        digestAlg: "sha-256",
+        canonicalization: "decidio-jcs-1",
+        nonce,
+        exp,
+    };
+    const payload = Buffer.from(canonicalize(body), "utf8").toString("base64url");
+    const protectedHdr = Buffer.from(JSON.stringify({ alg: "EdDSA", kid: fields.did, typ: "decidio-execution-report+jws" }), "utf8").toString("base64url");
+    const signature = Buffer.from(edSign(null, Buffer.from(`${protectedHdr}.${payload}`, "utf8"), key)).toString("base64url");
+    return { ...body, proof: { protected: protectedHdr, signature } };
+}
+export function verifyExecutionReport(report, expect) {
+    const r = report;
+    if (!r || r.purpose !== "decidio.execution-report" || r.v !== 1)
+        return { valid: false, reason: "not a v1 decidio execution report" };
+    if (r.decisionId !== expect.decisionId)
+        return { valid: false, reason: "report is bound to a DIFFERENT decision" };
+    if (expect.did && r.did !== expect.did)
+        return { valid: false, reason: "report was signed by a different agent key" };
+    if (typeof r.exp !== "number" || (expect.now ?? Date.now()) > r.exp)
+        return { valid: false, reason: "report expired" };
+    if (r.digestAlg !== "sha-256" || r.canonicalization !== "decidio-jcs-1")
+        return { valid: false, reason: "unsupported digest/canonicalization" };
+    try {
+        const { proof, ...body } = r;
+        const payload = Buffer.from(canonicalize(body), "utf8").toString("base64url");
+        const mc = b58decode(String(r.did).slice("did:key:z".length));
+        if (mc[0] !== 0xed || mc[1] !== 0x01)
+            return { valid: false, reason: "issuer did is not Ed25519" };
+        const pub = createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: Buffer.from(mc.subarray(2)).toString("base64url") }, format: "jwk" });
+        const ok = edVerify(null, Buffer.from(`${proof.protected}.${payload}`, "utf8"), pub, Buffer.from(proof.signature, "base64url"));
+        return ok ? { valid: true } : { valid: false, reason: "signature does not verify against the agent did" };
+    }
+    catch (e) {
+        return { valid: false, reason: `malformed report (${e?.message ?? e})` };
+    }
+}
+export function resultDigest(canonicalValue) {
+    return createHash("sha256").update(canonicalize(canonicalValue), "utf8").digest("hex");
+}
+function b58decode(s) {
+    const A = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    const bytes = [0];
+    for (const ch of s) {
+        const val = A.indexOf(ch);
+        if (val < 0)
+            throw new Error("bad base58 character");
+        let carry = val;
+        for (let i = 0; i < bytes.length; i++) {
+            carry += bytes[i] * 58;
+            bytes[i] = carry & 0xff;
+            carry >>= 8;
+        }
+        while (carry) {
+            bytes.push(carry & 0xff);
+            carry >>= 8;
+        }
+    }
+    for (const ch of s) {
+        if (ch === A[0])
+            bytes.push(0);
+        else
+            break;
     }
+    return Buffer.from(bytes.reverse());
 }

package/openapi.yaml

@@ -5,7 +5,7 @@
 openapi: 3.1.0
 info:
   title: Decidio Agent Gate
-  version: 0.1.10
+  version: 0.1.11
   description: >
     Authorize an AI-agent action (proceed | route | block), confirm the captured outcome, and
     receive the signed resume webhook when a routed action is decided. Every outcome seals a
@@ -101,6 +101,52 @@ components:
         requesterIdentity:
           $ref: "#/components/schemas/RequesterIdentity"
           description: confirm proof is bound to {action:"confirm", scope:decisionId}
+        executionReport:
+          $ref: "#/components/schemas/ExecutionReport"
+    ExecutionReport:
+      type: object
+      description: >
+        OPTIONAL proof of WHAT was executed: a domain-separated, versioned envelope over a digest
+        of the captured response, bound to the decision, the agent and the workspace. The server
+        VERIFIES it before persisting anything — it recomputes the digest from `capturedResponse`
+        on this same request, requires the signer to be the decision's original requesting agent
+        AND still registered and active, and burns the nonce so a report is single-use. A report
+        copied onto a different decision, a different agent, or an altered response is refused.
+
+        A REFUSED REPORT DOES NOT FAIL THE CONFIRM. This envelope grants no authority — the
+        evidence tier comes from the response, the identity from the confirm proof — so an
+        unverifiable attestation is refused as an ATTESTATION (never stored as evidence, and the
+        refusal is itself audited) while the confirmation is still recorded. The response reports
+        which happened via `executionReport.verified`; it is never silent. Omit the field entirely
+        and confirm behaves exactly as before.
+      required: [v, purpose, decisionId, agentId, did, source, resultDigest, digestAlg, canonicalization, nonce, exp, proof]
+      properties:
+        v: { type: integer, enum: [1] }
+        purpose: { type: string, enum: ["decidio.execution-report"], description: domain separation — this signature can never be replayed as another Decidio proof }
+        decisionId: { type: string }
+        agentId: { type: string }
+        did: { type: string, description: "did:key of the signing agent" }
+        workspaceId: { type: string, description: tenant binding; present when the agent knows it }
+        source: { type: string, enum: [wrapper, agent] }
+        resultDigest:
+          type: string
+          pattern: "^[0-9a-f]{64}$"
+          description: lowercase-hex SHA-256 over the canonicalized captured response (the server recomputes it and compares)
+        digestAlg: { type: string, enum: ["sha-256"] }
+        canonicalization: { type: string, enum: ["decidio-jcs-1"], description: RFC 8785 JCS with Decidio's refusal rules }
+        nonce:
+          type: string
+          pattern: "^[A-Za-z0-9._:-]{8,64}$"
+          description: single-use; burned server-side, so a replayed report is refused
+        exp:
+          type: integer
+          description: unix ms expiry. The server also refuses an expiry more than 15 minutes ahead of now — a client-chosen lifetime is not freshness.
+        proof:
+          type: object
+          required: [protected, signature]
+          properties:
+            protected: { type: string, description: "base64url JWS protected header (EdDSA, kid=did, typ=decidio-execution-report+jws)" }
+            signature: { type: string, description: base64url detached signature over protected.payload }
     ResumeWebhook:
       type: object
       description: >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.1.10",
+  "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",
@@ -81,7 +81,7 @@
     "prepublishOnly": "npm run typecheck && npm run build"
   },
   "dependencies": {
-    "@decidio/verify": "0.1.9"
+    "@decidio/verify": "0.1.10"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {