@paydlux/agent 0.1.4 → 0.1.5

package/README.md

@@ -44,9 +44,35 @@ stellar/onboard.ts   keys → funded vault → printed agent key
 ```bash
 npm i
 npx tsx stellar/demo.ts                    # 17 checks, live testnet
-npx tsx stellar/story.ts --public --split  # unguessable link; approve on your phone
+npx tsx stellar/story.ts --tls --split     # https://desk.paydlux.com; approve on your phone
 ```
 
+`--tls` is the one to use for anything real. It runs a named Cloudflare tunnel
+so the desk is served over `https://desk.paydlux.com` with a real certificate,
+instead of a random `trycloudflare.com` hostname (`--public`) that nothing tells
+the human is *your* desk. Setup is one-time and free:
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create paydlux-desk
+cloudflared tunnel route dns paydlux-desk desk.paydlux.com
+```
+
+Then `~/.cloudflared/config.yml` points the hostname at `http://127.0.0.1:4022`.
+The tunnel's credentials file stays in `~/.cloudflared/` and must never be
+committed: whoever holds it can serve your hostname.
+
+What the desk enforces once it is public (`npx tsx stellar/tls-check.ts`, 19 checks):
+
+- plain `http://` is 301'd to `https://` and never served, with HSTS set
+- the desk listens on `127.0.0.1` only, and refuses any `Host` that is not
+  `desk.paydlux.com` — so the local port cannot be driven directly to skip TLS
+- a desk configured with a public hostname **refuses to start** without a portal
+  key, rather than coming up as an open approval button
+- the portal key also rides in an `HttpOnly; SameSite=Strict; Secure` cookie, so
+  the approver app can load its own scripts (a `<script src>` cannot inherit
+  `?k=` from the page URL) without the key ever appearing in the DOM
+
 No wallet, no faucet, no config.
 
 ### The human key does not live on the seller's machine

package/dist/desk.d.ts

@@ -38,6 +38,15 @@ export type DeskConfig = {
     /** If set, the portal and its actions require this key in the URL.
      *  Required before putting the desk on any public URL. */
     portalKey?: string;
+    /**
+     * The hostname this desk is served on, e.g. "desk.paydlux.com". When set, the
+     * desk answers ONLY requests for that Host. A named Cloudflare tunnel gives
+     * real TLS on your own domain, but the local port it forwards to is still
+     * plain HTTP: if anything on this machine (or network) reached 127.0.0.1:4022
+     * directly it would bypass TLS and the HSTS/cookie protections the domain
+     * gives you. Pinning the Host means the only way in is through the tunnel.
+     */
+    publicHost?: string;
 };
 export declare class ApprovalDesk {
     private records;

package/dist/desk.js

@@ -97,6 +97,20 @@ function readBody(req) {
         req.on("error", reject);
     });
 }
+/** Read one cookie out of the request header. No dependency for this. */
+function cookieOf(req, name) {
+    const raw = req.headers.cookie;
+    if (!raw)
+        return null;
+    for (const part of raw.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq < 0)
+            continue;
+        if (part.slice(0, eq).trim() === name)
+            return decodeURIComponent(part.slice(eq + 1).trim());
+    }
+    return null;
+}
 function same(a, b) {
     const x = Buffer.from(a), y = Buffer.from(b);
     return x.length === y.length && timingSafeEqual(x, y);
@@ -230,16 +244,68 @@ export class ApprovalDesk {
     /** Serve the pending list as JSON (the portal polls this). */
     api(handler) { return handler; }
     listen(port = this.cfg.port) {
+        // A desk reachable from outside this machine must be gated. This is a
+        // startup refusal rather than a runtime one because the dangerous case is
+        // forgetting a flag: a public desk with no portal key is an open approval
+        // button, and it would otherwise start up looking completely healthy.
+        if (this.cfg.publicHost && !this.cfg.portalKey) {
+            throw new Error("a desk served on " + this.cfg.publicHost + " needs a portalKey; " +
+                "refusing to start an ungated approval desk");
+        }
         const srv = createServer(async (req, res) => {
             // (server handle kept below so close() can stop it)
             const url = new URL(req.url ?? "/", "http://localhost");
+            // Order matters. The Host pin runs first so a request that did not come
+            // through the tunnel is refused before the desk reveals anything about
+            // itself, including whether a portal key looks correct.
+            if (this.cfg.publicHost) {
+                const want = this.cfg.publicHost.toLowerCase();
+                const got = String(req.headers.host ?? "").toLowerCase().replace(/:\d+$/, "");
+                if (got !== want) {
+                    res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
+                    res.end("403 — this desk only answers on " + want + ".");
+                    return;
+                }
+                // Cloudflare terminates TLS and forwards both http and https to us, so
+                // http://desk.paydlux.com answers too unless we send it away. A human
+                // approving a payment over plain HTTP is handing the portal key and the
+                // transaction to anyone on the path, so plain HTTP gets a redirect and
+                // nothing else. x-forwarded-proto is set by Cloudflare, not the client.
+                if (String(req.headers["x-forwarded-proto"] ?? "").split(",")[0].trim() === "http") {
+                    res.writeHead(301, { location: "https://" + want + (req.url ?? "/") });
+                    res.end();
+                    return;
+                }
+                // Once HTTPS is established, tell the browser to never try plain HTTP
+                // again for this host.
+                res.setHeader("strict-transport-security", "max-age=31536000; includeSubDomains");
+            }
+            // Liveness probe, before the portal-key gate: it proves the desk and its
+            // TLS path are up without revealing anything. No data, safe to poll.
+            if (url.pathname === "/healthz") {
+                res.writeHead(200, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
+                res.end("ok");
+                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.
-            if (this.cfg.portalKey && !same(url.searchParams.get("k") ?? "", this.cfg.portalKey)) {
+            //
+            // The key may arrive in the URL (the link the human opened) or in a
+            // cookie the desk set when that link was first validated. The cookie is
+            // what makes the approver app work: its <script src="xdr.js"> cannot
+            // inherit ?k= from the page URL, so without a cookie the app 403s on its
+            // own code and shows a blank form. HttpOnly + SameSite=Strict + Secure
+            // keeps it out of the DOM and off any cross-site request.
+            const presented = url.searchParams.get("k") ?? cookieOf(req, "pd_portal");
+            if (this.cfg.portalKey && !same(presented ?? "", this.cfg.portalKey)) {
                 res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
                 res.end("403 — this approval link was never issued or has been rotated.");
                 return;
             }
+            if (this.cfg.portalKey && url.searchParams.get("k") !== null) {
+                res.setHeader("set-cookie", `pd_portal=${this.cfg.portalKey}; Path=/; HttpOnly; SameSite=Strict; ` +
+                    `Secure; Max-Age=${12 * 3600}`);
+            }
             const qs = url.search;
             const send = (code, obj) => {
                 res.writeHead(code, { "content-type": "application/json" });
@@ -332,7 +398,10 @@ export class ApprovalDesk {
             }
         });
         this.server = srv;
-        return new Promise((r) => srv.listen(port, () => r()));
+        // Loopback only. The public path is the Cloudflare tunnel, which connects
+        // back to 127.0.0.1; binding to 0.0.0.0 would expose a plain-HTTP desk to
+        // the LAN and defeat both the TLS and the Host pin above.
+        return new Promise((r) => srv.listen(port, "127.0.0.1", () => r()));
     }
     /** Stop serving. Without this the process never exits. */
     close() {

package/dist/gateway.d.ts

@@ -30,6 +30,8 @@ export type GatewayConfig = {
     deskPort?: number;
     /** gate the approval portal behind a single unguessable link */
     portalKey?: string;
+    /** hostname the desk is publicly served on; pins the Host header. See DeskConfig. */
+    publicHost?: string;
 };
 export type PaymentProof = {
     /** pre-authorised envelope, base64 XDR, as issued by the vault */

package/dist/gateway.js

@@ -36,6 +36,7 @@ export class Gateway {
             port: cfg.deskPort ?? 4022,
             portalKey: cfg.portalKey,
             split: cfg.split,
+            publicHost: cfg.publicHost,
         });
     }
     /** Mandates the vault currently holds, so the gateway can hand them out. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paydlux/agent",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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",
@@ -29,6 +29,8 @@
     "demo:stellar": "tsx stellar/demo.ts",
     "setup:stellar": "tsx stellar/onboard.ts",
     "story:stellar": "tsx stellar/story.ts",
+    "story:tls": "tsx stellar/story.ts --tls --split",
+    "test:tls": "tsx stellar/tls-check.ts",
     "test": "cd contracts && forge test",
     "test:stellar": "tsx stellar/demo.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",