@paydlux/agent 0.1.1 → 0.1.3

package/README.md

@@ -46,13 +46,39 @@ npx tsx stellar/demo.ts             # 12 checks, live testnet
 npx tsx stellar/story.ts --public   # one unguessable link; approve from your phone
 ```
 
-No wallet, no faucet, no config. The SDK also builds as an npm package
-(`npm run build` → `dist/`, published as `@paydlux/agent`):
+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
+```
+
+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.
+
+Use it as a package instead of cloning:
+
+```bash
+npm install @paydlux/agent
+```
 
 ```ts
 import { StellarVault, Gateway, PaydluxAgent } from "@paydlux/agent";
 ```
 
+`npm run build` produces `dist/`. The package depends only on
+`@stellar/stellar-sdk` — no transitive `toml`, so `npm audit` is clean.
+
 `story.ts --public` matters for demos: the portal has no login, so the printed
 link carries a 22-character key and every request without it gets a 403.
 

package/dist/agent.d.ts

@@ -1,4 +1,4 @@
-import { Horizon } from "stellar-sdk";
+import { Horizon } from "@stellar/stellar-sdk";
 import { type Mandate } from "./vault.ts";
 export type AgentConfig = {
     /** the agent's own key. One of two signers on the vault. */

package/dist/agent.js

@@ -5,7 +5,7 @@
 //
 // The agent holds one key of two. It can ask, and it can execute a mandate a
 // human already signed. It cannot move money on its own — the ledger refuses.
-import { Horizon, Keypair, Transaction } from "stellar-sdk";
+import { Horizon, Keypair, Transaction } from "@stellar/stellar-sdk";
 import { passphrase } from "./vault.js";
 const PAY_HEADER = "x-payment";
 export class PaydluxAgent {

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

@@ -11,11 +11,66 @@
 //   - the approval is a real ledger signature, not a database flag
 import { createServer } from "node:http";
 import { randomBytes, timingSafeEqual } from "node:crypto";
-import { Keypair } from "stellar-sdk";
+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";
 /** 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 +78,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 +89,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 +122,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 +205,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 +227,15 @@ export class ApprovalDesk {
                 }
                 if (url.pathname === "/list")
                     return send(200, this.list());
-                const m = url.pathname.match(/^\/(approve|deny)\/([\w-]+)$/);
+                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 +245,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

@@ -1,5 +1,5 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
-import { Transaction } from "stellar-sdk";
+import { Transaction } from "@stellar/stellar-sdk";
 import { StellarVault, StellarTxError, type Amount, type Mandate, type Network } from "./vault.ts";
 import { ApprovalDesk, type DeskStore } from "./desk.ts";
 export declare const PAY_HEADER = "x-payment";
@@ -58,7 +58,7 @@ export declare class Gateway {
         payTo: string;
         token: {
             code: string;
-            issuer: string;
+            issuer: string | undefined;
         };
         vault: string;
         mode: "approval" | "preauth";
@@ -72,7 +72,7 @@ export declare class Gateway {
      */
     verify(uri: string, proof: PaymentProof): Promise<{
         route: Route;
-        tx: Transaction<import("stellar-sdk").Memo<import("stellar-sdk").MemoType>, import("stellar-sdk").Operation[]>;
+        tx: Transaction;
         hash: string;
     }>;
     handler(getContent: (uri: string) => string): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/dist/gateway.js

@@ -13,8 +13,8 @@
 //
 // Either way the agent's key alone can never move money: threshold is 2.
 import { createServer } from "node:http";
-import { Keypair, StrKey, Transaction } from "stellar-sdk";
-import { StellarTxError, passphrase } from "./vault.js";
+import { Keypair, StrKey, Transaction } from "@stellar/stellar-sdk";
+import { StellarTxError, hex, passphrase } from "./vault.js";
 import { ApprovalDesk } from "./desk.js";
 export const PAY_HEADER = "x-payment";
 export class Gateway {
@@ -123,7 +123,7 @@ export class Gateway {
             || op.asset?.getIssuer?.() !== this.cfg.vault.token.getIssuer()) {
             throw new Error("envelope pays in a different token");
         }
-        const hash = tx.hash().toString("hex");
+        const hash = hex(tx.hash());
         if (hash !== proof.mandateHash)
             throw new Error("envelope hash does not match the declared mandate");
         // The vault stores the mandate as a strkey "T…" signer (base32 of the hash),
@@ -131,7 +131,7 @@ export class Gateway {
         const live = await this.cfg.vault.signerSummary();
         const registered = live.signers
             .filter((s) => s.type === "preauth-mandate")
-            .map((s) => StrKey.decodePreAuthTx(s.key).toString("hex"));
+            .map((s) => hex(StrKey.decodePreAuthTx(s.key)));
         if (!registered.includes(hash)) {
             throw new Error("mandate is not registered on the vault (expired or revoked)");
         }
@@ -212,7 +212,7 @@ export class Gateway {
                 const agentSig = tx.signatures?.[0];
                 if (!agentSig)
                     throw new Error("envelope carries no agent signature");
-                const envHash = tx.hash().toString("hex");
+                const envHash = hex(tx.hash());
                 if (this.settled.has(envHash))
                     throw new Error("mandate already redeemed");
                 const applied = await this.cfg.vault.txExists(envHash);

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 };

package/dist/phone.js

@@ -0,0 +1,163 @@
+// Paydlux — the approval half that lives on a phone.
+//
+// The problem this solves: until now the human's key was a string in the
+// seller's own process. That makes "2 of 2" a lie — one machine held both
+// halves, so whoever owned that machine was the human.
+//
+// Split it the way banks and hardware wallets do:
+//
+//   laptop (seller)   builds the payment, signs with the principal key,
+//                     sends the UNSIGNED transaction out
+//   phone  (human)    decodes it, shows a person what it says, signs with the
+//                     approver key, sends the signature back
+//   laptop (seller)   submits the now-complete transaction
+//
+// The approver seed never travels to the laptop. The phone needs no network to
+// sign — it only needs the transaction, and it can refuse.
+//
+// The signature is over the transaction hash, so the phone is signing THIS
+// payment: change the amount or the payee and the signature stops counting.
+import { Asset, Keypair, Memo, Operation, StrKey, TransactionBuilder, } from "@stellar/stellar-sdk";
+import { passphrase, StellarTxError, txResultName } from "./vault.js";
+/**
+ * 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 async function createApprovalChallenge(opts) {
+    const pass = passphrase(opts.network);
+    const acc = await opts.horizon.loadAccount(opts.vaultAddress);
+    const asset = opts.tokenCode === "XLM" ? Asset.native() : new Asset(opts.tokenCode, opts.tokenIssuer);
+    const built = new TransactionBuilder(acc, { fee: "100", networkPassphrase: pass })
+        .addOperation(Operation.payment({ destination: opts.payee, asset, amount: opts.amount }))
+        .setTimeout(opts.decideWithinSeconds ?? 1800);
+    if (opts.memo)
+        built.addMemo(Memo.text(opts.memo));
+    const tx = built.build();
+    tx.sign(opts.principal);
+    return {
+        id: opts.id,
+        network: opts.network,
+        xdr: tx.toXDR(),
+        summary: {
+            payee: opts.payee,
+            amount: opts.amount,
+            token: opts.tokenCode,
+            tokenIssuer: opts.tokenIssuer,
+            from: opts.vaultAddress,
+            memo: opts.memo,
+            expiresAt: tx.timeBounds ? Number(tx.timeBounds.maxTime) || undefined : undefined,
+        },
+        hash: Buffer.from(tx.hash()).toString("hex"),
+    };
+}
+/**
+ * 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 function signChallenge(challenge, approverSeed) {
+    const pass = passphrase(challenge.network);
+    const tx = TransactionBuilder.fromXDR(challenge.xdr, pass);
+    const hash = Buffer.from(tx.hash()).toString("hex");
+    if (hash !== challenge.hash) {
+        throw new Error("challenge was altered in transit — hash does not match, refusing to sign");
+    }
+    tx.sign(Keypair.fromSecret(approverSeed));
+    return tx.toXDR();
+}
+/**
+ * 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 function describeChallenge(challenge) {
+    const s = challenge.summary;
+    return [
+        `pay      ${s.amount} ${s.token}`,
+        `to       ${s.payee}`,
+        `from     ${s.from}`,
+        `issuer   ${s.tokenIssuer}`,
+        s.memo ? `note     ${readableMemo(s.memo)}` : null,
+        `network  ${challenge.network}`,
+        `signs    ${challenge.hash.slice(0, 16)}…`,
+    ].filter(Boolean).join("\n");
+}
+/**
+ * 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 async function submitApproved(signedXdr, network, horizon) {
+    const pass = passphrase(network);
+    const tx = TransactionBuilder.fromXDR(signedXdr, pass);
+    if (!tx.signatures.length)
+        throw new Error("no signatures on the returned transaction");
+    try {
+        await horizon.submitTransaction(tx);
+        return { hash: Buffer.from(tx.hash()).toString("hex"), ok: true };
+    }
+    catch (e) {
+        // Horizon answers 400 with the reason buried in the result codes. Surface
+        // the ledger's own word (BAD_AUTH, OP_INNER, ...) instead of "400".
+        let codes;
+        try {
+            codes = e?.resultResultCodes?.()?.results;
+        }
+        catch { /* shape differs */ }
+        codes ??= e?.response?.data?.extras?.result_codes?.results;
+        const resultXdr = e?.response?.data?.extras?.result_xdr;
+        const detail = codes?.join(",")
+            || (resultXdr ? txResultName(resultXdr) : undefined)
+            || resultXdr
+            || e.message;
+        throw new StellarTxError(detail, e);
+    }
+}
+/**
+ * A memo can arrive as text or as raw bytes depending on how the transaction was
+ * decoded. Show a human words, never a byte list.
+ */
+function readableMemo(memo) {
+    if (typeof memo === "string")
+        return memo;
+    if (Array.isArray(memo) || memo instanceof Uint8Array) {
+        try {
+            return Buffer.from(memo).toString("utf8");
+        }
+        catch {
+            return String(memo);
+        }
+    }
+    return String(memo ?? "");
+}
+/** A stable, scannable form of a challenge — what a phone would read from a QR code. */
+export function challengeQrPayload(challenge) {
+    return `paydlux:1\n${challenge.id}\n${challenge.network}\n${challenge.hash}\n${challenge.xdr}`;
+}
+/** Parse what a QR code carried. Rejects a payload whose hash disagrees. */
+export function parseChallengeQr(payload) {
+    const [tag, id, network, hash, xdr] = payload.split("\n");
+    if (tag !== "paydlux:1")
+        throw new Error("not a paydlux approval payload");
+    if (network !== "testnet" && network !== "public")
+        throw new Error("unknown network");
+    const tx = TransactionBuilder.fromXDR(xdr, passphrase(network));
+    const actual = Buffer.from(tx.hash()).toString("hex");
+    if (actual !== hash)
+        throw new Error("payload was tampered with: hash mismatch");
+    const op = tx.operations[0];
+    const asset = op.asset;
+    return {
+        id, network: network, xdr, hash,
+        summary: {
+            payee: op.destination,
+            amount: op.amount,
+            token: asset?.getCode ? asset.getCode() : "XLM",
+            tokenIssuer: asset?.getIssuer ? (asset.getIssuer() ?? "native") : "native",
+            from: tx.source,
+            memo: readableMemo(tx.memo?.value),
+        },
+    };
+}
+export { StrKey };

package/dist/portal.js

@@ -23,6 +23,8 @@ export function portalPage(records, vault, network, qs = "") {
  .st{font-size:12px;text-transform:uppercase;letter-spacing:.06em}
  .settled{color:var(--green)} .denied,.failed{color:#e07a6b} .pending{color:var(--gold)}
  .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}
  .foot{margin-top:28px;color:var(--muted);font-size:12px}
  @media(max-width:640px){.body{max-width:180px}}
 </style></head><body>
@@ -38,8 +40,9 @@ export function portalPage(records, vault, network, qs = "") {
    document.querySelector('tbody').innerHTML=d.map(row).join('')||'<tr><td colspan="5" class="empty">nothing waiting</td></tr>';
    document.getElementById('t').textContent=new Date().toLocaleTimeString()}
  function row(x){const st='<span class="st '+x.status+'">'+x.status+'</span>'+(x.tx?'<div class="tx">'+x.tx+'</div>':'')+(x.reason?'<div class="tx">'+x.reason+'</div>':'');
-  const btns=x.status==='pending'?'<button class="yes" onclick="act(\\'approve\\',\\''+x.id+'\\')">Approve</button><button class="no" onclick="act(\\'deny\\',\\''+x.id+'\\')">Deny</button>':'';
-  return '<tr><td>'+new Date(x.at).toLocaleTimeString()+'</td><td><div class="uri">'+x.uri+'</div><div class="body">'+(x.body||'')+'</div></td><td class="amt">'+x.price+'</td><td>'+st+'</td><td style="min-width:130px">'+btns+'</td></tr>'}
+  const btns=x.status==='pending'?'<button class="yes" onclick="act(\'approve\',\''+x.id+'\')">Approve</button><button class="no" onclick="act(\'deny\',\''+x.id+'\')">Deny</button>':'';
+  const ph=x.status==='awaiting_phone'?'<div class="tx">awaiting your phone</div>':'';
+  return '<tr><td>'+new Date(x.at).toLocaleTimeString()+'</td><td><div class="uri">'+x.uri+'</div><div class="body">'+(x.body||'')+'</div></td><td class="amt">'+x.price+'</td><td>'+st+ph+'</td><td style="min-width:130px">'+btns+'</td></tr>'}
  setInterval(load,3000);
 </script></body></html>`;
 }
@@ -48,7 +51,13 @@ function render(r) {
         ? `<button class="yes" onclick="act('approve','${r.id}')">Approve</button>
        <button class="no" onclick="act('deny','${r.id}')">Deny</button>`
         : "";
-    const meta = [r.tx && `<div class="tx">${r.tx}</div>`, r.reason && `<div class="tx">${r.reason}</div>`].filter(Boolean).join("");
+    // 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.
+    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>
+       <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("");
     return `<tr>
   <td>${new Date(r.at).toLocaleTimeString()}</td>
   <td><div class="uri">${r.uri}</div><div class="body">${r.body || ""}</div></td>

package/dist/vault.d.ts

@@ -1,12 +1,15 @@
-import { Asset, Horizon, Keypair, Networks } from "stellar-sdk";
+import { Asset, Horizon, Keypair, Networks } from "@stellar/stellar-sdk";
 export type Network = "testnet" | "public";
+/** stellar-sdk v17 hands back Uint8Array where v13 gave Buffer. One helper, one shape. */
+export declare function hex(b: Uint8Array | string): string;
 /**
  * Circle's own USDC issuer on Stellar. Not a wrapped token, not a bridge:
  * native, and Circle is the issuer. Anyone can put "USDC" on a token name —
  * only these two accounts are real money. Never accept any other issuer.
  */
 export declare const USDC_ISSUER: Record<Network, string>;
-/** A rejected Stellar transaction, with the ledger's own reason code. */
+/** Turn Horizon's result_xdr into a readable code, e.g. "BAD_AUTH". */
+export declare function txResultName(resultXdr: string): string | undefined;
 export declare class StellarTxError extends Error {
     code: string;
     constructor(code: string, cause?: unknown);

package/dist/vault.js

@@ -14,7 +14,11 @@
 // amount, the payee, the window, or run it twice — the ledger says no.
 //
 // Verified on testnet by stellar/probe-envelope.ts before this file existed.
-import { Account, Asset, Horizon, Keypair, Memo, Networks, Operation, StrKey, Transaction, TransactionBuilder, } from "stellar-sdk";
+import { Account, Asset, Horizon, Keypair, Memo, Networks, Operation, StrKey, Transaction, TransactionBuilder, } from "@stellar/stellar-sdk";
+/** stellar-sdk v17 hands back Uint8Array where v13 gave Buffer. One helper, one shape. */
+export function hex(b) {
+    return typeof b === "string" ? b : Buffer.from(b).toString("hex");
+}
 /**
  * Circle's own USDC issuer on Stellar. Not a wrapped token, not a bridge:
  * native, and Circle is the issuer. Anyone can put "USDC" on a token name —
@@ -25,6 +29,31 @@ export const USDC_ISSUER = {
     testnet: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
 };
 /** A rejected Stellar transaction, with the ledger's own reason code. */
+// Horizon hands back the transaction result as XDR:
+//   struct TransactionResult { int64 feeCharged; TransactionResultCode resultCode; ... }
+// so the code is the signed int32 at byte offset 8, not the first 8 bytes (that
+// is the fee). -6 = txBAD_AUTH = "not enough signatures", which is exactly what
+// a half-signed vault payment looks like.
+const TX_RESULT_CODES = {
+    0: "SUCCESS", [-1]: "FAILED", [-2]: "TOO_EARLY", [-3]: "TOO_LATE",
+    [-4]: "MISSING_OPERATION", [-5]: "BAD_SEQ", [-6]: "BAD_AUTH",
+    [-7]: "INSUFFICIENT_BALANCE", [-8]: "NO_ACCOUNT", [-9]: "INSUFFICIENT_FEE",
+    [-10]: "BAD_AUTH_EXTRA", [-11]: "INTERNAL_ERROR", [-12]: "NOT_SUPPORTED",
+    [-13]: "ACCOUNT_EXISTS", [-14]: "INSUFFICIENT_REWARDS",
+};
+/** Turn Horizon's result_xdr into a readable code, e.g. "BAD_AUTH". */
+export function txResultName(resultXdr) {
+    try {
+        const b = Buffer.from(resultXdr, "base64");
+        if (b.length < 12)
+            return undefined;
+        const n = b.readInt32BE(8);
+        return TX_RESULT_CODES[n] ?? `code ${n}`;
+    }
+    catch {
+        return undefined;
+    }
+}
 export class StellarTxError extends Error {
     code;
     constructor(code, cause) {
@@ -181,7 +210,7 @@ export class StellarVault {
         if (spec.memo)
             eb.addMemo(Memo.text(spec.memo));
         const envelope = eb.build();
-        const hash = envelope.hash().toString("hex");
+        const hash = hex(envelope.hash());
         // register the hash as a weight-1 signer. Two signatures now exist that
         // reach threshold 2: (agent + this hash) and (principal + approver).
         // setOptions needs med threshold 2, so registering a mandate always takes
@@ -289,7 +318,9 @@ async function sub(h, _pass, tx, ...signers) {
         }
         catch { /* shape differs */ }
         codes ??= e?.response?.data?.extras?.result_codes?.results;
-        const detail = codes?.join(",") || e?.response?.data?.extras?.result_xdr || e?.message || String(e);
+        const resultXdr = e?.response?.data?.extras?.result_xdr;
+        const named = resultXdr ? txResultName(resultXdr) : undefined;
+        const detail = codes?.join(",") || named || resultXdr || e?.message || String(e);
         throw new StellarTxError(detail, e);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paydlux/agent",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",
@@ -54,7 +54,7 @@
     "access": "public"
   },
   "dependencies": {
-    "stellar-sdk": "^13.3.0"
+    "@stellar/stellar-sdk": "^17.4.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.6",