@nodefony/security 10.0.0-alpha.1

package/dist/nodefony/src/authenticator/FirewallRealtimeAuthenticator.js

@@ -0,0 +1,174 @@
+import { AuthenticationError } from "../../errors/AuthenticationError.js";
+import { UserRealtimeToken } from "../realtime/UserRealtimeToken.js";
+import { Nodefony, RequestContext } from "nodefony";
+import { anonymousUser } from "@nodefony/user";
+//#region nodefony/src/authenticator/FirewallRealtimeAuthenticator.ts
+/**
+* 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).
+*/
+var FirewallRealtimeAuthenticator = class {
+	name = "firewall-realtime";
+	/**
+	* Accès **paresseux** au store de révocation des jetons porteurs. Résolu au
+	* plus tôt à la première re-validation d'une socket à jeton — jamais au boot,
+	* jamais pour une session. Absent (`null`) → seule la borne `exp` du jeton
+	* fait foi.
+	*/
+	#resolveStore;
+	/**
+	* @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 = null) {
+		this.#resolveStore = resolveStore;
+	}
+	/** Une identité authentifiée a-t-elle été résolue (par le firewall) au handshake ? */
+	supports(_handshake) {
+		return isAuthenticatedUser(RequestContext.getUser());
+	}
+	/**
+	* 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).
+	*/
+	async authenticate(_handshake) {
+		const user = RequestContext.getUser();
+		if (!isAuthenticatedUser(user)) throw new AuthenticationError("Invalid realtime session");
+		const issued = readFirewallToken();
+		const type = typeof issued?.type === "string" && issued.type ? issued.type : "session";
+		const revalidate = type === "session" ? buildSessionRevalidator(user.identifier) : this.#buildBearerRevalidator(issued, user.identifier, type);
+		const scopes = issued ? issued.getScopes() : void 0;
+		return new UserRealtimeToken(user, revalidate, type, scopes);
+	}
+	/**
+	* Re-validation d'une identité portée par un **jeton** (JWT, clé API, OAuth) :
+	* rejoue les trois conditions qui tuent un jeton, sans jamais parler de session.
+	*
+	* `exp` est vérifié **sans personne** (la borne voyage dans le jeton) ; le store
+	* n'ajoute que la révocation *avant terme*. C'est pourquoi un store en panne ne
+	* coupe pas les sockets d'agents : ce serait une panne de disponibilité déguisée
+	* en mesure de sécurité, alors que la borne du jeton tient toujours.
+	*/
+	#buildBearerRevalidator(issued, identifier, type) {
+		const claims = issued.getAttribute("claims") ?? EMPTY_CLAIMS;
+		const expMs = secondsToMs(claims.exp);
+		const iatMs = secondsToMs(claims.iat);
+		const jti = issued.getAttribute("jti") ?? (typeof claims.jti === "string" ? claims.jti : null);
+		const resolveStore = this.#resolveStore;
+		if (expMs === null && (resolveStore === null || jti === null && iatMs === null)) {
+			Nodefony.getKernel()?.log?.(`Realtime ${type} token "${identifier}" carries neither an expiry nor any revocation handle ("jti"/"iat") — connection will be revoked (fail-closed). Ensure the authenticator forwards the token claims.`, "WARNING");
+			return () => Promise.resolve(false);
+		}
+		return async (nowMs = Date.now()) => {
+			if (expMs !== null && nowMs >= expMs) return false;
+			if (!resolveStore) return true;
+			let store;
+			try {
+				store = resolveStore();
+			} catch {
+				return expMs !== null;
+			}
+			if (!store) return expMs !== null;
+			try {
+				if (jti !== null && await store.isJtiDenied(jti)) return false;
+				const invalidBefore = await store.getInvalidBefore(identifier);
+				if (invalidBefore !== null && iatMs !== null && iatMs < invalidBefore) return false;
+				return true;
+			} catch {
+				return expMs !== null;
+			}
+		};
+	}
+};
+const EMPTY_CLAIMS = Object.freeze({});
+/** Claim temporel JWT (secondes, RFC 7519) → epoch ms, ou `null` si absent/invalide. */
+function secondsToMs(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value * 1e3 : null;
+}
+/** Le jeton posé dans l'ALS par `firewall.handleSecurity`, s'il y en a un. */
+function readFirewallToken() {
+	return RequestContext.get()?.token;
+}
+/**
+* Re-validation d'une identité portée par la **session BFF** : re-lit la session
+* (par son id, capturé au handshake) et vérifie qu'elle est TOUJOURS vivante et
+* TOUJOURS celle de `identifier` — ce qui détecte la déconnexion comme le
+* changement de compte sur un navigateur partagé.
+*
+* Renvoie TOUJOURS un revalidateur (jamais `null`) : une identité authentifiée
+* par session DOIT rester révocable. Une lecture qui throw (store down, session
+* détruite) → invalide ; une session non re-lisible au handshake → invalide
+* aussi (fail-closed, cf ci-dessous).
+*/
+function buildSessionRevalidator(identifier) {
+	const session = RequestContext.getContext()?.session;
+	const id = session?.id;
+	const storage = session?.storage;
+	if (typeof id !== "string" || !storage || typeof storage.read !== "function") {
+		Nodefony.getKernel()?.log?.(`Realtime session token "${identifier}" has no revalidatable session at handshake — connection will be revoked (fail-closed). Ensure the realtime zone runs after startSession.`, "WARNING");
+		return () => Promise.resolve(false);
+	}
+	return async () => {
+		try {
+			const serialized = await storage.read(id);
+			return !!serialized && serialized.user === identifier;
+		} catch {
+			return false;
+		}
+	};
+}
+/**
+* Vrai si `user` est un utilisateur AUTHENTIFIÉ (≠ anonyme). Le firewall pose
+* `token.getUser()` dans l'ALS : soit l'`IUser` réel, soit `anonymousUser`
+* (singleton). Tout ce qui n'est pas l'anonyme et porte un `identifier` est
+* une identité valide.
+*/
+function isAuthenticatedUser(user) {
+	return !!user && user !== anonymousUser && typeof user.identifier === "string";
+}
+//#endregion
+export { FirewallRealtimeAuthenticator, FirewallRealtimeAuthenticator as default };

package/dist/nodefony/src/authenticator/JwtAuthenticator.js

@@ -0,0 +1,176 @@
+import { AuthenticationError } from "../../errors/AuthenticationError.js";
+import { UserToken } from "../token/UserToken.js";
+import { bearerToken } from "./bearer.js";
+import peekIssuer from "./peekIssuer.js";
+//#region nodefony/src/authenticator/JwtAuthenticator.ts
+const COMPACT_JWS = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*$/;
+const INVALID_TOKEN = "Invalid token";
+/**
+* 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).
+*/
+var JwtAuthenticator = class {
+	name = "jwt";
+	#container;
+	#runtime;
+	#jose = null;
+	#getKey = null;
+	#keystore = null;
+	#store = null;
+	#userProvider = null;
+	/**
+	* @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, runtime) {
+		this.#container = container;
+		this.#runtime = runtime;
+	}
+	/**
+	* 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) {
+		const auth = context.request?.headers?.authorization;
+		if (typeof auth !== "string") return false;
+		const token = bearerToken(auth);
+		if (token === null || !COMPACT_JWS.test(token)) return false;
+		const issuer = peekIssuer(token);
+		return issuer === null || issuer === this.#runtime.issuer;
+	}
+	/** Extrait le token brut (non vérifié) → porté par un `UserToken` type `"jwt"`. */
+	createToken(context) {
+		const auth = context.request?.headers?.authorization;
+		return Promise.resolve(new UserToken("jwt", bearerToken(auth) ?? ""));
+	}
+	/**
+	* 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).
+	*/
+	async authenticate(token) {
+		const raw = token.getCredentials();
+		if (typeof raw !== "string" || raw.length === 0) throw new AuthenticationError(INVALID_TOKEN);
+		const jose = this.#jose ??= await import("jose");
+		const getKey = await this.#ensureGetKey(jose);
+		let payload;
+		try {
+			payload = (await jose.jwtVerify(raw, getKey, {
+				algorithms: ["EdDSA"],
+				issuer: this.#runtime.issuer,
+				audience: this.#runtime.audiences,
+				typ: "at+jwt"
+			})).payload;
+		} catch {
+			throw new AuthenticationError(INVALID_TOKEN);
+		}
+		const sub = payload.sub;
+		const jti = payload.jti;
+		if (typeof sub !== "string" || typeof jti !== "string") throw new AuthenticationError(INVALID_TOKEN);
+		const store = this.#resolveStore();
+		if (await store.isJtiDenied(jti)) throw new AuthenticationError(INVALID_TOKEN);
+		const invalidBefore = await store.getInvalidBefore(sub);
+		if (invalidBefore !== null) {
+			if ((typeof payload.iat === "number" ? payload.iat * 1e3 : 0) < invalidBefore) throw new AuthenticationError(INVALID_TOKEN);
+		}
+		const user = await this.#resolveUserOrReject(sub);
+		return this.#promote(token, user, payload);
+	}
+	/** Slot audit (J4b). */
+	onSuccess(_context, _token) {
+		return Promise.resolve();
+	}
+	/** Slot audit (J4b) — le 401 + challenge sont posés par le firewall. */
+	onFailure(_context, _error) {
+		return Promise.resolve();
+	}
+	/** Challenge RFC 6750/7235 posé par le firewall sur les 401 de la zone. */
+	challenge() {
+		return "Bearer";
+	}
+	/** Construit (une fois) le résolveur de clé par `kid` depuis le JWKS public. */
+	async #ensureGetKey(jose) {
+		if (this.#getKey !== null) return this.#getKey;
+		const jwks = await this.#resolveKeystore().getPublicJWKS();
+		return this.#getKey = jose.createLocalJWKSet(jwks);
+	}
+	/** Promeut le token : utilisateur vérifié + scopes/claims posés en attributs. */
+	#promote(token, user, payload) {
+		const ut = token;
+		ut.promote(user);
+		const scope = payload.scope;
+		const scopes = typeof scope === "string" && scope.length > 0 ? scope.split(" ") : [];
+		ut.setAttribute("scopes", scopes);
+		ut.setAttribute("jti", payload.jti);
+		ut.setAttribute("claims", payload);
+		return ut;
+	}
+	async #resolveUserOrReject(sub) {
+		const provider = this.#resolveUserProvider();
+		let user;
+		try {
+			user = await provider.loadUserByIdentifier(sub);
+		} catch {
+			throw new AuthenticationError(INVALID_TOKEN);
+		}
+		if (!user.isActive() || user.isLocked()) throw new AuthenticationError(INVALID_TOKEN);
+		return user;
+	}
+	#resolveKeystore() {
+		if (this.#keystore === null) {
+			const ks = this.#container.get("jwtKeystore");
+			if (!ks) throw new Error("JwtAuthenticator: service 'jwtKeystore' absent du container — le TokenService de @nodefony/security doit être chargé.");
+			this.#keystore = ks;
+		}
+		return this.#keystore;
+	}
+	#resolveStore() {
+		if (this.#store === null) {
+			const store = this.#container.get("tokenStore");
+			if (!store) throw new Error("JwtAuthenticator: service 'tokenStore' absent du container — le TokenService de @nodefony/security doit être chargé.");
+			this.#store = store;
+		}
+		return this.#store;
+	}
+	#resolveUserProvider() {
+		if (this.#userProvider === null) {
+			const provider = this.#container.get("users");
+			if (!provider) throw new Error("JwtAuthenticator: aucun service 'users' (IUserProvider) dans le container — enregistrer un UserService au boot de l'application.");
+			this.#userProvider = provider;
+		}
+		return this.#userProvider;
+	}
+};
+//#endregion
+export { JwtAuthenticator, JwtAuthenticator as default };

package/dist/nodefony/src/authenticator/SessionAuthenticator.js

@@ -0,0 +1,92 @@
+import { AuthenticationError } from "../../errors/AuthenticationError.js";
+import { resolveSessionIdentity } from "../sessionIdentity.js";
+import { UserToken } from "../token/UserToken.js";
+//#region nodefony/src/authenticator/SessionAuthenticator.ts
+/**
+* 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).
+*/
+var SessionAuthenticator = class {
+	name = "session";
+	#provider = null;
+	#resolveProvider;
+	/**
+	* @param resolveProvider - résolution lazy de la source d'identité
+	*   (typiquement `container.get("users")`) — appelée à la première requête.
+	*/
+	constructor(resolveProvider) {
+		this.#resolveProvider = resolveProvider;
+	}
+	/**
+	* 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) {
+		if (area.stateless) throw new Error(`area "${area.name}": l'authenticator "${this.name}" est incompatible avec \`stateless: true\` — une zone sans registre ne peut pas tirer son identité d'une session serveur. Retirer "session" de cette zone (l'appelant porte sa preuve : \`apikey\`, \`jwt\`, \`external-jwt\`), ou passer la zone à \`stateless: false\` si elle sert un navigateur.`);
+	}
+	/** La requête porte-t-elle une session reprise avec un utilisateur ? */
+	supports(context) {
+		const user = context.session?.user;
+		return typeof user === "string" && user.length > 0;
+	}
+	/** Extrait l'identifiant du blob de session (jamais de secret en jeu). */
+	createToken(context) {
+		const credentials = { identifier: context.session?.user ?? "" };
+		return Promise.resolve(new UserToken(this.name, credentials));
+	}
+	/**
+	* 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é.
+	*/
+	async authenticate(token) {
+		const credentials = token.getCredentials();
+		if (!credentials?.identifier) throw new AuthenticationError("Invalid session");
+		const provider = this.#provider ??= this.#resolveProvider();
+		const user = await resolveSessionIdentity(provider, credentials.identifier);
+		return token.promote(user);
+	}
+	/**
+	* Pose l'identifiant sur le contexte : la persistance de session du pipeline
+	* (`saveSession`) lie le blob au principal courant (string attendu).
+	*/
+	onSuccess(context, token) {
+		context.user = token.getUser().identifier;
+		return Promise.resolve();
+	}
+	/** Slot audit (P6.14). Le 401 est posé par le firewall. */
+	onFailure(_context, _error) {
+		return Promise.resolve();
+	}
+};
+//#endregion
+export { SessionAuthenticator, SessionAuthenticator as default };

package/dist/nodefony/src/authenticator/UserPasswordAuthenticator.js

@@ -0,0 +1,95 @@
+import { AuthenticationError } from "../../errors/AuthenticationError.js";
+import { ThrottledError } from "../../errors/ThrottledError.js";
+import { UserToken } from "../token/UserToken.js";
+//#region nodefony/src/authenticator/UserPasswordAuthenticator.ts
+const BASIC_SCHEME = /^basic\s+/i;
+const INVALID_CREDENTIALS = "Invalid credentials";
+/**
+* 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.
+*/
+var UserPasswordAuthenticator = class {
+	name = "userpassword";
+	#verifier = null;
+	#resolveVerifier;
+	#throttler;
+	/**
+	* @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, throttler = null) {
+		this.#resolveVerifier = resolveVerifier;
+		this.#throttler = throttler;
+	}
+	/** La requête porte-t-elle un en-tête `Authorization: Basic ...` ? */
+	supports(context) {
+		const auth = context.request?.headers?.authorization;
+		return typeof auth === "string" && BASIC_SCHEME.test(auth);
+	}
+	/** Décode l'enveloppe Basic — un contenu malformé donne un credential vide (échec uniforme). */
+	createToken(context) {
+		const auth = context.request?.headers?.authorization;
+		const decoded = Buffer.from(auth.replace(BASIC_SCHEME, ""), "base64").toString("utf8");
+		const sep = decoded.indexOf(":");
+		const credentials = sep > 0 ? {
+			identifier: decoded.slice(0, sep),
+			password: decoded.slice(sep + 1)
+		} : {
+			identifier: "",
+			password: ""
+		};
+		return Promise.resolve(new UserToken(this.name, credentials));
+	}
+	/**
+	* 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.
+	*/
+	async authenticate(token) {
+		const credentials = token.getCredentials();
+		if (!credentials?.identifier || !credentials.password) throw new AuthenticationError(INVALID_CREDENTIALS);
+		if (this.#throttler !== null) {
+			const retryAfterS = this.#throttler.check(credentials.identifier);
+			if (retryAfterS > 0) throw new ThrottledError(retryAfterS);
+		}
+		const user = await (this.#verifier ??= this.#resolveVerifier()).authenticate(credentials.identifier, credentials.password);
+		if (user === null) {
+			this.#throttler?.recordFailure(credentials.identifier);
+			throw new AuthenticationError(INVALID_CREDENTIALS);
+		}
+		this.#throttler?.recordSuccess(credentials.identifier);
+		return token.promote(user);
+	}
+	/** Slot J3 (session BFF au login) — rien à poser pour du Basic pur. */
+	onSuccess(_context, _token) {
+		return Promise.resolve();
+	}
+	/** Slot J3+ (audit events). Le throttling vit dans `authenticate` (clé = identifiant) ; le 401 + challenge sont posés par le firewall. */
+	onFailure(_context, _error) {
+		return Promise.resolve();
+	}
+	/** Challenge RFC 7235 posé par le firewall sur les 401 de la zone. */
+	challenge() {
+		return "Basic realm=\"nodefony\", charset=\"UTF-8\"";
+	}
+};
+//#endregion
+export { UserPasswordAuthenticator, UserPasswordAuthenticator as default };

package/dist/nodefony/src/authenticator/authenticatorRegistry.js

@@ -0,0 +1,63 @@
+import { AnonymousAuthenticator } from "./AnonymousAuthenticator.js";
+import { SessionAuthenticator } from "./SessionAuthenticator.js";
+import { UserPasswordAuthenticator } from "./UserPasswordAuthenticator.js";
+import { JwtAuthenticator } from "./JwtAuthenticator.js";
+import { ApiKeyAuthenticator } from "./ApiKeyAuthenticator.js";
+import { ExternalJwtAuthenticator } from "./ExternalJwtAuthenticator.js";
+import { resolveJwtRuntime } from "../token/jwtRuntime.js";
+//#region nodefony/src/authenticator/authenticatorRegistry.ts
+const factories = /* @__PURE__ */ new Map();
+/**
+* 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...).
+*/
+function registerAuthenticatorFactory(name, factory) {
+	factories.set(name, factory);
+}
+/** Fabrique d'un authenticator par nom, ou `undefined` si inconnu. */
+function getAuthenticatorFactory(name) {
+	return factories.get(name);
+}
+/** Noms enregistrés (validation boot, introspection Studio, tests). */
+function listAuthenticatorFactories() {
+	return [...factories.keys()];
+}
+registerAuthenticatorFactory("anonymous", () => new AnonymousAuthenticator());
+registerAuthenticatorFactory("userpassword", ({ container }) => {
+	const throttler = container.get("loginThrottler") ?? null;
+	return new UserPasswordAuthenticator(() => {
+		const verifier = container.get("users");
+		if (!verifier) throw new Error("UserPasswordAuthenticator: aucun service \"users\" (IPasswordVerifier) dans le container — enregistrer un UserService au boot de l'application.");
+		return verifier;
+	}, throttler);
+});
+registerAuthenticatorFactory("session", ({ container }) => {
+	return new SessionAuthenticator(() => {
+		const provider = container.get("users");
+		if (!provider) throw new Error("SessionAuthenticator: aucun service \"users\" (IUserProvider) dans le container — enregistrer un UserService au boot de l'application.");
+		return provider;
+	});
+});
+registerAuthenticatorFactory("jwt", ({ container, config }) => {
+	return new JwtAuthenticator(container, resolveJwtRuntime(config.jwt));
+});
+registerAuthenticatorFactory("external-jwt", ({ container, config }) => {
+	const rs = config.resourceServer;
+	return new ExternalJwtAuthenticator(container, {
+		issuers: rs.issuers.map((i) => ({
+			issuer: i.issuer,
+			subjectMapping: i.subjectMapping
+		})),
+		subjectPolicy: rs.subjectPolicy,
+		ephemeralRoles: rs.ephemeralRoles
+	});
+});
+registerAuthenticatorFactory("apikey", ({ container, config }) => {
+	return new ApiKeyAuthenticator(container, {
+		prefix: config.apiKeys.prefix,
+		lastUsedThrottleS: config.apiKeys.lastUsedThrottleS
+	});
+});
+//#endregion
+export { getAuthenticatorFactory, listAuthenticatorFactories, registerAuthenticatorFactory };

package/dist/nodefony/src/authenticator/bearer.js

@@ -0,0 +1,2 @@
+import { bearerToken } from "nodefony";
+export { bearerToken };

package/dist/nodefony/src/authenticator/externalSubject.js

@@ -0,0 +1,36 @@
+//#region nodefony/src/authenticator/externalSubject.ts
+/**
+* Séparateur entre l'émetteur et le sujet.
+*
+* `#` est choisi parce qu'un identifiant d'émetteur ne peut PAS en contenir :
+* la RFC 8414 §2 interdit le fragment dans un `issuer`. La composition est donc
+* **injective** — deux paires `(iss, sub)` distinctes ne peuvent jamais produire
+* le même identifiant local, et c'est précisément la propriété qui empêche un
+* émetteur d'usurper le sujet d'un autre.
+*/
+const SEPARATOR = "#";
+/**
+* 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
+*/
+function localIdentifierFor(issuer, subject, mapping) {
+	if (mapping === "subject") return subject;
+	return `${issuer}${SEPARATOR}${subject}`;
+}
+//#endregion
+export { localIdentifierFor };