lfg2025/archy
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 33 Wiki Activity

feat: Phase 3 Week 1 — X3DH key agreement + HKDF foundation

Browse Source 
- Add hkdf = "0.12" dependency for Double Ratchet key derivation
- Extend mesh/crypto.rs with hkdf_sha256, hkdf_sha256_32, hkdf_sha256_64,
  and generate_x25519_ephemeral() for DH ratchet steps
- Create mesh/x3dh.rs: full X3DH key agreement protocol
  - PrekeyBundle generation with Ed25519-signed prekeys
  - 3-way (or 4-way) ECDH → HKDF-SHA256 → root key
  - Initiator and responder sides derive identical root key
  - CBOR encoding for mesh transmission
  - Bundle signature verification
  - 5 unit tests: generate+verify, both-sides-same-key,
    without-one-time-prekey, cbor-roundtrip, tamper-detection

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Dorian
2026-03-17 01:28:35 +00:00
parent d6bf9c5202
commit 1ced0fdbf3
5 changed files with 542 additions and 211 deletions
Download Patch File Download Diff File Expand all files Collapse all files

313
.claude/plans/luminous-snacking-snowflake.md
View File

@@ -1,247 +1,138 @@
# Phase 2: Mesh as Federation Transport
# Phase 3 & 4: Encrypted Mesh Messaging + Off-Grid Bitcoin Operations
## Context
Phase 1 built three independent communication silos: Tor-HTTP for federation, Meshcore LoRa for offline mesh, Nostr relays for discovery. They share no common abstraction — federation hardcodes Tor SOCKS5, mesh has its own serial listener, peer messaging uses a separate HTTP POST. Adding a new transport (LAN/mDNS) or changing routing logic means touching every caller.
Phase 1 built the mesh radio layer (Meshcore protocol, serial driver, basic chat). Phase 2 added transport abstraction (Mesh>LAN>Tor routing, CBOR delta sync, Reed-Solomon chunking). Current encryption is static X25519 shared secret per peer — no forward secrecy, no message type discrimination, no store-and-forward.
Phase 2 unifies these under a `NodeTransport` trait with automatic transport selection per peer (Mesh > LAN > Tor), chunked LoRa messaging with Reed-Solomon FEC for payloads >160 bytes, CBOR delta compression for state sync, mDNS LAN discovery, and a "mesh only" off-grid mode.
Phase 3 adds Signal-style Double Ratchet for forward secrecy, typed messages (ALERT, INVOICE, COORDINATE, PSBT_HASH), and store-and-forward relay. Phase 4 adds off-grid Bitcoin operations: block header relay, transaction relay, Lightning invoice relay, and emergency alert system with dead man's switch.
The v2.0 roadmap (`docs/roadmap-v2.0.md`) also calls for a visual topology map and CRDT-based state sync — those are deferred to Phase 5 (Mesh Intelligence), but the transport abstraction here enables them.
## Dependencies (Verified)
## Dependencies to Add
```toml
ciborium = "0.2.2" # CBOR serde (134M downloads, active)
reed-solomon-erasure = "6.0" # FEC (4M downloads, MIT)
mdns-sd = "0.18.2" # LAN peer discovery (1.86M, active)
hkdf = "0.12" # KDF for Double Ratchet chains
lightning-invoice = "0.34" # BOLT11 parsing (LDK standard, MIT)
```
Custom Double Ratchet from existing crypto (ed25519-dalek, curve25519-dalek, chacha20poly1305, sha2, hmac) — no DR crate needed.
## Architecture
```
core/archipelago/src/transport/
├── mod.rs — NodeTransport trait, TransportKind, TransportRouter, PeerRegistry
├── tor.rs — TorTransport (wraps node_message.rs SOCKS5 logic)
├── mesh_transport.rs — MeshTransport (bridges MeshService cmd channel)
├── lan.rs — LanTransport (mdns-sd + direct HTTP)
├── chunking.rs — Split/reassemble with Reed-Solomon FEC
└── delta.rs — CBOR delta encoding for NodeStateSnapshot
```
### Unified Peer Identity
DID is the canonical identifier. Transport-specific addresses are attributes:
```rust
pub struct PeerRecord {
pub did: String,
pub pubkey_hex: String,
pub name: Option<String>,
pub trust_level: TrustLevel,
// Transport capabilities
pub mesh_contact_id: Option<u32>,
pub lan_address: Option<SocketAddr>,
pub onion_address: Option<String>,
// Freshness
pub last_mesh: Option<String>,
pub last_lan: Option<String>,
pub last_tor: Option<String>,
}
```
### Transport Routing
```
TransportRouter::send_to_peer(did, payload)
1. Look up PeerRecord by DID
2. Filter to transports where peer has address AND transport is available AND not stale
3. Sort by priority: Mesh(1) > LAN(2) > Tor(3)
4. If mesh_only_mode: only allow Mesh
5. Try each in order, fall back on failure
```
### Chunking Protocol (for LoRa >160B)
Per-chunk structure (8 byte header + 124 byte payload = 132B, fits in 160B after encryption):
```
[0x01] [msg_id: u32 LE] [chunk_idx: u8] [total: u8] [is_parity: u8] [payload: 124B]
```
Reed-Solomon: 25% parity shards. 4 data chunks = 1 parity chunk. Any N-of-(N+parity) reconstructs.
Max practical: ~10 chunks (~1.2KB) before LoRa airtime becomes unreasonable.
### CBOR Delta Sync
Full JSON state: ~500-2000 bytes. CBOR delta when only CPU/mem changed: ~30-50 bytes. Fits single LoRa chunk.
```rust
pub struct StateDelta {
pub ts: String,
pub v: u8,
pub apps: Option<Vec<AppStatus>>, // Only changed apps
pub apps_rm: Option<Vec<String>>, // Removed app IDs
pub cpu: Option<f64>,
pub mem_u: Option<u64>,
// ... only changed fields, short names for wire size
}
mesh/
├── x3dh.rs — X3DH key agreement (prekey bundles, 3-way ECDH)
├── ratchet.rs — Double Ratchet state machine (forward secrecy)
├── session.rs — Per-peer session manager (ratchet state persistence)
├── prekey.rs — Prekey store (signed + one-time prekeys, rotation)
├── message_types.rs — Typed message envelope (TEXT/ALERT/INVOICE/COORDINATE/PSBT_HASH)
├── outbox.rs — Store-and-forward queue (24h TTL, relay hops)
├── bitcoin_relay.rs — TX relay, Lightning relay, block header announce
├── alerts.rs — Emergency alerts, dead man's switch
└── (existing files extended: crypto.rs, listener.rs, types.rs, mod.rs)
```
## Implementation Steps
### Step 1: Add deps to Cargo.toml
**File**: `core/archipelago/Cargo.toml`
Add ciborium, reed-solomon-erasure, mdns-sd.
### Week 1: X3DH + HKDF Foundation
### Step 2: Create `transport/mod.rs` — Core trait + PeerRegistry + TransportRouter
**New file**: `core/archipelago/src/transport/mod.rs`
- `NodeTransport` trait: `kind()`, `is_available()`, `send(address, payload)`
- `TransportKind` enum: `Mesh = 1, Lan = 2, Tor = 3`
- `TransportMessage`: `{from_did, payload: Vec<u8>, message_type}`
- `PeerRegistry`: unified peer store (DID -> PeerRecord), JSON persistence to `transport-peers.json`
- `TransportRouter`: holds Vec<Box<dyn NodeTransport>>, routes by priority with fallback
- Register `mod transport;` in `core/archipelago/src/lib.rs` or main.rs
**New**: `mesh/x3dh.rs`, `mesh/prekey.rs`
**Modify**: `Cargo.toml` (+hkdf), `mesh/crypto.rs`, `mesh/mod.rs`
### Step 3: Create `transport/chunking.rs` — Reed-Solomon FEC
**New file**: `core/archipelago/src/transport/chunking.rs`
- `encode_chunked(data: &[u8]) -> Vec<Vec<u8>>` — split + FEC parity shards
- `ChunkReassembler` — state machine tracking pending messages, attempts reconstruction when enough chunks arrive
- `decode_chunked(chunks: &[Option<Vec<u8>>]) -> Result<Vec<u8>>` — reconstruct from data+parity
- Unit tests: roundtrip, missing chunks, corrupted chunks
- `PrekeyBundle`: identity_key + signed_prekey + one_time_prekeys (CBOR, ~200B)
- `PrekeyStore`: disk persistence at `{data_dir}/prekeys/`, rotation, consumption
- X3DH: 3-way ECDH → HKDF-SHA256 → root key for Double Ratchet
- ARCHY:3 identity broadcast with embedded prekey bundle
### Step 4: Create `transport/delta.rs` — CBOR delta sync
**New file**: `core/archipelago/src/transport/delta.rs`
- `compute_delta(prev, curr: &NodeStateSnapshot) -> StateDelta`
- `apply_delta(base: &NodeStateSnapshot, delta: &StateDelta) -> NodeStateSnapshot`
- `encode_cbor(delta) -> Vec<u8>` via ciborium
- `decode_cbor(bytes) -> Result<StateDelta>`
- Unit tests: delta correctness, CBOR roundtrip, size comparison vs JSON
### Week 2: Double Ratchet Protocol
### Step 5: Create `transport/tor.rs` — TorTransport
**New file**: `core/archipelago/src/transport/tor.rs`
- Wraps existing `node_message::send_to_peer()` pattern (reqwest + SOCKS5)
- Reuses: `node_message.rs:66` send logic, `node_message.rs:115` health check
- `is_available()` checks SOCKS5 proxy reachable at 127.0.0.1:9050
- Receives handled by existing HTTP handler in `api/handler.rs`
**New**: `mesh/ratchet.rs` (~500 LOC), `mesh/session.rs` (~300 LOC)
### Step 6: Create `transport/mesh_transport.rs` — MeshTransport
**New file**: `core/archipelago/src/transport/mesh_transport.rs`
- Holds reference to `Arc<RwLock<Option<MeshService>>>` (same as RpcHandler)
- `send()` routes through `MeshService::send_message()` for small payloads
- For payloads >124B: chunk with `chunking::encode_chunked()`, send each chunk via `MeshCommand::SendText`
- 200ms inter-chunk delay for LoRa airtime fairness
- `is_available()` checks mesh device connected via `MeshService::status()`
`RatchetState`: DH ratchet keypair, root key, send/recv chain keys, counters, skipped keys (max 100). HKDF-SHA256 chains + ChaCha20-Poly1305 per-message.
### Step 7: Create `transport/lan.rs` — LanTransport
**New file**: `core/archipelago/src/transport/lan.rs`
- Uses `mdns-sd::ServiceDaemon` for discovery
- Advertises: `_archipelago._tcp.local.` with TXT records: `did=..., pubkey=..., version=...`
- Browses for peers, updates PeerRegistry when found
- `send()`: direct HTTP POST to `http://{ip}:5678/archipelago/node-message` (same endpoint as Tor, no proxy)
- Non-blocking init — if Avahi not available, fail gracefully
Wire format: 40B header (DH pub + counters) + 12 nonce + ciphertext + 16 tag = 68B overhead. Single frame: 64B plaintext. Chunked: ~2.4KB.
### Step 8: Add `mesh_only_mode` to MeshConfig
**File**: `core/archipelago/src/mesh/mod.rs`
- Add `pub mesh_only_mode: Option<bool>` to MeshConfig (with `#[serde(default)]`)
- TransportRouter reads this flag to restrict routing
`SessionManager`: HashMap<DID, RatchetState>, lazy load from `{data_dir}/ratchet/{did_hash}.json`. Backward compat: falls back to static shared secret for ARCHY:2 peers.
### Step 9: Wire TransportRouter into server.rs
**File**: `core/archipelago/src/server.rs` (~line 136, after mesh service init)
- Create PeerRegistry, load from disk
- Create TorTransport, MeshTransport, LanTransport
- Start LAN advertisement + discovery
- Create TransportRouter with all three + mesh_only flag
- Spawn background task bridging `MeshEvent::IdentityReceived` -> PeerRegistry
- Store router on RpcHandler
### Week 3: Typed Messages + Store-and-Forward
### Step 10: Add transport RPC endpoints
**New file**: `core/archipelago/src/api/rpc/transport.rs`
**Modify**: `core/archipelago/src/api/rpc/mod.rs` (add dispatch routes)
**New**: `mesh/message_types.rs`, `mesh/outbox.rs`
**Modify**: `mesh/types.rs`, `mesh/listener.rs`
Endpoints:
- `transport.status` — available transports, mesh_only flag, peer count
- `transport.peers` — unified peer list with per-peer transport capabilities + preferred transport
- `transport.send` — send message via best transport (by DID)
- `transport.set-mode` — toggle mesh_only mode
CBOR envelope: `[0x02] [{ t: u8, v: bytes, ts: u32, sig?: bytes }]`
### Step 11: Add opt-in federation sync via transport
**File**: `core/archipelago/src/federation.rs`
- Add `sync_with_peer_via_transport()` alongside existing `sync_with_peer()`
- Uses CBOR delta encoding when transport is mesh (saves bandwidth)
- Falls back to full JSON over Tor for backward compat
- Background sync task checks for TransportRouter, uses it if available
Types: TEXT(0), ALERT(1), INVOICE(2), PSBT_HASH(3), COORDINATE(4), PREKEY_BUNDLE(5), SESSION_INIT(6)
### Step 12: Frontend — transport store + UI indicators
**New file**: `neode-ui/src/stores/transport.ts` — Pinia store for transport status
**Modify**: `neode-ui/src/views/Mesh.vue` — "OFF-GRID" indicator when mesh_only mode
**Modify**: `neode-ui/mock-backend.js` — add transport.* mock RPC responses
GPS as `Coordinate { lat_microdeg: i32, lng_microdeg: i32 }` — integer only, no float.
### Step 13: Mock backend transport data
**File**: `neode-ui/mock-backend.js`
Add `transport.status`, `transport.peers`, `transport.send`, `transport.set-mode` mock responses with realistic data showing mixed transport capabilities.
`MeshOutbox`: VecDeque, 24h TTL, max 3 relay hops, disk persistence. Checked every 10s tick.
## Files Summary
### Week 4: RPC Endpoints + Session Bootstrap
### New (8)
1. `core/archipelago/src/transport/mod.rs`
2. `core/archipelago/src/transport/tor.rs`
3. `core/archipelago/src/transport/mesh_transport.rs`
4. `core/archipelago/src/transport/lan.rs`
5. `core/archipelago/src/transport/chunking.rs`
6. `core/archipelago/src/transport/delta.rs`
7. `core/archipelago/src/api/rpc/transport.rs`
8. `neode-ui/src/stores/transport.ts`
**Modify**: `api/rpc/mesh.rs`, `api/rpc/mod.rs`, `mesh/listener.rs`
### Modified (8)
1. `core/archipelago/Cargo.toml` — add 3 deps
2. `core/archipelago/src/lib.rs` or main — `mod transport;`
3. `core/archipelago/src/server.rs` — init router, bridge events
4. `core/archipelago/src/api/rpc/mod.rs` — dispatch + store router
5. `core/archipelago/src/mesh/mod.rs` — `mesh_only_mode` config field
6. `core/archipelago/src/federation.rs` — `sync_with_peer_via_transport()`
7. `neode-ui/src/views/Mesh.vue` — off-grid indicator
8. `neode-ui/mock-backend.js` — transport.* mock data
New RPC: `mesh.send-invoice`, `mesh.send-coordinate`, `mesh.send-alert`, `mesh.outbox`, `mesh.session-status`, `mesh.rotate-prekeys`
### Reused Existing Code
- `node_message.rs:66-112` — Tor SOCKS5 send logic -> wrapped by TorTransport
- `node_message.rs:115-135` — Tor health check -> TorTransport.is_available()
- `mesh/mod.rs:209-282` — MeshService::send_message() -> called by MeshTransport
- `mesh/listener.rs:35-37` — MeshCommand channel -> used for chunked sends
- `mesh/crypto.rs` — X25519 ECDH + ChaCha20-Poly1305 -> reused as-is
- `federation.rs:36-49` — FederatedNode struct -> PeerRecord wraps this
- `federation.rs:179-191` — update_node_state() -> adapted for CBOR deltas
Prekey distribution via ARCHY:3 broadcasts. Session init via X3DH on first message to new peer.
### Week 5: Off-Grid Bitcoin (Phase 4)
**New**: `mesh/bitcoin_relay.rs`, `mesh/block_headers.rs`
**Modify**: `Cargo.toml` (+lightning-invoice), `api/rpc/mesh.rs`
Block header relay: Internet node broadcasts `BlockHeaderAnnouncement` (height, hash, Ed25519 sig) on new block. Mesh-only peers display "SPV sync via mesh".
TX relay: Mesh-only node sends raw tx hex → internet peer calls `sendrawtransaction` → returns txid.
Lightning relay: Create invoice → send bolt11 → peer pays → proof-of-payment returned.
### Week 6: Emergency Alerts + Dead Man's Switch
**New**: `mesh/alerts.rs`
`DeadManSwitch`: Background task, configurable interval (default 6h), broadcasts signed ALERT with GPS to emergency contacts when triggered. Auto-check-in on any authenticated RPC.
RPC: `mesh.alert-configure`, `mesh.alert-checkin`, `mesh.alert-test`, `mesh.alert-status`
### Week 7: Frontend
**Modify**: `stores/mesh.ts`, `views/Mesh.vue`, `mock-backend.js`
Message rendering by type: invoice (orange card + Pay button), alert (red card), coordinate (blue card + OSM link), psbt_hash (gray card + Review).
Session indicator: shield icon (green=ratchet, yellow=static, gray=none).
Block height in off-grid banner. Alert config panel. Dead man switch toggle.
### Week 8: Integration Test + Deploy
E2E on .228 (internet) + .198 (mesh-only): X3DH handshake, 50-message ratchet, invoice relay, TX relay, block headers, dead man switch. Deploy to both servers.
## New Files (8)
1. `core/archipelago/src/mesh/x3dh.rs`
2. `core/archipelago/src/mesh/prekey.rs`
3. `core/archipelago/src/mesh/ratchet.rs`
4. `core/archipelago/src/mesh/session.rs`
5. `core/archipelago/src/mesh/message_types.rs`
6. `core/archipelago/src/mesh/outbox.rs`
7. `core/archipelago/src/mesh/bitcoin_relay.rs`
8. `core/archipelago/src/mesh/alerts.rs`
## Modified Files (8)
1. `core/archipelago/Cargo.toml` — +hkdf, +lightning-invoice
2. `core/archipelago/src/mesh/crypto.rs` — +hkdf_sha256, +ephemeral keygen
3. `core/archipelago/src/mesh/types.rs` — +message_type, +typed payloads
4. `core/archipelago/src/mesh/listener.rs` — typed dispatch, session bootstrap, relay
5. `core/archipelago/src/mesh/mod.rs` — new submodules, new MeshService methods
6. `core/archipelago/src/api/rpc/mesh.rs` — ~12 new RPC endpoints
7. `core/archipelago/src/api/rpc/mod.rs` — register new routes
8. `neode-ui/src/views/Mesh.vue` — typed rendering, alert UI, session badges
## Verification
1. **Unit tests** (run on dev server):
```bash
cargo test --all-features -- transport
cargo test --all-features -- chunking
cargo test --all-features -- delta
```
2. **Frontend type check**:
```bash
cd neode-ui && npm run type-check
```
3. **Dev mode test**:
```bash
cd neode-ui && npm start
# Navigate to /dashboard/mesh — verify OFF-GRID toggle
```
4. **Deploy + integration test**:
```bash
./scripts/deploy-to-target.sh --live
# On .228: curl transport.status RPC
# Verify mDNS advertises _archipelago._tcp.local.
# If mesh device connected: send chunked message >160B to .198
# Verify federation sync uses CBOR delta when available
```
## Implementation Order
**Week 1**: Steps 1-4 (deps, trait, chunking, delta — pure library code with unit tests)
**Week 2**: Steps 5-7 (three transport implementations)
**Week 3**: Steps 8-11 (integration: server wiring, RPC, federation migration)
**Week 4**: Steps 12-13 (frontend UI, mock data, deploy + test)
```bash
cargo test --all-features -- mesh::ratchet mesh::x3dh mesh::session
cargo clippy --all-targets --all-features
cd neode-ui && npm run type-check
./scripts/deploy-to-target.sh --both
```