first

docs/protocol_events_signaling_update.md

@@ -0,0 +1,93 @@
+# 📄 signaling.md — Mesh WebRTC Signaling & ICE Strategy (v2)
+
+## 1. Objectif
+Décrire la **signalisation WebRTC** (média) et la stratégie de connexions pour Mesh.
+
+Mesh utilise :
+- **WebRTC** pour audio/vidéo/partage écran entre navigateurs
+- **QUIC P2P** pour transferts data (fichiers/dossiers/terminal) via Agent Rust
+
+---
+
+## 2. Rappels d’architecture
+- **Control plane** : Mesh Server (WS)
+- **Media plane** : WebRTC (clients web)
+- **Data plane** : QUIC (agents Rust)
+
+Le serveur ne transporte pas de média.
+
+---
+
+## 3. WebRTC (média) — ICE
+### STUN (obligatoire)
+Découverte IP publique.
+
+### TURN (fallback)
+Relais en cas d’échec P2P direct.
+
+Politique candidats :
+1. host
+2. srflx
+3. relay
+
+Recommandations :
+- Ne jamais forcer TURN
+- Logguer si relay utilisé
+
+---
+
+## 4. WebRTC — séquence standard
+1) Client A demande action (call/screen) au serveur
+2) serveur valide ACL + émet `cap_token`
+3) échange SDP/ICE via WS (`rtc.offer/answer/ice`)
+4) flux média direct A↔B
+
+---
+
+## 5. QUIC P2P (data) — stratégie
+- QUIC = TLS 1.3 natif, multiplexing streams, perf élevée
+- Démarrage : création de session via `p2p.session.request`
+- Le serveur fournit `session_token` + endpoints
+- Les pairs se connectent directement (UDP)
+
+### NAT / connectivité
+- QUIC peut nécessiter :
+  - UDP sortant autorisé
+  - parfois des contraintes NAT/CGNAT
+
+Recommandations :
+- privilégier LAN direct
+- sur Internet : documenter ouverture/autorisation UDP
+- fallback HTTP temporaire (exception)
+
+---
+
+## 6. Optimisations data
+- chunking 64–256 KB
+- backpressure
+- reprise par offset
+- hash par chunk + hash final (blake3 recommandé)
+
+---
+
+## 7. Sécurité
+- actions gated by capability token TTL court
+- QUIC TLS 1.3
+- terminal : preview-only par défaut, contrôle arbitré via serveur
+
+---
+
+## 8. Diagnostics
+Exposer :
+- WebRTC : host/srflx/relay
+- QUIC : latence, débit, retries
+- erreurs : sessions refusées, tokens expirés
+
+---
+
+## 9. Changelog
+```
+0.1.0 – WebRTC signaling + ICE
+0.2.0 – QUIC data-plane sessions (agent Rust)
+```
+