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

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

@@ -1,4 +1,4 @@
-import { createOidcProvider } from "./providers/oidc.js";
+import { createDiscoveredOidcProvider } from "./providers/oidc.js";
 import { createGithubProvider } from "./providers/github.js";
 //#region nodefony/src/oauth/oauthProviderRegistry.ts
 const factories = /* @__PURE__ */ new Map();
@@ -17,21 +17,10 @@ function getOAuthProviderFactory(name) {
 function listOAuthProviders() {
 	return [...factories.keys()];
 }
-registerOAuthProvider("google", (ctx) => createOidcProvider({
-	name: "google",
-	client: new ctx.arctic.Google(ctx.clientId, ctx.clientSecret, ctx.redirectUri),
-	issuer: "https://accounts.google.com",
-	decodeIdToken: ctx.arctic.decodeIdToken
-}));
-registerOAuthProvider("keycloak", (ctx) => {
-	if (!ctx.issuer) throw new Error("OAuth provider \"keycloak\" : config \"issuer\" requise (URL du realm, ex. https://kc.example/realms/app).");
-	return createOidcProvider({
-		name: "keycloak",
-		client: new ctx.arctic.KeyCloak(ctx.issuer, ctx.clientId, ctx.clientSecret, ctx.redirectUri),
-		issuer: ctx.issuer,
-		decodeIdToken: ctx.arctic.decodeIdToken
-	});
-});
+const GOOGLE_ISSUER = "https://accounts.google.com";
+registerOAuthProvider("google", (ctx) => createDiscoveredOidcProvider("google", ctx, { issuer: GOOGLE_ISSUER }));
+registerOAuthProvider("keycloak", (ctx) => createDiscoveredOidcProvider("keycloak", ctx));
+registerOAuthProvider("oidc", (ctx) => createDiscoveredOidcProvider("oidc", ctx));
 registerOAuthProvider("github", createGithubProvider);
 //#endregion
 export { getOAuthProviderFactory, listOAuthProviders, registerOAuthProvider };

package/dist/nodefony/src/oauth/providers/github.js

@@ -1,7 +1,15 @@
+import { readJsonBounded } from "../httpJson.js";
+import { OAuth2Client } from "../oauth2Client.js";
 //#region nodefony/src/oauth/providers/github.ts
 /** Scopes minimaux : profil public + emails (l'email primaire peut être privé). */
 const DEFAULT_SCOPES = ["read:user", "user:email"];
 const API = "https://api.github.com";
+/** Une API muette ne doit pas retenir le callback jusqu'aux délais du runtime. */
+const API_TIMEOUT_MS = 1e4;
+/** Au-delà, ce n'est plus un profil : on refuse de lire. */
+const MAX_PROFILE_BYTES = 1048576;
+const AUTHORIZATION_ENDPOINT = "https://github.com/login/oauth/authorize";
+const TOKEN_ENDPOINT = "https://github.com/login/oauth/access_token";
 function ghHeaders(accessToken) {
 	return {
 		Authorization: `Bearer ${accessToken}`,
@@ -11,27 +19,44 @@ function ghHeaders(accessToken) {
 	};
 }
 async function ghGet(url, accessToken) {
-	const res = await fetch(url, { headers: ghHeaders(accessToken) });
+	const res = await fetch(url, {
+		headers: ghHeaders(accessToken),
+		redirect: "error",
+		signal: AbortSignal.timeout(API_TIMEOUT_MS)
+	});
 	if (!res.ok) throw new Error(`GitHub API ${url} → ${res.status}`);
-	return res.json();
+	return readJsonBounded(res, MAX_PROFILE_BYTES, `GitHub API ${url}`);
 }
 /**
 * Fournisseur **GitHub** (OAuth 2.0 simple, NON-OIDC). Pas de PKCE, pas d'ID
 * token : le profil est lu via l'API REST (`/user`), et l'email — souvent privé —
 * via `/user/emails` (scope `user:email`). GitHub n'émet pas de paramètre `iss`
-* (`expectedIssuer = null`) : la défense anti-CSRF repose sur le `state`.
+* (`issuerPolicy = null`) : la défense anti-CSRF repose sur le `state`.
 */
 function createGithubProvider(ctx) {
-	const client = new ctx.arctic.GitHub(ctx.clientId, ctx.clientSecret, ctx.redirectUri);
+	const client = new OAuth2Client({
+		authorizationEndpoint: AUTHORIZATION_ENDPOINT,
+		tokenEndpoint: TOKEN_ENDPOINT,
+		clientId: ctx.clientId,
+		clientSecret: ctx.clientSecret,
+		clientAuthMethod: ctx.clientAuthMethod ?? "client_secret_basic",
+		redirectUri: ctx.redirectUri
+	});
 	return {
 		usesPkce: false,
-		expectedIssuer: null,
+		issuerPolicy: null,
 		defaultScopes: DEFAULT_SCOPES,
-		createAuthorizationURL(state, _codeVerifier, scopes) {
-			return client.createAuthorizationURL(state, scopes);
+		createAuthorizationURL(request) {
+			return client.createAuthorizationURL({
+				...request,
+				codeVerifier: null
+			});
 		},
-		validateAuthorizationCode(code, _codeVerifier) {
-			return client.validateAuthorizationCode(code);
+		validateAuthorizationCode(request) {
+			return client.validateAuthorizationCode({
+				...request,
+				codeVerifier: null
+			});
 		},
 		async fetchProfile(tokens) {
 			const accessToken = tokens.accessToken();

package/dist/nodefony/src/oauth/providers/oidc.js

@@ -1,3 +1,5 @@
+import { OAuth2Client } from "../oauth2Client.js";
+import { discoverAuthorizationServer } from "../metadata.js";
 //#region nodefony/src/oauth/providers/oidc.ts
 const DEFAULT_OIDC_SCOPES = [
 	"openid",
@@ -5,14 +7,42 @@ const DEFAULT_OIDC_SCOPES = [
 	"email"
 ];
 /**
+* Lit les claims d'un ID token SANS vérifier sa signature.
+*
+* @remarks C'est ce qu'autorise OpenID Connect Core §3.1.3.7 dans le flux
+* *Authorization Code* : le jeton vient d'être reçu du point de jeton, sur un
+* canal TLS direct et authentifié — il n'a traversé ni le navigateur ni un tiers.
+* `jose` est chargé paresseusement, comme partout ailleurs dans ce module : il
+* n'entre jamais dans le coût du boot.
+*/
+async function decodeIdTokenClaims(idToken) {
+	return (await import("jose")).decodeJwt(idToken);
+}
+/**
+* Éprouve les claims OBLIGATOIRES d'un ID token (OpenID Connect Core §3.1.3.7).
+*
+* @remarks La SIGNATURE n'est pas vérifiée — le jeton vient d'être reçu du point
+* de jeton sur un canal TLS direct, ce que la norme admet explicitement. Mais les
+* autres exigences du même paragraphe ne coûtent aucun réseau et ferment de vrais
+* écarts : un jeton d'un autre émetteur (point 2), délivré à une autre
+* application (point 3), ou périmé (point 9), n'a rien à faire ici.
+*
+* @throws Error - un claim obligatoire est absent, discordant ou périmé.
+*/
+function assertIdTokenClaims(claims, opts) {
+	if (typeof claims.sub !== "string" || claims.sub.length === 0) throw new Error(`${opts.name}: ID token sans claim 'sub'.`);
+	if (claims.iss !== opts.issuer) throw new Error(`${opts.name}: ID token émis par « ${String(claims.iss)} », attendu « ${opts.issuer} ».`);
+	const aud = claims.aud;
+	if (!(aud === opts.clientId || Array.isArray(aud) && aud.includes(opts.clientId))) throw new Error(`${opts.name}: ID token délivré à une autre application.`);
+	if (typeof claims.exp !== "number" || claims.exp * 1e3 <= Date.now()) throw new Error(`${opts.name}: ID token périmé ou sans 'exp'.`);
+}
+/**
 * Fabrique un {@link IOAuthProvider} **générique OIDC** — couvre TOUT fournisseur
 * OpenID Connect sans code spécifique : le profil se lit toujours pareil (claims
-* standard `sub`/`email`/`email_verified`/`name` de l'ID token). Ajouter un
-* fournisseur OIDC = une entrée de quelques lignes (nom + classe arctic + issuer),
-* pas un fichier.
+* standard `sub`/`email`/`email_verified`/`name` de l'ID token).
 *
-* PKCE S256 systématique (RFC 7636) ; le profil vient de l'ID token signé obtenu
-* du token endpoint via TLS (décodage suffisant en code flow, RFC 8725).
+* PKCE S256 systématique (RFC 7636) ; le profil vient de l'ID token obtenu du
+* point de jeton via TLS.
 */
 function createOidcProvider(opts) {
 	const requireVerifier = (codeVerifier) => {
@@ -21,18 +51,27 @@ function createOidcProvider(opts) {
 	};
 	return {
 		usesPkce: true,
-		expectedIssuer: opts.issuer,
+		issuerPolicy: {
+			issuer: opts.issuer,
+			requireIssParameter: opts.issParameterSupported === true
+		},
 		defaultScopes: opts.defaultScopes ?? DEFAULT_OIDC_SCOPES,
-		createAuthorizationURL(state, codeVerifier, scopes) {
-			return opts.client.createAuthorizationURL(state, requireVerifier(codeVerifier), scopes);
+		createAuthorizationURL(request) {
+			return opts.client.createAuthorizationURL({
+				...request,
+				codeVerifier: requireVerifier(request.codeVerifier)
+			});
 		},
-		validateAuthorizationCode(code, codeVerifier) {
-			return opts.client.validateAuthorizationCode(code, requireVerifier(codeVerifier));
+		validateAuthorizationCode(request) {
+			return opts.client.validateAuthorizationCode({
+				...request,
+				codeVerifier: requireVerifier(request.codeVerifier)
+			});
 		},
 		async fetchProfile(tokens) {
-			const claims = opts.decodeIdToken(tokens.idToken());
+			const claims = await opts.decodeIdToken(tokens.idToken());
+			assertIdTokenClaims(claims, opts);
 			const sub = claims.sub;
-			if (typeof sub !== "string" || sub.length === 0) throw new Error(`${opts.name}: ID token sans claim 'sub'.`);
 			return {
 				provider: opts.name,
 				providerId: sub,
@@ -44,5 +83,40 @@ function createOidcProvider(opts) {
 		}
 	};
 }
+/**
+* Construit un fournisseur OIDC **en demandant ses points d'entrée à l'émetteur**
+* (RFC 8414 / OpenID Connect Discovery) — aucune URL n'est écrite en dur.
+*
+* C'est ce qui permet d'enregistrer n'importe quel fournisseur OpenID Connect sans
+* écrire une ligne de code : seul son émetteur le distingue.
+*
+* @param name - nom sous lequel le fournisseur est configuré.
+* @param options - émetteur explicite, transport injectable, délai d'attente.
+* @throws Error - émetteur absent, découverte impossible, ou serveur annonçant ne
+*   pas supporter PKCE S256 alors que ce fournisseur l'exige.
+*/
+async function createDiscoveredOidcProvider(name, ctx, options = {}) {
+	const effectiveIssuer = options.issuer ?? ctx.issuer;
+	if (!effectiveIssuer) throw new Error(`OAuth provider "${name}" : config "issuer" requise (URL de l'émetteur OIDC).`);
+	const metadata = await discoverAuthorizationServer(effectiveIssuer, options);
+	if (metadata.codeChallengeMethodsSupported !== null && !metadata.codeChallengeMethodsSupported.includes("S256")) throw new Error(`OAuth provider "${name}" : l'émetteur « ${effectiveIssuer} » n'annonce pas PKCE S256 (RFC 7636).`);
+	return createOidcProvider({
+		name,
+		issuer: metadata.issuer,
+		issParameterSupported: metadata.issParameterSupported,
+		clientId: ctx.clientId,
+		decodeIdToken: decodeIdTokenClaims,
+		client: new OAuth2Client({
+			authorizationEndpoint: metadata.authorizationEndpoint,
+			tokenEndpoint: metadata.tokenEndpoint,
+			clientId: ctx.clientId,
+			clientSecret: ctx.clientSecret,
+			clientAuthMethod: ctx.clientAuthMethod ?? "client_secret_basic",
+			redirectUri: ctx.redirectUri,
+			fetch: options.fetch,
+			timeoutMs: options.timeoutMs
+		})
+	});
+}
 //#endregion
-export { createOidcProvider };
+export { createDiscoveredOidcProvider, createOidcProvider };

package/dist/types/index.d.ts

@@ -114,9 +114,16 @@ export type { IWebAuthnUser, IWebAuthnAssertionResult, } from "./nodefony/servic
 export type { IWebAuthnCredential } from "./nodefony/contracts/IWebAuthnCredential.js";
 export type { IWebAuthnCredentialStore, IWebAuthnCredentialSummary, IWebAuthnListQuery, WebAuthnAuthUpdate, } from "./nodefony/contracts/IWebAuthnCredentialStore.js";
 export type { IOAuthAuthorization } from "./nodefony/service/oauth2.js";
-export type { IOAuthProvider } from "./nodefony/contracts/IOAuthProvider.js";
+export type { IOAuthProvider, IIssuerPolicy, } from "./nodefony/contracts/IOAuthProvider.js";
 export { registerOAuthProvider, getOAuthProviderFactory, listOAuthProviders, } from "./nodefony/src/oauth/oauthProviderRegistry.js";
 export type { OAuthProviderFactory, IOAuthProviderContext, } from "./nodefony/src/oauth/oauthProviderRegistry.js";
+export { OAuth2Client, OAuth2Tokens, OAuth2RequestError, generateState, generateCodeVerifier, createCodeChallenge, } from "./nodefony/src/oauth/oauth2Client.js";
+export type { IOAuth2ClientOptions } from "./nodefony/src/oauth/oauth2Client.js";
+export { discoverAuthorizationServer } from "./nodefony/src/oauth/metadata.js";
+export type { IDiscoveredAuthorizationServer, IDiscoveryOptions, } from "./nodefony/src/oauth/metadata.js";
+export { createOidcProvider, createDiscoveredOidcProvider, } from "./nodefony/src/oauth/providers/oidc.js";
+export type { IOidcPkceClient, IOidcProviderOptions, } from "./nodefony/src/oauth/providers/oidc.js";
+export { createGithubProvider } from "./nodefony/src/oauth/providers/github.js";
 export { MemoryAuditStore } from "./nodefony/src/audit/MemoryAuditStore.js";
 export type { AuditStoreSnapshot } from "./nodefony/src/audit/MemoryAuditStore.js";
 export type { IAuditEvent, IAuditEventDraft, IAuditEventFlags, AuditCategory, AuditOutcome, } from "./nodefony/contracts/IAuditEvent.js";

package/dist/types/nodefony/config/config.d.ts

@@ -228,6 +228,10 @@ export declare const securityConfigSchema: z.ZodObject<{
         providers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
             clientId: z.ZodString;
             clientSecret: z.ZodString;
+            clientAuthMethod: z.ZodOptional<z.ZodEnum<{
+                client_secret_basic: "client_secret_basic";
+                client_secret_post: "client_secret_post";
+            }>>;
             redirectUri: z.ZodString;
             issuer: z.ZodOptional<z.ZodString>;
             scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;

package/dist/types/nodefony/contracts/IOAuthProvider.d.ts

@@ -1,9 +1,36 @@
-import type { OAuth2Tokens } from "arctic";
+import type { IAuthorizationRequest, ITokenRequest, OAuth2Tokens } from "../src/oauth/oauth2Client.js";
 import type { IOAuthProfile } from "@nodefony/user";
 /**
- * Adaptateur d'**un fournisseur OAuth/OIDC**, façade UNIFORME au-dessus d'une
- * classe `arctic` — masque les divergences entre fournisseurs derrière un contrat
- * stable consommé par `OAuth2Service` :
+ * Ce qu'on exige du paramètre `iss` renvoyé par le serveur d'autorisation
+ * (RFC 9207).
+ *
+ * @remarks La règle a **trois** états, pas deux — et c'est ce que le booléen
+ * seul ne pouvait pas dire. La RFC §2.4 impose au client d'extraire `iss`
+ * « **if the parameter is present** », et son §2.3 fait annoncer le support par
+ * les métadonnées de l'émetteur. Refuser une réponse sans `iss` d'un serveur qui
+ * n'a jamais promis de l'émettre revient donc à refuser un serveur CONFORME —
+ * Microsoft Entra en est un.
+ *
+ * La défense anti-mix-up ne repose d'ailleurs pas sur ce seul paramètre : chaque
+ * fournisseur a son URL de redirection propre (`…/{provider}/callback`) et le
+ * flux vérifie que le fournisseur de retour est celui qui a démarré, ce que la
+ * RFC 9700 §4.4.2.2 donne comme défense principale. `iss` est la seconde ceinture.
+ */
+export interface IIssuerPolicy {
+    /** Émetteur attendu, sous sa forme canonique. */
+    readonly issuer: string;
+    /**
+     * `true` si le serveur ANNONCE émettre `iss`
+     * (`authorization_response_iss_parameter_supported`) : son absence est alors
+     * une promesse non tenue, donc un refus. `false` : absent, on continue ;
+     * présent, il doit correspondre.
+     */
+    readonly requireIssParameter: boolean;
+}
+/**
+ * Adaptateur d'**un fournisseur OAuth/OIDC**, façade UNIFORME au-dessus d'un client
+ * OAuth 2.0 — masque les divergences entre fournisseurs derrière un contrat stable
+ * consommé par `OAuth2Service` :
  *
  * - **PKCE ou non** : Google attend `createAuthorizationURL(state, codeVerifier,
  *   scopes)` ; GitHub `createAuthorizationURL(state, scopes)` (pas de
@@ -13,9 +40,9 @@ import type { IOAuthProfile } from "@nodefony/user";
  *   l'API du fournisseur (GitHub `/user`). Le résultat est toujours normalisé en
  *   {@link IOAuthProfile}.
  *
- * @remarks `arctic` n'est référencé ici qu'en **type** (`import type`, effacé à la
- * compilation) — l'instance runtime est chargée paresseusement par le service et
- * injectée aux fabriques. Aucune dépendance runtime n'entre par ce contrat.
+ * @remarks Ce contrat n'introduit aucune dépendance : le client OAuth 2.0 sous-jacent
+ * est écrit dans le module même, et un fournisseur maison peut l'implémenter sans
+ * rien installer.
  */
 export interface IOAuthProvider {
     /**
@@ -24,24 +51,28 @@ export interface IOAuthProvider {
      */
     readonly usesPkce: boolean;
     /**
-     * Identifiant d'émetteur attendu pour la défense anti-mix-up (RFC 9207), ou
-     * `null` si le fournisseur n'émet pas le paramètre `iss` (ex. GitHub, non-OIDC).
-     * Quand non-`null`, le service **rejette** une réponse dont l'`iss` diffère ou
-     * manque.
+     * Politique de vérification du paramètre `iss` (anti-mix-up, RFC 9207), ou
+     * `null` pour un fournisseur qui ne relève pas de cette défense (GitHub,
+     * non-OIDC).
      */
-    readonly expectedIssuer: string | null;
+    readonly issuerPolicy: IIssuerPolicy | null;
     /** Scopes appliqués quand la configuration n'en précise aucun. */
     readonly defaultScopes: string[];
     /**
      * Construit l'URL d'autorisation (étape 1). `codeVerifier` est non-`null`
      * lorsque {@link usesPkce} ; les fournisseurs sans PKCE l'ignorent.
+     *
+     * @remarks La forme est un OBJET pour que les paramètres normalisés encore
+     * absents — `resource` (RFC 8707), `nonce`, `prompt`… — s'ajoutent plus tard
+     * sans rupture. Ce contrat est EXPORTÉ, donc gelé à la publication : une
+     * signature positionnelle y aurait figé l'impossibilité de les accueillir.
      */
-    createAuthorizationURL(state: string, codeVerifier: string | null, scopes: string[]): URL;
+    createAuthorizationURL(request: IAuthorizationRequest): URL;
     /**
      * Échange le `code` d'autorisation contre des jetons (étape 2, canal serveur).
      * `codeVerifier` doit correspondre à celui de l'étape 1 si {@link usesPkce}.
      */
-    validateAuthorizationCode(code: string, codeVerifier: string | null): Promise<OAuth2Tokens>;
+    validateAuthorizationCode(request: ITokenRequest): Promise<OAuth2Tokens>;
     /**
      * Récupère et **normalise** le profil de l'utilisateur à partir des jetons.
      *

package/dist/types/nodefony/contracts/ITokenStore.d.ts

@@ -92,7 +92,7 @@ export interface IAccessTokenRecord {
     secretHash: string;
     /** Algorithme de hachage du secret (agilité crypto, migration future). Ex. `"sha256"`. */
     hashAlg: string;
-    /** Client OAuth émetteur (slot OAuth2/arctic) ; `null` = non-OAuth. */
+    /** Client OAuth émetteur (slot OAuth2) ; `null` = non-OAuth. */
     clientId: string | null;
     /** Confirmation sender-constrained : `jkt` (DPoP RFC 9449) / `x5t#S256` (mTLS RFC 8705) ; `null` = bearer simple. */
     cnf: string | null;

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

@@ -9,8 +9,7 @@ export interface IOAuthAuthorization {
     readonly codeVerifier: string | null;
 }
 /**
- * **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**
@@ -18,10 +17,11 @@ export interface IOAuthAuthorization {
  * (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

package/dist/types/nodefony/src/oauth/httpJson.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+export declare function readJsonBounded(response: Response, maxBytes: number, subject: string): Promise<unknown>;
+/**
+ * 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.
+ */
+export declare function readJsonObjectBounded(response: Response, maxBytes: number, subject: string): Promise<Record<string, unknown>>;

package/dist/types/nodefony/src/oauth/metadata.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Points d'entrée retenus d'un serveur d'autorisation — le sous-ensemble dont le
+ * flux *Authorization Code* a besoin (RFC 8414 §2).
+ *
+ * @remarks Le nom dit **ce qu'on a découvert chez autrui**, à ne pas confondre
+ * avec `IAuthorizationServerMetadata` du cœur, qui décrit le document que Nodefony
+ * PUBLIE (champs bruts de la RFC).
+ */
+export interface IDiscoveredAuthorizationServer {
+    /** Émetteur canonique, vérifié identique à celui interrogé (RFC 8414 §3.3). */
+    readonly issuer: string;
+    /** Point d'autorisation (RFC 6749 §3.1). */
+    readonly authorizationEndpoint: string;
+    /** Point de jeton (RFC 6749 §3.2). */
+    readonly tokenEndpoint: string;
+    /** Jeu de clés de signature — la porte d'une future vérification d'ID token. */
+    readonly jwksUri: string;
+    /** Méthodes PKCE annoncées (RFC 7636), ou `null` si le serveur n'en publie aucune. */
+    readonly codeChallengeMethodsSupported: string[] | null;
+    /**
+     * `true` si le serveur ANNONCE émettre le paramètre `iss` dans sa réponse
+     * d'autorisation (RFC 9207 §2.3). Absent du document ⇒ `false` : on ne peut
+     * alors pas exiger ce qu'il n'a pas promis.
+     */
+    readonly issParameterSupported: boolean;
+}
+/** Réglages de la découverte — l'injection de `fetch` est la voie pour éprouver sans TLS. */
+export interface IDiscoveryOptions {
+    /**
+     * Implémentation de `fetch` à employer.
+     *
+     * @remarks C'est ce que prescrit le cœur pour éprouver le mécanisme sans TLS :
+     * un émetteur en clair est refusé (RFC 8414 §2), on injecte donc le transport
+     * plutôt que d'affaiblir la règle.
+     */
+    readonly fetch?: typeof globalThis.fetch;
+    /** Délai d'attente par URL candidate, en millisecondes. */
+    readonly timeoutMs?: number;
+}
+/**
+ * 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.
+ */
+export declare function discoverAuthorizationServer(rawIssuer: string, options?: IDiscoveryOptions): Promise<IDiscoveredAuthorizationServer>;

package/dist/types/nodefony/src/oauth/oauth2Client.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Tire un `state` anti-CSRF (RFC 6749 §10.12, RFC 9700 §4.7) — 256 bits issus du
+ * générateur cryptographique du système.
+ */
+export declare function generateState(): string;
+/**
+ * Tire un `code_verifier` PKCE (RFC 7636 §4.1) — 43 caractères de l'alphabet
+ * `unreserved`, porteurs de 256 bits d'entropie.
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * 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é.
+ */
+export declare function createCodeChallenge(codeVerifier: string): string;
+/**
+ * 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.
+ */
+export declare class OAuth2RequestError extends Error {
+    /** Code normalisé (`invalid_grant`, `invalid_client`, ...) — RFC 6749 §5.2. */
+    readonly code: string;
+    /** Description lisible fournie par le serveur, ou `null`. */
+    readonly description: string | null;
+    constructor(code: string, description: string | null);
+}
+/**
+ * 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.
+ */
+export declare class OAuth2Tokens {
+    #private;
+    /** Corps JSON brut de la réponse — donne accès aux extensions du fournisseur. */
+    readonly data: Record<string, unknown>;
+    constructor(data: Record<string, unknown>);
+    /** Jeton d'accès (RFC 6749 §5.1). */
+    accessToken(): string;
+    /** Type du jeton d'accès — `Bearer` en pratique (RFC 6750). */
+    tokenType(): string;
+    /** Jeton d'identité OIDC (OpenID Connect Core §3.1.3.3). */
+    idToken(): string;
+    /** `true` si le serveur a émis un jeton de rafraîchissement. */
+    hasRefreshToken(): boolean;
+    /** Jeton de rafraîchissement (RFC 6749 §1.5). */
+    refreshToken(): string;
+    /** Durée de vie restante du jeton d'accès, en secondes. */
+    accessTokenExpiresInSeconds(): number;
+    /** Instant d'expiration du jeton d'accès, dérivé de `expires_in`. */
+    accessTokenExpiresAt(): Date;
+    /** `true` si le serveur a annoncé les portées effectivement accordées. */
+    hasScopes(): boolean;
+    /** Portées accordées, telles que le serveur les a annoncées (RFC 6749 §3.3). */
+    scopes(): string[];
+}
+/**
+ * Comment le client s'authentifie au point de jeton (RFC 6749 §2.3, et le
+ * registre `token_endpoint_auth_method` d'OpenID Connect Discovery).
+ *
+ * 🔴 Elle se DÉCLARE, elle ne se déduit plus de la vacuité du secret. La
+ * convention implicite « secret non vide ⇒ Basic » avait deux défauts : elle ne
+ * pouvait pas exprimer `client_secret_post`, que certains serveurs exigent et
+ * annoncent dans leurs métadonnées (`token_endpoint_auth_methods_supported`,
+ * déjà découvert et lu par personne) ; et elle rendait un client public
+ * indiscernable d'un client dont le secret manque par erreur — deux situations
+ * qu'un serveur traite très différemment.
+ *
+ * L'union est ouverte par le bas : `private_key_jwt` (qu'Apple réclame)
+ * s'ajoutera ici sans toucher à la forme des appels.
+ */
+export type OAuth2ClientAuthMethod = "client_secret_basic" | "client_secret_post" | "none";
+/**
+ * Étape 1 — ce qu'on demande au point d'autorisation.
+ *
+ * La forme est un OBJET, et c'est tout l'enjeu : les paramètres normalisés qui
+ * manquent encore — `resource` (RFC 8707, exigé par le Model Context Protocol),
+ * `nonce`, `prompt`, `max_age`, `login_hint`, `access_type` — s'ajouteront en
+ * champs nommés sans toucher à un seul appelant. Une signature positionnelle
+ * aurait figé cette impossibilité à la publication de la 10.0.0.
+ */
+export interface IAuthorizationRequest {
+    /** Valeur anti-CSRF à retrouver au retour (RFC 6749 §10.12). */
+    readonly state: string;
+    /** Secret PKCE (RFC 7636), ou `null` pour un fournisseur qui n'en veut pas. */
+    readonly codeVerifier: string | null;
+    /** Portées demandées ; aucune n'est ajoutée d'office. */
+    readonly scopes: readonly string[];
+    /**
+     * Paramètres versés TELS QUELS dans la requête d'autorisation.
+     *
+     * Un champ dédié plutôt qu'une signature d'index sur tout l'objet : celle-ci
+     * accepterait `stat` pour `state` sans rien dire. Ici, ce qui est nommé est
+     * vérifié par le compilateur, et ce qui passe en supplément est déclaré comme
+     * tel.
+     */
+    readonly additionalParameters?: Readonly<Record<string, string>>;
+}
+/**
+ * Étape 2 — ce qu'on présente au point de jeton.
+ *
+ * Même raison d'être qu'{@link IAuthorizationRequest} : `resource` doit être
+ * répété ici (RFC 8707 §2.2), et rien ne pouvait s'ajouter à une signature
+ * positionnelle.
+ */
+export interface ITokenRequest {
+    /** Code reçu sur l'URL de redirection (RFC 6749 §4.1.2). */
+    readonly code: string;
+    /** Secret PKCE de l'étape 1, ou `null`. */
+    readonly codeVerifier: string | null;
+    /** Paramètres versés TELS QUELS dans le corps de la requête de jeton. */
+    readonly additionalParameters?: Readonly<Record<string, string>>;
+}
+/** Points d'entrée d'un serveur d'autorisation et identité du client. */
+export interface IOAuth2ClientOptions {
+    /** Point d'autorisation (RFC 6749 §3.1) — où l'utilisateur est redirigé. */
+    readonly authorizationEndpoint: string;
+    /** Point de jeton (RFC 6749 §3.2) — où le code est échangé, de serveur à serveur. */
+    readonly tokenEndpoint: string;
+    /** Identifiant client délivré par le fournisseur. */
+    readonly clientId: string;
+    /** Secret client — vide, et seulement vide, quand {@link clientAuthMethod} vaut `"none"`. */
+    readonly clientSecret: string;
+    /**
+     * Comment ce client s'authentifie au point de jeton.
+     *
+     * REQUIS, et volontairement : c'est ce qui remplace la convention implicite
+     * « secret non vide ⇒ Basic ». Un fournisseur doit dire ce qu'il fait, pas le
+     * laisser déduire d'une longueur de chaîne.
+     */
+    readonly clientAuthMethod: OAuth2ClientAuthMethod;
+    /** URL de redirection exacte, telle qu'enregistrée chez le fournisseur (RFC 9700 §4.1). */
+    readonly redirectUri: string;
+    /**
+     * Implémentation de `fetch` à employer — la voie pour éprouver l'échange sans
+     * réseau, plutôt que de remplacer le `fetch` global du processus.
+     */
+    readonly fetch?: typeof globalThis.fetch;
+    /** Délai d'attente de l'échange, en millisecondes. */
+    readonly timeoutMs?: number;
+}
+/**
+ * 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).
+ */
+export declare class OAuth2Client {
+    #private;
+    constructor(options: IOAuth2ClientOptions);
+    /**
+     * 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: IAuthorizationRequest): 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.
+     */
+    validateAuthorizationCode(request: ITokenRequest): Promise<OAuth2Tokens>;
+}