@paydlux/agent 0.1.22 → 0.1.24

package/dist/desk.js

@@ -17,7 +17,8 @@ import { randomBytes, timingSafeEqual } from "node:crypto";
 import { Keypair } from "@stellar/stellar-sdk";
 import { TransactionBuilder } from "@stellar/stellar-sdk";
 import { passphrase } from "./vault.js";
-import { portalPage } from "./portal.js";
+import { DEFAULT_POLICY, normalizeCategory } from "./policy.js";
+import { portalPage, rulesPage } from "./portal.js";
 import { createApprovalChallenge, submitApproved, challengeQrPayload, } from "./phone.js";
 import { claimEscrow, prepareEscrowRelease } from "./escrow.js";
 /**
@@ -181,6 +182,30 @@ function cookieOf(req, name) {
     }
     return null;
 }
+/**
+ * Form-field readers for /rules. A form is untrusted input arriving on a route
+ * that gates money, so each reader narrows to one type instead of trusting the
+ * field name. Empty means "not supplied", which lets a blank input fall back to
+ * the engine's default rather than becoming a zero.
+ */
+function numField(v) {
+    const s = String(v ?? "").trim();
+    if (!s)
+        return undefined;
+    const n = Number(s);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+/** One account id per line. Anything that is not G…56 is dropped, not warned. */
+function linesField(v) {
+    return String(v ?? "").split(/[\s,]+/).map((s) => s.trim().toUpperCase())
+        .filter((s) => /^G[A-Z2-7]{55}$/.test(s));
+}
+/** A Stellar account id, and nothing else. Same shape the policy engine accepts. */
+const isAccountId = (s) => /^G[A-Z2-7]{55}$/.test(s);
+/** A comma-separated list of ids carried by a hidden field. */
+function listField(v) {
+    return String(v ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+}
 function same(a, b) {
     const x = Buffer.from(a), y = Buffer.from(b);
     return x.length === y.length && timingSafeEqual(x, y);
@@ -188,6 +213,17 @@ function same(a, b) {
 export class ApprovalDesk {
     records = new Map();
     seq = 0;
+    /** when /rules last saved, so the page can say "saved" without a query flag */
+    rulesSavedAt = 0;
+    /**
+     * When the approver app last polled /queue. The desktop portal reads /list and
+     * the phone reads /queue, so a hit here means a phone is pointed at THIS desk
+     * with THIS link. It is how a Mac can tell "the seller's phone is asleep" from
+     * "the phone is still talking to the desk from the last run" — the second one
+     * makes a live demo look dead, because the parked payment goes to a queue
+     * nobody is looking at.
+     */
+    lastPhonePollAt = 0;
     server;
     cfg;
     constructor(cfg) { this.cfg = cfg; }
@@ -325,13 +361,20 @@ export class ApprovalDesk {
         // `pending` deliberately does NOT count: that is a request nobody has
         // approved, and counting the whole queue would refuse the first approval
         // just because more requests exist than the budget can cover.
-        const committed = this.list().reduce((sum, r) => (r.id !== rec.id && (r.status === "awaiting_phone" || r.status === "approved"))
-            ? sum + Number(r.price) : sum, 0);
+        const waiting = this.list().filter((r) => r.id !== rec.id && (r.status === "awaiting_phone" || r.status === "approved"));
+        const committed = waiting.reduce((sum, r) => sum + Number(r.price), 0);
+        // The same promise, counted inside the payee's category. A category budget
+        // that ignored the queue would let the human approve five payments and have
+        // the fifth fail at submission. This desk pays one payee, so every waiting
+        // record belongs to that payee's bucket — no per-record lookup needed.
+        const category = policy.categoryOf(this.cfg.payee);
+        const committedInCategory = category ? committed : undefined;
         const verdict = policy.check({
             amount: Number(rec.price),
             payee: this.cfg.payee,
             ttl: this.cfg.decideWithinSeconds,
             committed,
+            committedInCategory,
         });
         if (verdict.ok)
             return null;
@@ -350,6 +393,136 @@ export class ApprovalDesk {
             uri: rec.uri, mandateHash: tx,
         });
     }
+    /** The rules as they stand, for the /rules page. */
+    policyView() {
+        return this.cfg.policy?.policy ?? { ...DEFAULT_POLICY };
+    }
+    /** What today's counters read, per category, for the /rules page. */
+    spentView() {
+        const p = this.cfg.policy;
+        if (!p)
+            return { total: 0, byCategory: {} };
+        const byCategory = {};
+        for (const name of Object.keys(p.policy.categories ?? {}))
+            byCategory[name] = p.spentInCategory(name);
+        return { total: p.spentToday(), byCategory };
+    }
+    /**
+     * The cross-origin gate used by every route that changes money or the rules
+     * that gate it. A cross-origin fetch POST is a CORS *simple request*: no
+     * preflight, so the attacker's page never sees the reply but the action still
+     * happens. Browsers always send Origin on POST and Sec-Fetch-Site on every
+     * request, so checking both closes that path while leaving local automation
+     * (curl, tests, the phone app on its own origin) alone.
+     *
+     * Returns a reason string when the request must be refused, null when it may
+     * proceed.
+     */
+    crossOriginGate(req) {
+        const origin = String(req.headers.origin ?? "");
+        if (origin) {
+            const here = String(req.headers.host ?? "").toLowerCase();
+            let oh;
+            try {
+                oh = new URL(origin).host.toLowerCase();
+            }
+            catch {
+                oh = "";
+            }
+            if (oh !== here)
+                return `this desk only accepts actions from itself, not from ${origin}`;
+        }
+        const site = String(req.headers["sec-fetch-site"] ?? "").toLowerCase();
+        if (site && site !== "same-origin" && site !== "none") {
+            return `this desk only accepts same-site actions (got ${site})`;
+        }
+        return null;
+    }
+    /**
+     * Apply an edit from the /rules form.
+     *
+     * The form carries the whole rule set, so this rebuilds rather than patches:
+     * what you see on the page is what gets saved, and a stale field cannot
+     * survive an edit. Names and numbers are validated inside PolicyEngine.update
+     * — this function only decides which fields the form is allowed to touch.
+     *
+     * Deliberately absent: maxMandateTtl and maxLiveMandates. Those are ledger
+     * constraints (sequence binding), not owner preferences, and a form field for
+     * them would be an invitation to configure a mandate the chain will refuse.
+     */
+    applyRules(action, form) {
+        const engine = this.cfg.policy;
+        if (!engine)
+            return { ...DEFAULT_POLICY };
+        const current = engine.policy;
+        const dropped = new Set(listField(form.get("delcat")));
+        // A category whose name was edited, old -> new. The page renders the name as
+        // a hidden field, so this only fires for a hand-crafted POST; keeping the
+        // mapping rather than dropping it means a rename never silently removes a
+        // wallet's ceiling.
+        const renamed = new Map();
+        const next = {};
+        const maxPer = numField(form.get("maxPerPayment"));
+        const daily = numField(form.get("dailyBudget"));
+        if (maxPer !== undefined)
+            next.maxPerPayment = maxPer;
+        if (daily !== undefined)
+            next.dailyBudget = daily;
+        next.allowlist = linesField(form.get("allowlist"));
+        next.denylist = linesField(form.get("denylist"));
+        // Categories: rebuilt from the rows the page shows, minus the ones the
+        // human removed, plus the one they just typed.
+        const categories = {};
+        for (const [key, value] of form) {
+            const m = /^cat_(.{1,32})_name$/.exec(key);
+            if (!m)
+                continue;
+            const was = m[1];
+            const name = normalizeCategory(value || was);
+            if (!name || dropped.has(was) || dropped.has(name))
+                continue;
+            if (name !== was)
+                renamed.set(was, name);
+            categories[name] = {
+                maxPerPayment: numField(form.get(`cat_${was}_max`)),
+                dailyBudget: numField(form.get(`cat_${was}_daily`)),
+            };
+        }
+        // Both "add" boxes are processed whenever they are filled, not only when
+        // their own button was pressed. The alternative is a form where typing a
+        // wallet and pressing the wrong button silently discards what was typed —
+        // and a rule that vanishes without an error is worse than a strict one.
+        const addCat = normalizeCategory(form.get("newcat"));
+        if (addCat && !dropped.has(addCat)) {
+            categories[addCat] = {
+                maxPerPayment: numField(form.get("newcat_max")),
+                dailyBudget: numField(form.get("newcat_daily")),
+            };
+        }
+        next.categories = categories;
+        // Wallet → category map: keep what is there, drop what was removed, add the
+        // new one. Rebuilt from the engine rather than the form, because a form
+        // field for the whole map would let a POST invent mappings for accounts
+        // nobody typed. A renamed bucket carries its wallets with it, so a rename
+        // can never quietly drop a ceiling.
+        const droppedMap = new Set(listField(form.get("delmap")));
+        const payeeCategory = {};
+        for (const [payee, name] of Object.entries(current.payeeCategory ?? {})) {
+            if (droppedMap.has(payee))
+                continue;
+            payeeCategory[payee] = renamed.get(name) ?? name;
+        }
+        const addWallet = String(form.get("newpayee") ?? "").trim().toUpperCase();
+        const addCatForWallet = normalizeCategory(form.get("newpayee_cat"));
+        if (isAccountId(addWallet) && addCatForWallet && categories[addCatForWallet]) {
+            payeeCategory[addWallet] = addCatForWallet;
+        }
+        next.payeeCategory = payeeCategory;
+        const policy = engine.update(next);
+        console.log(`[desk] spending rules updated (${action}): max ${policy.maxPerPayment}, daily ${policy.dailyBudget}, `
+            + `${Object.keys(policy.categories ?? {}).length} categories, ${Object.keys(policy.payeeCategory ?? {}).length} wallets mapped`);
+        return policy;
+    }
     async approve(id) {
         this.sweepExpired();
         const rec = this.records.get(id);
@@ -765,10 +938,68 @@ export class ApprovalDesk {
                 }
                 if (url.pathname === "/list")
                     return send(200, this.list());
+                // The spending rules. Read-only view of the mandate the desk enforces,
+                // plus the form that edits it. Key-gated like everything else: these
+                // numbers decide what money leaves the vault, so an unauthenticated
+                // /rules would be an open "raise the budget" endpoint.
+                if (url.pathname === "/rules" && req.method === "GET") {
+                    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                    res.end(rulesPage(this.policyView(), this.spentView(), this.cfg.vault.address, this.cfg.vault.network, qs, Date.now() - this.rulesSavedAt < 15_000));
+                    return;
+                }
+                if (url.pathname === "/rules.js") {
+                    const body = readPortalFile("rules.js");
+                    if (body === null)
+                        return notFound(res);
+                    res.writeHead(200, {
+                        "content-type": "text/javascript; charset=utf-8",
+                        "x-content-type-options": "nosniff",
+                    });
+                    res.end(body);
+                    return;
+                }
+                if (url.pathname === "/rules" && req.method === "POST") {
+                    // Editing the rules moves money indirectly, so it gets the same
+                    // cross-origin gate as /approve: a page on another site must not be
+                    // able to POST a form that raises your daily budget.
+                    const gate = this.crossOriginGate(req);
+                    if (gate)
+                        return send(403, { error: "cross_origin", reason: gate });
+                    const body = await readBody(req);
+                    const form = new URLSearchParams(body);
+                    const action = form.get("action") ?? "save";
+                    const policy = this.applyRules(action, form);
+                    this.rulesSavedAt = Date.now();
+                    this.cfg.onPolicyChange?.(policy);
+                    res.writeHead(303, { location: "/rules" + (this.cfg.portalKey ? `?k=${encodeURIComponent(this.cfg.portalKey)}` : "") });
+                    res.end();
+                    return;
+                }
                 // The approver app's list view. Key-gated like everything else, and it
-                // carries no paid content and no challenge XDR.
-                if (url.pathname === "/queue")
+                // carries no paid content and no challenge XDR. Polling it is also the
+                // proof that a phone is attached to this desk, so note the time.
+                if (url.pathname === "/queue") {
+                    this.lastPhonePollAt = Date.now();
                     return send(200, this.queue());
+                }
+                // "Is the phone actually connected?" for the Mac's demo app. Counts and
+                // public ledger identities only — no payment content, no challenge, no
+                // key material — and still behind the portal key like everything else.
+                if (url.pathname === "/status") {
+                    const all = this.list();
+                    return send(200, {
+                        ok: true,
+                        network: this.cfg.vault.network,
+                        vault: this.cfg.vault.address,
+                        approver: this.cfg.vault.signers.approver,
+                        pending: all.filter((r) => r.status === "pending").length,
+                        awaitingPhone: all.filter((r) => r.status === "awaiting_phone").length,
+                        settled: all.filter((r) => r.status === "settled").length,
+                        phoneSeenSecondsAgo: this.lastPhonePollAt
+                            ? Math.round((Date.now() - this.lastPhonePollAt) / 1000)
+                            : null,
+                    });
+                }
                 // The app fetches the pending transaction by handle rather than asking
                 // the human to paste 400 characters of base64 on a phone.
                 const ch = url.pathname.match(/^\/challenge\/([\w-]+)$/);
@@ -831,31 +1062,10 @@ export class ApprovalDesk {
                 const m = url.pathname.match(/^\/(approve|deny|signed)\/([\w-]+)$/);
                 if (m && req.method === "POST") {
                     // These routes move money, so they must not be reachable from another
-                    // page. A cross-origin fetch POST is a CORS *simple request*: no
-                    // preflight, so the attacker's page never sees the reply but the
-                    // approval still happens. Verified end to end: a page on another port
-                    // settled a parked payment and paid the seller. Browsers always send
-                    // Origin on POST and Sec-Fetch-Site on every request, so checking both
-                    // closes that path while leaving local automation (curl, tests, the
-                    // phone app on its own origin) alone.
-                    const origin = String(req.headers.origin ?? "");
-                    if (origin) {
-                        const here = String(req.headers.host ?? "").toLowerCase();
-                        let oh;
-                        try {
-                            oh = new URL(origin).host.toLowerCase();
-                        }
-                        catch {
-                            oh = "";
-                        }
-                        if (oh !== here) {
-                            return send(403, { error: "cross_origin", reason: `this desk only accepts actions from itself, not from ${origin}` });
-                        }
-                    }
-                    const site = String(req.headers["sec-fetch-site"] ?? "").toLowerCase();
-                    if (site && site !== "same-origin" && site !== "none") {
-                        return send(403, { error: "cross_origin", reason: `this desk only accepts same-site actions (got ${site})` });
-                    }
+                    // page — same gate as /rules, see crossOriginGate.
+                    const gate = this.crossOriginGate(req);
+                    if (gate)
+                        return send(403, { error: "cross_origin", reason: gate });
                     if (m[1] === "signed") {
                         const body = await readBody(req);
                         const { signedXdr } = JSON.parse(body || "{}");

package/dist/gateway.d.ts

@@ -2,7 +2,7 @@ import { type IncomingMessage, type Server, type ServerResponse } from "node:htt
 import { Keypair, Transaction } from "@stellar/stellar-sdk";
 import { StellarVault, StellarTxError, type Amount, type Mandate, type Network } from "./vault.ts";
 import { ApprovalDesk, type DeskStore } from "./desk.ts";
-import type { PolicyEngine } from "./policy.ts";
+import type { PolicyEngine, Policy } from "./policy.ts";
 import { claimEscrow } from "./escrow.ts";
 export declare const PAY_HEADER = "x-payment";
 export type Route = {
@@ -71,6 +71,11 @@ export type GatewayConfig = {
      * enforced — see DeskConfig.policy for why the gateway is the wrong place.
      */
     policy?: PolicyEngine;
+    /**
+     * Persist an edited spending policy. Passed straight to the desk; see
+     * DeskConfig.onPolicyChange for why it is a callback.
+     */
+    onPolicyChange?: (policy: Policy) => void;
 };
 export type PaymentProof = {
     /** pre-authorised envelope, base64 XDR, as issued by the vault */

package/dist/gateway.js

@@ -49,6 +49,7 @@ export class Gateway {
             publicHost: cfg.publicHost,
             decideWithinSeconds: cfg.decideWithinSeconds,
             policy: cfg.policy,
+            onPolicyChange: cfg.onPolicyChange,
         });
     }
     /** Mandates the vault currently holds, so the gateway can hand them out. */

package/dist/mcp.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Network } from "./vault.ts";
+import { type Policy } from "./policy.ts";
+type Cfg = {
+    path: string;
+    network: Network;
+    vault: string;
+    token: {
+        code: string;
+        issuer?: string;
+    };
+    payee?: string;
+    policy: Partial<Policy>;
+    /** the only secret this process holds. One of two vault signers. */
+    agentSeed: string;
+    principalPub: string;
+    approverPub?: string;
+    agentPub: string;
+    readOnly: boolean;
+};
+export declare function buildServer(cfg: Cfg): McpServer;
+export declare function start(): Promise<void>;
+export {};