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

package/dist/types/nodefony/controller/OAuth2Controller.d.ts

@@ -1,6 +1,6 @@
-import type { Module } from "nodefony";
+import { type Module } from "nodefony";
 import type { ContextType } from "@nodefony/http";
-import Controller from "../src/Controller.js";
+import SecurityApiController from "../src/SecurityApiController.js";
 /**
  * Vue MINIMALE du service `oauth2` (`@nodefony/security`) — couplage par NOM
  * (framework ne dépend pas de security). Contrat structurel imposé par
@@ -24,13 +24,31 @@ export interface IOAuth2Service {
         success: string;
         failure: string;
     };
-    createAuthorization(provider: string): Promise<{
+    /** `options` : une version de security qui ne le lit pas l'ignore. */
+    createAuthorization(provider: string, options?: {
+        theme?: "light" | "dark";
+    }): Promise<{
         url: string;
         state: string;
         codeVerifier: string | null;
     }>;
     exchangeAndProvision(provider: string, code: string, codeVerifier: string | null, returnedIss: string | null): Promise<{
         identifier: string;
+        logoutHint?: unknown;
+    }>;
+    /**
+     * Retient en session de quoi fermer plus tard la session du fournisseur
+     * (RP-Initiated Logout). Optionnel : la clé et la forme appartiennent au
+     * service, ce contrôleur ne fait que transmettre.
+     */
+    rememberLogout?(session: IOAuth2Session, hint: unknown): void;
+    /**
+     * Déconnexion demandée par le fournisseur sur le canal arrière (OpenID
+     * Connect Back-Channel Logout). Optionnel, même raison que
+     * {@link listDisplayProviders} : absent, la route répond 501.
+     */
+    backchannelLogout?(provider: string, logoutToken: string): Promise<{
+        outcome: "unsupported" | "refused" | "done";
     }>;
 }
 /** Vue minimale d'une session — porte l'état du flux OAuth (anti-CSRF/anti-replay). */
@@ -50,16 +68,45 @@ export interface IOAuth2BffFlow {
     /** Garantit une session (anonyme) pour porter `state`/`code_verifier`. */
     ensureSession(context: ContextType): Promise<IOAuth2Session | null>;
 }
+/**
+ * Thème que la page appelante a rendu (`?theme=`), à transmettre à l'écran du
+ * fournisseur. Liste FERMÉE : la chaîne vient de l'URL, toute autre valeur est
+ * ignorée sans un mot — rien d'arbitraire n'atteint la requête d'autorisation.
+ *
+ * @param value - paramètre `theme` de la requête, ou `null`
+ * @returns l'option à passer à `createAuthorization`, vide hors liste
+ */
+export declare function providerThemeOption(value: string | null): {
+    theme?: "light" | "dark";
+};
+/**
+ * Compose l'adresse de l'écran d'échec : la raison de l'échec, et la page où
+ * aller une fois connecté, pour que l'écran la garde à la tentative suivante.
+ *
+ * `reason` vaut le code rendu par le fournisseur s'il appartient à la liste
+ * normalisée (`access_denied` = l'utilisateur a choisi de revenir), sinon
+ * {@link OAUTH2_FAILED_REASON} — jamais la chaîne reçue, qui vient de l'URL.
+ * Une `reason` ou un `from` déjà présents sont REMPLACÉS (l'écran qui a lancé
+ * le flux peut porter ceux d'une tentative précédente) ; le reste de la
+ * requête et le fragment sont conservés, et une adresse relative reste relative.
+ *
+ * @param failure - l'écran d'échec : `back` revalidé, ou `failureRedirect`
+ * @param error - le paramètre `error` reçu au callback, ou `null`
+ * @param from - la page où aller une fois connecté (revalidée), ou `null`
+ * @returns l'adresse de redirection
+ */
+export declare function oauth2FailureTarget(failure: string, error: string | null, from: string | null): string;
 /**
  * Endpoints HTTP du **social login OAuth 2.0** (P6 J9) — adaptateurs MINCES
  * au-dessus du service `oauth2` (`@nodefony/security`) :
  *
- *  - `GET /nodefony/security/api/oauth2/{provider}/authorize` — démarre le flux :
- *    pose `state`+`code_verifier` en session (anonyme), redirige (302) vers le
- *    fournisseur.
+ *  - `GET /nodefony/security/api/oauth2/{provider}/authorize?from=&back=` —
+ *    démarre le flux : pose `state`+`code_verifier` en session (anonyme), avec
+ *    les retours revalidés en chemins locaux, redirige (302) vers le fournisseur.
  *  - `GET /nodefony/security/api/oauth2/{provider}/callback` — valide le `state`
  *    (anti-CSRF), échange le `code`, provisionne le Shadow User et OUVRE la
- *    session BFF (302 vers `successRedirect`).
+ *    session BFF (302 vers `from`, sinon `successRedirect`). Un échec mène à
+ *    `back`, sinon à `failureRedirect`, avec `reason` et `from`.
  *
  * Montés UNIQUEMENT si le service `oauth2` existe (social login activé) — 404
  * sinon, zéro surface.
@@ -70,7 +117,7 @@ export interface IOAuth2BffFlow {
  * La session anonyme ne porte que `state`/`verifier` ; `establishSessionFor`
  * régénère l'ID (anti-fixation) à la promotion.
  */
-declare class OAuth2Controller extends Controller {
+declare class OAuth2Controller extends SecurityApiController {
     #private;
     constructor(context: ContextType);
     /**
@@ -87,6 +134,18 @@ declare class OAuth2Controller extends Controller {
     authorize(provider: string): Promise<import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse | undefined>;
     /** Valide `state`, échange le `code`, ouvre la session BFF (302). */
     callback(provider: string): Promise<import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse | undefined>;
+    /**
+     * Canal arrière : le fournisseur demande de fermer les sessions qu'il
+     * désigne (OpenID Connect Back-Channel Logout 1.0 §2.5-2.8).
+     *
+     * Appelé serveur à serveur — ni cookie, ni session, ni jeton CSRF : la
+     * SIGNATURE du `logout_token` est la seule authentification. Réponses de la
+     * norme (§2.8) : 200 si la déconnexion a eu lieu (ou n'avait plus lieu
+     * d'être), 400 sinon — jeton refusé (`invalid_request`) comme déconnexion
+     * impossible (la cause part au journal, jamais au fournisseur). Toujours
+     * `Cache-Control: no-store`.
+     */
+    backchannelLogout(provider: string): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
 }
 /**
  * Monte les routes du social login OAuth — appelé par le module framework à

package/dist/types/nodefony/controller/SessionAuthController.d.ts

@@ -1,6 +1,6 @@
-import type { Module } from "nodefony";
+import { type ILoginPageDescription, type Module } from "nodefony";
 import type { ContextType } from "@nodefony/http";
-import Controller from "../src/Controller.js";
+import SecurityApiController from "../src/SecurityApiController.js";
 /**
  * Vue MINIMALE du flux de session BFF que consomme ce controller — le service
  * `authFlow` est posé au container par `@nodefony/security` (P6 J3). Contrat
@@ -14,14 +14,29 @@ type ILoginOutcome = {
     user: unknown;
 } | {
     status: "mfa_required";
-    methods: string[];
+    methods: readonly string[];
 };
 export interface ISessionAuthFlow {
     login(context: ContextType, identifier: unknown, password: unknown): Promise<ILoginOutcome>;
     completeMfaLogin(context: ContextType, code: unknown): Promise<unknown>;
     logout(context: ContextType): Promise<boolean>;
+    /**
+     * Déconnexion qui ferme AUSSI la session du fournisseur d'identité. Optionnelle :
+     * une version de `@nodefony/security` qui ne l'expose pas encore dégrade sur
+     * {@link logout}.
+     */
+    logoutWithProvider?(context: ContextType): Promise<{
+        destroyed: boolean;
+        logoutUrl: string | null;
+    }>;
     /** Identité courante, ou `null` sans session authentifiée. */
     me(context: ContextType): Promise<unknown>;
+    /**
+     * Ce que la page de connexion par défaut doit afficher, ou `null` quand
+     * elle est désactivée. Optionnelle : une version de `@nodefony/security`
+     * qui ne l'expose pas encore laisse la page absente (404).
+     */
+    describeLoginPage?(): ILoginPageDescription | null;
 }
 /**
  * Endpoints HTTP du flux de session BFF — adaptateurs MINCES au-dessus du
@@ -29,7 +44,8 @@ export interface ISessionAuthFlow {
  *
  *  - `POST /nodefony/security/api/auth/login`  — body JSON `{username, password}`
  *  - `POST /nodefony/security/api/auth/logout` — idempotent
- *  - `GET  /nodefony/security/api/auth/me`     — identité de la session courante
+ *  - `GET  /nodefony/security/api/auth/me`     — identité de la session courante :
+ *    TOUJOURS `200`, `{ user }` ou `{ user: null }` sans session
  *
  * Montés par le module framework UNIQUEMENT si le service `authFlow` existe
  * (module security chargé) — sans lui, les routes n'existent pas (404, zéro
@@ -40,14 +56,20 @@ export interface ISessionAuthFlow {
  * `Retry-After` (RFC 6585) posé par le throttler NIST ; tout le reste remonte
  * au pipeline d'erreurs standard (500, détail loggé jamais fuité).
  *
- * @remarks Dérogation RFC 7235 §3.1 DÉLIBÉRÉE : les 401 de `login`/`me` ne
+ * `me` est une SONDE d'état, pas une ressource protégée : « pas de session »
+ * est un état normal du navigateur, pas une faute — d'où `200` + `{ user:
+ * null }`, comme les bibliothèques qui livrent aussi le client de connexion
+ * (Auth.js, better-auth). Le `401` y écrivait une erreur réseau dans la console
+ * de chaque visiteur anonyme, sans rien protéger : la réponse ne révèle rien.
+ *
+ * @remarks Dérogation RFC 9110 §15.5.2 DÉLIBÉRÉE : les 401 de `login` ne
  * portent PAS de `WWW-Authenticate` — aucun scheme HTTP ne décrit un cookie de
  * session, et un challenge `Basic` mensonger déclencherait le popup natif du
  * navigateur (l'anti-pattern que le BFF élimine). Les zones du firewall, elles,
  * restent strictement conformes (challenge du premier authenticator qui en
  * déclare un).
  */
-declare class SessionAuthController extends Controller {
+declare class SessionAuthController extends SecurityApiController {
     #private;
     constructor(context: ContextType);
     /** Login BFF : credential JSON présenté UNE fois → cookie de session opaque. */
@@ -58,9 +80,18 @@ declare class SessionAuthController extends Controller {
      * absent/invalide → 401 (uniforme) ; trop de tentatives → 429 (Retry-After).
      */
     loginTotp(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
-    /** Détruit la session (storage + cookie). Toujours 200 (idempotent). */
+    /**
+     * Détruit la session (storage + cookie). Toujours 200 (idempotent). Quand la
+     * session venait d'un fournisseur qui publie un point de déconnexion, la
+     * réponse porte `logoutUrl` : le client y envoie le navigateur pour fermer
+     * aussi la session du fournisseur.
+     */
     logout(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
-    /** Identité de la session courante, re-résolue (rôles frais), ou 401. */
+    /**
+     * Identité de la session courante, re-résolue (rôles frais). Toujours `200` :
+     * `{ user: null }` quand il n'y a pas de session (ou qu'elle ne mène plus à
+     * un compte actif) — l'absence de session est un état, pas une erreur.
+     */
     me(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
 }
 /**

package/dist/types/nodefony/controller/TokenAuthController.d.ts

@@ -1,6 +1,6 @@
 import type { Module } from "nodefony";
 import type { ContextType } from "@nodefony/http";
-import Controller from "../src/Controller.js";
+import SecurityApiController from "../src/SecurityApiController.js";
 /**
  * Vue MINIMALE du service d'émission de jetons (`tokenService`, posé au container
  * par `@nodefony/security` P6 J4). Contrat structurel local : framework ne dépend
@@ -10,7 +10,9 @@ export interface ITokenIssuer {
     /** `true` si l'émission JWT est opérationnelle (JWT activé + store prêt). */
     isEnabled(): boolean;
     /** Émet access+refresh après vérification d'un credential (grant M2M/CLI). */
-    issueForCredentials(identifier: unknown, password: unknown, scopes?: string[], resource?: unknown): Promise<unknown>;
+    issueForCredentials(identifier: unknown, password: unknown, scopes?: string[], resource?: unknown, 
+    /** Requête porteuse — soumet le credential au refus du clair en production. */
+    context?: ContextType): Promise<unknown>;
     /** Rotation d'un refresh token (nouveau couple, ancien révoqué). */
     refresh(rawRefresh: unknown, resource?: unknown): Promise<unknown>;
 }
@@ -31,11 +33,11 @@ export interface ITokenIssuer {
  * framework ne peut pas importer les classes d'erreur de security ; un 429
  * reporte le `Retry-After` (RFC 6585) du throttler NIST.
  *
- * @remarks Dérogation RFC 7235 §3.1 (comme `SessionAuthController`) : ces 401 ne
+ * @remarks Dérogation RFC 9110 §15.5.2 (comme `SessionAuthController`) : ces 401 ne
  * portent pas de `WWW-Authenticate` — l'endpoint d'émission n'est pas une
  * ressource protégée par Bearer, il DÉLIVRE le Bearer.
  */
-declare class TokenAuthController extends Controller {
+declare class TokenAuthController extends SecurityApiController {
     #private;
     constructor(context: ContextType);
     /** Émission : credential présenté → couple access/refresh. */

package/dist/types/nodefony/controller/TotpController.d.ts

@@ -1,6 +1,6 @@
 import type { Module } from "nodefony";
 import type { ContextType } from "@nodefony/http";
-import Controller from "../src/Controller.js";
+import SecurityApiController from "../src/SecurityApiController.js";
 /**
  * Endpoints HTTP **self-service 2FA TOTP (P6.17)** — console « ma sécurité »,
  * adaptateurs MINCES au-dessus du service `totp` (`@nodefony/security`) :
@@ -19,7 +19,7 @@ import Controller from "../src/Controller.js";
  * `totp` existe (security chargé) — sans security, 404 et zéro surface ; 2FA
  * désactivé, les routes répondent 503.
  */
-declare class TotpController extends Controller {
+declare class TotpController extends SecurityApiController {
     #private;
     constructor(context: ContextType);
     /** Démarre l'enrôlement : secret + URI otpauth affichés une seule fois. */

package/dist/types/nodefony/controller/WebAuthnController.d.ts

@@ -1,6 +1,6 @@
-import type { Module } from "nodefony";
+import { type Module } from "nodefony";
 import type { ContextType } from "@nodefony/http";
-import Controller from "../src/Controller.js";
+import SecurityApiController from "../src/SecurityApiController.js";
 /**
  * Options de cérémonie renvoyées au navigateur (forme JSON WebAuthn) — seul le
  * `challenge` nous intéresse côté serveur (stocké en session, anti-replay) ; le
@@ -20,6 +20,7 @@ export interface IWebAuthnService {
         id: string;
         name: string;
         displayName?: string;
+        handle?: string;
     }): Promise<CeremonyOptions>;
     verifyRegistration(response: unknown, expectedChallenge: string, userId: string, requestOrigin?: string): Promise<{
         id: string;
@@ -46,7 +47,8 @@ export interface IWebAuthnSession {
 /** Vue minimale du flux de session BFF (`authFlow`) consommée ici. */
 export interface IWebAuthnBffFlow {
     me(context: ContextType): Promise<{
-        username: string;
+        id: string;
+        identifier: string;
     } | null>;
     /**
      * @param reason - facteur d'authentification journalisé par l'audit
@@ -84,9 +86,15 @@ export interface IWebAuthnBffFlow {
  * firewall (qui, sur l'aire data plane, déclencherait un deadlock identique au
  * login BFF).
  */
-declare class WebAuthnController extends Controller {
+declare class WebAuthnController extends SecurityApiController {
     #private;
     constructor(context: ContextType);
+    /**
+     * Dit si la connexion par passkey répondra : `{ enabled }`, toujours `200`.
+     * Un écran de connexion le lit pour ne pas proposer un bouton dont la
+     * cérémonie répondrait `503` (passkeys coupées).
+     */
+    status(): import("nodefony").MaybePromise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
     /** Défi d'enregistrement — l'utilisateur connecté ajoute un passkey. */
     registerOptions(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
     /** Vérifie la réponse d'enregistrement et persiste le credential. */

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

@@ -562,7 +562,49 @@ 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;
 /**
  * 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 +630,7 @@ 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;
     /** `@Redirect` de l'action — `null` si absent. */
     redirectMeta: RedirectMeta | null;
     /** `@HttpCode` de l'action — `null` si absent. */
@@ -603,6 +645,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 +693,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/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

@@ -30,6 +30,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é.
      *

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,6 +95,13 @@ 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);
     /**
@@ -177,6 +185,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/Resolver.d.ts

@@ -115,6 +115,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;
@@ -339,5 +345,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/Route.d.ts

@@ -62,9 +62,25 @@ export interface RouteOptions {
      * exception qui se justifie. Défaut `false`.
      */
     areaRoleExempt?: boolean;
+    /**
+     * Route de REPLI : elle ne sert un chemin que si aucune autre route ne le
+     * sert, quel que soit l'ordre de déclaration.
+     *
+     * Le routeur retient la première route déclarée qui correspond ; un repli à
+     * variable (`/nodefony/{page}`, la page d'une application monopage) déclaré
+     * tôt capturerait donc les routes de même forme des modules chargés après
+     * lui — sans erreur ni avertissement. Les replis sont rangés après toutes les
+     * autres routes, dans leur ordre relatif, à la construction de l'index :
+     * aucun coût par requête. Défaut `false`.
+     */
+    fallback?: boolean;
 }
 export interface RouteRequirements {
     domain?: string | string[] | undefined;
+    /**
+     * Transport exigé : `https`/`wss` refuse un canal clair, `http`/`ws` un
+     * canal chiffré — 403 sinon. Proto transmis par un proxy de confiance compris.
+     */
     scheme?: SchemeType | undefined;
     methods?: HTTPMethod[] | HTTPMethod | undefined;
     protocol?: string | undefined;
@@ -77,7 +93,6 @@ declare class Route implements IRoute {
     classMethod?: string | undefined;
     prefix?: string | undefined;
     method?: HTTPMethod | undefined;
-    schemes?: SchemeType | undefined;
     pattern?: RegExp | undefined;
     variables: string[];
     /**
@@ -115,6 +130,8 @@ declare class Route implements IRoute {
      * pas son rôle par défaut. Cf {@link RouteOptions.areaRoleExempt}.
      */
     areaRoleExempt: boolean;
+    /** Route de repli, résolue après toutes les autres. Cf {@link RouteOptions.fallback}. */
+    fallback: boolean;
     /**
      * P2.9 — Cache mémoïsé : l'action attend-elle le **flux brut** du body
      * (`@Body({ stream:true })`) ? `undefined` = pas encore calculé (résolu au 1er

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

@@ -0,0 +1,17 @@
+import type { OutgoingHttpHeaders } from "node:http";
+import Controller from "./Controller.js";
+/**
+ * Base des contrôleurs d'authentification (`/nodefony/security/api/*`) : toute
+ * réponse JSON part en `Cache-Control: no-store`.
+ *
+ * Ces réponses portent une identité, un jeton, un secret affiché une seule
+ * fois (clé API, secret TOTP, codes de récupération) ou leur refus. Un cookie
+ * ou un en-tête dans la requête n'empêche pas un cache partagé de STOCKER la
+ * réponse (RFC 9111 §3) ; RFC 6749 §5.1 exige `no-store` sur un jeton. La règle
+ * vit ici, une fois : une action ajoutée à un contrôleur héritier ne peut pas
+ * l'oublier. Un en-tête passé par l'action garde la priorité.
+ */
+declare abstract class SecurityApiController extends Controller {
+    renderJson(obj: unknown, status?: string | number, headers?: OutgoingHttpHeaders): ReturnType<Controller["renderJson"]>;
+}
+export default SecurityApiController;