@paydlux/agent 0.1.10 → 0.1.12

package/README.md

@@ -213,11 +213,32 @@ if (res.ok) console.log(res.data, "paid in tx", res.tx);
 `npx tsx stellar/onboard.ts` creates the vault and prints that key. The key is
 **one of two signatures** — it cannot spend alone.
 
+### Your spending mandate (one command, enforced at the approve button)
+
+```bash
+paydlux sell --price 4.50 --max 10 --daily 20
+```
+
+No payment above 10, nothing past 20 in a day. The desk checks this **before**
+it asks your phone, and again at submission — the budget can be spent between
+your approval and the ledger call, so a stale signature is refused rather than
+honoured. Approvals already waiting count against the budget, so a queue of six
+4.50 requests against a 20/day cap sends four to your phone and refuses two at
+the button instead of letting you approve six and watch two fail.
+
+A refusal answers the buyer with `error: "mandate_refused"` on the **same**
+handle, so a polite agent cannot park-refuse-park forever. `paydlux sell` also
+refuses to start if `--price` is above `--max` or `--daily`, because that
+combination blocks every payment and looks like a bug in the desk.
+
+Verified on the published package: 6 x 4.50 against `--daily 20` -> four
+settled, two refused, vault balance moved exactly 18.00 and stopped.
+
 ### What is enforced where (said honestly)
 
-| enforced by Stellar | enforced by `policy.ts` |
+| enforced by Stellar | enforced by the desk (`policy.ts`) |
 |---|---|
-| max per payment, payee, token, time window, one-shot execution | payments per day, running daily total, seller allow/deny list |
+| payee, token, time window, one-shot execution, per-payment ceiling as a signer rule | per-payment ceiling and daily total at the approve button and again at submission, running daily total, seller allow/deny list |
 
 The vault is one payment at a time; counting payments is our job. A rule break
 means we never build the transaction, so nothing reaches the ledger.

package/dist/agent.d.ts

@@ -19,6 +19,14 @@ export type PayResponse<T = string> = {
     tx?: string;
     /** set when a human has to approve */
     handle?: string;
+    /**
+     * Why a payment was refused, as the seller named it: "mandate_refused" (the
+     * seller's spending ceiling — retrying the same request can never work) or
+     * "payment_denied" (a human said no to this one). Without the distinction an
+     * agent retries a refused payment forever, which is exactly what a polite
+     * buyer does.
+     */
+    error?: string;
     /** where a human approves (the seller's desk) */
     desk?: string;
     /** where THIS buyer polls for the answer (the gateway, no key needed) */

package/dist/agent.js

@@ -46,7 +46,7 @@ export class PaydluxAgent {
             if (parked.status === 200) {
                 return { ok: true, status: 200, data: (j.data ?? j), tx: j.tx };
             }
-            return { ok: false, status: parked.status, handle: j.handle, desk: j.desk,
+            return { ok: false, status: parked.status, handle: j.handle, error: j.error, desk: j.desk,
                 statusUrl: j.statusUrl, requirements: reqs,
                 reason: j.reason ?? "a human has to approve this payment" };
         }

package/dist/cli.d.ts

@@ -1,8 +1,28 @@
 #!/usr/bin/env node
+import { StellarVault } from "./vault.ts";
 export declare const VAULT_FILE_DEFAULT = "paydlux-vault.json";
 /** The one file that holds everything. Refuses to read a file that is world-readable. */
 export declare function loadVault(path?: string): {
     path: string;
     data: any;
 };
+/**
+ * Persist the portal key so the phone link survives a restart. A new key every
+ * boot means the human re-scans a QR every time and any link already opened on
+ * a phone stops working mid-payment.
+ */
+export declare function deskKeys(path: string, data: any): string;
+/**
+ * Where the money lands.
+ *
+ * `setup` creates a payee account for you. Two cases break that: a vault made
+ * before the payee existed, and a seller who wants the money in their own
+ * account (a Binance deposit address, an exchange wallet). Both are handled
+ * here, because a payment to an account that does not exist — or that does not
+ * trust the token — fails on the ledger with a code the seller never sees.
+ *
+ * Adding a trustline needs the payee's own key, so for an outside account we can
+ * only check and explain. For a payee we generated, we do it ourselves.
+ */
+export declare function ensurePayee(path: string, data: any, vault: StellarVault): Promise<any>;
 export declare function main(): Promise<void>;

package/dist/cli.js

@@ -14,11 +14,13 @@
 // A seller should type one command and get a price, a link, and a key to paste
 // into their bot.
 import { createInterface } from "node:readline/promises";
+import { createServer } from "node:http";
+import { execSync } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync, chmodSync, realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { resolve } from "node:path";
-import { Keypair } from "@stellar/stellar-sdk";
-import { StellarVault, USDC_ISSUER } from "./vault.js";
+import { Account, Keypair, Operation, TransactionBuilder } from "@stellar/stellar-sdk";
+import { StellarVault, USDC_ISSUER, passphrase } from "./vault.js";
 import { Gateway } from "./gateway.js";
 import { newPortalKey } from "./desk.js";
 import { PolicyEngine } from "./policy.js";
@@ -33,6 +35,39 @@ const log = (...a) => console.log("•", ...a);
 /** Print a reason and stop. Declared as a function (not an arrow in a const) so
  *  TypeScript's control-flow analysis actually narrows the caller after it. */
 function bad(msg) { console.error("\n" + msg + "\n"); process.exit(1); }
+/**
+ * Ask the OS whether a port is free, and if not, who owns it. Returns null when
+ * the port is available. Naming the owning process is what turns "EADDRINUSE"
+ * into something a seller can act on.
+ */
+function portHolder(port) {
+    return new Promise((resolve) => {
+        const probe = createServer();
+        probe.once("error", (e) => {
+            if (e.code === "EADDRINUSE")
+                resolve(findListener(port) ?? "another process");
+            else
+                resolve(null); // some other bind problem; let the real listen report it
+        });
+        probe.once("listening", () => { probe.close(() => resolve(null)); });
+        probe.listen(port, "127.0.0.1");
+    });
+}
+/** Best-effort: which command is holding this port, from `lsof`. */
+function findListener(port) {
+    try {
+        const out = execSync(`lsof -nP -ti tcp:${port} -sTCP:LISTEN 2>/dev/null`, { encoding: "utf8" });
+        const pid = out.trim().split("\n")[0];
+        if (!pid)
+            return null;
+        const cmd = execSync(`ps -o command= -p ${pid} 2>/dev/null`, { encoding: "utf8" }).trim();
+        const mine = cmd.includes("cli") || cmd.includes("paydlux");
+        return `${mine ? "another Paydlux (pid " + pid + ")" : cmd || "pid " + pid}`;
+    }
+    catch {
+        return null;
+    }
+}
 /** The one file that holds everything. Refuses to read a file that is world-readable. */
 export function loadVault(path = resolve(process.cwd(), arg("file") ?? VAULT_FILE_DEFAULT)) {
     if (!existsSync(path)) {
@@ -49,7 +84,7 @@ function pub(seed) { return Keypair.fromSecret(seed).publicKey(); }
  * boot means the human re-scans a QR every time and any link already opened on
  * a phone stops working mid-payment.
  */
-function deskKeys(path, data) {
+export function deskKeys(path, data) {
     if (!data.desk)
         data.desk = {};
     if (!data.desk.portalKey) {
@@ -60,14 +95,104 @@ function deskKeys(path, data) {
     }
     return data.desk.portalKey;
 }
+/** Does this account already hold the token the vault pays in? */
+async function trusts(vault, address) {
+    const acc = await vault.horizon.loadAccount(address).catch(() => null);
+    if (!acc)
+        return false;
+    const code = vault.token.getCode(), issuer = vault.token.getIssuer();
+    return acc.balances.some((b) => b.asset_type !== "native"
+        && b.asset_code === code && b.asset_issuer === issuer);
+}
+/**
+ * Where the money lands.
+ *
+ * `setup` creates a payee account for you. Two cases break that: a vault made
+ * before the payee existed, and a seller who wants the money in their own
+ * account (a Binance deposit address, an exchange wallet). Both are handled
+ * here, because a payment to an account that does not exist — or that does not
+ * trust the token — fails on the ledger with a code the seller never sees.
+ *
+ * Adding a trustline needs the payee's own key, so for an outside account we can
+ * only check and explain. For a payee we generated, we do it ourselves.
+ */
+export async function ensurePayee(path, data, vault) {
+    const specified = arg("payee");
+    if (specified) {
+        if (!/^G[A-Z2-7]{55}$/.test(specified))
+            bad(`--payee must be a Stellar account (G…56 chars), got "${specified}"`);
+        if (specified === vault.address)
+            bad("--payee cannot be the vault itself");
+        if (!(await trusts(vault, specified))) {
+            bad(`${specified} does not hold ${vault.token.getCode()} yet, so a payment to it would be\n  rejected by the ledger (OP_NO_TRUST).\n\n  add a trustline for ${vault.token.getCode()} from ${vault.token.getIssuer()} to that account\n  (the exchange or wallet that owns it does this), or drop --payee and Paydlux will\n  create and manage a payee account for you.`);
+        }
+        data.payee = { address: specified, external: true };
+        writeFileSync(path, JSON.stringify(data, null, 2));
+        chmodSync(path, 0o600);
+        log(`payments land in your account ${specified}`);
+        return specified;
+    }
+    if (data.payee?.address && !data.payee.seed)
+        return data.payee.address;
+    if (data.payee?.address && (await trusts(vault, data.payee.address)))
+        return data.payee.address;
+    const keys = data.keys;
+    if (!keys.approver) {
+        bad(`this vault has no payee account yet, and creating one needs both human keys —\n  this machine holds only one.\n\n  point the payments at an account you already own that holds ${vault.token.getCode()}:\n\n  paydlux sell --payee G…`);
+    }
+    const kp = Keypair.fromSecret(data.payee?.seed ?? Keypair.random().secret());
+    if (!data.payee?.address) {
+        log(`creating the payee account (2 XLM of ledger rent)…`);
+        const acc = await vault.horizon.loadAccount(vault.address);
+        const tx = new TransactionBuilder(new Account(vault.address, acc.sequence), {
+            fee: "100", networkPassphrase: passphrase((data.network ?? "testnet")),
+        })
+            .addOperation(Operation.createAccount({ destination: kp.publicKey(), startingBalance: "2" }))
+            .setTimeout(120).build();
+        tx.sign(Keypair.fromSecret(keys.principal));
+        tx.sign(Keypair.fromSecret(keys.approver));
+        await vault.horizon.submitTransaction(tx);
+    }
+    if (!(await trusts(vault, kp.publicKey())))
+        await vault.trustToken(kp.publicKey(), "1000000", kp);
+    data.payee = { address: kp.publicKey(), seed: kp.secret() };
+    writeFileSync(path, JSON.stringify(data, null, 2));
+    chmodSync(path, 0o600);
+    log(`payments land in ${kp.publicKey()}`);
+    return kp.publicKey();
+}
+/**
+ * Change what the vault settles in. USDC only: a custom token would need an
+ * issuer key, and holding one quietly is not a decision to make in a flag.
+ * The trustline needs both human keys, so this has to run before
+ * `approver --forget` takes one away.
+ */
+async function switchToken(path, data, code) {
+    if (code !== "USDC") {
+        bad(`switching to a custom token means holding an issuer key. Only USDC can be\n  switched to here. Create a token vault with: paydlux setup --token ${code}`);
+    }
+    const network = (data.network ?? "testnet");
+    if (!data.keys.approver)
+        bad(`adding the USDC trustline needs both human keys and this machine holds one. Re-run on the machine with both, then use approver --forget.`);
+    const vault = await StellarVault.load(data.vault, data.token.code, data.token.issuer, { principal: pub(data.keys.principal), approver: pub(data.keys.approver), agent: pub(data.keys.agent) }, network);
+    log(`adding a USDC trustline to the vault…`);
+    await vault.trustUsdc(Keypair.fromSecret(data.keys.principal), Keypair.fromSecret(data.keys.approver));
+    data.token = { code: "USDC", issuer: USDC_ISSUER[network] };
+    writeFileSync(path, JSON.stringify(data, null, 2));
+    chmodSync(path, 0o600);
+    log("the vault now settles in Circle USDC");
+}
 // ------------------------------------------------------------------------ sell
 async function sell() {
     const { path, data } = loadVault();
     const network = (data.network ?? "testnet");
     const keys = data.keys;
-    const payee = data.payee?.address;
-    if (!payee)
-        bad(`${path} has no payee.address — where should payment land?\n  add it, or re-run: paydlux setup`);
+    // Settle in real money instead of the token this vault issued. Needs a
+    // trustline, which needs both human keys, so it happens here — before
+    // `approver --forget` takes one of them away.
+    const wantToken = arg("token")?.toUpperCase();
+    if (wantToken && wantToken !== data.token.code)
+        await switchToken(path, data, wantToken);
     const price = arg("price") ?? data.policy?.defaultPrice ?? "1";
     if (!(Number(price) > 0))
         bad("--price must be a positive number");
@@ -82,9 +207,26 @@ async function sell() {
     const maxPer = Number(arg("max") ?? data.policy?.maxPerPayment ?? 2);
     const daily = Number(arg("daily") ?? data.policy?.dailyBudget ?? 10);
     const policy = new PolicyEngine({ maxPerPayment: maxPer, dailyBudget: daily });
-    const vault = await StellarVault.load(data.vault, data.token.code, data.token.issuer, { principal: pub(keys.principal), approver: pub(keys.approver), agent: pub(keys.agent) }, network);
+    // A ceiling below the price blocks every payment, and the failure looks like
+    // a bug in the desk: the buyer waits, the human never sees an approvable
+    // item, and the log says "mandate refused". Say it now, before anything is
+    // started, because this is a mistake in the flags and not in the product.
+    const priceNum = Number(price);
+    if (!(priceNum > 0))
+        bad(`--price ${price} is not a number greater than zero.`);
+    if (priceNum > maxPer) {
+        bad(`--price ${price} is above --max ${maxPer}, so every payment would be refused by your own mandate.\n  raise --max to at least ${price} (for example --max ${price}) or lower --price.`);
+    }
+    if (priceNum > daily) {
+        bad(`--price ${price} is above --daily ${daily}: one payment would spend the whole day's budget and the second would be refused.\n  set --daily to at least ${price}.`);
+    }
+    const vault = await StellarVault.load(data.vault, data.token.code, data.token.issuer, { principal: pub(keys.principal), approver: keys.approver ? pub(keys.approver) : undefined, agent: pub(keys.agent) }, network);
     if (data.token.code === "USDC")
         vault.useUsdc();
+    // Resolve where the money lands before anything starts listening. A parked
+    // payment with no valid payee is a payment that fails an hour later, after
+    // the human already said yes.
+    const payee = await ensurePayee(path, data, vault);
     if (network === "public") {
         console.log(`
   MAINNET — real money.
@@ -112,6 +254,19 @@ async function sell() {
     const publicHost = tls ? PUBLIC_HOST : (arg("host") ?? undefined);
     const deskPort = Number(arg("desk") ?? 4022);
     const gwPort = Number(arg("port") ?? 4021);
+    // A taken port used to surface as an unhandled EADDRINUSE stack trace from
+    // inside Node. To someone following the README that reads as a broken
+    // install, and the stack names neither port nor remedy.
+    for (const [label, port] of [["gateway", gwPort], ["approval desk", deskPort]]) {
+        const who = await portHolder(port);
+        if (who) {
+            // Suggest the pair, not the clashing port twice: --port and --desk with
+            // the same number would fail on the next line.
+            bad(`port ${port} (${label}) is already in use by ${who}.\n` +
+                `  another Paydlux is probably running. Stop it, or move this one:\n` +
+                `  paydlux sell --port ${gwPort + 100} --desk ${deskPort + 100}`);
+        }
+    }
     const gw = new Gateway({
         vault, network, payee,
         deskPort,
@@ -123,6 +278,8 @@ async function sell() {
         publicHost,
         agentKeys: [pub(keys.agent)],
         routes: [{ uri, price, mode, holdSeconds: Number(arg("hold") ?? 3600) }],
+        // The banner prints these numbers. This line is what makes them true.
+        policy,
     });
     let tunnel = null;
     if (tls) {
@@ -186,7 +343,7 @@ async function vaultRent(vault) {
 async function status() {
     const { data } = loadVault();
     const network = (data.network ?? "testnet");
-    const vault = await StellarVault.load(data.vault, data.token.code, data.token.issuer, { principal: pub(data.keys.principal), approver: pub(data.keys.approver), agent: pub(data.keys.agent) }, network);
+    const vault = await StellarVault.load(data.vault, data.token.code, data.token.issuer, { principal: pub(data.keys.principal), approver: data.keys.approver ? pub(data.keys.approver) : undefined, agent: pub(data.keys.agent) }, network);
     if (data.token.code === "USDC")
         vault.useUsdc();
     const rent = await vaultRent(vault);

package/dist/desk.d.ts

@@ -1,5 +1,6 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
 import type { StellarVault } from "./vault.ts";
+import type { PolicyEngine } from "./policy.ts";
 import { type ApprovalChallenge } from "./phone.ts";
 /** A portal link is a capability: whoever holds it can approve. So it is long,
  *  random, and compared without leaking timing. */
@@ -20,6 +21,13 @@ export type DeskRecord = {
      * twice and the buyer never gets the content they already bought.
      */
     key?: string;
+    /**
+     * The failure came from the seller's spending mandate, not from the ledger.
+     * The gateway needs this distinction: a ledger failure is worth retrying, a
+     * mandate refusal never changes, so re-parking the same request would loop
+     * forever — refuse, and make the buyer change the request to ask again.
+     */
+    mandateBlocked?: boolean;
     /** split mode: what the phone is asked to sign, and what it sent back */
     challenge?: ApprovalChallenge;
     qr?: string;
@@ -53,6 +61,18 @@ export type DeskConfig = {
      * gives you. Pinning the Host means the only way in is through the tunnel.
      */
     publicHost?: string;
+    /**
+     * The spending mandate. Optional only so existing tests keep compiling; every
+     * real seller passes one.
+     *
+     * Enforced HERE, at the moment money moves, not in the gateway. The gateway is
+     * the buyer's surface: it can be restarted, bypassed, or run by someone who
+     * forgot to configure it. The desk is the one place every payment passes
+     * through on its way to the ledger — dev mode signs and submits here, split
+     * mode submits the phone's signature here — so this is the only place a
+     * ceiling can actually hold.
+     */
+    policy?: PolicyEngine;
 };
 export declare class ApprovalDesk {
     private records;
@@ -75,6 +95,20 @@ export declare class ApprovalDesk {
      *             principal only, and hand it to the phone. The money moves when
      *             /signed comes back with the phone's signature.
      */
+    /**
+     * The mandate check, in one place, called before money moves.
+     *
+     * Returns null when the payment is allowed, or the reason it is not. The
+     * record is marked failed so the buyer's poll gets a real answer instead of a
+     * timeout, and the reason is surfaced to the human rather than logged only.
+     *
+     * Why this exists at all: `--max` and `--daily` were printed in the seller's
+     * banner and never applied to anything. A ceiling nobody enforces is worse
+     * than no ceiling, because the seller believes they have one.
+     */
+    private mandateBlock;
+    /** The mandate has been satisfied: count the money as spent. */
+    private recordSpend;
     approve(id: string): Promise<DeskRecord>;
     /** Split mode step 1: ask the phone to sign. Nothing is submitted yet. */
     private requestPhoneSignature;

package/dist/desk.js

@@ -10,7 +10,7 @@
 //   - a stolen phone cannot approve alone
 //   - the approval is a real ledger signature, not a database flag
 import { createServer } from "node:http";
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomBytes, timingSafeEqual } from "node:crypto";
@@ -27,31 +27,51 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 const APP_DIR = join(HERE, "..", "phone-app");
 const PORTAL_DIR = join(HERE, "..", "portal-app");
 const staticCache = new Map();
+// mtime of the bytes held in staticCache, so an edited file is picked up on the
+// next request instead of after a restart. See readStatic.
+const staticStamp = new Map();
 /**
- * Static files are read on each process start rather than bundled, so the desk
- * and its front ends can never drift apart. The name is stripped to [a-z.]
- * before it touches a path, so a request can't walk out of the directory.
+ * Static files are read from disk, not bundled, so the desk and its front ends
+ * can never drift apart. The name is stripped to [a-z._-] before it touches a
+ * path, so a request can't walk out of the directory.
  *
  * PNGs are returned as bytes: reading an image as utf8 text replaces every
  * invalid sequence with U+FFFD and ships a corrupt icon to the phone.
+ *
+ * The cache is keyed on the file's mtime, not just its name. Caching once per
+ * process looked fine and was not: the approver's service worker is deliberately
+ * network-first so that a security fix reaches an installed phone on the next
+ * open, and a desk that holds the old bytes in memory until it restarts breaks
+ * exactly that promise. A patched app.js on disk would have sat invisible for
+ * days behind a running desk. One stat() per request is cheap; a stale approver
+ * page that keeps signing old-style transactions is not.
  */
 function readStatic(dir, name, label) {
     const safe = name.replace(/[^a-z0-9._-]/g, "");
-    const hit = staticCache.get(dir + "/" + safe);
-    if (hit)
+    const file = join(dir, safe);
+    let stamp;
+    try {
+        stamp = statSync(file).mtimeMs;
+    }
+    catch {
+        return null; // missing file: a 404, not a crash
+    }
+    const key = dir + "/" + safe;
+    const hit = staticCache.get(key);
+    if (hit && staticStamp.get(key) === stamp)
         return hit;
     let text;
     try {
-        text = safe.endsWith(".png")
-            ? readFileSync(join(dir, safe))
-            : readFileSync(join(dir, safe), "utf8");
+        text = safe.endsWith(".png") ? readFileSync(file) : readFileSync(file, "utf8");
     }
     catch {
-        // A missing file is a 404, not a crash. Throwing here took the whole desk
-        // down over one bad URL: the request handler is not a place to raise.
+        // Unreadable between the stat and the read, or not a file at all. The
+        // request handler is not a place to raise: one bad URL must not take the
+        // whole desk down.
         return null;
     }
-    staticCache.set(dir + "/" + safe, text);
+    staticCache.set(key, text);
+    staticStamp.set(key, stamp);
     return text;
 }
 const readAppFile = (name) => readStatic(APP_DIR, name, "approver app");
@@ -174,12 +194,61 @@ export class ApprovalDesk {
      *             principal only, and hand it to the phone. The money moves when
      *             /signed comes back with the phone's signature.
      */
+    /**
+     * The mandate check, in one place, called before money moves.
+     *
+     * Returns null when the payment is allowed, or the reason it is not. The
+     * record is marked failed so the buyer's poll gets a real answer instead of a
+     * timeout, and the reason is surfaced to the human rather than logged only.
+     *
+     * Why this exists at all: `--max` and `--daily` were printed in the seller's
+     * banner and never applied to anything. A ceiling nobody enforces is worse
+     * than no ceiling, because the seller believes they have one.
+     */
+    mandateBlock(rec, when) {
+        const policy = this.cfg.policy;
+        if (!policy)
+            return null;
+        // Approvals already made that have not settled yet. Those are promises the
+        // seller has already given, so a new one has to fit alongside them.
+        // `pending` deliberately does NOT count: that is a request nobody has
+        // approved, and counting the whole queue would refuse the first approval
+        // just because more requests exist than the budget can cover.
+        const committed = this.list().reduce((sum, r) => (r.id !== rec.id && (r.status === "awaiting_phone" || r.status === "approved"))
+            ? sum + Number(r.price) : sum, 0);
+        const verdict = policy.check({
+            amount: Number(rec.price),
+            payee: this.cfg.payee,
+            ttl: this.cfg.decideWithinSeconds,
+            committed,
+        });
+        if (verdict.ok)
+            return null;
+        rec.status = "failed";
+        rec.reason = `mandate refused (${verdict.rule}): ${verdict.detail}`;
+        rec.mandateBlocked = true;
+        rec.challenge = undefined;
+        rec.signedXdr = undefined;
+        console.log(`[desk] ${rec.id} ${when}: ${rec.reason}`);
+        return rec.reason;
+    }
+    /** The mandate has been satisfied: count the money as spent. */
+    recordSpend(rec, tx) {
+        this.cfg.policy?.record({
+            at: Date.now(), amount: Number(rec.price), payee: this.cfg.payee,
+            uri: rec.uri, mandateHash: tx,
+        });
+    }
     async approve(id) {
         const rec = this.records.get(id);
         if (!rec)
             throw new Error("unknown handle " + id);
         if (rec.status !== "pending")
             throw new Error(`already ${rec.status}`);
+        // Check before asking the phone. A human who approves a payment the mandate
+        // will refuse has spent a Face ID scan and a signature for nothing.
+        if (this.mandateBlock(rec, "refused before asking"))
+            return rec;
         if (this.cfg.split)
             return this.requestPhoneSignature(rec);
         if (!this.cfg.principal || !this.cfg.approver) {
@@ -191,6 +260,7 @@ export class ApprovalDesk {
             const res = await this.cfg.vault.release(this.cfg.payee, rec.price, Keypair.fromSecret(this.cfg.principal), Keypair.fromSecret(this.cfg.approver), id);
             rec.status = "settled";
             rec.tx = String(res?.hash ?? "");
+            this.recordSpend(rec, rec.tx);
         }
         catch (e) {
             rec.status = "failed";
@@ -255,15 +325,25 @@ export class ApprovalDesk {
             console.log(`[desk] ${id} rejected: ${problem}`);
             return rec;
         }
+        // Re-check at the last possible moment. The budget was verified when the
+        // phone was asked; a day is long and other payments have been approved since.
+        // Better to refuse now than to submit a payment the mandate forbids.
+        if (this.mandateBlock(rec, "refused at submission"))
+            return rec;
         rec.signedXdr = signedXdr;
         try {
             const res = await submitApproved(signedXdr, this.cfg.vault.network, this.cfg.vault.horizon);
             rec.status = "settled";
             rec.tx = res.hash;
+            this.recordSpend(rec, res.hash);
+            // The money moving is the one event a seller should never have to
+            // discover by refreshing a page.
+            console.log(`[desk] ${rec.id} PAID ${rec.price} ${this.cfg.vault.token.getCode()} — ledger ${rec.tx}`);
         }
         catch (e) {
             rec.status = "failed";
             rec.reason = e.message;
+            console.log(`[desk] ${rec.id} failed on the ledger: ${rec.reason}`);
         }
         return rec;
     }
@@ -500,6 +580,11 @@ export class ApprovalDesk {
                     return send(200, {
                         id: rec.id, network: rec.challenge.network,
                         hash: rec.challenge.hash, xdr: rec.challenge.xdr,
+                        // Which key this vault will actually accept. A phone holding a key
+                        // from a previous run signs a valid signature over a valid
+                        // transaction, and the ledger answers BAD_AUTH with no explanation.
+                        // Naming the expected key here lets the app say so BEFORE signing.
+                        approver: this.cfg.vault.signers.approver,
                         // what the human is being asked to read. Agent-controlled text: the
                         // app renders it as text, never as markup.
                         wants: (rec.body ?? "").slice(0, 200),

package/dist/gateway.d.ts

@@ -1,7 +1,8 @@
-import { type IncomingMessage, type ServerResponse } from "node:http";
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import { Transaction } from "@stellar/stellar-sdk";
 import { StellarVault, StellarTxError, type Amount, type Mandate, type Network } from "./vault.ts";
 import { ApprovalDesk, type DeskStore } from "./desk.ts";
+import type { PolicyEngine } from "./policy.ts";
 export declare const PAY_HEADER = "x-payment";
 export type Route = {
     uri: string;
@@ -37,6 +38,8 @@ export type GatewayConfig = {
     portalKey?: string;
     /** hostname the desk is publicly served on; pins the Host header. See DeskConfig. */
     publicHost?: string;
+    /** how long a human gets to decide before the parked payment's tx is dead */
+    decideWithinSeconds?: number;
     /**
      * Agent public keys allowed to park a payment for approval. An intent is only
      * honoured if it is signed by one of these, so an unlisted key gets a plain
@@ -50,6 +53,11 @@ export type GatewayConfig = {
      * loopback address, which is only useful on one machine.
      */
     deskUrl?: string;
+    /**
+     * The spending mandate. Passed straight to the desk, which is where it is
+     * enforced — see DeskConfig.policy for why the gateway is the wrong place.
+     */
+    policy?: PolicyEngine;
 };
 export type PaymentProof = {
     /** pre-authorised envelope, base64 XDR, as issued by the vault */
@@ -111,7 +119,7 @@ export declare class Gateway {
         hash: string;
     }>;
     handler(getContent: (uri: string) => string): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
-    listen(port: number, getContent?: (uri: string) => string): Promise<void>;
+    listen(port: number, getContent?: (uri: string) => string): Promise<Server<typeof IncomingMessage, typeof ServerResponse>>;
 }
 export { StellarTxError };
 export type { DeskStore };

package/dist/gateway.js

@@ -39,6 +39,8 @@ export class Gateway {
             portalKey: cfg.portalKey,
             split: cfg.split,
             publicHost: cfg.publicHost,
+            decideWithinSeconds: cfg.decideWithinSeconds,
+            policy: cfg.policy,
         });
     }
     /** Mandates the vault currently holds, so the gateway can hand them out. */
@@ -244,6 +246,20 @@ export class Gateway {
                             return;
                         }
                     }
+                    // The seller's own spending mandate refused this one. Retrying the
+                    // identical request can never succeed — the ceiling is not going to
+                    // move — so re-parking it would loop: park, refuse, park, refuse, with
+                    // a fresh handle each time and a queue the human cannot clear. Answer
+                    // 402 and make the buyer change the request (a smaller price, a
+                    // different route) to ask again.
+                    if (hit.mandateBlocked) {
+                        res.writeHead(402, { [PAY_HEADER]: JSON.stringify(this.requirements(uri)) });
+                        res.end(JSON.stringify({
+                            error: "mandate_refused", handle: hit.id,
+                            reason: hit.reason ?? "refused by the seller's spending mandate",
+                        }));
+                        return;
+                    }
                     // A human said no. Do not silently re-open the same request and nag
                     // them with it: the buyer has to change the request to ask again.
                     if (hit.status === "denied") {
@@ -332,7 +348,10 @@ export class Gateway {
     }
     listen(port, getContent = (u) => `payload for ${u} at ${new Date().toISOString()}`) {
         const srv = createServer(this.handler(getContent));
-        return new Promise((resolve) => srv.listen(port, () => resolve()));
+        // Hand the server back. Returning void meant a started gateway could never
+        // be stopped, which left tests holding ports and a seller with no clean way
+        // to change a route without killing the process.
+        return new Promise((resolve) => srv.listen(port, () => resolve(srv)));
     }
 }
 function readBody(req) {