docs: add devel-phases.md — 5-phase development roadmap

Phase 1 complete (POC + foundations).
Phase 2 starting: Node v1 with keystore, hub client,
indexer, TCP+TLS chunk server, local web UI.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

1 files changed, 132 insertions, 0 deletions

diff --git a/devel-phases.md b/devel-phases.md
new file mode 100644
index 0000000..c224ece
--- /dev/null
+++ b/devel-phases.md
@@ -0,0 +1,132 @@
+# MeshBay — Development Phases
+
+> Reference: architecture spec in `docs/meshbay-draft-v3.md`
+> POC results: `poc/spike-results.md`
+
+---
+
+## Phase 1 — Foundations ✅ DONE
+
+**Goal:** validate all blocking concepts before writing production code.
+
+### Deliverables
+
+| Item | Status | Notes |
+|---|---|---|
+| POC Spike 1 — Crypto primitives | ✅ | All 22 tests pass. ChaCha20 1MB in 1.1ms. |
+| POC Spike 2 — Hub skeleton | ✅ | 12/12 endpoints. JWT EdDSA offline verify in 884µs. |
+| POC Spike 3 — Node registration | ✅ | Full handshake. jti bug found and fixed. |
+| POC Spike 4 — NAT traversal | ✅ | Cone NAT on SFR. UDP P2P works. UPnP disabled (SFR). |
+| POC Spike 5 — Encrypted transfer | ✅ | 1MB P2P. 3.2ms encrypt, 3.9ms decrypt. 4.3MB/s. |
+| POC Spike 6 — GEK distribution | ✅ | X25519+HKDF wrap/unwrap. 0.48ms/0.59ms. Hub opaque. |
+| Security cleanup meshbay.org | ✅ | UFW: 22/80/443 only. No services exposed. |
+| Git monorepo | ✅ | 3 packages: meshbay-common, meshbay-hub, meshbay-node. |
+| Draft v3 | ✅ | POC findings integrated. All corrections applied. |
+| CLAUDE.md conventions | ✅ | Python 3.12+, uv, ruff, SemVer, commit format. |
+
+### Key findings from POC
+
+- jti mandatory in all JWTs (Ed25519 is deterministic — same payload = same token)
+- Argon2id at 64MB/3iter = 78ms — increase to 256MB for production (~500ms target)
+- NAT order: STUN/hole-punching is priority 2, not UPnP (UPnP disabled on tested SFR box)
+- TCP+TLS for v1 transport; QUIC in v2
+- GEK wrapping: ephemeral X25519 + HKDF(salt=pk_eph) + ChaCha20-Poly1305(aad=pk_recipient)
+
+---
+
+## Phase 2 — Node v1 🚧 IN PROGRESS
+
+**Goal:** a working Mesh Node that indexes a directory, registers with the hub,
+serves encrypted chunks over TCP+TLS, and has a minimal local web UI.
+
+**Transport:** TCP+TLS (QUIC added in v2).
+**TLS:** self-signed cert per node. Client verifies node identity via Ed25519 PK from hub,
+not via cert chain. Client uses `CERT_NONE` ssl context.
+
+### Milestones
+
+| # | Component | File(s) | Status |
+|---|---|---|---|
+| 2.1 | Keystore | `meshbay_node/keystore.py` | 🚧 |
+| 2.2 | Hub client | `meshbay_node/hub_client.py` | 🚧 |
+| 2.3 | Directory indexer | `meshbay_node/indexer/` | 🚧 |
+| 2.4 | Mesh Group Index | `meshbay_node/indexer/group_index.py` | 🚧 |
+| 2.5 | TCP+TLS chunk server | `meshbay_node/transport/server.py` | 🚧 |
+| 2.6 | Daemon + config | `meshbay_node/daemon.py`, `config.py` | 🚧 |
+| 2.7 | Local web UI | `meshbay_node/ui/` | 🚧 |
+
+### Node v1 scope
+
+**In scope:**
+- Single group, single shared directory
+- GEK loaded from hub bundle (hub must be running)
+- Serve file chunks to authenticated clients (JWT bearer)
+- Mesh Group Index: encrypted, delta updates
+- Local web UI: status, file list, group info
+- Keystore: Argon2id + AES-256-GCM, 3 unlock modes (password / file / env var)
+- Config file: `~/.config/meshbay/node.toml`
+- Systemd service unit
+
+**Out of scope for v1:**
+- Multiple groups or directories
+- Chat / Double Ratchet
+- QUIC transport
+- Module sandbox
+- Mobile pairing
+- Streaming (HLS) — chunks are raw, player integration later
+
+---
+
+## Phase 3 — Hub v1 production
+
+**Goal:** replace POC in-memory hub with a production-ready service.
+
+| # | Component | Notes |
+|---|---|---|
+| 3.1 | PostgreSQL persistence | SQLAlchemy async + asyncpg, Alembic migrations |
+| 3.2 | HTTPS via Caddy | Auto Let's Encrypt, ProxyPass to uvicorn on 127.0.0.1:8000 |
+| 3.3 | Full user/group management | All POC endpoints hardened, input validation, rate limiting |
+| 3.4 | IP logging | Legal compliance: creation, login, group events (1-year retention) |
+| 3.5 | Revocation | Signed revocation tokens, hub → node push via WebSocket |
+| 3.6 | Moderation | blake3 blocklist, DMCA takedown endpoint, escalation flow |
+| 3.7 | CSAM hash matching | NCMEC/IWF integration on public content registration |
+| 3.8 | Systemd service + RPM/DEB | meshbay-hub package, `/etc/meshbay/hub.toml` |
+
+---
+
+## Phase 4 — Integration & Client
+
+**Goal:** end-to-end working product: node + hub + web client.
+
+| # | Component | Notes |
+|---|---|---|
+| 4.1 | Web client (browser) | Browse Mesh Group Index, download, stream VOD |
+| 4.2 | End-to-end integration test | Node ↔ Hub ↔ Client full flow |
+| 4.3 | HLS/DASH streaming | Node segments on-the-fly, per-segment GEK-derived key |
+| 4.4 | Chat (Double Ratchet) | Group messaging with attachments, Signal-like |
+| 4.5 | Multi-group support | Node hosts N groups across M directories |
+
+---
+
+## Phase 5 — QUIC, Federation, Mobile
+
+**Goal:** full decentralization, mobile support, community infrastructure.
+
+| # | Component | Notes |
+|---|---|---|
+| 5.1 | QUIC transport (MNP v2) | Replace TCP+TLS with aioquic; same application protocol |
+| 5.2 | MHP federation | Hub-to-hub Mesh Directory exchange, explicit peer allowlist |
+| 5.3 | Mesh Relay | Community TURN relay registration protocol |
+| 5.4 | Android client | Kotlin/Flutter, hub account, group access, node pairing |
+| 5.5 | Content replication | Node-to-node, admin-authorized, no hub involvement |
+| 5.6 | iOS client | After Android stabilizes |
+| 5.7 | Argon2id calibration CLI | `meshbay-node --calibrate-argon2` tuning command |
+
+---
+
+## Conventions reminder
+
+- Commits: `feat(node):`, `fix(hub):`, `chore(common):`, `docs:`, `test(node):`
+- Branch per feature/fix, merge to `main` via PR (when remote is set up)
+- Close test UFW ports after any spike on meshbay.org
+- Never commit key material (keystore.enc, hub_private.pem, *.key, node_state.json)