@nodefony/http 10.0.0-beta.1 → 10.0.0-beta.3

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

@@ -0,0 +1,476 @@
+import http from "node:http";
+import https from "node:https";
+//#region nodefony/src/proxy/forward.ts
+/**
+* En-têtes de CONNEXION (RFC 9110 §7.6.1) : ils décrivent un saut, jamais le
+* message — un intermédiaire ne les transmet pas. Les cinq premiers sont en
+* outre INTERDITS en HTTP/2 (RFC 9113 §8.2.2) : Node lève
+* `ERR_HTTP2_INVALID_CONNECTION_HEADERS` si une réponse les porte.
+*/
+const HOP_BY_HOP = /* @__PURE__ */ new Set([
+	"connection",
+	"keep-alive",
+	"proxy-connection",
+	"transfer-encoding",
+	"upgrade",
+	"te",
+	"trailer",
+	"proxy-authorization",
+	"proxy-authenticate"
+]);
+/**
+* En-têtes qui décrivent la chaîne de relais. Crus d'un relais de confiance,
+* écartés sinon : un client direct qui les pose ment sur son origine.
+*/
+const FORWARDING = /* @__PURE__ */ new Set([
+	"forwarded",
+	"x-forwarded-for",
+	"x-forwarded-proto",
+	"x-forwarded-host",
+	"x-forwarded-port",
+	"x-forwarded-prefix",
+	"x-forwarded-scheme",
+	"x-real-ip"
+]);
+/** Corps d'erreur du proxy — courts, sans détail interne. */
+const BAD_GATEWAY = "Bad Gateway";
+const GATEWAY_TIMEOUT = "Gateway Timeout";
+const LOOP_DETECTED = "Loop Detected";
+const NOT_IMPLEMENTED = "Not Implemented";
+/**
+* Sauts `Via` au-delà desquels un message est tenu pour une boucle. Notre
+* pseudonyme ne repère une boucle qu'au RETOUR dans ce processus : derrière un
+* répartiteur qui tourne sur N instances, cela peut prendre N+1 sauts, chacun
+* tenant une connexion. Une chaîne légitime (CDN, répartiteur, ingress) en
+* compte rarement plus de cinq.
+*/
+const MAX_VIA_HOPS = 10;
+/**
+* Noms listés par l'en-tête `Connection` d'un message : eux aussi ne valent
+* que pour ce saut (RFC 9110 §7.6.1).
+*
+* @param value - valeur brute de `Connection`
+* @returns noms en minuscules, ou `null` s'il n'y en a aucun
+*/
+function connectionTokens(value) {
+	if (value === void 0) return null;
+	const raw = Array.isArray(value) ? value.join(",") : value;
+	let tokens = null;
+	for (const t of raw.split(",")) {
+		const name = t.trim().toLowerCase();
+		if (name === "") continue;
+		(tokens ??= /* @__PURE__ */ new Set()).add(name);
+	}
+	return tokens;
+}
+/** Valeur d'en-tête aplatie (`a, b` pour un tableau). */
+function flat(value) {
+	return Array.isArray(value) ? value.join(", ") : value;
+}
+/**
+* Le message est-il déjà passé par CE processus ? Un `Via` qui porte notre
+* pseudonyme signe une boucle (RFC 9110 §7.6 : un proxy ne se renvoie pas un
+* message sans s'en protéger).
+*
+* @param via - en-tête `Via` reçu
+* @param pseudonym - pseudonyme de ce processus
+*/
+function viaLoops(via, pseudonym) {
+	const value = flat(via);
+	if (value === void 0) return false;
+	const hops = value.split(",");
+	if (hops.length >= 10) return true;
+	for (const hop of hops) if (hop.trim().split(/\s+/)[1] === pseudonym) return true;
+	return false;
+}
+/** Entrée `Via` de ce saut : `<version> <pseudonyme>` (RFC 9110 §7.6.3). */
+function viaEntry(httpVersion, pseudonym) {
+	return `${httpVersion.startsWith("2") ? "2" : httpVersion || "1.1"} ${pseudonym}`;
+}
+/**
+* Cadrage du corps reçu — décidé UNE fois, pour que l'amont lise exactement
+* les octets que le proxy lui envoie (RFC 9112 §6.3). Un `Transfer-Encoding`
+* l'emporte sur un `Content-Length` (que l'on retire alors) ; en HTTP/2, un
+* flux sans fin à la tête porte un corps même sans longueur annoncée.
+*
+* @param req - requête reçue
+* @returns le cadrage à appliquer vers l'amont
+*/
+function bodyFramingOf(req) {
+	const coding = req.headers["transfer-encoding"];
+	if (coding !== void 0) {
+		if (coding === "chunked") return "chunked";
+		return coding.trim().toLowerCase() === "chunked" ? "chunked" : "unsupported";
+	}
+	if (req.headers["content-length"] !== void 0) return "length";
+	const stream = req.stream;
+	if (stream !== void 0 && !stream.endAfterHeaders) return "chunked";
+	return "none";
+}
+/**
+* En-têtes de la requête à transmettre à l'amont.
+*
+* - écartés : pseudo-en-têtes HTTP/2, en-têtes de connexion et ceux que nomme
+*   `Connection`, `Expect` (le serveur a déjà répondu `100`), en-têtes retirés
+*   par le montage, chaîne de relais venue d'un pair NON fiable ;
+* - `Host` réécrit sur la cible (sauf `preserveHost`) ;
+* - `X-Forwarded-For` prolongé (pair fiable) ou recommencé ;
+*   `X-Forwarded-Proto`/`-Host` hérités d'un pair fiable, posés sinon ;
+*   `X-Forwarded-Prefix` quand le préfixe est retiré — à la suite de celui
+*   d'un pair fiable ; `Forwarded` d'un pair fiable prolongé de ce saut ;
+* - `Via` prolongé de ce saut ;
+* - cadrage du corps rendu cohérent ({@link bodyFramingOf}).
+*
+* @returns un objet neuf, prêt pour `http.request`
+*/
+function requestHeadersFor(headers, mount, target, from, pseudonym, framing) {
+	const listed = connectionTokens(headers.connection);
+	const stripped = mount.stripHeaders;
+	const out = {};
+	for (const name of Object.keys(headers)) {
+		const lower = name.toLowerCase();
+		if (lower.charCodeAt(0) === 58) continue;
+		if (HOP_BY_HOP.has(lower) || listed?.has(lower)) continue;
+		if (lower === "host" || lower === "expect" || lower === "via") continue;
+		if (lower === "content-length" && framing !== "length") continue;
+		if (FORWARDING.has(lower) && !from.trustedPeer) continue;
+		if (stripped?.includes(lower)) continue;
+		const value = headers[name];
+		if (value !== void 0) out[lower] = value;
+	}
+	out.host = mount.preserveHost === true && from.host ? from.host : target.host;
+	const prior = from.trustedPeer ? flat(headers["x-forwarded-for"]) : void 0;
+	if (from.remoteAddress) out["x-forwarded-for"] = prior ? `${prior}, ${from.remoteAddress}` : from.remoteAddress;
+	out["x-forwarded-proto"] ??= from.scheme;
+	if (from.host) out["x-forwarded-host"] ??= from.host;
+	if (mount.stripPrefix === true) {
+		let outer = from.trustedPeer ? flat(headers["x-forwarded-prefix"]) : void 0;
+		if (outer?.endsWith("/")) outer = outer.slice(0, -1);
+		out["x-forwarded-prefix"] = (outer ?? "") + mount.prefix.slice(0, -1);
+	}
+	const forwarded = from.trustedPeer ? flat(headers.forwarded) : void 0;
+	if (forwarded) out.forwarded = `${forwarded}, ${forwardedElement(from)}`;
+	const via = flat(headers.via);
+	const hop = viaEntry(from.httpVersion, pseudonym);
+	out.via = via ? `${via}, ${hop}` : hop;
+	if (framing === "chunked") out["transfer-encoding"] = "chunked";
+	return out;
+}
+/** Caractères d'un `token` (RFC 9110 §5.6.2) — compilé une fois. */
+const TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+/** Valeur d'un paramètre `Forwarded` : jeton nu, sinon chaîne entre guillemets (RFC 7239 §4). */
+function forwardedValue(value) {
+	return TOKEN.test(value) ? value : `"${value.replace(/["\\]/g, "\\$&")}"`;
+}
+/**
+* Élément `Forwarded` de ce saut : `for=` (une IPv6 entre crochets et
+* guillemets, RFC 7239 §6), `proto=`, `host=`.
+*/
+function forwardedElement(from) {
+	const address = from.remoteAddress;
+	let element = `for=${forwardedValue(address === void 0 ? "unknown" : address.includes(":") ? `[${address}]` : address)};proto=${forwardedValue(from.scheme)}`;
+	if (from.host) element += `;host=${forwardedValue(from.host)}`;
+	return element;
+}
+/**
+* Ramène sous le préfixe un `Location` émis par un amont qui ignore son
+* montage (`stripPrefix`) — l'équivalent de `proxy_redirect default` de
+* nginx. Un chemin absolu (`/login`) et une URL sur l'origine de l'amont sont
+* réécrits ; toute autre URL (un tiers) part intacte.
+*
+* @returns la valeur réécrite, ou celle reçue
+*/
+function rewriteLocation(location, mount, target) {
+	if (mount.stripPrefix !== true) return location;
+	if (location.startsWith("/") && !location.startsWith("//")) return mount.prefix + location.slice(1);
+	if (location.startsWith(target.origin + "/") || location === target.origin) return mount.prefix + location.slice(target.origin.length + 1);
+	return location;
+}
+/**
+* En-têtes de la réponse de l'amont à renvoyer au client : en-têtes de
+* connexion écartés — y compris ceux que nomme `Connection` —, `Via`
+* prolongé, `Location` ramené sous le préfixe (`stripPrefix`) ; le reste
+* intact (un `set-cookie` multiple reste un tableau).
+*
+* @returns un objet neuf, valable en HTTP/1.1 comme en HTTP/2
+*/
+function responseHeadersFor(headers, mount, target, hop) {
+	const listed = connectionTokens(headers.connection);
+	const out = {};
+	for (const name of Object.keys(headers)) {
+		if (HOP_BY_HOP.has(name) || listed?.has(name)) continue;
+		const value = headers[name];
+		if (value !== void 0) out[name] = value;
+	}
+	const via = flat(headers.via);
+	out.via = via ? `${via}, ${hop}` : hop;
+	if (typeof out.location === "string") out.location = rewriteLocation(out.location, mount, target);
+	return out;
+}
+/**
+* Chemin transmis à l'amont : tel quel, ou sans le préfixe (`stripPrefix`).
+*
+* @param url - cible de la requête (chemin + requête), qui commence par le préfixe
+* @param mount - montage qui relaie
+* @returns le chemin, toujours avec un `/` en tête
+*/
+function upstreamPath(url, mount) {
+	if (mount.stripPrefix !== true) return url;
+	return `/${url.slice(mount.prefix.length)}`;
+}
+/**
+* Options de `http.request` communes aux deux relais : cible, pool, TLS.
+* La vérification du certificat suit `secure` (refusé hors boucle locale
+* au montage).
+*/
+function requestOptions(target, mount, relay) {
+	const options = {
+		protocol: target.protocol,
+		hostname: target.hostname,
+		port: target.port
+	};
+	if (relay.agent !== void 0) options.agent = relay.agent;
+	if (target.protocol === "https:") options.rejectUnauthorized = mount.secure !== false;
+	return options;
+}
+/** Module client selon le scheme de la cible. */
+function requestFn(target) {
+	return target.protocol === "https:" ? https.request : http.request;
+}
+/**
+* Arme le délai d'ÉTABLISSEMENT de la connexion amont — distinct du délai
+* d'inactivité : un amont qui n'accepte pas la connexion ne doit pas tenir le
+* client pendant tout `timeoutMs`. Un socket réutilisé (pool) est déjà
+* connecté : rien à armer.
+*
+* @param upstream - requête vers l'amont
+* @param ms - délai
+* @param onTimeout - appelé si la connexion n'est pas établie à temps
+*/
+function armConnectTimeout(upstream, ms, onTimeout) {
+	upstream.once("socket", (socket) => {
+		if (!socket.connecting) return;
+		const timer = setTimeout(onTimeout, ms);
+		const clear = () => {
+			clearTimeout(timer);
+			socket.removeListener("connect", clear);
+			socket.removeListener("close", clear);
+		};
+		socket.once("connect", clear);
+		socket.once("close", clear);
+	});
+}
+/**
+* Relaie une requête HTTP vers l'amont et renvoie sa réponse au client.
+*
+* Le corps est transmis avec un cadrage cohérent ({@link bodyFramingOf}). Un
+* message qui porte déjà notre `Via` rend 508 sans contacter l'amont. Un
+* client parti coupe l'échange amont ; un amont injoignable rend 502 ; une
+* connexion non établie à temps ou un amont muet rendent 504 — à condition
+* que rien n'ait encore été envoyé, sinon la réponse est interrompue (un
+* statut ne se rattrape pas). Un amont coupé en plein corps interrompt la
+* réponse au client au lieu de la laisser pendre.
+*
+* @returns une promesse résolue à la fermeture de la réponse — jamais rejetée
+*/
+function forwardRequest(req, res, mount, target, from, relay) {
+	return new Promise((resolve) => {
+		const out = res;
+		let closed = false;
+		let failed = false;
+		const fail = (status, body) => {
+			if (failed || closed) return;
+			failed = true;
+			if (out.headersSent) {
+				out.destroy();
+				return;
+			}
+			out.writeHead(status, {
+				"content-type": "text/plain; charset=utf-8",
+				"content-length": Buffer.byteLength(body),
+				"cache-control": "no-store"
+			});
+			out.end(body);
+		};
+		let upstream = null;
+		out.once("close", () => {
+			closed = true;
+			if (!out.writableFinished) upstream?.destroy();
+			resolve();
+		});
+		if (viaLoops(req.headers.via, relay.pseudonym)) {
+			fail(508, LOOP_DETECTED);
+			return;
+		}
+		const framing = bodyFramingOf(req);
+		if (framing === "unsupported") {
+			fail(501, NOT_IMPLEMENTED);
+			return;
+		}
+		const options = requestOptions(target, mount, relay);
+		options.method = req.method ?? "GET";
+		options.path = upstreamPath(req.url ?? "/", mount);
+		options.headers = requestHeadersFor(req.headers, mount, target, from, relay.pseudonym, framing);
+		if (mount.timeoutMs !== void 0) options.timeout = mount.timeoutMs;
+		const request = requestFn(target)(options);
+		upstream = request;
+		let timedOut = false;
+		const giveUp = () => {
+			timedOut = true;
+			fail(504, GATEWAY_TIMEOUT);
+			request.destroy();
+		};
+		armConnectTimeout(request, relay.connectTimeoutMs, giveUp);
+		request.on("timeout", giveUp);
+		request.on("error", () => {
+			if (!timedOut) fail(502, BAD_GATEWAY);
+		});
+		const hop = viaEntry(from.httpVersion, relay.pseudonym);
+		request.on("response", (answer) => {
+			if (closed || failed) {
+				answer.resume();
+				return;
+			}
+			try {
+				out.writeHead(answer.statusCode ?? 502, responseHeadersFor(answer.headers, mount, target, hop));
+			} catch {
+				answer.resume();
+				fail(502, BAD_GATEWAY);
+				return;
+			}
+			answer.once("close", () => {
+				if (!answer.complete) out.destroy();
+			});
+			answer.pipe(out);
+		});
+		if (framing === "none") {
+			request.end();
+			return;
+		}
+		const body = req;
+		const onClientError = () => {
+			request.destroy();
+		};
+		body.once("error", onClientError);
+		request.once("close", () => {
+			body.removeListener("error", onClientError);
+			body.unpipe(request);
+			if (!body.readableEnded) body.resume();
+		});
+		body.pipe(request);
+	});
+}
+/**
+* Sérialise une tête de réponse HTTP/1.1 depuis des en-têtes BRUTS (paires
+* nom/valeur), sans réordonner ni fusionner, en écartant les noms donnés —
+* une réponse `101` doit rendre au client exactement ce que l'amont a négocié.
+*
+* @param status - ligne de statut, sans CRLF
+* @param rawHeaders - `IncomingMessage.rawHeaders`
+* @param skip - noms à écarter (minuscules)
+* @param extra - lignes ajoutées à la fin (`Nom: valeur`)
+* @returns la tête complète, CRLF final compris
+*/
+function rawHead(status, rawHeaders, skip = null, extra = []) {
+	let head = `${status}\r\n`;
+	for (let i = 0; i + 1 < rawHeaders.length; i += 2) {
+		const name = rawHeaders[i] ?? "";
+		if (skip?.has(name.toLowerCase())) continue;
+		head += `${name}: ${rawHeaders[i + 1]}\r\n`;
+	}
+	for (const line of extra) head += `${line}\r\n`;
+	return `${head}\r\n`;
+}
+/** Réponse brute minimale sur un socket d'upgrade, puis fermeture. */
+function refuseUpgrade(socket, status, reason) {
+	if (!socket.writable) {
+		socket.destroy();
+		return;
+	}
+	socket.end(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+}
+/** En-têtes d'une réponse d'amont REFUSANT l'upgrade, à ne pas recopier tels quels. */
+const REFUSAL_SKIP = /* @__PURE__ */ new Set([
+	"transfer-encoding",
+	"content-length",
+	"connection",
+	"keep-alive"
+]);
+/**
+* Relaie un upgrade WebSocket DÉJÀ validé (méthode, `Upgrade`, clé, version,
+* `Origin` — cf `ReverseProxy.handleUpgrade`) : rejoue le handshake vers
+* l'amont, renvoie sa réponse `101` au client puis raccorde les deux sockets
+* octet pour octet. Un refus de l'amont (`400`, `403`…) est rendu avec un
+* cadrage refait (fin de corps = fermeture) ; un amont injoignable rend `502`,
+* une connexion non établie à temps — ou un amont qui accepte puis se tait
+* au-delà de `timeoutMs` — `504`, une boucle `508`. Le délai d'inactivité
+* cesse au `101` : un tunnel établi peut rester muet. Une erreur d'un côté
+* détruit l'autre.
+*/
+function forwardUpgrade(req, socket, head, mount, target, from, relay) {
+	if (viaLoops(req.headers.via, relay.pseudonym)) {
+		refuseUpgrade(socket, 508, LOOP_DETECTED);
+		return;
+	}
+	const options = requestOptions(target, mount, relay);
+	options.agent = false;
+	options.method = "GET";
+	options.path = upstreamPath(req.url ?? "/", mount);
+	const headers = requestHeadersFor(req.headers, mount, target, from, relay.pseudonym, "none");
+	headers.connection = "Upgrade";
+	headers.upgrade = "websocket";
+	options.headers = headers;
+	if (mount.timeoutMs !== void 0) options.timeout = mount.timeoutMs;
+	if (head.length > 0) socket.unshift(head);
+	const upstream = requestFn(target)(options);
+	let state = "pending";
+	const onClientError = () => {
+		upstream.destroy();
+	};
+	socket.once("error", onClientError);
+	armConnectTimeout(upstream, relay.connectTimeoutMs, () => {
+		state = "refused";
+		refuseUpgrade(socket, 504, GATEWAY_TIMEOUT);
+		upstream.destroy();
+	});
+	upstream.on("timeout", () => {
+		if (state === "open") return;
+		if (state === "pending") refuseUpgrade(socket, 504, GATEWAY_TIMEOUT);
+		else socket.destroy();
+		state = "refused";
+		upstream.destroy();
+	});
+	upstream.on("upgrade", (answer, upSocket, upHead) => {
+		state = "open";
+		upSocket.setTimeout(0);
+		socket.removeListener("error", onClientError);
+		const destroyBoth = () => {
+			socket.destroy();
+			upSocket.destroy();
+		};
+		socket.on("error", destroyBoth);
+		upSocket.on("error", destroyBoth);
+		upSocket.setKeepAlive(true);
+		socket.setKeepAlive(true);
+		if (upHead.length > 0) upSocket.unshift(upHead);
+		socket.write(rawHead(`HTTP/1.1 101 ${answer.statusMessage ?? "Switching Protocols"}`, answer.rawHeaders));
+		upSocket.pipe(socket).pipe(upSocket);
+	});
+	upstream.on("response", (answer) => {
+		state = "refused";
+		socket.write(rawHead(`HTTP/1.1 ${answer.statusCode ?? 502} ${answer.statusMessage ?? ""}`, answer.rawHeaders, REFUSAL_SKIP, ["Connection: close"]));
+		answer.pipe(socket);
+	});
+	upstream.on("error", () => {
+		if (state === "refused") return;
+		if (state === "open") {
+			socket.destroy();
+			return;
+		}
+		state = "refused";
+		refuseUpgrade(socket, 502, BAD_GATEWAY);
+	});
+	upstream.end();
+}
+//#endregion
+export { MAX_VIA_HOPS, bodyFramingOf, forwardRequest, forwardUpgrade, rawHead, refuseUpgrade, requestHeadersFor, responseHeadersFor, rewriteLocation, upstreamPath, viaLoops };

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

@@ -0,0 +1,182 @@
+import { isLoopbackHostname } from "nodefony";
+//#region nodefony/src/proxy/rules.ts
+/**
+* Règles d'un montage du proxy inverse — UNIQUE source, lue par le schéma de
+* configuration (`proxy.mounts`) ET par `ReverseProxy.mount()` : un montage
+* écrit dans la config et un montage posé par un module obéissent aux mêmes
+* refus, avec les mêmes mots.
+*
+* Pur : n'importe que le cœur, importable depuis `config/config.ts` sans
+* cycle.
+*/
+/**
+* Préfixes que le framework se réserve : un montage n'y est JAMAIS accepté.
+* `/nodefony/` porte la console d'administration et les API de Studio — les
+* relayer ailleurs détournerait une surface protégée par le pare-feu.
+*/
+const RESERVED_PROXY_PREFIXES = ["/nodefony/"];
+/**
+* Préfixes réservés aux montages POSÉS PAR UN MODULE : la configuration ne
+* peut pas les prendre. `/_vite/` appartient à `@nodefony/frontend`, qui y
+* relaie ses serveurs Vite de développement.
+*/
+const MODULE_PROXY_PREFIXES = ["/_vite/"];
+/** Jeton de méthode HTTP (RFC 9110 §9.1 → `token`, §5.6.2). */
+const METHOD_TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+/** Nom de champ d'en-tête (RFC 9110 §5.1 → `token`). */
+const HEADER_TOKEN = METHOD_TOKEN;
+/**
+* Normalise un préfixe d'URL : `/` en tête et en fin, sans `/` doublé. Règle
+* UNIQUE des montages statiques et du proxy inverse — deux écritures du même
+* préfixe doivent désigner la même entrée.
+*
+* @param prefix - préfixe tel qu'écrit (`"svc"`, `"/svc"`, `"/svc/"`)
+* @returns le préfixe normalisé (`"/svc/"`)
+*/
+function normalizePrefix(prefix) {
+	let p = prefix.trim();
+	if (!p.startsWith("/")) p = `/${p}`;
+	if (!p.endsWith("/")) p = `${p}/`;
+	return p.replace(/\/{2,}/g, "/");
+}
+/**
+* Analyse une origine d'amont. Seule une origine NUE est acceptée : un chemin,
+* une requête, un fragment ou des identifiants dans la cible déplaceraient en
+* silence toutes les URL relayées, ou feraient voyager un secret dans la
+* configuration.
+*
+* @param origin - `scheme://hôte[:port]`
+* @returns l'URL analysée, ou `null` si ce n'est pas une origine http(s) nue
+*/
+function parseProxyOrigin(origin) {
+	let url;
+	try {
+		url = new URL(origin);
+	} catch {
+		return null;
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+	if (!/^https?:\/\/[^/?#]+\/?$/i.test(origin.trim())) return null;
+	if (url.search !== "" || url.hash !== "") return null;
+	if (url.username !== "" || url.password !== "") return null;
+	return url;
+}
+/**
+* Examine un montage. Rend TOUS les refus, pas le premier : une configuration
+* se corrige en une passe.
+*
+* @param prefix - préfixe tel qu'écrit
+* @param mount - réglages du montage
+* @param source - `"config"` (déclaré dans `proxy.mounts`) ou `"module"`
+*   (posé par un module) — seuls les préfixes réservés aux modules diffèrent
+* @returns la liste des refus, vide si le montage est sain
+*/
+function proxyMountProblems(prefix, mount, source) {
+	const problems = [];
+	const raw = prefix.trim();
+	const p = normalizePrefix(raw);
+	if (p === "/") problems.push({
+		field: "prefix",
+		message: "le préfixe « / » relaierait TOUTE l'application, routes et pare-feu compris — monter un préfixe dédié (`/svc/`)"
+	});
+	else if (/[?#\s\\%]/.test(raw) || p.split("/").some((s) => s === "." || s === "..")) problems.push({
+		field: "prefix",
+		message: `préfixe « ${raw} » invalide — un chemin littéral, sans « ? », « # », « % », « \\ », espace ni segment « . » / « .. »`
+	});
+	else if (RESERVED_PROXY_PREFIXES.some((r) => p.startsWith(r))) problems.push({
+		field: "prefix",
+		message: `le préfixe « ${p} » est réservé au framework (console d'administration)`
+	});
+	else if (source === "config" && MODULE_PROXY_PREFIXES.some((r) => p.startsWith(r))) problems.push({
+		field: "prefix",
+		message: `le préfixe « ${p} » est réservé à @nodefony/frontend (serveurs Vite de développement), qui le monte lui-même`
+	});
+	let target = null;
+	if (typeof mount.target === "string") {
+		target = parseProxyOrigin(mount.target);
+		if (target === null) problems.push({
+			field: "target",
+			message: `cible « ${mount.target} » invalide — attendu une origine http(s) nue (\`scheme://hôte[:port]\`), sans chemin, requête ni identifiants`
+		});
+	} else if (typeof mount.target !== "function") problems.push({
+		field: "target",
+		message: "cible absente — une origine `scheme://hôte[:port]`"
+	});
+	if (mount.secure === false && target !== null) {
+		if (target.protocol !== "https:") problems.push({
+			field: "secure",
+			message: "`secure: false` ne concerne qu'une cible https: — le retirer"
+		});
+		else if (!isLoopbackHostname(target.hostname)) problems.push({
+			field: "secure",
+			message: `\`secure: false\` refusé vers « ${target.hostname} » : sans vérification de certificat, n'importe qui sur le chemin réseau se fait passer pour l'amont. Réservé à la boucle locale — sinon, fournir l'autorité de certification de l'amont au processus (\`http.certificates.extraCaFiles\`, ou NODE_EXTRA_CA_CERTS)`
+		});
+	}
+	if (mount.methods !== void 0) {
+		if (mount.methods.length === 0) problems.push({
+			field: "methods",
+			message: "liste de méthodes vide : rien ne serait relayé — retirer `methods` pour toutes"
+		});
+		for (const m of mount.methods) if (!METHOD_TOKEN.test(m)) problems.push({
+			field: "methods",
+			message: `méthode « ${m} » invalide (RFC 9110 §9.1)`
+		});
+	}
+	for (const h of mount.stripHeaders ?? []) if (!HEADER_TOKEN.test(h)) problems.push({
+		field: "stripHeaders",
+		message: `nom d'en-tête « ${h} » invalide`
+	});
+	else if (h.toLowerCase() === "host") problems.push({
+		field: "stripHeaders",
+		message: "« host » ne se retire pas : il est toujours posé — voir `preserveHost`"
+	});
+	if (mount.timeoutMs !== void 0 && (!Number.isInteger(mount.timeoutMs) || mount.timeoutMs <= 0)) problems.push({
+		field: "timeoutMs",
+		message: `délai « ${mount.timeoutMs} » invalide — un entier de millisecondes > 0`
+	});
+	return problems;
+}
+/** Encodages qui changent le SENS d'un chemin selon qui le décode. */
+const AMBIGUOUS_ENCODING = /%(?:2e|2f|5c|00|25)/i;
+/**
+* Le chemin d'une requête relayée est-il ambigu ? Un chemin que le proxy et
+* l'amont pourraient lire différemment — segment `.`/`..`, barre inverse,
+* octet nul, ou leur forme encodée (`%2e`, `%2f`, `%5c`, `%00`, `%25`) — est
+* REFUSÉ (400), jamais normalisé en silence : c'est le défaut de Traefik, et
+* la parade aux contournements de préfixe (`/svc/..%2fadmin`).
+*
+* @param url - cible brute de la requête (chemin + requête éventuelle)
+* @returns `true` si le chemin doit être refusé
+*/
+function isAmbiguousPath(url) {
+	const q = url.indexOf("?");
+	const path = q === -1 ? url : url.slice(0, q);
+	if (path.includes("\\") || path.includes("\0")) return true;
+	if (AMBIGUOUS_ENCODING.test(path)) return true;
+	for (const segment of path.split("/")) if (segment === "." || segment === "..") return true;
+	return false;
+}
+/** Clé de handshake : 16 octets en base64 (RFC 6455 §4.1, §4.2.1). */
+const WS_KEY = /^[A-Za-z0-9+/]{22}==$/;
+/**
+* Un upgrade est-il un handshake WebSocket conforme (RFC 6455 §4.2.1) ? Seul
+* un tel handshake est relayé : un `Upgrade` quelconque (`h2c`…) raccordé
+* octet pour octet ouvrirait un tunnel que rien n'inspecte.
+*
+* @param method - méthode de la requête
+* @param headers - en-têtes reçus
+* @returns la raison du refus, ou `null` si le handshake est conforme
+*/
+function websocketHandshakeProblem(method, headers) {
+	if (method !== "GET") return "méthode autre que GET";
+	const upgrade = headers.upgrade;
+	if (typeof upgrade !== "string" || upgrade.trim().toLowerCase() !== "websocket") return "Upgrade autre que websocket";
+	const connection = headers.connection;
+	if (!(Array.isArray(connection) ? connection.join(",") : connection ?? "").toLowerCase().split(",").map((t) => t.trim()).includes("upgrade")) return "Connection sans upgrade";
+	if (headers["sec-websocket-version"] !== "13") return "Sec-WebSocket-Version ≠ 13";
+	const key = headers["sec-websocket-key"];
+	if (typeof key !== "string" || !WS_KEY.test(key.trim())) return "Sec-WebSocket-Key invalide";
+	return null;
+}
+//#endregion
+export { MODULE_PROXY_PREFIXES, RESERVED_PROXY_PREFIXES, isAmbiguousPath, normalizePrefix, parseProxyOrigin, proxyMountProblems, websocketHandshakeProblem };