# 📄 protocol-events.md — Mesh Event & Signaling Protocol (v2, Rust pragmatique)

## 1. Objectif
Ce document définit le protocole d’événements Mesh pour :
- signalisation WebRTC (média),
- orchestration des connexions P2P (data),
- autorisations (capabilities),
- notifications Gotify.

Séparation :
- **Control plane** : Mesh Server (REST + WebSocket)
- **Media plane** : WebRTC (clients web)
- **Data plane** : QUIC P2P (agents Rust)

---

## 2. Transports
- **WSS** : Client/Agent ↔ Mesh Server
- **WebRTC** : audio/vidéo/écran (client ↔ client)
- **QUIC (TLS 1.3)** : fichiers/dossiers/terminal (agent ↔ agent)

---

## 3. Format WS
```json
{
  "type": "event.type",
  "id": "uuid",
  "timestamp": "ISO-8601",
  "from": "peer_id|device_id|server",
  "to": "peer_id|device_id|room_id|server",
  "payload": {}
}
```
Payload recommandé : `room_id`, `target_peer_id`, `target_device_id`, `cap_token`, `session_id`.

---

## 4. Identités
- `user_id` : utilisateur
- `peer_id` : client web
- `device_id` : agent
- `room_id` : room (2–4)

---

## 5. Capabilities (JWT TTL court)
Contenu : `sub`, `room_id`, `caps[]`, `exp` (+ option `target_*`, `max_size`, `max_rate`).

Caps typiques :
- `call`, `screen`
- `share:file`, `share:folder`
- `terminal:view`, `terminal:control`

Règles :
- aucune session P2P ne démarre sans cap_token valide.
- terminal : input interdit sans `terminal:control`.

---

## 6. Système
### `system.hello`
Client/Agent → Server
```json
{ "peer_type": "client|agent", "version": "x.y.z" }
```

### `system.welcome`
Server → Client/Agent
```json
{ "peer_id": "...", "user_id": "..." }
```

---

## 7. Rooms / présence
### `room.join`
```json
{ "room_id": "..." }
```

### `room.joined`
```json
{ "peer_id": "...", "role": "member", "room_id": "..." }
```

### `presence.update`
```json
{ "peer_id": "...", "status": "online|busy|sharing" }
```

---

## 8. Chat
### `chat.message.send`
```json
{ "room_id": "...", "content": "hello" }
```

### `chat.message.created`
```json
{ "message_id": "...", "from": "...", "content": "hello" }
```

---

## 9. WebRTC signaling (média)
### `rtc.offer`
```json
{ "room_id": "...", "target_peer_id": "...", "sdp": "...", "cap_token": "..." }
```

### `rtc.answer`
```json
{ "room_id": "...", "target_peer_id": "...", "sdp": "...", "cap_token": "..." }
```

### `rtc.ice`
```json
{ "room_id": "...", "target_peer_id": "...", "candidate": {}, "cap_token": "..." }
```

---

## 10. QUIC P2P sessions (data plane)
Les flux data (file/folder/terminal) utilisent une session QUIC orchestrée par le serveur.

### 10.1 Création
#### `p2p.session.request`
Agent A → Server
```json
{
  "room_id": "...",
  "target_device_id": "...",
  "kind": "file|folder|terminal",
  "cap_token": "...",
  "meta": { "name": "...", "size": 123 }
}
```

#### `p2p.session.created`
Server → A et Server → B
```json
{
  "session_id": "uuid",
  "kind": "file|folder|terminal",
  "expires_in": 180,
  "auth": {
    "session_token": "...",
    "fingerprint": "..."
  },
  "endpoints": {
    "a": { "ip": "x.x.x.x", "port": 45432 },
    "b": { "ip": "y.y.y.y", "port": 45433 }
  }
}
```

### 10.2 Handshake applicatif
Premier message sur un stream QUIC :

`P2P_HELLO`
```json
{ "t": "P2P_HELLO", "session_id": "...", "session_token": "...", "from_device_id": "..." }
```

Réponse : `P2P_OK` ou `P2P_DENY`.

---

## 11. Data messages (sur QUIC)
### 11.1 Fichier
- `FILE_META` (nom, taille, hash)
- `FILE_CHUNK` (offset, bytes)
- `FILE_ACK` (last_offset)
- `FILE_DONE` (hash final)

### 11.2 Dossier
- `FOLDER_MODE` (zip|sync)
- (zip) `ZIP_META` / `ZIP_CHUNK` / `ZIP_DONE`
- (sync, V2) `MANIFEST` / `DIFF_CHUNK` / `CONFLICT`

### 11.3 Terminal
- `TERM_OUT` (UTF-8)
- `TERM_RESIZE` (cols/rows)
- `TERM_IN` (input) — seulement si contrôle accordé

---

## 12. Contrôle terminal
Arbitrage via WS :
- `terminal.control.take`
- `terminal.control.granted`
- `terminal.control.release`

---

## 13. Notifications (Gotify)
Événements notifiables :
- `chat.message.created`
- `call.missed`
- `share.completed`
- `terminal.share.started`
- `agent.offline`

---

## 14. Erreurs
`error`
```json
{ "code": "CAP_EXPIRED", "message": "Capability token expired" }
```

Codes suggérés : `CAP_REQUIRED`, `CAP_EXPIRED`, `ROOM_NOT_FOUND`, `P2P_SESSION_DENIED`, `UNROUTABLE`.

---

## 15. Changelog
```
0.1.0 – Base events + WebRTC signaling
0.2.0 – QUIC sessions for data plane (file/folder/terminal)
```