nsec-tree

Deterministic Nostr identity hierarchies. One master secret, unlimited identities.

npm install nsec-tree

ESM-only. Zero custom crypto — all primitives from @noble/@scure.

Discuss: NIP draft · FAQ · Nostr: npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2

Why nsec-tree?

NIP-06 standardises mnemonic-based key derivation, but most clients surface one primary key. nsec-tree gives you a purpose-tagged identity tree.

• Unlinkable by default — no observer can prove two child npubs share a master
• Recoverable — 12 words recreate your entire identity tree
• Purpose-tagged — human-readable derivation ("social", "commerce", "trott:rider")
• Composable hierarchies — model trees like work -> company:a -> signing

Children are ordinary Nostr keypairs. Clients that do not understand linkage proofs will treat them as separate identities.

This is not just "multiple accounts from one seed". You can derive structured subtrees for personas, organisations, applications, environments, and rotated replacement keys:

• personal -> social -> main
• personal -> social -> alt
• work -> company:a -> payroll
• work -> company:b -> ops
• work -> company:b -> ops -> emergency

---

Quick start

From a mnemonic (greenfield)

import { fromMnemonic, derive } from 'nsec-tree'

const root = fromMnemonic('abandon abandon ... about')
const social = derive(root, 'social')
const commerce = derive(root, 'commerce')
console.log(social.npub)   // npub1...
console.log(commerce.npub) // npub1... (different, unlinkable)
root.destroy()

From an existing nsec (existing users)

import { fromNsec, derive } from 'nsec-tree/core' // no BIP deps

const root = fromNsec('nsec1...')
const throwaway = derive(root, 'throwaway', 42)

Build a hierarchy

import { fromMnemonic, deriveFromIdentity } from 'nsec-tree'
import { derivePersona } from 'nsec-tree/persona'

const root = fromMnemonic('abandon abandon ... about')
const work = derivePersona(root, 'work')
const companyA = deriveFromIdentity(work.identity, 'company:a')
const payroll = deriveFromIdentity(companyA, 'payroll')
const companyB = deriveFromIdentity(work.identity, 'company:b')
const ops = deriveFromIdentity(companyB, 'ops')

console.log(work.identity.npub) // master -> work
console.log(payroll.npub)       // master -> work -> company:a -> payroll
console.log(ops.npub)           // master -> work -> company:b -> ops

Each level is deterministic and isolated. Compromising company:a -> payroll does not expose the sibling company:b -> ops branch.

Prove ownership (linkage proofs)

import { createBlindProof, verifyProof } from 'nsec-tree/proof'

const proof = createBlindProof(root, child)
// Send proof to verifier...
const valid = verifyProof(proof) // true

Publish proof to Nostr (NIP-78)

import { toUnsignedEvent } from 'nsec-tree/event'

const unsigned = toUnsignedEvent(proof)
// Sign with your Nostr library, then publish to relays

---

API

fromMnemonic(mnemonic, passphrase?)

Create a TreeRoot from a BIP-39 mnemonic. Derives the tree root at m/44'/1237'/727'/0'/0'.

fromNsec(nsec)

Create a TreeRoot from a bech32 nsec string or raw 32-byte key. An intermediate HMAC separates the signing key from the derivation key.

derive(root, purpose, index?)

Derive a child Identity from a TreeRoot. Returns { nsec, npub, privateKey, publicKey, purpose, index }. The index defaults to 0.

deriveFromIdentity(identity, purpose, index?)

Derive a child Identity from any existing Identity, enabling arbitrary-depth hierarchies like work -> company:a -> payroll -> hot-wallet.

recover(root, purposes, scanRange?)

Scan multiple purposes and indices, returning Map<string, Identity[]>. Default scan range: 20 (BIP-44 gap limit).

zeroise(identity)

Zero the private key bytes of a derived identity.

createBlindProof(root, child)

BIP-340 Schnorr proof that the master owns a child — without revealing the derivation slot.

createFullProof(root, child)

Like blind proof, but also reveals the purpose and index.

verifyProof(proof)

Verify a LinkageProof. Returns boolean.

toUnsignedEvent(proof)

Convert a LinkageProof to an unsigned NIP-78 Kind 30078 Nostr event. The application signs and publishes it.

fromEvent(event)

Extract a LinkageProof from a NIP-78 event's tags. Pass the result to verifyProof() to check cryptographic validity.

---

Subpath exports

Import	What	BIP deps?
nsec-tree	Full API	Yes
nsec-tree/core	fromNsec, derive, recover, zeroise	No
nsec-tree/mnemonic	fromMnemonic	Yes
nsec-tree/proof	Linkage proofs	No
nsec-tree/persona	Persona derivation, two-level hierarchy, recovery	No
nsec-tree/event	NIP-78 event conversion (toUnsignedEvent, fromEvent)	No
nsec-tree/encoding	NIP-19 bech32 helpers (encodeNsec, decodeNsec, encodeNpub, decodeNpub)	No

Use nsec-tree/core if you only need nsec-based derivation — it avoids pulling in BIP-32/39 dependencies.

---

How it works

• Tree root from mnemonic (BIP-32 at m/44'/1237'/727'/0'/0') or nsec (intermediate HMAC)
• Child keys: HMAC-SHA256(tree_root, "nsec-tree\0" || purpose || "\0" || index_be32)
• Linkage proofs: BIP-340 Schnorr signatures over attestation strings
• Hierarchies: any derived identity can itself become a subtree root via deriveFromIdentity(...)
• See PROTOCOL.md for the full derivation spec with test vectors

---

Personas

A persona is a named Nostr identity derived from your master secret using the convention nostr:persona:{name}. Each persona gets its own keypair — suitable for a separate kind-0 profile — and is unlinkable to other personas by default.

Deriving personas

import { fromMnemonic } from 'nsec-tree'
import { derivePersona } from 'nsec-tree/persona'

const root = fromMnemonic('abandon abandon ... about')
const personal = derivePersona(root, 'personal')
const bitcoiner = derivePersona(root, 'bitcoiner')
const work = derivePersona(root, 'work')

console.log(personal.identity.npub)  // npub1...
console.log(bitcoiner.identity.npub) // npub1... (different, unlinkable)

Two-level hierarchy

deriveFromPersona creates sub-identities beneath a persona. This is useful for group signing keys — each group gets an isolated keypair derived from the persona, not the master.

import { deriveFromPersona } from 'nsec-tree/persona'

const meetup = deriveFromPersona(bitcoiner, 'canary:group:local-meetup')
const conference = deriveFromPersona(bitcoiner, 'canary:group:btcpp-2026')

The hierarchy is: master → persona → group identity. Compromising a group key does not expose the persona key, and compromising a persona does not expose the master.

Arbitrary-depth hierarchy

deriveFromPersona(...) is just a convenience helper. The more general deriveFromIdentity(...) API lets you keep branching as deep as you need.

import { deriveFromIdentity } from 'nsec-tree'

const companyA = deriveFromIdentity(work.identity, 'company:a')
const payroll = deriveFromIdentity(companyA, 'payroll')
const hotWallet = deriveFromIdentity(payroll, 'hot-wallet')

const companyB = deriveFromIdentity(work.identity, 'company:b')
const ops = deriveFromIdentity(companyB, 'ops')

That gives you paths like:

• master -> work -> company:a -> payroll -> hot-wallet
• master -> work -> company:b -> ops

This is where nsec-tree becomes more than a "multi-account" library. It lets you model real operational structure directly in deterministic keys: people, teams, customers, devices, environments, or services. One backup recreates the entire tree.

Recovery

recoverPersonas re-derives all personas from a mnemonic by scanning a list of known names. When no names are provided it uses DEFAULT_PERSONA_NAMES: personal, bitcoiner, work, social, anonymous.

import { recoverPersonas, DEFAULT_PERSONA_NAMES } from 'nsec-tree/persona'

const root = fromMnemonic('abandon abandon ... about')
const recovered = recoverPersonas(root, DEFAULT_PERSONA_NAMES, 2)

for (const [name, personas] of recovered) {
  console.log(`${name}: ${personas.length} indices scanned`)
}

Recovery is deterministic — the same mnemonic always produces the same personas. You only need to know (or conventionalise) the persona names to scan.

The same principle applies to deeper trees: recovery is easy when branch names and rotation conventions are stable. The more hierarchy you use, the more important naming discipline becomes.

Rotation

If a persona is compromised, derive it at a higher index:

const bitcoinerV0 = derivePersona(root, 'bitcoiner', 0) // compromised
const bitcoinerV1 = derivePersona(root, 'bitcoiner', 1) // replacement

Use a blind linkage proof to prove continuity — the new persona is controlled by the same master — without revealing which derivation slot was used:

import { createBlindProof, verifyProof } from 'nsec-tree/proof'

const proof = createBlindProof(root, bitcoinerV1.identity)
verifyProof(proof) // true — same master, new identity

Ecosystem integration

For internal architecture details, see ARCHITECTURE.md.

nsec-tree personas are designed to compose with other libraries:

• canary-kit — deriveFromPersona(persona, 'canary:group:...') produces the group signing key that canary-kit uses for encrypted location beacons, duress alerts, and liveness checks.
• spoken-token — bind a spoken verification token to a persona's public key for identity confirmation over voice calls.
• heartwood — hardware signing appliance that implements nsec-tree in Rust on a Pi Zero 2 W, serving NIP-46 remote signing over Tor.
• bark — browser extension that connects to heartwood (or any NIP-46 bunker) for NIP-07 signing with per-persona identity selection.

Security model

Compromise at different levels has different blast radii:

Compromised	Impact	Mitigation
Group key	One group identity exposed	Rotate the group key (new purpose or index)
Persona key	All group keys under that persona derivable	Rotate the persona (increment index), issue linkage proof
Master secret	All personas and group keys derivable	Rotate the mnemonic, migrate all identities

The two-level hierarchy ensures that a group key compromise does not escalate to the persona, and a persona compromise does not escalate to the master.

---

Examples

Runnable examples in the examples/ directory:

Example	What it shows
basic-derivation.ts	Derive social + commerce identities
existing-nsec.ts	Use an existing nsec, no mnemonic needed
recovery.ts	Recover all identities from a mnemonic
linkage-proofs.ts	Blind and full ownership proofs
bot-fleet.ts	10 bots from one seed
nostr-event-signing.ts	Sign a kind-1 event with nostr-tools
nip78-event.ts	NIP-78 round-trip — toUnsignedEvent / fromEvent
persona.ts	Persona derivation, deep hierarchies, rotation, recovery

Run any example: npx tsx examples/<name>.ts

Further reading

• FAQ — common questions and objections
• Comparison — nsec-tree vs NIP-06, NIP-26, linked subkeys
• NIP draft — formal specification in NIP format
• PROTOCOL.md — full derivation spec with test vectors

---

Security

• Zero custom crypto — HMAC-SHA256 (RFC 2104), BIP-32, BIP-340 Schnorr. All from @noble/@scure.
• Unlinkable by default — selective disclosure only via linkage proofs
• Zeroisation — call root.destroy() and zeroise(identity) when done. FinalizationRegistry provides best-effort cleanup if you forget.
• Master compromise — if the master secret leaks, all child keys are derivable. Protect it with the same rigour as any nsec.
• See PROTOCOL.md for the full threat model

---

Part of the ForgeSworn Toolkit

ForgeSworn builds open-source cryptographic identity, payments, and coordination tools for Nostr.

Library	What it does
nsec-tree	Deterministic sub-identity derivation
ring-sig	SAG/LSAG ring signatures on secp256k1
range-proof	Pedersen commitment range proofs
canary-kit	Coercion-resistant spoken verification
spoken-token	Human-speakable verification tokens
toll-booth	L402 payment middleware
geohash-kit	Geohash toolkit with polygon coverage
nostr-attestations	NIP-VA verifiable attestations
dominion	Epoch-based encrypted access control
nostr-veil	Privacy-preserving Web of Trust

Licence

MIT

---

If you find nsec-tree useful, consider sending a tip:

• Lightning: thedonkey@strike.me
• Nostr zaps: npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2