@paydlux/agent 0.1.3 → 0.1.5

package/README.md

@@ -33,7 +33,8 @@ stellar/agent.ts     the buyer side — one class, one method call
 stellar/desk.ts      approval queue: a human decides, in the clear
 stellar/portal.ts    the page that human looks at
 stellar/policy.ts    daily budget / seller allowlist (the part a ledger can't count)
-stellar/demo.ts      12 checks against the live testnet, one command
+stellar/demo.ts      17 checks against the live testnet, one command
+phone-app/           the approver app a human opens on their own device
 stellar/probe-*.ts   the experiments that settled how the ledger behaves
 stellar/onboard.ts   keys → funded vault → printed agent key
 ```
@@ -42,10 +43,36 @@ stellar/onboard.ts   keys → funded vault → printed agent key
 
 ```bash
 npm i
-npx tsx stellar/demo.ts             # 12 checks, live testnet
-npx tsx stellar/story.ts --public   # one unguessable link; approve from your phone
+npx tsx stellar/demo.ts                    # 17 checks, live testnet
+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
@@ -54,17 +81,28 @@ The vault needs two signatures. If both keys sit in one process, that is really
 one key. So the approval half is split off:
 
 ```bash
-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 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
 ```
 
-The seller builds the payment and signs it with their own half. The human's
-device (`tools/phone-sign.ts`) decodes it, shows a person the amount and payee,
-and signs offline. The approver seed never travels to the seller's machine, and
-the signature is over the transaction hash — change the amount or the payee and
-it stops counting.
-
-No wallet, no faucet, no config.
+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
+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
+its own Stellar transaction decoder (`phone-app/xdr.js`) rather than the SDK, and
+refuses any transaction shape it does not fully understand: path payments,
+account merges, signer changes and multi-operation transactions are rejected
+outright rather than guessed at. The key is imported into WebCrypto as
+**non-extractable** and only the `CryptoKey` object itself is persisted, so the
+seed is never in localStorage, IndexedDB, or a file. The page is served with
+`connect-src 'self'`, so an injected script cannot phone the key home.
+
+The approver seed never travels to the seller's machine, and the signature is
+over the transaction hash — change the amount or the payee and it stops counting.
+`tools/phone-sign.ts` is the same flow for a terminal instead of a browser.
 
 Use it as a package instead of cloning:
 

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

@@ -10,12 +10,38 @@
 //   - a stolen phone cannot approve alone
 //   - the approval is a real ledger signature, not a database flag
 import { createServer } from "node:http";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { Keypair } from "@stellar/stellar-sdk";
 import { TransactionBuilder } from "@stellar/stellar-sdk";
 import { passphrase } from "./vault.js";
 import { portalPage } from "./portal.js";
 import { createApprovalChallenge, submitApproved, challengeQrPayload, } from "./phone.js";
+/**
+ * The approver app is plain static files under phone-app/. Read on each request
+ * rather than bundled, so the desk and the app can never drift apart.
+ */
+const APP_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "phone-app");
+const appCache = new Map();
+function readAppFile(name) {
+    const safe = name.replace(/[^a-z.]/g, "");
+    const hit = appCache.get(safe);
+    if (hit)
+        return hit;
+    let text;
+    try {
+        text = readFileSync(join(APP_DIR, safe), "utf8");
+    }
+    catch {
+        // A package install that shipped without phone-app/ should say so instead of
+        // throwing out of the request handler.
+        throw new Error("approver app is missing from this install (expected " + join(APP_DIR, safe) + ")");
+    }
+    appCache.set(safe, text);
+    return text;
+}
 /** A portal link is a capability: whoever holds it can approve. So it is long,
  *  random, and compared without leaking timing. */
 export function newPortalKey() { return randomBytes(16).toString("base64url"); }
@@ -71,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);
@@ -204,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" });
@@ -227,6 +319,66 @@ export class ApprovalDesk {
                 }
                 if (url.pathname === "/list")
                     return send(200, this.list());
+                // The approver app. Served from the desk so the human opens one link on
+                // their phone instead of pasting XDR around. The app itself makes no
+                // requests after loading, and the portalKey gate above already covers
+                // these paths: without the key, nothing here is reachable.
+                // The app uses relative script srcs, so it must be served from a
+                // directory URL. /phone without the slash would resolve app.js to
+                // /app.js, so send it to the canonical path with the key intact.
+                if (url.pathname === "/phone") {
+                    res.writeHead(302, { location: "/phone/" + url.search });
+                    res.end();
+                    return;
+                }
+                if (url.pathname === "/phone/" || url.pathname === "/phone/index.html") {
+                    res.writeHead(200, {
+                        "content-type": "text/html; charset=utf-8",
+                        // The key lives in IndexedDB behind a non-extractable CryptoKey;
+                        // an injected script is the realistic threat, so lock the origin.
+                        // No inline script on the page: app.js and xdr.js are separate
+                        // files, so script-src 'self' actually holds. connect-src 'self' is
+                        // what stops the app talking anywhere but the desk that served it.
+                        "content-security-policy": "default-src 'none'; script-src 'self'; style-src 'unsafe-inline'; " +
+                            "img-src 'self' data:; connect-src 'self'; base-uri 'none'; " +
+                            "form-action 'none'; frame-ancestors 'none'",
+                        "referrer-policy": "no-referrer",
+                        "x-content-type-options": "nosniff",
+                    });
+                    res.end(readAppFile("index.html"));
+                    return;
+                }
+                if (url.pathname.startsWith("/phone/")) {
+                    const file = url.pathname.slice("/phone/".length);
+                    if (!/^[a-z]+\.(js|css)$/.test(file))
+                        return send(404, { error: "not found" });
+                    res.writeHead(200, {
+                        "content-type": (file.endsWith(".css") ? "text/css" : "text/javascript") + "; charset=utf-8",
+                        "cache-control": "no-store",
+                        "x-content-type-options": "nosniff",
+                    });
+                    res.end(readAppFile(file));
+                    return;
+                }
+                // The app fetches the pending transaction by handle rather than asking
+                // the human to paste 400 characters of base64 on a phone.
+                const ch = url.pathname.match(/^\/challenge\/([\w-]+)$/);
+                if (ch) {
+                    const rec = this.records.get(ch[1]);
+                    if (!rec)
+                        return send(404, { error: "unknown handle" });
+                    // Opening the phone link IS the approval gesture, so build the
+                    // challenge here if nobody pressed the button yet. The human should
+                    // need one link, not a button on a desktop plus a link on a phone.
+                    if (rec.status === "pending")
+                        await this.approve(rec.id);
+                    if (!rec.challenge)
+                        return send(409, { error: `not awaiting a phone signature (it is ${rec.status})` });
+                    return send(200, {
+                        id: rec.id, network: rec.challenge.network,
+                        hash: rec.challenge.hash, xdr: rec.challenge.xdr,
+                    });
+                }
                 const m = url.pathname.match(/^\/(approve|deny|signed)\/([\w-]+)$/);
                 if (m && req.method === "POST") {
                     if (m[1] === "signed") {
@@ -246,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

@@ -19,9 +19,19 @@ export type GatewayConfig = {
     /** human keys. In production these live on the phone, never here. */
     principal?: string;
     approver?: string;
+    /**
+     * Split mode: the desk gets the principal key (the seller's own half) but NOT
+     * the approver key, so this process cannot approve anything. Approval happens
+     * on a second device through the approver app. Pass `approver: undefined`
+     * together with this; the gateway still settles, using the signature the
+     * phone sends back.
+     */
+    split?: boolean;
     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

@@ -35,6 +35,8 @@ export class Gateway {
             approver: cfg.approver,
             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/dist/portal.js

@@ -1,6 +1,6 @@
 export function portalPage(records, vault, network, qs = "") {
     const rows = records.length
-        ? records.map(render).join("\n")
+        ? records.map((r) => render(r, qs)).join("\n")
         : `<tr><td colspan="5" class="empty">nothing waiting</td></tr>`;
     return `<!doctype html><html><head>
 <meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
@@ -25,6 +25,7 @@ export function portalPage(records, vault, network, qs = "") {
  .tx{font-family:ui-monospace,monospace;font-size:11px;color:var(--muted);word-break:break-all}
  .qr{font-size:10px;white-space:pre-wrap;background:#141715;padding:8px;border-radius:8px;color:var(--text)}
  details summary{cursor:pointer}
+ .phlink{color:var(--gold);text-decoration:underline;font-size:12px}
  .foot{margin-top:28px;color:var(--muted);font-size:12px}
  @media(max-width:640px){.body{max-width:180px}}
 </style></head><body>
@@ -46,15 +47,22 @@ export function portalPage(records, vault, network, qs = "") {
  setInterval(load,3000);
 </script></body></html>`;
 }
-function render(r) {
+function render(r, qs = "") {
+    // qs is the portal key query string ("?k=..."). The approver link has to carry
+    // it, because the desk answers 403 for anything without it.
+    const link = `phone/?id=${encodeURIComponent(r.id)}${qs.replace("?", "&")}`;
     const btns = r.status === "pending"
         ? `<button class="yes" onclick="act('approve','${r.id}')">Approve</button>
        <button class="no" onclick="act('deny','${r.id}')">Deny</button>`
         : "";
     // Split mode: the desk has no approver key, so approving hands the payment to
     // a phone. Show the human exactly what the phone will be asked to sign.
+    // Split mode: the desk has no approver key, so approving hands the payment to
+    // a phone. Show the human exactly what the phone will be asked to sign, and
+    // give the approver app a link so nobody pastes base64 on a small screen.
     const phone = r.status === "awaiting_phone" && r.challenge
         ? `<div class="tx">awaiting your phone · ${r.challenge.summary.amount} ${r.challenge.summary.token} to ${r.challenge.summary.payee.slice(0, 12)}…</div>
+       <div class="tx"><a class="phlink" href="${link}">open on your phone to sign</a></div>
        <details class="tx"><summary>approval payload for the phone</summary><pre class="qr">${r.qr}</pre></details>`
         : "";
     const meta = [phone, r.tx && `<div class="tx">${r.tx}</div>`, r.reason && `<div class="tx">${r.reason}</div>`].filter(Boolean).join("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paydlux/agent",
-  "version": "0.1.3",
+  "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",
@@ -13,6 +13,9 @@
   },
   "files": [
     "dist",
+    "phone-app/index.html",
+    "phone-app/app.js",
+    "phone-app/xdr.js",
     "README.md",
     "LICENSE"
   ],
@@ -26,8 +29,11 @@
     "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",
     "typecheck": "tsc --noEmit"
   },
   "keywords": [

package/phone-app/app.js

@@ -0,0 +1,253 @@
+// The approver app's own logic. Loaded by phone-app/index.html and served by the
+// desk at /phone/app.js. Kept in a separate file so the Content-Security-Policy
+// (script-src 'self') is real rather than defeated by an inline <script>.
+(function () {
+  "use strict";
+  const X = window.PaydluxXdr;
+  const $ = (id) => document.getElementById(id);
+  const DB = "paydlux-approver", STORE = "keys";
+
+  let signingKey = null;
+
+  function idb(mode, fn) {
+    return new Promise((res, rej) => {
+      const open = indexedDB.open(DB, 1);
+      open.onupgradeneeded = () => open.result.createObjectStore(STORE);
+      open.onerror = () => rej(open.error);
+      open.onsuccess = () => {
+        const tx = open.result.transaction(STORE, mode);
+        const req = fn(tx.objectStore(STORE));
+        req.onsuccess = () => res(req.result);
+        req.onerror = () => rej(req.error);
+      };
+    });
+  }
+  const saveKey = (k) => idb("readwrite", (s) => s.put(k, "approver"));
+  const loadKey = () => idb("readonly", (s) => s.get("approver"));
+  const dropKey = () => idb("readwrite", (s) => s.delete("approver"));
+
+  function base64urlToBytes(s) {
+    const bin = atob(s.replace(/-/g, "+").replace(/_/g, "/"));
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+  }
+
+  async function showReady(pub) {
+    $("who").textContent = X.encodeAccountEd25519(pub);
+    $("enrol").classList.add("hidden");
+    $("ready").classList.remove("hidden");
+  }
+
+  // ------------------------------------------------------------- enrolment
+  $("enrolBtn").addEventListener("click", async () => {
+    $("enrolErr").textContent = "";
+    const seed = $("seed").value.trim();
+    try {
+      // Imported twice on purpose: once extractable purely to read the PUBLIC
+      // half back for display, once non-extractable as the key we keep.
+      const seedBytes = X.decodeSecretSeed(seed);
+      const pkcs8 = new Uint8Array(16 + 32);
+      pkcs8.set([0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20], 0);
+      pkcs8.set(seedBytes, 16);
+
+      // "verify" is not a legal usage for a private Ed25519 key — the browser
+      // refuses the import outright. Sign only.
+      const tmp = await crypto.subtle.importKey("pkcs8", pkcs8, { name: "Ed25519" }, true, ["sign"]);
+      const jwk = await crypto.subtle.exportKey("jwk", tmp);
+      const pub = base64urlToBytes(jwk.x);
+
+      signingKey = await X.importSecretSeed(seed);      // non-extractable
+      seedBytes.fill(0); pkcs8.fill(0); $("seed").value = "";
+
+      // What is persisted is the non-extractable CryptoKey object, not the seed.
+      // Whatever backs IndexedDB can use that key to sign; no code path can read
+      // the seed out of it. Losing the database leaks nothing; stealing it leaks
+      // nothing either.
+      await saveKey({ key: signingKey, x: jwk.x });
+      await showReady(pub);
+    } catch (e) {
+      $("enrolErr").textContent = e.message;
+    }
+  });
+
+  $("forget").addEventListener("click", async () => {
+    signingKey = null;
+    await dropKey();
+    location.reload();
+  });
+
+  // --------------------------------------------------------------- review
+  let pending = null;
+
+  /**
+   * Deep link from the desk: /phone/?id=pay_0001&k=PORTALKEY
+   * The human taps a link instead of pasting 400 characters of base64 on a
+   * phone. The desk returns its own record of the challenge, so the amount the
+   * phone displays is the amount the desk recorded.
+   */
+  async function loadFromDesk() {
+    const q = new URLSearchParams(location.search);
+    const id = q.get("id"), k = q.get("k");
+    if (!id) return;
+    try {
+      const res = await fetch("/challenge/" + encodeURIComponent(id) +
+        (k ? "?k=" + encodeURIComponent(k) : ""), { cache: "no-store" });
+      if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error || res.status);
+      const rec = await res.json();
+      $("xdr").value = rec.xdr;
+      pending = { fromDesk: true, id, k };
+      await renderChallenge(rec.xdr);
+      $("readErr").textContent = "";
+    } catch (e) {
+      $("readErr").textContent = "could not load " + id + ": " + e.message;
+    }
+  }
+
+  async function renderChallenge(xdrText) {
+    const env = X.parseEnvelope(xdrText);
+    const op = env.tx.ops[0];
+    const testnet = await X.transactionHash(xdrText, X.NETWORK_ID.testnet);
+    const publicNet = await X.transactionHash(xdrText, X.NETWORK_ID.public);
+    pending = Object.assign({}, pending, {
+      xdrText, env, hashes: { testnet: testnet.hash, public: publicNet.hash },
+    });
+
+    $("amount").textContent = X.formatAmount(op.amount) + " " + op.asset.code;
+    $("token").textContent = op.asset.issuer
+      ? op.asset.code + " issued by " + op.asset.issuer
+      : "XLM (native)";
+    $("payee").textContent = X.encodeAccountEd25519(op.destination.pub);
+    $("vault").textContent = X.encodeAccountEd25519(env.tx.source.pub);
+    $("memo").textContent = env.tx.memo || "(none)";
+    const max = env.tx.bounds && env.tx.bounds.maxTime;
+    $("deadline").textContent = max && max !== "0"
+      ? new Date(Number(max) * 1000).toLocaleString() + " (" + remaining(Number(max)) + ")"
+      : "none — this transaction never expires";
+
+    // Which network an envelope belongs to is NOT inside the envelope, so the
+    // human picks it. Signing for the wrong network yields a signature the
+    // ledger refuses; it cannot silently move funds somewhere else.
+    $("hash").innerHTML =
+      '<label class="tag ok"><input type="radio" name="net" value="testnet" checked> testnet</label> '
+      + testnet.hash +
+      '<br><label class="tag warn"><input type="radio" name="net" value="public"> mainnet</label> '
+      + publicNet.hash;
+    $("review").classList.remove("hidden");
+  }
+
+  function remaining(unix) {
+    const s = unix - Math.floor(Date.now() / 1000);
+    if (s <= 0) return "EXPIRED";
+    if (s < 120) return s + "s left";
+    return Math.round(s / 60) + " min left";
+  }
+
+  $("read").addEventListener("click", async () => {
+    $("readErr").textContent = "";
+    $("review").classList.add("hidden");
+    const xdrText = $("xdr").value.trim().replace(/\s+/g, "");
+    try {
+      await renderChallenge(xdrText);
+    } catch (e) {
+      $("readErr").textContent = e.message;
+    }
+  });
+
+  $("reject").addEventListener("click", () => reset());
+  $("again").addEventListener("click", () => reset());
+  function reset() {
+    pending = null;
+    $("result").classList.add("hidden");
+    $("review").classList.add("hidden");
+    $("xdr").value = "";
+  }
+
+  // ---------------------------------------------------------------- sign
+  $("approve").addEventListener("click", async () => {
+    $("signErr").textContent = "";
+    if (!signingKey) {
+      $("signErr").textContent = "Import the approver key first.";
+      return;
+    }
+    if (!pending) return;
+
+    const picked = document.querySelector("input[name=net]:checked");
+    const which = picked ? picked.value : "testnet";
+    const network = which === "testnet" ? X.NETWORK_ID.testnet : X.NETWORK_ID.public;
+
+    // A pasted transaction has no trusted source, so the human proves they were
+    // shown this exact one by typing its hash back. A transaction fetched from
+    // the desk over the portal key is already bound to the desk's own record,
+    // which the desk re-checks before submitting.
+    if (!pending.fromDesk) {
+      const quoted = prompt("Type the first 16 characters of the hash the seller quoted you:");
+      if (!quoted) return;
+      const q = quoted.trim().toLowerCase();
+      if (q !== pending.hashes.testnet.slice(0, 16) && q !== pending.hashes.public.slice(0, 16)) {
+        $("signErr").textContent = "That hash matches neither. Nothing was signed.";
+        return;
+      }
+    }
+
+    try {
+      const { hash } = await X.transactionHash(pending.xdrText, network);
+      // The signature covers the 32 raw hash bytes. sha256-ing the hex text
+      // instead yields a well-formed envelope the ledger refuses with BAD_AUTH.
+      const sig = new Uint8Array(await crypto.subtle.sign(
+        "Ed25519", signingKey, X.signaturePreimage(hash)));
+      const rec = await loadKey();
+      const signed = X.addSignature(pending.xdrText, sig, base64urlToBytes(rec.x));
+
+      if (pending.fromDesk) {
+        const res = await fetch("/signed/" + encodeURIComponent(pending.id) +
+          (pending.k ? "?k=" + encodeURIComponent(pending.k) : ""), {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ signedXdr: signed }),
+        });
+        const out = await res.json().catch(() => ({}));
+        if (out.status === "settled") {
+          // Show the ledger hash and keep the panel up: this is the only proof
+          // the human gets that the payment actually landed. reset() would hide
+          // it again, so clear the form by hand instead.
+          pending = null;
+          $("xdr").value = "";
+          $("review").classList.add("hidden");
+          $("signed").textContent = "settled on ledger\n" + (out.tx || "");
+          $("result").classList.remove("hidden");
+          return;
+        }
+        $("signErr").textContent = "the desk refused it: " +
+          (out.reason || out.error || out.status || res.status);
+        return;
+      }
+      $("signed").textContent = signed;
+      $("result").classList.remove("hidden");
+    } catch (e) {
+      $("signErr").textContent = e.message;
+    }
+  });
+
+  $("copy").addEventListener("click", async () => {
+    try {
+      await navigator.clipboard.writeText($("signed").textContent);
+      $("copy").textContent = "Copied";
+    } catch (e) {
+      $("copy").textContent = "Select the text above and copy it manually";
+    }
+  });
+
+  // On reload, pull the non-extractable CryptoKey back out of IndexedDB. It can
+  // sign; it cannot be exported. The seed itself is never stored anywhere.
+  (async () => {
+    try {
+      const rec = await loadKey();
+      if (rec && rec.key instanceof CryptoKey) {
+        signingKey = rec.key;
+        await showReady(base64urlToBytes(rec.x));
+      }
+    } catch (e) { /* enrolment UI stays up */ }
+    await loadFromDesk();
+  })();
+})();

package/phone-app/index.html

@@ -0,0 +1,148 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<meta name="theme-color" content="#0b0f14">
+<title>Paydlux Approver</title>
+<!--
+  The approver half of a Paydlux vault.
+
+  This page holds ONE key: the approver's. It cannot spend anything by itself.
+  It reads a pending payment, shows a human what they are approving, and signs
+  the transaction hash. Signing is a purely local operation: no network call can
+  change what was signed.
+
+  The page talks to one origin only — the desk that served it — to fetch the
+  pending transaction and hand back the signature. connect-src 'self' in the
+  desk's Content-Security-Policy enforces that.
+
+  What the key model actually guarantees:
+    - the seed becomes a NON-extractable WebCrypto key; after enrolment nothing
+      on this page, including an injected script, can read it back;
+    - the signature covers the transaction hash, so a changed amount or payee
+      produces a different hash and a signature the ledger refuses;
+    - the approver key alone cannot move funds — the vault needs 2 signatures.
+
+  What it does NOT guarantee: a person who roots this device, or who approves a
+  transaction without reading it. The human reading the amount and payee is part
+  of the security model, not a UX step.
+
+  Serve it over http(s) on a device you control:  npx tsx tools/phone-serve.ts
+-->
+<style>
+  :root {
+    --bg:#0b0f14; --panel:#121821; --line:#22303f; --ink:#e8eef6; --dim:#8fa3b8;
+    --ok:#3ddc97; --warn:#ffb454; --bad:#ff6b6b; --accent:#4da3ff;
+  }
+  * { box-sizing:border-box }
+  body {
+    margin:0; background:var(--bg); color:var(--ink); font:16px/1.5 ui-sans-serif,system-ui,-apple-system,sans-serif;
+    padding:max(16px, env(safe-area-inset-top)) 16px max(24px, env(safe-area-inset-bottom));
+    max-width:560px; margin-inline:auto;
+  }
+  h1 { font-size:17px; margin:0 0 4px; letter-spacing:.02em }
+  .sub { color:var(--dim); font-size:13px; margin-bottom:18px }
+  .panel { background:var(--panel); border:1px solid var(--line); border-radius:14px; padding:14px; margin-bottom:14px }
+  label { display:block; font-size:12px; color:var(--dim); margin:10px 0 4px; text-transform:uppercase; letter-spacing:.06em }
+  textarea, input {
+    width:100%; background:#0d131a; color:var(--ink); border:1px solid var(--line);
+    border-radius:10px; padding:10px; font:13px/1.4 ui-monospace,SFMono-Regular,Menlo,monospace;
+    word-break:break-all;
+  }
+  textarea { min-height:84px; resize:vertical }
+  button {
+    width:100%; margin-top:12px; padding:14px; border:0; border-radius:12px;
+    background:var(--accent); color:#04121f; font-size:16px; font-weight:700; cursor:pointer;
+  }
+  button.ghost { background:transparent; color:var(--dim); border:1px solid var(--line); font-weight:600 }
+  button.danger { background:var(--bad); color:#2a0707 }
+  button:disabled { opacity:.4 }
+  .row { display:flex; gap:10px }
+  .row > * { flex:1 }
+  .kv { display:grid; grid-template-columns:96px 1fr; gap:6px 10px; font-size:14px }
+  .kv dt { color:var(--dim); font-size:12px; text-transform:uppercase; letter-spacing:.06em; padding-top:2px }
+  .kv dd { margin:0; font-family:ui-monospace,Menlo,monospace; word-break:break-all; font-size:13px }
+  .amount { font-size:34px; font-weight:800; margin:2px 0 10px; font-variant-numeric:tabular-nums }
+  .tag { display:inline-block; font-size:11px; padding:3px 8px; border-radius:999px; letter-spacing:.06em; text-transform:uppercase }
+  .tag.ok { background:rgba(61,220,151,.14); color:var(--ok) }
+  .tag.warn { background:rgba(255,180,84,.14); color:var(--warn) }
+  .tag.bad { background:rgba(255,107,107,.14); color:var(--bad) }
+  .err { color:var(--bad); font-size:13px; margin-top:8px; word-break:break-word }
+  .hint { color:var(--dim); font-size:12px; margin-top:8px }
+  .hidden { display:none }
+  .out { background:#0d131a; border:1px solid var(--line); border-radius:10px; padding:10px;
+         font:12px/1.4 ui-monospace,Menlo,monospace; word-break:break-all; max-height:180px; overflow:auto }
+  .who { font-family:ui-monospace,Menlo,monospace; font-size:12px; color:var(--dim); word-break:break-all }
+</style>
+</head>
+<body>
+<h1>Paydlux Approver</h1>
+<div class="sub">Signs payments on this device. The key never leaves it.</div>
+
+<!-- ---------------------------------------------------------- enrolment -->
+<div class="panel" id="enrol">
+  <div class="tag warn">No approver key on this device</div>
+  <label for="seed">Approver secret seed (S&hellip;)</label>
+  <input id="seed" type="password" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"
+         placeholder="S">
+  <button id="enrolBtn">Import key</button>
+  <div class="hint">
+    The seed becomes a non-extractable signing key and is then dropped. Only that key is
+    kept: it can sign, nothing can read the seed back out of it. If this device is wiped,
+    re-enter the seed.
+  </div>
+  <div class="err" id="enrolErr"></div>
+</div>
+
+<!-- ------------------------------------------------------------ ready -->
+<div class="panel hidden" id="ready">
+  <div class="tag ok">Key loaded</div>
+  <dl class="kv" style="margin-top:10px">
+    <dt>Approver</dt><dd class="who" id="who"></dd>
+  </dl>
+  <button class="ghost" id="forget">Remove key from this device</button>
+</div>
+
+<!-- --------------------------------------------------------- approval -->
+<div class="panel">
+  <label for="xdr">Pending transaction (paste the XDR from the seller)</label>
+  <textarea id="xdr" autocorrect="off" autocapitalize="off" spellcheck="false"
+            placeholder="Paste the transaction the seller sent you"></textarea>
+  <button id="read">Read it</button>
+  <div class="err" id="readErr"></div>
+</div>
+
+<div class="panel hidden" id="review">
+  <div class="amount" id="amount"></div>
+  <dl class="kv">
+    <dt>Token</dt><dd id="token"></dd>
+    <dt>Payee</dt><dd id="payee"></dd>
+    <dt>From</dt><dd id="vault"></dd>
+    <dt>Reference</dt><dd id="memo"></dd>
+    <dt>Deadline</dt><dd id="deadline"></dd>
+    <dt>Network</dt><dd id="network"></dd>
+    <dt>Hash</dt><dd id="hash"></dd>
+  </dl>
+  <div class="hint">
+    Only the hash is signed. If anything above differs from what the seller told you,
+    do not approve &mdash; a changed amount or payee produces a different hash.
+  </div>
+  <button id="approve">Approve &amp; sign</button>
+  <button class="ghost" id="reject">Reject</button>
+  <div class="err" id="signErr"></div>
+</div>
+
+<!-- ----------------------------------------------------------- result -->
+<div class="panel hidden" id="result">
+  <div class="tag ok">Signed</div>
+  <label>Signed transaction &mdash; send this back to the seller</label>
+  <div class="out" id="signed"></div>
+  <button id="copy">Copy</button>
+  <button class="ghost" id="again">Done</button>
+</div>
+
+<script src="xdr.js"></script>
+<script src="app.js"></script>
+</body>
+</html>

package/phone-app/xdr.js

@@ -0,0 +1,436 @@
+// Minimal Stellar transaction codec for the phone. No dependencies, no network.
+//
+// The phone must be able to (a) read a payment so a human can see what they are
+// approving, (b) recompute the transaction hash so it can prove the bytes it was
+// given are the bytes it was shown, and (c) append its signature.
+//
+// It deliberately understands only the payment envelope shape. Anything it does
+// not recognise is an error, not a guess — refusing to sign is always safe.
+//
+// Field order below is taken from the Stellar XDR schema (Transaction,
+// Operation, PaymentOp, Preconditions, Memo, Asset, TransactionExt,
+// DecoratedSignature). phone-app/xdr-check.ts asserts this decoder agrees with
+// the official SDK on a real vault payment.
+//
+// This file runs unchanged in the browser and in Node (tests).
+(function (root) {
+  "use strict";
+
+  // ------------------------------------------------------------------ reader
+  function Reader(bytes) {
+    this.b = bytes; this.i = 0;
+  }
+  Reader.prototype.u32 = function () {
+    if (this.i + 4 > this.b.length) throw new Error("xdr: truncated reading uint32");
+    const v = (this.b[this.i] << 24 | this.b[this.i + 1] << 16 | this.b[this.i + 2] << 8 | this.b[this.i + 3]) >>> 0;
+    this.i += 4; return v;
+  };
+  // Sequence numbers and amounts are int64 and routinely exceed
+  // Number.MAX_SAFE_INTEGER, so 64-bit values stay BigInt until displayed.
+  Reader.prototype.u64 = function () {
+    const hi = BigInt(this.u32()), lo = BigInt(this.u32());
+    return (hi << 32n) | lo;
+  };
+  Reader.prototype.i64 = function () {
+    const v = this.u64();
+    return v >= (1n << 63n) ? v - (1n << 64n) : v;
+  };
+  Reader.prototype.fixed = function (n) {
+    if (this.i + n > this.b.length) throw new Error("xdr: truncated fixed bytes");
+    const out = this.b.slice(this.i, this.i + n);
+    this.i += n;
+    const pad = (4 - (n % 4)) % 4;
+    for (let p = 0; p < pad; p++) {
+      if (this.b[this.i + p] !== 0) throw new Error("xdr: bad padding");
+    }
+    this.i += pad;
+    return out;
+  };
+  Reader.prototype.varOpaque = function (max) {
+    const n = this.u32();
+    if (n > max) throw new Error(`xdr: opaque length ${n} exceeds the ${max}-byte limit`);
+    return this.fixed(n);
+  };
+
+  // ------------------------------------------------------------------ writer
+  function Writer() { this.b = []; }
+  Writer.prototype.u32 = function (v) {
+    this.b.push((v >>> 24) & 255, (v >>> 16) & 255, (v >>> 8) & 255, v & 255);
+  };
+  Writer.prototype.u64 = function (v) {
+    const b = BigInt(v);
+    this.u32(Number((b >> 32n) & 0xffffffffn)); this.u32(Number(b & 0xffffffffn));
+  };
+  Writer.prototype.fixed = function (bytes) {
+    for (const x of bytes) this.b.push(x);
+    const pad = (4 - (bytes.length % 4)) % 4;
+    for (let p = 0; p < pad; p++) this.b.push(0);
+  };
+  Writer.prototype.varOpaque = function (bytes) { this.u32(bytes.length); this.fixed(bytes); };
+  Writer.prototype.bytes = function () { return Uint8Array.from(this.b); };
+
+  // ------------------------------------------------------------------ constants
+  const ENVELOPE_TYPE_TX = 2;          // TransactionEnvelope holding a v1 tx
+  const KEY_TYPE_ED25519 = 0;
+  const KEY_TYPE_MUXED_ED25519 = 256;
+  const SC_ADDRESS = 4;                // soroban account: we refuse it
+  const ASSET_NATIVE = 0, ASSET_ALPHANUM4 = 1, ASSET_ALPHANUM12 = 2;
+  const OP_PAYMENT = 1;
+  const PRECOND_NONE = 0, PRECOND_TIME = 1, PRECOND_V2 = 2;
+  const MEMO_NONE = 0, MEMO_TEXT = 1, MEMO_ID = 2, MEMO_HASH = 3, MEMO_RETURN = 4;
+  const STROOPS = 10000000;
+
+  // ------------------------------------------------------------------ strkey
+  const B32 = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+  /** Stellar account id (G...) from a 32-byte ed25519 public key. */
+  function encodeAccountEd25519(pub) {
+    if (pub.length !== 32) throw new Error("public key must be 32 bytes");
+    return encodeStrKey(6 << 3, pub);
+  }
+
+  /** 32-byte public key from a Stellar account id. */
+  function decodeAccountEd25519(str) {
+    if (typeof str !== "string" || str[0] !== "G") {
+      throw new Error("not a Stellar account id (expected G...)");
+    }
+    return decodeStrKey(str, 6 << 3, 32);
+  }
+
+  /**
+   * Stellar secret seed (S...) -> 32-byte seed. Same base32 envelope as an
+   * account id, different version byte.
+   */
+  function decodeSecretSeed(str) {
+    if (typeof str !== "string" || str[0] !== "S") {
+      throw new Error("not a Stellar secret seed (expected S...)");
+    }
+    return decodeStrKey(str, 18 << 3, 32);
+  }
+
+  /** Stellar secret seed (S...) from a 32-byte seed. */
+  function encodeSecretSeed(seed) {
+    if (seed.length !== 32) throw new Error("seed must be 32 bytes");
+    return encodeStrKey(18 << 3, seed);
+  }
+
+  function encodeStrKey(version, body) {
+    const bytes = [version, ...body, 0, 0];
+    const crc = crc16Xmodem(bytes.slice(0, 1 + body.length));
+    bytes[bytes.length - 2] = crc & 255;
+    bytes[bytes.length - 1] = (crc >> 8) & 255;
+    const bits = [];
+    for (const byte of bytes) for (let k = 7; k >= 0; k--) bits.push((byte >> k) & 1);
+    let out = "";
+    for (let k = 0; k + 5 <= bits.length; k += 5) {
+      out += B32[bits[k] * 16 + bits[k + 1] * 8 + bits[k + 2] * 4 + bits[k + 3] * 2 + bits[k + 4]];
+    }
+    return out;
+  }
+
+  function decodeStrKey(str, version, bodyLen) {
+    if (str.length !== 56) throw new Error("strkey must be 56 characters");
+    const bits = [];
+    for (const ch of str) {
+      const v = B32.indexOf(ch);
+      if (v < 0) throw new Error("not a valid strkey: bad character " + ch);
+      for (let k = 4; k >= 0; k--) bits.push((v >> k) & 1);
+    }
+    const bytes = [];
+    for (let k = 0; k + 8 <= bits.length; k += 8) {
+      let byte = 0;
+      for (let j = 0; j < 8; j++) byte = (byte << 1) | bits[k + j];
+      bytes.push(byte);
+    }
+    if (bytes[0] !== version) throw new Error("wrong strkey version byte");
+    const body = Uint8Array.from(bytes.slice(1, 1 + bodyLen));
+    const checksum = (bytes[1 + bodyLen] | (bytes[2 + bodyLen] << 8)) >>> 0;
+    if (checksum !== crc16Xmodem(bytes.slice(0, 1 + bodyLen))) {
+      throw new Error("strkey checksum does not match — the key was mistyped");
+    }
+    return body;
+  }
+
+  /** CRC16-XMODEM, the checksum Stellar strkeys use. */
+  function crc16Xmodem(bytes) {
+    let crc = 0;
+    for (const b of bytes) {
+      crc ^= b << 8;
+      for (let i = 0; i < 8; i++) {
+        crc = (crc & 0x8000) ? ((crc << 1) ^ 0x1021) & 0xffff : (crc << 1) & 0xffff;
+      }
+    }
+    return crc & 0xffff;
+  }
+
+  /**
+   * Turn a Stellar secret seed into a WebCrypto signing key.
+   *
+   * The result is NON-extractable: the app can sign with it, but nothing — not
+   * the page's own JavaScript, not an injected script — can read the seed back
+   * out of it. That is the point of the phone holding the approval half.
+   * The public half is captured at enrolment and stored separately.
+   */
+  async function importSecretSeed(seedStr) {
+    const seed = decodeSecretSeed(seedStr);
+    const pkcs8 = new Uint8Array(16 + 32);
+    pkcs8.set([
+      0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06,
+      0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
+    ], 0);
+    pkcs8.set(seed, 16);
+    const privateKey = await crypto.subtle.importKey(
+      "pkcs8", pkcs8, { name: "Ed25519" }, false, ["sign"]);
+    seed.fill(0);                       // drop the plaintext copy as soon as we can
+    return privateKey;
+  }
+
+  // ------------------------------------------------------------------ parsing
+  function readMuxedAccount(r) {
+    const type = r.u32();
+    if (type === KEY_TYPE_ED25519) return { kind: "ed25519", pub: r.fixed(32) };
+    if (type === KEY_TYPE_MUXED_ED25519) {
+      const id = r.u64();
+      const pub = r.fixed(32);
+      return { kind: "muxed", id: id.toString(), pub };
+    }
+    if (type === SC_ADDRESS) throw new Error("a smart-contract address cannot approve a payment");
+    throw new Error("unknown account key type " + type);
+  }
+
+  function readAsset(r) {
+    const type = r.u32();
+    if (type === ASSET_NATIVE) return { code: "XLM", issuer: null };
+    if (type === ASSET_ALPHANUM4 || type === ASSET_ALPHANUM12) {
+      const code = asciiTrim(r.fixed(type === ASSET_ALPHANUM4 ? 4 : 12));
+      return { code, issuer: encodeAccountEd25519(readPublicKey(r)) };
+    }
+    throw new Error("asset type " + type + " is not supported; refusing to sign");
+  }
+
+  /**
+   * Asset issuers use public_key, which is a union: a 4-byte key-type word
+   * before the 32 bytes. Missing that word shifts every later field by four
+   * bytes and silently misreads the amount, so it is read explicitly.
+   */
+  function readPublicKey(r) {
+    const type = r.u32();
+    if (type !== KEY_TYPE_ED25519) {
+      throw new Error("issuer key type " + type + " is not supported; refusing to sign");
+    }
+    return r.fixed(32);
+  }
+
+  function asciiTrim(bytes) {
+    let s = "";
+    for (const b of bytes) { if (b === 0) break; s += String.fromCharCode(b); }
+    if (!/^[A-Za-z0-9]{1,12}$/.test(s)) {
+      throw new Error("asset code is not alphanumeric: " + JSON.stringify(s));
+    }
+    return s;
+  }
+
+  function readMemo(r) {
+    const type = r.u32();
+    if (type === MEMO_NONE) return null;
+    if (type === MEMO_TEXT) {
+      const s = r.varOpaque(28);
+      let text = "";
+      for (const b of s) {
+        if (b < 0x20 || b > 0x7e) throw new Error("memo text is not printable");
+        text += String.fromCharCode(b);
+      }
+      return text;
+    }
+    if (type === MEMO_ID) return "id:" + r.u64().toString();
+    if (type === MEMO_HASH) return "hash:" + hex(r.fixed(32));
+    if (type === MEMO_RETURN) return "return:" + hex(r.fixed(32));
+    throw new Error("unknown memo type " + type);
+  }
+
+  function readPreconditions(r) {
+    const type = r.u32();
+    if (type === PRECOND_NONE) return null;
+    if (type === PRECOND_TIME) {
+      const minTime = r.u64().toString(), maxTime = r.u64().toString();
+      return { minTime, maxTime };
+    }
+    if (type === PRECOND_V2) {
+      // timeBounds? ledgerBounds? minSeqNum? minSeqAge minSeqLedgerGap extraSigners[2]
+      const hasTime = r.u32();
+      const bounds = hasTime
+        ? { minTime: r.u64().toString(), maxTime: r.u64().toString() }
+        : null;
+      const hasLedger = r.u32();
+      if (hasLedger) throw new Error("ledger bounds are not supported; refusing to sign");
+      const hasSeq = r.u32();
+      if (hasSeq) throw new Error("sequence preconditions are not supported; refusing to sign");
+      r.u64();                                  // minSeqAge
+      r.u32();                                  // minSeqLedgerGap
+      const n = r.u32();
+      if (n !== 0) throw new Error("extra signers are not supported; refusing to sign");
+      return bounds;
+    }
+    throw new Error("unknown precondition type " + type);
+  }
+
+  function readOperation(r) {
+    const hasSource = r.u32();
+    const source = hasSource ? readMuxedAccount(r) : null;
+    const type = r.u32();                          // OperationBody union switch
+    if (type !== OP_PAYMENT) {
+      throw new Error("operation type " + type + " is not a payment; this app only signs payments");
+    }
+    const destination = readMuxedAccount(r);
+    const asset = readAsset(r);
+    const amount = r.i64();
+    if (amount < 0n) throw new Error("payment amount is negative; refusing to sign");
+    return { type, source, destination, asset, amount: amount.toString() };
+  }
+
+  function readTransaction(r) {
+    const source = readMuxedAccount(r);
+    const fee = r.u32();
+    const seq = r.u64();
+    const bounds = readPreconditions(r);
+    const memo = readMemo(r);
+    const numOps = r.u32();
+    if (numOps !== 1) {
+      throw new Error("this app signs single-payment transactions, and this one has "
+        + numOps + " operations");
+    }
+    const ops = [];
+    for (let i = 0; i < numOps; i++) ops.push(readOperation(r));
+    // TransactionExt is a union: v0 carries nothing at all.
+    const ext = r.u32();
+    if (ext !== 0) throw new Error("transaction carries soroban data; refusing to sign");
+    return { source, fee, seq, bounds, memo, ops };
+  }
+
+  function readDecorativeSignature(r) {
+    const hint = r.fixed(4);
+    const sig = r.varOpaque(64);
+    return { hint, sig };
+  }
+
+  /** Parse a base64 TransactionEnvelope, returning the tx plus its raw bytes. */
+  function parseEnvelope(base64) {
+    const bytes = base64ToBytes(base64);
+    const r = new Reader(bytes);
+    const type = r.u32();
+    if (type !== ENVELOPE_TYPE_TX) {
+      throw new Error("expected a v1 transaction envelope (type 2), got " + type
+        + " — a fee-bump or v0 envelope is not supported");
+    }
+    const txStart = r.i;
+    const tx = readTransaction(r);
+    const txEnd = r.i;
+    const n = r.u32();
+    if (n === 0 || n > 20) throw new Error("envelope has " + n + " signatures; expected 1 or 2");
+    const signatures = [];
+    for (let i = 0; i < n; i++) signatures.push(readDecorativeSignature(r));
+    if (r.i !== bytes.length) {
+      throw new Error("trailing bytes after the envelope (" + (bytes.length - r.i) + ")");
+    }
+    return { tx, signatures, txBytes: bytes.slice(txStart, txEnd), bytes };
+  }
+
+  // ------------------------------------------------------------------ hashing
+  /**
+   * The hash a Stellar signature covers:
+   *   sha256( sha256(passphrase) || ENVELOPE_TYPE_TX(4) || transactionBytes )
+   *
+   * The leading 32 bytes are the hash of the network passphrase, not the
+   * passphrase itself. Recomputing this on the phone is what stops a swapped
+   * transaction: the human is shown this value, and the bytes actually signed
+   * have to produce it.
+   */
+  async function transactionHash(base64, passphraseStr) {
+    const env = parseEnvelope(base64);
+    const networkId = new Uint8Array(await crypto.subtle.digest(
+      "SHA-256", new TextEncoder().encode(passphraseStr)));
+    const buf = new Uint8Array(32 + 4 + env.txBytes.length);
+    buf.set(networkId, 0);
+    buf[32] = 0; buf[33] = 0; buf[34] = 0; buf[35] = ENVELOPE_TYPE_TX;
+    buf.set(env.txBytes, 36);
+    const digest = await crypto.subtle.digest("SHA-256", buf);
+    return { hash: hex(new Uint8Array(digest)), env };
+  }
+
+  // ------------------------------------------------------------------ signing
+  /**
+   * The bytes an approver signature must cover: the transaction hash itself,
+   * as 32 raw bytes. NOT sha256 of the hex text the human reads. Signing the
+   * wrong preimage produces a well-formed envelope the ledger refuses with
+   * BAD_AUTH, so this is exported rather than left to each caller to guess.
+   */
+  function signaturePreimage(hashHex) { return hexToBytes(hashHex); }
+
+  /** Append one ed25519 signature to the envelope. Returns new base64 XDR. */
+  function addSignature(base64, signatureBytes, pubKeyBytes) {
+    if (signatureBytes.length !== 64) throw new Error("signature must be 64 bytes");
+    if (pubKeyBytes.length !== 32) throw new Error("public key must be 32 bytes");
+    const env = parseEnvelope(base64);
+    if (env.signatures.length >= 2) {
+      throw new Error("envelope already has " + env.signatures.length + " signatures");
+    }
+    const w = new Writer();
+    w.u32(ENVELOPE_TYPE_TX);
+    w.fixed(env.txBytes);
+    const sigs = env.signatures.concat([{
+      hint: pubKeyBytes.slice(28), sig: signatureBytes,
+    }]);
+    w.u32(sigs.length);
+    for (const s of sigs) { w.fixed(s.hint); w.varOpaque(s.sig); }
+    return bytesToBase64(w.bytes());
+  }
+
+  // ------------------------------------------------------------------ amounts
+  /** int64 stroops -> "4.5000000", the way the ledger prints it. */
+  function formatAmount(stroopAmount) {
+    const v = typeof stroopAmount === "bigint" ? stroopAmount : BigInt(stroopAmount);
+    if (v < 0n) throw new Error("negative payment amount");
+    const whole = v / BigInt(STROOPS);
+    const frac = v % BigInt(STROOPS);
+    return whole.toString() + "." + frac.toString().padStart(7, "0");
+  }
+
+  // ------------------------------------------------------------------ base64
+  function base64ToBytes(s) {
+    const bin = atob(s);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+  }
+  function bytesToBase64(bytes) {
+    let bin = "";
+    for (const b of bytes) bin += String.fromCharCode(b);
+    return btoa(bin);
+  }
+  function hexToBytes(s) {
+    if (!/^[0-9a-fA-F]+$/.test(s) || s.length % 2) throw new Error("not a hex string");
+    const out = new Uint8Array(s.length / 2);
+    for (let i = 0; i < out.length; i++) out[i] = parseInt(s.substr(i * 2, 2), 16);
+    return out;
+  }
+
+  function hex(bytes) {
+    let s = "";
+    for (const b of bytes) s += b.toString(16).padStart(2, "0");
+    return s;
+  }
+
+  const NETWORK_ID = {
+    testnet: "Test SDF Network ; September 2015",
+    public: "Public Global Stellar Network ; September 2015",
+  };
+
+  root.PaydluxXdr = {
+    parseEnvelope, transactionHash, addSignature, formatAmount,
+    hex, hexToBytes, signaturePreimage,
+    encodeAccountEd25519, decodeAccountEd25519,
+    decodeSecretSeed, encodeSecretSeed, importSecretSeed,
+    NETWORK_ID, crc16Xmodem,
+    ENVELOPE_TYPE_TX, OP_PAYMENT, STROOPS,
+  };
+})(typeof globalThis !== "undefined" ? globalThis : this);