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