1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
|
# 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)
python3 -m venv .venv && source .venv/bin/activate
```
> **Important — ne pas copier `.venv/` entre machines d'OS différents.**
> Le venv est spécifique à l'OS. Si vous avez cloné/copié le repo depuis une machine Fedora
> vers Ubuntu (ou inversement), le venv doit être recréé avec `--clear` :
```bash
python3 -m venv .venv --clear # ← --clear force la recréation propre
source .venv/bin/activate
pip install -e packages/meshbay-common -e packages/meshbay-node httpx blake3 uvicorn
```
Sans `--clear`, pip peut échouer avec `FileNotFoundError` dans `certifi` parce qu'il
cherche les certificats CA à un chemin valide sur l'OS d'origine mais absent sur l'OS cible.
---
## É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 sur http://127.0.0.1:19001
Info: http://localhost:19001/
Index: http://localhost:19001/index
CTRL+C pour arrêter.
```
Vérification rapide dans un autre terminal :
```bash
curl http://localhost:19001/
# {"node_version":"0.1.0","file_count":1,"group_name":"demo-group",...}
curl http://localhost:19001/index
# {"entries":[{"name":"README.txt","size":93,...}],...}
```
**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.
|