nostr-bray 3.2.2 → 3.4.0

package/README.md

@@ -1,6 +1,6 @@
 # nostr-bray
 
-**Trust-aware Nostr MCP for AI and humans.** 253 tools across 28 groups. Model-agnostic. Works with Claude, ChatGPT, Gemini, Cursor, Windsurf, or any MCP client.
+**Trust-aware Nostr MCP for AI and humans.** 258 tools across 29 groups. Model-agnostic. Works with Claude, ChatGPT, Gemini, Cursor, Windsurf, or any MCP client.
 
 [![npm](https://img.shields.io/npm/v/nostr-bray)](https://www.npmjs.com/package/nostr-bray)
 [![CI](https://github.com/forgesworn/bray/actions/workflows/ci.yml/badge.svg)](https://github.com/forgesworn/bray/actions/workflows/ci.yml)
@@ -85,6 +85,7 @@ For production use, prefer [Heartwood](https://github.com/forgesworn/heartwood)
 | **Blossom** | 10 | `blossom-upload`, `blossom-mirror`, `blossom-verify`, `blossom-repair` |
 | **Privacy** | 10 | `privacy-commit`, `privacy-prove-range`, `privacy-prove-age`, `privacy-publish-proof` |
 | **Zap** | 9 | `zap-send`, `zap-balance`, `zap-make-invoice`, `zap-decode` |
+| **Wallet service** | 5 | `wallet-grant`, `wallet-grants`, `wallet-revoke`, `wallet-refill`, `wallet-serve` |
 | **Vault** | 9 | `vault-create`, `vault-encrypt`, `vault-share`, `vault-rotate` |
 | **Workflow** | 7 | `trust-score`, `verify-person`, `identity-setup`, `relay-health`, `feed-discover` |
 | **Signet** | 7 | `signet-badge`, `signet-vouch`, `signet-credentials`, `signet-challenge` |
@@ -214,6 +215,7 @@ Search order: `BRAY_CONFIG` env var > `$XDG_CONFIG_HOME/bray/config.json` > `~/.
 | `NOSTR_NCRYPTSEC_PASSWORD` | Password for ncryptsec |
 | `NWC_URI_FILE` | Path to a private `0600` file containing the NWC bearer URI |
 | `NOSTR_RELAYS` | Comma-separated relay URLs |
+| `NOSTR_FORBID_PUBKEY` | Comma-separated npubs or hex this process must never sign as. See below. |
 | `TOR_PROXY` | SOCKS5h proxy for Tor |
 | `NIP04_ENABLED` | Set `1` to enable legacy NIP-04 DMs |
 | `TRANSPORT` | `stdio` (default) or `http` |
@@ -224,6 +226,78 @@ Raw `NWC_URI` is refused; use `NWC_URI_FILE` or `wallet connect <nwc-file>` so
 the bearer credential never appears in a process environment, command argument
 or MCP tool argument.
 
+### Keys this process must never be
+
+An agent that comes up holding the wrong key is indistinguishable from one
+working correctly. Every signature verifies, every tool succeeds, and the
+only symptom is that `whoami` quietly answers with somebody else's npub —
+which the driving model has no reason to doubt, because it is its own tool
+telling it.
+
+The worst version is a **principal's** key: a person's own. An agent signing
+as its principal can attest that it belongs to itself, and approve its own
+requests, because it *is* the principal those checks look for.
+
+```bash
+NOSTR_FORBID_PUBKEY=npub1yourownkey...,npub1anotherhuman...
+```
+
+or `forbidPubkeys` in the config file. Either takes npubs or hex. Activating
+one of those keys throws instead — at startup, on `identity-switch`, and on
+`bunker --persona` alike, because the check sits at the moment an identity
+becomes active rather than at any one entry point. An entry that cannot be
+parsed is an error too: a list nobody can read must not silently permit
+everything.
+
+The active npub is printed on stderr on every start, so the answer to "which
+key is this?" does not depend on asking the agent.
+
+## Handing out a wallet connection
+
+`zap-send` spends through the NWC URI you configured. That URI is an
+unbounded capability over the wallet behind it: every method it supports, no
+ceiling, until it is rotated. Handing one to an agent hands over everything.
+
+`wallet-grant` issues connections over the same wallet that are narrower.
+
+```
+wallet-grant   { name: "research-agent", methods: ["get_info","pay_invoice"],
+                 budgetMsat: 50000, maxPaymentMsat: 5000 }
+wallet-grants  # what exists, what it may do, what it has spent
+wallet-revoke  { nameOrId: "research-agent" }
+wallet-refill  { nameOrId: "research-agent", budgetMsat: 50000 }
+wallet-serve   { action: "start" }
+```
+
+What a connection may do is an allowlist, and the default grants no spending
+and does not disclose the balance: `get_info`, `make_invoice`,
+`lookup_invoice`. Both of the others are opt-in per connection, and **a
+connection that can spend must carry a budget** - there is no unlimited grant
+to issue by accident.
+
+The rules exist because a payment cannot be recalled:
+
+- A request is answered **once**. Its id is persisted *before* the payment is
+  attempted, so a process that dies mid-payment comes back knowing not to try
+  again - a relay will hand the same signed request over twice.
+- Requests on one connection are **serialised**, so two arriving together
+  cannot both read the same remaining budget.
+- A request older than five minutes is not answered, whatever its own
+  `expiration` tag claims.
+- Each connection has **its own service key**: two grants share nothing a
+  relay can correlate, and revoking one is deleting a key.
+- The budget is charged what the **invoice** says, decoded here. A budget
+  checked against a figure the payer supplied is not a budget.
+- A claimed payment whose preimage does not settle the invoice is refused
+  rather than passed on. Repeating an unproven claim would make this service
+  the one telling the lie.
+
+Grants live in `wallet-grants.json` (0600, per identity), and they are
+answered **only while `wallet-serve` is running** - which is to say, only for
+as long as this process is alive. That is worth telling whoever you hand a URI
+to: a connection that works while an MCP session is open is a different
+promise from one that works overnight.
+
 ## CLI
 
 ```bash

package/dist/cli/index.js

@@ -384,7 +384,7 @@ if (config.bunkerUri) {
     console.error(`Connected to ${hw ? 'Heartwood' : 'bunker'} — signing as ${ctx.activeNpub}`);
 }
 else {
-    ctx = new IdentityContext(config.secretKey, config.secretFormat);
+    ctx = new IdentityContext(config.secretKey, config.secretFormat, { forbidPubkeys: config.forbidPubkeys });
 }
 // NIP-42: the pool answers AUTH challenges with the active identity's key.
 pool.setAuthSigner(async (evt) => ctx.getSigningFunction()(evt));

package/dist/config.d.ts

@@ -36,6 +36,8 @@ interface ConfigFile {
     trustCacheTtl?: number;
     trustCacheMax?: number;
     dispatchIdentities?: string;
+    /** Public keys this process must never sign as. See ContextOptions. */
+    forbidPubkeys?: string[];
 }
 /**
  * Load config from a JSON file. Searches in order:

package/dist/config.js

@@ -283,6 +283,14 @@ export async function loadConfig() {
         : 'weekly';
     // --- Dispatch identities file ---
     const dispatchIdentities = process.env.DISPATCH_IDENTITIES ?? file.dispatchIdentities ?? undefined;
+    // Comma-separated npubs or hex. A list nobody can parse is rejected at
+    // startup by resolvePubkeyRef rather than silently permitting everything.
+    const forbidPubkeys = [
+        ...(process.env.NOSTR_FORBID_PUBKEY ?? '').split(','),
+        ...(file.forbidPubkeys ?? []),
+    ]
+        .map((s) => s.trim())
+        .filter(Boolean);
     // --- Wallets file ---
     const walletsFile = process.env.BRAY_WALLETS_FILE
         ?? file.walletsFile
@@ -309,5 +317,6 @@ export async function loadConfig() {
         port,
         bindAddress,
         dispatchIdentities,
+        forbidPubkeys,
     };
 }

package/dist/context.d.ts

@@ -3,14 +3,41 @@ import type { PublicIdentity, SignFn } from './types.js';
 import type { ExtendedSigningContext } from './signing-context.js';
 export interface ContextOptions {
     maxCache?: number;
+    /** Public keys this process must never sign as, hex or npub.
+     *
+     *  For PRINCIPALS - a person's own key. An agent that comes up holding one
+     *  is indistinguishable from one working correctly: every signature
+     *  verifies, every tool succeeds, and the only symptom is that `whoami`
+     *  quietly answers with a human's npub. Listing them here turns that into
+     *  a refusal at the moment of activation, which covers startup, an
+     *  `identity-switch`, and `bunker --persona` alike. */
+    forbidPubkeys?: string[];
 }
+/** An npub or 64-hex pubkey as lowercase hex. Throws on anything else, so a
+ *  forbidden entry nobody can parse fails loudly rather than silently
+ *  permitting everything. */
+export declare function resolvePubkeyRef(ref: string): string;
 export declare class IdentityContext implements ExtendedSigningContext {
     private root;
     private cache;
     private masterEntry;
     private activeEntry;
     private maxCacheSize;
+    private forbidden;
     constructor(secretKey: string, format: 'nsec' | 'hex' | 'mnemonic', opts?: ContextOptions);
+    /**
+     * Make an identity the active one, refusing a forbidden key.
+     *
+     * Every assignment to `activeEntry` goes through here - the constructor,
+     * `use()`, `switch()` and the persona paths - so there is no route to
+     * signing as a forbidden key, and no new route can be added by accident.
+     *
+     * Throws rather than falling back to the master identity. A process asked
+     * to be a key it must not be has been misconfigured, and quietly running
+     * as something else is how the misconfiguration survives to do damage.
+     * Only the npub is in the message; it is public, and nothing else is.
+     */
+    private activate;
     /** Current active identity's npub (bech32) */
     get activeNpub(): string;
     /** Derivation path of the current active identity, for reporting to a human */

package/dist/context.js

@@ -2,6 +2,7 @@ import { fromNsec, fromMnemonic, derive, zeroise } from 'nsec-tree';
 import { createBlindProof, createFullProof } from 'nsec-tree/proof';
 import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
 import { decode, npubEncode, nsecEncode } from 'nostr-tools/nip19';
+import { decode as decodeNip19 } from 'nostr-tools/nip19';
 /** Build an Identity-compatible object from raw key bytes */
 function rawIdentity(privateKey) {
     const publicKeyHex = getPublicKey(privateKey);
@@ -15,14 +16,45 @@ function rawIdentity(privateKey) {
         index: 0,
     };
 }
+/** An npub or 64-hex pubkey as lowercase hex. Throws on anything else, so a
+ *  forbidden entry nobody can parse fails loudly rather than silently
+ *  permitting everything. */
+export function resolvePubkeyRef(ref) {
+    const trimmed = ref.trim();
+    if (!trimmed)
+        throw new Error('forbidPubkeys entry is empty');
+    if (/^[0-9a-fA-F]{64}$/.test(trimmed))
+        return trimmed.toLowerCase();
+    if (trimmed.toLowerCase().startsWith('nsec1')) {
+        throw new Error('forbidPubkeys wants a PUBLIC key; that is an nsec. Treat it as exposed.');
+    }
+    try {
+        const decoded = decodeNip19(trimmed);
+        if (decoded.type === 'npub')
+            return decoded.data;
+        throw new Error(`forbidPubkeys entry "${trimmed}" is a ${decoded.type}, not an npub`);
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith('forbidPubkeys'))
+            throw err;
+        throw new Error(`forbidPubkeys entry "${trimmed}" is neither an npub nor 64 hex characters`);
+    }
+}
 export class IdentityContext {
     root;
     cache = new Map();
     masterEntry;
+    // Definite-assignment asserted: every branch of the constructor assigns it
+    // through activate(), and TypeScript does not track assignments made
+    // inside a called method.
     activeEntry;
     maxCacheSize;
+    forbidden;
     constructor(secretKey, format, opts) {
         this.maxCacheSize = opts?.maxCache ?? 5;
+        // Built before anything is activated, so the constructor's own
+        // activation is checked too.
+        this.forbidden = new Set((opts?.forbidPubkeys ?? []).map(resolvePubkeyRef));
         // Parse the raw secret key bytes — this IS the user's actual Nostr identity
         let rawKeyBytes;
         if (format === 'mnemonic') {
@@ -30,7 +62,7 @@ export class IdentityContext {
             this.root = fromMnemonic(secretKey);
             const derived = derive(this.root, 'master', 0);
             this.masterEntry = { identity: derived, purpose: 'master', index: 0, lastUsed: Date.now() };
-            this.activeEntry = this.masterEntry;
+            this.activate(this.masterEntry);
             return;
         }
         else if (format === 'hex') {
@@ -47,10 +79,32 @@ export class IdentityContext {
             index: 0,
             lastUsed: Date.now(),
         };
-        this.activeEntry = this.masterEntry;
+        this.activate(this.masterEntry);
         // nsec-tree root for child derivation
         this.root = fromNsec(rawKeyBytes);
     }
+    /**
+     * Make an identity the active one, refusing a forbidden key.
+     *
+     * Every assignment to `activeEntry` goes through here - the constructor,
+     * `use()`, `switch()` and the persona paths - so there is no route to
+     * signing as a forbidden key, and no new route can be added by accident.
+     *
+     * Throws rather than falling back to the master identity. A process asked
+     * to be a key it must not be has been misconfigured, and quietly running
+     * as something else is how the misconfiguration survives to do damage.
+     * Only the npub is in the message; it is public, and nothing else is.
+     */
+    activate(entry) {
+        const hex = Buffer.from(entry.identity.publicKey).toString('hex');
+        if (this.forbidden.has(hex)) {
+            throw new Error(`Refusing to activate ${entry.identity.npub}: it is on this process's forbidden list. ` +
+                'That list is for principals - a person\'s key, never an agent\'s. An agent signing as its ' +
+                'principal can attest that it belongs to itself and approve its own requests, because it is ' +
+                'the principal those checks look for. Point NOSTR_SECRET_KEY at the agent\'s own key.');
+        }
+        this.activeEntry = entry;
+    }
     /** Current active identity's npub (bech32) */
     get activeNpub() {
         return this.activeEntry.identity.npub;
@@ -90,14 +144,14 @@ export class IdentityContext {
         for (const [, entry] of this.cache) {
             if (entry.purpose === purpose && entry.index === index && !entry.personaName) {
                 entry.lastUsed = Date.now();
-                this.activeEntry = entry;
+                this.activate(entry);
                 return;
             }
         }
         const identity = derive(this.root, purpose, index);
         const entry = { identity, purpose, index, lastUsed: Date.now() };
         this.putCache(identity.npub, entry);
-        this.activeEntry = entry;
+        this.activate(entry);
     }
     /** Derive a named persona */
     async derivePersona(name, index) {
@@ -123,7 +177,7 @@ export class IdentityContext {
     /** Switch active identity by purpose+index, persona name, or "master" */
     async switch(purposeOrName, index) {
         if (purposeOrName === 'master') {
-            this.activeEntry = this.masterEntry;
+            this.activate(this.masterEntry);
             this.masterEntry.lastUsed = Date.now();
             return;
         }
@@ -133,7 +187,7 @@ export class IdentityContext {
             const matchesPersona = entry.personaName === purposeOrName && (index === undefined || entry.index === index);
             if (matchesPurpose || matchesPersona) {
                 entry.lastUsed = Date.now();
-                this.activeEntry = entry;
+                this.activate(entry);
                 return;
             }
         }
@@ -160,7 +214,7 @@ export class IdentityContext {
             lastUsed: Date.now(),
         };
         this.putCache(identity.npub, entry);
-        this.activeEntry = entry;
+        this.activate(entry);
     }
     /** Get a signing function bound to the current active identity */
     getSigningFunction() {

package/dist/index.js

@@ -10,6 +10,7 @@ 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';
@@ -103,7 +104,12 @@ if (config.bunkerUri) {
     void establishBunkerInBackground(base);
 }
 else {
-    ctx = new IdentityContext(config.secretKey, config.secretFormat);
+    ctx = new IdentityContext(config.secretKey, config.secretFormat, { forbidPubkeys: config.forbidPubkeys });
+    // Said out loud, on stderr, every start. The alternative is asking the
+    // agent which identity it holds, and an agent whose key is wrong will
+    // answer that confidently and wrongly - it has no reason to doubt its
+    // own tools. stdout is reserved for JSON-RPC.
+    console.error(`Signing as ${ctx.activeNpub}`);
     // Local key is ready immediately -- load its relay list now.
     loadIdentityRelays(ctx.activeNpub);
 }
@@ -157,6 +163,7 @@ registerTrustTools(proxy, deps);
 registerRelayTools(proxy, deps);
 registerRelayIntelligenceTools(proxy, deps);
 registerZapTools(proxy, deps);
+registerWalletServiceTools(proxy, deps);
 registerSafetyTools(proxy, deps);
 registerUtilTools(proxy, deps);
 registerWorkflowTools(proxy, {

package/dist/types.d.ts

@@ -61,6 +61,11 @@ export interface BrayConfig {
     readonly port: number;
     readonly bindAddress: string;
     readonly dispatchIdentities?: string;
+    /** Public keys this process must never sign as, hex or npub. For
+     *  principals: an agent holding one can attest that it belongs to itself
+     *  and approve its own requests. Enforced in IdentityContext, at the
+     *  moment an identity is activated. */
+    readonly forbidPubkeys?: string[];
 }
 export type { SigningContext, ExtendedSigningContext } from './signing-context.js';
 export { hasExtendedIdentity } from './signing-context.js';

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

@@ -0,0 +1,8 @@
+import type { Grant } 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[];
+export declare function saveGrants(path: string, pubkeyHex: string, grants: Grant[]): void;

package/dist/wallet-service/grants.js

@@ -0,0 +1,56 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+// 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.
+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) {
+    if (!existsSync(path))
+        return [];
+    const raw = readFileSync(path, 'utf8');
+    if (raw.length > MAX_FILE_BYTES)
+        throw new Error('The grants file is implausibly large; refusing to read it.');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    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];
+    return Array.isArray(held) ? held : [];
+}
+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)) {
+        try {
+            const parsed = JSON.parse(readFileSync(path, 'utf8'));
+            if (parsed?.version === 1 && typeof parsed.grants === 'object')
+                file = parsed;
+        }
+        catch {
+            // an unreadable file is replaced rather than appended to; the
+            // alternative is refusing to ever write again
+        }
+    }
+    file.grants[pubkeyHex] = grants;
+    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);
+}

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

@@ -0,0 +1,98 @@
+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 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 {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare class PaymentNotSentError extends ServiceError {
+    constructor(message: string);
+}
+export interface ServiceInvoice {
+    type: 'incoming' | 'outgoing';
+    invoice: string;
+    paymentHash: string;
+    amountMsat: number;
+    feesPaidMsat?: number;
+    preimage?: string;
+    description?: string;
+    settledAt?: number;
+    createdAt: number;
+    expiresAt?: number;
+}
+export interface ServiceWallet {
+    alias(): string;
+    balanceMsat(): Promise<number>;
+    makeInvoice(request: {
+        amountMsat: number;
+        description?: string;
+    }): Promise<ServiceInvoice>;
+    payInvoice(request: {
+        invoice: string;
+        amountMsat: number;
+    }): Promise<{
+        preimage: string;
+        feesPaidMsat: number;
+    }>;
+    lookupInvoice(query: {
+        paymentHash?: string;
+        invoice?: string;
+    }): Promise<ServiceInvoice | null>;
+}
+export interface ServiceTransport {
+    subscribe(relays: string[], filter: Filter, onEvent: (event: NostrEvent) => void): Promise<() => void>;
+    publish(relays: string[], event: NostrEvent): Promise<void>;
+}
+export interface Grant {
+    id: string;
+    name: string;
+    serviceSecretHex: string;
+    servicePubkey: string;
+    clientSecretHex: string;
+    clientPubkey: string;
+    relays: string[];
+    methods: string[];
+    budgetMsat?: number;
+    spentMsat: number;
+    maxPaymentMsat?: number;
+    seen?: string[];
+    createdAt: number;
+    lastUsedAt?: number;
+    revokedAt?: number;
+}
+export declare function grantUri(grant: Grant): string;
+export declare function spends(methods: string[]): boolean;
+export declare function validateGrant(input: {
+    methods: string[];
+    relays: string[];
+    budgetMsat?: number;
+    maxPaymentMsat?: number;
+}): void;
+export declare function remainingBudgetMsat(grant: Grant): number;
+export declare function newGrant(input: {
+    name: string;
+    relays: string[];
+    methods?: string[];
+    budgetMsat?: number;
+    maxPaymentMsat?: number;
+}): Grant;
+export declare function infoEvent(grant: Grant): NostrEvent;
+export interface ServiceOptions {
+    wallet: ServiceWallet;
+    transport: ServiceTransport;
+    persist: () => Promise<void>;
+    log?: (message: string) => void;
+    now?: () => number;
+}
+export declare class WalletService {
+    #private;
+    constructor(opts: ServiceOptions);
+    serving(): string[];
+    serve(grant: Grant): Promise<void>;
+    stop(grantId: string): void;
+    close(): void;
+}

package/dist/wallet-service/service.js

@@ -0,0 +1,365 @@
+import { finalizeEvent, getPublicKey, verifyEvent, nip44 } from 'nostr-tools';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
+import { tryDecodeBolt11 } from 'farrier-kit';
+// 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
+// the operator configured. This is the other direction. bray answers NIP-47
+// on behalf of that wallet, and what it adds is the thing the wallet itself
+// does not have: a connection you can hand to an agent that is narrower
+// than the one you hold.
+//
+// That is the whole point. An NWC URI is an unbounded capability over a
+// node - hand it to an agent and it can spend everything, forever, by any
+// method the wallet supports. What is handed out here is scoped:
+//
+//   - the method list is an allowlist, defaulting to no spending and no
+//     balance disclosure. Both are opt-in, per connection.
+//   - a connection that may spend MUST carry a budget. There is no
+//     unlimited grant to issue by accident.
+//   - a request that arrives twice is answered once. A relay will hand the
+//     same signed request over again, and a replayed pay_invoice is a
+//     second payment.
+//   - requests on one connection are serialised, so two arriving together
+//     cannot both read the same remaining budget.
+//
+// The same runtime, and the same rules, front a bearer-note wallet in
+// forgesworn/notecase (src/nwcservice.ts). It is deliberately written
+// against a `ServiceWallet` interface rather than against either wallet.
+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'];
+export const SUPPORTED_METHODS = [
+    'get_info',
+    'get_balance',
+    'make_invoice',
+    'lookup_invoice',
+    'pay_invoice',
+];
+export const SPENDING_METHODS = ['pay_invoice'];
+// A request older than this is not answered. NIP-47 requests carry their
+// own `expiration`, but that is the sender's word for it: a relay replaying
+// a week-old event must not be able to spend, whatever the event claims
+// about itself.
+const MAX_REQUEST_AGE_SECS = 300;
+const MAX_REQUEST_FUTURE_SECS = 60;
+const SEEN_LIMIT = 256;
+export class ServiceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+// Thrown by a wallet that refused BEFORE anything could leave: a bad
+// invoice, an expired one, not enough balance. The only failure that gives
+// the budget back, because it is the only one where nothing went out.
+export class PaymentNotSentError extends ServiceError {
+    constructor(message) {
+        super('PAYMENT_FAILED', message);
+    }
+}
+export function grantUri(grant) {
+    const relays = grant.relays.map((relay) => `relay=${encodeURIComponent(relay)}`).join('&');
+    return `nostr+walletconnect://${grant.servicePubkey}?${relays}&secret=${grant.clientSecretHex}`;
+}
+export function spends(methods) {
+    return methods.some((method) => SPENDING_METHODS.includes(method));
+}
+export function validateGrant(input) {
+    if (input.relays.length === 0)
+        throw new ServiceError('OTHER', 'A connection needs at least one relay.');
+    if (input.methods.length === 0)
+        throw new ServiceError('OTHER', 'A connection needs at least one method.');
+    for (const method of input.methods) {
+        if (!SUPPORTED_METHODS.includes(method)) {
+            throw new ServiceError('NOT_IMPLEMENTED', `This service cannot answer ${method}.`);
+        }
+    }
+    if (spends(input.methods)) {
+        if (input.budgetMsat === undefined) {
+            throw new ServiceError('OTHER', 'A connection that can spend needs a budget - there is no unlimited grant.');
+        }
+        if (!Number.isSafeInteger(input.budgetMsat) || input.budgetMsat <= 0) {
+            throw new ServiceError('OTHER', 'The budget must be a positive integer of milli-satoshis.');
+        }
+    }
+    else if (input.budgetMsat !== undefined) {
+        throw new ServiceError('OTHER', 'A budget means nothing on a connection that cannot spend.');
+    }
+    if (input.maxPaymentMsat !== undefined) {
+        if (!Number.isSafeInteger(input.maxPaymentMsat) || input.maxPaymentMsat <= 0) {
+            throw new ServiceError('OTHER', 'The per-payment ceiling must be a positive integer of milli-satoshis.');
+        }
+        if (input.budgetMsat !== undefined && input.maxPaymentMsat > input.budgetMsat) {
+            throw new ServiceError('OTHER', 'The per-payment ceiling is above the whole budget.');
+        }
+    }
+}
+export function remainingBudgetMsat(grant) {
+    return grant.budgetMsat === undefined ? 0 : Math.max(0, grant.budgetMsat - grant.spentMsat);
+}
+export function newGrant(input) {
+    const methods = input.methods ?? [...DEFAULT_METHODS];
+    validateGrant({ methods, relays: input.relays, ...(input.budgetMsat === undefined ? {} : { budgetMsat: input.budgetMsat }), ...(input.maxPaymentMsat === undefined ? {} : { maxPaymentMsat: input.maxPaymentMsat }) });
+    const serviceSecretHex = bytesToHex(randomSecret());
+    const clientSecretHex = bytesToHex(randomSecret());
+    return {
+        id: bytesToHex(randomSecret()).slice(0, 16),
+        name: input.name,
+        serviceSecretHex,
+        servicePubkey: getPublicKey(hexToBytes(serviceSecretHex)),
+        clientSecretHex,
+        clientPubkey: getPublicKey(hexToBytes(clientSecretHex)),
+        relays: [...new Set(input.relays)],
+        methods,
+        spentMsat: 0,
+        ...(input.budgetMsat === undefined ? {} : { budgetMsat: input.budgetMsat }),
+        ...(input.maxPaymentMsat === undefined ? {} : { maxPaymentMsat: input.maxPaymentMsat }),
+        createdAt: Date.now(),
+    };
+}
+function randomSecret() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return bytes;
+}
+function conversationKey(grant) {
+    return nip44.getConversationKey(hexToBytes(grant.serviceSecretHex), grant.clientPubkey);
+}
+export function infoEvent(grant) {
+    return finalizeEvent({
+        kind: NWC_INFO_KIND,
+        created_at: Math.floor(Date.now() / 1000),
+        tags: [['encryption', 'nip44_v2']],
+        content: grant.methods.join(' '),
+    }, hexToBytes(grant.serviceSecretHex));
+}
+function responseEvent(grant, request, answer) {
+    return finalizeEvent({
+        kind: NWC_RESPONSE_KIND,
+        created_at: Math.floor(Date.now() / 1000),
+        tags: [
+            ['p', request.pubkey],
+            ['e', request.id],
+            ['encryption', 'nip44_v2'],
+        ],
+        content: nip44.encrypt(JSON.stringify(answer), conversationKey(grant)),
+    }, hexToBytes(grant.serviceSecretHex));
+}
+function invoiceResult(view) {
+    return {
+        type: view.type,
+        invoice: view.invoice,
+        payment_hash: view.paymentHash,
+        amount: view.amountMsat,
+        created_at: view.createdAt,
+        ...(view.description === undefined ? {} : { description: view.description }),
+        ...(view.expiresAt === undefined ? {} : { expires_at: view.expiresAt }),
+        ...(view.settledAt === undefined ? {} : { settled_at: view.settledAt }),
+        ...(view.preimage === undefined ? {} : { preimage: view.preimage }),
+        ...(view.feesPaidMsat === undefined ? {} : { fees_paid: view.feesPaidMsat }),
+    };
+}
+export class WalletService {
+    #opts;
+    #now;
+    #stops = new Map();
+    #queues = new Map();
+    #grants = new Map();
+    constructor(opts) {
+        this.#opts = opts;
+        this.#now = opts.now ?? (() => Date.now());
+    }
+    serving() {
+        return [...this.#stops.keys()];
+    }
+    async serve(grant) {
+        if (grant.revokedAt)
+            return;
+        this.stop(grant.id);
+        this.#grants.set(grant.id, grant);
+        await this.#opts.transport.publish(grant.relays, infoEvent(grant));
+        const since = Math.floor(this.#now() / 1000) - MAX_REQUEST_AGE_SECS;
+        const stop = await this.#opts.transport.subscribe(grant.relays, { kinds: [NWC_REQUEST_KIND], '#p': [grant.servicePubkey], since }, (event) => this.#enqueue(grant.id, event));
+        this.#stops.set(grant.id, stop);
+        this.#opts.log?.(`serving ${grant.name} on ${grant.relays.join(', ')}`);
+    }
+    stop(grantId) {
+        this.#stops.get(grantId)?.();
+        this.#stops.delete(grantId);
+        this.#grants.delete(grantId);
+    }
+    close() {
+        for (const id of [...this.#stops.keys()])
+            this.stop(id);
+    }
+    // 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.
+    #enqueue(grantId, event) {
+        const previous = this.#queues.get(grantId) ?? Promise.resolve();
+        this.#queues.set(grantId, previous
+            .then(() => this.#handle(grantId, event))
+            .catch((err) => this.#opts.log?.(`request failed: ${err.message}`)));
+    }
+    async #handle(grantId, event) {
+        const grant = this.#grants.get(grantId);
+        if (!grant || grant.revokedAt)
+            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,
+        // so NIP-44 cannot open anything anyone else sealed. This is the cheap
+        // rejection of noise before the expensive one.
+        if (event.pubkey !== grant.clientPubkey)
+            return;
+        if (!verifyEvent(event))
+            return;
+        const seconds = Math.floor(this.#now() / 1000);
+        if (event.created_at < seconds - MAX_REQUEST_AGE_SECS)
+            return;
+        if (event.created_at > seconds + MAX_REQUEST_FUTURE_SECS)
+            return;
+        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)) {
+            this.#opts.log?.(`ignored a replayed request on ${grant.name}`);
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(nip44.decrypt(event.content, conversationKey(grant)));
+        }
+        catch {
+            this.#opts.log?.(`could not read a request on ${grant.name}`);
+            return;
+        }
+        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();
+        };
+        // 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
+        // that might be paid twice.
+        const spending = SPENDING_METHODS.includes(method);
+        if (spending)
+            await remember();
+        let answer;
+        try {
+            if (!grant.methods.includes(method)) {
+                throw new ServiceError('RESTRICTED', SUPPORTED_METHODS.includes(method)
+                    ? `This connection may not ${method}.`
+                    : `This service cannot answer ${method}.`);
+            }
+            answer = { result_type: method, result: await this.#dispatch(grant, method, params) };
+        }
+        catch (err) {
+            const code = err instanceof ServiceError ? err.code : 'INTERNAL';
+            const message = err.message || 'The wallet could not answer that.';
+            answer = { result_type: method, error: { code, message } };
+            this.#opts.log?.(`refused ${method || 'an unnamed method'} on ${grant.name}: ${message}`);
+        }
+        if (!spending)
+            await remember();
+        await this.#opts.transport.publish(grant.relays, responseEvent(grant, event, answer));
+    }
+    async #dispatch(grant, method, params) {
+        const wallet = this.#opts.wallet;
+        switch (method) {
+            case 'get_info':
+                return { alias: wallet.alias(), network: 'mainnet', methods: grant.methods, notifications: [] };
+            case 'get_balance':
+                return { balance: await wallet.balanceMsat() };
+            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 }) }));
+            }
+            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) {
+                    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.');
+                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();
+                try {
+                    const paid = await this.#opts.wallet.payInvoice({ invoice, amountMsat });
+                    return { preimage: paid.preimage, fees_paid: paid.feesPaidMsat };
+                }
+                catch (err) {
+                    if (err instanceof PaymentNotSentError) {
+                        grant.spentMsat -= amountMsat;
+                        await this.#opts.persist();
+                    }
+                    throw err;
+                }
+            }
+            default:
+                throw new ServiceError('NOT_IMPLEMENTED', `This service cannot answer ${method}.`);
+        }
+    }
+}
+// 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 priceOf(invoice, params) {
+    const decoded = tryDecodeBolt11(invoice);
+    if (!decoded)
+        throw new PaymentNotSentError('That is not a decodable BOLT-11 invoice.');
+    const asked = params.amount === undefined ? undefined : Number(params.amount);
+    if (asked !== undefined && (!Number.isSafeInteger(asked) || asked <= 0)) {
+        throw new PaymentNotSentError('That amount is not a whole number of milli-satoshis.');
+    }
+    if (decoded.amountMsats !== null) {
+        const stated = Number(decoded.amountMsats);
+        if (asked !== undefined && asked !== stated) {
+            throw new PaymentNotSentError(`That invoice is for ${stated} msat, not the ${asked} msat asked for.`);
+        }
+        return stated;
+    }
+    if (asked === undefined)
+        throw new PaymentNotSentError('That invoice states no amount - say how much to send.');
+    return asked;
+}
+// Refuses before anything is attempted, and says which ceiling it hit: a
+// payer told only "no" tries again.
+function charge(grant, amountMsat) {
+    if (grant.budgetMsat === undefined) {
+        throw new ServiceError('RESTRICTED', 'This connection has no budget to spend from.');
+    }
+    if (grant.maxPaymentMsat !== undefined && amountMsat > grant.maxPaymentMsat) {
+        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.`);
+    }
+}

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

@@ -0,0 +1,3 @@
+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;

package/dist/wallet-service/tools.js

@@ -0,0 +1,189 @@
+import { z } from 'zod';
+import { resolveNwcUri } from '../zap/handlers.js';
+import { defaultGrantsFile, loadGrants, saveGrants } from './grants.js';
+import { upstreamWallet } from './upstream.js';
+import { DEFAULT_METHODS, SUPPORTED_METHODS, WalletService, grantUri, 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
+// unbounded capability: every method the wallet supports, no ceiling, for
+// as long as it exists. These tools issue connections over that same
+// wallet that are not - a method allowlist, a budget that spending
+// requires, a per-payment ceiling, and a revocation that takes effect the
+// moment it is asked for.
+//
+// Nothing is answered unless the service is running, and it runs for as
+// long as this process does. That is worth saying out loud rather than
+// 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.
+let service = null;
+let servingFor = null;
+const served = new Map();
+const text = (value) => ({
+    content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+});
+const shown = (grant) => ({
+    id: grant.id,
+    name: grant.name,
+    methods: grant.methods,
+    state: grant.revokedAt ? 'revoked' : 'live',
+    ...(grant.budgetMsat === undefined
+        ? {}
+        : { budgetMsat: grant.budgetMsat, spentMsat: grant.spentMsat, remainingMsat: remainingBudgetMsat(grant) }),
+    ...(grant.maxPaymentMsat === undefined ? {} : { maxPaymentMsat: grant.maxPaymentMsat }),
+    ...(grant.lastUsedAt === undefined ? {} : { lastUsedAt: new Date(grant.lastUsedAt).toISOString() }),
+});
+export function registerWalletServiceTools(server, deps) {
+    const grantsFile = defaultGrantsFile();
+    const identity = () => deps.ctx.activePublicKeyHex;
+    const read = () => loadGrants(grantsFile, identity());
+    const write = (grants) => {
+        saveGrants(grantsFile, identity(), grants);
+    };
+    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)
+            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.');
+        servingFor = pubkey;
+        service = new WalletService({
+            wallet: upstreamWallet({ uri, alias: deps.ctx.activeNpub }),
+            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));
+            },
+        });
+        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.',
+        });
+    });
+    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 },
+    }, async () => text({
+        serving: service?.serving() ?? [],
+        grants: read().map(shown),
+    }));
+    server.registerTool('wallet-revoke', {
+        description: 'Revoke a connection by name or id. It stops being answered immediately; nothing needs to be published anywhere.',
+        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);
+        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() ?? [] });
+    });
+}

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

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

package/dist/wallet-service/upstream.js

@@ -0,0 +1,97 @@
+import { NwcClient } from '@forgesworn/nwc-kit';
+import { tryDecodeBolt11, verifyPreimage } from 'farrier-kit';
+import { PaymentNotSentError, ServiceError } from './service.js';
+async function withClient(options, run) {
+    const client = new NwcClient(options.uri, { ...(options.transport ? { transport: options.transport } : {}) });
+    try {
+        return await run(client);
+    }
+    finally {
+        client.close();
+    }
+}
+export function upstreamWallet(options) {
+    return {
+        alias: () => options.alias ?? 'bray',
+        balanceMsat: async () => withClient(options, async (client) => {
+            await client.connect();
+            const balance = await client.getBalance();
+            return Number(balance.balance ?? 0);
+        }),
+        async makeInvoice({ amountMsat, description }) {
+            return withClient(options, async (client) => {
+                const capabilities = await client.connect();
+                if (!capabilities.methods.includes('make_invoice')) {
+                    throw new ServiceError('NOT_IMPLEMENTED', 'The wallet behind this service cannot issue invoices.');
+                }
+                const transaction = await client.makeInvoice({
+                    amount: amountMsat,
+                    ...(description === undefined ? {} : { description }),
+                });
+                const invoice = String(transaction.invoice ?? '');
+                const decoded = tryDecodeBolt11(invoice);
+                if (!decoded) {
+                    throw new ServiceError('INTERNAL', 'The wallet returned something that is not a decodable invoice.');
+                }
+                // An invoice for a different amount than the one asked for is not a
+                // smaller problem than no invoice: whoever pays it pays that.
+                if (decoded.amountMsats !== null && Number(decoded.amountMsats) !== amountMsat) {
+                    throw new ServiceError('INTERNAL', `The wallet issued an invoice for ${String(decoded.amountMsats)} msat, not the ${amountMsat} msat asked for.`);
+                }
+                return {
+                    type: 'incoming',
+                    invoice,
+                    paymentHash: decoded.paymentHashHex,
+                    amountMsat,
+                    createdAt: decoded.timestamp,
+                    expiresAt: decoded.timestamp + decoded.expirySeconds,
+                    ...(description === undefined ? {} : { description }),
+                };
+            });
+        },
+        async payInvoice({ invoice }) {
+            const decoded = tryDecodeBolt11(invoice);
+            if (!decoded)
+                throw new PaymentNotSentError('That is not a decodable BOLT-11 invoice.');
+            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)) {
+                    // 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.
+                    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) };
+            });
+        },
+        async lookupInvoice(query) {
+            return withClient(options, async (client) => {
+                const capabilities = await client.connect();
+                if (!capabilities.methods.includes('lookup_invoice')) {
+                    throw new ServiceError('NOT_IMPLEMENTED', 'The wallet behind this service cannot look invoices up.');
+                }
+                const found = await client.lookupInvoice({
+                    ...(query.paymentHash === undefined ? {} : { payment_hash: query.paymentHash }),
+                    ...(query.invoice === undefined ? {} : { invoice: query.invoice }),
+                });
+                if (!found)
+                    return null;
+                return {
+                    type: found.type === 'outgoing' ? 'outgoing' : 'incoming',
+                    invoice: String(found.invoice ?? ''),
+                    paymentHash: String(found.payment_hash ?? ''),
+                    amountMsat: Number(found.amount ?? 0),
+                    createdAt: Number(found.created_at ?? 0),
+                    ...(found.settled_at === undefined ? {} : { settledAt: Number(found.settled_at) }),
+                    ...(found.preimage === undefined ? {} : { preimage: String(found.preimage) }),
+                    ...(found.fees_paid === undefined ? {} : { feesPaidMsat: Number(found.fees_paid) }),
+                    ...(found.description === undefined ? {} : { description: String(found.description) }),
+                };
+            });
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nostr-bray",
-  "version": "3.2.2",
+  "version": "3.4.0",
   "mcpName": "dev.forgesworn/bray",
   "description": "Trust-aware Nostr for AI and humans. Three dimensions of trust -- verification, proximity, and access -- woven into every interaction.",
   "type": "module",