nostr-bray 1.20.0 → 1.21.0

package/README.md

@@ -16,6 +16,41 @@ AI agents interacting with Nostr today are handed a single key pair with no sepa
 
 nostr-bray solves this with nsec-tree hierarchical derivation. A single master secret generates unlimited child identities, each with its own key pair, purpose, and relay set. Private keys are zeroed from memory on eviction. Agents can switch personas mid-conversation, prove they control the master without revealing the derivation path, and activate a duress identity if compromised.
 
+## How It Works
+
+Every tool operates as the "active identity." Derive a persona, switch to it, and everything you do is signed by that persona's key — cryptographically unlinkable to the master unless you publish a proof.
+
+```
+identity-derive-persona("work")    → npub1abc...
+identity-switch("work")            → now operating as work persona
+social-post("Hello from work!")    → signed by npub1abc...
+identity-switch("master")          → back to master
+social-post("Back to main")       → signed by master npub
+```
+
+This is not just key management — it is context isolation. Each persona has its own relay set, its own contact list, and its own attestation chain. Compromise one and the others remain intact.
+
+## Comparison
+
+| Feature | nostr-bray | nak | nostr-mcp | nostr-tools |
+|---------|-----------|-----|-----------|-------------|
+| MCP server | 77 tools | [via `nak mcp`](https://github.com/fiatjaf/nak) | 5–23 tools | — |
+| CLI | 77 commands | ✓ (mature) | — | — |
+| Hierarchical identity (nsec-tree) | ✓ | — | — | — |
+| Persona switching | ✓ | — | — | — |
+| Ring signatures (anonymous proofs) | ✓ | — | — | — |
+| Shamir backup (BIP-39 words) | ✓ | — | — | — |
+| Duress detection | ✓ | — | — | — |
+| NIP-VA attestations (kind 31000) | ✓ | — | — | — |
+| Linkage proofs (blind/full) | ✓ | — | — | — |
+| NIP-46 bunker (server + client) | ✓ | ✓ (client) | partial | — |
+| NIP-17 encrypted DMs | ✓ | ✓ | ✓ | ✓ |
+| NWC Lightning payments | ✓ | — | — | — |
+| Blossom media | ✓ | ✓ | — | — |
+| NIP-29 groups | ✓ | — | — | — |
+| Tor routing (SOCKS5h) | ✓ | — | — | — |
+| 329 tests, 96% coverage | ✓ | — | — | — |
+
 ## Quick Start — CLI
 
 ```bash
@@ -68,7 +103,7 @@ Or with a secret file (recommended):
 
 ## Tool Groups
 
-### Identity (12 tools)
+### Identity (12 tools) — create, derive, switch, prove, backup, and migrate Nostr identities
 
 | Tool | Description |
 |------|-------------|
@@ -85,7 +120,7 @@ Or with a secret file (recommended):
 | `identity-restore` | Re-sign migratable events under the active identity |
 | `identity-migrate` | Full migration with preview, confirmation, and linkage proof |
 
-### Social (14 tools)
+### Social (14 tools) — post, reply, react, DM, follow, and read feeds
 
 | Tool | Description |
 |------|-------------|
@@ -104,7 +139,7 @@ Or with a secret file (recommended):
 | `social-notifications` | Fetch mentions, replies, reactions, zap receipts |
 | `social-feed` | Fetch kind 1 text note feed |
 
-### Trust (11 tools)
+### Trust (11 tools) — attestations, ring signatures, linkage proofs, spoken verification
 
 | Tool | Description |
 |------|-------------|
@@ -120,7 +155,7 @@ Or with a secret file (recommended):
 | `trust-spoken-challenge` | Generate spoken verification token |
 | `trust-spoken-verify` | Verify spoken token response |
 
-### Relay (5 tools)
+### Relay (5 tools) — per-identity relay lists, NIP-65 management, direct queries
 
 | Tool | Description |
 |------|-------------|
@@ -130,7 +165,7 @@ Or with a secret file (recommended):
 | `relay-query` | Query events from relays by kind, author, tags, or time range |
 | `relay-info` | Fetch NIP-11 relay information document |
 
-### Zap (7 tools)
+### Zap (7 tools) — Lightning payments and invoices via Nostr Wallet Connect
 
 | Tool | Description |
 |------|-------------|
@@ -142,14 +177,14 @@ Or with a secret file (recommended):
 | `zap-receipts` | Parse zap receipts (amount, sender, message) |
 | `zap-decode` | Decode bolt11 invoice fields |
 
-### Safety (2 tools)
+### Safety (2 tools) — duress personas for coercion resistance
 
 | Tool | Description |
 |------|-------------|
 | `safety-configure` | Configure an alternative identity persona |
 | `safety-activate` | Switch to alternative identity |
 
-### Blossom (3 tools)
+### Blossom (3 tools) — media uploads and management
 
 | Tool | Description |
 |------|-------------|
@@ -157,7 +192,7 @@ Or with a secret file (recommended):
 | `blossom-list` | List blobs for a pubkey |
 | `blossom-delete` | Delete a blob by SHA-256 hash |
 
-### Groups — NIP-29 (4 tools)
+### Groups — NIP-29 (4 tools) — group chat, metadata, and membership
 
 | Tool | Description |
 |------|-------------|
@@ -166,14 +201,14 @@ Or with a secret file (recommended):
 | `group-send` | Send message to a group |
 | `group-members` | List group members |
 
-### Community NIPs (2 tools)
+### Community NIPs (2 tools) — publish and read community-proposed NIPs
 
 | Tool | Description |
 |------|-------------|
 | `nip-publish` | Publish a community NIP (kind 30817) |
 | `nip-read` | Fetch community NIPs |
 
-### Utility (18 tools)
+### Utility (18 tools) — encode, decode, encrypt, verify, filter, fetch, browse NIPs
 
 | Tool | Description |
 |------|-------------|
@@ -196,20 +231,6 @@ Or with a secret file (recommended):
 | `nip-list` | List all official NIPs |
 | `nip-show` | Show a specific NIP's content |
 
-## Identity Switching
-
-The killer feature. Every tool operates as the "active identity." Switch with a single call:
-
-```
-identity-derive-persona("work")    → npub1abc...
-identity-switch("work")            → now operating as work persona
-social-post("Hello from work!")    → signed by npub1abc...
-identity-switch("master")          → back to master
-social-post("Back to main")       → signed by master npub
-```
-
-Derived identities are cryptographically unlinkable unless you publish a linkage proof.
-
 ## Configuration
 
 | Variable | Description |

package/dist/catalog.d.ts

@@ -0,0 +1,35 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+type ToolHandler = (args: any) => Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+/**
+ * Holds non-promoted tool definitions and exposes them via search-actions
+ * and execute-action meta-tools. This keeps the primary tool list lean
+ * (context-window economics) while still making every action discoverable.
+ */
+export declare class ActionCatalog {
+    private readonly entries;
+    add(name: string, definition: any, handler: ToolHandler): void;
+    get size(): number;
+    search(intent: string): Array<{
+        name: string;
+        description: string;
+        parameters?: Record<string, string>;
+    }>;
+    execute(name: string, params: Record<string, unknown>): Promise<{
+        content: Array<{
+            type: 'text';
+            text: string;
+        }>;
+    }>;
+    registerMetaTools(server: McpServer): void;
+}
+/**
+ * Create a proxy around McpServer that intercepts registerTool calls.
+ * Promoted tools go to the real server; everything else goes to the catalog.
+ */
+export declare function createCatalogProxy(server: McpServer, catalog: ActionCatalog, promoted: Set<string>): McpServer;
+export {};

package/dist/catalog.js

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+/**
+ * Holds non-promoted tool definitions and exposes them via search-actions
+ * and execute-action meta-tools. This keeps the primary tool list lean
+ * (context-window economics) while still making every action discoverable.
+ */
+export class ActionCatalog {
+    entries = new Map();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    add(name, definition, handler) {
+        this.entries.set(name, {
+            name,
+            description: definition.description ?? '',
+            inputSchema: definition.inputSchema,
+            annotations: definition.annotations,
+            handler,
+        });
+    }
+    get size() {
+        return this.entries.size;
+    }
+    search(intent) {
+        const tokens = intent.toLowerCase().split(/[\s\-_]+/).filter(t => t.length > 1);
+        const scored = [];
+        for (const entry of this.entries.values()) {
+            const haystack = `${entry.name} ${entry.description}`.toLowerCase();
+            let score = 0;
+            for (const token of tokens) {
+                if (haystack.includes(token))
+                    score++;
+            }
+            if (score > 0)
+                scored.push({ entry, score });
+        }
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, 10).map(({ entry }) => ({
+            name: entry.name,
+            description: entry.description,
+            parameters: extractParams(entry.inputSchema),
+        }));
+    }
+    async execute(name, params) {
+        const entry = this.entries.get(name);
+        if (!entry) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: `Unknown action "${name}". Use search-actions to find available actions.`,
+                        }),
+                    }],
+            };
+        }
+        if (entry.inputSchema && Object.keys(entry.inputSchema).length > 0) {
+            const schema = z.object(entry.inputSchema);
+            const result = schema.safeParse(params);
+            if (!result.success) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: 'Invalid parameters',
+                                action: name,
+                                issues: result.error.issues.map(i => `${i.path.join('.')}: ${i.message}`),
+                                expected: extractParams(entry.inputSchema),
+                            }, null, 2),
+                        }],
+                };
+            }
+            return entry.handler(result.data);
+        }
+        return entry.handler(params);
+    }
+    registerMetaTools(server) {
+        const catalog = this;
+        server.registerTool('search-actions', {
+            description: `Search ${catalog.size} additional actions by describing what you want to do. ` +
+                'Returns matching actions with names, descriptions, and parameter schemas. ' +
+                'Use this when the promoted tools (whoami, social-post, social-reply, social-feed, ' +
+                'dm-send, dm-read, zap-send, zap-balance, identity-switch, relay-query) ' +
+                'do not cover what you need.',
+            inputSchema: {
+                intent: z.string().describe('Describe what you want to do (e.g. "upload a file", "verify an attestation", ' +
+                    '"encrypt a message", "manage contacts", "ring signature")'),
+            },
+            annotations: { readOnlyHint: true },
+        }, async ({ intent }) => {
+            const matches = catalog.search(intent);
+            if (matches.length === 0) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                matches: [],
+                                hint: 'No matches found. Try different keywords or broader terms.',
+                            }, null, 2),
+                        }],
+                };
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ matches }, null, 2),
+                    }],
+            };
+        });
+        server.registerTool('execute-action', {
+            description: 'Execute an action found via search-actions. Pass the exact action name and its parameters.',
+            inputSchema: {
+                action: z.string().describe('Action name from search-actions results'),
+                params: z.record(z.string(), z.unknown()).default({}).describe('Parameters for the action (see search-actions results for expected params)'),
+            },
+            annotations: { openWorldHint: true },
+        }, async ({ action, params }) => {
+            return catalog.execute(action, params);
+        });
+    }
+}
+/**
+ * Create a proxy around McpServer that intercepts registerTool calls.
+ * Promoted tools go to the real server; everything else goes to the catalog.
+ */
+export function createCatalogProxy(server, catalog, promoted) {
+    return new Proxy(server, {
+        get(target, prop, receiver) {
+            if (prop === 'registerTool') {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return (name, definition, handler) => {
+                    if (promoted.has(name)) {
+                        return target.registerTool(name, definition, handler);
+                    }
+                    catalog.add(name, definition, handler);
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractParams(schema) {
+    if (!schema || Object.keys(schema).length === 0)
+        return undefined;
+    const params = {};
+    for (const [key, zodType] of Object.entries(schema)) {
+        params[key] = zodType?.description ?? '(no description)';
+    }
+    return params;
+}

package/dist/cli.js

@@ -130,7 +130,8 @@ Social:
   group-members <group-id>           List group members
 
 Trust:
-  attest <type> <identifier> [subject]  Create kind 31000 attestation
+  attest <event-id>                     Verify someone's assertion (assertion-first)
+  claim <type>                          Make a direct claim (endorsement, vouch, review)
   trust-read [--subject X] [--type X]   Read attestations
   trust-verify <event-json>             Validate attestation structure
   trust-revoke <type> <identifier>      Revoke an attestation
@@ -473,13 +474,27 @@ async function run(cmdArgs) {
             out(await handleNotifications(ctx, pool, { limit: parseInt(flag('limit', '50'), 10) }), fmt.formatNotifications);
             break;
         // === Trust ===
-        case 'attest':
+        case 'attest': {
+            const assertionId = req(1, 'attest <assertion-event-id> [--subject <hex>] [--type <type>] [--summary <text>]');
             out(await handleTrustAttest(ctx, pool, {
-                type: req(1, 'attest <type> <identifier> [subject]'),
-                identifier: cmdArgs[2],
-                subject: cmdArgs[3],
+                assertionId,
+                subject: flag('subject'),
+                type: flag('type'),
+                summary: flag('summary'),
+                assertionRelay: flag('relay'),
             }));
             break;
+        }
+        case 'claim': {
+            const type = req(1, 'claim <type> [--subject <hex>] [--identifier <string>] [--summary <text>]');
+            out(await handleTrustAttest(ctx, pool, {
+                type,
+                subject: flag('subject'),
+                identifier: flag('identifier'),
+                summary: flag('summary'),
+            }));
+            break;
+        }
         case 'trust-read':
             out(await handleTrustRead(pool, ctx.activeNpub, {
                 subject: flag('subject'),

package/dist/index.js

@@ -11,6 +11,7 @@ import { registerRelayTools } from './relay/tools.js';
 import { registerZapTools } from './zap/tools.js';
 import { registerSafetyTools } from './safety/tools.js';
 import { registerUtilTools } from './util/tools.js';
+import { ActionCatalog, createCatalogProxy } from './catalog.js';
 const config = loadConfig();
 const pool = new RelayPool({
     torProxy: config.torProxy,
@@ -36,19 +37,29 @@ config.bunkerUri = undefined;
 nip65.loadForIdentity(ctx.activeNpub).then(masterRelays => {
     pool.reconfigure(ctx.activeNpub, masterRelays);
 }).catch(e => console.error('NIP-65 relay load failed:', e.message));
-const server = new McpServer({ name: 'nostr-bray', version: '0.1.0' });
-// Phase 2: Identity tools
-registerIdentityTools(server, deps);
-// Phase 3: Social tools
-registerSocialTools(server, deps);
-// Phase 4: Trust tools
-registerTrustTools(server, deps);
-// Phase 5: Relay, Zap & Safety tools
-registerRelayTools(server, deps);
-registerZapTools(server, deps);
-registerSafetyTools(server, deps);
-// Utility tools
-registerUtilTools(server, deps);
+const server = new McpServer({ name: 'nostr-bray', version: '0.1.0' }, {
+    instructions: 'Always check whoami before posting or signing. Use social-feed or social-notifications to get event IDs and author pubkeys before calling social-reply or social-react. DMs default to NIP-17 gift wrap (most private); only use NIP-04 if the recipient requires it. For less common actions (encoding, encryption, ring signatures, blossom, groups, NIPs, key management, safety), use search-actions to discover them, then execute-action to run them.',
+});
+// Promoted tools are registered directly with the server (always visible to Claude).
+// Everything else goes to the catalog, discoverable via search-actions + execute-action.
+const PROMOTED = new Set([
+    'whoami', 'social-post', 'social-reply', 'social-feed',
+    'dm-send', 'dm-read', 'zap-send', 'zap-balance',
+    'identity-switch', 'relay-query',
+]);
+const catalog = new ActionCatalog();
+const proxy = createCatalogProxy(server, catalog, PROMOTED);
+// Register all tools — the proxy routes promoted to server, rest to catalog
+registerIdentityTools(proxy, deps);
+registerSocialTools(proxy, deps);
+registerTrustTools(proxy, deps);
+registerRelayTools(proxy, deps);
+registerZapTools(proxy, deps);
+registerSafetyTools(proxy, deps);
+registerUtilTools(proxy, deps);
+// Add search-actions and execute-action meta-tools to the real server
+catalog.registerMetaTools(server);
+console.error(`nostr-bray: ${PROMOTED.size} promoted tools + ${catalog.size} cataloged (${PROMOTED.size + catalog.size + 2} total)`);
 if (config.transport === 'stdio') {
     const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
     await server.connect(new StdioServerTransport());

package/dist/trust/handlers.d.ts

@@ -9,9 +9,11 @@ export interface AttestResult {
 }
 /** Create and publish a kind 31000 attestation */
 export declare function handleTrustAttest(ctx: IdentityContext, pool: RelayPool, args: {
-    type: string;
+    type?: string;
     identifier?: string;
     subject?: string;
+    assertionId?: string;
+    assertionRelay?: string;
     summary?: string;
     content?: string;
     expiration?: number;

package/dist/trust/handlers.js

@@ -6,10 +6,17 @@ import { toUnsignedEvent } from 'nsec-tree/event';
 import { decode } from 'nostr-tools/nip19';
 /** Create and publish a kind 31000 attestation */
 export async function handleTrustAttest(ctx, pool, args) {
+    if (!args.type && !args.assertionId) {
+        throw new Error('at least one of type or assertionId must be provided');
+    }
     const template = createAttestation({
         type: args.type,
         identifier: args.identifier,
         subject: args.subject,
+        assertion: args.assertionId ? {
+            id: args.assertionId,
+            relay: args.assertionRelay,
+        } : undefined,
         summary: args.summary,
         content: args.content,
         expiration: args.expiration,

package/dist/trust/tools.js

@@ -5,19 +5,45 @@ import { handleTrustRingProve, handleTrustRingVerify } from './ring.js';
 import { handleTrustSpokenChallenge, handleTrustSpokenVerify } from './spoken.js';
 export function registerTrustTools(server, deps) {
     server.registerTool('trust-attest', {
-        description: 'Create and publish a kind 31000 verifiable attestation (NIP-VA) as the active identity. An attestation is a signed statement about a subject (e.g. "I verify this pubkey belongs to Alice"). Warns if attesting from a derived persona instead of master. Use trust_read to find existing attestations, trust_revoke to revoke them.',
+        description: 'Verify someone else\'s claim by attesting to their assertion event. The subject publishes their claim as a Nostr event; you reference it and say "I verify this." The type is inherited from the referenced event. This is the recommended pattern — it puts the individual at the centre.',
         inputSchema: {
-            type: z.string().describe('Attestation type (e.g. "identity-verification", "endorsement")'),
-            identifier: z.string().optional().describe('D-tag identifier (hex pubkey or context string)'),
-            subject: z.string().optional().describe('Subject hex pubkey (for third-party attestations)'),
+            assertionId: hexId.describe('Event ID of the subject\'s assertion to verify'),
+            subject: hexId.optional().describe('Subject hex pubkey (auto-detected from assertion if omitted)'),
+            type: z.string().optional().describe('Explicit type override (usually inherited from the assertion)'),
+            summary: z.string().optional().describe('Human-readable summary of what was verified'),
+            content: z.string().optional().describe('Evidence payload (text or JSON)'),
+            expiration: z.number().optional().describe('Unix timestamp for attestation expiry'),
+            assertionRelay: z.string().optional().describe('Relay hint for the assertion event'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ assertionId, subject, type, summary, content, expiration, assertionRelay }) => {
+        const result = await handleTrustAttest(deps.ctx, deps.pool, {
+            assertionId, subject, type, summary, content, expiration, assertionRelay,
+        });
+        const response = {
+            id: result.event.id,
+            publish: result.publish,
+        };
+        if (result.warning)
+            response.warning = result.warning;
+        return {
+            content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
+        };
+    });
+    server.registerTool('trust-claim', {
+        description: 'Make a direct statement about another identity — an endorsement, review, vouch, or any attestor-originated claim. You define the type and subject. Use trust-attest instead if the subject has published their own assertion event.',
+        inputSchema: {
+            type: z.string().describe('Claim type (e.g. "endorsement", "vouch", "review")'),
+            subject: hexId.optional().describe('Subject hex pubkey (omit for self-declarations)'),
+            identifier: z.string().optional().describe('D-tag identifier (defaults to subject pubkey)'),
             summary: z.string().optional().describe('Human-readable summary'),
             content: z.string().optional().describe('Event content (text or JSON)'),
             expiration: z.number().optional().describe('Unix timestamp for attestation expiry'),
         },
-        annotations: { readOnlyHint: false, destructiveHint: true },
-    }, async ({ type, identifier, subject, summary, content, expiration }) => {
+        annotations: { readOnlyHint: false },
+    }, async ({ type, subject, identifier, summary, content, expiration }) => {
         const result = await handleTrustAttest(deps.ctx, deps.pool, {
-            type, identifier, subject, summary, content, expiration,
+            type, subject, identifier, summary, content, expiration,
         });
         const response = {
             id: result.event.id,
@@ -30,7 +56,7 @@ export function registerTrustTools(server, deps) {
         };
     });
     server.registerTool('trust-read', {
-        description: 'Read kind 31000 attestations from relays. Filter by subject, type, or attestor.',
+        description: 'Read kind 31000 attestations from relays. Filter by subject, type, or attestor. Works with both assertion-first (trust-attest) and direct claims (trust-claim).',
         inputSchema: {
             subject: hexId.optional().describe('Subject hex pubkey to filter by'),
             type: z.string().optional().describe('Attestation type to filter by'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nostr-bray",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "MCP server giving AI agents sovereign Nostr identities — key derivation, personas, attestations, duress detection, zaps",
   "type": "module",
   "main": "dist/index.js",
@@ -77,7 +77,7 @@
     "@forgesworn/shamir-words": "^1.0.4",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "canary-kit": "^2.6.2",
-    "nostr-attestations": "^2.1.0",
+    "nostr-attestations": "^2.2.0",
     "nostr-tools": "^2.23.3",
     "nsec-tree": "^1.4.1",
     "socks-proxy-agent": "^9.0.0",