@paydlux/agent 0.1.9 → 0.1.11

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,29 +27,58 @@ 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-z.]/g, "");
-    const hit = staticCache.get(dir + "/" + safe);
-    if (hit)
+    const safe = name.replace(/[^a-z0-9._-]/g, "");
+    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 = readFileSync(join(dir, safe), "utf8");
+        text = safe.endsWith(".png") ? readFileSync(file) : readFileSync(file, "utf8");
     }
     catch {
-        // A package install that shipped without the folder should say so instead of
-        // throwing out of the request handler.
-        throw new Error(label + " is missing from this install (expected " + join(dir, safe) + ")");
+        // 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");
+const notFound = (res) => {
+    res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+    res.end("404");
+};
 const readPortalFile = (name) => readStatic(PORTAL_DIR, name, "portal app");
 /** A portal link is a capability: whoever holds it can approve. So it is long,
  *  random, and compared without leaking timing. */
@@ -165,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) {
@@ -182,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";
@@ -246,28 +325,73 @@ 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;
     }
+    /**
+     * The human said no.
+     *
+     * `awaiting_phone` is a valid state to deny from. Opening the phone link
+     * builds the challenge on the spot (so a human needs one tap, not two), which
+     * means the first thing a person sees on their phone is already
+     * `awaiting_phone` — refusing to deny from that state left the Reject button
+     * dead, which was verified on live testnet. Denying is always allowed up to
+     * the point the transaction is submitted; after that it is too late.
+     */
     deny(id, reason = "denied by the approver") {
         const rec = this.records.get(id);
         if (!rec)
             throw new Error("unknown handle " + id);
-        if (rec.status !== "pending")
-            throw new Error(`already ${rec.status}`);
+        if (rec.status === "settled")
+            throw new Error("already settled — the money has moved, it cannot be denied");
+        if (rec.status === "denied")
+            return rec; // idempotent: the app may retry
         rec.status = "denied";
         rec.reason = reason;
+        rec.challenge = undefined; // the phone's answer is now worthless
+        rec.signedXdr = undefined;
         return rec;
     }
+    /**
+     * What the phone app is allowed to see. Never the paid `content` — that is
+     * what the buyer has not paid for yet — and never the raw challenge XDR,
+     * which the app fetches per item so the desk can re-check the binding.
+     */
+    queue() {
+        return this.list().map((r) => ({
+            id: r.id,
+            at: r.at,
+            uri: r.uri,
+            price: r.price,
+            status: r.status,
+            reason: r.reason,
+            tx: r.tx,
+            /** what the buyer says it wants. Agent-controlled text: render as text. */
+            wants: (r.body ?? "").slice(0, 200),
+            token: this.cfg.vault.token.getCode(),
+            expiresAt: r.challenge?.summary.expiresAt,
+            hash: r.challenge?.hash,
+        }));
+    }
     /** Serve the pending list as JSON (the portal polls this). */
     api(handler) { return handler; }
     listen(port = this.cfg.port) {
@@ -329,6 +453,65 @@ export class ApprovalDesk {
                 res.end("ok");
                 return;
             }
+            // The approver app's static shell is served BEFORE the key gate, on
+            // purpose. It is index.html, app.js, xdr.js, the icons and the manifest:
+            // client code with no secret and no payment data in it, the same as the
+            // portal's own portal.js. Serving it unauthenticated is what lets a phone
+            // install it to a home screen from a plain URL, with the seller's key
+            // arriving separately in the link. Everything that carries data or moves
+            // money — /queue, /challenge, /list, /approve, /deny, /signed — stays
+            // behind the gate below.
+            //
+            // The app uses relative script srcs, so it must be served from a
+            // directory URL: /phone without the slash would resolve app.js to /app.js.
+            if (url.pathname === "/phone") {
+                res.writeHead(302, { location: "/phone/" + url.search });
+                res.end();
+                return;
+            }
+            if (url.pathname === "/phone/" || url.pathname === "/phone/index.html") {
+                res.writeHead(200, {
+                    "content-type": "text/html; charset=utf-8",
+                    // The approver key goes in IndexedDB behind a non-extractable
+                    // CryptoKey; an injected script is the realistic threat, so lock the
+                    // origin. No inline script on the page: app.js and xdr.js are
+                    // separate files, so script-src 'self' actually holds. connect-src
+                    // 'self' is what stops the app talking anywhere but the desk that
+                    // served it.
+                    "content-security-policy": "default-src 'none'; script-src 'self'; style-src 'unsafe-inline'; " +
+                        "img-src 'self' data:; connect-src 'self'; base-uri 'none'; " +
+                        "form-action 'none'; frame-ancestors 'none'",
+                    "referrer-policy": "no-referrer",
+                    "x-content-type-options": "nosniff",
+                    "cache-control": "no-store",
+                });
+                const page = readAppFile("index.html");
+                if (page === null)
+                    return notFound(res);
+                res.end(page);
+                return;
+            }
+            if (url.pathname.startsWith("/phone/")) {
+                const file = url.pathname.slice("/phone/".length);
+                // Icons and the manifest are part of installing the app to a home
+                // screen, so they are served alongside the code. Names are still
+                // stripped to a safe set before they touch a path.
+                if (!/^[a-z0-9_-]+\.(js|png|webmanifest)$/.test(file))
+                    return notFound(res);
+                const type = file.endsWith(".png") ? "image/png"
+                    : file.endsWith(".webmanifest") ? "application/manifest+json"
+                        : "text/javascript";
+                const body = readAppFile(file);
+                if (body === null)
+                    return notFound(res);
+                res.writeHead(200, {
+                    "content-type": type + (file.endsWith(".png") ? "" : "; charset=utf-8"),
+                    "cache-control": "no-store",
+                    "x-content-type-options": "nosniff",
+                });
+                res.end(body);
+                return;
+            }
             // A public demo link must not be an open approval button. If a portalKey
             // is configured, every route needs it, or the desk answers 403.
             //
@@ -364,56 +547,22 @@ export class ApprovalDesk {
                 // approval page and an injected string can't become executable script.
                 if (url.pathname === "/portal.js" || url.pathname === "/portal.css") {
                     const file = url.pathname.slice(1);
+                    const body = readPortalFile(file);
+                    if (body === null)
+                        return notFound(res);
                     res.writeHead(200, {
                         "content-type": (file.endsWith(".css") ? "text/css" : "text/javascript") + "; charset=utf-8",
                         "x-content-type-options": "nosniff",
                     });
-                    res.end(readPortalFile(file));
+                    res.end(body);
                     return;
                 }
                 if (url.pathname === "/list")
                     return send(200, this.list());
-                // The approver app. Served from the desk so the human opens one link on
-                // their phone instead of pasting XDR around. The app itself makes no
-                // requests after loading, and the portalKey gate above already covers
-                // these paths: without the key, nothing here is reachable.
-                // The app uses relative script srcs, so it must be served from a
-                // directory URL. /phone without the slash would resolve app.js to
-                // /app.js, so send it to the canonical path with the key intact.
-                if (url.pathname === "/phone") {
-                    res.writeHead(302, { location: "/phone/" + url.search });
-                    res.end();
-                    return;
-                }
-                if (url.pathname === "/phone/" || url.pathname === "/phone/index.html") {
-                    res.writeHead(200, {
-                        "content-type": "text/html; charset=utf-8",
-                        // The key lives in IndexedDB behind a non-extractable CryptoKey;
-                        // an injected script is the realistic threat, so lock the origin.
-                        // No inline script on the page: app.js and xdr.js are separate
-                        // files, so script-src 'self' actually holds. connect-src 'self' is
-                        // what stops the app talking anywhere but the desk that served it.
-                        "content-security-policy": "default-src 'none'; script-src 'self'; style-src 'unsafe-inline'; " +
-                            "img-src 'self' data:; connect-src 'self'; base-uri 'none'; " +
-                            "form-action 'none'; frame-ancestors 'none'",
-                        "referrer-policy": "no-referrer",
-                        "x-content-type-options": "nosniff",
-                    });
-                    res.end(readAppFile("index.html"));
-                    return;
-                }
-                if (url.pathname.startsWith("/phone/")) {
-                    const file = url.pathname.slice("/phone/".length);
-                    if (!/^[a-z]+\.(js|css)$/.test(file))
-                        return send(404, { error: "not found" });
-                    res.writeHead(200, {
-                        "content-type": (file.endsWith(".css") ? "text/css" : "text/javascript") + "; charset=utf-8",
-                        "cache-control": "no-store",
-                        "x-content-type-options": "nosniff",
-                    });
-                    res.end(readAppFile(file));
-                    return;
-                }
+                // The approver app's list view. Key-gated like everything else, and it
+                // carries no paid content and no challenge XDR.
+                if (url.pathname === "/queue")
+                    return send(200, this.queue());
                 // The app fetches the pending transaction by handle rather than asking
                 // the human to paste 400 characters of base64 on a phone.
                 const ch = url.pathname.match(/^\/challenge\/([\w-]+)$/);
@@ -431,6 +580,16 @@ 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),
+                        memo: rec.challenge.summary.memo ?? "",
+                        expiresAt: rec.challenge.summary.expiresAt,
                     });
                 }
                 const m = url.pathname.match(/^\/(approve|deny|signed)\/([\w-]+)$/);

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.9",
+  "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",
@@ -16,6 +16,10 @@
     "phone-app/index.html",
     "phone-app/app.js",
     "phone-app/xdr.js",
+    "phone-app/app.css",
+    "phone-app/manifest.webmanifest",
+    "phone-app/icon-192.png",
+    "phone-app/icon-512.png",
     "portal-app/portal.js",
     "portal-app/portal.css",
     "README.md",
@@ -36,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"