@paydlux/agent 0.1.6 → 0.1.8

package/README.md

@@ -114,6 +114,62 @@ npm install @paydlux/agent
 import { StellarVault, Gateway, PaydluxAgent } from "@paydlux/agent";
 ```
 
+### Seller setup, in full (the four things that bite)
+
+A stranger following only the previous version of this README hit four walls.
+All four are in the code; here they are up front.
+
+```ts
+import { Keypair } from "@stellar/stellar-sdk";
+import { StellarVault, Gateway } from "@paydlux/agent";
+
+const issuer = Keypair.random(), principal = Keypair.random();
+const approver = Keypair.random(), agent = Keypair.random();
+const payee = Keypair.random();
+
+await StellarVault.fundTestnet(issuer);          // testnet only
+await StellarVault.fundTestnet(payee);
+const vault = await StellarVault.create({
+  network: "testnet", issuer, principal, approver, agent, tokenCode: "USDC",
+});
+await vault.trustToken(payee.publicKey(), "1000", payee);   // payee must trust the token
+await vault.deposit("50", issuer);                          // vault must hold the money
+
+const gw = new Gateway({
+  vault, network: "testnet", payee: payee.publicKey(),
+  routes: [{ uri: "/api/data", price: "1.00", mode: "approval" }],
+  principal: principal.secret(),
+  approver: approver.secret(),      // omit this + set `split: true` to approve on a phone
+  agentKeys: [agent.publicKey()],   // (1) without it, no agent can park a payment
+  deskPort: 4022,
+  portalKey: newPortalKey(),        // (2) required before the desk is public
+  deskUrl: "https://desk.example.com",  // (3) what the buyer is told, not loopback
+});
+
+await gw.listen(8080, (uri) => myPayload(uri));
+await gw.desk.listen(4022);         // (4) gw.listen() does NOT start the desk
+```
+
+1. **`agentKeys`** — an intent is only honoured if signed by a listed key. Empty
+   list means nothing can request approval, and the failure looks like a plain
+   402 with no explanation.
+2. **`portalKey`** — the approval page has no login. The key *is* the
+   authentication, so it is a 22-character secret in the link. A desk configured
+   with a public hostname refuses to start without one.
+3. **`deskUrl`** — the 202 the buyer gets says where a human approves. It
+   defaults to `http://127.0.0.1:4022`, which is only right when buyer and
+   seller share a machine.
+4. **`gw.desk.listen(port)`** — the gateway and the desk are two HTTP servers.
+   Starting the gateway alone leaves the queue unreachable.
+
+The buyer side needs the agent **secret**, not the vault's signer list:
+
+```ts
+const agent = new PaydluxAgent({ agentKey: process.env.AGENT_KEY! });
+const res = await agent.get("https://seller.example.com/api/data", { mandate });
+if (!res.ok && res.handle) console.log("parked, awaiting a human at", res.desk);
+```
+
 `npm run build` produces `dist/`. The package depends only on
 `@stellar/stellar-sdk` — no transitive `toml`, so `npm audit` is clean.
 

package/dist/agent.d.ts

@@ -19,7 +19,10 @@ export type PayResponse<T = string> = {
     tx?: string;
     /** set when a human has to approve */
     handle?: string;
+    /** where a human approves (the seller's desk) */
     desk?: string;
+    /** where THIS buyer polls for the answer (the gateway, no key needed) */
+    statusUrl?: string;
     reason?: string;
     requirements?: any;
 };
@@ -44,6 +47,13 @@ export declare class PaydluxAgent {
     /**
      * Wait for a human to decide on an approval-mode payment.
      * Returns the settled record, or null on deny/timeout.
+     *
+     * Pass the response you got from get() — that is the whole point of the
+     * handle. It carries the exact URL to poll. Poll the GATEWAY, never the desk:
+     * the desk is the human's surface, gated behind a portal key, and whoever
+     * holds that key can approve. A buyer must never have it. The gateway's
+     * status route answers for a handle it handed out and reveals only what the
+     * buyer already knows (id, price, status) plus the tx hash once it settles.
      */
-    waitForApproval(desk: string, handle: string): Promise<any>;
+    waitForApproval(res: PayResponse | string, handle?: string): Promise<any>;
 }

package/dist/agent.js

@@ -40,8 +40,15 @@ export class PaydluxAgent {
                 headers: { [PAY_HEADER]: JSON.stringify({ intent }) },
             });
             const j = await parked.json().catch(() => ({}));
-            return { ok: false, status: parked.status, handle: j.handle, desk: j.desk, requirements: reqs,
-                reason: "a human has to approve this payment" };
+            // A 200 here means the human already approved this request — the seller
+            // serves the content on the retry. Reporting "needs approval" in that case
+            // would leave a buyer polling forever for a payment that is already paid.
+            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,
+                statusUrl: j.statusUrl, requirements: reqs,
+                reason: j.reason ?? "a human has to approve this payment" };
         }
         if (!opts.mandate) {
             return { ok: false, status: 402, requirements: reqs,
@@ -77,18 +84,38 @@ export class PaydluxAgent {
     /**
      * Wait for a human to decide on an approval-mode payment.
      * Returns the settled record, or null on deny/timeout.
+     *
+     * Pass the response you got from get() — that is the whole point of the
+     * handle. It carries the exact URL to poll. Poll the GATEWAY, never the desk:
+     * the desk is the human's surface, gated behind a portal key, and whoever
+     * holds that key can approve. A buyer must never have it. The gateway's
+     * status route answers for a handle it handed out and reveals only what the
+     * buyer already knows (id, price, status) plus the tx hash once it settles.
      */
-    async waitForApproval(desk, handle) {
+    async waitForApproval(res, handle) {
         const f = this.cfg.fetch ?? fetch;
+        const url = typeof res === "string"
+            ? `${res.replace(/\/+$/, "")}/pay/status?handle=${encodeURIComponent(handle ?? "")}`
+            : (res.statusUrl ?? `${res.desk?.replace(/\/+$/, "")}/list`);
+        const want = typeof res === "string" ? handle : res.handle;
+        if (!want)
+            throw new Error("nothing to wait on: this response has no payment handle");
         const deadline = Date.now() + this.cfg.approvalTimeoutMs;
         while (Date.now() < deadline) {
-            const r = await f(`${desk}/list`).then((x) => x.json()).catch(() => []);
-            const rec = r.find((x) => x.id === handle);
-            if (rec && rec.status === "settled")
-                return rec;
-            if (rec && (rec.status === "denied" || rec.status === "failed"))
-                return rec;
-            await new Promise((res) => setTimeout(res, this.cfg.pollMs));
+            const r = await f(url).catch(() => null);
+            if (!r?.ok) {
+                // A desk /list fallback needs the portal key, so it 403s for a buyer.
+                // That is correct behaviour, not a bug to work around.
+                if (url.endsWith("/list"))
+                    throw new Error("cannot poll the desk for status — pass the response from get(), which carries statusUrl");
+                await new Promise((res2) => setTimeout(res2, this.cfg.pollMs));
+                continue;
+            }
+            const rec = await r.json().catch(() => null);
+            const found = Array.isArray(rec) ? rec.find((x) => x.id === want) : rec;
+            if (found && found.status !== "pending" && found.status !== "awaiting_phone")
+                return found;
+            await new Promise((res2) => setTimeout(res2, this.cfg.pollMs));
         }
         return null;
     }

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+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;
+};
+export declare function main(): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,443 @@
+#!/usr/bin/env node
+// paydlux — the seller app. One command, no repo checkout, no config file to
+// hand-edit.
+//
+//   paydlux setup                 create a vault (testnet by default)
+//   paydlux sell                  start the gateway + approval desk
+//   paydlux status                what a vault holds and who can sign for it
+//
+// Everything reads one file, ./paydlux-vault.json, which `setup` writes. That
+// file holds the vault's private keys, so it is 0600 and it is in .gitignore.
+//
+// This is the difference between a demo and a product: before, running Paydlux
+// meant reading stellar/demo.ts and editing an array of routes in TypeScript.
+// 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 { resolve } from "node:path";
+import { Keypair } from "@stellar/stellar-sdk";
+import { StellarVault, USDC_ISSUER } from "./vault.js";
+import { Gateway } from "./gateway.js";
+import { newPortalKey } from "./desk.js";
+import { PolicyEngine } from "./policy.js";
+import { PUBLIC_HOST, runTunnel, tunnelLive, tunnelProblem } from "./tunnel.js";
+export const VAULT_FILE_DEFAULT = "paydlux-vault.json";
+const arg = (name) => {
+    const i = process.argv.indexOf(`--${name}`);
+    return i > -1 ? process.argv[i + 1] : undefined;
+};
+const flag = (name) => process.argv.includes(`--${name}`);
+const log = (...a) => console.log("•", ...a);
+/** Print a reason and stop. Declared as a function (not an arrow in a const) so
+ *  TypeScript's control-flow analysis actually narrows the caller after it. */
+function bad(msg) { console.error("\n" + msg + "\n"); process.exit(1); }
+/** The one file that holds everything. Refuses to read a file that is world-readable. */
+export function loadVault(path = resolve(process.cwd(), arg("file") ?? VAULT_FILE_DEFAULT)) {
+    if (!existsSync(path)) {
+        bad(`no vault here. Run:  paydlux setup`);
+    }
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    if (!data.keys?.principal)
+        bad(`${path} has no keys.principal — it is not a Paydlux vault file`);
+    return { path, data };
+}
+function pub(seed) { return Keypair.fromSecret(seed).publicKey(); }
+/**
+ * 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.
+ */
+function deskKeys(path, data) {
+    if (!data.desk)
+        data.desk = {};
+    if (!data.desk.portalKey) {
+        data.desk.portalKey = newPortalKey();
+        data.desk.createdAt = new Date().toISOString();
+        writeFileSync(path, JSON.stringify(data, null, 2));
+        chmodSync(path, 0o600);
+    }
+    return data.desk.portalKey;
+}
+// ------------------------------------------------------------------------ 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`);
+    const price = arg("price") ?? data.policy?.defaultPrice ?? "1";
+    if (!(Number(price) > 0))
+        bad("--price must be a positive number");
+    const uri = arg("route") ?? "/api/data";
+    const mode = flag("preauth") ? "preauth" : "approval";
+    const tls = flag("tls");
+    const split = flag("split");
+    // Real money gets a hard ceiling, and it is not a suggestion. The ledger
+    // already caps a single payment at the mandate amount; what it cannot do is
+    // count payments. So the ceiling lives here, and it is applied before the
+    // desk is even built.
+    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);
+    if (data.token.code === "USDC")
+        vault.useUsdc();
+    if (network === "public") {
+        console.log(`
+  MAINNET — real money.
+    token            ${data.token.code}
+    max per payment  ${maxPer}
+    daily budget     ${daily}
+    vault            ${vault.address}
+    balance          ${await vault.balance()} ${data.token.code}
+`);
+        if (!flag("yes") && process.stdin.isTTY) {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            const ans = await rl.question("  every payment here is real and irreversible. continue? [y/N] ");
+            rl.close();
+            if (!/^y(es)?$/i.test(ans.trim()))
+                bad("stopped. nothing was started.");
+        }
+    }
+    // A vault that cannot pay its ledger rent stops working with a confusing
+    // error, so say what is actually wrong before starting anything.
+    const rent = await vaultRent(vault);
+    if (rent.short) {
+        bad(`the vault is short of XLM for its own ledger rent.\n  needs ${rent.min} XLM, has ${rent.xlm} XLM.\n  send more XLM to ${vault.address} and try again.`);
+    }
+    const portalKey = deskKeys(path, data);
+    const publicHost = tls ? PUBLIC_HOST : (arg("host") ?? undefined);
+    const deskPort = Number(arg("desk") ?? 4022);
+    const gwPort = Number(arg("port") ?? 4021);
+    const gw = new Gateway({
+        vault, network, payee,
+        deskPort,
+        principal: keys.principal,
+        // --split is the honest mode: this process cannot approve anything.
+        approver: split ? undefined : keys.approver,
+        split,
+        portalKey,
+        publicHost,
+        agentKeys: [pub(keys.agent)],
+        routes: [{ uri, price, mode, holdSeconds: Number(arg("hold") ?? 3600) }],
+    });
+    let tunnel = null;
+    if (tls) {
+        const problem = tunnelProblem();
+        if (problem)
+            bad("--tls cannot run here: " + problem);
+        tunnel = runTunnel();
+    }
+    await gw.listen(gwPort, (u) => JSON.stringify({
+        served: u, at: new Date().toISOString(),
+        note: "paid through Paydlux; the payment is on the Stellar ledger",
+    }));
+    await gw.desk.listen(deskPort);
+    const deskUrl = tls ? `https://${PUBLIC_HOST}` : `http://127.0.0.1:${deskPort}`;
+    if (tls) {
+        const live = await tunnelLive();
+        log(live ? `desk is live at https://${PUBLIC_HOST}` : `tunnel started but https://${PUBLIC_HOST} is not answering yet`);
+        if (!live) {
+            const why = tunnel?.lastError();
+            log(why ? "tunnel said: " + why : "give it a few seconds, then open the link");
+        }
+    }
+    console.log(`
+  selling ${uri} for ${price} ${data.token.code}   (${mode})
+  gateway    http://127.0.0.1:${gwPort}${uri}
+  approvals  ${deskUrl}/?k=${portalKey}
+  phone      ${deskUrl}/phone/?k=${portalKey}
+
+  paste into your bot:
+      import { PaydluxAgent } from "@paydlux/agent";
+      const agent = new PaydluxAgent({ agentKey: "${keys.agent}", network: "${network}" });
+      const res = await agent.get("http://127.0.0.1:${gwPort}${uri}");
+
+  ${split
+        ? "approvals need your phone. this machine holds one of the two keys."
+        : "WARNING: this process holds BOTH human keys. Anyone with this machine can approve. Use --split for anything real."}
+  policy: max ${maxPer} per payment, ${daily} per day
+  ctrl-c to stop
+`);
+    // The desk is a queue, not a database. If it dies with a payment parked, the
+    // buyer is waiting on nothing, so say so rather than exiting silently.
+    const bye = () => {
+        const open = gw.desk.list().filter((r) => r.status === "pending" || r.status === "awaiting_phone");
+        if (open.length)
+            console.log(`\n  stopping with ${open.length} payment(s) still waiting: ${open.map((r) => r.id).join(", ")}`);
+        if (tunnel && !tunnel.proc.killed)
+            tunnel.proc.kill("SIGTERM");
+        process.exit(0);
+    };
+    process.on("SIGINT", bye);
+    process.on("SIGTERM", bye);
+}
+/** XLM the vault must hold to exist, versus what it actually has. */
+async function vaultRent(vault) {
+    const acc = await vault.horizon.loadAccount(vault.address);
+    const xlm = acc.balances.find((b) => b.asset_type === "native")?.balance ?? "0";
+    const min = ((2 + (acc.subentry_count ?? 0)) * 0.5).toFixed(1);
+    return { xlm, min, short: Number(xlm) < Number(min) };
+}
+// ---------------------------------------------------------------------- status
+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);
+    if (data.token.code === "USDC")
+        vault.useUsdc();
+    const rent = await vaultRent(vault);
+    const signers = await vault.signerSummary();
+    const live = signers.signers.filter((s) => s.type === "preauth-mandate");
+    console.log(`
+  network   ${network}
+  vault     ${vault.address}
+  token     ${data.token.code} (${data.token.issuer.slice(0, 8)}…)
+  balance   ${await vault.balance()} ${data.token.code}
+  xlm rent  ${rent.xlm} / ${rent.min} XLM  ${rent.short ? "SHORT — payments will fail" : "ok"}
+  payee     ${data.payee?.address ?? "(not set)"}
+  thresholds ${JSON.stringify(signers.thresholds)}
+  signers   ${signers.signers.map((s) => `${s.type}${s.weight === 0 ? " (off)" : ""}`).join(", ")}
+  live mandates ${live.length}
+  explorer  https://stellar.expert/explorer/${network === "public" ? "account" : "testnet/account"}/${vault.address}
+`);
+}
+// ----------------------------------------------------------------------- setup
+/**
+ * Create a vault. Testnet is the default and needs nothing from you.
+ * --mainnet is a different conversation: it needs a wallet to fund the accounts
+ * and it puts real XLM and real USDC into play, so it asks before spending.
+ */
+async function setup() {
+    const mainnet = flag("mainnet");
+    const network = mainnet ? "public" : "testnet";
+    const file = resolve(process.cwd(), arg("file") ?? VAULT_FILE_DEFAULT);
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ask = async (q, def) => process.stdin.isTTY ? (await rl.question(`${q} [${def}]: `)).trim() || def : def;
+    if (existsSync(file) && !flag("force")) {
+        const ans = await ask(`${file} already exists. Overwrite? [y/N] `, "n");
+        if (!/^y(es)?$/i.test(ans.trim())) {
+            console.log("keeping the existing vault.");
+            rl.close();
+            return;
+        }
+    }
+    const code = ((arg("token") ?? await ask("token for your payments", mainnet ? "USDC" : "AGPAY")) || "AGPAY").toUpperCase();
+    const budget = Number(arg("max") ?? await ask("max per payment", mainnet ? "2" : "10"));
+    const daily = Number(arg("daily") ?? await ask("daily budget", mainnet ? "10" : "50"));
+    if (mainnet && code !== "USDC") {
+        bad("on mainnet this first release only supports USDC. Custom tokens need an issuer key you would have to hold and protect — not a first-money decision.");
+    }
+    rl.close();
+    console.log(`\nPaydlux setup — Stellar ${network}${mainnet ? " (REAL MONEY)" : ""}\n`);
+    const principal = Keypair.random(), approver = Keypair.random(), agent = Keypair.random();
+    const payee = Keypair.random();
+    const issuer = code === "USDC" ? null : Keypair.random();
+    // The account that pays the XLM for creating everything. On testnet that is
+    // friendbot. On mainnet it has to be a wallet the human already controls.
+    let funder;
+    if (!mainnet) {
+        if (!issuer)
+            throw new Error("internal: a custom token needs an issuer key");
+        console.log("funding on testnet (friendbot, no captcha)…");
+        for (const k of [issuer, principal, approver, payee])
+            await StellarVault.fundTestnet(k);
+        funder = issuer;
+    }
+    else {
+        const seed = arg("fund-seed") ?? process.env.PAYDLUX_FUND_SEED;
+        if (!seed) {
+            bad(`mainnet needs a wallet to pay the account-creation costs.
+
+  paydlux setup --mainnet --fund-seed S…
+
+  The wallet only needs a few XLM (about 8 XLM covers everything here, at
+  ~0.17 USDT per XLM). It is used to CREATE two accounts; it cannot touch the
+  vault afterwards, because the vault's own keys are made fresh right now and
+  its master key is switched off in the same transaction that creates it.`);
+        }
+        funder = Keypair.fromSecret(seed);
+        const h = new (await import("@stellar/stellar-sdk")).Horizon.Server("https://horizon.stellar.org");
+        const acc = await h.loadAccount(funder.publicKey()).catch(() => null);
+        if (!acc)
+            bad(`the funding wallet ${funder.publicKey()} does not exist on mainnet. Send it some XLM first.`);
+        const xlm = acc.balances.find((b) => b.asset_type === "native")?.balance ?? "0";
+        if (Number(xlm) < 8)
+            bad(`the funding wallet has ${xlm} XLM. Creating a vault + a payee account needs about 8 XLM.`);
+        console.log(`funding wallet ${funder.publicKey()} — ${xlm} XLM`);
+    }
+    console.log("creating the 2-of-2 vault…");
+    const vault = await StellarVault.create({
+        network,
+        issuer: funder,
+        principal, approver, agent,
+        tokenCode: code,
+        tokenIssuer: code === "USDC" ? USDC_ISSUER[network] : undefined,
+        // mainnet: 2 base reserves + 3 signers + 1 trustline = 3 XLM locked, plus
+        // room for one live mandate (0.5 XLM) and fees. 5 leaves a margin.
+        startingBalance: mainnet ? "5" : undefined,
+    });
+    console.log("vault created. master key is off: it can never act alone again.");
+    // A Stellar account must exist before it can be paid, and a payment cannot
+    // create one — only createAccount can. And holding a token is not automatic:
+    // the receiving account has to open a trustline first, or the payment fails
+    // with OP_NO_TRUST. This is the single most common reason a first real
+    // payment is rejected, so it happens here, once, at setup.
+    if (mainnet) {
+        console.log("creating the payee account (2 XLM) and its USDC trustline…");
+        const { Horizon, TransactionBuilder, Operation, Account, Networks } = await import("@stellar/stellar-sdk");
+        const h = new Horizon.Server("https://horizon.stellar.org");
+        const fa = await h.loadAccount(funder.publicKey());
+        const t1 = new TransactionBuilder(new Account(funder.publicKey(), fa.sequence), { fee: "100", networkPassphrase: Networks.PUBLIC })
+            .addOperation(Operation.createAccount({ destination: payee.publicKey(), startingBalance: "2" }))
+            .setTimeout(120).build();
+        t1.sign(funder);
+        await h.submitTransaction(t1);
+    }
+    await vault.trustToken(payee.publicKey(), "100000", payee);
+    console.log("payee account ready and trusted for " + code + ".");
+    if (issuer)
+        await vault.deposit(String(daily), issuer);
+    const data = {
+        createdAt: new Date().toISOString(),
+        network,
+        vault: vault.address,
+        token: { code, issuer: code === "USDC" ? USDC_ISSUER[network] : issuer.publicKey() },
+        policy: { maxPerPayment: budget, dailyBudget: daily, defaultPrice: mainnet ? "1" : "2" },
+        payee: { address: payee.publicKey(), seed: payee.secret() },
+        keys: {
+            principal: principal.secret(),
+            approver: approver.secret(),
+            agent: agent.secret(),
+            ...(issuer ? { issuer: issuer.secret() } : {}),
+        },
+        explorer: `https://stellar.expert/explorer/${network === "public" ? "account" : "testnet/account"}/${vault.address}`,
+    };
+    writeFileSync(file, JSON.stringify(data, null, 2));
+    chmodSync(file, 0o600);
+    console.log(`
+done.
+
+  vault account   ${vault.address}
+  payee account   ${payee.publicKey()}
+  balance         ${await vault.balance()} ${code}
+  keys written to ${file}  (permissions 0600 — treat like a password)
+`);
+    if (mainnet) {
+        console.log(`next — put real money in it:
+  1. send ${daily} USDC to ${vault.address}
+     (from any exchange or wallet that supports USDC on Stellar; the vault
+      already trusts Circle USDC, so the transfer will land)
+  2. check it arrived:   paydlux status
+  3. start selling:      paydlux sell --split --tls
+
+  keep the approver key off this machine:
+     paydlux sell --split   prints the approver seed for your phone only
+`);
+    }
+    else {
+        console.log(`next:
+  1. start selling:   paydlux sell
+  2. open approvals:  http://127.0.0.1:4022
+  3. hand the agent key to your bot (printed by paydlux sell)
+
+the agent key is ONE of two signatures. It cannot spend on its own.
+`);
+    }
+}
+// -------------------------------------------------------------------- approver
+/**
+ * The approver key is the human's half of the vault. While it sits in
+ * paydlux-vault.json on this laptop, this machine can approve its own payments
+ * and the 2-of-2 vault is really 1-of-1 with extra steps.
+ *
+ * `paydlux approver` prints it once so it can be put on the phone.
+ * `paydlux approver --forget` then deletes it from this machine for good: the
+ * laptop keeps the principal half, the phone holds the other, and neither can
+ * release money alone. That is the point of the design, so it is a command and
+ * not a paragraph in a README.
+ */
+async function approver() {
+    const { path, data } = loadVault();
+    const forget = flag("forget");
+    const seed = data.keys?.approver;
+    if (!seed) {
+        console.log(`no approver key on this machine — approvals already need your phone.
+  sell with:  paydlux sell --split --tls`);
+        return;
+    }
+    const pub = Keypair.fromSecret(seed).publicKey();
+    const portalKey = data.desk?.portalKey;
+    const host = flag("tls") || portalKey ? `https://${PUBLIC_HOST}` : `http://127.0.0.1:4022`;
+    console.log(`
+approver key (the human half of the vault)
+
+  public   ${pub}
+  secret   ${seed}
+
+Put that secret on the phone approver. It is the only thing that can release
+money besides this laptop, so anyone holding it can spend up to your cap.
+
+phone link:  ${host}/phone/?k=${portalKey ?? "(run paydlux sell --tls first)"}
+`);
+    if (!forget) {
+        console.log("this laptop still holds it, so it can still approve alone.\n"
+            + "when the phone is set up, run:\n\n  paydlux approver --forget\n");
+        return;
+    }
+    // Confirm: deleting this is irreversible unless the seed was written down.
+    if (process.stdin.isTTY) {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const ans = await rl.question("  the phone has it and you do not need it here again. delete? [y/N] ");
+        rl.close();
+        if (!/^y(es)?$/i.test(ans.trim())) {
+            console.log("kept. nothing changed.");
+            return;
+        }
+    }
+    delete data.keys.approver;
+    data.keys.approverRemovedAt = new Date().toISOString();
+    writeFileSync(path, JSON.stringify(data, null, 2));
+    chmodSync(path, 0o600);
+    console.log(`
+removed from ${path}. this machine can no longer approve anything by itself.
+sell with:  paydlux sell --split --tls
+`);
+}
+// ------------------------------------------------------------------------- main
+const HELP = `paydlux — get paid by AI agents, with a human in the loop.
+
+  paydlux setup [--mainnet] [--token USDC] [--fund-seed S…]
+      create a vault. testnet by default (free, no wallet needed).
+  paydlux sell  [--price 1] [--route /api/data] [--split] [--tls] [--preauth]
+      start the gateway and the approval desk.
+  paydlux status
+      balances, signers, live mandates, ledger rent.
+  paydlux approver [--forget]
+      print the human half of the vault, then optionally delete it from this
+      machine so only the phone can approve.
+
+one file holds it all: ./paydlux-vault.json (0600, never commit it)
+`;
+export async function main() {
+    const cmd = process.argv[2];
+    if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
+        console.log(HELP);
+        return;
+    }
+    if (cmd === "setup")
+        return setup();
+    if (cmd === "sell")
+        return sell();
+    if (cmd === "status")
+        return status();
+    if (cmd === "approver")
+        return approver();
+    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])) {
+    main().catch((e) => { console.error("failed:", e.message); process.exit(1); });
+}

package/dist/desk.d.ts

@@ -14,6 +14,12 @@ export type DeskRecord = {
     content?: string;
     tx?: string;
     reason?: string;
+    /**
+     * Dedupe key: same buyer + same request + same price. Without it, every retry
+     * after an approval parks a NEW payment, so a human approving twice pays
+     * twice and the buyer never gets the content they already bought.
+     */
+    key?: string;
     /** split mode: what the phone is asked to sign, and what it sent back */
     challenge?: ApprovalChallenge;
     qr?: string;
@@ -54,7 +60,10 @@ export declare class ApprovalDesk {
     private server?;
     cfg: DeskConfig;
     constructor(cfg: DeskConfig);
-    enqueue(uri: string, price: string, body: string, content: string): string;
+    enqueue(uri: string, price: string, body: string, content: string, key?: string): string;
+    /** Every record carrying this key, newest first. */
+    allByKey(key: string): DeskRecord[];
+    findByKey(key: string): DeskRecord | null;
     get(id: string): DeskRecord | null;
     list(): DeskRecord[];
     /**

package/dist/desk.js

@@ -130,12 +130,30 @@ export class ApprovalDesk {
     server;
     cfg;
     constructor(cfg) { this.cfg = cfg; }
-    enqueue(uri, price, body, content) {
+    enqueue(uri, price, body, content, key) {
+        // Re-use an existing request for the same buyer + body + price. A buyer who
+        // retries after a human approved must get their content, not a second
+        // payment waiting in the queue. Settled records are NOT reused here — the
+        // gateway decides how long a paid-for request stays free to collect.
+        if (key) {
+            const hit = this.allByKey(key).find((r) => r.status === "pending" || r.status === "awaiting_phone");
+            if (hit)
+                return hit.id;
+        }
         const id = `pay_${(++this.seq).toString().padStart(4, "0")}`;
-        this.records.set(id, { id, at: Date.now(), uri, price, body, status: "pending", content });
+        this.records.set(id, { id, at: Date.now(), uri, price, body, status: "pending", content, key });
         console.log(`[desk] ${id} awaiting a human: ${price} for ${uri}`);
         return id;
     }
+    /** Every record carrying this key, newest first. */
+    allByKey(key) {
+        if (!key)
+            return [];
+        return [...this.records.values()].filter((r) => r.key === key).sort((a, b) => b.at - a.at);
+    }
+    findByKey(key) {
+        return this.allByKey(key)[0] ?? null;
+    }
     get(id) { return this.records.get(id) ?? null; }
     list() { return [...this.records.values()]; }
     /**
@@ -417,6 +435,32 @@ export class ApprovalDesk {
                 }
                 const m = url.pathname.match(/^\/(approve|deny|signed)\/([\w-]+)$/);
                 if (m && req.method === "POST") {
+                    // These routes move money, so they must not be reachable from another
+                    // page. A cross-origin fetch POST is a CORS *simple request*: no
+                    // preflight, so the attacker's page never sees the reply but the
+                    // approval still happens. Verified end to end: a page on another port
+                    // settled a parked payment and paid the seller. Browsers always send
+                    // Origin on POST and Sec-Fetch-Site on every request, so checking both
+                    // closes that path while leaving local automation (curl, tests, the
+                    // phone app on its own origin) alone.
+                    const origin = String(req.headers.origin ?? "");
+                    if (origin) {
+                        const here = String(req.headers.host ?? "").toLowerCase();
+                        let oh;
+                        try {
+                            oh = new URL(origin).host.toLowerCase();
+                        }
+                        catch {
+                            oh = "";
+                        }
+                        if (oh !== here) {
+                            return send(403, { error: "cross_origin", reason: `this desk only accepts actions from itself, not from ${origin}` });
+                        }
+                    }
+                    const site = String(req.headers["sec-fetch-site"] ?? "").toLowerCase();
+                    if (site && site !== "same-origin" && site !== "none") {
+                        return send(403, { error: "cross_origin", reason: `this desk only accepts same-site actions (got ${site})` });
+                    }
                     if (m[1] === "signed") {
                         const body = await readBody(req);
                         const { signedXdr } = JSON.parse(body || "{}");

package/dist/gateway.d.ts

@@ -9,6 +9,11 @@ export type Route = {
     mode: "preauth" | "approval";
     /** seconds the seller's content stays reserved while a human decides */
     holdSeconds?: number;
+    /**
+     * How long one approved payment keeps buying this route. Defaults to
+     * holdSeconds. Set it to 0 to make every single call cost its own approval.
+     */
+    collectSeconds?: number;
 };
 export type GatewayConfig = {
     vault: StellarVault;
@@ -32,6 +37,19 @@ export type GatewayConfig = {
     portalKey?: string;
     /** hostname the desk is publicly served on; pins the Host header. See DeskConfig. */
     publicHost?: string;
+    /**
+     * 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
+     * 402 instead of a queue entry. Leave empty and nothing can request approval.
+     */
+    agentKeys?: string[];
+    /**
+     * Where a human approves, as the BUYER should see it. Set this to the public
+     * desk URL (e.g. "https://desk.paydlux.com") when the desk is reachable there;
+     * it is returned in the 202 so the buyer knows where to go. Defaults to the
+     * loopback address, which is only useful on one machine.
+     */
+    deskUrl?: string;
 };
 export type PaymentProof = {
     /** pre-authorised envelope, base64 XDR, as issued by the vault */
@@ -56,6 +74,13 @@ export declare class Gateway {
     syncMandates(): Promise<any>;
     /** Register a pre-authorised mandate for a route (needs both human keys). */
     authorise(uri: string, spec: Parameters<StellarVault["createMandate"]>[0], principal: Parameters<StellarVault["createMandate"]>[1], approver: Parameters<StellarVault["createMandate"]>[2]): Promise<Mandate>;
+    /**
+     * This gateway's own externally visible base URL, as the client sees it.
+     * Behind a TLS proxy (a Cloudflare tunnel) the Host header is the public name
+     * and X-Forwarded-Proto says https, so links handed to a buyer point at the
+     * address they can actually reach instead of a loopback port.
+     */
+    private selfUrl;
     /** The intent must be signed by a real agent key on the vault. */
     private verifyIntent;
     /** Keys allowed to place approval requests. */

package/dist/gateway.js

@@ -13,6 +13,7 @@
 //
 // Either way the agent's key alone can never move money: threshold is 2.
 import { createServer } from "node:http";
+import { createHash } from "node:crypto";
 import { Keypair, StrKey, Transaction } from "@stellar/stellar-sdk";
 import { StellarTxError, hex, passphrase } from "./vault.js";
 import { ApprovalDesk } from "./desk.js";
@@ -26,6 +27,7 @@ export class Gateway {
     cfg;
     constructor(cfg) {
         this.cfg = cfg;
+        this.agentKeys = cfg.agentKeys ?? [];
         for (const r of cfg.routes)
             this.routes.set(r.uri, r);
         this.desk = new ApprovalDesk({
@@ -55,31 +57,46 @@ export class Gateway {
         this.mandates.set(m.hash, m);
         return m;
     }
+    /**
+     * This gateway's own externally visible base URL, as the client sees it.
+     * Behind a TLS proxy (a Cloudflare tunnel) the Host header is the public name
+     * and X-Forwarded-Proto says https, so links handed to a buyer point at the
+     * address they can actually reach instead of a loopback port.
+     */
+    selfUrl(req) {
+        const proto = (req.headers["x-forwarded-proto"] ?? "").toString().split(",")[0].trim()
+            || (this.cfg.publicHost ? "https" : "http");
+        const host = req.headers.host ?? "127.0.0.1";
+        return `${proto}://${host}`;
+    }
     /** The intent must be signed by a real agent key on the vault. */
     verifyIntent(intent) {
         if (!intent?.payload || !intent?.signature)
-            return false;
+            return null;
         const [url, amount, vault] = intent.payload.split("|");
         if (vault !== this.cfg.vault.address)
-            return false;
+            return null;
         if (Number(amount) <= 0)
-            return false;
+            return null;
         const age = Date.now() - Number(intent.payload.split("|").at(-1));
         if (!Number.isFinite(age) || age > 5 * 60 * 1000)
-            return false;
+            return null;
         const msg = Buffer.from(intent.payload);
         const sig = Buffer.from(intent.signature, "base64");
         for (const s of this.agentKeys) {
+            // Returning WHICH key signed it matters downstream: the dedupe key is
+            // built from the buyer's identity, so two different agents asking for the
+            // same resource must not share one queue entry.
             try {
                 if (Keypair.fromPublicKey(s).verify(msg, sig))
-                    return true;
+                    return s;
             }
             catch { /* keep going */ }
         }
-        return false;
+        return null;
     }
     /** Keys allowed to place approval requests. */
-    agentKeys = [];
+    agentKeys;
     requirements(uri) {
         const r = this.routes.get(uri);
         return {
@@ -148,8 +165,21 @@ export class Gateway {
             if (uri === "/pay/status") {
                 const handle = new URL(req.url, "http://x").searchParams.get("handle");
                 const rec = handle ? this.desk.get(handle) : null;
+                // A projection, never the record. The desk record carries `content` —
+                // the payload the seller only ships once money has landed. Handing the
+                // whole object to this ungated route would let anyone holding a handle
+                // read the paid content while the payment still sits pending, which
+                // defeats the entire product. The buyer already knows the id, price and
+                // uri; the tx hash is theirs once it settles. Nothing else goes out.
+                const safe = rec
+                    ? {
+                        id: rec.id, status: rec.status, price: rec.price, uri: rec.uri,
+                        ...(rec.tx ? { tx: rec.tx } : {}),
+                        ...(rec.reason ? { reason: rec.reason } : {}),
+                    }
+                    : { error: "unknown handle" };
                 res.writeHead(rec ? 200 : 404, { "content-type": "application/json" });
-                res.end(JSON.stringify(rec ?? { error: "unknown handle" }));
+                res.end(JSON.stringify(safe));
                 return;
             }
             const r = this.routes.get(uri);
@@ -184,14 +214,75 @@ export class Gateway {
                     res.end(JSON.stringify({ error: "payment_invalid", reason: "approval mode needs a signed intent" }));
                     return;
                 }
-                if (!this.verifyIntent(proof.intent)) {
+                const signer = this.verifyIntent(proof.intent);
+                if (!signer) {
                     res.writeHead(402, { [PAY_HEADER]: JSON.stringify(this.requirements(uri)) });
                     res.end(JSON.stringify({ error: "payment_invalid", reason: "intent signature is not from the agent key" }));
                     return;
                 }
-                const handle = this.desk.enqueue(uri, r.price, body, getContent(uri));
+                // One request per buyer + body + price, not one per HTTP call. A buyer
+                // retries by design (that is how they wait for a human), so without this
+                // each retry parks a fresh payment: the human approves twice, money moves
+                // twice, and the buyer still has no content. The signer is in the key so
+                // two different agents never share one queue entry.
+                const key = createHash("sha256")
+                    .update(`${signer}|${uri}|${r.price}|${body}`).digest("hex");
+                const hit = this.desk.findByKey(key);
+                if (hit) {
+                    // Already paid: hand over the content. This is the whole point of the
+                    // retry. It stays collectable for the route's hold window, then a
+                    // fresh payment is required — otherwise one approval would buy the
+                    // resource forever, which is not what the human agreed to.
+                    if (hit.status === "settled") {
+                        const windowMs = (r.collectSeconds ?? r.holdSeconds ?? 3600) * 1000;
+                        if (Date.now() - hit.at <= windowMs) {
+                            res.writeHead(200, {
+                                "content-type": "application/json",
+                                "x-payment-response": JSON.stringify({ tx: hit.tx }),
+                            });
+                            res.end(JSON.stringify({ data: getContent(uri), tx: hit.tx }));
+                            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") {
+                        res.writeHead(402, { [PAY_HEADER]: JSON.stringify(this.requirements(uri)) });
+                        res.end(JSON.stringify({
+                            error: "payment_denied", handle: hit.id,
+                            reason: hit.reason ?? "denied by the approver",
+                        }));
+                        return;
+                    }
+                    // pending / awaiting_phone: reuse the existing handle.
+                    // failed: the human approved but the ledger refused, so no money moved
+                    // and the buyer is not at fault — park a fresh one below.
+                    if (hit.status === "pending" || hit.status === "awaiting_phone") {
+                        const deskUrl = this.cfg.deskUrl
+                            ?? (this.cfg.publicHost ? `https://${this.cfg.publicHost}` : `http://127.0.0.1:${this.cfg.deskPort ?? 4022}`);
+                        res.writeHead(202, { "content-type": "application/json", "x-payment-hold": hit.id });
+                        res.end(JSON.stringify({
+                            status: "awaiting_approval", handle: hit.id, desk: deskUrl,
+                            statusUrl: `${this.selfUrl(req)}/pay/status?handle=${encodeURIComponent(hit.id)}`,
+                        }));
+                        return;
+                    }
+                }
+                const handle = this.desk.enqueue(uri, r.price, body, getContent(uri), key);
                 res.writeHead(202, { "content-type": "application/json", "x-payment-hold": handle });
-                res.end(JSON.stringify({ status: "awaiting_approval", handle, desk: `http://127.0.0.1:${this.cfg.deskPort ?? 4022}` }));
+                // The buyer needs to know where a human approves. Loopback is only
+                // right when both sides are on one machine; anything real sets deskUrl
+                // (or publicHost) so this points at the https desk.
+                const deskUrl = this.cfg.deskUrl
+                    ?? (this.cfg.publicHost ? `https://${this.cfg.publicHost}` : `http://127.0.0.1:${this.cfg.deskPort ?? 4022}`);
+                // ...and where to poll for the answer. That is THIS gateway, not the
+                // desk: the desk is the human's surface and is gated behind a portal key
+                // the buyer must never hold. Without this the buyer has no way to learn
+                // that a payment was approved and waits until timeout.
+                res.end(JSON.stringify({
+                    status: "awaiting_approval", handle, desk: deskUrl,
+                    statusUrl: `${this.selfUrl(req)}/pay/status?handle=${encodeURIComponent(handle)}`,
+                }));
                 return;
             }
             try {

package/dist/tunnel.d.ts

@@ -0,0 +1,21 @@
+import { type ChildProcess } from "node:child_process";
+export declare function cloudflaredPath(): string | null;
+export declare const TUNNEL_NAME = "paydlux-desk";
+export declare const PUBLIC_HOST = "desk.paydlux.com";
+/** Why this machine cannot run the named tunnel, or null if it can. */
+export declare function tunnelProblem(): string | null;
+/** True if this machine can run the named tunnel. */
+export declare function tunnelReady(): boolean;
+/**
+ * Start the named tunnel and make sure it dies with us. An orphaned cloudflared
+ * is a public approval desk with nobody watching it, so every exit path kills
+ * the child.
+ */
+export interface Tunnel {
+    proc: ChildProcess;
+    /** Why cloudflared failed to start or run, if it did. */
+    lastError(): string | null;
+}
+export declare function runTunnel(): Tunnel;
+/** Is the tunnel actually serving TLS yet? Probes the real URL. */
+export declare function tunnelLive(host?: string, tries?: number): Promise<boolean>;

package/dist/tunnel.js

@@ -0,0 +1,106 @@
+// The named Cloudflare tunnel: real TLS on a domain you control.
+//
+// A trycloudflare.com URL (story.ts --public) is fine for a demo clip and wrong
+// for anything else: the hostname is random and disposable, there is no HSTS,
+// and nothing tells the human they reached *your* desk. A named tunnel gives
+// https://desk.paydlux.com — same free tier, but the human's browser can verify
+// where it is, and the desk can pin the Host header so the local port cannot be
+// driven directly.
+//
+// One-time setup, already done on this machine:
+//   cloudflared tunnel login
+//   cloudflared tunnel create paydlux-desk
+//   cloudflared tunnel route dns paydlux-desk desk.paydlux.com
+//
+// The tunnel's credentials live in ~/.cloudflared/<tunnel-id>.json. They are NOT
+// in this repo and must never be. Anyone holding that file can serve your
+// hostname. Losing it means deleting the tunnel and making a new one.
+import { spawn } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Where cloudflared actually is. A GUI-launched or login-shell PATH often lacks
+ * /opt/homebrew/bin, and spawn() then dies with "spawn cloudflared ENOENT" — an
+ * unhandled ChildProcess error that takes the whole story down with a stack
+ * trace. Resolve the absolute path instead of trusting PATH.
+ */
+const CANDIDATES = [
+    "/opt/homebrew/bin/cloudflared", // Apple Silicon Homebrew
+    "/usr/local/bin/cloudflared", // Intel Homebrew
+    "/usr/bin/cloudflared",
+    join(homedir(), ".local/bin/cloudflared"),
+];
+export function cloudflaredPath() {
+    // PATH first, so an explicit choice (or a version manager) wins.
+    for (const dir of (process.env.PATH ?? "").split(":")) {
+        if (!dir)
+            continue;
+        const p = join(dir, "cloudflared");
+        if (existsSync(p))
+            return p;
+    }
+    for (const p of CANDIDATES)
+        if (existsSync(p))
+            return p;
+    return null;
+}
+export const TUNNEL_NAME = "paydlux-desk";
+export const PUBLIC_HOST = "desk.paydlux.com";
+/** Why this machine cannot run the named tunnel, or null if it can. */
+export function tunnelProblem() {
+    if (!cloudflaredPath()) {
+        return "cloudflared is not installed, or not on PATH. " +
+            "Install with: brew install cloudflared";
+    }
+    const dir = join(homedir(), ".cloudflared");
+    if (!existsSync(join(dir, "cert.pem"))) {
+        return "no Cloudflare login on this machine. Run: cloudflared tunnel login";
+    }
+    if (!existsSync(join(dir, "config.yml"))) {
+        return "no ~/.cloudflared/config.yml — the tunnel needs ingress to 127.0.0.1";
+    }
+    if (!readdirSync(dir).some((f) => /^[0-9a-f-]{36}\.json$/.test(f))) {
+        return "no tunnel credentials in ~/.cloudflared/. Run: cloudflared tunnel create " + TUNNEL_NAME;
+    }
+    return null;
+}
+/** True if this machine can run the named tunnel. */
+export function tunnelReady() { return tunnelProblem() === null; }
+export function runTunnel() {
+    const bin = cloudflaredPath();
+    if (!bin)
+        throw new Error("cloudflared not found — brew install cloudflared");
+    const cf = spawn(bin, ["tunnel", "run", TUNNEL_NAME], { stdio: ["ignore", "pipe", "pipe"] });
+    // Without this handler a spawn failure is an UNHANDLED 'error' event that
+    // crashes the process with a stack trace, after the story already funded
+    // accounts and printed a portal link. Capture it and report it plainly.
+    let failure = null;
+    cf.on("error", (e) => { failure = e.message; });
+    cf.stderr?.on("data", (b) => {
+        const line = b.toString().trim();
+        // cloudflared logs config errors to stderr; keep the last useful one.
+        if (line && /error|ERR|not found|invalid/i.test(line))
+            failure = line.slice(0, 300);
+    });
+    const close = () => { if (!cf.killed)
+        cf.kill("SIGTERM"); };
+    process.on("exit", close);
+    for (const sig of ["SIGINT", "SIGTERM"]) {
+        process.on(sig, () => { close(); process.exit(0); });
+    }
+    return { proc: cf, lastError: () => failure };
+}
+/** Is the tunnel actually serving TLS yet? Probes the real URL. */
+export async function tunnelLive(host = PUBLIC_HOST, tries = 12) {
+    for (let i = 0; i < tries; i++) {
+        try {
+            const res = await fetch(`https://${host}/healthz`);
+            if (res.ok || res.status === 403)
+                return true; // 403 = desk answered, TLS works
+        }
+        catch { /* not up yet */ }
+        await new Promise((r) => setTimeout(r, 1500));
+    }
+    return false;
+}

package/dist/vault.d.ts

@@ -59,6 +59,13 @@ export declare class StellarVault {
      * Create a vault. `issuer` signs the token; the vault account itself is a
      * multisig whose release threshold needs principal + approver, or agent +
      * a pre-authorised mandate hash. Nothing else reaches threshold.
+     *
+     * `tokenIssuer` separates two roles that are the same account for a custom
+     * token and different accounts for real USDC. Circle mints USDC, so on
+     * mainnet the account that pays to create the vault is the seller's wallet
+     * while the token's issuer is Circle's — we hold no key for it and must not
+     * pretend to. Pass the issuer's public key there and the asset is built from
+     * it instead of from `issuer`.
      */
     static create(opts: {
         network: Network;
@@ -67,6 +74,7 @@ export declare class StellarVault {
         approver: Keypair;
         agent: Keypair;
         tokenCode: string;
+        tokenIssuer?: string;
         vaultSeed?: string;
         startingBalance?: string;
     }): Promise<StellarVault>;

package/dist/vault.js

@@ -99,6 +99,13 @@ export class StellarVault {
      * Create a vault. `issuer` signs the token; the vault account itself is a
      * multisig whose release threshold needs principal + approver, or agent +
      * a pre-authorised mandate hash. Nothing else reaches threshold.
+     *
+     * `tokenIssuer` separates two roles that are the same account for a custom
+     * token and different accounts for real USDC. Circle mints USDC, so on
+     * mainnet the account that pays to create the vault is the seller's wallet
+     * while the token's issuer is Circle's — we hold no key for it and must not
+     * pretend to. Pass the issuer's public key there and the asset is built from
+     * it instead of from `issuer`.
      */
     static async create(opts) {
         const { network, issuer, principal, approver, agent } = opts;
@@ -116,7 +123,7 @@ export class StellarVault {
         // The trustline has to ride in this same transaction: once masterWeight is
         // 0 the vault seed cannot sign anything on its own, so a later changeTrust
         // would need two human signatures before the vault can even hold tokens.
-        const token = new Asset(opts.tokenCode, issuer.publicKey());
+        const token = new Asset(opts.tokenCode, opts.tokenIssuer ?? issuer.publicKey());
         await sub(h, pass, (await tb(h, vault.publicKey(), undefined, pass))
             .addOperation(Operation.changeTrust({ asset: token, limit: "100000000" }))
             .addOperation(Operation.setOptions({ signer: { ed25519PublicKey: principal.publicKey(), weight: 1 } }))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paydlux/agent",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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",
@@ -37,7 +37,9 @@
     "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",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "app": "tsx stellar/cli.ts",
+    "app:mainnet": "tsx stellar/cli.ts setup --mainnet"
   },
   "keywords": [
     "x402",
@@ -71,5 +73,8 @@
     "typescript": "^7.0.2",
     "viem": "^2.57.13",
     "xrpl": "^5.3.0"
+  },
+  "bin": {
+    "paydlux": "dist/cli.js"
   }
 }