security hardening

docs/MASTER_PLAN.md

@@ -11,6 +11,8 @@
 | **BUG-3** | **IndeedHub WebSocket spam in console** | **P2** | PLANNED | - |
 | **FEATURE-4** | **Onboarding loading screen with progress** | **P1** | IN PROGRESS | - |
 | **INQUIRY-5** | **Offline balance check via mesh relay** | **P2** | PLANNED | - |
+| **FEATURE-6** | **Watch-only wallet architecture** | **P1** | PLANNED | - |
+| **TASK-7** | **Mesh Bitcoin security hardening** | **P1** | PLANNED | FEATURE-6 |
 
 ## Active Work
 
@@ -121,6 +123,64 @@ Design how to query wallet balance (LND/Bitcoin Core) from an off-grid node by r
 - [ ] Consider trust model — relay peer could lie about balance
 - [ ] Explore UTXO set proof (SPV-style) for trustless verification
 
+### FEATURE-6: Watch-only wallet architecture (PLANNED)
+**Priority**: P1 — High
+**Status**: PLANNED (2026-03-18)
+
+Archipelago should never hold private keys or seeds. Users create wallets on companion devices (Coldcard, SeedSigner, phone) and import xpubs to the node for watch-only tracking. The node creates unsigned PSBTs, the companion signs, and the node broadcasts.
+
+**Security rationale**: If the node is compromised (physical theft, remote exploit), no funds can be stolen — only xpubs are present, which reveal balances but cannot sign transactions. This is the standard for Bitcoin node OS security (see: Specter Desktop, Sparrow Wallet).
+
+**Design considerations**:
+- xpub import: QR scan, USB file, manual paste
+- PSBT workflow: create unsigned on node → transfer to companion → sign → return → broadcast
+- Hardware wallet compatibility: Coldcard (USB/SD), SeedSigner (QR), Passport (QR/USB)
+- Bitcoin Knots `importdescriptors` for watch-only wallet setup
+- Derive receive addresses from xpub (BIP84 native segwit, BIP86 taproot)
+- UTXO/balance tracking via watch-only wallet RPC
+- UI: receive address display, UTXO list, PSBT generation, transaction history
+
+**Key files**:
+- `core/archipelago/src/api/rpc/package.rs` — Bitcoin Knots container config
+- `neode-ui/src/views/Web5.vue` — Bitcoin/wallet UI
+- Bitcoin Knots RPC: `createwallet`, `importdescriptors`, `listunspent`, `walletcreatefundedpsbt`
+
+**Tasks**:
+- [ ] Research Bitcoin Knots watch-only wallet RPC workflow (createwallet, importdescriptors)
+- [ ] Design xpub import UI flow (QR scan, paste, file upload)
+- [ ] Implement watch-only wallet creation via RPC on first xpub import
+- [ ] Implement PSBT creation flow (select UTXOs → build unsigned PSBT → export)
+- [ ] Design PSBT transfer UX (QR animated export, file download, USB)
+- [ ] Implement signed PSBT import and broadcast
+- [ ] Build receive address derivation and display (BIP84/BIP86)
+- [ ] Add balance/UTXO tracking dashboard
+- [ ] Ensure no private key material ever touches the node (audit all wallet RPC calls)
+- [ ] Hardware wallet compatibility testing (Coldcard, SeedSigner)
+- [ ] Document the companion device setup guide
+
+### TASK-7: Mesh Bitcoin security hardening (PLANNED)
+**Priority**: P1 — High
+**Status**: PLANNED (2026-03-18)
+
+Implement the security gaps identified in the off-grid Bitcoin security analysis (`docs/mesh-bitcoin.md`, Section 12). These harden the existing mesh Bitcoin relay infrastructure against the most impactful attack vectors.
+
+**Reference**: `docs/mesh-bitcoin.md` — full analysis with severity ratings and effort estimates.
+
+**Tasks (ordered by severity × effort)**:
+- [ ] **G1**: Validate block header chain continuity — reject headers where `prev_hash` doesn't match stored header at height-1 (`BlockHeaderCache::store_header`)
+- [ ] **G5**: RBF detection — check nSequence on `TxRelayPayload`, warn/reject if RBF-signaled in off-grid context
+- [ ] **G9**: Timestamp sanity checking — reject headers with timestamps >2 hours in future or suspiciously old
+- [ ] **G3**: Sign `TxRelayResponse` with relay's Ed25519 key (`TypedEnvelope::new_signed`)
+- [ ] **G6**: BOLT11 invoice expiry validation — reject relay payment if invoice expires in <10 minutes
+- [ ] **G11**: Random broadcast delay jitter — relay adds 0-30s random delay before `sendrawtransaction` to resist timing analysis
+- [ ] **G2**: Validate proof-of-work on received block headers (check hash meets difficulty target)
+- [ ] **G4**: Encrypt dead man alerts to emergency contacts individually (not cleartext broadcast)
+- [ ] **G7**: Multi-relay header comparison — track headers by source, flag divergence between relays
+- [ ] **G8**: Merkle proof relay — new message type for SPV transaction inclusion verification
+- [ ] **G10**: Payment intent message type — signed envelope (destination, amount, timestamp) for non-repudiable records
+- [ ] **G12**: Evaluate Cashu/ecash integration for low-value off-grid payments (spike/prototype)
+- [ ] **G13**: Watch-only wallet integration with mesh relay (balance queries use local watch-only, not relay trust)
+
 ## Completed
 
 <!-- Done tasks are moved here -->