nostr-bray 3.4.3 → 3.5.0

package/dist/marketplace/tools.js

@@ -2,8 +2,10 @@ import { z } from 'zod';
 import { randomUUID } from 'node:crypto';
 import { hexId, relayUrl } from '../validation.js';
 import { resolveRecipient } from '../resolve.js';
-import { handleMarketplaceDiscover, handleMarketplaceInspect, handleMarketplaceSearch, handleMarketplaceReputation, handleMarketplaceCompare, handleMarketplaceProbe, handleMarketplaceCall, handleMarketplaceAnnounce, handleMarketplaceUpdate, handleMarketplaceRetire, storeCredential, clearCredentials, extractBolt11AmountSats, } from './handlers.js';
+import { handleMarketplaceDiscover, handleMarketplaceInspect, handleMarketplaceSearch, handleMarketplaceReputation, handleMarketplaceCompare, handleMarketplaceProbe, handleMarketplaceCall, handleMarketplaceAnnounce, handleMarketplaceUpdate, handleMarketplaceRetire, storeCredential, credentialOrigin, clearCredentials, extractBolt11AmountSats, } from './handlers.js';
 import { handleZapSend, handleZapDecode } from '../zap/handlers.js';
+import { defaultPaymentGuard } from '../zap/payment-guard.js';
+import { askHumanToApprovePayment } from '../zap/confirm.js';
 import { handleListingCreate, handleListingRead, handleListingSearch, handleListingClose, } from './listings.js';
 import { toolResponse } from '../tool-response.js';
 import * as fmt from '../format.js';
@@ -137,15 +139,20 @@ export function registerMarketplaceTools(server, deps) {
     });
     server.registerTool('marketplace-pay', {
         description: 'Pay an L402 invoice via NWC and store credentials for authenticated API calls. ' +
-            'SPENDS REAL SATS. Decodes the invoice first — set confirm: true to execute payment. ' +
+            'SPENDS REAL SATS. Decodes the invoice first; set confirm: true to pay. When the MCP client supports ' +
+            'elicitation the human is asked to approve the payment as well, and bray\'s spending caps always apply. ' +
             'Returns an opaque credential ID for use with marketplace-call.',
         inputSchema: {
+            url: z.string().url().describe('The endpoint URL whose 402 challenge this is. The credential is only ever sent back to this origin'),
             macaroon: z.string().describe('Base64-encoded macaroon from L402 challenge'),
             invoice: z.string().describe('Bolt11 Lightning invoice from L402 challenge'),
             confirm: z.boolean().default(false).describe('Set true to execute payment (preview by default)'),
         },
         annotations: { readOnlyHint: false, destructiveHint: true },
-    }, async ({ macaroon, invoice, confirm }) => {
+    }, async ({ url, macaroon, invoice, confirm }) => {
+        // Bound before anything is paid: a credential with nowhere valid to go
+        // is money spent for nothing.
+        const origin = credentialOrigin(url);
         const decoded = handleZapDecode(invoice);
         if (decoded.expiry === undefined)
             throw new Error('Invalid BOLT-11 invoice');
@@ -165,32 +172,57 @@ export function registerMarketplaceTools(server, deps) {
                     }],
             };
         }
+        const guard = defaultPaymentGuard();
+        guard.check(decoded.paymentHash, decoded.amountMsats);
+        const approval = await askHumanToApprovePayment(server, {
+            amountMsats: decoded.amountMsats,
+            purpose: 'buy access to a paid API (L402)',
+            ...(decoded.description ? { description: decoded.description } : {}),
+            paymentHash: decoded.paymentHash,
+        });
+        if (approval === 'declined') {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            paid: false,
+                            declined: true,
+                            amountMsats: decoded.amountMsats,
+                            message: 'The payment was not approved, so nothing was sent.',
+                        }, null, 2),
+                    }],
+            };
+        }
         // Pay via NWC (same as zap-send) — resolve per-identity wallet
         const { resolveNwcUri } = await import('../zap/handlers.js');
         const payResult = await handleZapSend(deps.ctx, deps.pool, {
             invoice,
             nwcUri: resolveNwcUri(deps.ctx, deps.walletsFile, deps.nwcUri),
+            guard,
+            ...(deps.nwcTransport ? { transport: deps.nwcTransport } : {}),
         });
         // Keep the bearer credential in process and return only an opaque handle.
         const credentialId = randomUUID();
-        storeCredential(credentialId, macaroon, payResult.preimage);
+        storeCredential(credentialId, macaroon, payResult.preimage, origin);
         return {
             content: [{
                     type: 'text',
                     text: JSON.stringify({
                         paid: true,
                         verified: payResult.verified,
+                        humanApproved: approval === 'approved',
                         credentialId,
+                        origin,
                         costSats,
                         amountMsats: decoded.amountMsats,
-                        note: 'Use this credentialId with marketplace-call to make authenticated requests.',
+                        note: `Use this credentialId with marketplace-call to make authenticated requests to ${origin}. It is refused for any other origin.`,
                     }, null, 2),
                 }],
         };
     });
     server.registerTool('marketplace-call', {
         description: 'Make an authenticated API call using L402 credentials obtained from marketplace-pay. ' +
-            'The credential ID maps to a stored macaroon + preimage — never exposed directly.',
+            'The credential ID maps to a stored macaroon + preimage, never exposed directly, and is only sent to the origin it was paid for.',
         inputSchema: {
             url: z.string().url().describe('HTTP(S) endpoint URL'),
             method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']).default('GET').describe('HTTP method'),

package/dist/sdk.js

@@ -28,6 +28,7 @@ import { handleTrustSpokenChallenge, handleTrustSpokenVerify } from './trust/spo
 import { handleRelayInfo, handleRelayList, handleRelaySet, handleRelayQuery } from './relay/handlers.js';
 import { handleSyncPlan, handleSyncPull, handleSyncPush } from './sync/handlers.js';
 import { handleZapSend, handleZapBalance, handleZapMakeInvoice, handleZapLookupInvoice, handleZapListTransactions, handleZapReceipts, handleZapDecode, resolveNwcUri } from './zap/handlers.js';
+import { defaultPaymentGuard } from './zap/payment-guard.js';
 import { handleDuressConfigure, handleDuressActivate } from './safety/handlers.js';
 import { handlePublishRaw } from './event/handlers.js';
 import { handleValidateEvent } from './event-validation/validator.js';
@@ -241,7 +242,9 @@ class BrayClientImpl {
     }
     // ── Zap ─────────────────────────────────────────────────────────────────────
     #nwc() { return resolveNwcUri(this.#ctx, this.#walletsFile, this.#nwcUri); }
-    async zapSend(bolt11) { return handleZapSend(this.#ctx, this.#pool, { invoice: bolt11, nwcUri: this.#nwc() }); }
+    async zapSend(bolt11) {
+        return handleZapSend(this.#ctx, this.#pool, { invoice: bolt11, nwcUri: this.#nwc(), guard: defaultPaymentGuard() });
+    }
     async zapBalance() { return handleZapBalance(this.#ctx, this.#pool, { nwcUri: this.#nwc() }); }
     async zapInvoice(amountMsats, description) {
         return handleZapMakeInvoice(this.#ctx, this.#pool, { amountMsats, description, nwcUri: this.#nwc() });

package/dist/tool-groups.d.ts

@@ -0,0 +1,16 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolDeps } from './identity/tools.js';
+export interface ToolGroupOptions {
+    veilCacheTtl: number;
+    veilCacheMax: number;
+    /** Dispatch tools are registered only when an identities file is configured. */
+    dispatchIdentitiesPath?: string;
+    /** wallet-grant, wallet-refill and wallet-serve are registered only when true. */
+    walletService?: boolean;
+}
+/**
+ * Register every tool group, in one place. The MCP server, the tool-schema
+ * export and the tool-count test all go through this, so the number of
+ * tools the docs quote is the number the server registers.
+ */
+export declare function registerAllTools(server: McpServer, deps: ToolDeps, options: ToolGroupOptions): void;

package/dist/tool-groups.js

@@ -0,0 +1,52 @@
+import { registerIdentityTools } from './identity/tools.js';
+import { registerSocialTools } from './social/tools.js';
+import { registerTrustTools } from './trust/tools.js';
+import { registerRelayTools } from './relay/tools.js';
+import { registerRelayIntelligenceTools } from './relay/intelligence-tools.js';
+import { registerZapTools } from './zap/tools.js';
+import { registerWalletServiceTools } from './wallet-service/tools.js';
+import { registerSafetyTools } from './safety/tools.js';
+import { registerUtilTools } from './util/tools.js';
+import { registerWorkflowTools } from './workflow/tools.js';
+import { registerMarketplaceTools } from './marketplace/tools.js';
+import { registerPrivacyTools } from './privacy/tools.js';
+import { registerModerationTools } from './moderation/tools.js';
+import { registerSignetTools } from './signet/tools.js';
+import { registerVaultTools } from './vault/tools.js';
+import { registerDispatchTools } from './dispatch/tools.js';
+import { registerHandlerTools } from './handler/tools.js';
+import { registerSyncTools } from './sync/tools.js';
+/**
+ * Register every tool group, in one place. The MCP server, the tool-schema
+ * export and the tool-count test all go through this, so the number of
+ * tools the docs quote is the number the server registers.
+ */
+export function registerAllTools(server, deps, options) {
+    registerIdentityTools(server, deps);
+    registerSocialTools(server, deps);
+    registerTrustTools(server, deps);
+    registerRelayTools(server, deps);
+    registerRelayIntelligenceTools(server, deps);
+    registerZapTools(server, deps);
+    registerWalletServiceTools(server, deps, { issuing: options.walletService === true });
+    registerSafetyTools(server, deps);
+    registerUtilTools(server, deps);
+    registerWorkflowTools(server, {
+        ctx: deps.ctx,
+        pool: deps.pool,
+        nip65: deps.nip65,
+        veilCacheTtl: options.veilCacheTtl,
+        veilCacheMax: options.veilCacheMax,
+    });
+    registerMarketplaceTools(server, deps);
+    registerPrivacyTools(server, deps);
+    registerModerationTools(server, deps);
+    registerSignetTools(server, deps);
+    registerVaultTools(server, deps);
+    registerDispatchTools(server, {
+        ...deps,
+        ...(options.dispatchIdentitiesPath ? { dispatchIdentitiesPath: options.dispatchIdentitiesPath } : {}),
+    });
+    registerHandlerTools(server, deps);
+    registerSyncTools(server, deps);
+}

package/dist/types.d.ts

@@ -45,6 +45,8 @@ export interface BrayConfig {
     readonly bunkerUri?: string;
     readonly nwcUri?: string;
     readonly walletsFile: string;
+    /** Whether the spending-authority wallet-service tools are registered (BRAY_WALLET_SERVICE=1). */
+    readonly walletService?: boolean;
     readonly torProxy?: string;
     readonly allowClearnetWithTor: boolean;
     readonly allowPrivateRelays: boolean;

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const BRAY_VERSION: string;

package/dist/version.js

@@ -0,0 +1,6 @@
+import { createRequire } from 'node:module';
+// Read from package.json at runtime so the version the MCP server reports
+// cannot drift from the one that was published. From both src/ (tests) and
+// dist/ (the build), package.json is one directory up.
+const require = createRequire(import.meta.url);
+export const BRAY_VERSION = require('../package.json').version;

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;
 }