@paydlux/agent 0.1.9 → 0.1.11

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/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);
@@ -407,6 +516,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.
 
@@ -419,6 +571,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)
 `;
@@ -436,6 +591,8 @@ export async function main() {
         return status();
     if (cmd === "approver")
         return approver();
+    if (cmd === "withdraw")
+        return withdraw();
     bad(`unknown command "${cmd}".\n\n${HELP}`);
 }
 // Run only when this file is the entry point, so importing it in a test is safe.

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;
@@ -85,7 +119,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>;