@paydlux/agent 0.1.21 → 0.1.23

package/README.md

@@ -242,6 +242,31 @@ too, because a budget that silently reads as unspent is worse than no budget.
 The banner shows what is left: `policy: max 10 per payment, 50 per day (27.50
 left today)`.
 
+### Spend it by category, and edit the rules in a browser
+
+One vault, several pockets. Open **spending rules** on the approvals page (or
+`/rules` on the desk) and set, per named category, its own per-payment ceiling and
+daily budget — then say which seller wallet belongs to which category:
+
+```
+data-api    max 3 / payment    6 / day     ← api.example.com wallet
+coding      max 1 / payment    2 / day     ← assistant wallet
+```
+
+A category can only be **tighter** than the limits above it; it can never raise
+them, because the base ceilings are checked first. That asymmetry is the security
+property, and `npm run test:policy` proves it, along with the queue counting
+inside a category and the fact that a form posted from another site cannot raise
+your budget.
+
+Edits are saved to the vault's config file, so they survive a restart. Once you
+have edited them there, the saved numbers win over `--max`/`--daily` on the next
+start, and the seller prints which it is using — a rule that quietly reverts by
+morning is worse than no rule.
+
+`stellar/policy.ts` is the engine; the page is a plain HTML form, so it works with
+JavaScript off.
+
 ### What is enforced where (said honestly)
 
 | enforced by Stellar | enforced by the desk (`policy.ts`) |

package/dist/cli.js

@@ -221,7 +221,26 @@ async function sell() {
     // desk is even built.
     const maxPer = Number(arg("max") ?? data.policy?.maxPerPayment ?? 2);
     const daily = Number(arg("daily") ?? data.policy?.dailyBudget ?? 10);
-    const policy = new PolicyEngine({ maxPerPayment: maxPer, dailyBudget: daily });
+    // Categories and the wallet map come from the config file only: they are set
+    // at the desk (/rules), not from the command line. A flag for them would be a
+    // second, easier way to say the same thing, and the page would drift from it.
+    //
+    // The same is true of the two ceilings once an owner edits them at the desk:
+    // the saved file wins over the flags, because the app scripts pass --max and
+    // --daily on every start and would otherwise silently undo whatever was set in
+    // the browser. The line printed below is what keeps that from being a
+    // surprise — a rule that quietly reverts is worse than no rule at all.
+    const saved = data.policy?.savedByOwner === true;
+    const maxPerFinal = saved ? Number(data.policy.maxPerPayment ?? maxPer) : maxPer;
+    const dailyFinal = saved ? Number(data.policy.dailyBudget ?? daily) : daily;
+    if (saved && (maxPerFinal !== maxPer || dailyFinal !== daily)) {
+        log(`using the rules you saved at the desk (max ${maxPerFinal}, daily ${dailyFinal}) instead of the command line (${maxPer}/${daily}).\n  to change them: open the approvals link and press "spending rules".`);
+    }
+    const policy = new PolicyEngine({
+        maxPerPayment: maxPerFinal, dailyBudget: dailyFinal,
+        allowlist: data.policy?.allowlist, denylist: data.policy?.denylist,
+        categories: data.policy?.categories, payeeCategory: data.policy?.payeeCategory,
+    });
     // A ceiling below the price blocks every payment, and the failure looks like
     // a bug in the desk: the buyer waits, the human never sees an approvable
     // item, and the log says "mandate refused". Say it now, before anything is
@@ -233,16 +252,16 @@ async function sell() {
     // takes money IN from the buyer, so the ceiling does not apply to it — and
     // applying it would refuse a perfectly good escrow price for no reason.
     if (mode === "escrow") {
-        if (priceNum > maxPer) {
-            log(`note: --escrow price ${price} is above --max ${maxPer}. That is fine here — escrow money comes FROM the buyer, so your spending mandate never touches it.`);
+        if (priceNum > maxPerFinal) {
+            log(`note: --escrow price ${price} is above --max ${maxPerFinal}. That is fine here — escrow money comes FROM the buyer, so your spending mandate never touches it.`);
         }
     }
     else {
-        if (priceNum > maxPer) {
-            bad(`--price ${price} is above --max ${maxPer}, so every payment would be refused by your own mandate.\n  raise --max to at least ${price} (for example --max ${price}) or lower --price.`);
+        if (priceNum > maxPerFinal) {
+            bad(`--price ${price} is above --max ${maxPerFinal}, so every payment would be refused by your own mandate.\n  raise --max to at least ${price} (for example --max ${price}) or lower --price.`);
         }
-        if (priceNum > daily) {
-            bad(`--price ${price} is above --daily ${daily}: one payment would spend the whole day's budget and the second would be refused.\n  set --daily to at least ${price}.`);
+        if (priceNum > dailyFinal) {
+            bad(`--price ${price} is above --daily ${dailyFinal}: one payment would spend the whole day's budget and the second would be refused.\n  set --daily to at least ${price}.`);
         }
     }
     const vault = await StellarVault.load(data.vault, data.token.code, data.token.issuer, { principal: pub(keys.principal), approver: keys.approver ? pub(keys.approver) : undefined, agent: pub(keys.agent) }, network);
@@ -267,20 +286,31 @@ async function sell() {
             + `the daily budget of ${daily} cannot be enforced without it, so nothing was started. `
             + `Check the network and try again.`);
     }
-    policy.seedFromLedger(alreadyPaid);
+    policy.seedFromLedger(alreadyPaid, policy.categoryOf(payee));
     if (alreadyPaid > 0) {
-        log(`ledger says ${alreadyPaid.toFixed(2)} of the ${daily} daily budget is already spent today`);
-        if (alreadyPaid >= daily) {
-            bad(`today's budget is already gone: ${alreadyPaid.toFixed(2)} paid, ${daily} allowed.\n  `
+        log(`ledger says ${alreadyPaid.toFixed(2)} of the ${dailyFinal} daily budget is already spent today`);
+        if (alreadyPaid >= dailyFinal) {
+            bad(`today's budget is already gone: ${alreadyPaid.toFixed(2)} paid, ${dailyFinal} allowed.\n  `
                 + `the mandate would refuse every payment. Raise --daily or wait for the UTC day to roll over.`);
         }
     }
+    // Say out loud what the rules are, including the categories, so the numbers
+    // an owner set in a browser are visible to whoever starts the seller. A rule
+    // nobody can see is a rule nobody trusts.
+    const catNames = Object.keys(policy.policy.categories ?? {});
+    if (catNames.length) {
+        const mapped = Object.entries(policy.policy.payeeCategory ?? {});
+        log(`spending categories: ${catNames.map((c) => {
+            const r = policy.policy.categories[c];
+            return `${c} (${r.maxPerPayment ?? policy.policy.maxPerPayment}/payment, ${r.dailyBudget ?? dailyFinal}/day)`;
+        }).join(", ")}${mapped.length ? ` · ${mapped.length} wallet(s) mapped` : ""}`);
+    }
     if (network === "public") {
         console.log(`
   MAINNET — real money.
     token            ${data.token.code}
-    max per payment  ${maxPer}
-    daily budget     ${daily}
+    max per payment  ${maxPerFinal}
+    daily budget     ${dailyFinal}
     vault            ${vault.address}
     balance          ${await vault.balance()} ${data.token.code}
 `);
@@ -322,6 +352,7 @@ async function sell() {
         // --split is the honest mode: this process cannot approve anything.
         approver: split ? undefined : keys.approver,
         split,
+        agentSeed: keys.agent,
         portalKey,
         publicHost,
         agentKeys: [pub(keys.agent)],
@@ -336,6 +367,25 @@ async function sell() {
         ],
         // The banner prints these numbers. This line is what makes them true.
         policy,
+        // Rules edited at the desk must survive the next restart, or the mandate in
+        // the banner is a promise that lasts until ctrl-c. Written back to the same
+        // config file, with the same 0600 as everywhere else in this file, because
+        // it also holds key material.
+        onPolicyChange: (p) => {
+            data.policy = {
+                ...(data.policy ?? {}),
+                // The marker that says "a human set these in a browser". Without it the
+                // app scripts' --max/--daily flags win on every restart and the edit is
+                // lost by morning.
+                savedByOwner: true,
+                maxPerPayment: p.maxPerPayment, dailyBudget: p.dailyBudget,
+                allowlist: p.allowlist ?? [], denylist: p.denylist ?? [],
+                categories: p.categories ?? {}, payeeCategory: p.payeeCategory ?? {},
+            };
+            writeFileSync(path, JSON.stringify(data, null, 2));
+            chmodSync(path, 0o600);
+            log(`rules saved to ${path}`);
+        },
     });
     let tunnel = null;
     if (tls) {
@@ -846,21 +896,50 @@ async function escrow() {
     const keys = data.keys ?? {};
     const agent = Keypair.fromSecret(keys.agent);
     if (!keys.approver) {
+        // The recommended setup: the desk is running with the phone approver, so
+        // hand the release to the DESK instead of writing a file nothing reads.
+        // The desk queues it, the phone signs the claim, the desk submits it.
+        const deskPort = Number(arg("desk") ?? 4022);
+        const portalKey = data.desk?.portalKey;
+        if (portalKey) {
+            try {
+                const res = await fetch(`http://127.0.0.1:${deskPort}/escrow?k=${encodeURIComponent(portalKey)}`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({
+                        escrowId: hit.balanceId, order: hit.memo || undefined,
+                        amount: hit.amount,
+                        asset: hit.asset === "native" ? "XLM" : hit.asset.split(":")[0],
+                        buyer: hit.buyer,
+                    }),
+                });
+                if (res.ok) {
+                    const queued = await res.json();
+                    console.log(`\nrelease queued on the approval desk as ${queued.id}.`);
+                    console.log(`  open:  ${flag("tls") ? `https://${PUBLIC_HOST}` : `http://127.0.0.1:${deskPort}`}/phone/?k=${portalKey}`);
+                    console.log(`  the order is ${hit.memo || hit.balanceId} — approve on the phone only if you delivered it.`);
+                    console.log(`  the phone signs the claim; the desk submits it. vault balance updates after.\n`);
+                    return;
+                }
+                console.log(`the desk answered ${res.status}; falling back to the manual challenge.\n`);
+            }
+            catch {
+                // No desk listening on that port. Fall through to the file path.
+            }
+        }
         const challenge = await prepareEscrowRelease(network, hit.balanceId, vault.address, agent);
         console.log(`\nthis laptop holds one of the two keys, so the release needs your phone.\n`);
         console.log(describeChallenge(challenge));
-        console.log(`\n  open:  ${flag("tls") ? `https://${PUBLIC_HOST}` : "http://127.0.0.1:4022"}/?k=${data.desk?.portalKey ?? "…"}`);
-        console.log(`  the order id is ${hit.memo || hit.balanceId} — sign only if you delivered it.\n`);
-        // Written out so the second signature can be added by whatever holds the
-        // approver key, without retyping XDR. Said exactly, because a promise here
-        // that nothing implements is a lie in the seller's terminal: no process
-        // reads this file back on its own.
+        console.log(`\n  the order id is ${hit.memo || hit.balanceId} — sign only if you delivered it.\n`);
+        console.log(`no approval desk is answering on port ${deskPort}. start one with \`paydlux sell\` (or the`);
+        console.log(`app:mainnet:sell script) and re-run this command, and the release goes to your phone.`);
+        console.log(`or finish it on a machine that holds the approver key.\n`);
+        // Written out so the second signature can still be added by hand from a
+        // machine that holds the approver key. Said exactly: nothing reads this
+        // file back on its own.
         const file = path.replace(/\.json$/, ".escrow-release.json");
         writeFileSync(file, JSON.stringify({ order: hit.memo || hit.balanceId, challenge }, null, 2), { mode: 0o600 });
-        console.log(`challenge written to ${file} (0600).`);
-        console.log(`nothing completes this by itself. finish it from a machine that holds the approver key,`);
-        console.log(`or run this command there. the phone approver releases PAYMENTS today; releasing ESCROW`);
-        console.log(`from the phone is not wired yet, so until it is, use the second key's machine.\n`);
+        console.log(`challenge also written to ${file} (0600) for the manual path.\n`);
         return;
     }
     const out = await claimEscrow(network, hit.balanceId, vault.address, { agent, approver: Keypair.fromSecret(keys.approver) });

package/dist/desk.d.ts

@@ -1,6 +1,6 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
 import type { StellarVault } from "./vault.ts";
-import type { PolicyEngine } from "./policy.ts";
+import type { PolicyEngine, Policy } from "./policy.ts";
 import { type ApprovalChallenge } from "./phone.ts";
 /** A portal link is a capability: whoever holds it can approve. So it is long,
  *  random, and compared without leaking timing. */
@@ -32,6 +32,20 @@ export type DeskRecord = {
     challenge?: ApprovalChallenge;
     qr?: string;
     signedXdr?: string;
+    /**
+     * What the human is being asked to authorise. `payment` is the vault paying
+     * money OUT. `escrow` is the vault claiming a claimable balance the buyer
+     * already locked — money coming IN. The distinction is load-bearing: the
+     * spending mandate caps payments out, so it must not touch an escrow
+     * release, and the signed transaction is verified against a different
+     * operation type.
+     */
+    kind?: "payment" | "escrow";
+    /** escrow records: the claimable balance to claim, and the order it belongs to */
+    escrowId?: string;
+    order?: string;
+    /** escrow records: the asset the balance pays out ("XLM", "USDC", ...) */
+    asset?: string;
 };
 export type DeskStore = DeskRecord;
 export type DeskConfig = {
@@ -46,6 +60,15 @@ export type DeskConfig = {
      * the desk submits it. The approver seed never touches this machine.
      */
     split?: boolean;
+    /**
+     * The agent seed (the machine-side key). Payments are built with the
+     * principal key; an ESCROW CLAIM is built with the agent key — that is the
+     * key pair the escrow was designed around (agent + phone approver). The desk
+     * needs it to build the release challenge, exactly as it needs the principal
+     * seed to build a payment challenge. It is not the approving half: the claim
+     * still needs the phone's signature to reach the vault's threshold of 2.
+     */
+    agentSeed?: string;
     /** how long a human has to decide before the payment is dead */
     decideWithinSeconds?: number;
     port: number;
@@ -73,10 +96,22 @@ export type DeskConfig = {
      * ceiling can actually hold.
      */
     policy?: PolicyEngine;
+    /**
+     * Called when the human edits the spending rules from the portal. The CLI
+     * wires this to the config file, so a rule set at the desk survives the next
+     * restart instead of resetting to the command-line defaults.
+     *
+     * A callback rather than a path: the desk must not know where secrets live.
+     * The config file also holds key material, so the writer stays with the code
+     * that already handles it (0600, same serialisation).
+     */
+    onPolicyChange?: (policy: Policy) => void;
 };
 export declare class ApprovalDesk {
     private records;
     private seq;
+    /** when /rules last saved, so the page can say "saved" without a query flag */
+    private rulesSavedAt;
     private server?;
     cfg: DeskConfig;
     constructor(cfg: DeskConfig);
@@ -99,6 +134,27 @@ export declare class ApprovalDesk {
     /** Every record carrying this key, newest first. */
     allByKey(key: string): DeskRecord[];
     findByKey(key: string): DeskRecord | null;
+    /**
+     * Queue an escrow release for the human. This is the missing half of
+     * `paydlux escrow --release` on a --split vault: the money already sits in a
+     * claimable balance the buyer locked, so releasing it is the vault CLAIMING
+     * that balance — money coming IN, not going out. The claim still needs the
+     * vault's threshold of 2 (agent + approver), and the approver half lives on
+     * the phone, so it goes through the same challenge/sign/submit loop as a
+     * payment, tagged `kind: "escrow"` so the spending mandate — which caps
+     * money OUT — never touches it.
+     *
+     * The generic fields (uri/price/body) are filled so the portal page renders
+     * the row without knowing about escrow; the structured fields carry the
+     * truth the verification uses.
+     */
+    addEscrow(input: {
+        escrowId: string;
+        order?: string;
+        amount: string;
+        asset: string;
+        buyer?: string;
+    }): DeskRecord;
     get(id: string): DeskRecord | null;
     list(): DeskRecord[];
     /**
@@ -124,9 +180,53 @@ export declare class ApprovalDesk {
     private mandateBlock;
     /** The mandate has been satisfied: count the money as spent. */
     private recordSpend;
+    /** The rules as they stand, for the /rules page. */
+    policyView(): Policy;
+    /** What today's counters read, per category, for the /rules page. */
+    private spentView;
+    /**
+     * 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.
+     */
+    private crossOriginGate;
+    /**
+     * 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.
+     */
+    private applyRules;
     approve(id: string): Promise<DeskRecord>;
     /** Split mode step 1: ask the phone to sign. Nothing is submitted yet. */
     private requestPhoneSignature;
+    /**
+     * Split mode step 1 for an ESCROW release: build the claim, sign it with the
+     * agent key, hand it to the phone. `prepareEscrowRelease` reads the ledger
+     * and refuses a balance that does not exist or whose timer has not passed,
+     * so a queued-but-fake escrow dies here with a real reason instead of
+     * reaching the human as a signable challenge.
+     */
+    private requestEscrowSignature;
+    /**
+     * Split mode step 2 for an ESCROW release: the phone signed the claim.
+     * No mandate check — this is money coming IN — and no recordSpend: the
+     * daily budget counts payments OUT, and counting a release against it would
+     * make the seller's own earned money unclaimable.
+     */
+    private completeEscrow;
     /**
      * Split mode step 2: the phone answered. `signedXdr` is the transaction with
      * the approver signature added, returned by signChallenge() on the phone.