From d7120761fe8cf406f374ef769db6e1f9bf1fe287 Mon Sep 17 00:00:00 2001 From: Christophe Besson Date: Fri, 14 Aug 2026 01:28:12 +0200 Subject: docs: record the invite redesign — H3 and M3 closed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit draft-v5 §2: against an active hub, reading content moves from "❌ H3" to "❌ T3 (browser) · ✅ native". The defensible sentence becomes "the hub cannot read your content unless it ships you malicious client code" — T3 is now the only path, it is an artifact rather than a silent directory lie, and it does not exist for a native client. New §5.5 describes admission and key delivery, with the four properties that carry it and the one exception (open-join groups, where the hub can walk in the front door — a property of open joining, and the setting is read from node.toml). Corrected while writing it: §5.1 said the C5b fix stopped a group admin who does not run the node from inviting, and that the redesign reverses this. It does not, because delegation was deferred. What changed is the timing — the operator issues a code and is then out of the loop. devel-phases-next: 12.1 is done and NOT as written. The plan was key transparency plus safety numbers; what shipped removes the directory read instead. Safety numbers make substitution detectable by a human who checks, at first contact, when there is nothing to check against. 12.2 (served-SPA integrity) is now the highest-value item in that phase. Phase 14 marked for what landed. second-review: H3 and M3 annotated closed at the finding, with what actually closed them. The §7 verdict table is left intact — it is the record of an audit on a date, and falsifying it would be worse than leaving it — with a note pointing at draft-v5 §2 for current state. CLAUDE.md matters most here, being loaded every session: NS4 read "admin_pk_ed25519 auto-pinned from keystore ✅ DONE", which is M3 described as a feature. Rewritten, with the two fixes that must never be attempted (auto-pin, hub lookup). QE/deploy/README.md: set-admin-pk retired from the walkthrough; the regression checklist now exercises pairing, joining by code, recognition without a code, and revocation. USERGUIDE.md is beyond the invite work but was actively wrong: it told users to POST GEK bundles to a hub endpoint deleted in Phase 12, and to re-wrap for every remaining member on revocation. Both replaced with what the code does. Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 32 +++++++++++- devel-phases-next.md | 72 +++++++++++++++++--------- docs/USERGUIDE.md | 80 +++++++++++++---------------- docs/meshbay-draft-v5.md | 131 ++++++++++++++++++++++++++++++++++++----------- second-review.md | 21 +++++++- 5 files changed, 232 insertions(+), 104 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 549e83b..b2fb9b0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -116,7 +116,11 @@ Scope: `hub`, `node`, `common`, or omitted for cross-cutting - **NS1** GEK-HMAC proof in handshake — blocks hub admin from accessing any group content ✅ DONE - **NS2** Ed25519 challenge-response for admin operations — blocks hub admin impersonation ✅ DONE - **NS3** `gek_req` endpoint removed — node never serves GEK in plaintext ✅ DONE -- **NS4** `admin_pk_ed25519` pinned in node.toml — auto-pinned from keystore ✅ DONE +- **NS4** ~~`admin_pk_ed25519` auto-pinned from keystore~~ ❌ **that was finding M3.** The + keystore key is not the key the browser signs with, so every admin operation failed + closed. Authority now comes from the node's roster — `meshbay-node operator pair` + (2026-08-14). `admin_pk_ed25519` is still read as a legacy form; never auto-pin again, + and never resolve the operator's key through the hub - **NS5** DTLS channel binding in GEK-HMAC — `HMAC(GEK, nonce || offer_fp || answer_fp)` detects WebRTC signaling MitM ✅ DONE - **NS6** Chat `sender_id` enforced from authenticated session — prevents impersonation ✅ DONE - **NS7** Node Ed25519 auth — node daemon authenticates to hub via `POST /v1/nodes/auth` (Ed25519 signed timestamp), no auth_key/password on node. JWT `scope: "node"` blocks group management (create/add/delete/join). Operator manages groups from browser only. ✅ DONE @@ -124,7 +128,10 @@ Scope: `hub`, `node`, `common`, or omitted for cross-cutting **Known remaining trust assumptions (Phase 12 — all actionable items done):** - **T1** ✅ DONE: password split (auth_key / bundle_key, independent PBKDF2). Legacy migration on first login. -- **T2** Hub controls public key distribution → can substitute keys during invite. Fix: out-of-band key verification (safety numbers) +- **T2** ✅ **CLOSED 2026-08-14** (the finding is H3). Not by safety numbers: the invite + path stopped reading the directory. The node holds the GEK and wraps it for a key the + recipient proves possession of; identities are bound to accounts by one-time codes the + hub never sees. See `docs/invite-pairing-v1.md` - **T3** SPA served by hub → fundamentally unsolvable in browser. Fix: native client or browser extension **T3 attack surface reduction (2026-08-12, all phases complete):** @@ -165,6 +172,27 @@ on the WebRTC path only, and three other paths into the node were left behind. - **H3** Hub is the key directory → key substitution at invite yields the GEK. "Unreadable even by the hub" is true against a *passive* hub only +## Invite redesign (2026-08-14) — closes H3 and M3 + +See `docs/invite-pairing-v1.md`. Read it before touching invites, admin authority or +`gek_bundle_store`. + +- **The node wraps the group key**, on every connection, for the X25519 key the joiner + signed with their pinned Ed25519 identity. **Nothing fetches a public key from the hub + to wrap for** — not the SPA, not `gek-init`. That lookup *was* H3 +- **`gek_bundle_store` is deleted**, not gated. No member hands the node key material +- **The node's roster decides who gets the key**, not hub membership: a hub that invents + an account and mints it a token gets `not_authorized_for_group` +- **One-time codes** bind a key to an account without the directory. 40 bits, single use, + one account, node-wide lockout. 7 days for invitations, 24 h for operator pairing, both + in `[node]` of node.toml +- **`join_policy`** (`invite`|`open`) is read from **node.toml, never the hub** — a hub + able to declare a group open would be handed its key. Unknown group ⇒ `invite` +- Operator surface over SSH: `operator pair`, `member list|invite|revoke|unpin`. Deleting + a file is the last browser-only operation +- Revocation now works for key delivery (nothing stored survives it) — but **still rotate + the GEK**, the ex-member holds the current one + **Corrections to remember:** - `punch_nat()` is **not** a NAT traversal stack — one UDP probe, no STUN, no candidate gathering, one ISP validated. **ICE/STUN (WebRTC) is the traversal path**, for native diff --git a/devel-phases-next.md b/devel-phases-next.md index 682cb1b..3c9c639 100644 --- a/devel-phases-next.md +++ b/devel-phases-next.md @@ -745,29 +745,38 @@ cannot delete or overwrite another member's file, and cannot change the group ke > opaque private-group metadata, chat_notify minimization, schema cleanup) is dropped > from the plan; the swarm item already shipped in 11.5.18. -**Objective:** make the hub's two remaining powers over confidentiality *detectable*, -given that it stays in the trusted path by choice. +**Objective:** make the hub's remaining power over confidentiality *detectable*, given +that it stays in the trusted path by choice. -### Why these two survive +### 12.1 is DONE — and not as it was written -**H3 is the last open High finding, and nothing else fixes it.** 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 that returns its own key gets -the group key, decrypts everything, and nothing in the protocol notices. This needs no -JWT forgery and no code injection. Deferring Phase 12 wholesale would leave it open -indefinitely, so it moves here rather than disappearing. +**H3 is closed (2026-08-14), by removing the lookup rather than by verifying it.** The +plan here was key transparency and safety numbers: keep fetching the invitee's key from +the hub, and give humans a way to notice a substitution. What shipped instead is the +invite redesign in `docs/invite-pairing-v1.md` — the node holds the GEK and wraps it +itself, for a key the recipient proves possession of, and identities are bound to +accounts by one-time codes the hub never sees. -**Serving the SPA is now a deliberate choice, not a residual risk.** A hub that ships -the code can exfiltrate keys from the page whatever the protocol does (T3). That is -accepted — but it should be labelled honestly and made verifiable where possible. +Why that is better than what was planned: safety numbers make a substitution *detectable +by a human who bothers to check*, at the single worst moment (first contact, when there +is no previous key to compare against). Removing the directory read from the invite path +makes the substitution impossible instead, and costs the user one code to pass along +rather than a fingerprint comparison ritual. + +It also closed **M3** as a side effect, and absorbed **14.3/14.4** (CLI invite, member +management), which had to exist for a headless operator to admit anyone. + +Safety numbers may still return later as defence in depth for *identity* verification — +"is this really Bob's account" — which is a different question from "which key gets the +group key". They are no longer load-bearing. ### Milestones | # | Component | Description | |---|---|---| -| 12.1 | **Key transparency + safety numbers** [H3] | Hub-signed append-only key log; clients pin the key they first saw for a contact and audit the log; a key change raises a blocking warning before any GEK is wrapped for it; safety-number comparison UI between two members. Applies to the SPA and the native client alike | -| 12.2 | Served-SPA integrity | Strict CSP, Subresource Integrity on the bundle, and a signed digest of the served bundle published by the hub so a native client or extension can verify what the browser was given | -| 12.3 | Honest labelling | `/app/` states plainly that the hub serves this code and what that implies. Docs stop claiming end-to-end integrity for the hub-served path — the claim that holds is "the hub cannot read your content unless it actively attacks you" | +| 12.1 | ~~Key transparency + safety numbers~~ [H3] | ✅ **DONE 2026-08-14**, by a different design — see above and `docs/invite-pairing-v1.md` | +| 12.2 | Served-SPA integrity | Strict CSP, Subresource Integrity on the bundle, and a signed digest of the served bundle published by the hub so a native client or extension can verify what the browser was given. **Now the highest-value item here**: T3 is the only remaining way an active hub reads content, and it can also lift a pairing code out of the page it served | +| 12.3 | Honest labelling | `/app/` states plainly that the hub serves this code and what that implies. Docs stop claiming end-to-end integrity for the hub-served path — the claim that holds is "the hub cannot read your content unless it ships you malicious client code" | | 12.4 | Written threat model | One page: passive hub, active hub, malicious node operator, malicious member, network attacker, local attacker — and for each claim, which adversary it holds against. This is what stops the overclaiming pattern the second review kept finding | **Dropped from the old Phase 12** (recorded so the intent is not lost if it returns): @@ -866,8 +875,13 @@ Every operator action lived behind a web UI on the node's own loopback interface so a node on a server reached over SSH could not be operated at all without port-forwarding a browser session — and 11.5.3 added a token that had to be copied out of a log to get in. `status`, `ui` and `gek-init` shipped to unblock -that. The remaining commands matter for the same reason: **a headless operator -still cannot invite a member or delete a file without a browser.** +that. + +**Member management landed 2026-08-14** with the invite redesign, for the same +reason: a node admits people from its own roster, and a headless operator had no +way to put anyone on it. `operator pair`, `member list|invite|revoke|unpin` all +work over SSH. **Deleting a file is now the only operator action that still needs +a browser.** ### Milestones @@ -879,19 +893,27 @@ still cannot invite a member or delete a file without a browser.** | 14.2 | `meshbay-node group list` | List configured groups with online status | | 14.3 | `meshbay-node group create` | Create group on hub, add to config, generate GEK | | 14.4 | `meshbay-node group join` | Join existing group, fetch GEK from local BundleStore, add to config | -| 14.5 | `meshbay-node member invite` | Wrap GEK for new member, store bundle in the local BundleStore (**not** the hub — bundles have been P2P since Phase 12) | -| 14.6 | `meshbay-node member remove` | Rotate GEK, re-wrap for remaining members, store locally | -| 14.7 | `meshbay-node member list` | List group members with online status | +| 14.5 | `meshbay-node member invite` | ✅ **DONE 2026-08-14** — issues a one-time code; the node wraps the GEK itself when the invitee connects. The original description ("wrap GEK for new member, store bundle") describes the design the invite redesign replaced | +| 14.6 | `meshbay-node member revoke` | ✅ **DONE** — stops the node serving the key, and tells the operator to rotate it, since the ex-member still holds the current one | +| 14.6b | `meshbay-node member unpin` | ✅ **DONE** — forget a pinned identity so someone can pair again after a key reset | +| 14.7 | `meshbay-node member list` | ✅ **DONE** — roster: who is admitted, with what role, pinned when and how. Online status still to add | | 14.8 | Config reload (SIGHUP) | Daemon reloads config and adds/removes groups without restart | -| 14.9 | `meshbay-node admin-key` | Pin the operator's **client** Ed25519 key as `admin_pk_ed25519` — fixes M3, where auto-pinning the node keystore key makes operator deletion impossible | +| 14.9 | ~~`meshbay-node admin-key`~~ | ✅ **Superseded by `operator pair`** — pairing binds the operator's browser key with a one-time code instead of pasting a base64 key, and the auto-pin that made M3 possible is deleted | | 14.10 | `meshbay-node denylist` | Inspect and clear the persisted revocation denylist (11.5.17) | +| 14.11 | `meshbay-node file rm` | The one operator action still requiring a browser | ### Architecture -CLI commands communicate with the running daemon via a local Unix socket -(`/run/meshbay-node.sock`, mode 0600, owner-only). The daemon exposes a small internal API -for status queries and management operations. If the daemon is not running, -commands that require it fail with a clear error. +CLI commands talk to the running daemon over its **loopback admin API**, authenticated +with the per-run session token (11.5.3) — `_daemon_api()` in `daemon.py`. The Unix-socket +design below was the original plan; the loopback API already existed for the admin UI, +carries the same authorization, and avoided a second control plane. A socket would still +be an improvement (no port, file permissions instead of a token file) if the admin UI +ever goes away. + +`status` deliberately does *not* use it: it reads the keystore, the config and the roster +directly, so it works while the daemon is stopped — which is when an operator most needs +to know why. --- diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md index ccbf112..f5c10b8 100644 --- a/docs/USERGUIDE.md +++ b/docs/USERGUIDE.md @@ -189,59 +189,49 @@ Save `group_id` — you will need it in your `node.toml` and when adding members | Join | Open / approval-gated | By invitation only | | GEK | Not applicable | Required | -For private groups, the group admin generates a Group Encryption Key (GEK) — a random 32-byte ChaCha20-Poly1305 key. The GEK is never sent over the wire in cleartext. Instead, the admin wraps a copy of it for each member using that member's X25519 public key and stores the opaque bundle on the hub. +For private groups the node holds a Group Encryption Key (GEK) — a random 32-byte key that is never sent over the wire in cleartext. Each member receives a copy wrapped for their own X25519 public key (ECIES: X25519 + HKDF + AEAD). + +**The node does the wrapping, and it never asks the hub for anybody's key.** That matters: the hub is the account directory, so a hub that answered a key lookup with its own key would be handed the group key by an honest member following the protocol exactly (finding H3). Instead the recipient presents their own public keys over the authenticated P2P channel, signed by their identity key, and the node wraps for what it just verified. ### Add a member to a private group -The group admin fetches the new member's X25519 public key from the hub, wraps the GEK for them, and uploads the bundle: +The node operator issues a one-time code, from the server or from their browser: -```python -import base64, httpx -from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey, X25519PublicKey -from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305 -from cryptography.hazmat.primitives.kdf.hkdf import HKDF -from cryptography.hazmat.primitives import hashes, serialization -import os - -HUB = "https://meshbay.org" -GROUP_ID = "10484cb7-e45a-4cdc-8b06-f8ccdacc04d2" -TOKEN = "alice_test-access-token" -GEK_RAW = bytes.fromhex("your-32-byte-gek-in-hex") # load from keystore - -headers = {"Authorization": f"Bearer {TOKEN}"} - -# 1. Fetch new member's X25519 public key -r = httpx.get(f"{HUB}/v1/users/bob_test/pubkeys", headers=headers) -r.raise_for_status() -pk_member_raw = base64.b64decode(r.json()["pk_x25519"]) - -# 2. Wrap GEK for them (ECIES-like) -sk_eph = X25519PrivateKey.generate() -pk_eph_raw = sk_eph.public_key().public_bytes( - serialization.Encoding.Raw, serialization.PublicFormat.Raw) -shared = sk_eph.exchange(X25519PublicKey.from_public_bytes(pk_member_raw)) -wrap_key = HKDF(algorithm=hashes.SHA256(), length=32, - salt=pk_eph_raw, info=b"meshbay:gek_wrap:v1").derive(shared) -nonce = os.urandom(12) -wrapped = ChaCha20Poly1305(wrap_key).encrypt(nonce, GEK_RAW, pk_member_raw) - -# 3. Upload the opaque bundle to the hub -bundle = { - "pk_eph_b64": base64.b64encode(pk_eph_raw).decode(), - "nonce_b64": base64.b64encode(nonce).decode(), - "wrapped_b64": base64.b64encode(wrapped).decode(), -} -r = httpx.post(f"{HUB}/v1/groups/{GROUP_ID}/members/bob_test/gek", - json=bundle, headers=headers) -r.raise_for_status() -print("Bundle stored. bob_test can now access the group.") +```bash +# On the node, over SSH — no browser needed +meshbay-node member invite bob + +INVITATION CODE R3H8-TB6V +valid until 2026-08-21T12:00:00+00:00 ``` -The hub stores the bundle as an opaque blob. It cannot decrypt it — it stores `pk_eph`, `nonce`, and `wrapped` as separate columns but has no key to derive `wrap_key`. +Send the code to Bob however you already talk to him — it never passes through the hub, which is what stops the hub from claiming to be Bob. He enters it the first time he opens the group, and the node then wraps the group key for the key he proved he holds. + +After that first time the pin is his credential: he is recognised on every later connection, and asked for nothing. You do not need to be online when he joins. + +| | | +|---|---| +| Code lifetime | 7 days (`[node] invite_ttl_hours`) | +| Reuse | Single use; re-inviting supersedes the previous code | +| If it expires | Issue another one — nothing else is affected | +| Wrong code, repeatedly | Bounded per connection and node-wide, and logged in the node's audit log | + +The same operation is available in the web app: the group's **Members** tab, if your browser is paired with the node (`meshbay-node operator pair`). + +### Removing a member + +```bash +meshbay-node member revoke bob +meshbay-node gek-init # rotate: Bob still holds the old key +``` + +Revoking stops the node serving Bob the key from his next connection onward — there is no stored bundle left behind that could outlive the decision. It does **not** take back the key he already has, which is why the second command exists. + +### What revocation does and does not do -### Member revocation +Rotating the GEK (`meshbay-node gek-init`) makes the node encrypt new content with a new key, which every remaining member picks up automatically on their next connection — nothing has to be re-uploaded or re-wrapped by hand. -To revoke a member: generate a new GEK, re-encrypt it for all remaining members, and upload the new bundles. The node begins encrypting new content with the new GEK from that point. Former members can still decrypt previously received content (no retroactive re-encryption). +A former member can still decrypt content they already received: there is no retroactive re-encryption, and there is no way to reach into someone's disk. Revocation controls what happens next, not what already happened. --- diff --git a/docs/meshbay-draft-v5.md b/docs/meshbay-draft-v5.md index 8035824..b4a9e45 100644 --- a/docs/meshbay-draft-v5.md +++ b/docs/meshbay-draft-v5.md @@ -1,6 +1,8 @@ # MeshBay — Architecture Draft v5 -> Status: **Phase 11.5 (security remediation) complete.** See `devel-phases-next.md`. +> 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 @@ -19,7 +21,7 @@ v4 described intent. Several of its statements were contradicted by the implemen | "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 | +| "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 @@ -38,7 +40,8 @@ written that way. | 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 | +| 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 | @@ -54,31 +57,39 @@ 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 | ❌ | ❌ | ✅ | +| 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 actively -attacks you.* That is true, defensible, and stronger than most platforms offer. +**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. -**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. +**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). -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*. +**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*. --- @@ -187,14 +198,22 @@ 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** | +| `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. **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. +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 @@ -210,22 +229,65 @@ 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 — `meshbay-node status`, `ui`, `gek-init` | +| **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); until then a -headless operator still needs a browser to invite members or delete files. +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 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. +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). --- @@ -248,6 +310,11 @@ private keys, GEK bundles, keypair bundles, node IPs beyond ephemeral signaling. 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` @@ -335,16 +402,18 @@ format. | 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 | |---|---|---| -| **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) | +| — | 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 diff --git a/second-review.md b/second-review.md index a2218ad..071e6ef 100644 --- a/second-review.md +++ b/second-review.md @@ -394,6 +394,16 @@ Consider a localhost token in the URL to blunt DNS-rebinding against the unauthe ### H3 — An active hub breaks confidentiality through key substitution (T2 is not a residual risk) +> **CLOSED 2026-08-14.** Not by the fix proposed below. The invite path no longer reads +> the directory at all: the node holds the GEK and wraps it for a key the recipient +> proves possession of over the authenticated channel, and identities are bound to +> accounts by one-time codes the hub never sees. Safety numbers would have made the +> substitution *detectable by a human who checks*; removing the lookup makes it +> impossible. See `docs/invite-pairing-v1.md` and draft-v5 §5.5. +> +> `gek-init` had the same flaw with the node as the victim — it fetched every member's +> public key from the hub and wrapped for the answer. That is gone too. + **Location:** `app.js:1389-1415`, `users.py:340-358`, `users.py:310-337` The invite flow is: fetch `pk_x25519` for the invitee **from the hub**, wrap the GEK for it, @@ -535,7 +545,11 @@ minimum password, and the calibration command prints instructions to hand-edit a `meshbay_common` rather than writing a per-node parameter — so the keystore parameters cannot actually be tuned per hardware as §4.2.1 promises. -**M3 — Node operator cannot delete files in the default configuration.** `_resolve_admin_pk` +**M3 — Node operator cannot delete files in the default configuration.** *(CLOSED +2026-08-14 — the auto-pin is deleted; authority comes from the node's roster, established +locally by `meshbay-node operator pair`. Asking the hub for the operator's key, the +obvious-looking fix, would have let the hub install itself as node administrator.)* +`_resolve_admin_pk` (`daemon.py:451-465`) auto-pins the **node keystore's** Ed25519 key, while the browser signs challenges with the **user identity** key from the keypair bundle (`app.js:983`). These are different keys, so verification fails unless the operator manually sets `admin_pk_ed25519` to @@ -619,6 +633,11 @@ client path. ## 7. Does the system do what it claims? +> This table is the verdict **on the code as it stood on 2026-08-13**, and is left as the +> record of what the review found. It is not the current state: Phase 11.5 closed C1–C6 +> and H1–H7 except H3, and the invite redesign closed H3 and M3 on 2026-08-14. For what +> holds today, and against which adversary, read draft-v5 §2 — never this table. + | Claim (draft-v4) | Verdict | Why | |---|---|---| | Data never transits a central server | **Yes** | WebRTC DataChannel is genuinely P2P; hub relays SDP only. Well executed. | -- cgit v1.2.3