@paydlux/agent 0.1.20 → 0.1.22

package/dist/desk.js

@@ -19,6 +19,7 @@ import { TransactionBuilder } from "@stellar/stellar-sdk";
 import { passphrase } from "./vault.js";
 import { portalPage } 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 +122,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 = "";
@@ -222,6 +254,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()]; }
     /**
@@ -285,6 +357,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 +437,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 +510,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 +588,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). */
@@ -635,7 +796,37 @@ 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") {

package/dist/escrow.d.ts

@@ -0,0 +1,154 @@
+import { Asset, Keypair } from "@stellar/stellar-sdk";
+import { type Amount, type Network } from "./vault.ts";
+export declare const horizonUrl: (network: Network) => string;
+/** Horizon writes an asset as "native" or "USDC:Gissuer…". */
+export declare function assetToHorizonString(asset: Asset): string;
+export declare function assetFromHorizonString(s: string): Asset;
+/** The deal the buyer must lock into the ledger. */
+export type EscrowTerms = {
+    /** the order id the buyer must put in the creating transaction's memo */
+    orderId: string;
+    asset: Asset;
+    amount: Amount;
+    /**
+     * The account that funds and locks the escrow. Required to create one.
+     * Optional when VERIFYING: a seller usually does not care who the buyer is,
+     * only that the money is locked to the right order, price and vault. Pin it
+     * when the buyer's account was agreed up front, and any other account is
+     * refused.
+     */
+    buyer?: string;
+    /** the seller vault allowed to claim after release */
+    vault: string;
+    /** unix seconds; the vault cannot claim before this, the buyer can refund until this */
+    releaseAt: number;
+};
+export type Escrow = {
+    balanceId: string;
+    amount: Amount;
+    asset: string;
+    vault: string;
+    buyer: string;
+    releaseAt: number;
+    /** the transaction that created it, and the memo it carried */
+    txHash: string;
+    memo: string;
+    memoType: string;
+    /** true once the ledger says the balance is gone (claimed or swept) */
+    claimed: boolean;
+};
+export type EscrowCheck = {
+    ok: boolean;
+    reason?: string;
+    escrow?: Escrow;
+};
+/**
+ * Read a claimable balance back from the ledger and turn it into an Escrow.
+ *
+ * Horizon does NOT put the memo on the balance record — the memo lives on the
+ * transaction that created it. So the join between "this pile of money" and
+ * "that order" is one extra request. It is not optional: without it, two orders
+ * of the same price to the same vault are indistinguishable, and a seller could
+ * deliver order A and claim the escrow that was locked for order B.
+ */
+export declare function readEscrow(network: Network, balanceId: string): Promise<Escrow | null>;
+/**
+ * Does this on-chain escrow actually pay THIS deal?
+ *
+ * Every field is checked against the terms the gateway issued, because the
+ * buyer is untrusted: a buyer could lock 0.0000001 XLM, or lock money to a
+ * different vault, or set the timer to next year, or reuse the escrow from a
+ * previous order. Anything short of an exact match is a refusal.
+ */
+export declare function verifyEscrow(network: Network, balanceId: string, want: EscrowTerms, opts?: {
+    minReleaseSeconds?: number;
+    maxReleaseSeconds?: number;
+    /**
+     * The refund window being open is a requirement when ACCEPTING a deal —
+     * a buyer who locks money with a timer that already expired has locked
+     * nothing, because the seller could claim it the instant it lands.
+     *
+     * It is not a requirement when RELEASING one. An escrow that reached its
+     * timer is still a valid escrow; that is the normal, successful case. So
+     * the release path passes allowClosedWindow and gets the money it earned.
+     */
+    allowClosedWindow?: boolean;
+}): Promise<EscrowCheck>;
+/**
+ * The balance id of the escrow a submitted transaction created.
+ *
+ * Horizon does not return this to the submitter, and the id is not derivable
+ * from the account alone — it comes out of the transaction RESULT. A buyer who
+ * locks money with their own code needs this to know what to put in the
+ * `x-payment` header, so it is exported rather than kept private.
+ */
+export declare function escrowBalanceId(resultXdr: string, index?: number): string;
+/**
+ * Lock an escrow. Needs the BUYER's key: the money leaves the buyer's account,
+ * so only the buyer can put it in escrow. The seller never gets a signature on
+ * this transaction — that is the point.
+ */
+export declare function createEscrow(network: Network, terms: EscrowTerms, buyerKey: Keypair): Promise<{
+    escrow: Escrow;
+    txHash: string;
+}>;
+/**
+ * The seller takes the escrow. Two keys, always: the vault's threshold is 2 and
+ * the claim is a medium-threshold operation, so the agent key alone gets
+ * tx_bad_auth. `approverKey` lives on the phone in a real deployment.
+ *
+ * Refuses before the release time rather than letting Horizon reject it, so the
+ * caller gets a sentence instead of an error code — and so a buggy scheduler
+ * cannot accidentally try to release early in a loop.
+ */
+export declare function claimEscrow(network: Network, balanceId: string, vaultAddress: string, keys: {
+    agent: Keypair;
+    approver: Keypair;
+}): Promise<{
+    txHash: string;
+    claimedAt: number;
+}>;
+/**
+ * Release an escrow with the approver's key on a PHONE.
+ *
+ * `claimEscrow` needs both keys in one process. In a real deployment the human
+ * half never lives on the seller's machine — it lives on their phone. So build
+ * the claim here, sign it with the agent key, and hand it out as the same
+ * challenge the payment desk already uses: the phone reads a sentence
+ * ("claim 3.5 XLM from escrow ord_…"), signs, and sends back XDR.
+ *
+ * The phone is the only place the second signature can be added. This process
+ * cannot sign for it, cannot submit a completed claim, and cannot do anything
+ * with the half-signed transaction except wait.
+ */
+export declare function prepareEscrowRelease(network: Network, balanceId: string, vaultAddress: string, agent: Keypair): Promise<import("./phone.ts").ApprovalChallenge>;
+/**
+ * The buyer takes their money back. No seller signature, no permission, and it
+ * works right up to the release second — which is why the seller has to earn
+ * the release by proving delivery instead of waiting for the timer.
+ */
+export declare function refundEscrow(network: Network, balanceId: string, buyerKey: Keypair): Promise<{
+    txHash: string;
+}>;
+/**
+ * Every escrow currently waiting on this vault, newest first.
+ *
+ * Horizon filters claimable balances by claimant, which is exactly the seller's
+ * question: "what money is sitting in escrow for me, and when does each one
+ * become mine?" A balance that has already been claimed disappears from this
+ * list, so it doubles as the pending-release queue.
+ */
+export declare function pendingEscrows(network: Network, vaultAddress: string, limit?: number): Promise<Escrow[]>;
+/**
+ * Has this escrow been settled, and by whom?
+ *
+ * A claimed balance vanishes from Horizon, so the answer is in the operations
+ * of the transaction that claimed it. This is the proof-of-delivery receipt:
+ * the buyer can look up the same number on any explorer.
+ */
+export declare function escrowOutcome(network: Network, balanceId: string): Promise<{
+    settled: boolean;
+    by?: string;
+    txHash?: string;
+    at?: string;
+}>;