summaryrefslogtreecommitdiffstats
path: root/docs/QUICKSTART.md
diff options
context:
space:
mode:
authorChristophe Besson <cbesson@gmail.com>2026-09-11 00:19:06 +0200
committerChristophe Besson <cbesson@gmail.com>2026-09-11 00:19:06 +0200
commitf059cb118c556d1f0279350507f74b8a47d5a98a (patch)
tree9a97762a844038a06134b4b7dcead1758477dfc1 /docs/QUICKSTART.md
parentb045ba0010d69360b6a0265eb7c73a07900fe328 (diff)
downloadmeshbay-f059cb118c556d1f0279350507f74b8a47d5a98a.tar.gz
docs: remove the documents MESHBAY_DESIGN.md replaces
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YVoHVCcfBqud6ZjG4db3y7
Diffstat (limited to 'docs/QUICKSTART.md')
-rw-r--r--docs/QUICKSTART.md243
1 files changed, 0 insertions, 243 deletions
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://<IP-D-ALICE>: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.