path: root/docs/meshbay-draft-v1-fr.md

# MeshBay — Brouillon d'Architecture v1

> Statut : brouillon préliminaire — de nombreux points restent ouverts, marqués [TBD]

---

## 1. Présentation du projet

MeshBay est une plateforme décentralisée, pair-à-pair, pour le partage de fichiers, le streaming vidéo et la messagerie de groupe. Elle combine une fédération d'identité (via les Mesh Hubs) avec un échange de données véritablement pair-à-pair (via les Mesh Nodes), dans l'objectif d'être résiliente, résistante à la censure et accessible aux utilisateurs.

**Principes fondamentaux :**
- Les données ne transitent jamais par un serveur central — seuls l'identité et le routage le font
- Chiffrement de bout en bout pour tout contenu privé (fichiers, index, messages)
- L'opérateur du node est l'hébergeur légal et porte l'entière responsabilité de son contenu
- Le hub est un registrar léger, pas un hébergeur ni un indexeur de contenu
- Open source, auto-hébergeable à chaque niveau

**Domaine :** meshbay.org

---

## 2. Terminologie

| Terme | Rôle |
|---|---|
| **Mesh Hub** | Serveur d'autorité d'identité et registre de groupes |
| **Mesh Node** | Programme local sur la machine de l'utilisateur hébergeur |
| **Mesh Client** | Navigateur web ou application Android (utilisateur final) |
| **Mesh Relay** | Relais TURN de secours opéré par la communauté |
| **MNP** | Mesh Node Protocol — protocole P2P entre nodes et clients |
| **MHP** | Mesh Bay Hub Protocol — protocole de fédération inter-hubs |
| **GEK** | Group Encryption Key — clé symétrique de chiffrement du groupe |
| **Mesh Directory** | Registre public des groupes (niveau hub) |
| **Mesh Group Index** | Listing chiffré des fichiers d'un groupe (niveau node) |

---

## 3. Composants du système

### 3.1 Mesh Hub

Serveur léger agissant comme un registrar. Il est intentionnellement maintenu minimal pour réduire l'exposition légale et la charge opérationnelle.

**Ce que le hub stocke :**
- Comptes utilisateurs : nom d'utilisateur, email haché, `PK_user` (empreinte de clé publique), ID du hub, statut
- Registre de groupes : nom, `PK_group`, adresse du node hébergeur, visibilité, liste des membres avec bundles GEK chiffrés
- Listes de révocation (utilisateurs et groupes)
- Hubs pairs enregistrés (liste d'autorisation explicite — pas de découverte automatique)

**Ce que le hub ne stocke jamais :**
- Contenu de fichiers ou métadonnées
- Index de groupes privés
- Contenu de messages
- Adresses IP des nodes (gérées par le service de signaling éphémère)

**Interactions hub — quand est-il sollicité ?**

| Événement | Charge hub | Fréquence |
|---|---|---|
| Création de compte | Hash du credential, stockage PK | Une fois |
| Login | Vérification credentials, émission JWT signé | Par session (~30j de validité) |
| Création de groupe | Enregistrement nom, PK_group, node | Une fois par groupe |
| Ajout/suppression membre | Stockage/suppression bundle GEK chiffré | Sur action admin |
| Discovery d'un groupe | Retour adresse node + PK_node + bundle GEK | Par accès initial |
| Signaling NAT | Relais de quelques messages WebSocket (<1 Ko) | Par nouvelle connexion P2P |
| Recherche publique | Délégation de requête aux nodes à la demande | Sur demande |
| Sync fédération MHP | Échange mises à jour du Mesh Directory | Background, périodique |
| Révocation | Émission token de révocation signé | Rare |

**Le hub n'est jamais dans le chemin des données après l'établissement de la connexion initiale.**

**Le JWT comme passeport hors-ligne :**
Le hub émet un JWT signé avec sa clé privée Ed25519. Les nodes vérifient ce JWT localement en utilisant la clé publique connue du hub — aucun aller-retour hub requis par requête. Validité JWT : ~30 jours.

**Stack technique :**
- Langage : Python
- Framework : FastAPI + Uvicorn
- Base de données : PostgreSQL + SQLAlchemy + Alembic
- Déploiement : derrière un reverse proxy Apache (ProxyPass)
- Authentification : système propre (JWT signé Ed25519, sans dépendance OAuth)

**Création de compte :** [TBD] — email seul dans un premier temps, numéro de téléphone associable par la suite. Via l'app Android, les deux collectés par défaut. Comptes fusionnables.

### 3.2 Mesh Node

Programme local tournant sur la machine de l'utilisateur hébergeur. Le node est l'hébergeur effectif de tout le contenu.

**Responsabilités :**
- Surveiller et indexer les répertoires partagés (Mesh Group Index)
- Servir fichiers et flux vidéo aux membres du groupe
- Gérer toutes les clés cryptographiques localement (keystore, protégé par mot de passe)
- Gérer les connexions P2P et la traversée NAT
- Exécuter le protocole MNP
- Héberger le sandbox de modules Python
- Servir l'interface web locale (localhost)
- [Futur] Recevoir et redistribuer une vidéo éphémère depuis mobile

**Plateforme :** Linux en priorité, cross-platform dès le départ (Windows/macOS). Python assure la portabilité.

**Stack technique :**
- Langage : Python (principal), extensions Rust uniquement si strictement nécessaire pour les parties critiques en performance
- QUIC : `aioquic`
- ICE/STUN : `aioice`
- WebRTC (futur) : `aiortc`
- Crypto : `cryptography` (PyCA, backed OpenSSL, accélération matérielle)
- Sérialisation : `msgpack`
- Compression : `zstandard` (zstd)
- Surveillance fichiers : `watchdog`
- BDD locale : SQLite
- Interface web locale : servie par le node sur localhost (port [TBD])

**Appairage node avec mobile :** QR code depuis l'interface web locale [futur].

### 3.3 Mesh Client

Navigateur web ou application Android. Consomme le contenu depuis le node ; gère le compte via le hub.

**Opérations côté hub :**
- Création de compte et login
- Recherche et découverte de groupes publics
- Gestion de l'appartenance aux groupes

**Opérations côté node (P2P direct) :**
- Navigation dans les fichiers (Mesh Group Index)
- Lecture du fil de messages (avec pièces jointes, façon Signal)
- Téléchargement de fichiers
- Streaming vidéo (VOD)
- [Futur] Flux vidéo éphémère

**Modes client** [à concevoir] :
- Mode explorateur : navigation dans les fichiers d'un groupe
- Mode flux : fil de messages avec pièces jointes
- Articulation UI hub/node à définir

### 3.4 Mesh Relay

Relais TURN opéré par la communauté. Utilisé uniquement en dernier recours quand toutes les méthodes de connexion P2P échouent. Le trafic est toujours chiffré E2E — le relais ne voit que des paquets QUIC opaques et ne peut pas lire le contenu.

Non opéré par meshbay.org. Un protocole d'enregistrement des relais auprès des hubs est [TBD].

---

## 4. Modèle de groupe

Les groupes sont l'unité organisationnelle centrale.

| Paramètre | Options |
|---|---|
| Visibilité | Public / Privé |
| Politique d'adhésion | Libre / Sur demande / Sur invitation uniquement |
| Admin | L'opérateur du node hébergeur (hébergeur légal) |

Un groupe public fonctionne comme un forum thématique : fichiers partagés, fil de discussion, liste de membres. Il peut être à entrée libre, sur demande ou sur invitation, indépendamment de sa visibilité publique.

Le contenu d'un groupe privé (fichiers, index, messages) est toujours chiffré E2E avec la GEK. Seuls les membres possédant la GEK peuvent déchiffrer quoi que ce soit.

**Adressage des groupes** [TBD] :
```
meshbay.org/u/username/groupname    — groupe public via hub
meshbay.org/g/groupname             — groupe public direct
group://<PK_group_fingerprint>@<node_addr>   — accès direct sans hub
```

---

## 5. Architecture cryptographique

### 5.1 Hiérarchie de clés

```
Clé d'identité utilisateur   Ed25519     Signature, authentification
Clé d'échange utilisateur    X25519      Accord de clé
Clé d'identité groupe        Ed25519     Signature métadonnées groupe (tenue par le node admin)
Clé de chiffrement groupe    ChaCha20    Chiffrement contenu et index (symétrique, 256 bits)
Clés de session              X25519/HKDF Perfect forward secrecy par connexion P2P
```

Toutes les clés privées sont stockées exclusivement sur le node (ou l'appareil client), dans un keystore local protégé par mot de passe. Le hub ne voit jamais aucune clé privée.

### 5.2 Gestion de la GEK

**Création de groupe :**
1. Le node admin génère la GEK (ChaCha20-Poly1305, 256 bits, CSPRNG)
2. La GEK est chiffrée pour chaque membre via accord de clé X25519 + HKDF
3. Les bundles GEK chiffrés sont stockés sur le hub (ou sur le node — [TBD])

**Ajout de membre :**
- GEK chiffrée avec la `PK_user` du nouveau membre et distribuée

**Révocation de membre :**
- Le node admin génère une nouvelle GEK
- Re-chiffrement pour tous les membres restants
- Les nouveaux contenus sont chiffrés avec la nouvelle GEK
- L'ancien membre conserve la capacité de déchiffrer le contenu précédemment reçu (compromis acceptable — re-chiffrement complet non prévu)

### 5.3 Chiffrement à la volée pour le transfert de fichiers

Les fichiers sont stockés en clair sur le disque de l'hébergeur. Le node chiffre à la lecture avant transmission.

```
Disque (clair) → [Node] → compression zstd → chiffrement GEK (par chunk) → session QUIC → [Client] → déchiffrement QUIC → déchiffrement GEK → clair
```

**Stratégie de chunking :**
- Taille de chunk : 1 Mo (amortit l'overhead AEAD, permet le seek)
- Dérivation de clé par chunk :
  `chunk_key = HKDF(GEK, "file:" || blake3(fichier) || "chunk:" || index)`
- Chaque chunk déchiffrable indépendamment (permet le seek vidéo)
- Compresser avant chiffrer (la compression zstd est inutile après chiffrement)

**Authentification des chunks :**
Chaque chunk (ou lot) est signé avec la clé Ed25519 du node. Le client vérifie avant déchiffrement. Prévient l'injection de données par un relais compromis.

### 5.4 Sécurité du transport

- Protocole principal : **QUIC** (TLS 1.3 intégré, UDP, multiplexé)
- Clés de session par connexion via X25519 ECDH + HKDF
- La couche QUIC est indépendante de la couche applicative GEK — deux couches de chiffrement indépendantes

### 5.5 Chiffrement du chat

La messagerie de groupe utilise l'algorithme **Double Ratchet** (comme Signal) :
- Forward secrecy et break-in recovery par message
- Chaque message chiffré indépendamment
- Implémentation : bibliothèque Python ou Rust existante [TBD]

---

## 6. Réseau et connectivité

### 6.1 Traversée NAT — ordre des tentatives

```
1. IPv6 disponible des deux côtés          → connexion directe, aucun problème NAT
2. UPnP / NAT-PMP sur le routeur           → le node ouvre un port automatiquement
3. ICE + STUN / UDP hole punching           → fonctionne pour ~80-85% des cas
4. Mesh Relay (fallback TURN)              → opéré par la communauté, trafic E2E chiffré
```

**Signaling** (étapes 3/4) : coordonné via WebSocket du hub, <1 Ko par tentative, sans état après connexion établie.

**Couverture étape 4 :** ~15-20% des connexions (NAT symétrique des deux côtés, CGNAT). Le relais ne voit que des paquets QUIC chiffrés.

### 6.2 MNP — Mesh Node Protocol

Protocole applicatif sur QUIC. Blocs définis :

- **Handshake** : échange de clés, vérification d'appartenance au groupe (présentation JWT)
- **Sync d'index** : delta de Mesh Group Index chiffré à la connexion
- **Transfert de fichiers** : requête/réponse par chunk avec vérification de hash
- **Streaming VOD** : segments HLS/DASH, chiffrés par segment avec des clés dérivées de la GEK
- **Messagerie** : messages Double Ratchet encapsulés dans des frames MNP
- **[Futur] Flux éphémère** : type `ephemeral_stream` avec métadonnées TTL

### 6.3 Diffusion de contenu public

Les fichiers publics sont identifiés par leur hash `blake3`. Plusieurs nodes peuvent servir le même fichier :

1. Le Node A possède le fichier public X (hash H)
2. Tout node qui obtient X et choisit de le mirrorer s'enregistre auprès du hub : "je sers le hash H"
3. Le hub maintient : `{ blake3_hash → [node_A, node_B, ...] }`
4. Un client demande X → le hub retourne la liste des sources → le client récupère des chunks en parallèle depuis plusieurs nodes

**Transport contenu public :** TLS uniquement (pas de GEK). Contenu signé avec la clé Ed25519 du node original pour vérification d'authenticité par les clients, même servi depuis un miroir. Possibilité laissée ouverte d'ajouter une GEK pour des groupes "publics réservés aux inscrits" dans une révision future.

---

## 7. Index

### 7.1 Mesh Directory (niveau hub)

Registre public des groupes. Échangé entre hubs via MHP.

Format : msgpack, signé par la clé Ed25519 du hub.

Champs par entrée : nom de groupe, `PK_group`, hub hébergeur, description, tags de type de contenu, politique d'adhésion.

### 7.2 Mesh Group Index (niveau node)

Listing des fichiers d'un groupe. Généré et maintenu par le node hébergeur.

Format : msgpack → compressé zstd → chiffré GEK (groupes privés) ou signé en clair (groupes publics).

Structure d'une entrée :
```python
{
  "id":        "<blake3_hash>",
  "name":      "fichier.mkv",
  "path":      "Films/2024/",         # relatif au répertoire partagé
  "size":      4294967296,
  "type":      "video",               # video | audio | image | document | archive | other
  "duration":  7245,                  # secondes, pour les médias
  "thumb_hash":"<blake3>",            # hash de la miniature (miniature aussi chiffrée GEK)
  "added_at":  1720000000
}
```

**Mises à jour delta :** chaque mise à jour porte `{base_version, additions, deletions}` — pas de re-chiffrement complet à chaque changement.

**Transit :** les nodes poussent les deltas d'index aux membres connectés sur modification. Les membres tirent l'index complet à la première connexion. Le hub ne stocke aucun contenu d'index — seulement l'adresse du node pour le routage.

### 7.3 Recherche

**Groupes privés :** la recherche est entièrement locale sur l'appareil du client. Le client maintient un cache local chiffré de tous les index des groupes dont il est membre. Aucun appel réseau, aucune implication du hub, résultats instantanés.

**Groupes publics :** le client interroge les nodes directement à la demande. Le hub fournit le routage (quel node héberge quel groupe) mais n'effectue aucune recherche de contenu lui-même.

**Interface web du hub — recherche :** délègue la requête aux nodes concernés à la demande. Le hub ne stocke rien de cette interaction. Micro-cache en mémoire des résultats : **TTL 60 secondes maximum, RAM uniquement, jamais écrit sur disque, contenu public uniquement.** Ceci relève du caching technique (DSA EU Article 13) et ne constitue pas de l'indexation.

---

## 8. Fédération inter-hubs (MHP)

### 8.1 Hiérarchie des hubs

```
Root Hub (meshbay.org)
    ├── Full Hub (auto-hébergé, CA déléguée)
    │     └── émet des credentials utilisateurs, gère ses propres groupes
    │     └── peut se fédérer avec d'autres Full Hubs via MHP
    └── Mirror Hub
          └── héberge uniquement le Mesh Directory public (pas de comptes utilisateurs)
```

Un Full Hub reçoit un certificat signé par le Root Hub (ou un Full Hub parent) prouvant son autorité. Les clients vérifient la chaîne. Un Mirror Hub ne peut que répliquer des données publiques.

### 8.2 Principes de conception MHP

- Sélection explicite des pairs : chaque hub maintient une liste d'autorisation de hubs de confiance
- Pas de découverte automatique de hubs
- Données échangées : Mesh Directory (groupes publics), listes de révocation, credentials utilisateurs cross-hub
- Authentification cross-hub : l'utilisateur du Hub A présente un JWT signé par Hub A ; Hub B vérifie en utilisant la clé publique de Hub A (récupérée une fois à la première interaction, mise en cache)

### 8.3 Accès client cross-hub

Client de Hub A accédant à un groupe sur Hub B :
1. Le Mesh Directory de Hub A ou un lien direct amène le client vers Hub B
2. Le client présente son JWT Hub A directement à Hub B
3. Hub B vérifie la signature JWT avec la clé publique de Hub A
4. Hub B émet un token local de courte durée pour cette session
5. Le client rejoint le node normalement

---

## 9. Modération

### 9.1 Contenu public

```
Signalement #1  → suspension automatique de l'accès public au contenu
                → notification à l'opérateur du node
Une republication autorisée
Signalement #2  → escalade vers les modérateurs du hub
Confirmé        → groupe révoqué sur le hub local
                → révocation propagée aux hubs fédérés via MHP
```

Mécanisme : hash blake3 du contenu ajouté à la liste de blocage du hub. Le node reçoit un avis de révocation signé et coupe l'accès public.

### 9.2 CSAM

Hash matching contre la base de données NCMEC/IWF sur tout contenu public lors de l'enregistrement. La participation démontre la bonne foi et réduit significativement l'exposition légale. Pas de scanning de contenu privé/chiffré.

### 9.3 Copyright

Cadre de notification légale DMCA/équivalent (takedown sur notification). Pas de blocage technique automatique — trop complexe, trop de faux positifs (fair use, variations régionales). Le hub peut révoquer sur demande légale confirmée.

### 9.4 Contenu privé

Non modérable directement (chiffré E2E par conception). Seule action disponible : révoquer l'utilisateur ou le groupe au niveau du hub sur demande légale formelle. Le hub émet un token de révocation signé que les nodes de tous les membres peuvent vérifier.

---

## 10. Système de modules Python

Le node peut charger des modules d'extension (Python) s'exécutant dans un sous-processus sandbox.

**Manifeste de module** (capacités déclarées) :
```python
{
  "name": "group-chat",
  "version": "1.0.0",
  "permissions": ["read_index", "send_message", "receive_events"]
}
```

**APIs disponibles (restreintes) :**
- `read_index()` — lecture de l'index courant du groupe (lecture seule)
- `send_message(content)` — poster un message dans le fil du groupe
- `receive_events(handler)` — s'abonner aux événements du groupe (nouveau fichier, nouveau message)

**Non disponible :**
- Accès réseau arbitraire
- Accès au système de fichiers hors du contexte du groupe
- Appels système

**Premier module officiel :** fil de discussion de groupe (façon Signal, avec pièces jointes). Fourni avec le node.

---

## 11. Cadre légal

**Opérateur du node :** hébergeur légal principal du contenu. Entièrement responsable de ce qu'il partage. Le logiciel node communique clairement cela lors de l'installation.

**Opérateur du hub :** registrar, pas hébergeur de contenu. Stocke un minimum de données personnelles. Opère le mécanisme de takedown. Participe au hash matching CSAM. Exposition légale analogue à celle d'un bureau d'enregistrement de domaines.

**Auteur du protocole/logiciel :** protégé par les usages non-contrefaisants substantiels. Pas de facilitation active de l'infraction.

**Minimisation des données du hub :**
- Email stocké haché après vérification [TBD]
- Pas de journalisation des IP (ou suppression automatique après 24h)
- Aucune métadonnée de contenu stockée
- Adresse courante du node gérée uniquement par le service de signaling éphémère

---

## 12. Fonctionnalités futures (notées, non conçues)

- **Réplication de contenu entre nodes :** node-à-node, autorisée par l'admin, sans implication du hub
- **Push vidéo depuis mobile :** mobile filme → pousse vers le node hébergeur → distribué comme flux éphémère avec TTL aux membres du groupe. Type MNP `ephemeral_stream` réservé.
- **Protocole d'enregistrement des Mesh Relays :** relais TURN communautaires enregistrés auprès des hubs
- **Appairage node-mobile :** QR code depuis l'interface web locale
- **Téléchargement multi-sources :** récupération de chunks en parallèle depuis plusieurs nodes pour un même fichier public (swarm)
- **Client iOS**
- **Chiffrement at-rest sur le node :** optionnel, pour les nodes déployés sur des serveurs distants

---

## 13. Questions ouvertes [TBD]

1. **Stockage des bundles GEK :** sur le hub ou sur le node uniquement ? Hub = discovery plus facile ; node uniquement = plus décentralisé
2. **Schéma d'adressage des groupes :** format URL final
3. **Périmètre de l'interface web locale du hub pour la V1 :** configuration uniquement, ou aussi navigation dans les groupes ?
4. **Création de compte :** email seul pour commencer, téléphone associable — à confirmer
5. **Implémentation du chat :** module bundlé ou fonctionnalité core ?
6. **Maturité de la lib QUIC :** évaluation de `aioquic` en production à effectuer
7. **Bibliothèque Double Ratchet :** identifier la meilleure implémentation Python
8. **Protocole d'enregistrement des relais :** à concevoir lors de l'introduction des relais communautaires
9. **Échange de répertoire cross-hub :** fréquence, résolution de conflits
10. **Port de l'interface web locale du node :** à définir
11. **Stratégie d'expiration et renouvellement des JWT**
12. **Format du keystore et mécanisme de déverrouillage au démarrage du node**