@paydlux/agent 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ziibo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# Paydlux — spend-limited payments for AI agents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AI agents are starting to buy things (APIs, data, compute) over HTTP with
+stablecoin payments ([x402](https://x402.org)). Today an agent gets a raw
+crypto wallet: **no spending cap, no human approval, no refund path** — and
+real money has already been drained this way.
+
+Paydlux puts the guardrails **on the ledger** instead of in your code.
+
+## The Stellar path (primary — no smart contract, no faucet, no gas fight)
+
+There is no contract to audit. The whole mechanism is three native Stellar
+primitives:
+
+| primitive | what it gives us |
+|---|---|
+| issued asset / Circle USDC | the payment token |
+| multisig account | the vault — releasing funds needs 2 of the signers |
+| pre-authorised transaction hash | the spending mandate, as a *signer* |
+
+The mandate is the trick. We pre-build a transaction whose operations are
+exactly "pay N tokens to this payee, inside this time window, once", take its
+hash, and register that hash as a weight-1 signer on the vault. The agent key
+is also weight-1 and the threshold is 2. So the agent can reach threshold only
+by presenting **that exact transaction**. Change the amount, the payee, the
+token, the window, or try to run it twice, and the ledger refuses. A prompt
+injection cannot talk its way past a signature check.
+
+```
+stellar/vault.ts     create a 2-of-2 vault, register mandates, settle, revoke
+stellar/gateway.ts   HTTP 402 resource server; serves only after the ledger agrees
+stellar/agent.ts     the buyer side — one class, one method call
+stellar/desk.ts      approval queue: a human decides, in the clear
+stellar/portal.ts    the page that human looks at
+stellar/policy.ts    daily budget / seller allowlist (the part a ledger can't count)
+stellar/demo.ts      12 checks against the live testnet, one command
+stellar/probe-*.ts   the experiments that settled how the ledger behaves
+stellar/onboard.ts   keys → funded vault → printed agent key
+```
+
+### Try it
+
+```bash
+npm i
+npx tsx stellar/demo.ts             # 12 checks, live testnet
+npx tsx stellar/story.ts --public   # one unguessable link; approve from your phone
+```
+
+No wallet, no faucet, no config. The SDK also builds as an npm package
+(`npm run build` → `dist/`, published as `@paydlux/agent`):
+
+```ts
+import { StellarVault, Gateway, PaydluxAgent } from "@paydlux/agent";
+```
+
+`story.ts --public` matters for demos: the portal has no login, so the printed
+link carries a 22-character key and every request without it gets a 403.
+
+It prints what it proves:
+
+```
+— 4. human pre-authorises a mandate; agent executes it
+  ✅ content served, tx cabeb25ec92c2391…
+  ✅ seller 2.0000000, vault 48.0000000
+— 5. tamper with the envelope — the ledger refuses
+  ✅ refused: price mismatch: want 2 got 9.0000000
+— 6. replay the same mandate — money moves once
+  ✅ refused: mandate is not registered on the vault (expired or revoked)
+— 7. over-budget request is declined before anything is built
+  ✅ declined [max_per_payment]: 40 exceeds the per-payment ceiling of 10
+— 8. approval mode — a human decides
+  ✅ human approved → settled on-chain, tx bf4ce06c742f18f2…
+— 9. deny path — nothing moves
+  ✅ denied, balance unchanged at 42.0000000
+```
+
+Plug your own agent in:
+
+```ts
+import { PaydluxAgent } from "./stellar/agent.ts";
+
+const agent = new PaydluxAgent({ agentKey: process.env.AGENT_KEY! });
+const res = await agent.get("https://seller.example.com/api/data", { mandate });
+if (res.ok) console.log(res.data, "paid in tx", res.tx);
+```
+
+`npx tsx stellar/onboard.ts` creates the vault and prints that key. The key is
+**one of two signatures** — it cannot spend alone.
+
+### What is enforced where (said honestly)
+
+| enforced by Stellar | enforced by `policy.ts` |
+|---|---|
+| max per payment, payee, token, time window, one-shot execution | payments per day, running daily total, seller allow/deny list |
+
+The vault is one payment at a time; counting payments is our job. A rule break
+means we never build the transaction, so nothing reaches the ledger.
+
+Two ledger behaviours we verified rather than assumed, and designed around:
+
+- **A mandate is consumed on use.** After it runs, Stellar removes the pre-auth
+  signer. One mandate, one payment — no counter needed.
+- **A pre-auth transaction is bound to a sequence number**, so only the newest
+  mandate can ever run; an older one is in the past and can never fire.
+  `createMandate` therefore revokes previous mandates in the same transaction.
+  The product is deliberately one open order at a time.
+- **Resubmitting an identical envelope does not error.** Horizon returns the
+  *cached* result. The money cannot move twice, but a naive gateway would serve
+  the content twice — so `gateway.ts` checks the ledger for an already-applied
+  transaction before shipping anything.
+
+### Real money
+
+Circle issues USDC natively on Stellar — not wrapped, not bridged. `vault.ts`
+pins the issuer (`GA5ZSEJY…KZVN` on public, `GBBD47IF…FLA5` on testnet) and
+rejects any other token that calls itself USDC. The vault's USDC trustline is
+verified on testnet. Settlement fee is 0.00001 XLM.
+
+## The EVM path (research, kept for the deeper feature set)
+
+`contracts/` + `sdk/` are the earlier Base Sepolia work: a Solidity vault with
+escrow, proof-of-delivery receipts, session keys and Merkle-batched settlement
+(~$0.00005/payment). 61 contract tests pass, including 4×512-run fuzz suites
+over the core invariants.
+
+```
+contracts/src/AgentVault.sol       vault, mandates, settle, escrow, sessions, batches
+contracts/src/AgentCreditToken.sol USDC-backed credit token (deferred settlement)
+sdk/core.ts                        EIP-712 typed data (mirrors the contract exactly)
+sdk/gateway.ts                     x402-style HTTP 402 resource server
+sdk/approval.ts                    human-in-the-loop Approval Desk
+sdk/economics.ts                   unit economics from measured gas + live prices
+```
+
+```bash
+anvil --chain-id 31337 &
+cd contracts && forge build && forge test
+cd ../sdk && node demo.ts
+```
+
+## Status
+
+Working prototype on **Stellar testnet**, end to end, verified by `stellar/demo.ts`.
+The EVM contracts are tested but **not audited**. Nothing here has run with
+real funds. Do not use it with real funds.
+
+## Economics
+
+Stellar settles for ~0.00001 XLM, so per-payment cost is not the constraint —
+trust is. Pricing is 0.5¢ per settlement capped at 1%, plus SaaS for mandate
+management, dashboards and compliance evidence.
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,49 @@
+import { Horizon } from "stellar-sdk";
+import { type Mandate } from "./vault.ts";
+export type AgentConfig = {
+    /** the agent's own key. One of two signers on the vault. */
+    agentKey: string;
+    /** where to send the payment proof once a gateway asks for one */
+    network?: "testnet" | "public";
+    /** max attempts before giving up */
+    maxRetries?: number;
+    /** approval mode: how long to wait for a human, and how often to poll */
+    approvalTimeoutMs?: number;
+    pollMs?: number;
+    fetch?: typeof fetch;
+};
+export type PayResponse<T = string> = {
+    ok: boolean;
+    status: number;
+    data?: T;
+    tx?: string;
+    /** set when a human has to approve */
+    handle?: string;
+    desk?: string;
+    reason?: string;
+    requirements?: any;
+};
+export declare class PaydluxAgent {
+    private key;
+    private cfg;
+    constructor(cfg: AgentConfig);
+    get publicKey(): string;
+    /**
+     * GET a paid resource. Handles the 402 handshake: read what the seller
+     * wants, satisfy it, retry once with the proof attached.
+     */
+    get<T = string>(url: string, opts?: {
+        mandate?: Mandate;
+        body?: string;
+    }): Promise<PayResponse<T>>;
+    /**
+     * Sign and submit a mandate envelope directly to Horizon. Used when the
+     * gateway wants the payment settled before it serves anything.
+     */
+    submitEnvelope(mandate: Mandate): Promise<Awaited<ReturnType<Horizon.Server["submitTransaction"]>>>;
+    /**
+     * Wait for a human to decide on an approval-mode payment.
+     * Returns the settled record, or null on deny/timeout.
+     */
+    waitForApproval(desk: string, handle: string): Promise<any>;
+}

package/dist/agent.js

@@ -0,0 +1,113 @@
+// The agent side. This is all a buyer has to write.
+//
+//   const agent = new PaydluxAgent({ gateway: "http://localhost:4021", agentKey });
+//   const res = await agent.get("https://api.example.com/data");
+//
+// The agent holds one key of two. It can ask, and it can execute a mandate a
+// human already signed. It cannot move money on its own — the ledger refuses.
+import { Horizon, Keypair, Transaction } from "stellar-sdk";
+import { passphrase } from "./vault.js";
+const PAY_HEADER = "x-payment";
+export class PaydluxAgent {
+    key;
+    cfg;
+    constructor(cfg) {
+        this.key = Keypair.fromSecret(cfg.agentKey);
+        this.cfg = {
+            network: "testnet", maxRetries: 3, approvalTimeoutMs: 120_000, pollMs: 2_000, ...cfg,
+        };
+    }
+    get publicKey() { return this.key.publicKey(); }
+    /**
+     * GET a paid resource. Handles the 402 handshake: read what the seller
+     * wants, satisfy it, retry once with the proof attached.
+     */
+    async get(url, opts = {}) {
+        const f = this.cfg.fetch ?? fetch;
+        const first = await f(url, { method: opts.body ? "POST" : "GET", body: opts.body });
+        if (first.status !== 402) {
+            return { ok: first.ok, status: first.status, data: (await first.json().catch(() => first.text())) };
+        }
+        const reqs = parseRequirements(first.headers.get(PAY_HEADER));
+        if (!reqs)
+            return { ok: false, status: 402, reason: "seller sent 402 without payment terms", requirements: null };
+        if (reqs.mode === "approval") {
+            // Tell the seller we want it. The seller parks the request at the
+            // approval desk and a person decides. We do not get to decide.
+            const intent = signIntent(url, reqs, this.key);
+            const parked = await f(url, {
+                method: opts.body ? "POST" : "GET", body: opts.body,
+                headers: { [PAY_HEADER]: JSON.stringify({ intent }) },
+            });
+            const j = await parked.json().catch(() => ({}));
+            return { ok: false, status: parked.status, handle: j.handle, desk: j.desk, requirements: reqs,
+                reason: "a human has to approve this payment" };
+        }
+        if (!opts.mandate) {
+            return { ok: false, status: 402, requirements: reqs,
+                reason: "seller wants a pre-authorised mandate and none was supplied" };
+        }
+        // Sign locally, then send. Signing does not change the hash (the hash is
+        // over the unsigned body), so the vault still recognises the mandate.
+        const signed = new Transaction(opts.mandate.envelope, passphrase(this.cfg.network));
+        signed.sign(this.key);
+        const proof = { envelope: signed.toXDR(), mandateHash: opts.mandate.hash };
+        const retry = await f(url, {
+            method: opts.body ? "POST" : "GET",
+            body: opts.body,
+            headers: { [PAY_HEADER]: JSON.stringify(proof) },
+        });
+        const j = await retry.json().catch(() => ({}));
+        if (retry.status === 200) {
+            return { ok: true, status: 200, data: (j.data ?? j), tx: j.tx, requirements: reqs };
+        }
+        return { ok: false, status: retry.status, reason: j.reason ?? "payment rejected", requirements: reqs };
+    }
+    /**
+     * Sign and submit a mandate envelope directly to Horizon. Used when the
+     * gateway wants the payment settled before it serves anything.
+     */
+    async submitEnvelope(mandate) {
+        const tx = new Transaction(mandate.envelope, passphrase(this.cfg.network));
+        tx.sign(this.key);
+        const h = new Horizon.Server(this.cfg.network === "public"
+            ? "https://horizon.stellar.org" : "https://horizon-testnet.stellar.org");
+        return h.submitTransaction(tx);
+    }
+    /**
+     * Wait for a human to decide on an approval-mode payment.
+     * Returns the settled record, or null on deny/timeout.
+     */
+    async waitForApproval(desk, handle) {
+        const f = this.cfg.fetch ?? fetch;
+        const deadline = Date.now() + this.cfg.approvalTimeoutMs;
+        while (Date.now() < deadline) {
+            const r = await f(`${desk}/list`).then((x) => x.json()).catch(() => []);
+            const rec = r.find((x) => x.id === handle);
+            if (rec && rec.status === "settled")
+                return rec;
+            if (rec && (rec.status === "denied" || rec.status === "failed"))
+                return rec;
+            await new Promise((res) => setTimeout(res, this.cfg.pollMs));
+        }
+        return null;
+    }
+}
+/**
+ * A signed intent: proof the request came from the real agent key, so a random
+ * visitor cannot spam the approval desk with pending payments.
+ */
+function signIntent(url, reqs, key) {
+    const payload = `${url}|${reqs.maxAmountRequired}|${reqs.vault}|${Date.now()}`;
+    return { payload, signature: Buffer.from(key.sign(Buffer.from(payload))).toString("base64") };
+}
+function parseRequirements(header) {
+    if (!header)
+        return null;
+    try {
+        return JSON.parse(header);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/desk.d.ts

@@ -0,0 +1,43 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import type { StellarVault } from "./vault.ts";
+/** A portal link is a capability: whoever holds it can approve. So it is long,
+ *  random, and compared without leaking timing. */
+export declare function newPortalKey(): string;
+export type DeskRecord = {
+    id: string;
+    at: number;
+    uri: string;
+    price: string;
+    body: string;
+    status: "pending" | "approved" | "denied" | "settled" | "failed";
+    content?: string;
+    tx?: string;
+    reason?: string;
+};
+export type DeskStore = DeskRecord;
+export type DeskConfig = {
+    vault: StellarVault;
+    payee: string;
+    /** seeds of the two human keys. DEV ONLY — in production these live on the phone. */
+    principal?: string;
+    approver?: string;
+    port: number;
+    /** If set, the portal and its actions require this key in the URL.
+     *  Required before putting the desk on any public URL. */
+    portalKey?: string;
+};
+export declare class ApprovalDesk {
+    private records;
+    private seq;
+    cfg: DeskConfig;
+    constructor(cfg: DeskConfig);
+    enqueue(uri: string, price: string, body: string, content: string): string;
+    get(id: string): DeskRecord | null;
+    list(): DeskRecord[];
+    /** The human clicked Approve: sign and submit the release. */
+    approve(id: string): Promise<DeskRecord>;
+    deny(id: string, reason?: string): DeskRecord;
+    /** Serve the pending list as JSON (the portal polls this). */
+    api(handler: (req: IncomingMessage, res: ServerResponse) => void): (req: IncomingMessage, res: ServerResponse) => void;
+    listen(port?: number): Promise<void>;
+}

package/dist/desk.js

@@ -0,0 +1,107 @@
+// Paydlux approval desk on Stellar — the human-in-the-loop layer.
+//
+// A route in "approval" mode never settles on the agent's say-so. The gateway
+// parks the request here; a person opens the portal, reads what the agent
+// wanted to buy and for how much, and clicks Approve or Deny.
+//
+// Approving means signing a Stellar transaction with the human's key. The
+// vault needs principal + approver (threshold 2), so:
+//   - a stolen agent key cannot approve
+//   - a stolen phone cannot approve alone
+//   - the approval is a real ledger signature, not a database flag
+import { createServer } from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { Keypair } from "stellar-sdk";
+import { portalPage } from "./portal.js";
+/** A portal link is a capability: whoever holds it can approve. So it is long,
+ *  random, and compared without leaking timing. */
+export function newPortalKey() { return randomBytes(16).toString("base64url"); }
+function same(a, b) {
+    const x = Buffer.from(a), y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+export class ApprovalDesk {
+    records = new Map();
+    seq = 0;
+    cfg;
+    constructor(cfg) { this.cfg = cfg; }
+    enqueue(uri, price, body, content) {
+        const id = `pay_${(++this.seq).toString().padStart(4, "0")}`;
+        this.records.set(id, { id, at: Date.now(), uri, price, body, status: "pending", content });
+        console.log(`[desk] ${id} awaiting a human: ${price} for ${uri}`);
+        return id;
+    }
+    get(id) { return this.records.get(id) ?? null; }
+    list() { return [...this.records.values()]; }
+    /** The human clicked Approve: sign and submit the release. */
+    async approve(id) {
+        const rec = this.records.get(id);
+        if (!rec)
+            throw new Error("unknown handle " + id);
+        if (rec.status !== "pending")
+            throw new Error(`already ${rec.status}`);
+        if (!this.cfg.principal || !this.cfg.approver) {
+            rec.status = "failed";
+            rec.reason = "no human keys configured (portal signing not wired yet)";
+            return rec;
+        }
+        try {
+            const res = await this.cfg.vault.release(this.cfg.payee, rec.price, Keypair.fromSecret(this.cfg.principal), Keypair.fromSecret(this.cfg.approver), id);
+            rec.status = "settled";
+            rec.tx = String(res?.hash ?? "");
+        }
+        catch (e) {
+            rec.status = "failed";
+            rec.reason = e.message;
+        }
+        return rec;
+    }
+    deny(id, reason = "denied by the approver") {
+        const rec = this.records.get(id);
+        if (!rec)
+            throw new Error("unknown handle " + id);
+        if (rec.status !== "pending")
+            throw new Error(`already ${rec.status}`);
+        rec.status = "denied";
+        rec.reason = reason;
+        return rec;
+    }
+    /** Serve the pending list as JSON (the portal polls this). */
+    api(handler) { return handler; }
+    listen(port = this.cfg.port) {
+        const srv = createServer(async (req, res) => {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            // A public demo link must not be an open approval button. If a portalKey
+            // is configured, every route needs it, or the desk answers 403.
+            if (this.cfg.portalKey && !same(url.searchParams.get("k") ?? "", this.cfg.portalKey)) {
+                res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
+                res.end("403 — this approval link was never issued or has been rotated.");
+                return;
+            }
+            const qs = url.search;
+            const send = (code, obj) => {
+                res.writeHead(code, { "content-type": "application/json" });
+                res.end(JSON.stringify(obj));
+            };
+            try {
+                if (url.pathname === "/") {
+                    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                    res.end(portalPage(this.list(), this.cfg.vault.address, this.cfg.vault.network, qs));
+                    return;
+                }
+                if (url.pathname === "/list")
+                    return send(200, this.list());
+                const m = url.pathname.match(/^\/(approve|deny)\/([\w-]+)$/);
+                if (m && req.method === "POST") {
+                    const rec = m[1] === "approve" ? await this.approve(m[2]) : this.deny(m[2]);
+                    return send(200, rec);
+                }
+                return send(404, { error: "not found" });
+            }
+            catch (e) {
+                return send(400, { error: e.message });
+            }
+        });
+        return new Promise((r) => srv.listen(port, () => r()));
+    }
+}

package/dist/gateway.d.ts

@@ -0,0 +1,82 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { Transaction } from "stellar-sdk";
+import { StellarVault, StellarTxError, type Amount, type Mandate, type Network } from "./vault.ts";
+import { ApprovalDesk, type DeskStore } from "./desk.ts";
+export declare const PAY_HEADER = "x-payment";
+export type Route = {
+    uri: string;
+    price: Amount;
+    mode: "preauth" | "approval";
+    /** seconds the seller's content stays reserved while a human decides */
+    holdSeconds?: number;
+};
+export type GatewayConfig = {
+    vault: StellarVault;
+    network: Network;
+    /** the seller receiving payment (usually the vault owner's merchant account) */
+    payee: string;
+    routes: Route[];
+    /** human keys. In production these live on the phone, never here. */
+    principal?: string;
+    approver?: string;
+    deskPort?: number;
+    /** gate the approval portal behind a single unguessable link */
+    portalKey?: string;
+};
+export type PaymentProof = {
+    /** pre-authorised envelope, base64 XDR, as issued by the vault */
+    envelope?: string;
+    /** hex hash of the envelope, also the vault's preauth signer */
+    mandateHash?: string;
+    /** approval mode: a signed statement of what the agent wants to buy */
+    intent?: {
+        payload: string;
+        signature: string;
+    };
+};
+export declare class Gateway {
+    private routes;
+    private mandates;
+    /** envelope hashes already redeemed, so one mandate = one delivery */
+    private settled;
+    desk: ApprovalDesk;
+    cfg: GatewayConfig;
+    constructor(cfg: GatewayConfig);
+    /** Mandates the vault currently holds, so the gateway can hand them out. */
+    syncMandates(): Promise<any>;
+    /** 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>;
+    /** The intent must be signed by a real agent key on the vault. */
+    private verifyIntent;
+    /** Keys allowed to place approval requests. */
+    agentKeys: string[];
+    requirements(uri: string): {
+        scheme: string;
+        network: string;
+        maxAmountRequired: string;
+        resource: string;
+        payTo: string;
+        token: {
+            code: string;
+            issuer: string;
+        };
+        vault: string;
+        mode: "approval" | "preauth";
+        maxTimeoutSeconds: number;
+        version: string;
+    };
+    /**
+     * 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.
+     */
+    verify(uri: string, proof: PaymentProof): Promise<{
+        route: Route;
+        tx: Transaction<import("stellar-sdk").Memo<import("stellar-sdk").MemoType>, import("stellar-sdk").Operation[]>;
+        hash: string;
+    }>;
+    handler(getContent: (uri: string) => string): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    listen(port: number, getContent?: (uri: string) => string): Promise<void>;
+}
+export { StellarTxError };
+export type { DeskStore };