diff options
| -rw-r--r-- | devel-phases-next.md | 186 |
1 files changed, 155 insertions, 31 deletions
diff --git a/devel-phases-next.md b/devel-phases-next.md index e423d83..1f6f0b4 100644 --- a/devel-phases-next.md +++ b/devel-phases-next.md @@ -494,7 +494,110 @@ Browser Node --- -## Phase 11 — Android client MVP +## Phase 11 — Node daemon: production-ready + +**Objective:** the node daemon (`meshbay-node`) runs as a complete, self-contained +service. Today the daemon starts QUIC/TCP servers and the local web UI, but +everything else (WebRTC, hub WS, chat store, index push, HTTP file API) is only +wired up in the QE demo script. This phase moves all that logic into the daemon. + +**Current daemon gap (what `run_node_simple.py` does that `daemon.py` doesn't):** +- Starts `maintain_ws()` (hub WebSocket for signaling, revocation, WebRTC offers) +- Creates `WebRTCTransport` and passes it as `on_webrtc_offer` callback +- Creates `ChatStore` per group and injects it into the WebRTC context +- Sets `hub_ws` in WebRTC context (for chat notifications) +- Sets `node_user_id` in WebRTC context (for file delete authorization) +- Starts the HTTP file API server (`create_http_app()`) +- None of these are in `daemon.py` + +### Milestones + +| # | Component | Description | +|---|---|---| +| 11.1 | Daemon: hub WS integration | `maintain_ws()` as asyncio task, auto-reconnect, pass group_ids | +| 11.2 | Daemon: WebRTC transport | Create `WebRTCTransport`, wire as `on_webrtc_offer` callback | +| 11.3 | Daemon: chat store | Create `ChatStore` per group, inject into WebRTC + QUIC contexts | +| 11.4 | Daemon: HTTP file API | Start `create_http_app()` on configured `http_port` | +| 11.5 | Daemon: index push on change | Wire `DirectoryIndexer.on_change` to push `INDEX_DELTA` to connected peers | +| 11.6 | Daemon: node_user_id + hub_ws context | Set `node_user_id` and `hub_ws` in transport contexts for authorization + notifications | +| 11.7 | Daemon: graceful shutdown | Cancel WS task, close WebRTC peers, close chat stores, stop HTTP server | +| 11.8 | Systemd unit file | `meshbay-node.service` with `EnvironmentFile=` for unlock key, restart on failure | +| 11.9 | Swarm registration | Register own public files with hub swarm table on index change | +| 11.10 | Integration test | Daemon starts, connects WS, accepts WebRTC offer, serves file, shuts down clean | + +### Priority + +This is the **most important next phase**. Without it, every node deployment +requires a custom demo script. The daemon must be self-sufficient — start it, +it does everything. No glue code. + +--- + +## Phase 12 — Node CLI + management + +**Objective:** `meshbay-node` CLI becomes a full management tool, not just a +daemon launcher. Users can manage groups, members, and node state from the +command line. + +### Milestones + +| # | Component | Description | +|---|---|---| +| 12.1 | `meshbay-node status` | Show daemon state: groups, peers, connected members, uptime | +| 12.2 | `meshbay-node group list` | List configured groups with online status | +| 12.3 | `meshbay-node group create` | Create group on hub, add to config, generate GEK | +| 12.4 | `meshbay-node group join` | Join existing group, fetch GEK, add to config | +| 12.5 | `meshbay-node member invite` | Wrap GEK for new member, push bundle to hub | +| 12.6 | `meshbay-node member remove` | Rotate GEK, re-wrap for remaining members, push to hub | +| 12.7 | `meshbay-node member list` | List group members with online status | +| 12.8 | Config reload (SIGHUP) | Daemon reloads config and adds/removes groups without restart | + +### Architecture + +CLI commands communicate with the running daemon via a local Unix socket +(`/run/meshbay-node.sock`). The daemon exposes a small internal API for +status queries and management operations. If the daemon is not running, +commands that require it fail with a clear error. + +--- + +## Phase 13 — Chat encryption (Sender Keys) + retention + +**Objective:** implement spec section 6.6 — group chat messages are encrypted +with the Sender Keys protocol. Currently, chat messages are stored and +transmitted as plaintext payloads (relying on transport encryption only). + +### Background + +`meshbay_common.senderkeys` (Phase 7.5) implements the Sender Keys protocol, +but the node chat flow (`_do_chat_message`) stores raw payloads without +encrypting them. The Sender Keys module provides: +- Per-sender chain key derivation (ratcheting) +- Symmetric encryption of group messages +- Key distribution via pairwise GEK-wrapped channels + +### Milestones + +| # | Component | Description | +|---|---|---| +| 13.1 | Node: sender key init | Generate sender key on group join, distribute to members | +| 13.2 | Node: encrypt chat on send | Encrypt payload with sender's chain key before broadcast | +| 13.3 | Node: decrypt chat on receive | Decrypt incoming chat messages, handle out-of-order | +| 13.4 | Key rotation on member removal | Admin removes member → all remaining members rotate keys | +| 13.5 | Chat retention config | Per-group `max_age_days` setting, periodic cleanup in ChatStore | +| 13.6 | MNP version negotiation | Handshake declares supported version range, not just single `v` field | + +### Security note + +Without Sender Keys, any node operator (or anyone with filesystem access to +the node) can read all chat messages in plaintext. With Sender Keys, messages +are encrypted with per-sender chain keys that the node operator does NOT +possess — only group members with the distributed sender keys can decrypt. +This is a fundamental security upgrade for group privacy. + +--- + +## Phase 14 — Android client MVP **Objective:** Android app for account creation, group browsing, file download, chat. No node functionality on mobile (client-only). @@ -505,14 +608,14 @@ clients (`punch_nat` + QUIC). | # | Component | Tech | Priority | |---|---|---|---| -| 11.1 | Hub client (auth, groups, GEK) | Kotlin + Retrofit | High | -| 11.2 | Crypto (Ed25519, X25519, ChaCha20) | Bouncy Castle JVM | High | -| 11.3 | QUIC client | quiche (Rust JNI) | High | -| 11.4 | NAT traversal (STUN + punch) | Kotlin native UDP | High | -| 11.5 | File browser + download | Kotlin + streaming IO | High | -| 11.6 | Chat UI | Jetpack Compose | Medium | -| 11.7 | Contact list integration | Android Contacts API (permission-gated) | Medium | -| 11.8 | Account creation from app | Registration flow + keypair bundle | High | +| 14.1 | Hub client (auth, groups, GEK) | Kotlin + Retrofit | High | +| 14.2 | Crypto (Ed25519, X25519, ChaCha20) | Bouncy Castle JVM | High | +| 14.3 | QUIC client | quiche (Rust JNI) | High | +| 14.4 | NAT traversal (STUN + punch) | Kotlin native UDP | High | +| 14.5 | File browser + download | Kotlin + streaming IO | High | +| 14.6 | Chat UI | Jetpack Compose | Medium | +| 14.7 | Contact list integration | Android Contacts API (permission-gated) | Medium | +| 14.8 | Account creation from app | Registration flow + keypair bundle | High | **Cross-device compatibility:** the user may switch between web and Android. The `keypair_bundle` (encrypted, stored on hub) enables this — same credentials, @@ -527,19 +630,19 @@ with an `upload` message type for client→node push. --- -## Phase 12 — Network resilience (optional, low priority) +## Phase 15 — Network resilience (optional, low priority) **Objective:** handle edge cases — symmetric NAT (CGNAT mobile), TURN relay, 0-RTT reconnection. Not needed for typical residential users. | # | Component | Priority | |---|---|---| -| 12.1 | Mesh Relay TURN server | Low | -| 12.2 | Relay registration via MHP | Low | -| 12.3 | Node fallback to relay after ICE failure | Low | -| 12.4 | QUIC 0-RTT (session tickets) | Medium | -| 12.5 | Connection pool (1 QUIC conn = N requests) | Medium | -| 12.6 | Test CGNAT mobile 4G | Low | +| 15.1 | Mesh Relay TURN server | Low | +| 15.2 | Relay registration via MHP | Low | +| 15.3 | Node fallback to relay after ICE failure | Low | +| 15.4 | QUIC 0-RTT (session tickets) | Medium | +| 15.5 | Connection pool (1 QUIC conn = N requests) | Medium | +| 15.6 | Test CGNAT mobile 4G | Low | **Note:** enterprise users behind restrictive firewalls can configure port forwarding themselves. This phase targets the ~15% of residential connections @@ -548,32 +651,52 @@ the user explicitly deprioritized this. --- -## Phase 13 — RPM/DEB packaging + CI +## Phase 16 — RPM/DEB packaging + CI | # | Component | |---|---| -| 13.1 | RPM build pipeline (Fedora, RHEL) | -| 13.2 | DEB build pipeline (Ubuntu, Debian) | -| 13.3 | GitHub Actions CI (pytest + ruff on PR) | -| 13.4 | Release signing (GPG key) | -| 13.5 | Repo apt/dnf on meshbay.org/packages/ | -| 13.6 | Android APK distribution on meshbay.org/downloads/ | +| 16.1 | RPM build pipeline (Fedora, RHEL) | +| 16.2 | DEB build pipeline (Ubuntu, Debian) | +| 16.3 | GitHub Actions CI (pytest + ruff on PR) | +| 16.4 | Release signing (GPG key) | +| 16.5 | Repo apt/dnf on meshbay.org/packages/ | +| 16.6 | Android APK distribution on meshbay.org/downloads/ | + +--- + +## Phase 17 — Extension module sandbox (future) + +**Objective:** implement spec section 12 — Python extension modules that can +react to group events, access the file index, and send messages, running in +a sandboxed subprocess with limited permissions. + +| # | Component | Description | +|---|---|---| +| 17.1 | Module manifest loader | Parse `module.toml`, validate permissions | +| 17.2 | Sandboxed subprocess | `read_index()`, `send_message()`, `receive_events()` API | +| 17.3 | Permission enforcement | No filesystem/network beyond group context | +| 17.4 | Module marketplace on hub | List/install/rate extension modules | + +**Low priority.** This is an extensibility feature for power users and +community developers. Core functionality must be complete and stable first. --- ## Recommended order ``` -Phase 9 (Web client) ← core product: browser P2P to nodes -Phase 10 (Site + admin UI) ← public-facing site, moderation, admin -Phase 11 (Android) ← mobile client, long effort -Phase 13 (Packaging) ← distribution -Phase 12 (Resilience) ← optional, edge cases only +Phase 11 (Node daemon) ← CRITICAL: daemon must be self-sufficient +Phase 12 (Node CLI) ← management UX +Phase 13 (Sender Keys) ← chat security upgrade +Phase 14 (Android) ← mobile client, long effort +Phase 16 (Packaging) ← distribution +Phase 15 (Resilience) ← optional, edge cases only +Phase 17 (Extensions) ← future, community-driven ``` -Phase 9 is the critical path. Milestone 9.5 (spike: browser → NAT → node file -transfer) is the single most important validation in the project. If it works, -the web client is viable. If not, the architecture needs fundamental rethinking. +Phase 11 is the critical path now. The web client and hub are production-ready, +but every node deployment requires a custom demo script. Fixing this unblocks +everything else — packaging, multiple installations, community adoption. --- @@ -593,3 +716,4 @@ the web client is viable. If not, the architecture needs fundamental rethinking. 12. **Chat stored on nodes, not hub** ✅ (decided 2026-08-10) 13. **Web UI: Preact SPA, dark/light, responsive, i18n** ✅ (decided 2026-08-10) 14. **Site overlay: meshbay.org-specific pages separate from generic hub** ✅ (decided 2026-08-10) +15. **MSE streaming: ffmpeg fMP4 remux on node, SourceBuffer on browser** ✅ (Phase 10c) |