@paydlux/agent 0.0.0-stage → 0.1.0

package/dist/gateway.js

@@ -0,0 +1,252 @@
+// Paydlux gateway on Stellar — an HTTP resource server that answers 402 and
+// only serves the body once payment has actually landed on the ledger.
+//
+// Two modes per route:
+//
+//   preauth   the human already registered a mandate envelope for this seller
+//             and amount. The gateway hands it over, the agent signs, submits,
+//             and the ledger enforces the cap. No human needed at buy time.
+//
+//   approval  nothing is pre-authorised. The gateway verifies the request,
+//             holds it at the approval desk, and a person approves or denies.
+//             On approval the vault releases with principal + approver.
+//
+// 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 { ApprovalDesk } from "./desk.js";
+export const PAY_HEADER = "x-payment";
+export class Gateway {
+    routes = new Map();
+    mandates = new Map();
+    /** envelope hashes already redeemed, so one mandate = one delivery */
+    settled = new Set();
+    desk;
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+        for (const r of cfg.routes)
+            this.routes.set(r.uri, r);
+        this.desk = new ApprovalDesk({
+            vault: cfg.vault,
+            payee: cfg.payee,
+            principal: cfg.principal,
+            approver: cfg.approver,
+            port: cfg.deskPort ?? 4022,
+            portalKey: cfg.portalKey,
+        });
+    }
+    /** Mandates the vault currently holds, so the gateway can hand them out. */
+    async syncMandates() {
+        const s = await this.cfg.vault.signerSummary();
+        return s.signers.filter((x) => x.type === "preauth-mandate");
+    }
+    /** Register a pre-authorised mandate for a route (needs both human keys). */
+    async authorise(uri, spec, principal, approver) {
+        const r = this.routes.get(uri);
+        if (!r)
+            throw new Error(`no route ${uri}`);
+        if (spec.payee !== this.cfg.payee)
+            throw new Error("mandate payee does not match this gateway's payee");
+        const m = await this.cfg.vault.createMandate(spec, principal, approver);
+        this.mandates.set(m.hash, m);
+        return m;
+    }
+    /** The intent must be signed by a real agent key on the vault. */
+    verifyIntent(intent) {
+        if (!intent?.payload || !intent?.signature)
+            return false;
+        const [url, amount, vault] = intent.payload.split("|");
+        if (vault !== this.cfg.vault.address)
+            return false;
+        if (Number(amount) <= 0)
+            return false;
+        const age = Date.now() - Number(intent.payload.split("|").at(-1));
+        if (!Number.isFinite(age) || age > 5 * 60 * 1000)
+            return false;
+        const msg = Buffer.from(intent.payload);
+        const sig = Buffer.from(intent.signature, "base64");
+        for (const s of this.agentKeys) {
+            try {
+                if (Keypair.fromPublicKey(s).verify(msg, sig))
+                    return true;
+            }
+            catch { /* keep going */ }
+        }
+        return false;
+    }
+    /** Keys allowed to place approval requests. */
+    agentKeys = [];
+    requirements(uri) {
+        const r = this.routes.get(uri);
+        return {
+            scheme: "stellar-exact",
+            network: `stellar:${this.cfg.network}`,
+            maxAmountRequired: r.price,
+            resource: uri,
+            payTo: this.cfg.payee,
+            token: { code: this.cfg.vault.token.getCode(), issuer: this.cfg.vault.token.getIssuer() },
+            vault: this.cfg.vault.address,
+            mode: r.mode,
+            maxTimeoutSeconds: r.holdSeconds ?? 3600,
+            version: "1",
+        };
+    }
+    /**
+     * Check a proof against the live request before spending anything.
+     * The envelope must name this gateway's payee and this exact price, and it
+     * must be a hash the vault actually recognises.
+     */
+    async verify(uri, proof) {
+        const r = this.routes.get(uri);
+        if (!r)
+            throw new Error("unpriced resource " + uri);
+        if (r.mode !== "preauth")
+            throw new Error("route requires human approval, not a preauth envelope");
+        if (!proof.envelope)
+            throw new Error("preauth mode needs an envelope");
+        const tx = new Transaction(proof.envelope, passphrase(this.cfg.vault.network));
+        if (tx.source !== this.cfg.vault.address)
+            throw new Error("envelope is not drawn on this vault");
+        const ops = tx.operations;
+        if (ops.length !== 1 || ops[0].type !== "payment")
+            throw new Error("envelope must contain exactly one payment");
+        const op = ops[0];
+        // Stellar normalises amounts to 7 decimals, so compare as numbers.
+        if (Number(op.amount) !== Number(r.price)) {
+            throw new Error(`price mismatch: want ${r.price} got ${op.amount}`);
+        }
+        if (op.destination !== this.cfg.payee)
+            throw new Error("envelope pays a different seller");
+        if (op.asset?.getCode?.() !== this.cfg.vault.token.getCode()
+            || op.asset?.getIssuer?.() !== this.cfg.vault.token.getIssuer()) {
+            throw new Error("envelope pays in a different token");
+        }
+        const hash = tx.hash().toString("hex");
+        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),
+        // so decode it back to hex before comparing.
+        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"));
+        if (!registered.includes(hash)) {
+            throw new Error("mandate is not registered on the vault (expired or revoked)");
+        }
+        const tb = tx.timebounds;
+        if (tb?.maxTime && Number(tb.maxTime) * 1000 < Date.now())
+            throw new Error("mandate window closed");
+        return { route: r, tx, hash };
+    }
+    handler(getContent) {
+        return async (req, res) => {
+            const uri = (req.url ?? "/").split("?")[0];
+            if (uri === "/pay/status") {
+                const handle = new URL(req.url, "http://x").searchParams.get("handle");
+                const rec = handle ? this.desk.get(handle) : null;
+                res.writeHead(rec ? 200 : 404, { "content-type": "application/json" });
+                res.end(JSON.stringify(rec ?? { error: "unknown handle" }));
+                return;
+            }
+            const r = this.routes.get(uri);
+            if (!r) {
+                res.writeHead(404).end("not found");
+                return;
+            }
+            const body = await readBody(req);
+            const raw = req.headers[PAY_HEADER];
+            if (!raw) {
+                const reqs = this.requirements(uri);
+                res.writeHead(402, { [PAY_HEADER]: JSON.stringify(reqs) });
+                res.end(JSON.stringify({ error: "payment_required", accepts: reqs }));
+                return;
+            }
+            let proof;
+            try {
+                proof = JSON.parse(String(raw));
+            }
+            catch {
+                res.writeHead(400).end("bad payment header");
+                return;
+            }
+            if (!proof.intent && !proof.envelope) {
+                res.writeHead(400).end("payment header needs an envelope or an intent");
+                return;
+            }
+            // approval mode: the agent sends a signed intent, a human decides
+            if (r.mode === "approval") {
+                if (!proof.intent) {
+                    res.writeHead(402, { [PAY_HEADER]: JSON.stringify(this.requirements(uri)) });
+                    res.end(JSON.stringify({ error: "payment_invalid", reason: "approval mode needs a signed intent" }));
+                    return;
+                }
+                if (!this.verifyIntent(proof.intent)) {
+                    res.writeHead(402, { [PAY_HEADER]: JSON.stringify(this.requirements(uri)) });
+                    res.end(JSON.stringify({ error: "payment_invalid", reason: "intent signature is not from the agent key" }));
+                    return;
+                }
+                const handle = this.desk.enqueue(uri, r.price, body, getContent(uri));
+                res.writeHead(202, { "content-type": "application/json", "x-payment-hold": handle });
+                res.end(JSON.stringify({ status: "awaiting_approval", handle, desk: `http://127.0.0.1:${this.cfg.deskPort ?? 4022}` }));
+                return;
+            }
+            try {
+                await this.verify(uri, proof);
+            }
+            catch (e) {
+                res.writeHead(402, { [PAY_HEADER]: JSON.stringify(this.requirements(uri)) });
+                res.end(JSON.stringify({ error: "payment_invalid", reason: e.message }));
+                return;
+            }
+            // Submit the envelope. The agent signed it; the preauth hash is the
+            // second signature. If the ledger refuses, the body does not ship.
+            //
+            // Replay: Stellar de-duplicates an identical resubmission and hands back
+            // the ORIGINAL result instead of an error. So the money cannot move
+            // twice, but a naive gateway would happily serve the body twice. Check
+            // the ledger for an already-applied transaction before serving.
+            try {
+                const tx = new Transaction(proof.envelope, passphrase(this.cfg.vault.network));
+                const agentSig = tx.signatures?.[0];
+                if (!agentSig)
+                    throw new Error("envelope carries no agent signature");
+                const envHash = tx.hash().toString("hex");
+                if (this.settled.has(envHash))
+                    throw new Error("mandate already redeemed");
+                const applied = await this.cfg.vault.txExists(envHash);
+                if (applied) {
+                    this.settled.add(envHash);
+                    throw new Error("mandate already redeemed");
+                }
+                const out = await this.cfg.vault.horizon.submitTransaction(tx).catch(() => null);
+                if (!out)
+                    throw new Error("ledger rejected the envelope");
+                this.settled.add(envHash);
+                const content = getContent(uri);
+                res.writeHead(200, {
+                    "content-type": "application/json",
+                    "x-payment-response": JSON.stringify({ tx: out.hash, ledger: out.ledger }),
+                });
+                res.end(JSON.stringify({ data: content, tx: out.hash }));
+            }
+            catch (e) {
+                res.writeHead(402, { [PAY_HEADER]: JSON.stringify(this.requirements(uri)) });
+                res.end(JSON.stringify({ error: "payment_invalid", reason: e.message }));
+            }
+        };
+    }
+    listen(port, getContent = (u) => `payload for ${u} at ${new Date().toISOString()}`) {
+        const srv = createServer(this.handler(getContent));
+        return new Promise((resolve) => srv.listen(port, () => resolve()));
+    }
+}
+function readBody(req) {
+    return new Promise((resolve) => {
+        let acc = "";
+        req.on("data", (c) => (acc += c.toString()));
+        req.on("end", () => resolve(acc));
+    });
+}
+export { StellarTxError };

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { StellarVault, StellarTxError, passphrase, USDC_ISSUER } from "./vault.ts";
+export type { Network, Amount, Mandate, MandateSpec, VaultSigners } from "./vault.ts";
+export { Gateway } from "./gateway.ts";
+export type { GatewayConfig, Route, PaymentProof } from "./gateway.ts";
+export { PaydluxAgent } from "./agent.ts";
+export type { AgentConfig, PayResponse } from "./agent.ts";
+export { ApprovalDesk, newPortalKey } from "./desk.ts";
+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";

package/dist/index.js

@@ -0,0 +1,9 @@
+// Public API of the Paydlux agent-payment SDK.
+//
+//   import { StellarVault, Gateway, PaydluxAgent, ApprovalDesk } from "@paydlux/agent";
+export { StellarVault, StellarTxError, passphrase, USDC_ISSUER } from "./vault.js";
+export { Gateway } from "./gateway.js";
+export { PaydluxAgent } from "./agent.js";
+export { ApprovalDesk, newPortalKey } from "./desk.js";
+export { portalPage } from "./portal.js";
+export { PolicyEngine, DEFAULT_POLICY } from "./policy.js";

package/dist/policy.d.ts

@@ -0,0 +1,52 @@
+export type Policy = {
+    /** hard ceiling on any single payment */
+    maxPerPayment: number;
+    /** total across a calendar day */
+    dailyBudget: number;
+    /** sellers that may be paid; empty = any */
+    allowlist?: string[];
+    /** sellers that may never be paid, even if allowlisted */
+    denylist?: string[];
+    /** longest a mandate may stay live, seconds */
+    maxMandateTtl: number;
+    /**
+     * Mandates live at once. Stellar binds a pre-auth transaction to a sequence
+     * number, so only the newest can ever run — keep this at 1 and the state
+     * matches what the ledger will actually honour.
+     */
+    maxLiveMandates: number;
+};
+export declare const DEFAULT_POLICY: Policy;
+export type SpendEvent = {
+    at: number;
+    amount: number;
+    payee: string;
+    uri?: string;
+    mandateHash?: string;
+};
+export type Verdict = {
+    ok: true;
+} | {
+    ok: false;
+    rule: string;
+    detail: string;
+};
+export declare class PolicyEngine {
+    private events;
+    policy: Policy;
+    constructor(policy?: Partial<Policy>);
+    record(e: SpendEvent): void;
+    /** Everything spent in the current UTC day. */
+    spentToday(): number;
+    today(): SpendEvent[];
+    /**
+     * Check a request BEFORE any transaction is built. Returns the reason a
+     * payment is refused; the caller must not proceed on ok:false.
+     */
+    check(req: {
+        amount: number;
+        payee: string;
+        ttl?: number;
+        liveMandates?: number;
+    }): Verdict;
+}

package/dist/policy.js

@@ -0,0 +1,58 @@
+export const DEFAULT_POLICY = {
+    maxPerPayment: 50,
+    dailyBudget: 200,
+    allowlist: [],
+    denylist: [],
+    maxMandateTtl: 3600,
+    maxLiveMandates: 1,
+};
+export class PolicyEngine {
+    events = [];
+    policy;
+    constructor(policy = {}) {
+        this.policy = { ...DEFAULT_POLICY, ...policy };
+    }
+    record(e) { this.events.push(e); }
+    /** Everything spent in the current UTC day. */
+    spentToday() {
+        const start = new Date();
+        start.setUTCHours(0, 0, 0, 0);
+        const t = start.getTime();
+        return this.events.filter((e) => e.at >= t).reduce((a, b) => a + b.amount, 0);
+    }
+    today() {
+        const start = new Date();
+        start.setUTCHours(0, 0, 0, 0);
+        return this.events.filter((e) => e.at >= start.getTime());
+    }
+    /**
+     * Check a request BEFORE any transaction is built. Returns the reason a
+     * payment is refused; the caller must not proceed on ok:false.
+     */
+    check(req) {
+        const p = this.policy;
+        if (!(req.amount > 0))
+            return no("amount", "amount must be greater than zero");
+        if (req.amount > p.maxPerPayment) {
+            return no("max_per_payment", `${req.amount} exceeds the per-payment ceiling of ${p.maxPerPayment}`);
+        }
+        const spent = this.spentToday();
+        if (spent + req.amount > p.dailyBudget) {
+            return no("daily_budget", `${req.amount} would take today to ${(spent + req.amount).toFixed(2)}, over the ${p.dailyBudget} budget (spent ${spent.toFixed(2)})`);
+        }
+        if (p.denylist?.includes(req.payee))
+            return no("denylist", `${short(req.payee)} is blocked`);
+        if (p.allowlist?.length && !p.allowlist.includes(req.payee)) {
+            return no("allowlist", `${short(req.payee)} is not on the approved seller list`);
+        }
+        if (req.ttl !== undefined && req.ttl > p.maxMandateTtl) {
+            return no("max_ttl", `mandate would live ${req.ttl}s, longer than the ${p.maxMandateTtl}s limit`);
+        }
+        if (req.liveMandates !== undefined && req.liveMandates >= p.maxLiveMandates) {
+            return no("max_live", `${req.liveMandates} mandates already live (limit ${p.maxLiveMandates})`);
+        }
+        return { ok: true };
+    }
+}
+const no = (rule, detail) => ({ ok: false, rule, detail });
+const short = (k) => k.slice(0, 6) + "…" + k.slice(-4);

package/dist/portal.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { DeskRecord } from "./desk.ts";
+export declare function portalPage(records: DeskRecord[], vault: string, network: string, qs?: string): string;
+export declare function servePortal(req: IncomingMessage, res: ServerResponse, html: string): void;

package/dist/portal.js

@@ -0,0 +1,62 @@
+export function portalPage(records, vault, network, qs = "") {
+    const rows = records.length
+        ? records.map(render).join("\n")
+        : `<tr><td colspan="5" class="empty">nothing waiting</td></tr>`;
+    return `<!doctype html><html><head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Paydlux — approvals</title>
+<style>
+ :root{--ink:#0d0f0e;--line:#262a28;--text:#eceae4;--muted:#9aa39d;--gold:#e8b04b;--green:#5fbf8b}
+ *{box-sizing:border-box}
+ body{margin:0;background:var(--ink);color:var(--text);font:16px/1.5 -apple-system,"Avenir Next",system-ui,sans-serif;padding:24px}
+ h1{font-size:20px;margin:0 0 4px}
+ .sub{color:var(--muted);font-size:13px;margin-bottom:24px;word-break:break-all}
+ table{width:100%;border-collapse:collapse}
+ th{color:var(--muted);font-size:12px;text-transform:uppercase;letter-spacing:.06em;text-align:left;padding:8px;border-bottom:1px solid var(--line)}
+ td{padding:14px 8px;border-bottom:1px solid var(--line);vertical-align:middle}
+ .amt{font-weight:700;color:var(--gold);white-space:nowrap}
+ .uri{font-family:ui-monospace,monospace;font-size:13px}
+ .body{color:var(--muted);font-size:12px;max-width:340px;word-break:break-word}
+ button{border:0;border-radius:10px;padding:12px 18px;font-size:15px;font-weight:600;cursor:pointer;display:block;width:100%;margin:4px 0}
+ .yes{background:var(--green);color:#08110c}
+ .no{background:transparent;color:var(--muted);border:1px solid var(--line)}
+ .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}
+ .foot{margin-top:28px;color:var(--muted);font-size:12px}
+ @media(max-width:640px){.body{max-width:180px}}
+</style></head><body>
+<h1>Paydlux — approvals</h1>
+<div class="sub">vault ${vault} · ${network} · refreshed <span id="t">now</span></div>
+<table><thead><tr><th>when</th><th>what</th><th>cost</th><th>status</th><th></th></tr></thead>
+<tbody>${rows}</tbody></table>
+<div class="foot">Approving signs a Stellar transaction with your key. The vault needs two signatures, so this device alone cannot release funds.</div>
+<script>
+ const Q=${JSON.stringify(qs)};
+ async function act(kind,id){await fetch('/'+kind+'/'+id+Q,{method:'POST'});load()}
+ async function load(){const r=await fetch('/list'+Q);const d=await r.json();
+   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>'}
+ setInterval(load,3000);
+</script></body></html>`;
+}
+function render(r) {
+    const btns = r.status === "pending"
+        ? `<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("");
+    return `<tr>
+  <td>${new Date(r.at).toLocaleTimeString()}</td>
+  <td><div class="uri">${r.uri}</div><div class="body">${r.body || ""}</div></td>
+  <td class="amt">${r.price}</td>
+  <td><span class="st ${r.status}">${r.status}</span>${meta}</td>
+  <td style="min-width:130px">${btns}</td></tr>`;
+}
+export function servePortal(req, res, html) {
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(html);
+}

package/dist/vault.d.ts

@@ -0,0 +1,135 @@
+import { Asset, Horizon, Keypair, Networks } from "stellar-sdk";
+export type Network = "testnet" | "public";
+/**
+ * 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. */
+export declare class StellarTxError extends Error {
+    code: string;
+    constructor(code: string, cause?: unknown);
+}
+/** The network passphrase for a network name (needed to hash transactions). */
+export declare function passphrase(network: Network): string;
+/** Stellar amounts are strings with at most 7 decimals. */
+export type Amount = string;
+export type MandateSpec = {
+    payee: string;
+    amount: Amount;
+    /** seconds from now the mandate may first execute */
+    notBefore?: number;
+    /** seconds from now after which it can no longer execute */
+    ttl?: number;
+    /** memo attached to the payment, so the seller can match it to an order */
+    memo?: string;
+};
+export type Mandate = {
+    /** hex hash; also the signer that authorises the payment */
+    hash: string;
+    /** the built, unsigned transaction — hand this to the agent */
+    envelope: string;
+    spec: MandateSpec;
+    /** sequence number this envelope must be submitted at */
+    sequence: string;
+    expiresAt: number;
+};
+export type VaultSigners = {
+    /** the human who owns the money */
+    principal: string;
+    /** the human approval key (phone / browser wallet) */
+    approver: string;
+    /** the agent key, handed to the software doing the buying */
+    agent: string;
+};
+export declare class StellarVault {
+    readonly horizon: Horizon.Server;
+    readonly network: Network;
+    readonly address: string;
+    token: Asset;
+    signers: VaultSigners;
+    private constructor();
+    /** Fund a key on testnet. No captcha, no phone, no faucet hunt. */
+    static fundTestnet(kp: Keypair): Promise<string>;
+    /**
+     * Create a vault. `issuer` signs the token; the vault account itself is a
+     * multisig whose release threshold needs principal + approver, or agent +
+     * a pre-authorised mandate hash. Nothing else reaches threshold.
+     */
+    static create(opts: {
+        network: Network;
+        issuer: Keypair;
+        principal: Keypair;
+        approver: Keypair;
+        agent: Keypair;
+        tokenCode: string;
+        vaultSeed?: string;
+        startingBalance?: string;
+    }): Promise<StellarVault>;
+    /**
+     * A vault that settles in real Circle USDC instead of a test token.
+     * Circle mints USDC, so there is no issuer key for us to hold: the vault
+     * just needs a trustline, and money arrives from an exchange or Circle's
+     * faucet on testnet. Everything else (mandates, thresholds, replay) is the
+     * same code.
+     */
+    static usdcToken(network: Network): Asset;
+    /** Add a USDC trustline to an existing vault (needs both human keys). */
+    trustUsdc(principal: Keypair, approver: Keypair, limit?: string): Promise<Horizon.HorizonApi.SubmitTransactionResponse>;
+    /** Point this vault at USDC instead of a custom token. */
+    useUsdc(): this;
+    /** Re-attach to an existing vault by account id. */
+    static load(address: string, tokenCode: string, issuer: string, signers: VaultSigners, network: Network): Promise<StellarVault>;
+    /** The seller must opt in to holding our token before we can pay them. */
+    trustToken(seller: string, limit: string | undefined, sellerKeypair: Keypair): Promise<void>;
+    /** Move tokens into the vault. Only the vault's signers can move them out. */
+    deposit(amount: Amount, from: Keypair): Promise<string>;
+    /**
+     * Has this transaction already been applied? Horizon de-duplicates an
+     * identical resubmission and returns the original result, so "submit
+     * succeeded" does NOT mean "money moved just now". Sellers must check.
+     */
+    txExists(hash: string): Promise<boolean>;
+    balance(account?: string): Promise<Amount>;
+    /**
+     * Build a mandate and register it on the vault.
+     *
+     * Returns the envelope (base64 XDR) to hand to the agent plus its hash. The
+     * agent submits it with its own signature; the pre-auth signer supplies the
+     * second. The agent cannot alter it: any edit changes the hash, and the hash
+     * is the signer.
+     */
+    createMandate(spec: MandateSpec, principal: Keypair, approver: Keypair): Promise<Mandate>;
+    /** The agent's side: sign the envelope and submit. That is all it can do. */
+    executeMandate(mandate: Mandate, agentKeypair: Keypair): Promise<Horizon.HorizonApi.SubmitTransactionResponse>;
+    /**
+     * The human path: approve a payment directly. Needs principal + approver,
+     * so a stolen agent key cannot use it and a stolen phone cannot use it alone.
+     */
+    release(payee: string, amount: Amount, principal: Keypair, approver: Keypair, memo?: string): Promise<Horizon.HorizonApi.SubmitTransactionResponse>;
+    /**
+     * Kill every outstanding mandate at once. Any accepted transaction bumps the
+     * vault's sequence, which invalidates all pre-authorized hashes pointing at a
+     * later sequence. This is the panic button: it needs principal + approver,
+     * so a stolen agent key cannot pull it and a stolen phone cannot pull it alone.
+     */
+    revokeAll(principal: Keypair, approver: Keypair): Promise<{
+        revoked: number;
+        tx: string;
+    } | null>;
+    /** Rotate the agent key: a compromised agent is replaced, mandates die with it. */
+    rotateAgent(oldAgent: Keypair, newAgentPub: string, human: Keypair): Promise<Horizon.HorizonApi.SubmitTransactionResponse>;
+    /** Who can sign for this vault right now. */
+    signerSummary(): Promise<{
+        thresholds: {
+            low: any;
+            med: any;
+            high: any;
+        };
+        signers: any;
+    }>;
+    private tb;
+    private tbAt;
+}
+export { Keypair, Asset, Networks };