@nodefony/security 10.0.0-alpha.1

package/dist/nodefony/service/firewall.js

@@ -0,0 +1,699 @@
+import { SecuredArea } from "../src/SecuredArea.js";
+import { LoginThrottler } from "../src/throttle/LoginThrottler.js";
+import { RoleHierarchyWalker } from "../src/RoleHierarchyWalker.js";
+import { mergeCspFragments } from "../src/csp.js";
+import { CsrfTokenManager } from "../src/csrfToken.js";
+import { CsrfError } from "../errors/CsrfError.js";
+import { Csrf } from "./csrf.js";
+import { Cors } from "./cors.js";
+import { SecurityHeaders } from "./securityHeaders.js";
+import { AuthenticationError } from "../errors/AuthenticationError.js";
+import { ThrottledError } from "../errors/ThrottledError.js";
+import { UnverifiableTokenError } from "../errors/UnverifiableTokenError.js";
+import { defineSecurityConfig } from "../config/defineModuleConfig.js";
+import { getAuthenticatorFactory, listAuthenticatorFactories } from "../src/authenticator/authenticatorRegistry.js";
+import { FirewallRealtimeAuthenticator } from "../src/authenticator/FirewallRealtimeAuthenticator.js";
+import { DEFAULT_SYSTEM_RULES, buildFrameAuthorizer, buildSystemRules } from "../src/realtime/frameAuthorizer.js";
+import { recordAudit } from "../src/audit/recordAudit.js";
+import { readAuditContext } from "../src/audit/readAuditContext.js";
+import { SECURITY_AUDIT_CHANNEL, createAuditBridge } from "../src/audit/auditBridge.js";
+import { RequestContext, Service, logColor } from "nodefony";
+import { encoderFromConfig } from "@nodefony/user";
+import { randomBytes } from "node:crypto";
+//#region nodefony/service/firewall.ts
+const serviceName = "firewall";
+/**
+* Réponse partagée de {@link Firewall.publishedProtectedResources} quand il n'y
+* a rien à publier — le cas de l'immense majorité des applications. Gelée et
+* réutilisée : allouer un tableau vide pour dire « rien » est exactement le
+* genre de dépense que la règle de lazy-allocation proscrit.
+*/
+const EMPTY_PROTECTED_RESOURCES = Object.freeze([]);
+function headerValue(headers, name) {
+	const v = headers?.[name];
+	return Array.isArray(v) ? v[0] : v;
+}
+/**
+* Extrait la valeur d'un cookie de l'en-tête `Cookie` brut (lecture directe, sans
+* dépendre du parse du Context — robuste quel que soit l'ordre du pipeline).
+* Retient la 1ʳᵉ occurrence du nom. Utilisé par la défense synchronizer CSRF.
+*/
+function cookieValue(cookieHeader, name) {
+	if (!cookieHeader) return void 0;
+	for (const part of cookieHeader.split(";")) {
+		const eq = part.indexOf("=");
+		if (eq === -1) continue;
+		if (part.slice(0, eq).trim() === name) return decodeURIComponent(part.slice(eq + 1).trim());
+	}
+}
+/**
+* Orchestrateur de sécurité Nodefony — refonte 2026 (P6).
+*
+* `isSecure()` (hot-path, court-circuit si aucune zone) ne fait QUE matcher la
+* zone et poser `context.security`. `handleSecurity()` (lazy, seulement sur une
+* zone protégée) exécute la chaîne d'authentication selon le `mode` de la zone
+* (`first` : le premier qui reconnaît la requête authentifie ; `all` : tous
+* doivent passer, le dernier porte l'identité) → propage l'utilisateur dans
+* l'ALS → applique le **Zero Trust** (zone protégée sans preuve acceptée → 401,
+* sauf anonymat explicite via l'authenticator `anonymous`).
+*
+* **Fail-closed** : config invalide au boot (Zod, nom d'authenticator inconnu)
+* → le firewall capture TOUT le trafic et répond 401 (jamais une app servie
+* sans sa sécurité). Erreur interne pendant l'authentification (source
+* d'identité down, câblage manquant) → log ERROR serveur + 401 générique
+* (aucun détail ne fuite au client).
+*
+* Conformité : tout 401 porte un challenge `WWW-Authenticate` (RFC 7235) fourni
+* par le premier authenticator de la zone qui en déclare un.
+*
+* CORS, CSRF et autorisation par décorateurs viennent se brancher en S4/S5.
+* Toutes les structures sont **lazy** (perf : une app sans zone = zéro alloc).
+*/
+var Firewall = class extends Service {
+	module;
+	#areas = null;
+	#authenticators = null;
+	#roleHierarchy = null;
+	#csrf = null;
+	#csrfTokens = null;
+	#cors = null;
+	#securityHeaders = null;
+	#cspFragments = null;
+	#config = null;
+	#configError = null;
+	constructor(module) {
+		super(serviceName, module.container, module.notificationsCenter, module.options);
+		this.module = module;
+		this.kernel?.once("onBoot", () => this.#build());
+	}
+	#build() {
+		try {
+			this.#config = defineSecurityConfig(this.options);
+		} catch (e) {
+			this.#configError = e;
+			this.log(`Security configuration INVALID — firewall fail-closed, ALL requests rejected: ${e.message}`, "CRITIC");
+			return;
+		}
+		this.#roleHierarchy = new RoleHierarchyWalker(this.#config.roleHierarchy);
+		this.container?.set("roleHierarchy", this.#roleHierarchy);
+		this.#provisionSharedServices(this.#config);
+		if (this.#config.csrf.enabled) {
+			this.#csrf = new Csrf(this.#config.csrf, [...this.#config.csrf.trustedOrigins, ...this.#config.cors.origins]);
+			let secret = this.#config.csrf.secret;
+			if (!secret) {
+				secret = randomBytes(32).toString("base64url");
+				this.log("csrf.secret absent → secret synchronizer ÉPHÉMÈRE généré (dev). En PROD/cluster, fixer csrf.secret (≥16 car., partagé entre process) — générer la clé et le câblage : `npx nodefony security:secrets`.", "WARNING");
+			}
+			this.#csrfTokens = new CsrfTokenManager(secret);
+		}
+		if (this.#config.cors.enabled) this.#cors = new Cors(this.#config.cors);
+		if (this.#config.headers.enabled) this.#securityHeaders = new SecurityHeaders(this.#config.headers);
+		const areas = this.#config.areas;
+		const names = Object.keys(areas);
+		if (names.length) {
+			const list = [];
+			for (const name of names) list.push(new SecuredArea(name, areas[name]));
+			list.sort((a, b) => b.pattern.source.length - a.pattern.source.length);
+			this.#areas = list;
+			this.#instantiateAuthenticators(list);
+		}
+		if (!this.#configError) {
+			this.#wireRealtime();
+			this.log(`Firewall ready — ${this.#areas?.length ?? 0} area(s), ${this.#authenticators?.size ?? 0} authenticator(s)`, "DEBUG");
+		}
+	}
+	#wireRealtime() {
+		const realtime = this.container?.get("realtimeService");
+		if (!realtime) return;
+		let wired = false;
+		for (const area of this.#areas ?? []) {
+			if (!area.security || !area.realtime) continue;
+			const matcher = area.host ? {
+				pattern: area.pattern,
+				host: area.host
+			} : { pattern: area.pattern };
+			realtime.useAuthenticator(matcher, new FirewallRealtimeAuthenticator(() => this.container?.get("tokenStore") ?? null));
+			wired = true;
+		}
+		const configRules = (this.#config?.realtimeChannels ?? []).map((r) => ({
+			prefix: r.pattern,
+			policy: {
+				authenticated: r.authenticated,
+				roles: r.roles,
+				scopes: r.scopes
+			}
+		}));
+		const reserved = realtime.reservedSystemPrefixes?.();
+		const defaultRules = reserved && reserved.length > 0 ? buildSystemRules(reserved) : DEFAULT_SYSTEM_RULES;
+		const systemRules = configRules.length > 0 ? [...configRules, ...defaultRules] : defaultRules;
+		const container = this.container;
+		realtime.setFrameAuthorizer(buildFrameAuthorizer(this, {
+			channelResolver: realtime,
+			systemRules,
+			onDeny: (_surface, target, reason, token) => recordAudit(container, {
+				category: "ws",
+				action: "frame.denied",
+				outcome: "denied",
+				actor: token.getUserIdentifier(),
+				resource: target,
+				reason
+			})
+		}), { silentProbe: buildFrameAuthorizer(this, {
+			channelResolver: realtime,
+			systemRules
+		}) });
+		const auditSource = this.container?.get("auditService");
+		if (auditSource && realtime.registerSystemChannel) realtime.registerSystemChannel(SECURITY_AUDIT_CHANNEL, (ch, publish) => createAuditBridge(auditSource, publish, ch));
+		this.log(wired ? "Realtime data plane locked — WS handshake authenticators (RBAC) + frame authorizer + audit channel wired" : "Realtime data plane locked — frame authorizer (system floor) wired without qualifying zone; system channels closed to anonymous", "DEBUG");
+	}
+	#provisionSharedServices(config) {
+		const specs = Object.values(config.encoders);
+		if (specs.length > 0) this.container?.set("passwordEncoder", encoderFromConfig(specs));
+		const rl = config.rateLimit;
+		if (rl.enabled) this.container?.set("loginThrottler", new LoginThrottler({
+			freeAttempts: rl.freeAttempts,
+			baseDelayS: rl.baseDelayS,
+			capDelayS: rl.capDelayS,
+			maxTracked: rl.maxTracked
+		}));
+	}
+	#instantiateAuthenticators(areas) {
+		for (const area of areas) for (const name of area.authenticators) {
+			if (!this.#authenticators?.has(name)) {
+				const factory = getAuthenticatorFactory(name);
+				if (!factory) {
+					this.#configError = /* @__PURE__ */ new Error(`area "${area.name}": authenticator "${name}" unknown — registered: [${listAuthenticatorFactories().join(", ")}]`);
+					this.log(`Security configuration INVALID — ${this.#configError.message}`, "CRITIC");
+					return;
+				}
+				this.registerAuthenticator(factory({
+					container: this.container,
+					config: this.#config
+				}));
+			}
+			const authenticator = this.#authenticators?.get(name);
+			try {
+				authenticator?.validateArea?.(area);
+			} catch (error) {
+				this.#configError = error;
+				this.log(`Security configuration INVALID — ${error.message}`, "CRITIC");
+				return;
+			}
+		}
+	}
+	/** Hiérarchie de rôles résolue (niveau A de l'autorisation, P6.8). */
+	get roleHierarchy() {
+		return this.#roleHierarchy ??= new RoleHierarchyWalker();
+	}
+	/**
+	* `true` si l'un des rôles de l'utilisateur couvre `required` (hiérarchie
+	* comprise). Surface lue par le verrou de frame WS ({@link buildFrameAuthorizer})
+	* pour le RBAC par canal — délègue au {@link RoleHierarchyWalker}.
+	*/
+	hasRole(userRoles, required) {
+		return this.roleHierarchy.hasRole(userRoles, required);
+	}
+	registerAuthenticator(authenticator) {
+		(this.#authenticators ??= /* @__PURE__ */ new Map()).set(authenticator.name, authenticator);
+	}
+	getArea(name) {
+		return this.#areas?.find((a) => a.name === name);
+	}
+	/**
+	* Projection LECTURE SEULE de l'état RUNTIME (data plane Studio P6.15) — décrit
+	* ce qui TOURNE (zones montées, authenticators instanciés, défenses résolues),
+	* pas la config brute. **Secrets exclus par construction** (le synchronizer CSRF
+	* et la clé JWT ne sont JAMAIS exposés — on remonte leur PRÉSENCE, pas leur
+	* valeur, comme le journal d'audit). Cold-path admin (lecture rare) → 0
+	* contrainte hot-path.
+	*/
+	/**
+	* État RÉEL des trois en-têtes de transport (HSTS, X-Frame-Options,
+	* X-Content-Type-Options), lu chez celui qui les émet : `@nodefony/http`.
+	*
+	* Pourquoi ne pas lire la config `security` : ses clés `hsts`/`frameguard`/
+	* `noSniff` sont conservées pour la compatibilité mais **inertes** — leur
+	* `.meta({ reserved: true })` le dit. Une console d'administration qui affiche
+	* une valeur inerte comme si elle était appliquée ne se contente pas d'être
+	* inexacte : elle donne à l'exploitant une fausse assurance sur sa défense.
+	*
+	* @param config - config security, utilisée en repli si le HttpKernel est absent.
+	*/
+	#transportHeaderState(config) {
+		const emitted = (this.container?.get("HttpKernel"))?.describeTransportSecurityHeaders?.();
+		if (!emitted) return {
+			hsts: config.headers.hsts,
+			hstsMaxAgeS: config.headers.hstsMaxAgeS,
+			frameguard: config.headers.frameguard,
+			noSniff: config.headers.noSniff
+		};
+		const hstsHeader = emitted.strictTransportSecurity;
+		return {
+			hsts: hstsHeader !== null,
+			hstsMaxAgeS: hstsHeader ? Number.parseInt(/max-age=(\d+)/.exec(hstsHeader)?.[1] ?? "0", 10) : 0,
+			frameguard: (emitted.frameOptions ?? "").toUpperCase() === "SAMEORIGIN" ? "sameorigin" : "deny",
+			noSniff: emitted.contentTypeOptions !== null
+		};
+	}
+	describe() {
+		const config = this.#config;
+		const mounted = this.#authenticators;
+		const zones = (this.#areas ?? []).map((a) => ({
+			name: a.name,
+			pattern: a.pattern.source,
+			security: a.security,
+			stateless: a.stateless,
+			mode: a.mode,
+			authenticators: [...a.authenticators],
+			allowsAnonymous: a.authenticators.includes("anonymous"),
+			host: a.host ?? null,
+			realtime: a.realtime
+		}));
+		const available = new Set(listAuthenticatorFactories());
+		const names = new Set(available);
+		if (mounted) for (const n of mounted.keys()) names.add(n);
+		const authenticators = [...names].sort().map((name) => ({
+			name,
+			mounted: mounted?.has(name) ?? false,
+			available: available.has(name),
+			challenge: typeof mounted?.get(name)?.challenge === "function"
+		}));
+		return {
+			configValid: !this.#configError,
+			configError: this.#configError ? this.#configError.message : null,
+			zones,
+			authenticators,
+			defenses: config ? this.#describeDefenses(config) : null
+		};
+	}
+	#describeDefenses(config) {
+		return {
+			csrf: {
+				enabled: config.csrf.enabled,
+				fetchMetadata: config.csrf.fetchMetadata,
+				checkOrigin: config.csrf.checkOrigin,
+				strictSameSite: config.csrf.strictSameSite,
+				sameSite: config.csrf.sameSite,
+				trustedOrigins: [...config.csrf.trustedOrigins],
+				synchronizerToken: this.#csrfTokens !== null
+			},
+			cors: {
+				enabled: config.cors.enabled,
+				origins: [...config.cors.origins],
+				credentials: config.cors.credentials,
+				methods: [...config.cors.methods],
+				allowedHeaders: [...config.cors.allowedHeaders],
+				exposedHeaders: [...config.cors.exposedHeaders],
+				maxAgeS: config.cors.maxAgeS
+			},
+			headers: {
+				enabled: config.headers.enabled,
+				...this.#transportHeaderState(config),
+				csp: config.headers.csp,
+				cspNonces: config.headers.cspNonces,
+				referrerPolicy: config.headers.referrerPolicy,
+				coop: config.headers.coop,
+				coep: config.headers.coep,
+				corp: config.headers.corp,
+				originAgentCluster: config.headers.originAgentCluster,
+				permissionsPolicy: config.headers.permissionsPolicy
+			},
+			rateLimit: {
+				enabled: config.rateLimit.enabled,
+				freeAttempts: config.rateLimit.freeAttempts,
+				baseDelayS: config.rateLimit.baseDelayS,
+				capDelayS: config.rateLimit.capDelayS
+			}
+		};
+	}
+	/**
+	* Hiérarchie de rôles déclarée + résolution transitive (data plane Studio).
+	* Brut = ce que l'app a écrit ; `inherits` = aplati précalculé par le walker.
+	*/
+	describeRoleHierarchy() {
+		const raw = this.#config?.roleHierarchy ?? {};
+		const hierarchy = {};
+		for (const role of Object.keys(raw)) hierarchy[role] = [...raw[role]];
+		const walker = this.roleHierarchy;
+		return {
+			hierarchy,
+			roles: Object.keys(hierarchy).map((role) => ({
+				role,
+				inherits: [...walker.reachableRoles([role])].filter((r) => r !== role).sort()
+			}))
+		};
+	}
+	/**
+	* Ce que l'application PROTÈGE, à publier en RFC 9728 — une entrée par
+	* ressource déclarée par une zone.
+	*
+	* ⭐ **Même donnée que le défi, donc impossible qu'ils divergent.** Le `401`
+	* d'une zone porte `resource_metadata="…/.well-known/oauth-protected-resource
+	* /<chemin de `area.resource`>"` ; ce que rend cette méthode est la source de
+	* ce que `@nodefony/framework` monte à cette URL. Une seconde déclaration —
+	* une clé « ressources publiées » à côté des zones — se serait périmée au
+	* premier renommage, et le symptôme aurait été un `404` que rien n'explique.
+	*
+	* 🔴 **Les serveurs d'autorisation sont les émetteurs de confiance, pas une
+	* liste à part.** `authorization_servers` répond à « qui peut délivrer un
+	* jeton pour cette ressource ? » — c'est exactement l'allowlist
+	* `resourceServer.issuers`, la seule que le vérificateur consulte. Publier
+	* autre chose reviendrait à envoyer le client demander un jeton à un émetteur
+	* dont on refuse ensuite la signature.
+	*
+	* Aucun émetteur de confiance ⇒ **rien à publier** : un document sans serveur
+	* d'autorisation apprendrait au client qu'un jeton est nécessaire sans jamais
+	* lui dire où l'obtenir (et la RFC 9728 comme la spécification MCP l'excluent).
+	*
+	* Appelée UNE fois, au montage des routes (`onKernelReady`) — hors hot path,
+	* d'où l'allocation directe plutôt qu'un cache à invalider.
+	*
+	* @returns les ressources protégées déclarées, éventuellement vide
+	*/
+	publishedProtectedResources() {
+		const config = this.#config;
+		if (!config) return EMPTY_PROTECTED_RESOURCES;
+		const authorizationServers = config.resourceServer.issuers.map((i) => i.issuer).filter((issuer) => typeof issuer === "string" && issuer.length > 0);
+		if (authorizationServers.length === 0) return EMPTY_PROTECTED_RESOURCES;
+		const published = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const area of this.#areas ?? []) {
+			if (!area.resource || seen.has(area.resource)) continue;
+			seen.add(area.resource);
+			published.push({
+				resource: area.resource,
+				authorizationServers
+			});
+		}
+		return published.length > 0 ? published : EMPTY_PROTECTED_RESOURCES;
+	}
+	/**
+	* Match de zone par pathname (+ host) SANS contexte — source UNIQUE consultée
+	* par `isSecure` (HTTP) ET le verrou WebSocket (la frame `api.request` n'a
+	* qu'un path). Hot-path : patterns pré-compilés + pathname fourni → 0 alloc.
+	*/
+	matchPath(pathname, host) {
+		if (!this.#areas) return null;
+		for (const area of this.#areas) if (area.matchPath(pathname, host)) return area;
+		return null;
+	}
+	/** Match rapide de zone — pose `context.security`. `true` si zone capturée. */
+	isSecure(context) {
+		if (this.#configError) return true;
+		if (!this.#areas) return false;
+		const req = context.request;
+		if (!req) return false;
+		const rp = req.pathname;
+		let pathname;
+		if (typeof rp === "string") pathname = rp;
+		else {
+			if (!req.url) return false;
+			pathname = req.url instanceof URL ? req.url.pathname : String(req.url);
+		}
+		const area = this.matchPath(pathname, context.domain);
+		if (area) {
+			context.security = area;
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Pipeline complet de la zone : chaîne d'authenticators (selon `mode`) → ALS
+	* → Zero Trust. Rejette (401, challenge RFC 7235 posé) ou résout.
+	*/
+	async handleSecurity(context) {
+		if (this.#configError) throw new AuthenticationError("Security configuration invalid");
+		const area = context.security;
+		if (!area || !area.security) return context;
+		const bypass = context.resolver?.bypassFirewall;
+		const trace = this.#startTrace(context);
+		if (bypass) {
+			if (trace) trace.outcome = "bypass";
+			return context;
+		}
+		let token;
+		try {
+			token = await this.#authenticate(context, area, trace);
+		} catch (error) {
+			if (error instanceof ThrottledError) {
+				context.response?.setHeader("Retry-After", String(error.retryAfterS));
+				this.#recordAuth(context, area, "auth.throttled", "failure", "throttled", null);
+				throw error;
+			}
+			if (error instanceof UnverifiableTokenError) {
+				this.#recordAuth(context, area, "auth.unverifiable", "failure", "verifier_unavailable", null);
+				throw error;
+			}
+			this.#setChallenge(context, area);
+			this.#recordAuth(context, area, "auth.failure", "failure", "invalid_credentials", null);
+			throw error;
+		}
+		if (token === null) {
+			this.#setChallenge(context, area);
+			this.#recordAuth(context, area, "auth.denied", "denied", "no_credentials", null);
+			throw new AuthenticationError(`Authentication required for area "${area.name}"`);
+		}
+		RequestContext.set("user", token.getUser());
+		RequestContext.set("token", token);
+		if (!token.isAuthenticated() && token.type !== "anonymous") {
+			this.#setChallenge(context, area);
+			this.#recordAuth(context, area, "auth.denied", "denied", "unauthenticated", token.getUserIdentifier());
+			throw new AuthenticationError(`Authentication required for area "${area.name}"`);
+		}
+		if (trace) {
+			trace.outcome = token.isAuthenticated() ? "granted" : "anonymous";
+			trace.user = token.getUserIdentifier();
+			trace.roles = token.getRoles();
+		}
+		return context;
+	}
+	/**
+	* Ouvre la trace de décision de la zone — **dev-only**, gratuit en production.
+	*
+	* L'allocation est conditionnée au témoin `context.profiling` (posé par le
+	* HttpKernel quand le Profiler est actif, donc jamais en prod) : sur le
+	* hot-path nominal, ceci coûte une lecture de booléen.
+	*
+	* @returns la trace fraîche (posée sur le context), ou `null` hors profiling.
+	*/
+	#startTrace(context) {
+		const ctx = context;
+		if (!ctx.profiling) return null;
+		const trace = {
+			authenticator: null,
+			outcome: "denied",
+			reason: null,
+			user: null,
+			roles: null
+		};
+		ctx.securityTrace = trace;
+		return trace;
+	}
+	#recordAuth(context, area, action, outcome, reason, actor) {
+		const trace = context.securityTrace;
+		if (trace) {
+			trace.outcome = reason === "throttled" ? "throttled" : outcome;
+			trace.reason = reason;
+			trace.user = actor;
+		}
+		recordAudit(this.container, {
+			category: "auth",
+			action,
+			outcome,
+			actor,
+			resource: area.name,
+			reason,
+			...readAuditContext(context)
+		});
+	}
+	/**
+	* Défense CSRF (P6 J5/étape 2) — branchée dans le pipeline HTTP de `@nodefony/http`
+	* pour TOUTE requête (zone ou non), APRÈS le resolve (les marqueurs `@CsrfProtect`/
+	* `@CsrfExempt` de la route sont disponibles). Trois rôles :
+	*
+	*  - **Émission** : sur une requête SÛRE vers une route `@CsrfProtect`, minte le
+	*    synchronizer token (`context.csrfToken`) — HttpContext pose ensuite le cookie
+	*    lisible `csrf-token`. Sinon, hot-path GET = retour immédiat (aucun en-tête lu).
+	*  - **Étape 1 (globale)** : sur une mutation, défense Fetch Metadata / Origin
+	*    (rejet cross-site même sur route publique). Skippée si `@CsrfExempt` (webhook,
+	*    auth par signature/clé) ou `bypassFirewall` (callbacks OAuth).
+	*  - **Étape 2 (opt-in)** : sur une mutation `@CsrfProtect`, exige EN PLUS le
+	*    synchronizer token (en-tête `x-csrf-token` ≡ cookie + HMAC valide).
+	*
+	* @throws CsrfError (403) — provenance tierce, ou synchronizer token absent/invalide.
+	*/
+	enforceCsrf(context) {
+		if (!this.#csrf) return;
+		if (context.resolver?.bypassFirewall) return;
+		const ctx = context;
+		if (!Csrf.isStateChanging(context.method)) {
+			if (ctx.csrfProtect && this.#csrfTokens && ctx.csrfToken == null) ctx.csrfToken = this.#csrfTokens.issue();
+			return;
+		}
+		if (ctx.csrfExempt) return;
+		const headers = context.request?.headers;
+		this.#csrf.enforce({
+			method: context.method,
+			secFetchSite: headerValue(headers, "sec-fetch-site"),
+			origin: headerValue(headers, "origin"),
+			referer: headerValue(headers, "referer"),
+			host: headerValue(headers, "host") ?? headerValue(headers, ":authority") ?? context.domain
+		});
+		if (ctx.csrfProtect && this.#csrfTokens) {
+			if (!this.#csrfTokens.verify(headerValue(headers, "x-csrf-token"), cookieValue(headerValue(headers, "cookie"), "csrf-token"))) throw new CsrfError("Missing or invalid CSRF token");
+		}
+	}
+	/**
+	* Politique CORS (P6 J5) — appelée par `HttpKernel.handleHttp()`
+	* (`http-kernel.ts:1169`), en TÊTE du pipeline : avant le routing, avant le parse
+	* du corps, donc bien avant `handleFrontController` et le firewall. Un preflight
+	* n'a pas de route déclarée — router d'abord lèverait un 405.
+	* Pose les en-têtes `Access-Control-*` et **court-circuite le
+	* preflight** `OPTIONS` en `204` (le preflight ne porte jamais de credentials,
+	* Fetch Standard → il ne doit ni router ni s'authentifier). No-op hors requête
+	* cross-origin (pas d'`Origin`), CORS désactivé, ou réponse non-HTTP (WS).
+	*
+	* @returns `204` si la requête est un preflight (l'appelant court-circuite la
+	*   réponse), sinon `undefined` (la requête réelle suit le pipeline normal).
+	*/
+	handleCors(context) {
+		if (!this.#cors) return void 0;
+		const headers = context.request?.headers;
+		const origin = headerValue(headers, "origin");
+		if (!origin) return void 0;
+		const response = context.response;
+		if (typeof response?.setHeader !== "function") return void 0;
+		const isPreflight = context.method?.toUpperCase() === "OPTIONS" && headerValue(headers, "access-control-request-method") !== void 0;
+		const corsHeaders = isPreflight ? this.#cors.preflightHeaders(origin) : this.#cors.actualHeaders(origin);
+		if (corsHeaders) for (const name in corsHeaders) response.setHeader(name, corsHeaders[name]);
+		return isPreflight ? 204 : void 0;
+	}
+	/**
+	* En-têtes de sécurité APPLICATIFS (P6 J5) — CSP, Referrer-Policy, isolation
+	* cross-origin (COOP/COEP/CORP), Origin-Agent-Cluster, Permissions-Policy.
+	* Posés sur toute réponse du pipeline (branché dans `handleHttp`). Complète le
+	* socle transport de `@nodefony/http` (nosniff/frame/HSTS, posé à l'entrée brute)
+	* SANS le ré-émettre. No-op si désactivé ou réponse non-HTTP (WS).
+	*
+	* En-têtes constants = table figée pré-calculée au boot (0 alloc/concat). Le CSP
+	* nonce/req (étape B) ajoute 1 `join` + 1 `setHeader` UNIQUEMENT si activé.
+	*/
+	applySecurityHeaders(context) {
+		const sh = this.#securityHeaders;
+		if (!sh) return;
+		const response = context.response;
+		if (typeof response?.setHeader !== "function") return;
+		const headers = sh.headers;
+		for (const name in headers) response.setHeader(name, headers[name]);
+		const extra = context.cspDirectives;
+		if (sh.hasNonce) {
+			const nonce = context.cspNonce;
+			response.setHeader("Content-Security-Policy", extra ? sh.cspForExtra(nonce, extra) : sh.cspFor(nonce));
+		} else if (extra) response.setHeader("Content-Security-Policy", sh.cspForExtra("", extra));
+	}
+	/**
+	* Déclare des directives CSP additionnelles pour `moduleName` (cf `IFirewall`).
+	* No-op si les en-têtes applicatifs sont désactivés (pas de CSP à étendre).
+	* Recompose `#securityHeaders` (merge + re-split nonce) — hors hot-path.
+	*/
+	registerCspOrigins(moduleName, fragment) {
+		if (!this.#securityHeaders || !this.#config) return;
+		(this.#cspFragments ??= /* @__PURE__ */ new Map()).set(moduleName, fragment);
+		this.#rebuildSecurityHeaders();
+	}
+	/** Retire les directives CSP de `moduleName` et recompose si nécessaire. */
+	unregisterCspOrigins(moduleName) {
+		if (!this.#cspFragments?.delete(moduleName)) return;
+		this.#rebuildSecurityHeaders();
+	}
+	/**
+	* Reconstruit `SecurityHeaders` depuis le CSP de base mergé avec les fragments
+	* enregistrés. Appelé UNIQUEMENT au (dé)enregistrement d'un module (jamais par
+	* requête) → parse/merge/serialize amortis hors hot-path. Repart toujours de
+	* `headers.csp` (base) → idempotent (pas de merge sur du déjà-mergé).
+	*/
+	#rebuildSecurityHeaders() {
+		const headers = this.#config?.headers;
+		if (!headers) return;
+		const csp = this.#cspFragments && this.#cspFragments.size > 0 ? mergeCspFragments(headers.csp, this.#cspFragments.values()) : headers.csp;
+		this.#securityHeaders = new SecurityHeaders({
+			...headers,
+			csp
+		});
+	}
+	/**
+	* Exécute la chaîne d'authenticators de la zone selon son `mode`.
+	*
+	* `first` : le premier dont `supports()` est vrai authentifie — un credential
+	* PRÉSENTÉ mais invalide échoue immédiatement (jamais de fallback silencieux
+	* vers le maillon suivant). Aucune preuve présentée → `null`.
+	*
+	* `all` : tous les maillons doivent supporter ET authentifier (MFA) ; le
+	* DERNIER token porte l'identité. Une preuve manquante = 401.
+	*
+	* @param trace - radiographie dev-only ; reçoit le NOM du maillon qui a
+	*   résolu l'identité (`null` en prod → aucune écriture).
+	* @returns le token accepté, ou `null` si aucune preuve n'a été présentée.
+	* @throws AuthenticationError (401) — credential invalide ou preuve manquante
+	*   (mode `all`). Toute erreur interne est logguée ERROR puis wrappée 401
+	*   fail-closed (rien ne fuite au client).
+	*/
+	async #authenticate(context, area, trace = null) {
+		let token = null;
+		for (const name of area.authenticators) {
+			const authenticator = this.#authenticators?.get(name);
+			if (!authenticator) {
+				this.log(`authenticator "${name}" not registered`, "ERROR");
+				throw new AuthenticationError(`Authentication required for area "${area.name}"`);
+			}
+			if (!authenticator.supports(context)) {
+				if (area.mode === "first") continue;
+				throw new AuthenticationError(`Authentication required for area "${area.name}"`);
+			}
+			const created = await authenticator.createToken(context);
+			let authenticated;
+			try {
+				authenticated = await authenticator.authenticate(created);
+			} catch (error) {
+				await authenticator.onFailure(context, error);
+				if (error instanceof AuthenticationError) {
+					this.log(`authentication failed (area "${area.name}", authenticator "${name}")`, "WARNING");
+					throw error;
+				}
+				if (error instanceof ThrottledError) {
+					this.log(`login throttled (area "${area.name}", authenticator "${name}", retry in ${error.retryAfterS}s)`, "WARNING");
+					throw error;
+				}
+				if (error instanceof UnverifiableTokenError) {
+					this.log(`token unverifiable (area "${area.name}", authenticator "${name}") — ${error.detail ?? "cause non renseignée"}`, "ERROR");
+					this.log(error, "ERROR");
+					throw error;
+				}
+				this.log(error, "ERROR");
+				throw new AuthenticationError("Authentication failed");
+			}
+			await authenticator.onSuccess(context, authenticated);
+			if (trace) trace.authenticator = name;
+			if (area.mode === "first") return authenticated;
+			token = authenticated;
+		}
+		return token;
+	}
+	#setChallenge(context, area) {
+		const response = context.response;
+		if (typeof response?.setHeader !== "function") return;
+		for (const name of area.authenticators) {
+			const challenge = this.#authenticators?.get(name)?.challenge?.(area);
+			if (challenge) {
+				response.setHeader("WWW-Authenticate", challenge);
+				return;
+			}
+		}
+	}
+	log(pci, severity, msgid, msg) {
+		if (!msgid) msgid = logColor.cyan("FIREWALL");
+		return super.log(pci, severity, msgid, msg);
+	}
+};
+//#endregion
+export { Firewall, Firewall as default };