@nodefony/security 10.0.0-alpha.8 → 10.0.0-beta.1

package/docs/totp.md

@@ -110,9 +110,9 @@ 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:71`)
+**1. La logique est PURE, le service n'est qu'une prise de courant.** `TotpService` (`totp.ts:74`)
 résout au boot deux choses seulement : le **store** de secrets et la **clé de chiffrement**
-(`TotpService.#build()`, `totp.ts:89`). Tout le reste — enrôler, confirmer, vérifier — vit dans des
+(`TotpService.#build()`, `totp.ts:92`). 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
 serveur, sans base, avec une horloge injectée** — et c'est pour ça qu'elle est couverte à ~100 %.
@@ -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:254`). Même dessin que
+passe et l'ouverture de session (`AuthFlow.completeMfaLogin()`, `authFlow.ts:257`). 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é
 > ⇒ service absent ⇒ le login nominal **ne paie strictement rien** (`AuthFlow.#resolveTotp()`,
-> `authFlow.ts:455`).
+> `authFlow.ts:458`).
 
 ## 🚀 Démarrage rapide
 
@@ -143,7 +143,7 @@ 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:36`) :
+(`nodefony security:secrets`, `security-secrets.ts:79`) :
 
 ```bash
 npx nodefony security:secrets --write
@@ -154,7 +154,7 @@ npx nodefony security:secrets --write
 # 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:122`) et
+Elle produit 32 octets aléatoires en base64 (`randomBytes(32)`, `security-secrets.ts:136`) et
 **n'écrase jamais** une valeur existante — une rotation reste un geste manuel et conscient.
 
 ### 2. Déclarer puis câbler la clé
@@ -301,7 +301,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:97`).
+> tous le **même** `400 Invalid or expired code` (`TotpController.confirm()`, `TotpController.ts:78`).
 > La cause fine reste côté serveur.
 
 ### La vérification au login
@@ -333,13 +333,13 @@ sequenceDiagram
   A-->>U: 200 { user }
 ```
 
-Trois propriétés à retenir de `AuthFlow.completeMfaLogin()` (`authFlow.ts:254`) :
+Trois propriétés à retenir de `AuthFlow.completeMfaLogin()` (`authFlow.ts:257`) :
 
 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:298`).
+   (`authFlow.ts:301`).
 2. **Le code à 6 chiffres est throttlé** comme un mot de passe — même backoff partagé
-   (`AuthFlow.#resolveThrottler()`, `authFlow.ts:264`) : 10⁶ combinaisons se forcent brute en
+   (`AuthFlow.#resolveThrottler()`, `authFlow.ts:447`) : 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.
@@ -403,13 +403,13 @@ Le store, lui, ne voit que des octets : il ne déchiffre jamais rien (`ITotpSecr
 
 ### La politique de clé — bruyante en dev, fail-closed en production
 
-`TotpService.#resolveKey()` (`totp.ts:204`) tranche au boot :
+`TotpService.#resolveKey()` (`totp.ts:211`) tranche au boot :
 
 | Situation                    | Environnement | Comportement                                                 |
 | ---------------------------- | ------------- | ------------------------------------------------------------ |
-| `totp.encryptionKey` fournie | tous          | Clé dérivée HKDF — cas nominal (`totp.ts:207`).              |
-| Clé absente                  | dev / test    | Clé **éphémère** + `WARNING` (`totp.ts:221`).                |
-| Clé absente                  | production    | `CRITIC` + **2FA désactivé** (`totp.ts:212`).                |
+| `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. |
 
 Le refus en production est délibéré : une clé éphémère chiffrerait des secrets **illisibles au
@@ -452,20 +452,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:1138`) — validée au boot, donc une valeur hors bornes
+La section `totp` du schéma Zod (`config.ts:1144`) — 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:98`). |
-| `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:537`).        |
-| `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:538`).                    |
-| `recoveryCodes` | `int` > 0                    | `10`   | Nombre de codes générés à l'activation (`config.ts:546`).         |
-| `encryptionKey` | `string?`                    | —      | Clé de chiffrement du secret au repos (`config.ts:574`).          |
-| `store`         | `string`                     | `auto` | Backend de persistance du secret (`config.ts:580`).               |
+| 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`).                |
 
 ### Situation 1 — un utilisateur active la 2FA sur son compte
 
@@ -492,7 +492,7 @@ Le second facteur validé au login ne dit rien de **qui est devant l'écran dix
 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:262`) :
+dans ton controller à partir du service public `TotpService.verifyLogin()` (`totp.ts:269`) :
 
 ```typescript
 import { controller, Controller, Post } from "@nodefony/framework";
@@ -557,28 +557,30 @@ dialecte via le colKit :
 | `period`        | Durée d'un code (s)                             | `integer`          | `integer`  | `int`           |
 | `recoveryCodes` | Condensats des codes **non consommés**          | `text` (mode json) | `jsonb`    | `json`          |
 | `confirmedAt`   | Activation (epoch ms) ou `null` = en attente    | `integer`          | `bigint`   | `bigint`        |
-| `lastUsedStep`  | Dernière tranche `T` validée (**pas** une date) | `integer`          | `integer`  | `int`           |
+| `lastUsedStep`  | Dernière tranche `T` validée (**pas** une date) | `integer`          | `bigint`   | `bigint`        |
 | `createdAt`     | Création (epoch ms)                             | `integer`          | `bigint`   | `bigint`        |
 | `lastUsedAt`    | Dernier usage réussi (epoch ms) ou `null`       | `integer`          | `bigint`   | `bigint`        |
 
 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:53`).
+  partout, quand les vraies dates sont en `epochMs` (`totpSecretEntity.ts:61`).
 - 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 — et ceux qui manquent
+### 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:279`) | durable, partagé entre pods         | ✅ 3 dialectes SQL   |
-| `mongoose` | —                                             | —                                   | ⏳ manquant, à venir |
+| `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 |
 
-Ces deux absences sont des **manques**, pas des choix de périmètre —
-mais elles se comblent à deux régimes différents.
+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.
+
+Reste une absence, et c'est un **manque**, pas un choix de périmètre.
 
 `redis` le portera **en opt-in explicite, jamais choisi par `auto`** — exactement le régime des
 passkeys qu'il porte déjà. Un secret TOTP est de la même famille qu'un credential passkey : une
@@ -587,20 +589,19 @@ dehors. Porter l'un et refuser l'autre au nom du « cache évincible » serait i
 est identique, et il est déjà assumé, avec son avertissement — sur Redis, la persistance devient la
 responsabilité de l'exploitant (AOF, pas d'éviction sur ces clés).
 
-`mongoose` le portera **au régime normal** : une application choisit son ORM, elle ne choisit pas de
-se passer du 2FA — l'objectif est de pouvoir tourner entièrement sur Mongo, sans drizzle. Aujourd'hui, une application MongoDB qui active le 2FA **retombe sur `memory`** (avec la
-raison annoncée dans les journaux de boot, et un avertissement en production) : ses secrets ne
-survivent pas au redémarrage, et ses utilisateurs se retrouvent verrouillés hors de leur second
-facteur. **En attendant** : charger `@nodefony/drizzle` à côté de Mongo — même en SQLite local — suffit
-à rendre le store durable, les deux modules cohabitent sans conflit.
+Côté `mongoose`, le store est **100 % portable** lui aussi : tout passe par le contrat
+`IRepository` et le helper `paginate()` d'orm-core, sans query native
+(`MongooseTotpSecretStore.ts`). Le modèle « un secret par utilisateur » y est porté par la clé
+primaire (`_id` = `userId`) — donc l'unicité existe dès le premier document, sans index construit
+en tâche de fond.
 
 Côté `drizzle`, les **trois dialectes** sont portés — `TOTP_PORTED` vaut l'ensemble des dialectes
-(`registerStores.ts:92`) : SQLite, PostgreSQL, MySQL/MariaDB. Le store n'écrit **aucun SQL natif**,
-tout passe par le contrat `IRepository` (`DrizzleTotpSecretStore`, `DrizzleTotpSecretStore.ts:38`)
+(`registerStores.ts:94`) : SQLite, PostgreSQL, MySQL/MariaDB. Le store n'écrit **aucun SQL natif**,
+tout passe par le contrat `IRepository` (`DrizzleTotpSecretStore`, `DrizzleTotpSecretStore.ts:44`)
 — 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:134`) :
+adapters réellement chargés (`TotpService.#resolveStore()`, `totp.ts:137`) :
 
 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` ;
@@ -608,7 +609,7 @@ adapters réellement chargés (`TotpService.#resolveStore()`, `totp.ts:134`) :
 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:167`). Une faute de frappe ne dégrade jamais la sécurité en douce.
+production (`totp.ts:174`). Une faute de frappe ne dégrade jamais la sécurité en douce.
 
 ## Le listing paginé des enrôlements
 
@@ -621,14 +622,14 @@ d'un seul utilisateur.
 - **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:153`) ;
+  donc indexable : le critère `$like` est **ancré à gauche**, `DrizzleTotpSecretStore.ts:176`) ;
 - **la vue ne peut pas porter de secret** — `ITotpEnrollmentSummary` (`ITotpSecretStore.ts:16`)
   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:18`). C'est ce qu'exerce le banc de contrat partagé.
+(`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
 ligne.
@@ -637,23 +638,23 @@ ligne.
 
 Tout est exporté depuis `@nodefony/security` — signatures complètes dans `.ai/symbols.json`.
 
-**Le service** (`TotpService`, `totp.ts:71`), résolu par nom dans le container (`"totp"`) :
+**Le service** (`TotpService`, `totp.ts:74`), résolu par nom dans le container (`"totp"`) :
 
-| Méthode                             | Rôle                                                         |
-| ----------------------------------- | ------------------------------------------------------------ |
-| `isEnabled()` (`totp.ts:247`)       | 2FA opérationnel (activé en config **et** boot réussi).      |
-| `beginEnrollment()` (`totp.ts:252`) | Démarre l'enrôlement → secret + URI `otpauth://`, 1×.        |
-| `confirmEnrollment()` (`:257`)      | Confirme par un 1ᵉʳ code → active + codes de récupération.   |
-| `verifyLogin()` (`totp.ts:262`)     | Vérifie un code TOTP **ou** de récupération. Ne lève jamais. |
-| `disable()` (`totp.ts:267`)         | Retire secret et codes.                                      |
-| `status()` (`totp.ts:272`)          | `{ enabled, pending, recoveryCodesRemaining }`.              |
-| `isEnabledFor()` (`totp.ts:299`)    | Raccourci du flux de login (`false` si le 2FA est inerte).   |
-| `listPage()` (`totp.ts:283`)        | Page d'enrôlements (data plane admin).                       |
-| `countEnrollments()` (`:294`)       | Compte filtré, sans énumération.                             |
+| 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.                             |
 
 **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:72`).
+`verifyTotpLogin()`, `disableTotp()`, `totpStatus()` (`totpOperations.ts:200`).
 
 **Les primitives crypto**, pour écrire un client ou un banc de test : `totpCode()`
 (`totpCrypto.ts:174`), `base32Decode()` (`totpCrypto.ts:81`), `deriveTotpKey()`
@@ -698,7 +699,7 @@ vérifie que ta projection n'expose ni secret ni condensat.
 | 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:264`)      |
+| Backoff des tentatives      | NIST SP 800-63B          | `AuthFlow.completeMfaLogin()` (`authFlow.ts:257`)      |
 | Rate limit (429)            | RFC 6585                 | `429` + `Retry-After` (`SessionAuthController.ts:145`) |
 
 Les **vecteurs de test de la RFC 6238 (Appendix B)** sont rejoués en test sur les trois fonctions de
@@ -708,18 +709,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:455`)
+- **Sur le login nominal** (2FA absent ou désactivé) : `AuthFlow.#resolveTotp()` (`authFlow.ts:458`)
   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:62`) n'existe que si le 2FA est activé — le service ne construit rien
-  quand `totp.enabled` est `false` (`totp.ts:98`).
+  (`MemoryTotpSecretStore.ts:74`) n'existe que si le 2FA est activé — le service ne construit rien
+  quand `totp.enabled` est `false` (`totp.ts:101`).
 - **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:234`)
+- **Arrêt propre** : si le store sait se vider sur disque, `TotpService.#shutdown()` (`totp.ts:241`)
   le déclenche à `onTerminate` — aucune écriture en attente perdue.
 
 ## 📡 Observabilité — Studio
@@ -733,34 +734,34 @@ 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:606`).
+- `GET /nodefony/security/api/totp/list` — couverture 2FA paginée (`SecurityAdminApi.ts:636`).
   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:658`).
+- `GET /nodefony/security/api/users/{id}/totp` — statut d'un utilisateur (`SecurityAdminApi.ts:686`).
 - `POST /nodefony/security/api/users/{id}/totp/disable` — reset admin, **audité**
-  (`SecurityAdminApi.ts:683`).
+  (`SecurityAdminApi.ts:711`).
 
 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:299`), `login.failure` avec
+`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:707`).
+(`SecurityAdminApi.ts:735`).
 
 ## ⚠️ 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:212`)           | `npx nodefony security:secrets`, puis câbler `ctx.env.NF_TOTP_KEY` |
+| 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:264`) | Respecter `Retry-After` — attendu sous attaque                     |
-| `503 2FA unavailable` sur `…/totp/*`              | Service absent ou `isEnabled()` faux (`TotpController.ts:128`)       | Vérifier `totp.enabled` + la clé + les logs de boot                |
+| `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                |