diff options
| -rw-r--r-- | docs/MESHBAY_DESIGN.md | 83 |
1 files changed, 81 insertions, 2 deletions
diff --git a/docs/MESHBAY_DESIGN.md b/docs/MESHBAY_DESIGN.md index 189dbc5..3672da2 100644 --- a/docs/MESHBAY_DESIGN.md +++ b/docs/MESHBAY_DESIGN.md @@ -152,7 +152,86 @@ document uses: | **Registered hub user with no membership** | Reach every hub endpoint that does not check membership | | **Federated peer hub** | Push directory rows and revocations over MHP | -### 2.2 Security claims +### 2.2 Security claims — and how to read them + +Every collaboration product carries the structural limits this section lists. +Most never write them down. What follows states ours plainly and separates three +things a single ❌ usually hides — a **definition**, a **guarantee** and an +**accepted risk** — and says, where it matters, how a comparable product fares on +the same point. Read it with one rule: **where you see a limit here, assume the +mainstream closed product has it too and does not tell you.** + +The verdict first. Against anyone *outside* your group — the hub, the network, +another group's operator — your content is unreadable. *Inside* your group, your +operator and fellow members read it, because that is what a group is. The one +place the protocol cannot protect a browser is **T3** (below); the native client +turns that from an invisible attack into a publicly verifiable one. + +#### What a group inherently means + +These are not defeats of the design; they are what *a shared, hosted group* is. +Each would read as ❌ in any honest table, for any product in this class: + +- Your **operator and fellow members read the group's content** — files, index + and chat. You chose them when you joined; they are your trust boundary, not the + hub's. +- Your **operator hosts the files, so they can alter what they host.** Authority + over a node's content is the operator's by design (§2.4, §7). +- **Leaving clears you hub-side; copies on a node you were hosted on stay** with + that operator (§7.7). + +On the one point every product in this class shares — who can read your content — +stated the way an honest table would: + +| Who can read your content | MeshBay | A mainstream E2EE messenger | A mainstream cloud suite | +|---|---|---|---| +| The people in your group | Yes — operator + members | Yes — every member | Yes — members + workspace admin | +| The server / host itself | No (native) · T3 (browser) | No — but a web build has the same client-code exposure, unstated | Yes, routinely | +| Is this limit written down for you? | Here, explicitly | Rarely | Almost never | + +#### What MeshBay guarantees + +Stated as guarantees, not as the absence of failure, against the adversaries in +§2.1: + +- Your **content never transits the hub** — the hub relays, it does not hold your + plaintext (§5). +- **No party outside your group reads your files, index or chat**: not the hub, + not the network, not the operator of any *other* group (§3.2, §4). +- The **hub holds no user key and cannot countersign**: it cannot add a device to + your account, become *you*, or obtain your group key — except where you ask it + to (open-join, mailed invitations; §7.3, §3.4). +- A **node cannot be impersonated**, and content one node holds cannot be forged + into another's (§5). +- Your **identity keys are per-node**: a bundle that leaks opens that one node's + bundle and no other (§3, §2.4). +- **Chat is unreadable from a copy of a node's storage** that lacks its unlock + key (§4.5). + +#### Residual risks, and how they are checked + +Two risks are real, named and accepted — each with the control that bounds it: + +- **T3 — a compromised hub and the browser.** The hub serves the browser SPA, so + an active hub can ship modified code to a browser user and lift their keys. No + protocol prevents this; it is accepted for browsers (§2.3). The **native client + removes it**: its code ships in the package, not from the hub, so a malicious + hub cannot alter it **without the change being publicly verifiable** — anyone + can rebuild from source and compare hashes (reproducible builds). The attack + moves from invisible-and-per-user to an artifact the whole community can check. + This is *verifiable*, not merely *detectable*: integrity someone actively + confirms, not something a victim might happen to notice. +- **C4 — keypair bundles.** For an account with browser access, each node holds + the bundle, sealed under the passphrase *and* a pepper the hub alone holds: no + operator can search it offline, only an active hub can — which is T3's adversary + already. For an account the desktop app keeps (browser access off, §3.7), + nothing of it sits on any node. An account is only as strong as its weakest + client. + +#### The full claim matrix + +For auditors: the complete claim-by-adversary matrix. The sections above are the +reading; this is the reference. | Claim | Passive hub | Active hub | Malicious node operator | Malicious member | Network attacker | |---|---|---|---|---|---| @@ -163,7 +242,7 @@ document uses: | Chat is unreadable **from a copy of the node's storage that lacks its unlock key** — not from a whole disk by default (§4.5) | ✅ | ✅ | — the operator holds the unlock key | ✅ | ✅ | | 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** | ✅ | ✅ | ✅ | +| Client code integrity | ❌ **T3, accepted** (browser) · ✅ ships in the package (native) | ❌ T3 · ⚠️ native: **publicly verifiable, not prevented** | ✅ | ✅ | ✅ | | 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 | ✅ | ✅ | |