@paydlux/agent 0.1.2 → 0.1.4

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,12 +43,41 @@ 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 --public --split  # unguessable link; approve on your phone
 ```
 
 No wallet, no faucet, no config.
 
+### The human key does not live on the seller's machine
+
+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 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 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:
 
 ```bash

package/dist/desk.d.ts

@@ -1,5 +1,6 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
 import type { StellarVault } from "./vault.ts";
+import { type ApprovalChallenge } from "./phone.ts";
 /** A portal link is a capability: whoever holds it can approve. So it is long,
  *  random, and compared without leaking timing. */
 export declare function newPortalKey(): string;
@@ -9,10 +10,14 @@ export type DeskRecord = {
     uri: string;
     price: string;
     body: string;
-    status: "pending" | "approved" | "denied" | "settled" | "failed";
+    status: "pending" | "awaiting_phone" | "approved" | "denied" | "settled" | "failed";
     content?: string;
     tx?: string;
     reason?: string;
+    /** split mode: what the phone is asked to sign, and what it sent back */
+    challenge?: ApprovalChallenge;
+    qr?: string;
+    signedXdr?: string;
 };
 export type DeskStore = DeskRecord;
 export type DeskConfig = {
@@ -21,6 +26,14 @@ export type DeskConfig = {
     /** seeds of the two human keys. DEV ONLY — in production these live on the phone. */
     principal?: string;
     approver?: string;
+    /**
+     * Split signing: the desk holds only the agent/principal half. Approving
+     * produces a challenge the phone signs offline; the signature comes back and
+     * the desk submits it. The approver seed never touches this machine.
+     */
+    split?: boolean;
+    /** how long a human has to decide before the payment is dead */
+    decideWithinSeconds?: number;
     port: number;
     /** If set, the portal and its actions require this key in the URL.
      *  Required before putting the desk on any public URL. */
@@ -29,15 +42,35 @@ export type DeskConfig = {
 export declare class ApprovalDesk {
     private records;
     private seq;
+    private server?;
     cfg: DeskConfig;
     constructor(cfg: DeskConfig);
     enqueue(uri: string, price: string, body: string, content: string): string;
     get(id: string): DeskRecord | null;
     list(): DeskRecord[];
-    /** The human clicked Approve: sign and submit the release. */
+    /**
+     * The human clicked Approve.
+     *
+     * dev mode  (approver seed present): sign and submit here. One machine holds
+     *             both keys, which is fine for a testnet demo and nothing else.
+     * split mode (no approver seed):     build the challenge, sign it with the
+     *             principal only, and hand it to the phone. The money moves when
+     *             /signed comes back with the phone's signature.
+     */
     approve(id: string): Promise<DeskRecord>;
+    /** Split mode step 1: ask the phone to sign. Nothing is submitted yet. */
+    private requestPhoneSignature;
+    /**
+     * Split mode step 2: the phone answered. `signedXdr` is the transaction with
+     * the approver signature added, returned by signChallenge() on the phone.
+     * The desk cannot forge this: it does not hold the approver key, and the
+     * ledger rejects it if the signature is not over this exact transaction.
+     */
+    complete(id: string, signedXdr: string): Promise<DeskRecord>;
     deny(id: string, reason?: string): DeskRecord;
     /** Serve the pending list as JSON (the portal polls this). */
     api(handler: (req: IncomingMessage, res: ServerResponse) => void): (req: IncomingMessage, res: ServerResponse) => void;
     listen(port?: number): Promise<void>;
+    /** Stop serving. Without this the process never exits. */
+    close(): Promise<void>;
 }

package/dist/desk.js

@@ -10,12 +10,93 @@
 //   - 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"); }
+/**
+ * Check that a signature the phone sent back belongs to THIS payment.
+ * Returns a reason string if it does not, or null if it is fine.
+ */
+function verifyAgainstChallenge(signedXdr, rec) {
+    const ch = rec.challenge;
+    let signed;
+    try {
+        signed = TransactionBuilder.fromXDR(signedXdr, passphrase(recNetwork(rec)));
+    }
+    catch {
+        return "the phone returned something that is not a valid transaction for this network";
+    }
+    // 1. same transaction the human was shown: same hash, so the amount, payee,
+    //    source account and sequence are all identical to what was approved.
+    const hash = Buffer.from(signed.hash()).toString("hex");
+    if (hash !== ch.hash) {
+        return `signed a different transaction (${hash.slice(0, 12)}… was not issued for ${rec.id}, which is ${ch.hash.slice(0, 12)}…)`;
+    }
+    // 2. the phone added exactly one signature; nothing else changed.
+    if (signed.signatures.length < 2) {
+        return `only ${signed.signatures.length} signature(s); the vault needs 2`;
+    }
+    // 3. belt and braces: the payment still says what the record says.
+    const op = signed.operations?.[0];
+    if (!op || op.type !== "payment")
+        return "the transaction is not a payment";
+    if (op.destination !== rec.challenge.summary.payee)
+        return "payee does not match the approval";
+    const want = rec.challenge.summary.amount;
+    if (op.amount !== want && Number(op.amount) !== Number(want)) {
+        return `amount ${op.amount} does not match the approved ${want}`;
+    }
+    return null;
+}
+function recNetwork(rec) {
+    return rec.challenge.network;
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        req.on("data", (c) => {
+            data += c;
+            if (data.length > 64_000) {
+                reject(new Error("body too large"));
+                req.destroy();
+            }
+        });
+        req.on("end", () => resolve(data));
+        req.on("error", reject);
+    });
+}
 function same(a, b) {
     const x = Buffer.from(a), y = Buffer.from(b);
     return x.length === y.length && timingSafeEqual(x, y);
@@ -23,6 +104,7 @@ function same(a, b) {
 export class ApprovalDesk {
     records = new Map();
     seq = 0;
+    server;
     cfg;
     constructor(cfg) { this.cfg = cfg; }
     enqueue(uri, price, body, content) {
@@ -33,13 +115,23 @@ export class ApprovalDesk {
     }
     get(id) { return this.records.get(id) ?? null; }
     list() { return [...this.records.values()]; }
-    /** The human clicked Approve: sign and submit the release. */
+    /**
+     * The human clicked Approve.
+     *
+     * dev mode  (approver seed present): sign and submit here. One machine holds
+     *             both keys, which is fine for a testnet demo and nothing else.
+     * split mode (no approver seed):     build the challenge, sign it with the
+     *             principal only, and hand it to the phone. The money moves when
+     *             /signed comes back with the phone's signature.
+     */
     async approve(id) {
         const rec = this.records.get(id);
         if (!rec)
             throw new Error("unknown handle " + id);
         if (rec.status !== "pending")
             throw new Error(`already ${rec.status}`);
+        if (this.cfg.split)
+            return this.requestPhoneSignature(rec);
         if (!this.cfg.principal || !this.cfg.approver) {
             rec.status = "failed";
             rec.reason = "no human keys configured (portal signing not wired yet)";
@@ -56,6 +148,75 @@ export class ApprovalDesk {
         }
         return rec;
     }
+    /** Split mode step 1: ask the phone to sign. Nothing is submitted yet. */
+    async requestPhoneSignature(rec) {
+        if (!this.cfg.principal) {
+            rec.status = "failed";
+            rec.reason = "split mode needs the principal seed on the seller's side";
+            return rec;
+        }
+        try {
+            const challenge = await createApprovalChallenge({
+                vaultAddress: this.cfg.vault.address,
+                principal: Keypair.fromSecret(this.cfg.principal),
+                payee: this.cfg.payee,
+                amount: rec.price,
+                tokenCode: this.cfg.vault.token.getCode(),
+                tokenIssuer: this.cfg.vault.token.getIssuer() ?? "",
+                network: this.cfg.vault.network,
+                horizon: this.cfg.vault.horizon,
+                id: rec.id,
+                memo: rec.id,
+                decideWithinSeconds: this.cfg.decideWithinSeconds,
+            });
+            rec.challenge = challenge;
+            rec.qr = challengeQrPayload(challenge);
+            rec.status = "awaiting_phone";
+            console.log(`[desk] ${rec.id} sent to the phone: ${rec.price} for ${rec.uri}`);
+        }
+        catch (e) {
+            rec.status = "failed";
+            rec.reason = e.message;
+        }
+        return rec;
+    }
+    /**
+     * Split mode step 2: the phone answered. `signedXdr` is the transaction with
+     * the approver signature added, returned by signChallenge() on the phone.
+     * The desk cannot forge this: it does not hold the approver key, and the
+     * ledger rejects it if the signature is not over this exact transaction.
+     */
+    async complete(id, signedXdr) {
+        const rec = this.records.get(id);
+        if (!rec)
+            throw new Error("unknown handle " + id);
+        if (rec.status !== "awaiting_phone")
+            throw new Error(`not awaiting a phone signature (it is ${rec.status})`);
+        if (!rec.challenge)
+            throw new Error("no challenge was issued for " + id);
+        // Bind the answer to the question. Without this check the desk would submit
+        // any signed transaction posted to this route — including one the phone
+        // signed for a DIFFERENT payment, at a different price. That is how a
+        // payments bug becomes a wrong-amount bug.
+        const problem = verifyAgainstChallenge(signedXdr, rec);
+        if (problem) {
+            rec.status = "failed";
+            rec.reason = problem;
+            console.log(`[desk] ${id} rejected: ${problem}`);
+            return rec;
+        }
+        rec.signedXdr = signedXdr;
+        try {
+            const res = await submitApproved(signedXdr, this.cfg.vault.network, this.cfg.vault.horizon);
+            rec.status = "settled";
+            rec.tx = res.hash;
+        }
+        catch (e) {
+            rec.status = "failed";
+            rec.reason = e.message;
+        }
+        return rec;
+    }
     deny(id, reason = "denied by the approver") {
         const rec = this.records.get(id);
         if (!rec)
@@ -70,6 +231,7 @@ export class ApprovalDesk {
     api(handler) { return handler; }
     listen(port = this.cfg.port) {
         const srv = createServer(async (req, res) => {
+            // (server handle kept below so close() can stop it)
             const url = new URL(req.url ?? "/", "http://localhost");
             // 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.
@@ -91,8 +253,75 @@ export class ApprovalDesk {
                 }
                 if (url.pathname === "/list")
                     return send(200, this.list());
-                const m = url.pathname.match(/^\/(approve|deny)\/([\w-]+)$/);
+                // 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") {
+                        const body = await readBody(req);
+                        const { signedXdr } = JSON.parse(body || "{}");
+                        if (!signedXdr)
+                            return send(400, { error: "signedXdr is required" });
+                        return send(200, await this.complete(m[2], String(signedXdr)));
+                    }
                     const rec = m[1] === "approve" ? await this.approve(m[2]) : this.deny(m[2]);
                     return send(200, rec);
                 }
@@ -102,6 +331,15 @@ export class ApprovalDesk {
                 return send(400, { error: e.message });
             }
         });
+        this.server = srv;
         return new Promise((r) => srv.listen(port, () => r()));
     }
+    /** Stop serving. Without this the process never exits. */
+    close() {
+        return new Promise((r) => {
+            if (!this.server)
+                return r();
+            this.server.close(() => r());
+        });
+    }
 }

package/dist/gateway.d.ts

@@ -19,6 +19,14 @@ 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;

package/dist/gateway.js

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

package/dist/index.d.ts

@@ -9,3 +9,6 @@ export type { DeskConfig, DeskRecord } from "./desk.ts";
 export { portalPage } from "./portal.ts";
 export { PolicyEngine, DEFAULT_POLICY } from "./policy.ts";
 export type { Policy, SpendEvent, Verdict } from "./policy.ts";
+export { createApprovalChallenge, signChallenge, describeChallenge, submitApproved, challengeQrPayload, parseChallengeQr, } from "./phone.ts";
+export { txResultName } from "./vault.ts";
+export type { ApprovalChallenge } from "./phone.ts";

package/dist/index.js

@@ -7,3 +7,6 @@ export { PaydluxAgent } from "./agent.js";
 export { ApprovalDesk, newPortalKey } from "./desk.js";
 export { portalPage } from "./portal.js";
 export { PolicyEngine, DEFAULT_POLICY } from "./policy.js";
+// Split signing: the human's key lives on a phone, not in the seller's process.
+export { createApprovalChallenge, signChallenge, describeChallenge, submitApproved, challengeQrPayload, parseChallengeQr, } from "./phone.js";
+export { txResultName } from "./vault.js";

package/dist/phone.d.ts

@@ -0,0 +1,65 @@
+import { Keypair, StrKey } from "@stellar/stellar-sdk";
+import type { Network } from "./vault.ts";
+/** What the seller sends to the phone. Unsigned on purpose. */
+export type ApprovalChallenge = {
+    id: string;
+    network: Network;
+    /** the transaction, as XDR, signed by the principal only */
+    xdr: string;
+    /** what a human should read before signing */
+    summary: {
+        payee: string;
+        amount: string;
+        token: string;
+        tokenIssuer: string;
+        from: string;
+        memo?: string;
+        expiresAt?: number;
+    };
+    hash: string;
+};
+/**
+ * Build the payment and sign it with the principal key only. The result is
+ * deliberately incomplete: it reaches the vault's threshold of 2 only once the
+ * approver's signature is added.
+ */
+export declare function createApprovalChallenge(opts: {
+    vaultAddress: string;
+    principal: Keypair;
+    payee: string;
+    amount: string;
+    tokenCode: string;
+    tokenIssuer: string;
+    network: Network;
+    horizon: import("@stellar/stellar-sdk").Horizon.Server;
+    id: string;
+    memo?: string;
+    /** how long the human has to decide; the tx is dead after this */
+    decideWithinSeconds?: number;
+}): Promise<ApprovalChallenge>;
+/**
+ * What a person (or a phone app) does with a challenge: read it, decide, sign.
+ *
+ * This function does not talk to the network. It cannot submit anything. It
+ * cannot change the amount. It either adds a valid signature or returns the
+ * challenge untouched. That is the whole point of running it on the phone.
+ */
+export declare function signChallenge(challenge: ApprovalChallenge, approverSeed: string): string;
+/**
+ * Read a challenge without any secrets, to show a human. Deliberately separate
+ * from signing so a UI can render it on an untrusted machine.
+ */
+export declare function describeChallenge(challenge: ApprovalChallenge): string;
+/**
+ * The seller's side: take the phone's signature back and submit. Fails loudly
+ * if the transaction is still short of the vault's threshold.
+ */
+export declare function submitApproved(signedXdr: string, network: Network, horizon: import("@stellar/stellar-sdk").Horizon.Server): Promise<{
+    hash: string;
+    ok: true;
+}>;
+/** A stable, scannable form of a challenge — what a phone would read from a QR code. */
+export declare function challengeQrPayload(challenge: ApprovalChallenge): string;
+/** Parse what a QR code carried. Rejects a payload whose hash disagrees. */
+export declare function parseChallengeQr(payload: string): ApprovalChallenge;
+export { StrKey };