nostr-bray 3.4.2 → 3.5.0

package/dist/heartwood-context.js

@@ -5,50 +5,148 @@
  * extension methods for identity derivation, switching, proofs, and recovery.
  * HeartwoodContext auto-detects these extensions by probing the remote signer.
  */
-import { BunkerContext } from './bunker-context.js';
+import { BunkerContext, withTimeout, TimeoutError, REQUEST_TIMEOUT_MS } from './bunker-context.js';
+/** Matches an error whose text indicates the remote signer does not know the method at all. */
+function isMethodUnknownError(message) {
+    return /unsupported method|method not found|unknown method|no such method|not implemented/i.test(message);
+}
+/** Matches an error whose text indicates the request was understood but refused by policy. */
+function isUnauthorisedError(message) {
+    return /unauthori[sz]ed|denied|not permitted|forbidden/i.test(message);
+}
+/** How long a Heartwood request runs before we hint that it's probably
+ *  waiting on a device button press. Well under REQUEST_TIMEOUT_MS so the
+ *  hint has a chance to show before the request either completes or times out. */
+const APPROVAL_HINT_MS = 3_000;
+/**
+ * Wrap a Heartwood NIP-46 request with the standard 60s timeout, and log a
+ * one-off hint to stderr if it's still pending after {@link APPROVAL_HINT_MS}.
+ * bray is an MCP server over stdio, so this MUST go to stderr (console.error,
+ * same channel every other log line in this codebase uses) and never stdout,
+ * which carries the JSON-RPC transport.
+ */
+function withApprovalHint(promise, label) {
+    const hint = setTimeout(() => {
+        console.error(`Waiting for approval on your Heartwood (${label})...`);
+    }, APPROVAL_HINT_MS);
+    return withTimeout(promise, REQUEST_TIMEOUT_MS, label).finally(() => clearTimeout(hint));
+}
+/** Extract a human-readable message from whatever `sendRequest` rejected with.
+ *  NIP-46 error responses reject with a bare string (the signer's `error`
+ *  field); our own code (timeouts, network failures) rejects with an `Error`. */
+function errorMessage(e) {
+    if (typeof e === 'string')
+        return e;
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}
 export class HeartwoodContext extends BunkerContext {
+    /** Whether `listIdentities()` (and thus features that depend on the
+     *  device's identity list) is expected to work for this pairing. `true`
+     *  unless `probe()` could not confirm listing works. */
+    listingAvailable = true;
+    /** Set by `probe()` alongside `listingAvailable = false`; explains why. */
+    listingUnavailableReason;
+    /** Human-readable explanation of `listingUnavailableReason`, suitable for
+     *  logging or surfacing to a caller. Undefined when listing is available. */
+    listingUnavailableMessage;
     /**
      * Probe a connected BunkerContext for Heartwood extensions.
-     * Returns a HeartwoodContext if extensions are available, null otherwise.
      *
-     * The probe sends a single heartwood_list_identities request. If the remote
-     * signer responds with a result (not an error), the extensions are available.
+     * Returns `null` when the remote signer does not speak the Heartwood
+     * dialect at all (method unknown/unsupported, or a response that doesn't
+     * look like an identity list) -- the base context stays a plain bunker,
+     * silently, as before.
+     *
+     * Returns a `HeartwoodContext` in every other case where the device IS a
+     * Heartwood but identity listing could not be confirmed:
+     * - the request was refused by policy (`unauthorised`/denied -- e.g. a
+     *   strict slot that doesn't list `heartwood_list_identities`), or
+     * - the request timed out, most likely because it's awaiting a button
+     *   press on the device right now.
+     *
+     * In both of those cases `listingAvailable` is set to `false` and
+     * `listingUnavailableReason` / `listingUnavailableMessage` explain why.
+     * Callers that only check "is this a Heartwood" (`hw !== null` /
+     * `instanceof HeartwoodContext`) see no change in behaviour.
      */
     static async probe(base) {
+        // Cast to access protected signer — safe because HeartwoodContext extends BunkerContext
+        const signer = base.signer;
+        let result;
         try {
-            // Cast to access protected signer — safe because HeartwoodContext extends BunkerContext
-            const signer = base.signer;
-            const result = await signer.sendRequest('heartwood_list_identities', []);
-            if (!isHeartwoodIdentitiesResponse(result))
-                return null;
-            // Re-class the base context as HeartwoodContext
-            return Object.setPrototypeOf(base, HeartwoodContext.prototype);
+            result = await withTimeout(signer.sendRequest('heartwood_list_identities', []), REQUEST_TIMEOUT_MS, 'heartwood probe (heartwood_list_identities)');
         }
-        catch {
+        catch (e) {
+            const message = errorMessage(e);
+            if (e instanceof TimeoutError) {
+                return HeartwoodContext.upgrade(base, 'pending-approval', 'Heartwood is awaiting approval on the device for identity listing ' +
+                    '(heartwood_list_identities timed out) -- approve the pending request on the device.');
+            }
+            if (isUnauthorisedError(message)) {
+                return HeartwoodContext.upgrade(base, 'denied', 'Heartwood denied identity listing for this pairing; allow heartwood_list_identities for this app in Sapwood.');
+            }
+            if (isMethodUnknownError(message))
+                return null;
+            // Anything else is genuinely ambiguous -- keep the previous, conservative
+            // behaviour of treating it as "not a Heartwood" rather than guessing.
             return null;
         }
+        if (!isHeartwoodIdentitiesResponse(result))
+            return null;
+        // Re-class the base context as HeartwoodContext. Object.setPrototypeOf
+        // only swaps the prototype -- it does NOT re-run class field
+        // initialisers on an object that was constructed as a plain
+        // BunkerContext, so `listingAvailable` must be set explicitly here.
+        const hw = Object.setPrototypeOf(base, HeartwoodContext.prototype);
+        hw.listingAvailable = true;
+        hw.listingUnavailableReason = undefined;
+        hw.listingUnavailableMessage = undefined;
+        return hw;
+    }
+    /** Re-class `base` as a HeartwoodContext with listing marked unavailable. */
+    static upgrade(base, reason, message) {
+        const hw = Object.setPrototypeOf(base, HeartwoodContext.prototype);
+        hw.listingAvailable = false;
+        hw.listingUnavailableReason = reason;
+        hw.listingUnavailableMessage = message;
+        return hw;
     }
-    /** Derive a child identity by purpose and index on the Heartwood device. */
+    /** Derive a child identity by purpose and index on the Heartwood device.
+     *  Does not depend on `heartwood_list_identities` -- works even when
+     *  `listingAvailable` is `false`. */
     async derive(purpose, index) {
-        const result = await this.signer.sendRequest('heartwood_derive', [purpose, String(index)]);
+        const result = await withApprovalHint(this.signer.sendRequest('heartwood_derive', [purpose, String(index)]), 'heartwood derive');
         return JSON.parse(result);
     }
-    /** Derive a named persona on the Heartwood device. */
+    /** Derive a named persona on the Heartwood device.
+     *  Does not depend on `heartwood_list_identities` -- works even when
+     *  `listingAvailable` is `false`. */
     async derivePersona(name, index) {
-        const result = await this.signer.sendRequest('heartwood_derive_persona', [name, String(index)]);
+        const result = await withApprovalHint(this.signer.sendRequest('heartwood_derive_persona', [name, String(index)]), 'heartwood derive persona');
         return JSON.parse(result);
     }
-    /** List all known identities on the Heartwood device. */
+    /** List all known identities on the Heartwood device.
+     *
+     * Throws immediately, without a device round trip, when `probe()` already
+     * established that listing isn't available for this pairing -- retrying
+     * would just re-hit the same denial or wait out the same timeout. */
     async listIdentities() {
-        const result = await this.signer.sendRequest('heartwood_list_identities', []);
+        if (!this.listingAvailable) {
+            throw new Error(this.listingUnavailableMessage ?? 'Heartwood identity listing is unavailable for this pairing.');
+        }
+        const result = await withApprovalHint(this.signer.sendRequest('heartwood_list_identities', []), 'heartwood list identities');
         return JSON.parse(result);
     }
-    /** Switch the active identity on the Heartwood device. */
+    /** Switch the active identity on the Heartwood device.
+     *  Does not depend on `heartwood_list_identities` -- works even when
+     *  `listingAvailable` is `false`. */
     async switch(purposeOrName, index) {
         const params = index !== undefined
             ? [purposeOrName, String(index)]
             : [purposeOrName];
-        const raw = await this.signer.sendRequest('heartwood_switch', params);
+        const raw = await withApprovalHint(this.signer.sendRequest('heartwood_switch', params), 'heartwood switch');
         // Parse response — device may return { npub } object or a bare npub string
         const { decode, npubEncode } = await import('nostr-tools/nip19');
         let npub;
@@ -80,13 +178,13 @@ export class HeartwoodContext extends BunkerContext {
     }
     /** Create a linkage proof on the Heartwood device. */
     async prove(mode = 'blind') {
-        const result = await this.signer.sendRequest('heartwood_create_proof', [this.activePublicKeyHex, mode]);
+        const result = await withApprovalHint(this.signer.sendRequest('heartwood_create_proof', [this.activePublicKeyHex, mode]), 'heartwood create proof');
         return JSON.parse(result);
     }
     /** Recover identities by scanning derived keys on the Heartwood device. */
     async recover(lookahead) {
         const params = lookahead !== undefined ? [String(lookahead)] : [];
-        const result = await this.signer.sendRequest('heartwood_recover', params);
+        const result = await withApprovalHint(this.signer.sendRequest('heartwood_recover', params), 'heartwood recover');
         return JSON.parse(result);
     }
 }

package/dist/http-token.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The bearer token the HTTP transport requires.
+ *
+ * A token the operator supplied in BRAY_HTTP_TOKEN is never echoed: they
+ * already have it, and stderr ends up in logs and process supervisors. A
+ * generated one is printed once, because nobody else can know it.
+ */
+export declare function resolveHttpToken(env?: NodeJS.ProcessEnv, log?: (message: string) => void): string;

package/dist/http-token.js

@@ -0,0 +1,18 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * The bearer token the HTTP transport requires.
+ *
+ * A token the operator supplied in BRAY_HTTP_TOKEN is never echoed: they
+ * already have it, and stderr ends up in logs and process supervisors. A
+ * generated one is printed once, because nobody else can know it.
+ */
+export function resolveHttpToken(env = process.env, log = (message) => console.error(message)) {
+    const supplied = env.BRAY_HTTP_TOKEN?.trim();
+    if (supplied) {
+        log('nostr-bray HTTP auth: using the token from BRAY_HTTP_TOKEN');
+        return supplied;
+    }
+    const generated = randomUUID();
+    log(`nostr-bray HTTP auth token: ${generated}`);
+    return generated;
+}

package/dist/identity/tools.d.ts

@@ -3,12 +3,15 @@ import type { SigningContext } from '../signing-context.js';
 import type { RelayPool } from '../relay-pool.js';
 import type { Nip65Manager } from '../nip65.js';
 import type { TrustContext } from '../trust-context.js';
+import type { NwcTransport } from '@forgesworn/nwc-kit';
 export interface ToolDeps {
     ctx: SigningContext;
     pool: RelayPool;
     nip65: Nip65Manager;
     nwcUri?: string;
     walletsFile: string;
+    /** NWC relay transport override. Tests only; production uses the default relays. */
+    nwcTransport?: NwcTransport;
     nip04Enabled?: boolean;
     veilCacheTtl?: number;
     veilCacheMax?: number;

package/dist/index.js

@@ -4,27 +4,11 @@ import { loadConfig } from './config.js';
 import { IdentityContext } from './context.js';
 import { RelayPool } from './relay-pool.js';
 import { Nip65Manager } from './nip65.js';
-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 { TrustContext } from './trust-context.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';
-import { ActionCatalog, createCatalogProxy } from './catalog.js';
+import { ActionCatalog, createCatalogProxy, PROMOTED_TOOLS } from './catalog.js';
+import { registerAllTools } from './tool-groups.js';
 import { configureHttpClient } from './http-client.js';
+import { BRAY_VERSION } from './version.js';
 const config = await loadConfig();
 // Route every fetch() in this process through the SOCKS proxy when Tor is
 // configured, before any HTTP-using code runs. Structural protection
@@ -79,8 +63,11 @@ async function establishBunkerInBackground(base) {
                 // Probe for Heartwood extensions and upgrade the prototype in place so
                 // tools that check `ctx instanceof HeartwoodContext` see it.
                 const hw = await HeartwoodContext.probe(base);
-                if (hw)
+                if (hw) {
                     console.error(`Heartwood extensions detected -- ${base.activeNpub}`);
+                    if (!hw.listingAvailable)
+                        console.error(hw.listingUnavailableMessage);
+                }
             }
             catch (e) {
                 console.error('Heartwood probe failed (non-fatal):', e.message);
@@ -132,58 +119,24 @@ config.nwcUri = undefined;
 config.bunkerUri = undefined;
 // NIP-65 relay list is loaded via loadIdentityRelays(): immediately for a local
 // key, or after the bunker pubkey resolves (see establishBunkerInBackground).
-const server = new McpServer({ name: 'nostr-bray', version: '0.1.0' }, {
+const server = new McpServer({ name: 'nostr-bray', version: BRAY_VERSION }, {
     instructions: 'Always check whoami before posting or signing. Use signet-badge to check trust before interacting with unfamiliar pubkeys. Use trust-score for the full three-dimensional view (verification + proximity + access). Use social-feed or social-notifications to get event IDs and author pubkeys before calling social-reply or social-react. DMs default to NIP-17 gift wrap (most private); only use NIP-04 if the recipient requires it. Respect vault tiers -- do not share decrypted content outside its intended audience. For less common actions, use search-actions to discover them, then execute-action to run them.',
 });
 // Promoted tools are registered directly with the server (always visible to Claude).
 // Everything else goes to the catalog, discoverable via search-actions + execute-action.
-const PROMOTED = new Set([
-    'whoami', 'social-post', 'social-reply', 'social-feed',
-    'dm-send', 'dm-read', 'zap-send', 'zap-balance',
-    'identity-switch', 'relay-query',
-    'signet-badge', 'trust-score', 'vault-read',
-    'dispatch-send', 'dispatch-check', 'dispatch-reply',
-    'dispatch-ack', 'dispatch-status', 'dispatch-cancel',
-    'dispatch-refuse', 'dispatch-failure', 'dispatch-query',
-    'article-publish', 'article-read', 'article-list',
-    'search-notes', 'search-profiles', 'hashtag-feed',
-    'social-profile-get', 'dm-conversation', 'verify-person',
-    'dispatch-propose', 'dispatch-capability-publish', 'dispatch-capability-discover', 'dispatch-capability-read',
-    'badge-create', 'badge-award', 'badge-accept', 'badge-list',
-    'community-create', 'community-feed', 'community-post', 'community-approve', 'community-list',
-    'calendar-create', 'calendar-read', 'calendar-rsvp',
-    'listing-create', 'listing-read', 'listing-search', 'listing-close',
-]);
 const catalog = new ActionCatalog();
-const proxy = createCatalogProxy(server, catalog, PROMOTED);
-// Register all tools — the proxy routes promoted to server, rest to catalog
-registerIdentityTools(proxy, deps);
-registerSocialTools(proxy, deps);
-registerTrustTools(proxy, deps);
-registerRelayTools(proxy, deps);
-registerRelayIntelligenceTools(proxy, deps);
-registerZapTools(proxy, deps);
-registerWalletServiceTools(proxy, deps);
-registerSafetyTools(proxy, deps);
-registerUtilTools(proxy, deps);
-registerWorkflowTools(proxy, {
-    ctx: deps.ctx,
-    pool: deps.pool,
-    nip65: deps.nip65,
+const proxy = createCatalogProxy(server, catalog, PROMOTED_TOOLS);
+// Register all tools. The proxy routes promoted ones to the server and the
+// rest to the catalog.
+registerAllTools(proxy, deps, {
     veilCacheTtl: config.veilCacheTtl,
     veilCacheMax: config.veilCacheMax,
+    ...(config.dispatchIdentities ? { dispatchIdentitiesPath: config.dispatchIdentities } : {}),
+    walletService: config.walletService,
 });
-registerMarketplaceTools(proxy, deps);
-registerPrivacyTools(proxy, deps);
-registerModerationTools(proxy, deps);
-registerSignetTools(proxy, deps);
-registerVaultTools(proxy, deps);
-registerDispatchTools(proxy, { ...deps, dispatchIdentitiesPath: config.dispatchIdentities });
-registerHandlerTools(proxy, deps);
-registerSyncTools(proxy, deps);
 // Add search-actions and execute-action meta-tools to the real server
 catalog.registerMetaTools(server);
-console.error(`nostr-bray: ${PROMOTED.size} promoted tools + ${catalog.size} cataloged (${PROMOTED.size + catalog.size + 2} total)`);
+console.error(`nostr-bray: ${catalog.promotedCount} promoted tools + ${catalog.size} cataloged (${catalog.promotedCount + catalog.size + 2} total)`);
 if (config.transport === 'stdio') {
     const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
     await server.connect(new StdioServerTransport());
@@ -194,8 +147,8 @@ else {
     const { StreamableHTTPServerTransport } = await import('@modelcontextprotocol/sdk/server/streamableHttp.js');
     const { isInitializeRequest } = await import('@modelcontextprotocol/sdk/types.js');
     const { randomUUID, timingSafeEqual } = await import('node:crypto');
-    const token = process.env.BRAY_HTTP_TOKEN ?? randomUUID();
-    console.error(`nostr-bray HTTP auth token: ${token}`);
+    const { resolveHttpToken } = await import('./http-token.js');
+    const token = resolveHttpToken();
     const expectedAuth = Buffer.from(`Bearer ${token}`);
     // Sliding window rate limiter (per-IP).
     // Cap the map size so a caller rotating source IPs cannot grow it without

package/dist/marketplace/handlers.d.ts

@@ -133,11 +133,15 @@ export interface PayResult {
     credentialId: string;
     costSats?: number;
 }
-export declare function storeCredential(id: string, macaroon: string, preimage: string): void;
-export declare function getCredential(id: string): {
+interface StoredCredential {
     macaroon: string;
     preimage: string;
-} | undefined;
+    origin: string;
+}
+/** The origin a credential is bound to, normalised as `URL.origin`. */
+export declare function credentialOrigin(url: string): string;
+export declare function storeCredential(id: string, macaroon: string, preimage: string, url: string): void;
+export declare function getCredential(id: string): StoredCredential | undefined;
 export declare function clearCredentials(): void;
 /** Build the L402 Authorization header from stored credentials. */
 export declare function buildL402AuthHeader(credentialId: string): string | null;
@@ -194,3 +198,4 @@ export declare function handleMarketplaceRetire(ctx: SigningContext, pool: Relay
     event: NostrEvent;
     publish: PublishResult;
 }>;
+export {};

package/dist/marketplace/handlers.js

@@ -310,10 +310,23 @@ export function extractBolt11AmountSats(bolt11) {
     }
     return undefined;
 }
-// In-memory credential store for L402 tokens (per-session, not persisted)
 const credentialStore = new Map();
-export function storeCredential(id, macaroon, preimage) {
-    credentialStore.set(id, { macaroon, preimage });
+/** The origin a credential is bound to, normalised as `URL.origin`. */
+export function credentialOrigin(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error('The URL the L402 challenge came from is not a valid URL.');
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw new Error('L402 credentials can only be bound to an http(s) origin.');
+    }
+    return parsed.origin;
+}
+export function storeCredential(id, macaroon, preimage, url) {
+    credentialStore.set(id, { macaroon, preimage, origin: credentialOrigin(url) });
 }
 export function getCredential(id) {
     return credentialStore.get(id);
@@ -331,10 +344,14 @@ export function buildL402AuthHeader(credentialId) {
 /** Make an authenticated API call using L402 credentials. */
 export async function handleMarketplaceCall(args) {
     validatePublicUrl(args.url);
+    const credential = credentialStore.get(args.credentialId);
     const authHeader = buildL402AuthHeader(args.credentialId);
-    if (!authHeader) {
+    if (!credential || !authHeader) {
         throw new Error(`No credentials found for ID "${args.credentialId}". Use marketplace-pay first.`);
     }
+    if (credentialOrigin(args.url) !== credential.origin) {
+        throw new Error(`That credential was paid for ${credential.origin} and is only sent there; refusing to send it to ${credentialOrigin(args.url)}.`);
+    }
     const headers = {
         ...args.headers,
         Authorization: authHeader,

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;