@paydlux/agent 0.1.10 → 0.1.11

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

@@ -17,8 +17,8 @@ import { createInterface } from "node:readline/promises";
 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";
@@ -49,7 +49,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 +60,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 +172,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.
@@ -123,6 +230,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 +295,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) {

package/dist/policy.d.ts

@@ -48,5 +48,14 @@ export declare class PolicyEngine {
         payee: string;
         ttl?: number;
         liveMandates?: number;
+        /**
+         * Money not spent yet but already promised: payments a human has approved
+         * and is waiting on a signature for. Without this the ceiling only counts
+         * settled payments, so a seller with a 20/day budget can approve six 4.50
+         * requests, spend six Face ID scans, and watch two of them fail at
+         * submission. Counting the queue refuses the fifth one at the button
+         * instead, which is the point of having a human in the loop.
+         */
+        committed?: number;
     }): Verdict;
 }

package/dist/policy.js

@@ -36,9 +36,9 @@ export class PolicyEngine {
         if (req.amount > p.maxPerPayment) {
             return no("max_per_payment", `${req.amount} exceeds the per-payment ceiling of ${p.maxPerPayment}`);
         }
-        const spent = this.spentToday();
+        const spent = this.spentToday() + (req.committed ?? 0);
         if (spent + req.amount > p.dailyBudget) {
-            return no("daily_budget", `${req.amount} would take today to ${(spent + req.amount).toFixed(2)}, over the ${p.dailyBudget} budget (spent ${spent.toFixed(2)})`);
+            return no("daily_budget", `${req.amount} would take today to ${(spent + req.amount).toFixed(2)}, over the ${p.dailyBudget} budget (${this.spentToday().toFixed(2)} paid${req.committed ? ` + ${req.committed.toFixed(2)} already approved and waiting` : ""})`);
         }
         if (p.denylist?.includes(req.payee))
             return no("denylist", `${short(req.payee)} is blocked`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paydlux/agent",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Payments for AI agents that a human approves. Spending mandates enforced on the Stellar ledger: 2-of-2 vault, pre-authorised transaction envelopes, HTTP 402, USDC.",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,7 +40,11 @@
     "test": "cd contracts && forge test",
     "test:stellar": "tsx stellar/demo.ts",
     "test:portal": "tsx stellar/xss-check.ts",
-    "test:phone": "tsx stellar/phone-check.ts && tsx stellar/desk-split-check.ts && tsx stellar/e2e-phone.ts && tsx phone-app/xdr-check.ts && tsx phone-app/app-check.ts && tsx phone-app/desk-app-check.ts",
+    "test:mandate": "tsx stellar/mandate-check.ts",
+    "test:phone": "tsx stellar/phone-check.ts && tsx stellar/desk-split-check.ts && tsx stellar/mandate-check.ts && tsx stellar/e2e-phone.ts && tsx phone-app/xdr-check.ts && tsx phone-app/app-check.ts && tsx phone-app/desk-app-check.ts && tsx ios/bridge-check.ts",
+    "test:ios": "tsx ios/bridge-check.ts",
+    "test:link": "swiftc ios/PaydluxApprover/LinkResolver.swift ios/Checks/linkcheck/main.swift -o \"$TMPDIR/linkcheck\" && \"$TMPDIR/linkcheck\"",
+    "test:seed": "DEVELOPER_DIR=/Library/Developer/CommandLineTools /usr/bin/swiftc -target arm64-apple-macosx14.0 ios/PaydluxApprover/Seed.swift ios/PaydluxApprover/Hex.swift ios/Checks/main.swift -o \"$TMPDIR/seedcheck\" && \"$TMPDIR/seedcheck\"",
     "typecheck": "tsc --noEmit",
     "app": "tsx stellar/cli.ts",
     "app:mainnet": "tsx stellar/cli.ts setup --mainnet"