# 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 | HTTP API + UI locale | | `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 Admin UI : meshbay-node ui (boucle locale, 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'UI d'administration, sur la boucle locale et protégée par un jeton. **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.