@nodefony/security 10.0.0-beta.1 → 10.0.0-beta.3

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:142`).
 
 ## 📖 Lexique
 
@@ -125,14 +125,14 @@ 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:297`). 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:79`). 2FA désactivé
 > ⇒ service absent ⇒ le login nominal **ne paie strictement rien** (`AuthFlow.#resolveTotp()`,
-> `authFlow.ts:458`).
+> `authFlow.ts:642`).
 
 ## 🚀 Démarrage rapide
 
@@ -148,13 +148,13 @@ illisibles au redémarrage). La commande la génère et te dit exactement où la
 ```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:156`) et
 **n'écrase jamais** une valeur existante — une rotation reste un geste manuel et conscient.
 
 ### 2. Déclarer puis câbler la clé
@@ -190,8 +190,9 @@ 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, **et seulement si**
-le service `totp` existe (security chargé + 2FA activé) — sinon zéro surface, 404 :
+`mountTotpRoutes()` (`TotpController.ts:161`) 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` :
 
 | Route                                      | Corps      | Réponse                                        |
 | ------------------------------------------ | ---------- | ---------------------------------------------- |
@@ -201,17 +202,23 @@ le service `totp` existe (security chargé + 2FA activé) — sinon zéro surfac
 | `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:214`) :
 
 | 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
 > zone data plane et exigent une session BFF. Le sujet est **toujours** l'utilisateur courant, lu
-> depuis la session (`TotpController.#currentSubject()`, `TotpController.ts:138`) — jamais un
+> depuis la session (`TotpController.#currentSubject()`, `TotpController.ts:145`) — jamais un
 > paramètre : on n'active ni ne désactive le 2FA d'autrui (anti-IDOR).
 
 ### 4. Ce qu'on observe
@@ -301,7 +308,7 @@ Ce que le code garantit à chaque étape :
 
 > [!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:82`).
 > La cause fine reste côté serveur.
 
 ### La vérification au login
@@ -333,13 +340,13 @@ 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:297`) :
 
 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:283`), posée par le login, **consommée** avant l'ouverture de session
    (`authFlow.ts:301`).
 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:630`) : 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.
@@ -452,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:1461`) — 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 non montées (`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: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:618`).      |
+| `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:639`).                  |
+| `recoveryCodes` | `int` > 0                    | `10`   | Nombre de codes générés à l'activation (`config.ts:586`).       |
+| `encryptionKey` | `string?`                    | —      | Clé de chiffrement du secret au repos (`config.ts:655`).        |
+| `store`         | `string`                     | `auto` | Backend de persistance du secret (`config.ts:595`).             |
 
 ### Situation 1 — un utilisateur active la 2FA sur son compte
 
@@ -491,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:300`) :
 
 ```typescript
 import { controller, Controller, Post } from "@nodefony/framework";
@@ -542,9 +565,22 @@ 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:75`). Pas d'identifiant de ligne, pas d'index secondaire —
 tout accès passe par la clé primaire.
 
+**`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:270`).
+
+**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:51`). 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:36`), déclinée par
 dialecte via le colKit :
 
@@ -631,7 +667,7 @@ Ce dernier point est une garantie **de contrat**, pas une redaction faite à l'a
 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é.
 
-`countEnrollments()` (`ITotpSecretStore.ts:90`) donne le KPI de couverture sans énumérer une seule
+`countEnrollments()` (`ITotpSecretStore.ts:96`) donne le KPI de couverture sans énumérer une seule
 ligne.
 
 ## 🧰 API publique
@@ -645,12 +681,12 @@ Tout est exporté depuis `@nodefony/security` — signatures complètes dans `.a
 | `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.                             |
+| `verifyLogin()` (`totp.ts:300`)       | Vérifie un code TOTP **ou** de récupération. Ne lève jamais. |
+| `disable()` (`totp.ts:316`)           | Retire secret et codes.                                      |
+| `status()` (`totp.ts:331`)            | `{ enabled, pending, recoveryCodesRemaining }`.              |
+| `isEnabledFor()` (`totp.ts:358`)      | Raccourci du flux de login (`false` si le 2FA est inerte).   |
+| `listPage()` (`totp.ts:342`)          | Page d'enrôlements (data plane admin).                       |
+| `countEnrollments()` (`totp.ts:353`)  | 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()`,
@@ -688,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: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:297`)          |
+| Rate limit (429)            | RFC 6585                 | `429` + `Retry-After` (`SessionAuthController.ts:164-172`) |
 
 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.
@@ -709,7 +745,7 @@ 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:642`)
   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
@@ -734,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:601`).
   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:748`).
 - `POST /nodefony/security/api/users/{id}/totp/disable` — reset admin, **audité**
-  (`SecurityAdminApi.ts:711`).
+  (`SecurityAdminApi.ts:767`).
+
+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`),
+Côté journal d'audit, cinq 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`).
+`reason: "mfa_invalid"` (`authFlow.ts:291`), `user.totp_enabled` quand le titulaire active son
+facteur (`totp.ts:290`), et `user.totp_disabled` — par le titulaire (`totp.ts:321`,
+`viaAdmin: false`) ou par un administrateur (`SecurityAdminApi.ts:789`, `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: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`                             |
+| `…/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:170`)    | Terminer le step-up                                                |
+| `429` pendant la saisie du code                               | Throttle NIST dans `AuthFlow.completeMfaLogin()` (`authFlow.ts:297`) | 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                |
 
 ## 🧪 Tests & couverture