nostr-bray 0.0.0-development

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeSworn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# nostr-bray
+
+> Sovereign Nostr identities for AI agents
+
+[![CI](https://github.com/forgesworn/bray/actions/workflows/ci.yml/badge.svg)](https://github.com/forgesworn/bray/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/nostr-bray)](https://www.npmjs.com/package/nostr-bray)
+[![licence](https://img.shields.io/npm/l/nostr-bray)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ESM-blue)](./tsconfig.json)
+
+An MCP server that gives AI agents a full Nostr identity — not just a key pair, but a hierarchical identity tree with personas, attestations, ring signatures, encrypted DMs, and duress detection. 44 tools across 7 groups.
+
+## The Problem
+
+AI agents interacting with Nostr today are handed a single key pair with no separation of concerns. One compromised session leaks everything. There is no way to rotate keys, prove identity links, or maintain separate personas for different contexts.
+
+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.
+
+## Quick Start
+
+```json
+{
+  "mcpServers": {
+    "nostr": {
+      "command": "npx",
+      "args": ["nostr-bray"],
+      "env": {
+        "NOSTR_SECRET_KEY": "nsec1...",
+        "NOSTR_RELAYS": "wss://relay.damus.io,wss://nos.lol"
+      }
+    }
+  }
+}
+```
+
+Or with a secret file (recommended):
+
+```json
+{
+  "mcpServers": {
+    "nostr": {
+      "command": "npx",
+      "args": ["nostr-bray"],
+      "env": {
+        "NOSTR_SECRET_KEY_FILE": "/path/to/secret.key",
+        "NOSTR_RELAYS": "wss://relay.damus.io,wss://nos.lol"
+      }
+    }
+  }
+}
+```
+
+## Tool Groups
+
+### Identity (11 tools)
+
+| Tool | Description |
+|------|-------------|
+| `identity_create` | Generate a fresh identity with BIP-39 mnemonic |
+| `identity_derive` | Derive a child identity by purpose and index |
+| `identity_derive_persona` | Derive a named persona (work, personal, anonymous) |
+| `identity_switch` | Switch active identity — all tools operate as the new identity |
+| `identity_list` | List all known identities (public info only) |
+| `identity_prove` | Create blind/full linkage proof |
+| `identity_backup_shamir` | Split master secret into Shamir shard files |
+| `identity_restore_shamir` | Reconstruct secret from shard files |
+| `identity_backup` | Fetch profile, contacts, relay list as portable bundle |
+| `identity_restore` | Re-sign migratable events under the active identity |
+| `identity_migrate` | Full migration with preview, confirmation, and linkage proof |
+
+### Social (9 tools)
+
+| Tool | Description |
+|------|-------------|
+| `social_post` | Post a text note (kind 1) |
+| `social_reply` | Reply with correct e-tag and p-tag threading |
+| `social_react` | React to an event (kind 7) |
+| `social_profile_get` | Fetch and parse a kind 0 profile |
+| `social_profile_set` | Set profile with overwrite safety guard |
+| `dm_send` | Send encrypted DM (NIP-17 default, NIP-04 opt-in) |
+| `dm_read` | Read and decrypt received DMs |
+| `social_notifications` | Fetch mentions, replies, reactions, zap receipts |
+| `social_feed` | Fetch kind 1 text note feed |
+
+### Trust (10 tools)
+
+| Tool | Description |
+|------|-------------|
+| `trust_attest` | Create kind 31000 verifiable attestation |
+| `trust_read` | Read attestations by subject/type/attestor |
+| `trust_verify` | Validate attestation structure |
+| `trust_revoke` | Revoke an attestation (identity check) |
+| `trust_request` | Send attestation request via NIP-17 |
+| `trust_request_list` | Scan DMs for attestation requests |
+| `trust_proof_publish` | Publish linkage proof (kind 30078) with confirmation |
+| `trust_ring_prove` | Anonymous group membership proof (ring signature) |
+| `trust_ring_verify` | Verify ring signature proof |
+| `trust_spoken_challenge` | Generate spoken verification token |
+| `trust_spoken_verify` | Verify spoken token response |
+
+### Relay (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `relay_list` | List relays with shared-relay warnings |
+| `relay_set` | Publish kind 10002 relay list |
+| `relay_add` | Add relay to active identity (in-memory) |
+| `relay_info` | Fetch NIP-11 relay information document |
+
+### Zap (7 tools)
+
+| Tool | Description |
+|------|-------------|
+| `zap_send` | Pay a Lightning invoice via NWC |
+| `zap_balance` | Request wallet balance via NWC |
+| `zap_make_invoice` | Generate a Lightning invoice via NWC |
+| `zap_lookup_invoice` | Check invoice payment status via NWC |
+| `zap_list_transactions` | List recent Lightning transactions |
+| `zap_receipts` | Parse zap receipts (amount, sender, message) |
+| `zap_decode` | Decode bolt11 invoice fields |
+
+### Safety (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `safety_configure` | Configure an alternative identity persona |
+| `safety_activate` | Switch to alternative identity |
+
+## 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 |
+|----------|-------------|
+| `NOSTR_SECRET_KEY` | nsec bech32, 64-char hex, or BIP-39 mnemonic |
+| `NOSTR_SECRET_KEY_FILE` | Path to secret key file (takes precedence) |
+| `NOSTR_RELAYS` | Comma-separated relay URLs |
+| `TOR_PROXY` | SOCKS5h proxy for Tor (blocks clearnet relays by default) |
+| `NIP04_ENABLED` | Set `1` to enable legacy NIP-04 DMs |
+| `TRANSPORT` | `stdio` (default) or `http` |
+| `PORT` | HTTP port (default 3000) |
+
+## Documentation
+
+- **[Usage Guide](./docs/guide.md)** — walkthroughs for identity management, DMs, attestations, NWC payments, Tor, and duress
+- **[Examples](./examples/)** — MCP config files (basic, NWC, Tor) and a CLI workflow script
+- **[Contributing](./CONTRIBUTING.md)** — setup, architecture, testing, and conventions
+
+## For AI Assistants
+
+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.
+
+## Licence
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * nostr-bray CLI — standalone Nostr identity management from the terminal.
+ *
+ * Usage:
+ *   nostr-bray                          Start MCP server (default)
+ *   nostr-bray post "hello nostr"       Post a text note
+ *   nostr-bray reply <event-id> "text"  Reply to an event
+ *   nostr-bray react <event-id>         React to an event (+)
+ *   nostr-bray derive <purpose>         Derive a child identity
+ *   nostr-bray persona <name>           Derive a named persona
+ *   nostr-bray switch <target>          Switch active identity
+ *   nostr-bray list                     List all identities
+ *   nostr-bray prove [blind|full]       Create a linkage proof
+ *   nostr-bray profile <pubkey-hex>     Fetch a profile
+ *   nostr-bray relay-info <url>         Fetch NIP-11 relay info
+ *   nostr-bray backup <dir>             Shamir backup (threshold=3, shares=5)
+ *   nostr-bray whoami                   Show active identity npub
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * nostr-bray CLI — standalone Nostr identity management from the terminal.
+ *
+ * Usage:
+ *   nostr-bray                          Start MCP server (default)
+ *   nostr-bray post "hello nostr"       Post a text note
+ *   nostr-bray reply <event-id> "text"  Reply to an event
+ *   nostr-bray react <event-id>         React to an event (+)
+ *   nostr-bray derive <purpose>         Derive a child identity
+ *   nostr-bray persona <name>           Derive a named persona
+ *   nostr-bray switch <target>          Switch active identity
+ *   nostr-bray list                     List all identities
+ *   nostr-bray prove [blind|full]       Create a linkage proof
+ *   nostr-bray profile <pubkey-hex>     Fetch a profile
+ *   nostr-bray relay-info <url>         Fetch NIP-11 relay info
+ *   nostr-bray backup <dir>             Shamir backup (threshold=3, shares=5)
+ *   nostr-bray whoami                   Show active identity npub
+ */
+import { loadConfig } from './config.js';
+import { IdentityContext } from './context.js';
+import { RelayPool } from './relay-pool.js';
+import { Nip65Manager } from './nip65.js';
+import { handleSocialPost, handleSocialReply, handleSocialReact, handleSocialProfileGet } from './social/handlers.js';
+import { handleIdentityList, handleIdentityProve } from './identity/handlers.js';
+import { handleBackupShamir } from './identity/shamir.js';
+import { handleRelayInfo } from './relay/handlers.js';
+const args = process.argv.slice(2);
+const command = args[0];
+// No command = start MCP server (default behaviour)
+if (!command || command === 'serve') {
+    await import('./index.js');
+    process.exit(0);
+}
+// Help — no config needed
+if (command === 'help' || command === '--help' || command === '-h') {
+    console.log('nostr-bray — Sovereign Nostr identities for AI agents');
+    console.log('');
+    console.log('Usage: nostr-bray [command] [args]');
+    console.log('');
+    console.log('Commands:');
+    console.log('  (no command)                  Start MCP server (stdio)');
+    console.log('  whoami                        Show active identity npub');
+    console.log('  list                          List all identities');
+    console.log('  derive <purpose> [index]      Derive a child identity');
+    console.log('  persona <name> [index]        Derive a named persona');
+    console.log('  switch <target> [index]       Switch active identity');
+    console.log('  prove [blind|full]            Create a linkage proof');
+    console.log('  post "message"                Post a text note');
+    console.log('  reply <event-id> "text"       Reply to an event');
+    console.log('  react <event-id> [reaction]   React to an event');
+    console.log('  profile <pubkey-hex>          Fetch a profile');
+    console.log('  relay-info <wss://url>        Fetch NIP-11 relay info');
+    console.log('  backup <dir> [t] [n]          Shamir backup (default 3-of-5)');
+    console.log('');
+    console.log('Environment:');
+    console.log('  NOSTR_SECRET_KEY              nsec, hex, or BIP-39 mnemonic');
+    console.log('  NOSTR_SECRET_KEY_FILE         Path to secret key file');
+    console.log('  NOSTR_RELAYS                  Comma-separated relay URLs');
+    process.exit(0);
+}
+// CLI commands need config + context
+const config = loadConfig();
+const pool = new RelayPool({
+    torProxy: config.torProxy,
+    allowClearnet: config.allowClearnetWithTor || !config.torProxy,
+    defaultRelays: config.relays,
+});
+const nip65 = new Nip65Manager(pool, config.relays);
+const ctx = new IdentityContext(config.secretKey, config.secretFormat);
+config.secretKey = '';
+config.nwcUri = undefined;
+// Load master relay list
+const masterRelays = await nip65.loadForIdentity(ctx.activeNpub);
+pool.reconfigure(ctx.activeNpub, masterRelays);
+async function run() {
+    switch (command) {
+        case 'whoami': {
+            console.log(ctx.activeNpub);
+            break;
+        }
+        case 'list': {
+            const identities = handleIdentityList(ctx);
+            console.log(JSON.stringify(identities, null, 2));
+            break;
+        }
+        case 'derive': {
+            const purpose = args[1];
+            if (!purpose) {
+                console.error('Usage: nostr-bray derive <purpose> [index]');
+                process.exit(1);
+            }
+            const index = parseInt(args[2] ?? '0', 10);
+            const result = ctx.derive(purpose, index);
+            console.log(JSON.stringify(result, null, 2));
+            break;
+        }
+        case 'persona': {
+            const name = args[1];
+            if (!name) {
+                console.error('Usage: nostr-bray persona <name> [index]');
+                process.exit(1);
+            }
+            const index = parseInt(args[2] ?? '0', 10);
+            const result = ctx.derivePersona(name, index);
+            console.log(JSON.stringify(result, null, 2));
+            break;
+        }
+        case 'switch': {
+            const target = args[1];
+            if (!target) {
+                console.error('Usage: nostr-bray switch <target> [index]');
+                process.exit(1);
+            }
+            const index = args[2] ? parseInt(args[2], 10) : undefined;
+            ctx.switch(target, index);
+            console.log(ctx.activeNpub);
+            break;
+        }
+        case 'prove': {
+            const mode = (args[1] === 'full' ? 'full' : 'blind');
+            const proof = handleIdentityProve(ctx, { mode });
+            console.log(JSON.stringify(proof, null, 2));
+            break;
+        }
+        case 'post': {
+            const content = args[1];
+            if (!content) {
+                console.error('Usage: nostr-bray post "your message"');
+                process.exit(1);
+            }
+            const result = await handleSocialPost(ctx, pool, { content });
+            console.log(JSON.stringify({ id: result.event.id, pubkey: result.event.pubkey, publish: result.publish }, null, 2));
+            break;
+        }
+        case 'reply': {
+            const eventId = args[1];
+            const content = args[2];
+            if (!eventId || !content) {
+                console.error('Usage: nostr-bray reply <event-id> "your reply"');
+                process.exit(1);
+            }
+            const result = await handleSocialReply(ctx, pool, {
+                content,
+                replyTo: eventId,
+                replyToPubkey: '', // simplified for CLI
+            });
+            console.log(JSON.stringify({ id: result.event.id, publish: result.publish }, null, 2));
+            break;
+        }
+        case 'react': {
+            const eventId = args[1];
+            if (!eventId) {
+                console.error('Usage: nostr-bray react <event-id> [reaction]');
+                process.exit(1);
+            }
+            const result = await handleSocialReact(ctx, pool, {
+                eventId,
+                eventPubkey: '',
+                reaction: args[2] ?? '+',
+            });
+            console.log(JSON.stringify({ id: result.event.id, publish: result.publish }, null, 2));
+            break;
+        }
+        case 'profile': {
+            const pubkeyHex = args[1];
+            if (!pubkeyHex) {
+                console.error('Usage: nostr-bray profile <pubkey-hex>');
+                process.exit(1);
+            }
+            const profile = await handleSocialProfileGet(pool, ctx.activeNpub, pubkeyHex);
+            console.log(JSON.stringify(profile, null, 2));
+            break;
+        }
+        case 'relay-info': {
+            const url = args[1];
+            if (!url) {
+                console.error('Usage: nostr-bray relay-info <wss://relay-url>');
+                process.exit(1);
+            }
+            const info = await handleRelayInfo(url);
+            console.log(JSON.stringify(info, null, 2));
+            break;
+        }
+        case 'backup': {
+            const dir = args[1];
+            if (!dir) {
+                console.error('Usage: nostr-bray backup <output-dir> [threshold] [shares]');
+                process.exit(1);
+            }
+            const threshold = parseInt(args[2] ?? '3', 10);
+            const shares = parseInt(args[3] ?? '5', 10);
+            const result = handleBackupShamir({
+                secret: new Uint8Array(ctx.activePrivateKey),
+                threshold,
+                shares,
+                outputDir: dir,
+            });
+            console.log(JSON.stringify(result, null, 2));
+            break;
+        }
+        default:
+            console.error(`Unknown command: ${command}`);
+            console.error('');
+            console.error('Commands:');
+            console.error('  whoami                        Show active identity npub');
+            console.error('  list                          List all identities');
+            console.error('  derive <purpose> [index]      Derive a child identity');
+            console.error('  persona <name> [index]        Derive a named persona');
+            console.error('  switch <target> [index]       Switch active identity');
+            console.error('  prove [blind|full]            Create a linkage proof');
+            console.error('  post "message"                Post a text note');
+            console.error('  reply <event-id> "text"       Reply to an event');
+            console.error('  react <event-id> [reaction]   React to an event');
+            console.error('  profile <pubkey-hex>          Fetch a profile');
+            console.error('  relay-info <wss://url>        Fetch NIP-11 relay info');
+            console.error('  backup <dir> [t] [n]          Shamir backup (default 3-of-5)');
+            console.error('');
+            console.error('No command = start MCP server (stdio)');
+            process.exit(1);
+    }
+}
+try {
+    await run();
+}
+finally {
+    ctx.destroy();
+    pool.close();
+}

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+import type { BrayConfig } from './types.js';
+/** Auto-detect key format from string content */
+export declare function detectKeyFormat(key: string): 'nsec' | 'hex' | 'mnemonic';
+/** Load configuration from environment variables and optional secret files */
+export declare function loadConfig(): BrayConfig;

package/dist/config.js

@@ -0,0 +1,87 @@
+import { readFileSync } from 'node:fs';
+const NSEC_RE = /^nsec1[a-z0-9]{58}$/;
+const HEX_RE = /^[0-9a-f]{64}$/;
+/** Auto-detect key format from string content */
+export function detectKeyFormat(key) {
+    if (NSEC_RE.test(key))
+        return 'nsec';
+    if (HEX_RE.test(key))
+        return 'hex';
+    // BIP-39 mnemonic: 12 or 24 space-separated lowercase words
+    const words = key.split(/\s+/);
+    if (words.length >= 12 && words.every(w => /^[a-z]+$/.test(w)))
+        return 'mnemonic';
+    throw new Error(`Invalid key format: expected nsec1..., 64-char hex, or BIP-39 mnemonic`);
+}
+/** Read and trim a secret from a file */
+function readSecretFile(path) {
+    return readFileSync(path, 'utf-8').trim();
+}
+/** Parse comma-separated relay URLs */
+function parseRelays(csv) {
+    return csv.split(',').map(r => r.trim()).filter(Boolean);
+}
+/** Check that all relays are Tor-safe when a SOCKS proxy is configured */
+function validateTorRelays(relays, torProxy, allowClearnet) {
+    if (!torProxy || allowClearnet)
+        return;
+    const clearnet = relays.filter(r => !r.includes('.onion'));
+    if (clearnet.length > 0) {
+        throw new Error(`Clearnet relays not allowed with Tor proxy (set ALLOW_CLEARNET_WITH_TOR=1 to override): ${clearnet.join(', ')}`);
+    }
+}
+/** Load configuration from environment variables and optional secret files */
+export function loadConfig() {
+    // --- Secret key ---
+    const keyFilePath = process.env.NOSTR_SECRET_KEY_FILE;
+    const keyEnvVar = process.env.NOSTR_SECRET_KEY;
+    let secretKey;
+    if (keyFilePath) {
+        secretKey = readSecretFile(keyFilePath);
+    }
+    else if (keyEnvVar) {
+        secretKey = keyEnvVar;
+    }
+    else {
+        throw new Error('No secret key provided: set NOSTR_SECRET_KEY or NOSTR_SECRET_KEY_FILE');
+    }
+    const secretFormat = detectKeyFormat(secretKey);
+    // --- NWC URI ---
+    const nwcFilePath = process.env.NWC_URI_FILE;
+    let nwcUri;
+    if (nwcFilePath) {
+        nwcUri = readSecretFile(nwcFilePath);
+    }
+    else if (process.env.NWC_URI) {
+        nwcUri = process.env.NWC_URI;
+    }
+    // --- Relays ---
+    const relays = parseRelays(process.env.NOSTR_RELAYS ?? '');
+    // --- Tor ---
+    const torProxy = process.env.TOR_PROXY || undefined;
+    const allowClearnetWithTor = process.env.ALLOW_CLEARNET_WITH_TOR === '1';
+    validateTorRelays(relays, torProxy, allowClearnetWithTor);
+    // --- Transport ---
+    const transport = (process.env.TRANSPORT === 'http' ? 'http' : 'stdio');
+    const port = parseInt(process.env.PORT ?? '3000', 10);
+    const bindAddress = process.env.BIND_ADDRESS ?? '127.0.0.1';
+    // --- NIP-04 ---
+    const nip04Enabled = process.env.NIP04_ENABLED === '1';
+    // --- Clean up secrets from process.env ---
+    delete process.env.NOSTR_SECRET_KEY;
+    delete process.env.NOSTR_SECRET_KEY_FILE;
+    delete process.env.NWC_URI;
+    delete process.env.NWC_URI_FILE;
+    return {
+        secretKey,
+        secretFormat,
+        relays,
+        nwcUri,
+        torProxy,
+        allowClearnetWithTor,
+        nip04Enabled,
+        transport,
+        port,
+        bindAddress,
+    };
+}

package/dist/context.d.ts

@@ -0,0 +1,35 @@
+import type { LinkageProof } from 'nsec-tree';
+import type { PublicIdentity, SignFn } from './types.js';
+export interface ContextOptions {
+    maxCache?: number;
+}
+export declare class IdentityContext {
+    private root;
+    private cache;
+    private masterEntry;
+    private activeEntry;
+    private maxCacheSize;
+    constructor(secretKey: string, format: 'nsec' | 'hex' | 'mnemonic', opts?: ContextOptions);
+    /** Current active identity's npub */
+    get activeNpub(): string;
+    /** Derive a child identity by purpose and index */
+    derive(purpose: string, index: number): PublicIdentity;
+    /** Derive a named persona */
+    derivePersona(name: string, index: number): PublicIdentity;
+    /** Switch active identity by purpose+index, persona name, or "master" */
+    switch(purposeOrName: string, index?: number): void;
+    /** Get a signing function bound to the current active identity */
+    getSigningFunction(): SignFn;
+    /** List all known identities — returns public info only, never private keys */
+    listIdentities(): PublicIdentity[];
+    /** Create a linkage proof for the active identity */
+    prove(mode?: 'blind' | 'full'): LinkageProof;
+    /** Get the active identity's private key for NIP-17/44/04 crypto operations */
+    get activePrivateKey(): Uint8Array;
+    /** Test helper — returns reference to private key bytes for verifying zeroise */
+    _getPrivateKeyRefForTesting(npub: string): Uint8Array | undefined;
+    /** Destroy all identities and the tree root */
+    destroy(): void;
+    /** Insert into LRU cache, evicting oldest if at capacity */
+    private putCache;
+}