@nodefony/security 10.0.0-alpha.1

package/dist/nodefony/src/audit/auditBridge.js

@@ -0,0 +1,82 @@
+import { PLATFORM_CHANNELS } from "nodefony";
+//#region nodefony/src/audit/auditBridge.ts
+/**
+* Canal WS du flux live d'audit (P6.14 lot 4). Le préfixe `security:` le place
+* sous le plancher `SECURITY_CHANNEL_POLICY` (ROLE_NODEFONY_ADMIN) du verrou de
+* frame — un user lambda ne peut pas s'y abonner (refus audité `frame.denied`).
+*/
+const SECURITY_AUDIT_CHANNEL = PLATFORM_CHANNELS.audit;
+/**
+* Pont journal d'audit → canal `nodefony:audit`, **coalescé** (P6.14 lot 4).
+*
+* Calque {@link createSyslogBridge} (studio) : au lieu de 1 frame WS par
+* événement (un pic d'`auth.failure` sous brute-force noierait la console
+* auditeur), on accumule dans un **ring buffer borné** et on flush **1 frame
+* agrégée toutes les `flushMs`** : `{ events, dropped }`. Sous surcharge, le ring
+* écrase les plus vieux et `dropped` indique combien ont été omis → la console
+* affiche un récap au lieu de se figer (budget borné, dégradable — règle
+* observabilité « superviser ≠ tomber la prod »).
+*
+* **Lazy par construction** (créé par le hub au 1ᵉʳ abonné, `dispose` au dernier) :
+* tant qu'aucun auditeur n'écoute `nodefony:audit`, ce pont N'EXISTE PAS — aucun
+* listener sur l'`AuditService`, aucun timer. Au repos avec auditeur connecté mais
+* sans événement : ring `null`, 0 timer (armé au 1ᵉʳ événement, `unref`).
+*
+* @param source  - l'`AuditService` (slot `subscribe`).
+* @param publish - publication hub (le canal est fourni par la factory).
+* @param channel - canal de publication (`nodefony:audit`).
+* @returns dispose() — détache le listener `AuditService` ET désarme le timer.
+*          OBLIGATOIRE (aucun listener/timer sans cleanup, sinon fuite à chaque
+*          dernier désabonnement).
+*/
+function createAuditBridge(source, publish, channel, opts = {}) {
+	const flushMs = opts.flushMs ?? 250;
+	const maxBatch = opts.maxBatch ?? 200;
+	let ring = null;
+	let head = 0;
+	let count = 0;
+	let dropped = 0;
+	let timer = null;
+	const flush = () => {
+		timer = null;
+		if (count === 0 && dropped === 0) return;
+		const events = new Array(count);
+		for (let i = 0; i < count; i++) events[i] = ring[(head + i) % maxBatch];
+		const d = dropped;
+		for (let i = 0; i < maxBatch; i++) ring[i] = void 0;
+		head = 0;
+		count = 0;
+		dropped = 0;
+		publish(channel, {
+			events,
+			dropped: d
+		});
+	};
+	const onEvent = (event) => {
+		if (ring === null) ring = new Array(maxBatch);
+		if (count === maxBatch) {
+			ring[head] = event;
+			head = (head + 1) % maxBatch;
+			dropped++;
+		} else {
+			ring[(head + count) % maxBatch] = event;
+			count++;
+		}
+		if (timer === null) {
+			timer = setTimeout(flush, flushMs);
+			timer.unref?.();
+		}
+	};
+	const unsubscribe = source.subscribe(onEvent);
+	return () => {
+		if (timer) {
+			clearTimeout(timer);
+			timer = null;
+		}
+		ring = null;
+		head = count = dropped = 0;
+		unsubscribe();
+	};
+}
+//#endregion
+export { SECURITY_AUDIT_CHANNEL, createAuditBridge, createAuditBridge as default };

package/dist/nodefony/src/audit/auditFilters.js

@@ -0,0 +1,60 @@
+//#region nodefony/src/audit/auditFilters.ts
+/**
+* **Le vocabulaire de filtre du journal d'audit**, en noms PUBLICS — ceux qu'un
+* auditeur écrit dans l'URL (`?category=authz&outcome=denied&since=…`).
+*
+* Les deux énumérations y sont écrites en toutes lettres, et
+* {@link AUDIT_FILTER_VOCABULARY_IS_COMPLETE} vérifie **à la compilation**
+* qu'elles couvrent exactement `AuditCategory` et `AuditOutcome`.
+*
+* Ce contrôle n'est pas décoratif : la liste qu'il remplace avait DÉJÀ dérivé.
+* Un `Set` recopié à la main dans le data plane portait dix catégories quand le
+* type en déclarait onze — `?category=config` tombait donc hors de l'allowlist,
+* était ignoré en silence, et l'auditeur recevait le journal ENTIER en croyant
+* lire les seules mutations de configuration. Une liste recopiée ne diverge
+* jamais bruyamment.
+*
+* `actor`, `action` et `requestId` restent des chaînes libres : ce sont des
+* identifiants produits à l'exécution, aucune allowlist ne peut les connaître.
+* `since`/`until` sont des horodatages en millisecondes (bornes incluses).
+*/
+const AUDIT_FILTERS = {
+	/** Famille d'événement — la liste EST le type `AuditCategory`. */
+	category: [
+		"auth",
+		"authz",
+		"token",
+		"session",
+		"oauth",
+		"webauthn",
+		"csrf",
+		"cors",
+		"ws",
+		"webhook",
+		"config"
+	],
+	/** Issue — `denied` est le signal d'accès non autorisé. */
+	outcome: [
+		"success",
+		"failure",
+		"denied"
+	],
+	/** Identité de l'acteur (égalité stricte). */
+	actor: "string",
+	/** Nom de l'action auditée (égalité stricte). */
+	action: "string",
+	/** Corrèle toutes les traces d'une même requête. */
+	requestId: "string",
+	/** Borne basse, horodatage en millisecondes. */
+	since: "int",
+	/** Borne haute, horodatage en millisecondes. */
+	until: "int"
+};
+/**
+* Preuve **à la compilation** que le vocabulaire ci-dessus est exactement celui
+* des types du contrat. Elle remplace la discipline humaine « penser à mettre
+* les deux à jour », qui avait échoué en silence.
+*/
+const AUDIT_FILTER_VOCABULARY_IS_COMPLETE = [true, true];
+//#endregion
+export { AUDIT_FILTERS, AUDIT_FILTER_VOCABULARY_IS_COMPLETE };

package/dist/nodefony/src/audit/auditStoreRegistry.js

@@ -0,0 +1,25 @@
+import { MemoryAuditStore } from "./MemoryAuditStore.js";
+//#region nodefony/src/audit/auditStoreRegistry.ts
+const factories = /* @__PURE__ */ new Map();
+/**
+* Enregistre (ou remplace) la fabrique d'un store d'audit. Appelée par le builtin
+* `memory` au chargement, et par les adapters (drizzle/mongoose/redis) pour les leurs.
+*/
+function registerAuditStore(name, factory) {
+	factories.set(name, factory);
+}
+/** Fabrique d'un store par nom, ou `undefined` si inconnu. */
+function getAuditStoreFactory(name) {
+	return factories.get(name);
+}
+/** Noms enregistrés (validation boot, introspection Studio, tests). */
+function listAuditStores() {
+	return [...factories.keys()];
+}
+const MS_PER_DAY = 864e5;
+registerAuditStore("memory", (ctx) => {
+	const days = ctx?.config?.audit?.retentionDays;
+	return typeof days === "number" ? new MemoryAuditStore(Date.now, days * MS_PER_DAY) : new MemoryAuditStore();
+});
+//#endregion
+export { getAuditStoreFactory, listAuditStores, registerAuditStore };

package/dist/nodefony/src/audit/readAuditContext.js

@@ -0,0 +1,24 @@
+//#region nodefony/src/audit/readAuditContext.ts
+/**
+* Extrait IP / User-Agent / requestId + drapeaux de présence (jamais la valeur)
+* d'un contexte de requête — pour enrichir un événement d'audit avec la
+* provenance (« d'où vient cette tentative »). Calque {@link JsonAuditLogger}.
+*
+* @param context - contexte HTTP/WS courant (typé `unknown` à la frontière).
+* @returns provenance normalisée ; champs `null` si l'info est absente.
+*/
+function readAuditContext(context) {
+	const ctx = context ?? {};
+	const headers = ctx.request?.headers ?? {};
+	return {
+		ip: ctx.remoteAddress ?? null,
+		userAgent: ctx.getUserAgent?.() ?? null,
+		requestId: ctx.requestId ?? null,
+		flags: {
+			hasAuthorization: Boolean(headers["authorization"]),
+			hasCookie: Boolean(headers["cookie"])
+		}
+	};
+}
+//#endregion
+export { readAuditContext };

package/dist/nodefony/src/audit/recordAudit.js

@@ -0,0 +1,16 @@
+//#region nodefony/src/audit/recordAudit.ts
+/**
+* Émet un événement d'audit **si** le service est présent — no-op sinon. La
+* résolution se fait par le container (`auditService`) sur le **cold-path**
+* (login, refus, révocation) : le coût d'un `Map.get` y est négligeable, et le
+* journal reste **découplé** (module audit absent ou désactivé → aucun effet,
+* jamais d'exception qui remonterait dans le flux métier).
+*
+* @param container - container du service émetteur (`this.container`).
+* @param event - brouillon d'événement (l'`AuditService` pose `id` + `ts`).
+*/
+function recordAudit(container, event) {
+	(container?.get("auditService"))?.record(event);
+}
+//#endregion
+export { recordAudit };

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

@@ -0,0 +1,36 @@
+import { AnonymousToken } from "../token/AnonymousToken.js";
+//#region nodefony/src/authenticator/AnonymousAuthenticator.ts
+/**
+* Acceptation EXPLICITE de l'anonymat dans une zone — le seul authenticator
+* autorisé à produire un token non authentifié sans déclencher le Zero Trust.
+*
+* Ne le lister que volontairement : une zone `authenticators: ["jwt", "anonymous"]`
+* (mode `first`) signifie « identifié si preuve présente, sinon visiteur anonyme
+* accepté ». Sans lui, zone protégée + aucune preuve → 401. En mode `all` il
+* reste utile en DERNIER : « le canal doit être prouvé (ex. mtls), l'identité
+* utilisateur est optionnelle ».
+*
+* Zéro coût : `supports()` accepte tout, le token porte le singleton gelé
+* `anonymousUser` (aucune allocation d'utilisateur).
+*/
+var AnonymousAuthenticator = class {
+	name = "anonymous";
+	supports() {
+		return true;
+	}
+	createToken() {
+		return Promise.resolve(new AnonymousToken());
+	}
+	/** Toujours un succès — accepter l'anonymat ne vérifie rien. */
+	authenticate(token) {
+		return Promise.resolve(token);
+	}
+	onSuccess(_context, _token) {
+		return Promise.resolve();
+	}
+	onFailure(_context, _error) {
+		return Promise.resolve();
+	}
+};
+//#endregion
+export { AnonymousAuthenticator, AnonymousAuthenticator as default };

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

@@ -0,0 +1,164 @@
+import { AuthenticationError } from "../../errors/AuthenticationError.js";
+import { UserToken } from "../token/UserToken.js";
+import { bearerToken } from "./bearer.js";
+import { looksLikeApiKey, parseApiKey } from "../apikey/apiKeyFormat.js";
+//#region nodefony/src/authenticator/ApiKeyAuthenticator.ts
+const INVALID_TOKEN = "Invalid token";
+/**
+* Marqueur interne posé par `authenticate()` et consommé par `onSuccess()` :
+* l'horodatage à inscrire, quand la fenêtre de throttle est dépassée. Il ne
+* traverse jamais le pipeline — l'attribut vit sur le token de la requête.
+*/
+const MARK_USED_AT = "apiKeyMarkUsedAt";
+/**
+* Authentification par **clé API personnelle (PAT, P6.12)** présentée en
+* `Authorization: Bearer <prefix>_…` (RFC 6750). Réservée API/CI/scripts — le web
+* utilise la session BFF.
+*
+* Un PAT est un **bearer opaque** (≠ JWT auto-porté) : sa vérité vit côté serveur
+* (`ITokenStore`), donc il est **révocable immédiatement**. Discrimination du
+* JWT : le PAT porte le préfixe `<prefix>_` (le JWT a la structure compacte
+* `a.b.c`) → les deux authenticators cohabitent dans une même zone.
+*
+* Défenses :
+*  - **forme + CRC validés AVANT tout accès au store** ({@link parseApiKey}) →
+*    une valeur malformée n'atteint jamais la base (anti-DoS) ;
+*  - lookup par **hash** (`sha256`) — le secret n'existe nulle part au repos ;
+*  - **révocation** immédiate (`revokedAt`) + **expiration** (`expiresAt`) +
+*    **ban en masse** du porteur (`invalidBefore` vs `createdAt`) ;
+*  - **sujet revérifié** à chaque requête (`loadUserByIdentifier` → disparu/
+*    inactif/verrouillé = rejet) — rôles **frais** (révocation effective) ;
+*  - message d'échec **uniforme** (anti-énumération).
+*
+* Dépendances (store, userProvider) résolues **paresseusement** du container.
+*/
+var ApiKeyAuthenticator = class {
+	name = "apikey";
+	#container;
+	#prefix;
+	#throttleMs;
+	#store = null;
+	#userProvider = null;
+	/**
+	* @param container - container DI (résolution lazy de `tokenStore`/`users`).
+	* @param runtime - préfixe + throttle effectifs (dérivés de `config.apiKeys`).
+	*/
+	constructor(container, runtime) {
+		this.#container = container;
+		this.#prefix = runtime.prefix;
+		this.#throttleMs = Math.max(0, runtime.lastUsedThrottleS) * 1e3;
+	}
+	/** La requête porte-t-elle un `Authorization: Bearer <prefix>_…` ? (test bon marché) */
+	supports(context) {
+		const auth = context.request?.headers?.authorization;
+		if (typeof auth !== "string") return false;
+		const token = bearerToken(auth);
+		return token !== null && looksLikeApiKey(token, this.#prefix);
+	}
+	/** Extrait la valeur brute (non vérifiée) → portée par un `UserToken` type `"apikey"`. */
+	createToken(context) {
+		const auth = context.request?.headers?.authorization;
+		return Promise.resolve(new UserToken("apikey", bearerToken(auth) ?? ""));
+	}
+	/**
+	* Valide la clé (forme+CRC, puis store) et résout le sujet — ou lève un 401 au
+	* message uniforme.
+	*
+	* @throws AuthenticationError (401) — clé malformée/inconnue/révoquée/expirée,
+	*   ou sujet disparu/banni.
+	* @throws Error (câblage : store/users absents) — loggé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 parsed = parseApiKey(raw, this.#prefix);
+		if (parsed === null) throw new AuthenticationError(INVALID_TOKEN);
+		const store = this.#resolveStore();
+		const record = await store.findByHash(parsed.secretHash);
+		const now = Date.now();
+		if (!record || record.kind !== "pat" || record.revokedAt !== null || record.expiresAt !== null && record.expiresAt <= now) throw new AuthenticationError(INVALID_TOKEN);
+		const invalidBefore = await store.getInvalidBefore(record.subjectId);
+		if (invalidBefore !== null && record.createdAt < invalidBefore) throw new AuthenticationError(INVALID_TOKEN);
+		const user = await this.#resolveUserOrReject(record.subjectId);
+		const last = record.lastUsedAt;
+		if (this.#throttleMs === 0 || last === null || now - last >= this.#throttleMs) token.setAttribute(MARK_USED_AT, now);
+		const ut = token;
+		ut.promote(user);
+		ut.setAttribute("scopes", [...record.scopes]);
+		ut.setAttribute("apiKeyId", record.id);
+		ut.setAttribute("tenantId", record.tenantId);
+		return ut;
+	}
+	/**
+	* Inscrit la trace d'usage de la clé — horodatage, IP et agent.
+	*
+	* C'est ici, et pas dans `authenticate()`, parce que c'est ici qu'on reçoit
+	* le contexte. La provenance se lit par les ACCESSEURS proxy-aware des
+	* contextes concrets (`getRemoteAddress()` dépouille `X-Forwarded-For` selon
+	* `trustProxy`), absents du type de base — duck-typing optionnel, même
+	* approche que `AuthFlow.#openSession()`.
+	*
+	* Rien n'est écrit si `authenticate()` n'a pas posé le marqueur : la fenêtre
+	* de throttle n'était pas dépassée, et le hot path reste sans écriture.
+	*/
+	async onSuccess(context, token) {
+		const at = token.getAttribute(MARK_USED_AT);
+		if (at === void 0) return;
+		const id = token.getAttribute("apiKeyId");
+		if (id === void 0) return;
+		const provenance = context;
+		let ip;
+		let userAgent;
+		try {
+			ip = provenance.getRemoteAddress?.() ?? void 0;
+			userAgent = provenance.getUserAgent?.();
+		} catch {}
+		try {
+			await this.#resolveStore().markUsed(id, {
+				at,
+				ip,
+				userAgent
+			});
+		} catch (e) {
+			context.log(`apikey: trace d'usage non enregistrée (${id}) — ${String(e)}`, "WARNING");
+		}
+	}
+	/** Slot audit (P6.14) — 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";
+	}
+	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;
+	}
+	#resolveStore() {
+		if (this.#store === null) {
+			const store = this.#container.get("tokenStore");
+			if (!store) throw new Error("ApiKeyAuthenticator: 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("ApiKeyAuthenticator: aucun service 'users' (IUserProvider) dans le container — enregistrer un UserService au boot de l'application.");
+			this.#userProvider = provider;
+		}
+		return this.#userProvider;
+	}
+};
+//#endregion
+export { ApiKeyAuthenticator, ApiKeyAuthenticator as default };

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

@@ -0,0 +1,224 @@
+import { AuthenticationError } from "../../errors/AuthenticationError.js";
+import { UnverifiableTokenError } from "../../errors/UnverifiableTokenError.js";
+import { UserToken } from "../token/UserToken.js";
+import { bearerToken } from "./bearer.js";
+import peekIssuer from "./peekIssuer.js";
+import { localIdentifierFor } from "./externalSubject.js";
+import { ACCESS_TOKEN_VERIFIER, buildBearerChallenge, canonicalIssuer, protectedResourceMetadataUrl } from "nodefony";
+import { BaseUser } from "@nodefony/user";
+//#region nodefony/src/authenticator/ExternalJwtAuthenticator.ts
+/**
+* Message UNIFORME de refus — la cause fine (expiré, audience, signature, sujet
+* inconnu) part au journal, jamais au client : un refus détaillé est un oracle
+* qui aide à fabriquer un jeton acceptable.
+*/
+const INVALID_TOKEN = "Invalid token";
+/** Clé de transport de l'audience entre `createToken` et `authenticate`. */
+const AUDIENCE = "audience";
+/**
+* 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.
+*/
+var ExternalJwtAuthenticator = class {
+	name = "external-jwt";
+	#container;
+	#issuers;
+	#policy;
+	#ephemeralRoles;
+	#userProvider = null;
+	/**
+	* @param container - container DI (résolution lazy du vérificateur et de `users`)
+	* @param options - émetteurs reconnus et politique de rattachement
+	*/
+	constructor(container, options) {
+		this.#container = container;
+		const issuers = /* @__PURE__ */ new Map();
+		for (const binding of options.issuers) try {
+			issuers.set(canonicalIssuer(binding.issuer), binding.subjectMapping);
+		} catch {
+			continue;
+		}
+		this.#issuers = issuers;
+		this.#policy = options.subjectPolicy;
+		this.#ephemeralRoles = options.ephemeralRoles;
+	}
+	/**
+	* 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) {
+		const auth = context.request?.headers?.authorization;
+		if (typeof auth !== "string") return false;
+		const raw = bearerToken(auth);
+		if (raw === null) return false;
+		const issuer = peekIssuer(raw);
+		if (issuer === null) return false;
+		if (this.#issuers.has(issuer)) return true;
+		try {
+			return this.#issuers.has(canonicalIssuer(issuer));
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* 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) {
+		const auth = context.request?.headers?.authorization;
+		const token = new UserToken("external-jwt", bearerToken(auth) ?? "");
+		const area = context.security;
+		if (area?.resource) token.setAttribute(AUDIENCE, area.resource);
+		return Promise.resolve(token);
+	}
+	/**
+	* 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
+	*/
+	async authenticate(token) {
+		const raw = token.getCredentials();
+		if (typeof raw !== "string" || raw.length === 0) throw new AuthenticationError(INVALID_TOKEN);
+		const audience = token.getAttribute(AUDIENCE);
+		if (!audience) throw new UnverifiableTokenError();
+		const verify = this.#container.get(ACCESS_TOKEN_VERIFIER);
+		if (typeof verify !== "function") throw new UnverifiableTokenError();
+		let principal;
+		try {
+			principal = await verify(raw, audience);
+		} catch (error) {
+			throw new UnverifiableTokenError(error.message);
+		}
+		if (principal === null) throw new AuthenticationError(INVALID_TOKEN);
+		const subject = principal.subject;
+		if (!subject) throw new AuthenticationError(INVALID_TOKEN);
+		const mapping = this.#issuers.get(principal.issuer);
+		if (mapping === void 0) throw new UnverifiableTokenError(`émetteur « ${principal.issuer} » vérifié mais absent de la table de rattachement des sujets — configuration incohérente.`);
+		const user = await this.#resolveUser(principal.issuer, subject, mapping);
+		const ut = token;
+		ut.promote(user);
+		ut.setAttribute("scopes", [...principal.scopes]);
+		ut.setAttribute("subject", subject);
+		ut.setAttribute("issuer", principal.issuer);
+		if (principal.expiresAt !== void 0 || principal.issuedAt !== void 0) ut.setAttribute("claims", {
+			exp: principal.expiresAt,
+			iat: principal.issuedAt
+		});
+		if (principal.tokenId !== void 0) ut.setAttribute("jti", principal.tokenId);
+		return ut;
+	}
+	/** Slot audit — le firewall enregistre déjà succès et échec par zone. */
+	onSuccess(_context, _token) {
+		return Promise.resolve();
+	}
+	/** Slot audit — le 401 et le défi sont posés par le firewall. */
+	onFailure(_context, _error) {
+		return Promise.resolve();
+	}
+	/**
+	* 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) {
+		if (!area?.resource) return "Bearer";
+		return buildBearerChallenge({ resourceMetadataUrl: protectedResourceMetadataUrl(area.resource) });
+	}
+	/**
+	* 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) {
+		if (!area.resource) throw new Error(`area "${area.name}": l'authenticator "${this.name}" exige que la zone déclare sa ressource (\`resource\`) — c'est l'audience que le jeton doit porter (RFC 8707 §2). Sans elle, un jeton valide délivré au même porteur pour un AUTRE service serait accepté ici.`);
+	}
+	/**
+	* Établit l'utilisateur applicatif à partir du sujet du jeton.
+	*
+	* Les deux politiques répondent à deux questions différentes : « qui, chez
+	* nous, est cette personne ? » et « quel pouvoir accorde-t-on à une machine
+	* que l'annuaire a authentifiée ? ».
+	*/
+	async #resolveUser(issuer, subject, mapping) {
+		const identifier = localIdentifierFor(issuer, subject, mapping);
+		if (this.#policy === "ephemeral") return new BaseUser({
+			id: identifier,
+			identifier,
+			roles: [...this.#ephemeralRoles]
+		});
+		const provider = this.#resolveUserProvider();
+		let user;
+		try {
+			user = await provider.loadUserByIdentifier(identifier);
+		} catch {
+			throw new AuthenticationError(INVALID_TOKEN);
+		}
+		if (!user.isActive() || user.isLocked()) throw new AuthenticationError(INVALID_TOKEN);
+		return user;
+	}
+	#resolveUserProvider() {
+		if (this.#userProvider === null) {
+			const provider = this.#container.get("users");
+			if (!provider) throw new Error("ExternalJwtAuthenticator: aucun service \"users\" (IUserProvider) dans le container — enregistrer un UserService au boot, ou passer la politique de sujet à \"ephemeral\" si l'appelant est une machine sans compte local.");
+			this.#userProvider = provider;
+		}
+		return this.#userProvider;
+	}
+};
+//#endregion
+export { ExternalJwtAuthenticator, ExternalJwtAuthenticator as default };