mesh/docs/security.md

📄 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)