nostr-bray 3.4.2 → 3.5.0

package/dist/wallet-service/tools.js

@@ -1,8 +1,9 @@
 import { z } from 'zod';
 import { resolveNwcUri } from '../zap/handlers.js';
-import { defaultGrantsFile, loadGrants, saveGrants } from './grants.js';
+import { acquireServeLock, defaultGrantsFile, fileGrantStore, loadGrants, refillGrant, releaseServeLock, revokeGrant, updateGrants, writeGrantUriFile, } from './grants.js';
 import { upstreamWallet } from './upstream.js';
-import { DEFAULT_METHODS, SUPPORTED_METHODS, WalletService, grantUri, newGrant, remainingBudgetMsat, } from './service.js';
+import { defaultPaymentGuard } from '../zap/payment-guard.js';
+import { DEFAULT_METHODS, SUPPORTED_METHODS, WalletService, newGrant, remainingBudgetMsat, } from './service.js';
 // Handing out a wallet connection that is narrower than the one you hold.
 //
 // `zap-send` spends through the operator's own NWC URI, which is an
@@ -17,13 +18,13 @@ import { DEFAULT_METHODS, SUPPORTED_METHODS, WalletService, grantUri, newGrant,
 // leaving someone to discover it: a grant handed to an agent that only
 // works while an MCP session is open is a different promise from one that
 // works overnight.
-// The running service, and the grant objects it was handed. The service
-// mutates those in place - a budget it has spent, a request id it has
-// answered - so persisting means writing THOSE back, not re-writing
-// whatever the file already said.
+// The running service. It keeps no authority of its own: every grant it
+// answers for is re-read from the grants file before each request and
+// changed there under a lock, and only one process may serve at a time.
 let service = null;
 let servingFor = null;
-const served = new Map();
+let lockedFile = null;
+let releaseOnExit = false;
 const text = (value) => ({
     content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
 });
@@ -38,87 +39,93 @@ const shown = (grant) => ({
     ...(grant.maxPaymentMsat === undefined ? {} : { maxPaymentMsat: grant.maxPaymentMsat }),
     ...(grant.lastUsedAt === undefined ? {} : { lastUsedAt: new Date(grant.lastUsedAt).toISOString() }),
 });
-export function registerWalletServiceTools(server, deps) {
+export function registerWalletServiceTools(server, deps, options = {}) {
+    const issuing = options.issuing === true;
     const grantsFile = defaultGrantsFile();
     const identity = () => deps.ctx.activePublicKeyHex;
     const read = () => loadGrants(grantsFile, identity());
-    const write = (grants) => {
-        saveGrants(grantsFile, identity(), grants);
+    const stopService = () => {
+        service?.close();
+        service = null;
+        servingFor = null;
+        if (lockedFile)
+            releaseServeLock(lockedFile);
+        lockedFile = null;
     };
     const running = async () => {
         const pubkey = identity();
         // An identity switch is a different wallet and different grants, so the
         // old service is stopped rather than left answering under a name this
         // session no longer means.
-        if (service && servingFor !== pubkey) {
-            service.close();
-            service = null;
-            served.clear();
-        }
+        if (service && servingFor !== pubkey)
+            stopService();
         if (service)
             return service;
         const uri = resolveNwcUri(deps.ctx, deps.walletsFile, deps.nwcUri);
         if (!uri)
             throw new Error('No wallet is configured - `zap-wallet-set` points this identity at one first.');
+        acquireServeLock(grantsFile);
+        lockedFile = grantsFile;
+        if (!releaseOnExit) {
+            releaseOnExit = true;
+            process.once('exit', () => { if (lockedFile)
+                releaseServeLock(lockedFile); });
+        }
         servingFor = pubkey;
         service = new WalletService({
-            wallet: upstreamWallet({ uri, alias: deps.ctx.activeNpub }),
+            wallet: upstreamWallet({ uri, alias: deps.ctx.activeNpub, guard: defaultPaymentGuard() }),
             transport: {
                 subscribe: (relays, filter, onEvent) => deps.pool.subscribe(relays, filter, onEvent),
                 publish: async (relays, event) => {
                     await deps.pool.publishDirect(relays, event);
                 },
             },
-            persist: async () => {
-                // The in-memory grants win: they are the ones the service has been
-                // charging. Anything on disk it is not serving is carried through
-                // untouched.
-                const stored = loadGrants(grantsFile, pubkey);
-                saveGrants(grantsFile, pubkey, stored.map((held) => served.get(held.id) ?? held));
-            },
+            store: fileGrantStore(grantsFile, pubkey),
         });
         return service;
     };
     const startServing = async (grant) => {
-        served.set(grant.id, grant);
         await (await running()).serve(grant);
     };
-    server.registerTool('wallet-grant', {
-        description: 'Issue a NIP-47 connection over this identity\'s wallet, narrower than the URI you hold. Defaults to invoice-only: no spending and no balance disclosure. A connection that can spend must carry a budget. Returns the nostr+walletconnect:// URI to hand over.',
-        inputSchema: {
-            name: z.string().describe('What this connection is for - it is how you revoke the right one later'),
-            methods: z
-                .array(z.enum(SUPPORTED_METHODS))
-                .optional()
-                .describe(`NIP-47 methods this connection may call. Default: ${DEFAULT_METHODS.join(', ')}`),
-            budgetMsat: z.number().int().positive().optional().describe('Total it may ever spend, in msat. Required with pay_invoice'),
-            maxPaymentMsat: z.number().int().positive().optional().describe('Ceiling on any single payment, in msat'),
-            relays: z.array(z.string()).optional().describe('Relays to answer on. Defaults to this identity\'s write relays'),
-        },
-        annotations: { readOnlyHint: false, destructiveHint: true },
-    }, async ({ name, methods, budgetMsat, maxPaymentMsat, relays }) => {
-        const grants = read();
-        if (grants.some((held) => !held.revokedAt && held.name.toLowerCase() === name.trim().toLowerCase())) {
-            throw new Error(`There is already a live connection called ${name}.`);
-        }
-        const on = relays?.length ? relays : deps.pool.getRelays(deps.ctx.activeNpub).write;
-        const grant = newGrant({
-            name: name.trim(),
-            relays: on,
-            ...(methods ? { methods: [...methods] } : {}),
-            ...(budgetMsat === undefined ? {} : { budgetMsat }),
-            ...(maxPaymentMsat === undefined ? {} : { maxPaymentMsat }),
-        });
-        write([...grants, grant]);
-        if (service)
-            await startServing(grant);
-        return text({
-            ok: true,
-            ...shown(grant),
-            uri: grantUri(grant),
-            note: 'Whoever holds this URI can do exactly the above and nothing else. It is answered only while `wallet-serve` is running.',
+    if (issuing)
+        server.registerTool('wallet-grant', {
+            description: 'Issue a scoped NIP-47 connection over this identity\'s one wallet, narrower than the URI you hold. Defaults to invoice-only: no spending and no balance disclosure. A connection that can spend must carry a budget. Writes the nostr+walletconnect:// URI to a private 0600 file and returns its path; the URI itself is never returned.',
+            inputSchema: {
+                name: z.string().describe('What this connection is for - it is how you revoke the right one later'),
+                methods: z
+                    .array(z.enum(SUPPORTED_METHODS))
+                    .optional()
+                    .describe(`NIP-47 methods this connection may call. Default: ${DEFAULT_METHODS.join(', ')}`),
+                budgetMsat: z.number().int().positive().optional().describe('Total it may ever spend, in msat. Required with pay_invoice'),
+                maxPaymentMsat: z.number().int().positive().optional().describe('Ceiling on any single payment, in msat'),
+                relays: z.array(z.string()).optional().describe('Relays to answer on. Defaults to this identity\'s write relays'),
+            },
+            annotations: { readOnlyHint: false, destructiveHint: true },
+        }, async ({ name, methods, budgetMsat, maxPaymentMsat, relays }) => {
+            const on = relays?.length ? relays : deps.pool.getRelays(deps.ctx.activeNpub).write;
+            const grant = newGrant({
+                name: name.trim(),
+                relays: on,
+                ...(methods ? { methods: [...methods] } : {}),
+                ...(budgetMsat === undefined ? {} : { budgetMsat }),
+                ...(maxPaymentMsat === undefined ? {} : { maxPaymentMsat }),
+            });
+            updateGrants(grantsFile, identity(), (grants) => {
+                if (grants.some((held) => !held.revokedAt && held.name.toLowerCase() === grant.name.toLowerCase())) {
+                    throw new Error(`There is already a live connection called ${name}.`);
+                }
+                grants.push(grant);
+            });
+            const uriFile = writeGrantUriFile(grantsFile, grant);
+            if (service)
+                await startServing(grant);
+            return text({
+                ok: true,
+                ...shown(grant),
+                uriFile,
+                note: 'The connection URI is in uriFile (mode 0600) and is deliberately not shown here: it is a bearer secret. Hand that file to whoever should hold the connection. Whoever holds the URI can do exactly the above and nothing else, and it is answered only while `wallet-serve` is running.',
+            });
         });
-    });
     server.registerTool('wallet-grants', {
         description: 'List the NIP-47 connections issued over this identity\'s wallet, what each may do, and what it has spent. Secrets are never returned.',
         annotations: { readOnlyHint: true },
@@ -131,59 +138,42 @@ export function registerWalletServiceTools(server, deps) {
         inputSchema: { nameOrId: z.string() },
         annotations: { readOnlyHint: false, destructiveHint: true },
     }, async ({ nameOrId }) => {
-        const grants = read();
-        const wanted = nameOrId.trim().toLowerCase();
-        const grant = grants.find((held) => held.id === wanted) ??
-            grants.find((held) => held.name.toLowerCase() === wanted) ??
-            grants.find((held) => held.id.startsWith(wanted));
-        if (!grant)
-            throw new Error(`No connection here called ${nameOrId}.`);
-        grant.revokedAt ??= Date.now();
-        write(grants);
+        // Written to the grants file, which a serving process re-reads before
+        // every request: this takes effect there too, even when that process
+        // is another one.
+        const grant = revokeGrant(grantsFile, identity(), nameOrId);
         service?.stop(grant.id);
-        served.delete(grant.id);
         return text({ ok: true, ...shown(grant) });
     });
-    server.registerTool('wallet-refill', {
-        description: 'Put a spending connection\'s budget back where it started, optionally at a new figure. Deliberately separate from granting: topping up is a decision, not a side effect of use.',
-        inputSchema: { nameOrId: z.string(), budgetMsat: z.number().int().positive().optional() },
-        annotations: { readOnlyHint: false, destructiveHint: true },
-    }, async ({ nameOrId, budgetMsat }) => {
-        const grants = read();
-        const wanted = nameOrId.trim().toLowerCase();
-        const grant = grants.find((held) => held.id === wanted) ?? grants.find((held) => held.name.toLowerCase() === wanted);
-        if (!grant)
-            throw new Error(`No connection here called ${nameOrId}.`);
-        if (grant.revokedAt)
-            throw new Error('That connection is revoked - issue a new one.');
-        if (grant.budgetMsat === undefined)
-            throw new Error('That connection cannot spend, so it has no budget.');
-        if (budgetMsat !== undefined)
-            grant.budgetMsat = budgetMsat;
-        grant.spentMsat = 0;
-        write(grants);
-        return text({ ok: true, ...shown(grant) });
-    });
-    server.registerTool('wallet-serve', {
-        description: 'Start or stop answering NIP-47 for the connections issued above. While it runs, holders of those URIs can call the methods their grant allows, against this identity\'s wallet. It answers only while this process is alive.',
-        inputSchema: { action: z.enum(['start', 'stop', 'status']).default('status') },
-        annotations: { readOnlyHint: false },
-    }, async ({ action }) => {
-        if (action === 'stop') {
-            service?.close();
-            service = null;
-            servingFor = null;
-            served.clear();
-            return text({ ok: true, serving: [], message: 'Stopped. Nothing is answered until it runs again.' });
-        }
-        if (action === 'start') {
-            const live = read().filter((grant) => !grant.revokedAt);
-            if (!live.length)
-                throw new Error('Nothing to serve - `wallet-grant` issues a connection first.');
-            for (const grant of live)
-                await startServing(grant);
-            return text({ ok: true, serving: service?.serving() ?? [], grants: live.map(shown) });
-        }
-        return text({ ok: true, running: service !== null, serving: service?.serving() ?? [] });
-    });
+    if (issuing)
+        server.registerTool('wallet-refill', {
+            description: 'Put a spending connection\'s budget back where it started, optionally at a new figure. Deliberately separate from granting: topping up is a decision, not a side effect of use.',
+            inputSchema: { nameOrId: z.string(), budgetMsat: z.number().int().positive().optional() },
+            annotations: { readOnlyHint: false, destructiveHint: true },
+        }, async ({ nameOrId, budgetMsat }) => {
+            // The serving process re-reads the grant before each request, so the
+            // new budget applies to the very next payment.
+            const grant = refillGrant(grantsFile, identity(), nameOrId, budgetMsat);
+            return text({ ok: true, ...shown(grant) });
+        });
+    if (issuing)
+        server.registerTool('wallet-serve', {
+            description: 'Start or stop answering NIP-47 for the connections issued above. While it runs, holders of those URIs can call the methods their grant allows, against this identity\'s wallet. It answers only while this process is alive.',
+            inputSchema: { action: z.enum(['start', 'stop', 'status']).default('status') },
+            annotations: { readOnlyHint: false },
+        }, async ({ action }) => {
+            if (action === 'stop') {
+                stopService();
+                return text({ ok: true, serving: [], message: 'Stopped. Nothing is answered until it runs again.' });
+            }
+            if (action === 'start') {
+                const live = read().filter((grant) => !grant.revokedAt);
+                if (!live.length)
+                    throw new Error('Nothing to serve - `wallet-grant` issues a connection first.');
+                for (const grant of live)
+                    await startServing(grant);
+                return text({ ok: true, serving: service?.serving() ?? [], grants: live.map(shown) });
+            }
+            return text({ ok: true, running: service !== null, serving: service?.serving() ?? [] });
+        });
 }

package/dist/wallet-service/upstream.d.ts

@@ -1,8 +1,10 @@
 import type { NwcTransport } from '@forgesworn/nwc-kit';
 import { type ServiceWallet } from './service.js';
+import { type PaymentGuard } from '../zap/payment-guard.js';
 export interface UpstreamOptions {
     uri: string;
     transport?: NwcTransport;
     alias?: string;
+    guard?: PaymentGuard;
 }
 export declare function upstreamWallet(options: UpstreamOptions): ServiceWallet;

package/dist/wallet-service/upstream.js

@@ -1,6 +1,7 @@
-import { NwcClient } from '@forgesworn/nwc-kit';
+import { NwcClient, NwcError } from '@forgesworn/nwc-kit';
 import { tryDecodeBolt11, verifyPreimage } from 'farrier-kit';
 import { PaymentNotSentError, ServiceError } from './service.js';
+import { PaymentLimitError } from '../zap/payment-guard.js';
 async function withClient(options, run) {
     const client = new NwcClient(options.uri, { ...(options.transport ? { transport: options.transport } : {}) });
     try {
@@ -49,23 +50,58 @@ export function upstreamWallet(options) {
                 };
             });
         },
-        async payInvoice({ invoice }) {
+        async payInvoice({ invoice, amountMsat }) {
             const decoded = tryDecodeBolt11(invoice);
             if (!decoded)
                 throw new PaymentNotSentError('That is not a decodable BOLT-11 invoice.');
+            if (decoded.amountMsats === null || Number(decoded.amountMsats) !== amountMsat) {
+                throw new PaymentNotSentError('Only invoices that state the amount being charged are paid.');
+            }
+            const paymentHash = decoded.paymentHashHex;
+            const guard = options.guard;
             return withClient(options, async (client) => {
                 const capabilities = await client.connect();
                 if (!capabilities.methods.includes('pay_invoice')) {
                     throw new PaymentNotSentError('The wallet behind this service cannot pay invoices.');
                 }
-                const result = await client.payInvoice({ invoice });
-                if (!result.preimage || !verifyPreimage(result.preimage, decoded.paymentHashHex)) {
+                try {
+                    guard?.reserve(paymentHash, amountMsat);
+                }
+                catch (err) {
+                    if (err instanceof PaymentLimitError)
+                        throw new PaymentNotSentError(err.message);
+                    throw err;
+                }
+                let result;
+                try {
+                    result = await client.payInvoice({ invoice });
+                }
+                catch (err) {
+                    // An authenticated refusal from the wallet is definitive, exactly
+                    // as zap-send treats it: nothing left, so the budget and bray's
+                    // allowance are given back. Its text is not passed on - "not
+                    // enough funds" tells a scoped connection about a wallet it has
+                    // no business knowing about.
+                    if (err instanceof NwcError && err.code === 'WALLET_ERROR') {
+                        guard?.release(paymentHash);
+                        throw new PaymentNotSentError('The wallet behind this service declined the payment; nothing was sent.');
+                    }
+                    // Anything else may have happened after the payment went out.
+                    guard?.markUnknown(paymentHash);
+                    throw new ServiceError('OTHER', 'The wallet behind this service did not confirm the payment; it may or may not have been sent.');
+                }
+                if (!result.preimage || !verifyPreimage(result.preimage, paymentHash)) {
                     // The wallet says it paid and cannot prove it. Not a refusal -
                     // something may well have gone out - so the budget keeps the
                     // charge and the caller is told the proof is missing.
+                    guard?.markUnknown(paymentHash);
                     throw new ServiceError('OTHER', 'The wallet claims payment but its preimage does not settle that invoice.');
                 }
-                return { preimage: result.preimage, feesPaidMsat: Number(result.fees_paid ?? 0) };
+                guard?.settle(paymentHash, result.fees_paid);
+                return {
+                    preimage: result.preimage,
+                    ...(result.fees_paid === undefined ? {} : { feesPaidMsat: Number(result.fees_paid) }),
+                };
             });
         },
         async lookupInvoice(query) {

package/dist/zap/confirm.d.ts

@@ -0,0 +1,16 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export type HumanApproval = 'approved' | 'declined' | 'unavailable';
+export declare function clientCanElicit(server: McpServer): boolean;
+/**
+ * Ask the person using the MCP client to approve a payment.
+ *
+ * Returns `unavailable` when the client cannot be asked. Any failure to get
+ * a clear yes once asking is possible is a `declined`: a payment is never
+ * made because a prompt went wrong.
+ */
+export declare function askHumanToApprovePayment(server: McpServer, details: {
+    amountMsats: number;
+    purpose: string;
+    description?: string;
+    paymentHash?: string;
+}): Promise<HumanApproval>;

package/dist/zap/confirm.js

@@ -0,0 +1,58 @@
+function elicitingServer(server) {
+    const inner = server.server;
+    if (!inner || typeof inner.getClientCapabilities !== 'function' || typeof inner.elicitInput !== 'function') {
+        return null;
+    }
+    return inner;
+}
+export function clientCanElicit(server) {
+    const inner = elicitingServer(server);
+    if (!inner)
+        return false;
+    const elicitation = inner.getClientCapabilities()?.elicitation;
+    if (!elicitation || typeof elicitation !== 'object')
+        return false;
+    // An empty capability object means form elicitation (the pre-modes shape).
+    return 'form' in elicitation ? Boolean(elicitation.form) : Object.keys(elicitation).length === 0;
+}
+/**
+ * Ask the person using the MCP client to approve a payment.
+ *
+ * Returns `unavailable` when the client cannot be asked. Any failure to get
+ * a clear yes once asking is possible is a `declined`: a payment is never
+ * made because a prompt went wrong.
+ */
+export async function askHumanToApprovePayment(server, details) {
+    if (!clientCanElicit(server))
+        return 'unavailable';
+    const inner = elicitingServer(server);
+    const sats = details.amountMsats / 1000;
+    const lines = [
+        `bray wants to spend ${details.amountMsats} msat (${sats} sats) to ${details.purpose}.`,
+        ...(details.description ? [`Invoice description: ${details.description}`] : []),
+        ...(details.paymentHash ? [`Payment hash: ${details.paymentHash}`] : []),
+        'Approve only if you asked for this payment.',
+    ];
+    try {
+        const result = await inner.elicitInput({
+            mode: 'form',
+            message: lines.join('\n'),
+            requestedSchema: {
+                type: 'object',
+                properties: {
+                    approve: {
+                        type: 'boolean',
+                        title: 'Approve this payment',
+                        description: `Pay ${details.amountMsats} msat`,
+                        default: false,
+                    },
+                },
+                required: ['approve'],
+            },
+        });
+        return result.action === 'accept' && result.content?.approve === true ? 'approved' : 'declined';
+    }
+    catch {
+        return 'declined';
+    }
+}

package/dist/zap/handlers.d.ts

@@ -1,6 +1,7 @@
 import type { GetBalanceResult, NwcRequestOptions, NwcTransaction, NwcTransport, PayInvoiceResult } from '@forgesworn/nwc-kit';
 import type { SigningContext } from '../signing-context.js';
 import type { RelayPool } from '../relay-pool.js';
+import type { PaymentGuard } from './payment-guard.js';
 /**
  * Load the wallets map from the JSON file. Returns empty map if file missing.
  *
@@ -98,6 +99,7 @@ export declare function handleZapDecode(bolt11: string): {
     amountMsats?: number;
     description?: string;
     expiry?: number;
+    paymentHash?: string;
 };
 interface NwcOperationOptions extends NwcRequestOptions {
     /** Injectable for deterministic tests and specialised relay transports. */
@@ -119,9 +121,16 @@ export declare class ZapPaymentOutcomeUnknownError extends Error {
     readonly code = "PAYMENT_OUTCOME_UNKNOWN";
     constructor(paymentHash: string);
 }
-/** Pay a BOLT-11 invoice and return only after the wallet proves settlement. */
+/**
+ * Pay a BOLT-11 invoice and return only after the wallet proves settlement.
+ *
+ * With a `guard`, bray's own per-payment and rolling daily ceilings are
+ * checked and the attempt is recorded before anything is sent. Every bray
+ * surface that spends passes one; library callers should too.
+ */
 export declare function handleZapSend(_ctx: SigningContext, _pool: RelayPool, args: {
     invoice: string;
+    guard?: PaymentGuard;
 } & NwcArgs): Promise<ZapPaymentResult>;
 /** Return the wallet's confirmed balance in millisatoshis. */
 export declare function handleZapBalance(_ctx: SigningContext, _pool: RelayPool, args: NwcArgs): Promise<GetBalanceResult>;

package/dist/zap/handlers.js

@@ -201,6 +201,7 @@ export function handleZapDecode(bolt11) {
         ...(decoded.amountMsats !== null ? { amountMsats: Number(decoded.amountMsats) } : {}),
         ...(decoded.description !== null ? { description: decoded.description } : {}),
         expiry: decoded.expirySeconds,
+        paymentHash: decoded.paymentHashHex,
     };
 }
 /**
@@ -237,7 +238,42 @@ async function withClient(nwcUri, transport, operation) {
         client.close();
     }
 }
-/** Pay a BOLT-11 invoice and return only after the wallet proves settlement. */
+/**
+ * An earlier attempt at this invoice ended without an answer. Ask the wallet
+ * what happened before anything is sent again: settled means it was paid
+ * (and the proof is returned), failed or expired means it may be retried,
+ * and anything else leaves it unknown and refused.
+ */
+async function reconcileUnknownPayment(uri, paymentHash, guard, args) {
+    let found;
+    try {
+        found = await withClient(uri, args.transport, (client) => client.lookupInvoice({ payment_hash: paymentHash }, requestOptions(args)));
+    }
+    catch {
+        throw new ZapPaymentOutcomeUnknownError(paymentHash);
+    }
+    if (typeof found.preimage === 'string' && verifyPreimage(found.preimage, paymentHash)) {
+        guard.settle(paymentHash, found.fees_paid);
+        return {
+            preimage: found.preimage,
+            ...(found.fees_paid === undefined ? {} : { fees_paid: found.fees_paid }),
+            paymentHash,
+            verified: true,
+        };
+    }
+    if (found.state === 'failed' || found.state === 'expired') {
+        guard.release(paymentHash);
+        return null;
+    }
+    throw new ZapPaymentOutcomeUnknownError(paymentHash);
+}
+/**
+ * Pay a BOLT-11 invoice and return only after the wallet proves settlement.
+ *
+ * With a `guard`, bray's own per-payment and rolling daily ceilings are
+ * checked and the attempt is recorded before anything is sent. Every bray
+ * surface that spends passes one; library callers should too.
+ */
 export async function handleZapSend(_ctx, _pool, args) {
     const uri = requireWallet(args.nwcUri, 'enable payments');
     const decoded = tryDecodeBolt11(args.invoice);
@@ -249,6 +285,15 @@ export async function handleZapSend(_ctx, _pool, args) {
     if (decoded.amountMsats > BigInt(Number.MAX_SAFE_INTEGER)) {
         throw new Error('BOLT-11 amount exceeds JavaScript safe integer range');
     }
+    const paymentHash = decoded.paymentHashHex;
+    const guard = args.guard;
+    const prior = guard?.status(paymentHash);
+    if (guard && (prior === 'pending' || prior === 'unknown')) {
+        const settled = await reconcileUnknownPayment(uri, paymentHash, guard, args);
+        if (settled)
+            return settled;
+    }
+    guard?.reserve(paymentHash, Number(decoded.amountMsats));
     let paid;
     try {
         paid = await withClient(uri, args.transport, (client) => client.payInvoice({ invoice: args.invoice }, requestOptions(args)));
@@ -256,14 +301,19 @@ export async function handleZapSend(_ctx, _pool, args) {
     catch (error) {
         // An authenticated wallet rejection is definitive. Transport, timeout,
         // abort, and malformed-response failures can happen after submission.
-        if (error instanceof NwcError && error.code === 'WALLET_ERROR')
+        if (error instanceof NwcError && error.code === 'WALLET_ERROR') {
+            guard?.release(paymentHash);
             throw error;
-        throw new ZapPaymentOutcomeUnknownError(decoded.paymentHashHex);
+        }
+        guard?.markUnknown(paymentHash);
+        throw new ZapPaymentOutcomeUnknownError(paymentHash);
     }
-    if (!verifyPreimage(paid.preimage, decoded.paymentHashHex)) {
-        throw new ZapPaymentOutcomeUnknownError(decoded.paymentHashHex);
+    if (!verifyPreimage(paid.preimage, paymentHash)) {
+        guard?.markUnknown(paymentHash);
+        throw new ZapPaymentOutcomeUnknownError(paymentHash);
     }
-    return { ...paid, paymentHash: decoded.paymentHashHex, verified: true };
+    guard?.settle(paymentHash, paid.fees_paid);
+    return { ...paid, paymentHash, verified: true };
 }
 /** Return the wallet's confirmed balance in millisatoshis. */
 export async function handleZapBalance(_ctx, _pool, args) {

package/dist/zap/index.d.ts

@@ -1,2 +1,3 @@
 export * from './handlers.js';
 export * from './nwc-file.js';
+export * from './payment-guard.js';

package/dist/zap/index.js

@@ -1,2 +1,3 @@
 export * from './handlers.js';
 export * from './nwc-file.js';
+export * from './payment-guard.js';

package/dist/zap/payment-guard.d.ts

@@ -0,0 +1,59 @@
+/** 5,000 sats. */
+export declare const DEFAULT_MAX_PAYMENT_MSAT = 5000000;
+/** 20,000 sats in any rolling 24 hours. */
+export declare const DEFAULT_MAX_DAILY_MSAT = 20000000;
+/**
+ * Routing fees are unknown until a payment lands, so a payment reserves a
+ * margin for them: 1% of the amount, never less than 1 sat. The actual fee
+ * replaces the margin once the wallet reports it.
+ */
+export declare function feeReserveMsat(amountMsat: number): number;
+export interface PaymentLimits {
+    maxPaymentMsat: number;
+    maxDailyMsat: number;
+}
+/** Read `BRAY_MAX_PAYMENT_MSAT` and `BRAY_MAX_DAILY_MSAT`, falling back to the defaults. */
+export declare function paymentLimitsFromEnv(env?: NodeJS.ProcessEnv): PaymentLimits;
+/** bray's state directory: `BRAY_HOME`, else `$XDG_CONFIG_HOME/bray`, else `~/.config/bray`. */
+export declare function brayStateDir(env?: NodeJS.ProcessEnv): string;
+export declare function defaultLedgerPath(env?: NodeJS.ProcessEnv): string;
+/** A payment bray refused before anything was sent. */
+export declare class PaymentLimitError extends Error {
+    readonly code = "PAYMENT_LIMIT";
+    constructor(message: string);
+}
+export type PaymentStatus = 'pending' | 'paid' | 'failed' | 'unknown';
+export interface PaymentGuardOptions {
+    path?: string;
+    limits?: PaymentLimits;
+    now?: () => number;
+}
+export declare class PaymentGuard {
+    #private;
+    readonly path: string;
+    readonly limits: PaymentLimits;
+    constructor(options?: PaymentGuardOptions);
+    /**
+     * Throw if the caps would refuse a payment, without recording anything.
+     * An earlier attempt with an unknown outcome is left to the payment
+     * itself, which looks it up before deciding.
+     */
+    check(paymentHash: string, amountMsat: number): void;
+    /**
+     * Record a payment as about to be attempted, charging the amount plus a
+     * fee reserve against the daily total. Written before the attempt, so a
+     * crash mid-payment leaves the allowance spent rather than free.
+     */
+    reserve(paymentHash: string, amountMsat: number): void;
+    /** The payment settled: charge the amount and the fee actually paid. */
+    settle(paymentHash: string, feesPaidMsat: number | undefined): void;
+    /** The wallet refused before anything left: give the allowance back. */
+    release(paymentHash: string): void;
+    /** Something may have gone out: keep the whole reservation charged. */
+    markUnknown(paymentHash: string): void;
+    status(paymentHash: string): PaymentStatus | undefined;
+    /** Total counted against the rolling 24-hour allowance. */
+    spentTodayMsat(): number;
+}
+/** The guard every spending surface uses unless a test hands in its own. */
+export declare function defaultPaymentGuard(): PaymentGuard;