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

package/README.md

@@ -74,4 +74,4 @@ npm run test:memory      # GATE mémoire (memory.test.ts) — AVANT tout commit
 
 ## Licence
 
-CeCILL-B — Christophe CAMENSULI.
+Apache 2.0 — Christophe CAMENSULI.

package/dist/nodefony/command/assetsPublishCommand.js

@@ -43,14 +43,12 @@ var AssetsPublish = class extends Command {
 	async generate(opts) {
 		const outDir = opts.out ? isAbsolute(opts.out) ? opts.out : resolve(process.cwd(), opts.out) : join(process.cwd(), "dist-assets");
 		const sources = this.collectSources();
-		if (sources.length === 0) {
-			this.log("Aucune source d'assets (0 mount natif, 0 bundle frontend) — rien à publier.", "WARNING");
-			return this;
-		}
+		if (sources.length === 0) process.stdout.write(`Aucune source d'assets (0 mount natif, 0 bundle frontend) — arbre vide → ${outDir}\n`);
 		if (opts.clean && existsSync(outDir)) await fsp.rm(outDir, {
 			recursive: true,
 			force: true
 		});
+		await fsp.mkdir(outDir, { recursive: true });
 		const plan = planAssetPublish(sources, outDir);
 		const manifest = {
 			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),

package/dist/nodefony/command/proxyGenerateCommand.js

@@ -1,6 +1,9 @@
+import { resolveTrustedHostNames } from "../src/context/domainMatcher.js";
 import { defaultIntrospection, generateHaproxyConfig, generateNginxConfig } from "../src/proxy/generateProxyConfig.js";
+import { planAssetPublish } from "../src/assets/collectAssets.js";
 import { Command } from "nodefony";
 import fsp from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
 //#region nodefony/command/proxyGenerateCommand.ts
 const options = {
 	helpGroup: "FRONT ET RÉSEAU",
@@ -21,17 +24,20 @@ var ProxyGenerate = class extends Command {
 		this.addOption("-b, --backend <host>", "backend host the proxy connects to (default 127.0.0.1)");
 		this.addOption("-l, --listen <port>", "proxy listen port (default 80)");
 		this.addOption("--reencrypt", "re-encrypt to the HTTPS backend (TLS proxy↔backend) instead of clear");
+		this.addOption("--assets-root <dir>", "serve every static asset from this single tree (see `assets:publish`)");
+		this.addOption("--tls-cert <file>", "TLS certificate chain (nginx only)");
+		this.addOption("--tls-key <file>", "TLS private key (nginx only)");
+		this.addOption("--tls-listen <port>", "TLS listen port (default 443)");
 	}
 	async generate(target, opts) {
-		if (target !== "nginx" && target !== "haproxy") {
-			this.log(`Cible inconnue '${target}' — attendu: nginx | haproxy.`, "ERROR");
-			return this;
-		}
+		if (target !== "nginx" && target !== "haproxy") throw new Error(`Cible inconnue '${target}' — attendu: nginx | haproxy.`);
+		if (Boolean(opts.tlsCert) !== Boolean(opts.tlsKey)) throw new Error("--tls-cert et --tls-key vont ensemble — l'un sans l'autre ne produit aucune écoute TLS.");
+		if (opts.tlsCert && target === "haproxy") throw new Error("--tls-cert/--tls-key ne valent que pour nginx : haproxy exige un PEM combiné (cf docker/certs/build-haproxy-pem.sh).");
 		const intro = this.buildIntrospection(opts);
 		const conf = target === "nginx" ? generateNginxConfig(intro) : generateHaproxyConfig(intro);
 		if (opts.out) {
 			await fsp.writeFile(opts.out, conf, "utf8");
-			this.log(`Configuration ${target} écrite → ${opts.out}`, "INFO");
+			process.stdout.write(`Configuration ${target} écrite → ${opts.out}\n`);
 		} else process.stdout.write(conf);
 		return this;
 	}
@@ -42,14 +48,22 @@ var ProxyGenerate = class extends Command {
 		const servers = (this.kernel?.options)?.servers;
 		const staticSvc = module?.get("server-static");
 		staticSvc?.mountModulePublics?.();
-		const staticRoots = staticSvc?.servers ? Object.keys(staticSvc.servers) : [];
-		const mounts = (staticSvc?.mounts ?? []).map((m) => ({
+		let staticRoots = staticSvc?.servers ? Object.keys(staticSvc.servers) : [];
+		let mounts = (staticSvc?.mounts ?? []).map((m) => ({
 			prefix: m.prefix,
 			dir: m.dir
 		}));
+		if (opts.assetsRoot) {
+			const root = isAbsolute(opts.assetsRoot) ? opts.assetsRoot : resolve(process.cwd(), opts.assetsRoot);
+			mounts = planAssetPublish(mounts, root).map((p) => ({
+				prefix: p.prefix,
+				dir: p.target
+			}));
+			staticRoots = [root];
+		}
 		return {
 			...defaultIntrospection,
-			domains: httpOpts.trustedHosts ?? [],
+			domains: resolveTrustedHostNames(this.kernel?.domain ?? "", httpOpts.trustedHosts),
 			backendHost: opts.backend ?? "127.0.0.1",
 			httpPort: Number(servers?.http?.port) || defaultIntrospection.httpPort,
 			httpsPort: Number(servers?.https?.port) || defaultIntrospection.httpsPort,
@@ -58,7 +72,12 @@ var ProxyGenerate = class extends Command {
 			listen: opts.listen ? Number(opts.listen) : defaultIntrospection.listen,
 			reencrypt: Boolean(opts.reencrypt),
 			maxBodyBytes: Number(httpOpts.maxBodySize) || 0,
-			keepaliveIntervalMs: Number(httpOpts.websocket?.keepaliveInterval) || 0
+			keepaliveIntervalMs: Number(httpOpts.websocket?.keepaliveInterval) || 0,
+			tls: opts.tlsCert && opts.tlsKey ? {
+				certPath: opts.tlsCert,
+				keyPath: opts.tlsKey,
+				listen: Number(opts.tlsListen) || 443
+			} : null
 		};
 	}
 };

package/dist/nodefony/service/certificates.js

@@ -98,7 +98,32 @@ var Certificate = class Certificate extends Service {
 		if (!this.forge) throw new Error("node-forge non chargé — appeler loadForge() avant toute génération.");
 		return this.forge;
 	}
+	/**
+	* Fabrique-t-on un certificat au démarrage ?
+	*
+	* 🔴 Seulement si un serveur TLS est ACTIF. Sans cette question, le hook
+	* ci-dessous écrit dans `nodefony/config/certificates` à CHAQUE boot — y
+	* compris celui d'une application qui a coupé son écoute TLS, et y compris un
+	* run de console qui n'ouvre aucun port.
+	*
+	* Ce qu'il en coûtait, mesuré sur une image générée : le code d'une image
+	* appartient à `root` et le processus tourne en `1000` (c'est voulu — une
+	* application qui peut réécrire son propre `dist/` offre à une faille un moyen
+	* de PERSISTER). Le `mkdir` mourait donc en `EACCES`, le hook de boot était
+	* « critique », et l'application ne démarrait PAS — quel que soit son préset.
+	* L'erreur nommait un dossier de certificats sur une application qui n'en veut
+	* aucun : elle envoyait chercher du côté du TLS un défaut de permission.
+	*
+	* C'est aussi ce que le gabarit d'application promet en toutes lettres : en
+	* production, l'écoute TLS est coupée tant qu'aucun port HTTPS n'est demandé,
+	* précisément pour ne PAS fabriquer une clé RSA à chaque démarrage de chaque
+	* exemplaire. La promesse était écrite ; rien ne la tenait.
+	*/
+	get tlsWanted() {
+		return !!this.module.kernel?.options?.servers?.https;
+	}
 	async init() {
+		if (!this.tlsWanted) return this;
 		this.kernel?.once("onBoot", async () => {
 			this.options = extend(true, this.options, this.module.options.certificates || {});
 			await this.generateServerCertificates();

package/dist/nodefony/src/context/domainMatcher.js

@@ -74,6 +74,39 @@ function compileTrustedHosts(domain, trusted, isDev) {
 	return compileDomainPatterns(patterns);
 }
 /**
+* Rend les NOMS d'hôtes que la barrière `trustedHosts` accepte — la même
+* politique que {@link compileTrustedHosts}, mais lisible par un humain ou par
+* un générateur de configuration (`server_name` nginx, `hdr(host)` haproxy).
+*
+* Pourquoi une seconde lecture de la même règle : une `RegExp` ne se réécrit pas
+* en nom d'hôte. La commande `proxy:generate` lisait donc `trustedHosts` à sa
+* façon, en le supposant TOUJOURS `string[]` — alors que sa valeur par DÉFAUT
+* est `false`, celle de toute application générée. Une politique lue à deux
+* endroits finit par diverger : ici les deux fonctions partent de la même
+* valeur, et la règle « le domaine canonique est toujours accepté » n'est
+* écrite qu'une fois.
+*
+* Le loopback de développement n'en fait volontairement pas partie : une
+* configuration de proxy décrit un déploiement, pas la machine de l'auteur.
+*
+* @param domain - domaine canonique du serveur (`kernel.domain`).
+* @param trusted - config `http.trustedHosts` (optionnelle).
+* @returns les noms acceptés, sans doublon. **Vide** si `trusted === true`
+*   (bypass : le proxy filtre déjà le `Host`, aucun nom n'est à imposer) ; les
+*   motifs `RegExp` sont écartés, faute d'être exprimables en nom d'hôte.
+*/
+function resolveTrustedHostNames(domain, trusted) {
+	if (trusted === true) return [];
+	const patterns = [domain];
+	if (trusted) {
+		if (Array.isArray(trusted)) patterns.push(...trusted);
+		else patterns.push(trusted);
+	}
+	const names = [];
+	for (const p of patterns) if (typeof p === "string" && p && !names.includes(p)) names.push(p);
+	return names;
+}
+/**
 * Teste un `Host` entrant contre une liste de `RegExp` pré-compilée.
 *
 * @param regAlias - sortie de {@link compileTrustedHosts} ou {@link compileDomainPatterns}.
@@ -85,4 +118,4 @@ function isDomainAllowed(regAlias, domain) {
 	return false;
 }
 //#endregion
-export { compileDomainPattern, compileDomainPatterns, compileTrustedHosts, isDomainAllowed };
+export { compileDomainPattern, compileDomainPatterns, compileTrustedHosts, isDomainAllowed, resolveTrustedHostNames };

package/dist/nodefony/src/proxy/generateProxyConfig.js

@@ -10,7 +10,8 @@ const defaultIntrospection = {
 	listen: 80,
 	reencrypt: false,
 	maxBodyBytes: 0,
-	keepaliveIntervalMs: 0
+	keepaliveIntervalMs: 0,
+	tls: null
 };
 /**
 * Délai d'inactivité, en secondes, qu'un proxy doit accorder à une connexion
@@ -68,23 +69,49 @@ function generateNginxConfig(intro) {
 	const backendPort = intro.reencrypt ? intro.httpsPort : intro.httpPort;
 	const idleSeconds = idleTimeoutSeconds(intro);
 	const lines = [];
-	lines.push("# Généré par `nodefony proxy:generate nginx` — NE PAS éditer à la main.", "# Reverse-proxy dérivé de l'introspection Nodefony (domaines, statiques, ports).", "worker_processes auto;", "events { worker_connections 1024; }", "", "http {", "  # Upgrade WebSocket — HTTP et WS co-habitent sur le même port Nodefony.", "  map $http_upgrade $connection_upgrade { default upgrade; '' close; }", "", `  upstream nodefony { server ${intro.backendHost}:${backendPort}; keepalive 32; }`, "");
+	lines.push("# Généré par `nodefony proxy:generate nginx` — NE PAS éditer à la main.", "# Reverse-proxy dérivé de l'introspection Nodefony (domaines, statiques, ports).", "worker_processes auto;", "events { worker_connections 1024; }", "", "http {", "  include /etc/nginx/mime.types;", "  default_type application/octet-stream;", "", "  server_tokens off;", "", "  sendfile on;", "  tcp_nopush on;", "  tcp_nodelay on;", "", "  gzip on;", "  gzip_vary on;", "  gzip_min_length 1024;", "  gzip_proxied any;", "  gzip_types text/plain text/css text/xml application/javascript application/json application/xml image/svg+xml application/manifest+json;", "", "  # Upgrade WebSocket — HTTP et WS co-habitent sur le même port Nodefony.", "  map $http_upgrade $connection_upgrade { default upgrade; '' close; }", "", `  upstream nodefony { server ${intro.backendHost}:${backendPort}; keepalive 32; }`, "");
 	if (intro.maxBodyBytes > 0) lines.push(`  # Aligné sur \`http.maxBodySize\` (${intro.maxBodyBytes} octets) — sans quoi`, "  # nginx rendrait 413 à 1 Mo, son défaut, sans que le serveur le sache.", `  client_max_body_size ${intro.maxBodyBytes};`, "");
-	lines.push("  server {", `    listen ${intro.listen};`, `    server_name ${serverNames(intro.domains)};`);
+	lines.push(...nginxServerBlock(intro, scheme, idleSeconds, null));
+	if (intro.tls) lines.push("", ...nginxServerBlock(intro, scheme, idleSeconds, intro.tls));
+	lines.push("}", "");
+	return lines.join("\n");
+}
+/**
+* Un bloc `server {}` nginx — corps IDENTIQUE en clair et en TLS.
+*
+* Le scheme annoncé au backend reste `$scheme`, que nginx CONSTATE sur la
+* connexion entrante : le même corps sert donc les deux écoutes sans qu'aucune
+* n'ait à savoir laquelle elle est. C'est ce qui fait qu'un cookie `Secure`
+* tient derrière le frontal alors que le lien interne est en clair.
+*
+* @param intro - modèle d'introspection Nodefony.
+* @param scheme - `http` ou `https` vers le BACKEND (re-chiffrement).
+* @param idleSeconds - inactivité tolérée, dérivée du heartbeat WebSocket.
+* @param tls - terminaison TLS de CE bloc, ou `null` pour une écoute en clair.
+* @returns les lignes du bloc `server`.
+*/
+function nginxServerBlock(intro, scheme, idleSeconds, tls) {
+	const lines = ["  server {"];
+	if (tls) lines.push(`    listen ${tls.listen} ssl;`, "    http2 on;", `    server_name ${serverNames(intro.domains)};`, "", "    # Terminaison TLS au frontal. Ces chemins sont ceux d'un MONTAGE, à", "    # pourvoir au déploiement (volume compose, secret k8s) : une clé privée", "    # n'entre pas dans une image, où la couche reste lisible même effacée.", `    ssl_certificate     ${tls.certPath};`, `    ssl_certificate_key ${tls.keyPath};`, "    ssl_protocols TLSv1.2 TLSv1.3;", "    ssl_session_cache shared:SSL:10m;", "    ssl_session_timeout 1h;", "", "    error_page 497 =301 https://$http_host$request_uri;");
+	else lines.push(`    listen ${intro.listen};`, `    server_name ${serverNames(intro.domains)};`);
 	if (intro.reencrypt) lines.push("    # Re-encrypt : valider le cert backend (cf docker/certs).", "    # proxy_ssl_trusted_certificate /etc/nginx/certs/ca.pem;", "    # proxy_ssl_verify on; proxy_ssl_name nodefony.com;");
-	for (const m of intro.mounts) lines.push("", `    location ${m.prefix} {`, `      alias ${ensureTrailingSlash(m.dir)};`, "      access_log off;", "      expires 1h;", "    }");
+	for (const m of intro.mounts) {
+		const prefix = ensureTrailingSlash(m.prefix);
+		const dir = ensureTrailingSlash(m.dir);
+		lines.push("", `    location ${prefix}assets/ {`, `      alias ${dir}assets/;`, "      access_log off;", "      expires 1y;", "      add_header Cache-Control \"public, immutable\";", "    }", "", `    location ${prefix} {`, `      alias ${dir};`, "      access_log off;", "      expires 1h;", "    }");
+	}
 	lines.push("", `    location @nodefony {`, `      proxy_pass ${scheme}://nodefony;`, "      proxy_http_version 1.1;", nginxForwardHeaders(idleSeconds), "    }");
 	if (intro.staticRoots.length === 0) lines.push("", "    location / {", `      proxy_pass ${scheme}://nodefony;`, "      proxy_http_version 1.1;", nginxForwardHeaders(idleSeconds), "    }");
 	else {
 		const roots = intro.staticRoots;
-		lines.push("", "    # Statiques multi-dossiers (racine app + modules) : chaîne try_files,", "    # fallback vers le backend Nodefony si aucun fichier ne matche.", "    location / {", `      root ${roots[0]};`, `      try_files $uri ${roots.length > 1 ? "@r1" : "@nodefony"};`, "    }");
+		lines.push("", roots.length > 1 ? "    # Statiques multi-dossiers (racine app + modules) : chaîne try_files,\n    # fallback vers le backend Nodefony si aucun fichier ne matche." : "    # Statiques servis par le frontal ; fallback vers le backend\n    # Nodefony si aucun fichier ne correspond.", "    location / {", `      root ${roots[0]};`, `      try_files $uri ${roots.length > 1 ? "@r1" : "@nodefony"};`, "    }");
 		for (let i = 1; i < roots.length; i++) {
 			const next = i + 1 < roots.length ? `@r${i + 1}` : "@nodefony";
 			lines.push(`    location @r${i} {`, `      root ${roots[i]};`, `      try_files $uri ${next};`, "    }");
 		}
 	}
-	lines.push("  }", "}", "");
-	return lines.join("\n");
+	lines.push("  }");
+	return lines;
 }
 /**
 * Génère une configuration haproxy (reverse-proxy + Forwarded RFC 7239).

package/dist/types/nodefony/command/proxyGenerateCommand.d.ts

@@ -12,6 +12,10 @@ declare class ProxyGenerate extends Command {
         backend?: string;
         listen?: string;
         reencrypt?: boolean;
+        assetsRoot?: string;
+        tlsCert?: string;
+        tlsKey?: string;
+        tlsListen?: string;
     }): Promise<this>;
     /** Construit le modèle d'introspection depuis le kernel + le service statique. */
     private buildIntrospection;

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

@@ -146,6 +146,28 @@ declare class Certificate extends Service {
     loadForge(): Promise<ForgeModule>;
     /** Accès au backend forge déjà chargé (lève si `loadForge` n'a pas été appelé). */
     private get forgeLib();
+    /**
+     * Fabrique-t-on un certificat au démarrage ?
+     *
+     * 🔴 Seulement si un serveur TLS est ACTIF. Sans cette question, le hook
+     * ci-dessous écrit dans `nodefony/config/certificates` à CHAQUE boot — y
+     * compris celui d'une application qui a coupé son écoute TLS, et y compris un
+     * run de console qui n'ouvre aucun port.
+     *
+     * Ce qu'il en coûtait, mesuré sur une image générée : le code d'une image
+     * appartient à `root` et le processus tourne en `1000` (c'est voulu — une
+     * application qui peut réécrire son propre `dist/` offre à une faille un moyen
+     * de PERSISTER). Le `mkdir` mourait donc en `EACCES`, le hook de boot était
+     * « critique », et l'application ne démarrait PAS — quel que soit son préset.
+     * L'erreur nommait un dossier de certificats sur une application qui n'en veut
+     * aucun : elle envoyait chercher du côté du TLS un défaut de permission.
+     *
+     * C'est aussi ce que le gabarit d'application promet en toutes lettres : en
+     * production, l'écoute TLS est coupée tant qu'aucun port HTTPS n'est demandé,
+     * précisément pour ne PAS fabriquer une clé RSA à chaque démarrage de chaque
+     * exemplaire. La promesse était écrite ; rien ne la tenait.
+     */
+    private get tlsWanted();
     init(): Promise<this>;
     /**
      * Numéro de série X.509 — RFC 5280 §4.1.2.2 : entier positif unique par CA.

package/dist/types/nodefony/src/context/domainMatcher.d.ts

@@ -57,6 +57,29 @@ export declare function compileDomainPatterns(patterns: DomainPattern | DomainPa
  * @returns liste de `RegExp` pour {@link isDomainAllowed}.
  */
 export declare function compileTrustedHosts(domain: string, trusted: ITrustedHostsConfig | undefined, isDev: boolean): RegExp[];
+/**
+ * Rend les NOMS d'hôtes que la barrière `trustedHosts` accepte — la même
+ * politique que {@link compileTrustedHosts}, mais lisible par un humain ou par
+ * un générateur de configuration (`server_name` nginx, `hdr(host)` haproxy).
+ *
+ * Pourquoi une seconde lecture de la même règle : une `RegExp` ne se réécrit pas
+ * en nom d'hôte. La commande `proxy:generate` lisait donc `trustedHosts` à sa
+ * façon, en le supposant TOUJOURS `string[]` — alors que sa valeur par DÉFAUT
+ * est `false`, celle de toute application générée. Une politique lue à deux
+ * endroits finit par diverger : ici les deux fonctions partent de la même
+ * valeur, et la règle « le domaine canonique est toujours accepté » n'est
+ * écrite qu'une fois.
+ *
+ * Le loopback de développement n'en fait volontairement pas partie : une
+ * configuration de proxy décrit un déploiement, pas la machine de l'auteur.
+ *
+ * @param domain - domaine canonique du serveur (`kernel.domain`).
+ * @param trusted - config `http.trustedHosts` (optionnelle).
+ * @returns les noms acceptés, sans doublon. **Vide** si `trusted === true`
+ *   (bypass : le proxy filtre déjà le `Host`, aucun nom n'est à imposer) ; les
+ *   motifs `RegExp` sont écartés, faute d'être exprimables en nom d'hôte.
+ */
+export declare function resolveTrustedHostNames(domain: string, trusted: ITrustedHostsConfig | undefined): string[];
 /**
  * Teste un `Host` entrant contre une liste de `RegExp` pré-compilée.
  *

package/dist/types/nodefony/src/proxy/generateProxyConfig.d.ts

@@ -16,6 +16,22 @@ export interface ProxyStaticMount {
     /** Dossier absolu servi. */
     dir: string;
 }
+/**
+ * Terminaison TLS au frontal — **nginx uniquement**.
+ *
+ * Les chemins sont ceux vus par le PROXY à l'exécution, jamais ceux de la
+ * machine qui a généré la configuration : une clé privée n'entre pas dans une
+ * image (une couche reste lisible même effacée plus loin), elle se MONTE au
+ * déploiement — volume compose, secret Kubernetes.
+ */
+export interface ProxyTlsTermination {
+    /** Chaîne de certificats servie au client (`fullchain.pem`). */
+    certPath: string;
+    /** Clé privée correspondante (`privkey.pem`). */
+    keyPath: string;
+    /** Port d'écoute TLS du proxy. */
+    listen: number;
+}
 /** Modèle d'introspection consommé par les générateurs. */
 export interface ProxyIntrospection {
     /** `server_name` (hôtes de confiance, IP exclues). Vide → `_` (catch-all). */
@@ -55,6 +71,14 @@ export interface ProxyIntrospection {
      * saines.
      */
     keepaliveIntervalMs: number;
+    /**
+     * Terminaison TLS au frontal, ou `null` pour n'écouter qu'en clair.
+     *
+     * **nginx seulement** : haproxy exige un PEM COMBINÉ (certificat + clé dans
+     * un même fichier), que Nodefony ne fabrique pas — la commande REFUSE donc
+     * l'option sur cette cible plutôt que de l'accepter et de la jeter.
+     */
+    tls: ProxyTlsTermination | null;
 }
 /** Valeurs par défaut d'un modèle d'introspection (complété par la commande). */
 export declare const defaultIntrospection: ProxyIntrospection;

package/docs/cookies.md

@@ -284,8 +284,8 @@ posé pendant la **phase HTTP** qui précède l'upgrade. La forme d'un cookie d
 
 Les cookies **applicatifs** ne se configurent pas par schéma : on les construit dans le code, avec les
 défauts sûrs de `cookieDefaultSettings` (`cookie.ts:43`). Le seul cookie **piloté par la config** est celui
-de la **session** — bloc Zod `sessionCookieSchema` (`config.ts:727`), avec notamment `hostPrefix`
-(`config.ts:730`) qui décide du préfixe `__Host-`. Tout cela est documenté dans [Sessions](session.md) :
+de la **session** — bloc Zod `sessionCookieSchema` (`config.ts:748`), avec notamment `hostPrefix`
+(`config.ts:770`) qui décide du préfixe `__Host-`. Tout cela est documenté dans [Sessions](session.md) :
 cette page ne le duplique pas.
 
 Le nom effectif du cookie de session (avec ou sans `__Host-` selon le transport) est calculé par

package/docs/observabilite.md

@@ -112,7 +112,7 @@ un `requestId`, un `traceparent` et un contrat de logger **uniques** couvrent le
 
 **Le `requestId` est un citoyen du contexte, pas un décor.** Il naît dans le constructeur de base
 `Context.requestId = randomUUID()` (`Context.ts:244`), voyage dans l'ALS via `RequestContext.run(...)`
-(`http-kernel.ts:1300` pour HTTP, `http-kernel.ts:1590` pour WS), et se lit de n'importe où avec
+(`http-kernel.ts:435` pour HTTP, `http-kernel.ts:435` pour WS), et se lit de n'importe où avec
 `RequestContext.getRequestId()` — un controller, un service, un adapter ORM, sans jamais le threader.
 
 **La ligne de bilan est branchable.** Le kernel ne code pas un format en dur : il consulte un
@@ -420,7 +420,7 @@ instancié **qu'en dev** (fuite d'info + coût en prod).
 | Le `X-Request-Id` que j'envoie n'est pas réfléchi   | Valeur non conforme (espace, CR/LF, non-ASCII, > 128) → **rejetée** | Utiliser `[A-Za-z0-9._-]{1,128}` (UUID/nanoid/traceparent OK) — sinon UUID serveur |
 | Les logs de fin de requête n'ont pas de `requestId` | Ils sont émis hors bulle ALS                                        | Déjà géré : l'override `log()` rouvre une micro-bulle (`Context.ts:459`)           |
 | Réponse HTTP/2 sans `x-request-id`                  | Chemin de réponse h2 distinct du 1.1                                | Déjà géré (`http2/Response.ts:71`) — le port 5152 réfléchit aussi                  |
-| Pas de `traceparent` renvoyé sur un WebSocket       | `ws` n'expose pas l'écriture d'en-tête au handshake                 | Attendu — la trace WS reste propagée en ALS (`http-kernel.ts:1296`)                |
+| Pas de `traceparent` renvoyé sur un WebSocket       | `ws` n'expose pas l'écriture d'en-tête au handshake                 | Attendu — la trace WS reste propagée en ALS (`http-kernel.ts:1505`)                |
 | Frame WS binaire loggée en `{"0":..,"1":..}`        | Sérialisation naïve d'un Buffer                                     | Déjà géré : résumé `[binary N B]` (`wsLogContent.ts:63`)                           |
 | Le format de log ne change pas malgré la config     | Un `setRequestLogger(...)` programmatique gagne sur la config       | L'override est volontaire (last setter wins) — retirer l'appel, ou le régler       |
 | Logs d'audit trop volumineux en prod                | `stack` sérialisée, ou 100 % des 2xx audités                        | `includeStack:false` (défaut prod) + `sampleRate` via `setRequestLogger`           |

package/docs/rate-limit.md

@@ -106,7 +106,7 @@ Trois choix structurent l'implémentation, et chacun est un compromis assumé.
 
 **Désactivé par défaut — opt-in explicite.** En cloud-native, le plafond par IP est souvent mieux placé
 à l'**ingress/gateway** (il voit tout le trafic, tous les pods, et rejette avant le coût TLS). Le module
-laisse donc `rateLimit` désarmé par défaut (`config.ts:830`) : `null` tant qu'on ne l'active pas → **0
+laisse donc `rateLimit` désarmé par défaut (`config.ts:1065`) : `null` tant qu'on ne l'active pas → **0
 coût** sur le chemin chaud. On l'active quand on n'a **pas** d'edge devant soi (bare-metal, VPS), ou en
 défense en profondeur.
 
@@ -147,7 +147,7 @@ export default defineConfig(() => ({
 ```
 
 Les trois clés `enabled` / `windowS` / `max` sont **éditables à chaud** (`runtimeMutable`) : le kernel
-reconstruit le compteur sans redémarrage (`configureRateLimit()`, `http-kernel.ts:322`).
+reconstruit le compteur sans redémarrage (`configureRateLimit()`, `http-kernel.ts:416`).
 
 ### 2. Observer le 429 et les en-têtes
 
@@ -214,14 +214,14 @@ Autour de ce cœur, le kernel orchestre le cycle de vie :
 
 ## ⚙️ Configuration
 
-Table dérivée de `rateLimitSchema` (`config.ts:847`). Tout est optionnel : ce sont les défauts du
+Table dérivée de `rateLimitSchema` (`config.ts:868`). Tout est optionnel : ce sont les défauts du
 schéma, écrits ici pour les montrer.
 
 | Option        | Type         | Défaut    | Effet                                                                            | Chaud |
 | ------------- | ------------ | --------- | -------------------------------------------------------------------------------- | ----- |
 | `enabled`     | bool         | `false`   | Arme le rate-limit (HTTP **et** handshakes WS, même compteur) (`config.ts:849`). | oui   |
 | `windowS`     | int (s)      | `60`      | Largeur de la fenêtre fixe ; le compteur par IP repart à zéro (`config.ts:860`). | oui   |
-| `max`         | int          | `300`     | Requêtes/IP/fenêtre ; au-delà `429` + `Retry-After` (`config.ts:871`).           | oui   |
+| `max`         | int          | `300`     | Requêtes/IP/fenêtre ; au-delà `429` + `Retry-After` (`config.ts:892`).           | oui   |
 | `maxTracked`  | int (≥ 1000) | `100 000` | Borne mémoire : IP suivies ; au cap, purge puis éviction FIFO (`config.ts:883`). | non   |
 | `gcIntervalS` | int (s)      | `300`     | Intervalle du balayage de purge des fenêtres expirées, hors hot-path.            | non   |
 | `gcJitter`    | bool         | `true`    | Étale le tick GC d'un jitter aléatoire (anti-thundering-herd multi-pod).         | non   |
@@ -242,7 +242,7 @@ Et un réglage **séparé**, propre au WebSocket, à la racine du module :
 Un WebSocket ne peut **pas** recevoir un `429` : au moment où le rate-limit décide, le `101 Switching
 Protocols` est déjà parti sur le fil (émis par la bibliothèque `ws`). Le refoulement se fait donc par
 une **fermeture RFC 6455 `1013 Try Again Later`**, décidée dans `onWebsocketRequest()`
-(`http-kernel.ts:1505`) — **avant** `enterScope`, l'ALS et le pipeline, comme le `429` HTTP.
+(`http-kernel.ts:1540`) — **avant** `enterScope`, l'ALS et le pipeline, comme le `429` HTTP.
 
 Deux plafonds distincts, tous deux par IP forwarded-aware :
 

package/docs/servers.md

@@ -128,7 +128,7 @@ Nodefony crée un serveur HTTP/2 sécurisé avec `allowHTTP1: true` (`ServerHttp
 
 **Le WebSocket n'est jamais un citoyen de seconde zone.** Il est adossé au serveur HTTP porteur
 (`server-websocket.ts:80`), passe par le **même** rate-limit d'IP que les requêtes HTTP — un upgrade
-_est_ une requête HTTP (`HttpKernel.onWebsocketRequest()`, `http-kernel.ts:1497`) —, hérite de la même
+_est_ une requête HTTP (`HttpKernel.onWebsocketRequest()`, `http-kernel.ts:1540`) —, hérite de la même
 session et du même firewall, et se ferme avec le même soin qu'une réponse HTTP.
 
 > [!NOTE]
@@ -249,7 +249,7 @@ export default PingController;
 
 ### 4. Ce qu'on observe au boot
 
-Le kernel démarre les serveurs à la phase `onReady` (`Kernel.ts:1090`), puis affiche les URL réellement
+Le kernel démarre les serveurs à la phase `onReady` (`Kernel.ts:1214`), puis affiche les URL réellement
 en écoute — le récap de développement liste HTTP, HTTP/2, WS et WSS dans cet ordre
 (`BootReporter.ts:389`) :
 
@@ -264,7 +264,7 @@ en écoute — le récap de développement liste HTTP, HTTP/2, WS et WSS dans ce
 ```
 
 Hors écran animé (production, CI, `--debug`), ce sont les bannières par serveur qui sortent
-(`ServerHttp.showBanner()`, `server-http.ts:226`, appelées par le kernel — `Kernel.ts:457`) :
+(`ServerHttp.showBanner()`, `server-http.ts:226`, appelées par le kernel — `Kernel.ts:545`) :
 
 ```text
 Server Listen on http://127.0.0.1:5151 Family: IPv4 Protocol : 1.1
@@ -399,7 +399,7 @@ C'est la distinction la plus utile de cette page, et celle qu'on rate le plus so
 
 | Question                                  | Où ça se règle                 | Source                                                    |
 | ----------------------------------------- | ------------------------------ | --------------------------------------------------------- |
-| **Quels** serveurs, sur **quels ports** ? | `servers` (config d'app)       | `serversSchema` (`src/nodefony/src/config/schema.ts:132`) |
+| **Quels** serveurs, sur **quels ports** ? | `servers` (config d'app)       | `serversSchema` (`src/nodefony/src/config/schema.ts:149`) |
 | **Comment** ces serveurs se comportent ?  | `use("@nodefony/http", { … })` | `httpConfigSchema` (`config.ts:953`)                      |
 
 Autrement dit : la **topologie** est une propriété du déploiement (elle change entre le poste du dev,
@@ -422,7 +422,7 @@ Défauts matérialisés dans `defaultAppConfig` (`src/nodefony/src/config/defaul
 ### Niveau 2 — le transport HTTP / HTTPS
 
 Table dérivée de `httpServerSchema` (`config.ts:257`) ; la section `https` reprend les mêmes clés et en
-ajoute une (`httpsServerSchema`, `config.ts:315`).
+ajoute une (`httpsServerSchema`, `config.ts:336`).
 
 | Option                       | Type  | Défaut   | Effet                                                                            |
 | ---------------------------- | ----- | -------- | -------------------------------------------------------------------------------- |
@@ -441,7 +441,7 @@ quelle à Node. C'est délibéré — un schéma strict effacerait silencieuseme
 
 ### Niveau 2 — HTTP/2
 
-Depuis `http2Schema` (`config.ts:332`), appliqué seulement si défini
+Depuis `http2Schema` (`config.ts:353`), appliqué seulement si défini
 (`maxSessionMemory`, `server-https.ts:197`).
 
 | Option                 | Type | Défaut | Effet                                                                         |
@@ -451,7 +451,7 @@ Depuis `http2Schema` (`config.ts:332`), appliqué seulement si défini
 
 ### Niveau 2 — WebSocket (`websocket` et `websocketSecure`)
 
-Depuis `websocketSchema` (`config.ts:496`). Les deux sections partagent la forme et les défauts ; le WSS
+Depuis `websocketSchema` (`config.ts:517`). Les deux sections partagent la forme et les défauts ; le WSS
 lit `websocketSecure` (`config.ts:1043`).
 
 | Option                   | Type                | Défaut  | Effet                                                                              |
@@ -459,8 +459,8 @@ lit `websocketSecure` (`config.ts:1043`).
 | `keepaliveInterval`      | ms                  | `20000` | Intervalle des pings — détecte les connexions zombies.                             |
 | `keepaliveGracePeriod`   | ms                  | `10000` | Délai de grâce après un ping sans réponse avant fermeture.                         |
 | `closeTimeout`           | ms                  | `5000`  | Délai de fermeture propre avant destruction de la socket.                          |
-| `maxPayload`             | octets              | `1 MiB` | Taille max d'un message entrant → au-delà, **close 1009** (`config.ts:522`).       |
-| `allowedOrigins`         | bool \| str \| list | `false` | Allowlist d'`Origin` au handshake — **anti-CSWSH** (`config.ts:531`).              |
+| `maxPayload`             | octets              | `1 MiB` | Taille max d'un message entrant → au-delà, **close 1009** (`config.ts:543`).       |
+| `allowedOrigins`         | bool \| str \| list | `false` | Allowlist d'`Origin` au handshake — **anti-CSWSH** (`config.ts:552`).              |
 | `perMessageDeflate`      | bool \| objet       | `false` | Compression RFC 7692. Désactivée par défaut : coût CPU/RAM + risque de _zip bomb_. |
 | `skipUTF8Validation`     | bool                | `false` | Désactive la validation UTF-8 des frames texte (RFC 6455 §8.1). À laisser `false`. |
 | `autoPong`               | bool                | `true`  | Répond automatiquement aux pings entrants (RFC 6455 §5.5.2-3). À laisser `true`.   |
@@ -578,7 +578,7 @@ export default defineConfig(() => ({
 
 `node-forge` est une grosse dépendance. Elle est chargée **paresseusement**, uniquement sur le chemin
 de génération (`Certificate.loadForge()`, `certificates.ts:227`) : en production avec un certificat
-fourni, elle n'entre jamais dans le processus (`certificates.ts:334`).
+fourni, elle n'entre jamais dans le processus (`certificates.ts:227`).
 
 ### Conformité de l'auto-signé
 
@@ -784,7 +784,7 @@ processus à l'arrêt.
 
 L'upgrade WebSocket **est** une requête HTTP : il passe donc par le **même** compteur de rate-limit par
 IP que les requêtes ordinaires, vérifié avant toute allocation de contexte
-(`HttpKernel.onWebsocketRequest()`, `http-kernel.ts:1497`). Le `101` étant déjà émis par `ws`, un `429`
+(`HttpKernel.onWebsocketRequest()`, `http-kernel.ts:1540`). Le `101` étant déjà émis par `ws`, un `429`
 est impossible → la connexion est fermée en **1013 « Try Again Later »**
 (`rateLimiter`, `http-kernel.ts:287`), sans
 journalisation (un journal par handshake rejeté serait lui-même un amplificateur sous flood).
@@ -836,13 +836,13 @@ demande le backplane realtime.
 | ------------------------------------- | ------------------ | -------------------------------------------------------------------------- |
 | HTTP/1.1 (sémantique, message)        | RFC 9110, 9112     | `node:http` + pipeline `HttpKernel.onHttpRequest()` (`http-kernel.ts:819`) |
 | HTTP/2                                | RFC 9113           | `ServerHttps.createServerH2()` (`server-https.ts:174`)                     |
-| HTTP/2 Rapid Reset                    | CVE-2023-44487     | `maxConcurrentStreams` (`config.ts:334`)                                   |
+| HTTP/2 Rapid Reset                    | CVE-2023-44487     | `maxConcurrentStreams` (`config.ts:355`)                                   |
 | En-têtes trop volumineux → 431        | RFC 6585 §5        | `handleClientError()` (`clientError.ts:25`)                                |
 | WebSocket — protocole                 | RFC 6455           | `ws@8` + options (`config.ts:496`)                                         |
 | WebSocket — Close 1001 « Going Away » | RFC 6455 §7.4.1    | `Websocket.terminate()` (`server-websocket.ts:134`)                        |
-| WebSocket — 1009 « Message Too Big »  | RFC 6455 §7.4.1    | `maxPayload` (`config.ts:522`)                                             |
-| WebSocket — validation UTF-8          | RFC 6455 §8.1      | `skipUTF8Validation` (`config.ts:602`)                                     |
-| WebSocket — compression               | RFC 7692           | `perMessageDeflate` (`config.ts:546`)                                      |
+| WebSocket — 1009 « Message Too Big »  | RFC 6455 §7.4.1    | `maxPayload` (`config.ts:543`)                                             |
+| WebSocket — validation UTF-8          | RFC 6455 §8.1      | `skipUTF8Validation` (`config.ts:623`)                                     |
+| WebSocket — compression               | RFC 7692           | `perMessageDeflate` (`config.ts:567`)                                      |
 | CSWSH (Origin au handshake)           | OWASP WSTG-CLNT-10 | `HttpKernel.checkWebsocketOrigin()` (`http-kernel.ts:599`)                 |
 | En-têtes forwarded                    | RFC 7239           | `resolveForwarded()` (`forwarded.ts:253`)                                  |
 | Certificat — série, SAN, extensions   | RFC 5280           | `Certificate.generateSerialHex()` (`certificates.ts:264`)                  |
@@ -886,7 +886,7 @@ l'origine du transport.
 
 `proxy:generate` mérite un mot : la configuration nginx/HAProxy est **dérivée** des domaines de
 confiance, des ports effectifs et des dossiers statiques montés — donc elle ne diverge pas du code. Le
-résumé de certificat vient de `Certificate.describe()` (`certificates.ts:812`), source unique partagée
+résumé de certificat vient de `Certificate.describe()` (`certificates.ts:853`), source unique partagée
 par la commande, le boot et un futur écran d'administration.
 
 **Runtime.** `nodefony status` et `nodefony stop` lisent les ports effectifs publiés au boot ; ils

package/docs/session.md

@@ -144,7 +144,7 @@ seule présence d'un paramètre `@Session` — ou si un cookie arrive déjà : c
 ni `Set-Cookie`**.
 
 **3. Un seul modèle d'état pour le web et le temps réel.** Le même `startSession()` sert
-`HttpKernel.onRequestEnd()` (`http-kernel.ts:1391`) et `HttpKernel.onConnect()` (`http-kernel.ts:1659`) ;
+`HttpKernel.onRequestEnd()` (`http-kernel.ts:1434`) et `HttpKernel.onConnect()` (`http-kernel.ts:1702`) ;
 l'activité HTTP **ou** WS prolonge la même session (`Session.touchIfNeeded()`, `session.ts:421`).
 
 **4. L'administration ne voit jamais un identifiant.** Un opérateur manipule une `ref`, HMAC tronqué
@@ -278,12 +278,12 @@ faute de `Secure` (`Context.getSessionCookieName()`, `Context.ts:714`).
 
 ## ⚙️ Configuration
 
-Source unique des défauts : le schéma Zod `sessionSchema` (`config.ts:761`) et son sous-schéma
-`sessionCookieSchema` (`config.ts:727`).
+Source unique des défauts : le schéma Zod `sessionSchema` (`config.ts:782`) et son sous-schéma
+`sessionCookieSchema` (`config.ts:748`).
 
 | Option              | Type    | Défaut       | Effet                                                                             |
 | ------------------- | ------- | ------------ | --------------------------------------------------------------------------------- |
-| `store`             | string  | `"auto"`     | Backend de persistance — voir la résolution ci-dessous (`config.ts:755`).         |
+| `store`             | string  | `"auto"`     | Backend de persistance — voir la résolution ci-dessous (`config.ts:795`).         |
 | `name`              | string  | `"nodefony"` | Nom du cookie, préfixé `__Host-` selon `cookie.hostPrefix` (`config.ts:750`).     |
 | `strictMode`        | bool    | `true`       | Un identifiant inconnu du store est rejeté → session neuve (anti-fixation).       |
 | `idleTimeoutS`      | int ≥ 0 | `1800`       | Inactivité max (30 min). `0` = pas d'expiration par inactivité (`config.ts:796`). |
@@ -498,7 +498,7 @@ C'est le différenciateur du framework appliqué à l'état de session : un seul
 <!-- prettier-ignore -->
 | Aspect | HTTP | WebSocket |
 | --- | --- | --- |
-| Ouverture | à chaque requête — `startSession()` dans `onRequestEnd()` (`http-kernel.ts:1391`) | **une fois** au handshake — `startSession()` dans `onConnect()` (`http-kernel.ts:1659`) |
+| Ouverture | à chaque requête — `startSession()` dans `onRequestEnd()` (`http-kernel.ts:1434`) | **une fois** au handshake — `startSession()` dans `onConnect()` (`http-kernel.ts:1702`) |
 | Lecture du cookie | constructeur du contexte | constructeur, même nom effectif (`WebsocketContext.ts:172`) |
 | Sauvegarde | fin de requête | après **chaque frame** traitée (`WebsocketContext.ts:302`) |
 | Filet de fermeture | — | `once("onFinish")` sauve si non déjà fait (`http-kernel.ts:1185`) |
@@ -561,13 +561,13 @@ Trois barrières superposées :
    **liste blanche** : `ref`, `user`, `authenticated`, `ip`, `ua`, dates. Jamais un `delete` après coup.
 3. La `ref` elle-même est un HMAC tronqué non réversible (`computeSessionRef()`,
    `sessions-service.ts:100`) ; la clé est dérivée du certificat au boot et n'est jamais sérialisée
-   (`SessionsService.sessionRef()`, `sessions-service.ts:511`).
+   (`SessionsService.sessionRef()`, `sessions-service.ts:528`).
 
 ### Récapitulatif des défenses actives par défaut
 
 | Menace                            | Défense                                           | Ancrage                                            |
 | --------------------------------- | ------------------------------------------------- | -------------------------------------------------- |
-| Vol par script injecté (XSS)      | `HttpOnly`                                        | `sessionCookieSchema` (`config.ts:718`)            |
+| Vol par script injecté (XSS)      | `HttpOnly`                                        | `sessionCookieSchema` (`config.ts:748`)            |
 | Interception réseau               | `Secure` + `__Host-` sur TLS                      | `getSessionCookieName()` (`Context.ts:714`)        |
 | Requête inter-sites               | `SameSite=Lax` par défaut                         | `defaultCookieOptions` (`cookie.ts:48`)            |
 | Fixation (cookie pré-posé)        | `strictMode` + régénération au login              | `Session.resume()` (`session.ts:189`)              |
@@ -582,7 +582,7 @@ Trois barrières superposées :
 
 Les signatures vivent dans `.ai/symbols.json` (jamais recopiées ici). Voici les usages réels.
 
-**Depuis un contrôleur** — `this.session` est un getter sur le contexte (`Controller.ts:229`) ; un
+**Depuis un contrôleur** — `this.session` est un getter sur le contexte (`Controller.ts:279`) ; un
 paramètre `@Session()` suffit à déclarer l'intent.
 
 | Besoin                           | Appel                                | Effet                                                   |