nostr-bray 1.20.0 → 1.22.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/format.d.ts

@@ -10,8 +10,16 @@ export declare function formatContacts(contacts: Array<{
     relay?: string;
     petname?: string;
 }>): string;
+export declare function formatContactSearch(contacts: Array<{
+    pubkey: string;
+    name?: string;
+    displayName?: string;
+    nip05?: string;
+    petname?: string;
+}>): string;
 export declare function formatNotifications(notifications: any[]): string;
 export declare function formatFeed(events: any[]): string;
+export declare function formatConversation(dms: any[]): string;
 export declare function formatDms(dms: any[]): string;
 export declare function formatRelays(relays: {
     read: string[];

package/dist/format.js

@@ -58,6 +58,23 @@ export function formatContacts(contacts) {
     });
     return `${contacts.length} contacts:\n${lines.join('\n')}`;
 }
+export function formatContactSearch(contacts) {
+    if (contacts.length === 0)
+        return 'No matching contacts.';
+    const lines = contacts.map(c => {
+        const label = c.displayName || c.name || c.petname || c.pubkey.slice(0, 12) + '...';
+        const parts = [label];
+        if (c.name && c.displayName && c.name !== c.displayName)
+            parts.push(`(@${c.name})`);
+        else if (c.name && !c.displayName)
+            parts.push(`(@${c.name})`);
+        if (c.nip05)
+            parts.push(`[${c.nip05}]`);
+        parts.push(c.pubkey.slice(0, 12) + '...');
+        return parts.join('  ');
+    });
+    return `${contacts.length} match${contacts.length !== 1 ? 'es' : ''}:\n${lines.join('\n')}`;
+}
 export function formatNotifications(notifications) {
     if (notifications.length === 0)
         return 'No notifications.';
@@ -88,6 +105,17 @@ export function formatFeed(events) {
         return `${author}  ${time}\n  ${e.content?.slice(0, 200)}\n`;
     }).join('\n');
 }
+export function formatConversation(dms) {
+    if (dms.length === 0)
+        return 'No messages in this conversation.';
+    return dms.map(dm => {
+        const time = new Date(dm.createdAt * 1000).toLocaleString();
+        const from = dm.from?.slice(0, 12) + '...';
+        if (!dm.decrypted)
+            return `✗ ${from}  Could not decrypt  (${time})`;
+        return `${from}  ${time}\n  ${dm.content}`;
+    }).join('\n\n');
+}
 export function formatDms(dms) {
     if (dms.length === 0)
         return 'No messages.';

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/relay-pool.d.ts

@@ -26,6 +26,8 @@ export declare class RelayPool {
     getRelays(npub: string): RelaySet;
     /** Publish event to write relays for the given identity */
     publish(npub: string, event: NostrEvent): Promise<PublishResult>;
+    /** Publish event to explicit relay URLs (not identity-bound) */
+    publishDirect(relays: string[], event: NostrEvent): Promise<PublishResult>;
     /** One-shot query from read relays for the given identity */
     query(npub: string, filter: Filter): Promise<NostrEvent[]>;
     /** One-shot query against explicit relay URLs (not identity-bound) */

package/dist/relay-pool.js

@@ -97,6 +97,35 @@ export class RelayPool {
             errors,
         };
     }
+    /** Publish event to explicit relay URLs (not identity-bound) */
+    async publishDirect(relays, event) {
+        const pool = await this.poolReady;
+        if (relays.length === 0) {
+            return { success: false, accepted: [], rejected: [], errors: ['no relays specified'] };
+        }
+        const promises = pool.publish(relays, event);
+        const accepted = [];
+        const rejected = [];
+        const errors = [];
+        const results = await Promise.allSettled(promises);
+        for (let i = 0; i < results.length; i++) {
+            const result = results[i];
+            const url = relays[i] ?? `relay-${i}`;
+            if (result.status === 'fulfilled') {
+                accepted.push(url);
+            }
+            else {
+                rejected.push(url);
+                errors.push(`${url}: ${result.reason}`);
+            }
+        }
+        return {
+            success: accepted.length === relays.length,
+            accepted,
+            rejected,
+            errors,
+        };
+    }
     /** One-shot query from read relays for the given identity */
     async query(npub, filter) {
         const pool = await this.poolReady;

package/dist/social/dm.d.ts

@@ -1,11 +1,14 @@
 import type { Event as NostrEvent } from 'nostr-tools';
 import type { IdentityContext } from '../context.js';
 import type { RelayPool } from '../relay-pool.js';
+import type { Nip65Manager } from '../nip65.js';
 import type { PublishResult } from '../types.js';
 export interface DmSendResult {
     event: NostrEvent;
+    senderCopy?: NostrEvent;
     protocol: 'nip17' | 'nip04-deprecated';
     publish: PublishResult;
+    senderCopyPublish?: PublishResult;
 }
 export interface DmReadEntry {
     id: string;
@@ -23,6 +26,14 @@ export declare function handleDmSend(ctx: IdentityContext, pool: RelayPool, args
     nip04?: boolean;
     nip04Enabled?: boolean;
     recipientRelay?: string;
+    nip65?: Nip65Manager;
 }): Promise<DmSendResult>;
 /** Read DMs addressed to the active identity */
-export declare function handleDmRead(ctx: IdentityContext, pool: RelayPool): Promise<DmReadEntry[]>;
+export declare function handleDmRead(ctx: IdentityContext, pool: RelayPool, args?: {
+    limit?: number;
+}): Promise<DmReadEntry[]>;
+/** Read DM conversation with a specific pubkey — filters to messages from that person only */
+export declare function handleDmConversation(ctx: IdentityContext, pool: RelayPool, args: {
+    withPubkeyHex: string;
+    limit?: number;
+}): Promise<DmReadEntry[]>;

package/dist/social/dm.js

@@ -1,6 +1,6 @@
 import { wrapEvent } from 'nostr-tools/nip17';
 import * as nip04 from 'nostr-tools/nip04';
-import { decode } from 'nostr-tools/nip19';
+import { decode, npubEncode } from 'nostr-tools/nip19';
 /** Send a DM. Uses NIP-17 gift wrap by default. NIP-04 only if explicitly requested and enabled. */
 export async function handleDmSend(ctx, pool, args) {
     if (args.nip04) {
@@ -21,19 +21,58 @@ export async function handleDmSend(ctx, pool, args) {
         return { event, protocol: 'nip04-deprecated', publish };
     }
     // NIP-17 gift-wrapped DM (default)
-    const event = wrapEvent(ctx.activePrivateKey, { publicKey: args.recipientPubkeyHex, relayUrl: args.recipientRelay }, args.message);
-    const publish = await pool.publish(ctx.activeNpub, event);
-    return { event, protocol: 'nip17', publish };
+    // Look up recipient's inbox relays via NIP-65 for proper delivery
+    let recipientRelays = [];
+    if (args.nip65) {
+        try {
+            const recipientNpub = npubEncode(args.recipientPubkeyHex);
+            const relaySet = await args.nip65.loadForIdentity(recipientNpub, args.recipientPubkeyHex);
+            recipientRelays = relaySet.read; // recipient reads from their read relays
+        }
+        catch { /* fall back to sender's relays */ }
+    }
+    const recipientRelayHint = args.recipientRelay ?? recipientRelays[0];
+    // Wrap for recipient
+    const event = wrapEvent(ctx.activePrivateKey, { publicKey: args.recipientPubkeyHex, relayUrl: recipientRelayHint }, args.message);
+    // Publish to recipient's relays (primary) and sender's relays (fallback)
+    let publish;
+    if (recipientRelays.length > 0) {
+        // Merge recipient read relays with sender write relays for best coverage
+        const senderRelays = pool.getRelays(ctx.activeNpub).write;
+        const allRelays = [...new Set([...recipientRelays, ...senderRelays])];
+        publish = await pool.publishDirect(allRelays, event);
+    }
+    else {
+        publish = await pool.publish(ctx.activeNpub, event);
+    }
+    // Sender copy — wrap the same message addressed to ourselves so our client shows sent DMs.
+    // The inner rumor's p-tag (set by wrapEvent) points to us, but clients use the
+    // outer gift-wrap's p-tag to route, and the inner content to display.
+    const senderHex = decode(ctx.activeNpub).data;
+    const senderCopy = wrapEvent(ctx.activePrivateKey, { publicKey: senderHex, relayUrl: recipientRelayHint }, args.message);
+    const senderCopyPublish = await pool.publish(ctx.activeNpub, senderCopy);
+    return { event, senderCopy, protocol: 'nip17', publish, senderCopyPublish };
 }
 /** Read DMs addressed to the active identity */
-export async function handleDmRead(ctx, pool) {
+export async function handleDmRead(ctx, pool, args) {
     // Fetch gift wraps (kind 1059) and legacy DMs (kind 4) addressed to us
     const activeHex = decode(ctx.activeNpub).data;
     const events = await pool.query(ctx.activeNpub, {
         kinds: [1059, 4],
         '#p': [activeHex],
-        limit: 50,
+        limit: args?.limit ?? 50,
     });
+    return decryptDmEvents(ctx, events);
+}
+/** Read DM conversation with a specific pubkey — filters to messages from that person only */
+export async function handleDmConversation(ctx, pool, args) {
+    const allMessages = await handleDmRead(ctx, pool, { limit: args.limit ?? 100 });
+    return allMessages
+        .filter(m => m.from === args.withPubkeyHex)
+        .sort((a, b) => a.createdAt - b.createdAt); // chronological for conversation view
+}
+/** Decrypt a list of DM events (kind 1059 gift wrap + kind 4 legacy) */
+async function decryptDmEvents(ctx, events) {
     const results = [];
     for (const event of events) {
         if (event.kind === 1059) {

package/dist/social/handlers.d.ts

@@ -56,8 +56,15 @@ export interface Contact {
     relay?: string;
     petname?: string;
 }
+export interface EnrichedContact extends Contact {
+    name?: string;
+    displayName?: string;
+    nip05?: string;
+}
 /** Fetch the kind 3 contact list for a pubkey */
 export declare function handleContactsGet(pool: RelayPool, npub: string, pubkeyHex: string): Promise<Contact[]>;
+/** Search contacts by name/display_name/nip05 — resolves profiles in a single batch query */
+export declare function handleContactsSearch(pool: RelayPool, npub: string, pubkeyHex: string, query: string): Promise<EnrichedContact[]>;
 /** Follow a pubkey — fetches current contacts, adds, publishes new kind 3 */
 export declare function handleContactsFollow(ctx: IdentityContext, pool: RelayPool, args: {
     pubkeyHex: string;

package/dist/social/handlers.js

@@ -149,6 +149,59 @@ export async function handleContactsGet(pool, npub, pubkeyHex) {
         petname: t[3] || undefined,
     }));
 }
+/** Batch-fetch kind 0 profiles for a list of pubkeys, returning the newest per author */
+async function batchFetchProfiles(pool, npub, pubkeys) {
+    if (pubkeys.length === 0)
+        return new Map();
+    const events = await pool.query(npub, {
+        kinds: [0],
+        authors: pubkeys,
+    });
+    // Keep only the newest kind 0 per pubkey
+    const best = new Map();
+    for (const ev of events) {
+        const prev = best.get(ev.pubkey);
+        if (!prev || ev.created_at > prev.created_at) {
+            best.set(ev.pubkey, ev);
+        }
+    }
+    const profiles = new Map();
+    for (const [pk, ev] of best) {
+        try {
+            profiles.set(pk, JSON.parse(ev.content));
+        }
+        catch { /* skip unparseable */ }
+    }
+    return profiles;
+}
+/** Search contacts by name/display_name/nip05 — resolves profiles in a single batch query */
+export async function handleContactsSearch(pool, npub, pubkeyHex, query) {
+    const contacts = await handleContactsGet(pool, npub, pubkeyHex);
+    if (contacts.length === 0)
+        return [];
+    const profiles = await batchFetchProfiles(pool, npub, contacts.map(c => c.pubkey));
+    const q = query.toLowerCase();
+    const results = [];
+    for (const contact of contacts) {
+        const profile = profiles.get(contact.pubkey);
+        const name = profile?.name ?? '';
+        const displayName = profile?.display_name ?? '';
+        const nip05 = profile?.nip05 ?? '';
+        const petname = contact.petname ?? '';
+        if (name.toLowerCase().includes(q) ||
+            displayName.toLowerCase().includes(q) ||
+            nip05.toLowerCase().includes(q) ||
+            petname.toLowerCase().includes(q)) {
+            results.push({
+                ...contact,
+                name: name || undefined,
+                displayName: displayName || undefined,
+                nip05: nip05 || undefined,
+            });
+        }
+    }
+    return results;
+}
 /** Follow a pubkey — fetches current contacts, adds, publishes new kind 3 */
 export async function handleContactsFollow(ctx, pool, args) {
     // Fetch existing contacts

package/dist/social/tools.js

@@ -2,8 +2,8 @@ import { z } from 'zod';
 import { hexId } from '../validation.js';
 import { toolResponse } from '../tool-response.js';
 import * as fmt from '../format.js';
-import { handleSocialPost, handleSocialReply, handleSocialReact, handleSocialProfileGet, handleSocialProfileSet, handleContactsGet, handleContactsFollow, handleContactsUnfollow, handleSocialDelete, handleSocialRepost, } from './handlers.js';
-import { handleDmSend, handleDmRead } from './dm.js';
+import { handleSocialPost, handleSocialReply, handleSocialReact, handleSocialProfileGet, handleSocialProfileSet, handleContactsGet, handleContactsSearch, handleContactsFollow, handleContactsUnfollow, handleSocialDelete, handleSocialRepost, } from './handlers.js';
+import { handleDmSend, handleDmRead, handleDmConversation } from './dm.js';
 import { handleNotifications, handleFeed } from './notifications.js';
 import { handleNipPublish, handleNipRead } from './nips.js';
 import { handleBlossomUpload, handleBlossomList, handleBlossomDelete } from './blossom.js';
@@ -151,12 +151,14 @@ export function registerSocialTools(server, deps) {
             nip04,
             nip04Enabled: false, // TODO: wire from config
             recipientRelay,
+            nip65: deps.nip65,
         });
         return {
             content: [{ type: 'text', text: JSON.stringify({
                         protocol: result.protocol,
                         id: result.event.id,
                         publish: result.publish,
+                        senderCopyPublish: result.senderCopyPublish,
                     }, null, 2) }],
         };
     });
@@ -170,6 +172,63 @@ export function registerSocialTools(server, deps) {
         const messages = await handleDmRead(deps.ctx, deps.pool);
         return toolResponse(messages, output, fmt.formatDms);
     });
+    server.registerTool('dm-by-name', {
+        description: 'Send an encrypted DM to a contact by name — no pubkey needed. Searches your contacts, finds the match, and sends the message. Returns an error if zero or multiple matches are found (use contacts-search to disambiguate).',
+        inputSchema: {
+            name: z.string().describe('Contact name to search for (matches name, display_name, nip05 — case insensitive)'),
+            message: z.string().describe('Message text'),
+            nip04: z.boolean().default(false).describe('Use legacy NIP-04 instead of NIP-17'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, async ({ name, message, nip04 }) => {
+        // Search contacts for the name
+        const matches = await handleContactsSearch(deps.pool, deps.ctx.activeNpub, deps.ctx.activePublicKeyHex, name);
+        if (matches.length === 0) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            error: `No contact found matching "${name}". Use contacts-search to check your contacts.`,
+                        }, null, 2) }],
+            };
+        }
+        if (matches.length > 1) {
+            const names = matches.map(m => m.displayName || m.name || m.pubkey.slice(0, 12) + '...');
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            error: `Multiple contacts match "${name}": ${names.join(', ')}. Be more specific or use dm-send with the exact pubkey.`,
+                            matches: matches.map(m => ({ pubkey: m.pubkey, name: m.name, displayName: m.displayName })),
+                        }, null, 2) }],
+            };
+        }
+        const recipient = matches[0];
+        const result = await handleDmSend(deps.ctx, deps.pool, {
+            recipientPubkeyHex: recipient.pubkey,
+            message,
+            nip04,
+            nip04Enabled: false,
+            nip65: deps.nip65,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify({
+                        sentTo: recipient.displayName || recipient.name || recipient.pubkey.slice(0, 12) + '...',
+                        recipientPubkey: recipient.pubkey,
+                        protocol: result.protocol,
+                        id: result.event.id,
+                        publish: result.publish,
+                    }, null, 2) }],
+        };
+    });
+    server.registerTool('dm-conversation', {
+        description: 'Read DM conversation with a specific person. Filters to messages from one pubkey and shows them in chronological order. Use contacts-search first if you only know the name.',
+        inputSchema: {
+            pubkeyHex: hexId.describe('Hex pubkey to show conversation with'),
+            limit: z.number().int().min(1).max(200).default(50).describe('Max messages to fetch before filtering'),
+            output: z.enum(['json', 'human']).default('human').describe('Response format'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ pubkeyHex, limit, output }) => {
+        const messages = await handleDmConversation(deps.ctx, deps.pool, { withPubkeyHex: pubkeyHex, limit });
+        return toolResponse(messages, output, fmt.formatConversation);
+    });
     server.registerTool('social-notifications', {
         description: 'Fetch notifications for the active identity — mentions, replies, reactions, and zap receipts.',
         inputSchema: {
@@ -195,6 +254,74 @@ export function registerSocialTools(server, deps) {
         const feed = await handleFeed(deps.ctx, deps.pool, { authors, since, limit });
         return toolResponse(feed, output, fmt.formatFeed);
     });
+    server.registerTool('feed-by-name', {
+        description: 'Fetch recent posts by a contact, searching by name instead of pubkey. Returns an error if zero or multiple contacts match.',
+        inputSchema: {
+            name: z.string().describe('Contact name to search for (case insensitive)'),
+            since: z.number().optional().describe('Unix timestamp — only fetch posts after this time'),
+            limit: z.number().int().min(1).max(100).default(20).describe('Max posts to return'),
+            output: z.enum(['json', 'human']).default('human').describe('Response format'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ name, since, limit, output }) => {
+        const matches = await handleContactsSearch(deps.pool, deps.ctx.activeNpub, deps.ctx.activePublicKeyHex, name);
+        if (matches.length === 0) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            error: `No contact found matching "${name}".`,
+                        }, null, 2) }],
+            };
+        }
+        if (matches.length > 1) {
+            const names = matches.map(m => m.displayName || m.name || m.pubkey.slice(0, 12) + '...');
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            error: `Multiple contacts match "${name}": ${names.join(', ')}. Be more specific.`,
+                            matches: matches.map(m => ({ pubkey: m.pubkey, name: m.name, displayName: m.displayName })),
+                        }, null, 2) }],
+            };
+        }
+        const contact = matches[0];
+        const feed = await handleFeed(deps.ctx, deps.pool, { authors: [contact.pubkey], since, limit });
+        return toolResponse({ contact: { name: contact.displayName || contact.name, pubkey: contact.pubkey }, posts: feed }, output, (data) => {
+            const header = `Posts by ${data.contact.name ?? data.contact.pubkey.slice(0, 12) + '...'}:`;
+            if (data.posts.length === 0)
+                return `${header}\n  No posts found.`;
+            return `${header}\n${fmt.formatFeed(data.posts)}`;
+        });
+    });
+    server.registerTool('profile-by-name', {
+        description: 'Look up a contact\'s full profile by name — no pubkey needed. Searches your contacts and returns the kind 0 profile for the match.',
+        inputSchema: {
+            name: z.string().describe('Contact name to search for (case insensitive)'),
+            output: z.enum(['json', 'human']).default('human').describe('Response format'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ name, output }) => {
+        const matches = await handleContactsSearch(deps.pool, deps.ctx.activeNpub, deps.ctx.activePublicKeyHex, name);
+        if (matches.length === 0) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            error: `No contact found matching "${name}".`,
+                        }, null, 2) }],
+            };
+        }
+        if (matches.length > 1) {
+            const names = matches.map(m => m.displayName || m.name || m.pubkey.slice(0, 12) + '...');
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            error: `Multiple contacts match "${name}": ${names.join(', ')}. Be more specific.`,
+                            matches: matches.map(m => ({ pubkey: m.pubkey, name: m.name, displayName: m.displayName })),
+                        }, null, 2) }],
+            };
+        }
+        const contact = matches[0];
+        const profile = await handleSocialProfileGet(deps.pool, deps.ctx.activeNpub, contact.pubkey);
+        return toolResponse({ ...profile, _pubkey: contact.pubkey }, output, (data) => {
+            const { _pubkey, ...fields } = data;
+            return `Pubkey: ${_pubkey}\n${fmt.formatProfile(fields)}`;
+        });
+    });
     server.registerTool('contacts-get', {
         description: 'Fetch the contact list (kind 3 follows) for a pubkey. Returns pubkeys, relay hints, and petnames.',
         inputSchema: {
@@ -207,6 +334,21 @@ export function registerSocialTools(server, deps) {
         const contacts = await handleContactsGet(deps.pool, npub ?? deps.ctx.activeNpub, pubkeyHex);
         return toolResponse(contacts, output, fmt.formatContacts);
     });
+    server.registerTool('contacts-search', {
+        description: 'Search your contacts by name, display name, or NIP-05. Resolves profiles in one batch — much faster than fetching each individually. Use this to find a contact when you know their name but not their pubkey.',
+        inputSchema: {
+            query: z.string().describe('Search string (matches name, display_name, nip05, petname — case insensitive)'),
+            pubkeyHex: hexId.optional().describe('Hex pubkey whose contacts to search (defaults to active identity)'),
+            npub: z.string().optional().describe('Bech32 npub for relay routing (defaults to active identity)'),
+            output: z.enum(['json', 'human']).default('human').describe('Response format'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ query, pubkeyHex, npub, output }) => {
+        const resolvedNpub = npub ?? deps.ctx.activeNpub;
+        const resolvedPubkey = pubkeyHex ?? deps.ctx.activePublicKeyHex;
+        const results = await handleContactsSearch(deps.pool, resolvedNpub, resolvedPubkey, query);
+        return toolResponse(results, output, fmt.formatContactSearch);
+    });
     server.registerTool('contacts-follow', {
         description: 'Follow a Nostr pubkey. Fetches current contact list, adds the pubkey, publishes updated kind 3.',
         inputSchema: {

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.22.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",