Skip to content

CLAUDE.md

Latest commit

 

History

History
66 lines (51 loc) · 3.95 KB

CLAUDE.md

File metadata and controls

66 lines (51 loc) · 3.95 KB

CLAUDE.md — nostr-bray

MCP server giving AI agents sovereign Nostr identities. 238 tools across 27 groups.

Commands

  • npm run build — compile TypeScript to dist/
  • npm test — run all tests (vitest, 1098 tests)
  • npm run test:watch — watch mode
  • npm run lint — type-check without emitting (tsc --noEmit)
  • npm start — run the MCP server (requires NOSTR_SECRET_KEY + NOSTR_RELAYS)
  • node dist/cli.js --help — CLI help

Architecture

Single-process MCP server. Entry points:

  • src/index.ts — MCP server (config → IdentityContext → RelayPool → tool registration → transport)
  • src/cli.ts — CLI wrapper (same handlers, no MCP)

Central spine: IdentityContext in src/context.ts manages the nsec-tree root, LRU identity cache with cryptographic zeroing, and signing. TrustContext in src/trust-context.ts aggregates trust signals across verification (Signet), proximity (WoT), and access (Dominion) dimensions.

Handler extraction pattern: Each tool group has:

  • src/<group>/handlers.ts — pure logic functions (testable without MCP)
  • src/<group>/tools.ts — Zod schemas + server.registerTool() wiring
  • test/<group>/handlers.test.ts — unit tests for handlers

Source directories (16): identity/, social/ (includes blossom, dm, groups, nips, notifications), trust/, relay/, zap/, safety/, signet/, vault/, util/, workflow/ (trust-score, feed-discover, verify-person, identity-setup, identity-recover, relay-health), dispatch/ (13 tools: send, check, reply, ack, status, cancel, refuse, failure, query, propose, capability-publish, capability-discover, capability-read), handler/, marketplace/, moderation/, privacy/, widgets/. The 27 user-facing groups in README/llms.txt split social/ into sub-groups (dm, blossom, articles, calendar, badges, communities, groups, wiki, search, scheduling, community NIPs).

Shared modules:

  • src/config.ts — env var + file secret loading, format detection
  • src/relay-pool.ts — relay connections with SOCKS5h proxy, write queue, Tor policy
  • src/nip65.ts — NIP-65 relay list fetch with signature verification + TTL cache
  • src/validation.ts — Zod validators (hexId, relayUrl)

Key Dependencies

  • @modelcontextprotocol/sdk — MCP server framework
  • nostr-tools — Nostr event creation, signing, NIP-17/44/04 encryption
  • nsec-tree — hierarchical identity derivation from master secret
  • @forgesworn/ring-sig — SAG ring signatures on secp256k1
  • @forgesworn/shamir-words — Shamir Secret Sharing with BIP-39 output
  • nostr-attestations — NIP-VA kind 31000 attestation builders/validators
  • spoken-token — HMAC-based spoken verification tokens
  • canary-kit — duress detection (imported via spoken-token)
  • signet-protocol — identity verification protocol (Signet badge and credential types)
  • dominion-protocol — epoch-based encrypted access control (Shamir, HKDF vault keys)

Conventions

  • British English everywhere
  • Git: type: description commits. No Co-Authored-By lines.
  • Branch: work on branches, merge to main. forgesworn/anvil@v0 handles releases via workflow_call.
  • Security: never return private keys in tool responses. Zeroise buffers in finally blocks. Validate all external input.

Security-Critical Paths

Be extra careful when modifying:

  • src/context.ts — key material lifecycle, zeroise on eviction/destroy
  • src/zap/handlers.ts — NWC secret handling, NIP-44 encrypt/decrypt
  • src/config.ts — secret loading and env var cleanup
  • src/relay-pool.ts — Tor policy enforcement
  • src/nip65.ts — event signature verification
  • src/index.ts — HTTP auth, rate limiting, body size limits
  • src/trust-context.ts — trust signal aggregation across verification, proximity, and access dimensions
  • src/signet/ — Signet badge fetching, credential validation, policy enforcement
  • src/vault/ — Dominion vault key derivation, epoch rotation, access tier management