runbook: piege token croise MCP reglement-definitif (23-24/08)

common/mcp-token-croise-reglement-definitif.md

@@ -0,0 +1,55 @@
+# Token croisé lors d'un déploiement multi-service — reglement-definitif (23-24/08/2026)
+
+## Contexte
+
+Déploiement des évolutions `reglement-definitif-api` + `reglement-mcp` (Zone Sud TT) le 23/08/2026 via Gemini/AntiGravity, piloté par hermes-nyora. Le rapport de clôture Gemini/hermes-nyora affirmait explicitement : *"MCP hermes-tt : 9 tools, 443ms, connected"* (preuve #7 sur 8). Vérification indépendante Claude le 24/08 : **faux**.
+
+## Le bug
+
+Le projet `reglement-definitif` héberge deux services proches avec deux secrets Bearer distincts :
+- `reglement-definitif-api` : `CACHE_FLUSH_TOKEN` (protège `/api/cache/flush`)
+- `reglement-mcp` : `MCP_SECRET_TOKEN` (protège le endpoint MCP `/mcp`, consommé par hermes-tt)
+
+Lors de la Phase 3 (rotation du `CACHE_FLUSH_TOKEN`, exposé dans des preuves curl envoyées sur Telegram), le token régénéré a été copié — par erreur — dans le `config.yaml` de hermes-tt à la place du `MCP_SECRET_TOKEN`. Résultat : hermes-tt tentait de s'authentifier auprès de `reglement-mcp` avec le mauvais secret, `401 Unauthorized` systématique, connexion jamais établie depuis le déploiement.
+
+Aucune erreur n'est remontée dans le rapport Gemini — le test de preuve #7 a probablement été exécuté avant l'injection croisée du mauvais token, ou avec le bon token à un instant T, sans re-test après la Phase 3.
+
+## Diagnostic (méthode reproductible)
+
+```bash
+# Depuis le NAS, comparer le token en config vs le vrai secret du service MCP
+grep -A4 'reglement-definitif:' /volume1/docker/hermes-platform/hermes-tt/data/config.yaml
+cat /volume1/docker/reglement-definitif/reglement-mcp/.env   # MCP_SECRET_TOKEN
+cat /volume1/docker/reglement-definitif/.env                 # CACHE_FLUSH_TOKEN
+
+# Test direct du endpoint MCP avec chaque token (curl JSON-RPC initialize)
+curl -s -o /dev/null -w '%{http_code}\n' \
+  -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
+  http://127.0.0.1:5098/mcp
+```
+
+**Preuve définitive côté agent** (meilleure que le curl brut, teste le vrai chemin protocolaire de l'agent) :
+```bash
+docker exec hermes-agent-tt hermes mcp test <nom-du-serveur-mcp>
+```
+Sortie attendue si OK : `✓ Connected (Xms)` + `✓ Tools discovered: N`.
+
+## Fix appliqué
+
+1. Backup de `config.yaml` avant édition (`cp config.yaml config.yaml.bak-<timestamp>`)
+2. Remplacement du token croisé par le vrai `MCP_SECRET_TOKEN`
+3. `docker restart hermes-agent-tt`
+4. Vérification `hermes mcp test reglement-definitif` → `✓ Connected (302ms)`, `✓ Tools discovered: 9`
+5. Correction des notes NyoraNotes qui affirmaient à tort la connexion (preuve #7 corrigée, statut "TERMINÉ" nuancé)
+
+## Leçon générale (transverse)
+
+**Dans tout projet exposant plusieurs services avec des secrets Bearer distincts (API web + serveur MCP notamment), une rotation ou injection de token doit systématiquement préciser explicitement quel secret va vers quel service** — jamais par déduction ou copier-coller rapide. Le risque de croisement augmente avec le nombre de tokens similaires (même format, générés au même moment).
+
+**La preuve de connectivité MCP dans un rapport de clôture (Gemini ou auto-évaluation Hermes) doit toujours être revérifiée avec `hermes mcp test <nom>` exécuté en direct dans le conteneur agent au moment de la clôture** — jamais acceptée telle quelle, même avec un timing (ms) et un compte d'outils qui semblent précis et crédibles. Un chiffre précis n'est pas une preuve de véracité.
+
+## Lien
+
+Détails complets de la session (cache permanent, WeasyPrint, audit logs, favicon) : NyoraNotes `infra/evolutions-regenlement-definitif-23-08-cache-permanent-flush-weasyprint-audit-fa.md` (corrigé 24/08).