archy/.claude/plans/twinkly-baking-ladybug.md

BIP-39 Master Seed — Unified Key Derivation for Archipelago

Context

Archipelago's current identity system is broken:

• Node key generated randomly at boot, before the user exists
• Each identity creates independent random Ed25519 + secp256k1 keys
• ADR-008 says "both keys derived from same master seed" but code doesn't do this
• Backup only covers the node key, not identity keys
• No seed phrase — backup is an opaque encrypted blob with a user passphrase
• Restore path disabled ("Coming Soon")
• No connection between node identity and Bitcoin/LND wallet keys

Goal: One 24-word BIP-39 seed phrase derives ALL keys. User writes down 24 words, can recover everything on a fresh install.

---

Derivation Scheme

BIP-39 Mnemonic (24 words, 256-bit entropy)
  -> PBKDF2-HMAC-SHA512 (2048 rounds, empty passphrase)
  -> Master Seed (64 bytes)
     |
     +-- HKDF-SHA256(seed, info="archipelago/node/ed25519/v1")         -> Node Ed25519 key -> did:key
     +-- HKDF-SHA256(seed, info="archipelago/nostr-node/secp256k1/v1") -> Node Nostr key
     +-- HKDF-SHA256(seed, info="archipelago/identity/{i}/ed25519/v1") -> Identity i Ed25519 -> did:key
     +-- BIP-32 m/44'/1237'/0'/0/{i}                                   -> Identity i Nostr key (NIP-06)
     +-- BIP-32 m/84'/0'/0'                                            -> Bitcoin Core wallet (native segwit)
     +-- HKDF-SHA256(seed, info="archipelago/lnd/entropy/v1")          -> 16 bytes -> LND aezeed entropy

---

Phase 1: Seed Module (foundation)

New crates in core/archipelago/Cargo.toml

bip39 = "=2.1.0"
bitcoin = { version = "=0.32.5", features = ["rand-std"] }

New file: core/archipelago/src/seed.rs

MasterSeed struct — wraps Zeroizing<[u8; 64]>, implements ZeroizeOnDrop

Functions:

• MasterSeed::generate() -> (Mnemonic, MasterSeed) — 256-bit entropy, 24 words
• MasterSeed::from_mnemonic(mnemonic) -> MasterSeed — for restore
• MasterSeed::from_mnemonic_words(words: &str) -> Result<(Mnemonic, MasterSeed)> — parse + validate
• derive_node_ed25519(&MasterSeed) -> SigningKey — HKDF with info archipelago/node/ed25519/v1
• derive_identity_ed25519(&MasterSeed, index: u32) -> SigningKey — HKDF with info archipelago/identity/{index}/ed25519/v1
• derive_nostr_identity_key(&MasterSeed, index: u32) -> nostr_sdk::Keys — BIP-32 m/44'/1237'/0'/0/{index}
• derive_node_nostr_key(&MasterSeed) -> nostr_sdk::Keys — HKDF with info archipelago/nostr-node/secp256k1/v1
• derive_bitcoin_xprv(&MasterSeed) -> Xpriv — BIP-32 m/84'/0'/0'
• derive_lnd_entropy(&MasterSeed) -> [u8; 16] — HKDF with info archipelago/lnd/entropy/v1
• save_seed_encrypted(data_dir, mnemonic, passphrase) — Argon2+ChaCha20 to master_seed.enc
• load_seed_encrypted(data_dir, passphrase) -> Mnemonic
• seed_exists(data_dir) -> bool
• save_identity_index(data_dir, next_index: u32) / load_identity_index(data_dir) -> u32

Security: Never log seed/mnemonic. All seed types implement ZeroizeOnDrop. File permissions 0o600.

Existing building blocks to reuse:

• mesh/crypto.rs:hkdf_sha256() / hkdf_sha256_32() — already implemented
• backup/identity.rs encryption pattern — Argon2+ChaCha20 (reuse for save_seed_encrypted)
• ed25519-dalek, sha2, hmac, hkdf, zeroize — all in Cargo.toml already

---

Phase 2: Onboarding UI

New Vue views:

OnboardingSeedGenerate.vue — calls seed.generate, displays 24 words in grid, "I wrote these down" checkbox

OnboardingSeedVerify.vue — picks 4 random word positions, user types them back, calls seed.verify, shows DID + npub on success

OnboardingSeedRestore.vue — 24 input fields with BIP-39 wordlist autocomplete, calls seed.restore

New onboarding flow:

Intro -> Options (Fresh / Restore) -> [branch]

FRESH:  SeedGenerate -> SeedVerify -> Identity (name/purpose) -> Done
RESTORE: SeedRestore -> Done

Router changes (neode-ui/src/router/index.ts):

• Add routes: onboarding/seed, onboarding/seed-verify, onboarding/seed-restore
• Remove: onboarding/did, onboarding/backup, onboarding/verify
• Enable Restore path in OnboardingOptions.vue

RPC client (neode-ui/src/api/rpc-client.ts):

• generateSeed(), verifySeed(), restoreSeed(), saveSeedEncrypted(), seedStatus()

---

Phase 3: Backend Integration

identity.rs — add NodeIdentity::from_seed(identity_dir, &MasterSeed)

• Derives Ed25519 node key via seed::derive_node_ed25519()
• Writes to node_key / node_key.pub (same format as today)
• Existing load_or_create() unchanged (loads from disk, works for both seed-derived and legacy keys)

identity_manager.rs — seed-aware create()

• When seed available: derive Ed25519 from derive_identity_ed25519(seed, index), Nostr from derive_nostr_identity_key(seed, index)
• Increment and persist identity_index
• Add derivation_index: Option<u32> to IdentityFile (serde default, backward-compatible)
• When no seed (legacy): fall back to current random generation

server.rs — startup flow:

seed exists + node_key exists  -> Normal seed-backed operation
no seed + node_key exists      -> Legacy node, show migration prompt
no seed + no node_key          -> Fresh install, await onboarding
seed exists + no node_key      -> Re-derive from seed (recovery)

• Add seed_backed: bool to ServerInfo

New RPC endpoints in api/rpc/seed.rs:

• seed.generate — generates mnemonic, derives & writes node keys, returns words (onboarding only, unauth)
• seed.verify — validates user re-entered correct words (onboarding only)
• seed.restore — accepts 24 words, derives all keys, writes to disk (onboarding only, unauth)
• seed.save-encrypted — encrypts mnemonic to master_seed.enc (optional convenience)
• seed.status — returns { has_seed, is_legacy, identity_count, next_index }
• seed.derive-lnd-entropy — password-protected, returns 16 bytes for LND wallet init
• seed.derive-bitcoin-xprv — password-protected, returns xprv for Bitcoin Core import

In-memory mnemonic between seed.generate and seed.verify: held in Mutex<Option<Zeroizing<String>>> with 10-minute auto-clear timeout.

---

Phase 4: Bitcoin/LND Integration

LND wallet from seed:

• lnd.init-wallet-from-seed handler — derives 16-byte entropy, calls LND REST POST /v1/initwallet with seed_entropy
• Triggered during LND first-install flow

Bitcoin Core wallet from seed:

• bitcoin.init-wallet-from-seed handler — derives BIP-84 xprv, calls createwallet + importdescriptors via Bitcoin Core RPC
• Triggered during Bitcoin Core first-install flow

Both endpoints require password re-verification.

---

Phase 5: Migration & Polish

Legacy node migration:

• Detect legacy nodes (node_key exists, no master_seed.enc)
• Settings page shows prompt: "Set up seed phrase to protect future identities"
• Existing keys preserved — only NEW identities use seed derivation
• Optional full migration (seed.migrate-legacy) can be added later

Cleanup:

• Remove old OnboardingDid.vue, OnboardingBackup.vue, OnboardingVerify.vue
• Update Settings backup section to show seed status
• Update ADR-008 to reflect implementation matches description

---

File Layout After Implementation

{data_dir}/identity/
  node_key              # 32 bytes Ed25519 secret (derived from seed or legacy)
  node_key.pub          # 32 bytes Ed25519 public
  master_seed.enc       # NEW: encrypted mnemonic (optional convenience backup)
  identity_index        # NEW: next derivation index (plain text integer)
{data_dir}/identities/
  {uuid}.json           # Same format + optional derivation_index field

---

Critical Files to Modify

File	Change
core/archipelago/Cargo.toml	Add bip39, bitcoin crates
core/archipelago/src/seed.rs	NEW — all seed logic
core/archipelago/src/identity.rs	Add from_seed() constructor
core/archipelago/src/identity_manager.rs	Seed-aware create(), add derivation_index
core/archipelago/src/server.rs	Startup state detection (seed/legacy/fresh)
core/archipelago/src/api/rpc/seed.rs	NEW — seed RPC handlers
core/archipelago/src/api/rpc/dispatcher.rs	Register seed.* endpoints
neode-ui/src/views/OnboardingSeedGenerate.vue	NEW — show 24 words
neode-ui/src/views/OnboardingSeedVerify.vue	NEW — verify written words
neode-ui/src/views/OnboardingSeedRestore.vue	NEW — enter 24 words to restore
neode-ui/src/views/OnboardingOptions.vue	Enable Restore path
neode-ui/src/router/index.ts	Update onboarding routes
neode-ui/src/api/rpc-client.ts	Add seed RPC methods

---

Verification

1. Unit tests: Deterministic derivation (same mnemonic -> same keys), invalid mnemonic rejection, index increment, zeroization
2. Integration: Fresh install flow end-to-end, restore flow (generate on node A, enter words on node B, verify same DID/npub)
3. Security: Grep seed.rs for tracing macros that interpolate seed vars, verify file permissions
4. LND: Derive entropy, init wallet, verify deterministic aezeed
5. Bitcoin Core: Derive xprv, import descriptors, verify addresses match
6. Legacy: Existing node without seed starts normally, can still create identities
7. Type check: cd neode-ui && npx vue-tsc -b --noEmit