@paydlux/agent 0.1.20 → 0.1.22

package/dist/escrow.js

@@ -0,0 +1,325 @@
+// Paydlux escrow — a payment the buyer locks, not a payment the seller holds.
+//
+// The claim on the website is: "the escrow that holds a payment until delivery
+// is proven". This file is what makes that claim true, and it deliberately does
+// NOT use a smart contract. Stellar has a native primitive for exactly this
+// shape of deal — a claimable balance with two claimants and a time predicate —
+// and it is strictly better than a contract for a payment rail:
+//
+//   * no contract to audit, and no contract address that can be wrong
+//   * the money never sits in an account the seller controls
+//   * the reserve is paid by whoever creates the balance (the buyer), and the
+//     ledger gives it back when the balance is claimed
+//   * the rules are enforced by the network, not by our server being up
+//
+// The shape, verified against testnet (see stellar/escrow-check.ts):
+//
+//   claimant 1 — the seller vault, predicate NOT(abs_before = releaseAt)
+//                so the vault can only claim AFTER the release time
+//   claimant 2 — the buyer,          predicate abs_before = releaseAt
+//                so the buyer can claw the money back ONLY before it
+//
+// Three properties follow, and all three were observed on the ledger:
+//   1. before releaseAt the vault cannot take the money, even with both of its
+//      keys (tx_failed on the claim)
+//   2. after releaseAt the vault can take it, but only with BOTH keys — one
+//      signature is tx_bad_auth, so a stolen agent key cannot empty an escrow
+//   3. before releaseAt the buyer can always take it back, no seller consent
+//
+// So the seller's incentive is to prove delivery before the timer: releasing
+// early needs the human approval key anyway, and until then the money is the
+// buyer's to reclaim. That is the whole product in two claimants.
+import { Asset, Claimant, Horizon, Memo, Operation, TransactionBuilder, getClaimableBalanceIdFromResult, xdr, } from "@stellar/stellar-sdk";
+import { passphrase } from "./vault.js";
+const HORIZON_URL = {
+    testnet: "https://horizon-testnet.stellar.org",
+    public: "https://horizon.stellar.org",
+};
+export const horizonUrl = (network) => HORIZON_URL[network];
+/** Horizon writes an asset as "native" or "USDC:Gissuer…". */
+export function assetToHorizonString(asset) {
+    return asset.getAssetType() === "native"
+        ? "native"
+        : `${asset.getCode()}:${asset.getIssuer()}`;
+}
+export function assetFromHorizonString(s) {
+    if (s === "native")
+        return Asset.native();
+    const [code, issuer] = String(s).split(":");
+    if (!code || !issuer)
+        throw new Error(`unrecognised asset string "${s}"`);
+    return new Asset(code, issuer);
+}
+async function getJson(url) {
+    const r = await fetch(url);
+    if (!r.ok) {
+        const e = new Error(`horizon ${r.status} on ${url.split("?")[0]}`);
+        e.status = r.status;
+        throw e;
+    }
+    return r.json();
+}
+/**
+ * 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 async function readEscrow(network, balanceId) {
+    const h = horizonUrl(network);
+    let cb;
+    try {
+        cb = await getJson(`${h}/claimable_balances/${balanceId}`);
+    }
+    catch (e) {
+        if (e.status === 404 || e.status === 400)
+            return null;
+        throw e;
+    }
+    if (!cb?.claimants)
+        return null;
+    // The two claimants are distinguished by their predicate, not by position:
+    // the seller's is wrapped in `not`, the buyer's is the bare abs_before.
+    const seller = cb.claimants.find((c) => c.predicate?.not);
+    const buyer = cb.claimants.find((c) => !c.predicate?.not && c.predicate?.abs_before_epoch);
+    if (!seller || !buyer)
+        return null;
+    const txs = await getJson(`${h}/claimable_balances/${balanceId}/transactions?order=asc&limit=1`);
+    const tx = txs?._embedded?.records?.[0];
+    return {
+        balanceId,
+        amount: cb.amount,
+        asset: cb.asset,
+        vault: seller.destination,
+        buyer: buyer.destination,
+        releaseAt: Number(seller.predicate.not.abs_before_epoch),
+        txHash: tx?.hash ?? "",
+        memo: tx?.memo ?? "",
+        memoType: tx?.memo_type ?? "none",
+        claimed: false,
+    };
+}
+/**
+ * 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 async function verifyEscrow(network, balanceId, want, opts = {}) {
+    const e = await readEscrow(network, balanceId);
+    if (!e)
+        return { ok: false, reason: "no such claimable balance (already claimed, or never created)" };
+    if (e.asset !== assetToHorizonString(want.asset))
+        return { ok: false, reason: `escrow holds ${e.asset}, this route is priced in ${assetToHorizonString(want.asset)}` };
+    if (Number(e.amount) !== Number(want.amount))
+        return { ok: false, reason: `escrow holds ${e.amount}, this route costs ${want.amount}` };
+    if (e.vault !== want.vault)
+        return { ok: false, reason: "escrow names a different seller vault" };
+    if (want.buyer && e.buyer !== want.buyer)
+        return { ok: false, reason: "escrow was locked by a different account" };
+    // The memo is the only link between money and order. Exact match, or no deal.
+    if (e.memoType !== "text" || e.memo !== want.orderId)
+        return { ok: false, reason: `escrow memo "${e.memo}" does not match order ${want.orderId}` };
+    const now = Math.floor(Date.now() / 1000);
+    if (e.releaseAt <= now && !opts.allowClosedWindow) {
+        return { ok: false, reason: "the refund window has already closed — the seller could already have claimed it" };
+    }
+    if (opts.minReleaseSeconds != null && e.releaseAt - now < opts.minReleaseSeconds)
+        return { ok: false, reason: "release timer is too soon to prove delivery" };
+    if (opts.maxReleaseSeconds != null && e.releaseAt - now > opts.maxReleaseSeconds)
+        return { ok: false, reason: "release timer is further out than this route allows" };
+    return { ok: true, escrow: e };
+}
+/**
+ * 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 function escrowBalanceId(resultXdr, index = 0) {
+    return getClaimableBalanceIdFromResult(xdr.TransactionResult.fromXdr(resultXdr, "base64"), index);
+}
+/**
+ * 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 async function createEscrow(network, terms, buyerKey) {
+    if (!terms.buyer)
+        throw new Error("creating an escrow needs terms.buyer — the money leaves that account");
+    if (buyerKey.publicKey() !== terms.buyer)
+        throw new Error("the signing key is not the escrow buyer");
+    const h = new Horizon.Server(horizonUrl(network));
+    const acc = await h.loadAccount(terms.buyer);
+    const releaseAt = Math.floor(terms.releaseAt);
+    const tx = new TransactionBuilder(acc, { fee: "100", networkPassphrase: passphrase(network) })
+        .addOperation(Operation.createClaimableBalance({
+        asset: terms.asset,
+        amount: terms.amount,
+        // Order matters for readability only; the predicates are what enforce the deal.
+        claimants: [
+            new Claimant(terms.vault, Claimant.predicateNot(Claimant.predicateBeforeAbsoluteTime(String(releaseAt)))),
+            new Claimant(terms.buyer, Claimant.predicateBeforeAbsoluteTime(String(releaseAt))),
+        ],
+    }))
+        // The memo is the order id. Without it the escrow cannot be matched to an
+        // order, and verifyEscrow() will refuse it.
+        .addMemo(Memo.text(terms.orderId))
+        .setTimeout(300)
+        .build();
+    tx.sign(buyerKey);
+    const res = await h.submitTransaction(tx);
+    const balanceId = getClaimableBalanceIdFromResult(xdr.TransactionResult.fromXdr(res.result_xdr, "base64"), 0);
+    const escrow = await readEscrow(network, balanceId);
+    if (!escrow)
+        throw new Error("escrow was created but Horizon will not show it yet");
+    return { escrow, txHash: res.hash };
+}
+/**
+ * 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 async function claimEscrow(network, balanceId, vaultAddress, keys) {
+    const e = await readEscrow(network, balanceId);
+    if (!e)
+        throw new Error("no such escrow — it has already been claimed or refunded");
+    if (e.vault !== vaultAddress)
+        throw new Error(`escrow ${balanceId.slice(0, 12)}… pays a different vault`);
+    const now = Math.floor(Date.now() / 1000);
+    if (now < e.releaseAt)
+        throw new Error(`release timer has not passed (${e.releaseAt - now}s to go)`);
+    const h = new Horizon.Server(horizonUrl(network));
+    const acc = await h.loadAccount(vaultAddress);
+    const tx = new TransactionBuilder(acc, { fee: "100", networkPassphrase: passphrase(network) })
+        .addOperation(Operation.claimClaimableBalance({ balanceId }))
+        .setTimeout(120)
+        .build();
+    tx.sign(keys.agent);
+    tx.sign(keys.approver);
+    const res = await h.submitTransaction(tx);
+    return { txHash: res.hash, claimedAt: now };
+}
+/**
+ * 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 async function prepareEscrowRelease(network, balanceId, vaultAddress, agent) {
+    const e = await readEscrow(network, balanceId);
+    if (!e)
+        throw new Error("no such escrow — it has already been claimed or refunded");
+    if (e.vault !== vaultAddress)
+        throw new Error(`escrow ${balanceId.slice(0, 12)}… pays a different vault`);
+    const now = Math.floor(Date.now() / 1000);
+    if (now < e.releaseAt)
+        throw new Error(`release timer has not passed (${e.releaseAt - now}s to go)`);
+    const h = new Horizon.Server(horizonUrl(network));
+    const acc = await h.loadAccount(vaultAddress);
+    const tx = new TransactionBuilder(acc, { fee: "100", networkPassphrase: passphrase(network) })
+        .addOperation(Operation.claimClaimableBalance({ balanceId }))
+        .addMemo(Memo.text(`release ${e.memo}`))
+        .setTimeout(1800)
+        .build();
+    tx.sign(agent);
+    return {
+        id: `escrow:${balanceId}`,
+        network,
+        xdr: tx.toXDR(),
+        summary: {
+            payee: vaultAddress,
+            amount: e.amount,
+            token: e.asset === "native" ? "XLM" : e.asset.split(":")[0],
+            tokenIssuer: e.asset === "native" ? "" : e.asset.split(":")[1] ?? "",
+            from: `escrow ${balanceId.slice(0, 16)}…`,
+            memo: `order ${e.memo} — release timer passed`,
+            expiresAt: Number(tx.timeBounds?.maxTime) || undefined,
+        },
+        hash: Buffer.from(tx.hash()).toString("hex"),
+    };
+}
+/**
+ * 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 async function refundEscrow(network, balanceId, buyerKey) {
+    const e = await readEscrow(network, balanceId);
+    if (!e)
+        throw new Error("no such escrow — it has already been claimed or refunded");
+    if (e.buyer !== buyerKey.publicKey())
+        throw new Error("only the account that locked this escrow can refund it");
+    const now = Math.floor(Date.now() / 1000);
+    if (now >= e.releaseAt)
+        throw new Error("the refund window has closed");
+    const h = new Horizon.Server(horizonUrl(network));
+    const acc = await h.loadAccount(buyerKey.publicKey());
+    const tx = new TransactionBuilder(acc, { fee: "100", networkPassphrase: passphrase(network) })
+        .addOperation(Operation.claimClaimableBalance({ balanceId }))
+        .setTimeout(120)
+        .build();
+    tx.sign(buyerKey);
+    const res = await h.submitTransaction(tx);
+    return { txHash: res.hash };
+}
+/**
+ * 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 async function pendingEscrows(network, vaultAddress, limit = 200) {
+    const h = horizonUrl(network);
+    const list = await getJson(`${h}/claimable_balances?claimant=${vaultAddress}&order=desc&limit=${Math.min(limit, 200)}`);
+    const out = [];
+    for (const rec of list?._embedded?.records ?? []) {
+        const e = await readEscrow(network, rec.id);
+        if (e)
+            out.push(e);
+    }
+    return out.sort((a, b) => a.releaseAt - b.releaseAt);
+}
+/**
+ * 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 async function escrowOutcome(network, balanceId) {
+    const h = horizonUrl(network);
+    let ops;
+    try {
+        ops = await getJson(`${h}/claimable_balances/${balanceId}/operations?order=desc&limit=5`);
+    }
+    catch (e) {
+        if (e.status === 404 || e.status === 400)
+            return { settled: false };
+        throw e;
+    }
+    const claim = (ops?._embedded?.records ?? []).find((o) => o.type === "claim_claimable_balance");
+    if (!claim)
+        return { settled: false };
+    return { settled: true, by: claim.account ?? claim.source_account, txHash: claim.transaction_hash, at: claim.created_at };
+}

package/dist/gateway.d.ts

@@ -1,13 +1,14 @@
 import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
-import { Transaction } from "@stellar/stellar-sdk";
+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 { claimEscrow } from "./escrow.ts";
 export declare const PAY_HEADER = "x-payment";
 export type Route = {
     uri: string;
     price: Amount;
-    mode: "preauth" | "approval";
+    mode: "preauth" | "approval" | "escrow";
     /** seconds the seller's content stays reserved while a human decides */
     holdSeconds?: number;
     /**
@@ -15,6 +16,12 @@ export type Route = {
      * holdSeconds. Set it to 0 to make every single call cost its own approval.
      */
     collectSeconds?: number;
+    /**
+     * escrow mode: how long the buyer keeps the right to take their money back.
+     * The seller cannot touch the money before this passes, so it is also the
+     * deadline for proving delivery. Default 3600.
+     */
+    releaseSeconds?: number;
 };
 export type GatewayConfig = {
     vault: StellarVault;
@@ -33,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;
@@ -69,6 +82,12 @@ export type PaymentProof = {
         payload: string;
         signature: string;
     };
+    /**
+     * escrow mode: the id of the claimable balance the BUYER locked for this
+     * order. The money is not the seller's yet — it becomes claimable after the
+     * release timer, and only with both human keys.
+     */
+    escrow?: string;
 };
 export declare class Gateway {
     private routes;
@@ -80,6 +99,66 @@ export declare class Gateway {
     constructor(cfg: GatewayConfig);
     /** Mandates the vault currently holds, so the gateway can hand them out. */
     syncMandates(): Promise<any>;
+    /**
+     * Escrow orders this gateway has issued, keyed by order id.
+     *
+     * The order id is the ONLY link between a pile of money on the ledger and a
+     * piece of content behind a route: Horizon does not put a memo on the balance
+     * record, so matching money to a deal means reading the memo off the creating
+     * transaction and comparing it to an order we recognise. An escrow whose memo
+     * matches nothing here is money locked for a deal this seller never quoted, so
+     * it buys nothing.
+     */
+    private orders;
+    /**
+     * A stable order id for one request. Deterministic on purpose: a buyer who
+     * retries while the escrow settles must land on the same order, and a seller
+     * who restarts must be able to recognise the memo on money already locked.
+     * It is not a secret and it is not a capability — holding an id buys nothing
+     * without the matching escrow on the ledger.
+     */
+    orderId(uri: string, price: Amount, body: string): string;
+    /** Escrow orders, oldest first, with whatever the ledger says about each. */
+    escrowOrders(opts?: {
+        includeSettled?: boolean;
+    }): Promise<{
+        id: string;
+        uri: string;
+        price: Amount;
+        at: number;
+        escrowId?: string;
+        releaseAt?: number;
+        served: number;
+        state: string;
+        escrow: import("./escrow.ts").Escrow | null;
+        outcome: {
+            settled: boolean;
+            by?: string;
+            txHash?: string;
+            at?: string;
+        };
+    }[]>;
+    /**
+     * Take the money the buyer locked. Two keys, always — the vault's threshold
+     * is 2, so a stolen agent key cannot empty an escrow on its own.
+     */
+    releaseEscrow(orderId: string, keys: {
+        agent: Parameters<typeof claimEscrow>[3]["agent"];
+        approver: Parameters<typeof claimEscrow>[3]["approver"];
+    }): Promise<{
+        txHash: string;
+        claimedAt: number;
+    }>;
+    /**
+     * The split-key release: build the claim, sign it with the agent key, and
+     * hand it to the phone. This process cannot finish it — that is the point.
+     */
+    escrowReleaseChallenge(orderId: string, agent: Keypair): Promise<import("./phone.ts").ApprovalChallenge>;
+    /** Take the phone's signature back and settle the escrow on the ledger. */
+    submitEscrowRelease(signedXdr: string, orderId: string): Promise<{
+        hash: string;
+        ok: true;
+    }>;
     /** Register a pre-authorised mandate for a route (needs both human keys). */
     authorise(uri: string, spec: Parameters<StellarVault["createMandate"]>[0], principal: Parameters<StellarVault["createMandate"]>[1], approver: Parameters<StellarVault["createMandate"]>[2]): Promise<Mandate>;
     /**
@@ -104,9 +183,28 @@ export declare class Gateway {
             issuer: string | undefined;
         };
         vault: string;
-        mode: "approval" | "preauth";
+        mode: "approval" | "escrow" | "preauth";
         maxTimeoutSeconds: number;
         version: string;
+    } | {
+        scheme: string;
+        network: string;
+        maxAmountRequired: string;
+        resource: string;
+        payTo: string;
+        token: {
+            code: string;
+            issuer: string | undefined;
+        };
+        vault: string;
+        mode: "approval" | "escrow" | "preauth";
+        maxTimeoutSeconds: number;
+        version: string;
+        escrow: {
+            vault: string;
+            releaseSeconds: number;
+            memoMustBe: string;
+        };
     };
     /**
      * Check a proof against the live request before spending anything.