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

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

@@ -0,0 +1,156 @@
+import http from "node:http";
+import type http2 from "node:http2";
+import type { Duplex } from "node:stream";
+import type { IProxyMount } from "../../interfaces/IReverseProxy.js";
+/** Requête entrante relayable : HTTP/1.1 ou HTTP/2 (API de compatibilité). */
+export type ProxiedRequest = http.IncomingMessage | http2.Http2ServerRequest;
+/** Réponse vers le client : HTTP/1.1 ou HTTP/2 (API de compatibilité). */
+export type ProxiedResponse = http.ServerResponse | http2.Http2ServerResponse;
+/**
+ * Ce que le proxy sait du client, et qu'il annonce à l'amont
+ * (`X-Forwarded-*`, `Via`).
+ */
+export interface IForwardedFrom {
+    /** Adresse du pair TCP immédiat — ajoutée à la chaîne `X-Forwarded-For`. */
+    remoteAddress: string | undefined;
+    /** Scheme par lequel le pair est arrivé (`http` | `https`). */
+    scheme: string;
+    /** Autorité demandée (`Host` ou `:authority`). */
+    host: string | undefined;
+    /**
+     * Le pair est-il un relais de confiance (`trustProxy`) ? Seul un tel pair
+     * peut faire passer des `Forwarded`/`X-Forwarded-*`/`X-Real-IP` : venus
+     * d'ailleurs, ils sont forgeables (RFC 7239 §8.1) et sont écartés.
+     */
+    trustedPeer: boolean;
+    /** Version du message reçu, pour `Via` (`"1.1"`, `"2.0"`). */
+    httpVersion: string;
+}
+/** Réglages du relais, fixés par le service (identiques pour tous les montages). */
+export interface IRelaySettings {
+    /** Pseudonyme de CE processus dans `Via` (RFC 9110 §7.6.3) — base de la garde de boucle. */
+    pseudonym: string;
+    /** Délai d'établissement de la connexion amont (ms). Dépassé : 504. */
+    connectTimeoutMs: number;
+    /**
+     * Pool de connexions du montage (keep-alive borné) ; `false` = connexion à
+     * usage unique (arrêt engagé : plus de pool à créer).
+     */
+    agent: http.Agent | false | undefined;
+}
+/**
+ * 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.
+ */
+export declare const MAX_VIA_HOPS = 10;
+/**
+ * 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
+ */
+export declare function viaLoops(via: string | string[] | undefined, pseudonym: string): boolean;
+/**
+ * Cadrage du corps transmis à l'amont (RFC 9112 §6). `unsupported` : un
+ * codage de transfert autre que `chunked` seul — le proxy ne sait pas le
+ * transmettre fidèlement.
+ */
+export type BodyFraming = "none" | "length" | "chunked" | "unsupported";
+/**
+ * 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
+ */
+export declare function bodyFramingOf(req: ProxiedRequest): BodyFraming;
+/**
+ * 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`
+ */
+export declare function requestHeadersFor(headers: http.IncomingHttpHeaders, mount: IProxyMount, target: URL, from: IForwardedFrom, pseudonym: string, framing: BodyFraming): http.OutgoingHttpHeaders;
+/**
+ * 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
+ */
+export declare function rewriteLocation(location: string, mount: IProxyMount, target: URL): string;
+/**
+ * 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
+ */
+export declare function responseHeadersFor(headers: http.IncomingHttpHeaders, mount: IProxyMount, target: URL, hop: string): http.OutgoingHttpHeaders;
+/**
+ * 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
+ */
+export declare function upstreamPath(url: string, mount: IProxyMount): string;
+/**
+ * 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
+ */
+export declare function forwardRequest(req: ProxiedRequest, res: ProxiedResponse, mount: IProxyMount, target: URL, from: IForwardedFrom, relay: IRelaySettings): Promise<void>;
+/**
+ * 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
+ */
+export declare function rawHead(status: string, rawHeaders: readonly string[], skip?: ReadonlySet<string> | null, extra?: readonly string[]): string;
+/** Réponse brute minimale sur un socket d'upgrade, puis fermeture. */
+export declare function refuseUpgrade(socket: Duplex, status: number, reason: string): void;
+/**
+ * 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.
+ */
+export declare function forwardUpgrade(req: http.IncomingMessage, socket: Duplex, head: Buffer, mount: IProxyMount, target: URL, from: IForwardedFrom, relay: IRelaySettings): void;

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

@@ -0,0 +1,85 @@
+/**
+ * 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.
+ */
+export declare const RESERVED_PROXY_PREFIXES: readonly string[];
+/**
+ * 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.
+ */
+export declare const MODULE_PROXY_PREFIXES: readonly string[];
+/**
+ * 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/"`)
+ */
+export declare function normalizePrefix(prefix: string): string;
+/**
+ * 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
+ */
+export declare function parseProxyOrigin(origin: string): URL | null;
+/** Ce qu'une règle de montage examine — la forme commune config / code. */
+export interface IProxyMountShape {
+    target: unknown;
+    methods?: readonly string[] | undefined;
+    stripHeaders?: readonly string[] | undefined;
+    timeoutMs?: number | undefined;
+    secure?: boolean | undefined;
+}
+/** Un refus, nommé : le champ fautif et pourquoi. */
+export interface IProxyMountProblem {
+    field: "prefix" | "target" | "methods" | "stripHeaders" | "timeoutMs" | "secure";
+    message: string;
+}
+/**
+ * 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
+ */
+export declare function proxyMountProblems(prefix: string, mount: IProxyMountShape, source: "config" | "module"): IProxyMountProblem[];
+/**
+ * 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é
+ */
+export declare function isAmbiguousPath(url: string): boolean;
+/**
+ * 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
+ */
+export declare function websocketHandshakeProblem(method: string | undefined, headers: Record<string, string | string[] | undefined>): string | null;

package/dist/types/nodefony/src/servers/portBinder.d.ts

@@ -1,48 +1,3 @@
-/**
- * **portBinder** — écoute sur le port désiré, ou sur le prochain port libre.
- *
- * Pourquoi ce fichier existe : lancer deux apps Nodefony côte à côte (le repo et
- * une app générée, deux projets, un banc et une démo…) faisait mourir la seconde
- * en `EADDRINUSE`. Le port désiré est une PRÉFÉRENCE en développement ; il reste
- * un CONTRAT en production.
- *
- * ## Pourquoi retenter au `listen()` plutôt que sonder d'abord
- *
- * La tentation est d'appeler « le port 5151 est-il libre ? » puis de binder. C'est
- * une **course** (TOCTOU) : entre la réponse et le bind, un autre process peut
- * prendre le port — et on échoue quand même, après avoir cru le contraire. Le
- * `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
- * voler 5152 à HTTPS — qui se décalerait à son tour, en cascade. Les ports que les
- * AUTRES serveurs convoitent sont donc sautés d'emblée.
- *
- * ## Fail-loud
- *
- * Un décalage est TOUJOURS annoncé (`onShift`) : une app qui écoute ailleurs que
- * là où on l'attend sans le dire est une dégradation silencieuse.
- */
 import type { AddressInfo } from "node:net";
 import { resolvePortPolicy } from "nodefony";
 import type { PortPolicy } from "nodefony";
@@ -138,9 +93,18 @@ export declare function detectPortConflict(port: number, host: string | undefine
  * handler d'erreur durable s'installe APRÈS, sur le serveur qui écoute — sinon il
  * verrait passer les `EADDRINUSE` de repli et croirait à une panne).
  *
+ * @param server - serveur à mettre en écoute.
+ * @param host - hôte passé à `listen`.
+ * @param plan - port désiré et nombre de replis permis.
+ * @param probe - sonde de présence (injectée par le banc).
+ * @param sharedListener - vrai dans un worker `node:cluster` : le port y est
+ *   PARTAGÉ par le maître, et un voisin qui y répond est un frère, pas un
+ *   conflit. Sans cette exception, `nodefony cluster -w N` ne gardait qu'un
+ *   worker en vie — les autres mouraient sur « port déjà servi » et
+ *   bouclaient en relance.
  * @returns l'adresse obtenue + le port désiré si un décalage a eu lieu.
  * @throws l'erreur de `listen` : soit un code qui ne dit pas « ce port est pris »
  *   (`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, probe?: PortListeningProbe): Promise<BindResult>;
+export declare function bindWithFallback(server: Listenable, host: string, plan: BindPlan, probe?: PortListeningProbe, sharedListener?: boolean): Promise<BindResult>;

package/dist/types/nodefony/src/servers/upgradeDispatch.d.ts

@@ -0,0 +1,39 @@
+import { type IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+import type { WebSocketServer } from "ws";
+/** Serveur qui émet `upgrade` : HTTP/1.1, HTTPS ou HTTP/2 sécurisé (`allowHTTP1`). */
+interface IUpgradeEmitter {
+    on(event: "upgrade", listener: (req: IncomingMessage, socket: Duplex, head: Buffer) => void): unknown;
+    removeListener(event: "upgrade", listener: (req: IncomingMessage, socket: Duplex, head: Buffer) => void): unknown;
+}
+/** Ce que le répartiteur lit du proxy inverse (cf `ReverseProxy`). */
+interface IUpgradeRelay {
+    readonly mounts: readonly unknown[] | null;
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): boolean;
+}
+/**
+ * Pose l'UNIQUE écouteur `upgrade` d'un serveur : le proxy inverse d'abord,
+ * puis le serveur WebSocket de Nodefony.
+ *
+ * Pourquoi un seul écouteur : `ws` attaché par son option `server` prend TOUS
+ * les upgrades et répond `400` à ceux qu'il ne reconnaît pas. Un second
+ * écouteur, même posé avant, ne l'empêcherait pas de répondre sur un socket
+ * déjà relayé. Le serveur `ws` est donc créé en `noServer`, et c'est ici que
+ * l'upgrade lui est confié — avec ses propres contrôles intacts (`path`,
+ * `verifyClient`, `maxPayload`…), que `handleUpgrade` applique.
+ *
+ * Entre les deux, `refusal` tranche ce qui doit être refusé AVANT le `101`
+ * (RFC 6455 §4.2.2) : un chemin sans route WebSocket reçoit un statut HTTP,
+ * jamais une ouverture suivie d'une fermeture.
+ *
+ * Sans montage, le coût par connexion est une lecture de champ.
+ *
+ * @param server - serveur HTTP(S) qui reçoit les upgrades
+ * @param wss - serveur WebSocket de Nodefony (`noServer: true`)
+ * @param relay - proxy inverse, lu à chaque upgrade (il peut naître après)
+ * @param refusal - statut HTTP qui refuse l'upgrade, `null` pour l'admettre
+ *   (cf `HttpKernel.websocketUpgradeRefusal`)
+ * @returns la fonction qui retire l'écouteur — à appeler à l'arrêt
+ */
+export declare function attachUpgradeDispatch(server: IUpgradeEmitter, wss: WebSocketServer, relay: () => IUpgradeRelay | null, refusal: (req: IncomingMessage) => number | null): () => void;
+export {};

package/dist/types/nodefony/src/session/session.d.ts

@@ -118,6 +118,8 @@ declare class Session implements ISession {
      * `onSaveSession`.
      *
      * @param user - principal authentifié (string) lié au blob ; défaut courant.
+     *   Fourni, il DEVIENT le principal de la session : une sauvegarde suivante,
+     *   dans la même requête, le garde sans qu'on le lui redonne.
      */
     save(user?: string): Promise<this>;
     /**

package/docs/cookies.md

@@ -255,13 +255,13 @@ constructeur de `Cookie` (`cookie.ts:130`).
 
 | Besoin                         | Appel                                                 | Où                                       |
 | ------------------------------ | ----------------------------------------------------- | ---------------------------------------- |
-| Lire un cookie entrant         | `context.getRequestCookies("nom")` → `Cookie \| null` | `getRequestCookies()` (`Context.ts:660`) |
+| Lire un cookie entrant         | `context.getRequestCookies("nom")` → `Cookie \| null` | `getRequestCookies()` (`Context.ts:706`) |
 | Lire tous les cookies entrants | `context.cookies` → `Record<string, Cookie>`          | `cookies` (`Context.ts:193`)             |
-| Écrire un cookie sortant       | `context.setCookie(new Cookie(…))`                    | `setCookie()` (`Context.ts:667`)         |
-| Supprimer un cookie sortant    | `response.deleteCookieByName("nom")`                  | `http/Response.ts:156`                   |
+| Écrire un cookie sortant       | `context.setCookie(new Cookie(…))`                    | `setCookie()` (`Context.ts:717`)         |
+| Supprimer un cookie sortant    | `response.deleteCookieByName("nom")`                  | `http/Response.ts:233`                   |
 
-Côté réponse HTTP, `addCookie()` (`http/Response.ts:138`) enregistre le cookie, et `setCookies()`
-(`http/Response.ts:164`) émet **une ligne `Set-Cookie` par cookie** — un tableau passé à Node, jamais une
+Côté réponse HTTP, `addCookie()` (`http/Response.ts:215`) enregistre le cookie, et `setCookies()`
+(`http/Response.ts:241`) émet **une ligne `Set-Cookie` par cookie** — un tableau passé à Node, jamais une
 boucle de `setHeader` (qui écraserait tout sauf le dernier). Pour expirer un cookie chez le client :
 `clearCookie()` (`cookie.ts:200`) recule `Expires` à l'époque.
 
@@ -269,14 +269,14 @@ boucle de `setHeader` (qui écraserait tout sauf le dernier). Pour expirer un co
 
 `cookiesParser(context)` (`cookie.ts:87`) lit l'en-tête `Cookie:` (via la bibliothèque `cookie`,
 `parser()` `cookie.ts:50`), crée un `Cookie` par entrée et l'ajoute au contexte avec `addRequestCookie()`
-(`Context.ts:650`). Il est déclenché automatiquement par le pipeline : `parseCookies()` est appelé à
-l'initialisation du contexte HTTP (`HttpContext.ts:190`) **et** WebSocket (`WebsocketContext.ts:170`).
+(`Context.ts:696`). Il est déclenché automatiquement par le pipeline : `parseCookies()` est appelé à
+l'initialisation du contexte HTTP (`HttpContext.ts:255`) **et** WebSocket (`WebsocketContext.ts:170`).
 
 ### Côté WebSocket — lecture oui, écriture non
 
 Les cookies **entrants** sont lus au handshake, exactement comme en HTTP (même parseur). Mais la **poignée
 de main WebSocket ne peut pas poser de cookie** : `setCookie()` et `setCookies()` de la réponse WS sont des
-**no-op** (`websocket/Response.ts:299`), une limite de la bibliothèque `ws`. Le cookie de session, lui, est
+**no-op** (`websocket/Response.ts:315`), une limite de la bibliothèque `ws`. Le cookie de session, lui, est
 posé pendant la **phase HTTP** qui précède l'upgrade. La forme d'un cookie décrit pour le WS est
 `IWsCookie` (`ICookie.ts:19`), produite par `serializeWebSocket()`.
 
@@ -284,12 +284,12 @@ 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:39`). Le seul cookie **piloté par la config** est celui
-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) :
+de la **session** — bloc Zod `sessionCookieSchema` (`config.ts:769`), avec notamment `hostPrefix`
+(`config.ts:791`) 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
-`getSessionCookieName()` (`Context.ts:714`) — encore un détail qui appartient à la page Sessions.
+`getSessionCookieName()` (`Context.ts:757`) — encore un détail qui appartient à la page Sessions.
 
 ## 🛡️ Défenses par attribut
 
@@ -322,7 +322,7 @@ Le nom effectif du cookie de session (avec ou sans `__Host-` selon le transport)
 | `new Cookie(..., { signed: true })` **jette**             | Aucun `secret` configuré → refus du secret prévisible (fail-closed)       | Passer un `secret` réel (`{ signed: true, secret: … }`)                  |
 | Modifier un cookie entrant ne change rien côté client     | Lecture (`context.cookies`) et écriture (réponse) ne sont pas symétriques | (Re)poser le cookie sur la réponse : `context.setCookie(new Cookie(…))`  |
 | Le cookie WS posé au handshake n'arrive jamais            | `setCookie`/`setCookies` de la réponse WS sont des no-op (`ws`)           | Poser le cookie pendant la phase HTTP avant l'upgrade (cf session)       |
-| Deux `Set-Cookie` s'écrasent, un seul survit              | Un `setHeader('Set-Cookie', str)` remplace le précédent                   | Déjà géré : `setCookies()` passe un **tableau** (`http/Response.ts:164`) |
+| Deux `Set-Cookie` s'écrasent, un seul survit              | Un `setHeader('Set-Cookie', str)` remplace le précédent                   | Déjà géré : `setCookies()` passe un **tableau** (`http/Response.ts:241`) |
 | `SameSite` mal orthographié devient `Lax` silencieusement | Fallback fail-safe sur `Lax`                                              | Attendu — vérifier la casse ; `Strict`/`Lax`/`None` seulement            |
 | `maxAge` interprété en millisecondes                      | `maxAge` est en **secondes** (comme `Set-Cookie` Max-Age)                 | Passer des secondes (`30*24*60*60`), pas des ms                          |
 
@@ -330,7 +330,7 @@ Le nom effectif du cookie de session (avec ou sans `__Host-` selon le transport)
 
 Il n'y a pas d'écran Studio dédié aux cookies applicatifs (le cookie **de session** est surfacé dans
 l'écran **Sessions**). En développement, chaque écriture de cookie est journalisée en `DEBUG` par la
-réponse HTTP (`ADD COOKIE ==> …`, `setCookie()` `http/Response.ts:184`) — visible via le skill
+réponse HTTP (`ADD COOKIE ==> …`, `setCookie()` `http/Response.ts:261`) — visible via le skill
 `nodefony-tail-error-logs` ou le Suivi de requête. Sur le fil, un `curl -i` montre les lignes `Set-Cookie`.
 
 ## 🧪 Tests & couverture

package/docs/index.md

@@ -66,6 +66,7 @@ Le tableau pour choisir vite ; les cards en dessous pour savoir ce qu'on y trouv
 | [Upload & corps](upload.md) | parser le corps et recevoir des fichiers | formulaires, imports multipart, API JSON |
 | [Rate-limit](rate-limit.md) | plafonner le débit par client (429) | protéger une API d'un flood ou d'un abus |
 | [Observabilité](observabilite.md) | tracer et journaliser chaque requête | débugger en prod, corréler des logs |
+| [Proxy inverse](reverse-proxy.md) | relayer un préfixe d'URL vers un autre serveur, sur la même origine | servir Vite en dev, adosser un service interne sans CORS |
 | [Pipeline de requête](../../../../../docs/architecture/pipeline-requete.md) | l'ordre exact des étapes, HTTP comme WS | tu débugges « pourquoi ça passe / ça bloque ici » |
 
 ```nodefony-cards
@@ -88,6 +89,9 @@ Le tableau pour choisir vite ; les cards en dessous pour savoir ce qu'on y trouv
   { "icon": "📈", "title": "observabilite", "href": "observabilite.md",
     "desc": "Observer les requêtes : lignes de log (pretty ou JSON), requestId de corrélation, W3C Trace Context, trace des frames WebSocket, redaction et sampling d'audit. Où partent les logs est traité par la page Syslog du cœur.",
     "meta": "débugger en prod, corréler les logs par requête" },
+  { "icon": "↪️", "title": "reverse-proxy", "href": "reverse-proxy.md",
+    "desc": "Relayer un préfixe d'URL vers un autre serveur sans quitter l'origine de la page : HTTP et WebSocket, en-têtes de connexion jamais transmis, X-Forwarded-* et Via posés, barrière d'hôte appliquée avant le relais. C'est par lui que Vite est servi en développement.",
+    "meta": "une origine, un certificat — pas de CORS ni de contenu mixte" },
   { "icon": "🔀", "title": "pipeline-requete", "href": "../../../../../docs/architecture/pipeline-requete.md",
     "desc": "Où ce module s'arrête et où le framework prend le relais, et dans quel ordre s'enchaînent contexte, rate-limit, routage, session, CSRF et firewall.",
     "meta": "page transverse — celle qui relie tout" }
@@ -125,14 +129,16 @@ se périmeraient en silence.
 ## ⚙️ Configuration
 
 Tout se déclare dans `nodefony.config.ts` via `use("@nodefony/http", { … })`. Les blocs Zod
-(`nodefony/config/config.ts`) couvrent : `servers` (ports, transport, TLS, HTTP/2), `session` et
-`cookie`, `trustProxy`, `certificates`, `upload`, le rate-limit et les fichiers statiques. Chaque page
+(`nodefony/config/config.ts`) couvrent : `http`, `https`, `http2` (transport, TLS), `websocket` / `websocketSecure`, `session`
+(dont `session.cookie`), `trustProxy` et `trustedHosts`, `certificates`, `upload` et `maxBodySize`,
+`rateLimit`, `health` et `statics`. La topologie (`servers` : ports, protocole, politique de port) est
+un bloc de la configuration d'application, pas de ce module. Chaque page
 de brique détaille son bloc et ses défauts réels.
 
 ## 📜 Normes appliquées
 
 RFC 9110/9111/9112 (sémantique HTTP, cache, HTTP/1.1), RFC 9113 (HTTP/2), RFC 6455 (WebSocket et ses
-codes de fermeture), RFC 6265bis (cookies), RFC 6585 (429), RFC 6125 (identité des certificats),
+codes de fermeture), RFC 6265bis (cookies), RFC 6585 (429), RFC 9525 (identité des certificats),
 WHATWG Fetch (CORS), W3C Trace Context (`traceparent`).
 
 ## 📡 Observabilité — Studio

package/docs/observabilite.md

@@ -75,7 +75,7 @@ Trois idées portent tout le reste :
 | `X-Request-Id`   | En-tête HTTP de **convention** (de-facto, non normalisé) portant le `requestId` : le client peut l'imposer, le serveur le réfléchit. |
 | Corrélation      | Relier des lignes de log éparses à la **même** requête via une clé partagée (`requestId`, `pid`).                                    |
 | ALS              | _AsyncLocalStorage_ : mémoire Node attachée au contexte d'exécution async — propage `requestId` sans le passer en argument.          |
-| `RequestContext` | Façade Nodefony au-dessus de l'ALS : `getRequestId()`, `getUser()`, `getUserId()`, `traceparent`.                                    |
+| `RequestContext` | Façade Nodefony au-dessus de l'ALS : `getRequestId()`, `getAuthenticatedUser()`, `getUserId()`, `traceparent`.                       |
 | `Pdu`            | _Process Data Unit_ : une entrée de log structurée (RFC 5424). Porte `requestId` + `pid`.                                            |
 | Syslog           | Le hub de logs du cœur (ring buffer + drivers). Reçoit chaque `Pdu` — **page distincte**.                                            |
 | `traceparent`    | En-tête **W3C Trace Context** : `version-traceId-spanId-flags`. Corrèle une requête à travers plusieurs services.                    |
@@ -112,12 +112,12 @@ 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:455` pour HTTP, `http-kernel.ts:455` pour WS), et se lit de n'importe où avec
+(`http-kernel.ts:519` pour HTTP, `http-kernel.ts:1960` 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
 `IRequestLogger` (`IRequestLogger.ts:25`) résolu au boot depuis la config (`applyRequestLoggerFromConfig`,
-`http-kernel.ts:682`), remplaçable à chaud par `httpKernel.setRequestLogger(...)` (`http-kernel.ts:888`).
+`http-kernel.ts:756`), remplaçable à chaud par `httpKernel.setRequestLogger(...)` (`http-kernel.ts:986`).
 Trois formateurs sont livrés ; un quatrième maison s'écrit en implémentant l'interface.
 
 **Zero Trust sur l'entrée cliente.** Un `X-Request-Id` fourni par le client finit réfléchi en réponse,
@@ -226,16 +226,16 @@ GET  200 /trace/whoami 3.1ms 127.0.0.1                   [demo-abc]
 | ------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Génération          | `Context.requestId = randomUUID()` (`Context.ts:244`)               | UUID v4 posé dans le constructeur de base — HTTP **et** WS.                                                                                                                             |
 | Adoption HTTP       | `sanitizeRequestId(headers["x-request-id"])` (`HttpContext.ts:158`) | Remplace l'UUID **si** la valeur cliente est sûre, sinon on garde l'UUID.                                                                                                               |
-| Adoption WS         | `sanitizeRequestId(...)` au handshake (`WebsocketContext.ts:139`)   | Même validation, stable sur toute la durée de la socket (handshake → close).                                                                                                            |
-| Réflexion HTTP/1.1  | `Response.setHeader("x-request-id", …)` (`Response.ts:191`)         | Écrit dans `writeHead()`, sur **chaque** réponse.                                                                                                                                       |
+| Adoption WS         | `sanitizeRequestId(...)` au handshake (`WebsocketContext.ts:162`)   | Même validation, stable sur toute la durée de la socket (handshake → close).                                                                                                            |
+| Réflexion HTTP/1.1  | `Response.setHeader("x-request-id", …)` (`Response.ts:248`)         | Écrit dans `writeHead()`, sur **chaque** réponse.                                                                                                                                       |
 | Réflexion HTTP/2    | `this.headers["x-request-id"] = requestId` (`http2/Response.ts:71`) | Sinon les réponses du port 5152 sortiraient sans corrélation.                                                                                                                           |
-| ALS (HTTP)          | `RequestContext.run({ requestId, … })` (`http-kernel.ts:455`)       | Ouvre la bulle → tout `Pdu` créé dedans est tagué.                                                                                                                                      |
-| ALS (WS)            | `RequestContext.run({ requestId, … })` (`http-kernel.ts:455`)       | Handshake **et** messages : la bulle ouverte à la connexion est reliée à chaque message par `AsyncResource.bind`, sinon l'identité résolue au handshake se perdrait au premier message. |
+| ALS (HTTP)          | `RequestContext.run({ requestId, … })` (`http-kernel.ts:519`)       | Ouvre la bulle → tout `Pdu` créé dedans est tagué.                                                                                                                                      |
+| ALS (WS)            | `RequestContext.run({ requestId, … })` (`http-kernel.ts:519`)       | Handshake **et** messages : la bulle ouverte à la connexion est reliée à chaque message par `AsyncResource.bind`, sinon l'identité résolue au handshake se perdrait au premier message. |
 | Capture dans le log | `Pdu.requestId = Pdu.requestIdProvider?.()` (`Pdu.ts:262`)          | Provider injectable branché sur l'ALS côté Node — 0 lecture côté navigateur.                                                                                                            |
 
 > [!IMPORTANT]
 > Les logs de **fin** de requête (bilan `req`, `onClose`) sont émis **hors** de la bulle ALS (déjà
-> refermée). L'override `Context.log()` (`Context.ts:520`) rouvre alors une micro-bulle depuis
+> refermée). L'override `Context.log()` (`Context.ts:545`) rouvre alors une micro-bulle depuis
 > `this.requestId` pour que le `Pdu` capture quand même la corrélation — sinon la ligne d'entrée d'une
 > trace serait la seule à ne PAS porter son `requestId`.
 
@@ -249,15 +249,15 @@ Nodefony implémente **W3C Trace Context** (le code s'y réfère explicitement,
 - La validation refuse `version=ff` et un `traceId`/`spanId` tout-à-zéro — `parseTraceparent()`
   (`trace.ts:38`), conforme à la spec (le récepteur NE DOIT PAS propager ces valeurs).
 
-Le `traceparent` résolu est propagé en ALS **et** réfléchi sur la réponse HTTP (`context/http/Response.ts:494`). Côté
+Le `traceparent` résolu est propagé en ALS **et** réfléchi sur la réponse HTTP (`context/http/Response.ts:572`). Côté
 **WebSocket**, il est propagé en ALS mais **pas** réfléchi dans la réponse de handshake — la bibliothèque
-`ws` n'expose pas proprement ce chemin (`http-kernel.ts:1419`) ; la corrélation reste visible côté serveur.
+`ws` n'expose pas proprement ce chemin (`http-kernel.ts:1450`) ; la corrélation reste visible côté serveur.
 
 ### Le contrat de logger — `IRequestLogger`
 
-Le kernel tient un `IRequestLogger` singleton (`http-kernel.ts:289`) et lui délègue le rendu de la ligne
-de bilan, au teardown, via `Context.logRequest()` (`Context.ts:595`) côté HTTP et
-`WebsocketContext.logRequest()` (`WebsocketContext.ts:209`) côté WS. Le contrat a trois méthodes
+Le kernel tient un `IRequestLogger` singleton (`http-kernel.ts:334`) et lui délègue le rendu de la ligne
+de bilan, au teardown, via `Context.logRequest()` (`Context.ts:640`) côté HTTP et
+`WebsocketContext.logRequest()` (`WebsocketContext.ts:233`) côté WS. Le contrat a trois méthodes
 (`IRequestLogger.ts:25`) :
 
 - `renderHttp(context, error?)` → `{ text, severity, msgid }` remis à `context.log()`.
@@ -287,7 +287,7 @@ Un seul réglage d'app, côté cœur (bloc `log`), pilote le format des lignes.
 | ------------------- | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------ |
 | `log.requestFormat` | `auto` \| `default` \| `pretty` \| `json` | `auto` | Format de la ligne de bilan. `auto` = pretty en dev / json en prod (`schema.ts:39`). |
 
-`auto` est résolu au boot selon l'environnement (`applyRequestLoggerFromConfig`, `http-kernel.ts:682`) :
+`auto` est résolu au boot selon l'environnement (`applyRequestLoggerFromConfig`, `http-kernel.ts:756`) :
 
 | Valeur    | Formateur              | Rendu                                                                                     |
 | --------- | ---------------------- | ----------------------------------------------------------------------------------------- |
@@ -320,7 +320,7 @@ timing (`pretty-request-logger.ts:116`).
 
 ### `JsonAuditLogger` — un PDU par requête, pour la machine
 
-Émet un `AuditLogEntry` canonique (`audit-logger.ts:28`) : `ts`, `requestId`, `userId`, `type`, `method`,
+Émet un `AuditLogEntry` canonique (`audit-logger.ts:28`) : `ts`, `requestId`, `userIdentifier` (appelant authentifié, posé par le pare-feu sur `context.userIdentifier`), `type`, `method`,
 `url`, `status`, `durationMs`, `remoteAddress`, `host`, `userAgent`, phases, erreur enrichie (nom, code,
 `errorType`, `cause` bornée à 5, stack **dev seulement**). Deux propriétés majeures :
 
@@ -337,7 +337,7 @@ Singleton sans état, 0 allocation par requête (`request-logger.ts:21`). Conser
 ### Écrire son propre formateur
 
 Implémenter `IRequestLogger` (`IRequestLogger.ts:25`) et l'injecter — NCSA Common Log Format, syslog RFC
-5424 texte, OpenTelemetry logs… `httpKernel.setRequestLogger(monLogger)` (`http-kernel.ts:888`). Les trois
+5424 texte, OpenTelemetry logs… `httpKernel.setRequestLogger(monLogger)` (`http-kernel.ts:986`). Les trois
 formateurs et le type sont exportés depuis `@nodefony/http` (`index.ts:221`).
 
 ## 🔐 Sécurité
@@ -418,9 +418,9 @@ instancié **qu'en dev** (fuite d'info + coût en prod).
 | Symptôme                                            | Cause                                                               | Correction                                                                         |
 | --------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
 | 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:520`)           |
+| 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:545`)           |
 | Réponse HTTP/2 sans `x-request-id`                  | Chemin de réponse h2 distinct du 1.1                                | Déjà géré (`http2/Response.ts:106`) — 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:1698`)                |
+| 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:1990`)                |
 | 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`           |