nostr-bray 3.4.2 → 3.5.0

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

@@ -1,8 +1,31 @@
-import type { Grant } from './service.js';
+import { type Grant, type GrantStore } from './service.js';
 export interface GrantsFile {
     version: 1;
     grants: Record<string, Grant[]>;
 }
 export declare function defaultGrantsFile(): string;
 export declare function loadGrants(path: string, pubkeyHex: string): Grant[];
+/**
+ * Change one identity's grants as they stand on disk now, under a lock.
+ * If `mutate` throws, nothing is written.
+ */
+export declare function updateGrants<T>(path: string, pubkeyHex: string, mutate: (grants: Grant[]) => T): T;
+/** Replace one identity's grants wholesale. Prefer `updateGrants`. */
 export declare function saveGrants(path: string, pubkeyHex: string, grants: Grant[]): void;
+/** Claim the right to serve the grants in `path`, or say who holds it. */
+export declare function acquireServeLock(path: string): void;
+export declare function releaseServeLock(path: string): void;
+/** A `GrantStore` over the grants file, for the process that serves them. */
+export declare function fileGrantStore(path: string, pubkeyHex: string): GrantStore;
+/** Revoke a connection on disk. Every process sees it before its next request. */
+export declare function revokeGrant(path: string, pubkeyHex: string, nameOrId: string, now?: number): Grant;
+/** Reset a spending connection's budget on disk, optionally to a new figure. */
+export declare function refillGrant(path: string, pubkeyHex: string, nameOrId: string, budgetMsat?: number): Grant;
+/**
+ * Write a grant's connection URI to its own 0600 file and return the path.
+ *
+ * The URI is a bearer secret: whoever holds it can do what the grant
+ * allows. It goes to a file for the operator to hand over, never into a
+ * tool result, where it would sit in a model's context and transcript.
+ */
+export declare function writeGrantUriFile(grantsFile: string, grant: Grant): string;

package/dist/wallet-service/grants.js

@@ -1,21 +1,30 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { homedir } from 'node:os';
 import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { grantUri } from './service.js';
+import { withFileLock } from '../file-lock.js';
 // Where the grants live.
 //
 // Each one carries two secret keys: the service key it answers under, and
 // the client key inside the URI that was handed out. Both spend, so the
 // file is 0600 and written atomically - a half-written grants file after a
 // crash would either lose a capability or leave one nobody can revoke.
+//
+// The file, not any process's memory, is the record. Several bray
+// processes can share it (an MCP session, a CLI, a second client), so
+// every change is a locked read-modify-write of the current file, and the
+// process that serves grants re-reads a grant before each request. A
+// revocation or refill made anywhere is therefore seen everywhere, and no
+// process can undo one by writing back what it happened to remember.
 const MAX_FILE_BYTES = 1_048_576;
 const MAX_GRANTS = 128;
 export function defaultGrantsFile() {
     return join(process.env.BRAY_HOME ?? join(homedir(), '.config', 'bray'), 'wallet-grants.json');
 }
-export function loadGrants(path, pubkeyHex) {
+function readFile(path) {
     if (!existsSync(path))
-        return [];
+        return { version: 1, grants: {} };
     const raw = readFileSync(path, 'utf8');
     if (raw.length > MAX_FILE_BYTES)
         throw new Error('The grants file is implausibly large; refusing to read it.');
@@ -26,31 +35,174 @@ export function loadGrants(path, pubkeyHex) {
     catch {
         throw new Error('The grants file is not readable JSON.');
     }
-    if (parsed?.version !== 1 || typeof parsed.grants !== 'object')
-        return [];
-    const held = parsed.grants[pubkeyHex];
+    if (parsed?.version !== 1 || typeof parsed.grants !== 'object' || parsed.grants === null) {
+        return { version: 1, grants: {} };
+    }
+    return parsed;
+}
+function writeFile(path, file) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, JSON.stringify(file, null, 2), { mode: 0o600 });
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, path);
+    chmodSync(path, 0o600);
+}
+export function loadGrants(path, pubkeyHex) {
+    const held = readFile(path).grants[pubkeyHex];
     return Array.isArray(held) ? held : [];
 }
+/**
+ * Change one identity's grants as they stand on disk now, under a lock.
+ * If `mutate` throws, nothing is written.
+ */
+export function updateGrants(path, pubkeyHex, mutate) {
+    return withFileLock(path, () => {
+        const file = readFile(path);
+        const grants = Array.isArray(file.grants[pubkeyHex]) ? file.grants[pubkeyHex] : [];
+        const result = mutate(grants);
+        if (grants.length > MAX_GRANTS)
+            throw new Error(`No more than ${MAX_GRANTS} connections per identity.`);
+        file.grants[pubkeyHex] = grants;
+        writeFile(path, file);
+        return result;
+    });
+}
+/** Replace one identity's grants wholesale. Prefer `updateGrants`. */
 export function saveGrants(path, pubkeyHex, grants) {
     if (grants.length > MAX_GRANTS)
         throw new Error(`No more than ${MAX_GRANTS} connections per identity.`);
-    let file = { version: 1, grants: {} };
-    if (existsSync(path)) {
+    updateGrants(path, pubkeyHex, (held) => {
+        held.splice(0, held.length, ...grants);
+    });
+}
+// Only one process answers for the grants at a time. Two serving the same
+// connection would each charge their own copy of its budget and each
+// answer the same request.
+function servingPid(lockPath) {
+    try {
+        const pid = Number.parseInt(readFileSync(lockPath, 'utf8'), 10);
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            return null;
+        if (pid === process.pid)
+            return pid;
         try {
-            const parsed = JSON.parse(readFileSync(path, 'utf8'));
-            if (parsed?.version === 1 && typeof parsed.grants === 'object')
-                file = parsed;
+            process.kill(pid, 0);
+            return pid;
         }
-        catch {
-            // an unreadable file is replaced rather than appended to; the
-            // alternative is refusing to ever write again
+        catch (err) {
+            return err.code === 'EPERM' ? pid : null;
         }
     }
-    file.grants[pubkeyHex] = grants;
+    catch {
+        return null;
+    }
+}
+/** Claim the right to serve the grants in `path`, or say who holds it. */
+export function acquireServeLock(path) {
+    const lockPath = `${path}.serving`;
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    const temporary = `${path}.${randomUUID()}.tmp`;
-    writeFileSync(temporary, JSON.stringify(file, null, 2), { mode: 0o600 });
-    chmodSync(temporary, 0o600);
-    renameSync(temporary, path);
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            const descriptor = openSync(lockPath, 'wx', 0o600);
+            try {
+                writeSync(descriptor, String(process.pid));
+            }
+            finally {
+                closeSync(descriptor);
+            }
+            return;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            const holder = servingPid(lockPath);
+            if (holder === process.pid)
+                return;
+            if (holder !== null) {
+                throw new Error(`Another bray process (pid ${holder}) is already serving these wallet connections. Stop it first; two processes serving the same connections would each count their own budget.`);
+            }
+            // The holder is gone: its claim goes with it.
+            try {
+                unlinkSync(lockPath);
+            }
+            catch { /* someone else cleared it first */ }
+        }
+    }
+    throw new Error('Could not claim the wallet-service lock.');
+}
+export function releaseServeLock(path) {
+    const lockPath = `${path}.serving`;
+    if (servingPid(lockPath) === process.pid) {
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { /* already gone */ }
+    }
+}
+/** A `GrantStore` over the grants file, for the process that serves them. */
+export function fileGrantStore(path, pubkeyHex) {
+    return {
+        read: (grantId) => loadGrants(path, pubkeyHex).find((grant) => grant.id === grantId),
+        update: (grantId, mutate) => updateGrants(path, pubkeyHex, (grants) => {
+            const grant = grants.find((held) => held.id === grantId);
+            if (!grant)
+                return undefined;
+            mutate(grant);
+            return structuredClone(grant);
+        }),
+    };
+}
+function find(grants, nameOrId, byPrefix) {
+    const wanted = nameOrId.trim().toLowerCase();
+    return (grants.find((held) => held.id === wanted) ??
+        grants.find((held) => held.name.toLowerCase() === wanted) ??
+        (byPrefix ? grants.find((held) => held.id.startsWith(wanted)) : undefined));
+}
+/** Revoke a connection on disk. Every process sees it before its next request. */
+export function revokeGrant(path, pubkeyHex, nameOrId, now = Date.now()) {
+    return updateGrants(path, pubkeyHex, (grants) => {
+        const grant = find(grants, nameOrId, true);
+        if (!grant)
+            throw new Error(`No connection here called ${nameOrId}.`);
+        grant.revokedAt ??= now;
+        return structuredClone(grant);
+    });
+}
+/** Reset a spending connection's budget on disk, optionally to a new figure. */
+export function refillGrant(path, pubkeyHex, nameOrId, budgetMsat) {
+    return updateGrants(path, pubkeyHex, (grants) => {
+        const grant = find(grants, nameOrId, false);
+        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) {
+            if (grant.maxPaymentMsat !== undefined && grant.maxPaymentMsat > budgetMsat) {
+                throw new Error('The per-payment ceiling is above that budget.');
+            }
+            grant.budgetMsat = budgetMsat;
+        }
+        grant.spentMsat = 0;
+        return structuredClone(grant);
+    });
+}
+/**
+ * Write a grant's connection URI to its own 0600 file and return the path.
+ *
+ * The URI is a bearer secret: whoever holds it can do what the grant
+ * allows. It goes to a file for the operator to hand over, never into a
+ * tool result, where it would sit in a model's context and transcript.
+ */
+export function writeGrantUriFile(grantsFile, grant) {
+    const directory = join(dirname(grantsFile), 'wallet-connections');
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    chmodSync(directory, 0o700);
+    const slug = grant.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'connection';
+    const path = join(directory, `${slug}-${grant.id}.nwc`);
+    writeFileSync(path, `${grantUri(grant)}\n`, { mode: 0o600, flag: 'wx' });
     chmodSync(path, 0o600);
+    return path;
 }

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

@@ -2,7 +2,7 @@ import type { Event as NostrEvent, Filter } from 'nostr-tools';
 export declare const NWC_INFO_KIND = 13194;
 export declare const NWC_REQUEST_KIND = 23194;
 export declare const NWC_RESPONSE_KIND = 23195;
-export declare const DEFAULT_METHODS: readonly ["get_info", "make_invoice", "lookup_invoice"];
+export declare const DEFAULT_METHODS: readonly ["get_info", "make_invoice"];
 export declare const SUPPORTED_METHODS: readonly ["get_info", "get_balance", "make_invoice", "lookup_invoice", "pay_invoice"];
 export declare const SPENDING_METHODS: readonly string[];
 export declare class ServiceError extends Error {
@@ -36,7 +36,7 @@ export interface ServiceWallet {
         amountMsat: number;
     }): Promise<{
         preimage: string;
-        feesPaidMsat: number;
+        feesPaidMsat?: number;
     }>;
     lookupInvoice(query: {
         paymentHash?: string;
@@ -60,6 +60,7 @@ export interface Grant {
     spentMsat: number;
     maxPaymentMsat?: number;
     seen?: string[];
+    hashes?: string[];
     createdAt: number;
     lastUsedAt?: number;
     revokedAt?: number;
@@ -81,10 +82,15 @@ export declare function newGrant(input: {
     maxPaymentMsat?: number;
 }): Grant;
 export declare function infoEvent(grant: Grant): NostrEvent;
+export interface GrantStore {
+    read(grantId: string): Grant | undefined;
+    update(grantId: string, mutate: (grant: Grant) => void): Grant | undefined;
+}
 export interface ServiceOptions {
     wallet: ServiceWallet;
     transport: ServiceTransport;
-    persist: () => Promise<void>;
+    store?: GrantStore;
+    persist?: () => Promise<void>;
     log?: (message: string) => void;
     now?: () => number;
 }

package/dist/wallet-service/service.js

@@ -1,6 +1,7 @@
 import { finalizeEvent, getPublicKey, verifyEvent, nip44 } from 'nostr-tools';
 import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
 import { tryDecodeBolt11 } from 'farrier-kit';
+import { feeReserveMsat } from '../zap/payment-guard.js';
 // A NIP-47 wallet service: the server side of Nostr Wallet Connect.
 //
 // bray already speaks NWC as a client - `zap-send` spends through a wallet
@@ -29,7 +30,10 @@ import { tryDecodeBolt11 } from 'farrier-kit';
 export const NWC_INFO_KIND = 13194;
 export const NWC_REQUEST_KIND = 23194;
 export const NWC_RESPONSE_KIND = 23195;
-export const DEFAULT_METHODS = ['get_info', 'make_invoice', 'lookup_invoice'];
+// lookup_invoice is not a default: even scoped to this connection's own
+// invoices it is one more thing to hand out, and a connection that only
+// issues invoices has no need to read them back.
+export const DEFAULT_METHODS = ['get_info', 'make_invoice'];
 export const SUPPORTED_METHODS = [
     'get_info',
     'get_balance',
@@ -45,6 +49,8 @@ export const SPENDING_METHODS = ['pay_invoice'];
 const MAX_REQUEST_AGE_SECS = 300;
 const MAX_REQUEST_FUTURE_SECS = 60;
 const SEEN_LIMIT = 256;
+// Payment hashes a connection may look up: the ones it created or paid.
+const OWN_HASHES_LIMIT = 1024;
 export class ServiceError extends Error {
     code;
     constructor(code, message) {
@@ -162,6 +168,25 @@ function invoiceResult(view) {
         ...(view.feesPaidMsat === undefined ? {} : { fees_paid: view.feesPaidMsat }),
     };
 }
+// The fields another process may change while this one serves.
+function adopt(target, source) {
+    target.methods = source.methods;
+    target.spentMsat = source.spentMsat;
+    target.seen = source.seen;
+    target.hashes = source.hashes;
+    if (source.budgetMsat === undefined)
+        delete target.budgetMsat;
+    else
+        target.budgetMsat = source.budgetMsat;
+    if (source.maxPaymentMsat === undefined)
+        delete target.maxPaymentMsat;
+    else
+        target.maxPaymentMsat = source.maxPaymentMsat;
+    if (source.lastUsedAt !== undefined)
+        target.lastUsedAt = source.lastUsedAt;
+    if (source.revokedAt !== undefined)
+        target.revokedAt = source.revokedAt;
+}
 export class WalletService {
     #opts;
     #now;
@@ -195,6 +220,37 @@ export class WalletService {
         for (const id of [...this.#stops.keys()])
             this.stop(id);
     }
+    // The grant as the store has it now. False when it is gone or revoked.
+    #refresh(grant) {
+        const store = this.#opts.store;
+        if (store) {
+            const current = store.read(grant.id);
+            if (!current)
+                return false;
+            adopt(grant, current);
+        }
+        return !grant.revokedAt;
+    }
+    // Change a grant where it is recorded, then here.
+    async #change(grant, mutate) {
+        const store = this.#opts.store;
+        if (store) {
+            const updated = store.update(grant.id, mutate);
+            if (!updated)
+                throw new ServiceError('UNAUTHORIZED', 'This connection no longer exists.');
+            adopt(grant, updated);
+        }
+        else {
+            mutate(grant);
+        }
+        await this.#opts.persist?.();
+    }
+    async #own(grant, paymentHash) {
+        const hash = paymentHash.toLowerCase();
+        await this.#change(grant, (held) => {
+            held.hashes = remembered(held.hashes, hash);
+        });
+    }
     // Every request on one connection runs after the last has finished. Two
     // pay_invoice requests arriving together must not both read the same
     // remaining budget and both decide there is room.
@@ -206,8 +262,15 @@ export class WalletService {
     }
     async #handle(grantId, event) {
         const grant = this.#grants.get(grantId);
-        if (!grant || grant.revokedAt)
+        if (!grant)
+            return;
+        // Revoked by any process, or refilled, or spent from: the stored grant
+        // is the one that counts.
+        if (!this.#refresh(grant)) {
+            this.stop(grantId);
+            this.#opts.log?.(`stopped serving ${grant.name}: it has been revoked`);
             return;
+        }
         // Anyone can publish an event tagged at this pubkey - it is in the info
         // event, which is public. What keeps a stranger out is further down:
         // the conversation key is derived from THIS connection's client pubkey,
@@ -225,8 +288,7 @@ export class WalletService {
         const expiration = event.tags.find((tag) => tag[0] === 'expiration')?.[1];
         if (expiration && Number(expiration) < seconds)
             return;
-        const seen = grant.seen ?? [];
-        if (seen.includes(event.id)) {
+        if ((grant.seen ?? []).includes(event.id)) {
             this.#opts.log?.(`ignored a replayed request on ${grant.name}`);
             return;
         }
@@ -241,9 +303,11 @@ export class WalletService {
         const method = typeof parsed.method === 'string' ? parsed.method : '';
         const params = (parsed.params ?? {});
         const remember = async () => {
-            grant.seen = [...seen, event.id].slice(-SEEN_LIMIT);
-            grant.lastUsedAt = this.#now();
-            await this.#opts.persist();
+            const at = this.#now();
+            await this.#change(grant, (held) => {
+                held.seen = [...(held.seen ?? []), event.id].slice(-SEEN_LIMIT);
+                held.lastUsedAt = at;
+            });
         };
         // A spending request is written down before it runs, so a crash between
         // the two leaves a request that will not be tried again rather than one
@@ -276,51 +340,82 @@ export class WalletService {
             case 'get_info':
                 return { alias: wallet.alias(), network: 'mainnet', methods: grant.methods, notifications: [] };
             case 'get_balance':
-                return { balance: await wallet.balanceMsat() };
+                // What this connection can spend, not what the wallet holds: the
+                // parent balance is the operator's business, and a connection with
+                // no budget can spend nothing.
+                return { balance: remainingBudgetMsat(grant) };
             case 'make_invoice': {
                 const amountMsat = Number(params.amount);
                 if (!Number.isSafeInteger(amountMsat) || amountMsat <= 0) {
                     throw new ServiceError('OTHER', 'make_invoice needs an amount in milli-satoshis.');
                 }
                 const description = typeof params.description === 'string' ? params.description : undefined;
-                return invoiceResult(await wallet.makeInvoice({ amountMsat, ...(description === undefined ? {} : { description }) }));
+                const view = await wallet.makeInvoice({ amountMsat, ...(description === undefined ? {} : { description }) });
+                await this.#own(grant, view.paymentHash);
+                return invoiceResult(view);
             }
             case 'lookup_invoice': {
-                const paymentHash = typeof params.payment_hash === 'string' ? params.payment_hash : undefined;
-                const invoice = typeof params.invoice === 'string' ? params.invoice : undefined;
-                if (!paymentHash && !invoice) {
+                const asked = typeof params.payment_hash === 'string' ? params.payment_hash.trim().toLowerCase() : undefined;
+                const invoice = typeof params.invoice === 'string' ? params.invoice.trim() : undefined;
+                if (!asked && !invoice) {
                     throw new ServiceError('OTHER', 'lookup_invoice needs a payment_hash or an invoice.');
                 }
-                const view = await wallet.lookupInvoice({
-                    ...(paymentHash === undefined ? {} : { paymentHash }),
-                    ...(invoice === undefined ? {} : { invoice }),
-                });
-                if (!view)
-                    throw new ServiceError('NOT_FOUND', 'No invoice here by that name.');
+                const fromInvoice = invoice ? tryDecodeBolt11(invoice)?.paymentHashHex : undefined;
+                if (invoice && !fromInvoice)
+                    throw new ServiceError('OTHER', 'That is not a decodable BOLT-11 invoice.');
+                if (asked && fromInvoice && asked !== fromInvoice) {
+                    throw new ServiceError('OTHER', 'That payment_hash and invoice do not match.');
+                }
+                const paymentHash = (asked ?? fromInvoice);
+                // Not this connection's invoice: answered exactly as a missing one,
+                // so a connection cannot probe the wallet's history either.
+                const notFound = new ServiceError('NOT_FOUND', 'No invoice here by that name.');
+                if (!(grant.hashes ?? []).includes(paymentHash))
+                    throw notFound;
+                const view = await wallet.lookupInvoice({ paymentHash });
+                if (!view || view.paymentHash.toLowerCase() !== paymentHash)
+                    throw notFound;
                 return invoiceResult(view);
             }
             case 'pay_invoice': {
                 const invoice = typeof params.invoice === 'string' ? params.invoice.trim() : '';
                 if (!invoice)
                     throw new ServiceError('OTHER', 'pay_invoice needs an invoice.');
-                const amountMsat = priceOf(invoice, params);
-                charge(grant, amountMsat);
-                // Spent BEFORE the attempt and persisted: a crash mid-payment must
-                // leave a budget that has paid for it. The other order lets one
-                // connection spend its grant twice by dying at the right moment.
-                grant.spentMsat += amountMsat;
-                await this.#opts.persist();
+                const { amountMsat, paymentHash } = priceOf(invoice, params);
+                // Checked and spent in one step against the stored grant, BEFORE the
+                // attempt: a crash mid-payment must leave a budget that has paid for
+                // it. The other order lets one connection spend its grant twice by
+                // dying at the right moment.
+                // Routing fees come out of the budget too. They are unknown until
+                // the payment lands, so a margin is reserved up front and swapped
+                // for the real fee afterwards.
+                const reserveMsat = feeReserveMsat(amountMsat);
+                await this.#change(grant, (held) => {
+                    charge(held, amountMsat, reserveMsat);
+                    held.spentMsat += amountMsat + reserveMsat;
+                    held.hashes = remembered(held.hashes, paymentHash);
+                });
+                let paid;
                 try {
-                    const paid = await this.#opts.wallet.payInvoice({ invoice, amountMsat });
-                    return { preimage: paid.preimage, fees_paid: paid.feesPaidMsat };
+                    paid = await this.#opts.wallet.payInvoice({ invoice, amountMsat });
                 }
                 catch (err) {
                     if (err instanceof PaymentNotSentError) {
-                        grant.spentMsat -= amountMsat;
-                        await this.#opts.persist();
+                        await this.#change(grant, (held) => {
+                            held.spentMsat = Math.max(0, held.spentMsat - amountMsat - reserveMsat);
+                        });
                     }
                     throw err;
                 }
+                const fee = paid.feesPaidMsat;
+                const known = fee !== undefined && Number.isSafeInteger(fee) && fee >= 0;
+                // A wallet that does not report its fee keeps the whole margin charged.
+                if (known) {
+                    await this.#change(grant, (held) => {
+                        held.spentMsat = Math.max(0, held.spentMsat - reserveMsat + fee);
+                    });
+                }
+                return { preimage: paid.preimage, ...(known ? { fees_paid: fee } : {}) };
             }
             default:
                 throw new ServiceError('NOT_IMPLEMENTED', `This service cannot answer ${method}.`);
@@ -330,6 +425,10 @@ export class WalletService {
 // What this payment costs the budget, read off the invoice itself rather
 // than taken from the request. A budget checked against a figure the payer
 // supplied is not a budget.
+function remembered(hashes, paymentHash) {
+    const held = hashes ?? [];
+    return held.includes(paymentHash) ? held : [...held, paymentHash].slice(-OWN_HASHES_LIMIT);
+}
 function priceOf(invoice, params) {
     const decoded = tryDecodeBolt11(invoice);
     if (!decoded)
@@ -343,15 +442,16 @@ function priceOf(invoice, params) {
         if (asked !== undefined && asked !== stated) {
             throw new PaymentNotSentError(`That invoice is for ${stated} msat, not the ${asked} msat asked for.`);
         }
-        return stated;
+        return { amountMsat: stated, paymentHash: decoded.paymentHashHex };
     }
-    if (asked === undefined)
-        throw new PaymentNotSentError('That invoice states no amount - say how much to send.');
-    return asked;
+    // An amountless invoice is refused, as zap-send refuses one. The wallet
+    // behind the service is asked to pay the invoice alone, so a figure
+    // checked against the budget here would not be the figure it sent.
+    throw new PaymentNotSentError('Invoices that state no amount are not paid through this connection.');
 }
 // Refuses before anything is attempted, and says which ceiling it hit: a
 // payer told only "no" tries again.
-function charge(grant, amountMsat) {
+function charge(grant, amountMsat, reserveMsat) {
     if (grant.budgetMsat === undefined) {
         throw new ServiceError('RESTRICTED', 'This connection has no budget to spend from.');
     }
@@ -359,7 +459,7 @@ function charge(grant, amountMsat) {
         throw new ServiceError('QUOTA_EXCEEDED', `That is ${amountMsat} msat and this connection's ceiling for one payment is ${grant.maxPaymentMsat} msat.`);
     }
     const remaining = remainingBudgetMsat(grant);
-    if (amountMsat > remaining) {
-        throw new ServiceError('QUOTA_EXCEEDED', `That is ${amountMsat} msat and this connection has ${remaining} msat of its budget left.`);
+    if (amountMsat + reserveMsat > remaining) {
+        throw new ServiceError('QUOTA_EXCEEDED', `That is ${amountMsat} msat plus up to ${reserveMsat} msat reserved for fees, and this connection has ${remaining} msat of its budget left.`);
     }
 }

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

@@ -1,3 +1,12 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ToolDeps } from '../identity/tools.js';
-export declare function registerWalletServiceTools(server: McpServer, deps: ToolDeps): void;
+export interface WalletServiceToolOptions {
+    /**
+     * Register the tools that mint or widen spending authority: wallet-grant,
+     * wallet-refill and wallet-serve. Off by default; BRAY_WALLET_SERVICE=1
+     * turns it on. Listing and revoking connections are always available,
+     * because taking authority away should never need an opt-in.
+     */
+    issuing?: boolean;
+}
+export declare function registerWalletServiceTools(server: McpServer, deps: ToolDeps, options?: WalletServiceToolOptions): void;