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

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

@@ -1,4 +1,26 @@
 import { Service, Module } from "nodefony";
+/**
+ * Libellé affichable d'un fournisseur, quand sa configuration n'en donne pas.
+ *
+ * Un écran de connexion ne doit JAMAIS montrer un identifiant technique brut :
+ * `mon-idp-interne` sur un bouton ne dit rien à qui doit cliquer. À défaut de
+ * marque connue, le nom de la clé de configuration est ce qui s'en rapproche le
+ * plus — mais rendu lisible : séparateurs en espaces, initiales en capitales,
+ * sigles préservés.
+ *
+ * Fonction PURE, donc éprouvable sans boot ni réseau.
+ *
+ * @param name - nom du fournisseur, tel qu'il est écrit dans la configuration
+ * @returns le libellé à afficher sur le bouton
+ */
+export declare function oauthDisplayLabel(name: string): string;
+/** Un fournisseur tel que l'écran de connexion doit le présenter. */
+export interface IOAuthDisplayProvider {
+    /** Nom technique — celui que l'URL `/authorize` attend. */
+    readonly name: string;
+    /** Libellé du bouton : celui de la config, sinon dérivé du nom. */
+    readonly label: string;
+}
 /** Données à porter en session entre `authorize` et `callback` (anti-replay). */
 export interface IOAuthAuthorization {
     /** URL d'autorisation vers laquelle rediriger l'utilisateur. */
@@ -9,8 +31,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 +39,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
@@ -33,8 +55,26 @@ declare class OAuth2Service extends Service {
     constructor(module: Module);
     /** `true` si le social login est opérationnel (activé + boot OK). */
     isEnabled(): boolean;
-    /** Noms des fournisseurs configurés ET connus du registre (UI : boutons à afficher). */
+    /**
+     * Noms des fournisseurs OPÉRATIONNELS — configurés ET connus du registre.
+     *
+     * 🔴 C'est la **garde d'autorisation** : `/authorize` refuse en 404 tout nom
+     * absent de cette liste. Elle répond donc à « ce flux peut-il s'ouvrir ? »,
+     * jamais à « ce bouton doit-il s'afficher ? » — pour l'écran, voir
+     * {@link listDisplayProviders}. Confondre les deux ferait d'un masquage une
+     * désactivation, et couperait les bancs qui exercent une fixture masquée.
+     */
     listProviders(): string[];
+    /**
+     * Fournisseurs à MONTRER sur l'écran de connexion, libellés compris.
+     *
+     * Rend TOUT fournisseur opérationnel — y compris ceux dont le framework ne
+     * connaît pas la marque, qui sont précisément ceux qu'une application
+     * enregistre elle-même. Le seul retrait possible est explicite et se lit dans
+     * la configuration du fournisseur (`hidden: true`), à côté de la raison qui
+     * l'a motivé ; il ne désactive rien.
+     */
+    listDisplayProviders(): IOAuthDisplayProvider[];
     /**
      * Redirections post-login (succès / échec) — lues par le controller.
      * Surcharge PAR FOURNISSEUR si fournie, sinon valeur globale, sinon défaut.

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>;
+}

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

@@ -1,39 +1,56 @@
-import type * as Arctic from "arctic";
 import type { IOAuthProvider } from "../../contracts/IOAuthProvider.js";
+import type { OAuth2ClientAuthMethod } from "./oauth2Client.js";
 /**
  * Registre de **fabriques de fournisseurs OAuth** — résout un nom configuré
  * (`oauth2.providers.<name>`) vers un {@link IOAuthProvider}, SANS coupler le
  * cœur à un fournisseur en dur.
  *
  * Convention-frère : `tokenStoreRegistry`, `authenticatorRegistry`,
- * `webAuthnCredentialStoreRegistry`. Les builtins (`google`, `github`) couvrent
- * les deux archétypes (OIDC+PKCE / OAuth simple) ; une application enregistre les
- * ~50 autres fournisseurs `arctic` (Microsoft, Apple, Discord...) ou un
- * fournisseur maison via {@link registerOAuthProvider}, sans éditer le core.
+ * `webAuthnCredentialStoreRegistry`.
  *
- * @remarks `arctic` n'est ici qu'un **type** : l'instance runtime, chargée
- * paresseusement par `OAuth2Service` au premier login, est passée à la fabrique
- * via {@link IOAuthProviderContext.arctic} — zéro import runtime statique.
+ * @remarks Aucun fournisseur n'a de code propre : un serveur OpenID Connect publie
+ * ses points d'entrée (RFC 8414 / OpenID Connect Discovery), donc son seul émetteur
+ * suffit à le décrire. Enregistrer Microsoft Entra, Auth0, Okta ou Authentik tient
+ * en une ligne dans l'application :
+ *
+ * ```ts
+ * registerOAuthProvider("azure", (ctx) => createDiscoveredOidcProvider("azure", ctx));
+ * ```
  */
-/** Contexte de construction d'un fournisseur (lib arctic chargée + secrets de config). */
+/** Contexte de construction d'un fournisseur (secrets et URL issus de la config). */
 export interface IOAuthProviderContext {
-    /** Module `arctic` chargé paresseusement (les classes de fournisseurs). */
-    readonly arctic: typeof Arctic;
     /** Identifiant client (config, issu de l'env de l'app). */
     readonly clientId: string;
-    /** Secret client (config) — jamais loggé. */
+    /** Secret client (config) — jamais loggé ; vide pour un client public. */
     readonly clientSecret: string;
+    /**
+     * Comment le client s'authentifie au point de jeton, quand l'application le
+     * DÉCLARE ; `undefined` laisse le fournisseur poser son défaut.
+     *
+     * Elle remonte jusqu'ici parce qu'elle appartient au serveur d'autorisation,
+     * pas au code du fournisseur : un même Keycloak peut exiger `client_secret_post`
+     * là où un autre veut Basic, et ils l'annoncent dans leurs métadonnées. Sans ce
+     * champ, la forme serait ouverte dans le client et INATTEIGNABLE depuis une
+     * application — donc absente.
+     */
+    readonly clientAuthMethod?: OAuth2ClientAuthMethod;
     /** URL de callback exacte (RFC 9700). */
     readonly redirectUri: string;
     /**
-     * Émetteur/realm des fournisseurs OIDC self-hosted (Keycloak : URL du realm,
-     * ex. `https://kc.example/realms/app`) — `undefined` pour les fournisseurs à
-     * endpoints fixes (Google, GitHub).
+     * Émetteur du fournisseur OIDC (Keycloak : URL du realm, ex.
+     * `https://kc.example/realms/app`) — `undefined` pour les fournisseurs dont
+     * l'émetteur est connu d'avance (Google) ou qui n'en publient pas (GitHub).
      */
     readonly issuer?: string;
 }
-/** Fabrique d'un fournisseur OAuth pour un nom donné. */
-export type OAuthProviderFactory = (ctx: IOAuthProviderContext) => IOAuthProvider;
+/**
+ * Fabrique d'un fournisseur OAuth pour un nom donné.
+ *
+ * @remarks Elle peut être **asynchrone** : découvrir les points d'entrée d'un
+ * émetteur est une opération de construction, faite une seule fois par processus
+ * (le service mémoïse le fournisseur résolu).
+ */
+export type OAuthProviderFactory = (ctx: IOAuthProviderContext) => IOAuthProvider | Promise<IOAuthProvider>;
 /**
  * Enregistre (ou remplace) la fabrique d'un fournisseur OAuth. Appelée par les
  * builtins au chargement, et par une application pour ses fournisseurs.

package/dist/types/nodefony/src/oauth/providers/github.d.ts

@@ -4,6 +4,6 @@ import type { IOAuthProviderContext } from "../oauthProviderRegistry.js";
  * 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`.
  */
 export declare function createGithubProvider(ctx: IOAuthProviderContext): IOAuthProvider;

package/dist/types/nodefony/src/oauth/providers/oidc.d.ts

@@ -1,35 +1,60 @@
-import type { OAuth2Tokens } from "arctic";
 import type { IOAuthProvider } from "../../../contracts/IOAuthProvider.js";
+import type { IOAuthProviderContext } from "../oauthProviderRegistry.js";
+import { type IAuthorizationRequest, type ITokenRequest, type OAuth2Tokens } from "../oauth2Client.js";
+import { type IDiscoveryOptions } from "../metadata.js";
 /**
- * Client `arctic` minimal d'un fournisseur **OIDC avec PKCE** — surface
- * structurelle commune à `Google`, `MicrosoftEntraId`, `Auth0`, `Okta`,
- * `KeyCloak`... (une instance arctic de ces classes est assignable telle quelle).
+ * Client d'un fournisseur **OIDC avec PKCE** — surface structurelle que
+ * {@link OAuth2Client} remplit, et qu'un test peut remplacer par un double sans
+ * réseau.
  */
 export interface IOidcPkceClient {
-    createAuthorizationURL(state: string, codeVerifier: string, scopes: string[]): URL;
-    validateAuthorizationCode(code: string, codeVerifier: string): Promise<OAuth2Tokens>;
+    createAuthorizationURL(request: IAuthorizationRequest): URL;
+    validateAuthorizationCode(request: ITokenRequest): Promise<OAuth2Tokens>;
 }
 /** Paramètres d'un fournisseur OIDC générique. */
 export interface IOidcProviderOptions {
-    /** Nom du fournisseur (`"google"`, `"microsoft"`...) — porté dans le profil. */
+    /** Nom du fournisseur (`"google"`, `"keycloak"`...) — porté dans le profil. */
     readonly name: string;
-    /** Instance `arctic` (déjà construite avec les secrets). */
+    /** Client déjà construit sur les points d'entrée du fournisseur. */
     readonly client: IOidcPkceClient;
     /** Émetteur attendu (claim `iss`, anti-mix-up RFC 9207). */
     readonly issuer: string;
-    /** `arctic.decodeIdToken` (injecté — arctic est chargé paresseusement). */
-    readonly decodeIdToken: (idToken: string) => object;
+    /**
+     * `true` si l'émetteur ANNONCE le paramètre `iss` — son absence devient alors
+     * un refus. Défaut `false` : on ne peut pas exiger ce qui n'a pas été promis.
+     */
+    readonly issParameterSupported?: boolean;
+    /** Identifiant client — l'audience que l'ID token DOIT porter. */
+    readonly clientId: string;
+    /** Décodage des claims de l'ID token — synchrone ou non. */
+    readonly decodeIdToken: (idToken: string) => object | Promise<object>;
     /** Scopes par défaut si la config n'en précise aucun. */
     readonly defaultScopes?: string[];
 }
 /**
  * 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.
  */
 export declare function createOidcProvider(opts: IOidcProviderOptions): IOAuthProvider;
+/** Réglages d'un fournisseur OIDC découvert. */
+export interface IDiscoveredOidcOptions extends IDiscoveryOptions {
+    /** Émetteur ; à défaut, celui de la configuration de l'application. */
+    readonly issuer?: string;
+}
+/**
+ * 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.
+ */
+export declare function createDiscoveredOidcProvider(name: string, ctx: IOAuthProviderContext, options?: IDiscoveredOidcOptions): Promise<IOAuthProvider>;