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

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/nodefony/src/servers/portBinder.js

@@ -1,3 +1,4 @@
+import { isPortListening } from "nodefony";
 //#region nodefony/src/servers/portBinder.ts
 /** Nombre de ports essayés après le désiré, en `auto`. */
 const DEFAULT_PORT_RETRY_ATTEMPTS = 20;
@@ -42,6 +43,69 @@ function buildBindPlan(which, servers, environment) {
 		attempts: policy === "auto" ? servers?.portRetryAttempts ?? 20 : 0
 	};
 }
+/** Adresses qui désignent « toutes les interfaces » — rien ne s'y connecte. */
+const WILDCARD_HOSTS = /* @__PURE__ */ new Set([
+	"",
+	"*",
+	"0.0.0.0",
+	"::",
+	"[::]"
+]);
+/** Adresses de la boucle locale, toutes familles — c'est aussi ce qu'on REND. */
+const LOOPBACK_HOSTS = ["127.0.0.1", "::1"];
+/** Les mêmes, plus le nom qui les désigne — DÉRIVÉ, jamais recopié. */
+const LOOPBACK_ALIASES = /* @__PURE__ */ new Set([...LOOPBACK_HOSTS, "localhost"]);
+/**
+* Adresses à interroger pour savoir si notre future liaison chevauche déjà un
+* serveur vivant.
+*
+* La règle est celle du TRAFIC, pas celle du noyau : on sonde ce que notre
+* liaison va RECEVOIR.
+* - Écouter sur **toutes les interfaces** recouvre la boucle locale : on sonde
+*   ses deux adresses (`127.0.0.1` et `::1`). Un wildcard n'est pas une
+*   destination, on ne peut pas s'y connecter.
+* - Écouter sur la **boucle locale** (`localhost` résout `::1` ici, `127.0.0.1`
+*   ailleurs — et les clients ne choisissent pas) : les deux, là encore.
+* - Écouter sur une **adresse d'interface précise** : elle seule. Une connexion
+*   vers elle atteint le tiers qu'il ait lié cette adresse ou le wildcard, donc
+*   une cible suffit — et sonder la boucle locale ferait refuser un pod à cause
+*   d'un voisin de conteneur qui n'a jamais été en conflit.
+*
+* Fonction PURE : le banc l'éprouve sans ouvrir un socket.
+*
+* @param host - hôte passé à `listen` (`kernel.domain`).
+* @returns les adresses à interroger, dans l'ordre.
+*/
+function conflictProbeTargets(host) {
+	const value = (host ?? "").trim().toLowerCase();
+	if (WILDCARD_HOSTS.has(value) || LOOPBACK_ALIASES.has(value)) return LOOPBACK_HOSTS;
+	return [value];
+}
+/**
+* Première adresse où un serveur répond DÉJÀ sur ce port, `null` si la voie est
+* libre.
+*
+* @param port - port candidat.
+* @param host - hôte que `listen` recevra (décide des adresses interrogées).
+* @param probe - sonde de présence (injectée par le banc).
+*/
+async function detectPortConflict(port, host, probe) {
+	for (const target of conflictProbeTargets(host)) if (await probe(port, target)) return target;
+	return null;
+}
+/**
+* Erreur d'un conflit que le noyau aurait laissé passer.
+*
+* Porte `EADDRINUSE` : pour l'appelant c'est le même fait — le port n'est pas
+* prenable — et une seule branche le traite. Le message, lui, doit dire ce que
+* le code d'erreur seul ferait chercher au mauvais endroit : ici `listen` aurait
+* RÉUSSI, et c'est la liaison d'une AUTRE adresse qui capte le trafic.
+*/
+function portConflictError(port, host) {
+	const error = /* @__PURE__ */ new Error(`Port ${port} déjà servi par un autre processus sur ${host} — le noyau l'aurait pourtant accordé (deux adresses distinctes coexistent sur le même port), et cette application aurait écouté sans rien recevoir. Libérer le port (nodefony status · nodefony stop), en figer un autre (servers.http.port / servers.https.port), ou autoriser le repli (servers.portPolicy = "auto", défaut en développement).`);
+	error.code = "EADDRINUSE";
+	return error;
+}
 /** Prochain candidat : incrémente, en sautant ce que les autres serveurs veulent. */
 function nextCandidate(from, reserved) {
 	let port = from + 1;
@@ -84,31 +148,39 @@ function isPortUnavailable(code, port) {
 *   (`ENOTFOUND`, `EACCES` sous 1024 — cf `isPortUnavailable`), soit un port
 *   indisponible après épuisement des essais (le fallback n'est PAS infini).
 */
-function bindWithFallback(server, host, plan) {
-	return new Promise((resolve, reject) => {
-		let candidate = plan.desired;
-		let used = 0;
-		const attempt = () => {
-			const onError = (error) => {
-				server.removeListener("listening", onListening);
-				if (!isPortUnavailable(error.code, candidate) || plan.desired === 0 || used >= plan.attempts) return reject(error);
-				used += 1;
-				candidate = nextCandidate(candidate, plan.reserved);
-				attempt();
-			};
-			const onListening = () => {
-				server.removeListener("error", onError);
-				resolve({
-					address: server.address(),
-					shiftedFrom: candidate === plan.desired ? null : plan.desired
-				});
-			};
-			server.once("error", onError);
-			server.once("listening", onListening);
-			server.listen(candidate, host);
+async function bindWithFallback(server, host, plan, probe = isPortListening) {
+	let candidate = plan.desired;
+	let used = 0;
+	/**
+	* Une tentative d'écoute. L'erreur est RENDUE, jamais levée depuis le
+	* callback : les deux écouteurs se retirent dans les deux cas, et la boucle
+	* ci-dessous reste le seul endroit qui décide.
+	*/
+	const listenOnce = (port) => new Promise((settle) => {
+		const onError = (error) => {
+			server.removeListener("listening", onListening);
+			settle(error);
 		};
-		attempt();
+		const onListening = () => {
+			server.removeListener("error", onError);
+			settle(null);
+		};
+		server.once("error", onError);
+		server.once("listening", onListening);
+		server.listen(port, host);
 	});
+	for (;;) {
+		const conflict = plan.desired === 0 || candidate !== plan.desired ? null : await detectPortConflict(candidate, host, probe);
+		const failure = conflict ? portConflictError(candidate, conflict) : await listenOnce(candidate);
+		if (failure === null) return {
+			address: server.address(),
+			shiftedFrom: candidate === plan.desired ? null : plan.desired
+		};
+		if (!conflict && !isPortUnavailable(failure.code, candidate)) throw failure;
+		if (plan.desired === 0 || used >= plan.attempts) throw failure;
+		used += 1;
+		candidate = nextCandidate(candidate, plan.reserved);
+	}
 }
 //#endregion
-export { DEFAULT_PORT_RETRY_ATTEMPTS, bindWithFallback, buildBindPlan, resolvePortPolicy };
+export { DEFAULT_PORT_RETRY_ATTEMPTS, bindWithFallback, buildBindPlan, conflictProbeTargets, detectPortConflict, resolvePortPolicy };

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/dist/types/nodefony/src/servers/portBinder.d.ts

@@ -14,6 +14,24 @@
  * `listen()` est, lui, **atomique** : soit il réussit, soit le noyau dit
  * `EADDRINUSE`. On retente donc sur l'échec réel, jamais sur une prédiction.
  *
+ * ## Pourquoi une SONDE malgré cela
+ *
+ * Le `listen()` est atomique, mais il ne dit pas tout : un port peut être **déjà
+ * servi** et le noyau l'accorder quand même. Lier `0.0.0.0:P` alors qu'un autre
+ * processus tient `127.0.0.1:P` **réussit** sur macOS et les BSD — ce sont deux
+ * liaisons distinctes, et les connexions locales partent à la PLUS SPÉCIFIQUE.
+ * Entre familles d'adresses (`::1` tenu, `0.0.0.0` demandé), même linux
+ * l'accorde. L'application annonce alors `READY`, publie ses ports… et ne reçoit
+ * rien : une panne muette, et un banc qui interroge le serveur du VOISIN.
+ *
+ * On constate donc, AVANT de binder, qu'aucun serveur ne répond déjà là où notre
+ * liaison va recevoir (`isPortListening` — une connexion en boucle locale, aucun
+ * outil système, même verdict sur les trois plateformes). Ce n'est pas la sonde
+ * « ce port est-il libre ? » écartée plus haut : elle ne remplace pas le repli
+ * atomique, qui reste le seul à trancher la course — elle ajoute le seul conflit
+ * que le noyau n'exprime JAMAIS. La course résiduelle (un tiers prend le port
+ * entre la sonde et le bind) retombe donc sur `EADDRINUSE`, inchangé.
+ *
  * ## Pourquoi sauter les ports réservés
  *
  * HTTP veut 5151, HTTPS veut 5152. Si 5151 est pris, incrémenter naïvement ferait
@@ -86,6 +104,45 @@ export interface ServersPortConfig {
  * @param environment - `kernel.environment` (arbitre le défaut de la politique).
  */
 export declare function buildBindPlan(which: "http" | "https", servers: ServersPortConfig | undefined, environment: string | undefined): BindPlan;
+/**
+ * Sonde « un serveur répond-il déjà ici ? ».
+ *
+ * Injectable pour que le banc éprouve la DÉCISION sans dépendre d'un décor
+ * réseau ; le défaut est `isPortListening`, exposé par le cœur pour ne pas être
+ * recopié de paquet en paquet.
+ */
+export type PortListeningProbe = (port: number, host: string) => Promise<boolean>;
+/**
+ * Adresses à interroger pour savoir si notre future liaison chevauche déjà un
+ * serveur vivant.
+ *
+ * La règle est celle du TRAFIC, pas celle du noyau : on sonde ce que notre
+ * liaison va RECEVOIR.
+ * - Écouter sur **toutes les interfaces** recouvre la boucle locale : on sonde
+ *   ses deux adresses (`127.0.0.1` et `::1`). Un wildcard n'est pas une
+ *   destination, on ne peut pas s'y connecter.
+ * - Écouter sur la **boucle locale** (`localhost` résout `::1` ici, `127.0.0.1`
+ *   ailleurs — et les clients ne choisissent pas) : les deux, là encore.
+ * - Écouter sur une **adresse d'interface précise** : elle seule. Une connexion
+ *   vers elle atteint le tiers qu'il ait lié cette adresse ou le wildcard, donc
+ *   une cible suffit — et sonder la boucle locale ferait refuser un pod à cause
+ *   d'un voisin de conteneur qui n'a jamais été en conflit.
+ *
+ * Fonction PURE : le banc l'éprouve sans ouvrir un socket.
+ *
+ * @param host - hôte passé à `listen` (`kernel.domain`).
+ * @returns les adresses à interroger, dans l'ordre.
+ */
+export declare function conflictProbeTargets(host: string | undefined): readonly string[];
+/**
+ * Première adresse où un serveur répond DÉJÀ sur ce port, `null` si la voie est
+ * libre.
+ *
+ * @param port - port candidat.
+ * @param host - hôte que `listen` recevra (décide des adresses interrogées).
+ * @param probe - sonde de présence (injectée par le banc).
+ */
+export declare function detectPortConflict(port: number, host: string | undefined, probe: PortListeningProbe): Promise<string | null>;
 /**
  * Écoute sur `plan.desired`, ou sur le prochain port libre si `attempts > 0`.
  *
@@ -99,4 +156,4 @@ export declare function buildBindPlan(which: "http" | "https", servers: ServersP
  *   (`ENOTFOUND`, `EACCES` sous 1024 — cf `isPortUnavailable`), soit un port
  *   indisponible après épuisement des essais (le fallback n'est PAS infini).
  */
-export declare function bindWithFallback(server: Listenable, host: string, plan: BindPlan): Promise<BindResult>;
+export declare function bindWithFallback(server: Listenable, host: string, plan: BindPlan, probe?: PortListeningProbe): Promise<BindResult>;

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`           |