nsec-tree

https://github.com/forgesworn/nsec-tree
Admin
nsec-tree is a TypeScript library that enables deterministic derivation of unlinkable Nostr...
Tokens:26,582
Snippets:226
Trust Score:7.5
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Setup nsec-tree development environment

Source: https://github.com/forgesworn/nsec-tree/blob/main/CONTRIBUTING.md

Commands to clone the repository and install dependencies. Requires Node.js 22+.

```bash
git clone git@github.com:forgesworn/nsec-tree.git
cd nsec-tree
npm install
npm run build
npm test
```

--------------------------------

### Install nsec-tree

Source: https://github.com/forgesworn/nsec-tree/blob/main/llms.txt

Install the nsec-tree package using npm.

```bash
npm install nsec-tree
```

--------------------------------

### HMAC Message Construction for 'commerce' Purpose

Source: https://github.com/forgesworn/nsec-tree/blob/main/PROTOCOL.md

Example of constructing the HMAC message for deriving a child key with the purpose 'commerce' and index 0. The message includes the domain prefix, purpose, and index in big-endian format.

```plaintext
6e7365632d74726565 00 636f6d6d65726365 00 00000000
|________________| |  |______________| |  |______|
 nsec-tree          \0  commerce        \0  index=0 (big-endian)
```

--------------------------------

### HMAC Message Construction for 'social' Purpose

Source: https://github.com/forgesworn/nsec-tree/blob/main/PROTOCOL.md

Example of constructing the HMAC message for deriving a child key with the purpose 'social' and index 0. The message includes the domain prefix, purpose, and index in big-endian format.

```plaintext
6e7365632d74726565 00 736f6369616c 00 00000000
|________________| |  |__________| |  |______|
 nsec-tree          \0  social      \0  index=0 (big-endian)
```

--------------------------------

### Mnemonic Path Test Vector - Tree Root Derivation

Source: https://github.com/forgesworn/nsec-tree/blob/main/docs/NIP-XXXX.md

Outputs from the tree root derivation when starting with a mnemonic phrase. This includes the BIP-32 path used for derivation.

```text
tree_root:   cc92d213b5eccd19eb85c12c2cf6fd168f27c2cc347c51a7c4c62ac67795fc65
master_pub:  3eb14b67cc942c5388e03570b68d0887d40ff34af234662344e6c72a6298d656
```

--------------------------------

### Build and Test Commands

Source: https://github.com/forgesworn/nsec-tree/blob/main/AGENTS.md

Standard npm commands for managing dependencies, compiling TypeScript, and executing the test suite.

```bash
npm install        # install dependencies
npm run build      # compile TypeScript (tsc)
npm test           # run all tests (vitest)
npm run typecheck  # type-check without emitting
```

--------------------------------

### Project Architecture

Source: https://github.com/forgesworn/nsec-tree/blob/main/AGENTS.md

Overview of the source directory structure and module responsibilities.

```text
src/
  types.ts            -- interfaces (TreeRoot, Identity, LinkageProof, Persona), error class, constants
  encoding.ts         -- NIP-19 bech32 encode/decode (nsec, npub), hex utilities
  validate.ts         -- purpose string validation (non-empty, max 255 bytes, no nulls)
  derive.ts           -- HMAC-SHA256 child key derivation, derive() and zeroise() public API
  derive-identity.ts  -- deriveFromIdentity() for arbitrary-depth hierarchies
  root-nsec.ts        -- fromNsec(), createTreeRoot(), FinalizationRegistry for cleanup
  root-mnemonic.ts    -- fromMnemonic() via BIP-32 at m/44'/1237'/727'/0'/0'
  recover.ts          -- scan-based identity recovery across purposes x indices
  proof.ts            -- BIP-340 Schnorr linkage proofs (blind + full)
  persona.ts          -- named persona derivation, two-level hierarchy, recovery
  event.ts            -- NIP-78 Kind 30078 event conversion (toUnsignedEvent, fromEvent)
  index.ts            -- full API barrel re-export
  core.ts             -- no-BIP-deps barrel (must never import root-mnemonic.ts)
  mnemonic.ts         -- fromMnemonic-only barrel
```

--------------------------------

### fromMnemonic

Source: https://context7.com/forgesworn/nsec-tree/llms.txt

Creates a TreeRoot from a BIP-39 mnemonic phrase, deriving the tree root at path m/44'/1237'/727'/0'/0'.

```APIDOC
## fromMnemonic(mnemonic: string, passphrase?: string)

### Description
Creates a TreeRoot from a BIP-39 mnemonic phrase. This is the recommended entry point for new users who want full recoverability from 12 words.

### Parameters
- **mnemonic** (string) - Required - The 12-word BIP-39 mnemonic phrase.
- **passphrase** (string) - Optional - An optional BIP-39 passphrase.

### Response
- **TreeRoot** (object) - An object representing the root of the identity tree, capable of deriving child identities.
```

--------------------------------

### fromNsec

Source: https://context7.com/forgesworn/nsec-tree/llms.txt

Creates a TreeRoot from an existing bech32 nsec string or raw 32-byte key.

```APIDOC
## fromNsec(key: string | Uint8Array)

### Description
Creates a TreeRoot from an existing bech32 nsec string or raw 32-byte key. Uses an intermediate HMAC to separate the signing key from the derivation key.

### Parameters
- **key** (string | Uint8Array) - Required - The bech32 nsec string or raw 32-byte key.

### Response
- **TreeRoot** (object) - An object representing the root of the identity tree.
```

--------------------------------

### Create TreeRoot from BIP-39 Mnemonic

Source: https://context7.com/forgesworn/nsec-tree/llms.txt

Initialize a TreeRoot using a mnemonic phrase for full recoverability. The root should be destroyed after use to clear sensitive data.

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

const mnemonic = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about'

// Create tree root from mnemonic (optional passphrase as second argument)
const root = fromMnemonic(mnemonic)

// Derive purpose-tagged identities
const social = derive(root, 'social')
const commerce = derive(root, 'commerce')

console.log(social.npub)    // npub1rf...
console.log(commerce.npub)  // npub1gsp... (different, unlinkable)

// Deterministic: same mnemonic always produces the same keys
const root2 = fromMnemonic(mnemonic)
const social2 = derive(root2, 'social')
console.log(social.npub === social2.npub)  // true

// Clean up secrets when done
root.destroy()
root2.destroy()
```

--------------------------------

### Create TreeRoot from Existing nsec

Source: https://context7.com/forgesworn/nsec-tree/llms.txt

Initialize a TreeRoot from an existing nsec string or raw 32-byte key. Import from nsec-tree/core to minimize dependencies.

```typescript
import { fromNsec, derive, zeroise } from 'nsec-tree/core'

// Use an existing nsec — no mnemonic migration needed
const root = fromNsec('nsec1qyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqstywftw')

// Derive child identities
const social = derive(root, 'social')
const throwaway = derive(root, 'throwaway', 42)  // Custom index

console.log(social.npub)       // npub1...
console.log(throwaway.npub)    // npub1... (index 42)
console.log(throwaway.index)   // 42

// Also accepts raw 32-byte Uint8Array
const rawKey = new Uint8Array(32).fill(1)
const rootFromBytes = fromNsec(rawKey)

// Clean up
root.destroy()
rootFromBytes.destroy()
```

--------------------------------

### Project directory structure

Source: https://github.com/forgesworn/nsec-tree/blob/main/CONTRIBUTING.md

Overview of the source code organization and module responsibilities.

```text
src/
  types.ts         — Interfaces, error types, internal WeakMap
  encoding.ts      — NIP-19 bech32 (nsec/npub)
  validate.ts      — Purpose string validation
  derive.ts        — HMAC-SHA256 child key derivation + public derive()/zeroise()
  root-nsec.ts     — fromNsec(), createTreeRoot(), FinalizationRegistry
  root-mnemonic.ts — fromMnemonic() (BIP-32, imports @scure/bip32+bip39)
  recover.ts       — Scan-based identity recovery
  proof.ts         — BIP-340 Schnorr linkage proofs
  index.ts         — Full API re-export
  core.ts          — No-BIP-deps re-export (imports root-nsec, not root-mnemonic)
  mnemonic.ts      — fromMnemonic-only re-export
```

--------------------------------

### Derive nsec-tree keys for Vector 2

Source: https://github.com/forgesworn/nsec-tree/blob/main/PROTOCOL.md

Input parameters and derivation steps for nsec root, purpose 'commerce', index 0.

```text
nsec_bytes:  0101010101010101010101010101010101010101010101010101010101010101
purpose:     "commerce"
index:       0
```

```text
message      = 6e7365632d7472656500636f6d6d657263650000000000  (23 bytes)
child_priv   = fc62a2ec7f91970c485f9d7453268d1a6a07273ee829cf44c87685f78758f04f
child_pub    = 8441f7e2a73fea0742ccd12858bd5b95ccae385fbcb2856b7d7177880198a663
child_nsec   = nsec1l3329mrljxtscjzln469xf5drf4qwfe7aq5u73xgw6zl0p6c7p8sd6vumk
actual_index = 0
```

--------------------------------

### Create and verify linkage proofs

Source: https://github.com/forgesworn/nsec-tree/blob/main/llms-full.txt

Generate a blind proof to verify master ownership of a child identity without revealing the derivation path.

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

// Prove master owns child without revealing derivation slot
const proof = createBlindProof(root, child)
const valid = verifyProof(proof) // true
```

--------------------------------

### Linkage Proof Attestation Formats

Source: https://github.com/forgesworn/nsec-tree/blob/main/PROTOCOL.md

The string construction formats for blind and full linkage attestations.

```text
attestation = "nsec-tree:own|" || hex(master_xonly_pub) || "|" || hex(child_xonly_pub)
```

```text
attestation = "nsec-tree:link|" || hex(master_xonly_pub) || "|" || hex(child_xonly_pub) || "|" || purpose || "|" || decimal(index)
```

--------------------------------

### Create Full Ownership Proof

Source: https://context7.com/forgesworn/nsec-tree/llms.txt

Generates a Schnorr proof of ownership that explicitly reveals the derivation purpose and index.

```typescript
import { fromMnemonic, derive } from 'nsec-tree'
import { createFullProof, verifyProof } from 'nsec-tree/proof'

const root = fromMnemonic('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about')
const social = derive(root, 'social')

// Create full proof — reveals purpose and index
const proof = createFullProof(root, social)

console.log('Full proof:')
console.log(`  masterPubkey: ${proof.masterPubkey}`)
console.log(`  childPubkey:  ${proof.childPubkey}`)
console.log(`  purpose:      ${proof.purpose}`)  // 'social'
console.log(`  index:        ${proof.index}`)    // 0
console.log(`  attestation:  ${proof.attestation}`)
// "nsec-tree:link|<master>|<child>|social|0"
console.log(`  signature:    ${proof.signature.slice(0, 32)}...`)

// Verify
console.log(`  valid: ${verifyProof(proof)}`)  // true

// Tampered proof fails verification
const tampered = { ...proof, childPubkey: '00'.repeat(32) }
console.log(`\nTampered proof valid? ${verifyProof(tampered)}`)  // false

root.destroy()
```

--------------------------------

### Key Derivation Loop

Source: https://github.com/forgesworn/nsec-tree/blob/main/PROTOCOL.md

The algorithm for deriving a private key, including retry logic for invalid curve order outputs.

```pseudocode
current_index = requested_index
while current_index <= 0xFFFFFFFF:
    msg = utf8("nsec-tree") || 0x00 || utf8(purpose) || 0x00 || uint32_be(current_index)
    candidate = HMAC-SHA256(key = tree_root, msg = msg)
    if candidate < n:
        return (candidate, current_index)
    current_index += 1
error("index overflow")
```

--------------------------------

### Linkage Proofs

Source: https://github.com/forgesworn/nsec-tree/blob/main/llms-full.txt

Functions for creating and verifying linkage proofs.

```APIDOC
## Linkage Proofs

### `createBlindProof(root, child)`

BIP-340 Schnorr proof that master owns child, without revealing derivation slot.

### Method

`createBlindProof`

### Parameters

#### Path Parameters

- **root** (TreeRoot) - Required - The root of the derivation tree.
- **child** (Identity) - Required - The child identity.

### Response

#### Success Response (200)

- **LinkageProof** - The generated blind linkage proof.

---

### `createFullProof(root, child)`

Like blind proof, but also reveals purpose and index.

### Method

`createFullProof`

### Parameters

#### Path Parameters

- **root** (TreeRoot) - Required - The root of the derivation tree.
- **child** (Identity) - Required - The child identity.

### Response

#### Success Response (200)

- **LinkageProof** - The generated full linkage proof.

---

### `verifyProof(proof)`

Verify a LinkageProof.

### Method

`verifyProof`

### Parameters

#### Path Parameters

- **proof** (LinkageProof) - Required - The linkage proof to verify.

### Response

#### Success Response (200)

- **boolean** - True if the proof is valid, false otherwise.

```

--------------------------------

### Derive nsec-tree keys for Vector 1

Source: https://github.com/forgesworn/nsec-tree/blob/main/PROTOCOL.md

Input parameters and derivation steps for nsec root, purpose 'social', index 0.

```text
nsec_bytes:  0101010101010101010101010101010101010101010101010101010101010101
purpose:     "social"
index:       0
```

```text
tree_root    = HMAC-SHA256(key = nsec_bytes, msg = utf8("nsec-tree-root"))
             = 8d2db9ce9548534e7ae924d05e311355e3a12744214c88e65b39fa2bf2df6d6f
master_pub   = secp256k1_x_only(tree_root)
             = 8c03e047ae60c01e942a8337e71d17e3517fcc63ee6ceff8173bbd23fabe649d
master_npub  = npub13sp7q3awvrqpa9p2svm7w8ghudghlnrraekwl7qh8w7j8747vjwskvzy2u
```

```text
message      = 6e7365632d7472656500736f6369616c0000000000  (21 bytes)
child_priv   = HMAC-SHA256(key = tree_root, msg = message)
             = 98e98b476eab3c2bcb5020e4a679a41b74eebfb30a07944c4361c906501265e7
child_pub    = secp256k1_x_only(child_priv)
             = cdc4cd2a01ba1b8afd3299b66c38d13043a19acb687c334f0527cffaf464b372
child_nsec   = nsec1nr5ck3mw4v7zhj6syrj2v7dyrd6wa0anpgregnzrv8ysv5qjvhnsafv7mx
child_npub   = npub1ehzv62sphgdc4lfjnxmxcwx3xpp6rxktdp7rxnc9yl8l4arykdeqyfhrxy
actual_index = 0
```

--------------------------------

### Derive nsec-tree keys for Vector 3

Source: https://github.com/forgesworn/nsec-tree/blob/main/PROTOCOL.md

Input parameters and derivation steps for nsec root, purpose 'social', index 1.

```text
nsec_bytes:  0101010101010101010101010101010101010101010101010101010101010101
purpose:     "social"
index:       1
```

```text
message      = 6e7365632d7472656500736f6369616c0000000001  (21 bytes)
child_priv   = 802a2fd31d25517bd2bb9b7196c377e6cc2f32728b916c2c3ea71ca703767917
child_pub    = aed0bc4ccccdb868156e38cabf3a6acb98f8fa8a4abe0dcc68851d8468a87cd1
child_nsec   = nsec1sq4zl5cay4ghh54mndcedsmhumxz7vnj3wgkctp75uw2wqmk0yts3ny5vz
actual_index = 1
```

--------------------------------

### Verify path independence for Vector 5

Source: https://github.com/forgesworn/nsec-tree/blob/main/PROTOCOL.md

Comparison of tree roots derived from the same mnemonic via mnemonic path vs. nsec path.

```text
mnemonic     = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
tree_root    = cc92d213b5eccd19eb85c12c2cf6fd168f27c2cc347c51a7c4c62ac67795fc65
master_pub   = 3eb14b67cc942c5388e03570b68d0887d40ff34af234662344e6c72a6298d656
master_npub  = npub186c5ke7vjsk98z8qx4ctdrggsl2qlu627g6xvg6yumrj5c5c6etqcfaclx
```

```text
nsec_bytes   = 5f29af3b9676180290e77a4efad265c4c2ff28a5302461f73597fda26bb25731
tree_root    = 3ac534dcff9286225e0a254aade75a991a1f41fcbe719cc7dd899dd833b6e4d6
master_pub   = 4e444e24184d8b303bbbc6a7a4b97b8906ab8e475e2864bd71043d45819612ae
master_npub  = npub1fezyufqcfk9nqwamc6n6fwtm3yr2hrj8tc5xf0t3qs75tqvkz2hq40tnpd
```

--------------------------------

### Generate Full Attestation Signature

Source: https://github.com/forgesworn/nsec-tree/blob/main/docs/NIP-XXXX.md

Creates a full attestation to prove ownership and reveal the derivation slot (purpose and index). The attestation string includes the purpose and index, then is signed using the tree root.

```plaintext
attestation = "nsec-tree:link|" || hex(master_pub) || "|" || hex(child_pub) || "|" || purpose || "|" || decimal(index)
signature   = schnorr_sign(utf8(attestation), tree_root)
```

--------------------------------

### Create Blind Ownership Proof

Source: https://context7.com/forgesworn/nsec-tree/llms.txt

Generates a Schnorr proof of ownership that hides the derivation purpose and index.

```typescript
import { fromMnemonic, derive } from 'nsec-tree'
import { createBlindProof, verifyProof } from 'nsec-tree/proof'

const root = fromMnemonic('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about')
const social = derive(root, 'social')

// Create blind proof — hides purpose and index
const proof = createBlindProof(root, social)

console.log('Blind proof:')
console.log(`  masterPubkey: ${proof.masterPubkey}`)  // 64-char hex
console.log(`  childPubkey:  ${proof.childPubkey}`)   // 64-char hex
console.log(`  purpose:      ${proof.purpose ?? '(hidden)'}`)  // undefined
console.log(`  index:        ${proof.index ?? '(hidden)'}`)    // undefined
console.log(`  attestation:  ${proof.attestation}`)
// "nsec-tree:own|<master>|<child>"
console.log(`  signature:    ${proof.signature.slice(0, 32)}...`)  // 128-char hex

// Verify the proof (anyone can verify without secrets)
const valid = verifyProof(proof)
console.log(`  valid: ${valid}`)  // true

// Use case: prove rotated identity is same master
const socialRotated = derive(root, 'social', 1)
const rotationProof = createBlindProof(root, socialRotated)
console.log(`\nRotation proof valid? ${verifyProof(rotationProof)}`)  // true

root.destroy()
```

--------------------------------

### Derive identities from an existing nsec

Source: https://github.com/forgesworn/nsec-tree/blob/main/llms-full.txt

Initialize a root from an existing nsec string using the core module to avoid BIP-32/39 dependencies.

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

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

--------------------------------

### Derivation Protocol

Source: https://github.com/forgesworn/nsec-tree/blob/main/llms-full.txt

Details on the derivation protocols used for Tree Roots and child keys.

```APIDOC
## Derivation Protocol

### Tree Root (Mnemonic Path)

BIP-39 mnemonic -> BIP-32 seed -> derive at `m/44'/1237'/727'/0'/0'` (all hardened) -> 32-byte tree root.

### Tree Root (nsec Path)

`tree_root = HMAC-SHA256(key = nsec_bytes, msg = "nsec-tree-root")`

Intermediate HMAC ensures the nsec is never used directly as HMAC key. One-way separation between signing key and derivation key.

### Child Key Derivation

`child = HMAC-SHA256(key = tree_root, msg = "nsec-tree\0" || purpose || "\0" || uint32_be(index))`

Domain-separated with null bytes. If HMAC output >= secp256k1 curve order n, index is incremented (probability ~3.7x10^-39).

```

--------------------------------

### Attestation Signing and Verification

Source: https://github.com/forgesworn/nsec-tree/blob/main/PROTOCOL.md

The process for signing an attestation using BIP-340 and verifying the resulting signature.

```pseudocode
signature = schnorr_sign(utf8(attestation), tree_root)
```

```pseudocode
expected_attestation = canonical_attestation_from_fields(proof)
if expected_attestation != proof.attestation:
    return false
valid = schnorr_verify(signature, utf8(attestation), master_xonly_pub)
```

--------------------------------

### fromEvent

Source: https://context7.com/forgesworn/nsec-tree/llms.txt

Extracts a LinkageProof from a NIP-78 event's tags.

```APIDOC
## fromEvent

### Description
Extracts a LinkageProof from a NIP-78 event's tags. Throws NsecTreeError if the event does not contain a valid nsec-tree proof.

### Parameters
#### Request Body
- **event** (Object) - Required - The Nostr event object to parse.

### Response
#### Success Response (200)
- **proof** (LinkageProof) - The extracted proof object.
```

--------------------------------

### Derive Child Keypair

Source: https://github.com/forgesworn/nsec-tree/blob/main/docs/NIP-XXXX.md

Derives a child private key and public key from the tree root using a purpose string and index.

```text
message      = utf8("nsec-tree") || 0x00 || utf8(purpose) || 0x00 || uint32_be(index)
child_privkey = HMAC-SHA256(key = tree_root, msg = message)
child_pubkey  = secp256k1_x_only(child_privkey)
```

--------------------------------

### nsec-tree Linkage Proof Functions

Source: https://github.com/forgesworn/nsec-tree/blob/main/llms.txt

Functions for creating, verifying, and publishing linkage proofs.

```APIDOC
## nsec-tree Linkage Proof Functions

### Description
Provides functionality to create, verify, and manage linkage proofs, which are Schnorr attestations proving ownership of a child identity by a master secret. These proofs can be used for selective disclosure and published on Nostr.

### Functions

#### `createBlindProof(root, child)`
- **Description**: Create a blind linkage proof, proving ownership without revealing the derivation slot.
- **Parameters**:
  - `root` (TreeRoot) - Required - The master TreeRoot object.
  - `child` (Identity) - Required - The child identity object to create a proof for.
- **Returns**: `LinkageProof` - The blind linkage proof object.

#### `createFullProof(root, child)`
- **Description**: Create a full linkage proof, proving ownership and revealing the purpose and index.
- **Parameters**:
  - `root` (TreeRoot) - Required - The master TreeRoot object.
  - `child` (Identity) - Required - The child identity object to create a proof for.
- **Returns**: `LinkageProof` - The full linkage proof object.

#### `verifyProof(proof)`
- **Description**: Verify the validity of a linkage proof.
- **Parameters**:
  - `proof` (LinkageProof) - Required - The linkage proof object to verify.
- **Returns**: `boolean` - True if the proof is valid, false otherwise.

#### `deriveFromIdentity(identity, purpose, index?)`
- **Description**: Derive a child identity from any existing identity (supports arbitrary-depth hierarchies).
- **Parameters**:
  - `identity` (Identity) - Required - The parent identity object.
  - `purpose` (string) - Required - The purpose string for the new child identity.
  - `index` (number) - Optional - The derivation index for the new child identity.
- **Returns**: `Identity` - The newly derived child identity.

### Example Usage
```typescript
import { fromMnemonic, derive } from 'nsec-tree';
import { createFullProof, verifyProof } from 'nsec-tree/proof';

const root = fromMnemonic('your twelve word mnemonic phrase here ...');
const social = derive(root, 'social');
const proof = createFullProof(root, social);
const isValid = verifyProof(proof);
console.log(`Proof is valid: ${isValid}`);
root.destroy();
```
```

--------------------------------

### Implement Bot Fleet Pattern

Source: https://context7.com/forgesworn/nsec-tree/llms.txt

Derive multiple sequential identities for automated services and use recovery functions to rediscover them from the root seed.

```typescript
import { fromMnemonic, derive, recover } from 'nsec-tree'

const root = fromMnemonic('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about')

console.log('Deriving 10 bot identities:\n')

// Derive bots at indices 0-9
const bots = Array.from({ length: 10 }, (_, i) => derive(root, 'bot', i))

for (const bot of bots) {
  console.log(`  bot/${bot.index}: ${bot.npub}`)
}

// Recovery: scan the 'bot' purpose to rediscover all
console.log('\nRecovering bot fleet...\n')
const found = recover(root, ['bot'], 10)
const recovered = found.get('bot')!

console.log(`Recovered ${recovered.length} bots`)
console.log(`All match? ${bots.every((b, i) => b.npub === recovered[i]!.npub)}`)  // true

root.destroy()
```

--------------------------------

### Derive nsec-tree keys for Vector 4

Source: https://github.com/forgesworn/nsec-tree/blob/main/PROTOCOL.md

Input parameters and derivation steps for mnemonic root, purpose 'social', index 0.

```text
mnemonic:    "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
passphrase:  (none)
purpose:     "social"
index:       0
```

```text
BIP-32 path  = m/44'/1237'/727'/0'/0'
tree_root    = cc92d213b5eccd19eb85c12c2cf6fd168f27c2cc347c51a7c4c62ac67795fc65
master_pub   = 3eb14b67cc942c5388e03570b68d0887d40ff34af234662344e6c72a6298d656
master_npub  = npub186c5ke7vjsk98z8qx4ctdrggsl2qlu627g6xvg6yumrj5c5c6etqcfaclx
```

```text
child_priv   = f0e7c85f394df83212e108e60a7e226045742aa6d967ea1cfddf27ae65ac6ac8
child_pub    = 1a4e31045ee7be1fc736954ffe7ea48fffc784865452a79545a027d0e712fc97
child_nsec   = nsec17rnusheefhuryyhpprnq5l3zvpzhg24xm9n7588amun6uedvdtyqnpcsm4
actual_index = 0
```

--------------------------------

### Linkage Proofs

Source: https://github.com/forgesworn/nsec-tree/blob/main/README.md

Functions for creating and verifying linkage proofs to demonstrate ownership of derived identities.

```APIDOC
## createBlindProof(root, child)

### Description
Create a BIP-340 Schnorr proof that the master owns a child identity, without revealing the derivation path.

### Method
`createBlindProof`

### Parameters
- **root** (TreeRoot) - Required - The root of the identity tree.
- **child** (Identity) - Required - The child identity to prove ownership of.

### Response
- **LinkageProof** - The generated blind linkage proof.
```

```APIDOC
## createFullProof(root, child)

### Description
Create a linkage proof that also reveals the purpose and index of the derived identity.

### Method
`createFullProof`

### Parameters
- **root** (TreeRoot) - Required - The root of the identity tree.
- **child** (Identity) - Required - The child identity to prove ownership of.

### Response
- **LinkageProof** - The generated full linkage proof.
```

```APIDOC
## verifyProof(proof)

### Description
Verify the cryptographic validity of a `LinkageProof`.

### Method
`verifyProof`

### Parameters
- **proof** (LinkageProof) - Required - The linkage proof to verify.

### Response
- **boolean** - `true` if the proof is valid, `false` otherwise.
```

--------------------------------

### Publish linkage proofs to Nostr

Source: https://github.com/forgesworn/nsec-tree/blob/main/llms-full.txt

Convert a proof to an unsigned event for publication, and recover it from a signed event for verification.

```typescript
import { toUnsignedEvent, fromEvent } from 'nsec-tree/event'

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

// On the verifier side:
const recovered = fromEvent(signedEvent)
const isValid = verifyProof(recovered)
```

--------------------------------

### Constants

Source: https://github.com/forgesworn/nsec-tree/blob/main/llms-full.txt

Exported constants for nsec-tree operations.

```APIDOC
## Constants

- **DEFAULT_SCAN_RANGE**: `20` - Default recovery scan range (BIP-44 gap limit).
- **MAX_SCAN_RANGE**: `10000` - Maximum scan range (prevents self-DoS).
- **MAX_INDEX**: `0xFFFFFFFF` - Maximum derivation index (uint32).
- **NSEC_TREE_EVENT_KIND**: `30078` - NIP-78 application-specific data kind.
- **NSEC_TREE_D_PREFIX**: `"nsec-tree:"` - Namespace prefix for d-tags.
- **DEFAULT_PERSONA_NAMES**: `['personal', 'bitcoiner', 'work', 'social', 'anonymous']` - Default names for persona recovery.

```

--------------------------------

### Subpath Exports

Source: https://github.com/forgesworn/nsec-tree/blob/main/llms-full.txt

Available imports from different subpaths of the nsec-tree library.

```APIDOC
## Subpath Exports

- **`nsec-tree`**: Full API (all functions, types, constants). Requires BIP-32/39 dependencies.
- **`nsec-tree/core`**: `fromNsec`, `derive`, `recover`, `zeroise`, `deriveFromIdentity`. Does not require BIP-32/39 dependencies.
- **`nsec-tree/mnemonic`**: `fromMnemonic` only. Requires BIP-32/39 dependencies.
- **`nsec-tree/proof`**: `createBlindProof`, `createFullProof`, `verifyProof`. Does not require BIP-32/39 dependencies.
- **`nsec-tree/persona`**: `derivePersona`, `deriveFromPersona`, `recoverPersonas`, `DEFAULT_PERSONA_NAMES`. Does not require BIP-32/39 dependencies.
- **`nsec-tree/event`**: `toUnsignedEvent`, `fromEvent`, `NSEC_TREE_EVENT_KIND`, `NSEC_TREE_D_PREFIX`. Does not require BIP-32/39 dependencies.
- **`nsec-tree/encoding`**: `encodeNsec`, `decodeNsec`, `encodeNpub`, `decodeNpub`. Does not require BIP-32/39 dependencies.

Use `nsec-tree/core` if you only need nsec-based derivation to avoid pulling in BIP-32/39 dependencies.

```

--------------------------------

### nsec Path Test Vector - Input

Source: https://github.com/forgesworn/nsec-tree/blob/main/docs/NIP-XXXX.md

Input parameters for deriving keys from an nsec byte array. Ensure the nsec_bytes are correctly formatted.

```text
nsec_bytes:  0101010101010101010101010101010101010101010101010101010101010101
purpose:     "social"
index:       0
```

--------------------------------

### Nostr Event Integration

Source: https://github.com/forgesworn/nsec-tree/blob/main/README.md

Functions for converting linkage proofs into Nostr events for publishing.

```APIDOC
## toUnsignedEvent(proof)

### Description
Convert a `LinkageProof` into an unsigned NIP-78 Kind 30078 Nostr event.

### Method
`toUnsignedEvent`

### Parameters
- **proof** (LinkageProof) - Required - The linkage proof to convert.

### Response
- **object** - An unsigned Nostr event object that can be signed and published.
```

```APIDOC
## fromEvent(event)

### Description
Extract a `LinkageProof` from a NIP-78 event's tags.

### Method
`fromEvent`

### Parameters
- **event** (object) - Required - The Nostr event object.

### Response
- **LinkageProof | null** - The extracted linkage proof, or null if not found or invalid.
```

--------------------------------

### Identity Recovery and Management

Source: https://github.com/forgesworn/nsec-tree/blob/main/README.md

Functions for recovering identities and securely managing private keys.

```APIDOC
## recover(root, purposes, scanRange?)

### Description
Scan multiple purposes and indices, returning a map of derived identities.

### Method
`recover`

### Parameters
- **root** (TreeRoot) - Required - The root of the identity tree.
- **purposes** (string[]) - Required - An array of purpose tags to scan for.
- **scanRange** (number) - Optional - The number of indices to scan for each purpose. Defaults to 20 (BIP-44 gap limit).

### Response
- **Map<string, Identity[]>** - A map where keys are purpose tags and values are arrays of derived identities.
```

```APIDOC
## zeroise(identity)

### Description
Zero the private key bytes of a derived identity to securely discard it.

### Method
`zeroise`

### Parameters
- **identity** (Identity) - Required - The identity object whose private key should be zeroed.
```

--------------------------------

### Integrate nsec-tree with nostr-tools

Source: https://context7.com/forgesworn/nsec-tree/llms.txt

Use derived identity private keys directly with nostr-tools for signing events. Ensure root identities are destroyed after use to clear sensitive data.

```typescript
import { fromMnemonic, derive } from 'nsec-tree'
import { finalizeEvent, verifyEvent } from 'nostr-tools/pure'

const root = fromMnemonic('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about')
const social = derive(root, 'social')

console.log(`Signing identity: ${social.npub}`)

// finalizeEvent accepts Uint8Array — identity.privateKey works directly
const event = finalizeEvent({
  kind: 1,
  created_at: Math.floor(Date.now() / 1000),
  tags: [],
  content: 'Hello from a derived nsec-tree identity!',
}, social.privateKey)

console.log('Signed event:')
console.log(`  id:      ${event.id}`)
console.log(`  pubkey:  ${event.pubkey}`)
console.log(`  kind:    ${event.kind}`)
console.log(`  content: ${event.content}`)
console.log(`  sig:     ${event.sig.slice(0, 32)}...`)

// Verify — standard Nostr verification
const valid = verifyEvent(event)
console.log(`\nValid Nostr event? ${valid}`)  // true

root.destroy()
```

--------------------------------

### Derive Child Key with Curve Order Handling

Source: https://github.com/forgesworn/nsec-tree/blob/main/docs/NIP-XXXX.md

Derives a child key by repeatedly calculating HMAC-SHA256 until the output is less than the secp256k1 curve order 'n'. Increments the index if the candidate key is too large. The returned index is the one actually used.

```python
current_index = requested_index
while current_index <= 0xFFFFFFFF:
    msg       = utf8("nsec-tree") || 0x00 || utf8(purpose) || 0x00 || uint32_be(current_index)
    candidate = HMAC-SHA256(key = tree_root, msg = msg)
    if candidate < n:
        return (candidate, current_index)
    current_index += 1
error("index overflow")
```

--------------------------------

### NIP-78 Events

Source: https://github.com/forgesworn/nsec-tree/blob/main/llms-full.txt

Functions for converting linkage proofs to NIP-78 events and extracting proofs from events.

```APIDOC
## NIP-78 Events

### `toUnsignedEvent(proof)`

Convert LinkageProof to unsigned Kind 30078 Nostr event.

### Method

`toUnsignedEvent`

### Parameters

#### Path Parameters

- **proof** (LinkageProof) - Required - The linkage proof to convert.

### Response

#### Success Response (200)

- **UnsignedEvent** - The unsigned NIP-78 event.

---

### `fromEvent(event)`

Extract LinkageProof from a NIP-78 event's tags.

### Method

`fromEvent`

### Parameters

#### Path Parameters

- **event** (UnsignedEvent) - Required - The NIP-78 event.

### Response

#### Success Response (200)

- **LinkageProof** - The extracted linkage proof.

```

--------------------------------

### Extract Proof from NIP-78 Event

Source: https://context7.com/forgesworn/nsec-tree/llms.txt

Extracts a LinkageProof from a NIP-78 event's tags. Pass the result to verifyProof() to check cryptographic validity. Throws NsecTreeError if the event doesn't contain a valid nsec-tree proof. Useful for verifying received proofs.

```typescript
import { fromMnemonic, derive } from 'nsec-tree'
import { createFullProof, verifyProof } from 'nsec-tree/proof'
import { toUnsignedEvent, fromEvent } from 'nsec-tree/event'

const root = fromMnemonic('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about')
const social = derive(root, 'social')

// Create and convert proof to event
const originalProof = createFullProof(root, social)
const event = toUnsignedEvent(originalProof)

// Simulate receiving event from relay — extract proof from tags
const extractedProof = fromEvent(event)

console.log('Extracted proof from event:')
console.log(`  masterPubkey: ${extractedProof.masterPubkey}`)
console.log(`  childPubkey:  ${extractedProof.childPubkey}`)
console.log(`  purpose:      ${extractedProof.purpose}`)
console.log(`  index:        ${extractedProof.index}`)
console.log(`  attestation:  ${extractedProof.attestation}`)

// Verify the extracted proof
const valid = verifyProof(extractedProof)
console.log(`
  Valid? ${valid}`) 

// Extracted proof matches original
console.log(`  Matches original? ${extractedProof.masterPubkey === originalProof.masterPubkey}`) 

// Error handling for invalid events
try {
  fromEvent({ pubkey: 'invalid', tags: [] })
} catch (err) {
  console.log(`
Error: ${err.message}`)
}

root.destroy()
```

--------------------------------

### Derive identities from a BIP-39 mnemonic

Source: https://github.com/forgesworn/nsec-tree/blob/main/llms-full.txt

Create a root identity from a mnemonic and derive unlinkable child identities. Always call destroy() on the root to clear secret material from memory.

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

const root = fromMnemonic('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about')
const social = derive(root, 'social')
const commerce = derive(root, 'commerce')
console.log(social.npub)   // npub1... (unlinkable from commerce)
console.log(commerce.npub) // npub1... (different identity)
root.destroy() // zero secret material
```

--------------------------------

### NIP-19 Encoding Utilities

Source: https://context7.com/forgesworn/nsec-tree/llms.txt

Provides helpers for converting between raw bytes and NIP-19 bech32 format (nsec/npub). These utilities are also used internally by the library for encoding private and public keys.

```typescript
import { encodeNsec, decodeNsec, encodeNpub, decodeNpub } from 'nsec-tree/encoding'

// Encode raw bytes to bech32
const privateKey = new Uint8Array(32).fill(1)
const nsec = encodeNsec(privateKey)
console.log(`nsec: ${nsec}`) 

// Decode bech32 to raw bytes
const decoded = decodeNsec(nsec)
console.log(`Decoded length: ${decoded.length}`) 
console.log(`Matches original: ${privateKey.every((b, i) => b === decoded[i])}`) 

// Same for public keys
const publicKey = new Uint8Array(32).fill(2)
const npub = encodeNpub(publicKey)
console.log(`npub: ${npub}`)

const decodedPub = decodeNpub(npub)
console.log(`Decoded pubkey matches: ${publicKey.every((b, i) => b === decodedPub[i])}`) 

// Error handling
try {
  decodeNsec('npub1...')
} catch (err) {
  console.log(`Error: ${err.message}`)
}
```

--------------------------------

### NIP-19 Encoding Utilities

Source: https://context7.com/forgesworn/nsec-tree/llms.txt

Utilities for converting between raw bytes and NIP-19 bech32 format (nsec/npub).

```APIDOC
## NIP-19 Encoding Utilities

### Description
Provides functions to encode and decode private (nsec) and public (npub) keys using bech32 format.

### Functions
- **encodeNsec(bytes)**: Encodes raw bytes to nsec string.
- **decodeNsec(nsec)**: Decodes nsec string to raw bytes.
- **encodeNpub(bytes)**: Encodes raw bytes to npub string.
- **decodeNpub(npub)**: Decodes npub string to raw bytes.
```

--------------------------------

### Convert Proof to NIP-78 Nostr Event

Source: https://context7.com/forgesworn/nsec-tree/llms.txt

Converts a LinkageProof to an unsigned NIP-78 Kind 30078 Nostr event. The application must sign and publish the event using its own Nostr library. Useful for publishing proofs to relays.

```typescript
import { fromMnemonic, derive } from 'nsec-tree'
import { createBlindProof, createFullProof } from 'nsec-tree/proof'
import { toUnsignedEvent, NSEC_TREE_EVENT_KIND, NSEC_TREE_D_PREFIX } from 'nsec-tree/event'

const root = fromMnemonic('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about')
const social = derive(root, 'social')

// Create proofs
const blindProof = createBlindProof(root, social)
const fullProof = createFullProof(root, social)

// Convert blind proof to unsigned event
const blindEvent = toUnsignedEvent(blindProof)

console.log('Unsigned NIP-78 event (blind proof):')
console.log(`  kind:       ${blindEvent.kind}`)
console.log(`  pubkey:     ${blindEvent.pubkey}`)
console.log(`  created_at: ${blindEvent.created_at}`)
console.log(`  content:    "${blindEvent.content}"`) 
console.log(`  tags:`) 
for (const tag of blindEvent.tags) {
  console.log(`    ${JSON.stringify(tag)}`)
}

// Full proof includes purpose and index tags
const fullEvent = toUnsignedEvent(fullProof)
console.log('
Full proof tags:')
for (const tag of fullEvent.tags) {
  console.log(`  ${JSON.stringify(tag)}`)
}

// Sign and publish with nostr-tools or any Nostr library
// import { finalizeEvent } from 'nostr-tools/pure' 
// const signed = finalizeEvent(blindEvent, root.privateKey)
// await relay.publish(signed)

console.log(`
Event kind constant: ${NSEC_TREE_EVENT_KIND}`)
console.log(`D-tag prefix: ${NSEC_TREE_D_PREFIX}`)

root.destroy()
```

--------------------------------

### Derive Tree Root from Mnemonic

Source: https://github.com/forgesworn/nsec-tree/blob/main/docs/NIP-XXXX.md

Derives the tree root secret using a BIP-39 mnemonic and a specific hardened derivation path.

```text
BIP-39 mnemonic (with optional passphrase)
  -> BIP-32 seed
  -> derive child at m/44'/1237'/727'/0'/0'  (all five levels hardened)
  -> 32-byte private key = tree_root
```

```text
master_pubkey = secp256k1_x_only(tree_root)
```

--------------------------------

### Build a hierarchical identity structure

Source: https://github.com/forgesworn/nsec-tree/blob/main/llms-full.txt

Create nested identities using deriveFromIdentity to establish a parent-child relationship.

```typescript
import { fromMnemonic, deriveFromIdentity } from 'nsec-tree'

const root = fromMnemonic('abandon abandon ... about')
const work = derive(root, 'work')
const companyA = deriveFromIdentity(work, 'company:a')
const payroll = deriveFromIdentity(companyA, 'payroll')
// Path: master -> work -> company:a -> payroll
```

--------------------------------

### toUnsignedEvent

Source: https://context7.com/forgesworn/nsec-tree/llms.txt

Converts a LinkageProof object into an unsigned NIP-78 Kind 30078 Nostr event.

```APIDOC
## toUnsignedEvent

### Description
Converts a LinkageProof to an unsigned NIP-78 Kind 30078 Nostr event for publishing to relays.

### Parameters
#### Request Body
- **proof** (LinkageProof) - Required - The proof object to convert.

### Response
#### Success Response (200)
- **event** (Object) - The unsigned Nostr event object containing kind, pubkey, created_at, content, and tags.
```

--------------------------------

### nsec Path Test Vector - Child Derivation

Source: https://github.com/forgesworn/nsec-tree/blob/main/docs/NIP-XXXX.md

Details of the child key derivation, including the message, child private key, child public key, and the actual index used. This verifies the final derivation step.

```text
message:      6e7365632d7472656500736f6369616c0000000000  (21 bytes)
child_priv:   98e98b476eab3c2bcb5020e4a679a41b74eebfb30a07944c4361c906501265e7
child_pub:    cdc4cd2a01ba1b8afd3299b66c38d13043a19acb687c334f0527cffaf464b372
actual_index: 0
```
Tokens:
Raw