feat(ai): durcissement phase F (#79) - rate limit, redaction, OpenAPI/MCP, E2E

docs/AI_ARCHITECTURE_GUIDE.md

@@ -252,9 +252,14 @@ Tout outil reçoit un `ToolContext` et applique **systématiquement** :
 1. `check_vault_access(vault, user)` — `backend/auth/middleware.py:87`
 2. `_resolve_safe_path(vault_root, path)` — `backend/main.py:867`
 3. Confirmation utilisateur pour `risk in (write, dangerous)` (UI in-app : carte Apply ; MCP : two-step `propose`/`apply`).
-4. Redaction des secrets avant tout envoi au LLM — `redact_file_content()`.
+4. Redaction des secrets avant tout envoi au LLM — `redact_file_content()` puis
+   `backend/tools/redaction.py` sur **tout** résultat d'outil (diffs, extraits de recherche).
 5. Journalisation dans l'audit (`data/audit.log`).
-6. Rate limiting par token/outil ; quotas réutilisant `BOOKSLM_MAX_*`.
+6. **Rate limiting par jeton/outil** (`backend/tools/ratelimit.py` :
+   `OBSIGATE_TOOL_RATE_LIMIT`, `OBSIGATE_TOOL_RATE_LIMIT_PER_TOOL`,
+   `OBSIGATE_TOOL_RATE_WINDOW`) et **quotas** réutilisant `BOOKSLM_MAX_*`
+   (`BOOKSLM_MAX_TOOL_CALLS` par run d'agent, `BOOKSLM_MAX_TOOL_READ_BYTES`
+   pour `read_file`).
 
 ### Confirmations MCP — décision : two-step `propose`/`apply`
 
@@ -299,7 +304,7 @@ Pour répondre au besoin de cibler un fournisseur/modèle sans dépendre uniquem
 | **0 — Fondations** | `backend/tools/` (registry, context, service, audit) + extraction des services métier + tests unitaires | Couche d'outils testable sans IA |
 | **1 — Function calling in-app** | Abstraction tool-calling multi-provider, agent loop, confirmations UI, SSE réel, outils de navigation | Assistant qui lit/cherche/lit/ouvre/modifie avec confirmation |
 | **2 — Serveur MCP** | `backend/mcp/server.py` (tools + resources + prompts), **Streamable HTTP** (`/mcp`, auth JWT), confirmation two-step | ObsiGate accessible comme serveur MCP (local + distant, multi-utilisateur) |
-| **3 — Durcissement** | Rate limiting, quotas, redaction, tests, doc OpenAPI/MCP | Observabilité et sécurité complètes |
+| **3 — Durcissement** ✅ | Rate limiting (`backend/tools/ratelimit.py`), quotas `BOOKSLM_MAX_*`, redaction systématique des résultats (`backend/tools/redaction.py`), doc OpenAPI (tag/path MCP) + [guide MCP](./MCP_GUIDE.md), tests E2E | Observabilité et sécurité complètes |
 
 Voir `docs/ROADMAP.md` (item dédié) pour le détail des activités.
 
@@ -330,6 +335,9 @@ Voir `docs/ROADMAP.md` (item dédié) pour le détail des activités.
 - `backend/agent/loop.py` — agent loop in-app (multi-étapes, LLM injectable)
 - `backend/mcp/server.py` — serveur MCP (Streamable HTTP `/mcp`, tools/resources/prompts)
 - `backend/mcp/confirmations.py` — jetons de confirmation signés (two-step, anti-rejeu)
+- `backend/tools/ratelimit.py` — rate limiting par jeton/outil (phase F)
+- `backend/tools/redaction.py` — redaction récursive des résultats d'outils (phase F)
+- `docs/MCP_GUIDE.md` — guide d'installation et d'utilisation des clients MCP
 - `backend/bookslm.py`, `backend/bookslm_routes.py` — assistant contextuel (+ endpoint `/agent`)
 - `frontend/js/ai.js`, `frontend/js/bookslm.js` — UI IA
 - `backend/auth/middleware.py` — permissions

docs/MCP_GUIDE.md

@@ -0,0 +1,182 @@
+# ObsiGate — Guide MCP (Model Context Protocol)
+
+> **Statut :** livré (#79 phase E + F) · **Dernière mise à jour :** 2026-09-11
+> **Voir aussi :** [AI_ARCHITECTURE_GUIDE.md](./AI_ARCHITECTURE_GUIDE.md) ·
+> [features/ai-tools-mcp.md](./features/ai-tools-mcp.md) · [ROADMAP.md](./ROADMAP.md)
+
+ObsiGate expose ses vaults à des **clients MCP externes** (Claude Desktop, Cursor,
+tout client compatible MCP) via un serveur **Streamable HTTP** monté sur `/mcp`.
+Les outils sont les **mêmes** que ceux de l'assistant in-app : la couche
+`backend/tools/` est la source unique de vérité.
+
+---
+
+## 1. Prérequis
+
+1. Une instance ObsiGate accessible (locale ou distante).
+2. Un **jeton JWT** valide (`Authorization: Bearer <token>`), obtenu via
+   `POST /api/auth/login` (ou une clé API). Le jeton porte les permissions par
+   vault de l'utilisateur — l'autorisation MCP réutilise `get_current_user`.
+3. Si l'authentification est désactivée (`OBSIGATE_AUTH_ENABLED=false`), le
+   serveur MCP accepte un utilisateur anonyme disposant de tous les vaults.
+
+> Le transport `stdio` n'est **pas** encore supporté ; utilisez le transport
+> HTTP (un pont local type `mcp-remote` si votre client ne gère pas nativement
+> le Streamable HTTP distant).
+
+---
+
+## 2. Endpoint & protocole
+
+| Élément | Valeur |
+|---|---|
+| URL | `https://<obsigate>/mcp` |
+| Transport | Streamable HTTP (`POST` JSON-RPC 2.0, `Accept: application/json, text/event-stream`) |
+| Auth | `Authorization: Bearer <JWT>` |
+| Protocole MCP | `2025-03-26` (négocié à l'`initialize`) |
+| Réponses | JSON (`json_response=True`) |
+
+Handshake minimal :
+
+```bash
+curl -sS https://obsigate.example/mcp \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
+        "protocolVersion":"2025-03-26","capabilities":{},
+        "clientInfo":{"name":"curl","version":"1.0"}}}'
+```
+
+La réponse contient l'en-tête `Mcp-Session-Id` à réutiliser pour les appels
+suivants (`tools/list`, `tools/call`, `resources/read`, …).
+
+---
+
+## 3. Configuration des clients
+
+### Claude Desktop (via pont `mcp-remote`)
+
+```json
+{
+  "mcpServers": {
+    "obsigate": {
+      "command": "npx",
+      "args": [
+        "-y", "mcp-remote",
+        "https://obsigate.example/mcp",
+        "--header", "Authorization: Bearer ${OBSIGATE_TOKEN}"
+      ],
+      "env": { "OBSIGATE_TOKEN": "eyJ..." }
+    }
+  }
+}
+```
+
+### Cursor
+
+`.cursor/mcp.json` :
+
+```json
+{
+  "mcpServers": {
+    "obsigate": {
+      "url": "https://obsigate.example/mcp",
+      "headers": { "Authorization": "Bearer eyJ..." }
+    }
+  }
+}
+```
+
+---
+
+## 4. Primitives exposées
+
+### 4.1 Tools
+
+Les outils de **lecture/recherche** sont exposés directement. Les outils
+**d'écriture/destructifs** sont exposés via une paire **two-step** :
+`propose_<tool>` (aperçu + jeton de confirmation, aucune modification) puis
+`apply_<tool>` (consomme le jeton et exécute).
+
+| Catégorie | Outils |
+|---|---|
+| Vaults / navigation | `list_vaults`, `list_directory`, `list_all_files` |
+| Lecture | `read_file`, `read_file_raw`, `get_backlinks`, `list_backups`, `diff_backup`, `get_graph` |
+| Recherche | `search_fulltext`, `search_advanced`, `search_paths`, `list_tags`, `suggest_tags`, `list_recent` |
+| Écriture (propose/apply) | `create_file`, `create_directory`, `edit_file`, `append_to_file`, `restore_backup` |
+| Destructif (propose/apply) | `rename_file`, `rename_directory`, `move_path`, `replace_in_files`, `delete_file`, `delete_directory` |
+
+Flux d'une mutation :
+
+```text
+1. tools/call { name: "propose_edit_file",
+                arguments: { vault, path, content } }
+   → { tool, arguments, diff, confirmation_token, expires_in }
+
+2. (l'utilisateur / l'agent valide)
+
+3. tools/call { name: "apply_edit_file",
+                arguments: { confirmation_token } }
+   → { ok: true, data: { ... } }
+```
+
+Le jeton est **signé (JWT), à usage unique et à durée de vie limitée**
+(`OBSIGATE_MCP_CONFIRMATION_TTL`, défaut 300 s). Un rejeu renvoie
+`token_reused`.
+
+### 4.2 Resources
+
+| URI | Contenu |
+|---|---|
+| `vault://<name>` | Vault accessible (métadonnées, nombre de fichiers) |
+| `vault://<name>/<path>` | Contenu d'un fichier (lecture seule, **secrets redactés**) |
+
+### 4.3 Prompts
+
+`summarize-directory`, `generate-note`, `find-related`.
+
+---
+
+## 5. Sécurité
+
+- **Permissions par vault** : `check_vault_access` est appliqué à chaque outil
+  et chaque resource ; un utilisateur ne voit que ses vaults.
+- **Anti path-traversal** : `resolve_safe_path` rejette tout chemin hors du vault.
+- **Confirmation two-step** pour toute mutation (jeton signé, usage unique).
+- **Toggle par vault** `aiDestructiveTools` (défaut : activé) : le désactiver
+  bloque rename/move/replace/delete tout en laissant create/edit/append.
+- **Backup automatique** avant chaque opération destructive.
+- **Rate limiting** : par jeton et par outil
+  (`OBSIGATE_TOOL_RATE_LIMIT`, `OBSIGATE_TOOL_RATE_LIMIT_PER_TOOL`,
+  `OBSIGATE_TOOL_RATE_WINDOW`). Une limite dépassée renvoie le code
+  `rate_limited`.
+- **Redaction des secrets** : les résultats d'outils (lectures, diffs,
+  extraits de recherche) sont nettoyés avant tout retour au client.
+- **Audit** : chaque appel est journalisé (`data/audit.log`, action
+  `ai_tool_call`) avec arguments sensibles résumés.
+
+### Variables d'environnement
+
+| Variable | Défaut | Rôle |
+|---|---|---|
+| `OBSIGATE_MCP_CONFIRMATION_TTL` | `300` | Durée de vie (s) des jetons de confirmation |
+| `OBSIGATE_TOOL_RATE_LIMIT` | `60` | Appels d'outils max par identité et par fenêtre |
+| `OBSIGATE_TOOL_RATE_LIMIT_PER_TOOL` | = global | Appels max par outil et par fenêtre |
+| `OBSIGATE_TOOL_RATE_WINDOW` | `60` | Longueur de la fenêtre (s) |
+| `BOOKSLM_MAX_TOOL_CALLS` | `25` | Quota d'appels d'outils par run d'agent |
+| `BOOKSLM_MAX_TOOL_READ_BYTES` | `200000` | Taille max renvoyée par `read_file` |
+
+---
+
+## 6. Dépannage
+
+| Symptôme | Cause probable / remède |
+|---|---|
+| `401 Authentification requise` | En-tête `Authorization: Bearer` absent ou jeton expiré |
+| `vault_access_denied` | Le jeton n'a pas accès à ce vault (`vaults` / `_token_vaults`) |
+| `destructive_tools_disabled` | `aiDestructiveTools=false` pour ce vault |
+| `confirmation_required` | Appeler d'abord `propose_<tool>` puis `apply_<tool>` |
+| `token_reused` / `invalid_confirmation` | Jeton déjà consommé ou expiré → refaire un `propose_` |
+| `rate_limited` | Quota dépassé ; respecter `retry_after` |
+| Le client ne se connecte pas | Vérifier le transport Streamable HTTP / le pont `mcp-remote` |

docs/ROADMAP.md

@@ -40,18 +40,6 @@
   - [ ] Jumplist vaults récents dans le menu Démarrer (optionnel)
   - [ ] 6 tests E2E **manuels** : installation, tray icon, notifications natives, association `.md`, auto-update, désinstallation
 
-### 79. Assistant IA — Outils (function calling) & serveur MCP
-
-- **Effort :** 10-15 jours | **Impact :** 🟡
-- **Statut :** 🔵 Phase 0 + A2 + B1/B2/B3/B4/B5/B6/B7 + C + D + E + G livrés (2026-09-11). Détail complet : [features/ai-tools-mcp.md](./features/ai-tools-mcp.md)
-- **Description :** Transformer l'assistant BooksLM en agent (lire, chercher, lister, ouvrir, modifier) via **function calling natif**, puis exposer ObsiGate à des **clients MCP externes** (Claude Desktop, Cursor…). Les deux fronts consomment une **couche d'outils partagée**.
-- **Reste à faire :**
-  - [x] **C.** Catalogue lecture & recherche (vaults, read, backlinks, backups, search, tags)
-  - [x] **D.** Catalogue mutations (create/edit/append/rename/move/delete) + confirmations two-step
-  - [x] **E.** Serveur MCP (Streamable HTTP `/mcp`, auth Bearer JWT, `propose`/`apply`, toggle par vault)
-  - [ ] **F.** Durcissement (rate limiting, redaction secrets, OpenAPI + guide MCP, E2E)
-- **Documentation :** [AI_ARCHITECTURE_GUIDE.md](./AI_ARCHITECTURE_GUIDE.md) (architecture, catalogue d'outils, sécurité, phases).
-
 ### 80. Assistant IA — Rendu Markdown, liens fichiers/paths & sessions
 
 - **Effort :** 1-2 jours | **Impact :** 🟡
@@ -169,6 +157,7 @@
 | 72 | API publique documentée — OpenAPI 3.1 | 2.2.0 | [archive](./archive/COMPLETED_v1-v2.md) |
 | 76 | BooksLM — Console AI contextuelle par répertoire | 2.2.0 | [features/bookslm.md](./features/bookslm.md) |
 | 78 | Éditeur Excalidraw | 2.2.0 | [features/excalidraw.md](./features/excalidraw.md) |
+| 79 | Assistant IA — Outils (function calling) & serveur MCP | 2.3.0 | [features/ai-tools-mcp.md](./features/ai-tools-mcp.md) |
 | 77 | Application Desktop native — Tauri | 🔵 en cours | [features/desktop-tauri.md](./features/desktop-tauri.md) |
 | 80 | Assistant IA — Rendu Markdown, liens fichiers/paths & sessions | 🔵 en cours | [features/ai-assistant-ux.md](./features/ai-assistant-ux.md) |
 
@@ -178,11 +167,11 @@
 
 | Priorité | Items | Effort total estimé |
 |---|---|---|
-| ✅ Complété | #1 → #59, #61, #63–68, #71, #72, #74–76, #78 | ~82 jours réalisés |
+| ✅ Complété | #1 → #59, #61, #63–68, #71, #72, #74–79 | ~92 jours réalisés |
 | 🔵 P2 restant | #77 Desktop : signature code (optionnel), wizard 1er lancement (optionnel), 6 tests E2E **manuels** | ~1-2 jours |
-| ⚪ P3 restant | #62 Collaboration Yjs (5-7j) · #79 Assistant IA outils + MCP (10-15j, Phase 0 + A2 + B + C + D + E + G livrés) · #80 Assistant IA UX (livré, en attente vérif) | ~15-22 jours |
+| ⚪ P3 restant | #62 Collaboration Yjs (5-7j) · #80 Assistant IA UX (livré, en attente vérif) | ~5-7 jours |
 | ⚪ P4 restant | #69 Mobile éditeur (2-3j) · #70 Sémantique (4-5j) · #73 Sync (6-8j) | 11-16 jours |
-| **Total restant** | **6 items + finitions** | **~27-39 jours** |
+| **Total restant** | **5 items + finitions** | **~17-25 jours** |
 
 ---
 

docs/features/ai-tools-mcp.md

@@ -1,6 +1,6 @@
 # #79 — Assistant IA — Outils (function calling) & serveur MCP
 
-> **Statut :** 🔵 En cours — Phase 0 + A2 + B1/B2/B3/B4/B5/B6/B7 + C + D + E + G livrés (2026-09-11)
+> **Statut :** ✅ Livré — Phase 0 + A2 + B1/B2/B3/B4/B5/B6/B7 + C + D + E + F + G livrés (2026-09-11)
 > **Effort :** 10-15 jours | **Impact :** 🟡
 > **Références :** [Roadmap](../ROADMAP.md) · [Guide d'architecture IA](../AI_ARCHITECTURE_GUIDE.md)
 
@@ -53,11 +53,25 @@
     matcher `/mcp` exact, démarrage paresseux du manager pour les tests). Dépendances ajoutées :
     `mcp==1.9.4`, `sse-starlette==2.1.3` (compatibles avec FastAPI 0.110 / starlette 0.37).
 
-## F. Durcissement & documentation (1 jour)
-  - [ ] **F1.** Rate limiting par token/outil + quotas (`BOOKSLM_MAX_*`)
-  - [ ] **F2.** Redaction des secrets avant retour au LLM
-  - [ ] **F3.** Documentation OpenAPI (`backend/openapi_docs.py`) + guide MCP
-  - [ ] **F4.** Tests E2E de bout en bout
+## F. Durcissement & documentation (1 jour) — ✅ livré (2026-09-11)
+  - [x] **F1.** Rate limiting par token/outil + quotas — `backend/tools/ratelimit.py`
+    (fenêtre glissante par identité **et** par outil ; identité = JTI du jeton
+    (`_token_jti`, ajouté par `backend/auth/middleware.py`) sinon id/username).
+    Env : `OBSIGATE_TOOL_RATE_LIMIT` (60), `OBSIGATE_TOOL_RATE_LIMIT_PER_TOOL`,
+    `OBSIGATE_TOOL_RATE_WINDOW` (60 s) ; erreur `ToolRateLimitError` (`rate_limited`).
+    Quotas `BOOKSLM_MAX_*` : `BOOKSLM_MAX_TOOL_CALLS` (25) plafonne les appels d'outils
+    par run d'agent (`backend/agent/loop.py`, `stopped="quota_exceeded"`) et
+    `BOOKSLM_MAX_TOOL_READ_BYTES` (200000) plafonne `read_file`.
+  - [x] **F2.** Redaction des secrets avant retour au LLM — `backend/tools/redaction.py`
+    (`redact_payload`, récursif) appliqué à **tout** résultat d'outil dans
+    `call_tool` (couvre les diffs, extraits de recherche et lectures non pré-redactées).
+  - [x] **F3.** Documentation OpenAPI + guide MCP — `backend/openapi_docs.py` : tag `MCP`,
+    règle `/mcp`, injection du path `/mcp` (Streamable HTTP, JSON-RPC) dans le schéma ;
+    nouveau [`docs/MCP_GUIDE.md`](../MCP_GUIDE.md) (endpoint, auth, config Claude Desktop /
+    Cursor, tools/resources/prompts, sécurité, variables, dépannage).
+  - [x] **F4.** Tests E2E de bout en bout — `tests/test_ai_e2e.py` : agent in-app
+    read→confirmation→write, quota d'outils, rate limiting, redaction, et flux MCP complet
+    `read` → `propose_edit_file` → `apply_edit_file` → `resources/read`.
 
 ## G. Sélection fournisseur/modèle par défaut — ✅ livré
   - [x] **G1.** Persistance `ai_default_provider` + `ai_default_models` dans `data/config.json` (`_DEFAULT_CONFIG`)