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

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

@@ -1,5 +1,17 @@
 import type { ContextType } from "@nodefony/http";
 import Controller from "../src/Controller.js";
+type AdminQuery = Record<string, string | string[]>;
+/**
+ * Ramène les paramètres d'URL au contrat {@link IAdminRequest.query} : seules
+ * les chaînes et les tableaux de chaînes passent. `qs` produit des objets pour
+ * `a[b]=1` ; les laisser passer sous un type qui les nie tromperait chaque
+ * producteur du plan d'administration.
+ *
+ * @param source - paramètres d'URL de la requête (`Controller.query`)
+ * @returns `source` lui-même quand il respecte déjà le contrat (aucune
+ *   allocation), sinon une copie sans les valeurs imbriquées
+ */
+export declare function toAdminQuery(source: Record<string, unknown> | undefined): AdminQuery;
 /**
  * Controller pont unique du data plane admin (Studio).
  *

package/dist/types/nodefony/controller/ApiKeyController.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 de **gestion des clés API personnelles (PAT, P6.12)** — console
  * « mes clés » façon GitHub, adaptateurs MINCES au-dessus du service `apiKeys`
@@ -22,7 +22,7 @@ import Controller from "../src/Controller.js";
  * Erreurs mappées par DUCK-TYPING sur `code` (400/409/503) — framework ne peut pas
  * importer les classes d'erreur de security.
  */
-declare class ApiKeyController extends Controller {
+declare class ApiKeyController extends SecurityApiController {
     #private;
     constructor(context: ContextType);
     /** Émission : crée une clé pour le porteur courant → token clair (1×). */

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

@@ -0,0 +1,32 @@
+import { type Module } from "nodefony";
+import type { ContextType } from "@nodefony/http";
+import Controller from "../src/Controller.js";
+/**
+ * Page de connexion par défaut (ADR-0015) : gabarit F03 rendu côté serveur,
+ * feuille `nodefony/login.css`, script `nodefony/login.js`. Aucun front, aucun
+ * build côté application.
+ *
+ * Joignable sans session ; jamais mise en cache (`no-store`) ni affichable
+ * dans un cadre (`frame-ancestors 'none'`).
+ */
+declare class LoginPageController extends Controller {
+    constructor(context: ContextType);
+    /**
+     * Rend la page de connexion.
+     *
+     * @returns la page HTML, ou 404 quand security ne la décrit plus
+     */
+    page(): Promise<import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+}
+/**
+ * Monte la page de connexion par défaut quand security la décrit : la route
+ * sur `loginPage.path`, et ses fichiers sous `LOGIN_PAGE_ASSETS_BASE`.
+ *
+ * La page est le chemin vers la session : elle échappe au pare-feu, comme les
+ * routes de connexion — sinon une application qui protège `^/` exigerait
+ * d'être connecté pour se connecter.
+ *
+ * @param frameworkModule - module framework, qui porte les contrôleurs
+ */
+export declare function mountLoginPage(frameworkModule: Module): void;
+export default LoginPageController;

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,25 @@ 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.
+     *
+     * **Sème aussi le jeton anti-CSRF** (cookie lisible `csrf-token`) : c'est la
+     * seule requête sûre que TOUT client connaît d'avance. Sans elle, une mutation
+     * `@CsrfProtect` n'a de jeton à rejouer que si son auteur a AUSSI décoré une
+     * lecture — protéger les seules écritures, le geste naturel, rendait alors 403
+     * sans issue, au navigateur comme aux tests générés. Le jeton est sans état
+     * (HMAC) : celui-ci vaut pour toute route protégée.
+     */
     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. */