From 0135b093a56c723ef72ac92a2450ccbdd181a09d Mon Sep 17 00:00:00 2001
From: thibaud-lclr <thibaud.leclere2@protonmail.com>
Date: Sat, 2 May 2026 15:04:54 +0200
Subject: [PATCH] docs: document bitwarden cache controls

---
 docs/manifest.md |  3 +++
 docs/secrets.md  | 28 ++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/docs/manifest.md b/docs/manifest.md
index 0f945c5..8311969 100644
--- a/docs/manifest.md
+++ b/docs/manifest.md
@@ -29,6 +29,8 @@ known = ["MY_MCP_PROFILE", "MY_MCP_URL", "MY_MCP_TOKEN"]
 
 [secret_store]
 backend_policy = "auto"
+# Optionnel : mettre false pour désactiver le cache Bitwarden.
+bitwarden_cache = true
 
 [profiles]
 default = "prod"
@@ -80,6 +82,7 @@ Champs supportés :
 - `token_env_names` : liste de variables d'environnement candidates pour retrouver le token.
 - `[environment].known` : variables d'environnement connues du projet.
 - `[secret_store].backend_policy` : politique de secret store (`auto`, `kwallet-only`, `keyring-any`, `env-only`, `bitwarden-cli`).
+- `[secret_store].bitwarden_cache` : active le cache Bitwarden mémoire et disque chiffré quand `backend_policy = "bitwarden-cli"`. Par défaut, le cache est activé si le champ est absent. Mettre `false` pour le désactiver.
 - `[profiles].default` : profil recommandé par défaut.
 - `[profiles].known` : profils connus du projet.
 - `[bootstrap].description` : description CLI utilisée par le bootstrap.
diff --git a/docs/secrets.md b/docs/secrets.md
index b3f97a7..3c011ae 100644
--- a/docs/secrets.md
+++ b/docs/secrets.md
@@ -72,6 +72,34 @@ store, err := secretstore.Open(secretstore.Options{
 })
 ```
 
+## Cache Bitwarden
+
+Le backend `bitwarden-cli` met en cache les lectures de secrets par défaut.
+Le cache mémoire évite les appels répétés au CLI dans un même process. Le cache
+disque est chiffré avec une clé dérivée de `BW_SESSION` via HKDF-SHA256 et
+AES-GCM.
+
+TTL par défaut : 10 minutes.
+
+Pour désactiver le cache dans `mcp.toml` :
+
+```toml
+[secret_store]
+backend_policy = "bitwarden-cli"
+bitwarden_cache = false
+```
+
+Pour le désactiver sans modifier le manifeste :
+
+```bash
+MCP_FRAMEWORK_BITWARDEN_CACHE=0
+```
+
+Le fichier de cache et le binaire installé ne suffisent pas à déchiffrer les
+secrets. Si `BW_SESSION` change ou disparaît, les entrées disque existantes
+deviennent inutilisables. Cette protection ne couvre pas un attaquant qui peut
+lire l'environnement ou la mémoire du process pendant l'exécution.
+
 Pour vérifier explicitement que Bitwarden est prêt (login + unlock + `BW_SESSION`) :
 
 ```go