# MeshBay — Architecture Draft v5 > Status: **Phase 11.5 (security remediation) complete. Invite redesign complete > (2026-08-14) — H3 and M3 closed.** See `devel-phases-next.md` and, for the invite > and pairing design, `docs/invite-pairing-v1.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 was the key directory, so it could substitute a key at invite time and be handed the GEK legitimately *(fixed 2026-08-14; the invite path no longer reads the directory — §5.5)* | | "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 | **Nothing arriving over MNP can activate a GEK.** Member-supplied bundles are not gated but *gone*: `gek_bundle_store` was deleted when the node took over wrapping | Finding C5b | | 7b | Admission | **The node wraps the group key itself**, for a key the recipient proved possession of, and admits people from its own roster using one-time codes the hub never sees (§5.5) | Findings **H3**, **M3** | | 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 | ✅ | ❌ **T3** (browser) · ✅ native | ❌ by design — the operator hosts the files | ❌ members share the GEK | ✅ | | Chat content is unreadable | ✅ | ❌ T3 · ✅ native | ❌ plaintext at rest until Phase 15 | ❌ | ✅ | | File index is unreadable | ✅ | ❌ T3 · ✅ native | ❌ | ❌ | ✅ | | Content cannot be modified | ✅ | ✅ | ❌ by design | ✅ | ✅ | | Node cannot be impersonated | ✅ | ✅ | — | ✅ | ✅ | | Client code integrity | ❌ **T3, accepted** | ❌ T3 | ✅ | ✅ | ✅ | | Node content authority | ✅ | ✅ | ✅ sovereign | ✅ | ✅ | | Hub cannot obtain the group key | ✅ | ✅ **since H3 closed** — except in `join_policy = "open"` groups, where it can join legitimately | — | — | ✅ | **The claim this project can make:** *the hub cannot read your content unless it ships you malicious client code.* Since H3 closed (2026-08-14) that is the **only** remaining path, it is not silent, and it does not exist for a native client. **What changed.** The hub used to be the key directory on the invite path: the inviter fetched the invitee's `pk_x25519` from the hub and wrapped the GEK for whatever came back, so a hub answering with its own key was handed the group key by an honest member following the protocol exactly. That path is gone. The node holds the GEK and wraps it itself, for a key the recipient proved possession of over an authenticated channel, bound to an identity the operator admitted with a one-time code the hub never sees (§5.5). **The claim it must not make:** *"everything is encrypted and unreadable by other parties, even the hub."* Three reasons, all deliberate: - **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 — and can read a pairing code out of it. This is an artifact-level attack, not a silent directory lie: the native client (Phase 13) plus reproducible builds (18.7) remove it. - **Open-join groups.** Where `join_policy = "open"`, anyone the hub calls a member is served the key, so the hub can join through the front door. That is a property of open joining, not a defect, and the setting is read from `node.toml` — the hub cannot declare a group open. - **Members and the operator read everything.** Inherent: "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) | | `invite_create` | **Node operator only** (delegation designed, deferred) | | GEK activation | **Local admin UI or CLI only** — no MNP message can activate a GEK | | ~~`gek_bundle_store`~~ | **Message deleted.** No member ever hands the node key material | `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. It was first gated behind an operator signature, then removed outright when the node took over wrapping (§5.5) — the message has no remaining purpose, and a path that does not exist cannot be mis-authorized. **Who can invite.** Still the node operator only: `invite_create` is verified against the operator keys in the node's roster. A group admin who does not run the node cannot admit anyone until delegation ships (§6.2 of `invite-pairing-v1.md`, deferred by decision 2026-08-13). What *did* change is the timing: the operator issues a code and is then out of the loop, so nobody has to be online when the invitee actually joins. ### 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 Operator interface Two personas, and they need different tools: | Operator | Reaches the node via | |---|---| | Desktop | the local admin UI in their own browser | | **Headless / SSH** | the CLI — `status`, `ui`, `gek-init`, `operator pair`, `member list\|invite\|revoke\|unpin` | The CLI is the primary interface for servers, which is the normal deployment. `status` deliberately reads the keystore and config directly so it works while the daemon is stopped — the state an operator is most often in, since the daemon will not stay up before its key is linked or before a group exists. Anything the UI can do should eventually have a CLI equivalent (Phase 14). Inviting, revoking and pairing now have one; deleting a file is the remaining browser-only operation. ### 5.4 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, issues invitations and reads the audit log. All interpolated values are HTML-escaped — filenames chosen by members, and usernames that originate at the hub; CSP contains exfiltration but cannot prevent injected inline script, so escaping is the actual fix. ### 5.5 Admission and key delivery (closes H3) The node decides who receives the group key, and produces every copy of it itself. ``` grenet (SSH) meshbay-node member invite bob → CODE R3H8-TB6V (or the same from the SPA's Members tab, signed by the paired browser) grenet sends the code to bob out of band bob opens the group; the client holds no GEK bob → node join_request {pk_ed25519, pk_x25519, code, sig} ← pre-proof window node code valid for this account → pin the identity, admit to the group node → bob the GEK, wrapped for the X25519 key bob just proved he holds ``` Four properties, each load-bearing: 1. **No public key is ever fetched from the directory.** The invitee's key arrives from the invitee, signed by their identity key in the same transcript (`meshbay:join:v1`), so the identity key vouches for the encryption key. This is the H3 fix. 2. **The code binds the key to the account**, and the hub never sees it. 40 bits, single-use, one account, node-wide lockout on repeated failures. Codes live 7 days for invitations and 24 h for operator pairing, both configurable. 3. **The node's roster is the authority**, not hub membership. A hub that invents an account, adds it to a group and mints it a token gets `not_authorized_for_group`. Exception by configuration: `join_policy = "open"` pins the first comer (TOFU) and serves them — read from `node.toml`, never from the hub. 4. **Wrapping happens on every connection**, so key rotation propagates by itself and revocation actually takes effect. No member bundle is stored; nothing outlives the decision to stop serving someone. (Rotating the GEK after a revocation is still required — the ex-member holds the old one.) `gek-init` no longer pre-wraps the key for anyone but the node's own keystore. It used to fetch every member's public key from the hub and wrap for what came back, which was H3 with the node as the victim rather than the inviter. Node authority is established the same way, once per node: `meshbay-node operator pair` prints a code, the operator types it into their browser, and the node pins that identity key. It is never learned from the hub — a hub able to name the operator's key could install itself as node administrator (finding M3, which the old keystore auto-pin left inert and failing closed). --- ## 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. **No longer decides:** who holds the group key. The hub still publishes public keys, and they are still used to look up an account by name — but nothing wraps a key for a key that came from there. Hub membership lets someone *reach* a node; the node's roster decides whether it wraps anything for them (§5.5). A pairing code never touches the hub. ### 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 | | **H3** | Hub key substitution | **Closed 2026-08-14** by the invite redesign (§5.5), not by safety numbers: no public key is fetched from the directory at all, so there is nothing to substitute. See `docs/invite-pairing-v1.md` | | **M3** | Node authority inert as shipped | Closed with it — authority comes from the roster, established locally by pairing | ### Still open | # | Item | Status | |---|---|---| | 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 | | — | Delegation | Designed, deferred: a group admin who does not run the node still cannot invite | | **T3** | Hub serves the SPA | **Accepted permanently** (D1). Now the *only* way an active hub reads content — and it can also read a pairing code out of the page it served. Removed for native clients by Phase 13 + reproducible builds (18.7) | ### 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.