@paydlux/agent 0.1.21 → 0.1.23

package/dist/policy.d.ts

@@ -1,3 +1,22 @@
+/**
+ * A named bucket of spending with its own ceilings.
+ *
+ * This is the "transaction categories" idea: the same mandate, sliced by what
+ * the money is for. A vault can say "data APIs cost me $5 a day, my coding
+ * assistant costs $50 a month" without two vaults or two mandates.
+ *
+ * A category can only TIGHTEN the base mandate. It has no floor of its own:
+ * a category ceiling above the base ceiling is a number that can never bind,
+ * because the base ceiling already refused the payment. That asymmetry is the
+ * security property — adding a category can never widen what the agent may
+ * spend, only narrow it.
+ */
+export type CategoryRule = {
+    /** ceiling on any single payment in this category */
+    maxPerPayment?: number;
+    /** total across a calendar day for this category */
+    dailyBudget?: number;
+};
 export type Policy = {
     /** hard ceiling on any single payment */
     maxPerPayment: number;
@@ -15,14 +34,23 @@ export type Policy = {
      * matches what the ledger will actually honour.
      */
     maxLiveMandates: number;
+    /** named spend buckets, keyed by category name */
+    categories?: Record<string, CategoryRule>;
+    /** which category a seller's account falls into */
+    payeeCategory?: Record<string, string>;
 };
 export declare const DEFAULT_POLICY: Policy;
+/** A category name is rendered into HTML and stored in a config file, so it is
+ *  reduced to a safe alphabet here rather than escaped at every use site. */
+export declare function normalizeCategory(name: unknown): string;
 export type SpendEvent = {
     at: number;
     amount: number;
     payee: string;
     uri?: string;
     mandateHash?: string;
+    /** the bucket this spend counts against, when the payee is categorised */
+    category?: string;
 };
 export type Verdict = {
     ok: true;
@@ -36,6 +64,20 @@ export declare class PolicyEngine {
     policy: Policy;
     constructor(policy?: Partial<Policy>);
     record(e: SpendEvent): void;
+    /** Which bucket a seller's account belongs to, or undefined if uncategorised. */
+    categoryOf(payee: string): string | undefined;
+    /**
+     * Replace the policy from an untrusted source (the rules editor, a config
+     * file). Names are normalised and numbers validated here, so a bad value
+     * cannot smuggle markup or a negative ceiling into the engine.
+     *
+     * The owner may widen the counters this file keeps — the daily total and the
+     * allowlist are ours to count. What this cannot touch is the per-payment
+     * ceiling baked into the mandate's transaction hash: raise it here and the
+     * ledger still refuses above the mandate amount. `effectiveMaxPerPayment()`
+     * reports the number that actually binds so the UI can say so honestly.
+     */
+    update(next: Partial<Policy>): Policy;
     /**
      * Seed the day's total from the ledger instead of from this process's memory.
      *
@@ -44,9 +86,11 @@ export declare class PolicyEngine {
      * holds until the next restart. Seeding from the ledger makes the budget a
      * property of the vault, not of the uptime of whichever machine ran `sell`.
      */
-    seedFromLedger(amount: number): void;
+    seedFromLedger(amount: number, category?: string): void;
     /** Everything spent in the current UTC day. */
     spentToday(): number;
+    /** Everything spent in one category in the current UTC day. */
+    spentInCategory(category: string): number;
     today(): SpendEvent[];
     /**
      * Check a request BEFORE any transaction is built. Returns the reason a
@@ -66,5 +110,11 @@ export declare class PolicyEngine {
          * instead, which is the point of having a human in the loop.
          */
         committed?: number;
+        /**
+         * Same, per category. A category budget that ignores the queue has the same
+         * hole the daily budget had: the human approves five payments, the fifth
+         * fails, and the approval gesture was wasted.
+         */
+        committedInCategory?: number;
     }): Verdict;
 }

package/dist/policy.js

@@ -5,14 +5,81 @@ export const DEFAULT_POLICY = {
     denylist: [],
     maxMandateTtl: 3600,
     maxLiveMandates: 1,
+    categories: {},
+    payeeCategory: {},
 };
+/** A category name is rendered into HTML and stored in a config file, so it is
+ *  reduced to a safe alphabet here rather than escaped at every use site. */
+export function normalizeCategory(name) {
+    return String(name ?? "").trim().toLowerCase().replace(/[^a-z0-9_-]/g, "").slice(0, 32);
+}
 export class PolicyEngine {
     events = [];
     policy;
     constructor(policy = {}) {
         this.policy = { ...DEFAULT_POLICY, ...policy };
     }
-    record(e) { this.events.push(e); }
+    record(e) {
+        if (!e.category) {
+            const named = this.categoryOf(e.payee);
+            if (named)
+                e = { ...e, category: named };
+        }
+        this.events.push(e);
+    }
+    /** Which bucket a seller's account belongs to, or undefined if uncategorised. */
+    categoryOf(payee) {
+        const named = this.policy.payeeCategory?.[payee];
+        return named ? normalizeCategory(named) : undefined;
+    }
+    /**
+     * Replace the policy from an untrusted source (the rules editor, a config
+     * file). Names are normalised and numbers validated here, so a bad value
+     * cannot smuggle markup or a negative ceiling into the engine.
+     *
+     * The owner may widen the counters this file keeps — the daily total and the
+     * allowlist are ours to count. What this cannot touch is the per-payment
+     * ceiling baked into the mandate's transaction hash: raise it here and the
+     * ledger still refuses above the mandate amount. `effectiveMaxPerPayment()`
+     * reports the number that actually binds so the UI can say so honestly.
+     */
+    update(next) {
+        const merged = { ...this.policy, ...next };
+        // A garbage or blank number falls back to the rule that was in force a
+        // moment ago, NOT to DEFAULT_POLICY. Falling back to the default would make
+        // a malformed edit silently LOOSEN the mandate — an empty maxPerPayment on
+        // a form would turn a 2 into the default 50. Keeping the previous value
+        // means a bad field is a no-op, which is the only safe reading of a form
+        // that gates money.
+        merged.maxPerPayment = positive(merged.maxPerPayment, this.policy.maxPerPayment);
+        merged.dailyBudget = positive(merged.dailyBudget, this.policy.dailyBudget);
+        merged.maxMandateTtl = positive(merged.maxMandateTtl, this.policy.maxMandateTtl);
+        merged.maxLiveMandates = 1; // Stellar sequence binding: see Policy.maxLiveMandates
+        merged.allowlist = (merged.allowlist ?? []).filter(isAccount);
+        merged.denylist = (merged.denylist ?? []).filter(isAccount);
+        const cats = {};
+        for (const [name, rule] of Object.entries(merged.categories ?? {})) {
+            const key = normalizeCategory(name);
+            if (!key)
+                continue;
+            cats[key] = {
+                maxPerPayment: rule?.maxPerPayment === undefined ? undefined : positive(rule.maxPerPayment, merged.maxPerPayment),
+                dailyBudget: rule?.dailyBudget === undefined ? undefined : positive(rule.dailyBudget, merged.dailyBudget),
+            };
+        }
+        merged.categories = cats;
+        const map = {};
+        for (const [payee, name] of Object.entries(merged.payeeCategory ?? {})) {
+            if (!isAccount(payee))
+                continue;
+            const key = normalizeCategory(name);
+            if (key && cats[key])
+                map[payee] = key;
+        }
+        merged.payeeCategory = map;
+        this.policy = merged;
+        return this.policy;
+    }
     /**
      * Seed the day's total from the ledger instead of from this process's memory.
      *
@@ -21,14 +88,14 @@ export class PolicyEngine {
      * holds until the next restart. Seeding from the ledger makes the budget a
      * property of the vault, not of the uptime of whichever machine ran `sell`.
      */
-    seedFromLedger(amount) {
+    seedFromLedger(amount, category) {
         if (!(amount > 0))
             return;
         // One synthetic event at the start of the day: it counts toward the total
         // without pretending to be a payment this process can re-enact.
         const start = new Date();
         start.setUTCHours(0, 0, 0, 0);
-        this.record({ at: start.getTime(), amount, payee: "ledger" });
+        this.record({ at: start.getTime(), amount, payee: "ledger", category });
     }
     /** Everything spent in the current UTC day. */
     spentToday() {
@@ -37,6 +104,15 @@ export class PolicyEngine {
         const t = start.getTime();
         return this.events.filter((e) => e.at >= t).reduce((a, b) => a + b.amount, 0);
     }
+    /** Everything spent in one category in the current UTC day. */
+    spentInCategory(category) {
+        const start = new Date();
+        start.setUTCHours(0, 0, 0, 0);
+        const t = start.getTime();
+        return this.events
+            .filter((e) => e.at >= t && e.category === category)
+            .reduce((a, b) => a + b.amount, 0);
+    }
     today() {
         const start = new Date();
         start.setUTCHours(0, 0, 0, 0);
@@ -62,6 +138,22 @@ export class PolicyEngine {
         if (p.allowlist?.length && !p.allowlist.includes(req.payee)) {
             return no("allowlist", `${short(req.payee)} is not on the approved seller list`);
         }
+        // Category ceilings, checked last so a refusal names the narrowest rule it
+        // actually broke. A category can only tighten the base mandate: the base
+        // ceilings above already ran, so a category limit above them is inert.
+        const category = this.categoryOf(req.payee);
+        if (category) {
+            const rule = p.categories?.[category];
+            if (rule?.maxPerPayment !== undefined && req.amount > rule.maxPerPayment) {
+                return no("category_max_per_payment", `${req.amount} exceeds the ${category} per-payment ceiling of ${rule.maxPerPayment}`);
+            }
+            if (rule?.dailyBudget !== undefined) {
+                const inCat = this.spentInCategory(category) + (req.committedInCategory ?? 0);
+                if (inCat + req.amount > rule.dailyBudget) {
+                    return no("category_daily_budget", `${req.amount} would take the ${category} budget to ${(inCat + req.amount).toFixed(2)}, over its ${rule.dailyBudget} limit (${this.spentInCategory(category).toFixed(2)} paid${req.committedInCategory ? ` + ${req.committedInCategory.toFixed(2)} already approved and waiting` : ""})`);
+                }
+            }
+        }
         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`);
         }
@@ -73,3 +165,10 @@ export class PolicyEngine {
 }
 const no = (rule, detail) => ({ ok: false, rule, detail });
 const short = (k) => k.slice(0, 6) + "…" + k.slice(-4);
+/** A Stellar account id, and nothing else. */
+const isAccount = (s) => /^G[A-Z2-7]{55}$/.test(String(s ?? ""));
+/** Coerce to a usable positive number, falling back to the default. */
+function positive(v, fallback) {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}

package/dist/portal.d.ts

@@ -1,9 +1,26 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { DeskRecord } from "./desk.ts";
+import type { Policy } from "./policy.ts";
 /**
  * HTML escaping. Not optional: the request path and body are attacker-chosen
  * text that lands inside the one page that can authorise a payment.
  */
 export declare function esc(v: unknown): string;
 export declare function portalPage(records: DeskRecord[], vault: string, network: string, qs?: string): string;
+/**
+ * The spending rules, as a form the owner can read and edit.
+ *
+ * This is the surface the "customizable approval policy" request is really
+ * about: limits, approved wallets, and categories in one place, instead of
+ * command-line flags nobody outside a terminal can see.
+ *
+ * What it does NOT do is approve anything. Every payment still needs a human
+ * signature; these rules only decide what a human gets asked to sign. A rule
+ * set here can narrow the agent's reach, never widen what the ledger will
+ * accept, and the page says so in the same words the code enforces.
+ */
+export declare function rulesPage(policy: Policy, spent: {
+    total: number;
+    byCategory: Record<string, number>;
+}, vault: string, network: string, qs?: string, saved?: boolean): string;
 export declare function servePortal(req: IncomingMessage, res: ServerResponse, html: string): void;

package/dist/portal.js

@@ -19,12 +19,108 @@ export function portalPage(records, vault, network, qs = "") {
 <title>Paydlux — approvals</title>
 <link rel="stylesheet" href="portal.css"></head><body>
 <h1>Paydlux — approvals</h1>
-<div class="sub">vault ${esc(vault)} · ${esc(network)} · refreshed <span id="t">now</span></div>
+<div class="sub"><a class="nav" href="/${qs}">approvals</a> · <a class="nav" href="/rules${qs}">spending rules</a><br>
+vault ${esc(vault)} · ${esc(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 src="portal.js"></script></body></html>`;
 }
+/**
+ * The spending rules, as a form the owner can read and edit.
+ *
+ * This is the surface the "customizable approval policy" request is really
+ * about: limits, approved wallets, and categories in one place, instead of
+ * command-line flags nobody outside a terminal can see.
+ *
+ * What it does NOT do is approve anything. Every payment still needs a human
+ * signature; these rules only decide what a human gets asked to sign. A rule
+ * set here can narrow the agent's reach, never widen what the ledger will
+ * accept, and the page says so in the same words the code enforces.
+ */
+export function rulesPage(policy, spent, vault, network, qs = "", saved = false) {
+    const cats = Object.entries(policy.categories ?? {});
+    const catRows = cats.length
+        ? cats.map(([name, rule]) => categoryRow(name, rule, policy, spent.byCategory[name] ?? 0)).join("\n")
+        : `<tr><td colspan="5" class="empty">no categories — every seller shares the daily budget</td></tr>`;
+    const mapped = Object.entries(policy.payeeCategory ?? {});
+    return `<!doctype html><html><head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Paydlux — spending rules</title>
+<link rel="stylesheet" href="portal.css"></head><body>
+<h1>Paydlux — spending rules</h1>
+<div class="sub"><a class="nav" href="/${qs}">approvals</a> · <a class="nav" href="/rules${qs}">spending rules</a><br>
+vault ${esc(vault)} · ${esc(network)}${saved ? ` · <span class="saved">saved</span>` : ""}</div>
+
+<form id="rules" method="post" action="/rules${qs}">
+<h2>Every payment</h2>
+<div class="grid">
+  <label>Most for one payment
+    <input name="maxPerPayment" type="number" min="0.0000001" step="0.0000001" value="${esc(policy.maxPerPayment)}"></label>
+  <label>Daily budget
+    <input name="dailyBudget" type="number" min="0.0000001" step="0.0000001" value="${esc(policy.dailyBudget)}"></label>
+</div>
+<p class="note">Spent today: <b>${esc(spent.total.toFixed(7))}</b> of ${esc(policy.dailyBudget)}. The day resets at 00:00 UTC.</p>
+
+<h2>Wallets the agent may pay</h2>
+<div class="grid">
+  <label>Allowed (one account per line, blank = any)
+    <textarea name="allowlist" rows="3" spellcheck="false" autocomplete="off">${esc((policy.allowlist ?? []).join("\n"))}</textarea></label>
+  <label>Never allowed, even if listed above
+    <textarea name="denylist" rows="3" spellcheck="false" autocomplete="off">${esc((policy.denylist ?? []).join("\n"))}</textarea></label>
+</div>
+
+<h2>Categories</h2>
+<p class="note">Split the daily budget by what the money is for. A category can only be
+tighter than the limits above — it can never raise them.</p>
+<table class="cats"><thead><tr><th>name</th><th>max / payment</th><th>daily</th><th>spent today</th><th></th></tr></thead>
+<tbody id="catbody">${catRows}</tbody></table>
+<div class="addcat">
+  <input name="newcat" placeholder="name (a-z, 0-9)" maxlength="32" spellcheck="false" autocomplete="off">
+  <input name="newcat_max" type="number" min="0.0000001" step="0.0000001" placeholder="max / payment">
+  <input name="newcat_daily" type="number" min="0.0000001" step="0.0000001" placeholder="daily">
+  <button class="yes" type="submit" name="action" value="add">Add category</button>
+</div>
+
+<h2>Which wallet is in which category</h2>
+${mapped.length
+        ? `<table class="map"><thead><tr><th>wallet</th><th>category</th></tr></thead><tbody>
+${mapped.map(([payee, name]) => `<tr><td class="tx">${esc(payee)}</td><td>${esc(name)}`
+            + ` <button class="no mini" data-del="${esc(payee)}" data-map="1">Remove</button></td></tr>`).join("\n")}
+</tbody></table>`
+        : `<p class="note">Nothing categorised yet. Add a wallet below to cap it on its own.</p>`}
+<div class="addcat">
+  <input name="newpayee" placeholder="G… wallet address" maxlength="56" spellcheck="false" autocomplete="off">
+  <input name="newpayee_cat" placeholder="category" maxlength="32" spellcheck="false" autocomplete="off">
+  <button class="yes" type="submit" name="action" value="map">Add</button>
+</div>
+
+<div class="save">
+  <button class="yes" type="submit" name="action" value="save">Save rules</button>
+</div>
+</form>
+
+<div class="foot">These rules decide what you are <i>asked</i> to approve. They never approve
+anything themselves: every payment still needs your signature, and the vault needs two.</div>
+<script src="rules.js"></script></body></html>`;
+}
+function categoryRow(name, rule, policy, spent) {
+    // Names go in both a hidden value and the delete button's data-*, so they are
+    // escaped like any other attacker-chosen string — even though update() already
+    // reduced them to [a-z0-9_-].
+    //
+    // The name is deliberately NOT an editable input. Renaming a bucket would
+    // orphan every wallet mapped to it, and an orphaned wallet stops having a
+    // category ceiling — a rename would silently loosen the rules while looking
+    // like a cosmetic edit. Renaming is therefore remove + add, which forces the
+    // human to re-map the wallets and see what they are doing.
+    return `<tr>
+  <td><span class="catname">${esc(name)}</span><input type="hidden" name="cat_${esc(name)}_name" value="${esc(name)}"></td>
+  <td><input name="cat_${esc(name)}_max" type="number" min="0.0000001" step="0.0000001" value="${esc(rule.maxPerPayment ?? "")}" placeholder="${esc(policy.maxPerPayment)}"></td>
+  <td><input name="cat_${esc(name)}_daily" type="number" min="0.0000001" step="0.0000001" value="${esc(rule.dailyBudget ?? "")}" placeholder="${esc(policy.dailyBudget)}"></td>
+  <td class="amt">${esc(spent.toFixed(7))}</td>
+  <td><button class="no" data-del="${esc(name)}">Remove</button></td></tr>`;
+}
 function render(r, qs = "") {
     // qs is the portal key query string ("?k=..."). The approver link has to carry
     // it, because the desk answers 403 for anything without it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paydlux/agent",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Payments for AI agents that a human approves. Spending mandates enforced on the Stellar ledger: 2-of-2 vault, pre-authorised transaction envelopes, HTTP 402, USDC.",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,6 +24,7 @@
     "phone-app/icon-512.png",
     "portal-app/portal.js",
     "portal-app/portal.css",
+    "portal-app/rules.js",
     "README.md",
     "LICENSE"
   ],
@@ -44,6 +45,7 @@
     "test:stellar": "tsx stellar/demo.ts",
     "test:portal": "tsx stellar/xss-check.ts",
     "test:mandate": "tsx stellar/mandate-check.ts",
+    "test:policy": "tsx stellar/policy-check.ts",
     "test:phone": "tsx stellar/phone-check.ts && tsx stellar/desk-split-check.ts && tsx stellar/mandate-check.ts && tsx stellar/e2e-phone.ts && tsx phone-app/xdr-check.ts && tsx phone-app/app-check.ts && tsx phone-app/desk-app-check.ts && tsx ios/bridge-check.ts && tsx phone-app/ui-check.ts",
     "test:ios": "tsx ios/bridge-check.ts",
     "test:link": "swiftc ios/PaydluxApprover/LinkResolver.swift ios/Checks/linkcheck/main.swift -o \"$TMPDIR/linkcheck\" && \"$TMPDIR/linkcheck\"",
@@ -65,7 +67,7 @@
     "address:check": "tsx stellar/check-address.ts",
     "test:address": "tsx stellar/address-check.ts",
     "site:deploy": "tsx stellar/make-site-qr.ts paydlux-mainnet.json site/qr.svg && wrangler deploy",
-    "test:escrow": "tsx stellar/escrow-check.ts && tsx stellar/escrow-gateway-check.ts"
+    "test:escrow": "tsx stellar/escrow-check.ts && tsx stellar/escrow-gateway-check.ts && tsx stellar/escrow-phone-check.ts"
   },
   "keywords": [
     "x402",

package/phone-app/app.js

@@ -371,8 +371,16 @@ async function openReview(id) {
     const rec = await api("/challenge/" + encodeURIComponent(id));
     const env = X.parseEnvelope(rec.xdr);
     const op = env.tx.ops[0];
-    if (env.tx.ops.length !== 1 || op.type !== X.OP_PAYMENT) {
-      throw new Error("this transaction is not a single payment \u2014 refusing to sign it");
+    // Two shapes are signable: a single payment, and a single escrow claim
+    // (the vault taking money a buyer locked in a claimable balance). Anything
+    // else is refused, and the escrow branch verifies the claim targets the
+    // balance id the desk says this approval is for.
+    const isClaim = op.type === X.OP_CLAIM_CLAIMABLE_BALANCE;
+    if (env.tx.ops.length !== 1 || (op.type !== X.OP_PAYMENT && !isClaim)) {
+      throw new Error("this transaction is not a single payment or escrow claim \u2014 refusing to sign it");
+    }
+    if (isClaim && rec.escrowId && op.balanceId !== rec.escrowId) {
+      throw new Error("the claim targets a different balance than this approval is for \u2014 refusing");
     }
     const { hash } = await X.transactionHash(rec.xdr, X.NETWORK_ID[rec.network] || rec.network);
     if (rec.hash && hash !== rec.hash) {
@@ -391,10 +399,14 @@ async function openReview(id) {
     }
     current = {
       id, xdr: rec.xdr, hash,
-      amount: X.formatAmount(op.amount),
-      token: op.asset.code || "XLM",
-      issuer: op.asset.issuer || "",
-      payee: X.encodeAccountEd25519(op.destination.pub),
+      // A claim op carries no amount: the money is whatever the ledger says the
+      // balance holds. The desk read that number when it queued the release,
+      // so the human sees it from the desk, and the balance id next to it is
+      // what ties the number to the order.
+      amount: isClaim ? String(rec.amount ?? "") : X.formatAmount(op.amount),
+      token: isClaim ? String(rec.asset ?? "") : (op.asset.code || "XLM"),
+      issuer: isClaim ? "" : (op.asset.issuer || ""),
+      payee: isClaim ? op.balanceId : X.encodeAccountEd25519(op.destination.pub),
       vault: X.encodeAccountEd25519(env.tx.source.pub),
       // Read the memo out of the envelope, not out of the server's summary:
       // the envelope is what is being signed, so it is the only source that
@@ -417,6 +429,10 @@ async function openReview(id) {
     $("amount").append(num, tk);
     set("wantsBig", current.wants);
     set("token", current.issuer ? `${current.token} (${current.issuer.slice(0, 12)}\u2026)` : current.token);
+    // An escrow claim has no payee: the money goes to the vault itself. What
+    // the human verifies instead is the balance id — the ledger address of the
+    // locked money — so the row is labelled for that.
+    $("payeeLabel").textContent = isClaim ? "Escrow balance" : "Payee";
     set("payee", current.payee);
     set("vault", current.vault);
     set("wants", current.wants);
@@ -432,6 +448,10 @@ async function openReview(id) {
     $("netChip").style.color = current.network === "public" ? "var(--ok)" : "var(--warn)";
     err("signErr", "");
     resetHold();
+    // The hold button says what it does. Releasing an escrow is not paying
+    // anyone: it is the vault taking money a buyer already locked. After
+    // resetHold, which resets the label to the payment wording.
+    if (isClaim) set("holdLbl", "Hold to release \u0026 sign");
     show("review", true);
     show("queue", false);
     $("review").scrollIntoView({ behavior: "smooth", block: "start" });

package/phone-app/index.html

@@ -235,7 +235,7 @@
   <div class="hint" id="wantsBig"></div>
   <dl class="kv" style="margin-top:16px">
     <dt>Token</dt><dd id="token"></dd>
-    <dt>Payee</dt><dd id="payee"></dd>
+    <dt id="payeeLabel">Payee</dt><dd id="payee"></dd>
     <dt>From</dt><dd id="vault"></dd>
     <dt>Wants</dt><dd id="wants"></dd>
     <dt>Reference</dt><dd id="memo"></dd>

package/phone-app/xdr.js

@@ -76,6 +76,10 @@
   const SC_ADDRESS = 4;                // soroban account: we refuse it
   const ASSET_NATIVE = 0, ASSET_ALPHANUM4 = 1, ASSET_ALPHANUM12 = 2;
   const OP_PAYMENT = 1;
+  // ClaimClaimableBalance is the escrow release: the vault taking the money the
+  // buyer locked. The phone must read it as well as payments, or a seller on a
+  // --split vault can never release an escrow from the phone.
+  const OP_CLAIM_CLAIMABLE_BALANCE = 15;
   const PRECOND_NONE = 0, PRECOND_TIME = 1, PRECOND_V2 = 2;
   const MEMO_NONE = 0, MEMO_TEXT = 1, MEMO_ID = 2, MEMO_HASH = 3, MEMO_RETURN = 4;
   const STROOPS = 10000000;
@@ -318,14 +322,29 @@
     const hasSource = r.u32();
     const source = hasSource ? readMuxedAccount(r) : null;
     const type = r.u32();                          // OperationBody union switch
+    if (type === OP_CLAIM_CLAIMABLE_BALANCE) {
+      // ClaimableBalanceID is an union: switch word, then 32 raw bytes. Only
+      // the balance-id form (switch 0) exists today; anything else is refused
+      // rather than skipped, because skipping bytes misreads the rest.
+      const which = r.u32();
+      if (which !== 0) throw new Error("claimable balance id form " + which + " is not supported; refusing to sign");
+      // The balance id AS THE LEDGER AND THE SDK NAME IT: the 4-byte union
+      // switch ("00000000") followed by the 32-byte hash. Returning only the
+      // hash would disagree with every id the desk and Horizon use, and the
+      // desk's "this claim targets THIS escrow" check would never match.
+      const balanceId = "00000000" + hex(r.fixed(32));
+      // The claim op carries NO amount: the money is whatever the ledger says
+      // that balance holds. The human verifies the balance id instead.
+      return { type, source, balanceId, destination: null, asset: null, amount: null };
+    }
     if (type !== OP_PAYMENT) {
-      throw new Error("operation type " + type + " is not a payment; this app only signs payments");
+      throw new Error("operation type " + type + " is not a payment or an escrow claim; this app only signs those");
     }
     const destination = readMuxedAccount(r);
     const asset = readAsset(r);
     const amount = r.i64();
     if (amount < 0n) throw new Error("payment amount is negative; refusing to sign");
-    return { type, source, destination, asset, amount: amount.toString() };
+    return { type, source, destination, asset, amount: amount.toString(), balanceId: null };
   }
 
   function readTransaction(r) {
@@ -336,7 +355,7 @@
     const memo = readMemo(r);
     const numOps = r.u32();
     if (numOps !== 1) {
-      throw new Error("this app signs single-payment transactions, and this one has "
+      throw new Error("this app signs one operation at a time, and this one has "
         + numOps + " operations");
     }
     const ops = [];
@@ -471,6 +490,6 @@
     encodeAccountEd25519, decodeAccountEd25519,
     decodeSecretSeed, encodeSecretSeed, importSecretSeed, importSecretSeedPair,
     NETWORK_ID, crc16Xmodem,
-    ENVELOPE_TYPE_TX, OP_PAYMENT, STROOPS,
+    ENVELOPE_TYPE_TX, OP_PAYMENT, OP_CLAIM_CLAIMABLE_BALANCE, STROOPS,
   };
 })(typeof globalThis !== "undefined" ? globalThis : this);

package/portal-app/portal.css

@@ -19,4 +19,26 @@ button{border:0;border-radius:10px;padding:12px 18px;font-size:15px;font-weight:
 details summary{cursor:pointer}
 .phlink{color:var(--gold);text-decoration:underline;font-size:12px}
 .foot{margin-top:28px;color:var(--muted);font-size:12px}
+
+/* --- spending rules page --- */
+h2{font-size:13px;color:var(--muted);text-transform:uppercase;letter-spacing:.06em;margin:28px 0 10px}
+.grid{display:grid;grid-template-columns:1fr 1fr;gap:14px}
+label{display:block;color:var(--muted);font-size:12px}
+input,textarea{display:block;width:100%;margin-top:6px;background:#141715;color:var(--text);
+  border:1px solid var(--line);border-radius:10px;padding:11px 12px;font:15px/1.4 ui-monospace,monospace}
+textarea{resize:vertical}
+input:focus,textarea:focus{outline:none;border-color:var(--gold)}
+.note{color:var(--muted);font-size:13px;margin:10px 0}
+.note b{color:var(--gold)}
+table.cats,table.map{margin-top:6px}
+table.cats td{padding:8px 6px}
+.addcat{display:flex;gap:10px;align-items:end;margin-top:10px;flex-wrap:wrap}
+.addcat input{flex:1;min-width:140px}
+.addcat button{width:auto;flex:0 0 auto}
+.save{margin-top:26px}
+.save button{width:auto;min-width:180px}
+button.mini{display:inline;width:auto;padding:4px 10px;font-size:12px;margin:0}
+.nav{color:var(--gold);text-decoration:underline}
+.saved{color:var(--green);font-weight:700}
+@media(max-width:640px){.grid{grid-template-columns:1fr}}
 @media(max-width:640px){.body{max-width:180px}}

package/portal-app/rules.js

@@ -0,0 +1,62 @@
+// The spending-rules page's client half. Served by the desk at /rules.js.
+//
+// The page is a plain HTML form, so it works with JavaScript off. This file
+// only adds the two things a form cannot do by itself: a Remove button that
+// queues the row for deletion and submits, and a confirm before a rule that
+// gates money is loosened.
+//
+// No inline handlers, so the page's CSP keeps script-src 'self'. Category names
+// arrive from the server already reduced to [a-z0-9_-]; they are still read
+// through dataset, never interpolated into markup, so nothing here can be
+// turned into HTML by a name.
+const form = document.getElementById("rules");
+if (!form) throw new Error("rules page has no #rules form");
+
+// Hidden fields the server reads as "delete these". Accumulating rather than
+// replacing means a human can remove three rows before pressing Save.
+const hidden = (name) => {
+  let el = form.querySelector(`input[name="${name}"]`);
+  if (!el) {
+    el = document.createElement("input");
+    el.type = "hidden";
+    el.name = name;
+    form.appendChild(el);
+  }
+  return el;
+};
+
+document.addEventListener("click", (e) => {
+  const b = e.target.closest("button[data-del]");
+  if (!b) return;
+  e.preventDefault();
+  const field = b.dataset.map ? "delmap" : "delcat";
+  const el = hidden(field);
+  const val = b.dataset.del;
+  const have = el.value ? el.value.split(",") : [];
+  if (!have.includes(val)) have.push(val);
+  el.value = have.join(",");
+  // The row goes immediately: the human sees the rule stop protecting them
+  // before they press Save, which is the point of the confirm.
+  b.closest("tr")?.remove();
+  form.requestSubmit();
+});
+
+// A wider ceiling is the one edit that can only hurt. The ledger still caps a
+// single payment at the mandate amount, but the daily budget and the seller
+// list are ours to count, so raising them is a real loosening. Ask once.
+const limits = ["maxPerPayment", "dailyBudget"];
+const start = Object.fromEntries(
+  limits.map((n) => [n, form.querySelector(`[name="${n}"]`)?.value ?? ""]));
+
+form.addEventListener("submit", (e) => {
+  const raised = limits.filter((n) => {
+    const now = Number(form.querySelector(`[name="${n}"]`)?.value);
+    const was = Number(start[n]);
+    return Number.isFinite(now) && Number.isFinite(was) && now > was;
+  });
+  if (!raised.length) return;
+  const ok = confirm(
+    `This raises ${raised.join(" and ")}. Higher limits mean the agent may ask you for ` +
+    `more money, more often. Continue?`);
+  if (!ok) e.preventDefault();
+});