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

package/README.md

@@ -179,4 +179,4 @@ Un **secret n'entre jamais** dans un événement — seule sa _présence_ est tr
 
 ## Licence
 
-CeCILL-B — Christophe CAMENSULI.
+Apache 2.0 — Christophe CAMENSULI.

package/dist/index.js

@@ -73,6 +73,7 @@ import SecuritySecrets from "./nodefony/command/security-secrets.js";
 import SecurityUserAdd from "./nodefony/command/security-user-add.js";
 import SecurityUserList from "./nodefony/command/security-user-list.js";
 import SecurityUserDelete from "./nodefony/command/security-user-delete.js";
+import SecurityUserPassword from "./nodefony/command/security-user-password.js";
 import SecurityToken from "./nodefony/command/security-token.js";
 import { createSecurityAdminApi, parseAuditQuery, registerSecurityAdminApi } from "./nodefony/src/admin/SecurityAdminApi.js";
 import { registerUserRevocationCascade } from "./nodefony/src/admin/userRevocationCascade.js";
@@ -108,6 +109,7 @@ let Security = class Security extends Module {
 		this.addCommand(SecurityUserAdd);
 		this.addCommand(SecurityUserList);
 		this.addCommand(SecurityUserDelete);
+		this.addCommand(SecurityUserPassword);
 		this.addCommand(SecurityToken);
 	}
 	/**

package/dist/nodefony/command/security-user-add.js

@@ -16,6 +16,22 @@ const ADMIN_ROLES = ["ROLE_ADMIN", "ROLE_NODEFONY_ADMIN"];
 /** Rôle de base, toujours proposé même si l'application n'en déclare aucun. */
 const ROLE_BASE = "ROLE_USER";
 /**
+* La route qui échange un compte contre une SESSION — le geste qui manquait.
+*
+* Créer un compte ne sert à rien tant qu'on ne sait pas s'en servir : mesuré,
+* 33 minutes d'un essai réel se sont passées entre un premier refus et
+* l'abandon, faute de savoir quoi appeler. La commande dit donc l'étape
+* suivante au moment où elle a un sens.
+*
+* ⚠️ La route est MONTÉE ailleurs — `mountSessionAuthRoutes` du module
+* framework — et ce paquet ne peut pas l'importer pour la lire (le montage est
+* conditionné au service `authFlow`, et la valeur ne vit dans aucune constante
+* exportée). La copie est donc assumée, et un test la CONFRONTE à la table du
+* controller : deux copies qui divergent en silence, c'est précisément ce
+* qu'on refuse.
+*/
+const AUTH_LOGIN_PATH = "/nodefony/security/api/auth/login";
+/**
 * `nodefony security:user:add [identifier]` — crée un compte utilisateur via le
 * service applicatif `users` (hash Argon2id fait par `UserService.createUser`,
 * jamais de mot de passe stocké en clair).
@@ -80,7 +96,7 @@ var SecurityUserAdd = class extends Command {
 			return this;
 		}
 		if (await users.findByIdentifier(identifier)) {
-			this.log(`le compte « ${identifier} » existe déjà.\n  · le voir       : nodefony security:user:list -q ${identifier}\n  · le supprimer  : nodefony security:user:delete ${identifier}\n  · mot de passe oublié : par Studio (/nodefony) — la commande n'existe pas encore.`, "ERROR");
+			this.log(`le compte « ${identifier} » existe déjà.\n  · le voir       : nodefony security:user:list -q ${identifier}\n  · le supprimer  : nodefony security:user:delete ${identifier}\n  · mot de passe oublié : nodefony security:user:password ${identifier}`, "ERROR");
 			process.exitCode = 1;
 			return this;
 		}
@@ -124,9 +140,9 @@ var SecurityUserAdd = class extends Command {
 			plainPassword: password,
 			roles
 		});
-		process.stdout.write(`\n${GREEN}✓ compte créé${RESET} — ${BOLD}${user.identifier}${RESET} ${DIM}(id ${user.id})${RESET}\n  rôles : ${roles.join(" · ")}\n` + (opts.admin ? `  ${DIM}accès console Studio : /nodefony${RESET}\n` : "") + (opts.password ? `  ${YELLOW}⚠ mot de passe passé en argument — pense à purger l'historique shell${RESET}\n` : ""));
+		process.stdout.write(`\n${GREEN}✓ compte créé${RESET} — ${BOLD}${user.identifier}${RESET} ${DIM}(id ${user.id})${RESET}\n  rôles : ${roles.join(" · ")}\n` + (opts.admin ? `  ${DIM}accès console Studio : /nodefony${RESET}\n` : "") + `  ${DIM}pour t'authentifier : POST ${AUTH_LOGIN_PATH}${RESET}\n  ${DIM}  body JSON {"username","password"} → cookie de session ; l'identité courante se relit sur GET /nodefony/security/api/auth/me${RESET}\n` + (opts.password ? `  ${YELLOW}⚠ mot de passe passé en argument — pense à purger l'historique shell${RESET}\n` : ""));
 		return this;
 	}
 };
 //#endregion
-export { SecurityUserAdd as default };
+export { AUTH_LOGIN_PATH, SecurityUserAdd as default };

package/dist/nodefony/command/security-user-password.js

@@ -0,0 +1,111 @@
+import { CONSOLE_DATA_RUN_PROFILE, Command, askPasswordMasked } from "nodefony";
+import { USER_REVOKED_EVENT } from "@nodefony/user";
+//#region nodefony/command/security-user-password.ts
+const options = {
+	runProfile: CONSOLE_DATA_RUN_PROFILE,
+	helpGroup: "COMPTES ET SECRETS",
+	showBanner: false,
+	kernelEvent: "onPostReady",
+	quietBoot: true
+};
+const GREEN = "\x1B[32m";
+const YELLOW = "\x1B[33m";
+const DIM = "\x1B[2m";
+const BOLD = "\x1B[1m";
+const RESET = "\x1B[0m";
+/**
+* `nodefony security:user:password [identifiant]` — change le mot de passe d'un
+* compte.
+*
+* Le geste d'exploitation qui manquait : `user:add`, `user:list` et
+* `user:delete` existaient, mais un mot de passe perdu n'avait aucun recours en
+* ligne de commande — seule la console d'administration savait le faire, ce qui
+* suppose d'y être déjà entré. Sur un serveur, c'est précisément le cas où l'on
+* ne peut pas.
+*
+* Mot de passe : `--password` (visible dans l'historique shell — accepté pour
+* les scripts) ou PROMPT MASQUÉ en TTY, demandé deux fois. Le hachage est celui
+* du service (`UserService.changePassword` → Argon2id) : jamais de clair
+* persisté, et la liste de mots de passe interdits s'applique comme à la
+* création.
+*
+* 🔒 **Les sessions et les jetons du compte sont RÉVOQUÉS**, et ce n'est pas une
+* option : on change un mot de passe parce qu'il est compromis ou perdu, et
+* laisser vivre les sessions ouvertes laisserait l'accès à qui l'a volé. La
+* révocation passe par l'événement que la suppression emploie déjà — une
+* cascade, un seul canal, et les abonnés futurs (webhooks) en profitent sans
+* rien changer ici.
+*/
+var SecurityUserPassword = class extends Command {
+	constructor(cli) {
+		super("security:user:password", "change le mot de passe d'un compte", cli, options);
+		this.addArgument("[identifier]", "identifiant (login) du compte");
+		this.addOption("-p, --password <password>", "nouveau mot de passe (sinon : prompt masqué en TTY)");
+	}
+	async generate(identifierArg, opts) {
+		const users = this.kernel?.container?.get("users");
+		if (!users) {
+			this.log("service « users » absent — l'application ne provisionne pas son annuaire utilisateurs (cf nodefony/security/provisionUsers.ts d'une app générée).", "ERROR");
+			process.exitCode = 1;
+			return this;
+		}
+		let identifier;
+		try {
+			identifier = await this.askArgument(identifierArg, {
+				name: "identifier",
+				message: "Compte dont changer le mot de passe :"
+			});
+		} catch (e) {
+			this.log(e.message, "ERROR");
+			process.exitCode = 1;
+			return this;
+		}
+		const user = await users.findByIdentifier(identifier);
+		if (!user) {
+			this.log(`aucun compte « ${identifier} » — nodefony security:user:list`, "ERROR");
+			process.exitCode = 1;
+			return this;
+		}
+		let password = opts.password;
+		if (!password) {
+			if (!process.stdin.isTTY) {
+				this.log("mot de passe requis : --password <pwd> (pas de prompt hors terminal).", "ERROR");
+				process.exitCode = 1;
+				return this;
+			}
+			password = await askPasswordMasked(`${BOLD}Nouveau mot de passe de « ${identifier} »${RESET} ${DIM}(frappe masquée)${RESET} : `);
+			const confirmed = await askPasswordMasked(`${BOLD}Confirme le mot de passe${RESET} : `);
+			if (password !== confirmed) {
+				this.log("les deux saisies diffèrent — rien n'a changé.", "ERROR");
+				process.exitCode = 1;
+				return this;
+			}
+		}
+		if (!password) {
+			this.log("mot de passe vide — rien n'a changé.", "ERROR");
+			process.exitCode = 1;
+			return this;
+		}
+		try {
+			if (await users.changePassword(user.id, password) === null) {
+				this.log(`aucune ligne modifiée pour « ${identifier} » — le compte a-t-il disparu entre-temps ?`, "ERROR");
+				process.exitCode = 1;
+				return this;
+			}
+		} catch (e) {
+			this.log(e.message, "ERROR");
+			process.exitCode = 1;
+			return this;
+		}
+		this.kernel?.fire(USER_REVOKED_EVENT, {
+			id: user.id,
+			identifier: user.identifier,
+			tenantId: null,
+			reason: "password_changed"
+		});
+		process.stdout.write(`\n${GREEN}✓ mot de passe changé${RESET} — ${BOLD}${user.identifier}${RESET}\n${DIM}  ses sessions et ses jetons sont révoqués : il devra se reconnecter.${RESET}\n${DIM}  connexion : POST /nodefony/security/api/auth/login${RESET}\n` + (opts.password ? `  ${YELLOW}⚠ mot de passe passé en argument — pense à purger l'historique shell${RESET}\n` : "") + "\n");
+		return this;
+	}
+};
+//#endregion
+export { SecurityUserPassword as default };

package/dist/nodefony/src/token/JwtKeystore.js

@@ -2,6 +2,40 @@ import { messageNonRestreint, modeNonRestreintAsync, readIfPresent, writeSecret
 import { join } from "node:path";
 //#region nodefony/src/token/JwtKeystore.ts
 /**
+* Dossiers que le `Dockerfile` généré EFFACE à l'étage de construction.
+*
+* La liste est ici parce que c'est ici qu'on s'en sert ; elle est tenue honnête
+* par le test qui la confronte au gabarit — deux copies d'une même règle
+* divergent en silence, et c'est une clé privée qui paierait la dérive.
+*/
+const CLEANED_DIRS = ["var", "tmp"];
+/**
+* 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é.
+*/
+function keystoreLeaksIntoImage(dir) {
+	const normalized = dir.replace(/\\/gu, "/").replace(/^\.\//u, "");
+	if (normalized.startsWith("/") || /^[A-Za-z]:/u.test(normalized)) return null;
+	const first = normalized.split("/")[0];
+	if (CLEANED_DIRS.includes(first)) return null;
+	return `JWT keystore: « ${dir} » n'est PAS sous ${CLEANED_DIRS.map((d) => `\`${d}/\``).join(" ni ")}, les seuls dossiers que le Dockerfile généré efface avant de fabriquer l'image. La clé privée de signature partira donc dans ton image de conteneur, où elle reste lisible par quiconque la télécharge — même effacée par une couche suivante. Deux issues : déplacer le dossier sous \`var/\` (ex. \`var/keys\`), ou injecter la clé par jwt.keystore.keySetJson depuis l'environnement, ce qui est la voie de production.`;
+}
+/**
 * Keystore Ed25519 — implémentation de référence d'{@link IJwtKeystore}.
 *
 * Résout la clé de signature selon une **priorité** (jamais d'auto-génération en
@@ -61,6 +95,8 @@ var JwtKeystore = class {
 			return;
 		}
 		if (this.#source.dir) {
+			const risk = keystoreLeaksIntoImage(this.#source.dir);
+			if (risk) this.#log(risk, "WARNING");
 			const file = join(this.#source.dir, "keyset.json");
 			const existing = await this.#readFile(file);
 			if (existing) {
@@ -157,4 +193,4 @@ var JwtKeystore = class {
 	}
 };
 //#endregion
-export { JwtKeystore, JwtKeystore as default };
+export { JwtKeystore, JwtKeystore as default, keystoreLeaksIntoImage };

package/dist/types/nodefony/command/security-user-add.d.ts

@@ -1,4 +1,20 @@
 import { CliKernel, Command } from "nodefony";
+/**
+ * La route qui échange un compte contre une SESSION — le geste qui manquait.
+ *
+ * Créer un compte ne sert à rien tant qu'on ne sait pas s'en servir : mesuré,
+ * 33 minutes d'un essai réel se sont passées entre un premier refus et
+ * l'abandon, faute de savoir quoi appeler. La commande dit donc l'étape
+ * suivante au moment où elle a un sens.
+ *
+ * ⚠️ La route est MONTÉE ailleurs — `mountSessionAuthRoutes` du module
+ * framework — et ce paquet ne peut pas l'importer pour la lire (le montage est
+ * conditionné au service `authFlow`, et la valeur ne vit dans aucune constante
+ * exportée). La copie est donc assumée, et un test la CONFRONTE à la table du
+ * controller : deux copies qui divergent en silence, c'est précisément ce
+ * qu'on refuse.
+ */
+export declare const AUTH_LOGIN_PATH = "/nodefony/security/api/auth/login";
 /**
  * `nodefony security:user:add [identifier]` — crée un compte utilisateur via le
  * service applicatif `users` (hash Argon2id fait par `UserService.createUser`,

package/dist/types/nodefony/command/security-user-password.d.ts

@@ -0,0 +1,31 @@
+import { CliKernel, Command } from "nodefony";
+/**
+ * `nodefony security:user:password [identifiant]` — change le mot de passe d'un
+ * compte.
+ *
+ * Le geste d'exploitation qui manquait : `user:add`, `user:list` et
+ * `user:delete` existaient, mais un mot de passe perdu n'avait aucun recours en
+ * ligne de commande — seule la console d'administration savait le faire, ce qui
+ * suppose d'y être déjà entré. Sur un serveur, c'est précisément le cas où l'on
+ * ne peut pas.
+ *
+ * Mot de passe : `--password` (visible dans l'historique shell — accepté pour
+ * les scripts) ou PROMPT MASQUÉ en TTY, demandé deux fois. Le hachage est celui
+ * du service (`UserService.changePassword` → Argon2id) : jamais de clair
+ * persisté, et la liste de mots de passe interdits s'applique comme à la
+ * création.
+ *
+ * 🔒 **Les sessions et les jetons du compte sont RÉVOQUÉS**, et ce n'est pas une
+ * option : on change un mot de passe parce qu'il est compromis ou perdu, et
+ * laisser vivre les sessions ouvertes laisserait l'accès à qui l'a volé. La
+ * révocation passe par l'événement que la suppression emploie déjà — une
+ * cascade, un seul canal, et les abonnés futurs (webhooks) en profitent sans
+ * rien changer ici.
+ */
+declare class SecurityUserPassword extends Command {
+    constructor(cli: CliKernel);
+    generate(identifierArg: string | undefined, opts: {
+        password?: string;
+    }): Promise<this>;
+}
+export default SecurityUserPassword;

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