nostr-bray 1.8.0 → 1.9.1

package/dist/cli.js

@@ -652,6 +652,14 @@ async function shell() {
             continue;
         }
         const shellArgs = parseShellLine(trimmed);
+        // Per-command help in shell
+        if (shellArgs.includes('--help') && shellArgs[0]) {
+            const h = getCommandHelp(shellArgs[0]);
+            if (h) {
+                console.log(h);
+                continue;
+            }
+        }
         try {
             await run(shellArgs);
         }

package/dist/context.d.ts

@@ -10,8 +10,10 @@ export declare class IdentityContext {
     private activeEntry;
     private maxCacheSize;
     constructor(secretKey: string, format: 'nsec' | 'hex' | 'mnemonic', opts?: ContextOptions);
-    /** Current active identity's npub */
+    /** Current active identity's npub (bech32) */
     get activeNpub(): string;
+    /** Current active identity's hex public key — use this in relay filters */
+    get activePublicKeyHex(): string;
     /** Derive a child identity by purpose and index */
     derive(purpose: string, index: number): PublicIdentity;
     /** Derive a named persona */

package/dist/context.js

@@ -30,10 +30,14 @@ export class IdentityContext {
         };
         this.activeEntry = this.masterEntry;
     }
-    /** Current active identity's npub */
+    /** Current active identity's npub (bech32) */
     get activeNpub() {
         return this.activeEntry.identity.npub;
     }
+    /** Current active identity's hex public key — use this in relay filters */
+    get activePublicKeyHex() {
+        return Buffer.from(this.activeEntry.identity.publicKey).toString('hex');
+    }
     /** Derive a child identity by purpose and index */
     derive(purpose, index) {
         // Return from cache if already derived

package/dist/identity/tools.js

@@ -5,7 +5,7 @@ import { hexId } from '../validation.js';
 import { handleIdentityBackup, handleIdentityRestore, handleIdentityMigrate } from './migration.js';
 export function registerIdentityTools(server, deps) {
     server.registerTool('identity_create', {
-        description: 'Generate a fresh Nostr identity with a BIP-39 mnemonic seed. Returns the master npub and mnemonic for backup.',
+        description: 'Generate a fresh Nostr identity with a BIP-39 mnemonic seed. Returns { npub, mnemonic }. Store the mnemonic securely — it will not be shown again. Use this when the user needs a brand new identity unrelated to the current one.',
         annotations: { readOnlyHint: false },
     }, async () => {
         const result = handleIdentityCreate();
@@ -14,7 +14,7 @@ export function registerIdentityTools(server, deps) {
         };
     });
     server.registerTool('identity_derive', {
-        description: 'Derive a child Nostr identity from the active tree root. Returns the new npub.',
+        description: 'Derive a child Nostr identity from the master key by purpose and index. Deterministic — same inputs always produce the same npub. Returns { npub, purpose, index }. Use identity_switch after deriving to operate as the new identity.',
         inputSchema: {
             purpose: z.string().describe('Purpose string for derivation (e.g. "messaging", "signing")'),
             index: z.number().int().min(0).default(0).describe('Derivation index (default 0)'),
@@ -27,7 +27,7 @@ export function registerIdentityTools(server, deps) {
         };
     });
     server.registerTool('identity_derive_persona', {
-        description: 'Derive a named persona identity (e.g. "work", "personal", "anonymous"). Returns the new npub.',
+        description: 'Derive a named persona (e.g. "work", "personal", "anonymous"). Like identity_derive but uses a human-readable name. Returns { npub, personaName, index }. Follow with identity_switch to activate.',
         inputSchema: {
             name: z.string().describe('Persona name (e.g. "work", "personal", "anonymous")'),
             index: z.number().int().min(0).default(0).describe('Derivation index (default 0)'),
@@ -40,7 +40,7 @@ export function registerIdentityTools(server, deps) {
         };
     });
     server.registerTool('identity_switch', {
-        description: 'Switch the active Nostr identity. All subsequent tools operate as the new identity. Use "master" to return to root.',
+        description: 'Switch the active Nostr identity. ALL subsequent tool calls will sign events and query relays as the new identity. Pass "master" to return to root. Returns { npub } of the now-active identity. This is the key tool for multi-persona workflows.',
         inputSchema: {
             target: z.string().describe('Purpose, persona name, or "master" to switch to'),
             index: z.number().int().min(0).optional().describe('Derivation index (if switching by purpose)'),
@@ -53,7 +53,7 @@ export function registerIdentityTools(server, deps) {
         };
     });
     server.registerTool('identity_list', {
-        description: 'List all known Nostr identities. Returns npub, purpose, and persona name for each. Never includes private keys.',
+        description: 'List all known identities (master + all derived). Returns array of { npub, purpose, index, personaName }. Never includes private keys. Use this to see what identities are available before switching.',
         annotations: { readOnlyHint: true },
     }, async () => {
         const result = handleIdentityList(deps.ctx);
@@ -62,7 +62,7 @@ export function registerIdentityTools(server, deps) {
         };
     });
     server.registerTool('identity_prove', {
-        description: 'Create a cryptographic linkage proof between the master key and the active identity. Defaults to blind proof (no purpose/index revealed).',
+        description: 'Create a cryptographic linkage proof between the master key and the active identity. "blind" (default) proves they share a master without revealing how the child was derived. "full" also reveals the purpose and index. Returns a LinkageProof object that can be verified by anyone with nsec-tree. Use trust_proof_publish to make it permanent on relays.',
         inputSchema: {
             mode: z.enum(['blind', 'full']).default('blind').describe('Proof mode: "blind" hides derivation path, "full" reveals purpose and index'),
         },
@@ -74,7 +74,7 @@ export function registerIdentityTools(server, deps) {
         };
     });
     server.registerTool('identity_backup_shamir', {
-        description: 'Split the master secret into Shamir shard files. Shard content is written to disk — never returned in the response.',
+        description: 'Split the active identity\'s private key into Shamir shard files using threshold secret sharing. Any "threshold" shards can reconstruct the key. Files written with 0600 permissions via atomic rename. Returns file paths only — shard content never appears in the response.',
         inputSchema: {
             threshold: z.number().int().min(2).describe('Minimum shards needed to reconstruct'),
             shares: z.number().int().min(2).describe('Total number of shards to create'),

package/dist/relay/handlers.js

@@ -18,7 +18,7 @@ export async function handleRelaySet(ctx, pool, args) {
     // Check for existing relay list
     const existing = await pool.query(ctx.activeNpub, {
         kinds: [10002],
-        authors: [ctx.activeNpub],
+        authors: [ctx.activePublicKeyHex],
     });
     // Build r-tags
     const tags = args.relays.map(r => {

package/dist/social/handlers.js

@@ -90,7 +90,7 @@ export async function handleSocialProfileSet(ctx, pool, args) {
     // Check for existing profile
     const existing = await pool.query(ctx.activeNpub, {
         kinds: [0],
-        authors: [ctx.activeNpub], // simplified — in production, use hex pubkey
+        authors: [ctx.activePublicKeyHex], // simplified — in production, use hex pubkey
     });
     if (existing.length > 0 && !args.confirm) {
         // Build diff
@@ -154,7 +154,7 @@ export async function handleContactsFollow(ctx, pool, args) {
     // Fetch existing contacts
     const existing = await pool.query(ctx.activeNpub, {
         kinds: [3],
-        authors: [ctx.activeNpub],
+        authors: [ctx.activePublicKeyHex],
     });
     let tags = [];
     if (existing.length > 0) {
@@ -187,7 +187,7 @@ export async function handleContactsFollow(ctx, pool, args) {
 export async function handleContactsUnfollow(ctx, pool, args) {
     const existing = await pool.query(ctx.activeNpub, {
         kinds: [3],
-        authors: [ctx.activeNpub],
+        authors: [ctx.activePublicKeyHex],
     });
     let tags = [];
     if (existing.length > 0) {

package/dist/social/notifications.js

@@ -1,8 +1,10 @@
+import { decode } from 'nostr-tools/nip19';
 /** Fetch notifications (mentions, replies, reactions, zaps) for the active identity */
 export async function handleNotifications(ctx, pool, opts) {
+    const activeHex = decode(ctx.activeNpub).data;
     const events = await pool.query(ctx.activeNpub, {
         kinds: [1, 7, 9735],
-        '#p': [ctx.activeNpub],
+        '#p': [activeHex],
         limit: opts?.limit ?? 50,
         ...(opts?.since ? { since: opts.since } : {}),
     });

package/dist/social/tools.js

@@ -8,7 +8,7 @@ import { handleBlossomUpload, handleBlossomList, handleBlossomDelete } from './b
 import { handleGroupInfo, handleGroupChat, handleGroupSend, handleGroupMembers } from './groups.js';
 export function registerSocialTools(server, deps) {
     server.registerTool('social_post', {
-        description: 'Post a text note (kind 1) as the active identity. Returns the signed event.',
+        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.',
         inputSchema: {
             content: z.string().describe('Text content of the note'),
         },
@@ -24,7 +24,7 @@ export function registerSocialTools(server, deps) {
         };
     });
     server.registerTool('social_reply', {
-        description: 'Reply to a Nostr event (kind 1 with e-tag and p-tag) as the active identity.',
+        description: 'Reply to a Nostr event (kind 1) with correct threading tags. You need the event ID and the author\'s pubkey — get these from social_feed or social_notifications.',
         inputSchema: {
             content: z.string().describe('Reply text'),
             replyTo: hexId.describe('Event ID being replied to (hex)'),
@@ -42,7 +42,7 @@ export function registerSocialTools(server, deps) {
         };
     });
     server.registerTool('social_react', {
-        description: 'React to a Nostr event (kind 7) as the active identity. Default reaction is "+".',
+        description: 'React to a Nostr event (kind 7). Pass "+" for like, or any emoji (🤙, ❤️, 🔥). You need the event ID and author pubkey.',
         inputSchema: {
             eventId: hexId.describe('Event ID to react to (hex)'),
             eventPubkey: hexId.describe('Pubkey of the event author (hex)'),
@@ -135,7 +135,7 @@ export function registerSocialTools(server, deps) {
         };
     });
     server.registerTool('dm_send', {
-        description: 'Send a direct message to a Nostr pubkey. Uses NIP-17 gift wrap by default. Set nip04: true for legacy NIP-04 (requires NIP04_ENABLED).',
+        description: 'Send an encrypted direct message. Default: NIP-17 gift wrap (most private — sender identity hidden behind ephemeral key). Set nip04: true for legacy NIP-04 (only if NIP04_ENABLED=1). Returns { protocol, id, publish }.',
         inputSchema: {
             recipientPubkeyHex: hexId.describe('Recipient hex pubkey'),
             message: z.string().describe('Message text'),
@@ -160,7 +160,7 @@ export function registerSocialTools(server, deps) {
         };
     });
     server.registerTool('dm_read', {
-        description: 'Read direct messages addressed to the active identity. Decrypts NIP-17 and NIP-04 messages.',
+        description: 'Read direct messages addressed to the active identity. Decrypts both NIP-17 (gift wrap) and NIP-04 (legacy). Each message includes { from, content, protocol, decrypted }. Gracefully handles decryption failures without crashing.',
         annotations: { readOnlyHint: true },
     }, async () => {
         const messages = await handleDmRead(deps.ctx, deps.pool);

package/dist/trust/tools.js

@@ -5,7 +5,7 @@ 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 as the active identity.',
+        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.',
         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)'),
@@ -124,7 +124,7 @@ export function registerTrustTools(server, deps) {
         };
     });
     server.registerTool('trust_ring_prove', {
-        description: 'Create a ring signature proving anonymous membership in a group of public keys.',
+        description: 'Create a ring signature proving anonymous group membership. A verifier can confirm "someone in this ring signed this" but cannot determine who. The active identity must be one of the pubkeys in the ring. Returns kind 30078 event with the signature.',
         inputSchema: {
             ring: z.array(hexId).describe('Hex x-only public keys of ring members (must include active identity)'),
             attestationType: z.string().describe('Attestation type context for the canonical message'),

package/dist/zap/handlers.js

@@ -48,9 +48,11 @@ function decryptNwcResponse(conn, event) {
 }
 /** Parse zap receipts (kind 9735) for the active identity */
 export async function handleZapReceipts(ctx, pool, opts) {
+    const { decode } = await import('nostr-tools/nip19');
+    const activeHex = decode(ctx.activeNpub).data;
     const events = await pool.query(ctx.activeNpub, {
         kinds: [9735],
-        '#p': [ctx.activeNpub],
+        '#p': [activeHex],
         limit: opts?.limit ?? 20,
         ...(opts?.since ? { since: opts.since } : {}),
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nostr-bray",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "MCP server giving AI agents sovereign Nostr identities — key derivation, personas, attestations, duress detection, zaps",
   "type": "module",
   "main": "dist/index.js",