diff options
Diffstat (limited to 'docs/USERGUIDE.md')
| -rw-r--r-- | docs/USERGUIDE.md | 97 |
1 files changed, 40 insertions, 57 deletions
diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md index ccbf112..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,22 +88,13 @@ 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 \ @@ -189,59 +182,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 +```bash +# On the node, over SSH — no browser needed +meshbay-node member invite bob -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 +INVITATION CODE R3H8-TB6V +valid until 2026-08-21T12:00:00+00:00 +``` + +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. -headers = {"Authorization": f"Bearer {TOKEN}"} +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. -# 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"]) +| | | +|---|---| +| 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 | -# 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) +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`). -# 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.") +### Removing a member + +```bash +meshbay-node member revoke bob +meshbay-node gek-init # rotate: Bob still holds the old key ``` -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`. +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. --- @@ -764,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). | |