diff options
| -rw-r--r-- | devel-phases.md | 132 |
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) |