first

docs/security.md

@@ -0,0 +1,64 @@
+# 📄 security.md — Mesh Security Model
+
+## 1. Principes
+- **Server = control plane** : auth, ACL, signaling WebRTC, événements, notifications.
+- **Clients/Agents = data plane** : média + fichiers + terminal en P2P (WebRTC).
+- Le serveur ne transporte pas de flux média ni de transferts lourds (sauf fallback explicite).
+
+## 2. Identités
+- user_id : utilisateur
+- peer_id : instance client web
+- device_id : agent desktop
+- room_id : salon (2–4 personnes)
+
+## 3. Authentification
+- JWT (access token court recommandé, refresh optionnel).
+- WS authentifié (JWT dans query param sécurisé ou header lors du handshake).
+- Rotation et révocation (à prévoir V1/V2).
+
+## 4. Autorisations : Capability Tokens
+Le serveur émet des tokens à TTL court (ex 120s) contenant:
+- room_id
+- peer_id (ou device_id)
+- caps : ["call", "screen", "share:file", "share:folder", "terminal:view", "terminal:control"]
+- contraintes optionnelles : max_size, max_rate, target_peer_id
+
+Règles:
+- aucun offer WebRTC n’est accepté/relayé sans capability valide associée à l’action.
+- un viewer en terminal n’a pas le droit d’envoyer `TERM_IN` sans `terminal:control`.
+
+## 5. WebRTC sécurité
+- Chiffrement natif DTLS/SRTP (média) + DTLS (DataChannel).
+- Vérification fingerprint SDP côté client (V1+).
+- ICE: STUN + TURN (TURN = bande passante sensible; limiter via quotas).
+
+## 6. Terminal share (SSH preview)
+- Le SSH tourne **sur la machine du partageur** (agent), via PTY.
+- Aucun secret SSH (clé, mot de passe) n’est transmis aux viewers.
+- Mode par défaut : **preview (read-only)**.
+- “Take control” : un seul contrôleur à la fois, arbitrage via serveur (capability).
+- Option V2: masquage best-effort de secrets (non garanti).
+
+## 7. Notifications (Gotify)
+- Le serveur et l’agent peuvent notifier Gotify.
+- Ne jamais inclure de secrets dans le texte des notifications.
+- Niveau de détail configurable (ex: “Nouveau message” vs contenu).
+
+## 8. Journalisation
+- Server logs: auth failures, room joins, capability issuance, signaling events (sans contenu média).
+- Agent logs: démarrage/arrêt de partage, erreurs sync, diagnostics ICE.
+- Politique de rétention courte (ex 7–14 jours) + rotation.
+
+## 9. Menaces & mitigations (résumé)
+- Usurpation peer_id → JWT + WS auth + device_id registration.
+- Replay d’offers → capability TTL court + nonce/session_id.
+- Accès non autorisé à une room → ACL server-side + tokens scoped room_id.
+- Exfiltration via terminal → preview-only par défaut + contrôle explicite.
+- TURN abuse → quotas, credentials temporaires, rate limiting.
+
+## 10. Roadmap sécurité
+- Refresh tokens + révocation
+- RBAC (owner/member/guest)
+- E2E applicatif optionnel (au-dessus de WebRTC)
+- Attestation device (optionnel)
+