first

2026-01-05 13:13:08 +01:00
parent 8e14adafc6
commit 1d177e96a6
149 changed files with 29541 additions and 1 deletions
--- a/docs/AGENT.md
+++ b/docs/AGENT.md
@@ -0,0 +1,185 @@
+# 📄 agent.md — Mesh Agent (Rust pragmatique)
+
+## 1. Description
+**Mesh Agent** est un agent desktop multi-OS (Linux / Windows / macOS) conçu pour compléter Mesh (app web) avec des capacités locales avancées.
+
+Objectifs :
+- **Flux lourds P2P** (faible charge serveur)
+- **Binaires multi-OS** simples à déployer
+- Terminal/SSH partagé robuste
+- Partage fichiers/dossiers performant
+- Notifications directes Gotify
+
+L’agent communique :
+- avec le **Mesh Server** (REST + WebSocket) pour auth/permissions/signalisation,
+- avec les **autres clients/agents** en **P2P** pour les flux data,
+- avec **Gotify** pour les notifications.
+
+---
+
+## 2. Architecture (control plane vs data plane)
+- **Control plane** : Mesh Server
+  - Auth
+  - Rooms & ACL
+  - Tokens de capacités (TTL court)
+  - Signalisation (WS)
+  - Événements + notifications Gotify
+- **Data plane** : P2P
+  - Audio/Vidéo/Écran : WebRTC (côté client web)
+  - Fichiers/Dossiers/Terminal : P2P via **QUIC** (recommandé V1)
+    - fallback possible : WebRTC DataChannel (V2) ou HTTP temporaire (exception)
+
+Le serveur ne transporte pas de média ni de transferts lourds.
+
+---
+
+## 3. Fonctions principales
+### 3.1 Partage fichiers & dossiers (P2P)
+- Envoi fichier : chunks + reprise + checksum
+- Envoi dossier :
+  - mode simple : **zip à la volée**
+  - mode sync (optionnel) : watcher + manifest + diff
+- Débit contrôlé + backpressure
+
+### 3.2 Terminal / SSH share (preview + contrôle)
+- L’agent lance une session locale via **PTY** (bash/pwsh) et peut lancer `ssh user@host`.
+- Diffuse la sortie terminal en P2P.
+- Modes :
+  - **preview (lecture seule)** par défaut
+  - **take control** (un seul contrôleur à la fois)
+
+### 3.3 Notifications
+- Envoi direct vers Gotify (agent → Gotify)
+- Notifications OS locales (optionnel V1)
+
+### 3.4 Intégration OS
+- Tray icon (optionnel)
+- Auto-start (optionnel)
+- Identité machine : `device_id`
+
+---
+
+## 4. Stack technique (Rust)
+### Runtime / réseau
+- **Rust stable**
+- **tokio** (async)
+- **reqwest** (HTTP)
+- **tokio-tungstenite** (WebSocket)
+- **quinn** (QUIC P2P) — recommandé pour data plane (fichiers/terminal)
+
+### Terminal
+- Unix : **portable-pty** (ou equivalent) pour PTY
+- Windows : **ConPTY** (crate dédiée / wrapper)
+
+### FS / sync
+- notify (watcher cross-platform)
+- hashing (blake3 recommandé)
+
+### Config / logs
+- serde + toml/yaml
+- tracing + tracing-subscriber
+
+### Packaging
+- binaire unique par OS
+- install : MSI (Windows), deb/rpm (Linux), dmg/pkg (macOS) — V1/V2
+
+---
+
+## 5. Structure recommandée
+```
+agent/
+  Cargo.toml
+  src/
+    main.rs
+    config/
+      mod.rs
+    mesh/
+      rest.rs
+      ws.rs
+      types.rs
+    p2p/
+      mod.rs
+      quic/
+        endpoint.rs
+        protocol.rs
+      fallback_http/
+        mod.rs
+    share/
+      file_send.rs
+      folder_zip.rs
+      folder_sync/
+        manifest.rs
+        diff.rs
+        watcher.rs
+    terminal/
+      mod.rs
+      pty_unix.rs
+      conpty_windows.rs
+      stream.rs
+    notifications/
+      gotify.rs
+      router.rs
+    os/
+      autostart.rs
+      tray.rs
+  tests/
+```
+
+---
+
+## 6. Protocole & permissions
+- Toutes les actions P2P sont autorisées par **capability tokens** (TTL court), émis par le serveur :
+  - `share:file`, `share:folder`, `terminal:view`, `terminal:control`
+- Le P2P (QUIC) utilise un **handshake applicatif** :
+  - échange d’un token de session (issu du serveur)
+  - validation côté pair avant d’accepter un flux
+
+---
+
+## 7. Sécurité (résumé)
+- Les secrets SSH ne sortent jamais de la machine partageuse.
+- Terminal share : preview-only par défaut.
+- Chiffrement transport : QUIC (TLS 1.3), WebSocket/TLS.
+- Logs sans contenu sensible.
+
+---
+
+## 8. TODO
+### MVP (priorité)
+- [ ] Config + identité `device_id`
+- [ ] Connexion WS au serveur (auth)
+- [ ] Réception events (room, terminal, share)
+- [ ] Notifications Gotify
+- [ ] Terminal preview (PTY) + stream P2P (QUIC)
+
+### V1
+- [ ] Envoi fichier P2P (QUIC)
+- [ ] Envoi dossier (zip) P2P
+- [ ] Take control terminal (arbitrage via serveur)
+- [ ] Diagnostics (mode P2P, erreurs, stats)
+
+### V2
+- [ ] Sync dossier (manifest/diff)
+- [ ] Tray + autostart multi-OS
+- [ ] Fallback HTTP serveur (temporaire) si P2P impossible
+- [ ] WebRTC DataChannel agent (si besoin compat)
+
+---
+
+## 9. Améliorations futures
+- `.meshignore`
+- Diff binaire + dédup
+- Chiffrement applicatif E2E optionnel
+- Tunnel SSH (TCP-like) au-dessus de QUIC (avancé)
+
+---
+
+## 10. Changelog
+```
+0.1.0 – Rust agent skeleton (WS + Gotify)
+0.2.0 – Terminal share preview (QUIC)
+0.3.0 – File transfer (QUIC)
+0.4.0 – Folder zip + take control
+0.5.0 – Folder sync (beta)
+```
+