docs: record the invite redesign — H3 and M3 closed

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 <noreply@anthropic.com>

1 files changed, 30 insertions, 40 deletions

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
+```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
+```
 
-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
+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.
 
 ---