nostr-bray 1.27.3 → 1.27.5

package/README.md

@@ -1,6 +1,6 @@
 # nostr-bray
 
-**Trust-aware Nostr MCP for AI and humans.** 234 tools. Model-agnostic. Works with Claude, ChatGPT, Gemini, Cursor, Windsurf, or any MCP client.
+**Trust-aware Nostr MCP for AI and humans.** 236 tools. 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)
@@ -225,6 +225,23 @@ npx nostr-bray --help                    # see all commands
 
 See [llms.txt](./llms.txt) for a concise summary optimised for AI context windows, or [llms-full.txt](./llms-full.txt) for complete tool documentation with parameter details.
 
+## Part of the ForgeSworn Toolkit
+
+[ForgeSworn](https://forgesworn.dev) builds open-source cryptographic identity, payments, and coordination tools for Nostr.
+
+| Library | What it does |
+|---------|-------------|
+| [nsec-tree](https://github.com/forgesworn/nsec-tree) | Deterministic sub-identity derivation |
+| [ring-sig](https://github.com/forgesworn/ring-sig) | SAG/LSAG ring signatures on secp256k1 |
+| [range-proof](https://github.com/forgesworn/range-proof) | Pedersen commitment range proofs |
+| [canary-kit](https://github.com/forgesworn/canary-kit) | Coercion-resistant spoken verification |
+| [spoken-token](https://github.com/forgesworn/spoken-token) | Human-speakable verification tokens |
+| [toll-booth](https://github.com/forgesworn/toll-booth) | L402 payment middleware |
+| [geohash-kit](https://github.com/forgesworn/geohash-kit) | Geohash toolkit with polygon coverage |
+| [nostr-attestations](https://github.com/forgesworn/nostr-attestations) | NIP-VA verifiable attestations |
+| [dominion](https://github.com/forgesworn/dominion) | Epoch-based encrypted access control |
+| [nostr-veil](https://github.com/forgesworn/nostr-veil) | Privacy-preserving Web of Trust |
+
 ## Licence
 
 MIT

package/dist/bunker-context.d.ts

@@ -5,9 +5,12 @@
  * remote bunker via encrypted Nostr relay messages.
  *
  * Usage:
- *   BUNKER_URI=bunker://pk?relay=wss://...
- *   or
- *   BUNKER_URI=bunker://pk?relay=wss://...&secret=clienthex
+ *   BUNKER_URI=bunker://<pubkey>?relay=wss://...&relay=wss://...&secret=<pairing-nonce>
+ *
+ * A bunker URI can list multiple relays; all of them are used. The
+ * `secret=` parameter is a NIP-46 pairing nonce (proof-of-URI-possession)
+ * that the client echoes to the signer on the initial `connect` request,
+ * and is NOT a private key.
  */
 import { BunkerSigner } from 'nostr-tools/nip46';
 import { SimplePool } from 'nostr-tools/pool';
@@ -15,12 +18,46 @@ import type { PublicIdentity, SignFn } from './types.js';
 import type { SigningContext } from './signing-context.js';
 export interface BunkerConfig {
     pubkey: string;
+    /**
+     * All relays declared in the URI. A bunker URI can (and usually does)
+     * list several relays for redundancy; every one must be tried since the
+     * remote signer is listening on all of them. Earlier versions of this
+     * parser only read the first `?relay=` parameter and discarded the
+     * rest, which could produce a silent hang if the first relay was down.
+     */
     relays: string[];
-    secret?: string;
+    /**
+     * NIP-46 pairing nonce from the URI's `?secret=` parameter. This is
+     * NOT a private key. It is a proof-of-URI-possession token that the
+     * client must echo back to the signer in its first `connect` request
+     * so the signer knows the client received the URI out-of-band. Any
+     * client with the URI can present this value; after the first
+     * `connect` the signer TOFU-approves the client for crypto methods
+     * and the nonce is not needed again for that specific client.
+     *
+     * Earlier versions of this interface named this field `secret` without
+     * the distinction and the code then used it as a client private key,
+     * which was both a hang (wrong client identity, remote signer rejected
+     * the unknown client) and a security bug (any URI-holder could
+     * impersonate the client on the wire). Do not do that.
+     */
+    connectSecret?: string;
 }
 /** Parse a bunker:// URI */
 export declare function parseBunkerUri(uri: string): BunkerConfig;
-/** Resolve the client secret key: URI secret > cached > generate & persist. */
+/**
+ * Resolve the client secret key for a given bunker.
+ *
+ * Caches a freshly-generated client key per bunker pubkey so that repeat
+ * invocations against the same bunker reuse the same client identity,
+ * letting the remote signer's TOFU approval persist across reconnects
+ * without needing a fresh button press each time.
+ *
+ * Critically, the URI's `connectSecret` is NEVER used as a client
+ * private key here. It's a public pairing nonce (see BunkerConfig docs)
+ * and using it as a key would leak the client identity to anyone who
+ * has the URI.
+ */
 export declare function resolveClientKey(config: BunkerConfig, stateDir?: string): Uint8Array;
 export declare class BunkerContext implements SigningContext {
     protected signer: BunkerSigner;
@@ -29,7 +66,13 @@ export declare class BunkerContext implements SigningContext {
     private clientSk;
     protected constructor(signer: BunkerSigner, pool: SimplePool, clientSk: Uint8Array);
     /** Connect to a remote bunker. Blocks until the connection is established. */
-    static connect(uri: string, timeoutMs?: number): Promise<BunkerContext>;
+    static connect(uri: string, _timeoutMs?: number, stateDir?: string): Promise<BunkerContext>;
+    /**
+     * Resolve the signing identity pubkey from the remote bunker.
+     * Called lazily on first access so startup stays fast (no extra
+     * NIP-46 round-trip). The result is cached for subsequent calls.
+     */
+    resolvePublicKey(): Promise<string>;
     /** The remote identity's npub */
     get activeNpub(): string;
     /** The remote identity's hex pubkey */

package/dist/bunker-context.js

@@ -5,9 +5,12 @@
  * remote bunker via encrypted Nostr relay messages.
  *
  * Usage:
- *   BUNKER_URI=bunker://pk?relay=wss://...
- *   or
- *   BUNKER_URI=bunker://pk?relay=wss://...&secret=clienthex
+ *   BUNKER_URI=bunker://<pubkey>?relay=wss://...&relay=wss://...&secret=<pairing-nonce>
+ *
+ * A bunker URI can list multiple relays; all of them are used. The
+ * `secret=` parameter is a NIP-46 pairing nonce (proof-of-URI-possession)
+ * that the client echoes to the signer on the initial `connect` request,
+ * and is NOT a private key.
  */
 import { BunkerSigner } from 'nostr-tools/nip46';
 import { useWebSocketImplementation, SimplePool } from 'nostr-tools/pool';
@@ -18,22 +21,34 @@ import { readStateFile, writeStateFile } from './state.js';
 useWebSocketImplementation(WebSocket);
 /** Parse a bunker:// URI */
 export function parseBunkerUri(uri) {
-    // bunker://<pubkey>?relay=<url>&relay=<url>&secret=<hex>
+    // bunker://<pubkey>?relay=<url>&relay=<url>...&secret=<hex>
     const url = new URL(uri);
     const pubkey = url.hostname || url.pathname.replace('//', '');
     const relays = url.searchParams.getAll('relay');
-    const secret = url.searchParams.get('secret') ?? undefined;
-    if (!pubkey || relays.length === 0) {
-        throw new Error('Invalid bunker URI: missing pubkey or relay');
+    const connectSecret = url.searchParams.get('secret') ?? undefined;
+    if (!pubkey) {
+        throw new Error('Invalid bunker URI: missing pubkey');
+    }
+    if (relays.length === 0) {
+        throw new Error('Invalid bunker URI: missing relay parameter(s)');
     }
-    return { pubkey, relays, secret };
+    return { pubkey, relays, connectSecret };
 }
 const CLIENT_KEYS_FILE = 'client-keys.json';
-/** Resolve the client secret key: URI secret > cached > generate & persist. */
+/**
+ * Resolve the client secret key for a given bunker.
+ *
+ * Caches a freshly-generated client key per bunker pubkey so that repeat
+ * invocations against the same bunker reuse the same client identity,
+ * letting the remote signer's TOFU approval persist across reconnects
+ * without needing a fresh button press each time.
+ *
+ * Critically, the URI's `connectSecret` is NEVER used as a client
+ * private key here. It's a public pairing nonce (see BunkerConfig docs)
+ * and using it as a key would leak the client identity to anyone who
+ * has the URI.
+ */
 export function resolveClientKey(config, stateDir) {
-    if (config.secret) {
-        return Buffer.from(config.secret, 'hex');
-    }
     const cache = readStateFile(CLIENT_KEYS_FILE, stateDir);
     if (cache[config.pubkey]) {
         return Buffer.from(cache[config.pubkey], 'hex');
@@ -54,24 +69,52 @@ export class BunkerContext {
         this.clientSk = clientSk;
     }
     /** Connect to a remote bunker. Blocks until the connection is established. */
-    static async connect(uri, timeoutMs = 15_000) {
+    static async connect(uri, _timeoutMs = 15_000, stateDir) {
         const config = parseBunkerUri(uri);
-        const clientSk = resolveClientKey(config);
+        const clientSk = resolveClientKey(config, stateDir);
         const pool = new SimplePool();
-        const signer = BunkerSigner.fromBunker(clientSk, { pubkey: config.pubkey, relays: config.relays, secret: null }, { pool });
-        // Connect and verify
+        const signer = BunkerSigner.fromBunker(clientSk, {
+            pubkey: config.pubkey,
+            relays: config.relays,
+            // The URI pairing nonce -- gets echoed in the `connect` call so
+            // the remote signer can TOFU-approve this client. If omitted the
+            // signer will still accept the connect but every subsequent
+            // request will require a manual approval on the signer side.
+            secret: config.connectSecret ?? null,
+        }, { pool });
+        // Only the `connect` handshake is needed at startup. Ping is
+        // redundant (if connect succeeded the signer is alive), and
+        // getPublicKey is deferred to first access so startup stays fast.
         await signer.connect();
-        await signer.ping();
         const ctx = new BunkerContext(signer, pool, clientSk);
-        ctx.pubkeyHex = await signer.getPublicKey();
+        // Do NOT use config.pubkey here — that is the bunker's transport
+        // key from the URI, not the signing identity. The actual identity
+        // pubkey is resolved lazily via getPublicKey() on first access.
         return ctx;
     }
+    /**
+     * Resolve the signing identity pubkey from the remote bunker.
+     * Called lazily on first access so startup stays fast (no extra
+     * NIP-46 round-trip). The result is cached for subsequent calls.
+     */
+    async resolvePublicKey() {
+        if (!this.pubkeyHex) {
+            this.pubkeyHex = await this.signer.getPublicKey();
+        }
+        return this.pubkeyHex;
+    }
     /** The remote identity's npub */
     get activeNpub() {
+        if (!this.pubkeyHex) {
+            throw new Error('pubkey not yet resolved — call resolvePublicKey() first');
+        }
         return npubEncode(this.pubkeyHex);
     }
     /** The remote identity's hex pubkey */
     get activePublicKeyHex() {
+        if (!this.pubkeyHex) {
+            throw new Error('pubkey not yet resolved — call resolvePublicKey() first');
+        }
         return this.pubkeyHex;
     }
     /** Sign an event via the remote bunker */

package/dist/cli.js

@@ -24,10 +24,26 @@ import { getCommandHelp } from './help.js';
 import * as fmt from './format.js';
 const args = process.argv.slice(2);
 const command = args[0];
-// No command = start MCP server
+// No command = start MCP server.
+//
+// index.js's top-level await sets up the StdioServerTransport (or HTTP
+// transport) and registers tools. Once that chain resolves, the transport
+// keeps the event loop alive on its own, BUT we must prevent cli.ts from
+// falling through to the per-command handlers below (which re-loadConfig
+// and build a second ctx, racing with index.js's state and throwing when
+// run in MCP mode because there is no command to dispatch to).
+//
+// The old version of this block called process.exit(0) after the import,
+// which terminated the MCP server immediately -- before Claude Code's MCP
+// client could send its `initialize` request. The other long-running
+// commands in this file use `await new Promise(() => {})` to hold cli.ts
+// open until SIGINT/SIGTERM; matching that pattern here keeps the MCP
+// server process alive forever without executing any more cli.ts code.
+// SIGINT/SIGTERM are caught by the shutdown handler at the bottom of
+// index.ts which calls ctx.destroy() + pool.close() + process.exit(0).
 if (!command) {
     await import('./index.js');
-    process.exit(0);
+    await new Promise(() => { });
 }
 // Bunker = NIP-46 remote signer
 if (command === 'bunker' && !args.includes('--help')) {

package/dist/index.js

@@ -29,22 +29,39 @@ const pool = new RelayPool({
     defaultRelays: config.relays,
 });
 const nip65 = new Nip65Manager(pool, config.relays);
-// Connect to bunker (with Heartwood auto-detection) or use local key
+// Connect to bunker or use local key.
+//
+// In bunker mode we defer the Heartwood extension probe to a background
+// task rather than blocking startup on it. The probe sends a
+// heartwood_list_identities round-trip to the remote signer, which costs
+// an extra 1-2 seconds on top of the NIP-46 connect and pubkey lookup.
+// Sync startup takes 3-6s total over five relays, and Claude Code's MCP
+// stdio health check will mark the server as "Failed to connect" if the
+// StdioServerTransport isn't serving within its window -- so every second
+// we can shave off startup matters. Heartwood-specific tools
+// (heartwood_derive etc.) still work because nostr-tools' BunkerSigner
+// sends arbitrary NIP-46 method names via sendRequest; the probe only
+// controlled whether to expose those methods as typed instance methods
+// on HeartwoodContext, which is a cosmetic distinction for MCP use.
 let ctx;
 if (config.bunkerUri) {
     const { BunkerContext } = await import('./bunker-context.js');
     const base = await BunkerContext.connect(config.bunkerUri);
-    // Probe for Heartwood extensions
-    const { HeartwoodContext } = await import('./heartwood-context.js');
-    const hw = await HeartwoodContext.probe(base);
-    if (hw) {
-        ctx = hw;
-        console.error(`Connected to Heartwood — signing as ${hw.activeNpub}`);
-    }
-    else {
-        ctx = base;
-        console.error(`Connected to bunker — signing as ${base.activeNpub}`);
-    }
+    await base.resolvePublicKey();
+    ctx = base;
+    console.error(`Connected to bunker — signing as ${base.activeNpub}`);
+    (async () => {
+        try {
+            const { HeartwoodContext } = await import('./heartwood-context.js');
+            const hw = await HeartwoodContext.probe(base);
+            if (hw) {
+                console.error(`Heartwood extensions detected — ${base.activeNpub}`);
+            }
+        }
+        catch (e) {
+            console.error('Heartwood probe failed (non-fatal):', e.message);
+        }
+    })();
 }
 else {
     ctx = new IdentityContext(config.secretKey, config.secretFormat);

package/dist/relay-pool.d.ts

@@ -6,6 +6,25 @@ export interface PoolLike {
     querySync(relays: string[], filter: Filter): Promise<NostrEvent[]>;
     destroy(): void;
 }
+/**
+ * Summarise a publish attempt into the two boolean flags on {@link PublishResult}.
+ *
+ * `success` is true when the event reached the network as a majority: at least
+ * one relay accepted AND at least 50% of attempted relays accepted. This is the
+ * default "did my publish work" signal. Paywalled, whitelisted, or transient
+ * failures routinely leave some relays in the rejected list, so requiring every
+ * relay to accept produces far too many false negatives.
+ *
+ * `allAccepted` preserves the strict "every attempted relay accepted" semantic
+ * for callers that genuinely need it (e.g. high-assurance publishing to a
+ * small curated list of private relays).
+ *
+ * Zero attempted relays is treated as failure on both flags.
+ */
+export declare function summarisePublish(acceptedCount: number, attempted: number): {
+    success: boolean;
+    allAccepted: boolean;
+};
 export interface RelayPoolConfig {
     torProxy?: string;
     allowClearnet: boolean;

package/dist/relay-pool.js

@@ -1,3 +1,26 @@
+/**
+ * Summarise a publish attempt into the two boolean flags on {@link PublishResult}.
+ *
+ * `success` is true when the event reached the network as a majority: at least
+ * one relay accepted AND at least 50% of attempted relays accepted. This is the
+ * default "did my publish work" signal. Paywalled, whitelisted, or transient
+ * failures routinely leave some relays in the rejected list, so requiring every
+ * relay to accept produces far too many false negatives.
+ *
+ * `allAccepted` preserves the strict "every attempted relay accepted" semantic
+ * for callers that genuinely need it (e.g. high-assurance publishing to a
+ * small curated list of private relays).
+ *
+ * Zero attempted relays is treated as failure on both flags.
+ */
+export function summarisePublish(acceptedCount, attempted) {
+    if (attempted <= 0)
+        return { success: false, allAccepted: false };
+    return {
+        success: acceptedCount >= 1 && acceptedCount * 2 >= attempted,
+        allAccepted: acceptedCount === attempted,
+    };
+}
 /** Initialise WebSocket and create a real SimplePool — lazy-loaded to avoid side effects at import */
 async function createRealPool(torProxy) {
     const { useWebSocketImplementation, SimplePool } = await import('nostr-tools/pool');
@@ -72,7 +95,7 @@ export class RelayPool {
         const relays = this.getRelays(npub);
         const writeRelays = relays.write;
         if (writeRelays.length === 0) {
-            return { success: false, accepted: [], rejected: [], errors: ['no write relays configured'] };
+            return { success: false, allAccepted: false, accepted: [], rejected: [], errors: ['no write relays configured'] };
         }
         const promises = pool.publish(writeRelays, event);
         const accepted = [];
@@ -91,7 +114,7 @@ export class RelayPool {
             }
         }
         return {
-            success: accepted.length === writeRelays.length,
+            ...summarisePublish(accepted.length, writeRelays.length),
             accepted,
             rejected,
             errors,
@@ -101,7 +124,7 @@ export class RelayPool {
     async publishDirect(relays, event) {
         const pool = await this.poolReady;
         if (relays.length === 0) {
-            return { success: false, accepted: [], rejected: [], errors: ['no relays specified'] };
+            return { success: false, allAccepted: false, accepted: [], rejected: [], errors: ['no relays specified'] };
         }
         const promises = pool.publish(relays, event);
         const accepted = [];
@@ -120,7 +143,7 @@ export class RelayPool {
             }
         }
         return {
-            success: accepted.length === relays.length,
+            ...summarisePublish(accepted.length, relays.length),
             accepted,
             rejected,
             errors,

package/dist/social/scheduled.js

@@ -123,7 +123,12 @@ export async function handlePublishScheduled(pool, npub, queueDir) {
                 published++;
             }
             else {
-                console.error(`Failed to publish ${data.event.id}: rejected by all relays`);
+                // success is the majority-quorum flag: treat as failure only when
+                // we did not reach at least 50% of attempted relays.
+                const reason = result.accepted.length === 0
+                    ? 'rejected by all relays'
+                    : `only ${result.accepted.length}/${result.accepted.length + result.rejected.length} relays accepted`;
+                console.error(`Failed to publish ${data.event.id}: ${reason}`);
                 failed++;
             }
         }

package/dist/social/tools.js

@@ -25,7 +25,7 @@ export function registerSocialTools(server, deps) {
         maxEntries: deps.veilCacheMax ?? 500,
     });
     server.registerTool('social-post', {
-        description: 'Post a text note (kind 1) signed by the active identity and publish to relays. Returns { id, pubkey, publish: { success, accepted, rejected } }. The most common social action.',
+        description: 'Post a text note (kind 1) signed by the active identity and publish to relays. Returns { id, pubkey, publish: { success, allAccepted, accepted, rejected } } where success is the majority-quorum signal (true when at least one relay accepted and at least half of attempted relays accepted) and allAccepted is true only when every attempted relay accepted. The most common social action.',
         inputSchema: {
             content: z.string().describe('Text content of the note'),
         },

package/dist/types.d.ts

@@ -21,7 +21,18 @@ export interface RelaySet {
 }
 /** Result of a publish operation */
 export interface PublishResult {
+    /**
+     * True when the event is reliably published: at least one relay accepted
+     * AND at least 50% of attempted relays accepted. Captures both "reached
+     * the network" and "reached a majority", which matches real-world
+     * expectations where paywalled or whitelisted relays routinely reject.
+     */
     success: boolean;
+    /**
+     * True when every attempted relay accepted. Use this for high-assurance
+     * publishing to a small curated list of private relays.
+     */
+    allAccepted: boolean;
     accepted: string[];
     rejected: string[];
     errors: string[];

package/dist/vault/handlers.d.ts

@@ -60,7 +60,15 @@ export interface VaultRotateResult {
 export declare function handleVaultCreate(ctx: SigningContext, pool: RelayPool, args: {
     tiers: string[];
 }): Promise<VaultCreateResult>;
-/** Encrypt content with a content key derived from the active identity for a given tier + epoch. */
+/**
+ * Encrypt content with the active identity's content key for the given epoch.
+ *
+ * The `tier` is recorded on the returned result for caller bookkeeping but is
+ * not part of the content key derivation itself. dominion-protocol's content
+ * keys rotate per-epoch via HKDF(privkey, "epoch:{epochId}"); tier-level
+ * access control is implemented by sharing the CK to different subsets of
+ * pubkeys (addToTier / addIndividualGrant), not by tier-scoped keys.
+ */
 export declare function handleVaultEncrypt(ctx: SigningContext, args: {
     content: string;
     tier: string;
@@ -72,7 +80,12 @@ export declare function handleVaultShare(ctx: SigningContext, pool: RelayPool, a
     recipients: string[];
     epoch?: string;
 }): Promise<VaultShareResult>;
-/** Decrypt ciphertext using the content key for the active identity's tier + epoch. */
+/**
+ * Decrypt ciphertext using the active identity's content key for the given epoch.
+ *
+ * `tier` is carried on the result for caller bookkeeping but not used in CK
+ * derivation (see handleVaultEncrypt for the same note).
+ */
 export declare function handleVaultRead(ctx: SigningContext, args: {
     ciphertext: string;
     tier: string;

package/dist/vault/handlers.js

@@ -63,7 +63,15 @@ export async function handleVaultCreate(ctx, pool, args) {
         tiers: Object.keys(config.tiers),
     };
 }
-/** Encrypt content with a content key derived from the active identity for a given tier + epoch. */
+/**
+ * Encrypt content with the active identity's content key for the given epoch.
+ *
+ * The `tier` is recorded on the returned result for caller bookkeeping but is
+ * not part of the content key derivation itself. dominion-protocol's content
+ * keys rotate per-epoch via HKDF(privkey, "epoch:{epochId}"); tier-level
+ * access control is implemented by sharing the CK to different subsets of
+ * pubkeys (addToTier / addIndividualGrant), not by tier-scoped keys.
+ */
 export async function handleVaultEncrypt(ctx, args) {
     const privkeyHex = Buffer.from(ctx.activePrivateKey).toString('hex');
     const epoch = args.epoch ?? getCurrentEpochId();
@@ -122,7 +130,12 @@ export async function handleVaultShare(ctx, pool, args) {
     }
     return { published, failed, recipients: successfulRecipients };
 }
-/** Decrypt ciphertext using the content key for the active identity's tier + epoch. */
+/**
+ * Decrypt ciphertext using the active identity's content key for the given epoch.
+ *
+ * `tier` is carried on the result for caller bookkeeping but not used in CK
+ * derivation (see handleVaultEncrypt for the same note).
+ */
 export async function handleVaultRead(ctx, args) {
     const privkeyHex = Buffer.from(ctx.activePrivateKey).toString('hex');
     const ck = deriveContentKey(privkeyHex, args.epoch, args.tier);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nostr-bray",
-  "version": "1.27.3",
+  "version": "1.27.5",
   "description": "Trust-aware Nostr for AI and humans. Three dimensions of trust -- verification, proximity, and access -- woven into every interaction.",
   "type": "module",
   "main": "dist/index.js",