@nodefony/http 10.0.0-alpha.9 → 10.0.0-beta.2

package/dist/types/nodefony/src/errors/thrownMessage.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Message lisible d'une valeur LEVÉE (`catch`, rejet) dont on ignore le type.
+ *
+ * Même rendu que `String(value)` pour une `Error` (son `message`) et pour les
+ * primitives ; un objet quelconque rend son étiquette (`[object Object]`) sans
+ * appeler un `toString` arbitraire ni sérialiser son contenu — ce texte peut
+ * finir dans une réponse ou un journal, il ne doit rien divulguer.
+ *
+ * @param value - la valeur levée.
+ * @returns un texte court, jamais vide pour une valeur définie.
+ */
+export declare function thrownMessage(value: unknown): string;

package/dist/types/nodefony/src/profiler/Profiler.d.ts

@@ -38,13 +38,13 @@ export interface ProfileQuery {
     /** Requête (SQL ou commande NoSQL), tronquée si volumineuse. */
     sql: string;
     /** Début relatif (`performance.now()`) — même horloge que les phases. */
-    startMs?: number;
+    startMs?: number | undefined;
     /** Durée d'exécution en ms. */
     durationMs: number;
     /** Lignes affectées/retournées, si connu. */
-    rows?: number;
+    rows?: number | undefined;
     /** Connecteur émetteur (`drizzle`, `mongoose`…). */
-    connector?: string;
+    connector?: string | undefined;
 }
 /**
  * Traversée du firewall par cette requête — **ce qui était possible** (la zone :
@@ -97,9 +97,9 @@ export interface ProfileEntry {
     error: string | null;
     phases: ProfilePhase[];
     /** Requêtes ORM (SEAM futur — `undefined` tant qu'aucun adapter ne pushe). */
-    queries?: ProfileQuery[];
+    queries?: ProfileQuery[] | undefined;
     /** Traversée du firewall — `undefined` si la requête n'a croisé aucune zone. */
-    security?: ProfileSecurity;
+    security?: ProfileSecurity | undefined;
 }
 /** Résumé léger d'un profil pour la liste `recent` (sans les phases). */
 export interface ProfileSummary {
@@ -115,49 +115,49 @@ export interface ProfileSummary {
 }
 /** Forme structurelle minimale lue sur un `Context` (lecture défensive). */
 interface ProfilableContext {
-    requestId?: string;
-    type?: string;
-    scheme?: string;
-    method?: string | null;
-    url?: string;
-    remoteAddress?: string | null;
-    traceparent?: string | null;
+    requestId?: string | undefined;
+    type?: string | undefined;
+    scheme?: string | undefined;
+    method?: string | null | undefined;
+    url?: string | undefined;
+    remoteAddress?: string | null | undefined;
+    traceparent?: string | null | undefined;
     error?: {
         message?: string;
-    } | null;
+    } | null | undefined;
     response?: {
         statusCode?: number;
-    } | null;
+    } | null | undefined;
     phases?: ReadonlyArray<{
         name: string;
         startMs: number;
-        durationMs?: number;
-    }>;
+        durationMs?: number | undefined;
+    }> | undefined;
     resolver?: {
         route?: {
-            name?: string;
+            name?: string | undefined;
         } | null;
         controller?: {
-            name?: string;
-        } | null;
-        actionName?: string;
-    } | null;
+            name?: string | undefined;
+        } | null | undefined;
+        actionName?: string | undefined;
+    } | null | undefined;
     /**
      * Buffer de requêtes ORM rempli pendant la requête (dev-only). Même tableau
      * que la payload ALS — les adapters ORM y poussent via `RequestContext`.
      * `null`/absent hors profiling.
      */
-    profilerQueries?: ProfileQuery[] | null;
+    profilerQueries?: ProfileQuery[] | null | undefined;
     /**
      * Zone firewall capturée (`SecuredArea`, posée par `Firewall.isSecure`). Lue
      * en structurel : `@nodefony/http` ne peut pas importer `@nodefony/security`.
      */
     security?: {
-        name?: string;
-        security?: boolean;
-        mode?: string;
-        authenticators?: readonly string[];
-    } | null;
+        name?: string | undefined;
+        security?: boolean | undefined;
+        mode?: string | undefined;
+        authenticators?: readonly string[] | undefined;
+    } | null | undefined;
     /** Décision du firewall sur cette requête (dev-only, cf `ISecurityTrace`). */
     securityTrace?: {
         authenticator: string | null;
@@ -165,7 +165,7 @@ interface ProfilableContext {
         reason: string | null;
         user: string | null;
         roles: string[] | null;
-    } | null;
+    } | null | undefined;
 }
 export declare class Profiler {
     private readonly _buf;

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

@@ -0,0 +1,20 @@
+import type { ServersConfig } from "nodefony";
+/**
+ * Rétrécit la section `servers` de la configuration du kernel (lue dans le sac
+ * de config non typé du cœur) en {@link ServersConfig}, sans propager `any`.
+ *
+ * Seule lecture de `kernel.options.servers` dans `@nodefony/http` : les serveurs
+ * et le `HttpKernel` passent tous par ici.
+ *
+ * @param servers - la valeur brute de `kernel.options.servers`.
+ * @returns la section typée, ou `undefined` si elle est absente ou n'est pas un objet.
+ */
+export declare function asServersConfig(servers: unknown): ServersConfig | undefined;
+/**
+ * Port DEMANDÉ pour un serveur (`servers.<type>.port`), ou `undefined` si le
+ * serveur est désactivé, absent, ou sans port numérique.
+ *
+ * @param servers - section `servers` déjà rétrécie ({@link asServersConfig}).
+ * @param type - le serveur visé.
+ */
+export declare function configuredServerPort(servers: ServersConfig | undefined, type: "http" | "https"): number | undefined;

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

@@ -1,49 +1,8 @@
-/**
- * **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";
+export { resolvePortPolicy };
+export type { PortPolicy };
 /** Serveur écoutable (surface minimale commune `http`/`https`/`http2`). */
 export interface Listenable {
     listen(port: number, host?: string): unknown;
@@ -51,8 +10,6 @@ export interface Listenable {
     once(event: string, listener: (...args: never[]) => void): unknown;
     removeListener(event: string, listener: (...args: never[]) => void): unknown;
 }
-/** Que faire si le port désiré est occupé. */
-export type PortPolicy = "auto" | "strict";
 /** Nombre de ports essayés après le désiré, en `auto`. */
 export declare const DEFAULT_PORT_RETRY_ATTEMPTS = 20;
 export interface BindPlan {
@@ -69,28 +26,13 @@ export interface BindResult {
     /** Port désiré si l'écoute a dû être décalée, `null` si on l'a obtenu. */
     shiftedFrom: number | null;
 }
-/**
- * Politique de port effective.
- *
- * Le défaut dépend de l'environnement, et ce n'est pas de la coquetterie :
- * - **production** → `strict`. Le port y est un contrat (service k8s, ingress,
- *   sonde de santé). Un bind silencieux ailleurs donnerait un pod déclaré sain
- *   que personne n'atteint : une panne invisible, le pire des deux mondes.
- * - **test** → `strict`. Un port occupé veut dire « un serveur est resté debout » ;
- *   le banc doit s'arrêter, pas viser à côté (il taperait le serveur du voisin).
- * - **développement** → `auto`. Ici un port pris n'est qu'une nuisance.
- *
- * @param environment - `kernel.environment` (normalisé `development`/`production`/`test`).
- * @param explicit - `servers.portPolicy` s'il est configuré (il gagne toujours).
- */
-export declare function resolvePortPolicy(environment: string | undefined, explicit?: PortPolicy): PortPolicy;
 /** Forme lue de `kernel.options.servers` (lecture structurelle, pas d'import core). */
 export interface ServersPortConfig {
     http?: {
-        port?: number;
+        port?: number | undefined;
     } | false;
     https?: {
-        port?: number;
+        port?: number | undefined;
     } | false;
     portPolicy?: PortPolicy;
     portRetryAttempts?: number;
@@ -151,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/session/session.d.ts

@@ -11,24 +11,24 @@ import type { ISession, ISessionStorage, ISerializedSession, SessionStatusType,
  * hash chiffré « maison ».
  */
 export type OptionsSessionType = {
-    name?: string;
-    cookie?: CookieOptionsType;
+    name?: string | undefined;
+    cookie?: CookieOptionsType | undefined;
     /** Strict mode : un identifiant inconnu du storage → nouvelle session (anti-fixation). */
-    strictMode?: boolean;
+    strictMode?: boolean | undefined;
     /** Lie la session à l'hôte (méta `host`) — rejette un changement d'origine. */
-    refererCheck?: boolean;
+    refererCheck?: boolean | undefined;
     /**
      * Idle timeout (NIST/OWASP, secondes) : inactivité MAX depuis la dernière
      * activité (`updatedAt`, rafraîchi par le touch). `0`/absent = pas d'expiration
      * par inactivité. Enforcement serveur ({@link Session.isValidSession} + GC).
      */
-    idleTimeoutS?: number;
+    idleTimeoutS?: number | undefined;
     /**
      * Absolute timeout (OWASP, secondes) : durée de vie MAX depuis la création,
      * indépendante de l'activité. Borne la fenêtre d'exploitation d'un identifiant
      * volé même sur session active. `0`/absent = désactivé (seul l'idle s'applique).
      */
-    absoluteTimeoutS?: number;
+    absoluteTimeoutS?: number | undefined;
 };
 /**
  * Session serveur Nodefony — état persistant lié à une identité, indexé par un
@@ -59,13 +59,13 @@ declare class Session implements ISession {
      * aucune écriture storage.
      */
     readOnly: boolean;
-    context?: ContextType;
-    created?: Date;
-    updated?: Date;
+    context?: ContextType | undefined;
+    created?: Date | undefined;
+    updated?: Date | undefined;
     options: OptionsSessionType;
     cookieSession: Cookie | null;
-    lifetime?: number;
-    user?: string;
+    lifetime?: number | undefined;
+    user?: string | undefined;
     strategy: SessionStrategyType;
     /** Sac d'attributs applicatifs (clé/valeur) — exposé via {@link getAttributes}. */
     private attributesBag;
@@ -161,7 +161,7 @@ declare class Session implements ISession {
     clearFlashBag(key: string): void;
     clearFlashBags(): void;
     serialize(user?: string): ISerializedSession;
-    deSerialize(data: ISerializedSession): void;
+    deSerialize(serialized: ISerializedSession): void;
     /** Réinitialise les trois sacs (attributs, métas, flash) — état vide. */
     clear(): void;
     getName(): string;

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

@@ -68,7 +68,7 @@ declare class RevocationGuardStorage implements ISessionStorage {
      * Comme ce décorateur est posé en production dès qu'une révocation est
      * possible, l'oubli aurait désactivé le tri **partout**.
      */
-    readonly sortableFields?: readonly string[];
+    readonly sortableFields?: readonly string[] | undefined;
     constructor(inner: ISessionStorage);
     read(id: string): Promise<ISerializedSession>;
     start(id: string): Promise<ISerializedSession>;

package/docs/cookies.md

@@ -116,12 +116,12 @@ les invariants** que le navigateur exigerait de toute façon — pour que l'erre
 cookie lu en JS), jamais choisir de fermer.
 
 **Les préfixes sont forcés, pas espérés.** Nommer un cookie `__Host-…` ne suffit pas : `serialize()`
-(`cookie.ts:383`) **réécrit** la sortie — `Secure` ajouté, `Path=/` imposé, `Domain` retiré — pour que le
+(`cookie.ts:393`) **réécrit** la sortie — `Secure` ajouté, `Path=/` imposé, `Domain` retiré — pour que le
 navigateur ne rejette jamais le cookie en silence. Idem `__Secure-` (Secure imposé) et `SameSite=None` (qui
 impose `Secure`, `cookie.ts:393`).
 
 **La signature refuse le secret prévisible.** Un cookie `signed: true` sans secret configuré **jette**
-(`setValue()`, `cookie.ts:199`) : signer avec le secret public par défaut ne protégerait rien
+(`setValue()`, `cookie.ts:205`) : signer avec le secret public par défaut ne protégerait rien
 (fail-closed). La vérification est **timing-safe** (`unsign()` → `crypto.timingSafeEqual`, `cookie.ts:380`).
 
 **`SameSite` retombe toujours sur `Lax`, jamais sur `None`.** Toute valeur inconnue est normalisée vers
@@ -223,7 +223,7 @@ Le constructeur accepte `(nom, valeur, options?)` ou **un cookie à copier** (su
 | Option     | Type                       | Défaut       | Effet                                                                  |
 | ---------- | -------------------------- | ------------ | ---------------------------------------------------------------------- |
 | `maxAge`   | `number` (secondes)        | `0`          | Durée de vie. `0` = cookie de session (ni `Max-Age` ni `Expires`).     |
-| `expires`  | `Date \| string \| number` | —            | Date d'expiration absolue (`setExpires()`, `cookie.ts:264`).           |
+| `expires`  | `Date \| string \| number` | —            | Date d'expiration absolue (`setExpires()`, `cookie.ts:272`).           |
 | `path`     | `string`                   | `/`          | Préfixe d'URL de portée.                                               |
 | `domain`   | `string`                   | `undefined`  | Domaine de portée (retiré si nom `__Host-`).                           |
 | `secure`   | `boolean`                  | `true`       | HTTPS only. Forcé si `SameSite=None` ou préfixe `__Host-`/`__Secure-`. |
@@ -231,18 +231,18 @@ Le constructeur accepte `(nom, valeur, options?)` ou **un cookie à copier** (su
 | `sameSite` | `SameSiteType`             | `Lax`        | `Strict`/`Lax`/`None`. Toute autre valeur retombe sur `Lax`.           |
 | `signed`   | `boolean`                  | `false`      | Signe la valeur (HMAC). Exige `secret` configuré, sinon **jette**.     |
 | `secret`   | `string`                   | (par défaut) | Clé HMAC. Le secret par défaut est **refusé** pour signer.             |
-| `priority` | `High \| Medium \| Low`    | `undefined`  | Attribut `Priority` (`setPriority()`, `cookie.ts:297`).                |
+| `priority` | `High \| Medium \| Low`    | `undefined`  | Attribut `Priority` (`setPriority()`, `cookie.ts:305`).                |
 
 Les défauts sont matérialisés dans `cookieDefaultSettings` (`cookie.ts:39`) ; la fusion se fait dans le
 constructeur de `Cookie` (`cookie.ts:130`).
 
 ### Sérialiser : `serialize()` et `serializeWebSocket()`
 
-- `serialize()` (`cookie.ts:383`) produit la **ligne `Set-Cookie`** complète (attributs dans l'ordre,
+- `serialize()` (`cookie.ts:393`) produit la **ligne `Set-Cookie`** complète (attributs dans l'ordre,
   préfixes forcés, `Max-Age` seulement s'il est positif).
-- `serializeWebSocket()` (`cookie.ts:425`) produit un **objet** `IWsCookie` (mêmes invariants de sécurité)
+- `serializeWebSocket()` (`cookie.ts:435`) produit un **objet** `IWsCookie` (mêmes invariants de sécurité)
   — utilisé quand un cookie doit être décrit hors en-tête HTTP.
-- `toString()` (`cookie.ts:317`) ne rend que `nom=valeurEncodée` (sans attributs).
+- `toString()` (`cookie.ts:325`) ne rend que `nom=valeurEncodée` (sans attributs).
 
 ### Signer / vérifier : `sign()` et `unsign()`
 
@@ -255,28 +255,28 @@ 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:674`) |
 | 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:119`                   |
+| Écrire un cookie sortant       | `context.setCookie(new Cookie(…))`                    | `setCookie()` (`Context.ts:685`)         |
+| Supprimer un cookie sortant    | `response.deleteCookieByName("nom")`                  | `http/Response.ts:213`                   |
 
-Côté réponse HTTP, `addCookie()` (`http/Response.ts:101`) enregistre le cookie, et `setCookies()`
-(`http/Response.ts:127`) émet **une ligne `Set-Cookie` par cookie** — un tableau passé à Node, jamais une
+Côté réponse HTTP, `addCookie()` (`http/Response.ts:195`) enregistre le cookie, et `setCookies()`
+(`http/Response.ts:221`) é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:194`) recule `Expires` à l'époque.
+`clearCookie()` (`cookie.ts:200`) recule `Expires` à l'époque.
 
 ### Parsing des cookies entrants
 
 `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é à
+(`Context.ts:664`). Il est déclenché automatiquement par le pipeline : `parseCookies()` est appelé à
 l'initialisation du contexte HTTP (`HttpContext.ts:190`) **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:295`), une limite de la bibliothèque `ws`. Le cookie de session, lui, est
+**no-op** (`websocket/Response.ts:299`), 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`
+de la **session** — bloc Zod `sessionCookieSchema` (`config.ts:752`), avec notamment `hostPrefix`
 (`config.ts:770`) qui décide du préfixe `__Host-`. Tout cela est documenté dans [Sessions](session.md) :
 cette page ne le duplique pas.
 
 Le nom effectif du cookie de session (avec ou sans `__Host-` selon le transport) est calculé par
-`getSessionCookieName()` (`Context.ts:714`) — encore un détail qui appartient à la page Sessions.
+`getSessionCookieName()` (`Context.ts:733`) — encore un détail qui appartient à la page Sessions.
 
 ## 🛡️ Défenses par attribut
 
@@ -297,19 +297,19 @@ Le nom effectif du cookie de session (avec ou sans `__Host-` selon le transport)
 | -------------------------- | --------------------------------------- | ------------------------------------------------------------------------ |
 | `HttpOnly` (défaut `true`) | Vol de cookie par **XSS**               | Défaut fermé (`cookieDefaultSettings`, `cookie.ts:39`)                   |
 | `SameSite=Lax` (défaut)    | **CSRF** inter-site                     | Fallback toujours `Lax`, jamais `None` (`setSameSite()` `cookie.ts:250`) |
-| `Secure` (défaut `true`)   | Interception en clair                   | Forcé aussi par `None`/préfixes (`serialize()` `cookie.ts:383`)          |
-| Préfixe `__Host-`          | **Session fixation** cross-sous-domaine | `Domain` retiré + `Path=/` imposés (`serialize()` `cookie.ts:383`)       |
+| `Secure` (défaut `true`)   | Interception en clair                   | Forcé aussi par `None`/préfixes (`serialize()` `cookie.ts:393`)          |
+| Préfixe `__Host-`          | **Session fixation** cross-sous-domaine | `Domain` retiré + `Path=/` imposés (`serialize()` `cookie.ts:393`)       |
 | Cookie signé (HMAC)        | Altération de la valeur côté client     | `sign()`/`unsign()` timing-safe (`cookie.ts:355`, `cookie.ts:355`)       |
-| Refus du secret par défaut | Signature « fantôme » sans protection   | Fail-closed à la signature (`setValue()` `cookie.ts:199`)                |
+| Refus du secret par défaut | Signature « fantôme » sans protection   | Fail-closed à la signature (`setValue()` `cookie.ts:205`)                |
 
 ## 📜 Normes appliquées
 
 | Domaine                            | Norme                | Ancrage                                                            |
 | ---------------------------------- | -------------------- | ------------------------------------------------------------------ |
-| Cookies — syntaxe `Set-Cookie`     | RFC 6265bis          | `serialize()` (`cookie.ts:383`)                                    |
+| Cookies — syntaxe `Set-Cookie`     | RFC 6265bis          | `serialize()` (`cookie.ts:393`)                                    |
 | `SameSite` — 3 valeurs canoniques  | RFC 6265bis §5.4.7   | `SameSiteType` (`ICookie.ts:3`), `setSameSite()` (`cookie.ts:250`) |
-| Préfixes `__Host-` / `__Secure-`   | RFC 6265bis §4.1.3   | `serialize()` force les contraintes (`cookie.ts:383`)              |
-| `SameSite=None` impose `Secure`    | RFC 6265bis          | `serialize()` (`cookie.ts:383`)                                    |
+| Préfixes `__Host-` / `__Secure-`   | RFC 6265bis §4.1.3   | `serialize()` force les contraintes (`cookie.ts:393`)              |
+| `SameSite=None` impose `Secure`    | RFC 6265bis          | `serialize()` (`cookie.ts:393`)                                    |
 | Intégrité — HMAC-SHA256, base64url | RFC 2104 / RFC 4648  | `sign()` (`cookie.ts:331`)                                         |
 | Vérification à temps constant      | bonne pratique OWASP | `unsign()` → `timingSafeEqual` (`cookie.ts:380`)                   |
 
@@ -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:127`) |
+| 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:221`) |
 | `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:146`) — visible via le skill
+réponse HTTP (`ADD COOKIE ==> …`, `setCookie()` `http/Response.ts:241`) — 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

@@ -125,8 +125,10 @@ 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

package/docs/observabilite.md

@@ -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:435` pour HTTP, `http-kernel.ts:435` pour WS), et se lit de n'importe où avec
+(`http-kernel.ts:1510` pour HTTP, `http-kernel.ts:1929` 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:660`), remplaçable à chaud par `httpKernel.setRequestLogger(...)` (`http-kernel.ts:866`).
+`http-kernel.ts:682`), remplaçable à chaud par `httpKernel.setRequestLogger(...)` (`http-kernel.ts:910`).
 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,
@@ -222,20 +222,20 @@ GET  200 /trace/whoami 3.1ms 127.0.0.1                   [demo-abc]
 
 ### Le `requestId` — génération, adoption, réflexion
 
-| Étape               | Où                                                                  | Comportement                                                                 |
-| ------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| 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:153`)         | É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:436`)       | Ouvre la bulle → tout `Pdu` créé dedans est tagué.                           |
-| ALS (WS)            | `RequestContext.run({ requestId, … })` (`http-kernel.ts:436`)       | Handshake **et** messages (via `AsyncResource.bind`, BUG-001).               |
-| 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. |
+| Étape               | Où                                                                  | Comportement                                                                                                                                                                            |
+| ------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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: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:1510`)      | Ouvre la bulle → tout `Pdu` créé dedans est tagué.                                                                                                                                      |
+| ALS (WS)            | `RequestContext.run({ requestId, … })` (`http-kernel.ts:1929`)      | 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:459`) rouvre alors une micro-bulle depuis
+> refermée). L'override `Context.log()` (`Context.ts:535`) 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:435`). Côté
+Le `traceparent` résolu est propagé en ALS **et** réfléchi sur la réponse HTTP (`context/http/Response.ts:551`). 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.
 
 ### Le contrat de logger — `IRequestLogger`
 
-Le kernel tient un `IRequestLogger` singleton (`http-kernel.ts:270`) 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:289`) et lui délègue le rendu de la ligne
+de bilan, au teardown, via `Context.logRequest()` (`Context.ts:608`) 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,19 +287,19 @@ 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:660`) :
+`auto` est résolu au boot selon l'environnement (`applyRequestLoggerFromConfig`, `http-kernel.ts:682`) :
 
 | Valeur    | Formateur              | Rendu                                                                                     |
 | --------- | ---------------------- | ----------------------------------------------------------------------------------------- |
 | `pretty`  | `PrettyRequestLogger`  | 1 ligne colorée `GET 200 /x 12.3ms 127.0.0.1 [a1b2c3d4]` (`pretty-request-logger.ts:34`). |
-| `json`    | `JsonAuditLogger`      | 1 objet JSON canonique par requête (`audit-logger.ts:122`).                               |
+| `json`    | `JsonAuditLogger`      | 1 objet JSON canonique par requête (`audit-logger.ts:136`).                               |
 | `default` | `DefaultRequestLogger` | Format legacy verbeux `URL : … FROM : … ID : <uuid>` (`request-logger.ts:21`).            |
 
 > [!NOTE]
 > Le **réglage fin** du logger JSON (`sampleRate`, `includeStack`, `maxCauseDepth`, `nominal`) n'est pas
 > un champ déclaré du schéma d'app : il se pose **programmatiquement**, en construisant le logger et en
 > l'injectant — `httpKernel.setRequestLogger(new JsonAuditLogger({ sampleRate: 10 }))` (options :
-> `JsonAuditLoggerOptions`, `audit-logger.ts:78`). L'override programmatique gagne toujours sur la config.
+> `JsonAuditLoggerOptions`, `audit-logger.ts:92`). L'override programmatique gagne toujours sur la config.
 
 ## 🧰 Les trois formateurs (et le contrat)
 
@@ -325,7 +325,7 @@ timing (`pretty-request-logger.ts:116`).
 `errorType`, `cause` bornée à 5, stack **dev seulement**). Deux propriétés majeures :
 
 - **Redaction par construction** : `Authorization` et `Cookie` ne sont **jamais** sérialisés — seuls des
-  drapeaux `hasAuthorization`/`hasCookie` le sont (`audit-logger.ts:211`).
+  drapeaux `hasAuthorization`/`hasCookie` le sont (`audit-logger.ts:226`).
 - **Sampling déterministe** : `shouldSample()` (`audit-logger.ts:156`) garde 1 requête nominale sur N mais
   **jamais** une erreur ni un `status >= 400` — on ne perd aucun échec ; compteur, pas de RNG.
 
@@ -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:866`). Les trois
+5424 texte, OpenTelemetry logs… `httpKernel.setRequestLogger(monLogger)` (`http-kernel.ts:910`). Les trois
 formateurs et le type sont exportés depuis `@nodefony/http` (`index.ts:221`).
 
 ## 🔐 Sécurité
@@ -389,7 +389,7 @@ Le `requestId` est la **clé de jointure** de l'admin Studio (dev). Les écrans
 | **Audit** | écran Audit | Les événements d'audit persistés. |
 | **Profiler** (dev) | `/nodefony/profiler/api/{requestId}` (`ProfilerAdminApi.ts:23`) | Le profil complet (waterfall des phases) d'une requête donnée. |
 
-Le profiler indexe ses instantanés par `requestId` (`Profiler.ts:203`) ; la debug bar lit le
+Le profiler indexe ses instantanés par `requestId` (`Profiler.ts:214`) ; la debug bar lit le
 `X-Request-Id` de son propre appel AJAX et va chercher le profil (`Profiler.ts:14`). Le profiler n'est
 instancié **qu'en dev** (fuite d'info + coût en prod).
 
@@ -407,7 +407,7 @@ instancié **qu'en dev** (fuite d'info + coût en prod).
 | Sûreté des valeurs d'en-tête (field-value) | RFC 9110 §5.5 | `sanitizeRequestId()` allowlist (`requestId.ts:38`) |
 | En-têtes trop volumineux / borne | anti-abus (log flooding) | `MAX_REQUEST_ID_LENGTH` (`requestId.ts:18`) |
 | Log structuré (PDU, sévérités) | RFC 5424 | `Pdu` + `requestId`/`pid` (`Pdu.ts:184`) |
-| Sévérité dérivée du statut HTTP | RFC 9110 (catégories) | `severityFromStatus()` (`audit-logger.ts:71`) |
+| Sévérité dérivée du statut HTTP | RFC 9110 (catégories) | `severityFromStatus()` (`audit-logger.ts:85`) |
 | Non-journalisation des secrets | OWASP (logging) | redaction présence-only (`audit-logger.ts:211`) |
 
 > `X-Request-Id` n'est **pas** un en-tête normalisé (convention de-facto) ; c'est la **valeur** qu'il
@@ -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:459`)           |
-| Réponse HTTP/2 sans `x-request-id`                  | Chemin de réponse h2 distinct du 1.1                                | Déjà géré (`http2/Response.ts:71`) — le port 5152 réfléchit aussi                  |
-| Pas de `traceparent` renvoyé sur un WebSocket       | `ws` n'expose pas l'écriture d'en-tête au handshake                 | Attendu — la trace WS reste propagée en ALS (`http-kernel.ts:1348`)                |
+| 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:535`)           |
+| 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:1915`)                |
 | 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`           |