@nodefony/security 10.0.0-alpha.3 → 10.0.0-alpha.5

package/dist/types/nodefony/config/config.d.ts

@@ -238,6 +238,8 @@ export declare const securityConfigSchema: z.ZodObject<{
             successRedirect: z.ZodOptional<z.ZodString>;
             failureRedirect: z.ZodOptional<z.ZodString>;
             defaultRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            label: z.ZodOptional<z.ZodString>;
+            hidden: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
     apiKeys: z.ZodDefault<z.ZodObject<{

package/dist/types/nodefony/service/oauth2.d.ts

@@ -1,4 +1,26 @@
 import { Service, Module } from "nodefony";
+/**
+ * Libellé affichable d'un fournisseur, quand sa configuration n'en donne pas.
+ *
+ * Un écran de connexion ne doit JAMAIS montrer un identifiant technique brut :
+ * `mon-idp-interne` sur un bouton ne dit rien à qui doit cliquer. À défaut de
+ * marque connue, le nom de la clé de configuration est ce qui s'en rapproche le
+ * plus — mais rendu lisible : séparateurs en espaces, initiales en capitales,
+ * sigles préservés.
+ *
+ * Fonction PURE, donc éprouvable sans boot ni réseau.
+ *
+ * @param name - nom du fournisseur, tel qu'il est écrit dans la configuration
+ * @returns le libellé à afficher sur le bouton
+ */
+export declare function oauthDisplayLabel(name: string): string;
+/** Un fournisseur tel que l'écran de connexion doit le présenter. */
+export interface IOAuthDisplayProvider {
+    /** Nom technique — celui que l'URL `/authorize` attend. */
+    readonly name: string;
+    /** Libellé du bouton : celui de la config, sinon dérivé du nom. */
+    readonly label: string;
+}
 /** Données à porter en session entre `authorize` et `callback` (anti-replay). */
 export interface IOAuthAuthorization {
     /** URL d'autorisation vers laquelle rediriger l'utilisateur. */
@@ -33,8 +55,26 @@ declare class OAuth2Service extends Service {
     constructor(module: Module);
     /** `true` si le social login est opérationnel (activé + boot OK). */
     isEnabled(): boolean;
-    /** Noms des fournisseurs configurés ET connus du registre (UI : boutons à afficher). */
+    /**
+     * Noms des fournisseurs OPÉRATIONNELS — configurés ET connus du registre.
+     *
+     * 🔴 C'est la **garde d'autorisation** : `/authorize` refuse en 404 tout nom
+     * absent de cette liste. Elle répond donc à « ce flux peut-il s'ouvrir ? »,
+     * jamais à « ce bouton doit-il s'afficher ? » — pour l'écran, voir
+     * {@link listDisplayProviders}. Confondre les deux ferait d'un masquage une
+     * désactivation, et couperait les bancs qui exercent une fixture masquée.
+     */
     listProviders(): string[];
+    /**
+     * Fournisseurs à MONTRER sur l'écran de connexion, libellés compris.
+     *
+     * Rend TOUT fournisseur opérationnel — y compris ceux dont le framework ne
+     * connaît pas la marque, qui sont précisément ceux qu'une application
+     * enregistre elle-même. Le seul retrait possible est explicite et se lit dans
+     * la configuration du fournisseur (`hidden: true`), à côté de la raison qui
+     * l'a motivé ; il ne désactive rien.
+     */
+    listDisplayProviders(): IOAuthDisplayProvider[];
     /**
      * Redirections post-login (succès / échec) — lues par le controller.
      * Surcharge PAR FOURNISSEUR si fournie, sinon valeur globale, sinon défaut.

package/dist/types/nodefony/src/token/JwtKeystore.d.ts

@@ -9,6 +9,26 @@ interface KeystoreSource {
     /** Dossier de persistance `keyset.json` — source `fichier` (opt-in dev/VPS). */
     readonly dir?: string;
 }
+/**
+ * Le trousseau va-t-il partir dans l'image de conteneur ?
+ *
+ * ⭐ **Pourquoi cet avertissement existe.** Le trousseau est une clé privée
+ * Ed25519. Elle ne sort pas de l'image aujourd'hui pour UNE seule raison : le
+ * gabarit a choisi `var/keys`, et le `Dockerfile` généré efface `var/`. Rien
+ * n'attache cette sécurité à la configuration — un utilisateur qui écrit
+ * `keystore: { dir: "nodefony/config/keys" }`, chemin parfaitement raisonnable,
+ * publie sa clé privée sans qu'aucun signal n'existe. C'est exactement le
+ * chemin par lequel une clé TLS est déjà partie dans une image publiée.
+ *
+ * ⚠️ **Les chemins ABSOLUS ne sont pas jugés**, et c'est délibéré : `/etc/…` ou
+ * un point de montage sont des choix d'exploitation qui sortent du contexte de
+ * construction, et prétendre les évaluer ferait crier ce contrôle sur la
+ * pratique la plus saine. Un contrôle qui crie faux apprend à passer outre.
+ *
+ * @param dir - la valeur de `jwt.keystore.dir`, telle que configurée.
+ * @returns le message à journaliser, ou `null` quand le dossier est nettoyé.
+ */
+export declare function keystoreLeaksIntoImage(dir: string): string | null;
 /**
  * Keystore Ed25519 — implémentation de référence d'{@link IJwtKeystore}.
  *

package/docs/audit.md

@@ -383,7 +383,7 @@ Quatre sorties d'échec du firewall passent par le même helper `Firewall.#recor
 - `auth.failure` — un credential a été **présenté** et rejeté (`firewall.ts:794`) ;
 - `auth.denied` / `no_credentials` — Zero Trust : rien n'a été présenté sur une zone protégée
   (`firewall.ts:811`) ;
-- `auth.denied` / `unauthenticated` — un jeton non promu hors `anonymous` (`firewall.ts:638`).
+- `auth.denied` / `unauthenticated` — un jeton non promu hors `anonymous` (`firewall.ts:850`).
 
 Le parcours de login BFF émet en parallèle son propre vocabulaire depuis `AuthFlow` :
 `login.failure` sur identité inconnue (`authFlow.ts:125`) ou mot de passe faux (`authFlow.ts:153`),
@@ -458,7 +458,7 @@ Quatre mécanismes, tous prouvés par les tests.
 
 **1. Le chemin nominal n'émet rien.** Ce n'est pas une optimisation, c'est le modèle : le firewall
 n'appelle `#recordAuth()` que depuis ses quatre sorties d'échec, jamais depuis le succès
-(`firewall.ts:884`). Le verrou WS ne tire sa closure `onDeny` que sur refus (`firewall.ts:341`).
+(`firewall.ts:900`). Le verrou WS ne tire sa closure `onDeny` que sur refus (`firewall.ts:341`).
 Prouvé : « frame AUTORISÉE → onDeny JAMAIS appelé » (`auditEmissionHotPath.test.ts:324`).
 
 **2. Audit désactivé = coût nul, pas juste coût faible.** `record()` sort avant toute allocation et
@@ -484,7 +484,7 @@ jamais faire tomber ce qu'on supervise.
 ## ⚙️ Configuration
 
 Table dérivée du schéma Zod `auditSchema` (`config.ts:877`), rattaché à la racine sous la clé `audit`
-(`config.ts:1121`).
+(`config.ts:1152`).
 
 | Option          | Type      | Défaut   | Effet                                                                                |
 | --------------- | --------- | -------- | ------------------------------------------------------------------------------------ |
@@ -503,7 +503,7 @@ Table dérivée du schéma Zod `auditSchema` (`config.ts:877`), rattaché à la
 ### Comment `store: "auto"` décide
 
 Le défaut ne suppose rien : il **suit l'infrastructure déclarée**, borné aux backends réellement
-enregistrés (`auditService.ts:92`, logique `resolveAutoStore()` dans `infra.ts:241`).
+enregistrés (`auditService.ts:92`, logique `resolveAutoStore()` dans `infra.ts:289`).
 
 1. `NF_STORE` posée et le backend est enregistré pour l'audit → il gagne (levier de banc de charge) ;
 2. sinon, une base est déclarée (`NF_DATABASE_URL`) → `drizzle`, ou `mongoose` selon la famille ;
@@ -618,7 +618,7 @@ pour les migrations de production ; en dev et en test, le DDL dérivé les ignor
 filtrage, jamais de sémantique.
 
 L'entité et la fabrique sont enregistrées automatiquement par l'adapter au démarrage
-(`registerStores.ts:241`, entité via `registerAuditEntities()`, `auditEventEntity.ts:141`). Côté
+(`registerStores.ts:276`, entité via `registerAuditEntities()`, `auditEventEntity.ts:141`). Côté
 implémentation, `DrizzleAuditStore` (`DrizzleAuditStore.ts:64`) résout son handle de base **à chaque
 appel**, pas à la construction : l'ordre de démarrage n'est pas garanti, et l'ORM se déconnecte au
 `onTerminate` avant le drain des serveurs.

package/docs/authenticators.md

@@ -49,7 +49,7 @@ flowchart TD
   S --> CTRL["→ autorisation → contrôleur"]
 ```
 
-C'est `Firewall.#authenticate()` (`firewall.ts:1112`) qui déroule ce cycle pour chaque maillon de la
+C'est `Firewall.#authenticate()` (`firewall.ts:1128`) qui déroule ce cycle pour chaque maillon de la
 zone, dans l'ordre déclaré. Le succès pose l'identité dans l'ALS ; l'échec remonte au firewall qui
 pose le 401 et son challenge — l'authenticator, lui, ne touche jamais à la réponse.
 
@@ -105,7 +105,7 @@ totalement agnostique de la stratégie :
 ### Le registre pluggable
 
 Les authenticators sont résolus par **nom** : `Firewall.#instantiateAuthenticators()`
-(`firewall.ts:402`) interroge `getAuthenticatorFactory()` (`authenticatorRegistry.ts:59`) — jamais
+(`firewall.ts:429`) interroge `getAuthenticatorFactory()` (`authenticatorRegistry.ts:59`) — jamais
 un `if (name === "jwt")` dans le firewall, qui trahirait la promesse « pluggable ».
 
 - Les **cinq builtins HTTP** (`anonymous`, `userpassword`, `session`, `jwt`, `apikey`)
@@ -116,7 +116,7 @@ un `if (name === "jwt")` dans le firewall, qui trahirait la promesse « pluggabl
 - La fabrique ne fait que **construire** ; les résolutions de services coûteuses (`users`,
   `tokenStore`, keystore) restent **lazy** dans l'instance (cold path).
 - Un nom inconnu en config = boot **fail-closed** — `#configError` posé + log CRITIC
-  (`firewall.ts:419`) : jamais de zone « protégée » silencieusement ouverte à cause d'une
+  (`firewall.ts:582`) : jamais de zone « protégée » silencieusement ouverte à cause d'une
   faute de frappe.
 
 ## 🚀 Démarrage rapide
@@ -261,10 +261,10 @@ Credential = l'**identifiant** posé dans le blob de session, jamais un secret.
   d'un utilisateur (`SessionAuthenticator.ts:43-46`) — le pipeline http démarre la session _avant_
   le firewall ; c'est `AuthFlow.login()` qui ouvre et régénère l'ID (anti-fixation).
 - **L'identité est re-résolue à CHAQUE requête** via `resolveSessionIdentity`
-  (`SessionAuthenticator.ts:70`) → rôles frais, révocation immédiate. Les contrôles d'état sont
+  (`SessionAuthenticator.ts:91`) → rôles frais, révocation immédiate. Les contrôles d'état sont
   partagés avec `AuthFlow.me()` : `isLocked()`/`isActive()` → rejet (`sessionIdentity.ts:40`).
 - `onSuccess()` pose l'identifiant sur le contexte — la persistance de session lie le blob au
-  principal courant (`SessionAuthenticator.ts:78-80`).
+  principal courant (`SessionAuthenticator.ts:110-116`).
 - **Pas de `challenge()`** : session absente = 401 nu → le front redirige vers son écran de login,
   jamais une popup Basic (`SessionAuthenticator.ts:25-27`).
 
@@ -353,12 +353,12 @@ Deux preuves différentes, mêmes routes — c'est la config du Démarrage rapid
 de lecture :
 
 - un maillon dont `supports()` est faux est simplement **sauté** en mode `first`
-  (`firewall.ts:1128`) ;
+  (`firewall.ts:1114`) ;
 - un credential **présenté mais invalide échoue immédiatement** — l'échec d'`authenticate()`
-  remonte, jamais de fallback silencieux vers le maillon suivant (`firewall.ts:1112`). Une clé
+  remonte, jamais de fallback silencieux vers le maillon suivant (`firewall.ts:1128`). Une clé
   API révoquée donne un 401 direct, même si un autre maillon aurait pu réussir.
 - aucune preuve présentée sur toute la chaîne → `handleSecurity()` lève l'`AuthenticationError`
-  Zero Trust (`firewall.ts:738`).
+  Zero Trust (`firewall.ts:754`).
 
 ### Situation 2 — le piège de l'ordre (`anonymous` toujours EN DERNIER)
 
@@ -397,7 +397,7 @@ paresse : c'est une **défense anti-énumération / anti-oracle**.
 Distinguer « compte inconnu » de « mot de passe faux », ou « token expiré » de « signature
 invalide », donnerait à un attaquant une sonde. La cause fine part **toujours** en log d'audit ; le
 client n'obtient qu'un 401 + son challenge — posé par le firewall, premier maillon de la zone qui
-en déclare un (`Firewall.#setChallenge()`, `firewall.ts:1191`).
+en déclare un (`Firewall.#setChallenge()`, `firewall.ts:1207`).
 
 ## 🧩 Ajouter un authenticator maison
 
@@ -423,7 +423,7 @@ registerAuthenticatorFactory("ldap", ({ container, config }) => {
 <!-- prettier-ignore -->
 | Domaine | Norme | Ancrage |
 | --- | --- | --- |
-| Challenge d'auth (401) | RFC 7235 | `Firewall.#setChallenge()` (`firewall.ts:1191`) |
+| Challenge d'auth (401) | RFC 7235 | `Firewall.#setChallenge()` (`firewall.ts:1207`) |
 | Bearer | RFC 6750 | `readBearerHeader()` (`runtime/bearer.ts:68`, cœur) — une porte UNIQUE au cœur, plus une constante par authenticator |
 | JWT (BCP) | RFC 7519, 8725 | `jwtVerify` durci : allowlist + claims (`JwtAuthenticator.ts:103-107`) |
 | HTTP Basic | RFC 7617 | `UserPasswordAuthenticator` (`UserPasswordAuthenticator.ts:25-27`) |

package/docs/authorization.md

@@ -302,7 +302,7 @@ Dès le `DENY`, le jury **s'arrête** — court-circuit, inutile de finir (`auth
 
 **Contre-exemple piégeux** : le veto ne traverse **pas** une clause OR. Dans
 `@IsGranted(["ROLE_ADMIN", "doc.edit"])`, chaque attribut est un **jury séparé**
-(`Resolver.ts:592-600`) : si `ROLE_ADMIN` est accordé, `doc.edit` — et son veto — n'est même pas
+(`Resolver.ts:587-607`) : si `ROLE_ADMIN` est accordé, `doc.edit` — et son veto — n'est même pas
 consulté. Un interdit absolu se porte en clause **AND** : empiler `@IsGranted("ROLE_ADMIN")` puis
 `@IsGranted("doc.edit", { subject: "id" })`.
 
@@ -428,7 +428,7 @@ compilation** — rien à scanner au runtime ; le registre **est** le marqueur e
   et `IRealtimeToken` (WS) (`authorization.ts:119-122`).
 - **Le verrou de frame** (canaux realtime) applique son RBAC par canal avec la **même
   hiérarchie** : `satisfies()` (`frameAuthorizer.ts:276`) délègue à `Firewall.hasRole()`
-  (`firewall.ts:466`) — les rôles exigés par un canal héritent comme partout ailleurs.
+  (`firewall.ts:482`) — les rôles exigés par un canal héritent comme partout ailleurs.
 
 ## 📜 Normes appliquées
 

package/docs/cors.md

@@ -323,7 +323,7 @@ sequenceDiagram
 ```
 
 `Firewall.handleCors()` (`firewall.ts:991`) est appelé **en tête de** `HttpKernel.handleHttp()`
-(`http-kernel.ts:1258`), à la ligne `http-kernel.ts:1258` — **avant le routing**. La raison est
+(`http-kernel.ts:1301`), à la ligne `http-kernel.ts:1301` — **avant le routing**. La raison est
 concrète : un preflight `OPTIONS /api/articles` n'a **pas de route déclarée** ; s'il traversait le
 router, il repartirait en 405. Et selon le Fetch Standard, un preflight ne transporte jamais de
 credentials — il ne doit donc ni s'authentifier, ni exécuter le moindre code applicatif.
@@ -338,7 +338,7 @@ Quatre sorties en no-op, dans cet ordre (`firewall.ts:797`) :
    court-circuité en 204 (`firewall.ts:822`).
 
 **La détection du preflight est stricte** : méthode `OPTIONS` **et** présence de
-`Access-Control-Request-Method` (`firewall.ts:808`). Un `OPTIONS` nu — celui d'un client qui interroge
+`Access-Control-Request-Method` (`firewall.ts:999`). Un `OPTIONS` nu — celui d'un client qui interroge
 les méthodes supportées d'une route — est donc traité comme une requête réelle et continue le pipeline.
 
 ### Ce que chaque moment pose
@@ -384,7 +384,7 @@ origine (`config.ts:180`). Ajouter une origine à `cors.origins` est **plus** pe
 **Les navigateurs n'appliquent pas CORS aux WebSockets.** Une page tierce peut ouvrir un
 `new WebSocket("wss://api.example.com/…")` et le handshake partira **avec le cookie de session de la
 victime** : c'est le CSWSH. C'est pourquoi `handleCors` s'arrête net sur un contexte WS
-(`firewall.ts:991`) — il n'y aurait rien à protéger avec des en-têtes que personne ne lit.
+(`firewall.ts:1007`) — il n'y aurait rien à protéger avec des en-têtes que personne ne lit.
 
 La garde équivalente vit dans le transport : `HttpKernel.checkWebsocketOrigin()`
 (`http-kernel.ts:599`) valide l'`Origin` **au handshake**, avant l'accept, et ferme en code WS `1008`
@@ -428,7 +428,7 @@ Le coût par requête est donc :
 ## 📡 Observabilité — Studio
 
 La configuration CORS **résolue** (celle qui tourne réellement, pas le fichier source) est exposée par
-`Firewall.describe()` (`firewall.ts:505`), qui délègue à `Firewall.#describeDefenses()`
+`Firewall.describe()` (`firewall.ts:549`), qui délègue à `Firewall.#describeDefenses()`
 (`firewall.ts:575`). La projection CORS y expose `origins`, `credentials`, `methods`,
 `allowedHeaders`, `exposedHeaders` et `maxAgeS` (`firewall.ts:594`) — aucun secret ne transite par
 cette surface.

package/docs/csrf.md

@@ -93,7 +93,7 @@ contrôleur** : l'attaque meurt sans avoir touché ton code.
 - **Vérifier la provenance d'abord** (OWASP 2025, modèle Go 1.25 `CrossOriginProtection`) : la
   couche 1 est la défense **par défaut**, `csrf.enabled: true` (`config.ts:151-156`).
 - **Globale, pas liée aux zones** : toute mutation cross-site est refusée, route publique ou non —
-  branchée dans le pipeline HTTP — l'appel `enforceCsrf` (`http-kernel.ts:1427`) arrive **après** le
+  branchée dans le pipeline HTTP — l'appel `enforceCsrf` (`http-kernel.ts:1470`) arrive **après** le
   resolve (les marqueurs de route sont lisibles) et **avant** la session (rejet précoce : un
   attaquant ne coûte ni lecture de session ni authentification).
 - **Logique pure** : la classe `Csrf` est synchrone, sans I/O ni allocation sur le hot-path —
@@ -153,7 +153,7 @@ le fait pour toi. Posé sur la **classe**, `@CsrfProtect()` couvre toutes les ac
 ### Comment le front obtient — puis rejoue — le token
 
 1. **Obtenir** : une requête **sûre** (GET) vers n'importe quelle route `@CsrfProtect` sème le token
-   (`firewall.ts:753-757`) ; la réponse pose le cookie **lisible** `csrf-token` — non `HttpOnly`
+   (`firewall.ts:958-964`) ; la réponse pose le cookie **lisible** `csrf-token` — non `HttpOnly`
    exprès, `SameSite=Strict`, `Secure` en HTTPS (`HttpContext.writeHead()`, `HttpContext.ts:419-432`).
 2. **Rejouer** : le SPA lit le cookie et renvoie sa valeur **à l'identique** dans l'en-tête
    `x-csrf-token` sur chaque mutation.
@@ -298,10 +298,10 @@ de session (TSDoc `CsrfTokenManager`, `csrfToken.ts:12-15`).
 2. Au match de la route, `Resolver.match()` recopie les marqueurs sur le contexte
    (`Resolver.ts:152-153`) — champs portés par le `Context` de base, HTTP comme WS
    (`Context.ts:181-183`).
-3. `Firewall.enforceCsrf()` (`firewall.ts:932`) fait les trois rôles : **émission** du token sur
+3. `Firewall.enforceCsrf()` (`firewall.ts:948`) fait les trois rôles : **émission** du token sur
    requête sûre `@CsrfProtect`, **couche 1** sur toute mutation, **couche 2** en plus si
    `@CsrfProtect`. Les routes `bypassFirewall` (callbacks OAuth) sont exemptées
-   (`firewall.ts:743-745`), les `@CsrfExempt` sortent après la barrière méthode sûre
+   (`firewall.ts:950-953`), les `@CsrfExempt` sortent après la barrière méthode sûre
    (`firewall.ts:951`).
 4. `HttpContext.writeHead()` matérialise `context.csrfToken` en cookie `csrf-token` — flush groupé
    avec le cookie de session (`HttpContext.ts:419-432`).
@@ -346,7 +346,7 @@ de session (TSDoc `CsrfTokenManager`, `csrfToken.ts:12-15`).
 L'écran **Firewall** de Studio expose la défense dans son onglet Défenses (`FirewallDefenses`,
 `Firewall.tsx:313-314`). La projection est **sans secret par construction** :
 `Firewall.#describeDefenses()` (`firewall.ts:575`) publie la config résolue, et `synchronizerToken`
-n'est que la **présence** du secret armé — jamais sa valeur (`firewall.ts:557`).
+n'est que la **présence** du secret armé — jamais sa valeur (`firewall.ts:601`).
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 

package/docs/firewall.md

@@ -342,7 +342,7 @@ Ce qui se passe, requête par requête :
 | --- | --- | --- |
 | le cookie de session | `session` | identifié, `apikey` jamais consulté |
 | `Authorization: Bearer nf_…` | `apikey` | identifié (session ne matche pas, on passe) |
-| une clé **révoquée** `nf_…` | `apikey` | **401 direct** — l'échec d'`authenticate()` remonte, pas de fallback (`firewall.ts:1112`) |
+| une clé **révoquée** `nf_…` | `apikey` | **401 direct** — l'échec d'`authenticate()` remonte, pas de fallback (`firewall.ts:1128`) |
 | rien | aucun | **401** (Zero Trust) |
 
 ### Situation 2 — le piège de l'ordre (`anonymous` toujours EN DERNIER)
@@ -377,7 +377,7 @@ Basic …`). Une seule manque → 401. Le **dernier** token de la chaîne porte
 
 > [!TIP]
 > Un nom d'authenticator inconnu en config **fait échouer le boot** —
-> `Firewall.#instantiateAuthenticators()` est fail-closed (`firewall.ts:402`) : jamais de zone
+> `Firewall.#instantiateAuthenticators()` est fail-closed (`firewall.ts:429`) : jamais de zone
 > « protégée » silencieusement ouverte à cause d'une faute de frappe.
 
 ## 🧑‍⚖️ Autorisation — rôles, scopes, voters (« as-tu le droit ? »)
@@ -470,10 +470,10 @@ Sur une socket, un refus n'a pas d'en-tête `WWW-Authenticate` (`Firewall.#setCh
 
 ## 🛡️ En-têtes de sécurité, CSRF, CORS
 
-- **`Firewall.applySecurityHeaders()`** (`firewall.ts:1029`) : CSP, Referrer-Policy, COOP/COEP/CORP
-  au-dessus du socle transport de `@nodefony/http`. **Nonce CSP paresseux** (`hasNonce`, `firewall.ts:855`) :
+- **`Firewall.applySecurityHeaders()`** (`firewall.ts:1045`) : CSP, Referrer-Policy, COOP/COEP/CORP
+  au-dessus du socle transport de `@nodefony/http`. **Nonce CSP paresseux** (`hasNonce`, `firewall.ts:1045`) :
   alloué seulement si une directive en a besoin.
-- **`Firewall.enforceCsrf()`** (défense en profondeur, `firewall.ts:932`) : Fetch Metadata
+- **`Firewall.enforceCsrf()`** (défense en profondeur, `firewall.ts:948`) : Fetch Metadata
   (`Sec-Fetch-Site`) + garde `Origin` (`firewall.ts:764`), puis double-submit `x-csrf-token` ≡
   cookie + HMAC (`firewall.ts:778`).
 - **`Firewall.handleCors()`** : preflight `OPTIONS` → 204 (`firewall.ts:991`).
@@ -482,13 +482,13 @@ Sur une socket, un refus n'a pas d'en-tête `WWW-Authenticate` (`Firewall.#setCh
 
 | Domaine                | Norme           | Ancrage                                                |
 | ---------------------- | --------------- | ------------------------------------------------------ |
-| Challenge d'auth (401) | RFC 7235        | `Firewall.#setChallenge()` (`firewall.ts:1191`)        |
+| Challenge d'auth (401) | RFC 7235        | `Firewall.#setChallenge()` (`firewall.ts:1207`)        |
 | Bearer                 | RFC 6750        | `JwtAuthenticator.ts:13` · `ApiKeyAuthenticator.ts:11` |
 | JWT (BCP)              | RFC 7519, 8725  | `JwtAuthenticator.ts:33-44,104-108`                    |
 | HTTP Basic             | RFC 7617        | `UserPasswordAuthenticator.ts:10-28`                   |
 | Rate limit (429)       | RFC 6585        | 429 + `Retry-After` (`firewall.ts:764`)                |
 | Backoff de login       | NIST SP 800-63B | `UserPasswordAuthenticator.ts:43-46,101-104`           |
-| CSRF                   | Fetch Metadata  | `Firewall.enforceCsrf()` (`firewall.ts:932`)           |
+| CSRF                   | Fetch Metadata  | `Firewall.enforceCsrf()` (`firewall.ts:948`)           |
 | Modèle                 | Zero Trust      | `firewall.ts:611` (aucune preuve → 401)                |
 
 ## ⚡ Performance & mémoire

package/docs/headers.md

@@ -39,7 +39,7 @@ source: "src/packages/@nodefony/security/docs/headers.md"
 > (`@nodefony/http`, dès l'entrée brute — couvre aussi les fichiers statiques et les erreurs) et la
 > couche **applicative** (`@nodefony/security`, dans le pipeline — CSP, Referrer-Policy, isolation
 > cross-origin). Ancré sur `SecurityHeaders` (`securityHeaders.ts:42`) et
-> `Firewall.applySecurityHeaders()` (`firewall.ts:1029`).
+> `Firewall.applySecurityHeaders()` (`firewall.ts:1045`).
 
 📍 [Documentation](../../../../../docs/index.md) › [Sécurité](index.md) › **En-têtes de sécurité**
 
@@ -287,7 +287,7 @@ pour un HTML statique servi directement depuis `public/`.
 avec tes cookies.
 
 Valeur unique reconnue : `nosniff`, posée depuis le cache `secContentTypeOptions`
-(`http-kernel.ts:1334`). C'est **l'en-tête qui justifie le mieux la couche transport** : le danger
+(`http-kernel.ts:963`). C'est **l'en-tête qui justifie le mieux la couche transport** : le danger
 vient précisément des fichiers servis hors pipeline applicatif — un banc live le prouve sur une 404
 (`security-headers.test.ts:38`).
 
@@ -452,7 +452,7 @@ rester imprévisible, jamais pilotable par le client — contrairement au `reque
 une corrélation entrante.
 
 **Placement dans le pipeline** : `applySecurityHeaders` est appelé **après le resolve** et **avant**
-le repli statique et le `writeHead` (`http-kernel.ts:1334`). Cet ordre n'est pas cosmétique : il
+le repli statique et le `writeHead` (`http-kernel.ts:1372`). Cet ordre n'est pas cosmétique : il
 faut que le routeur ait posé les directives `@Csp` de la route pour pouvoir les fusionner, et il faut
 être avant l'écriture des en-têtes pour pouvoir en poser.
 
@@ -510,7 +510,7 @@ Trois propriétés à retenir :
 
 L'exemple de référence vit dans le framework : en développement, `@nodefony/frontend` déclare les
 origines du serveur Vite et `'unsafe-eval'` (exigé par le Fast Refresh de React) via
-`FrontendService.#viteCspFragment()` (`FrontendService.ts:909`) — ce qui explique qu'un CSP observé
+`FrontendService.#viteCspFragment()` (`FrontendService.ts:1012`) — ce qui explique qu'un CSP observé
 en dev soit plus large qu'en production, où ce fragment n'existe pas.
 
 ## 📜 Normes appliquées
@@ -523,7 +523,7 @@ en dev soit plus large qu'en production, où ce fragment n'existe pas.
 | Champ structuré booléen              | RFC 8941                         | `Origin-Agent-Cluster: ?1` (`securityHeaders.ts:75`)         |
 | Referrer-Policy                      | W3C Referrer Policy (enum fermé) | 8 valeurs validées au boot (`config.ts:239`)                 |
 | Isolation cross-origin               | WHATWG HTML (COOP/COEP/CORP)     | `securityHeaders.ts:71`                                      |
-| Anti-MIME-sniffing                   | WHATWG Fetch (`nosniff`)         | `secContentTypeOptions` (`http-kernel.ts:1334`)              |
+| Anti-MIME-sniffing                   | WHATWG Fetch (`nosniff`)         | `secContentTypeOptions` (`http-kernel.ts:963`)               |
 | Durcissement en-têtes                | OWASP Secure Headers             | `computeSecurityHeaderCaches()` (`http-kernel.ts:330`)       |
 
 ## ⚡ Performance & mémoire
@@ -539,7 +539,7 @@ Le coût est concentré au boot, par construction :
   protège en plus les chemins internes qui n'atteignent jamais le firewall.
 - **Merge CSP** : jamais dans le chemin chaud. Le fragment d'un module est fusionné à
   l'enregistrement (`firewall.ts:1067`) ; celui d'une route ne coûte que sur les routes `@Csp`.
-- **Socle transport** : trois `setHeader` sur des chaînes précalculées (`http-kernel.ts:1334`), avec
+- **Socle transport** : trois `setHeader` sur des chaînes précalculées (`http-kernel.ts:958-966`), avec
   un test `!== null` qui annule le coût des en-têtes désactivés.
 
 Le module n'attache aucun écouteur d'événement et ne conserve aucun état par requête : il n'entre pas
@@ -550,7 +550,7 @@ dans le périmètre du gate mémoire, qu'il ne peut structurellement pas dégrad
 L'écran **Firewall** de Studio affiche la section « En-têtes de sécurité » — pilotée par
 `headers.enabled` (`FirewallDefenses.tsx:219`) — avec le CSP effectif, l'état du nonce par requête, la
 Referrer-Policy et les valeurs d'isolation. Les données
-viennent de `Firewall.describe()` (`firewall.ts:505`), qui projette la config **sans aucun secret**,
+viennent de `Firewall.describe()` (`firewall.ts:549`), qui projette la config **sans aucun secret**,
 exposée par `GET /nodefony/security/api/firewall`.
 
 L'onglet **Configuration** de Studio rend les mêmes options depuis le schéma Zod — chaque champ y

package/docs/index.md

@@ -138,6 +138,30 @@ Services `Firewall`, `AuthFlow`, `TokenService`, `ApiKeyService`, `Authorization
 Les signatures exactes vivent dans le graphe généré — `jq '.symbols.Firewall' .ai/symbols.json` —
 jamais recopiées ici (elles divergeraient).
 
+## 🛠️ Gérer les comptes en exploitation
+
+Sur un serveur, la console d'administration suppose d'y être déjà entré — ce qui est précisément
+impossible quand on a perdu le mot de passe. Ces commandes sont l'autre porte, et elles s'exécutent
+sans ouvrir de port (profil console) :
+
+<!-- prettier-ignore -->
+| Commande | Ce qu'elle fait |
+| --- | --- |
+| `nodefony security:user:add <id> [--admin]` | crée un compte, puis dit comment s'authentifier |
+| `nodefony security:user:list [-q <motif>]` | identifiant, rôles, état |
+| `nodefony security:user:password <id>` | change le mot de passe — **et révoque sessions et jetons** |
+| `nodefony security:user:delete <id>` | supprime, après confirmation ; refuse le dernier administrateur |
+| `nodefony security:secrets [--write]` | engendre les clés attendues et guide leur câblage |
+| `nodefony security:token` | émet un jeton d'accès pour la porte MCP |
+
+En terminal, le mot de passe est **demandé masqué** et confirmé ; pour un script, `--password <pwd>`
+l'accepte en argument — au prix de l'historique du shell, que la commande rappelle.
+
+Deux garde-fous qui se constatent plutôt qu'ils ne se supposent : le **dernier administrateur actif
+ne se supprime pas** (`security-user-delete.ts:101`), et un changement de mot de passe **éjecte les
+accès en cours** par la même cascade que la suppression (`userRevocationCascade.ts:37`) — on change
+un mot de passe parce qu'il est perdu ou compromis.
+
 ## ⚙️ Configuration
 
 Un seul point d'entrée : `use("@nodefony/security", { … })` dans `nodefony.config.ts`, validé par Zod