@nodefony/security 10.0.0-beta.2 → 10.0.0-beta.4

package/docs/totp.md

@@ -66,7 +66,7 @@ flowchart TD
 
 Tant que le second facteur n'est pas validé, **l'identité n'est pas établie** : `session.user` reste
 vide et le Zero Trust du firewall répond 401 sur tout le reste (`AuthFlow.login()`,
-`authFlow.ts:170`).
+`authFlow.ts#AuthFlow.login`).
 
 ## 📖 Lexique
 
@@ -110,29 +110,29 @@ reste le second facteur **universel** — celui qui marche sans matériel dédi
 
 Trois partis pris, tous vérifiables dans le code.
 
-**1. La logique est PURE, le service n'est qu'une prise de courant.** `TotpService` (`totp.ts:74`)
+**1. La logique est PURE, le service n'est qu'une prise de courant.** `TotpService` (`totp.ts#TotpService`)
 résout au boot deux choses seulement : le **store** de secrets et la **clé de chiffrement**
-(`TotpService.#build()`, `totp.ts:92`). Tout le reste — enrôler, confirmer, vérifier — vit dans des
+(`TotpService.#build()`, `totp.ts#TotpService.#build`). Tout le reste — enrôler, confirmer, vérifier — vit dans des
 fonctions sans I/O ni container (`totpOperations.ts`), qui reçoivent leurs dépendances en argument
-(`ITotpDeps`, `totpOperations.ts:22`). Conséquence directe : la logique critique se teste **sans
+(`ITotpDeps`, `totpOperations.ts#ITotpDeps`). Conséquence directe : la logique critique se teste **sans
 serveur, sans base, avec une horloge injectée** — et c'est pour ça qu'elle est couverte à ~100 %.
 
 **2. Le secret est CHIFFRÉ, jamais haché.** Un mot de passe se hache (à sens unique) parce que le
 serveur n'a qu'à le **comparer**. Un secret TOTP, lui, doit être **relu en clair** à chaque
 vérification pour recalculer le code → il est **chiffré** en AES-256-GCM
-(`ITotpSecret.secretEnc`, `ITotpSecret.ts:18`). C'est la différence de nature qui commande la
+(`ITotpSecret.secretEnc`, `ITotpSecret.ts#ITotpSecret.secretEnc`). C'est la différence de nature qui commande la
 différence de traitement, pas une négligence.
 
 **3. Le TOTP n'est pas un authenticator du firewall — c'est un step-up de login.** Il n'apparaît
 jamais dans `area.authenticators` : il s'insère **dans le flux de session BFF**, entre le mot de
-passe et l'ouverture de session (`AuthFlow.completeMfaLogin()`, `authFlow.ts:257`). Même dessin que
+passe et l'ouverture de session (`AuthFlow.completeMfaLogin()`, `authFlow.ts#AuthFlow.completeMfaLogin`). Même dessin que
 WebAuthn et OAuth : le firewall n'a qu'un seul mécanisme à connaître, la **session**.
 
 > [!IMPORTANT]
 > Le couplage est fait **par nom de service**, jamais par import : `AuthFlow` ne connaît du 2FA
-> qu'une interface locale de trois méthodes (`ITotpLoginVerifier`, `authFlow.ts:44`). 2FA désactivé
+> qu'une interface locale de trois méthodes (`ITotpLoginVerifier`, `authFlow.ts#ITotpLoginVerifier`). 2FA désactivé
 > ⇒ service absent ⇒ le login nominal **ne paie strictement rien** (`AuthFlow.#resolveTotp()`,
-> `authFlow.ts:458`).
+> `authFlow.ts#AuthFlow.#resolveTotp`).
 
 ## 🚀 Démarrage rapide
 
@@ -143,18 +143,18 @@ activer un second facteur depuis sa page « ma sécurité », et que le login l'
 
 Le secret TOTP est chiffré au repos → il faut une clé **stable** (sinon les secrets deviennent
 illisibles au redémarrage). La commande la génère et te dit exactement où la coller
-(`nodefony security:secrets`, `security-secrets.ts:79`) :
+(`nodefony security:secrets`, `security-secrets.ts#SecuritySecrets`) :
 
 ```bash
 npx nodefony security:secrets --write
 # 🔐 Secrets security — 3 étapes, 3 FICHIERS
-# 1. Fichier .env.local — les valeurs
-#    ✓ écrit dans .env.local (NF_TOTP_KEY, NF_WEBHOOK_KEY, NF_CSRF_SECRET)
+# 1. Fichier .env — les valeurs
+#    ✓ écrit dans .env (NF_TOTP_KEY, NF_WEBHOOK_KEY, NF_CSRF_SECRET)
 # 2. Fichier env.ts — la déclaration typée
 # 3. Fichier nodefony.config.ts — le câblage vers le module security
 ```
 
-Elle produit 32 octets aléatoires en base64 (`randomBytes(32)`, `security-secrets.ts:136`) et
+Elle produit 32 octets aléatoires en base64 (`randomBytes(32)`, `security-secrets.ts#SecuritySecrets.generate`) et
 **n'écrase jamais** une valeur existante — une rotation reste un geste manuel et conscient.
 
 ### 2. Déclarer puis câbler la clé
@@ -190,7 +190,7 @@ export default defineConfig<typeof env>((ctx) => ({
 
 ### 3. Les endpoints sont FOURNIS — tu n'écris aucun controller
 
-`mountTotpRoutes()` (`TotpController.ts:154`) monte quatre routes self-service dès que
+`mountTotpRoutes()` (`TotpController.ts#mountTotpRoutes`) monte quatre routes self-service dès que
 `@nodefony/security` est chargé (le service `totp` est alors toujours enregistré). 2FA désactivé, ou
 service non initialisé : elles répondent `503 2FA unavailable` :
 
@@ -202,17 +202,23 @@ service non initialisé : elles répondent `503 2FA unavailable` :
 | `GET /nodefony/security/api/totp/status`   | —          | `{ enabled, pending, recoveryCodesRemaining }` |
 
 Et côté login, deux routes du flux de session BFF (`mountSessionAuthRoutes()`,
-`SessionAuthController.ts:166`) :
+`SessionAuthController.ts#mountSessionAuthRoutes`) :
 
 | Route                                         | Corps                    | Réponse                                    |
 | --------------------------------------------- | ------------------------ | ------------------------------------------ |
 | `POST /nodefony/security/api/auth/login`      | `{ username, password }` | `200` + identité, **ou** `202 mfaRequired` |
 | `POST /nodefony/security/api/auth/login/totp` | `{ code }`               | `200` + identité, `401`, ou `429`          |
 
+Le `202` est un **défi**, pas un succès : `{ mfaRequired: true, methods: [...] }`. La liste
+`methods` est **ouverte** — aujourd'hui `["totp"]` (`MFA_METHOD_TOTP`, exporté par `nodefony`),
+demain une passkey ou un code par courriel s'y ajouteront sans rupture. Un client ne retient que
+les méthodes qu'il sait conduire ; `NodefonyLogin` traite un défi sans aucune méthode connue comme
+une réponse inattendue (erreur `server`), jamais comme un écran de code.
+
 > [!WARNING]
-> Les routes `totp/*` **n'ont pas** `bypassFirewall` (`TotpController.ts:52`) : elles vivent dans la
+> Les routes `totp/*` **n'ont pas** `bypassFirewall` (`TotpController.ts#TotpController`) : elles vivent dans la
 > zone data plane et exigent une session BFF. Le sujet est **toujours** l'utilisateur courant, lu
-> depuis la session (`TotpController.#currentSubject()`, `TotpController.ts:142`) — jamais un
+> depuis la session (`TotpController.#currentSubject()`, `TotpController.ts#TotpController.#currentSubject`) — jamais un
 > paramètre : on n'active ni ne désactive le 2FA d'autrui (anti-IDOR).
 
 ### 4. Ce qu'on observe
@@ -291,18 +297,18 @@ sequenceDiagram
 
 Ce que le code garantit à chaque étape :
 
-- **`beginTotpEnrollment()`** (`totpOperations.ts:72`) écrit le secret **déjà chiffré** avec
+- **`beginTotpEnrollment()`** (`totpOperations.ts#beginTotpEnrollment`) écrit le secret **déjà chiffré** avec
   `confirmedAt: null` — l'état « en attente ». Il est **idempotent** : rappeler l'enrôlement écrase
   simplement le précédent non confirmé (l'utilisateur qui a raté son scan recommence, sans support).
-- **`confirmTotpEnrollment()`** (`totpOperations.ts:112`) refuse si aucun enrôlement n'est en cours
+- **`confirmTotpEnrollment()`** (`totpOperations.ts#confirmTotpEnrollment`) refuse si aucun enrôlement n'est en cours
   ou s'il est déjà confirmé, et **reste en attente** si le code est faux — aucun état intermédiaire
   bancal.
 - Le pas qui a servi à confirmer est marqué **consommé** (`lastUsedStep: res.step`,
-  `totpOperations.ts:142`) : le code de confirmation n'est pas rejouable comme premier code de login.
+  `totpOperations.ts#confirmTotpEnrollment`) : le code de confirmation n'est pas rejouable comme premier code de login.
 
 > [!TIP]
 > Le HTTP ne laisse jamais fuir le détail : code faux, enrôlement absent, ou déjà confirmé donnent
-> tous le **même** `400 Invalid or expired code` (`TotpController.confirm()`, `TotpController.ts:78`).
+> tous le **même** `400 Invalid or expired code` (`TotpController.confirm()`, `TotpController.ts#TotpController.confirm`).
 > La cause fine reste côté serveur.
 
 ### La vérification au login
@@ -334,22 +340,22 @@ sequenceDiagram
   A-->>U: 200 { user }
 ```
 
-Trois propriétés à retenir de `AuthFlow.completeMfaLogin()` (`authFlow.ts:257`) :
+Trois propriétés à retenir de `AuthFlow.completeMfaLogin()` (`authFlow.ts#AuthFlow.completeMfaLogin`) :
 
 1. **Le défi vit en session, pas dans l'URL ni dans un jeton client** — clé `mfa:pending`
-   (`authFlow.ts:18`), posée par le login, **consommée** avant l'ouverture de session
-   (`authFlow.ts:301`).
+   (`authFlow.ts#AuthFlow.completeMfaLogin`), posée par le login, **consommée** avant l'ouverture de session
+   (`authFlow.ts#AuthFlow.completeMfaLogin`).
 2. **Le code à 6 chiffres est throttlé** comme un mot de passe — même backoff partagé
-   (`AuthFlow.#resolveThrottler()`, `authFlow.ts:447`) : 10⁶ combinaisons se forcent brute en
+   (`AuthFlow.#resolveThrottler()`, `authFlow.ts#AuthFlow.#resolveThrottler`) : 10⁶ combinaisons se forcent brute en
    quelques minutes sans lui. Trop de tentatives → `429` + `Retry-After`.
 3. **Un échec ne détruit pas le défi** — l'utilisateur qui s'est trompé de chiffre ressaisit ; il
    n'a pas à refaire son mot de passe.
 
 ### La fenêtre de dérive et l'anti-rejeu
 
-Les deux horloges ne sont jamais parfaitement synchrones. `verifyTotp()` (`totpCrypto.ts:207`)
+Les deux horloges ne sont jamais parfaitement synchrones. `verifyTotp()` (`totpCrypto.ts#verifyTotp`)
 balaie donc les tranches `T-window … T+window` et compare **en temps constant**
-(`timingSafeEqual`, `totpCrypto.ts:227`) — une comparaison naïve fuirait le préfixe correct par le
+(`timingSafeEqual`, `totpCrypto.ts#verifyTotp`) — une comparaison naïve fuirait le préfixe correct par le
 temps de réponse.
 
 | `window` | Tolérance réelle | Codes acceptés simultanément | Verdict                                  |
@@ -359,8 +365,8 @@ temps de réponse.
 | `2`      | ±60 s            | 5                            | Surface d'attaque ×1,7 pour peu de gain. |
 
 Le contrepoids obligatoire, c'est l'**anti-rejeu** : la tranche qui a validé est mémorisée
-(`ITotpSecret.lastUsedStep`, `ITotpSecret.ts:36`), et tout code d'une tranche **≤** à la dernière
-consommée est refusé par la garde `lastUsedStep` (`totpOperations.ts:173`). Un code intercepté —
+(`ITotpSecret.lastUsedStep`, `ITotpSecret.ts#ITotpSecret.lastUsedStep`), et tout code d'une tranche **≤** à la dernière
+consommée est refusé par la garde `lastUsedStep` (`totpOperations.ts#verifyTotpLogin`). Un code intercepté —
 épaule, proxy, phishing en temps réel — est donc **mort dès qu'il a servi une fois**.
 
 > [!WARNING]
@@ -373,52 +379,52 @@ consommée est refusé par la garde `lastUsedStep` (`totpOperations.ts:173`). Un
 
 La valeur de `totp.encryptionKey` est une chaîne d'application : passphrase, hex, base64, longueur
 quelconque. AES-256 exige exactement **32 octets de haute entropie**. `deriveKey()`
-(`secretCipher.ts:54`) passe donc le matériel dans **HKDF-SHA256** (RFC 5869) :
+(`secretCipher.ts#deriveKey`) passe donc le matériel dans **HKDF-SHA256** (RFC 5869) :
 
 - **Déterministe** — tous les pods d'un cluster dérivent la **même** clé du même secret : un secret
   écrit par un pod se relit par les autres, sans réplication de clé.
 - **Séparation de domaine** — chaque brique dérive avec un `salt`/`info` distinct. Le contexte TOTP
-  est figé (`TOTP_DERIVATION`, `totpCipher.ts:23`) : un blob de webhook ne se déchiffre **jamais**
+  est figé (`TOTP_DERIVATION`, `totpCipher.ts#TOTP_DERIVATION`) : un blob de webhook ne se déchiffre **jamais**
   avec la clé TOTP, par construction, même si la clé maître de config est la même.
 - **Longueur libre en entrée** — une passphrase courte ne devient jamais une clé AES faible.
 
 ### Le format du blob
 
-`encryptSecret()` (`secretCipher.ts:77`) produit une chaîne opaque, préfixée par sa version :
+`encryptSecret()` (`secretCipher.ts#encryptSecret`) produit une chaîne opaque, préfixée par sa version :
 
 ```
 gcm1.<base64url( iv‖tag‖ciphertext )>
       └ 12 o ┘└16 o┘
 ```
 
-- **IV de 12 octets tiré à chaque chiffrement** (`secretCipher.ts:30`) — deux enrôlements du même
+- **IV de 12 octets tiré à chaque chiffrement** (`secretCipher.ts#IV_BYTES`) — deux enrôlements du même
   secret donnent deux blobs différents.
 - **GCM = chiffrement authentifié** : le tag de 16 octets fait échouer `decryptSecret()`
-  (`secretCipher.ts:90`) si le blob a été altéré **ou** si la clé est la mauvaise. GCM ne distingue
+  (`secretCipher.ts#decryptSecret`) si le blob a été altéré **ou** si la clé est la mauvaise. GCM ne distingue
   pas les deux cas, par construction — toute manipulation du secret stocké est donc détectée.
 - **Préfixe versionné `gcm1`** : une rotation d'algorithme future pourra cohabiter avec les secrets
   existants.
 
 Le store, lui, ne voit que des octets : il ne déchiffre jamais rien (`ITotpSecret.secretEnc`,
-`ITotpSecret.ts:18`).
+`ITotpSecret.ts#ITotpSecret.secretEnc`).
 
 ### La politique de clé — bruyante en dev, fail-closed en production
 
-`TotpService.#resolveKey()` (`totp.ts:211`) tranche au boot :
+`TotpService.#resolveKey()` (`totp.ts#TotpService.#resolveKey`) tranche au boot :
 
-| Situation                    | Environnement | Comportement                                                 |
-| ---------------------------- | ------------- | ------------------------------------------------------------ |
-| `totp.encryptionKey` fournie | tous          | Clé dérivée HKDF — cas nominal (`totp.ts:214`).              |
-| Clé absente                  | dev / test    | Clé **éphémère** + `WARNING` (`totp.ts:228`).                |
-| Clé absente                  | production    | `CRITIC` + **2FA désactivé** (`totp.ts:220`).                |
-| `store: "memory"` en prod    | production    | `WARNING` — secrets volatils, comptes verrouillés au reboot. |
+| Situation                    | Environnement | Comportement                                                        |
+| ---------------------------- | ------------- | ------------------------------------------------------------------- |
+| `totp.encryptionKey` fournie | tous          | Clé dérivée HKDF — cas nominal (`totp.ts#TotpService.#resolveKey`). |
+| Clé absente                  | dev / test    | Clé **éphémère** + `WARNING` (`totp.ts#TotpService.#resolveKey`).   |
+| Clé absente                  | production    | `CRITIC` + **2FA désactivé** (`totp.ts#TotpService.#resolveKey`).   |
+| `store: "memory"` en prod    | production    | `WARNING` — secrets volatils, comptes verrouillés au reboot.        |
 
 Le refus en production est délibéré : une clé éphémère chiffrerait des secrets **illisibles au
 redémarrage suivant** et sur les autres pods — les utilisateurs seraient enfermés dehors, sans
 message. Mieux vaut un 2FA absent et bruyant qu'un 2FA qui casse silencieusement en pleine nuit.
 
 > [!CAUTION]
-> Ne **jamais** modifier `TOTP_DERIVATION` (`totpCipher.ts:23`). Changer son sel ou son `info` rend
+> Ne **jamais** modifier `TOTP_DERIVATION` (`totpCipher.ts#TOTP_DERIVATION`). Changer son sel ou son `info` rend
 > illisibles **tous** les secrets déjà stockés — chaque utilisateur devra ré-enrôler.
 
 ## Les codes de récupération — perdre son téléphone
@@ -426,24 +432,24 @@ message. Mieux vaut un 2FA absent et bruyant qu'un 2FA qui casse silencieusement
 Un second facteur crée un risque neuf : **s'enfermer dehors**. Les codes de récupération sont la
 sortie de secours — le NIST les classe comme _look-up secrets_ (SP 800-63B §5.1.2).
 
-**Comment ils sont fabriqués** (`generateRecoveryCodes()`, `totpCrypto.ts:330`) :
+**Comment ils sont fabriqués** (`generateRecoveryCodes()`, `totpCrypto.ts#generateRecoveryCodes`) :
 
 - 10 codes par défaut (`totp.recoveryCodes`), au format lisible `XXXXX-XXXXX` ;
-- alphabet **sans caractères ambigus** — ni `I`, ni `L`, ni `O`, ni `U` (`totpCrypto.ts:269`) : on les
+- alphabet **sans caractères ambigus** — ni `I`, ni `L`, ni `O`, ni `U` (`totpCrypto.ts#unbiasedIndices`) : on les
   recopie à la main, souvent sous stress ;
 - ~50 bits d'aléa chacun — non devinable, mais ce n'est **pas** un mot de passe humain.
 
-**Comment ils sont stockés** : en condensat `sha256` (`hashRecoveryCode()`, `totpCrypto.ts:347`),
+**Comment ils sont stockés** : en condensat `sha256` (`hashRecoveryCode()`, `totpCrypto.ts#hashRecoveryCode`),
 jamais en clair. Un `sha256` simple suffit ici, précisément parce que l'entrée est **aléatoire** (une
 attaque par dictionnaire n'a rien à mordre) — contrairement à un mot de passe, qui exige Argon2id.
 
 **Comment ils sont consommés** : au login, si le code présenté n'est pas un TOTP valide,
 `verifyTotpLogin()` cherche une correspondance parmi les condensats — **en temps constant sur chaque
 entrée**, et sans court-circuit à la première trouvaille (`matchRecoveryCode()`,
-`totpCrypto.ts:356`). Le code trouvé est **retiré de la liste** (`totpOperations.ts:186`) : usage
+`totpCrypto.ts#matchRecoveryCode`). Le code trouvé est **retiré de la liste** (`totpOperations.ts#verifyTotpLogin`) : usage
 unique, strictement.
 
-La saisie est tolérante — casse et tirets ignorés à la normalisation (`totpCrypto.ts:272`) :
+La saisie est tolérante — casse et tirets ignorés à la normalisation (`totpCrypto.ts#unbiasedIndices`) :
 `k7m2p9xq4r` vaut `K7M2P-9XQ4R`.
 
 > [!TIP]
@@ -453,20 +459,20 @@ La saisie est tolérante — casse et tirets ignorés à la normalisation (`totp
 
 ## ⚙️ Configuration et mises en situation
 
-La section `totp` du schéma Zod (`config.ts:1144`) — validée au boot, donc une valeur hors bornes
+La section `totp` du schéma Zod (`config.ts#securityConfigSchema`) — validée au boot, donc une valeur hors bornes
 échoue **au démarrage**, pas au premier login :
 
-| Option          | Type                         | Défaut | Effet                                                           |
-| --------------- | ---------------------------- | ------ | --------------------------------------------------------------- |
-| `enabled`       | `boolean`                    | `true` | Coupe le 2FA : service inerte, routes en `503` (`totp.ts:101`). |
-| `issuer`        | `string?`                    | —      | Nom affiché dans l'app d'authentification. Omis = nom de l'app. |
-| `algorithm`     | `"SHA1"\|"SHA256"\|"SHA512"` | `SHA1` | Fonction HMAC. `SHA1` = compat maximale (`config.ts:551`).      |
-| `digits`        | `int` 6–8                    | `6`    | Longueur du code (RFC 4226 §5.3 : 6 minimum).                   |
-| `period`        | `int` > 0                    | `30`   | Durée de vie d'un code, en secondes.                            |
-| `window`        | `int` ≥ 0                    | `1`    | Tolérance de dérive, en pas (`config.ts:572`).                  |
-| `recoveryCodes` | `int` > 0                    | `10`   | Nombre de codes générés à l'activation (`config.ts:580`).       |
-| `encryptionKey` | `string?`                    | —      | Clé de chiffrement du secret au repos (`config.ts:588`).        |
-| `store`         | `string`                     | `auto` | Backend de persistance du secret (`config.ts:594`).             |
+| Option          | Type                         | Défaut | Effet                                                                          |
+| --------------- | ---------------------------- | ------ | ------------------------------------------------------------------------------ |
+| `enabled`       | `boolean`                    | `true` | Coupe le 2FA : service inerte, routes en `503` (`totp.ts#TotpService.#build`). |
+| `issuer`        | `string?`                    | —      | Nom affiché dans l'app d'authentification. Omis = nom de l'app.                |
+| `algorithm`     | `"SHA1"\|"SHA256"\|"SHA512"` | `SHA1` | Fonction HMAC. `SHA1` = compat maximale (`config.ts#totpSchema`).              |
+| `digits`        | `int` 6–8                    | `6`    | Longueur du code (RFC 4226 §5.3 : 6 minimum).                                  |
+| `period`        | `int` > 0                    | `30`   | Durée de vie d'un code, en secondes.                                           |
+| `window`        | `int` ≥ 0                    | `1`    | Tolérance de dérive, en pas (`config.ts#totpSchema`).                          |
+| `recoveryCodes` | `int` > 0                    | `10`   | Nombre de codes générés à l'activation (`config.ts#passkeysSchema`).           |
+| `encryptionKey` | `string?`                    | —      | Clé de chiffrement du secret au repos (`config.ts#totpSchema`).                |
+| `store`         | `string`                     | `auto` | Backend de persistance du secret (`config.ts#passkeysSchema`).                 |
 
 ### Situation 1 — un utilisateur active la 2FA sur son compte
 
@@ -475,7 +481,7 @@ self-service sont déjà là, la console Studio les consomme déjà (`/nodefony/
 
 ```typescript
 use("@nodefony/security", {
-  totp: { encryptionKey: process.env.NF_TOTP_KEY },
+  totp: { encryptionKey: ctx.env.NF_TOTP_KEY },
 });
 ```
 
@@ -492,8 +498,24 @@ Le second facteur validé au login ne dit rien de **qui est devant l'écran dix
 (poste laissé ouvert, session volée). Pour une suppression de compte ou une rotation de clés, on
 redemande le code : c'est le _sudo mode_.
 
-Nodefony fournit le step-up **de login** ; la re-vérification en cours de session, elle, se compose
-dans ton controller à partir du service public `TotpService.verifyLogin()` (`totp.ts:269`) :
+**La voie déclarative** — une étiquette sur la route, qui lit ce que la session a retenu à son
+ouverture (quand, et avec quels moyens) :
+
+```typescript
+import { Post, RequireAuthentication } from "@nodefony/framework";
+
+@Post("/delete")
+@RequireAuthentication({ maxAge: 300, amr: ["otp"] }) // connexion < 5 min, avec le code
+async remove() { … }
+```
+
+Une connexion trop ancienne ou sans le code reçoit un **401** dont le `WWW-Authenticate` porte
+`error="insufficient_user_authentication"` (RFC 9470) : le client redemande une connexion — mot de
+passe puis code — et rejoue l'action. Évaluée APRÈS `@IsGranted` : un rôle absent reste un 403.
+Une session qui ne dit pas comment elle a été ouverte est refusée.
+
+**La voie composée** — quand le code doit être saisi DANS l'action, sans repasser par la page de
+connexion, à partir du service public `TotpService.verifyLogin()` (`totp.ts#TotpService.verifyLogin`) :
 
 ```typescript
 import { controller, Controller, Post } from "@nodefony/framework";
@@ -504,7 +526,7 @@ class DangerController extends Controller {
   @Post("/delete")
   async remove() {
     const totp = this.get<TotpService>("totp");
-    const code = (this.queryPost as { code?: unknown }).code;
+    const code = (this.body as { code?: unknown }).code;
     // Zone protégée : le firewall a déjà authentifié. On exige la PREUVE FRAÎCHE.
     if (!totp?.isEnabled() || typeof code !== "string") {
       return this.renderJson({ error: "2FA required" }, 403);
@@ -535,7 +557,7 @@ totp: { algorithm: "SHA512", digits: 8 },   // ❌ Google Authenticator ignore c
 ```
 
 L'URI `otpauth://` transporte bien `algorithm` et `digits` (`buildOtpauthUri()`,
-`totpCrypto.ts:253`), mais plusieurs applications grand public les **ignorent** et calculent en
+`totpCrypto.ts#buildOtpauthUri`), mais plusieurs applications grand public les **ignorent** et calculent en
 `SHA1`/6 chiffres. Résultat : le QR est scanné, l'app affiche un code… systématiquement refusé, sans
 que rien ne semble anormal. Le gain de sécurité réel est par ailleurs nul — l'anti-rejeu et le
 throttle bornent déjà les tentatives bien avant l'espace des codes.
@@ -543,10 +565,23 @@ throttle bornent déjà les tentatives bien avant l'espace des codes.
 ## L'entité de persistance — un secret par utilisateur
 
 Le modèle est volontairement minimal : **clé naturelle = `userId`**, `save` est un upsert
-(`ITotpSecretStore`, `ITotpSecretStore.ts:69`). Pas d'identifiant de ligne, pas d'index secondaire —
+(`ITotpSecretStore`, `ITotpSecretStore.ts#ITotpSecretStore`). Pas d'identifiant de ligne, pas d'index secondaire —
 tout accès passe par la clé primaire.
 
-Spécification logique de la table (`TOTP_SECRET_TABLE_SPEC`, `totpSecretEntity.ts:36`), déclinée par
+**`userId` vaut `IUser.identifier`, jamais `IUser.id`** — la même clé que la session et les jetons,
+et elle est immuable. Les deux sont des chaînes : un appelant qui passe l'`id` ne se fait pas
+refuser, il vise une clé vide et reçoit un succès qui n'a rien touché. Le plan d'administration,
+qui adresse les comptes par leur `id`, traduit donc d'abord l'`id` en `identifier`
+(`resolveSubject`, `SecurityAdminApi.ts#resolveSubject`).
+
+**Le secret disparaît avec le compte.** Supprimer un compte (plan d'administration ou
+`security:user:delete`) passe par `UserService.delete`, qui émet `onUserRevoked`
+(`reason: "deleted"`) ; la cascade retire le secret
+TOTP et les passkeys (`cascadeUserRevocation`, `userRevocationCascade.ts#cascadeUserRevocation`). Sans elle, un compte
+recréé sous le même identifiant hériterait du second facteur de l'ancien titulaire. Un compte
+seulement désactivé ou verrouillé garde ses facteurs.
+
+Spécification logique de la table (`TOTP_SECRET_TABLE_SPEC`, `totpSecretEntity.ts#TOTP_SECRET_TABLE_SPEC`), déclinée par
 dialecte via le colKit :
 
 | Colonne         | Rôle                                            | SQLite             | PostgreSQL | MySQL / MariaDB |
@@ -565,18 +600,18 @@ dialecte via le colKit :
 Deux pièges de lecture, signalés dans l'entité elle-même :
 
 - `lastUsedStep` est un **numéro de tranche RFC 6238**, pas un horodatage — d'où le type `int`
-  partout, quand les vraies dates sont en `epochMs` (`totpSecretEntity.ts:61`).
+  partout, quand les vraies dates sont en `epochMs` (`totpSecretEntity.ts#TotpSecretRow.algorithm`).
 - Un epoch en millisecondes **déborde** un `integer` 32 bits → `bigint` en PostgreSQL et MySQL
   (SQLite, lui, a des INTEGER 64 bits).
 
 ### Les backends disponibles
 
-| Backend    | Enregistré par                                | Durabilité                          | État                 |
-| ---------- | --------------------------------------------- | ----------------------------------- | -------------------- |
-| `memory`   | builtin (`totpSecretStoreRegistry.ts:54`)     | **volatile** — perdu au redémarrage | ✅ dev / tests       |
-| `drizzle`  | `@nodefony/drizzle` (`registerStores.ts:320`) | durable, partagé entre pods         | ✅ 3 dialectes SQL   |
-| `mongoose` | `@nodefony/mongoose` (`registerStores.ts`)    | durable, partagé entre pods         | ✅ MongoDB           |
-| `redis`    | —                                             | —                                   | ⏳ manquant, à venir |
+| Backend    | Enregistré par                                                           | Durabilité                          | État                 |
+| ---------- | ------------------------------------------------------------------------ | ----------------------------------- | -------------------- |
+| `memory`   | builtin (`totpSecretStoreRegistry.ts`)                                   | **volatile** — perdu au redémarrage | ✅ dev / tests       |
+| `drizzle`  | `@nodefony/drizzle` (`registerStores.ts#registerDrizzleFrameworkStores`) | durable, partagé entre pods         | ✅ 3 dialectes SQL   |
+| `mongoose` | `@nodefony/mongoose` (`registerStores.ts`)                               | durable, partagé entre pods         | ✅ MongoDB           |
+| `redis`    | —                                                                        | —                                   | ⏳ manquant, à venir |
 
 Une application peut donc activer le 2FA **entièrement sur MongoDB**, sans charger d'ORM SQL : une
 application choisit son ORM, elle ne choisit pas de se passer du second facteur.
@@ -597,12 +632,12 @@ primaire (`_id` = `userId`) — donc l'unicité existe dès le premier document,
 en tâche de fond.
 
 Côté `drizzle`, les **trois dialectes** sont portés — `TOTP_PORTED` vaut l'ensemble des dialectes
-(`registerStores.ts:94`) : SQLite, PostgreSQL, MySQL/MariaDB. Le store n'écrit **aucun SQL natif**,
-tout passe par le contrat `IRepository` (`DrizzleTotpSecretStore`, `DrizzleTotpSecretStore.ts:44`)
+(`registerStores.ts#TOTP_PORTED`) : SQLite, PostgreSQL, MySQL/MariaDB. Le store n'écrit **aucun SQL natif**,
+tout passe par le contrat `IRepository` (`DrizzleTotpSecretStore`, `DrizzleTotpSecretStore.ts#DrizzleTotpSecretStore`)
 — c'est ce qui rend la portabilité gratuite.
 
 **Comment le backend est choisi.** `store: "auto"` (le défaut) suit l'infra déclarée puis les
-adapters réellement chargés (`TotpService.#resolveStore()`, `totp.ts:137`) :
+adapters réellement chargés (`TotpService.#resolveStore()`, `totp.ts#TotpService.#resolveStore`) :
 
 1. `NF_STORE` (override global de banc de charge), s'il est enregistré ici ;
 2. infra base de données déclarée (`NF_DATABASE_URL`) → `drizzle` ;
@@ -610,7 +645,7 @@ adapters réellement chargés (`TotpService.#resolveStore()`, `totp.ts:137`) :
 4. sinon **repli `memory`, annoncé** — jamais silencieux.
 
 Un `store` **explicite** introuvable, en revanche, ne se replie pas : `CRITIC` en dev, boot avorté en
-production (`totp.ts:174`). Une faute de frappe ne dégrade jamais la sécurité en douce.
+production (`totp.ts#TotpService.#resolveStore`). Une faute de frappe ne dégrade jamais la sécurité en douce.
 
 ## Le listing paginé des enrôlements
 
@@ -618,48 +653,48 @@ Question d'exploitation : « quelle est la **couverture** 2FA, et qui est resté
 confirmation ? » Un secret jamais confirmé ne protège personne, et c'est invisible depuis la fiche
 d'un seul utilisateur.
 
-`ITotpSecretStore.listPage()` (`ITotpSecretStore.ts:85`) répond, avec trois garanties :
+`ITotpSecretStore.listPage()` (`ITotpSecretStore.ts#ITotpSecretStore.listPage`) répond, avec trois garanties :
 
 - **pagination native au store** — jamais de parcours complet en mémoire ; l'ordre est contractuel
   (`createdAt` DESC, départagé par `userId` ASC) ;
 - **filtres appliqués côté backend** — `confirmed` (activés / en attente) et `q` (préfixe d'`userId`,
-  donc indexable : le critère `$like` est **ancré à gauche**, `DrizzleTotpSecretStore.ts:176`) ;
-- **la vue ne peut pas porter de secret** — `ITotpEnrollmentSummary` (`ITotpSecretStore.ts:16`)
+  donc indexable : le critère `$like` est **ancré à gauche**, `DrizzleTotpSecretStore.ts#DrizzleTotpSecretStore.#listCriteria`) ;
+- **la vue ne peut pas porter de secret** — `ITotpEnrollmentSummary` (`ITotpSecretStore.ts#ITotpEnrollmentSummary`)
   n'a ni `secretEnc` ni les condensats de récupération, seulement leur **nombre**
   (`recoveryCodesLeft`).
 
 Ce dernier point est une garantie **de contrat**, pas une redaction faite à l'affichage : quel que
 soit le backend, ces champs ne peuvent pas remonter par ce chemin, même si un appelant les demandait
-(`toTotpEnrollment()`, `MemoryTotpSecretStore.ts:19`). C'est ce qu'exerce le banc de contrat partagé.
+(`toTotpEnrollment()`, `MemoryTotpSecretStore.ts#toTotpEnrollment`). C'est ce qu'exerce le banc de contrat partagé.
 
-`countEnrollments()` (`ITotpSecretStore.ts:90`) donne le KPI de couverture sans énumérer une seule
+`countEnrollments()` (`ITotpSecretStore.ts#ITotpSecretStore.countEnrollments`) donne le KPI de couverture sans énumérer une seule
 ligne.
 
 ## 🧰 API publique
 
 Tout est exporté depuis `@nodefony/security` — signatures complètes dans `.ai/symbols.json`.
 
-**Le service** (`TotpService`, `totp.ts:74`), résolu par nom dans le container (`"totp"`) :
+**Le service** (`TotpService`, `totp.ts#TotpService`), résolu par nom dans le container (`"totp"`) :
 
-| Méthode                               | Rôle                                                         |
-| ------------------------------------- | ------------------------------------------------------------ |
-| `isEnabled()` (`totp.ts:254`)         | 2FA opérationnel (activé en config **et** boot réussi).      |
-| `beginEnrollment()` (`totp.ts:259`)   | Démarre l'enrôlement → secret + URI `otpauth://`, 1×.        |
-| `confirmEnrollment()` (`totp.ts:264`) | Confirme par un 1ᵉʳ code → active + codes de récupération.   |
-| `verifyLogin()` (`totp.ts:269`)       | Vérifie un code TOTP **ou** de récupération. Ne lève jamais. |
-| `disable()` (`totp.ts:274`)           | Retire secret et codes.                                      |
-| `status()` (`totp.ts:279`)            | `{ enabled, pending, recoveryCodesRemaining }`.              |
-| `isEnabledFor()` (`totp.ts:306`)      | Raccourci du flux de login (`false` si le 2FA est inerte).   |
-| `listPage()` (`totp.ts:290`)          | Page d'enrôlements (data plane admin).                       |
-| `countEnrollments()` (`totp.ts:301`)  | Compte filtré, sans énumération.                             |
+| Méthode                                                         | Rôle                                                         |
+| --------------------------------------------------------------- | ------------------------------------------------------------ |
+| `isEnabled()` (`totp.ts#TotpService.isEnabled`)                 | 2FA opérationnel (activé en config **et** boot réussi).      |
+| `beginEnrollment()` (`totp.ts#TotpService.beginEnrollment`)     | Démarre l'enrôlement → secret + URI `otpauth://`, 1×.        |
+| `confirmEnrollment()` (`totp.ts#TotpService.confirmEnrollment`) | Confirme par un 1ᵉʳ code → active + codes de récupération.   |
+| `verifyLogin()` (`totp.ts#TotpService.verifyLogin`)             | Vérifie un code TOTP **ou** de récupération. Ne lève jamais. |
+| `disable()` (`totp.ts#TotpService.disable`)                     | Retire secret et codes.                                      |
+| `status()` (`totp.ts#TotpService.status`)                       | `{ enabled, pending, recoveryCodesRemaining }`.              |
+| `isEnabledFor()` (`totp.ts#TotpService.isEnabledFor`)           | Raccourci du flux de login (`false` si le 2FA est inerte).   |
+| `listPage()` (`totp.ts#TotpService.listPage`)                   | Page d'enrôlements (data plane admin).                       |
+| `countEnrollments()` (`totp.ts#TotpService.countEnrollments`)   | Compte filtré, sans énumération.                             |
 
 **Les opérations pures**, si tu veux le 2FA **sans** le service (test, script, autre transport) —
 elles prennent leurs dépendances en argument : `beginTotpEnrollment()`, `confirmTotpEnrollment()`,
-`verifyTotpLogin()`, `disableTotp()`, `totpStatus()` (`totpOperations.ts:200`).
+`verifyTotpLogin()`, `disableTotp()`, `totpStatus()` (`totpOperations.ts#totpStatus`).
 
 **Les primitives crypto**, pour écrire un client ou un banc de test : `totpCode()`
-(`totpCrypto.ts:174`), `base32Decode()` (`totpCrypto.ts:81`), `deriveTotpKey()`
-(`totpCipher.ts:33`).
+(`totpCrypto.ts#totpCode`), `base32Decode()` (`totpCrypto.ts#base32Decode`), `deriveTotpKey()`
+(`totpCipher.ts#deriveTotpKey`).
 
 ```typescript
 // Calculer le code attendu côté « application d'authentification » — exactement
@@ -671,7 +706,7 @@ const code = totpCode(base32Decode(secretBase32), { epochMs: Date.now() });
 ## 🧩 Extension — brancher son propre store
 
 Le registre découple le cœur du backend : implémente `ITotpSecretStore`
-(`ITotpSecretStore.ts:69`), enregistre la fabrique, sélectionne-la en config.
+(`ITotpSecretStore.ts#ITotpSecretStore`), enregistre la fabrique, sélectionne-la en config.
 
 ```typescript
 import { registerTotpStore, type ITotpSecretStore } from "@nodefony/security";
@@ -689,19 +724,19 @@ vérifie que ta projection n'expose ni secret ni condensat.
 
 ## 📜 Normes appliquées
 
-| Domaine                     | Norme                    | Ancrage dans le code                                   |
-| --------------------------- | ------------------------ | ------------------------------------------------------ |
-| TOTP (algorithme)           | RFC 6238 §4              | `totpCode()` (`totpCrypto.ts:174`)                     |
-| HOTP + troncature dynamique | RFC 4226 §5.3            | `hotp()` (`totpCrypto.ts:129`), masque `0x7f` (`:141`) |
-| Taille du secret (≥ 128 b)  | RFC 4226 R6              | `TOTP_DEFAULTS.secretBytes` = 20 (`totpCrypto.ts:33`)  |
-| Fenêtre de dérive           | RFC 6238 §5.2            | `verifyTotp()` (`totpCrypto.ts:207`)                   |
-| Anti-rejeu du code          | RFC 6238 §5.2            | garde `lastUsedStep` (`totpOperations.ts:173`)         |
-| Encodage du secret          | RFC 4648 (base32)        | `base32Encode()` (`totpCrypto.ts:58`)                  |
-| Dérivation de clé           | RFC 5869 (HKDF)          | `deriveKey()` (`secretCipher.ts:54`)                   |
-| Nonce GCM 96 bits           | NIST SP 800-38D §5.2.1.1 | `IV_BYTES` (`secretCipher.ts:30`)                      |
-| Codes de secours            | NIST SP 800-63B §5.1.2   | `generateRecoveryCodes()` (`totpCrypto.ts:330`)        |
-| Backoff des tentatives      | NIST SP 800-63B          | `AuthFlow.completeMfaLogin()` (`authFlow.ts:257`)      |
-| Rate limit (429)            | RFC 6585                 | `429` + `Retry-After` (`SessionAuthController.ts:145`) |
+| Domaine                     | Norme                    | Ancrage dans le code                                                        |
+| --------------------------- | ------------------------ | --------------------------------------------------------------------------- |
+| TOTP (algorithme)           | RFC 6238 §4              | `totpCode()` (`totpCrypto.ts#totpCode`)                                     |
+| HOTP + troncature dynamique | RFC 4226 §5.3            | `hotp()` (`totpCrypto.ts#hotp`), masque `0x7f` (`totpCrypto.ts#hotp`)       |
+| Taille du secret (≥ 128 b)  | RFC 4226 R6              | `TOTP_DEFAULTS.secretBytes` = 20 (`totpCrypto.ts#TOTP_DEFAULTS`)            |
+| Fenêtre de dérive           | RFC 6238 §5.2            | `verifyTotp()` (`totpCrypto.ts#verifyTotp`)                                 |
+| Anti-rejeu du code          | RFC 6238 §5.2            | garde `lastUsedStep` (`totpOperations.ts#verifyTotpLogin`)                  |
+| Encodage du secret          | RFC 4648 (base32)        | `base32Encode()` (`totpCrypto.ts#base32Encode`)                             |
+| Dérivation de clé           | RFC 5869 (HKDF)          | `deriveKey()` (`secretCipher.ts#deriveKey`)                                 |
+| Nonce GCM 96 bits           | NIST SP 800-38D §5.2.1.1 | `IV_BYTES` (`secretCipher.ts#IV_BYTES`)                                     |
+| Codes de secours            | NIST SP 800-63B §5.1.2   | `generateRecoveryCodes()` (`totpCrypto.ts#generateRecoveryCodes`)           |
+| Backoff des tentatives      | NIST SP 800-63B          | `AuthFlow.completeMfaLogin()` (`authFlow.ts#AuthFlow.completeMfaLogin`)     |
+| Rate limit (429)            | RFC 6585                 | `429` + `Retry-After` (`SessionAuthController.ts#SessionAuthController.me`) |
 
 Les **vecteurs de test de la RFC 6238 (Appendix B)** sont rejoués en test sur les trois fonctions de
 hachage — c'est la preuve d'interopérabilité, pas une auto-évaluation.
@@ -710,18 +745,18 @@ hachage — c'est la preuve d'interopérabilité, pas une auto-évaluation.
 
 Le 2FA est un chemin **froid** : il ne coûte rien tant qu'on ne se connecte pas.
 
-- **Sur le login nominal** (2FA absent ou désactivé) : `AuthFlow.#resolveTotp()` (`authFlow.ts:458`)
+- **Sur le login nominal** (2FA absent ou désactivé) : `AuthFlow.#resolveTotp()` (`authFlow.ts#AuthFlow.#resolveTotp`)
   résout le service **une seule fois** puis met le résultat en cache. Service absent ⇒ `null` ⇒
   **zéro accès au store**, zéro allocation par login.
 - **Aucun coût par requête** : le TOTP n'est pas un authenticator du firewall, il ne s'exécute donc
   jamais dans le pipeline HTTP/WS.
 - **Allocation paresseuse du store** : la `Map` de `MemoryTotpSecretStore`
-  (`MemoryTotpSecretStore.ts:74`) n'existe que si le 2FA est activé — le service ne construit rien
-  quand `totp.enabled` est `false` (`totp.ts:101`).
+  (`MemoryTotpSecretStore.ts#MemoryTotpSecretStore.#byUser`) n'existe que si le 2FA est activé — le service ne construit rien
+  quand `totp.enabled` est `false` (`totp.ts#TotpService.#build`).
 - **Le coût réel d'une vérification** : ≤ `2·window + 1` HMAC (3 par défaut) + un déchiffrement
   AES-GCM. De l'ordre de la microseconde — négligeable devant le hachage Argon2id du mot de passe
   qui l'a précédé.
-- **Arrêt propre** : si le store sait se vider sur disque, `TotpService.#shutdown()` (`totp.ts:241`)
+- **Arrêt propre** : si le store sait se vider sur disque, `TotpService.#shutdown()` (`totp.ts#TotpService.#shutdown`)
   le déclenche à `onTerminate` — aucune écriture en attente perdue.
 
 ## 📡 Observabilité — Studio
@@ -735,37 +770,43 @@ Le 2FA est un chemin **froid** : il ne coûte rien tant qu'on ne se connecte pas
 
 Le data plane admin correspondant, gardé par `ROLE_NODEFONY_ADMIN` :
 
-- `GET /nodefony/security/api/totp/list` — couverture 2FA paginée (`SecurityAdminApi.ts:636`).
+- `GET /nodefony/security/api/totp/list` — couverture 2FA paginée, `?q=` = préfixe d'`userId`
+  (`SecurityAdminApi.ts#createSecurityAdminApi`).
   Réponse **honnête** si le 2FA est désactivé : `{ enabled: false, items: [] }`, jamais une erreur —
   la console doit pouvoir afficher « 2FA désactivé ».
-- `GET /nodefony/security/api/users/{id}/totp` — statut d'un utilisateur (`SecurityAdminApi.ts:686`).
+- `GET /nodefony/security/api/users/{id}/totp` — statut d'un utilisateur (`SecurityAdminApi.ts#createSecurityAdminApi`).
 - `POST /nodefony/security/api/users/{id}/totp/disable` — reset admin, **audité**
-  (`SecurityAdminApi.ts:711`).
+  (`SecurityAdminApi.ts#createSecurityAdminApi`).
+
+Ces deux routes répondent `503` si le service `users` manque : sans lui, l'`id` ne se traduit pas en
+clé de sujet, et agir quand même rendrait un faux succès.
 
 L'admin peut **désactiver**, jamais **activer** pour autrui : le secret se scanne sur l'appareil de
 l'utilisateur, lui seul peut l'armer.
 
-Côté journal d'audit, quatre actions tracent le cycle : `login.mfa_required` (`authFlow.ts:177`),
-`login.success` avec `reason: "totp"` ou `"recovery"` (`authFlow.ts:232`), `login.failure` avec
-`reason: "mfa_invalid"` (`authFlow.ts:291`), et `user.totp_disabled` côté admin
-(`SecurityAdminApi.ts:735`).
+Côté journal d'audit, cinq actions tracent le cycle : `login.mfa_required` (`authFlow.ts#AuthFlow.login`),
+`login.success` avec `reason: "totp"` ou `"recovery"` (`authFlow.ts#AuthFlow.login`), `login.failure` avec
+`reason: "mfa_invalid"` (`authFlow.ts#AuthFlow.completeMfaLogin`), `user.totp_enabled` quand le titulaire active son
+facteur (`totp.ts#TotpService.confirmEnrollment`), et `user.totp_disabled` — par le titulaire (`totp.ts#TotpService.disable`,
+`viaAdmin: false`) ou par un administrateur (`SecurityAdminApi.ts#createSecurityAdminApi`, `viaAdmin: true`). Les
+deux gestes du titulaire portent l'IP, le navigateur et l'identifiant de la requête.
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
-| Symptôme                                          | Cause (dans le code)                                                 | Correction                                                         |
-| ------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| 2FA inactif en production, `CRITIC` au boot       | `totp.encryptionKey` absente — fail-closed (`totp.ts:220`)           | `npx nodefony security:secrets`, puis câbler `ctx.env.NF_TOTP_KEY` |
-| Tous les secrets illisibles après déploiement     | Clé éphémère (dev) ou `TOTP_DERIVATION` modifié                      | Clé **stable** partagée ; ne jamais toucher au contexte HKDF       |
-| Secrets perdus à chaque redémarrage               | Store résolu en `memory` (aucun adapter durable chargé)              | Charger `@nodefony/drizzle` ou déclarer `NF_DATABASE_URL`          |
-| Code « juste » systématiquement refusé            | Horloge décalée de plus d'un pas (fenêtre = ±30 s)                   | Synchroniser NTP serveur **et** téléphone                          |
-| Le QR est scanné mais aucun code ne passe         | `digits`/`algorithm` non standard, ignorés par l'app                 | Rester en `SHA1` / 6 chiffres                                      |
-| `202` au login au lieu de `200`                   | Comportement **attendu** : second facteur requis                     | Enchaîner sur `POST …/auth/login/totp`                             |
-| `401` sur `…/auth/me` juste après le mot de passe | L'identité n'est posée qu'après le 2ᵉ facteur (`authFlow.ts:170`)    | Terminer le step-up                                                |
-| `429` pendant la saisie du code                   | Throttle NIST dans `AuthFlow.completeMfaLogin()` (`authFlow.ts:257`) | Respecter `Retry-After` — attendu sous attaque                     |
-| `503 2FA unavailable` sur `…/totp/*`              | Service absent ou `isEnabled()` faux (`TotpController.ts:21`)        | Vérifier `totp.enabled` + la clé + les logs de boot                |
-| Utilisateur bloqué, plus aucun code               | Codes de récupération épuisés                                        | Reset admin via `…/users/{id}/totp/disable`, puis ré-enrôlement    |
-| Même code accepté deux fois                       | Impossible — anti-rejeu `lastUsedStep` (`totpOperations.ts:173`)     | —                                                                  |
-| Code de récupération réutilisable                 | Impossible — retiré du stock à l'usage (`totpOperations.ts:186`)     | Régénérer un lot en ré-enrôlant si le stock est bas                |
+| Symptôme                                                      | Cause (dans le code)                                                                       | Correction                                                         |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| 2FA inactif en production, `CRITIC` au boot                   | `totp.encryptionKey` absente — fail-closed (`totp.ts#TotpService.#resolveKey`)             | `npx nodefony security:secrets`, puis câbler `ctx.env.NF_TOTP_KEY` |
+| Tous les secrets illisibles après déploiement                 | Clé éphémère (dev) ou `TOTP_DERIVATION` modifié                                            | Clé **stable** partagée ; ne jamais toucher au contexte HKDF       |
+| Secrets perdus à chaque redémarrage                           | Store résolu en `memory` (aucun adapter durable chargé)                                    | Charger `@nodefony/drizzle` ou déclarer `NF_DATABASE_URL`          |
+| Code « juste » systématiquement refusé                        | Horloge décalée de plus d'un pas (fenêtre = ±30 s)                                         | Synchroniser NTP serveur **et** téléphone                          |
+| Le QR est scanné mais aucun code ne passe                     | `digits`/`algorithm` non standard, ignorés par l'app                                       | Rester en `SHA1` / 6 chiffres                                      |
+| `202` au login au lieu de `200`                               | Comportement **attendu** : second facteur requis                                           | Enchaîner sur `POST …/auth/login/totp`                             |
+| `…/auth/me` rend `{ user: null }` juste après le mot de passe | L'identité n'est posée qu'après le 2ᵉ facteur (`authFlow.ts#AuthFlow.login`)               | Terminer le step-up                                                |
+| `429` pendant la saisie du code                               | Throttle NIST dans `AuthFlow.completeMfaLogin()` (`authFlow.ts#AuthFlow.completeMfaLogin`) | Respecter `Retry-After` — attendu sous attaque                     |
+| `503 2FA unavailable` sur `…/totp/*`                          | Service absent ou `isEnabled()` faux (`TotpController.ts#ITotpManager.isEnabled`)          | Vérifier `totp.enabled` + la clé + les logs de boot                |
+| Utilisateur bloqué, plus aucun code                           | Codes de récupération épuisés                                                              | Reset admin via `…/users/{id}/totp/disable`, puis ré-enrôlement    |
+| Même code accepté deux fois                                   | Impossible — anti-rejeu `lastUsedStep` (`totpOperations.ts#verifyTotpLogin`)               | —                                                                  |
+| Code de récupération réutilisable                             | Impossible — retiré du stock à l'usage (`totpOperations.ts#verifyTotpLogin`)               | Régénérer un lot en ré-enrôlant si le stock est bas                |
 
 ## 🧪 Tests & couverture