# 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)