@decidio/sdk 0.6.3 → 0.7.0

package/dist/cli.js

@@ -4,6 +4,7 @@ import { randomBytes } from "node:crypto";
 import { homedir, tmpdir } from "node:os";
 import { join as joinPath, resolve as resolvePath, sep as pathSep, basename } from "node:path";
 import { createServer } from "node:http";
+import { isIP } from "node:net";
 import { execFileSync, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
 import { pathToFileURL as toFileUrl, fileURLToPath as fromFileUrl } from "node:url";
@@ -12,7 +13,7 @@ import { createRequire } from "node:module";
 import { generateKeypair, assertSafeTransport, redactUrl } from "./signing.js";
 import { hardenFile } from "./resume.js";
 import { withApproval, DecidioRateLimitError, DecidioRejectedError, DecidioTimeoutError, didFromPrivateKey } from "./index.js";
-import { verifyReceipt, runVerify, pinRequiredMessage } from "@decidio/verify";
+import { verifyReceipt, runVerify, pinRequiredMessage, builtInAnchor, KNOWN_ISSUERS } from "@decidio/verify";
 import { startDemoGate } from "./demo-gate.js";
 const VERSION = (() => {
     try {
@@ -63,16 +64,19 @@ if (!OFFLINE_CMD)
             console.error("⚠ ignoring DECIDIO_SESSION_TOKEN found in .env — session tokens belong in your shell or CI secret store, never on disk. Remove that line; export it in the shell instead.");
             continue;
         }
+        if (!k.startsWith("DECIDIO_"))
+            continue;
         if (process.env[k] === undefined)
             process.env[k] = v;
     }
-let API = (process.env.DECIDIO_API_URL ?? "https://decidio-api.onrender.com").replace(/\/$/, "");
+const DEFAULT_API = "https://decidio-api.onrender.com";
+let API = (process.env.DECIDIO_API_URL ?? DEFAULT_API).replace(/\/$/, "");
 let DEMO = false;
 function enterDemo(url) { API = url; process.env.DECIDIO_API_URL = url; DEMO = true; }
 const pinWords = () => (DEMO ? "PINNED to this demo's own key" : "PINNED to your workspace issuer");
 const issuerNote = () => (DEMO
     ? "· a key this demo generated for this run — real tours pin the host's published DID at https://decidio-api.onrender.com/api/did"
-    : `· your trust anchor — first seen over this signed-in connection; cross-check ${API}/api/did, then verify --issuer <did> <receipt.json>`);
+    : `· your trust anchor — named by this server over the signed-in connection, never read from the receipt; cross-check ${API}/api/did`);
 const TOKEN = () => process.env.DECIDIO_API_TOKEN;
 const ENV_PATH = ".env";
 const log = (...a) => console.log(...a);
@@ -509,14 +513,15 @@ if (process.env.DECIDIO_DEBUG_INPUT && process.stdin.isTTY) {
 }
 function terminalId() {
     for (const k of ["WT_SESSION", "VSCODE_IPC_HOOK_CLI", "TERM_SESSION_ID", "ITERM_SESSION_ID", "TMUX_PANE", "KONSOLE_DBUS_SESSION", "GNOME_TERMINAL_SCREEN", "WINDOWID"]) {
-        const v = process.env[k];
+        const v = SHELL_ENV[k];
         if (v)
             return `${k}=${v}`;
     }
     return "";
 }
 function sessionDir() {
-    const base = process.platform === "win32" ? (process.env.LOCALAPPDATA ?? joinPath(homedir(), "AppData", "Local")) : (process.env.XDG_CONFIG_HOME ?? joinPath(homedir(), ".config"));
+    const home = process.platform === "win32" ? (SHELL_ENV.USERPROFILE ?? homedir()) : (SHELL_ENV.HOME ?? homedir());
+    const base = process.platform === "win32" ? (SHELL_ENV.LOCALAPPDATA ?? joinPath(home, "AppData", "Local")) : (SHELL_ENV.XDG_CONFIG_HOME ?? joinPath(home, ".config"));
     return joinPath(base, "decidio");
 }
 const sessionFile = () => joinPath(sessionDir(), "session.json");
@@ -572,6 +577,140 @@ function endSession() {
         return false;
     }
 }
+const issuersFile = () => joinPath(sessionDir(), "issuers.json");
+const DID_KEY_SHAPE = /^did:key:z[1-9A-HJ-NP-Za-km-z]{40,60}$/;
+const STORE_HOST_LABELS = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
+export function issuerStoreKey(url) {
+    const raw = url.trim();
+    const low = raw.replace(/\/+$/, "").toLowerCase();
+    const m = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^/?#]*)(?:[/?#]|$)/.exec(raw);
+    if (!m)
+        return low;
+    const scheme = m[1].toLowerCase();
+    if (scheme !== "http" && scheme !== "https")
+        return low;
+    let authority = m[2];
+    const at = authority.lastIndexOf("@");
+    if (at >= 0)
+        authority = authority.slice(at + 1);
+    let host, portStr = "";
+    if (authority.startsWith("[")) {
+        const rb = authority.indexOf("]");
+        if (rb < 0)
+            return low;
+        const inner = authority.slice(1, rb).toLowerCase();
+        const rest = authority.slice(rb + 1);
+        if (isIP(inner) !== 6)
+            return low;
+        if (rest !== "") {
+            if (!/^:\d+$/.test(rest))
+                return low;
+            portStr = rest.slice(1);
+        }
+        host = `[${inner}]`;
+    }
+    else {
+        const c = authority.lastIndexOf(":");
+        if (c >= 0) {
+            const p = authority.slice(c + 1);
+            if (!/^\d+$/.test(p))
+                return low;
+            portStr = p;
+            host = authority.slice(0, c).toLowerCase();
+        }
+        else
+            host = authority.toLowerCase();
+        if (!STORE_HOST_LABELS.test(host))
+            return low;
+    }
+    const port = portStr === "" ? null : Number(portStr);
+    const dflt = scheme === "https" ? 443 : 80;
+    return port !== null && port !== dflt ? `${scheme}://${host}:${port}` : `${scheme}://${host}`;
+}
+function readIssuerStore() {
+    const f = issuersFile();
+    if (!existsSync(f))
+        return {};
+    const rawText = readFileSync(f, "utf8");
+    const s = JSON.parse(rawText);
+    const vLiteral = /"v"\s*:\s*(-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)/.exec(rawText)?.[1] ?? null;
+    const hosts = s?.v === 1 && vLiteral === "1" && s.hosts && typeof s.hosts === "object" && !Array.isArray(s.hosts) ? s.hosts : null;
+    if (!hosts)
+        throw new Error("not a v1 issuer store");
+    const out = {};
+    for (const [h, e] of Object.entries(hosts)) {
+        if (typeof e?.did !== "string" || !DID_KEY_SHAPE.test(e.did) || typeof e?.firstSeen !== "string")
+            throw new Error(`malformed entry for ${h}`);
+        const k = issuerStoreKey(h);
+        if (out[k] && out[k].did !== e.did)
+            throw new Error(`two entries for ${k} name different DIDs`);
+        out[k] ??= { did: e.did, firstSeen: e.firstSeen };
+    }
+    return out;
+}
+function rememberedIssuer(host = API) { return readIssuerStore()[issuerStoreKey(host)] ?? null; }
+const verifyHost = () => (SHELL_ENV.DECIDIO_API_URL ?? DEFAULT_API).replace(/\/$/, "");
+function warnIssuerChanged(known, seen, via) {
+    const key = issuerStoreKey(API);
+    err(`⚠ THE ISSUER DID OF ${key} HAS CHANGED — it was NOT adopted.`);
+    err(`    remembered (first seen ${known.firstSeen.slice(0, 10)}):  ${known.did}`);
+    err(`    ${via} now says:  ${seen}`);
+    err(`  Receipts from this host are still verified against the REMEMBERED DID. A new DID means a new signing key: a planned`);
+    err(`  rotation, another deployment behind the same address, or someone answering in its place. Confirm it with the host's`);
+    err(`  operator out of band before trusting it; to adopt it, remove the "${key}" entry from ${issuersFile()} and sign in again.`);
+}
+async function rememberHostIssuer() {
+    if (DEMO)
+        return;
+    let store;
+    try {
+        store = readIssuerStore();
+    }
+    catch (e) {
+        err(`⚠ the issuer DIDs this computer remembers (${issuersFile()}) could not be read (${e?.message ?? e}) — left as found, nothing new remembered. Repair the file or move it aside.`);
+        return;
+    }
+    const r = await api("/api/did", {}, "", true);
+    const did = typeof r.body?.did === "string" && DID_KEY_SHAPE.test(r.body.did) ? r.body.did : null;
+    if (!did) {
+        log(dim(`  (${API}/api/did did not answer with a DID (${r.status || "no response"}), so this host's issuer is not remembered yet — verify needs --issuer for its receipts until a later sign-in remembers it)`));
+        return;
+    }
+    const key = issuerStoreKey(API);
+    const known = store[key];
+    if (known?.did === did)
+        return;
+    if (known) {
+        warnIssuerChanged(known, did, `${API}/api/did`);
+        return;
+    }
+    store[key] = { did, firstSeen: new Date().toISOString() };
+    try {
+        mkdirSync(sessionDir(), { recursive: true });
+        writeSecretFile(issuersFile(), JSON.stringify({ v: 1, hosts: store }, null, 2) + "\n");
+    }
+    catch (e) {
+        err(`⚠ could not remember this host's issuer DID (${issuersFile()}: ${e?.message ?? e}) — verify will need --issuer for its receipts.`);
+        return;
+    }
+    log(`  ✔ remembered this host's issuer DID (from ${API}/api/did) — verify pins its receipts to it, no --issuer needed: ${did}`);
+}
+function hostAnchor(body) {
+    const named = typeof body?.expectedIssuer === "string" && DID_KEY_SHAPE.test(body.expectedIssuer) ? body.expectedIssuer : null;
+    if (DEMO)
+        return named;
+    let mem;
+    try {
+        mem = rememberedIssuer();
+    }
+    catch (e) {
+        err(`⚠ the issuer DIDs this computer remembers (${issuersFile()}) could not be read (${e?.message ?? e}) — no trust anchor until it is repaired or moved aside.`);
+        return null;
+    }
+    if (mem && named && mem.did !== named)
+        warnIssuerChanged(mem, named, "this server's verify response");
+    return mem?.did ?? named;
+}
 async function loginFlow(purpose, emailArg) {
     log(purpose === "Signing in" ? `Sign in once — kept on this computer for 30 days, or until this terminal closes, logout, or cleanup.` : `${purpose} needs your Decidio workspace sign-in — once: kept on this computer for 30 days, or until this terminal closes, logout, or cleanup.`);
     const email = emailArg ?? await ask("  email: ");
@@ -585,6 +724,7 @@ async function loginFlow(purpose, emailArg) {
         if (r.status >= 200 && r.status < 300 && r.body?.token) {
             const s = saveSession(String(r.body.token), email);
             log(`  ✔ signed in as ${email} until ${s.expiresAt.slice(0, 10)}${s.terminal ? "" : dim(" (no terminal id here: the sign-in ends on logout or cleanup, not on close)")}`);
+            await rememberHostIssuer();
             return s.token;
         }
         log(`  ✘ password sign-in failed (${r.status})${r.body?.error ? ` — ${r.body.error}` : ""}. No problem — the emailed link works for every account:`);
@@ -610,6 +750,7 @@ async function loginFlow(purpose, emailArg) {
         if (r.status >= 200 && r.status < 300 && r.body?.token) {
             const s = saveSession(String(r.body.token), email);
             log(`  ✔ signed in as ${email} until ${s.expiresAt.slice(0, 10)}${s.terminal ? "" : dim(" (no terminal id here: the sign-in ends on logout or cleanup, not on close)")}`);
+            await rememberHostIssuer();
             return s.token;
         }
         if (isLink) {
@@ -897,6 +1038,7 @@ async function cmdInit(agentId, opts = {}) {
     log(`✔ wrote ${ENV_PATH} (owner-only where the OS supports it) — every decidio command reads it from this directory (your script loads it with node --env-file=.env)`);
     if (privateKey)
         log(`  (the agent's private signing key is in there — for production, move it to your secret manager)`);
+    await rememberHostIssuer();
     log("");
     log("Next: protect one function and watch it route. Two steps:");
     log("");
@@ -1151,19 +1293,42 @@ async function cmdReceipt(id, jsonMode = false) {
     }
     const name = receiptFileName(id);
     const nextBytes = JSON.stringify(r.body.credential, null, 2) + "\n";
-    const wrote = writeReceiptFile(name, nextBytes, jsonMode ? err : log);
+    const issuer = hostAnchor(r.body);
+    const local = issuer ? verifyReceipt(r.body.credential, issuer) : null;
+    const serverInvalid = r.body?.valid === false;
+    const localInvalid = !!local && !local.valid;
+    const bad = serverInvalid || localInvalid;
+    const say = jsonMode ? err : log;
+    const wrote = writeReceiptFile(name, nextBytes, say);
     if (wrote === "conflict")
         return 1;
     if (wrote === "written")
-        (jsonMode ? err : log)(`✔ wrote ${name} (downloaded from your workspace — the download is online; VERIFYING it is offline)`);
+        say(bad ? `• wrote ${name} — kept for inspection only: it does NOT verify (below)` : `✔ wrote ${name} (downloaded from your workspace — the download is online; VERIFYING it is offline)`);
     const detail = await api(`/api/records/${encodeURIComponent(id)}`, {}, bearer);
     const conf = detail.body?.record?.confirmation;
-    const issuer = r.body?.issuer;
     const resolved = r.body?.resolved;
+    const badSaid = () => {
+        if (serverInvalid) {
+            err(`✘ the server's own check says this record does NOT verify: ${r.body?.reason ?? "no reason given"}`);
+            err(`  (signature ${r.body?.signatureValid === false ? "INVALID" : "valid"} · content bound ${r.body?.contentBound === false ? "NO" : "yes"} · matches the stored record ${r.body?.matchesRecord === false ? "NO" : "yes"} · stored payload ${r.body?.payloadMatches === false ? "ALTERED" : "intact"})`);
+        }
+        if (localInvalid)
+            err(`✘ this receipt does NOT verify against this Decidio's issuer DID (${issuer}): ${local.reason ?? "no reason given"}`);
+        err(`  Do not rely on ${name}. Report it to the operator of ${API} — a sealed record is immutable, so this is tampering, a defect, or an unannounced key change (see any warning above), never a normal state.`);
+    };
     if (jsonMode) {
-        log(JSON.stringify({ file: name, decisionId: id, evidenceTier: conf?.status ?? null, confirmed: !!conf?.confirmed, issuer: issuer ?? null, ...(resolved ? { resolved } : {}) }, null, 2));
+        const valid = bad ? false : local?.valid === true ? true : null;
+        log(JSON.stringify({ file: name, decisionId: id, evidenceTier: conf?.status ?? null, confirmed: !!conf?.confirmed, issuer: issuer ?? null, valid, ...(bad ? { reason: serverInvalid ? r.body?.reason ?? null : local?.reason ?? null } : {}), ...(resolved ? { resolved } : {}) }, null, 2));
+        if (bad) {
+            badSaid();
+            return 1;
+        }
         return 0;
     }
+    if (bad) {
+        badSaid();
+        return 1;
+    }
     if (conf?.status)
         log(`  Sealed credential: the authority decision (its confirmation field reads "pending" forever — immutable). Current record evidence tier: ${conf.status}${conf.confirmed ? " (confirmed)" : ""}.`);
     if (resolved && Object.keys(resolved).length && !process.stdout.isTTY) {
@@ -1176,19 +1341,37 @@ async function cmdReceipt(id, jsonMode = false) {
     }
     log(`  Verify it offline — no Decidio account or network needed (the verifier is built in):`);
     if (issuer) {
-        log(`  Record your workspace's issuer DID — copy this line, and pin it forever:`);
+        const vHost = verifyHost();
+        let plain = false, via = "";
+        try {
+            const mem = rememberedIssuer(vHost);
+            const claimed = String(r.body.credential?.issuer ?? "");
+            plain = (mem ? mem.did : KNOWN_ISSUERS.find((k) => k.did === claimed)?.did) === issuer;
+            via = mem ? "remembered on this computer" : "built into the verifier";
+        }
+        catch {
+            plain = false;
+        }
+        if (plain) {
+            log(`    npx @decidio/sdk verify ${name}`);
+            log(`  No --issuer needed here: it pins to this Decidio's issuer (${via}), which the server also named:`);
+        }
+        else {
+            log(`  Record your workspace's issuer DID — copy this line, and pin it forever:`);
+        }
         log(``);
         log(`${issuer}`);
         log(``);
         log(`  Cross-check it out of band — the same DID is published by this Decidio host at ${API}/api/did (public, no sign-in).`);
-        log(`  Then verify, pinned to it (the same DID, inline — copy from the line above, not this one,`);
-        log(`  which your terminal may wrap):`);
+        log(plain ? `  Anywhere else, pin it explicitly (copy the DID from the line above — this one may wrap):` : `  Then verify, pinned to it (the same DID, inline — copy from the line above, not this one, which your terminal may wrap):`);
         log(`    npx @decidio/sdk verify --issuer ${issuer} ${name}`);
-        log(`  The verifier refuses to run without --issuer: a pin is what makes VALID mean "issued by your`);
-        log(`  workspace"; --allow-unpinned runs a structural check only, and says so.`);
+        if (!plain && issuerStoreKey(vHost) !== issuerStoreKey(API))
+            log(`  (verify reads no .env, so a flagless run pins to the DID for ${vHost}, not ${API} - export DECIDIO_API_URL=${API} in your shell to verify this host's receipts without --issuer.)`);
+        else if (!plain)
+            log(`  Or sign in once (npx @decidio/sdk login): this computer then remembers the DID, and verify needs no --issuer.`);
     }
     else {
-        log(`  To also prove WHO issued it, pin your workspace's issuer DID (shown in your app's record verify panel):`);
+        log(`  To also prove WHO issued it, pin your Decidio's issuer DID — published at ${API}/api/did (public, no sign-in), never read off the receipt:`);
         log(`    npx @decidio/sdk verify --issuer <did:key:...> ${name}`);
     }
     return 0;
@@ -1237,7 +1420,7 @@ function cmdVerify(argsIn) {
         }
     }
     if (!files.length) {
-        err("usage: npx @decidio/sdk verify --issuer <did:key> <receipt.json> [more.json ...]   (or --allow-unpinned)");
+        err("usage: npx @decidio/sdk verify [--issuer <did:key>] <receipt.json> [more.json ...]   (or --allow-unpinned)");
         err("  Verifies Authority Receipts OFFLINE — signature, content binding, and (for several files) chain order.");
         return 2;
     }
@@ -1245,10 +1428,6 @@ function cmdVerify(argsIn) {
         err("✘ --allow-unpinned and --issuer together — an unpinned check and a pinned one are different questions; ask one.");
         return 2;
     }
-    if (expectedIssuer === undefined && !allowUnpinned) {
-        err(pinRequiredMessage("npx @decidio/sdk verify"));
-        return 2;
-    }
     const texts = new Map();
     for (const f of files) {
         try {
@@ -1259,7 +1438,34 @@ function cmdVerify(argsIn) {
             return 1;
         }
     }
-    const { ok, lines } = runVerify(files, expectedIssuer, (f) => texts.get(f));
+    const read = (f) => texts.get(f);
+    let anchor = expectedIssuer !== undefined ? "--issuer" : undefined;
+    if (expectedIssuer === undefined && !allowUnpinned) {
+        let mem;
+        try {
+            mem = rememberedIssuer(verifyHost());
+        }
+        catch (e) {
+            err(`✘ the issuer DIDs this computer remembers (${issuersFile()}) could not be read (${e?.message ?? e}) — refusing to fall back to another trust anchor.`);
+            err(`  Pass --issuer <did:key> for this run, or repair the file (or move it aside and sign in again). Nothing was verified.`);
+            return 2;
+        }
+        if (mem) {
+            expectedIssuer = mem.did;
+            anchor = `remembered for ${issuerStoreKey(verifyHost())} since ${mem.firstSeen.slice(0, 10)}`;
+        }
+        else {
+            const pick = builtInAnchor(files, read);
+            if ("refusal" in pick) {
+                err(pinRequiredMessage("npx @decidio/sdk verify", pick.refusal));
+                err(`  Nothing is remembered for ${issuerStoreKey(verifyHost())} on this computer: signing in once (npx @decidio/sdk login) remembers its DID, and then no --issuer is needed.`);
+                return 2;
+            }
+            expectedIssuer = pick.anchor.did;
+            anchor = `built in: ${pick.anchor.label}, ${pick.anchor.host}`;
+        }
+    }
+    const { ok, lines } = runVerify(files, expectedIssuer, read, anchor);
     for (const l of lines)
         log(l);
     return ok ? 0 : 1;
@@ -1610,8 +1816,12 @@ async function cmdQuickstartInner(opts = {}) {
             log(`③ the tour's blocking call gave up after 5 minutes while waiting for your answer, so your answer is NOT posted:`);
             if (DEMO)
                 log(`   the demo ends here; nothing is kept (the demo's agent, token and folder go now). Re-run and answer within 5 minutes.`);
+            else if (earlyError.withdrawn) {
+                log(`   the request was WITHDRAWN from your queue (it no longer waits for an answer; deciding it there does nothing). Re-run the tour and answer within 5 minutes.`);
+                log(`   NOTE: this tour's credentials are still live in ${envFile} - remove them: npx @decidio/sdk quickstart cleanup`);
+            }
             else {
-                log(`   the request is still ROUTED in your queue - decide it there, or re-run the tour and answer within 5 minutes.`);
+                log(`   the request is still ROUTED in your queue (the withdraw call did not land) - decide it there, or re-run the tour and answer within 5 minutes.`);
                 log(`   NOTE: this tour's credentials are still live in ${envFile} - remove them: npx @decidio/sdk quickstart cleanup`);
             }
             log("");
@@ -1701,12 +1911,13 @@ async function cmdQuickstartInner(opts = {}) {
                 const wrote = writeReceiptFile(fname, JSON.stringify(rec.body.credential, null, 2) + "\n");
                 if (wrote === "conflict")
                     return failTour(1);
-                const issuer = rec.body?.issuer;
+                const issuer = hostAnchor(rec.body) ?? undefined;
                 const v = verifyReceipt(rec.body.credential, issuer);
-                const kindLine = `${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? ", " + pinWords() : ""}) · record kind: ${recordKindOf(rec.body.credential) ?? "?"}`;
-                if (!v.valid || !issuer) {
+                const serverInvalid = rec.body?.valid === false;
+                const kindLine = `${v.valid && !serverInvalid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? ", " + pinWords() : ""}) · record kind: ${recordKindOf(rec.body.credential) ?? "?"}`;
+                if (!v.valid || !issuer || serverInvalid) {
                     log(`  ${kindLine}`);
-                    err(`  ✘ the denial's receipt did not verify PINNED (${!issuer ? "no issuer DID from the server" : v.reason ?? "no reason given"}) — the tour did not complete.`);
+                    err(`  ✘ the denial's receipt did not verify PINNED (${!issuer ? "no trust anchor: the server named no issuer and none is remembered for this host" : !v.valid ? v.reason ?? "no reason given" : `the server's own check says it does NOT verify: ${rec.body?.reason ?? "no reason given"}`}) — the tour did not complete.`);
                     return failTour(1);
                 }
                 block("④", "The record", [
@@ -1776,19 +1987,24 @@ async function cmdQuickstartInner(opts = {}) {
         const fname = receiptFileName(decisionId);
         if (writeReceiptFile(fname, JSON.stringify(rec.body.credential, null, 2) + "\n") === "conflict")
             return failTour(1);
-        const issuer = rec.body?.issuer;
+        const issuer = hostAnchor(rec.body) ?? undefined;
         const v = verifyReceipt(rec.body.credential, issuer);
-        const kindLine = `${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? ", " + pinWords() : ""}) · record kind: ${recordKindOf(rec.body.credential) ?? "?"}`;
-        if (!v.valid || !issuer)
+        const serverInvalid = rec.body?.valid === false;
+        const kindLine = `${v.valid && !serverInvalid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? ", " + pinWords() : ""}) · record kind: ${recordKindOf(rec.body.credential) ?? "?"}`;
+        if (!v.valid || !issuer || serverInvalid)
             log(`  ${kindLine}`);
         if (!v.valid) {
             err(`  ✘ the receipt did not verify (${v.reason ?? "no reason given"}) — the tour did not complete.`);
             return failTour(1);
         }
+        if (serverInvalid) {
+            err(`  ✘ the server's own check says this record does NOT verify (${rec.body?.reason ?? "no reason given"}) — the tour did not complete.`);
+            return failTour(1);
+        }
         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(`  ⚠ the server named no issuer (expectedIssuer) and no DID is remembered for this host, so this check ran UNPINNED —`);
+            err(`    it proves the receipt is internally consistent, NOT who issued it (a self-signed forgery also passes).`);
+            err(`    Take your Decidio's issuer DID from ${API}/api/did (public, no sign-in) — never from the receipt — then re-check:`);
             err(`      npx @decidio/sdk verify --issuer <did:key:...> ${fname}`);
             err(`  ✘ the tour does not count an UNPINNED check as success.`);
             return failTour(1);
@@ -2194,8 +2410,10 @@ APPROVALS AND RECEIPTS
   npx @decidio/sdk receipt <id> [--json]   download a sealed decision's Authority Receipt to a .json FILE; --json prints
                                        a summary to stdout (file name, evidence, issuer, the identities you may see) -
                                        the credential itself is the file
-  npx @decidio/sdk verify --issuer <did> <receipt.json> [more...]   verify receipts OFFLINE, pinned to your
-                                       workspace's issuer (--allow-unpinned: structural check only)
+  npx @decidio/sdk verify [--issuer <did>] <receipt.json> [more...]   verify receipts OFFLINE, pinned to a trust
+                                       anchor it prints first: --issuer if given, else the DID this computer remembered
+                                       for your Decidio when you signed in, else the built-in hosted-service issuer
+                                       (never the receipt's own issuer field; --allow-unpinned: structural check only)
 
 DEVELOPMENT
   npx @decidio/sdk dev [--target URL] [--port N]   local relay for the resume webhook
@@ -2204,7 +2422,7 @@ DEVELOPMENT
 NOTES
   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.
+  fully offline — it touches no network and reads no .env (only the issuer DIDs remembered at sign-in).
   Update check: network commands (and the bare command on a terminal) ask the public npm registry once a day
   whether a newer version exists. If so,
   an interactive run asks "Upgrade now? [y/n]" first (y upgrades the way you installed - global, or in the
@@ -2221,8 +2439,9 @@ NOTES
   (quickstart, durable resume, workers, adapters).`;
 const GATED_CMDS = new Set(["quickstart", "init", "login", "doctor", "approvals", "receipt", "tokens"]);
 function semverNewer(a, b) {
-    const pa = a.split(".").map((x) => parseInt(x, 10)), pb = b.split(".").map((x) => parseInt(x, 10));
-    if (pa.length < 3 || pb.length < 3 || pa.some((x) => Number.isNaN(x)) || pb.some((x) => Number.isNaN(x)))
+    const parse = (s) => (/^\d+\.\d+\.\d+$/.test(s) ? s.split(".").map((x) => parseInt(x, 10)) : null);
+    const pa = parse(a), pb = parse(b);
+    if (!pa || !pb)
         return false;
     for (let i = 0; i < 3; i++)
         if (pa[i] !== pb[i])
@@ -2233,7 +2452,7 @@ async function latestPublished() {
     const cache = joinPath(sessionDir(), "update-check.json");
     try {
         const c = JSON.parse(readFileSync(cache, "utf8"));
-        if (c && typeof c.latest === "string" && Date.now() - Number(c.checkedAt) < 24 * 3600 * 1000)
+        if (c && typeof c.latest === "string" && /^\d+\.\d+\.\d+$/.test(c.latest) && Date.now() - Number(c.checkedAt) < 24 * 3600 * 1000)
             return c.latest;
     }
     catch { }

package/dist/demo-gate.js

@@ -35,10 +35,12 @@ export async function startDemoGate(opts = {}) {
     const issuerDid = "did:key:z" + b58(Buffer.concat([Buffer.from([0xed, 0x01]), issuerRaw]));
     const sealedAt = new Date().toISOString();
     let verdict = null;
+    let withdrawnDemo = false;
     let decidedBy = "the human at the terminal";
     let lastReason = "quickstart";
     let relayCode = null;
     let relayOk = null;
+    let committed = null;
     const relayFetch = async (path, init = {}) => {
         if (!relayBase)
             return null;
@@ -110,7 +112,8 @@ export async function startDemoGate(opts = {}) {
                     return send({ ok: true, changed: true });
                 if (path === "/agent/authorize") {
                     verdict = null;
-                    return send({ decision: "route", decisionId: DECISION_ID, receiptId: "R-DEMO-1" });
+                    committed = typeof body?.requestCommitment === "string" && /^[0-9a-f]{64}$/.test(body.requestCommitment) ? body.requestCommitment : null;
+                    return send({ decision: "route", decisionId: DECISION_ID, receiptId: "R-DEMO-1", requestCommitment: committed });
                 }
                 if (path.startsWith("/agent/status/")) {
                     if (!verdict && relayCode) {
@@ -121,7 +124,15 @@ export async function startDemoGate(opts = {}) {
                             lastReason = "decided on the demo page";
                         }
                     }
-                    return send(verdict === "reject" ? { state: "rejected", reason: "quickstart: rejected by the approver" } : { state: verdict === "approve" ? "approved" : "pending" });
+                    if (withdrawnDemo && !verdict)
+                        return send({ state: "rejected", reason: "quickstart: withdrawn — the tour stopped waiting", requestCommitment: committed });
+                    return send(verdict === "reject" ? { state: "rejected", reason: "quickstart: rejected by the approver", requestCommitment: committed } : { state: verdict === "approve" ? "approved" : "pending", requestCommitment: committed });
+                }
+                if (path.startsWith("/agent/withdraw/")) {
+                    if (verdict)
+                        return send({ code: "NOT_OPEN", state: verdict === "approve" ? "approved" : "rejected", decisionId: DECISION_ID }, 409);
+                    withdrawnDemo = true;
+                    return send({ ok: true, withdrawn: true, state: "rejected", decisionId: DECISION_ID, reason: "requester_stopped_waiting" });
                 }
                 if (/^\/api\/decisions\/[^/]+\/(approve|reject)$/.test(path)) {
                     const already = verdict !== null;
@@ -148,7 +159,7 @@ export async function startDemoGate(opts = {}) {
                 }
                 if (/^\/api\/records\/[^/]+\/verify$/.test(path)) {
                     const cred = issueReceipt(verdict === "reject" ? "denial" : "approval");
-                    return send({ dNumber: D_NUMBER, issuer: issuerDid, alg: "Ed25519", valid: true, signatureValid: true, contentBound: true, matchesRecord: true, payloadMatches: true, hash: cred.credentialSubject.contentHash, prevHash: null, credential: cred });
+                    return send({ dNumber: D_NUMBER, issuer: issuerDid, expectedIssuer: issuerDid, alg: "Ed25519", valid: true, signatureValid: true, contentBound: true, matchesRecord: true, payloadMatches: true, hash: cred.credentialSubject.contentHash, prevHash: null, credential: cred });
                 }
                 if (/^\/api\/records\/[^/]+$/.test(path))
                     return send({ record: { confirmation: verdict === "approve" ? { status: "application_confirmed", confirmed: true } : { status: "pending", confirmed: false } } });

package/dist/guard.js

@@ -65,8 +65,8 @@ export class Guard {
         if ((opts?.mode ?? "durable") === "blocking") {
             const ceilingMs = opts?.pollTimeoutMs ?? base.pollTimeoutMs ?? 600_000;
             console.warn(`[decidio] WARNING: blocking wait — this call gives up after ${Math.round(ceilingMs / 1000)}s ` +
-                `(pollTimeoutMs), and when it does, the decision stays OPEN in Decidio while this process stops waiting: ` +
-                `a later approval cannot resume it. Only safe for short, watched approvals — omit mode:"blocking" for ` +
+                `(pollTimeoutMs), and when it does, this process stops waiting and the request is withdrawn in Decidio: ` +
+                `a later approval does nothing. Only safe for short, watched approvals — omit mode:"blocking" for ` +
                 `durable async resume on real (minutes-to-days) approvals.`);
             return withApproval(fn, describe, base, { ...(opts?.evidence ? { evidence: opts.evidence } : {}), ...(opts?.withContext ? { withContext: true } : {}) });
         }

package/dist/index.d.ts

@@ -1,11 +1,13 @@
-import type { ResumeController } from "./resume.js";
+import type { ResumeController, ApprovalCheck } from "./resume.js";
+import { type CommittedRequest } from "./signing.js";
 import { type EvidenceOutcome } from "./evidence.js";
-export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
-export type { PendingAction, PendingStore, ResumeController, ResumeOutcome } from "./resume.js";
+export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded, checkApproval } from "./resume.js";
+export type { PendingAction, PendingStore, ResumeController, ResumeOutcome, ApprovalCheck, ApprovalCheckCode, DecisionStatus } from "./resume.js";
 export { guard, Guard } from "./guard.js";
 export type { GuardFacadeConfig, ProtectOptions } from "./guard.js";
 export { DecidioHttpError, decisionIdProblem } from "./errors.js";
-export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential } from "./signing.js";
+export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential, bindingMaterial, requestCommitment, idempotencyKey, committedRequestJson } from "./signing.js";
+export type { BindingMaterial, CommittedRequest } 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";
@@ -80,9 +82,44 @@ export declare class DecidioRejectedError extends Error {
     decisionId: string;
     constructor(reason: string, decisionId: string);
 }
+/** THE REQUEST CHANGED AFTER APPROVAL (0.7.0). Decidio records an approval for `decisionId`, but it is
+ *  bound (by a keyed commitment) to a DIFFERENT request than the one about to run — the arguments, the
+ *  amount or the described context changed after a human approved, or this agent's key material changed
+ *  since it asked. Nothing was executed. A new request needs a new approval: reject this decision and
+ *  run the action again. Extends DecidioBlockedError, so code that already treats a block as "did not
+ *  run" keeps doing so. */
+export declare class DecidioRequestChangedError extends DecidioBlockedError {
+    readonly code: "request_changed";
+    constructor(decisionId: string, detail?: string);
+}
+/** An approval that cannot be TIED to this request (0.7.0): Decidio answered without the request
+ *  commitment this SDK sent (`commitment_missing` — the gate predates request binding), or holds one
+ *  this process cannot recompute (`unverifiable` — no or unreadable key material, or a malformed
+ *  answer). Fail closed: nothing was executed. Extends DecidioBlockedError. */
+export declare class DecidioApprovalUnverifiedError extends DecidioBlockedError {
+    readonly code: "commitment_missing" | "unverifiable";
+    constructor(decisionId: string, code: "commitment_missing" | "unverifiable", detail: string);
+}
+/** The typed refusal for an approval check that did not pass — ONE mapping for every door that throws
+ *  (inline, LangGraph, Temporal, Inngest, OpenAI Agents). `pending` is included for the doors that
+ *  cannot wait again; the doors that can (LangGraph, Temporal, Inngest) wait instead of calling this. */
+export declare function approvalRefusal(check: ApprovalCheck): Error;
+/** What a routed approval must be bound to on the CORE door: exactly what executes — the canonical
+ *  argument snapshot plus the described action/amount/scope. The durable resume recomputes the same
+ *  shape over the parked payload. */
+export declare function coreRequest(ctx: {
+    action: string;
+    amount: number;
+    scope?: string | null;
+}, args: readonly unknown[]): CommittedRequest;
 export declare class DecidioTimeoutError extends Error {
     decisionId: string;
-    constructor(decisionId: string);
+    withdrawn: boolean;
+    /** `withdrawn` (0.6.4+): true when the SDK told Decidio it gave up and the request was closed as
+     *  WITHDRAWN (the queue no longer carries it; a later approval does nothing); false when that
+     *  best-effort call failed, so the request may still be open in Decidio. Nothing was executed
+     *  locally either way. */
+    constructor(decisionId: string, withdrawn?: boolean);
 }
 /** A transport failure with GUIDANCE instead of a raw fetch stack. Carries the endpoint, the
  *  operation, the underlying code, and the safety state a caller cares about most: whether