1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
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)
|