path: root/docs/meshbay-draft-v5.md

# MeshBay — Architecture Draft v5

> Status: **Phase 11.5 (security remediation) complete.** See `devel-phases-next.md`.
> Supersedes `meshbay-draft-v4.md`. Sections not restated here are unchanged from v4.
>
> v5 exists because the second security review (`second-review.md`, 2026-08-13) found
> that v4 described a system the code did not implement, and because several v4 claims
> were simply wrong. This document states what is true, what is chosen, and what is
> knowingly accepted. **Where a property does not hold, it says so.**

---

## 0. How to read this document

v4 described intent. Several of its statements were contradicted by the implementation:

| v4 said | Reality found in the code |
|---|---|
| "ALL operations require passing the GEK proof first" (§4.2.x) | True on WebRTC only. QUIC, TCP and the node HTTP API each had their own weaker handshake |
| "The node NEVER serves the GEK in plaintext" | True, but the node's HTTP API served the *decrypted files themselves* with no authentication at all |
| "Argon2id parameters updated: memory_cost 262144" | Applied to the hub's password verifier only; the node keystore was still at 64 MB |
| "GEK bundles: opaque blobs; hub cannot decrypt them" | True, and irrelevant — the hub is the key directory, so it can substitute a key at invite time and be handed the GEK legitimately |
| "hub stores no content metadata" | The node registered blake3 hashes of **private** files with the hub |

So v5 carries an explicit rule: **a claim in this document must name the adversary it
holds against.** A property that holds against a passive hub and not an active one is
written that way.

---

## 1. Changes from v4

| # | Category | Change | Source |
|---|---|---|---|
| 1 | Transport | TCP+TLS transport and the node HTTP file API **removed**. Two listeners remain: WebRTC DataChannel (primary) and QUIC (LAN / port-forwarded / hub-less) | 11.5.1–2, findings C1/C6 |
| 2 | NAT traversal | **ICE/STUN is the traversal mechanism**, for native clients too. `punch_nat()` is a direct-connection helper, not a traversal stack | Decision D3 |
| 3 | Handshake | One implementation in `meshbay_common.handshake`, shared by every transport | 11.5.4, finding C6 |
| 4 | Handshake | **Mutual authentication**: the node proves GEK possession and signs the transcript. Authentication used to run one way only | 11.5.7, finding C3 |
| 5 | Handshake | Transcripts are length-prefixed and domain-separated; `group_id` is mandatory; missing channel binding is refused | L4, M1 |
| 6 | Admin ops | Destructive operations sign a structured transcript naming operation, node, group, subject, nonce and time — not 32 opaque random bytes | Finding H5 |
| 7 | Node authority | GEK bundle storage requires the node operator's signature; **nothing arriving over MNP can activate a GEK** | Finding C5b |
| 8 | Uploads | Confined to a per-user quarantine directory; no overwrite | Finding C5a |
| 9 | Node identity | Hub verifies node ownership on WebSocket registration; group claims are derived from the database | Finding C2 |
| 10 | Revocation | Group revocations are honoured by nodes; denylist persists across restarts | Finding H4 |
| 11 | Privacy | Only **public** groups register content hashes with the hub | Finding H7 |
| 12 | Client architecture | The hub **keeps serving the web UI**. A native desktop client is offered **alongside** it | Decision D1/D2 |
| 13 | Hub role | "Hub minimization" is **deferred and may be dropped**. The hub stays in the trusted path by choice | Decision D4 |

---

## 2. Security claims — what holds, against whom

This replaces the informal assurances scattered through v4 §4.2.x and §13.

| Claim | Passive hub | **Active hub** | Malicious node operator | Malicious group member | Network attacker |
|---|---|---|---|---|---|
| File content is unreadable | ✅ | ❌ **H3** | ❌ by design — the operator hosts the files | ❌ members share the GEK | ✅ |
| Chat content is unreadable | ✅ | ❌ H3 | ❌ plaintext at rest until Phase 15 | ❌ | ✅ |
| File index is unreadable | ✅ | ❌ H3 | ❌ | ❌ | ✅ |
| Content cannot be modified | ✅ | ✅ | ❌ by design | ✅ | ✅ |
| Node cannot be impersonated | ✅ | ✅ | — | ✅ | ✅ |
| Client code integrity | ❌ **T3, accepted** | ❌ T3 | ✅ | ✅ | ✅ |
| Node content authority | ✅ | ✅ | ✅ sovereign | ✅ | ✅ |

**The claim this project can make:** *the hub cannot read your content unless it actively
attacks you.* That is true, defensible, and stronger than most platforms offer.

**The claim it must not make:** *"everything is encrypted and unreadable by other parties,
even the hub."* Two reasons, both deliberate:

- **H3 — key substitution.** The hub is the public-key directory. When a member invites
  someone, the inviter fetches the invitee's `pk_x25519` **from the hub** and wraps the
  GEK for it. A hub returning its own key is handed the group key. No forgery, no code
  injection, undetectable by the client today. Fixed only by key transparency and safety
  numbers (Phase 12.1); open until then.
- **T3 — the hub serves the SPA.** Accepted permanently for browser users (decision D1).
  A hub that ships the code can lift keys from the page regardless of protocol design.

Content is also readable by **every group member** and by **the node operator**, who
stores it in plaintext on disk. That is inherent to the model, not a defect — but it
means "end-to-end" here describes *client ↔ node*, never *client ↔ client*.

---

## 3. Transport (replaces v4 §6.4, §6.5, §7.1)

### 3.1 Listeners

| Listener | Role | Status |
|---|---|---|
| **WebRTC DataChannel** (aiortc) | Primary, browser **and** native clients | Unified handshake enforced |
| **QUIC** (aioquic) | LAN, port-forwarded, hub-less `group://` | Unified handshake enforced |
| ~~TCP + TLS 1.3~~ | — | **Removed** (C6) |
| ~~HTTP file API~~ | — | **Removed** (C1) |

The HTTP API bound `0.0.0.0` for every group, private ones included, and served the
Mesh Group Index and raw plaintext files with no authentication. It was deleted rather
than repaired: it duplicated MNP without any of its controls.

### 3.2 NAT traversal — correction

v4 presented `punch_nat()` as the native-client traversal mechanism. It is not one. It
is a single UDP probe to one address (`quic_server.py`), with:

- no STUN client (the `aioice` dependency is pulled in by `aiortc` only)
- no candidate gathering, no candidate pairs, no dual-stack fallback
- a requirement that the client already know its own external IP:port and connect from a
  fixed source port

It was validated on one ISP and one NAT type. **ICE/STUN is the traversal path** —
validated across two ISPs, two browsers, IPv4 STUN + IPv6 direct, and 4G CGNAT.

Native clients therefore run `aiortc` in Python rather than reimplementing traversal.
Every native benefit (local keystore, ChaCha20, Argon2id, Ed25519 auth) comes from being
native, not from the transport. QUIC is retained for LAN, port-forwarded and hub-less
access, where a signaling channel is unavailable or unwanted.

---

## 4. MNP handshake (replaces v4 §4.2.x handshake description)

One implementation: `meshbay_common/handshake.py`.

```
client → node   handshake            {token, group_id, nonce_c}
node            authorize_token()    JWT · scope · denylist · group_id · membership · hosting
node → client   handshake_challenge  {nonce_s}
client → node   handshake_response   {proof}
node            verify               HMAC(GEK, client transcript)
node → client   handshake_ack        {proof, sig, node_pk, is_node_admin}
client          verify               HMAC(GEK, node transcript) + Ed25519(node_pk)
```

### 4.1 Transcript

```
"meshbay:mnp:handshake:v1" ‖ len‖role ‖ len‖group_id ‖ len‖nonce_c ‖ len‖nonce_s ‖ len‖binding
```

Every field length-prefixed; the role bound in so a client proof cannot be replayed as a
node proof. v4's transcript was `nonce ‖ offer_fp ‖ answer_fp` — bare concatenation, and
a missing fingerprint silently degraded it to nonce-only, dropping MitM detection.
**An absent channel binding is now refused.**

### 4.2 Channel binding

| Transport | Anchor |
|---|---|
| WebRTC | both DTLS certificate fingerprints |
| QUIC | SHA-256 of the server certificate. aioquic exposes no RFC 5705 exporter; the client's access to the peer certificate is a guarded private attribute, and on a **resumed** session — which carries no certificate — the anchor travels with the session ticket |

### 4.3 Authorization rules

- `group_id` is **mandatory**. Omitting it previously skipped the membership check and
  fell back to the node's first group.
- Node-scoped daemon tokens are **refused** on the client path.
- The denylist is consulted for user, `jti` **and** group.

### 4.4 Mutual authentication

The node proves GEK possession over a client-chosen nonce **and** signs the transcript
with its long-term key. Previously the client received an unverifiable `node_pk` and
trusted `is_node_admin` from whoever answered — so a peer that had hijacked signaling
could serve a forged index, forged chat history and forged permissions.

The client also **pins** `pk_node` per node on first use (11.5.8) and refuses a changed
key outright, with a deliberate reset path in Settings for a legitimate rotation.

---

## 5. Node authority (replaces v4 §4.2.x)

### 5.1 Privileged operations

Destructive and privileged operations require an Ed25519 signature over a structured
transcript, never a JWT — the hub controls JWT issuance and can therefore never
establish node-level authority.

```
"meshbay:admin:v1" ‖ len‖op ‖ len‖node_pk ‖ len‖group_id ‖ len‖subject ‖ len‖nonce ‖ len‖ts
```

TTL 120 s. The client reconstructs the transcript from announced fields and **refuses to
sign** if the operation or subject does not match what the user requested. v4's challenge
was 32 opaque random bytes signed blind — an unbound signing oracle.

| Operation | Authority |
|---|---|
| `file_delete` | Node operator, or the user who uploaded the file (verified by the key recorded at upload) |
| `gek_bundle_store` | **Node operator only** |
| GEK activation | **Local admin UI or CLI only** — no MNP message can activate a GEK |

`gek_bundle_store` previously accepted any member's bundle and auto-activated one
addressed to the operator. Since the operator's X25519 public key is published in
`handshake_ack`, any member could wrap a key of their choosing for it and take over the
group. **Consequence of the fix:** a group admin who does not run the node can no longer
invite members — the operator decides what is stored on their machine.

### 5.2 Uploads

Confined to `shared_root/.uploads/{user_id}/`, filename allowlist, no overwrite, chunk
ordering enforced, size capped. Previously uploads landed in the shared root under a
client-chosen name and overwrote anything there — which also defeated deletion
authorization, since overwriting a file made the attacker its recorded uploader.

### 5.3 Local admin UI

Loopback plus a **per-run session token** (`?t=` or `X-MeshBay-Token`), printed at
startup. "Localhost only" is not authentication: any local process can reach it, as can
a page in the operator's browser via DNS rebinding — and this API re-initialises group
keys and reads the audit log. All interpolated values are HTML-escaped; CSP contains
exfiltration but cannot prevent injected inline script, so escaping is the actual fix.

---

## 6. Hub (replaces v4 §4.1)

### 6.1 Role — chosen, not minimal

Hub minimization was considered and **deferred** (decision D4). The hub keeps serving
the web UI and remains in the trusted path by choice. This section describes what it
*does*, not an aspiration.

**Stores:** accounts (username, encrypted email, public keys, status, role), group
registry and membership, IP logs (1 year, legal), node registrations, refresh tokens,
notifications, moderation blocklist.

**Does not store:** file content, file names, private-group indexes, message content,
private keys, GEK bundles, keypair bundles, node IPs beyond ephemeral signaling.

**Knows, unavoidably:** who is a member of what, when nodes connect, when a chat message
was posted and by whom (`chat_notify` — minimization was in the dropped phase), and
content hashes for **public** groups only.

### 6.2 Node registration

Registration on `/v1/nodes/ws` requires a node-scoped token, verifies `Node.user_id`
against the token subject, and derives group claims from the database — a node may
narrow the set to what it hosts but cannot widen it. It previously took `node_id` and
`group_ids` verbatim from the client's first message, letting any user hijack a victim
node's signaling and impersonate it to browsers.

### 6.3 Signaling

Rate-limited, SDP size bounded, capped per user, and the caller must share an **active**
group with the target node. Previously reachable by any authenticated user for any node,
making a third party's machine allocate peer connections on demand. `peer_ip` in the NAT
punch request must match the caller's source address.

### 6.4 Client addresses

`X-Forwarded-For` is honoured only from a trusted proxy, rightmost hop. It was trusted
unconditionally, so anyone could forge the IP written to the compliance log.

---

## 7. Cryptography (amends v4 §6)

Unchanged: GEK wrapping (ECIES, X25519 + HKDF + AEAD), per-chunk key derivation, domain
separation, on-the-fly encryption.

| Parameter | Value |
|---|---|
| Node keystore KDF | Argon2id **256 MB**, iterations 3, lanes 4 — parameters recorded per envelope so they can be raised without orphaning existing keystores |
| Hub password verifier | Argon2id 256 MB over a PBKDF2-derived `auth_key` |
| Browser bundle key | PBKDF2-SHA512, 600 000 iterations |

**Known weakness (C4).** Keypair bundles are protected only by PBKDF2 and are pushed to
every node whose group the user joins, while GEK and keypair bundle fetches are served in
the pre-proof window because the client needs its bundle to compute the proof. The window
is bounded (4 fetches) and audited. It closes properly when the native client stops
storing keypair bundles remotely (Phase 13.3) — the material belongs on the user's own
device, not on the hub *or* on other people's nodes.

---

## 8. Clients (replaces v4 §4.3)

### 8.1 Two clients, deliberately

| | Hub-served web SPA | Native desktop client |
|---|---|---|
| Distribution | Served by the hub | Installed, signed release |
| Code integrity | **T3 accepted** — the hub can inject | Detectable *if* reproducible builds ship |
| Key storage | IndexedDB / sessionStorage | OS-protected local keystore |
| Crypto | WebCrypto (AES-GCM) | Full (ChaCha20, Argon2id) |
| Transport | WebRTC | WebRTC **+ QUIC** |
| Positioning | **Convenience tier** — zero install | Recommended for sensitive use |

The SPA is not deprecated. It is the zero-install path and it stays. It must be labelled
honestly: `/app/` states that the hub serves this code, and the docs never claim
end-to-end *integrity* for that path.

### 8.2 Native client

pywebview + aiortc, sharing ~69% of the existing UI unchanged (the SPA contains no direct
`crypto.subtle` or `RTCPeerConnection` usage; everything goes through three injected
globals and one fetch helper). Assets ship **inside the package** and load from disk — a
shell pointing its WebView at the hub's `/app/` would be a browser with a different icon
and would fix nothing.

Native does **not** remove trust in the hub operator; it converts an undetectable,
per-request, per-user attack into a persistent artifact that can be hashed and compared.
That value is realised by reproducible builds and published hashes, not by the packaging
format.

---

## 9. Open items

**Phase 11.5 is complete.** All six critical and all seven high findings from
`second-review.md` are closed, bounded, or deferred by explicit decision.

### Closed since this document was drafted

| # | Item | Closed by |
|---|---|---|
| **C6** | GEK proof on the QUIC path | QUIC now runs the same challenge/response as WebRTC — client nonce, role-bound transcript, GEK proof, and the node proving itself with a GEK proof plus an Ed25519 signature |
| 11.5.6 | QUIC channel-binding anchor | Certificate hash. Server reads its own certificate from disk; the client's access to the peer certificate is guarded and fails loudly if aioquic moves it. **A resumed TLS session carries no certificate**, so the anchor travels with the session ticket — sound, because the ticket is derived from the handshake where the certificate was presented |
| 11.5.8 | `pk_node` TOFU pinning | Pinned per `node_id` on first handshake; a change is **refused**, with a deliberate reset in Settings |
| **M8** | Node announce proof-of-possession | Announcer signs `meshbay:node_announce:{user_id}:{pk_node}:{timestamp}`; re-announcing updates in place |

### Still open

| # | Item | Status |
|---|---|---|
| **H3** | Hub key substitution | **Open** — the last unfixed finding. The hub is the public-key directory, so it can be handed the GEK at invite time. Fixed by Phase 12.1 safety numbers |
| C4 | Remote keypair bundles | Bounded (4 pre-proof fetches, audited); closes in Phase 13.3 when the native client stops storing them remotely |
| — | Chat encryption (Sender Keys) | Phase 15. Distribution must be **pairwise to identity keys**, never GEK-derived |
| — | Chat attachments | Plaintext on the node; decide in Phase 15.7 |
| **T3** | Hub serves the SPA | **Accepted permanently** (D1) |

### Scope note on pinning

With C6 closed, `pk_node` pinning is defence in depth rather than the primary control: a
substituted node already fails the GEK proof. Pinning covers the case where an attacker
*holds* the group key — an ex-member, or a leaked GEK — and swaps the node underneath,
which the proof alone cannot distinguish from the genuine node.

### Sender Keys — scope correction

Sender Keys protects chat from someone holding the node's disk who is **not** a group
member — a seized machine, a hosting provider, a compromised node. It does **not**
protect chat from the node operator, who is a group member and therefore a legitimate
recipient. Distributing sender keys under the GEK would make the encryption decorative,
since anyone with the GEK would recover every sender key.

---

## 10. Testing posture

The pre-remediation suite passed 209 tests while every finding in the review was live. It
tested that features work, and in doing so **pinned four vulnerabilities in place** as
expected behaviour: GEK auto-activation, the transport-wide chat store, the blind admin
challenge, and private-group hashes registered with the hub. A refactor that accidentally
fixed one would have been reported as a regression.

Security tests are therefore written as **negative assertions** — "this attack does not
work" — and verified to fail against the pre-fix source before being trusted.
`test_security_regressions.py`, `test_node_ws_auth.py` and `test_handshake.py` hold them.