@nodefony/framework 10.0.0-alpha.1

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

@@ -0,0 +1,86 @@
+import type { Module } from "nodefony";
+import type { ContextType } from "@nodefony/http";
+import Controller from "../src/Controller.js";
+/**
+ * Vue MINIMALE du service d'émission de jetons, côté **publication**
+ * (`tokenService`, posé au container par `@nodefony/security`). Contrat
+ * structurel local : framework ne dépend JAMAIS de security — couplage par nom
+ * de service, comme `authFlow`/`adminBroker`.
+ *
+ * Les deux méthodes disent l'essentiel du partage des rôles : security DÉCIDE
+ * (peut-on se déclarer émetteur ?) et FOURNIT la matière (les clés publiques) ;
+ * framework se contente d'ouvrir la porte.
+ */
+export interface IIssuerPublisher {
+    /** Émetteur canonique publiable, ou `null` si rien ne doit l'être. */
+    publishedIssuer(): string | null;
+    /** Jeu de clés PUBLIQUES de signature (jamais de clé privée). */
+    getPublicJWKS(): Promise<unknown>;
+}
+/**
+ * Les deux documents qui rendent une application Nodefony **découvrable** comme
+ * émetteur de jetons — RFC 8414 :
+ *
+ *  - `GET /.well-known/oauth-authorization-server` — métadonnées d'émetteur
+ *    (`issuer`, `jwks_uri`) ; c'est le seul document qu'un tiers sait trouver,
+ *    puisqu'il ne le lit pas mais le CONSTRUIT depuis l'identifiant d'émetteur
+ *    par insertion de chemin (§3.1).
+ *  - `GET /.well-known/jwks.json` — le jeu de clés publiques lui-même.
+ *
+ * ## Pourquoi ces routes existent
+ *
+ * Sans elles, `getPublicJWKS()` n'a qu'un usage interne : Nodefony vérifie ses
+ * propres jetons en mémoire. Un tiers — une autre application Nodefony, un
+ * agent, un service — ne peut donc PAS valider une signature émise ici, même en
+ * connaissant l'URL des clés : il n'y en a pas. C'est le symétrique exact du
+ * rôle serveur de ressource : là, on refusait en disant où aller ; ici, on
+ * permet à quelqu'un d'autre de vérifier ce qu'on a signé.
+ *
+ * ## Ce qui les monte, et ce qui les retient
+ *
+ * Montées par le module framework UNIQUEMENT si `tokenService.publishedIssuer()`
+ * rend une valeur — c'est-à-dire si le JWT est actif, `security.jwt.jwks` vrai,
+ * et l'émetteur écrit sous forme d'URL https. Sinon les routes **n'existent
+ * pas** (`404`, zéro surface) : un document creux apprendrait à un client qu'il
+ * y a quelque chose à découvrir sans lui donner de quoi le faire.
+ *
+ * Le montage ne suffit pas : servir encore exige que la requête entre par
+ * **l'autorité de l'émetteur** ({@link IssuerMetadataController.metadata}). Un
+ * serveur écoute plusieurs adresses ; l'émetteur n'en désigne qu'une.
+ *
+ * `bypassFirewall: true` : ces documents sont publics par construction. Un JWKS
+ * derrière une authentification serait un non-sens — il sert précisément à
+ * vérifier les jetons de ceux qui ne sont pas encore authentifiés. Ils ne
+ * révèlent rien de secret : des clés PUBLIQUES et un identifiant, jamais `d`.
+ *
+ * @remarks Le chemin des métadonnées est **dérivé** de l'émetteur
+ * (`authorizationServerMetadataPath`) et non écrit en dur : un émetteur porteur
+ * d'un chemin se publie SOUS ce chemin (RFC 8414 §3.1), et c'est la même
+ * fonction qui sert au lecteur, dans `@nodefony/security`.
+ */
+declare class IssuerMetadataController extends Controller {
+    #private;
+    constructor(context: ContextType);
+    /**
+     * `GET /.well-known/oauth-authorization-server` — métadonnées d'émetteur.
+     *
+     * @returns le document RFC 8414, ou `404` si la publication a été coupée
+     *          après le montage des routes
+     */
+    metadata(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /**
+     * `GET /.well-known/jwks.json` — clés publiques de signature.
+     *
+     * @returns le JWK Set (paramètres publics seuls)
+     */
+    jwks(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+}
+/**
+ * Monte les deux documents d'émetteur — appelé par le module framework à
+ * `onKernelReady`, seulement si `tokenService.publishedIssuer()` répond.
+ *
+ * @param frameworkModule - module porteur des routes
+ * @param issuer - émetteur canonique, qui DÉTERMINE le chemin des métadonnées
+ */
+export declare function mountIssuerMetadataRoutes(frameworkModule: Module, issuer: string): void;
+export default IssuerMetadataController;

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

@@ -0,0 +1,81 @@
+import type { Module } from "nodefony";
+import type { ContextType } from "@nodefony/http";
+import Controller from "../src/Controller.js";
+/**
+ * Vue MINIMALE du service `oauth2` (`@nodefony/security`) — couplage par NOM
+ * (framework ne dépend ni de security ni d'arctic). Contrat structurel imposé par
+ * cast (`this.get<…>`), aucune liaison de build.
+ */
+export interface IOAuth2Service {
+    isEnabled(): boolean;
+    listProviders(): string[];
+    getRedirects(provider?: string): {
+        success: string;
+        failure: string;
+    };
+    createAuthorization(provider: string): Promise<{
+        url: string;
+        state: string;
+        codeVerifier: string | null;
+    }>;
+    exchangeAndProvision(provider: string, code: string, codeVerifier: string | null, returnedIss: string | null): Promise<{
+        identifier: string;
+    }>;
+}
+/** Vue minimale d'une session — porte l'état du flux OAuth (anti-CSRF/anti-replay). */
+export interface IOAuth2Session {
+    get(key: string): unknown;
+    set(key: string, value: unknown): unknown;
+    save(): Promise<unknown>;
+}
+/** Vue minimale du flux de session BFF (`authFlow`) consommée ici. */
+export interface IOAuth2BffFlow {
+    /**
+     * @param reason - facteur d'authentification journalisé par l'audit
+     *   (`"oauth"` ici). Omis, il retombe sur `"federated"`, qui ne distingue plus
+     *   un login social d'une passkey dans le journal.
+     */
+    establishSessionFor(context: ContextType, identifier: string, reason?: string): Promise<unknown>;
+    /** Garantit une session (anonyme) pour porter `state`/`code_verifier`. */
+    ensureSession(context: ContextType): Promise<IOAuth2Session | null>;
+}
+/**
+ * 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}/callback` — valide le `state`
+ *    (anti-CSRF), échange le `code`, provisionne le Shadow User et OUVRE la
+ *    session BFF (302 vers `successRedirect`).
+ *
+ * Montés UNIQUEMENT si le service `oauth2` existe (social login activé) — 404
+ * sinon, zéro surface.
+ *
+ * @remarks `bypassFirewall` : ces routes SONT (ou précèdent) le mécanisme d'auth
+ * (l'utilisateur est anonyme pendant tout l'aller-retour). Le firewall, sur l'aire
+ * data plane, déclencherait un deadlock identique au login BFF / WebAuthn login.
+ * La session anonyme ne porte que `state`/`verifier` ; `establishSessionFor`
+ * régénère l'ID (anti-fixation) à la promotion.
+ */
+declare class OAuth2Controller extends Controller {
+    #private;
+    constructor(context: ContextType);
+    /**
+     * Liste PUBLIQUE des fournisseurs activés (configurés ET connus du registre).
+     * Consommé par l'UI de login pour n'afficher QUE les boutons opérationnels —
+     * jamais de bouton mort. Aucun secret n'est exposé (uniquement les noms).
+     */
+    providers(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /** Démarre le flux : URL d'autorisation + état anti-replay en session, 302. */
+    authorize(provider: string): Promise<void | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /** Valide `state`, échange le `code`, ouvre la session BFF (302). */
+    callback(provider: string): Promise<void | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+}
+/**
+ * Monte les routes du social login OAuth — appelé par le module framework à
+ * `onKernelReady`, seulement si le service `oauth2` est présent.
+ */
+export declare function mountOAuth2Routes(frameworkModule: Module): void;
+export default OAuth2Controller;

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

@@ -0,0 +1,147 @@
+import type { Module } from "nodefony";
+import type { IProtectedResourceInput } from "nodefony";
+import type { ContextType } from "@nodefony/http";
+import Controller from "../src/Controller.js";
+/**
+ * Vue MINIMALE du service qui sait ce que l'application PROTÈGE, côté
+ * **publication**. Contrat structurel local : framework ne dépend JAMAIS de
+ * `@nodefony/security` — couplage par nom de service (`firewall`), comme
+ * `tokenService`/`authFlow`/`adminBroker`.
+ *
+ * Le partage des rôles est le même que pour l'émetteur : security DÉCIDE (quelles
+ * zones déclarent une ressource, quels serveurs d'autorisation les servent) et
+ * framework se contente d'ouvrir la porte.
+ */
+export interface IProtectedResourcePublisher {
+    /**
+     * Ressources protégées à publier — vide si l'application n'en protège aucune.
+     *
+     * Chaque entrée décrit une ressource telle qu'un client l'atteint, et les
+     * serveurs d'autorisation capables d'émettre un jeton pour elle.
+     */
+    publishedProtectedResources(): readonly IProtectedResourceInput[];
+}
+/**
+ * Le document qui rend un refus APPRENABLE — RFC 9728.
+ *
+ * ## Le trou que ce controller ferme
+ *
+ * Un `401` d'une zone qui déclare sa ressource porte désormais un défi complet :
+ *
+ * ```
+ * WWW-Authenticate: Bearer resource_metadata="https://app/.well-known/oauth-protected-resource/api"
+ * ```
+ *
+ * Sans ce controller, cette URL rendait **404** : un pointeur syntaxiquement
+ * conforme qui ne mène nulle part. Le client le lit, le suit, trouve une erreur,
+ * et conclut qu'il n'y a pas d'autorisation ici — c'est-à-dire exactement
+ * l'inverse de ce que le refus voulait lui apprendre. Seul `@nodefony/devkit`
+ * publiait un document, et uniquement pour SA porte MCP.
+ *
+ * ## Une route par CHEMIN, un document par AUTORITÉ
+ *
+ * La RFC 9728 §3.1 **insère** le chemin de la ressource dans l'URL bien connue
+ * (« Using path components enables supporting multiple resources per host ») :
+ * deux ressources de chemins distincts ont donc deux URL distinctes, et l'on
+ * monte une route par chemin. Deux ressources qui partagent le chemin mais pas
+ * l'autorité (`https://a.example/api` et `https://b.example/api`) partagent en
+ * revanche la même route : c'est alors l'autorité demandée qui départage, à la
+ * requête.
+ *
+ * ## Ce qui retient la publication
+ *
+ * Rien n'est monté si le service `firewall` est absent, ou s'il ne déclare
+ * aucune ressource : **`404`, zéro surface**. Un document creux apprendrait à un
+ * client qu'il y a quelque chose à découvrir sans lui donner de quoi le faire —
+ * et la spécification MCP l'interdit explicitement (« MUST include […] at least
+ * one authorization server »).
+ *
+ * `bypassFirewall: true` : ce document est public par construction. Le placer
+ * derrière l'authentification serait circulaire — il sert précisément à
+ * expliquer comment s'authentifier à qui ne l'est pas encore. Il ne révèle rien
+ * de secret : une URI publique, des émetteurs, des scopes.
+ *
+ * @see references/rfc/ietf/rfc9728.txt — métadonnées de la ressource protégée
+ * @see references/rfc/ietf/rfc8707.txt — l'audience, qui LIE un jeton à CE service
+ */
+declare class ProtectedResourceMetadataController extends Controller {
+    #private;
+    constructor(context: ContextType);
+    /**
+     * `GET /.well-known/oauth-protected-resource/<chemin>` — RFC 9728 §3.
+     *
+     * 🔴 Le document n'est servi que sur l'autorité de SA ressource. Un client
+     * conforme rejette un document dont la `resource` ne correspond pas à l'URI
+     * qu'il interrogeait (§3.3) — et un client réel s'arrête là au lieu de
+     * continuer sans authentification. C'est la faille déjà vécue sur le document
+     * d'émetteur, transposée : la règle est partagée (`onDeclaredAuthority`).
+     *
+     * @returns le document JSON, ou `404` si aucune ressource déclarée ne
+     *          correspond au chemin ET à l'autorité demandés
+     */
+    metadata(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+}
+/**
+ * Vue minimale du conteneur de services — assez pour balayer, pas plus.
+ *
+ * Le type complet vit dans `nodefony` mais l'importer ici lierait ce fichier au
+ * cœur pour une seule opération de lecture.
+ */
+export interface IServiceScan {
+    keys(): string[];
+    get<T = unknown>(name: string): T | null;
+}
+/**
+ * Rassemble ce que TOUS les services du conteneur déclarent protéger.
+ *
+ * ⭐ **Pourquoi balayer plutôt que demander à un service nommé.** Les ressources
+ * protégées d'une application n'ont pas une source unique : le pare-feu en
+ * déclare (une zone qui exige un jeton tiers), et un module peut en déclarer une
+ * de son propre chef — la porte MCP de `@nodefony/devkit` en est le premier cas.
+ * Interroger le seul `firewall` aurait laissé chaque autre module monter SON
+ * document, c'est-à-dire recopier cette règle autant de fois qu'il y a de
+ * sources, avec la collision de chemin en prime : `Router.createRoute` empile
+ * sans vérifier, et la seconde route ne serait jamais atteinte.
+ *
+ * Un **registre** aurait fait le même travail, au prix d'une dépendance d'ordre :
+ * un module qui s'enregistre après le `onKernelReady` du framework ne serait
+ * jamais publié, et rien ne le dirait. Le balayage n'a pas ce défaut — les
+ * services sont tous en place bien avant, et la question se pose au moment où
+ * l'on monte.
+ *
+ * Le contrat est **structurel** : porter la méthode suffit, aucun import, aucune
+ * interface à implémenter formellement — le même couplage que `tokenService` ou
+ * `adminBroker`.
+ *
+ * @param container - conteneur de services de l'application
+ * @returns les ressources déclarées, dans l'ordre des services
+ */
+export declare function collectProtectedResources(container: IServiceScan): readonly IProtectedResourceInput[];
+/**
+ * Chemins bien connus à monter pour un jeu de ressources déclarées.
+ *
+ * Fonction **pure**, exportée pour être éprouvée sans serveur : c'est elle qui
+ * porte les deux décisions qui font la différence entre un document servi et un
+ * `404` — la dérivation du chemin (insertion RFC 9728 §3.1, jamais une
+ * concaténation) et la déduplication.
+ *
+ * Deux zones peuvent parfaitement déclarer la même ressource (typiquement une
+ * zone HTTP et son pendant WebSocket) ; deux hôtes virtuels peuvent en déclarer
+ * deux différentes sous le même chemin. Dans les deux cas il ne faut monter
+ * qu'**une** route : `Router.createRoute` empile sans vérifier, et la seconde
+ * ne serait jamais atteinte — une collision parfaitement silencieuse.
+ *
+ * @param resources - ressources déclarées par le publieur
+ * @returns les chemins distincts à servir, dans l'ordre de déclaration
+ */
+export declare function protectedResourceRoutePaths(resources: readonly IProtectedResourceInput[]): string[];
+/**
+ * Monte les documents de ressource protégée — appelé par le module framework à
+ * `onKernelReady`, seulement si un publieur déclare au moins une ressource.
+ *
+ * @param frameworkModule - module porteur des routes
+ * @param resources - ressources déclarées, qui DÉTERMINENT les chemins montés
+ * @returns le nombre de routes montées
+ */
+export declare function mountProtectedResourceRoutes(frameworkModule: Module, resources: readonly IProtectedResourceInput[]): number;
+export default ProtectedResourceMetadataController;

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

@@ -0,0 +1,74 @@
+import type { Module } from "nodefony";
+import type { ContextType } from "@nodefony/http";
+import Controller from "../src/Controller.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
+ * structurel local : framework ne dépend JAMAIS de security (c'est http, sous
+ * framework, que security décore) ; le couplage se fait par nom de service,
+ * comme `adminBroker`.
+ */
+/** Issue d'un login BFF — identité établie, ou second facteur (2FA) requis. */
+type ILoginOutcome = {
+    status: "authenticated";
+    user: unknown;
+} | {
+    status: "mfa_required";
+    methods: 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>;
+    me(context: ContextType): Promise<unknown | null>;
+}
+/**
+ * Endpoints HTTP du flux de session BFF — adaptateurs MINCES au-dessus du
+ * service `authFlow` (`@nodefony/security`) :
+ *
+ *  - `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
+ *
+ * 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
+ * surface). Remplace les mocks `/nodefony/studio/api/auth/*` de Studio.
+ *
+ * Erreurs : mappées par DUCK-TYPING sur `code` (401/429) — framework ne peut
+ * pas importer les classes d'erreur de security. Un 429 reporte le
+ * `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
+ * 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 {
+    #private;
+    constructor(context: ContextType);
+    /** Login BFF : credential JSON présenté UNE fois → cookie de session opaque. */
+    login(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /**
+     * Second facteur (TOTP ou code de récupération) après un `login` ayant répondu
+     * `202 mfaRequired`. Body JSON `{ code }`. Succès → 200 + identité ; code
+     * 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). */
+    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. */
+    me(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+}
+/**
+ * Monte les routes du flux de session BFF — appelé par le module framework à
+ * `onKernelReady`, seulement si le service `authFlow` est présent.
+ *
+ * Routes nommées `security.auth.*` (espace data plane
+ * `/nodefony/security/api/*`, convention « toujours ≥ 3 segments »). HTTP-only :
+ * la sémantique session-par-socket du pont WS-RPC n'est pas conçue (P6+).
+ */
+export declare function mountSessionAuthRoutes(frameworkModule: Module): void;
+export default SessionAuthController;

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

@@ -0,0 +1,56 @@
+import type { Module } from "nodefony";
+import type { ContextType } from "@nodefony/http";
+import Controller from "../src/Controller.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
+ * JAMAIS de security — couplage par nom de service (comme `authFlow`/`adminBroker`).
+ */
+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>;
+    /** Rotation d'un refresh token (nouveau couple, ancien révoqué). */
+    refresh(rawRefresh: unknown, resource?: unknown): Promise<unknown>;
+}
+/**
+ * Endpoints HTTP d'émission/rotation de **JWT** — adaptateurs MINCES au-dessus du
+ * service `tokenService` (`@nodefony/security`) :
+ *
+ *  - `POST /nodefony/security/api/token`         — body `{username, password, scope?}`
+ *    → `{access_token, refresh_token, token_type, expires_in, scope}` (RFC 6749 §5.1)
+ *  - `POST /nodefony/security/api/token/refresh` — body `{refresh_token}` → rotation
+ *
+ * Montés par le module framework UNIQUEMENT si le service `tokenService` existe
+ * (module security chargé + JWT activé) — sans lui, les routes n'existent pas
+ * (404, zéro surface).
+ *
+ * Le JWT part en **réponse JSON** (Bearer), JAMAIS en cookie ni en URL (anti
+ * fuite / non-révocable). Erreurs mappées par DUCK-TYPING sur `code` (401/429) —
+ * 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
+ * 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 {
+    #private;
+    constructor(context: ContextType);
+    /** Émission : credential présenté → couple access/refresh. */
+    token(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /** Rotation : refresh présenté → nouveau couple (ancien révoqué). */
+    refresh(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+}
+/**
+ * Monte les routes d'émission/rotation JWT — appelé par le module framework à
+ * `onKernelReady`, seulement si le service `tokenService` est présent.
+ *
+ * Routes nommées `security.token.*` (espace data plane `/nodefony/security/api/*`).
+ * `bypassFirewall: true` : ces routes SONT le mécanisme d'émission — l'aire data
+ * plane les matcherait sinon (obtenir un token exigerait d'être déjà authentifié,
+ * deadlock).
+ */
+export declare function mountTokenAuthRoutes(frameworkModule: Module): void;
+export default TokenAuthController;

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

@@ -0,0 +1,42 @@
+import type { Module } from "nodefony";
+import type { ContextType } from "@nodefony/http";
+import Controller from "../src/Controller.js";
+/**
+ * Endpoints HTTP **self-service 2FA TOTP (P6.17)** — console « ma sécurité »,
+ * adaptateurs MINCES au-dessus du service `totp` (`@nodefony/security`) :
+ *
+ *  - `POST /nodefony/security/api/totp/enroll`  → `{secretBase32, otpauthUri}`
+ *    (secret affiché 1× pour le QR ; secret PENDING tant que non confirmé)
+ *  - `POST /nodefony/security/api/totp/confirm` — body `{code}` → `{recoveryCodes}`
+ *    (active le 2FA ; codes de récupération affichés 1×)
+ *  - `POST /nodefony/security/api/totp/disable` → `{ok}` (retire le 2FA)
+ *  - `GET  /nodefony/security/api/totp/status`  → `{enabled, pending, recoveryCodesRemaining}`
+ *
+ * **PAS de `bypassFirewall`** (≠ login/totp) : ces routes vivent DANS la zone data
+ * plane `^/nodefony/[^/]+/api(/|$)` → **session BFF requise**. Le sujet est
+ * TOUJOURS l'utilisateur courant (`authFlow.me`), jamais un paramètre — on n'active
+ * /ne désactive jamais le 2FA d'autrui (anti-IDOR). Montés seulement si le service
+ * `totp` existe (security chargé + 2FA activé) → 404, zéro surface, sinon.
+ */
+declare class TotpController extends Controller {
+    #private;
+    constructor(context: ContextType);
+    /** Démarre l'enrôlement : secret + URI otpauth affichés une seule fois. */
+    enroll(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /** Confirme l'enrôlement par un 1ᵉʳ code → active + codes de récupération (1×). */
+    confirm(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /** Désactive le 2FA du porteur courant (retire secret + codes). */
+    disable(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /** État 2FA du porteur courant (alimente la console « ma sécurité »). */
+    status(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+}
+/**
+ * Monte les routes self-service 2FA — appelé par le module framework à
+ * `onKernelReady`, seulement si le service `totp` est présent.
+ *
+ * Routes nommées `security.totp.*` (espace data plane `/nodefony/security/api/*`).
+ * **Aucun `bypassFirewall`** : l'aire data plane (session BFF) les garde — gérer
+ * son 2FA exige d'être authentifié.
+ */
+export declare function mountTotpRoutes(frameworkModule: Module): void;
+export default TotpController;

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

@@ -0,0 +1,123 @@
+import type { Module } from "nodefony";
+import type { ContextType } from "@nodefony/http";
+import Controller from "../src/Controller.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
+ * reste est relayé tel quel au client.
+ */
+type CeremonyOptions = {
+    challenge: string;
+} & Record<string, unknown>;
+/**
+ * Vue MINIMALE du service `webauthn` (`@nodefony/security`) — couplage par NOM
+ * (framework ne dépend jamais de security ni de `@simplewebauthn`). Contrat
+ * structurel imposé par cast (`this.get<…>`), aucune liaison de build.
+ */
+export interface IWebAuthnService {
+    isEnabled(): boolean;
+    generateRegistrationOptions(user: {
+        id: string;
+        name: string;
+        displayName?: string;
+    }): Promise<CeremonyOptions>;
+    verifyRegistration(response: unknown, expectedChallenge: string, userId: string, requestOrigin?: string): Promise<{
+        id: string;
+    }>;
+    generateAuthenticationOptions(userId?: string): Promise<CeremonyOptions>;
+    verifyAuthentication(response: unknown, expectedChallenge: string, requestOrigin?: string): Promise<{
+        userId: string;
+    }>;
+    listUserCredentials(userId: string): Promise<Array<{
+        id: string;
+        transports: string[];
+        backupState: boolean;
+        createdAt: number;
+        lastUsedAt: number | null;
+    }>>;
+    removeUserCredential(userId: string, credentialId: string): Promise<boolean>;
+}
+/** Vue minimale d'une session — porte le challenge de cérémonie (anti-replay). */
+export interface IWebAuthnSession {
+    get(key: string): unknown;
+    set(key: string, value: unknown): unknown;
+    save(): Promise<unknown>;
+}
+/** Vue minimale du flux de session BFF (`authFlow`) consommée ici. */
+export interface IWebAuthnBffFlow {
+    me(context: ContextType): Promise<{
+        username: string;
+    } | null>;
+    /**
+     * @param reason - facteur d'authentification journalisé par l'audit
+     *   (`"webauthn"` ici). Omis, il retombe sur `"federated"`, qui ne distingue
+     *   plus une passkey d'un login social dans le journal.
+     */
+    establishSessionFor(context: ContextType, identifier: string, reason?: string): Promise<unknown>;
+    /** Garantit une session (la démarre si déconnecté) pour porter le challenge. */
+    ensureSession(context: ContextType): Promise<IWebAuthnSession | null>;
+}
+/**
+ * Endpoints HTTP des cérémonies **WebAuthn / passkeys** (P6 J9) — adaptateurs
+ * MINCES au-dessus du service `webauthn` (`@nodefony/security`) :
+ *
+ *  - `POST /nodefony/security/api/webauthn/register/options` — défi de création
+ *    (utilisateur DÉJÀ connecté : lie un passkey à son compte)
+ *  - `POST /nodefony/security/api/webauthn/register/verify`  — vérifie + stocke
+ *  - `POST /nodefony/security/api/webauthn/login/options`    — défi d'assertion
+ *  - `POST /nodefony/security/api/webauthn/login/verify`     — vérifie + ouvre
+ *    la session BFF (l'empreinte remplace le mot de passe)
+ *
+ * Le **challenge** est stocké côté serveur en session (jamais rejouable) entre
+ * `options` et `verify`.
+ *
+ * **Deux conditions distinctes, deux réponses distinctes** : les routes ne sont
+ * montées que si le service `webauthn` est dans le container (`framework/index.ts:400`),
+ * c'est-à-dire dès que `@nodefony/security` est chargé — sans security, **404**,
+ * zéro surface. Le service reste enregistré même passkeys DÉSACTIVÉS
+ * (`@services` l'instancie inconditionnellement) : dans ce cas les routes existent
+ * et répondent **503** (`isEnabled()` faux). Ne pas lire un 503 comme « route
+ * absente », ni un 404 comme « passkeys coupés ».
+ *
+ * @remarks `bypassFirewall` : `login/*` précède toute authentification ;
+ * `register/*` exige une session active, vérifiée ICI (`me()` → 401), pas par le
+ * firewall (qui, sur l'aire data plane, déclencherait un deadlock identique au
+ * login BFF).
+ */
+declare class WebAuthnController extends Controller {
+    #private;
+    constructor(context: ContextType);
+    /** 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. */
+    registerVerify(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /**
+     * Défi d'authentification. **Le ciblage ne vient jamais de la requête** : un
+     * appelant anonyme obtient un défi découvrable (`allowCredentials` omis), un
+     * appelant déjà authentifié obtient le sien (ré-authentification / step-up).
+     *
+     * @remarks Route en `bypassFirewall` : n'importe qui peut la poster. Peupler
+     *   `allowCredentials` depuis un identifiant fourni dirait deux choses à cet
+     *   inconnu — que le compte porte une passkey, et **lesquelles** (W3C WebAuthn
+     *   L3, « Privacy leak via credential IDs » : un `credentialId` est un
+     *   identifiant corrélable, exposé il dés-anonymise entre sites et confirme
+     *   une hypothèse d'identité avec un accès momentané à l'authenticator). La
+     *   spec propose deux remèdes, ce sont les deux régimes ci-dessous : les
+     *   credentials découvrables pour l'anonyme, une **authentification préalable**
+     *   quand on cible vraiment. Verrouillé par
+     *   `tests/unit/webauthnLoginOptionsPrivacy.test.ts`.
+     */
+    loginOptions(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /** Vérifie l'assertion (empreinte) et OUVRE la session BFF. */
+    loginVerify(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /** Liste les passkeys de l'utilisateur courant (console « mes appareils »). */
+    listCredentials(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /** Supprime une passkey DU porteur courant (sinon 404 — anti-IDOR/anti-énumération). */
+    removeCredential(id: unknown): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+}
+/**
+ * Monte les routes des cérémonies WebAuthn — appelé par le module framework à
+ * `onKernelReady`, seulement si le service `webauthn` est présent.
+ */
+export declare function mountWebAuthnRoutes(frameworkModule: Module): void;
+export default WebAuthnController;