@nodefony/security 10.0.0-alpha.1

package/dist/types/nodefony/src/authenticator/ExternalJwtAuthenticator.d.ts

@@ -0,0 +1,132 @@
+import { type Container } from "nodefony";
+import type { ContextType } from "@nodefony/http";
+import type { IAuthenticator } from "../../contracts/IAuthenticator.js";
+import type { ISecuredArea } from "../../contracts/ISecuredArea.js";
+import type { IToken } from "../../contracts/IToken.js";
+import { type ExternalSubjectMapping } from "./externalSubject.js";
+/** Comment le sujet d'un jeton devient un utilisateur de cette application. */
+export type ExternalSubjectPolicy = "require" | "ephemeral";
+/** Un émetteur reconnu, et la façon dont ses sujets entrent chez nous. */
+export interface IExternalIssuerBinding {
+    /** Émetteur de confiance, sous sa forme canonique. */
+    issuer: string;
+    /** Comment le `sub` de CET émetteur devient un identifiant local. */
+    subjectMapping: ExternalSubjectMapping;
+}
+/** Ce que la fabrique doit fournir à l'authenticator. */
+export interface IExternalJwtAuthenticatorOptions {
+    /**
+     * Émetteurs de confiance, et leur politique de sujet.
+     *
+     * La liste sert à deux choses, qu'il ne faut pas confondre : reconnaître les
+     * jetons qui relèvent de cet authenticator (aiguillage — elle n'accorde
+     * rien, le vérificateur refait le contrôle sur sa propre liste), et savoir
+     * dans quel espace de noms lire le sujet de chacun.
+     */
+    issuers: readonly IExternalIssuerBinding[];
+    /** Politique de rattachement du sujet à un utilisateur local. */
+    subjectPolicy: ExternalSubjectPolicy;
+    /** Rôles accordés en mode `ephemeral`. */
+    ephemeralRoles: readonly string[];
+}
+/**
+ * Authentification par **jeton d'accès émis par un serveur d'autorisation
+ * TIERS** (Keycloak, Auth0, Entra, ou l'émetteur d'une flotte d'agents).
+ *
+ * C'est le chaînon qui relie deux pièces déjà en place : le vérificateur de
+ * jetons distants, qui sait lire un jeton dont on ne possède pas la clé, et le
+ * pare-feu, qui raisonne en utilisateurs et en rôles. Le vérificateur s'arrête
+ * à un sujet et des scopes — délibérément, car établir une identité
+ * applicative est une décision de l'application, pas du protocole. C'est cette
+ * décision-là que porte cette classe, et rien d'autre.
+ *
+ * ## Cohabitation avec les jetons maison
+ *
+ * `JwtAuthenticator` et celui-ci reconnaissent la même forme de credential.
+ * Chacun ne prend donc que les jetons dont l'émetteur revendiqué est le sien
+ * ({@link peekIssuer}) — lecture non vérifiée qui ne sert qu'à AIGUILLER. Sans
+ * cela, en mode `first`, le premier listé capturerait les deux familles et
+ * refuserait la moitié des jetons : l'ordre de la configuration deviendrait
+ * une décision de sécurité, dont l'erreur ne se verrait qu'en production.
+ *
+ * ## Ce qui vaut garantie
+ *
+ * - **L'audience vient de la ZONE**, jamais du jeton, et elle est obligatoire :
+ *   sans elle l'authenticator refuse de démarrer ({@link validateArea}).
+ * - **Un refus est un 401 uniforme ; une PANNE est un 503** — un émetteur
+ *   injoignable n'est pas un jeton invalide, et le dire autrement enverrait le
+ *   client renouveler en boucle un jeton parfaitement bon.
+ * - **Le sujet est revérifié localement** en mode `require` : un compte
+ *   supprimé, désactivé ou verrouillé ferme l'accès sans attendre l'expiration
+ *   du jeton, que l'application ne contrôle pas.
+ *
+ * - **Le sujet n'entre jamais nu dans l'espace de noms local** : un `sub` n'est
+ *   unique que chez son émetteur, et le rattachement passe donc par
+ *   {@link localIdentifierFor}, piloté par le `subjectMapping` de CET émetteur.
+ * - **Le refus est apprenable** : le défi porte le pointeur `resource_metadata`
+ *   (RFC 9728), qui dit au client où aller chercher de quoi obtenir un jeton.
+ */
+export declare class ExternalJwtAuthenticator implements IAuthenticator {
+    #private;
+    readonly name = "external-jwt";
+    /**
+     * @param container - container DI (résolution lazy du vérificateur et de `users`)
+     * @param options - émetteurs reconnus et politique de rattachement
+     */
+    constructor(container: Container, options: IExternalJwtAuthenticatorOptions);
+    /**
+     * La requête porte-t-elle un jeton se réclamant d'un émetteur de confiance ?
+     *
+     * Le contrôle est délibérément le MÊME que celui du vérificateur, et non un
+     * simple « c'est un JWT » : un jeton maison ne doit pas être capturé ici, et
+     * un jeton d'un émetteur inconnu n'a pas à provoquer le moindre travail.
+     */
+    supports(context: ContextType): boolean;
+    /**
+     * Extrait le jeton brut ET l'audience de la zone.
+     *
+     * L'audience transite par le token parce que `authenticate()` ne reçoit pas
+     * le contexte : c'est ici, et seulement ici, qu'on sait quelle ressource est
+     * visée.
+     */
+    createToken(context: ContextType): Promise<IToken>;
+    /**
+     * Vérifie le jeton auprès de son émetteur, puis rattache le sujet.
+     *
+     * @throws AuthenticationError (401) — jeton refusé, ou sujet sans compte
+     *   local utilisable
+     * @throws UnverifiableTokenError (503) — rien ne peut vérifier ce jeton, ou
+     *   l'émetteur est injoignable : on ne sait pas, et on le dit
+     */
+    authenticate(token: IToken): Promise<IToken>;
+    /** Slot audit — le firewall enregistre déjà succès et échec par zone. */
+    onSuccess(_context: ContextType, _token: IToken): Promise<void>;
+    /** Slot audit — le 401 et le défi sont posés par le firewall. */
+    onFailure(_context: ContextType, _error: Error): Promise<void>;
+    /**
+     * Défi RFC 6750 + pointeur RFC 9728, posé par le firewall sur les 401.
+     *
+     * ⭐ **C'est cet en-tête qui rend l'autorisation apprenable.** Un `Bearer` nu
+     * est un mur : le client sait qu'il lui faut un jeton, mais pas où le
+     * demander. `resource_metadata` nomme le document qui le lui dira — c'est le
+     * seul mécanisme normalisé pour ça, et celui qu'un client MCP conforme suit.
+     *
+     * Aucun `error` n'est joint : le firewall pose ce défi sur TOUT 401 de la
+     * zone, sans savoir si la requête portait un jeton. Or la RFC 6750 §3
+     * demande de ne PAS mettre de code d'erreur quand elle n'en portait aucun —
+     * un `invalid_token` ferait renouveler en boucle un jeton qui n'existe pas.
+     *
+     * @param area - zone refusante ; sans elle (ou sans ressource déclarée) le
+     *   défi retombe sur `Bearer` nu, faute de ressource à nommer
+     */
+    challenge(area?: ISecuredArea): string;
+    /**
+     * Refuse une zone sans ressource — au boot, pas à la première requête.
+     *
+     * Sans audience, la vérification accepterait un jeton émis pour un autre
+     * service : le seul verrou qui lie un jeton à CE service disparaîtrait, et
+     * l'application n'en saurait rien.
+     */
+    validateArea(area: ISecuredArea): void;
+}
+export default ExternalJwtAuthenticator;

package/dist/types/nodefony/src/authenticator/FirewallRealtimeAuthenticator.d.ts

@@ -0,0 +1,78 @@
+import type { IRealtimeAuthenticator, IRealtimeHandshake, IRealtimeToken } from "../realtime/realtimeContracts.js";
+/**
+ * Authenticator realtime des identités résolues par le **firewall** — équivalent
+ * WS de tout ce que le pipeline HTTP sait authentifier.
+ *
+ * ── Pourquoi il NE re-lit PAS la base ──────────────────────────────────────
+ * Un handshake WebSocket est une requête upgrade HTTP qui traverse le MÊME
+ * pipeline : `startSession` (reprise L1 du cookie) **puis** `firewall.handleSecurity`
+ * tournent AVANT que le `RealtimeController` ne fasse son handshake. Sur une zone
+ * data plane, le firewall a donc DÉJÀ : (1) authentifié (session, JWT, clé API…),
+ * (2) re-résolu l'identité via le provider `users` (rôles frais), (3) posé
+ * l'`IUser` **et le jeton** dans l'ALS et appliqué le Zero Trust (un anonyme est
+ * fermé AVANT d'arriver ici). Re-décoder le credential ici referait des lectures
+ * base **redondantes** par connexion — sur le différenciateur temps réel, un coût
+ * évitable. → on **réutilise** l'identité déjà en ALS.
+ *
+ * Le `RealtimeController.onHandshake` s'exécute dans la même bulle ALS que le
+ * firewall (un seul `RequestContext.run` enveloppe handshake + frames) → la
+ * lecture est sûre et synchrone.
+ *
+ * ── Il n'est PAS l'authenticator « de la session » ──────────────────────────
+ * Son nom d'origine (`SessionRealtimeAuthenticator`) décrivait le premier mode
+ * branché, pas son rôle : il promeut **toute** identité que le firewall a posée,
+ * y compris un agent authentifié par jeton porteur, sans cookie ni session. La
+ * confusion a coûté cher — un durcissement pensé pour la session a été appliqué
+ * à toutes les identités, et une connexion JWT parfaitement valide se faisait
+ * révoquer au motif qu'elle n'avait pas de session. D'où le nom actuel : il dit
+ * d'où vient l'identité (le firewall), pas comment elle a été prouvée.
+ *
+ * ── Révocation : un invariant, deux preuves ────────────────────────────────
+ * L'invariant est unique — **une socket ne survit pas à l'identité qui l'a
+ * ouverte** — mais la preuve dépend du mode, parce que ce sont deux mécanismes
+ * de révocation différents :
+ *
+ * | Mode                       | Ce qui rend l'identité morte                     |
+ * | -------------------------- | ------------------------------------------------ |
+ * | session BFF (`session`)    | session détruite, expirée, ou passée à un autre  |
+ * | jeton porteur (JWT, clé…)  | `exp` atteint · `jti` denylisté · `invalidBefore` |
+ *
+ * Le jeton est figé au handshake (les frames lisent un cache O(1), jamais la
+ * base) ; la re-validation tourne sur le tick du hub (`REVOCATION_REVALIDATE_MS`)
+ * et devant chaque `api.request`. Une révocation prend donc effet en une fenêtre,
+ * pas à la frame suivante — c'est l'état de l'art (Socket.IO/Phoenix figent aussi
+ * l'identité au handshake).
+ */
+export declare class FirewallRealtimeAuthenticator implements IRealtimeAuthenticator {
+    #private;
+    readonly name = "firewall-realtime";
+    /**
+     * @param resolveStore - fournit le store de révocation des jetons (le firewall
+     *   passe une closure sur son container). Omis → mode dégradé documenté :
+     *   seules les bornes portées par le jeton lui-même sont vérifiables.
+     */
+    constructor(resolveStore?: (() => IRealtimeRevocationStore | null) | null);
+    /** Une identité authentifiée a-t-elle été résolue (par le firewall) au handshake ? */
+    supports(_handshake: IRealtimeHandshake): boolean;
+    /**
+     * Promeut l'identité déjà résolue (ALS) en jeton realtime — 0 lecture base.
+     *
+     * @throws AuthenticationError — aucune identité authentifiée en ALS (ne devrait
+     *   pas arriver sur une zone data plane : le firewall ferme l'anonyme en amont ;
+     *   filet défensif fail-closed → le hub ferme la socket en 4001).
+     */
+    authenticate(_handshake: IRealtimeHandshake): Promise<IRealtimeToken>;
+}
+/**
+ * Surface MINIMALE du store de jetons consommée ici : les deux lectures qui
+ * disent si un jeton a été révoqué avant son terme. Typée localement plutôt
+ * qu'importée d'`ITokenStore` — ce module n'a besoin ni du reste du contrat ni
+ * du couplage, et un test peut fournir un double en deux lignes.
+ */
+export interface IRealtimeRevocationStore {
+    /** `true` si ce `jti` a été mis sur la denylist et n'est pas encore expiré. */
+    isJtiDenied(jti: string): Promise<boolean>;
+    /** Seuil de révocation en masse du porteur (epoch ms), ou `null`. */
+    getInvalidBefore(subjectId: string): Promise<number | null>;
+}
+export default FirewallRealtimeAuthenticator;

package/dist/types/nodefony/src/authenticator/JwtAuthenticator.d.ts

@@ -0,0 +1,69 @@
+import type { Container } from "nodefony";
+import type { ContextType } from "@nodefony/http";
+import type { IAuthenticator } from "../../contracts/IAuthenticator.js";
+import type { IToken } from "../../contracts/IToken.js";
+import type { IJwtRuntime } from "../token/jwtRuntime.js";
+/**
+ * Authentification par **JWT Bearer** (RFC 6750) — réservée API service↔service /
+ * agents (le web utilise la session BFF). Vérifie un access token EdDSA signé par
+ * le {@link IJwtKeystore} du serveur.
+ *
+ * Défenses **dures** (RFC 8725 JWT BCP, prouvées en test) :
+ *  - **allowlist d'algorithmes** côté serveur (`["EdDSA"]`) — l'algo n'est JAMAIS
+ *    choisi d'après l'en-tête du token (§3.1) ; `alg=none` jamais accepté par jose.
+ *  - **clé par `kid` depuis le keyset LOCAL** (`createLocalJWKSet`) — jamais
+ *    `jku`/`jwk` de l'en-tête (injection de clé / SSRF, §3.5).
+ *  - **`aud` (§3.9) + `iss` (§3.8) obligatoires** + `typ:"at+jwt"` (§3.11, sépare
+ *    access et refresh) + `exp`/`nbf` (jose).
+ *  - **révocation** : denylist `jti` + seuil `invalidBefore` par porteur (le JWT
+ *    est auto-porté et non révocable sans état serveur).
+ *  - **sujet revérifié** (§3.10) : `loadUserByIdentifier(sub)` → compte disparu,
+ *    inactif ou verrouillé = rejet.
+ *
+ * Dépendances (keystore, store, userProvider) résolues **paresseusement** du
+ * container au premier usage (cold path) ; jose importé **lazy** (dep lourde).
+ */
+export declare class JwtAuthenticator implements IAuthenticator {
+    #private;
+    readonly name = "jwt";
+    /**
+     * @param container - container DI (résolution lazy de `jwtKeystore`/`tokenStore`/`users`).
+     * @param runtime - paramètres JWT effectifs (iss/aud/ttl) partagés avec l'émetteur.
+     */
+    constructor(container: Container, runtime: IJwtRuntime);
+    /**
+     * La requête porte-t-elle un `Authorization: Bearer <jws>` émis par NOUS ?
+     *
+     * L'émetteur revendiqué est lu sans être vérifié ({@link peekIssuer}) et sert
+     * uniquement à AIGUILLER : `ExternalJwtAuthenticator` reconnaît la même forme
+     * de credential pour les jetons d'un serveur d'autorisation tiers. Sans ce
+     * discriminant, en mode `first`, le premier des deux listés dans la zone
+     * capturerait les deux familles et refuserait la moitié des jetons — l'ordre
+     * de la configuration deviendrait une décision de sécurité, dont l'erreur ne
+     * se verrait qu'en production.
+     *
+     * Un jeton dont l'émetteur est illisible reste pris en charge ici : c'est un
+     * jeton maison malformé, que la vérification refusera en le disant, plutôt
+     * qu'un credential qui disparaîtrait sans laisser de trace.
+     */
+    supports(context: ContextType): boolean;
+    /** Extrait le token brut (non vérifié) → porté par un `UserToken` type `"jwt"`. */
+    createToken(context: ContextType): Promise<IToken>;
+    /**
+     * Vérifie la signature + les claims du JWT, applique la révocation et résout le
+     * sujet — ou lève un 401 au message uniforme.
+     *
+     * @throws AuthenticationError (401) — token absent/invalide/expiré/révoqué, ou
+     *   sujet disparu/banni.
+     * @throws Error (câblage : keystore/store/users absents) — logguée ERROR par le
+     *   firewall puis 401 fail-closed (rien ne fuite au client).
+     */
+    authenticate(token: IToken): Promise<IToken>;
+    /** Slot audit (J4b). */
+    onSuccess(_context: ContextType, _token: IToken): Promise<void>;
+    /** Slot audit (J4b) — le 401 + challenge sont posés par le firewall. */
+    onFailure(_context: ContextType, _error: Error): Promise<void>;
+    /** Challenge RFC 6750/7235 posé par le firewall sur les 401 de la zone. */
+    challenge(): string;
+}
+export default JwtAuthenticator;

package/dist/types/nodefony/src/authenticator/SessionAuthenticator.d.ts

@@ -0,0 +1,70 @@
+import type { ContextType } from "@nodefony/http";
+import type { IUserProvider } from "@nodefony/user";
+import type { IAuthenticator } from "../../contracts/IAuthenticator.js";
+import type { ISecuredArea } from "../../contracts/ISecuredArea.js";
+import type { IToken } from "../../contracts/IToken.js";
+/**
+ * Authentification par **session serveur** (cookie opaque, modèle BFF) — la
+ * preuve des requêtes qui SUIVENT le login (`AuthFlow.login`, qui a déjà posé
+ * l'identifiant dans le blob et régénéré l'ID anti-fixation).
+ *
+ * `supports()` exige une session REPRISE porteuse d'un utilisateur : le
+ * pipeline http démarre la session AVANT le firewall (point d'activation
+ * unique, lazy — cookie entrant ou intent de route), cet authenticator ne
+ * démarre jamais rien lui-même. L'identité est re-résolue à CHAQUE requête
+ * via {@link resolveSessionIdentity} (rôles frais, révocation immédiate).
+ *
+ * Pas de `challenge()` : une session absente/expirée donne un 401 nu — le
+ * client web redirige vers son écran de login, jamais de popup Basic. Si la
+ * zone liste aussi `userpassword`, le firewall pose SON challenge (RFC 7235).
+ */
+export declare class SessionAuthenticator implements IAuthenticator {
+    #private;
+    readonly name = "session";
+    /**
+     * @param resolveProvider - résolution lazy de la source d'identité
+     *   (typiquement `container.get("users")`) — appelée à la première requête.
+     */
+    constructor(resolveProvider: () => IUserProvider);
+    /**
+     * Refuse une zone déclarée SANS REGISTRE — au boot, pas à la première requête.
+     *
+     * `stateless: true` annonce que l'identité tient tout entière dans la preuve
+     * portée par chaque requête, et que la session est ignorée « même si un
+     * cookie est présent ». Lister `session` dans une telle zone dit exactement
+     * l'inverse : {@link supports} y rendrait vrai dès qu'un cookie ramène une
+     * session porteuse d'un utilisateur, et la zone authentifierait par le
+     * registre qu'elle déclare ne pas tenir.
+     *
+     * Cette contradiction ne se voyait NULLE PART : l'application démarrait, la
+     * console d'administration affichait « aucun registre serveur », et le
+     * cookie authentifiait quand même. Elle se refuse donc au démarrage — le
+     * firewall en fait une erreur de configuration fail-closed, plutôt qu'une
+     * requête sur deux qui se comporte autrement que ce qui est écrit.
+     *
+     * @param area - la zone qui liste cet authenticator.
+     * @throws Error si la zone est `stateless` — le message la NOMME.
+     */
+    validateArea(area: ISecuredArea): void;
+    /** La requête porte-t-elle une session reprise avec un utilisateur ? */
+    supports(context: ContextType): boolean;
+    /** Extrait l'identifiant du blob de session (jamais de secret en jeu). */
+    createToken(context: ContextType): Promise<IToken>;
+    /**
+     * Re-résout l'identifiant de session en utilisateur vivant et promeut le
+     * token. Les contrôles d'état (existe, actif, non verrouillé) vivent dans
+     * {@link resolveSessionIdentity} — partagés avec `AuthFlow.me()`.
+     *
+     * @throws AuthenticationError (401, message uniforme) — session orpheline,
+     *   compte verrouillé ou désactivé.
+     */
+    authenticate(token: IToken): Promise<IToken>;
+    /**
+     * Pose l'identifiant sur le contexte : la persistance de session du pipeline
+     * (`saveSession`) lie le blob au principal courant (string attendu).
+     */
+    onSuccess(context: ContextType, token: IToken): Promise<void>;
+    /** Slot audit (P6.14). Le 401 est posé par le firewall. */
+    onFailure(_context: ContextType, _error: Error): Promise<void>;
+}
+export default SessionAuthenticator;

package/dist/types/nodefony/src/authenticator/UserPasswordAuthenticator.d.ts

@@ -0,0 +1,53 @@
+import type { ContextType } from "@nodefony/http";
+import type { IPasswordVerifier } from "@nodefony/user";
+import type { IAuthenticator } from "../../contracts/IAuthenticator.js";
+import type { IToken } from "../../contracts/IToken.js";
+import type { LoginThrottler } from "../throttle/LoginThrottler.js";
+/**
+ * Authentification par identifiant + mot de passe — schéma **HTTP Basic**
+ * (RFC 7617) : `Authorization: Basic base64(identifiant:motdepasse)`, charset
+ * UTF-8, split au PREMIER `:` (le mot de passe peut en contenir).
+ *
+ * La vérification est déléguée au {@link IPasswordVerifier} (`UserService` par
+ * défaut) : hash, comparaison, leurre anti-timing et re-hash transparent restent
+ * derrière la frontière user — cet authenticator ne voit que le verdict.
+ *
+ * Le verifier est résolu **paresseusement** au premier login (cold path) : le
+ * boot ne paie rien et l'ordre de chargement des modules est indifférent.
+ *
+ * @remarks Le login par formulaire (body JSON) n'est PAS ici : il arrive avec la
+ * session BFF (`AuthController`, J3) qui appelle le verifier directement.
+ */
+export declare class UserPasswordAuthenticator implements IAuthenticator {
+    #private;
+    readonly name = "userpassword";
+    /**
+     * @param resolveVerifier - résolution lazy de la source de vérification
+     *   (typiquement `container.get("users")`) — appelée au premier login.
+     * @param throttler - limiteur de tentatives (backoff NIST), `null` = désactivé.
+     */
+    constructor(resolveVerifier: () => IPasswordVerifier, throttler?: LoginThrottler | null);
+    /** La requête porte-t-elle un en-tête `Authorization: Basic ...` ? */
+    supports(context: ContextType): boolean;
+    /** Décode l'enveloppe Basic — un contenu malformé donne un credential vide (échec uniforme). */
+    createToken(context: ContextType): Promise<IToken>;
+    /**
+     * Vérifie le credential via le verifier ou lève un 401 au message uniforme.
+     * Au succès le token est promu : utilisateur posé, credential effacé.
+     *
+     * Throttling NIST (si activé) : l'identifiant SAISI est vérifié AVANT le
+     * verifier (un identifiant bloqué ne coûte aucun hash → le throttle protège
+     * aussi le serveur du DoS argon2), échec compté, succès remis à zéro.
+     *
+     * @throws ThrottledError (429 + `Retry-After`) — backoff encore actif.
+     * @throws AuthenticationError (401) — credential absent ou invalide.
+     */
+    authenticate(token: IToken): Promise<IToken>;
+    /** Slot J3 (session BFF au login) — rien à poser pour du Basic pur. */
+    onSuccess(_context: ContextType, _token: IToken): Promise<void>;
+    /** Slot J3+ (audit events). Le throttling vit dans `authenticate` (clé = identifiant) ; le 401 + challenge sont posés par le firewall. */
+    onFailure(_context: ContextType, _error: Error): Promise<void>;
+    /** Challenge RFC 7235 posé par le firewall sur les 401 de la zone. */
+    challenge(): string;
+}
+export default UserPasswordAuthenticator;

package/dist/types/nodefony/src/authenticator/authenticatorRegistry.d.ts

@@ -0,0 +1,39 @@
+import type { Container } from "nodefony";
+import type { IAuthenticator } from "../../contracts/IAuthenticator.js";
+import type { ISecurityConfig } from "../../config/defineModuleConfig.js";
+/**
+ * Registre de **fabriques d'authenticators** — résout les noms listés dans
+ * `areas.<zone>.authenticators` vers des instances, SANS que le firewall
+ * connaisse le moindre nom en dur.
+ *
+ * Pourquoi : `IAuthenticator` est pluggable par contrat ; un
+ * `if (name === "jwt") …` dans le firewall trahirait cette promesse (couplage
+ * aux noms, fermé à l'extension). Les builtins s'enregistrent au chargement du
+ * module (donc toujours AVANT le boot) ; un plugin externe enregistre le sien
+ * (`registerAuthenticatorFactory("ldap", …)`) puis le référence en config —
+ * aucun changement dans le cœur. Convention-frère : `backplaneRegistry`
+ * (realtime), `ormRegistry` (orm-core).
+ */
+/**
+ * Contexte passé à une fabrique : tout ce dont un authenticator peut avoir
+ * besoin pour se construire. La fabrique ne fait QUE construire — résolutions
+ * de services coûteuses en lazy à l'intérieur de l'instance (cold path).
+ */
+export interface IAuthenticatorFactoryContext {
+    /** Container DI — résolution de services (`users`, `sessions`...). */
+    readonly container: Container;
+    /** Config sécurité validée + gelée (sections `jwt`, `passkeys`...). */
+    readonly config: ISecurityConfig;
+}
+/** Fabrique d'un authenticator pour un nom donné. */
+export type AuthenticatorFactory = (ctx: IAuthenticatorFactoryContext) => IAuthenticator;
+/**
+ * Enregistre (ou remplace) la fabrique d'un authenticator. Appelé par les
+ * builtins au chargement du module, et par les plugins pour les leurs
+ * (LDAP, SSO maison...).
+ */
+export declare function registerAuthenticatorFactory(name: string, factory: AuthenticatorFactory): void;
+/** Fabrique d'un authenticator par nom, ou `undefined` si inconnu. */
+export declare function getAuthenticatorFactory(name: string): AuthenticatorFactory | undefined;
+/** Noms enregistrés (validation boot, introspection Studio, tests). */
+export declare function listAuthenticatorFactories(): string[];

package/dist/types/nodefony/src/authenticator/bearer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Lecture d'un en-tête `Authorization: Bearer …`.
+ *
+ * 🔴 **L'implémentation a déménagé au CŒUR** (`nodefony`), et ce fichier n'en
+ * garde que le point d'entrée. Le motif n'est pas cosmétique : deux couches qui
+ * ne se voient pas lisent le même en-tête — les authentificateurs d'ici, et le
+ * rôle *serveur de ressource* OAuth, qui vit au cœur parce qu'il ne dépend
+ * d'aucun module. Une frontière de paquets aurait imposé une copie, et une copie
+ * de cette fonction ne diverge pas bruyamment : elle diverge sur un cas limite
+ * (`Bearer` sans séparateur, espace insécable, jeton vide) que **chaque copie
+ * continue de passer dans ses propres tests**.
+ *
+ * Ce qui l'a motivée reste vrai et se relit au cœur : le motif d'origine était
+ * quadratique, et il s'exécutait avant toute authentification — donc pour un
+ * porteur qui n'avait rien prouvé.
+ *
+ * Les tests d'ici (`tests/unit/bearer.test.ts`, cas anti-ReDoS compris) valent
+ * désormais pour l'implémentation du cœur : ils l'atteignent par ce point
+ * d'entrée, ce qui est exactement le contrôle qu'on veut sur une brique
+ * partagée.
+ */
+export { bearerToken } from "nodefony";

package/dist/types/nodefony/src/authenticator/externalSubject.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Comment le sujet d'un émetteur donné entre dans l'espace de noms local.
+ *
+ * - `prefixed` — l'identifiant local est composé de l'émetteur ET du sujet.
+ * - `subject` — le sujet est pris tel quel (l'espace de noms est maîtrisé).
+ */
+export type ExternalSubjectMapping = "prefixed" | "subject";
+/**
+ * Compose l'identifiant local qui désigne le sujet d'un émetteur externe.
+ *
+ * 🔴 **Un `sub` seul ne désigne personne.** OpenID Connect Core §2 ne garantit
+ * son unicité et sa non-réattribution que *dans l'espace de son émetteur*.
+ * Chercher un compte local directement par `sub` verse donc des identifiants
+ * étrangers dans l'espace local : il suffit d'un annuaire où l'utilisateur
+ * choisit son identifiant — beaucoup le permettent — pour présenter
+ * `sub: "admin"` et se voir rattacher au compte local du même nom.
+ *
+ * C'est pour cela que `prefixed` est le défaut et que `subject` se déclare :
+ * le mode sûr ne doit rien demander, le mode qui fait confiance doit être écrit.
+ *
+ * @param issuer - émetteur VÉRIFIÉ, sous sa forme canonique (jamais la valeur
+ *   brute lue dans le jeton — elle est choisie par le porteur)
+ * @param subject - sujet du jeton (`sub`)
+ * @param mapping - politique déclarée pour CET émetteur
+ * @returns l'identifiant à chercher dans l'annuaire local
+ */
+export declare function localIdentifierFor(issuer: string, subject: string, mapping: ExternalSubjectMapping): string;

package/dist/types/nodefony/src/authenticator/peekIssuer.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Lecture NON VÉRIFIÉE de l'émetteur d'un JWS compact.
+ *
+ * Sert à **choisir qui doit examiner un jeton**, jamais à décider de son sort.
+ * Deux authenticators reconnaissent la même forme de credential — un
+ * `Authorization: Bearer <jws>` — l'un pour les jetons que Nodefony a émis,
+ * l'autre pour ceux d'un serveur d'autorisation tiers. Sans discriminant, le
+ * premier listé dans la zone capture les deux et refuse la moitié des jetons :
+ * l'ordre de la configuration deviendrait une décision de sécurité, et son
+ * erreur ne se verrait qu'en production.
+ *
+ * ## Ce qui rend cette lecture sûre
+ *
+ * Rien de ce qui est lu ici ne devient une clé, une URL ou un algorithme. La
+ * valeur ne sert qu'à sélectionner une entrée dans une liste **fermée**, écrite
+ * en configuration ; le jeton est ensuite vérifié entièrement par
+ * l'authenticator retenu, `iss` compris. Un attaquant qui ment sur `iss` ne
+ * gagne donc que le droit d'être refusé par un autre maillon.
+ *
+ * La taille est bornée AVANT tout travail : `JSON.parse` sur une entrée non
+ * fiable est le genre d'appel qu'on ne laisse pas grandir sans limite.
+ */
+/**
+ * Rend le claim `iss` d'un JWS compact, sans vérifier quoi que ce soit.
+ *
+ * @param raw - le jeton brut, tel que présenté
+ * @returns l'émetteur revendiqué, ou `null` si le jeton est trop gros, mal
+ *          formé, ou ne revendique pas d'émetteur exploitable
+ */
+export declare function peekIssuer(raw: string): string | null;
+export default peekIssuer;

package/dist/types/nodefony/src/crypto/secretCipher.d.ts

@@ -0,0 +1,31 @@
+import { Buffer } from "node:buffer";
+/** Contexte de dérivation HKDF — distingue les domaines cryptographiques. */
+export interface IKeyDerivation {
+    /** Sel HKDF (RFC 5869 §3.1) — constante par domaine. */
+    readonly salt: string | Buffer;
+    /** Info HKDF (RFC 5869 §3.2) — lie la sous-clé à son usage (séparation de domaine). */
+    readonly info: string | Buffer;
+}
+/**
+ * Dérive une clé AES-256 (32 octets) d'un matériel de clé applicatif via
+ * HKDF-SHA256 (RFC 5869). Accepte toute longueur/forme (passphrase, hex, base64)
+ * sans jamais l'utiliser brute comme clé AES. **Déterministe** : tous les pods
+ * d'un cluster dérivent la même clé du même secret de config + même domaine
+ * (secret lisible cross-pod). Domaines distincts (`info` différent) → clés
+ * indépendantes.
+ *
+ * @param material - matériel de clé brut (secret de config).
+ * @param derivation - sel + info propres au domaine (TOTP, webhook…).
+ * @returns clé AES-256 (32 octets).
+ */
+export declare function deriveKey(material: string | Buffer, derivation: IKeyDerivation): Buffer;
+/** Génère une clé éphémère 32 octets (dev sans clé configurée — non persistée). */
+export declare function generateEphemeralKey(): Buffer;
+/** Chiffre un secret en clair → blob opaque versionné (IV aléatoire à chaque appel). */
+export declare function encryptSecret(plain: Buffer, key: Buffer): string;
+/**
+ * Déchiffre un blob produit par {@link encryptSecret}. Lève si le format/version
+ * est invalide, le blob tronqué, ou le tag GCM non valide (altération OU mauvaise
+ * clé — GCM ne distingue pas les deux, par construction).
+ */
+export declare function decryptSecret(blob: string, key: Buffer): Buffer;

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

@@ -0,0 +1,39 @@
+/**
+ * Fusion de directives Content-Security-Policy — logique PURE (aucune dépendance
+ * à Vite, au frontend ni au transport). Permet à un module de DÉCLARER ses besoins
+ * CSP (ex. `@nodefony/frontend` en dev : origines Vite + `'unsafe-eval'` pour le
+ * Fast Refresh) sans que `@nodefony/security` connaisse leur sémantique : security
+ * se contente de MERGER des fragments génériques `directive → sources`.
+ *
+ * Pourquoi un merge structuré (et pas une simple concaténation) : en CSP une
+ * directive RÉPÉTÉE est ignorée après sa 1ʳᵉ occurrence (W3C CSP3 §3) → concaténer
+ * deux `script-src` perdrait le second. Il faut fusionner les sources dans UNE
+ * directive. Le token `'nonce-{{nonce}}'` est opaque (ni `;` ni espace) → préservé
+ * tel quel par parse/serialize.
+ */
+/** Fragment additif d'un module : directive CSP → sources à ajouter. */
+export type CspFragment = Record<string, readonly string[]>;
+/**
+ * Parse une chaîne CSP en directives ordonnées `[nom, sources[]]`. L'ordre des
+ * directives et des sources est préservé (déterminisme : header stable, tests
+ * fiables). Les séparateurs multiples / espaces superflus sont normalisés.
+ */
+export declare function parseCsp(csp: string): Array<[string, string[]]>;
+/** Sérialise des directives ordonnées en chaîne CSP (`a b; c d`). */
+export declare function serializeCsp(directives: Array<[string, string[]]>): string;
+/**
+ * Fusionne un CSP de base avec des fragments additifs par module.
+ *
+ * - directive déjà dans la base → ses sources sont COMPLÉTÉES (dédupliquées,
+ *   ordre base d'abord puis ajouts) ;
+ * - directive absente → AJOUTÉE en fin (ordre d'apparition des fragments).
+ *
+ * Pur + déterministe : recalculé uniquement quand un module (dé)enregistre ses
+ * origines (jamais par requête). Le résultat repart dans `SecurityHeaders`, qui
+ * re-split autour de `{{nonce}}` au boot → 1 `join` par requête (hot-path inchangé).
+ *
+ * @param base - CSP de configuration (peut contenir `'nonce-{{nonce}}'`).
+ * @param fragments - fragments additifs (un par module enregistré).
+ * @returns la chaîne CSP fusionnée.
+ */
+export declare function mergeCspFragments(base: string, fragments: Iterable<CspFragment>): string;

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

@@ -0,0 +1,36 @@
+/**
+ * Jeton synchronizer CSRF — modèle **double-submit signé** (OWASP CSRF Prevention
+ * Cheat Sheet, « Signed Double-Submit Cookie »). Le token est
+ * `nonce.HMAC-SHA256(secret, nonce)` (base64url), posé dans un cookie LISIBLE
+ * (`csrf-token`, non HttpOnly) ET rejoué par le client dans l'en-tête
+ * `x-csrf-token`. La défense `@CsrfProtect` exige les deux PRÉSENTS, ÉGAUX
+ * (double-submit) et la signature HMAC VALIDE.
+ *
+ * **Stateless** (aucune session requise) → couvre le BFF (cookie de session) ET
+ * l'API JWT sans coupler au stockage de session. Le secret HMAC empêche un script
+ * tiers de forger un token (il ne peut pas calculer la signature) ; le double
+ * submit empêche un attaquant cross-site d'en injecter un (il ne peut ni écrire
+ * l'en-tête custom — préflight CORS — ni lire le cookie de la victime — SameSite + SOP).
+ *
+ * Pure et synchrone (1 HMAC à l'émission, 1 à la vérif) — payé UNIQUEMENT sur les
+ * routes `@CsrfProtect` (la défense globale Fetch Metadata reste primaire, hot-path
+ * GET = 0).
+ *
+ * @see OWASP CSRF Prevention Cheat Sheet · RFC 9110 §15.5.4 (403).
+ */
+export declare class CsrfTokenManager {
+    #private;
+    constructor(secret: string);
+    /** Émet un token signé `nonce.signature` (base64url). */
+    issue(): string;
+    /**
+     * Vérifie une mutation `@CsrfProtect` : en-tête ET cookie présents, ÉGAUX
+     * (double-submit, comparaison à temps constant) et signature HMAC valide. Tout
+     * écart → `false` (le firewall lève alors un 403). Jamais d'exception.
+     *
+     * @param headerToken - valeur de l'en-tête `x-csrf-token` rejouée par le client.
+     * @param cookieToken - valeur du cookie `csrf-token` posé par le serveur.
+     */
+    verify(headerToken: string | undefined, cookieToken: string | undefined): boolean;
+}
+export default CsrfTokenManager;