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 --- docs/USERGUIDE.md | 80 ++++++++++++++++++++++++------------------------------- 1 file changed, 35 insertions(+), 45 deletions(-) (limited to 'docs/USERGUIDE.md') 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. --- -- cgit v1.2.3 From cfe49407abb3eb48b996ab6d08d66985f29846f0 Mon Sep 17 00:00:00 2001 From: Christophe Besson Date: Fri, 14 Aug 2026 19:15:49 +0200 Subject: docs: user guide and conventions catch up with per-node identity USERGUIDE said registration submits your public keys "so other members can wrap GEK bundles for you". Both halves are wrong now: registration creates an account and nothing else, and nobody wraps anything for a key fetched from the hub. The API reference and the register body followed the same correction. CLAUDE.md gains the block a future session needs before touching registration or anything shaped like a user's public key: keys are born at first contact with a node and stay there, the hub publishes none, tokens carry no pk_user, and a scripted signup is now a real account. Left alone deliberately: first-review.md, docs/poc-v1*.md and poc/spike-results.md still describe the old JWT and registration. They are records of what was true on their date, like second-review's verdict table, and draft-v5 is what states the present. Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 23 ++++++++++++++++++++++- docs/USERGUIDE.md | 27 ++++++++++----------------- 2 files changed, 32 insertions(+), 18 deletions(-) (limited to 'docs/USERGUIDE.md') diff --git a/CLAUDE.md b/CLAUDE.md index b8c2646..b2ff32a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -143,7 +143,8 @@ Scope: `hub`, `node`, `common`, or omitted for cross-cutting - `_bundleKey` persisted in IndexedDB (CryptoKey survives page refresh) - `_sessionKeys` persisted in sessionStorage (survives refresh, cleared on tab close) - `_pkFromSk()`: derive X25519 public key from recovered private key via JWK export (no hub fetch) -- Removed auto-`regenerateKeys()` on login (was silently rotating hub keys, breaking GEK unwrap) +- `regenerateKeys()` is gone entirely (2026-08-14): identity keys are per node, so + rotation is `meshbay-node member unpin ` plus a fresh code - Raw answer SDP saved before `setRemoteDescription` (Chrome strips sha-256 from multi-hash SDP) - Upload chunk size: 48KB (fits aiortc SCTP limit after msgpack overhead) @@ -212,6 +213,26 @@ See `docs/invite-pairing-v1.md`. Read it before touching invites, admin authorit - Floor: 12 characters and ~60 estimated bits, enforced client-side only — with the password split (T1) the hub never sees a passphrase +## Identity keys are PER NODE (2026-08-14) + +See `docs/per-node-identity-v1.md`. Read it before touching registration, the +keypair bundle, or anything that looks like a user's public key. + +- A keypair is created at **first contact with a node**, encrypted under the + passphrase, and left on that node. Never reused elsewhere. Cracking one yields + the identity used with that operator and nothing anywhere else +- **The hub stores and publishes no user keys.** `users.pk_ed25519`/`pk_x25519` + are dropped, `PUT /me/keys` is gone, `/pubkeys` returns an account id and the + node linking key. Do not reintroduce a key directory — that was H3 +- **Tokens carry no `pk_user`.** The node recorded it as the uploader's identity + and authorized deletion against it, so whoever issued tokens decided who could + delete a file. Attribution uses the roster pin (`_pinned_pk`) +- Registration generates nothing, so a scripted signup is a real account — + `QE/deploy/demo.py bootstrap` takes a wiped hub and node to a working demo +- The key handed back on a join belongs to the **group of the connection**, not + the group named in the invitation (an operator pairs node-wide while opening a + group) + ## Two lessons that cost four rounds of live testing - **`QE/deploy/e2e.py` cannot test `app.js`.** It is a second implementation of the diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md index f5c10b8..71b0060 100644 --- a/docs/USERGUIDE.md +++ b/docs/USERGUIDE.md @@ -62,7 +62,9 @@ MeshBay has three components. Understanding which role each plays avoids a lot o ### Register -Registration submits your Ed25519 (signing) and X25519 (key agreement) public keys. These let other members wrap GEK bundles for you and let nodes verify your JWT offline. +Registration creates an account and nothing else: a username, an email, and a value derived from your passphrase that lets the hub check it without ever seeing it. + +**No keys are generated here.** An identity keypair belongs to a *node*, not to the hub: one is created the first time you join a given node, encrypted under your passphrase, and left with that node. So an operator who takes their own disk holds a key that is worthless on anyone else's, and the hub has no key directory to publish — which is what finding H3 read. **Deux modes de génération de clés :** @@ -86,21 +88,12 @@ Implémenté dans `static/keyderive.js`. ``` POST /v1/users/register { - "username": "string", - "password": "string (min 8 chars)", - "pk_user_ed25519": "base64 raw 32-byte Ed25519 public key", - "pk_user_x25519": "base64 raw 32-byte X25519 public key", - "keypair_bundle": "base64 AES-256-GCM encrypted bundle (web clients only, optional)" + "username": "string", + "email": "string", + "auth_key": "base64 (PBKDF2-SHA512 of your passphrase — the hub never sees the passphrase itself)" } → 201 {"user_id": "uuid"} → 409 if username is taken -``` - -Passwords are hashed with Argon2id (iterations=3, memory=64 MB in dev; -target 256 MB / ~500ms in production). Intentionally slow to resist offline attacks. - -### Login - ``` POST /v1/users/login {"username": "yourname", "password": "yourpassword"} @@ -109,12 +102,12 @@ POST /v1/users/login "refresh_token": "opaque 256-bit token (30 days)", "token_type": "bearer", "expires_in": 3600, - "keypair_bundle": "base64 AES-GCM blob (présent uniquement si enregistré via web)" } ``` -Les clients web utilisent `keypair_bundle` pour récupérer leurs clés privées -sur un nouvel appareil : déchiffrement local avec le mot de passe via `keyderive.js`. +Le trousseau ne vient pas d'ici : chaque nœud conserve celui qui lui est propre, +chiffré par votre phrase de passe, et un nouveau navigateur le récupère auprès du +nœud auquel il se connecte. ```bash curl -s -X POST https://meshbay.org/v1/users/login \ @@ -754,7 +747,7 @@ All hub endpoints are under `https://meshbay.org`. Node endpoints are under `htt | Method | Path | Auth | Description | |---|---|---|---| -| POST | `/v1/users/register` | None | Register account. Body: `username, password, pk_user_ed25519, pk_user_x25519`. Returns `user_id`. | +| POST | `/v1/users/register` | None | Register account. Body: `username, email, auth_key`. No keys — identity keypairs are per node. Returns `user_id`. | | POST | `/v1/users/login` | None | Authenticate. Body: `username, password`. Returns `access_token, refresh_token`. | | POST | `/v1/users/token/refresh` | Refresh token | Issue new access token. Body: `refresh_token`. | | GET | `/v1/users/{username}/pubkeys` | Access token | Fetch `pk_ed25519` and `pk_x25519` for any user (used by group admins for GEK wrapping). | -- cgit v1.2.3