diff options
| -rw-r--r-- | docs/MESHBAY_DESIGN.md | 2 | ||||
| -rw-r--r-- | docs/USERGUIDE.md | 29 |
2 files changed, 30 insertions, 1 deletions
diff --git a/docs/MESHBAY_DESIGN.md b/docs/MESHBAY_DESIGN.md index 67f0bff..d34351b 100644 --- a/docs/MESHBAY_DESIGN.md +++ b/docs/MESHBAY_DESIGN.md @@ -33,7 +33,7 @@ | `MESHBAY_NODE_PROTOCOL.md` | the MNP wire format, message by message | | `transfers-v1.md` | the transfer system's failure-mode analysis, kept because a synthesis cannot carry "every way a slot can be lost" | | `playlists.md` | the playlist design in full — decided, not built (§9.10) | -| `USERGUIDE.md` | how to use and operate a deployment | +| ~~`USERGUIDE.md`~~ | **deprecated** — a large majority of it predates per-node identity, named roots and the sealed wire, and is wrong. Kept for provenance; its own banner lists what is false | | `PACKAGING-GUIDE.md`, `QUICKSTART.md`, `HTTPS.md`, `MAIL-SERVER.md`, `windows-build.md` | installation and server operations | | `CLAUDE.md` | project conventions and the engineering lessons that govern how changes are made | | `old-draft.md` | historical archive of drafts v1–v4. Nothing there is authoritative | diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md index 3c0e30c..c9febff 100644 --- a/docs/USERGUIDE.md +++ b/docs/USERGUIDE.md @@ -1,5 +1,34 @@ # MeshBay User Guide +> # ⚠️ DEPRECATED — do not rely on this document +> +> **A large majority of it is wrong.** It describes the system as it stood before +> several of the changes that define it now, and it has not been maintained since. +> It is kept for provenance only. **Read `MESHBAY_DESIGN.md` for the architecture +> and the security model, and `MESHBAY_NODE_PROTOCOL.md` for the wire format.** +> +> What is known to be false here, so that nothing below is mistaken for current: +> +> | Section | What it claims | What is true | +> |---|---|---| +> | §2 Account Management | Identity keys are derived from username + password, or generated in the browser and stored on the hub as an encrypted bundle | Identity keys are **per node**, created at first contact with each node and left there. Registration generates nothing, and the hub stores no keypair bundle and no user public key | +> | §4 Setting up a Node, §5 Sharing Files | A group has one `shared_dir`, and everything members send lands in `shared_dir/uploads/` | A group has **several named roots**, each read-only or read-write. The `uploads/` quarantine was removed on 2026-09-06 | +> | §8 Security Model — ciphers | ChaCha20-Poly1305 is the principal cipher, AES-GCM an optional browser variant | **AES-256-GCM encrypts everything.** No production path constructs a ChaCha20 cipher | +> | §8 Security Model — what the hub stores | The hub holds users' identity public keys and the wrapped group keys | It holds neither. Removing the key directory is what closed finding **H3**; the bundles moved to the node | +> | §8 GEK wrapping | A member wraps the group key for another member, and the hub stores the bundle | **The node wraps it**, on every connection, for a key the joiner proved possession of. The described flow *is* finding H3 | +> | §10 Troubleshooting | `GET /v1/groups/{id}/gek` returns 404 | That endpoint no longer exists | +> +> And it predates, so never mentions: encrypted chat, the sealed index and upload +> path, transfer leases, device linking, and the group-application framework. +> +> Two passages are also still in French, and one code fence is unbalanced. +> +> **Do not repair this file section by section.** Enough of it is wrong that a +> reader cannot tell the sound parts from the stale ones, which is worse than +> having no guide — and a patch that fixes one section leaves that problem intact. +> A user guide, when there is one again, starts from `MESHBAY_DESIGN.md`. + + This guide covers MeshBay in depth — architecture, configuration, security, and the full API. Read the [Quickstart](QUICKSTART.md) first if you have not set up a node yet. --- |