nostr-bray 2.4.0 → 3.1.0

package/README.md

@@ -212,13 +212,17 @@ Search order: `BRAY_CONFIG` env var > `$XDG_CONFIG_HOME/bray/config.json` > `~/.
 | `NOSTR_SECRET_KEY_FILE` | Path to secret key file |
 | `NOSTR_NCRYPTSEC` | NIP-49 encrypted key |
 | `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 |
 | `TOR_PROXY` | SOCKS5h proxy for Tor |
 | `NIP04_ENABLED` | Set `1` to enable legacy NIP-04 DMs |
 | `TRANSPORT` | `stdio` (default) or `http` |
 | `PORT` | HTTP port (default 3000) |
 
-All secret env vars are deleted from `process.env` immediately after parsing.
+All secret env vars are deleted from `process.env` before parsing can fail.
+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.
 
 ## CLI
 

package/dist/cli/commands/wallet.d.ts

@@ -7,8 +7,8 @@ export interface WalletExtras {
  * Dispatch `wallet *` subcommands (NIP-47 Nostr Wallet Connect).
  *
  * Commands:
- *   wallet connect <nwc-url>      Store NWC URI for the active identity
- *   wallet disconnect             Remove the stored NWC URI for the active identity
+ *   wallet connect <nwc-file>     Store an NWC secret-file reference for the active identity
+ *   wallet disconnect             Remove the stored NWC file reference for the active identity
  *   wallet status                 Show configured wallet pubkey and relay
  *   wallet pay <bolt11>           Pay a Lightning invoice via NWC
  *   wallet balance                Request wallet balance via NWC

package/dist/cli/commands/wallet.js

@@ -1,10 +1,10 @@
-import { handleZapSend, handleZapBalance, handleZapListTransactions, resolveNwcUri, loadWallets, saveWallets, parseNwcUri, } from '../../exports.js';
+import { handleZapSend, handleZapBalance, handleZapListTransactions, resolveNwcUri, loadWallets, saveWallets, parseNwcUri, normaliseNwcUriFile, } from '../../exports.js';
 /**
  * Dispatch `wallet *` subcommands (NIP-47 Nostr Wallet Connect).
  *
  * Commands:
- *   wallet connect <nwc-url>      Store NWC URI for the active identity
- *   wallet disconnect             Remove the stored NWC URI for the active identity
+ *   wallet connect <nwc-file>     Store an NWC secret-file reference for the active identity
+ *   wallet disconnect             Remove the stored NWC file reference for the active identity
  *   wallet status                 Show configured wallet pubkey and relay
  *   wallet pay <bolt11>           Pay a Lightning invoice via NWC
  *   wallet balance                Request wallet balance via NWC
@@ -15,13 +15,11 @@ export async function dispatch(cmd, _cmdArgs, h, ctx, pool, extras) {
     const { globalNwcUri, walletsFile } = extras;
     switch (cmd) {
         case 'wallet-connect': {
-            const uri = req(1, 'wallet connect <nwc-url>');
-            // Validate URI before storing
-            parseNwcUri(uri);
+            const secretFile = normaliseNwcUriFile(req(1, 'wallet connect <nwc-file>'));
             const pubkey = ctx.activePublicKeyHex;
             const npub = ctx.activeNpub;
             const wallets = loadWallets(walletsFile);
-            wallets[pubkey] = uri;
+            wallets[pubkey] = secretFile;
             saveWallets(walletsFile, wallets);
             out({ ok: true, identity: npub, message: `Wallet configured for ${npub}` });
             break;
@@ -40,7 +38,7 @@ export async function dispatch(cmd, _cmdArgs, h, ctx, pool, extras) {
             const npub = ctx.activeNpub;
             const uri = resolveNwcUri(ctx, walletsFile, globalNwcUri);
             if (!uri) {
-                out({ ok: false, identity: npub, configured: false, message: 'No wallet configured. Use `wallet connect <nwc-url>` or set NWC_URI.' });
+                out({ ok: false, identity: npub, configured: false, message: 'No wallet configured. Use `wallet connect <nwc-file>` or set NWC_URI_FILE.' });
                 break;
             }
             const conn = parseNwcUri(uri);
@@ -48,12 +46,16 @@ export async function dispatch(cmd, _cmdArgs, h, ctx, pool, extras) {
             out({ ok: true, identity: npub, configured: true, walletPubkey: conn.pubkey, relay: conn.relay });
             break;
         }
-        case 'wallet-pay':
-            out(await handleZapSend(ctx, pool, {
+        case 'wallet-pay': {
+            const result = await handleZapSend(ctx, pool, {
                 invoice: req(1, 'wallet pay <bolt11>'),
                 nwcUri: resolveNwcUri(ctx, walletsFile, globalNwcUri),
-            }));
+            });
+            // A preimage can be an L402 bearer credential when the challenge macaroon
+            // is known. Report verified payment without printing the preimage.
+            out({ paid: true, verified: result.verified, paymentHash: result.paymentHash, feesPaidMsats: result.fees_paid });
             break;
+        }
         case 'wallet-balance':
             out(await handleZapBalance(ctx, pool, { nwcUri: resolveNwcUri(ctx, walletsFile, globalNwcUri) }));
             break;

package/dist/cli/commands/zap.js

@@ -4,9 +4,11 @@ export async function dispatch(cmd, cmdArgs, h, ctx, pool, extras) {
     const { req, flag, out } = h;
     const { globalNwcUri, walletsFile } = extras;
     switch (cmd) {
-        case 'zap-send':
-            out(await handleZapSend(ctx, pool, { invoice: req(1, 'zap-send <bolt11>'), nwcUri: resolveNwcUri(ctx, walletsFile, globalNwcUri) }));
+        case 'zap-send': {
+            const result = await handleZapSend(ctx, pool, { invoice: req(1, 'zap-send <bolt11>'), nwcUri: resolveNwcUri(ctx, walletsFile, globalNwcUri) });
+            out({ paid: true, verified: result.verified, paymentHash: result.paymentHash, feesPaidMsats: result.fees_paid });
             break;
+        }
         case 'zap-balance':
             out(await handleZapBalance(ctx, pool, { nwcUri: resolveNwcUri(ctx, walletsFile, globalNwcUri) }));
             break;

package/dist/cli/index.js

@@ -182,8 +182,8 @@ Admin (NIP-86 relay management):
    listdisallowedkinds; they were never NIP-86 method names)
 
 Wallet (NIP-47 Nostr Wallet Connect):
-  wallet connect <nwc-url>            Store NWC URI for the active identity
-  wallet disconnect                   Remove stored NWC URI for the active identity
+  wallet connect <nwc-file>           Store a private NWC secret-file reference
+  wallet disconnect                   Remove stored NWC file reference
   wallet status                       Show configured wallet pubkey and relay
   wallet pay <bolt11>                 Pay a Lightning invoice via NWC
   wallet balance                      Request wallet balance via NWC
@@ -261,7 +261,7 @@ Environment:
   BUNKER_URI / BUNKER_URI_FILE  bunker:// URI (use INSTEAD of secret key)
   NOSTR_RELAYS                  Comma-separated relay URLs
   NOSTR_AUTH                    NIP-42 policy: off (default), on-demand, eager
-  NWC_URI / NWC_URI_FILE        Nostr Wallet Connect URI
+  NWC_URI_FILE                  Private 0600 file containing an NWC URI
   TOR_PROXY                     SOCKS5h proxy URL
   NOSTR_BRAY_OUTPUT             Default output: "human" (default) or "json"
 

package/dist/config.js

@@ -1,6 +1,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { readNwcUriFile } from './zap/nwc-file.js';
 const NSEC_RE = /^nsec1[a-z0-9]{58}$/;
 const HEX_RE = /^[0-9a-f]{64}$/;
 const NCRYPTSEC_RE = /^ncryptsec1[a-z0-9]+$/;
@@ -85,10 +86,34 @@ export function loadConfigFile() {
 /** Load configuration from config file, environment variables, and secret files.
  *  Priority: env vars > config file > defaults */
 export async function loadConfig() {
+    // Capture then remove bearer credentials before any parsing or validation can
+    // throw. This keeps failure paths from leaving secrets in process.env.
+    const secretEnvironment = {
+        secretKey: process.env.NOSTR_SECRET_KEY,
+        secretKeyFile: process.env.NOSTR_SECRET_KEY_FILE,
+        bunkerUri: process.env.BUNKER_URI,
+        bunkerUriFile: process.env.BUNKER_URI_FILE,
+        ncryptsec: process.env.NOSTR_NCRYPTSEC,
+        ncryptsecFile: process.env.NOSTR_NCRYPTSEC_FILE,
+        ncryptsecPassword: process.env.NOSTR_NCRYPTSEC_PASSWORD,
+        ncryptsecPasswordFile: process.env.NOSTR_NCRYPTSEC_PASSWORD_FILE,
+        nwcUri: process.env.NWC_URI,
+        nwcUriFile: process.env.NWC_URI_FILE,
+    };
+    delete process.env.NOSTR_SECRET_KEY;
+    delete process.env.NOSTR_SECRET_KEY_FILE;
+    delete process.env.NWC_URI;
+    delete process.env.NWC_URI_FILE;
+    delete process.env.BUNKER_URI;
+    delete process.env.BUNKER_URI_FILE;
+    delete process.env.NOSTR_NCRYPTSEC;
+    delete process.env.NOSTR_NCRYPTSEC_FILE;
+    delete process.env.NOSTR_NCRYPTSEC_PASSWORD;
+    delete process.env.NOSTR_NCRYPTSEC_PASSWORD_FILE;
     const file = loadConfigFile();
     // --- Secret key ---
-    const keyFilePath = process.env.NOSTR_SECRET_KEY_FILE ?? file.secretKeyFile;
-    const keyEnvVar = process.env.NOSTR_SECRET_KEY;
+    const keyFilePath = secretEnvironment.secretKeyFile ?? file.secretKeyFile;
+    const keyEnvVar = secretEnvironment.secretKey;
     let secretKey;
     // A local key source is an explicit choice to sign locally. A bunker URI
     // saved by `bunker connect` is only a fallback and must not override that
@@ -96,15 +121,15 @@ export async function loadConfig() {
     // it is present. Explicit bunker configuration still takes precedence.
     const hasLocalKeySource = !!(keyFilePath
         || keyEnvVar
-        || process.env.NOSTR_NCRYPTSEC_FILE
-        || process.env.NOSTR_NCRYPTSEC
+        || secretEnvironment.ncryptsecFile
+        || secretEnvironment.ncryptsec
         || file.ncryptsecFile);
     let bunkerUri;
-    if (process.env.BUNKER_URI_FILE) {
-        bunkerUri = readSecretFile(process.env.BUNKER_URI_FILE);
+    if (secretEnvironment.bunkerUriFile) {
+        bunkerUri = readSecretFile(secretEnvironment.bunkerUriFile);
     }
-    else if (process.env.BUNKER_URI) {
-        bunkerUri = process.env.BUNKER_URI;
+    else if (secretEnvironment.bunkerUri) {
+        bunkerUri = secretEnvironment.bunkerUri;
     }
     else if (file.bunkerUriFile) {
         bunkerUri = readSecretFile(file.bunkerUriFile);
@@ -118,10 +143,10 @@ export async function loadConfig() {
             bunkerUri = saved.uri;
     }
     // --- NIP-49 ncryptsec (password-encrypted key) ---
-    const ncryptsec = process.env.NOSTR_NCRYPTSEC_FILE
-        ? readSecretFile(process.env.NOSTR_NCRYPTSEC_FILE)
-        : process.env.NOSTR_NCRYPTSEC
-            ? process.env.NOSTR_NCRYPTSEC
+    const ncryptsec = secretEnvironment.ncryptsecFile
+        ? readSecretFile(secretEnvironment.ncryptsecFile)
+        : secretEnvironment.ncryptsec
+            ? secretEnvironment.ncryptsec
             : file.ncryptsecFile
                 ? readSecretFile(file.ncryptsecFile)
                 : undefined;
@@ -129,11 +154,11 @@ export async function loadConfig() {
     // Prefer file-based sources so the password can be delivered via systemd
     // credentials, docker secrets, or similar secure channels and never appears
     // in the process environment or config JSON.
-    const ncryptsecPasswordFile = process.env.NOSTR_NCRYPTSEC_PASSWORD_FILE ?? file.ncryptsecPasswordFile;
+    const ncryptsecPasswordFile = secretEnvironment.ncryptsecPasswordFile ?? file.ncryptsecPasswordFile;
     let ncryptsecPasswordBuf = null;
     let ncryptsecPassword;
-    if (process.env.NOSTR_NCRYPTSEC_PASSWORD) {
-        ncryptsecPassword = process.env.NOSTR_NCRYPTSEC_PASSWORD;
+    if (secretEnvironment.ncryptsecPassword) {
+        ncryptsecPassword = secretEnvironment.ncryptsecPassword;
     }
     else if (ncryptsecPasswordFile) {
         // Read as Buffer so we can zeroise the at-rest byte representation even
@@ -191,13 +216,14 @@ export async function loadConfig() {
     }
     const secretFormat = secretKey ? detectKeyFormat(secretKey) : 'nsec';
     // --- NWC URI ---
-    const nwcFilePath = process.env.NWC_URI_FILE ?? file.nwcUriFile;
+    const rawNwcUri = secretEnvironment.nwcUri;
+    const nwcFilePath = secretEnvironment.nwcUriFile ?? file.nwcUriFile;
+    if (rawNwcUri) {
+        throw new Error('NWC_URI is disabled because bearer wallet credentials must not be stored in environment variables; use NWC_URI_FILE');
+    }
     let nwcUri;
     if (nwcFilePath) {
-        nwcUri = readSecretFile(nwcFilePath);
-    }
-    else if (process.env.NWC_URI) {
-        nwcUri = process.env.NWC_URI;
+        nwcUri = readNwcUriFile(nwcFilePath);
     }
     // --- Relays ---
     const relays = process.env.NOSTR_RELAYS
@@ -261,17 +287,6 @@ export async function loadConfig() {
     const walletsFile = process.env.BRAY_WALLETS_FILE
         ?? file.walletsFile
         ?? (process.env.HOME ? `${process.env.HOME}/.nostr/bray-wallets.json` : '');
-    // --- Clean up secrets from process.env ---
-    delete process.env.NOSTR_SECRET_KEY;
-    delete process.env.NOSTR_SECRET_KEY_FILE;
-    delete process.env.NWC_URI;
-    delete process.env.NWC_URI_FILE;
-    delete process.env.BUNKER_URI;
-    delete process.env.BUNKER_URI_FILE;
-    delete process.env.NOSTR_NCRYPTSEC;
-    delete process.env.NOSTR_NCRYPTSEC_FILE;
-    delete process.env.NOSTR_NCRYPTSEC_PASSWORD;
-    delete process.env.NOSTR_NCRYPTSEC_PASSWORD_FILE;
     return {
         secretKey,
         secretFormat,

package/dist/help.js

@@ -57,14 +57,14 @@ export const COMMAND_HELP = {
     'relay-add': { usage: 'relay-add <url> [read|write]', description: 'Add a relay to the active identity\'s relay set (in-memory only — does not publish kind 10002).', examples: ['nostr-bray relay-add wss://new-relay.com', 'nostr-bray relay-add wss://read-only.com read'] },
     'relay-info': { usage: 'relay-info <wss://url>', description: 'Fetch the NIP-11 relay information document (name, description, supported NIPs, limits).', examples: ['nostr-bray relay-info wss://relay.damus.io'] },
     // Wallet (NIP-47 Nostr Wallet Connect)
-    'wallet-connect': { usage: 'wallet connect <nwc-url>', description: 'Store a nostr+walletconnect:// URI for the active identity. Each identity can have its own Lightning wallet.', examples: ['nostr-bray wallet connect "nostr+walletconnect://pubkey?relay=wss%3A%2F%2Frelay.example&secret=deadbeef"'], notes: 'URI is stored per-identity in the wallets file (0600). Use `wallet status` to confirm.' },
-    'wallet-disconnect': { usage: 'wallet disconnect', description: 'Remove the stored NWC URI for the active identity. Falls back to NWC_URI env var if set.', examples: ['nostr-bray wallet disconnect'] },
+    'wallet-connect': { usage: 'wallet connect <nwc-file>', description: 'Store a reference to a private local file containing the NWC URI for the active identity.', examples: ['nostr-bray wallet connect /run/secrets/alice-nwc'], notes: 'The file must be a regular 0600 file. The bearer URI is never passed on the command line or stored in the wallet registry.' },
+    'wallet-disconnect': { usage: 'wallet disconnect', description: 'Remove the stored NWC file reference for the active identity. Falls back to NWC_URI_FILE if configured.', examples: ['nostr-bray wallet disconnect'] },
     'wallet-status': { usage: 'wallet status', description: 'Show the wallet pubkey and relay configured for the active identity. The connection secret is never shown.', examples: ['nostr-bray wallet status --json'] },
-    'wallet-pay': { usage: 'wallet pay <bolt11>', description: 'Pay a Lightning invoice via Nostr Wallet Connect (NIP-47). Requires a wallet configured via `wallet connect` or NWC_URI.', examples: ['nostr-bray wallet pay lnbc10u1...'], notes: 'SPENDS REAL SATS. Decodes the invoice and sends a pay_invoice NIP-47 request.' },
+    'wallet-pay': { usage: 'wallet pay <bolt11>', description: 'Pay a Lightning invoice via Nostr Wallet Connect (NIP-47). Requires a wallet configured via `wallet connect` or NWC_URI_FILE.', examples: ['nostr-bray wallet pay lnbc10u1...'], notes: 'SPENDS REAL SATS. Waits for an authenticated wallet result and verifies the returned preimage without printing it.' },
     'wallet-balance': { usage: 'wallet balance', description: 'Request wallet balance via Nostr Wallet Connect (NIP-47).', examples: ['nostr-bray wallet balance', 'nostr-bray wallet balance --json'] },
     'wallet-history': { usage: 'wallet history [--limit N]', description: 'List recent Lightning transactions via Nostr Wallet Connect (NIP-47). Default limit: 10.', examples: ['nostr-bray wallet history', 'nostr-bray wallet history --limit 25 --json'] },
     // Zap
-    'zap-send': { usage: 'zap-send <bolt11>', description: 'Pay a Lightning invoice via Nostr Wallet Connect (NIP-47). Requires NWC_URI configured.', examples: ['nostr-bray zap-send lnbc10u1...'] },
+    'zap-send': { usage: 'zap-send <bolt11>', description: 'Pay a Lightning invoice via Nostr Wallet Connect (NIP-47). Requires NWC_URI_FILE or a persona wallet file.', examples: ['nostr-bray zap-send lnbc10u1...'] },
     'zap-balance': { usage: 'zap-balance', description: 'Request wallet balance via NWC.', examples: ['nostr-bray zap-balance'] },
     'zap-invoice': { usage: 'zap-invoice <msats> [description]', description: 'Generate a Lightning invoice via NWC to receive payments.', examples: ['nostr-bray zap-invoice 100000 "Coffee payment"'] },
     'zap-lookup': { usage: 'zap-lookup <payment-hash>', description: 'Look up a Lightning invoice payment status via NWC.', examples: ['nostr-bray zap-lookup abc123...'] },

package/dist/marketplace/tools.js

@@ -1,4 +1,5 @@
 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';
@@ -146,6 +147,10 @@ export function registerMarketplaceTools(server, deps) {
         annotations: { readOnlyHint: false, destructiveHint: true },
     }, async ({ macaroon, invoice, confirm }) => {
         const decoded = handleZapDecode(invoice);
+        if (decoded.expiry === undefined)
+            throw new Error('Invalid BOLT-11 invoice');
+        if (decoded.amountMsats === undefined)
+            throw new Error('Amountless L402 invoices are not supported');
         const costSats = extractBolt11AmountSats(invoice);
         if (!confirm) {
             return {
@@ -166,17 +171,15 @@ export function registerMarketplaceTools(server, deps) {
             invoice,
             nwcUri: resolveNwcUri(deps.ctx, deps.walletsFile, deps.nwcUri),
         });
-        // Store credentials keyed by event ID (opaque to caller)
-        const credentialId = payResult.event.id;
-        // In a real L402 flow the preimage comes from the payment result.
-        // NWC pay_invoice returns asynchronously — use the payment hash as placeholder
-        // until the wallet confirms. For now we store with the event id as preimage proxy.
-        storeCredential(credentialId, macaroon, credentialId);
+        // Keep the bearer credential in process and return only an opaque handle.
+        const credentialId = randomUUID();
+        storeCredential(credentialId, macaroon, payResult.preimage);
         return {
             content: [{
                     type: 'text',
                     text: JSON.stringify({
                         paid: true,
+                        verified: payResult.verified,
                         credentialId,
                         costSats,
                         amountMsats: decoded.amountMsats,

package/dist/sdk.d.ts

@@ -363,6 +363,6 @@ export interface BrayClient {
 export declare function createBray(config: BrayClientConfig): Promise<BrayClient>;
 /**
  * Get or create a singleton BrayClient built from environment variables.
- * Reads NOSTR_SECRET_KEY / BUNKER_URI / NOSTR_RELAYS / NWC_URI etc.
+ * Reads NOSTR_SECRET_KEY / BUNKER_URI / NOSTR_RELAYS / NWC_URI_FILE etc.
  */
 export declare function defaultBray(): Promise<BrayClient>;

package/dist/sdk.js

@@ -343,7 +343,7 @@ export async function createBray(config) {
 let _default = null;
 /**
  * Get or create a singleton BrayClient built from environment variables.
- * Reads NOSTR_SECRET_KEY / BUNKER_URI / NOSTR_RELAYS / NWC_URI etc.
+ * Reads NOSTR_SECRET_KEY / BUNKER_URI / NOSTR_RELAYS / NWC_URI_FILE etc.
  */
 export function defaultBray() {
     if (!_default) {

package/dist/zap/handlers.d.ts

@@ -1,34 +1,33 @@
-import type { Event as NostrEvent } from 'nostr-tools';
+import type { GetBalanceResult, NwcRequestOptions, NwcTransaction, NwcTransport, PayInvoiceResult } from '@forgesworn/nwc-kit';
 import type { SigningContext } from '../signing-context.js';
 import type { RelayPool } from '../relay-pool.js';
-import type { PublishResult } from '../types.js';
 /**
  * Load the wallets map from the JSON file. Returns empty map if file missing.
  *
  * @param walletsFile - Absolute path to the JSON wallets store.
- * @returns A map of public key hex strings to NWC URIs.
+ * @returns A map of public key hex strings to absolute NWC secret-file paths.
  *
  * @example
  * const wallets = loadWallets('/home/user/.bray/wallets.json')
- * // { 'abc123...': 'nostr+walletconnect://...' }
+ * // { 'abc123...': '/run/secrets/alice-nwc' }
  */
 export declare function loadWallets(walletsFile: string): Record<string, string>;
 /**
  * Save the wallets map to the JSON file. Creates parent dirs and sets 0600.
  *
  * @param walletsFile - Absolute path to the JSON wallets store.
- * @param wallets - Map of public key hex strings to NWC URIs to persist.
+ * @param wallets - Map of public key hex strings to absolute NWC secret-file paths.
  * @returns void
  *
  * @example
  * saveWallets('/home/user/.bray/wallets.json', {
- *   'abc123...': 'nostr+walletconnect://pubkey?relay=wss://relay.example&secret=deadbeef',
+ *   'abc123...': '/run/secrets/alice-nwc',
  * })
  */
 export declare function saveWallets(walletsFile: string, wallets: Record<string, string>): void;
 /**
  * Resolve the NWC URI for the active identity.
- * 1. Per-identity wallet from wallets file
+ * 1. Per-identity NWC secret file referenced by the wallet registry
  * 2. Global NWC URI (fallback)
  * 3. undefined (no wallet configured)
  *
@@ -37,27 +36,28 @@ export declare function saveWallets(walletsFile: string, wallets: Record<string,
  * @returns The resolved NWC URI, or `undefined` if no wallet is configured.
  *
  * @example
- * const uri = resolveNwcUri(ctx, '/home/user/.bray/wallets.json', process.env.NWC_URI)
+ * const uri = resolveNwcUri(ctx, '/home/user/.bray/wallets.json', configuredNwcUri)
  * if (!uri) throw new Error('No wallet configured')
  */
 export declare function resolveNwcUri(ctx: SigningContext, walletsFile: string, globalNwcUri?: string): string | undefined;
 export interface NwcConnection {
     pubkey: string;
     relay: string;
-    secret: string;
+    relays: readonly string[];
+    lud16?: string;
 }
 /**
  * Parse a nostr+walletconnect:// URI.
  *
  * @param uri - A `nostr+walletconnect://` URI as specified in NIP-47.
- * @returns A parsed {@link NwcConnection} containing the wallet pubkey, relay URL, and connection secret.
- * @throws {Error} If `pubkey`, `relay`, or `secret` are missing from the URI.
+ * @returns Public connection metadata. The connection secret is never returned.
+ * @throws {Error} If the URI is malformed or insecure.
  *
  * @example
  * const conn = parseNwcUri(
  *   'nostr+walletconnect://abc123?relay=wss%3A%2F%2Frelay.example&secret=deadbeef',
  * )
- * // { pubkey: 'abc123', relay: 'wss://relay.example', secret: 'deadbeef' }
+ * // { pubkey: 'abc123', relay: 'wss://relay.example/', relays: ['wss://relay.example/'] }
  */
 export declare function parseNwcUri(uri: string): NwcConnection;
 export interface ZapReceipt {
@@ -87,9 +87,8 @@ export declare function handleZapReceipts(ctx: SigningContext, pool: RelayPool,
  * Decode basic bolt11 invoice fields.
  *
  * @param bolt11 - A BOLT-11 Lightning invoice string (e.g. `lnbc...`).
- * @returns An object with the decoded fields. `amountMsats` is present when the
- *   amount is encoded in the invoice prefix; `description` and `expiry` are not
- *   yet decoded and will be absent in the current implementation.
+ * @returns The bounded amount, description and expiry fields committed by the
+ *   invoice. `amountMsats` is absent for an amountless invoice.
  *
  * @example
  * const { amountMsats } = handleZapDecode('lnbc1000n1...')
@@ -100,142 +99,47 @@ export declare function handleZapDecode(bolt11: string): {
     description?: string;
     expiry?: number;
 };
-/**
- * Pay a Lightning invoice via NWC.
- *
- * @param args - Payment arguments.
- * @param args.invoice - BOLT-11 Lightning invoice to pay.
- * @param args.nwcUri - NWC URI identifying the wallet to use.
- * @returns The signed NIP-47 request event and relay publish result.
- * @throws {Error} If `nwcUri` is not provided.
- *
- * @example
- * const { event, publish } = await handleZapSend(ctx, pool, {
- *   invoice: 'lnbc500n1...',
- *   nwcUri: 'nostr+walletconnect://abc123?relay=wss%3A%2F%2Frelay.example&secret=deadbeef',
- * })
- */
-export declare function handleZapSend(ctx: SigningContext, pool: RelayPool, args: {
-    invoice: string;
-    nwcUri?: string;
-}): Promise<{
-    event: NostrEvent;
-    publish: PublishResult;
-}>;
-/**
- * Request wallet balance via NWC.
- *
- * @param args - Balance request arguments.
- * @param args.nwcUri - NWC URI identifying the wallet to query.
- * @returns The signed NIP-47 `get_balance` request event and relay publish result.
- * @throws {Error} If `nwcUri` is not provided.
- *
- * @example
- * const { event, publish } = await handleZapBalance(ctx, pool, {
- *   nwcUri: 'nostr+walletconnect://abc123?relay=wss%3A%2F%2Frelay.example&secret=deadbeef',
- * })
- */
-export declare function handleZapBalance(ctx: SigningContext, pool: RelayPool, args: {
+interface NwcOperationOptions extends NwcRequestOptions {
+    /** Injectable for deterministic tests and specialised relay transports. */
+    transport?: NwcTransport;
+}
+interface NwcArgs extends NwcOperationOptions {
     nwcUri?: string;
-}): Promise<{
-    event: NostrEvent;
-    publish: PublishResult;
-}>;
+}
+export interface ZapPaymentResult extends PayInvoiceResult {
+    paymentHash: string;
+    verified: true;
+}
 /**
- * Generate a Lightning invoice via NWC.
- *
- * @param args - Invoice creation arguments.
- * @param args.amountMsats - Invoice amount in millisatoshis.
- * @param args.description - Optional human-readable memo attached to the invoice.
- * @param args.nwcUri - NWC URI identifying the wallet to use.
- * @returns The signed NIP-47 `make_invoice` request event and relay publish result.
- * @throws {Error} If `nwcUri` is not provided.
- *
- * @example
- * const { event, publish } = await handleZapMakeInvoice(ctx, pool, {
- *   amountMsats: 21_000,
- *   description: 'Coffee ☕',
- *   nwcUri: 'nostr+walletconnect://abc123?relay=wss%3A%2F%2Frelay.example&secret=deadbeef',
- * })
+ * The wallet may have submitted a payment but Bray cannot prove settlement.
+ * Callers must reconcile `paymentHash` before attempting the invoice again.
  */
-export declare function handleZapMakeInvoice(ctx: SigningContext, pool: RelayPool, args: {
+export declare class ZapPaymentOutcomeUnknownError extends Error {
+    readonly paymentHash: string;
+    readonly code = "PAYMENT_OUTCOME_UNKNOWN";
+    constructor(paymentHash: string);
+}
+/** Pay a BOLT-11 invoice and return only after the wallet proves settlement. */
+export declare function handleZapSend(_ctx: SigningContext, _pool: RelayPool, args: {
+    invoice: string;
+} & NwcArgs): Promise<ZapPaymentResult>;
+/** Return the wallet's confirmed balance in millisatoshis. */
+export declare function handleZapBalance(_ctx: SigningContext, _pool: RelayPool, args: NwcArgs): Promise<GetBalanceResult>;
+/** Generate a Lightning invoice through the configured wallet. */
+export declare function handleZapMakeInvoice(_ctx: SigningContext, _pool: RelayPool, args: {
     amountMsats: number;
     description?: string;
-    nwcUri?: string;
-}): Promise<{
-    event: NostrEvent;
-    publish: PublishResult;
-}>;
-/**
- * Look up an invoice via NWC.
- *
- * @param args - Lookup arguments. Provide at least one of `paymentHash` or `invoice`.
- * @param args.paymentHash - Hex-encoded payment hash of the invoice to look up.
- * @param args.invoice - BOLT-11 invoice string to look up.
- * @param args.nwcUri - NWC URI identifying the wallet to query.
- * @returns The signed NIP-47 `lookup_invoice` request event and relay publish result.
- * @throws {Error} If `nwcUri` is not provided.
- *
- * @example
- * const { event, publish } = await handleZapLookupInvoice(ctx, pool, {
- *   paymentHash: 'a1b2c3...',
- *   nwcUri: 'nostr+walletconnect://abc123?relay=wss%3A%2F%2Frelay.example&secret=deadbeef',
- * })
- */
-export declare function handleZapLookupInvoice(ctx: SigningContext, pool: RelayPool, args: {
+} & NwcArgs): Promise<NwcTransaction>;
+/** Look up an invoice and return the wallet's authenticated result. */
+export declare function handleZapLookupInvoice(_ctx: SigningContext, _pool: RelayPool, args: {
     paymentHash?: string;
     invoice?: string;
-    nwcUri?: string;
-}): Promise<{
-    event: NostrEvent;
-    publish: PublishResult;
-}>;
-/**
- * List recent transactions via NWC.
- *
- * @param args - Pagination arguments.
- * @param args.limit - Maximum number of transactions to return (default 10).
- * @param args.offset - Number of transactions to skip for pagination (default 0).
- * @param args.nwcUri - NWC URI identifying the wallet to query.
- * @returns The signed NIP-47 `list_transactions` request event and relay publish result.
- * @throws {Error} If `nwcUri` is not provided.
- *
- * @example
- * const { event, publish } = await handleZapListTransactions(ctx, pool, {
- *   limit: 5,
- *   offset: 0,
- *   nwcUri: 'nostr+walletconnect://abc123?relay=wss%3A%2F%2Frelay.example&secret=deadbeef',
- * })
- */
-export declare function handleZapListTransactions(ctx: SigningContext, pool: RelayPool, args: {
+} & NwcArgs): Promise<NwcTransaction>;
+/** List recent transactions through the isolated NIP-47 extension 05 client. */
+export declare function handleZapListTransactions(_ctx: SigningContext, _pool: RelayPool, args: {
     limit?: number;
     offset?: number;
-    nwcUri?: string;
-}): Promise<{
-    event: NostrEvent;
-    publish: PublishResult;
+} & NwcArgs): Promise<{
+    transactions: NwcTransaction[];
 }>;
-/**
- * Parse a NWC wallet response event.
- *
- * @param nwcUri - The NWC URI whose secret is used to decrypt the response.
- * @param event - A kind 23195 NIP-47 response event from the wallet service.
- * @returns The decrypted response payload containing `result_type`, an optional
- *   `result` object, and an optional `error` with `code` and `message`.
- *
- * @example
- * const response = handleZapParseResponse(
- *   'nostr+walletconnect://abc123?relay=wss%3A%2F%2Frelay.example&secret=deadbeef',
- *   walletResponseEvent,
- * )
- * if (response.error) console.error(response.error.message)
- * else console.log(response.result)
- */
-export declare function handleZapParseResponse(nwcUri: string, event: NostrEvent): {
-    result_type: string;
-    result?: Record<string, unknown>;
-    error?: {
-        code: string;
-        message: string;
-    };
-};
+export {};