@nodefony/security 10.0.0-alpha.8 → 10.0.0-alpha.9

package/docs/tokens.md

@@ -87,11 +87,11 @@ défaut » en prod.
 ## La vision Nodefony — un service propriétaire, des endpoints minces
 
 `TokenService` est **propriétaire** du store et du keystore : à `TokenService.#build()`
-(`tokenService.ts:93`), si `jwt.enabled` ou `apiKeys.enabled`, il résout le store pluggable, pose
-`tokenStore` au container (`tokenService.ts:163`) puis crée le keystore et pose `jwtKeystore`
-(`tokenService.ts:167-173`) — consommés par le `JwtAuthenticator` et les endpoints. Il arme un
+(`tokenService.ts:101`), si `jwt.enabled` ou `apiKeys.enabled`, il résout le store pluggable, pose
+`tokenStore` au container (`tokenService.ts:175`) puis crée le keystore et pose `jwtKeystore`
+(`tokenService.ts:181-186`) — consommés par le `JwtAuthenticator` et les endpoints. Il arme un
 **gc** via `GcScheduler` (timer `unref` + **jitter** de phase pour étaler les balayages entre pods,
-`tokenService.ts:175-181`).
+`tokenService.ts:188-194`).
 
 Les endpoints HTTP sont des **adaptateurs minces** portés par `@nodefony/framework`, couplés **par
 nom de service** via le contrat structurel `ITokenIssuer` — framework n'importe jamais security
@@ -136,7 +136,7 @@ seulement ses signatures vérifiables. Omettre `grant_types_supported` annoncera
 ### Les endpoints d'émission sont FOURNIS
 
 Dans une app `nodefony create app`, dès que le module security est chargé avec `jwt.enabled` (défaut),
-le framework monte deux routes (`mountTokenAuthRoutes()`, `TokenAuthController.ts:132-147`) :
+le framework monte deux routes (`mountTokenAuthRoutes()`, `TokenAuthController.ts:161-176`) :
 
 - `POST /nodefony/security/api/token` — body `{username, password, scope?}` → couple access/refresh ;
 - `POST /nodefony/security/api/token/refresh` — body `{refresh_token}` → rotation.
@@ -228,36 +228,36 @@ Erreurs mappées par duck-typing dans `#renderAuthError()` (`TokenAuthController
 
 ### Émission (grant M2M/CLI)
 
-`issueForCredentials()` (`tokenService.ts:317`) vérifie l'identifiant/mot de passe via le
+`issueForCredentials()` (`tokenService.ts:324`) vérifie l'identifiant/mot de passe via le
 service `users`, avec le **throttling NIST partagé** — `ThrottledError` avant tout hachage
-(`tokenService.ts:733`). Chaque tentative échouée est auditée `login.failure`/`login.throttled`
-par `#auditGrant()` (`tokenService.ts:362-374`). Puis `issueTokens()` (`tokenService.ts:490`)
+(`tokenService.ts:353`). Chaque tentative échouée est auditée `login.failure`/`login.throttled`
+par `#auditGrant()` (`tokenService.ts:369-381`). Puis `issueTokens()` (`tokenService.ts:497`)
 produit :
 
 - un **access token** : JWT signé EdDSA, en-tête `typ:"at+jwt"` + `kid`, claims
-  `iss`/`sub`/`aud`/`exp` (15 min) + `jti` — `#signAccess()` (`tokenService.ts:402-415`) ;
+  `iss`/`sub`/`aud`/`exp` (15 min) + `jti` — `#signAccess()` (`tokenService.ts:649-662`) ;
 - un **refresh token** : secret opaque haute entropie `nfr_<32 octets base64url>`, **stocké haché**
   `sha256` (le clair n'existe qu'en réponse, jamais au repos) — `#buildRefresh()`
-  (`tokenService.ts:674-709`).
+  (`tokenService.ts:681-716`).
 
-La réponse suit RFC 6749 §5.1 — `ITokenResponse` (`tokenService.ts:43-51`). Tout succès est audité
+La réponse suit RFC 6749 §5.1 — `ITokenResponse` (`tokenService.ts:49-57`). Tout succès est audité
 `token.issued` via `recordAudit` avec le `tokenId` corrélable (`tokenService.ts:312-318`).
 
 ### Rotation & détection de rejeu (RFC 9700 §4.14)
 
-`refresh()` (`tokenService.ts:555`) est le cœur défensif, dans l'ordre :
+`refresh()` (`tokenService.ts:562`) est le cœur défensif, dans l'ordre :
 
-1. Lookup par hash — `findByHash`, refus uniforme si inconnu/mauvais type (`tokenService.ts:564`).
+1. Lookup par hash — `findByHash`, refus uniforme si inconnu/mauvais type (`tokenService.ts:571`).
 2. **Détection de rejeu** : refresh **déjà révoqué** re-présenté → `revokeFamily` coupe toute la
-   famille + audit `token.reuse_detected`, signal d'attaque fort (`tokenService.ts:345-361`).
-3. Expiration `expiresAt` vérifiée (`tokenService.ts:363-368`).
+   famille + audit `token.reuse_detected`, signal d'attaque fort (`tokenService.ts:577-591`).
+3. Expiration `expiresAt` vérifiée (`tokenService.ts:594`).
 4. **Sujet revérifié** — compte disparu/inactif/verrouillé rejeté sans attendre l'exp,
-   `#resolveUserForRefresh()` (`tokenService.ts:745`).
+   `#resolveUserForRefresh()` (`tokenService.ts:752`).
 5. **Downscoping** : les `scopes` du nouveau couple sont ceux de l'ancien, jamais plus
-   (`tokenService.ts:592`).
+   (`tokenService.ts:600`).
 6. **Rotation** : nouveau refresh (même famille), l'ancien chaîné `replacedBy` + révoqué
-   `"rotated"` (`tokenService.ts:698`). Si `rotateRefresh` est désactivé, l'access est réémis
-   et le refresh courant reste valide (`tokenService.ts:627`).
+   `"rotated"` (`tokenService.ts:634-636`). Si `rotateRefresh` est désactivé, l'access est réémis
+   et le refresh courant reste valide (`tokenService.ts:620`).
 
 ### Mise en situation — ton refresh token a été volé
 
@@ -336,35 +336,35 @@ La décision (configuré → résolu, raison) est publiée au kernel par `regist
 
 - Builtin, enregistré à l'import du module via `registerTokenStore` (`tokenStoreRegistry.ts:63-68`).
 - `listPage` : tri `createdAt` DESC + tiebreaker `id`, déterministe pour l'offset — parité SQL
-  (`MemoryTokenStore.ts:122-142`).
+  (`MemoryTokenStore.ts:165-185`).
 - Denylist bornée : purge **amortie** tous les 256 ajouts — `#maybeSweep()`
-  (`MemoryTokenStore.ts:360`) + expiration paresseuse à la lecture. Pas de minuterie, pas de fuite.
+  (`MemoryTokenStore.ts:393`) + expiration paresseuse à la lecture. Pas de minuterie, pas de fuite.
 - `snapshot()`/`restore()` sérialisables — base d'une persistance fichier, index reconstruits
-  (`MemoryTokenStore.ts:253-283`).
+  (`MemoryTokenStore.ts:324-354`).
 - Volatil, par-process : dev/tests. Pilote le banc de contrat commun.
 
 ### `drizzle` — SQL, le défaut durable
 
-- Enregistré par le module drizzle (`drizzle/nodefony/registerStores.ts:220`).
+- Enregistré par le module drizzle (`drizzle/nodefony/registerStores.ts:261`).
 - Élu par `store:"auto"` dès qu'une infra database SQL est déclarée ; sinon sqlite local si drizzle
-  est chargé (`config.ts:394-399`).
+  est chargé (`config.ts:428-433`).
 - Pagination **offset + total** (helper `paginate()` d'orm-core) ; e2e sur PostgreSQL et MySQL réels.
 
 ### `mongoose` — MongoDB
 
-- Enregistré par le module mongoose (`mongoose/nodefony/registerStores.ts:119`).
-- Pagination **offset + total** via `listPage` (`MongooseTokenStore.ts:163-173`).
-- Purge par `gc()` explicite sur `expiresAt` (`MongooseTokenStore.ts:196`).
+- Enregistré par le module mongoose (`mongoose/nodefony/registerStores.ts:170`).
+- Pagination **offset + total** via `listPage` (`MongooseTokenStore.ts:236-246`).
+- Purge par `gc()` explicite sur `expiresAt` (`MongooseTokenStore.ts:170`).
 
 ### `redis` — cluster, TTL natif
 
-- Enregistré par le module redis (`redis/nodefony/registerStores.ts:49`).
-- TTL natif : `expire()` posé à l'écriture du record (`RedisTokenStore.ts:254`) — l'expiration ne
+- Enregistré par le module redis (`redis/nodefony/registerStores.ts:75`).
+- TTL natif : `expire()` posé à l'écriture du record (`RedisTokenStore.ts:308`) — l'expiration ne
   dépend pas du gc.
 - Listing par `SCAN` : curseur opaque `skip:scanCursor`, `decodeCursor()`
-  (`RedisTokenStore.ts:35-44`) — sans ordre global ni total, capacité réduite **assumée**.
+  (`RedisTokenStore.ts:428`) — sans ordre global ni total, capacité réduite **assumée**.
 - `countTokens()` renvoie `-1` : un comptage exact exigerait un SCAN complet O(N), refusé
-  (`RedisTokenStore.ts:432`).
+  (`RedisTokenStore.ts:483`).
 
 ### Le record — une seule table pour PAT et refresh
 
@@ -398,72 +398,72 @@ Les colonnes par dialecte vivent dans la doc de chaque adapter (règle anti-trip
 - **Un refresh/PAT** : `revoke()` idempotent, `revokeFamily()` pour la chaîne de rotation
   (`ITokenStore.ts:242`).
 - **Tout un porteur** (logout global, ban) : seuil `revokeAllForSubject()` — tout access dont
-  `iat < invalidBefore` est rejeté (`ITokenStore.ts:226-234`) ; le seuil est **monotone**, deux
-  logouts successifs ne le reculent pas (`MemoryTokenStore.ts:229`).
+  `iat < invalidBefore` est rejeté (`ITokenStore.ts:259-263`) ; le seuil est **monotone**, deux
+  logouts successifs ne le reculent pas (`MemoryTokenStore.ts:262-267`).
 
 ### La maintenance (gc)
 
 Le `gc()` du store purge la `denylist` expirée, les records à terme, les PAT révoqués au-delà de
-la rétention (`ITokenStore.ts:237-251`). Orchestré par le `GcScheduler` du service ; `runGc()` reste public pour
+la rétention (`ITokenStore.ts:274-280`). Orchestré par le `GcScheduler` du service ; `runGc()` reste public pour
 un futur worker cron — poser alors `gcIntervalS: 0` (`tokenService.ts:293`).
 
 > [!TIP]
 > Un refresh révoqué **par rotation** n'est PAS purgé tout de suite : il est conservé jusqu'à son
 > `expiresAt` — c'est la **fenêtre de détection de rejeu** — puis tombe au gc, `#isPurgeable()`
-> (`MemoryTokenStore.ts:239-248`). Un store **local** (memory) est par-process : seul SON process
+> (`MemoryTokenStore.ts:301-310`). Un store **local** (memory) est par-process : seul SON process
 > peut le purger → ne déléguez le gc au cron QUE pour un store partagé.
 
 ## ⚙️ Configuration
 
-Tables dérivées du schéma Zod — `jwtSchema` (`config.ts:334-390`) et `tokenStoreSchema`
-(`config.ts:392-425`), défauts inclus.
+Tables dérivées du schéma Zod — `jwtSchema` (`config.ts:366-425`) et `tokenStoreSchema`
+(`config.ts:426-458`), défauts inclus.
 
 ### `jwt.*`
 
 <!-- prettier-ignore -->
 | Option | Type | Défaut | Effet |
 | --- | --- | --- | --- |
-| `enabled` | boolean | `true` | Active signature + refresh (`config.ts:317`) |
+| `enabled` | boolean | `true` | Active signature + refresh (`config.ts:368`) |
 | `alg` | `EdDSA` \| `RS256` | `EdDSA` | `RS256` = slot non câblé (`jwtRuntime.ts:21`) |
-| `accessTtlS` | number (s) | `900` | TTL de l'access token — 15 min (`config.ts:364`) |
-| `refreshTtlS` | number (s) | `604800` | TTL du refresh — 7 jours (`config.ts:369`) |
-| `rotateRefresh` | boolean | `true` | Rotation du refresh à chaque usage, OWASP (`config.ts:374`) |
+| `accessTtlS` | number (s) | `900` | TTL de l'access token — 15 min (`config.ts:370`) |
+| `refreshTtlS` | number (s) | `604800` | TTL du refresh — 7 jours (`config.ts:375`) |
+| `rotateRefresh` | boolean | `true` | Rotation du refresh à chaque usage, OWASP (`config.ts:380`) |
 | `jwks` | boolean | `true` | Publie `/.well-known/jwks.json` + les métadonnées RFC 8414 — sans `issuer` en URL https, rien n'est publié |
-| `audiences` | string[] | `[]` | `aud` acceptées (RFC 8707) ; vide = `[issuer]` (`config.ts:384`) |
+| `audiences` | string[] | `[]` | `aud` acceptées (RFC 8707) ; vide = `[issuer]` (`config.ts:390`) |
 | `issuer` | string? | — | Claim `iss`, **STABLE** après émission ; omis → repli `"nodefony"`, qui n'est PAS publiable (RFC 8414 §2 exige une URL https) |
-| `keystore.keySetJson` | string? | — | JWK Set privé injecté depuis l'env — source prod, SECRET (`security/nodefony/config/config.ts:398`) |
-| `keystore.dir` | string? | — | Dossier `keyset.json` chmod 600 — source dev/VPS (`config.ts:376-381`) |
+| `keystore.keySetJson` | string? | — | JWK Set privé injecté depuis l'env — source prod, SECRET (`security/nodefony/config/config.ts:404`) |
+| `keystore.dir` | string? | — | Dossier `keyset.json` chmod 600 — source dev/VPS (`config.ts:410-418`) |
 
 ### `tokenStore.*`
 
 | Option                 | Type       | Défaut   | Effet                                                                                 |
 | ---------------------- | ---------- | -------- | ------------------------------------------------------------------------------------- |
-| `store`                | string     | `"auto"` | `auto`\|`memory`\|`drizzle`\|`mongoose`\|`redis` — pluggable (`config.ts:394-399`)    |
-| `gcIntervalS`          | number (s) | `600`    | Purge périodique ; `0` = désactivé — chaque process purge SON store (`config.ts:428`) |
-| `gcJitter`             | boolean    | `true`   | Étale le gc d'un délai aléatoire par process — cluster (`config.ts:436`)              |
-| `retentionRevokedDays` | number (j) | `30`     | Rétention d'un PAT révoqué SANS expiration avant purge (`config.ts:442`)              |
+| `store`                | string     | `"auto"` | `auto`\|`memory`\|`drizzle`\|`mongoose`\|`redis` — pluggable (`config.ts:428-433`)    |
+| `gcIntervalS`          | number (s) | `600`    | Purge périodique ; `0` = désactivé — chaque process purge SON store (`config.ts:434`) |
+| `gcJitter`             | boolean    | `true`   | Étale le gc d'un délai aléatoire par process — cluster (`config.ts:442`)              |
+| `retentionRevokedDays` | number (j) | `30`     | Rétention d'un PAT révoqué SANS expiration avant purge (`config.ts:448`)              |
 
 ## 📜 Normes appliquées
 
 | Domaine                          | Norme           | Ancrage                                                 |
 | -------------------------------- | --------------- | ------------------------------------------------------- |
-| Réponse d'émission               | RFC 6749 §5.1   | `ITokenResponse` (`tokenService.ts:43-51`)              |
-| Rotation + détection de rejeu    | RFC 9700 §4.14  | `refresh()` (`tokenService.ts:555`)                     |
-| Profil access token `typ:at+jwt` | RFC 9068        | `#signAccess()` (`tokenService.ts:402-415`)             |
-| Claims JWT (`iss/sub/aud/exp`)   | RFC 7519        | `#signAccess()` (`tokenService.ts:406-414`)             |
+| Réponse d'émission               | RFC 6749 §5.1   | `ITokenResponse` (`tokenService.ts:49-57`)              |
+| Rotation + détection de rejeu    | RFC 9700 §4.14  | `refresh()` (`tokenService.ts:562`)                     |
+| Profil access token `typ:at+jwt` | RFC 9068        | `#signAccess()` (`tokenService.ts:649-662`)             |
+| Claims JWT (`iss/sub/aud/exp`)   | RFC 7519        | `#signAccess()` (`tokenService.ts:649-657`)             |
 | Ed25519 / JWK / JWKS public      | RFC 8037 · 7517 | `#importKeyset()` (`JwtKeystore.ts:156-158`)            |
 | Audiences liées à la ressource   | RFC 8707        | `audience` du record (`ITokenStore.ts:104-105`)         |
 | 429 + `Retry-After`              | RFC 6585        | `#renderAuthError()` (`TokenAuthController.ts:108-115`) |
-| Backoff de login                 | NIST SP 800-63B | `ThrottledError` avant hachage (`tokenService.ts:346`)  |
+| Backoff de login                 | NIST SP 800-63B | `ThrottledError` avant hachage (`tokenService.ts:353`)  |
 
 ## ⚡ Performance & mémoire
 
-- **`jose` importé lazy** (dep lourde) : `#ensureJose()` au premier usage (`tokenService.ts:648`)
+- **`jose` importé lazy** (dep lourde) : `#ensureJose()` au premier usage (`tokenService.ts:726`)
   — le boot ne paie rien si le JWT n'est jamais sollicité ; keystore mémoïsé pareil.
 - **Rien sur le hot path requête** : émission et rotation sont des endpoints cold-path ; la
   vérification (hot path) vit chez le `JwtAuthenticator`.
 - **Timers civilisés** : `GcScheduler` `unref` (n'empêche pas l'arrêt) + jitter anti-balayages
-  simultanés (`tokenService.ts:175-181`) ; denylist mémoire bornée par purge amortie
+  simultanés (`tokenService.ts:188-194`) ; denylist mémoire bornée par purge amortie
   (`MemoryTokenStore.ts:331-341`).
 - **Jamais N en RAM** : `listPage()` borne toute lecture admin à une page (`ITokenStore.ts:233`).
 

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                |