From f059cb118c556d1f0279350507f74b8a47d5a98a Mon Sep 17 00:00:00 2001 From: Christophe Besson Date: Fri, 11 Sep 2026 00:19:06 +0200 Subject: docs: remove the documents MESHBAY_DESIGN.md replaces MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Twenty-four files, about 17 000 lines: the two architecture drafts, the three security reviews, eleven design notes, the roadmap, the decisions file, the v1–v4 archive, the deprecated user guide and the stale quickstart. Their content is in MESHBAY_DESIGN.md, and git history holds the originals. The reason to delete rather than keep bannered: a document that is superseded but present still gets read, and a reader cannot always tell which of two accounts of one mechanism is the live one. That was the argument for retiring the user guide rather than repairing it, and it applies to the whole set. What made this safe is the concordance. Roughly 290 comments and docstrings cite these files by section — `musicbay.md §6`, `mediacenter.md §5.5`, `draft-v6 §2.11` — and section 16 maps every one onto its replacement, so not a single comment needs editing to stay followable. It now says plainly that the files are gone and where to recover them, and it gained rows for the three reviews (their findings are section 13), and for the two guides. Four kept documents pointed into the set and were repointed first: `playlists.md` (nine references — it is a live proposal and must not dangle), `WINDOWS-PORT.md`, and CLAUDE.md's example. No dangling reference remains outside section 16. Two files were dropped from the list after checking what they hold. `HTTPS.md` is an operational runbook — Caddy, certificate renewal, DNS, troubleshooting — and MESHBAY_DESIGN.md deliberately covers no operations, so nothing would replace it; the versioned Caddyfile is the config, not the procedure. `cast-smart-tv.md` is the plan for the unbuilt DLNA phase of a feature whose first two phases ship, and section 11.4 summarises it in four lines rather than carrying the SSDP/UPnP work. There is no user guide now, and section 0.1 says so rather than leaving a reader to discover it. Suites green: 2258 passed, 4 skipped. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01YVoHVCcfBqud6ZjG4db3y7 --- CLAUDE.md | 2 +- docs/MESHBAY_DESIGN.md | 20 +- docs/QUICKSTART.md | 243 --- docs/USERGUIDE.md | 1184 ----------- docs/WINDOWS-PORT.md | 4 +- docs/apps.md | 333 ---- docs/auth-confirm.md | 560 ------ docs/captcha.md | 555 ------ docs/chat-sender-keys.md | 859 -------- docs/desktop-client-v1.md | 1179 ----------- docs/devel-phases-next.md | 1388 ------------- docs/first-review.md | 382 ---- docs/indexing-v2.md | 324 --- docs/invite-pairing-v1.md | 559 ------ docs/mediacenter.md | 1035 ---------- docs/meshbay-draft-v5.md | 622 ------ docs/meshbay-draft-v6.md | 620 ------ docs/musicbay.md | 502 ----- docs/old-draft.md | 4497 ------------------------------------------ docs/per-node-identity-v1.md | 225 --- docs/photos.md | 516 ----- docs/playlists.md | 21 +- docs/refactor-groups.md | 916 --------- docs/refactor-node-ui.md | 413 ---- docs/refactoring-search.md | 426 ---- docs/second-review.md | 880 --------- docs/third-review.md | 723 ------- docs/tmp-decisions.md | 191 -- 28 files changed, 30 insertions(+), 19149 deletions(-) delete mode 100644 docs/QUICKSTART.md delete mode 100644 docs/USERGUIDE.md delete mode 100644 docs/apps.md delete mode 100644 docs/auth-confirm.md delete mode 100644 docs/captcha.md delete mode 100644 docs/chat-sender-keys.md delete mode 100644 docs/desktop-client-v1.md delete mode 100644 docs/devel-phases-next.md delete mode 100644 docs/first-review.md delete mode 100644 docs/indexing-v2.md delete mode 100644 docs/invite-pairing-v1.md delete mode 100644 docs/mediacenter.md delete mode 100644 docs/meshbay-draft-v5.md delete mode 100644 docs/meshbay-draft-v6.md delete mode 100644 docs/musicbay.md delete mode 100644 docs/old-draft.md delete mode 100644 docs/per-node-identity-v1.md delete mode 100644 docs/photos.md delete mode 100644 docs/refactor-groups.md delete mode 100644 docs/refactor-node-ui.md delete mode 100644 docs/refactoring-search.md delete mode 100644 docs/second-review.md delete mode 100644 docs/third-review.md delete mode 100644 docs/tmp-decisions.md diff --git a/CLAUDE.md b/CLAUDE.md index df80c54..824a3ae 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -129,7 +129,7 @@ that produced it. | The node, the hub, the clients, the applications | §6, §7, §8, §9 | | Structural decisions that are not revisited | §14 | | What is built, what is not, what is open | §15 | -| An older document's section reference (`draft-v5 §5.2`, `apps.md §3`, …) | §16, the concordance | +| A reference to a document that no longer exists (`draft-v5 §5.2`, `apps.md §3`, …) | §16, the concordance — it maps every one onto its replacement section | The documents under `docs/` that this replaced are kept and carry a banner saying where their content went. **Where any of them disagrees with diff --git a/docs/MESHBAY_DESIGN.md b/docs/MESHBAY_DESIGN.md index d34351b..d24d7a9 100644 --- a/docs/MESHBAY_DESIGN.md +++ b/docs/MESHBAY_DESIGN.md @@ -33,10 +33,15 @@ | `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`~~ | **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 | +| `cast-smart-tv.md` | the DLNA/UPnP device backend — designed, not built (§11.4) | +| `WINDOWS-PORT.md` | the Windows port's audit and packaging detail (§11.2) | +| `PACKAGING-GUIDE.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 | + +**There is no user guide.** The one that existed described the system before +per-node identity, named roots and the sealed wire, and was retired rather than +repaired — a document a reader cannot tell the sound parts of is worse than none. +Writing a new one starts here. ### 0.2 Reference labels @@ -2597,7 +2602,11 @@ account recovery, and the Windows port through packaging. ## 16. Concordance Code comments, tests and older documents cite sections of the documents this one -replaces. The mapping: +replaces. **Those documents are no longer in the tree** — they were removed on +2026-09-11, once their content was here and this table could resolve every +reference they left behind. `git log -- docs/` recovers any of them. + +Nothing needs editing to follow a reference: look the citation up here. | Cited as | Read | |---|---| @@ -2643,6 +2652,9 @@ replaces. The mapping: | `per-node-identity-v1.md` — identity keys per node | §3.2 | | `captcha.md` — registration gate | §7.7 | | `tmp-decisions.md` D1–D4 | §14.2 | +| `first-review.md`, `second-review.md`, `third-review.md` — any finding | §13, which defines every label. §13.1 is the first review, §13.3 the second, §13.4 the third | +| `USERGUIDE.md` — anything | it was wrong and is gone. §2 for the trust model, §3 for identity, §6.7 for the operator surface | +| `QUICKSTART.md` — anything | it was stale and is gone. `PACKAGING-GUIDE.md` installs; §6.7 lists the operator commands | | `devel-phases-next.md` structural decisions | §14.1 | | `cast-smart-tv.md` | §11.4 | diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md deleted file mode 100644 index f9ab79b..0000000 --- a/docs/QUICKSTART.md +++ /dev/null @@ -1,243 +0,0 @@ -# MeshBay — Quickstart - -MeshBay partage des fichiers entre utilisateurs d'un groupe via un réseau pair-à-pair. -Le hub (`meshbay.org`) gère les identités et les clés — il ne voit jamais vos fichiers. -Le node tourne sur votre machine et héberge vos fichiers. - ---- - -## Ce qu'il faut - -- Python 3.12+ -- Le dépôt MeshBay (en local) -- Un accès à `https://meshbay.org` - -```bash -cd ~/meshbay # le dépôt local (pas encore publié sur GitHub) -``` - -> **Si vous synchez le repo depuis une autre machine (rsync, scp)** : -> ne pas copier `.venv/` — il est lié à l'OS source et casse pip sur l'OS cible. -> Toujours recréer le venv avec `--clear` sur la machine cible. - -```bash -# Créer (ou recréer proprement) le venv -python3 -m venv .venv --clear -source .venv/bin/activate - -# Installer les packages — les dépendances (aioquic, watchdog, etc.) viennent automatiquement -pip install -e packages/meshbay-common -e packages/meshbay-node -e packages/meshbay-hub -``` - -Les dépendances déclarées dans les `pyproject.toml` sont installées automatiquement : - -| Package | Vient de | Rôle | -|---|---|---| -| `cryptography` | meshbay-common | crypto (Ed25519, ChaCha20, Argon2id) | -| `PyJWT` | meshbay-common | JWT EdDSA | -| `blake3`, `msgpack`, `zstandard` | meshbay-common | hashing, sérialisation, compression | -| `fastapi`, `uvicorn` | meshbay-node | API de contrôle loopback | -| `httpx` | meshbay-node | client hub | -| `watchdog` | meshbay-node | surveillance répertoire | -| `aioquic` | meshbay-node | transport QUIC (MNP v2) | -| `aioice` | meshbay-node | ICE/STUN NAT traversal | -| `websockets` | meshbay-node | notifications hub→node | - ---- - -## Étape 1 — Setup (alice crée le groupe et invite bob) - -Un seul script fait tout : créer les comptes, générer les clés depuis les mots de passe, -créer le groupe, distribuer la clé de chiffrement. - -```bash -python QE/demo-v1/setup_demo.py \ - --hub https://meshbay.org \ - --alice-user alice_demo --alice-pass "AliceDemo2026!" \ - --bob-user bob_demo --bob-pass "BobDemo2026!" -``` - -Sortie attendue : -``` -[1/6] Génération des clés d'alice depuis son mot de passe... - Ed25519 public: VyVUcjPXwJfGhzr44Cb5... -[2/6] Inscription d'alice sur le hub... - OK — user_id=9b50a8c2... -[3/6] Génération des clés de bob + inscription... - OK -[4/6] Alice se connecte au hub... - JWT reçu (424 chars) -[5/6] Alice crée le groupe 'demo-group'... - group_id=e358fb8b-5b3f-44... -[6/6] Génération et distribution de la clé de groupe (GEK)... - GEK → alice: 201 - GEK → bob: 201 - -✓ Setup terminé. - Creds: QE/demo-v1/creds.json -``` - -Les credentials sont sauvegardés dans `QE/demo-v1/creds.json` (clés privées incluses — -ce fichier ne doit pas être partagé ni versionné, il est dans `.gitignore`). - -**Pourquoi les clés sont dérivées du mot de passe ?** -La commande `derive_keys_from_password(username, password)` génère toujours les mêmes -clés Ed25519 et X25519 à partir des mêmes identifiants. Pas besoin de stocker ou -transporter un fichier de clés séparé — le mot de passe suffit pour retrouver les clés -sur n'importe quelle machine. - ---- - -## Étape 2 — Démarrer le node d'alice - -Le node indexe un répertoire et le rend accessible aux membres du groupe. -Il crée automatiquement `QE/demo-v1/shared/` avec un fichier exemple. - -```bash -# Terminal 1 — node d'alice (écoute en local) -python QE/demo-v1/run_node.py --host 127.0.0.1 --port 19001 -``` - -Sortie : -``` -=== Node d'alice — répertoire partagé : QE/demo-v1/shared === -Fichiers disponibles : - README.txt 93 octets - -1 fichier(s) indexé(s) - -✓ Node actif — MNP sur le port 19001 - Contrôle : meshbay-node status (API loopback, jeton requis) - -CTRL+C pour arrêter. -``` - -Vérification rapide dans un autre terminal : -```bash -meshbay-node status -# état du node, clés, groupes configurés, fichiers indexés -``` - -> **Le node n'expose aucune API HTTP publique.** Les endpoints `/`, `/index` et -> `/file/{id}` ont été supprimés en 0.2.0 (findings C1 et C6) : ils servaient l'index -> et les fichiers en dehors du handshake qui décide de ce qu'un pair a le droit de -> voir. Le port 19001 est le listener MNP, pas un serveur web. La seule surface HTTP -> est l'API de contrôle JSON sur la boucle locale, protégée par un jeton — utilisée -> par le CLI et la page Node du client desktop. - -**Ajouter vos propres fichiers :** -```bash -cp ~/Videos/ma_video.mp4 QE/demo-v1/shared/ -# Le node le détecte automatiquement (watchdog) -``` - ---- - -## Étape 3 — Bob télécharge un fichier - -Bob se connecte au hub, récupère sa clé chiffrée (GEK), la déchiffre localement, -puis télécharge et déchiffre le fichier depuis le node d'alice. - -```bash -# Terminal 2 — client de bob -python QE/demo-v1/download.py --node http://localhost:19001 -``` - -Sortie complète : -``` -[1/5] Bob se connecte au hub https://meshbay.org... - ✓ JWT reçu -[2/5] Bob récupère son bundle GEK depuis le hub... - ✓ Bundle chiffré reçu (hub ne peut pas le lire) -[3/5] Bob déchiffre la GEK localement (X25519)... - ✓ GEK récupérée (32 octets) -[4/5] Bob browse le node d'alice (http://localhost:19001)... - ✓ 1 fichier(s) dans 'demo-group': - [document] README.txt 93 octets -[5/5] Bob télécharge et déchiffre 'README.txt'... - chunk 0: 93o réseau=10ms decrypt=0.0ms ✓ - -✓ 'README.txt' sauvegardé dans QE/demo-v1/downloads/README.txt - Total : 93 octets en 1 chunk(s) -``` - -Télécharger un fichier spécifique : -```bash -python QE/demo-v1/download.py --node http://localhost:19001 --file ma_video.mp4 -``` - ---- - -## Étape 4 — Tester depuis une autre machine - -Si le node d'alice est sur une machine avec IP publique (ou port ouvert sur le routeur), -bob peut télécharger depuis n'importe où : - -```bash -# Alice — démarrer le node sur toutes les interfaces -python QE/demo-v1/run_node.py --host 0.0.0.0 --port 19001 - -# Bob — depuis une autre machine -python QE/demo-v1/download.py --node http://:19001 -``` - -> **NAT résidentiel :** si alice est derrière une box internet, il faut soit -> ouvrir le port 19001 dans les règles NAT de la box, soit utiliser un tunnel -> (cloudflared, ngrok). La traversée NAT automatique par STUN/ICE est prévue -> pour la v2 du protocole. - ---- - -## Ce qui se passe sous le capot - -``` -alice génère ses clés depuis son mot de passe (Argon2id) - ↓ -alice s'inscrit sur le hub (envoie les clés publiques seulement) - ↓ -alice génère une GEK (clé symétrique 256 bits) pour le groupe - ↓ -alice envoie à bob sa GEK chiffrée avec la clé publique X25519 de bob - ↓ -bob récupère son bundle GEK depuis le hub (opaque, hub ne peut pas lire) - ↓ -bob déchiffre la GEK localement avec sa clé privée X25519 - ↓ -bob télécharge les chunks chiffrés depuis le node d'alice - ↓ -bob déchiffre les chunks avec la GEK → fichier en clair -``` - -Le hub ne voit jamais la GEK ni les fichiers. Il stocke uniquement les clés -publiques et les bundles GEK chiffrés qu'il ne peut pas déchiffrer. - ---- - -## Scripts disponibles dans `QE/demo-v1/` - -| Script | Rôle | -|---|---| -| `setup_demo.py` | Créer comptes + groupe + distribuer GEK | -| `run_node.py` | Démarrer le node HTTP d'alice | -| `download.py` | Télécharger un fichier comme bob | - -Tous les paramètres ont des valeurs par défaut ; lancer avec `--help` pour les options. - ---- - -## Dépannage rapide - -**`ModuleNotFoundError: No module named 'meshbay_common'`** -→ Activer le venv : `source .venv/bin/activate` - -**`ERREUR: creds.json introuvable`** -→ Lancer d'abord `setup_demo.py` - -**`HTTPStatusError: 409 Conflict`** lors du setup -→ Les comptes existent déjà. Soit changer les noms (`--alice-user`), soit continuer normalement — le script gère le 409 et continue. - -**`Connection refused` sur le node** -→ Vérifier que `run_node.py` tourne dans un autre terminal. - -**`InvalidTag` lors du déchiffrement** -→ Le bundle GEK du hub ne correspond pas aux clés locales. Relancer `setup_demo.py` pour régénérer les bundles. diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md deleted file mode 100644 index c9febff..0000000 --- a/docs/USERGUIDE.md +++ /dev/null @@ -1,1184 +0,0 @@ -# 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. - ---- - -## Table of Contents - -1. [Architecture overview](#1-architecture-overview) -2. [Account management](#2-account-management) -3. [Groups](#3-groups) -4. [Setting up a node](#4-setting-up-a-node) -5. [Sharing files](#5-sharing-files) -6. [Accessing files](#6-accessing-files) -7. [Video streaming](#7-video-streaming) -8. [Security model](#8-security-model) -9. [Moderation and legal](#9-moderation-and-legal) -10. [Troubleshooting](#10-troubleshooting) -11. [API reference](#11-api-reference) - ---- - -## 1. Architecture Overview - -MeshBay has three components. Understanding which role each plays avoids a lot of confusion. - -``` -┌─────────────────────────────────────────────┐ -│ Mesh Hub (meshbay.org) │ -│ │ -│ • User accounts and public keys │ -│ • Group registry (name, membership) │ -│ • Encrypted GEK bundles (opaque blobs) │ -│ • JWT issuance and verification key │ -│ • Connection logs (legal compliance) │ -│ • No file content, no indexes, no GEKs │ -└──────────────┬──────────────────────────────┘ - │ HTTPS (identity + routing only) - │ - ┌──────────┴──────────┐ - │ │ -┌───▼────────┐ ┌──────▼───────┐ -│ Mesh Node │ │ Mesh Client │ -│ │ │ │ -│ Your files │ MNP │ Browser or │ -│ Your keys │◄───►│ Android app │ -│ TCP+TLS │ │ │ -└────────────┘ └──────────────┘ -``` - -**Mesh Hub** — a lightweight registrar. Its job is to vouch for identities, track group membership, and store encrypted GEK bundles. After login, clients talk directly to nodes. The hub is never in the data path for file transfers. - -**Mesh Node** — the program you run on your server or home machine. It watches a directory, maintains a group index, handles connections from clients, encrypts files at read time, and holds your private keys. You are the legal host of everything in your shared directory. - -**Mesh Client** — a web browser or Android app. It authenticates with the hub, fetches the encrypted GEK bundle, and connects directly to nodes for file browsing and download. - -**Protocol versioning:** MNP (Mesh Node Protocol) is currently at v0.1 over TCP+TLS 1.3. QUIC transport is planned for v2 with no protocol changes. Every wire message carries a `v` field; N-2 minor version backward compatibility is guaranteed. - ---- - -## 2. Account Management - -### Register - -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 :** - -**Mode CLI / native node** (`setup_demo.py`, `meshbay-node`) : -Les clés sont *dérivées* de votre username + password via Argon2id — pas besoin de -fichier de clés séparé. Même identifiants → mêmes clés sur n'importe quelle machine. -Implémenté dans `meshbay_common.keyderive.derive_keys_from_password()`. - -```python -from meshbay_common.keyderive import derive_keys_from_password -sk_ed, sk_x = derive_keys_from_password("alice", "MonMotDePasse!") -``` - -**Mode navigateur** (interface web) : -Le navigateur génère des clés aléatoires via WebCrypto, les chiffre avec une clé -dérivée du mot de passe (PBKDF2-SHA512), et envoie le bundle chiffré au hub. -À la prochaine connexion, le hub retourne le bundle et le navigateur le déchiffre -localement. Le hub stocke le bundle mais ne peut pas le lire. -Implémenté dans `static/keyderive.js`. - -``` -POST /v1/users/register -{ - "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 -``` -POST /v1/users/login -{"username": "yourname", "password": "yourpassword"} -→ { - "access_token": "JWT (Ed25519, 4 hour validity)", - "refresh_token": "opaque 256-bit token (30 days)", - "token_type": "bearer", - "expires_in": 14400, - } -``` - -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 \ - -H "Content-Type: application/json" \ - -d '{"username":"alice_test","password":"AliceTest2026!"}' -``` - -### Token refresh - -Access tokens are valid for 4 hours. **The web app does this for itself** — it -renews ten minutes before expiry, on returning to the tab, and on any 401, then -replays the request. Nobody should meet an expired token in the browser; what -follows is for other clients. - -The endpoint **rotates**: it revokes the refresh token you present and returns a -new one, so store the replacement. Presenting a revoked token is treated as -theft and revokes the whole family, which is a full sign-out. - -``` -POST /v1/users/token/refresh -{"refresh_token": "your-refresh-token"} -→ {"access_token": "new JWT", "refresh_token": "USE THIS NEXT TIME", - "token_type": "bearer", "expires_in": 14400} -``` - -```bash -curl -s -X POST https://meshbay.org/v1/users/token/refresh \ - -H "Content-Type: application/json" \ - -d '{"refresh_token":"YOUR_REFRESH_TOKEN"}' -``` - -Refresh tokens are valid for 30 days — that is the session — and can be -invalidated by the hub at once on account compromise. Revoking one means the -next renewal fails; an access token already issued keeps working for up to 4 -hours. That window is not the whole story: the hub reloads the account on every -request and refuses a suspended one immediately, and it pushes signed -revocations to nodes, so suspending an account or revoking a membership takes -effect at once regardless of the token's remaining life. - -### Access token structure - -The JWT payload contains: - -| Claim | Value | -|---|---| -| `iss` | Hub ID (`meshbay.org`) | -| `sub` | Your `user_id` (UUID4) | -| `hub_id` | `meshbay.org` | -| `jti` | UUID4 — unique per token, enables revocation, prevents replay | -| `groups` | The `group_id`s you are a member of, for node-side authorization | -| `scope` | `user` for a browser, `node` for a daemon | -| `iat` | Issued at (Unix timestamp) | -| `exp` | Expires at (Unix timestamp, 4 hours from issue — `[jwt] access_token_ttl`) | - -The token carries **no public key of yours**. It used to carry `pk_user`, and a node -recorded that key as the uploader of a file — which meant the party issuing tokens -decided who was allowed to delete it. The hub certifies *accounts*; keys are generated -on each node and pinned there (§4). - -Nodes verify this JWT locally using the hub's cached Ed25519 public key. No hub roundtrip is needed — verified at 884µs in testing. This means your files remain accessible even if the hub is temporarily unreachable. - -### Deleting your account - -**Settings → Delete account.** You re-enter your passphrase: a live session may be a -borrowed laptop or a tab left open, and this cannot be undone. A hub administrator can -also delete an account, from Administration → Users. - -What deletion does: - -- Releases the username — someone else may register it afterwards -- Clears the email and password hash, and drops the node linking key -- Removes group memberships, notifications and refresh tokens -- Refuses any access token still within its validity, immediately - -What deletion does **not** do: - -- **It does not touch anything on a node.** Your files stay where you uploaded them, and - so do the identity pinned in the node's roster and the keypair bundle it holds for you. - Nodes are other people's machines; the hub cannot command them. To be removed there, - ask the operator — `meshbay-node member unpin ` and deleting your files are - their commands to run (§4). -- **It does not erase the connection log.** IP records are kept for their legal retention - period and stay attributable: the username is copied onto those rows as the account is - deleted, so the log still says *who*, and does not answer `deleted-3f9a1c` for exactly - the records anyone would be asking about. Releasing the name for re-registration and - keeping it in the log are separate things. - -Deletion is refused while you still own a group. Hand the group over or delete it first — -otherwise its members would be stranded. The error names the groups blocking you. - -``` -DELETE /v1/users/me -Authorization: Bearer -{"auth_key": ""} -→ 200 {"status": "deleted", "username": "alice_test"} -→ 403 {"detail": "Passphrase does not match"} -→ 409 {"detail": "This account still owns groups: ..."} -``` - -Node registrations are removed as well, so a deleted operator's nodes stop being -announced. The daemons keep running and keep their data — again, the hub does not -command them. - ---- - -## 3. Groups - -Groups are the primary unit of organization. Every file on a node belongs to a group. - -### Create a group - -```bash -TOKEN="your-access-token" - -curl -s -X POST https://meshbay.org/v1/groups \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{"name": "my-group"}' -``` - -Response: -```json -{"group_id": "uuid", "name": "my-group"} -``` - -Save `group_id` — you will need it in your `node.toml` and when adding members. - -### The description - -Set it at creation with `"description"`, or later from the group's page — the owner -sees an **Edit description** link under the name. Members see it on their home page -and, for public groups, in Explore. - -``` -PATCH /v1/groups/{group_id} -Authorization: Bearer (the group's owner) -{"description": "host grenoble"} -→ 200 {"group_id": "...", "description": "host grenoble"} -``` - -An empty string clears it; anything past 512 characters is trimmed rather than -refused. The description is all this endpoint changes: the name, the visibility and -the join policy are the terms members joined on, and a private group that could -quietly become public is not the group they agreed to be in. Changing those needs a -decision about who gets told, so it is not a field on a form. - -### Public vs. private groups - -| | Public | Private | -|---|---|---| -| File index | Plaintext + Ed25519 signed | GEK-encrypted, members only | -| Content | TLS transport only (no application-layer encryption) | GEK-encrypted per chunk | -| Join | Open / approval-gated | By invitation only | -| GEK | Not applicable | Required | - -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 node operator issues a one-time code, from the server or from their browser: - -```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 -``` - -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. - -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. - -| | | -|---|---| -| 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 | - -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`). - -### Removing a member - -```bash -meshbay-node member revoke bob -meshbay-node gek-init # rotate: Bob still holds the old 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 - -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. - -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. - -### Notifications - -The bell in the top bar counts what you have not read. Clicking an entry takes you to -what it is about and dismisses it. - -- **Chat is one entry per group, not one per message.** A conversation that has been busy - all afternoon is a single line whose date moves to the last thing said and which turns - unread again each time. Opening the group clears it. -- **You are never notified of your own messages.** The node names the author when it - tells the hub a message was posted, and the hub skips them. -- **An invitation disappears once you have joined**, i.e. after you enter the pairing - code — not when you first look at it. -- **Muting a group works from anywhere.** The setting lives on the hub with your - membership, so a muted group creates no notification at all rather than hiding one - after the fact. It follows you to another browser. (It used to be a checkbox in the - browser's local storage that nothing read, so it did nothing.) -- **Clear all** empties the list in one action. - -``` -GET /v1/notifications → {"notifications": [{id, kind, group_id, title, link, read, created_at}], "unread": 3} -DELETE /v1/notifications/{id} → dismiss one — the row is deleted -POST /v1/notifications/{id}/read → the same thing, under the name older clients use -POST /v1/notifications/read-all → dismiss every one -DELETE /v1/notifications → delete them all -POST /v1/groups/{group_id}/mute {"muted": true} -``` - -`GET /v1/groups/mine` reports `muted` for each group, so the browser shows the checkbox -in the state the hub actually holds. - ---- - -## 4. Setting up a Node - -### Configuration file - -Full `~/.config/meshbay/node.toml` reference: - -```toml -[hub] -url = "https://meshbay.org" - -[auth] -username = "yourname" -password = "YourPassword123!" - -# Each group this node hosts gets its own [[groups]] block -[[groups]] -group_id = "uuid-of-your-group" -shared_dir = "/srv/meshbay/my-group" - -[[groups]] -group_id = "uuid-of-second-group" -shared_dir = "/srv/meshbay/second-group" - -[node] -# MNP listener port (must be internet-reachable) -listen_port = 19001 - -# Local web UI port (loopback only, not exposed externally) -ui_port = 18000 - -# Announce this address to the hub (auto-detected via STUN if not set) -# endpoint_hint = "203.0.113.42:19001" - -[keystore] -# "secure" — password prompt at each startup -# "lazy_file" — password read from ~/.config/meshbay/unlock.key (chmod 600) -# "service" — password read from MESHBAY_UNLOCK_KEY env var -unlock_mode = "secure" -path = "~/.config/meshbay/keystore.enc" - -[crypto] -# Argon2id parameters for keystore password derivation. -# Run `meshbay-node --calibrate-argon2` to tune for your hardware. -# Target: ~500ms on your machine. -argon2_iterations = 4 -argon2_memory_cost = 262144 # 256 MB -argon2_parallelism = 1 -``` - -### Hosting another of your groups - -A node can host several groups, each with its own directory and its own key. -Create the group in the web app first, then, on the node: - -```bash -meshbay-node group add grenet --dir ~/grenet-share -# grenet (480d553f) added to /home/cbesson/.config/meshbay/node.toml -# shared_dir /home/cbesson/grenet-share - -# restart the daemon, then: -meshbay-node gek-init --group grenet -``` - -`group add` looks the name up among your groups on the hub, appends a -`[[groups]]` block to your `node.toml` — comments and all, it is appended, not -rewritten — and creates the directory. The daemon reads its config at startup, so -it needs a restart before the group exists for it; `gek-init` then generates that -group's key. - -Three things follow from the design, and are worth being explicit about: - -- **Each group's key is its own.** Members of one group cannot read another's - files, and admitting someone to one says nothing about the other. That is why - `gek-init` is per group. -- **Pairing is not.** `meshbay-node operator pair` pairs a *browser* with the - *node*: one paired browser can invite to, and delete files in, every group the - node hosts. It takes no `--group`. -- **Members are per group.** `meshbay-node member invite alice --group grenet` - admits alice to that group only. The roster keeps one row per group. - -`meshbay-node status` prints what the node hosts, with each directory — the -quickest way to see whether a group made in the browser is attached here yet. - -### Environment variables (alternative to node.toml) - -| Variable | Equivalent config | -|---|---| -| `MESHBAY_HUB_URL` | `[hub] url` | -| `MESHBAY_USERNAME` | `[auth] username` | -| `MESHBAY_PASSWORD` | `[auth] password` | -| `MESHBAY_UNLOCK_KEY` | keystore unlock key (for `service` mode) | -| `MESHBAY_LISTEN_PORT` | `[node] listen_port` | - -### Keystore unlock modes - -The keystore is an Argon2id-derived AES-256-GCM encrypted file holding your Ed25519 and X25519 private keys plus GEK copies. - -**secure (default):** prompts for a password at startup. Suitable for interactive use. The password is not stored anywhere. - -**lazy_file:** reads the password from `~/.config/meshbay/unlock.key` (must be `chmod 600`). Use on a physically secure home server where you want unattended restarts. - -```bash -echo -n "YourKeystorePassword" > ~/.config/meshbay/unlock.key -chmod 600 ~/.config/meshbay/unlock.key -``` - -**service:** reads the unlock key from the `MESHBAY_UNLOCK_KEY` environment variable. Standard practice for systemd deployments: - -```ini -# /etc/systemd/system/meshbay-node.service -[Unit] -Description=MeshBay Node -After=network.target - -[Service] -User=meshbay -EnvironmentFile=/etc/meshbay/unlock.env # chmod 600, owned by meshbay -ExecStart=/usr/bin/meshbay-node --config /etc/meshbay/node.toml -Restart=on-failure - -[Install] -WantedBy=multi-user.target -``` - -```bash -# /etc/meshbay/unlock.env (chmod 600, owned by meshbay user) -MESHBAY_UNLOCK_KEY=YourKeystorePassword -``` - -### Argon2id calibration - -The keystore password derivation is intentionally slow. Tune it to your hardware: - -```bash -meshbay-node --calibrate-argon2 -``` - -This prints the derivation time for several parameter combinations. Choose the set that gives ~500ms. The default (iterations=4, memory=256MB) is calibrated for a modern home server. - -### Hardware sizing (upload bandwidth is the constraint) - -| Scenario | Simultaneous users | Upload needed | RAM | -|---|---|---|---| -| Files + chat, no streaming | 10 | 20–50 Mbps | 512 MB | -| 1080p streaming, 5–6 streams | 10 | 50–80 Mbps | 1 GB | -| Mixed, light streaming | 50 | 200–300 Mbps | 2 GB | -| Heavy streaming | 50 | 400 Mbps | 2–4 GB | - -A standard home fiber line (100–500 Mbps symmetric) handles 10–30 concurrent users. Beyond that, a dedicated server is needed. - ---- - -## 5. Sharing Files - -### How indexing works - -The node watches `shared_dir` for file changes using filesystem events (`watchdog` library). When a file is added, modified, or removed: - -1. The node computes `blake3(file)` as the file identifier -2. It builds or updates a Mesh Group Index entry for that file -3. The index entry is serialized as msgpack, compressed with zstd, then encrypted with the GEK (for private groups) or signed with the node's Ed25519 key (for public groups) -4. Connected members receive an index delta push; new connections receive the full index - -### Index entry structure - -```python -{ - "version": 1, - "id": "", # file identity and chunk key input - "name": "filename.mkv", - "path": "Movies/2024/", # relative path within shared_dir - "size": 4294967296, # bytes - "type": "video", # video | audio | image | document | archive | other - "duration": 7245, # seconds (media files only) - "thumb_hash": "", # thumbnail, also GEK-encrypted - "added_at": 1720000000 # Unix timestamp -} -``` - -### Supported file types - -The node detects type by file extension and MIME sniffing: - -| Type | Extensions | -|---|---| -| `video` | mp4, mkv, avi, mov, webm | -| `audio` | mp3, flac, ogg, opus, m4a | -| `image` | jpg, jpeg, png, gif, webp, avif | -| `document` | pdf, txt, md, epub, doc, docx, odt | -| `archive` | zip, tar, gz, bz2, xz, 7z | -| `other` | everything else | - -### Where uploaded files land - -Everything a member sends arrives in **`shared_dir/uploads/`** — both files uploaded from -the Files panel and attachments sent in the chat. One visible directory, so an operator can -look at what was sent, move it, or empty it without hunting through the tree. - -- Filenames are checked against a conservative allowlist and nothing is ever overwritten: - a colliding name gets a suffix, and the sender is told the name it was stored under. -- Chat thumbnails are scaled by the browser from the file itself. The node writes no - derived images, so nothing accumulates beside your files. -- Uploads are attributed to the identity the node pinned for that member, and that is what - decides who may delete the file later — not anything the hub says. - -### Selecting files, and where transfers live - -The Files panel has a **Select** button. Turning it on puts a checkbox on every -row — files and folders — and the **⋮ Actions** button next to it acts on what is -ticked: download, play, view, download folders as a zip, delete. There is no -per-row menu: several transfers at once is the normal case, and starting them one -context menu at a time was the thing that made it awkward. - -Selection is remembered as you walk into folders, so you can tick something in -one and something else in another before choosing an action. - -**Where downloads are written** is a setting, under Settings → Downloads: - -- **Save automatically** (the default) writes into a folder you pick once, with - no dialog. Downloading twenty files puts twenty files there. A name already in - use gets a suffix — `clip (2).mp4` — rather than replacing what is there. -- **Ask every time** opens a Save As dialog per file, which is right for one file - and wrong for a selection of twenty. - -With no folder chosen, automatic still does not put a dialog in your way, and it -still does not hold the file in memory: a service worker hands the browser a -stream, which it writes to its own download folder as the bytes arrive. That is -how this works in Firefox and Safari, which have no way to open a file for writing -from a page. If even that is unavailable, a download under 512 MB is collected in -memory and handed over; a larger one asks where to put it, because a tab does not -survive a multi-gigabyte blob. - -**What has been exercised**, as of 2026-08-15, so the next person knows which of -this is measured and which is designed: - -| Path | Browser | State | -|---|---|---| -| Streamed into a granted folder | Chrome | works | -| Streamed by the service worker | Firefox | works — 180 MB, written to disk | -| Collected in memory (no folder, no worker) | any | works, bounded at 512 MB | -| Save As for a download over 512 MB | Chrome | works | -| Multi-gigabyte download, any path | — | designed for, not yet measured | - -The 180 MB run is the one that matters most, because the service worker is the -only way Firefox writes a download to disk rather than building it in a tab. It -has not been tried at the scale it exists for. - -A finished download offers **Open** in the transfers widget when it went into a -folder you granted: the file is handed to a new tab and the browser decides what -to do with it. That is the whole of what a web page can do here — it cannot start -a desktop application, and it cannot show you a file manager. No browser offers an -API for either, deliberately. - -A web page cannot be given a filesystem path, and cannot read one either: there -is no `~/Downloads` to configure, on any operating system, and nothing changes -here on Windows for the same reason. What a browser grants is access to a folder -the user picked in a dialog, and MeshBay only ever writes inside it. That grant -is remembered, but the browser may ask you to confirm it once per session. - -Firefox and Safari have no File System Access API, so no folder can be granted: -downloads go to the browser's own download folder, and Settings says so instead -of offering a choice that would do nothing. - -**Transfers run outside the page.** They are listed in the widget next to the -bell, with a progress bar, the current rate, and a cancel button each: - -- Leaving the group, or the group page, does not stop them. The connection stays - open until the last transfer using it is finished. -- **Signing out cancels them all** — they are moving data on a token that is about - to stop being yours. -- Cancelling stops the work, not just the display; a partly written file is left - where you told the browser to put it. -- Rates are measured over the last few seconds, so a stalled transfer reads as - stalled rather than reporting the average it once managed. - -### Downloading a folder as a zip - -Any member can take a whole folder: **⋮ → Download as zip** on the folder's row. -The archive is built in the browser as the files arrive and written straight to -disk, so it costs disk space and only a few megabytes of memory. - -- **A folder has to be 512 MB or smaller.** Larger than that and the button - refuses, naming the folder's size — take a subfolder at a time, or the files - individually. This is a deliberate cap, not a technical one: the writer would - happily stream a hundred gigabytes. Selecting several folders at once applies - it to each of them separately, so one oversized folder does not stop the rest. -- Nothing is compressed. Group content is video, images and archives — already - compressed — so deflating would spend CPU on every byte to save nothing, in the - same thread that is decrypting. -- The archive opens as the folder you asked for: a zip of `Holidays/2026` unpacks - as `2026/…`, not as a chain of empty parents. -- Files over 4 GiB, and archives over 4 GiB, use zip64. Anything current reads - them; a tool from before 2003 may not. -- **Firefox and Safari cannot write a download straight to disk** (no File System - Access API). There, the archive has to be assembled in memory first, and the - browser says so, with the size, before starting. Use Chrome or Edge for a large - one. - -### Removing a member - -The group's owner can remove someone from the Members tab. It does two things, in -the order that fails safe: - -1. **The node stops serving them the group key** — an operator-signed request, so - it works only from a paired browser (§3). This is the half that matters. -2. **The hub drops their membership**, which is what stops them reaching the node - through signaling at all. - -What it does **not** do: - -- It does not delete their account. Their other groups, their files and their - identity are untouched — one group's owner cannot erase someone from the hub. -- It does not make the node forget them. The pinned key stays, so they can be - admitted again without a new pairing code; `meshbay-node member unpin` forgets. -- It does not take back the key they already hold. Anyone who has connected has - unwrapped the current GEK, and no protocol reaches into their browser to remove - it. Rotate it with `meshbay-node gek-init --group ` if that matters — - members still in the group pick the new one up on their next connection. - -Removal is per group: on a node hosting several, someone removed from one keeps -the others. - -### Deleting a directory - -**⋮ → Delete folder**, for the node operator, from a paired browser (§3). The -directory must be **empty** — nothing here is recursive, and a folder with -anything in it is refused before a signature is even asked for. Delete the files -first, where you can see what you are losing. - -Like every privileged action on a node, it is signed with the key the node pinned -for that browser and refused otherwise: hub membership, or an admin role on the -hub, grants nothing here. - -### Creating a directory - -Any active member can create a directory from the Files panel (**New folder**). It is -created relative to the folder you are looking at, under `shared_dir`, and the same name -rules apply. Paths that try to leave the shared root are refused. - -### Files are stored in plaintext on disk - -The node holds your files in plaintext. Encryption happens at read time — the node encrypts each 1 MB chunk using a per-chunk key derived from the GEK before sending it over the wire. This means: - -- Disk-level encryption (LUKS, etc.) is your responsibility if you need at-rest protection -- Backups of the shared directory are plaintext -- Node compromise exposes all files in plaintext - ---- - -## 6. Accessing Files - -**There is no HTTP file API.** Files are requested over MNP — the node's authenticated -message channel, carried by WebRTC DataChannel or QUIC — and nothing on the node answers -an unauthenticated request. The `GET /index`, `GET /file/{id}` and `GET /stream/...` -endpoints documented before 0.2.0 were removed (findings C1 and C6): they served the index -and file bytes to anyone holding a token, outside the handshake that decides what a peer -is allowed to see. Port 19001 is the MNP listener, not a web server. - -The node's only HTTP surface is its admin UI, bound to loopback and requiring a token -(§4). It is for the operator, on the machine, over SSH. - -### Browse the index - -After the handshake, ask for the index: - -``` -→ {"type": "index_sync", "v": "0.1"} -← {"type": "index_sync", "entries": [{"id": "", "name": "...", "size": 1234, - "type": "video", "path": "uploads/"}, ...]} -``` - -For a private group the index itself is encrypted with the GEK, so a peer that never -proved possession of the key is served nothing to read. - -### Download a file, chunk by chunk - -``` -→ {"type": "file_req", "v": "0.1", "file_id": "", "chunk_index": 0} -← {"type": "file_chunk", "file_id": ..., "chunk_index": 0, - "nonce": , "ct": , "plaintext_size": 1048576} -``` - -Chunks are 1 MB. Chunk 0 is the first megabyte; for a 5 MB file, request 0–4. - -**Per-chunk key derivation** — each chunk has an independent key derived from the GEK and -the chunk's position, so a leaked chunk key opens exactly one chunk of one file, and a -player can seek without decrypting from the start: - -```python -chunk_key = HKDF( - algorithm=hashes.SHA256(), length=32, salt=None, - info=b"file:" + file_hash_bytes + b":chunk:" + chunk_index.to_bytes(4, "big"), -).derive(gek) - -plaintext = ChaCha20Poly1305(chunk_key).decrypt(nonce, ciphertext, None) -``` - -The browser client derives the same key the same way but uses **AES-GCM**: WebCrypto has -no ChaCha20-Poly1305. The node picks the cipher from what the peer negotiated at -handshake; the key schedule above is identical in both. - -### Identifying the node - -The node's `pk_node` (Ed25519) comes from the hub — `GET /v1/nodes/{node_id}` — and the -client checks the handshake signature against it. A node that cannot sign the transcript -with the key the hub published for it is refused, so hub signaling can introduce you to a -node but cannot substitute one. - ---- - -## 7. Video Streaming - -Video is streamed over the same MNP channel and played through Media Source Extensions. -The node remuxes to fragmented MP4 on the fly — the container changes, the video and audio -streams are copied untouched — and encrypts each segment exactly like a file chunk, so a -standard `