@nodefony/http 10.0.0-alpha.1

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

@@ -0,0 +1,415 @@
+import { buildMetaData } from "./metaData.js";
+import Cookie, { cookiesParser } from "../cookies/cookie.js";
+import { RequestContext, Service, logColor } from "nodefony";
+import { randomFillSync, randomUUID } from "node:crypto";
+import { performance } from "node:perf_hooks";
+import { AsyncResource } from "node:async_hooks";
+//#region nodefony/src/context/Context.ts
+const colorLogEvent = () => logColor.cyanBgBlack("EVENT CONTEXT");
+const PERF_PROBE_SUB = process.env.NF_PERF_PROBE === "1";
+const EVENT_SEVERITY = {
+	onRequest: "INFO",
+	onSend: "INFO",
+	onConnect: "INFO",
+	onClose: "INFO"
+};
+let lifecycleEventLogging = null;
+/**
+* Bascule runtime du gate des logs d'events lifecycle. Réservé HORS hot path :
+* tests et futur « Audit à chaud » (fenêtre bornée prod→verbeux, auto-revert
+* serveur) — le canal Studio `nodefony:syslog` retrouve alors les events sans
+* redémarrage. `null` → re-résolution depuis l'env au prochain event.
+*/
+function setLifecycleEventLogging(value) {
+	lifecycleEventLogging = value;
+}
+const EMPTY_PHASES = Object.freeze([]);
+const NONCE_POOL_SIZE = 4096;
+const NONCE_BYTES = 16;
+const noncePool = Buffer.allocUnsafe(NONCE_POOL_SIZE);
+let noncePoolOffset = NONCE_POOL_SIZE;
+/**
+* Rend le prochain nonce CSP (16 octets CSPRNG, base64) depuis le pool amorti.
+*
+* Exporté UNIQUEMENT pour le banc d'épuisement du pool (unicité à travers
+* plusieurs refills) — le code produit passe par `context.cspNonce`.
+*/
+function nextCspNonce() {
+	if (noncePoolOffset + NONCE_BYTES > NONCE_POOL_SIZE) {
+		randomFillSync(noncePool);
+		noncePoolOffset = 0;
+	}
+	const nonce = noncePool.toString("base64", noncePoolOffset, noncePoolOffset + NONCE_BYTES);
+	noncePoolOffset += NONCE_BYTES;
+	return nonce;
+}
+var Context = class extends Service {
+	secure = false;
+	security = null;
+	cleaned = false;
+	isControlledAccess = false;
+	validDomain = false;
+	finished = false;
+	pushAllowed = false;
+	requestEnded = false;
+	requested = false;
+	sessionStarting = false;
+	domain = "";
+	type;
+	server;
+	httpKernel;
+	request = null;
+	response = null;
+	url = "";
+	method = null;
+	remoteAddress = null;
+	_originUrl = null;
+	get originUrl() {
+		return this._originUrl;
+	}
+	set originUrl(value) {
+		this._originUrl = value;
+	}
+	cookies = {};
+	error = null;
+	sessionService;
+	session = null;
+	cookieSession = null;
+	user = null;
+	waitAsync = false;
+	isJson = false;
+	_isHtml = null;
+	get isHtml() {
+		return this._isHtml ?? (this._isHtml = this.resolveIsHtml());
+	}
+	set isHtml(value) {
+		this._isHtml = value;
+	}
+	/**
+	* Défaut paresseux d'{@link isHtml} — overridé par HttpContext (négociation
+	* `Accept`). Base et WS : jamais HTML.
+	*/
+	resolveIsHtml() {
+		return false;
+	}
+	crossDomain = false;
+	router = this.get("router");
+	resolver = null;
+	/**
+	* Intent de session de la route courante (posé par le Resolver depuis
+	* `@UseSession` / paramètre `@Session`). Pilote le point d'activation unique
+	* (HTTP + WS). `null` = aucune session sauf cookie existant (reprise L1).
+	*/
+	sessionIntent = null;
+	/**
+	* Directives CSP additionnelles de la route courante (`@Csp`), posées par le
+	* Resolver au match. `null` = la route n'en déclare pas (cas courant) → le
+	* firewall compose le CSP standard (0 surcoût). Lu par `applySecurityHeaders`
+	* APRÈS le resolve. Forme `directive → sources` (compatible `CspFragment`).
+	*/
+	cspDirectives = null;
+	/**
+	* CSRF per-route (`@CsrfProtect`/`@CsrfExempt`), posés par le Resolver au match,
+	* lus par `Firewall.enforceCsrf` (post-resolve). `csrfProtect` exige le
+	* synchronizer token sur la mutation ; `csrfExempt` sort la route de la défense
+	* CSRF (auth conservée). `csrfToken` = token émis par le firewall (cookie lisible
+	* + ce champ) sur une requête sûre vers une route protégée, à surfacer côté vue.
+	*/
+	csrfProtect = false;
+	csrfExempt = false;
+	csrfToken = null;
+	requestId = randomUUID();
+	#cspNonce = null;
+	get cspNonce() {
+		return this.#cspNonce ??= nextCspNonce();
+	}
+	traceparent = null;
+	profilerQueries = null;
+	profiling = false;
+	securityTrace = null;
+	_timingEnabled = false;
+	_timingVerbose = false;
+	phases = EMPTY_PHASES;
+	_phaseIndex = null;
+	_afterResponseFns = null;
+	_afterResponseFired = false;
+	_abortController = null;
+	metaData = {
+		nodefony: {},
+		result: null
+	};
+	scheme;
+	webSocketState = null;
+	constructor(container, type) {
+		super(`${type}`, container);
+		if (PERF_PROBE_SUB) {
+			const p = globalThis.__nfPerfProbe;
+			if (p && p.t0 !== 0n) p.svcNs += Number(process.hrtime.bigint() - p.t0);
+		}
+		this.type = type;
+		this.set("context", this);
+		this.httpKernel = this.get("HttpKernel");
+		this.sessionService = this.get("sessions");
+		this.setMetaData();
+		const explicit = (this.kernel?.options)?.timing?.enabled;
+		if (typeof explicit === "boolean") this._timingEnabled = explicit;
+		else this._timingEnabled = this.kernel?.environment !== "production";
+		if (this._timingEnabled) {
+			this.phases = [];
+			const verbose = (this.kernel?.options)?.timing?.verbose;
+			this._timingVerbose = verbose === true;
+		}
+		this.scheme = "https";
+		switch (this.type) {
+			case "http": {
+				this.scheme = "http";
+				const server = this.get("server-http");
+				this.server = server?.server;
+				break;
+			}
+			case "http2":
+			case "https": {
+				this.scheme = "https";
+				const server = this.get("server-https");
+				this.server = server?.server;
+				break;
+			}
+			case "http3": {
+				this.scheme = "https";
+				const server = this.get("server-http3");
+				this.server = server?.server ?? null;
+				break;
+			}
+			case "websocket": {
+				this.scheme = "ws";
+				const server = this.get("server-websocket");
+				this.server = server?.server;
+				break;
+			}
+			case "websocket-secure": {
+				this.scheme = "wss";
+				const server = this.get("server-websocket-secure");
+				this.server = server?.server;
+				break;
+			}
+		}
+		if (PERF_PROBE_SUB) {
+			const p = globalThis.__nfPerfProbe;
+			if (p && p.t0 !== 0n) p.ctxBaseNs += Number(process.hrtime.bigint() - p.t0);
+		}
+	}
+	/**
+	* Assemble l'enveloppe `metaData` de la requête (`nodefony.*` + `route`
+	* snapshot per-requête + overrides appelant). Délègue au builder monomorphe
+	* pur {@link buildMetaData} — pas de `extend(true, …)` (deep-clone + dispatch
+	* polymorphe inutiles : `this.metaData` est per-requête, jamais partagé). `this`
+	* satisfait structurellement {@link IMetaDataSource} (kernel/request/scheme/
+	* requestId/resolver) → zéro alloc d'objet intermédiaire.
+	*/
+	setMetaData(obj = {}) {
+		return buildMetaData(this.metaData, this, obj);
+	}
+	setScheme() {
+		return "https";
+	}
+	/**
+	* Le timing est-il actif sur CETTE requête ? (dev/test par défaut, opt-out en
+	* production — cf constructeur.)
+	*
+	* Exposé pour que les appelants qui devraient **payer** pour mesurer (un
+	* `try/finally` autour d'une chaîne de promesses = une microtask de plus par
+	* requête) puissent garder leur chemin nominal INTACT quand la mesure est
+	* éteinte : `if (!ctx.timingEnabled) return fastPath()`. Les autres n'ont rien
+	* à tester — {@link phaseStart}/{@link phaseEnd} sont déjà des no-ops.
+	*/
+	get timingEnabled() {
+		return this._timingEnabled;
+	}
+	phaseStart(name) {
+		if (!this._timingEnabled) return;
+		if (this._phaseIndex === null) this._phaseIndex = /* @__PURE__ */ new Map();
+		const idx = this.phases.length;
+		this.phases.push({
+			name,
+			startMs: performance.now()
+		});
+		this._phaseIndex.set(name, idx);
+	}
+	phaseEnd(name) {
+		if (!this._timingEnabled || this._phaseIndex === null) return;
+		const idx = this._phaseIndex.get(name);
+		if (idx === void 0) return;
+		const p = this.phases[idx];
+		if (p.endMs !== void 0) return;
+		p.endMs = performance.now();
+		p.durationMs = p.endMs - p.startMs;
+	}
+	onAfterResponse(fn) {
+		const boundFn = AsyncResource.bind(fn);
+		if (this._afterResponseFired) {
+			Promise.resolve().then(() => boundFn(this)).catch((e) => this.log(e, "ERROR", "onAfterResponse(late)"));
+			return;
+		}
+		if (this._afterResponseFns === null) this._afterResponseFns = [];
+		this._afterResponseFns.push(boundFn);
+	}
+	async _runAfterResponse() {
+		if (this._afterResponseFired) return;
+		this._afterResponseFired = true;
+		const fns = this._afterResponseFns;
+		if (fns === null || fns.length === 0) return;
+		this._afterResponseFns = null;
+		for (const fn of fns) try {
+			await fn(this);
+		} catch (e) {
+			this.log(e, "ERROR", "onAfterResponse");
+		}
+	}
+	get signal() {
+		if (this._abortController === null) {
+			this._abortController = new AbortController();
+			const req = this.request;
+			if (req && typeof req.once === "function") {
+				const onAborted = () => {
+					if (this._abortController && !this._abortController.signal.aborted && req.complete === false) this._abortController.abort(/* @__PURE__ */ new Error("Request aborted by client"));
+				};
+				if (req.destroyed && req.complete === false) onAborted();
+				else req.once("close", onAborted);
+			}
+		}
+		return this._abortController.signal;
+	}
+	_abortIfPending(reason) {
+		if (this._abortController && !this._abortController.signal.aborted) this._abortController.abort(new Error(reason ?? "Context aborted"));
+	}
+	log(pci, severity, msgid, msg) {
+		if (!msgid) msgid = this.type;
+		if (this.requestId && RequestContext.getRequestId() === void 0) return RequestContext.run({ requestId: this.requestId }, () => super.log(pci, severity, msgid, msg));
+		return super.log(pci, severity, msgid, msg);
+	}
+	clean() {
+		this.cleaned = true;
+		this.httpKernel = null;
+		return super.clean();
+	}
+	/**
+	* Log d'un event du cycle de vie — gate boot-time (V2.1) : en production le
+	* Pdu n'est PAS construit (return avant toute allocation). Hors prod, jalon
+	* notable → INFO (EVENT_SEVERITY), event technique → DEBUG.
+	*/
+	logEvent(event) {
+		if (lifecycleEventLogging === null) lifecycleEventLogging = this.kernel?.environment !== "production";
+		if (!lifecycleEventLogging) return;
+		this.log(`${colorLogEvent()} ${event}`, EVENT_SEVERITY[event] || "DEBUG");
+	}
+	fire(event, ...args) {
+		this.logEvent(event);
+		return super.fire(event, ...args);
+	}
+	emit(event, ...args) {
+		this.logEvent(event);
+		return super.emit(event, ...args);
+	}
+	emitAsync(event, ...args) {
+		this.logEvent(event);
+		return super.emitAsync(event, ...args);
+	}
+	fireAsync(event, ...args) {
+		this.logEvent(event);
+		return super.emitAsync(event, ...args);
+	}
+	logRequest(httpError) {
+		try {
+			const err = httpError ?? this.error ?? void 0;
+			if (err) this.error = err;
+			const logger = this.httpKernel?.getRequestLogger();
+			if (!logger) return;
+			if (logger.shouldSample && !logger.shouldSample(this, err)) return;
+			const entry = logger.renderHttp(this, err);
+			return this.log(entry.text, entry.severity, entry.msgid);
+		} catch {}
+	}
+	/**
+	* P3.7 — Émet au teardown un log DEBUG détaillant la durée de chaque phase du
+	* pipeline (`parse · action · firewall · …` + total). Opt-in via
+	* `kernel.options.timing.verbose`. Triple gate perf-first : `_timingVerbose`
+	* résolu 1× (false en prod/par défaut) → timing actif → phases non vides ;
+	* hors mode verbose, early-return AVANT toute allocation/`toFixed` (coût nul).
+	*/
+	logPhasesVerbose() {
+		if (!this._timingVerbose) return;
+		const phases = this.phases;
+		const n = phases.length;
+		if (n === 0) return;
+		let line = "";
+		let total = 0;
+		for (let i = 0; i < n; i++) {
+			const p = phases[i];
+			const d = p.durationMs ?? (p.endMs !== void 0 ? p.endMs - p.startMs : void 0);
+			if (i > 0) line += " · ";
+			if (d !== void 0) {
+				line += `${p.name}=${d.toFixed(2)}ms`;
+				total += d;
+			} else line += `${p.name}=…`;
+		}
+		this.log(`TRACE phases [Σ ${total.toFixed(2)}ms] ${line}`, "DEBUG", `${this.type} TIMING`);
+	}
+	addRequestCookie(cookie) {
+		if (cookie instanceof Cookie) return this.cookies[cookie.name] = cookie;
+		else {
+			const error = /* @__PURE__ */ new Error("addCookie cookie not valid !!");
+			this.log(cookie, "ERROR");
+			throw error;
+		}
+	}
+	getRequestCookies(name) {
+		if (name) return this.cookies[name] || null;
+		return this.cookies;
+	}
+	setCookie(cookie) {
+		if (cookie) return this.response?.addCookie(cookie);
+	}
+	getRequest() {
+		return this.request;
+	}
+	getResponse() {
+		return this.response;
+	}
+	isValidDomain() {
+		if (!this.httpKernel) throw new Error(`Http Kernel not ready`);
+		return this.httpKernel.isValidDomain(this);
+	}
+	async saveSession() {
+		if (this.sessionService) return this.sessionService.saveSession(this);
+		throw new Error(`sessionService not found `);
+	}
+	hasSession() {
+		return Boolean(this.cookieSession);
+	}
+	getCookieSession(name) {
+		if (this.cookies[name]) return this.cookies[name];
+		return null;
+	}
+	/**
+	* Nom effectif du cookie de session pour CE transport. Sur TLS (https/wss) on
+	* applique le préfixe **`__Host-`** (RFC 6265bis §4.1.3 / OWASP : recommandé
+	* pour les identifiants de session — impose Secure + Path=/ + interdit Domain,
+	* anti session-fixation cross-subdomain). En clair (http/ws) le préfixe est
+	* omis (le navigateur le rejetterait sans Secure) → dégradation gracieuse,
+	* notamment derrière un proxy qui termine le TLS. Lecture **et** écriture du
+	* cookie passent par ce nom unique → cohérence de la reprise (L1).
+	*/
+	getSessionCookieName() {
+		const base = this.sessionService?.defaultSessionName ?? "nodefony";
+		const mode = (this.sessionService?.options?.cookie)?.hostPrefix ?? "auto";
+		const tls = this.scheme === "https" || this.scheme === "wss";
+		return mode === true || mode === "auto" && tls ? `__Host-${base}` : base;
+	}
+	parseCookies() {
+		return cookiesParser(this);
+	}
+	setContextJson(_encoding = "utf-8") {}
+	setContextHtml(_encoding = "utf-8") {}
+};
+//#endregion
+export { Context as default, nextCspNonce, setLifecycleEventLogging };

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

@@ -0,0 +1,88 @@
+import { escapeRegExp } from "nodefony";
+//#region nodefony/src/context/domainMatcher.ts
+/**
+* Matching de domaine (`Host`) — fonctions PURES, politique UNIQUE partagée par
+* les deux étages de Nodefony :
+*
+* - **`trustedHosts` (kernel, sécu)** : barrière testée AVANT le routing. Quels
+*   `Host` ce serveur accepte de traiter (anti Host-header injection). Host non
+*   trusté → 401 (`HttpKernel.checkValidDomain`). Grossier, optionnel (en prod,
+*   typiquement délégué au reverse-proxy via `trustedHosts: true`).
+* - **`@Domain` (route, routing)** : restreint une route / un contrôleur à un
+*   vhost. Source de vérité du « qui sert quoi ». Testé PENDANT le routing
+*   (`Route.matchHostname`) → 403 si la route ne sert pas ce domaine.
+*
+* Politique de compilation (sûre, ancrée, ReDoS-free) :
+* - string sans `*` → match EXACT ancré (`^...$`, le `.` est littéral).
+* - string avec `*` → wildcard UN label (`*.example.com` → `^[^.]+\.example\.com$`,
+*   RFC 6125 TLS-wildcard : matche `img.example.com`, pas `a.b.example.com` ni `example.com`).
+* - `RegExp` → reprise telle quelle (l'auteur assume l'ancrage).
+*
+* Compilation faite UNE fois (boot / enregistrement de route) ; le test par
+* requête est un simple `RegExp.test` sur une liste pré-compilée (zéro alloc hot-path).
+*/
+const DEV_LOOPBACK = [
+	"localhost",
+	"127.0.0.1",
+	"[::1]"
+];
+/**
+* Compile UN pattern de domaine en `RegExp` selon la politique sûre.
+*
+* @param pattern - string (exact / `*`-wildcard) ou `RegExp` (reprise telle quelle).
+* @returns une `RegExp` ancrée (pour les string) ou le `RegExp` fourni.
+*/
+function compileDomainPattern(pattern) {
+	if (pattern instanceof RegExp) return pattern;
+	const body = pattern.split("*").map(escapeRegExp).join("[^.]+");
+	return new RegExp(`^${body}$`, "u");
+}
+/**
+* Compile une liste de patterns. Les string vides sont ignorées (un `^$` ne
+* sert à rien et masque une coquille de config).
+*
+* @param patterns - un pattern ou un tableau de patterns.
+* @returns liste de `RegExp` à tester contre le `Host` entrant.
+*/
+function compileDomainPatterns(patterns) {
+	const list = Array.isArray(patterns) ? patterns : [patterns];
+	const out = [];
+	for (const p of list) if (p instanceof RegExp) out.push(p);
+	else if (typeof p === "string" && p) out.push(compileDomainPattern(p));
+	return out;
+}
+/**
+* Construit la liste `RegExp` de la barrière `trustedHosts` (kernel, avant routing).
+*
+* Toujours : le domaine canonique (`kernel.domain`). En development : + loopback
+* (`localhost`/`127.0.0.1`/`[::1]`) pour que l'URL tapée (nom OU IP) passe.
+* `trustedHosts: true` → bypass total (un seul `/^.*$/`).
+*
+* @param domain - domaine canonique du serveur (`kernel.domain`).
+* @param trusted - config `http.trustedHosts` (optionnelle).
+* @param isDev - vrai en environnement `development` (ajoute le loopback).
+* @returns liste de `RegExp` pour {@link isDomainAllowed}.
+*/
+function compileTrustedHosts(domain, trusted, isDev) {
+	if (trusted === true) return [/^.*$/u];
+	const patterns = [domain];
+	if (isDev) patterns.push(...DEV_LOOPBACK);
+	if (trusted) {
+		if (Array.isArray(trusted)) patterns.push(...trusted);
+		else patterns.push(trusted);
+	}
+	return compileDomainPatterns(patterns);
+}
+/**
+* Teste un `Host` entrant contre une liste de `RegExp` pré-compilée.
+*
+* @param regAlias - sortie de {@link compileTrustedHosts} ou {@link compileDomainPatterns}.
+* @param domain - `Host` de la requête (`context.domain`, port déjà strippé).
+* @returns `true` dès le premier match (court-circuit), `false` sinon.
+*/
+function isDomainAllowed(regAlias, domain) {
+	for (const reg of regAlias) if (reg.test(domain)) return true;
+	return false;
+}
+//#endregion
+export { compileDomainPattern, compileDomainPatterns, compileTrustedHosts, isDomainAllowed };

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

@@ -0,0 +1,185 @@
+import { extractClientIp, resolveFromRight } from "./trustProxy.js";
+import { isIPv4 } from "node:net";
+//#region nodefony/src/context/forwarded.ts
+/**
+* Découpe une chaîne sur `sep` au **niveau supérieur uniquement**, en respectant
+* les `quoted-string` RFC 7230 (`value = token / quoted-string`, §4) : un
+* séparateur à l'intérieur de guillemets (ex. un host quoté, un IPv6) n'est PAS
+* un point de coupe. Les `\"` échappés à l'intérieur des guillemets sont préservés.
+*/
+function splitTopLevel(input, sep) {
+	if (input.indexOf("\"") === -1) return input.split(sep);
+	const out = [];
+	let buf = "";
+	let inQuote = false;
+	let escaped = false;
+	for (let i = 0; i < input.length; i += 1) {
+		const c = input[i];
+		if (escaped) {
+			buf += c;
+			escaped = false;
+			continue;
+		}
+		if (c === "\\" && inQuote) {
+			buf += c;
+			escaped = true;
+			continue;
+		}
+		if (c === "\"") {
+			inQuote = !inQuote;
+			buf += c;
+			continue;
+		}
+		if (c === sep && !inQuote) {
+			out.push(buf);
+			buf = "";
+			continue;
+		}
+		buf += c;
+	}
+	out.push(buf);
+	return out;
+}
+/** Retire les guillemets d'une `quoted-string` et déséchappe `\x` (RFC 7230 §3.2.6). */
+function unquote(value) {
+	const v = value.trim();
+	if (v.length >= 2 && v[0] === "\"" && v[v.length - 1] === "\"") return v.slice(1, -1).replace(/\\(.)/gu, "$1");
+	return v;
+}
+/**
+* Parse le header `Forwarded` (RFC 7239 §4) en liste de `forwarded-element`,
+* dans l'ordre **gauche→droite** (le plus à gauche = le plus proche du client).
+*
+* Grammaire honorée : `Forwarded = 1#forwarded-element`,
+* `forwarded-element = [ forwarded-pair ] *( ";" [ forwarded-pair ] )`,
+* `forwarded-pair = token "=" value`, `value = token / quoted-string`.
+* Les noms de paramètres sont insensibles à la casse (§7.1) → normalisés.
+*
+* @param raw - valeur brute du header (string, ou string[] si répété), ou `undefined`.
+* @returns les éléments parsés, ou `null` si le header est absent/vide.
+*/
+function parseForwarded(raw) {
+	if (!raw) return null;
+	const header = Array.isArray(raw) ? raw.join(",") : raw;
+	if (!header.trim()) return null;
+	const elements = [];
+	for (const part of splitTopLevel(header, ",")) {
+		if (!part.trim()) continue;
+		const element = {};
+		for (const pair of splitTopLevel(part, ";")) {
+			const eq = pair.indexOf("=");
+			if (eq === -1) continue;
+			const key = pair.slice(0, eq).trim().toLowerCase();
+			const rawValue = pair.slice(eq + 1);
+			switch (key) {
+				case "by":
+					element.by = unquote(rawValue);
+					break;
+				case "for":
+					element.for = unquote(rawValue);
+					break;
+				case "host":
+					element.host = unquote(rawValue);
+					break;
+				case "proto": element.proto = unquote(rawValue).toLowerCase();
+			}
+		}
+		elements.push(element);
+	}
+	return elements.length ? elements : null;
+}
+/**
+* Extrait l'**IP nue** d'un node identifier RFC 7239 §6
+* (`node = nodename [ ":" node-port ]`).
+*
+* - IPv6 entre crochets (`[2001:db8::1]`, éventuel `]:port`) → l'IPv6 sans crochets.
+* - IPv4 (`192.0.2.43`, éventuel `:port`) → l'IPv4 sans le port.
+* - `unknown` et identifiants obfusqués (`obfnode` commençant par `_`, §6.3) →
+*   `null` : non comparables à une politique de confiance (barrière from-right).
+*
+* @param node - valeur d'un paramètre `for`/`by`, déjà déquotée.
+* @returns l'IP exploitable, ou `null` si absente/obfusquée/illisible.
+*/
+function forwardedNodeIp(node) {
+	if (!node) return null;
+	const n = node.trim();
+	if (!n) return null;
+	if (n[0] === "[") {
+		const end = n.indexOf("]");
+		return end > 1 ? n.slice(1, end) : null;
+	}
+	if (n === "unknown" || n[0] === "_") return null;
+	const colon = n.indexOf(":");
+	const host = colon === -1 ? n : n.slice(0, colon);
+	return isIPv4(host) ? host : host || null;
+}
+/** Premier élément (le plus à gauche = côté client) définissant `key`. */
+function firstDefined(elements, key) {
+	for (const element of elements) {
+		const value = element[key];
+		if (value !== void 0) return value;
+	}
+}
+/**
+* Premier token d'un en-tête `X-Forwarded-*` multi-valeurs (`"a, b"` → `"a"`).
+* `indexOf` + `slice` (pas de `split`) → 0 array alloué (hot path prod).
+*/
+function firstToken(value, lower = false) {
+	if (!value) return;
+	const s = Array.isArray(value) ? value[0] : value;
+	if (!s) return;
+	const comma = s.indexOf(",");
+	const first = (comma === -1 ? s : s.slice(0, comma)).trim();
+	if (!first) return;
+	return lower ? first.toLowerCase() : first;
+}
+/**
+* Résout, en **une seule passe**, le scheme, le host et l'IP cliente effectifs à
+* partir des en-têtes forwarded — header standard `Forwarded` (RFC 7239)
+* **prioritaire**, repli sur les `X-Forwarded-*` de-facto.
+*
+* Le scheme/host effectifs sont pris sur l'élément le plus à GAUCHE (côté client) ;
+* l'IP cliente est résolue **from-right** ({@link resolveFromRight}) en partant du
+* socket réel, donc non spoofable. La priorité unique `Forwarded.proto` >
+* `x-forwarded-proto` > `x-forwarded-scheme` supprime l'ancienne double source.
+*
+* À n'appeler que derrière un proxy de confiance (RFC 7239 §8.1) : la décision
+* `isTrusted(socket)` est prise par l'appelant (lazy : pas d'allocation hors proxy).
+*
+* @param headers - en-têtes de la requête.
+* @param socketAddress - `socket.remoteAddress` (connexion TCP réelle).
+* @param checker - politique de confiance ({@link buildTrustProxy}).
+* @returns la résolution canonique unifiée.
+*/
+function resolveForwarded(headers, socketAddress, checker) {
+	const elements = parseForwarded(headers.forwarded);
+	if (elements) {
+		const chain = elements.map((element) => forwardedNodeIp(element.for));
+		const forwardedFor = elements.map((element) => element.for).filter((value) => Boolean(value)).join(", ") || void 0;
+		return {
+			proto: firstDefined(elements, "proto"),
+			host: firstDefined(elements, "host"),
+			forwardedFor,
+			clientIp: socketAddress ? resolveFromRight(chain, socketAddress, checker) : null,
+			fromStandard: true
+		};
+	}
+	const xff = headers["x-forwarded-for"];
+	return {
+		proto: firstToken(headers["x-forwarded-proto"], true) ?? firstToken(headers["x-forwarded-scheme"], true),
+		host: firstToken(headers["x-forwarded-host"]),
+		forwardedFor: typeof xff === "string" ? xff : xff?.join(", "),
+		clientIp: extractClientIp(xff, socketAddress, checker),
+		fromStandard: false
+	};
+}
+/**
+* Au moins un en-tête forwarded (standard ou de-facto) est-il présent ? Permet à
+* l'appelant de n'allouer la résolution que quand c'est utile (hot path : 0 alloc
+* sur une requête directe sans proxy).
+*/
+function hasForwardingHeaders(headers) {
+	return Boolean(headers.forwarded || headers["x-forwarded-for"] || headers["x-forwarded-proto"] || headers["x-forwarded-scheme"] || headers["x-forwarded-host"]);
+}
+//#endregion
+export { forwardedNodeIp, hasForwardingHeaders, parseForwarded, resolveForwarded };