@nodefony/security 10.0.0-alpha.2 → 10.0.0-alpha.3

package/dist/index.js

@@ -44,6 +44,10 @@ import { Authorization } from "./nodefony/service/authorization.js";
 import { MemoryWebAuthnCredentialStore } from "./nodefony/src/webauthn/MemoryWebAuthnCredentialStore.js";
 import { getWebAuthnStoreFactory, listWebAuthnStores, registerWebAuthnStore } from "./nodefony/src/webauthn/webAuthnCredentialStoreRegistry.js";
 import { WebAuthnService } from "./nodefony/service/webAuthn.js";
+import { OAuth2Client, OAuth2RequestError, OAuth2Tokens, createCodeChallenge, generateCodeVerifier, generateState } from "./nodefony/src/oauth/oauth2Client.js";
+import { discoverAuthorizationServer } from "./nodefony/src/oauth/metadata.js";
+import { createDiscoveredOidcProvider, createOidcProvider } from "./nodefony/src/oauth/providers/oidc.js";
+import { createGithubProvider } from "./nodefony/src/oauth/providers/github.js";
 import { getOAuthProviderFactory, listOAuthProviders, registerOAuthProvider } from "./nodefony/src/oauth/oauthProviderRegistry.js";
 import { OAuth2Service } from "./nodefony/service/oauth2.js";
 import { TOKEN_FACETS } from "./nodefony/src/token/tokenFilters.js";
@@ -148,4 +152,4 @@ Security = __decorate([services([
 ]), __decorateMetadata("design:paramtypes", [typeof Kernel === "undefined" ? Object : Kernel])], Security);
 var security_default = Security;
 //#endregion
-export { AccessDeniedError, AccessTokenVerifierService, AnonymousAuthenticator, AnonymousToken, ApiKeyAuthenticator, ApiKeyError, ApiKeyService, AuditService, AuthFlow, AuthenticationError, Authorization, Cors, Csrf, CsrfError, CsrfTokenManager, ExternalJwtAuthenticator, Firewall, InvalidTargetError, JwtAuthenticator, JwtKeystore, LoginThrottler, MemoryAuditStore, MemoryTokenStore, MemoryTotpSecretStore, MemoryWebAuthnCredentialStore, MemoryWebhookStore, OAuth2Service, RemoteJwtVerifier, RoleHierarchyWalker, RoleVoter, ScopeVoter, SecuredArea, SecurityHeaders, SessionAuthenticator, SsrfError, TOKEN_DEFAULT_ORDER, TOKEN_FACETS, TOKEN_SORTABLE_FIELDS, ThrottledError, TokenService, TotpService, UnverifiableTokenError, UserPasswordAuthenticator, UserToken, VoterVote, WEBHOOK_DEFAULT_ORDER, WEBHOOK_SORTABLE_FIELDS, WebAuthnService, WebhookService, assertPublicUrl, base32Decode, beginTotpEnrollment, confirmTotpEnrollment, createSecurityAdminApi, decryptSecret, security_default as default, defineSecurityConfig, deriveKey, deriveTotpKey, disableTotp, encryptSecret, generateApiKey, generateEphemeralKey, getAuditStoreFactory, getAuthenticatorFactory, getOAuthProviderFactory, getTokenStoreFactory, getTotpStoreFactory, getWebAuthnStoreFactory, getWebhookStoreFactory, hashApiKey, isBlockedAddress, listAuditStores, listAuthenticatorFactories, listOAuthProviders, listTokenStores, listTotpStores, listVoterFactories, listWebAuthnStores, listWebhookStores, looksLikeApiKey, matchesTokenStatus, parseApiKey, parseAuditQuery, peekIssuer, readAuditContext, recordAudit, registerAuditStore, registerAuthenticatorFactory, registerOAuthProvider, registerSecurityAdminApi, registerTokenStore, registerTotpStore, registerVoterFactory, registerWebAuthnStore, registerWebhookStore, resolveJwtRuntime, securityConfigJsonSchema, tokenStatusCriteria, tokenStatusOf, totpCode, totpStatus, verifyTotpLogin };
+export { AccessDeniedError, AccessTokenVerifierService, AnonymousAuthenticator, AnonymousToken, ApiKeyAuthenticator, ApiKeyError, ApiKeyService, AuditService, AuthFlow, AuthenticationError, Authorization, Cors, Csrf, CsrfError, CsrfTokenManager, ExternalJwtAuthenticator, Firewall, InvalidTargetError, JwtAuthenticator, JwtKeystore, LoginThrottler, MemoryAuditStore, MemoryTokenStore, MemoryTotpSecretStore, MemoryWebAuthnCredentialStore, MemoryWebhookStore, OAuth2Client, OAuth2RequestError, OAuth2Service, OAuth2Tokens, RemoteJwtVerifier, RoleHierarchyWalker, RoleVoter, ScopeVoter, SecuredArea, SecurityHeaders, SessionAuthenticator, SsrfError, TOKEN_DEFAULT_ORDER, TOKEN_FACETS, TOKEN_SORTABLE_FIELDS, ThrottledError, TokenService, TotpService, UnverifiableTokenError, UserPasswordAuthenticator, UserToken, VoterVote, WEBHOOK_DEFAULT_ORDER, WEBHOOK_SORTABLE_FIELDS, WebAuthnService, WebhookService, assertPublicUrl, base32Decode, beginTotpEnrollment, confirmTotpEnrollment, createCodeChallenge, createDiscoveredOidcProvider, createGithubProvider, createOidcProvider, createSecurityAdminApi, decryptSecret, security_default as default, defineSecurityConfig, deriveKey, deriveTotpKey, disableTotp, discoverAuthorizationServer, encryptSecret, generateApiKey, generateCodeVerifier, generateEphemeralKey, generateState, getAuditStoreFactory, getAuthenticatorFactory, getOAuthProviderFactory, getTokenStoreFactory, getTotpStoreFactory, getWebAuthnStoreFactory, getWebhookStoreFactory, hashApiKey, isBlockedAddress, listAuditStores, listAuthenticatorFactories, listOAuthProviders, listTokenStores, listTotpStores, listVoterFactories, listWebAuthnStores, listWebhookStores, looksLikeApiKey, matchesTokenStatus, parseApiKey, parseAuditQuery, peekIssuer, readAuditContext, recordAudit, registerAuditStore, registerAuthenticatorFactory, registerOAuthProvider, registerSecurityAdminApi, registerTokenStore, registerTotpStore, registerVoterFactory, registerWebAuthnStore, registerWebhookStore, resolveJwtRuntime, securityConfigJsonSchema, tokenStatusCriteria, tokenStatusOf, totpCode, totpStatus, verifyTotpLogin };

package/dist/nodefony/command/security-token.js

@@ -1,10 +1,11 @@
 import { messageNonRestreint, modeNonRestreint, readIfPresentSync, writeSecretSync } from "../src/token/secretFile.js";
-import { ADMIN_SCOPE_READ, ADMIN_SCOPE_WRITE, AGENT_TARGETS, Command, MCP_ENDPOINT_PATH, MCP_TOKEN_ENV, agentRoot, agentsPresents, alreadyHasKey, chargePrompts, poseVariable, requestedAgents } from "nodefony";
+import { ADMIN_SCOPE_READ, ADMIN_SCOPE_WRITE, AGENT_TARGETS, CONSOLE_DATA_RUN_PROFILE, Command, MCP_ENDPOINT_PATH, MCP_TOKEN_ENV, agentRoot, agentsPresents, alreadyHasKey, chargePrompts, poseVariable, requestedAgents } from "nodefony";
 import path from "node:path";
 import { existsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 //#region nodefony/command/security-token.ts
 const options = {
+	runProfile: CONSOLE_DATA_RUN_PROFILE,
 	helpGroup: "COMPTES ET SECRETS",
 	showBanner: false,
 	kernelEvent: "onReady",

package/dist/nodefony/command/security-user-add.js

@@ -1,6 +1,7 @@
-import { Command, askPasswordMasked } from "nodefony";
+import { CONSOLE_DATA_RUN_PROFILE, Command, askPasswordMasked } from "nodefony";
 //#region nodefony/command/security-user-add.ts
 const options = {
+	runProfile: CONSOLE_DATA_RUN_PROFILE,
 	helpGroup: "COMPTES ET SECRETS",
 	showBanner: false,
 	kernelEvent: "onPostReady"

package/dist/nodefony/command/security-user-delete.js

@@ -1,6 +1,7 @@
-import { Command } from "nodefony";
+import { CONSOLE_DATA_RUN_PROFILE, Command } from "nodefony";
 //#region nodefony/command/security-user-delete.ts
 const options = {
+	runProfile: CONSOLE_DATA_RUN_PROFILE,
 	helpGroup: "COMPTES ET SECRETS",
 	showBanner: false,
 	kernelEvent: "onPostReady",

package/dist/nodefony/command/security-user-list.js

@@ -1,6 +1,7 @@
-import { Command } from "nodefony";
+import { CONSOLE_DATA_RUN_PROFILE, Command } from "nodefony";
 //#region nodefony/command/security-user-list.ts
 const options = {
+	runProfile: CONSOLE_DATA_RUN_PROFILE,
 	helpGroup: "COMPTES ET SECRETS",
 	showBanner: false,
 	kernelEvent: "onReady",

package/dist/nodefony/config/config.js

@@ -303,6 +303,7 @@ const studioSchema = z.strictObject({
 const oauthProviderSchema = z.strictObject({
 	clientId: z.string().min(1).describe("Identifiant client OAuth délivré par le fournisseur."),
 	clientSecret: z.string().min(1).describe("Secret client OAuth — SECRET, fourni par env, jamais loggé."),
+	clientAuthMethod: z.enum(["client_secret_basic", "client_secret_post"]).optional().describe("Comment le client s'authentifie au point de jeton (RFC 6749 §2.3). OMIS = `client_secret_basic`, ce que la RFC demande de préférer et ce que la plupart des serveurs annoncent par défaut. Poser `client_secret_post` quand le serveur l'EXIGE — il le publie dans ses métadonnées (`token_endpoint_auth_methods_supported`). La méthode `none` (client public) n'est pas offerte ici : ce schéma exige un secret non vide."),
 	redirectUri: z.string().min(1).describe("URL de callback EXACTE (RFC 9700 : exact string matching) enregistrée chez le fournisseur — doit pointer sur .../oauth2/<provider>/callback."),
 	issuer: z.string().optional().describe("Émetteur OIDC self-hosted (Keycloak : URL du realm, ex. https://kc.example/realms/app). REQUIS pour keycloak ; ignoré par les fournisseurs à endpoints fixes (Google/GitHub)."),
 	scopes: z.array(z.string()).default([]).describe("Scopes demandés. Vide = défauts du fournisseur (Google: openid/profile/email ; GitHub: read:user/user:email)."),
@@ -316,8 +317,8 @@ const oauth2Schema = z.strictObject({
 	allowSignup: z.boolean().default(true).describe("true = crée une ligne locale au 1er login (JIT, Shadow User). false = un compte préexistant lié est requis (fail-closed)."),
 	successRedirect: z.string().default("/").describe("Redirection après login réussi."),
 	failureRedirect: z.string().default("/login").describe("Redirection après échec (state invalide, refus utilisateur...)."),
-	providers: z.record(z.string(), oauthProviderSchema).default({}).describe("Fournisseurs activés par nom (doit correspondre au registre : builtins google/keycloak/github ; +50 via arctic en enregistrant une fabrique).")
-}).describe("Social login OAuth 2.0 (arctic) — Authorization Code + PKCE, session BFF.");
+	providers: z.record(z.string(), oauthProviderSchema).default({}).describe("Fournisseurs activés par nom (doit correspondre au registre : builtins google/keycloak/oidc/github ; tout autre serveur OpenID Connect en enregistrant une fabrique, décrit par son seul émetteur).")
+}).describe("Social login OAuth 2.0 — Authorization Code + PKCE, session BFF.");
 /**
 * Règle d'autorisation d'un **namespace de canaux WebSocket** (subscribe/inbound)
 * par préfixe. Contraintes cumulatives ; un champ absent = pas de contrainte sur

package/dist/nodefony/service/oauth2.js

@@ -1,12 +1,12 @@
 import { AuthenticationError } from "../errors/AuthenticationError.js";
 import { defineSecurityConfig } from "../config/defineModuleConfig.js";
+import { generateCodeVerifier, generateState } from "../src/oauth/oauth2Client.js";
 import { getOAuthProviderFactory, listOAuthProviders } from "../src/oauth/oauthProviderRegistry.js";
 import { Service } from "nodefony";
 //#region nodefony/service/oauth2.ts
 const serviceName = "oauth2";
 /**
-* **Social login OAuth 2.0** (P6 J9) — orchestrateur du flux *Authorization Code*
-* au-dessus d'`arctic`.
+* **Social login OAuth 2.0** (P6 J9) — orchestrateur du flux *Authorization Code*.
 *
 * Posture OAuth 2.1 (RFC 9700) : Authorization Code uniquement (jamais implicit /
 * ROPC), **PKCE S256** quand le fournisseur le supporte (RFC 7636), **state**
@@ -14,10 +14,11 @@ const serviceName = "oauth2";
 * (le login produit une **session BFF**, gérée hors de ce service par le
 * controller + `AuthFlow`).
 *
-* `arctic` est **importé paresseusement** au premier login (cold path — jamais au
-* boot ni par requête), comme `@simplewebauthn`/`jose`. Au boot (si
-* `oauth2.enabled`) : seule la config est validée et les fournisseurs configurés
-* sont confrontés au registre (un nom inconnu = WARNING, pas fatal).
+* Les fournisseurs sont construits **au premier login** (cold path — jamais au boot
+* ni par requête) puis mémoïsés : c'est là que les points d'entrée d'un émetteur
+* OIDC sont découverts, une seule fois par processus. Au boot (si `oauth2.enabled`)
+* : seule la config est validée et les fournisseurs configurés sont confrontés au
+* registre (un nom inconnu = WARNING, pas fatal).
 *
 * Le service ne touche **ni HTTP ni session** : il rend à l'appelant les éléments
 * (URL, state, verifier) que le controller persiste en session — testable sans
@@ -26,7 +27,6 @@ const serviceName = "oauth2";
 var OAuth2Service = class extends Service {
 	module;
 	#config = null;
-	#lib = null;
 	#providers = null;
 	#ready = false;
 	constructor(module) {
@@ -83,11 +83,14 @@ var OAuth2Service = class extends Service {
 	*/
 	async createAuthorization(provider) {
 		const resolved = await this.#resolveProvider(provider);
-		const lib = await this.#ensureLib();
-		const state = lib.generateState();
-		const codeVerifier = resolved.provider.usesPkce ? lib.generateCodeVerifier() : null;
+		const state = generateState();
+		const codeVerifier = resolved.provider.usesPkce ? generateCodeVerifier() : null;
 		return {
-			url: resolved.provider.createAuthorizationURL(state, codeVerifier, resolved.scopes).toString(),
+			url: resolved.provider.createAuthorizationURL({
+				state,
+				codeVerifier,
+				scopes: resolved.scopes
+			}).toString(),
 			state,
 			codeVerifier
 		};
@@ -102,10 +105,15 @@ var OAuth2Service = class extends Service {
 	*/
 	async exchangeAndProvision(provider, code, codeVerifier, returnedIss) {
 		const { provider: p } = await this.#resolveProvider(provider);
-		if (p.expectedIssuer !== null) {
-			if (returnedIss === null || returnedIss !== p.expectedIssuer) throw new AuthenticationError("OAuth issuer mismatch");
+		const policy = p.issuerPolicy;
+		if (policy !== null) {
+			if (returnedIss !== null && returnedIss !== policy.issuer) throw new AuthenticationError("OAuth issuer mismatch");
+			if (returnedIss === null && policy.requireIssParameter) throw new AuthenticationError("OAuth issuer missing");
 		}
-		const tokens = await p.validateAuthorizationCode(code, codeVerifier);
+		const tokens = await p.validateAuthorizationCode({
+			code,
+			codeVerifier
+		});
 		const profile = await p.fetchProfile(tokens);
 		const cfg = this.#config.oauth2;
 		const defaultRoles = cfg.providers[provider]?.defaultRoles ?? cfg.defaultRoles;
@@ -114,37 +122,38 @@ var OAuth2Service = class extends Service {
 			allowSignup: cfg.allowSignup
 		})).identifier };
 	}
-	async #resolveProvider(name) {
+	#resolveProvider(name) {
 		this.#ensureReady();
 		this.#providers ??= /* @__PURE__ */ new Map();
 		const cached = this.#providers.get(name);
 		if (cached) return cached;
+		const pending = this.#buildProvider(name);
+		this.#providers.set(name, pending);
+		pending.catch(() => this.#providers?.delete(name));
+		return pending;
+	}
+	async #buildProvider(name) {
 		const cfg = this.#config.oauth2.providers[name];
 		if (!cfg) throw new AuthenticationError(`OAuth provider "${name}" non configuré`);
 		const factory = getOAuthProviderFactory(name);
 		if (!factory) throw new AuthenticationError(`OAuth provider "${name}" inconnu du registre`);
-		const provider = factory({
-			arctic: await this.#ensureLib(),
+		const provider = await factory({
 			clientId: cfg.clientId,
 			clientSecret: cfg.clientSecret,
+			clientAuthMethod: cfg.clientAuthMethod,
 			redirectUri: cfg.redirectUri,
 			issuer: cfg.issuer
 		});
-		const resolved = {
+		return {
 			provider,
 			scopes: cfg.scopes.length > 0 ? cfg.scopes : provider.defaultScopes
 		};
-		this.#providers.set(name, resolved);
-		return resolved;
 	}
 	#resolveProvisioner() {
 		const users = this.get("users");
 		if (!users || typeof users.provisionOAuthUser !== "function") throw new AuthenticationError("OAuth provisioning indisponible (le service users n'implémente pas IOAuthUserProvisioner)");
 		return users;
 	}
-	async #ensureLib() {
-		return this.#lib ??= await import("arctic");
-	}
 	#ensureReady() {
 		if (!this.#ready || this.#config === null) throw new Error("OAuth2Service: non initialisé (social login désactivé ou boot échoué)");
 	}

package/dist/nodefony/src/oauth/httpJson.js

@@ -0,0 +1,64 @@
+//#region nodefony/src/oauth/httpJson.ts
+/**
+* Lecture BORNÉE d'un corps JSON — la brique de transport commune aux trois
+* appels sortants du social login (découverte, point de jeton, API d'un
+* fournisseur non-OIDC).
+*
+* Elle existe parce qu'une borne posée APRÈS `response.text()` ne protège plus
+* rien : le corps est déjà entièrement en mémoire quand on mesure sa longueur.
+*/
+/**
+* Lit un corps JSON en refusant de dépasser une taille — la borne est vérifiée
+* PENDANT la lecture, pas après : un corps déjà entièrement en mémoire ne se
+* refuse plus.
+*
+* @param response - réponse dont le corps reste à lire.
+* @param maxBytes - plafond, en octets réels du flux.
+* @param subject - ce qu'on lisait, pour que l'erreur soit exploitable.
+* @returns la valeur JSON telle quelle — un objet OU un tableau (l'API d'un
+*   fournisseur rend les deux ; c'est à l'appelant d'exiger la forme qu'il attend).
+* @throws Error - corps trop gros ou illisible.
+*/
+async function readJsonBounded(response, maxBytes, subject) {
+	const announced = response.headers.get("content-length");
+	if (announced !== null && Number(announced) > maxBytes) throw new Error(`${subject} → corps hors gabarit (${announced} octets)`);
+	const body = response.body;
+	let text;
+	if (body === null) {
+		text = await response.text();
+		if (text.length > maxBytes) throw new Error(`${subject} → corps hors gabarit`);
+	} else {
+		const reader = body.getReader();
+		const chunks = [];
+		let seen = 0;
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			seen += value.byteLength;
+			if (seen > maxBytes) {
+				await reader.cancel();
+				throw new Error(`${subject} → corps hors gabarit (> ${maxBytes} octets)`);
+			}
+			chunks.push(value);
+		}
+		text = Buffer.concat(chunks).toString("utf8");
+	}
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new Error(`${subject} → corps illisible (JSON attendu)`);
+	}
+}
+/**
+* Comme {@link readJsonBounded}, mais exige un OBJET — la forme de toute réponse
+* normalisée par une RFC (document de métadonnées, réponse d'un point de jeton).
+*
+* @throws Error - corps trop gros, illisible, ou qui n'est pas un objet JSON.
+*/
+async function readJsonObjectBounded(response, maxBytes, subject) {
+	const payload = await readJsonBounded(response, maxBytes, subject);
+	if (payload === null || typeof payload !== "object" || Array.isArray(payload)) throw new Error(`${subject} → corps inattendu (objet JSON attendu)`);
+	return payload;
+}
+//#endregion
+export { readJsonBounded, readJsonObjectBounded };

package/dist/nodefony/src/oauth/metadata.js

@@ -0,0 +1,88 @@
+import { readJsonObjectBounded } from "./httpJson.js";
+import { canonicalIssuer, issuerMetadataUrls, validateIssuerMetadata } from "nodefony";
+//#region nodefony/src/oauth/metadata.ts
+/**
+* **Découverte des métadonnées d'un serveur d'autorisation** (RFC 8414) — la face
+* CLIENTE de la règle que le cœur porte déjà.
+*
+* C'est ce qui remplace, à soi seul, une classe par fournisseur : les points
+* d'entrée ne sont plus écrits en dur, ils sont demandés à l'émetteur. Ajouter un
+* fournisseur OIDC (Microsoft Entra, Auth0, Okta, Authentik...) ne demande donc
+* PLUS de code : son seul émetteur suffit.
+*
+* @remarks **Ce module ne réimplémente RIEN de la RFC 8414.** La normalisation de
+* l'émetteur (`canonicalIssuer`), l'ordre normatif des URL bien connues
+* (`issuerMetadataUrls`) et l'égalité stricte du §3.3 (`validateIssuerMetadata`)
+* vivent dans `nodefony` — la même implémentation sert à PUBLIER nos métadonnées
+* et à LIRE celles d'autrui, sans quoi les deux faces divergeraient en silence.
+* Il n'ajoute que le transport : requête bornée, et lecture des deux points
+* d'entrée dont le flux *Authorization Code* a besoin.
+*/
+/** Un émetteur muet ne doit pas retenir la requête de login. */
+const DISCOVERY_TIMEOUT_MS = 1e4;
+/** Au-delà, le document n'est plus un document de métadonnées — on refuse de lire. */
+const MAX_METADATA_BYTES = 1048576;
+async function fetchMetadataDocument(url, options) {
+	const response = await (options.fetch ?? globalThis.fetch)(url, {
+		headers: {
+			Accept: "application/json",
+			"User-Agent": "nodefony"
+		},
+		redirect: "error",
+		signal: AbortSignal.timeout(options.timeoutMs ?? DISCOVERY_TIMEOUT_MS)
+	});
+	if (!response.ok) throw new Error(`${url} → HTTP ${response.status}`);
+	return readJsonObjectBounded(response, MAX_METADATA_BYTES, url);
+}
+function requireEndpoint(document, field, issuer) {
+	const value = document[field];
+	if (typeof value !== "string" || value.length === 0) throw new Error(`métadonnées de « ${issuer} » : champ « ${field} » absent (RFC 8414 §2).`);
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new Error(`métadonnées de « ${issuer} » : « ${field} » n'est pas une URL.`);
+	}
+	if (url.protocol !== "https:") throw new Error(`métadonnées de « ${issuer} » : « ${field} » doit être en https.`);
+	return value;
+}
+/**
+* Interroge un serveur d'autorisation et rend ses points d'entrée.
+*
+* Les URL candidates sont celles du cœur (`issuerMetadataUrls`, ordre normatif
+* RFC 8414 §3.1 : insertion oauth → insertion oidc → ajout oidc), et la réponse
+* est CONFRONTÉE à l'émetteur demandé par `validateIssuerMetadata` (§3.3). C'est
+* cette garde qui empêche un émetteur détourné d'imposer ses propres points
+* d'entrée — la même attaque que le paramètre `iss` couvre au retour (RFC 9207).
+*
+* @param rawIssuer - identifiant d'émetteur tel qu'écrit en configuration.
+* @param options - transport injectable et délai d'attente.
+* @returns Les points d'entrée, prêts pour `OAuth2Client`.
+* @throws Error - émetteur mal formé, document introuvable, incomplet, ou `issuer` discordant.
+*/
+async function discoverAuthorizationServer(rawIssuer, options = {}) {
+	const issuer = canonicalIssuer(rawIssuer);
+	const failures = [];
+	for (const candidate of issuerMetadataUrls(issuer)) {
+		let document;
+		try {
+			document = await fetchMetadataDocument(candidate, options);
+		} catch (error) {
+			failures.push(error instanceof Error ? error.message : String(error));
+			continue;
+		}
+		const identity = validateIssuerMetadata(document, issuer);
+		const methods = document.code_challenge_methods_supported;
+		return {
+			issuer: identity.issuer,
+			jwksUri: identity.jwksUri,
+			authorizationEndpoint: requireEndpoint(document, "authorization_endpoint", issuer),
+			tokenEndpoint: requireEndpoint(document, "token_endpoint", issuer),
+			codeChallengeMethodsSupported: Array.isArray(methods) ? methods.filter((m) => typeof m === "string") : null,
+			issParameterSupported: document.authorization_response_iss_parameter_supported === true
+		};
+	}
+	throw new Error(`métadonnées introuvables pour « ${issuer} » — ${failures.join(" ; ")}`);
+}
+//#endregion
+export { discoverAuthorizationServer };

package/dist/nodefony/src/oauth/oauth2Client.js

@@ -0,0 +1,266 @@
+import { readJsonObjectBounded } from "./httpJson.js";
+import { createHash, randomBytes } from "node:crypto";
+//#region nodefony/src/oauth/oauth2Client.ts
+/**
+* Client **OAuth 2.0 / Authorization Code** minimal — la face cliente du protocole
+* dont Nodefony écrit déjà la face serveur (émetteur de jetons, métadonnées,
+* ressource protégée). Aucune dépendance : `node:crypto` pour l'entropie, `fetch`
+* pour l'échange.
+*
+* Posture OAuth 2.1 (RFC 9700) : Authorization Code seul, **PKCE S256** (RFC 7636)
+* quand le fournisseur le supporte, `state` anti-CSRF, jamais d'implicit ni de ROPC.
+*
+* @remarks Le flux vit sur un chemin FROID (un login humain) : les quelques
+* allocations et l'unique requête sortante n'entrent dans aucun chemin de requête.
+*/
+/**
+* Entropie tirée pour `state` et `code_verifier` : 32 octets, soit 43 caractères
+* en base64url — exactement la borne basse du `code_verifier` (RFC 7636 §4.1),
+* dont l'alphabet est inclus dans les caractères `unreserved` exigés.
+*/
+const ENTROPY_BYTES = 32;
+/** Au-delà, la réponse d'un point de jeton n'est plus plausible — on refuse d'analyser. */
+const MAX_TOKEN_RESPONSE_BYTES = 1048576;
+/** Un serveur d'autorisation muet ne doit pas retenir la requête de login. */
+const TOKEN_REQUEST_TIMEOUT_MS = 1e4;
+/**
+* Tire un `state` anti-CSRF (RFC 6749 §10.12, RFC 9700 §4.7) — 256 bits issus du
+* générateur cryptographique du système.
+*/
+function generateState() {
+	return randomBytes(ENTROPY_BYTES).toString("base64url");
+}
+/**
+* Tire un `code_verifier` PKCE (RFC 7636 §4.1) — 43 caractères de l'alphabet
+* `unreserved`, porteurs de 256 bits d'entropie.
+*/
+function generateCodeVerifier() {
+	return randomBytes(ENTROPY_BYTES).toString("base64url");
+}
+/**
+* Calcule le `code_challenge` de la méthode **S256** (RFC 7636 §4.2) :
+* `BASE64URL(SHA256(ASCII(code_verifier)))`.
+*
+* @remarks La méthode `plain` n'est jamais proposée — OAuth 2.1 et la RFC 9700
+* §2.1.1 l'excluent : elle ne protège pas d'un code intercepté.
+*/
+function createCodeChallenge(codeVerifier) {
+	assertCodeVerifier(codeVerifier);
+	return createHash("sha256").update(codeVerifier, "ascii").digest("base64url");
+}
+/** Grammaire d'un `code_verifier` : 43 à 128 caractères `unreserved` (RFC 7636 §4.1). */
+const CODE_VERIFIER = /^[A-Za-z0-9\-._~]{43,128}$/;
+/**
+* Refuse un `code_verifier` hors grammaire AVANT de s'en servir.
+*
+* @remarks Sans cette garde, un appelant qui fournit son propre secret (le
+* contrat l'autorise) obtiendrait un défi calculé sur une valeur que le serveur
+* d'autorisation rejettera plus tard : l'erreur sortirait au retour, sous la
+* forme d'un `invalid_grant` que rien ne relie à sa cause.
+*
+* @throws Error - la valeur ne respecte pas la grammaire de la RFC 7636 §4.1.
+*/
+function assertCodeVerifier(codeVerifier) {
+	if (!CODE_VERIFIER.test(codeVerifier)) throw new Error("code_verifier invalide : 43 à 128 caractères parmi [A-Za-z0-9-._~] (RFC 7636 §4.1).");
+}
+/**
+* Encode une valeur selon `application/x-www-form-urlencoded`, la forme qu'exige
+* l'authentification cliente HTTP Basic (RFC 6749 §2.3.1).
+*/
+function formUrlencode(value) {
+	return new URLSearchParams([["", value]]).toString().slice(1);
+}
+/**
+* Refus du serveur d'autorisation au point de jeton (RFC 6749 §5.2). Porte le
+* code `error` normalisé — la seule partie de la réponse sûre à journaliser.
+*/
+var OAuth2RequestError = class extends Error {
+	/** Code normalisé (`invalid_grant`, `invalid_client`, ...) — RFC 6749 §5.2. */
+	code;
+	/** Description lisible fournie par le serveur, ou `null`. */
+	description;
+	constructor(code, description) {
+		super(description === null ? code : `${code}: ${description}`);
+		this.name = "OAuth2RequestError";
+		this.code = code;
+		this.description = description;
+	}
+};
+/**
+* Jetons rendus par le point de jeton (RFC 6749 §5.1), enveloppés pour qu'un champ
+* attendu mais absent lève une erreur NOMMÉE au lieu de propager un `undefined`
+* jusqu'au décodage du profil.
+*/
+var OAuth2Tokens = class {
+	/** Corps JSON brut de la réponse — donne accès aux extensions du fournisseur. */
+	data;
+	constructor(data) {
+		this.data = data;
+	}
+	#requireString(field) {
+		const value = this.data[field];
+		if (typeof value !== "string" || value.length === 0) throw new Error(`Réponse du point de jeton sans champ « ${field} ».`);
+		return value;
+	}
+	/** Jeton d'accès (RFC 6749 §5.1). */
+	accessToken() {
+		return this.#requireString("access_token");
+	}
+	/** Type du jeton d'accès — `Bearer` en pratique (RFC 6750). */
+	tokenType() {
+		return this.#requireString("token_type");
+	}
+	/** Jeton d'identité OIDC (OpenID Connect Core §3.1.3.3). */
+	idToken() {
+		return this.#requireString("id_token");
+	}
+	/** `true` si le serveur a émis un jeton de rafraîchissement. */
+	hasRefreshToken() {
+		return typeof this.data.refresh_token === "string";
+	}
+	/** Jeton de rafraîchissement (RFC 6749 §1.5). */
+	refreshToken() {
+		return this.#requireString("refresh_token");
+	}
+	/** Durée de vie restante du jeton d'accès, en secondes. */
+	accessTokenExpiresInSeconds() {
+		const value = this.data.expires_in;
+		if (typeof value !== "number" || !Number.isFinite(value)) throw new Error("Réponse du point de jeton sans champ « expires_in ».");
+		return value;
+	}
+	/** Instant d'expiration du jeton d'accès, dérivé de `expires_in`. */
+	accessTokenExpiresAt() {
+		return new Date(Date.now() + this.accessTokenExpiresInSeconds() * 1e3);
+	}
+	/** `true` si le serveur a annoncé les portées effectivement accordées. */
+	hasScopes() {
+		return typeof this.data.scope === "string";
+	}
+	/** Portées accordées, telles que le serveur les a annoncées (RFC 6749 §3.3). */
+	scopes() {
+		return this.#requireString("scope").split(" ");
+	}
+};
+/**
+* Les paramètres que le protocole POSE lui-même, et qu'un appelant ne peut donc
+* pas fournir en supplément.
+*
+* Sans cette garde, `additionalParameters` deviendrait une porte pour réécrire
+* `client_id` ou `redirect_uri` — c'est-à-dire pour faire émettre par ce client
+* une requête qui ne le désigne plus. Le refus est explicite et nomme la clé :
+* un paramètre silencieusement ignoré serait pire, l'appelant croirait l'avoir
+* envoyé.
+*/
+const RESERVED_PARAMETERS = /* @__PURE__ */ new Set([
+	"response_type",
+	"client_id",
+	"client_secret",
+	"redirect_uri",
+	"state",
+	"scope",
+	"code",
+	"code_verifier",
+	"code_challenge",
+	"code_challenge_method",
+	"grant_type"
+]);
+/**
+* Verse des paramètres supplémentaires sans jamais recouvrir ceux du protocole.
+*
+* @param target - la collection en construction (requête ou corps).
+* @param extra - ce que l'appelant ajoute, tel quel.
+* @throws Error - une clé réservée au protocole a été fournie.
+*/
+function applyAdditionalParameters(target, extra) {
+	if (extra === void 0) return;
+	for (const [key, value] of Object.entries(extra)) {
+		if (RESERVED_PARAMETERS.has(key)) throw new Error(`Paramètre « ${key} » réservé au protocole : il est posé par le client, pas par l'appelant.`);
+		target.set(key, value);
+	}
+}
+/**
+* Client d'un serveur d'autorisation donné : construit l'URL d'autorisation puis
+* échange le code contre des jetons.
+*
+* Un exemplaire porte les endpoints DÉJÀ résolus — par découverte de métadonnées
+* ({@link discoverAuthorizationServer}) ou en dur pour un fournisseur qui n'en
+* publie pas (GitHub).
+*/
+var OAuth2Client = class {
+	#options;
+	constructor(options) {
+		this.#options = options;
+	}
+	/**
+	* Construit l'URL d'autorisation (RFC 6749 §4.1.1). Le `code_challenge` S256 est
+	* ajouté dès qu'un `codeVerifier` est fourni.
+	*
+	* @param request - ce qu'on demande au point d'autorisation.
+	* @returns l'URL vers laquelle rediriger l'utilisateur.
+	* @throws Error - un paramètre supplémentaire empiète sur le protocole.
+	*/
+	createAuthorizationURL(request) {
+		const url = new URL(this.#options.authorizationEndpoint);
+		applyAdditionalParameters(url.searchParams, request.additionalParameters);
+		url.searchParams.set("response_type", "code");
+		url.searchParams.set("client_id", this.#options.clientId);
+		url.searchParams.set("redirect_uri", this.#options.redirectUri);
+		url.searchParams.set("state", request.state);
+		if (request.scopes.length > 0) url.searchParams.set("scope", request.scopes.join(" "));
+		if (request.codeVerifier !== null) {
+			url.searchParams.set("code_challenge_method", "S256");
+			url.searchParams.set("code_challenge", createCodeChallenge(request.codeVerifier));
+		}
+		return url;
+	}
+	/**
+	* Échange le code d'autorisation contre des jetons (RFC 6749 §4.1.3), de serveur
+	* à serveur — le secret client ne quitte jamais ce canal.
+	*
+	* @param request - ce qu'on présente au point de jeton.
+	* @throws OAuth2RequestError - le serveur a refusé, en nommant la cause (RFC 6749 §5.2).
+	* @throws Error - réponse inintelligible, hors gabarit, serveur injoignable, ou
+	*   paramètre supplémentaire empiétant sur le protocole.
+	*/
+	async validateAuthorizationCode(request) {
+		const body = new URLSearchParams();
+		applyAdditionalParameters(body, request.additionalParameters);
+		body.set("grant_type", "authorization_code");
+		body.set("code", request.code);
+		body.set("redirect_uri", this.#options.redirectUri);
+		if (request.codeVerifier !== null) body.set("code_verifier", request.codeVerifier);
+		const headers = {
+			"Content-Type": "application/x-www-form-urlencoded",
+			Accept: "application/json",
+			"User-Agent": "nodefony"
+		};
+		switch (this.#options.clientAuthMethod) {
+			case "client_secret_basic":
+				headers.Authorization = `Basic ${this.#basicCredentials()}`;
+				break;
+			case "client_secret_post":
+				body.set("client_id", this.#options.clientId);
+				body.set("client_secret", this.#options.clientSecret);
+				break;
+			case "none": body.set("client_id", this.#options.clientId);
+		}
+		const response = await (this.#options.fetch ?? globalThis.fetch)(this.#options.tokenEndpoint, {
+			method: "POST",
+			headers,
+			body: body.toString(),
+			redirect: "error",
+			signal: AbortSignal.timeout(this.#options.timeoutMs ?? TOKEN_REQUEST_TIMEOUT_MS)
+		});
+		const data = await readJsonObjectBounded(response, MAX_TOKEN_RESPONSE_BYTES, `point de jeton (HTTP ${response.status})`);
+		if (typeof data.error === "string") throw new OAuth2RequestError(data.error, typeof data.error_description === "string" ? data.error_description : null);
+		if (!response.ok) throw new Error(`Point de jeton en échec (HTTP ${response.status}).`);
+		return new OAuth2Tokens(data);
+	}
+	#basicCredentials() {
+		const id = formUrlencode(this.#options.clientId);
+		const secret = formUrlencode(this.#options.clientSecret);
+		return Buffer.from(`${id}:${secret}`, "utf8").toString("base64");
+	}
+};
+//#endregion
+export { OAuth2Client, OAuth2RequestError, OAuth2Tokens, createCodeChallenge, generateCodeVerifier, generateState };