Verification, proximity, and access: three dimensions of trust, woven into every interaction. 106 tools for identity, social, payments, moderation, and encrypted access control.
npx nostr-bray
click to copy
Pubkeys prove ownership. They do not prove identity, reputation, or intent. Every Nostr user, human or AI, runs into the same three gaps.
Anyone can claim to be anyone. Impersonation is trivial. Without verifiable attestations, there is no way to tell a real person from a bot or an impostor.
Your Web of Trust lives in your head. There is no machine-readable social graph distance, so every feed is a flood and moderation is all-or-nothing.
You can post publicly or encrypt to one person. There is no way to share content with a trusted tier (members, subscribers, crew) without bespoke infrastructure.
Lose your nsec, lose your identity forever. No recovery, no recourse. Your entire social graph, reputation, and history, gone.
If forced to hand over your key, the attacker gets everything. There is no way to comply under duress while signalling the situation.
AI agents share your key or generate throwaway ones. No hierarchy, no recovery, no context separation. The agent's actions are indistinguishable from yours.
Bray combines three independent trust signals into a single, unified surface. Each dimension answers a different question.
Not workarounds. Proper cryptographic primitives across three axes: who you are, how close you are, and what you can see.
Seven Signet tools let any agent fetch, vouch, challenge, and enforce identity claims. Policy checks gate access by verification tier. No hand-rolled logic required.
SignetTrust scores derived from your social graph weight every interaction. Filter spam by graph distance. Endorse peers. Surface content from people you actually know.
trust-wot-scoreEight Vault tools create Dominion-encrypted content channels. Tiered keys are derived per epoch. Revoke a member's access and their old keys cannot decrypt new content.
VaultOne master secret generates unlimited child key pairs via nsec-tree. Derive personas for work, personal, anonymous use, each cryptographically independent.
nsec-treeSplit your master secret into BIP-39 word shards. Distribute them to trusted parties. Any threshold subset reconstructs the original. No single point of failure.
shamir-wordsNIP-17 gift wrapping hides sender, recipient, and conversation metadata. No opt-in required; it is the default for every DM.
NIP-17Configure an alternative identity that activates under coercion. Indistinguishable from a normal persona switch. The attacker cannot tell you have complied under duress.
canary-kitPrivate keys are cryptographically zeroed from memory on identity eviction and process shutdown. LRU cache ensures minimal key material exposure at any given moment.
IdentityContextEvery tool operates as the active identity. Switch persona, and your posts, DMs, attestations, and payments all follow. No configuration changes needed.
Create, derive, switch, prove, backup, and migrate Nostr identities. Hierarchical key tree with Shamir recovery.
Post, reply, react, repost, DM by name, read feeds and conversations. Name-based lookups across your contact graph.
Verifiable attestations, ring signatures for anonymous proofs, spoken verification tokens, linkage proofs.
Lightning payments via Nostr Wallet Connect. Send, receive, invoice, check balances, decode bolt11.
Per-identity relay lists with NIP-65 management. Query events, fetch relay info, health monitoring.
Duress personas for coercion resistance. Alternative identity indistinguishable from a normal persona switch.
Media uploads to Blossom servers. Upload, list, and delete blobs with authenticated requests.
NIP-29 group chat. Fetch metadata, read messages, send to groups, list members.
Publish and read community-proposed Nostr Implementation Possibilities (kind 30817).
Encode, decode, encrypt, verify, filter, fetch. NIP-44 encryption, NIP-49 key encryption, event verification.
Progressive identity verification. Fetch badges, issue vouches, run challenges, enforce policy. Four tiers from self-declaration to cryptographic attestation.
Epoch-based encrypted access control via Dominion. Create content tiers, manage members, rotate keys, and revoke access, all without a server or a database.
Use bray as an MCP server for AI agents (Claude, Cursor, Windsurf) or as a standalone CLI. Both share the same handlers, the same identity engine, the same security guarantees.
// claude_desktop_config.json // Option A: bunker (safest — key stays in bunker) { "mcpServers": { "nostr": { "command": "npx", "args": ["nostr-bray"], "env": { "BUNKER_URI": "bunker://<pubkey>?relay=wss://relay.damus.io" } } } } // Option B: file-based secret // Replace BUNKER_URI with: // "NOSTR_SECRET_KEY_FILE": "~/.nostr/secret.key", // "NOSTR_RELAYS": "wss://relay.damus.io"
# start your bunker (runs in background) npx nostr-bray bunker & # connect to it export BUNKER_URI="bunker://<pubkey>?relay=wss://relay.damus.io" # go npx nostr-bray whoami npx nostr-bray post "hello from bray" npx nostr-bray persona work npx nostr-bray prove blind
Bray assumes a hostile environment. Every default is the most private option. Every key operation has a zeroing path. Secrets never appear in tool responses.
Gift-wrapped DMs hide sender, recipient, and metadata. NIP-04 requires explicit opt-in via environment variable.
Your private key never leaves your signer. Bray connects via NIP-46 remote signing so the agent signs events without ever seeing the nsec.
Private keys are cryptographically zeroed from memory on LRU eviction and process shutdown. Minimal exposure window.
Tool responses never contain private keys or secret material. Shamir shards are written to files, not returned as text.
Secrets loaded from files are scrubbed from process.env immediately after parsing. No lingering plaintext in memory.
NIP-65 relay list events are signature-verified before use. Relay information documents are validated against NIP-11.
Bray stands on existing Nostr tooling. It does not replace nostr-tools or nak. It adds a narrow, opinionated identity layer on top.
838 stars · 1.2M monthly npm downloads
Our primary dependency. Handles event creation, signing, NIP-44 encryption, relay connections, and most protocol-level heavy lifting. If you are building a Nostr client in JavaScript, nostr-tools is the standard.
by fiatjaf (the Nostr protocol creator) · Go
The definitive Nostr Swiss Army knife. Covers far more ground than bray: MuSig2 collaborative signing, built-in relay with negentropy sync, FUSE filesystem, NIP-60 Cashu wallet, smart outbox routing, PoW mining, NIP-86 relay admin, and a full bunker with persistence and QR codes. If you want a power-user CLI for Nostr, nak is it.
A narrow set of capabilities that revolve around one theme: trust-aware Nostr for AI and humans.
All bundled into a single MCP server with 106 tools, so an AI agent gets a complete trust-aware Nostr identity out of the box without stitching together multiple tools.
# no install needed — npx runs it directly npx nostr-bray --help # or install globally npm install -g nostr-bray
Three options, safest first:
# RECOMMENDED: NIP-46 bunker (key never touches bray) # Terminal 1 — start the bunker with your key npx nostr-bray bunker # Terminal 2 — connect to it export BUNKER_URI="bunker://<pubkey>?relay=wss://relay.damus.io" npx nostr-bray whoami
# GOOD: file-based secret (protected by file permissions) echo "nsec1..." > ~/.nostr/secret.key chmod 600 ~/.nostr/secret.key export NOSTR_SECRET_KEY_FILE="~/.nostr/secret.key" export NOSTR_RELAYS="wss://relay.damus.io,wss://nos.lol"
# QUICK (testing only): env var export NOSTR_SECRET_KEY="nsec1..." export NOSTR_RELAYS="wss://relay.damus.io,wss://nos.lol"
# check your identity npx nostr-bray whoami # derive a work persona npx nostr-bray persona work # post as that persona npx nostr-bray post "hello from my work identity" # create a shamir backup npx nostr-bray backup-shamir --shares 5 --threshold 3