@paydlux/agent 0.1.8 → 0.1.10

package/README.md

@@ -84,11 +84,17 @@ one key. So the approval half is split off:
 npx tsx stellar/phone-check.ts       # 17 checks: seller alone cannot pay; phone alone cannot pay
 npx tsx stellar/e2e-phone.ts         # desk with no approver key still settles
 npx tsx phone-app/xdr-check.ts       # 32 checks: the phone's own decoder is byte-exact with the SDK
-npx tsx phone-app/desk-app-check.ts  # 28 checks: the real app over real HTTP, end to end
+npx tsx phone-app/desk-app-check.ts  # 57 checks: the real app over real HTTP, end to end
 ```
 
 The seller builds the payment and signs it with their own half. The human opens
-one link — `/phone/?id=...` — and the approver app in `phone-app/` shows them the
+one link — `/phone/?k=...` — and the approver app in `phone-app/` shows them the
+`https://desk.paydlux.com/phone/` link opens an installable app: it has a manifest
+and icons, so a phone can put it on the home screen and it runs full-screen. The
+shell (html, js, icons) is public because it holds no secret and no payment data
+and must load before the key does; every route that returns data or moves money
+(`/queue`, `/challenge`, `/approve`, `/signed`, `/deny`) still answers 403 without
+the portal key.
 amount, the token, the payee and the deadline, then signs on the device.
 
 The app is three static files with no dependencies and no build step. It carries

package/dist/cli.js

@@ -14,7 +14,8 @@
 // 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 { existsSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+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";
@@ -406,6 +407,49 @@ removed from ${path}. this machine can no longer approve anything by itself.
 sell with:  paydlux sell --split --tls
 `);
 }
+// --------------------------------------------------------------------- withdraw
+/**
+ * Take your money back out of the vault. This is a normal 2-of-2 payment:
+ * principal (this laptop) + approver (your phone, or the laptop until you run
+ * `approver --forget`). The agent key cannot do this — it has no path to an
+ * arbitrary destination, which is the whole point of the vault.
+ *
+ * The XLM the vault pays in ledger rent stays locked while the account exists.
+ * Closing the vault (not done here) returns that too.
+ */
+async function withdraw() {
+    const { data } = loadVault();
+    const to = arg("to");
+    const amount = arg("amount");
+    const all = flag("all");
+    if (!to)
+        bad(`where should it go?\n\n  paydlux withdraw --to G… [--all | --amount 8]\n\n  --to can be any Stellar account, including your Binance deposit address.`);
+    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),
+    }, (data.network ?? "testnet"));
+    if (data.token.code === "USDC")
+        vault.useUsdc();
+    const bal = await vault.balance();
+    const want = all ? bal : amount;
+    if (!want)
+        bad(`say how much: --all, or --amount 8 (vault holds ${bal} ${data.token.code})`);
+    if (Number(want) > Number(bal))
+        bad(`the vault holds ${bal} ${data.token.code}, not ${want}.`);
+    const keys = data.keys ?? {};
+    const principal = Keypair.fromSecret(keys.principal);
+    const approver = keys.approver ? Keypair.fromSecret(keys.approver) : null;
+    if (!approver) {
+        console.log(`this laptop holds only one of the two keys, so the withdrawal needs your phone.
+  open:  ${flag("tls") ? `https://${PUBLIC_HOST}` : "http://127.0.0.1:4022"}/?k=${data.desk?.portalKey ?? "…"}`);
+        bad("then run this again — approvals from the phone land automatically.");
+    }
+    console.log(`sending ${want} ${data.token.code} from the vault to ${to} …`);
+    const res = await vault.release(to, String(want), principal, approver, "paydlux withdraw");
+    console.log(`done. tx ${res?.hash}`);
+    console.log(`vault now holds ${await vault.balance()} ${data.token.code}`);
+}
 // ------------------------------------------------------------------------- main
 const HELP = `paydlux — get paid by AI agents, with a human in the loop.
 
@@ -418,6 +462,9 @@ const HELP = `paydlux — get paid by AI agents, with a human in the loop.
   paydlux approver [--forget]
       print the human half of the vault, then optionally delete it from this
       machine so only the phone can approve.
+  paydlux withdraw --to G… [--all | --amount N]
+      take your money back out of the vault. Needs both human keys; the agent
+      key can never do this.
 
 one file holds it all: ./paydlux-vault.json (0600, never commit it)
 `;
@@ -435,9 +482,17 @@ export async function main() {
         return status();
     if (cmd === "approver")
         return approver();
+    if (cmd === "withdraw")
+        return withdraw();
     bad(`unknown command "${cmd}".\n\n${HELP}`);
 }
-// Only run when this file is the entry point, so importing it in a test is safe.
-if (process.argv[1] && /cli\.(ts|js)$/.test(process.argv[1])) {
+// Run only when this file is the entry point, so importing it in a test is safe.
+// Compare realpaths, not the invocation string: npm's bin launcher runs this as
+// .../node_modules/.bin/paydlux, which does not end in .js, so a name-based test
+// silently turns the published `paydlux` command into a no-op.
+const invoked = process.argv[1]
+    ? pathToFileURL(existsSync(process.argv[1]) ? realpathSync(process.argv[1]) : process.argv[1]).href
+    : undefined;
+if (invoked === import.meta.url) {
     main().catch((e) => { console.error("failed:", e.message); process.exit(1); });
 }

package/dist/desk.d.ts

@@ -85,7 +85,23 @@ export declare class ApprovalDesk {
      * ledger rejects it if the signature is not over this exact transaction.
      */
     complete(id: string, signedXdr: string): Promise<DeskRecord>;
+    /**
+     * 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: string, reason?: string): DeskRecord;
+    /**
+     * 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(): Record<string, unknown>[];
     /** Serve the pending list as JSON (the portal polls this). */
     api(handler: (req: IncomingMessage, res: ServerResponse) => void): (req: IncomingMessage, res: ServerResponse) => void;
     listen(port?: number): Promise<void>;

package/dist/desk.js

@@ -31,25 +31,34 @@ const staticCache = 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.
+ *
+ * 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.
  */
 function readStatic(dir, name, label) {
-    const safe = name.replace(/[^a-z.]/g, "");
+    const safe = name.replace(/[^a-z0-9._-]/g, "");
     const hit = staticCache.get(dir + "/" + safe);
     if (hit)
         return hit;
     let text;
     try {
-        text = readFileSync(join(dir, safe), "utf8");
+        text = safe.endsWith(".png")
+            ? readFileSync(join(dir, safe))
+            : readFileSync(join(dir, safe), "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) + ")");
+        // 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.
+        return null;
     }
     staticCache.set(dir + "/" + safe, text);
     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. */
@@ -258,16 +267,51 @@ export class ApprovalDesk {
         }
         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 +373,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 +467,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 +500,11 @@ export class ApprovalDesk {
                     return send(200, {
                         id: rec.id, network: rec.challenge.network,
                         hash: rec.challenge.hash, xdr: rec.challenge.xdr,
+                        // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paydlux/agent",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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",