diff options
Diffstat (limited to 'docs/QUICKSTART.md')
| -rw-r--r-- | docs/QUICKSTART.md | 243 |
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. |