@paydlux/agent 0.1.21 → 0.1.23

package/dist/desk.js

@@ -17,8 +17,10 @@ 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 { DEFAULT_POLICY, normalizeCategory } from "./policy.js";
+import { portalPage, rulesPage } from "./portal.js";
 import { createApprovalChallenge, submitApproved, challengeQrPayload, } from "./phone.js";
+import { claimEscrow, prepareEscrowRelease } from "./escrow.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.
@@ -121,6 +123,37 @@ function verifyAgainstChallenge(signedXdr, rec) {
 function recNetwork(rec) {
     return rec.challenge.network;
 }
+/**
+ * Same binding check as verifyAgainstChallenge, for an escrow release. The
+ * signed transaction must be the claim the desk issued (same hash), carry both
+ * signatures, and — the escrow-specific part — claim EXACTLY the balance this
+ * record names. Without that last check a signature collected for one escrow
+ * could be replayed against another order's queue entry.
+ */
+function verifyEscrowAgainstChallenge(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";
+    }
+    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)}…)`;
+    }
+    if (signed.signatures.length < 2) {
+        return `only ${signed.signatures.length} signature(s); the vault needs 2`;
+    }
+    const op = signed.operations?.[0];
+    if (!op || op.type !== "claimClaimableBalance")
+        return "the transaction is not an escrow claim";
+    if (op.balanceId !== rec.escrowId) {
+        return `the claim targets ${String(op.balanceId).slice(0, 12)}…, not the escrow ${String(rec.escrowId).slice(0, 12)}… this approval is for`;
+    }
+    return null;
+}
 function readBody(req) {
     return new Promise((resolve, reject) => {
         let data = "";
@@ -149,6 +182,30 @@ function cookieOf(req, name) {
     }
     return null;
 }
+/**
+ * Form-field readers for /rules. A form is untrusted input arriving on a route
+ * that gates money, so each reader narrows to one type instead of trusting the
+ * field name. Empty means "not supplied", which lets a blank input fall back to
+ * the engine's default rather than becoming a zero.
+ */
+function numField(v) {
+    const s = String(v ?? "").trim();
+    if (!s)
+        return undefined;
+    const n = Number(s);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+/** One account id per line. Anything that is not G…56 is dropped, not warned. */
+function linesField(v) {
+    return String(v ?? "").split(/[\s,]+/).map((s) => s.trim().toUpperCase())
+        .filter((s) => /^G[A-Z2-7]{55}$/.test(s));
+}
+/** A Stellar account id, and nothing else. Same shape the policy engine accepts. */
+const isAccountId = (s) => /^G[A-Z2-7]{55}$/.test(s);
+/** A comma-separated list of ids carried by a hidden field. */
+function listField(v) {
+    return String(v ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+}
 function same(a, b) {
     const x = Buffer.from(a), y = Buffer.from(b);
     return x.length === y.length && timingSafeEqual(x, y);
@@ -156,6 +213,8 @@ function same(a, b) {
 export class ApprovalDesk {
     records = new Map();
     seq = 0;
+    /** when /rules last saved, so the page can say "saved" without a query flag */
+    rulesSavedAt = 0;
     server;
     cfg;
     constructor(cfg) { this.cfg = cfg; }
@@ -222,6 +281,46 @@ export class ApprovalDesk {
     findByKey(key) {
         return this.allByKey(key)[0] ?? null;
     }
+    /**
+     * Queue an escrow release for the human. This is the missing half of
+     * `paydlux escrow --release` on a --split vault: the money already sits in a
+     * claimable balance the buyer locked, so releasing it is the vault CLAIMING
+     * that balance — money coming IN, not going out. The claim still needs the
+     * vault's threshold of 2 (agent + approver), and the approver half lives on
+     * the phone, so it goes through the same challenge/sign/submit loop as a
+     * payment, tagged `kind: "escrow"` so the spending mandate — which caps
+     * money OUT — never touches it.
+     *
+     * The generic fields (uri/price/body) are filled so the portal page renders
+     * the row without knowing about escrow; the structured fields carry the
+     * truth the verification uses.
+     */
+    addEscrow(input) {
+        this.sweepExpired();
+        // One live record per balance id. A seller who runs --release twice must
+        // not get two Approve buttons for the same money: the second signature
+        // would fail on the ledger (balance already claimed) and confuse the human.
+        for (const r of this.records.values()) {
+            if (r.kind === "escrow" && r.escrowId === input.escrowId &&
+                r.status !== "denied" && r.status !== "failed" && r.status !== "expired")
+                return r;
+        }
+        const id = `esc_${input.escrowId.slice(-8)}${randomBytes(3).toString("hex")}`;
+        const label = input.order || `${input.escrowId.slice(0, 16)}…`;
+        const rec = {
+            id, at: Date.now(),
+            uri: `/escrow/${label}`,
+            // amount only, like a payment price; the asset rides in `asset` and
+            // reaches the phone as `token`, so the row never prints "3.5 XLM XLM".
+            price: input.amount,
+            body: `escrow release — buyer ${input.buyer ?? "?"} — balance ${input.escrowId}`,
+            status: "pending",
+            kind: "escrow", escrowId: input.escrowId, order: input.order, asset: input.asset,
+        };
+        this.records.set(id, rec);
+        console.log(`[desk] ${id} escrow release awaiting a human: ${rec.price} (${label})`);
+        return rec;
+    }
     get(id) { this.sweepExpired(); return this.records.get(id) ?? null; }
     list() { this.sweepExpired(); return [...this.records.values()]; }
     /**
@@ -253,13 +352,20 @@ export class ApprovalDesk {
         // `pending` deliberately does NOT count: that is a request nobody has
         // approved, and counting the whole queue would refuse the first approval
         // just because more requests exist than the budget can cover.
-        const committed = this.list().reduce((sum, r) => (r.id !== rec.id && (r.status === "awaiting_phone" || r.status === "approved"))
-            ? sum + Number(r.price) : sum, 0);
+        const waiting = this.list().filter((r) => r.id !== rec.id && (r.status === "awaiting_phone" || r.status === "approved"));
+        const committed = waiting.reduce((sum, r) => sum + Number(r.price), 0);
+        // The same promise, counted inside the payee's category. A category budget
+        // that ignored the queue would let the human approve five payments and have
+        // the fifth fail at submission. This desk pays one payee, so every waiting
+        // record belongs to that payee's bucket — no per-record lookup needed.
+        const category = policy.categoryOf(this.cfg.payee);
+        const committedInCategory = category ? committed : undefined;
         const verdict = policy.check({
             amount: Number(rec.price),
             payee: this.cfg.payee,
             ttl: this.cfg.decideWithinSeconds,
             committed,
+            committedInCategory,
         });
         if (verdict.ok)
             return null;
@@ -278,6 +384,136 @@ export class ApprovalDesk {
             uri: rec.uri, mandateHash: tx,
         });
     }
+    /** The rules as they stand, for the /rules page. */
+    policyView() {
+        return this.cfg.policy?.policy ?? { ...DEFAULT_POLICY };
+    }
+    /** What today's counters read, per category, for the /rules page. */
+    spentView() {
+        const p = this.cfg.policy;
+        if (!p)
+            return { total: 0, byCategory: {} };
+        const byCategory = {};
+        for (const name of Object.keys(p.policy.categories ?? {}))
+            byCategory[name] = p.spentInCategory(name);
+        return { total: p.spentToday(), byCategory };
+    }
+    /**
+     * The cross-origin gate used by every route that changes money or the rules
+     * that gate it. A cross-origin fetch POST is a CORS *simple request*: no
+     * preflight, so the attacker's page never sees the reply but the action still
+     * happens. Browsers always send Origin on POST and Sec-Fetch-Site on every
+     * request, so checking both closes that path while leaving local automation
+     * (curl, tests, the phone app on its own origin) alone.
+     *
+     * Returns a reason string when the request must be refused, null when it may
+     * proceed.
+     */
+    crossOriginGate(req) {
+        const origin = String(req.headers.origin ?? "");
+        if (origin) {
+            const here = String(req.headers.host ?? "").toLowerCase();
+            let oh;
+            try {
+                oh = new URL(origin).host.toLowerCase();
+            }
+            catch {
+                oh = "";
+            }
+            if (oh !== here)
+                return `this desk only accepts actions from itself, not from ${origin}`;
+        }
+        const site = String(req.headers["sec-fetch-site"] ?? "").toLowerCase();
+        if (site && site !== "same-origin" && site !== "none") {
+            return `this desk only accepts same-site actions (got ${site})`;
+        }
+        return null;
+    }
+    /**
+     * Apply an edit from the /rules form.
+     *
+     * The form carries the whole rule set, so this rebuilds rather than patches:
+     * what you see on the page is what gets saved, and a stale field cannot
+     * survive an edit. Names and numbers are validated inside PolicyEngine.update
+     * — this function only decides which fields the form is allowed to touch.
+     *
+     * Deliberately absent: maxMandateTtl and maxLiveMandates. Those are ledger
+     * constraints (sequence binding), not owner preferences, and a form field for
+     * them would be an invitation to configure a mandate the chain will refuse.
+     */
+    applyRules(action, form) {
+        const engine = this.cfg.policy;
+        if (!engine)
+            return { ...DEFAULT_POLICY };
+        const current = engine.policy;
+        const dropped = new Set(listField(form.get("delcat")));
+        // A category whose name was edited, old -> new. The page renders the name as
+        // a hidden field, so this only fires for a hand-crafted POST; keeping the
+        // mapping rather than dropping it means a rename never silently removes a
+        // wallet's ceiling.
+        const renamed = new Map();
+        const next = {};
+        const maxPer = numField(form.get("maxPerPayment"));
+        const daily = numField(form.get("dailyBudget"));
+        if (maxPer !== undefined)
+            next.maxPerPayment = maxPer;
+        if (daily !== undefined)
+            next.dailyBudget = daily;
+        next.allowlist = linesField(form.get("allowlist"));
+        next.denylist = linesField(form.get("denylist"));
+        // Categories: rebuilt from the rows the page shows, minus the ones the
+        // human removed, plus the one they just typed.
+        const categories = {};
+        for (const [key, value] of form) {
+            const m = /^cat_(.{1,32})_name$/.exec(key);
+            if (!m)
+                continue;
+            const was = m[1];
+            const name = normalizeCategory(value || was);
+            if (!name || dropped.has(was) || dropped.has(name))
+                continue;
+            if (name !== was)
+                renamed.set(was, name);
+            categories[name] = {
+                maxPerPayment: numField(form.get(`cat_${was}_max`)),
+                dailyBudget: numField(form.get(`cat_${was}_daily`)),
+            };
+        }
+        // Both "add" boxes are processed whenever they are filled, not only when
+        // their own button was pressed. The alternative is a form where typing a
+        // wallet and pressing the wrong button silently discards what was typed —
+        // and a rule that vanishes without an error is worse than a strict one.
+        const addCat = normalizeCategory(form.get("newcat"));
+        if (addCat && !dropped.has(addCat)) {
+            categories[addCat] = {
+                maxPerPayment: numField(form.get("newcat_max")),
+                dailyBudget: numField(form.get("newcat_daily")),
+            };
+        }
+        next.categories = categories;
+        // Wallet → category map: keep what is there, drop what was removed, add the
+        // new one. Rebuilt from the engine rather than the form, because a form
+        // field for the whole map would let a POST invent mappings for accounts
+        // nobody typed. A renamed bucket carries its wallets with it, so a rename
+        // can never quietly drop a ceiling.
+        const droppedMap = new Set(listField(form.get("delmap")));
+        const payeeCategory = {};
+        for (const [payee, name] of Object.entries(current.payeeCategory ?? {})) {
+            if (droppedMap.has(payee))
+                continue;
+            payeeCategory[payee] = renamed.get(name) ?? name;
+        }
+        const addWallet = String(form.get("newpayee") ?? "").trim().toUpperCase();
+        const addCatForWallet = normalizeCategory(form.get("newpayee_cat"));
+        if (isAccountId(addWallet) && addCatForWallet && categories[addCatForWallet]) {
+            payeeCategory[addWallet] = addCatForWallet;
+        }
+        next.payeeCategory = payeeCategory;
+        const policy = engine.update(next);
+        console.log(`[desk] spending rules updated (${action}): max ${policy.maxPerPayment}, daily ${policy.dailyBudget}, `
+            + `${Object.keys(policy.categories ?? {}).length} categories, ${Object.keys(policy.payeeCategory ?? {}).length} wallets mapped`);
+        return policy;
+    }
     async approve(id) {
         this.sweepExpired();
         const rec = this.records.get(id);
@@ -285,6 +521,27 @@ export class ApprovalDesk {
             throw new Error("unknown handle " + id);
         if (rec.status !== "pending")
             throw new Error(`already ${rec.status}`);
+        // An escrow release is money coming IN. The spending mandate caps money
+        // going OUT, so applying it here would refuse a release for a budget that
+        // the release does not touch — and would make the seller's own money
+        // unclaimable on a day they already spent.
+        if (rec.kind === "escrow") {
+            // dev mode (both keys on this machine): claim straight away.
+            if (this.cfg.approver && this.cfg.agentSeed) {
+                try {
+                    const out = await claimEscrow(this.cfg.vault.network, rec.escrowId, this.cfg.vault.address, { agent: Keypair.fromSecret(this.cfg.agentSeed), approver: Keypair.fromSecret(this.cfg.approver) });
+                    rec.status = "settled";
+                    rec.tx = out.txHash;
+                    console.log(`[desk] ${rec.id} ESCROW RELEASED ${rec.price} — ledger ${rec.tx}`);
+                }
+                catch (e) {
+                    rec.status = "failed";
+                    rec.reason = e.message;
+                }
+                return rec;
+            }
+            return this.requestEscrowSignature(rec);
+        }
         // Check before asking the phone. A human who approves a payment the mandate
         // will refuse has spent a Face ID scan and a signature for nothing.
         if (this.mandateBlock(rec, "refused before asking"))
@@ -344,6 +601,64 @@ export class ApprovalDesk {
         }
         return rec;
     }
+    /**
+     * Split mode step 1 for an ESCROW release: build the claim, sign it with the
+     * agent key, hand it to the phone. `prepareEscrowRelease` reads the ledger
+     * and refuses a balance that does not exist or whose timer has not passed,
+     * so a queued-but-fake escrow dies here with a real reason instead of
+     * reaching the human as a signable challenge.
+     */
+    async requestEscrowSignature(rec) {
+        if (!this.cfg.agentSeed) {
+            rec.status = "failed";
+            rec.reason = "an escrow release needs the agent seed on this machine to build the claim";
+            return rec;
+        }
+        try {
+            const challenge = await prepareEscrowRelease(this.cfg.vault.network, rec.escrowId, this.cfg.vault.address, Keypair.fromSecret(this.cfg.agentSeed));
+            // The challenge carries its own id; keep the desk's handle so
+            // /challenge/:id and /signed/:id line up with what the queue shows.
+            challenge.id = rec.id;
+            rec.challenge = challenge;
+            rec.qr = challengeQrPayload(challenge);
+            rec.status = "awaiting_phone";
+            console.log(`[desk] ${rec.id} escrow claim sent to the phone: ${rec.price}`);
+        }
+        catch (e) {
+            rec.status = "failed";
+            rec.reason = e.message;
+            console.log(`[desk] ${rec.id} escrow claim refused before asking: ${rec.reason}`);
+        }
+        return rec;
+    }
+    /**
+     * Split mode step 2 for an ESCROW release: the phone signed the claim.
+     * No mandate check — this is money coming IN — and no recordSpend: the
+     * daily budget counts payments OUT, and counting a release against it would
+     * make the seller's own earned money unclaimable.
+     */
+    async completeEscrow(rec, signedXdr) {
+        const problem = verifyEscrowAgainstChallenge(signedXdr, rec);
+        if (problem) {
+            rec.status = "failed";
+            rec.reason = problem;
+            console.log(`[desk] ${rec.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;
+            console.log(`[desk] ${rec.id} ESCROW RELEASED ${rec.price} — ledger ${rec.tx}`);
+        }
+        catch (e) {
+            rec.status = "failed";
+            rec.reason = e.message;
+            console.log(`[desk] ${rec.id} failed on the ledger: ${rec.reason}`);
+        }
+        return rec;
+    }
     /**
      * Split mode step 2: the phone answered. `signedXdr` is the transaction with
      * the approver signature added, returned by signChallenge() on the phone.
@@ -359,6 +674,11 @@ export class ApprovalDesk {
             throw new Error(`not awaiting a phone signature (it is ${rec.status})`);
         if (!rec.challenge)
             throw new Error("no challenge was issued for " + id);
+        // An escrow release verifies against its own shape (a claim of THIS
+        // balance id) and bypasses the spending mandate, which only caps payments
+        // going out.
+        if (rec.kind === "escrow")
+            return this.completeEscrow(rec, signedXdr);
         // 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
@@ -432,9 +752,14 @@ export class ApprovalDesk {
             tx: r.tx,
             /** what the buyer says it wants. Agent-controlled text: render as text. */
             wants: (r.body ?? "").slice(0, 200),
-            token: this.cfg.vault.token.getCode(),
+            token: r.kind === "escrow" ? r.asset ?? this.cfg.vault.token.getCode() : this.cfg.vault.token.getCode(),
             expiresAt: r.challenge?.summary.expiresAt,
             hash: r.challenge?.hash,
+            // The phone renders an escrow row differently: it is money IN, and the
+            // human verifies the balance id, not a payee.
+            kind: r.kind ?? "payment",
+            escrowId: r.escrowId,
+            order: r.order,
         }));
     }
     /** Serve the pending list as JSON (the portal polls this). */
@@ -604,6 +929,43 @@ export class ApprovalDesk {
                 }
                 if (url.pathname === "/list")
                     return send(200, this.list());
+                // The spending rules. Read-only view of the mandate the desk enforces,
+                // plus the form that edits it. Key-gated like everything else: these
+                // numbers decide what money leaves the vault, so an unauthenticated
+                // /rules would be an open "raise the budget" endpoint.
+                if (url.pathname === "/rules" && req.method === "GET") {
+                    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                    res.end(rulesPage(this.policyView(), this.spentView(), this.cfg.vault.address, this.cfg.vault.network, qs, Date.now() - this.rulesSavedAt < 15_000));
+                    return;
+                }
+                if (url.pathname === "/rules.js") {
+                    const body = readPortalFile("rules.js");
+                    if (body === null)
+                        return notFound(res);
+                    res.writeHead(200, {
+                        "content-type": "text/javascript; charset=utf-8",
+                        "x-content-type-options": "nosniff",
+                    });
+                    res.end(body);
+                    return;
+                }
+                if (url.pathname === "/rules" && req.method === "POST") {
+                    // Editing the rules moves money indirectly, so it gets the same
+                    // cross-origin gate as /approve: a page on another site must not be
+                    // able to POST a form that raises your daily budget.
+                    const gate = this.crossOriginGate(req);
+                    if (gate)
+                        return send(403, { error: "cross_origin", reason: gate });
+                    const body = await readBody(req);
+                    const form = new URLSearchParams(body);
+                    const action = form.get("action") ?? "save";
+                    const policy = this.applyRules(action, form);
+                    this.rulesSavedAt = Date.now();
+                    this.cfg.onPolicyChange?.(policy);
+                    res.writeHead(303, { location: "/rules" + (this.cfg.portalKey ? `?k=${encodeURIComponent(this.cfg.portalKey)}` : "") });
+                    res.end();
+                    return;
+                }
                 // The approver app's list view. Key-gated like everything else, and it
                 // carries no paid content and no challenge XDR.
                 if (url.pathname === "/queue")
@@ -635,36 +997,45 @@ export class ApprovalDesk {
                         wants: (rec.body ?? "").slice(0, 200),
                         memo: rec.challenge.summary.memo ?? "",
                         expiresAt: rec.challenge.summary.expiresAt,
+                        // An escrow challenge renders differently on the phone: the op
+                        // carries no amount and no payee, so the app shows the amount from
+                        // here and asks the human to check the balance id.
+                        kind: rec.kind ?? "payment",
+                        escrowId: rec.escrowId,
+                        // The claim op carries no amount, so the phone shows the amount
+                        // the desk read from the ledger alongside the balance id it puts
+                        // in front of the human.
+                        amount: rec.kind === "escrow" ? rec.price : undefined,
+                        asset: rec.kind === "escrow" ? rec.asset : undefined,
                     });
                 }
+                // The CLI's hand-off for `paydlux escrow --release` on a --split vault:
+                // queue this balance on the running desk so the phone can sign it.
+                // Key-gated like every other route, and it only queues — approving
+                // still needs the human's hold-and-sign on the phone.
+                if (url.pathname === "/escrow" && req.method === "POST") {
+                    const body = await readBody(req);
+                    const input = JSON.parse(body || "{}");
+                    if (!input.escrowId)
+                        return send(400, { error: "escrowId is required" });
+                    if (!input.amount || !input.asset)
+                        return send(400, { error: "amount and asset are required" });
+                    const rec = this.addEscrow({
+                        escrowId: String(input.escrowId),
+                        order: input.order ? String(input.order) : undefined,
+                        amount: String(input.amount),
+                        asset: String(input.asset),
+                        buyer: input.buyer ? String(input.buyer) : undefined,
+                    });
+                    return send(200, { id: rec.id, status: rec.status, escrowId: rec.escrowId });
+                }
                 const m = url.pathname.match(/^\/(approve|deny|signed)\/([\w-]+)$/);
                 if (m && req.method === "POST") {
                     // These routes move money, so they must not be reachable from another
-                    // page. A cross-origin fetch POST is a CORS *simple request*: no
-                    // preflight, so the attacker's page never sees the reply but the
-                    // approval still happens. Verified end to end: a page on another port
-                    // settled a parked payment and paid the seller. Browsers always send
-                    // Origin on POST and Sec-Fetch-Site on every request, so checking both
-                    // closes that path while leaving local automation (curl, tests, the
-                    // phone app on its own origin) alone.
-                    const origin = String(req.headers.origin ?? "");
-                    if (origin) {
-                        const here = String(req.headers.host ?? "").toLowerCase();
-                        let oh;
-                        try {
-                            oh = new URL(origin).host.toLowerCase();
-                        }
-                        catch {
-                            oh = "";
-                        }
-                        if (oh !== here) {
-                            return send(403, { error: "cross_origin", reason: `this desk only accepts actions from itself, not from ${origin}` });
-                        }
-                    }
-                    const site = String(req.headers["sec-fetch-site"] ?? "").toLowerCase();
-                    if (site && site !== "same-origin" && site !== "none") {
-                        return send(403, { error: "cross_origin", reason: `this desk only accepts same-site actions (got ${site})` });
-                    }
+                    // page — same gate as /rules, see crossOriginGate.
+                    const gate = this.crossOriginGate(req);
+                    if (gate)
+                        return send(403, { error: "cross_origin", reason: gate });
                     if (m[1] === "signed") {
                         const body = await readBody(req);
                         const { signedXdr } = JSON.parse(body || "{}");

package/dist/gateway.d.ts

@@ -2,7 +2,7 @@ import { type IncomingMessage, type Server, type ServerResponse } from "node:htt
 import { Keypair, Transaction } from "@stellar/stellar-sdk";
 import { StellarVault, StellarTxError, type Amount, type Mandate, type Network } from "./vault.ts";
 import { ApprovalDesk, type DeskStore } from "./desk.ts";
-import type { PolicyEngine } from "./policy.ts";
+import type { PolicyEngine, Policy } from "./policy.ts";
 import { claimEscrow } from "./escrow.ts";
 export declare const PAY_HEADER = "x-payment";
 export type Route = {
@@ -40,6 +40,12 @@ export type GatewayConfig = {
      * phone sends back.
      */
     split?: boolean;
+    /**
+     * The agent seed, passed to the desk so it can build an ESCROW RELEASE
+     * challenge (the claim is signed agent + phone approver). Same trust level
+     * as `principal`: it is the machine-side half, never the approving half.
+     */
+    agentSeed?: string;
     deskPort?: number;
     /** gate the approval portal behind a single unguessable link */
     portalKey?: string;
@@ -65,6 +71,11 @@ export type GatewayConfig = {
      * enforced — see DeskConfig.policy for why the gateway is the wrong place.
      */
     policy?: PolicyEngine;
+    /**
+     * Persist an edited spending policy. Passed straight to the desk; see
+     * DeskConfig.onPolicyChange for why it is a callback.
+     */
+    onPolicyChange?: (policy: Policy) => void;
 };
 export type PaymentProof = {
     /** pre-authorised envelope, base64 XDR, as issued by the vault */

package/dist/gateway.js

@@ -45,9 +45,11 @@ export class Gateway {
             port: cfg.deskPort ?? 4022,
             portalKey: cfg.portalKey,
             split: cfg.split,
+            agentSeed: cfg.agentSeed,
             publicHost: cfg.publicHost,
             decideWithinSeconds: cfg.decideWithinSeconds,
             policy: cfg.policy,
+            onPolicyChange: cfg.onPolicyChange,
         });
     }
     /** Mandates the vault currently holds, so the gateway can hand them out. */
@@ -89,6 +91,18 @@ export class Gateway {
                 : outcome.settled ? "released" : o.escrowId ? "gone" : "awaiting_escrow";
             if (state === "released" && !opts.includeSettled)
                 continue;
+            // A releasable escrow goes to the desk automatically, so the phone sees
+            // the release without anyone re-running the CLI. addEscrow is idempotent
+            // per balance id, so this is safe to call from a read path.
+            if (state === "releasable" && e) {
+                this.desk.addEscrow({
+                    escrowId: o.escrowId,
+                    order: o.id,
+                    amount: e.amount,
+                    asset: e.asset === "native" ? "XLM" : e.asset.split(":")[0],
+                    buyer: e.buyer,
+                });
+            }
             out.push({ ...o, state, escrow: e, outcome });
         }
         return out.sort((a, b) => (a.releaseAt ?? 0) - (b.releaseAt ?? 0));