From 1f6b67c7bfc8078991a4607bb0419aea15bfd54c Mon Sep 17 00:00:00 2001 From: Christophe Besson Date: Wed, 23 Sep 2026 18:16:44 +0200 Subject: docs: qualify what an invitation link changes about the code MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The security claims table, §3.4's property 2, the protocol's stated limits, the quickstart and the user guide's defaults now say where a link's code differs: bound to its account only when redeemed, and held by the hub when the inviter asks it to mail. Co-Authored-By: Claude Opus 5.5 --- docs/MESHBAY_DESIGN.md | 5 +++-- docs/MESHBAY_NODE_PROTOCOL.md | 5 +++++ docs/QUICKSTART.md | 5 +++++ docs/USERGUIDE.md | 1 + 4 files changed, 14 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/MESHBAY_DESIGN.md b/docs/MESHBAY_DESIGN.md index e7d7f0c..a9653b6 100644 --- a/docs/MESHBAY_DESIGN.md +++ b/docs/MESHBAY_DESIGN.md @@ -163,7 +163,7 @@ document uses: | Content cannot be modified | ✅ | ✅ | ❌ by design | ✅ | ✅ | | The node cannot be impersonated | ✅ | ✅ | — | ✅ | ✅ | | Client code integrity | ❌ **T3, accepted** (browser) · ✅ ships in the package (native) | ❌ T3 · ⚠️ native: **detectable, not prevented** | ✅ | ✅ | ✅ | -| The hub cannot obtain the group key | ✅ | ✅ **except** in an open-join group, where it can join legitimately (§7.3) | — | — | ✅ | +| The hub cannot obtain the group key | ✅ | ✅ **except** in an open-join group, where it can join legitimately (§7.3), and for an invitation the inviter asked the hub to mail, whose code it then holds (§3.4) | — | — | ✅ | | Node content authority | ✅ | ✅ | ✅ sovereign | ✅ | ✅ | | Devices cannot be added by the hub | ✅ | ✅ — the hub holds no user key and cannot countersign | ⚠️ a node adds a device only to itself, where it already reads everything | ✅ | ✅ | | Chat senders are authenticated to each other | ✅ | ✅ | ⚠️ only for accounts the reader has already seen (§3.3) | ✅ | ✅ | @@ -374,7 +374,8 @@ Four properties, each load-bearing: 2. **The code binds a key to an account**, and the hub never sees it — unless the inviter ticks *Send the invitation by e-mail* (below). 40 bits, Crockford base32 rendered `XXXX-XXXX`, single use, valid for exactly one - account in one group, stored only as `sha256(code)`. A password KDF over 40 + account in one group — except an invitation link's, which names its account + when it is redeemed (below) — stored only as `sha256(code)`. A password KDF over 40 uniformly random bits would buy nothing. Guessing is bounded by 5 attempts per connection and a node-wide lockout, and every attempt is an audit event. 3. **The node's roster is the authority**, not hub membership. A hub that invents diff --git a/docs/MESHBAY_NODE_PROTOCOL.md b/docs/MESHBAY_NODE_PROTOCOL.md index 3ae533b..48af939 100644 --- a/docs/MESHBAY_NODE_PROTOCOL.md +++ b/docs/MESHBAY_NODE_PROTOCOL.md @@ -2180,6 +2180,11 @@ walks through the gate meant to stop it. attacks apart: the pairing code defeats a hub that *lies in its directory* — silent, undetectable, per-request — not one that *rewrites the client*, which is an artifact that can be inspected and compared. +* **An invitation link's code is a bearer code** (§8.6). The node admits whoever brings + it first; what restricts who can bring it is the hub, which lets only the addressed + account reach the node — a rule an active hub does not have to keep. The challenge + signature (§6.5) keeps the code from reaching any node but the issuer; it does not + keep it from a hub the inviter asked to mail it, which then holds it. * **The pre-proof window is a disclosure surface.** A hub that forges a JWT can fetch a member's *encrypted* keypair bundle. It is bounded, audited, and closes when clients stop storing bundles on other people's nodes (§7). diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 4da1eff..bf6cc80 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -318,6 +318,11 @@ Send that code however you normally talk to them — message, mail, out loud. It works once, for that account only, for that group only, and the hub never sees it. You do not need to be online when they use it. +Someone with no account yet gets a link instead, bound to their e-mail address: +`meshbay-node member invite alice@example.org --link`. They open it, register +with that address, and land in the group without typing a code +([`USERGUIDE.md` §7](USERGUIDE.md#7-managing-people)). + You can do the same thing from the **Members** tab of the group, from the browser you paired in Step 8. There, **Send the invitation by e-mail** is ticked by default and has the hub mail the code for you — which means the hub reads it. diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md index dda69d2..d3676cf 100644 --- a/docs/USERGUIDE.md +++ b/docs/USERGUIDE.md @@ -853,6 +853,7 @@ and every member re-admitted. It is small — back it up somewhere safe. | | | |---|---| | Invitation code | 7 days, single use, one account, one group | +| Invitation link | 7 days, single use, one group, the account registered with its address; 20 pending per group | | Operator pairing code | 24 hours | | Device linking code | 1 hour | | Devices per account per node | 5 | -- cgit v1.2.3