@nodefony/http 10.0.0-beta.2 → 10.0.0-beta.4

package/dist/nodefony/src/session/storage/sessionFilters.js

@@ -1,4 +1,4 @@
-//#region nodefony/src/session/storage/sessionFilters.ts
+// nodefony/src/session/storage/sessionFilters.ts
 /**
 * **Le vocabulaire de filtre des sessions**, en noms PUBLICS — celui que la
 * console d'administration écrit dans l'URL (`?user=alice`).
@@ -79,5 +79,4 @@ const SESSION_FACETS = {
 * rouvert du même geste.
 */
 const SESSION_STATS_FILTERS = { user: "string" };
-//#endregion
 export { SESSION_FACETS, SESSION_FILTERS, SESSION_STATS_FILTERS };

package/dist/nodefony/src/session/storage/sessionSort.js

@@ -1,5 +1,5 @@
 import { renameOrderFields } from "nodefony";
-//#region nodefony/src/session/storage/sessionSort.ts
+// nodefony/src/session/storage/sessionSort.ts
 /**
 * **Le vocabulaire de tri des sessions**, en noms PUBLICS — ceux qu'un client
 * écrit dans l'URL (`?order=updatedAt:DESC`), jamais des noms de colonne.
@@ -49,5 +49,4 @@ const SESSION_COLUMN_ALIASES = { id: "session_id" };
 * `session_id` — {@link SESSION_DEFAULT_ORDER} déjà traduit.
 */
 const SESSION_DEFAULT_ORDER_SQL = renameOrderFields(SESSION_DEFAULT_ORDER, SESSION_COLUMN_ALIASES);
-//#endregion
 export { SESSION_COLUMN_ALIASES, SESSION_DEFAULT_ORDER, SESSION_DEFAULT_ORDER_SQL, SESSION_SORTABLE_FIELDS };

package/dist/types/index.d.ts

@@ -71,22 +71,31 @@ export { defineHttpConfig, httpConfigJsonSchema, } from "./nodefony/config/defin
 export { httpConfigSchema } from "./nodefony/config/config.js";
 export type { IHttpConfig, IHttpConfigInput, } from "./nodefony/interfaces/IHttpConfig.js";
 export { decideSend, readBackpressureOptions, type WsBackpressurePolicy, type WsSendDecision, type IWsBackpressureOptions, type IBackpressureSocket, type IBackpressureTarget, } from "./nodefony/src/context/websocket/wsBackpressure.js";
+export { isWebsocketContext } from "./nodefony/src/context/websocket/isWebsocketContext.js";
 export { compileDomainPattern, compileDomainPatterns, compileTrustedHosts, isDomainAllowed, } from "./nodefony/src/context/domainMatcher.js";
 export type { DomainPattern, ITrustedHostsConfig, } from "./nodefony/src/context/domainMatcher.js";
 export { MemoryRateLimitStore } from "./nodefony/src/rateLimit/MemoryRateLimitStore.js";
 export type { IRateLimitStore, IRateLimitOptions, RateLimitVerdict, } from "./nodefony/src/rateLimit/IRateLimitStore.js";
 export { Context, Session, SessionsService, HttpError, HttpKernel, Response, Http2Response, Response as HttpResponse, wsResponse, wsResponse as WebsocketResponse, Cookie, HttpContext, WebsocketContext, HttpRequest, Http2Request, DefaultErrorRenderer, DefaultRequestLogger, JsonAuditLogger, PrettyRequestLogger, Profiler, };
+export { SseStream, openSseStream, acceptsEventStream, SSE_HEARTBEAT_MS, } from "./nodefony/src/context/http/SseStream.js";
+export type { ISseStreamOptions, ISseSendOptions, } from "./nodefony/src/context/http/SseStream.js";
 export { schemaMismatchOf, type SchemaMismatchConfidence, } from "./nodefony/service/error-renderer.js";
-export type { ProfileEntry, ProfileSummary, ProfilePhase, ProfileQuery, ProfileSecurity, } from "./nodefony/src/profiler/Profiler.js";
+export { toValidationFields, type IValidationField, } from "./nodefony/service/error-renderer.js";
+export type { ProfileEntry, ProfileSummary, ProfilePhase, ProfileQuery, ProfileSecurity, IProfileBatch, IProfilerReader, } from "./nodefony/src/profiler/Profiler.js";
+export { aggregateProfiles, createProfileAggregator, isFailedProfile, sqlShape, N_PLUS_ONE_MIN_REPEATS, ACTION_SELF_PHASE, NO_ROUTE, TOOLING_URL_PREFIX, } from "./nodefony/src/profiler/aggregate.js";
+export type { IProfileAggregator, IProfileAggregatorOptions, IProfileReport, IRouteStats, IStatusBreakdown, IPhaseTotal, INPlusOne, ISqlShapeStats, IErrorSample, } from "./nodefony/src/profiler/aggregate.js";
 export { FrameProfile } from "./nodefony/src/profiler/FrameProfile.js";
 export type { FrameProfileInit, ProfiledArea, ProfiledResolver, } from "./nodefony/src/profiler/FrameProfile.js";
+export { default as ReverseProxy } from "./nodefony/service/reverse-proxy.js";
+export { parseProxyOrigin, normalizePrefix, proxyMountProblems, } from "./nodefony/src/proxy/rules.js";
+export type { IProxyMount, IProxyMountOptions, ProxyTarget, } from "./nodefony/interfaces/IReverseProxy.js";
 export { resolveUiDelivery, PrebuiltUi, } from "./nodefony/src/assets/prebuiltUi.js";
 export type { UiDeliveryMode, UiDeliveryResolved, IUiDeliveryResolution, IUiDeliveryOptions, IPrebuiltUiOptions, } from "./nodefony/src/assets/prebuiltUi.js";
-export type { IContext, IHttpContext, IWebsocketContext, ServerType, SchemeType, WebSocketStateType, CookiesMap, ISecurityTrace, SecurityOutcome, } from "./nodefony/interfaces/IContext.js";
+export type { IContext, IHttpContext, IWebsocketContext, IWebsocketConnectionState, ServerType, ProtocolName, AlpnProtocol, SchemeType, WebSocketStateType, CookiesMap, ISecurityTrace, SecurityOutcome, } from "./nodefony/interfaces/IContext.js";
 export type { ICookie, ICookieOptions, IWsCookie, SameSiteType, PriorityType, } from "./nodefony/interfaces/ICookie.js";
 export type { ISession, ISessionStorage, ISerializedSession, ISessionSummary, ISessionRecord, ISessionListFilter, ISessionListQuery, SessionIntent, SessionStatusType, SessionStrategyType, FlashBagType, MetaBagType, } from "./nodefony/interfaces/ISession.js";
 export { SESSION_SORTABLE_FIELDS, SESSION_DEFAULT_ORDER, SESSION_DEFAULT_ORDER_SQL, SESSION_COLUMN_ALIASES, } from "./nodefony/src/session/storage/sessionSort.js";
-export type { IHttpRequest, IHttp2Request, IWsRequest, HTTPMethodType, } from "./nodefony/interfaces/IRequest.js";
+export type { IHttpRequest, RequestBody, IHttp2Request, IWsRequest, HTTPMethodType, } from "./nodefony/interfaces/IRequest.js";
 export type { IHttpResponse, IWebsocketResponse, } from "./nodefony/interfaces/IResponse.js";
 export type { IHttpKernel } from "./nodefony/interfaces/IHttpKernel.js";
 export type { IResolvedRoute, IRouteResolver, IRequestRouter, } from "./nodefony/interfaces/IRouting.js";

package/dist/types/nodefony/config/config.d.ts

@@ -67,6 +67,7 @@ export declare const httpConfigSchema: z.ZodObject<{
         key: z.ZodDefault<z.ZodString>;
         cert: z.ZodDefault<z.ZodString>;
         privateKeyMode: z.ZodDefault<z.ZodNumber>;
+        extraCaFiles: z.ZodDefault<z.ZodArray<z.ZodString>>;
         san: z.ZodDefault<z.ZodObject<{
             dns: z.ZodDefault<z.ZodArray<z.ZodString>>;
             ip: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -184,6 +185,21 @@ export declare const httpConfigSchema: z.ZodObject<{
         readinessPath: z.ZodDefault<z.ZodString>;
         shutdownDelay: z.ZodDefault<z.ZodNumber>;
     }, z.core.$loose>>;
+    proxy: z.ZodDefault<z.ZodObject<{
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        connectTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        maxSockets: z.ZodDefault<z.ZodNumber>;
+        mounts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            target: z.ZodString;
+            methods: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            websocket: z.ZodDefault<z.ZodBoolean>;
+            stripPrefix: z.ZodDefault<z.ZodBoolean>;
+            preserveHost: z.ZodDefault<z.ZodBoolean>;
+            stripHeaders: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+            secure: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
     wsMaxConnectionsPerIp: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strict>;
 /** Type de sortie (config normalisée + défauts appliqués). */

package/dist/types/nodefony/interfaces/IContext.d.ts

@@ -3,7 +3,35 @@ import type { MaybePromise } from "nodefony";
 import type { ICookie } from "./ICookie.js";
 import type { ISession } from "./ISession.js";
 import type { HTTPMethodType } from "./IRequest.js";
-export type ServerType = "http" | "https" | "http2" | "http3" | "websocket" | "websocket-secure";
+/**
+ * Identité du serveur qui a reçu la requête, nommée par le schéma d'URI qu'il
+ * sert en LOCAL (RFC 9110 §4.2, RFC 6455 §3) : elle choisit la section de
+ * configuration du serveur (`http`, `https`, `websocket`, `websocketSecure`).
+ * Ce n'est PAS un protocole — `https` sert HTTP/1.1 et h2 sur le même port ;
+ * le protocole du saut se lit dans {@link AlpnProtocol}.
+ */
+export type ServerType = "http" | "https" | "ws" | "wss";
+/**
+ * Famille du protocole que le contrôleur traite, nommée comme l'attribut
+ * OpenTelemetry `network.protocol.name`.
+ *
+ * Union OUVERTE : une valeur peut apparaître en version mineure
+ * (`"webtransport"` sur HTTP/3) — pas de `switch` exhaustif sans `default`.
+ */
+export type ProtocolName = "http" | "websocket";
+/**
+ * Protocole du saut qui atteint CE processus, nommé par le registre IANA des
+ * identifiants ALPN — la valeur même que Node expose (`TLSSocket.alpnProtocol`,
+ * `Http2Session.alpnProtocol`, qui vaut `"h2c"` sur une session en clair).
+ *
+ * Union OUVERTE : `"h3"` s'ajoutera en version mineure, sans rupture.
+ */
+export type AlpnProtocol = "http/1.1" | "h2" | "h2c";
+/**
+ * Schéma d'URI vu par le CLIENT (RFC 9110 §4.2, RFC 6455 §3) : derrière un
+ * proxy de confiance, c'est le schéma qu'il a annoncé (`Forwarded`), pas
+ * celui du saut local. Toute décision de sécurité lit ce champ.
+ */
 export type SchemeType = "http" | "https" | "ws" | "wss";
 export type WebSocketStateType = "handshake" | "connected" | "closed" | "error" | "message" | null;
 export type CookiesMap = Record<string, ICookie>;
@@ -67,8 +95,14 @@ export interface IContext {
     csrfProtect: boolean;
     csrfExempt: boolean;
     csrfToken: string | null;
-    type: ServerType;
+    /** Famille traitée : `"http"` ou `"websocket"` (union ouverte). */
+    type: ProtocolName;
+    /** Schéma vu par le client — seul champ que lit une décision de sécurité. */
     scheme: SchemeType;
+    /** Protocole du saut local : `"http/1.1"`, `"h2"`, `"h2c"` (union ouverte). */
+    alpnProtocol: AlpnProtocol;
+    /** Serveur qui a reçu la requête — choisit la configuration par serveur. */
+    serverType: ServerType;
     method: HTTPMethodType | null;
     url: string;
     domain: string;
@@ -86,6 +120,8 @@ export interface IContext {
     cookieSession: ICookie | null | undefined;
     cookies: CookiesMap;
     user: unknown;
+    /** Identifiant de l'appelant authentifié (pare-feu), lisible au démontage. */
+    userIdentifier: string | null;
     error: Error | null | undefined;
     metaData: object;
     readonly phases: PhaseTiming[];
@@ -137,13 +173,38 @@ export interface IHttpContext extends IContext {
     getHost(): string | undefined;
     getUserAgent(): string | undefined;
 }
-export interface IWebsocketContext extends IContext {
+/**
+ * Ce qu'un module attache à une connexion WebSocket pour toute sa durée — interface
+ * VIDE par construction, qu'un module AUGMENTE par fusion de déclarations.
+ *
+ * `@nodefony/http` ignore les protocoles bâtis au-dessus de la socket (le JSON-RPC
+ * de `@nodefony/realtime`, par exemple) et ne peut pas les importer. Le module qui
+ * en porte un déclare son champ ici : {@link IWebsocketContext} et `WebsocketContext`
+ * le reçoivent typé, sans conversion chez le lecteur et sans rien coûter à
+ * l'exécution — la lecture reste un accès de champ ordinaire.
+ *
+ * Chaque champ se déclare OPTIONNEL : il n'existe qu'une fois posé par son module
+ * (à la poignée de main, en général), et vaut `undefined` avant, comme sur toute
+ * connexion que ce module ne sert pas.
+ *
+ * @example
+ * ```ts
+ * declare module "@nodefony/http" {
+ *   interface IWebsocketConnectionState {
+ *     myProtocol?: IMyProtocolState;
+ *   }
+ * }
+ * ```
+ */
+export interface IWebsocketConnectionState {
+}
+export interface IWebsocketContext extends IContext, IWebsocketConnectionState {
     acceptedProtocol?: string | undefined;
     connection: unknown;
     rejected: boolean;
     port: number | string;
     wsUrl: URL | null;
-    queryGet: Record<string, string>;
+    query: Record<string, string>;
     connect(): Promise<unknown>;
     handle(data?: unknown[]): Promise<object>;
     close(reasonCode: number, description: string): unknown;

package/dist/types/nodefony/interfaces/IErrorRenderer.d.ts

@@ -46,7 +46,7 @@ export interface IErrorWebsocketResult {
  *
  * Override via `httpKernel.setErrorRenderer(custom)` to customise:
  *   - hide stack traces in prod
- *   - emit RFC 7807 problem+json
+ *   - emit RFC 9457 problem+json
  *   - inject auth challenge headers
  */
 export interface IErrorRenderer {

package/dist/types/nodefony/interfaces/IRequest.d.ts

@@ -8,12 +8,18 @@ export interface IRequest {
     getHeader(name: string): string | string[] | undefined;
     getHeaders(): Record<string, string | string[] | undefined>;
 }
+/**
+ * Le corps DÉCODÉ d'une requête : un objet (JSON, formulaire, champs
+ * multipart, XML), une chaîne (`text/*`), ou des octets (`Uint8Array` — tout
+ * autre type, et un corps sans `Content-Type`). Le même type d'octets que la
+ * socket temps réel : un schéma de route valide l'un comme l'autre.
+ */
+export type RequestBody = Record<string, unknown> | string | Uint8Array;
 export interface IHttpRequest extends IRequest {
     url: URL;
     query: Record<string, unknown>;
-    queryGet: Record<string, unknown>;
-    queryPost: Record<string, unknown>;
-    queryFile: unknown[];
+    body: RequestBody;
+    files: readonly unknown[];
     remoteAddress: string | null | undefined;
     acceptHtml: boolean;
     getRemoteAddress(): string | null | undefined;
@@ -29,7 +35,6 @@ export interface IHttp2Request extends IHttpRequest {
 export interface IWsRequest extends IRequest {
     url: URL;
     query: Record<string, string>;
-    queryGet: Record<string, string>;
     path: string;
     cookies?: Record<string, ICookie>;
 }

package/dist/types/nodefony/interfaces/IReverseProxy.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Origine d'un amont relayé : `scheme://hôte[:port]`, sans chemin.
+ *
+ * Une fonction quand l'origine n'est connue qu'à l'exécution (un serveur
+ * enfant qui choisit son port au démarrage) : elle est rappelée à chaque
+ * requête, et `undefined` signifie « l'amont n'est pas prêt » — la requête
+ * reçoit `503` (`Retry-After: 1`), l'upgrade WebSocket `503` avant tout `101` :
+ * le préfixe appartient à l'amont, le routage n'a rien à y répondre.
+ */
+export type ProxyTarget = string | (() => string | undefined);
+/**
+ * Réglages d'un montage du proxy inverse (`ReverseProxy.mount`).
+ *
+ * Les défauts sont ceux d'un relais sans surprise : toutes les méthodes, le
+ * chemin transmis tel quel, l'en-tête `Host` réécrit sur la cible, aucun
+ * en-tête retiré au-delà des en-têtes de connexion, certificat de la cible
+ * vérifié.
+ */
+export interface IProxyMountOptions {
+    /** Origine de l'amont (cf {@link ProxyTarget}). */
+    target: ProxyTarget;
+    /**
+     * Méthodes relayées (majuscules). Une autre méthode n'est PAS relayée : la
+     * requête poursuit jusqu'au routage. Absent = toutes.
+     */
+    methods?: readonly string[] | undefined;
+    /**
+     * Relaie aussi l'upgrade WebSocket du préfixe. Sans ce drapeau, un upgrade
+     * sur le préfixe reste au serveur WebSocket de Nodefony.
+     */
+    websocket?: boolean | undefined;
+    /**
+     * Retire le préfixe avant de transmettre le chemin (`/svc/a` → `/a`).
+     * Défaut `false` : l'amont reçoit le chemin complet — c'est le cas d'un
+     * serveur qui connaît déjà son préfixe (Vite et son `base`).
+     */
+    stripPrefix?: boolean | undefined;
+    /**
+     * Garde l'en-tête `Host` du client au lieu de le réécrire sur la cible.
+     * Défaut `false` : un amont qui filtre les noms d'hôte (Vite et son
+     * `allowedHosts`) reçoit le sien, et le nom d'origine part dans
+     * `X-Forwarded-Host`.
+     */
+    preserveHost?: boolean | undefined;
+    /**
+     * En-têtes de requête à ne pas transmettre (insensible à la casse) — ce
+     * dont l'amont n'a pas l'usage ne doit pas lui parvenir (`cookie`,
+     * `authorization` vers un serveur de sources, par exemple).
+     */
+    stripHeaders?: readonly string[] | undefined;
+    /**
+     * Délai d'inactivité de l'échange avec l'amont, en ms. Dépassé avant la
+     * réponse : 504. Absent = `proxy.timeoutMs` de la configuration (30 s par
+     * défaut). Ne s'applique pas à un WebSocket établi.
+     */
+    timeoutMs?: number | undefined;
+    /**
+     * Vérifie le certificat d'une cible `https:`. Défaut `true` — `false` n'est
+     * ACCEPTÉ que vers la boucle locale (refus au montage sinon).
+     */
+    secure?: boolean | undefined;
+}
+/** Un montage tel que le proxy le garde : préfixe normalisé + réglages. */
+export interface IProxyMount extends IProxyMountOptions {
+    /** Préfixe d'URL normalisé (`/` en tête et en fin). */
+    readonly prefix: string;
+}

package/dist/types/nodefony/interfaces/IRouting.d.ts

@@ -60,6 +60,16 @@ export interface IRouteResolver {
      *   n'attendent, sinon sa promesse
      */
     callController(data?: unknown[], reload?: boolean): MaybePromise<unknown>;
+    /**
+     * Juge les gardes de l'action résolue (`@IsGranted`, `@RequireScope`,
+     * step-up, rôle de la zone) SANS l'exécuter — le pipeline WebSocket l'appelle
+     * avant d'accepter le handshake, pour qu'un refus parte en statut HTTP. Un
+     * verdict favorable vaut pour la PROCHAINE exécution, qui ne le rejuge pas.
+     *
+     * @returns `undefined` quand l'action n'est pas gardée ; sinon la promesse du
+     *   verdict, rompue par un refus (401/403)
+     */
+    authorizeAction(): Promise<void> | undefined;
 }
 /**
  * Ce que le pipeline HTTP/WS attend du service `router` — implémenté par
@@ -75,6 +85,22 @@ export interface IRequestRouter {
      * @returns le résolveur (`resolve === true` si une route a matché)
      */
     resolve(context: ContextType, cleanPathOverride?: string, methodOverride?: string): IRouteResolver;
+    /**
+     * Dit si au moins une route déclare le transport `WEBSOCKET` pour ce chemin.
+     *
+     * Lu AVANT le `101` : une socket vers un chemin sans route se refuse par un
+     * statut HTTP (RFC 6455 §4.2.2), jamais par une ouverture suivie d'une
+     * fermeture — un client qui sonde par une ouverture conclurait que le
+     * serveur l'a acceptée. La réponse est un SUR-ENSEMBLE de ce que
+     * {@link IRequestRouter.resolve} acceptera : l'hôte (`@Domain`), le
+     * sous-protocole et les exigences de variables ne sont pas jugés ici, ils
+     * restent des fermetures après ouverture — refuser à tort coûterait une
+     * connexion légitime.
+     *
+     * @param pathname - chemin de l'URL d'upgrade (WHATWG), barres finales comprises
+     * @returns `false` si aucune route WebSocket ne peut répondre à ce chemin
+     */
+    servesWebsocket(pathname: string): boolean;
     /**
      * Instance partagée d'un controller `scope: "singleton"`, créée une seule fois.
      *

package/dist/types/nodefony/interfaces/ISecurity.d.ts

@@ -42,4 +42,10 @@ export interface IFirewallGate {
     handleCors(context: ContextType): number | undefined;
     /** Pose les en-têtes de sécurité (CSP, HSTS…) de la réponse. */
     applySecurityHeaders(context: ContextType): void;
+    /**
+     * Le revalidateur de l'identité authentifiée de la requête courante, pour une
+     * connexion longue qui la gardera (flux SSE) : la même règle que les sockets
+     * WebSocket. `null` pour un anonyme — rien à révoquer.
+     */
+    currentRevalidator?(): ((nowMs?: number) => Promise<boolean>) | null;
 }

package/dist/types/nodefony/interfaces/index.d.ts

@@ -1,9 +1,10 @@
 export type { ICookie, ICookieOptions, IWsCookie, SameSiteType, PriorityType, } from "./ICookie.js";
 export type { ISession, ISessionStorage, ISerializedSession, SessionIntent, SessionStatusType, SessionStrategyType, FlashBagType, MetaBagType, } from "./ISession.js";
 export type { IUploadedFile, IUploadService, IParsedUploadFile, IUploadOptions, } from "./IUpload.js";
-export type { IRequest, IHttpRequest, IHttp2Request, IWsRequest, HTTPMethodType, } from "./IRequest.js";
+export type { IRequest, IHttpRequest, RequestBody, IHttp2Request, IWsRequest, HTTPMethodType, } from "./IRequest.js";
 export type { IResponse, IHttpResponse, IWebsocketResponse } from "./IResponse.js";
-export type { IContext, IHttpContext, IWebsocketContext, ServerType, SchemeType, WebSocketStateType, CookiesMap, } from "./IContext.js";
+export type { IContext, IHttpContext, IWebsocketContext, ServerType, ProtocolName, AlpnProtocol, SchemeType, WebSocketStateType, CookiesMap, } from "./IContext.js";
 export type { IHttpKernel } from "./IHttpKernel.js";
 export type { IResolvedRoute, IRouteResolver, IRequestRouter, } from "./IRouting.js";
 export type { ISecurityZone, IFirewallGate } from "./ISecurity.js";
+export type { IProxyMount, IProxyMountOptions, ProxyTarget, } from "./IReverseProxy.js";

package/dist/types/nodefony/service/audit-logger.d.ts

@@ -17,7 +17,8 @@ import type { IHttpContext, IWebsocketContext, PhaseTiming } from "../interfaces
 export interface AuditLogEntry {
     ts: string;
     requestId: string;
-    userId: string | null;
+    /** Identifiant de l'appelant authentifié (`context.userIdentifier`), `null` sinon. */
+    userIdentifier: string | null;
     type: "http" | "ws";
     scheme: string;
     method: string | null;

package/dist/types/nodefony/service/certificates.d.ts

@@ -1,6 +1,138 @@
 import { Service, Module } from "nodefony";
 import { type KeyObject } from "node:crypto";
 import { type ICertificateAttribute } from "./x509.js";
+/**
+ * Accès à la liste d'ancres TLS par défaut du processus — injectable pour
+ * éprouver la décision sans toucher la confiance du processus de test.
+ */
+export interface ITlsTrustStore {
+    getCACertificates?: (type?: "default") => string[];
+    setDefaultCACertificates?: (certs: ReadonlyArray<string>) => void;
+}
+/** Issue de {@link addDefaultCaCertificate}, CONSTATÉE à l'exécution. */
+export type CaTrustVerdict = "added" | "present" | "unsupported";
+/**
+ * Ajoute une autorité aux ancres TLS par défaut du processus (requêtes sortantes
+ * `fetch`, `https`, `tls.connect`), sans en retirer aucune.
+ *
+ * C'est l'équivalent en cours d'exécution de `NODE_EXTRA_CA_CERTS`, qui n'est lu
+ * qu'au lancement du processus — trop tôt pour une CA que le boot vient de
+ * générer, et que seul un script de banc posait. La capacité se CONSTATE
+ * (`tls.setDefaultCACertificates` n'existe qu'à partir de Node 24.5), elle ne se
+ * déduit pas d'un numéro de version. Idempotent : une autorité déjà présente
+ * n'est pas ajoutée deux fois.
+ *
+ * @param pem - autorité au format PEM.
+ * @param store - accès aux ancres ; `node:tls` par défaut.
+ * @returns `added`, `present` (déjà de confiance), ou `unsupported`.
+ */
+export declare function addDefaultCaCertificate(pem: string, store?: ITlsTrustStore): CaTrustVerdict;
+/**
+ * Découpe un fichier PEM en ses certificats — une chaîne d'entreprise est
+ * souvent livrée en un seul fichier (racine + intermédiaires).
+ *
+ * Chaque certificat est ajouté SÉPARÉMENT : c'est ce qui rend l'ajout
+ * idempotent certificat par certificat, la liste par défaut du processus
+ * n'étant faite que de certificats isolés.
+ *
+ * @param pem - contenu d'un fichier PEM (un ou plusieurs certificats)
+ * @returns les certificats, dans l'ordre du fichier ; vide s'il n'y en a aucun
+ */
+export declare function splitPemCertificates(pem: string): string[];
+/** Bilan de {@link trustCaFile}. */
+export interface ICaFileTrust {
+    /** Fichier lu, chemin absolu. */
+    readonly file: string;
+    /** Certificats ajoutés aux ancres du processus. */
+    readonly added: number;
+    /** Certificats déjà de confiance. */
+    readonly present: number;
+}
+/**
+ * Ajoute les autorités d'un fichier PEM aux ancres TLS du processus
+ * (`certificates.extraCaFiles`) — l'équivalent, porté par l'APPLICATION, de
+ * `NODE_EXTRA_CA_CERTS`.
+ *
+ * `NODE_EXTRA_CA_CERTS` n'est lu qu'au lancement de Node, et se pose dans la
+ * syntaxe du shell — `VAR=… npm run dev` n'existe pas sous Windows. Une autorité
+ * d'entreprise (Keycloak interne, proxy sortant qui ré-signe) se déclare donc
+ * dans la configuration, et sert à TOUTES les requêtes sortantes du processus :
+ * découverte OpenID, point de jeton, jeu de clés, appels d'administration.
+ *
+ * @param file - chemin du fichier, absolu ou relatif à `root`
+ * @param root - racine de l'application
+ * Chaque refus dit le problème, d'où vient le chemin quand on le sait, puis le
+ * geste qui répare ({@link caFileRemedy}).
+ *
+ * @param store - accès aux ancres ; `node:tls` par défaut
+ * @param origin - phrase qui dit d'où vient le chemin (` Valeur venue de …`), insérée dans un refus
+ * @returns le bilan de l'ajout
+ * @throws BootConfigurationError - fichier illisible, sans certificat, ou Node
+ *         incapable d'élargir ses ancres en cours d'exécution
+ */
+export declare function trustCaFile(file: string, root: string, store?: ITlsTrustStore, origin?: string): Promise<ICaFileTrust>;
+/**
+ * Le geste qui répare une autorité déclarée qu'on ne peut pas reconnaître.
+ *
+ * Un refus au démarrage qui ne dit que la cause envoie chercher ; celui-ci dit
+ * quoi faire. Pure : éprouvée cause par cause, y compris celles qu'une machine
+ * de test ne sait pas produire (un droit refusé ne l'est pas à `root`, ni
+ * sous Windows).
+ *
+ * @param cause - code système (`ENOENT`, `EACCES`, `EPERM`, `EISDIR`),
+ *   `NOPEM` pour un fichier lu sans certificat, ou tout autre motif
+ * @returns la phrase du geste
+ */
+export declare function caFileRemedy(cause: string): string;
+/**
+ * Dossier où Nodefony range les certificats qu'il fabrique en développement,
+ * relatif au répertoire courant.
+ *
+ * @returns le chemin absolu de `nodefony/config/certificates`
+ */
+export declare function certificatesDirectory(): string;
+/**
+ * Chemin de l'autorité de DÉVELOPPEMENT : le certificat racine que Nodefony
+ * fabrique lui-même pour signer le certificat du serveur local. Généré, jamais
+ * versionné — une seule convention, que le service et la confiance sortante lisent.
+ *
+ * @param directory - dossier des certificats ; {@link certificatesDirectory} par défaut
+ * @returns le chemin absolu du fichier PEM de l'autorité
+ */
+export declare function developmentAuthorityPath(directory?: string): string;
+/** Décor de {@link trustOutboundAuthorities} — injectable pour l'éprouver. */
+export interface IOutboundTrustContext {
+    /** Vrai en développement : seul décor où l'autorité de dev absente est tolérée. */
+    readonly development?: boolean;
+    /** Chemin absolu de l'autorité de développement ; {@link developmentAuthorityPath} par défaut. */
+    readonly developmentAuthority?: string;
+    /** Environnement lu pour nommer la variable d'origine ; `process.env` par défaut. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Accès aux ancres ; `node:tls` par défaut. */
+    readonly store?: ITlsTrustStore;
+}
+/**
+ * Ajoute aux ancres TLS du processus les autorités déclarées
+ * (`certificates.extraCaFiles`), au plus tôt : appelé à l'enregistrement du
+ * module, avant tout service — toute requête sortante, commande console
+ * comprise, les trouve en place.
+ *
+ * L'autorité de DÉVELOPPEMENT déclarée mais pas encore engendrée est ignorée en
+ * développement, et le journal le dit : elle n'a signé aucun certificat, il n'y
+ * a donc rien à lui faire confiance, et le serveur de développement la pose
+ * lui-même quand il la fabrique ({@link Certificate.generateServerCertificates}).
+ * Rien n'est fabriqué ici : une commande console n'écrit pas de certificat.
+ * Une autre autorité absente, ou n'importe laquelle hors développement, reste
+ * un refus — qui nomme la variable d'origine et le geste qui répare
+ * ({@link caFileRemedy}).
+ *
+ * @param files - `certificates.extraCaFiles`
+ * @param root - racine de l'application
+ * @param log - journal du module
+ * @param context - décor (environnement, autorité de dev, ancres)
+ * @throws BootConfigurationError - cf {@link trustCaFile}
+ */
+export declare function trustOutboundAuthorities(files: readonly string[], root: string, log: (message: string, severity: "INFO") => void, context?: IOutboundTrustContext): Promise<void>;
 /** Paire de clés RSA du certificat auto-signé. */
 export interface IRsaKeyPair {
     privateKey: KeyObject;
@@ -102,7 +234,7 @@ export interface CertificateInfo {
  *
  * Conformité (génération auto-signée) : signature SHA-256 (jamais SHA-1,
  * RFC 5280 / CA-B Forum), numéro de série aléatoire 128 bits unique
- * (RFC 5280 §4.1.2.2), SAN qui fait foi (RFC 6125), `notBefore` reculé,
+ * (RFC 5280 §4.1.2.2), SAN qui fait foi (RFC 9525), `notBefore` reculé,
  * clé privée écrite en `0600`.
  */
 declare class Certificate extends Service {
@@ -114,8 +246,6 @@ declare class Certificate extends Service {
     cert: Buffer | string | null;
     fullchainPem: Buffer | string | null;
     publicKeyPem: Buffer | string | null;
-    rootCertPem: Buffer | string | null;
-    intermediateCertPem: Buffer | string | null;
     /** CAROOT résolu de mkcert (null tant que non détecté / indisponible). */
     private mkcertCaRoot;
     path: string;
@@ -173,6 +303,18 @@ declare class Certificate extends Service {
      * @param force - forcer la régénération même si un certificat valide existe
      */
     generateServerCertificates(force?: boolean): Promise<this>;
+    /**
+     * En développement, fait confiance à la CA que Nodefony vient de générer ou de
+     * relire, pour les requêtes SORTANTES du processus.
+     *
+     * Sans elle, un service du décor qui sert le certificat de l'application
+     * (Keycloak, l'auto-vérification d'un jeton MCP) est injoignable depuis
+     * `nodefony development` — `fetch failed` / `SELF_SIGNED_CERT_IN_CHAIN` — alors
+     * que `curl -k` répond : la confiance n'existait que sous le script de banc.
+     * Réservé au DÉVELOPPEMENT et aux certificats que Nodefony fabrique : un
+     * certificat `explicit` (production) n'élargit jamais la confiance du processus.
+     */
+    private trustDevelopmentAuthority;
     /**
      * Résout la stratégie effective à partir de `certificates.strategy` :
      * - `explicit` : `key` + `cert` fournis (prod, Let's Encrypt…). Forcé →
@@ -193,7 +335,7 @@ declare class Certificate extends Service {
     /**
      * SAN effectif : config explicite si fournie, sinon dérivé du kernel
      * (localhost + domain en DNS ; loopback en IP). Une IP littérale (ex. domain
-     * `127.0.0.1` en dev) est classée en `ip`, pas en `dns` (RFC 6125).
+     * `127.0.0.1` en dev) est classée en `ip`, pas en `dns` (RFC 9525).
      */
     private derivedSan;
     /** Hostnames DNS couverts par le SAN. */
@@ -217,7 +359,7 @@ declare class Certificate extends Service {
      * @returns false si absent, illisible ou inadéquat → déclenche la régénération.
      */
     private isCertAdequate;
-    /** Le SAN présent couvre-t-il tous les noms DNS requis (RFC 6125) ? */
+    /** Le SAN présent couvre-t-il tous les noms DNS requis (RFC 9525) ? */
     private sanCovers;
     /** Charge un certificat fourni en config (chemin fichier ou Buffer). */
     private loadExplicitCert;

package/dist/types/nodefony/service/error-renderer.d.ts

@@ -1,5 +1,36 @@
 import type { IErrorRenderer, IErrorHttpResult, IErrorWebsocketResult } from "../interfaces/IErrorRenderer.js";
 import type { IHttpContext, IWebsocketContext } from "../interfaces/IContext.js";
+/** Champ fautif, tel qu'exposé au client dans le corps JSON (`error.fields`). */
+export interface IValidationField {
+    /** Chemin pointé du champ (`"author.email"`). */
+    field: string;
+    /** Message lisible. */
+    message: string;
+    /** Contrôle qui a échoué (`too_small`…) — utile au client pour réagir finement. */
+    rule?: string | undefined;
+    /**
+     * Partie de l'entrée qui porte le champ (`body`, `query`, `params`,
+     * `headers`) — présente pour une route à schéma, où deux parties peuvent
+     * porter le même nom. `field` reste relatif à sa partie : un formulaire le
+     * relie à son champ de saisie sans rien retirer.
+     */
+    in?: string | undefined;
+}
+/**
+ * Reconnaît une erreur de validation — `ZodError`, ou `SchemaValidationError`
+ * d'une route à schéma — et en extrait les champs fautifs.
+ *
+ * Reconnaissance **structurelle** (`name` + `issues`), pas `instanceof ZodError` :
+ * une application peut embarquer sa propre copie de zod (résolutions npm multiples),
+ * et `instanceof` échouerait alors en silence — la validation retomberait en 500.
+ * Même parti-pris que le duck-typing de `isPromise` dans le framework.
+ *
+ * Ne coûte rien au chemin nominal : ce code ne tourne que sur une erreur déjà levée.
+ *
+ * @param error - erreur remontée par le pipeline.
+ * @returns les champs fautifs, ou `null` si ce n'est pas une erreur de validation.
+ */
+export declare function toValidationFields(error: Error): IValidationField[] | null;
 /**
  * Reconnaît un identifiant MAL FORMÉ refusé par la base, et rend la valeur fautive.
  *
@@ -69,7 +100,7 @@ export declare function schemaMismatchOf(error: unknown): SchemaMismatchConfiden
  *   reason: error.message
  *
  * Stateless singleton — zero per-request allocation. Override via
- * `httpKernel.setErrorRenderer(custom)` for prod hardening or RFC 7807.
+ * `httpKernel.setErrorRenderer(custom)` for prod hardening or RFC 9457.
  */
 declare class DefaultErrorRenderer implements IErrorRenderer {
     renderHttp(error: Error, context: IHttpContext): IErrorHttpResult;