@paydlux/agent 0.1.6 → 0.1.7

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/desk.js

@@ -417,6 +417,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

@@ -32,6 +32,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 */

package/dist/gateway.js

@@ -26,6 +26,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({
@@ -79,7 +80,7 @@ export class Gateway {
         return false;
     }
     /** Keys allowed to place approval requests. */
-    agentKeys = [];
+    agentKeys;
     requirements(uri) {
         const r = this.routes.get(uri);
         return {
@@ -191,7 +192,12 @@ export class Gateway {
                 }
                 const handle = this.desk.enqueue(uri, r.price, body, getContent(uri));
                 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}`);
+                res.end(JSON.stringify({ status: "awaiting_approval", handle, desk: deskUrl }));
                 return;
             }
             try {

package/package.json

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