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

package/dist/types/nodefony/keycloak/keycloakRealm.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Le realm Keycloak d'une application — construit, jamais recopié.
+ *
+ * Deux usages, UNE construction : la contribution du paquet à une application
+ * neuve (`nodefony/keycloak/scaffold.ts`, jouée par `create app` après
+ * l'installation) écrit son realm d'import, et `security:keycloak:realm` le
+ * réécrit depuis la configuration EFFECTIVE d'une application qui tourne. Le
+ * cœur n'en sait rien : Keycloak est l'affaire de ce paquet.
+ *
+ * Avant lui, deux realms écrits à la main — celui du dépôt et le gabarit de
+ * l'application générée — répétaient ce que disait la configuration
+ * (identifiant de client, URL de retour, audience). Ils avaient divergé : le
+ * realm généré était né sans audience, et tout jeton y était refusé.
+ *
+ * Fonctions PURES : aucune lecture de disque, aucun environnement.
+ *
+ * @module
+ */
+/** Une valeur JSON — ce qu'un realm d'import peut contenir. */
+export type TKeycloakJson = string | number | boolean | null | TKeycloakJson[] | {
+    [key: string]: TKeycloakJson;
+};
+/** Un objet JSON du realm (client, mapper, utilisateur…). */
+export type TKeycloakObject = {
+    [key: string]: TKeycloakJson;
+};
+/** Un rôle à déclarer dans le realm. */
+export interface IKeycloakRoleInput {
+    /** Nom du rôle CÔTÉ KEYCLOAK (la clé de `roleMapping`). */
+    readonly name: string;
+    /** Texte affiché dans la console Keycloak. */
+    readonly description?: string;
+}
+/** Un compte de démonstration semé dans le realm de développement. */
+export interface IKeycloakUserInput {
+    /** Identifiant FIXÉ : laissé à Keycloak, il change à chaque réimport. */
+    readonly id: string;
+    readonly username: string;
+    readonly email: string;
+    readonly firstName: string;
+    readonly lastName: string;
+    /** Mot de passe de DÉVELOPPEMENT, public par nature. */
+    readonly password: string;
+    /** Rôles du client navigateur accordés à ce compte. */
+    readonly clientRoles?: readonly string[];
+}
+/** Le client « machine » (compte de service, `client_credentials`). */
+export interface IKeycloakMachineInput {
+    readonly clientId: string;
+    /** Secret de développement ; `null` = laissé à Keycloak (production). */
+    readonly secret: string | null;
+    readonly name?: string;
+    readonly description?: string;
+}
+/** Tout ce que le realm dit de l'application. */
+export interface IKeycloakRealmInput {
+    /** Nom du realm — le dernier segment de l'émetteur (`…/realms/<nom>`). */
+    readonly realm: string;
+    /** Titre affiché sur la page de connexion. */
+    readonly displayName?: string;
+    /** Identifiant du client navigateur (`oauth2.providers.<p>.clientId`). */
+    readonly clientId: string;
+    /** Secret du client ; `null` = laissé à Keycloak (production). */
+    readonly clientSecret: string | null;
+    readonly clientName?: string;
+    readonly clientDescription?: string;
+    /** URL de retour EXACTES (RFC 9700 : comparaison au caractère près). */
+    readonly redirectUris: readonly string[];
+    /** Où Keycloak a le droit de renvoyer le navigateur après déconnexion. */
+    readonly postLogoutRedirectUris: readonly string[];
+    /** Point de déconnexion par canal arrière ; `null` = aucun. */
+    readonly backchannelLogoutUrl: string | null;
+    /**
+     * Ressources pour lesquelles Keycloak émet des jetons à cette application :
+     * un mapper d'audience par entrée, sur chaque client. Vide = aucun mapper,
+     * et le jeton porte alors `aud: "account"`, que toute zone refuse.
+     */
+    readonly audiences: readonly string[];
+    /** Rôles du client navigateur (`rolesSource: ["client"]`). */
+    readonly clientRoles: readonly IKeycloakRoleInput[];
+    /** Rôles du realm (`rolesSource: ["realm"]`). */
+    readonly realmRoles: readonly IKeycloakRoleInput[];
+    /** Client machine ; `null` = aucun. */
+    readonly machine: IKeycloakMachineInput | null;
+    /** Thèmes à déclarer ; absent = ceux de Keycloak. */
+    readonly themes?: {
+        readonly login?: string;
+        readonly account?: string;
+        readonly email?: string;
+        readonly admin?: string;
+    };
+    /** Comptes de démonstration (développement seulement). */
+    readonly users?: readonly IKeycloakUserInput[];
+}
+/**
+ * Le rôle composite que Keycloak donne à tout compte CRÉÉ dans le realm —
+ * `manage-account`, `view-profile`, `offline_access`, `uma_authorization`.
+ *
+ * ⚠️ Un compte IMPORTÉ ne le reçoit pas : l'import n'accorde que les rôles
+ * qu'il liste. Sans lui, la console du compte rend 401 sur le profil même de
+ * l'utilisateur.
+ *
+ * @param realm - nom du realm
+ * @returns le nom du rôle par défaut
+ */
+export declare function keycloakDefaultRole(realm: string): string;
+/**
+ * Construit le realm d'import complet d'une application.
+ *
+ * @param input - ce que la configuration de l'application dit du realm
+ * @returns le realm, prêt à être sérialisé par {@link renderKeycloakRealm}
+ */
+export declare function buildKeycloakRealm(input: IKeycloakRealmInput): TKeycloakObject;
+/**
+ * Fond un realm dérivé de la config dans le realm d'import existant.
+ *
+ * Ce que la configuration DIT est réécrit : nom du realm, thèmes déclarés,
+ * client navigateur (flux, URL de retour, audience, déconnexion), client
+ * machine (flux, audience). Ce qu'un humain a écrit SURVIT : comptes,
+ * titre, noms et textes des clients, secret machine, rôles déjà déclarés,
+ * mappers qui ne sont pas d'audience, clients et clés inconnus. Régénérer
+ * ne détruit donc rien de ce que la console a ajouté.
+ *
+ * @param existing - le realm lu sur disque (JSON quelconque)
+ * @param derived - le realm construit par {@link buildKeycloakRealm}
+ * @returns le realm fusionné
+ * @throws Si `existing` n'est pas un objet JSON
+ */
+export declare function mergeKeycloakRealm(existing: TKeycloakJson, derived: TKeycloakObject): TKeycloakObject;
+/**
+ * Sérialise un realm comme le dépôt l'écrit : deux espaces, tableaux de
+ * valeurs simples sur une ligne quand ils tiennent en 80 colonnes, fin de
+ * ligne — la forme que prettier donne au fichier versionné.
+ *
+ * @param realm - le realm à écrire
+ * @returns le texte du fichier d'import
+ */
+export declare function renderKeycloakRealm(realm: TKeycloakObject): string;

package/dist/types/nodefony/keycloak/keycloakRealmInput.d.ts

@@ -0,0 +1,92 @@
+import type { IKeycloakMachineInput, IKeycloakRealmInput } from "./keycloakRealm.js";
+import { type LoginPageSkin } from "nodefony";
+import type { ISecurityConfig } from "../config/config.js";
+/**
+ * Les ports de l'application, lus dans `servers` de sa configuration.
+ *
+ * L'HÔTE n'en fait pas partie : le domaine de la config est une adresse
+ * d'ÉCOUTE (`127.0.0.1`, `0.0.0.0`), pas celle que tape le navigateur. Celle-ci
+ * est l'hôte de `redirectUri`, que Keycloak compare au caractère près.
+ */
+export interface IAppServers {
+    /** Port HTTP, `null` si le serveur en clair est coupé. */
+    readonly httpPort: number | null;
+    /** Port HTTPS, `null` si le serveur TLS est coupé. */
+    readonly httpsPort: number | null;
+}
+/** Ce qu'il faut savoir de l'application pour dériver son realm. */
+export interface IKeycloakRealmContext {
+    /** Nom du fournisseur dans `oauth2.providers` (défaut `keycloak`). */
+    readonly providerName: string;
+    /** La configuration de sécurité VALIDÉE. */
+    readonly config: ISecurityConfig;
+    readonly servers: IAppServers;
+    /**
+     * `true` en production : aucun secret écrit (Keycloak le génère, l'exploitant
+     * le copie dans son gestionnaire), aucune adresse locale de développement.
+     */
+    readonly production: boolean;
+    /** Client machine à tenir à jour ; `null` = aucun. */
+    readonly machine: IKeycloakMachineInput | null;
+    /**
+     * Origine que Keycloak utilise pour JOINDRE l'application (canal arrière).
+     * Défaut développement : `http://host.docker.internal:<port http>` — le
+     * Keycloak du compose vit dans un conteneur, `localhost` y désigne le sien.
+     */
+    readonly backchannelOrigin?: string;
+    /**
+     * `loginTheme` du realm déjà écrit, `null` s'il n'en déclare pas (ou s'il
+     * n'existe pas encore). Seul un realm déjà habillé par Nodefony change
+     * d'habillage : un thème propre à l'application n'est jamais remplacé.
+     */
+    readonly currentLoginTheme?: string | null;
+}
+/** Une dérivation, et ce qu'elle a remarqué en chemin. */
+export interface IKeycloakRealmDerivation {
+    readonly input: IKeycloakRealmInput;
+    /** Constats à DIRE à l'utilisateur (le realm reste écrit). */
+    readonly warnings: string[];
+}
+/** Erreur de dérivation : la config ne permet pas d'écrire un realm. */
+export declare class KeycloakRealmError extends Error {
+    readonly name = "KeycloakRealmError";
+}
+/**
+ * Le nom du realm, lu dans l'émetteur (`https://kc.example/realms/<nom>`).
+ *
+ * @throws {KeycloakRealmError} Si l'émetteur n'a pas la forme Keycloak
+ */
+export declare function realmNameFromIssuer(issuer: string | undefined): string;
+/**
+ * Dérive, depuis la configuration EFFECTIVE de l'application, ce que son realm
+ * Keycloak doit dire.
+ *
+ * - **Client** : `clientId`, et son secret hors production.
+ * - **URL de retour** : `redirectUri` du fournisseur, plus — hors production —
+ *   le même chemin sur chaque serveur local (http ET https), parce que
+ *   l'application répond sur les deux et que Keycloak compare au caractère près.
+ * - **Audience** : `audiences` du fournisseur, sinon la `resource` de chaque
+ *   zone `external-jwt`. Une audience qu'aucune zone ne porte est DITE : le
+ *   jeton serait refusé partout.
+ * - **Rôles** : les clés de `roleMapping`, rangées selon `rolesSource`.
+ *
+ * @param ctx - la configuration et le décor de l'application
+ * @returns l'entrée du constructeur de realm et les constats
+ * @throws {KeycloakRealmError} Si le fournisseur est absent ou sans émetteur
+ */
+/**
+ * Le thème Keycloak de connexion qui porte un habillage de la page `/login`.
+ *
+ * @param skin - habillage (`loginPage.skin`)
+ * @returns `nodefony` pour l'habillage par défaut, `nodefony-<habillage>` sinon
+ *   (thème enfant livré sous `keycloak/themes/`)
+ */
+export declare function keycloakLoginTheme(skin: LoginPageSkin): string;
+/**
+ * Dit si un thème Keycloak est l'un de ceux que livre Nodefony.
+ *
+ * @param theme - nom du thème
+ * @returns `true` pour `nodefony` et `nodefony-<habillage>`
+ */
+export declare function isNodefonyKeycloakTheme(theme: string): boolean;
+export declare function deriveKeycloakRealmInput(ctx: IKeycloakRealmContext): IKeycloakRealmDerivation;

package/dist/types/nodefony/keycloak/scaffold.d.ts

@@ -0,0 +1,98 @@
+import type { IAppContributionContext } from "nodefony";
+import { type IKeycloakRealmInput } from "./keycloakRealm.js";
+/** Le nom du thème, tel que le realm le déclare et que Keycloak le monte. */
+export declare const KEYCLOAK_THEME_NAME = "nodefony";
+/** Où l'application reçoit le décor Keycloak (chemins qui voyagent : `/`). */
+export declare const APP_KEYCLOAK_REALM_FILE = "docker/keycloak/import/realm.json";
+export declare const APP_KEYCLOAK_THEMES_DIR = "docker/keycloak/themes";
+export declare const APP_KEYCLOAK_THEME_DIR = "docker/keycloak/themes/nodefony";
+/**
+ * Ressource de l'API partenaire d'une application neuve en développement :
+ * ce que rend `partnerResource()` du gabarit `complete` sans `NF_JWT_ISSUER`
+ * ni `NF_PORT_HTTPS` — le port HTTPS par défaut, comme les URL de retour du
+ * realm. Deux paquets, une valeur : le test de contribution compare le
+ * gabarit rendu à cette constante.
+ */
+export declare const APP_PARTNER_DEV_RESOURCE = "https://localhost:5152/api/partner";
+/** Les types de thème que le realm sait déclarer, et la clé qui les porte. */
+declare const THEME_TYPES: readonly ["login", "account", "email", "admin"];
+type TThemeType = (typeof THEME_TYPES)[number];
+/**
+ * Le dossier du thème Keycloak livré par le paquet.
+ *
+ * @returns chemin natif absolu (`<paquet>/keycloak/themes/nodefony`)
+ */
+export declare function keycloakThemeSource(): string;
+/**
+ * Le dossier de TOUS les thèmes Keycloak livrés : `nodefony` et ses thèmes
+ * enfants `nodefony-<habillage>`, un par habillage de la page `/login`.
+ * Keycloak les monte côte à côte (`/opt/keycloak/themes/`).
+ *
+ * @returns chemin natif absolu (`<paquet>/keycloak/themes`)
+ */
+export declare function keycloakThemesSource(): string;
+/**
+ * Les types que le thème livré couvre — un dossier par type. Le realm ne
+ * déclare QUE ceux-là : déclarer un type absent ferait retomber Keycloak sur
+ * son thème par défaut, avec un avertissement à chaque page.
+ *
+ * @param themeDir - dossier du thème
+ * @returns les types présents, dans l'ordre de {@link THEME_TYPES}
+ */
+export declare function deliveredThemeTypes(themeDir: string): TThemeType[];
+/**
+ * Le secret du client navigateur dans le décor de développement d'une app.
+ *
+ * ⚠️ Même règle que le gabarit `.env` du cœur (`keycloak.clientSecret` dans
+ * `engine.ts`) : la frontière de paquets empêche de l'appeler, un test de ce
+ * paquet compare donc les deux sorties.
+ *
+ * @param appName - nom de l'application
+ * @returns le secret, PUBLIC par nature (écrit dans le realm versionné)
+ */
+export declare function devClientSecret(appName: string): string;
+/**
+ * Le secret de l'appelant machine (`<app>-machine`) dans le décor de
+ * développement d'une app.
+ *
+ * ⚠️ Même règle que le gabarit `.env` du cœur (`keycloak.machineSecret` dans
+ * `engine.ts`), comparée par le même test que {@link devClientSecret}.
+ *
+ * @param appName - nom de l'application
+ * @returns le secret, PUBLIC par nature (écrit dans le realm versionné)
+ */
+export declare function devMachineSecret(appName: string): string;
+/**
+ * Ce que dit la configuration rendue par le gabarit `security.ts` d'une app
+ * neuve : client `<app>`, URL de retour sur les deux ports de développement,
+ * rôle client `admin` (`roleMapping: { admin: "ROLE_ADMIN" }`), et les
+ * audiences des zones `external-jwt` que la configuration rendue déclare.
+ *
+ * @param appName - nom de l'application (= realm = identifiant de client)
+ * @param themes - types de thème à déclarer
+ * @param ids - `sub` des comptes de démonstration, FIXÉS dans le fichier :
+ *   laissés à Keycloak, ils changent à chaque réimport et la connexion
+ *   suivante est refusée (identifiant déjà lié à un autre `sub`)
+ * @param audiences - ressources que les jetons du realm doivent porter
+ *   (mapper sur les deux clients) ; vide = aucune zone ne les accepte
+ * @returns l'entrée du constructeur de realm
+ */
+export declare function appDevRealmInput(appName: string, themes: readonly TThemeType[], ids: {
+    readonly user: string;
+    readonly admin: string;
+}, audiences?: readonly string[]): IKeycloakRealmInput;
+/**
+ * Recopie les thèmes livrés dans l'application — `nodefony` et ses thèmes
+ * d'habillage —, fichier par fichier, sans jamais remplacer un fichier présent.
+ *
+ * @param context - contexte de contribution
+ */
+export declare function copyKeycloakTheme(context: IAppContributionContext): void;
+/**
+ * Pose le realm d'import et le thème Keycloak, si l'application monte un
+ * décor Keycloak.
+ *
+ * @param context - contexte fourni par le cœur (`runAppContributions`)
+ */
+export declare function contributeKeycloak(context: IAppContributionContext): void;
+export {};

package/dist/types/nodefony/keycloak/security-keycloak-realm.d.ts

@@ -0,0 +1,43 @@
+import { CliKernel, Command } from "nodefony";
+/**
+ * `nodefony security:keycloak:realm` — le realm Keycloak que la configuration
+ * de l'application implique.
+ *
+ * Le realm d'import répète ce que la config dit déjà : identifiant du client,
+ * URL de retour, audience de chaque zone, rôles de `roleMapping`. Écrit à la
+ * main, il diverge — et le symptôme est un 401 ou une URL de retour refusée,
+ * jamais un message qui nomme la cause. Cette commande le DÉRIVE, par le
+ * service `keycloak` — qui porte toutes les actions Keycloak ; elle n'en
+ * garde que l'affichage et les codes de sortie.
+ *
+ * Elle FUSIONNE dans le fichier existant au lieu de l'écraser : comptes de
+ * démonstration, titres, secret machine, mappers posés dans la console
+ * survivent (`mergeKeycloakRealm`, cœur — le même constructeur que
+ * `create app`).
+ *
+ * - sans option : affiche le realm fusionné ;
+ * - `--write` : l'écrit (le fichier par défaut est l'unique `.json` de
+ *   `docker/keycloak/import/`) ;
+ * - `--check` : sort en 1 si le fichier n'est plus à jour — la garde de CI ;
+ * - `--apply` : pose sur le realm EXISTANT le thème de connexion qui suit
+ *   `loginPage.skin`, par l'API d'administration (service `keycloak`) —
+ *   développement seulement, compte `oauth2.providers.<nom>.admin` requis.
+ *
+ * ⚠️ Keycloak n'importe un realm qu'à sa CRÉATION : un realm déjà présent
+ * n'est pas relu. Après `--write`, le porter par un import PARTIEL (clients en
+ * « Overwrite » : comptes et seconds facteurs survivent) ; retirer le volume
+ * ne se fait que sur un realm qui ne porte rien à garder.
+ */
+declare class SecurityKeycloakRealm extends Command {
+    #private;
+    constructor(cli: CliKernel);
+    generate(opts: {
+        write?: string | boolean;
+        check?: string | boolean;
+        apply?: boolean;
+        provider?: string;
+        machine?: string;
+        backchannelOrigin?: string;
+    }): Promise<this>;
+}
+export default SecurityKeycloakRealm;

package/dist/types/nodefony/scaffold/contribute.d.ts

@@ -0,0 +1,15 @@
+import type { IAppContributionContext } from "nodefony";
+/**
+ * Le point de contribution de `@nodefony/security` : ce que le paquet livre à
+ * une application, déclaré dans son `package.json` (`nodefony.contribute`) et
+ * joué par le cœur, qui n'en connaît rien.
+ *
+ * @module
+ */
+/**
+ * La contribution du paquet — aujourd'hui le seul décor Keycloak de
+ * développement (`nodefony/keycloak/`).
+ *
+ * @param context - contexte fourni par le cœur (`runAppContributions`)
+ */
+export declare function contribute(context: IAppContributionContext): void;

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

@@ -1,29 +1,50 @@
 import { Service, Module } from "nodefony";
-import { RemoteJwtVerifier } from "../src/token/RemoteJwtVerifier.js";
+import type { IAccessTokenVerifier } from "nodefony";
 /**
- * Pose (ou non) le vérificateur de jetons d'accès TIERS dans le conteneur.
+ * Pose (ou non) le vérificateur de jetons d'accès dans le conteneur — celui
+ * qu'une ressource protégée (porte MCP, zone `external-jwt`) interroge.
  *
- * Ce service est une **décision de câblage**, pas de la cryptographie : toute la
- * mécanique vit dans {@link RemoteJwtVerifier}, et la doctrine de refus dans le
- * cœur (`nodefony/src/oauth/`). Ici, on lit la configuration et on tranche une
- * seule question — cette application accepte-t-elle des jetons émis ailleurs ?
+ * Ce service est une **décision de câblage**, pas de la cryptographie : la
+ * vérification d'un jeton TIERS vit dans {@link RemoteJwtVerifier}, celle d'un
+ * jeton de CETTE application dans {@link JwtAuthenticator}, et la doctrine de
+ * refus dans le cœur (`nodefony/src/oauth/`). Ici, on tranche deux questions :
+ * l'application signe-t-elle ses jetons, et en accepte-t-elle d'ailleurs ?
  *
- * **Aucun émetteur déclaré = rien n'est posé**, et c'est le comportement voulu :
- * une porte protégée qui ne trouve pas de vérificateur refuse de servir en le
- * disant (503 + CRITIC), là où un vérificateur présent mais vide refuserait
+ * ⭐ **Un jeton signé par cette application est TOUJOURS vérifiable**, dès que
+ * sa capacité JWT est active (`security.jwt.enabled`, le défaut) — sans rien
+ * déclarer dans `resourceServer.issuers`. Une application qui émet un jeton
+ * pour sa propre porte (`nodefony security:mcp:token --resource …`) doit pouvoir
+ * le lire : sans cette règle, la porte refusait un jeton parfaitement valide,
+ * et l'application était un serveur d'autorisation dont aucune ressource ne
+ * reconnaissait la signature. Rien de nouveau ne devient valide : l'audience
+ * reste exigée, et seules celles de `jwt.audiences` sont émises.
+ *
+ * 🔴 **Il est vérifié par les règles de l'authentificateur `jwt`, pas par son
+ * jeu de clés seul** : révocation ciblée et en masse, compte encore actif. Lu
+ * comme un jeton tiers, un jeton RÉVOQUÉ — ou celui d'un compte désactivé —
+ * ouvrait encore la porte jusqu'à son expiration.
+ *
+ * L'aiguillage se fait sur l'émetteur revendiqué (`peekIssuer`), comme dans le
+ * pare-feu : l'émetteur de l'application va à la vérification locale, tout
+ * autre à la liste fermée des émetteurs tiers. Un émetteur inconnu est refusé
+ * sans la moindre requête sortante.
+ *
+ * **Rien à vérifier = rien n'est posé** (capacité JWT coupée, aucun émetteur
+ * tiers) : une porte protégée qui ne trouve pas de vérificateur refuse alors de
+ * servir en le disant (503 + CRITIC), là où un vérificateur vide refuserait
  * chaque jeton un par un — même résultat pour l'appelant, diagnostic beaucoup
  * plus difficile pour l'exploitant.
  *
- * Le coût est nul quand la capacité n'est pas utilisée : rien n'est instancié,
- * aucune requête n'est faite au démarrage. La découverte des clés n'a lieu qu'au
- * PREMIER jeton réellement présenté, et une seule fois par émetteur.
+ * Le coût est nul tant qu'aucun jeton n'est présenté : aucune requête au
+ * démarrage, clés locales lues au premier jeton, découverte d'un émetteur tiers
+ * au premier jeton qui s'en réclame.
  */
 declare class AccessTokenVerifierService extends Service {
     #private;
     module: Module;
     constructor(module: Module);
-    /** Le vérificateur, ou `null` si aucun émetteur n'est déclaré. */
-    get verifier(): RemoteJwtVerifier | null;
+    /** Le vérificateur posé, ou `null` si rien n'est vérifiable. */
+    get verifier(): IAccessTokenVerifier | null;
 }
 export default AccessTokenVerifierService;
 export { AccessTokenVerifierService };

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

@@ -40,11 +40,22 @@ declare class ApiKeyService extends Service {
      * Émet une nouvelle clé API pour un porteur — renvoie sa vue publique **+ le
      * token en clair** (affiché une seule fois).
      *
+     * Un scope que le porteur ne peut pas OBTENIR — réservé par
+     * `grantableScopes` à des rôles qu'il n'a pas, ou `admin:*` sans le rôle
+     * d'administration — refuse la création entière : une clé émise avec moins
+     * que demandé surprendrait sans qu'aucune réponse ne le dise. Même juge que
+     * l'émission des jetons ({@link refusedScopes}).
+     *
+     * @param roles - rôles du porteur tels que son compte les porte ; omis =
+     *   aucun rôle, donc tout scope réservé est refusé (fail-closed).
      * @throws ApiKeyError 400 — nom vide/trop long, scope hors catalogue, expiry invalide.
+     * @throws ApiKeyError 403 — scope réservé à des rôles que le porteur n'a pas.
      * @throws ApiKeyError 409 — plafond `maxPerSubject` atteint.
-     * @throws ApiKeyError 503 — store indisponible.
+     * @throws ApiKeyError 403 — aucun compte sous cet identifiant (la clé est liée
+     *   à l'`id` immuable du compte, lu dans l'annuaire).
+     * @throws ApiKeyError 503 — store ou annuaire `users` indisponible.
      */
-    createForSubject(subjectId: string, subjectType: "user" | "service", opts: ICreateApiKeyOptions): Promise<IApiKeyCreated>;
+    createForSubject(subjectId: string, subjectType: "user" | "service", opts: ICreateApiKeyOptions, roles?: readonly string[]): Promise<IApiKeyCreated>;
     /** Liste les clés (PAT) d'un porteur — vue publique, sans secret, récentes d'abord. */
     listForSubject(subjectId: string): Promise<IApiKeyView[]>;
     /**

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

@@ -1,4 +1,5 @@
 import { Service, Module } from "nodefony";
+import type { ILoginPageDescription } from "nodefony";
 import type { ContextType, ISession } from "@nodefony/http";
 /**
  * Projection PUBLIQUE de l'utilisateur — ce qui sort en JSON vers le client.
@@ -7,7 +8,7 @@ import type { ContextType, ISession } from "@nodefony/http";
  */
 export interface ISafeUser {
     id: string;
-    username: string;
+    identifier: string;
     roles: string[];
 }
 /**
@@ -19,7 +20,7 @@ export type ILoginOutcome = {
     user: ISafeUser;
 } | {
     status: "mfa_required";
-    methods: ["totp"];
+    methods: readonly string[];
 };
 /**
  * Flux de session BFF — login/logout/me côté serveur (P6 J3).
@@ -56,6 +57,8 @@ declare class AuthFlow extends Service {
      * @param identifier - identifiant saisi (body JSON, non typé à la frontière).
      * @param password - mot de passe saisi.
      * @returns `authenticated` (identité établie) ou `mfa_required` (2ᵉ facteur requis).
+     * @throws InsecureTransportError (403) — mot de passe reçu en clair en
+     *   production (refusé AVANT le throttle et le verifier).
      * @throws ThrottledError (429 + `Retry-After`) — backoff actif.
      * @throws AuthenticationError (401, message uniforme) — credential absent ou
      *   invalide.
@@ -86,6 +89,7 @@ declare class AuthFlow extends Service {
      * @param context - contexte HTTP (porte la session PENDING).
      * @param code - code présenté (TOTP ou code de récupération).
      * @returns la projection publique de l'utilisateur authentifié.
+     * @throws InsecureTransportError (403) — code reçu en clair en production.
      * @throws ThrottledError (429) — trop de tentatives.
      * @throws AuthenticationError (401, uniforme) — aucun défi en cours, code absent
      *   ou invalide (la session N'est PAS ouverte ; le défi reste pour un retry).
@@ -110,14 +114,42 @@ declare class AuthFlow extends Service {
      * @returns `true` si une session a réellement été détruite.
      */
     logout(context: ContextType): Promise<boolean>;
+    /**
+     * Déconnexion COMPLÈTE : détruit la session locale et rend, si la session
+     * vient d'un fournisseur qui publie un point de déconnexion (Keycloak…),
+     * l'adresse où envoyer le navigateur pour fermer AUSSI sa session à lui —
+     * sans quoi le clic suivant sur « Continuer avec … » reconnecte sans mot de
+     * passe (OpenID Connect RP-Initiated Logout 1.0).
+     *
+     * @returns `destroyed` comme {@link logout} ; `logoutUrl` à suivre, ou `null`.
+     */
+    logoutWithProvider(context: ContextType): Promise<{
+        destroyed: boolean;
+        logoutUrl: string | null;
+    }>;
     /**
      * Identité portée par la session courante, re-résolue auprès du provider
      * (mêmes contrôles que le `SessionAuthenticator` — source unique).
      *
      * @returns la projection publique, ou `null` (pas de session, session
-     *   orpheline, compte verrouillé/désactivé) — le handler répond 401.
+     *   orpheline, compte verrouillé/désactivé) — le handler répond `200`
+     *   `{ user: null }`.
      */
     me(context: ContextType): Promise<ISafeUser | null>;
+    /**
+     * Décrit la page de connexion par défaut : ce qu'elle propose et comment
+     * elle s'habille, depuis `security.loginPage` et les fournisseurs
+     * opérationnels.
+     *
+     * Lue par le contrôleur de `@nodefony/framework`, qui n'importe pas ce
+     * paquet. Les fournisseurs sont relus à chaque appel : l'un d'eux peut
+     * tomber ou revenir pendant que le serveur tourne.
+     *
+     * @returns la description, ou `null` quand la page par défaut est
+     *   désactivée (`loginPage.enabled: false`) ou la configuration invalide —
+     *   le contrôleur répond alors 404.
+     */
+    describeLoginPage(): ILoginPageDescription | null;
 }
 export default AuthFlow;
 export { AuthFlow };

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

@@ -90,7 +90,7 @@ declare class Firewall extends Service implements IFirewall {
     isSecure(context: ContextType): boolean;
     /**
      * Pipeline complet de la zone : chaîne d'authenticators (selon `mode`) → ALS
-     * → Zero Trust. Rejette (401, challenge RFC 7235 posé) ou résout.
+     * → Zero Trust. Rejette (401, challenge RFC 9110 §11 posé) ou résout.
      */
     handleSecurity(context: ContextType): Promise<ContextType>;
     /**
@@ -102,8 +102,13 @@ declare class Firewall extends Service implements IFirewall {
      *    synchronizer token (`context.csrfToken`) — HttpContext pose ensuite le cookie
      *    lisible `csrf-token`. Sinon, hot-path GET = retour immédiat (aucun en-tête lu).
      *  - **Étape 1 (globale)** : sur une mutation, défense Fetch Metadata / Origin
-     *    (rejet cross-site même sur route publique). Skippée si `@CsrfExempt` (webhook,
-     *    auth par signature/clé) ou `bypassFirewall` (callbacks OAuth).
+     *    (rejet cross-site même sur route publique). Skippée SEULEMENT par `@CsrfExempt`
+     *    (webhook, auth par signature/clé). `bypassFirewall` ne l'en dispense PAS : il
+     *    retire l'authentification, pas la provenance — les routes de connexion sont
+     *    en bypass, et c'est précisément là qu'un formulaire tiers ouvrirait chez la
+     *    victime une session sur le compte de l'attaquant (login CSRF, CWE-352). Un
+     *    appel de serveur à serveur (canal arrière OIDC) ne porte ni `Sec-Fetch-Site`
+     *    ni `Origin` : il passe toujours.
      *  - **Étape 2 (opt-in)** : sur une mutation `@CsrfProtect`, exige EN PLUS le
      *    synchronizer token (en-tête `x-csrf-token` ≡ cookie + HMAC valide).
      *
@@ -124,6 +129,15 @@ declare class Firewall extends Service implements IFirewall {
      *   réponse), sinon `undefined` (la requête réelle suit le pipeline normal).
      */
     handleCors(context: ContextType): number | undefined;
+    /**
+     * Le revalidateur de l'identité de la requête courante, pour une connexion
+     * longue qui la gardera (flux SSE). Même règle, même store de jetons que les
+     * sockets WebSocket — un transport qui en aurait une autre serait celui
+     * qu'un attaquant prendrait pour survivre à sa révocation.
+     *
+     * @returns `null` pour un anonyme ; sinon la fonction qui re-valide.
+     */
+    currentRevalidator(): ((nowMs?: number) => Promise<boolean>) | null;
     /**
      * En-têtes de sécurité APPLICATIFS (P6 J5) — CSP, Referrer-Policy, isolation
      * cross-origin (COOP/COEP/CORP), Origin-Agent-Cluster, Permissions-Policy.