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

package/dist/types/nodefony/decorators/routerDecorators.d.ts

@@ -1,10 +1,12 @@
 import "reflect-metadata";
+import type { Readable } from "node:stream";
 import { TypeController } from "../service/router.js";
 import { RouteOptions } from "../src/Route.js";
 import Controller from "../src/Controller.js";
 import type { ControllerScope } from "../src/Controller.js";
 import { Module } from "nodefony";
 import { ControllerConstructor } from "../src/Route.js";
+import type { IRouteSchema, RawRouteInput, RouteInput } from "../src/routeSchema.js";
 import type { SessionIntent } from "@nodefony/http";
 type Constructor<T = {}> = new (...args: any[]) => T;
 /**
@@ -66,7 +68,30 @@ declare function controller(prefix: string): <T extends ControllerConstructor &
  *   return this.renderJson({ name });
  * }
  */
-declare function route(name: string, options: RouteOptions): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+declare function route(name: string, options: RouteOptions & {
+    schema?: undefined;
+    bodyStream?: false;
+}): RouteMethodDecorator;
+declare function route<S extends IRouteSchema>(name: string, options: RouteOptionsWithSchema<S> & {
+    bodyStream?: false;
+}): SchemaRouteMethodDecorator<S, false>;
+declare function route<S extends IRouteSchema & {
+    readonly body?: undefined;
+}>(name: string, options: RouteOptionsWithSchema<S> & {
+    bodyStream: true;
+}): SchemaRouteMethodDecorator<S, true>;
+/** Options d'une route qui déclare un schéma. */
+type RouteOptionsWithSchema<S extends IRouteSchema> = RouteOptions & {
+    schema: S;
+};
+/** Décorateur de méthode d'une route sans schéma : la signature de l'action est libre. */
+type RouteMethodDecorator = (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Décorateur d'une action à schéma : la compilation refuse une action dont
+ * l'argument ne reçoit pas `RouteInput<S, Stream>` (champ absent du schéma,
+ * type divergent, second argument).
+ */
+type SchemaRouteMethodDecorator<S extends IRouteSchema, Stream extends boolean> = <T extends (input: RouteInput<S, Stream>) => unknown>(target: object, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T>;
 export declare const HTTP_CODE_METADATA = "route:httpCode";
 export declare const HEADERS_METADATA = "route:responseHeaders";
 export declare const REDIRECT_METADATA = "route:redirect";
@@ -158,19 +183,40 @@ export interface IdempotentMeta {
     readonly required: boolean;
 }
 type MethodDecoratorOptions = Omit<RouteOptions, "path" | "method">;
-declare const Get: (path?: string, options?: MethodDecoratorOptions) => (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
-declare const Post: (path?: string, options?: MethodDecoratorOptions) => (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
-declare const Put: (path?: string, options?: MethodDecoratorOptions) => (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
-declare const Delete: (path?: string, options?: MethodDecoratorOptions) => (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
-declare const Patch: (path?: string, options?: MethodDecoratorOptions) => (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
-declare const Options: (path?: string, options?: MethodDecoratorOptions) => (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
-declare const Head: (path?: string, options?: MethodDecoratorOptions) => (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Un décorateur de méthode HTTP (`@Get`, `@Post`…). Sans schéma, la signature
+ * de l'action est libre (décorateurs de paramètre) ; avec `schema`, l'action
+ * reçoit un argument unique `RouteInput<S>`, vérifié à la compilation.
+ */
+export interface IHttpMethodDecorator {
+    (path?: string, options?: MethodDecoratorOptions & {
+        schema?: undefined;
+        bodyStream?: false;
+    }): RouteMethodDecorator;
+    <S extends IRouteSchema>(path: string, options: MethodDecoratorOptions & {
+        schema: S;
+        bodyStream?: false;
+    }): SchemaRouteMethodDecorator<S, false>;
+    <S extends IRouteSchema & {
+        readonly body?: undefined;
+    }>(path: string, options: MethodDecoratorOptions & {
+        schema: S;
+        bodyStream: true;
+    }): SchemaRouteMethodDecorator<S, true>;
+}
+declare const Get: IHttpMethodDecorator;
+declare const Post: IHttpMethodDecorator;
+declare const Put: IHttpMethodDecorator;
+declare const Delete: IHttpMethodDecorator;
+declare const Patch: IHttpMethodDecorator;
+declare const Options: IHttpMethodDecorator;
+declare const Head: IHttpMethodDecorator;
 /**
  * `@All` — route sans restriction de méthode : matche **toutes** les méthodes
  * HTTP (équivalent NestJS `@All()`). N'émet aucun requirement `methods`, donc
  * `Route.matchRequirements` ne lève jamais 405 sur la méthode.
  */
-declare function All(path?: string, options?: MethodDecoratorOptions): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+declare const All: IHttpMethodDecorator;
 /**
  * Fixe le code de statut HTTP de la réponse d'une action.
  *
@@ -470,26 +516,18 @@ declare const Query: (key?: string) => (target: object, propertyKey: string, par
  *
  * ## Le corps n'est PAS validé — le type écrit ici ne promet rien
  *
- * `@Body()` injecte le corps **tel qu'il a été parsé** : `@Body() dto: CreateOrder`
- * compile, mais rien ne garantit qu'un `CreateOrder` soit arrivé. C'est un choix
- * assumé, pas un oubli — valider ici ne garderait que la porte HTTP, et devrait
- * rester **synchrone** ({@link resolveParamArg} l'est, et le rendre asynchrone
- * taxerait toute requête à paramètres décorés).
- *
- * Où valider, donc :
+ * `@Body()` injecte le corps **tel qu'il a été décodé** (objet JSON ou de
+ * formulaire, chaîne pour `text/*`, octets `Uint8Array` pour tout autre type) :
+ * `@Body() dto: CreateOrder` compile, mais rien ne garantit qu'un `CreateOrder`
+ * soit arrivé.
  *
- * - **Une entité** → les hooks `beforeCreate` / `beforeUpdate` d'
- *   `AbstractCrudService` : ils sont `await`és — donc une règle asynchrone
- *   (unicité en base) y est possible — et ils gardent REST, WebSocket **et** la
- *   CLI d'un seul geste. C'est ce que génère `nodefony create entity`.
- * - **Un cas isolé** → `schema.parse(body)` en première ligne de l'action, sur le
- *   modèle d'`assertPageQuery`. Rien d'autre à écrire : une `ZodError` qui remonte
- *   devient un **422** (RFC 9110 §15.5.21) portant `error.fields` — quel champ,
- *   quel message, quelle règle.
+ * Pour un contrat vérifié, déclarer l'option de route `schema` (ADR-0018) : le
+ * corps est validé AVANT l'action — 422 qui nomme chaque champ —, sur HTTP comme
+ * sur le pont WebSocket, et l'action le reçoit typé dans `input.body`. Une action
+ * à schéma ne prend aucun décorateur de paramètre.
  *
- * Et typer le paramètre avec `z.infer<typeof createXSchema>` plutôt qu'avec
- * `Partial<XRow>` : le premier décrit le contrat d'**entrée**, le second promet la
- * ligne de **table** (`id`, horodatages) que le schéma effacera de toute façon.
+ * Sans schéma, `schema.parse(body)` en première ligne de l'action reste le geste
+ * d'un cas isolé : une `ZodError` qui remonte devient le même **422**.
  *
  * @example
  * ```ts
@@ -524,20 +562,21 @@ export interface IParamArgContext {
     /**
      * Query de l'invocation courante quand elle ne vient PAS de l'URL du
      * transport — pont WS-RPC `api.request` (`Resolver.queryOverride`). Prime
-     * sur `request.queryGet` pour `@Query` uniquement (`@Req` reste le brut).
+     * sur `request.query` pour `@Query` uniquement (`@Req` reste le brut).
      */
     queryOverride?: Record<string, unknown> | undefined;
     request?: {
-        queryGet?: Record<string, unknown> | undefined;
-        queryPost?: Record<string, unknown> | undefined;
-        queryFile?: unknown[] | undefined;
+        query?: Record<string, unknown> | undefined;
+        /** Corps décodé : objet JSON, champs de formulaire, octets… */
+        body?: unknown;
+        files?: readonly unknown[] | undefined;
         headers?: Record<string, unknown> | undefined;
         /**
          * P2.9 — `IncomingMessage` brut (un `Readable`) sous-jacent au wrapper
          * `HttpRequest`. Injecté tel quel par `@Body({ stream: true })` (le pipeline
          * n'a pas consommé/parsé ce flux). `undefined` pour les contextes WS.
          */
-        request?: NodeJS.ReadableStream | undefined;
+        request?: Readable | undefined;
     } | null | undefined;
     response?: unknown;
     session?: {
@@ -545,6 +584,31 @@ export interface IParamArgContext {
     } | null | undefined;
     getRequestCookies(name?: string): unknown;
 }
+/**
+ * Le corps DÉCODÉ d'une invocation, depuis la requête seule — la règle de
+ * {@link readBody}, pour qui n'a pas de contexte de paramètres (porte
+ * d'idempotence).
+ *
+ * @param request - la requête du contexte.
+ * @returns le corps posé par le pont WebSocket, sinon le corps HTTP lu.
+ */
+export declare function readInvocationBody(request: IParamArgContext["request"]): unknown;
+/**
+ * L'entrée BRUTE d'une action à schéma, lue aux MÊMES sources que les
+ * décorateurs de paramètre ({@link readQuery}, {@link readBody}) : pont
+ * WebSocket compris. Seule allocation de la voie à schéma : cet objet, propre
+ * à l'invocation, que la validation complète en place et que l'action reçoit.
+ *
+ * Arguments POSITIONNELS, pas un objet de contexte : la voie à schéma n'en
+ * alloue aucun de plus.
+ *
+ * @param paramsMap - variables de route nommées.
+ * @param request - la requête du contexte.
+ * @param queryOverride - query du chemin invoqué (pont WebSocket), sinon rien.
+ * @param bodyStream - `true` : `body` est le flux brut, jamais lu.
+ * @returns les quatre parties, brutes.
+ */
+export declare function readRouteInput(paramsMap: Record<string, unknown>, request: IParamArgContext["request"], queryOverride: Record<string, unknown> | undefined, bodyStream: boolean): RawRouteInput;
 /**
  * Résout la valeur d'un unique paramètre décoré depuis le contexte de requête.
  *
@@ -562,7 +626,79 @@ declare function resolveParamArg(meta: ParamMeta, ctx: IParamArgContext): unknow
  * @param ctx - contexte de requête (forme structurelle minimale)
  * @returns arguments positionnels à spread dans l'action
  */
-declare function buildParamArgs(metas: ParamMeta[], ctx: IParamArgContext): unknown[];
+declare function buildParamArgs(metas: readonly ParamMeta[], ctx: IParamArgContext): unknown[];
+/**
+ * Ce qu'un `Context` — HTTP comme WebSocket — offre à la résolution des
+ * paramètres décorés. Forme structurelle : le framework n'importe pas les
+ * classes de contexte pour la lire.
+ */
+export interface IParamArgSource {
+    /** La requête du contexte (HTTP, ou l'upgrade d'une connexion WS). */
+    readonly request?: unknown;
+    /** La réponse du contexte. */
+    readonly response?: unknown;
+    /** La session, quand le contexte en porte une. */
+    readonly session?: unknown;
+    /** Lit un cookie de la requête, ou tous sans argument. */
+    getRequestCookies(name?: string): unknown;
+}
+/**
+ * Résout les paramètres décorés d'une action depuis un `Context` — la mise en
+ * forme UNIQUE, appelée par le Resolver (routes HTTP et WS) comme par les
+ * actions `@RealtimeAction`, pour qu'un décorateur ne puisse pas prendre deux
+ * sens selon le transport.
+ *
+ * Le corps d'un appel WebSocket voyage dans l'ALS (`RequestContext` clé
+ * `body`) et `@CurrentUser` y lit l'utilisateur : l'appelant pose la bulle,
+ * cette fonction n'en crée aucune.
+ *
+ * @param metas - paramètres décorés de l'action ({@link getParamArgsMeta})
+ * @param context - le contexte de la requête ou de la connexion
+ * @param paramsMap - variables de route nommées (vide hors route)
+ * @param queryOverride - query de l'invocation quand elle ne vient pas de l'URL
+ * @returns arguments positionnels à passer à l'action
+ */
+export declare function buildContextParamArgs(metas: readonly ParamMeta[], context: IParamArgSource, paramsMap: Record<string, unknown>, queryOverride?: Record<string, unknown>): unknown[];
+/**
+ * Les paramètres décorés d'une méthode (`@Body`, `@CurrentUser`…), ou `null`
+ * si elle n'en porte aucun. Lecture `Reflect` : à faire une fois, hors du
+ * chemin de chaque requête.
+ *
+ * @param proto - le prototype de la classe
+ * @param method - le nom de la méthode
+ * @returns les métadonnées, ou `null` — une action sans décorateur ne paie rien
+ */
+export declare function getParamArgsMeta(proto: object, method: string | symbol): readonly ParamMeta[] | null;
+/**
+ * Le schéma d'entrée d'une méthode (option de route `schema`), ou `null`.
+ * Lecture `Reflect` : à faire une fois, hors du chemin de chaque requête.
+ *
+ * @param proto - le prototype de la classe.
+ * @param method - le nom de la méthode.
+ * @returns le schéma, ou `null` — une action sans schéma ne paie rien.
+ * @throws BootConfigurationError si le schéma rangé est mal formé.
+ */
+export declare function getRouteSchema(proto: object, method: string): IRouteSchema | null;
+/**
+ * Refuse, au DÉMARRAGE, une action à schéma mal déclarée — appelé par
+ * `Router.setController` pour chaque route du contrôleur, pour qu'une faute
+ * ne se révèle pas à la première requête :
+ *
+ * - schéma mal formé (partie inconnue, valeur qui n'est pas un Standard Schema) ;
+ * - schéma ET décorateurs de paramètre (`@Body`…) : une action à schéma reçoit
+ *   un argument UNIQUE, les deux formes ne se combinent pas ;
+ * - `bodyStream: true` ET `schema.body` : un flux ne se valide pas.
+ *
+ * @param routeDef - la route (nom, contrôleur, méthode).
+ * @throws BootConfigurationError qui nomme la route.
+ */
+export declare function assertRouteSchemaDeclaration(routeDef: {
+    name: string;
+    controller?: {
+        prototype: object;
+    } | null | undefined;
+    classMethod?: string | undefined;
+}): void;
 /**
  * P2.9 — Indique si l'action d'une route attend le **flux brut** du body
  * (un paramètre `@Body({ stream:true })`). Le résultat est **mémoïsé** sur
@@ -588,7 +724,14 @@ declare function routeExpectsBodyStream(routeDef: {
  */
 export interface RouteActionMeta {
     /** Paramètres décorés (`@Param`/`@Body`/`@Query`…) — `null` si aucun. */
-    paramsMeta: ParamMeta[] | null;
+    paramsMeta: readonly ParamMeta[] | null;
+    /**
+     * Schéma d'entrée (`schema` de l'option de route) — `null` si l'action n'en
+     * déclare pas (cas courant → une comparaison, aucune allocation).
+     */
+    schema: IRouteSchema | null;
+    /** `bodyStream: true` déclaré en option de route. */
+    bodyStream: boolean;
     /** `@Redirect` de l'action — `null` si absent. */
     redirectMeta: RedirectMeta | null;
     /** `@HttpCode` de l'action — `null` si absent. */
@@ -603,6 +746,8 @@ export interface RouteActionMeta {
      * path (ni résolution de service, ni `decide`, ni await). Frozen, partagé.
      */
     security: SecurityRequirement | null;
+    /** `@RequireAuthentication` (fusion au plus strict) — `null` = 0 coût, frozen. */
+    authentication: IAuthenticationRequirement | null;
     /**
      * Directives CSP additionnelles (`@Csp`, fusion classe+méthode) — `null` si
      * l'action n'en déclare pas (cas courant → 0 composition CSP). Frozen, partagé.
@@ -649,4 +794,45 @@ declare function resolveActionMeta(routeDef: {
     classMethod?: string | undefined;
     actionMeta?: RouteActionMeta | undefined;
 }): RouteActionMeta;
-export { route, controller, controllers, Get, Post, Put, Delete, Patch, Options, Head, All, Domain, BypassFirewall, IsGranted, RequireScope, Anonymous, Csp, CsrfProtect, CsrfExempt, Idempotent, CurrentUser, Scope, UseSession, resolveSessionIntent, HttpCode, Header, Redirect, Param, Body, Query, Headers, Cookie, Session, Req, Res, UploadedFile, UploadedFiles, resolveParamArg, buildParamArgs, routeExpectsBodyStream, computeActionMeta, resolveActionMeta, extractActionScopes, };
+export { route, controller, controllers, Get, Post, Put, Delete, Patch, Options, Head, All, Domain, BypassFirewall, IsGranted, RequireScope, RequireAuthentication, Anonymous, Csp, CsrfProtect, CsrfExempt, Idempotent, CurrentUser, Scope, UseSession, resolveSessionIntent, HttpCode, Header, Redirect, Param, Body, Query, Headers, Cookie, Session, Req, Res, UploadedFile, UploadedFiles, resolveParamArg, buildParamArgs, routeExpectsBodyStream, computeActionMeta, resolveActionMeta, extractActionScopes, };
+/** Options de {@link RequireAuthentication}. */
+export interface IRequireAuthenticationOptions {
+    /** Âge maximal de la connexion, en secondes. Omis = aucune limite d'âge. */
+    readonly maxAge?: number;
+    /**
+     * Moyens d'authentification EXIGÉS, tous présents (RFC 8176) : `"pwd"` mot
+     * de passe, `"otp"` code à usage unique, `"pop"` clé d'accès. Omis = aucun.
+     */
+    readonly amr?: readonly string[];
+}
+/**
+ * Exigence d'authentification **figée** d'une action — fusion classe + méthode
+ * au plus strict (âge le plus court, moyens réunis), calculée UNE fois par
+ * route. Objet partagé entre requêtes : ne jamais muter.
+ */
+export interface IAuthenticationRequirement {
+    /** Âge maximal en secondes, `null` = sans limite. */
+    readonly maxAge: number | null;
+    /** Moyens exigés, tous présents. */
+    readonly amr: readonly string[];
+}
+/**
+ * Exige une connexion RÉCENTE et/ou faite avec certains moyens pour l'action
+ * (décorateur de méthode) ou tout le contrôleur (décorateur de classe).
+ *
+ * - `@RequireAuthentication({ maxAge: 300 })` — connexion de moins de 5 minutes.
+ * - `@RequireAuthentication({ amr: ["otp"] })` — second facteur exigé.
+ * - les deux se combinent ; classe + méthode fusionnent au plus strict.
+ *
+ * Lit ce que la session a retenu à son ouverture (`readSessionAuthentication`,
+ * ADR-0015) et s'évalue dans le `Resolver` APRÈS `@IsGranted` : un rôle absent
+ * reste un 403 définitif, une connexion trop ancienne ou trop faible devient un
+ * **401** dont le `WWW-Authenticate` porte
+ * `error="insufficient_user_authentication"` (RFC 9470) — le client sait qu'il
+ * doit redemander une connexion, pas que l'accès lui est fermé. Une session qui
+ * ne porte pas ces métadonnées est refusée, jamais acceptée.
+ *
+ * @param options - âge maximal et moyens exigés.
+ * @throws TypeError si `maxAge` n'est pas un entier positif ou si un moyen est vide.
+ */
+declare function RequireAuthentication(options?: IRequireAuthenticationOptions): (target: object, propertyKey?: string, descriptor?: PropertyDescriptor) => any;

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

@@ -10,10 +10,9 @@ export interface IController {
     context?: ContextType | undefined;
     session?: Session | null;
     method?: HTTPMethod | undefined;
-    queryGet: Record<string, unknown>;
     query: Record<string, unknown>;
-    queryFile: unknown[];
-    queryPost: Record<string, unknown>;
+    files: readonly unknown[];
+    body: Record<string, unknown>;
     module?: Module | undefined;
     setContext(context: ContextType): void;
     setContextJson(encoding?: BufferEncoding): unknown;

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

@@ -1,4 +1,4 @@
-import type { HTTPMethod, SchemeType, ContextType, IResolvedRoute } from "@nodefony/http";
+import type { HTTPMethod, ContextType, IResolvedRoute } from "@nodefony/http";
 import type { ControllerConstructor, RouteRequirements } from "../src/Route.js";
 export interface IRoute extends IResolvedRoute {
     name: string;
@@ -7,7 +7,6 @@ export interface IRoute extends IResolvedRoute {
     classMethod?: string | undefined;
     prefix?: string | undefined;
     method?: HTTPMethod | undefined;
-    schemes?: SchemeType | undefined;
     pattern?: RegExp | undefined;
     variables: unknown[];
     defaults: Partial<Record<string, unknown>>;

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

@@ -6,7 +6,16 @@ import type { IRequestRouter } from "@nodefony/http";
 import Resolver from "../src/Resolver.js";
 import Controller from "../src/Controller.js";
 export type TypeController<T> = new (...args: any[]) => T;
+/**
+ * Marque du Router de `@nodefony/framework` — ce que {@link isFrameworkRouter}
+ * lit. `Symbol.for` : la même marque pour deux copies installées du framework,
+ * là où `instanceof` échouerait en silence. Un faux routeur de test s'en
+ * réclame explicitement.
+ */
+export declare const FRAMEWORK_ROUTER: unique symbol;
 declare class Router extends Service implements IRequestRouter {
+    /** Marque {@link FRAMEWORK_ROUTER} — sur le prototype, aucun champ par instance. */
+    get [FRAMEWORK_ROUTER](): true;
     static routes: Route[];
     routes: Route[];
     private singletonControllers;
@@ -30,6 +39,19 @@ declare class Router extends Service implements IRequestRouter {
      *   cache, la requête suivante recrée.
      */
     getSingletonController<T extends object>(ctor: new (...args: never[]) => T, create: () => MaybePromise<T>): MaybePromise<T>;
+    /**
+     * Dit si au moins une route déclare le transport `WEBSOCKET` pour ce chemin
+     * — contrôle d'avant `101` du pipeline WebSocket (cf `IRequestRouter`).
+     *
+     * Parcours de la table entière, sans l'index de `resolve` : il est lu une
+     * fois par CONNEXION (pas par message), et une route dont les méthodes
+     * changent après coup (`addRequirement`) ne laisse ainsi aucun index périmé.
+     * Même normalisation que `resolve` (`stripTrailingSlashes`), même motif.
+     *
+     * @param pathname - chemin de l'URL d'upgrade
+     * @returns `true` si une route WebSocket a un motif qui couvre ce chemin
+     */
+    servesWebsocket(pathname: string): boolean;
     /**
      * Résout une route pour un contexte donné.
      *
@@ -42,7 +64,10 @@ declare class Router extends Service implements IRequestRouter {
      *   WEBSOCKET (pont WS-RPC `api.request` d'une MUTATION) : lève l'ambiguïté
      *   GET-via-WS / POST-via-WS sur un même chemin (`context.method` = "WEBSOCKET").
      *   `undefined` (GET/HTTP) → match historique sur `context.method`.
-     * @returns un `Resolver` (`.resolve === true` si une route a matché).
+     * @returns un `Resolver` (`.resolve === true` si une route a matché) — ou,
+     *   pour un chemin servi en WebSocket SEULEMENT et demandé en HTTP, un
+     *   `Resolver` dont `exception` porte le `426` (en-têtes `Upgrade` posés) :
+     *   le pipeline le lève après le pare-feu.
      */
     resolve(context: ContextType, cleanPathOverride?: string, methodOverride?: string): Resolver;
     resolveController(contex: ContextType, name: string): Resolver;
@@ -76,4 +101,18 @@ declare class Router extends Service implements IRequestRouter {
      */
     static getRoutesForController(myconstructor: TypeController<Controller>): Route[];
 }
+/**
+ * Dit si le service `router` d'un contexte est le Router de
+ * `@nodefony/framework` — la garde qui rétrécit le contrat `IRequestRouter` de
+ * `@nodefony/http` sans conversion, pour qui lit des membres propres au
+ * framework (le Resolver complet que rend `resolve`).
+ *
+ * Lit la marque {@link FRAMEWORK_ROUTER}, jamais `instanceof` : deux copies
+ * installées du framework feraient échouer `instanceof` en silence. Une
+ * lecture de propriété.
+ *
+ * @param router - le routeur lu sur le contexte (`context.router`).
+ * @returns `true` si c'est le Router du framework.
+ */
+export declare function isFrameworkRouter(router: IRequestRouter | null | undefined): router is Router;
 export default Router;

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

@@ -1,8 +1,9 @@
 import { Service, Module, FileClass } from "nodefony";
-import type { MaybePromise } from "nodefony";
+import type { IRequestUser, MaybePromise } from "nodefony";
 import type { IController } from "../interfaces/index.js";
 import Route from "./Route.js";
 import { contextRequest, HTTPMethod, HttpResponse, Session, ContextType, Http2Response, WebsocketResponse } from "@nodefony/http";
+import type { ISseStreamOptions, SseStream } from "@nodefony/http";
 import { OutgoingHttpHeaders } from "node:http";
 import { ReadStream } from "node:fs";
 import Eta from "../service/Eta.js";
@@ -94,30 +95,35 @@ declare class Controller extends Service implements IController {
     set request(request: contextRequest);
     get response(): HttpResponse | Http2Response | WebsocketResponse | null;
     set response(response: HttpResponse | Http2Response | WebsocketResponse | null);
+    /**
+     * L'utilisateur CONNECTÉ, ou `null` — anonyme, ou route hors de toute zone
+     * du pare-feu. C'est l'identité que le pare-feu a établie pour cette
+     * requête : aucun appel de plus. Une page publique qui veut savoir qui la
+     * visite se place sous une zone `authenticators: ["session", "anonymous"]`.
+     */
+    get user(): IRequestUser | null;
     get method(): HTTPMethod | undefined;
     set method(method: HTTPMethod | undefined);
     /**
-     * Query string de l'appel en cours — pour un singleton invoqué par le pont
-     * `api.request`, celle du chemin INVOQUÉ (résolveur d'appel dans l'ALS), pas
-     * celle du handshake de la connexion. Une seule lecture de l'ALS.
+     * Paramètres d'URL de l'appel en cours — jamais le corps, qui reste dans
+     * {@link body}. Pour un singleton invoqué par le pont `api.request`,
+     * ceux du chemin INVOQUÉ (résolveur d'appel dans l'ALS), pas ceux du
+     * handshake de la connexion. Une seule lecture de l'ALS.
      */
-    get queryGet(): Record<string, unknown>;
-    set queryGet(value: Record<string, unknown>);
-    /** Comme {@link queryGet}, pour la query fusionnée (`query`). */
     get query(): Record<string, unknown>;
     set query(value: Record<string, unknown>);
-    get queryFile(): unknown[];
-    set queryFile(value: unknown[]);
-    get queryPost(): Record<string, unknown>;
-    set queryPost(value: Record<string, unknown>);
+    /**
+     * Les fichiers reçus dans un corps multipart (`UploadedFile`) ; les champs
+     * texte du même corps sont dans {@link body}. Pour une action typée,
+     * préférer `@UploadedFiles()`.
+     */
+    get files(): readonly unknown[];
+    set files(value: readonly unknown[]);
     /**
      * Le CORPS de la requête, parsé — nom universel de l'écosystème (Express,
-     * Fastify, NestJS), alias de {@link queryPost}.
-     *
-     * Ne pas confondre avec {@link query}, qui FUSIONNE la query string et le
-     * corps. Pour une action typée, préférer le décorateur `@Body()`.
-     *
-     * Getter (aucune allocation) : `queryPost` reste la source unique.
+     * Fastify, NestJS). Jamais un paramètre d'URL : ceux-là sont dans
+     * {@link query}, et les deux ne fusionnent pas. Pour une action typée,
+     * préférer le décorateur `@Body()`.
      */
     get body(): Record<string, unknown>;
     set body(value: Record<string, unknown>);
@@ -177,6 +183,37 @@ declare class Controller extends Service implements IController {
      * @throws de façon SYNCHRONE ce que lève `JSON.stringify` (cycle, BigInt).
      */
     renderJson(obj: unknown, status?: string | number, headers?: OutgoingHttpHeaders): MaybePromise<Http2Response | HttpResponse | WebsocketResponse>;
+    /**
+     * Le client demande-t-il un flux d'événements (`Accept: text/event-stream`) ?
+     *
+     * La route ne change pas de méthode pour autant : un même `POST` répond en
+     * JSON ou en flux selon cette réponse. Toujours `false` sur WebSocket.
+     *
+     * @returns `true` quand `text/event-stream` est accepté avec un poids non nul.
+     */
+    acceptsSse(): boolean;
+    /**
+     * Répond par un flux d'événements serveur, en HTTP/1.1 comme en HTTP/2.
+     *
+     * L'action garde la main : elle `send()` à son rythme et `close()` quand elle
+     * a fini ; le départ du client ferme le flux (`sse.closed`, `sse.onClose`).
+     * Rendre le flux depuis l'action est sans effet — la réponse est déjà prise.
+     *
+     * @example
+     * ```ts
+     * @Get("/progress")
+     * async progress() {
+     *   const sse = await this.renderSse();
+     *   for (const step of steps) await sse.send(step, { event: "step" });
+     *   return sse.close();
+     * }
+     * ```
+     *
+     * @param options - battement de cœur, délai `retry:` initial.
+     * @returns le flux, ou sa promesse quand une session est à sauver d'abord.
+     * @throws HttpError 500 hors HTTP (WebSocket) ou quand la réponse est partie.
+     */
+    renderSse(options?: ISseStreamOptions): SseStream | Promise<SseStream>;
     /**
      * Pose la route de la requête courante sur l'instance (per-request).
      *

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

@@ -1,4 +1,5 @@
 import type { IAdminEndpoint } from "nodefony";
+import type { RoutePart } from "./routeSchema.js";
 /**
  * Endpoints « Playground » du data plane framework — la source de données de la
  * console vivante des controllers dans Studio (`/nodefony/playground`).
@@ -65,7 +66,18 @@ export interface PlaygroundAction {
     variables: string[];
     /** Défauts de variables (hors clé interne `controller`). */
     defaults: Record<string, unknown>;
+    /**
+     * Entrées de l'action. Pour une action à schéma, déduites du schéma (une
+     * entrée par champ de `query`/`headers`/`params`, une pour `body`) : le
+     * formulaire se construit pareil, quelle que soit la forme de l'action.
+     */
     params: PlaygroundParam[];
+    /**
+     * Le contrat d'une action à schéma — JSON Schema d'entrée de chaque partie
+     * déclarée (`null` quand la bibliothèque ne sait pas le décrire). `null`
+     * pour une action sans schéma.
+     */
+    schema: Partial<Record<RoutePart, Record<string, unknown> | null>> | null;
     guards: PlaygroundGuards;
 }
 /** Un controller et ses actions, groupés pour la navigation Studio. */

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

@@ -42,7 +42,7 @@ declare class Resolver implements IResolver {
     /**
      * Query d'une invocation **par message** (pont WS-RPC `api.request`) — pendant
      * de `cleanPathOverride` pour le `?…` du path invoqué. Le contexte WS étant
-     * PARTAGÉ par la connexion (sa `queryGet` = celle du handshake), la query
+     * PARTAGÉ par la connexion (sa `query` = celle du handshake), la query
      * per-invocation vit ici (le Resolver est per-invocation → zéro bleed entre
      * requêtes concurrentes d'une même socket). `null` (hot path HTTP) = ignoré.
      * Consommé par `@Query` (`_buildParamArgs`) et copié sur le controller
@@ -70,6 +70,11 @@ declare class Resolver implements IResolver {
      * administrateurs.
      */
     messageInvocation: boolean;
+    /**
+     * Les gardes de l'action ont été jugées favorables par {@link authorizeAction}
+     * et ne se rejugent pas à la prochaine exécution — consommé par elle.
+     */
+    private preAuthorized;
     constructor(context: ContextType);
     match(route: Route, context: ContextType, cleanPath?: string, literal?: boolean): ((string | null)[] & Record<string, unknown>) | null | undefined;
     /**
@@ -115,6 +120,12 @@ declare class Resolver implements IResolver {
      * `instanceof` au message suivant — le hub était RÉINSTANCIÉ (DI +
      * `initialize()`) à chaque frame qui suivait un `api.request`.
      *
+     * Ni pour un `forward` sur une connexion WebSocket : son résolveur est neuf,
+     * pas une invocation par message, et réécrivait le pointeur que la poignée
+     * de main a posé — même réinstanciation à la frame suivante (#574). Une
+     * connexion garde le contrôleur qui l'a ouverte. Chemin froid : seulement
+     * quand un contrôleur est créé.
+     *
      * @returns le controller reçu, pour enchaîner.
      */
     private _pinController;
@@ -163,6 +174,25 @@ declare class Resolver implements IResolver {
      *   d'action) ; un refus d'autorisation rompt la promesse rendue.
      */
     executeAction(data?: unknown[], reload?: boolean, metaArg?: RouteActionMeta): MaybePromise<ActionOutcome>;
+    /**
+     * Valide l'entrée d'une action à schéma, puis l'exécute avec cette entrée
+     * pour argument unique. Synchrone tant que le validateur l'est.
+     *
+     * @throws SchemaValidationError (422) quand l'entrée viole le schéma.
+     */
+    private _validateAndInvoke;
+    /**
+     * Juge les gardes de l'action résolue SANS l'exécuter — appelé par le
+     * pipeline WebSocket AVANT d'accepter le handshake (#596), pour qu'un
+     * connecté sans le rôle reçoive son 403 en statut HTTP au lieu d'une
+     * ouverture suivie d'une fermeture. Un verdict favorable vaut pour la
+     * PROCHAINE exécution (l'action de handshake), qui ne le rejuge pas ; les
+     * messages suivants, eux, sont jugés chacun.
+     *
+     * @returns `undefined` quand l'action n'est pas gardée ; sinon la promesse du
+     *   verdict, rompue par un refus
+     */
+    authorizeAction(): Promise<void> | undefined;
     /**
      * Les gardes d'autorisation d'une action : `@IsGranted`/`@RequireScope`, puis
      * le filet de la ZONE quand aucune garde n'a décidé du RÔLE.
@@ -339,5 +369,18 @@ declare class Resolver implements IResolver {
     returnController(result: unknown): MaybePromise<unknown>;
     /** Statut courant de la réponse (0 si le transport n'en porte pas). */
     private getResponseStatus;
+    /**
+     * `@RequireAuthentication` — les gardes d'autorisation d'abord (un rôle
+     * absent reste un 403 définitif : inutile de faire redemander une connexion à
+     * qui n'aura pas le droit), PUIS l'âge et les moyens de la connexion.
+     *
+     * Le refus est un 401 « step-up » (RFC 9470) : le `WWW-Authenticate` porte
+     * `error="insufficient_user_authentication"` et, quand la route fixe un âge,
+     * `max_age` — le client redemande une connexion au lieu de conclure à un
+     * accès fermé. Cold path : seules les routes décorées y passent.
+     *
+     * @throws nodefonyError 401 si la connexion est trop ancienne ou trop faible.
+     */
+    private _enforceStepUp;
 }
 export default Resolver;

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

@@ -86,7 +86,7 @@ export interface IResourceService<T = unknown> {
  *   sur `this` doit rétrograder : `static scope = "request"`.
  *
  * Sécurité : aucun critère de requête n'est passé AUTOMATIQUEMENT au service
- * (pas de `find(this.queryGet)` implicite) — exposer un filtrage est une
+ * (pas de `find(this.query)` implicite) — exposer un filtrage est une
  * décision EXPLICITE de la sous-classe (deny-by-default ; le scope de
  * sécurité des données se branche au niveau service/criteria, P6).
  *