--- title: "Référence d'API — @nodefony/security — oauth" source: docs/api/security/oauth.md url: https://nodefony.github.io/nodefony-core/docs/api/security/oauth/ --- [Documentation](../../../) › [Référence d'API](../../) › [`@nodefony/security`](../) › oauth > Générée depuis les déclarations de types publiées de `@nodefony/security` **10.0.0-beta.5** : exactement ce que reçoit une application qui l'installe. Cette page n'existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code. ## `@nodefony/security` `import { … } from "@nodefony/security"` — 32 symboles. ### Classes (3) #### `OAuth2Client` ```ts class OAuth2Client ``` Client d'un serveur d'autorisation donné : construit l'URL d'autorisation puis échange le code contre des jetons. - `constructor(options: IOAuth2ClientOptions)` - `createAuthorizationURL(request: IAuthorizationRequest): URL` — Construit l'URL d'autorisation (RFC 6749 §4.1.1). - `validateAuthorizationCode(request: ITokenRequest): Promise` — Échange le code d'autorisation contre des jetons (RFC 6749 §4.1.3), de serveur à serveur — le secret client ne quitte jamais ce canal. #### `OAuth2RequestError` ```ts class OAuth2RequestError extends Error ``` 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. - `readonly code: string` — Code normalisé (`invalid_grant`, `invalid_client`, ...) — RFC 6749 §5.2. - `readonly description: string | null` — Description lisible fournie par le serveur, ou `null`. - `readonly status: number | null` — Statut HTTP de la réponse, ou `null` s'il n'est pas connu. - `constructor(code: string, description: string | null, status?: number | null)` #### `OAuth2Tokens` ```ts class OAuth2Tokens ``` 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. - `readonly data: Record` — Corps JSON brut de la réponse — donne accès aux extensions du fournisseur. - `constructor(data: Record)` - `accessToken(): string` — Jeton d'accès (RFC 6749 §5.1). - `tokenType(): string` — Type du jeton d'accès — `Bearer` en pratique (RFC 6750). - `idToken(): string` — Jeton d'identité OIDC (OpenID Connect Core §3.1.3.3). - `hasRefreshToken(): boolean` — `true` si le serveur a émis un jeton de rafraîchissement. - `refreshToken(): string` — Jeton de rafraîchissement (RFC 6749 §1.5). - `accessTokenExpiresInSeconds(): number` — Durée de vie restante du jeton d'accès, en secondes. - `accessTokenExpiresAt(): Date` — Instant d'expiration du jeton d'accès, dérivé de `expires_in`. - `hasScopes(): boolean` — `true` si le serveur a annoncé les portées effectivement accordées. - `scopes(): string[]` — Portées accordées, telles que le serveur les a annoncées (RFC 6749 §3.3). ### Fonctions (14) #### `createCodeChallenge` ```ts function createCodeChallenge(codeVerifier: string): string ``` Calcule le `code_challenge` de la méthode **S256** (RFC 7636 §4.2) : `BASE64URL(SHA256(ASCII(code_verifier)))`. #### `createDiscoveredOidcProvider` ```ts function createDiscoveredOidcProvider(name: string, ctx: IOAuthProviderContext, options?: IDiscoveredOidcOptions): Promise ``` 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. #### `createGithubProvider` ```ts function createGithubProvider(ctx: IOAuthProviderContext): IOAuthProvider ``` 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` (`issuerPolicy = null`) : la défense anti-CSRF repose sur le `state`. #### `createOidcProvider` ```ts function createOidcProvider(opts: IOidcProviderOptions): IOAuthProvider ``` Fabrique un `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). #### `diagnoseOAuthProvider` ```ts function diagnoseOAuthProvider(input: IOAuthDiagnosisInput): Promise ``` Diagnostique un fournisseur OAuth sans connexion humaine. #### `discoverAuthorizationServer` ```ts function discoverAuthorizationServer(rawIssuer: string, options?: IDiscoveryOptions): Promise ``` Interroge un serveur d'autorisation et rend ses points d'entrée. #### `generateCodeVerifier` ```ts function generateCodeVerifier(): string ``` Tire un `code_verifier` PKCE (RFC 7636 §4.1) — 43 caractères de l'alphabet `unreserved`, porteurs de 256 bits d'entropie. #### `generateState` ```ts function generateState(): string ``` Tire un `state` anti-CSRF (RFC 6749 §10.12, RFC 9700 §4.7) — 256 bits issus du générateur cryptographique du système. #### `getOAuthProviderFactory` ```ts function getOAuthProviderFactory(name: string): OAuthProviderFactory ``` Fabrique d'un fournisseur par nom, ou `undefined` si inconnu. #### `listOAuthProviders` ```ts function listOAuthProviders(): string[] ``` Noms enregistrés (validation boot, introspection Studio, tests). #### `oauthProviderRequiresIssuer` ```ts function oauthProviderRequiresIssuer(name: string): boolean ``` `true` si le fournisseur nommé a déclaré exiger un émetteur en configuration. #### `readLogoutTokenClaims` ```ts function readLogoutTokenClaims(issuer: string, payload: Record): ILogoutTokenClaims | null ``` Lit ce qu'un jeton de déconnexion DÉSIGNE, une fois sa signature vérifiée — les points 5 à 7 de la validation (OpenID Connect Back-Channel Logout 1.0 §2.6) : `sub` ou `sid` présent, `events` qui le déclare jeton de déconnexion, AUCUN `nonce`. #### `registerOAuthProvider` ```ts function registerOAuthProvider(name: string, factory: OAuthProviderFactory, registration?: IOAuthProviderRegistration): void ``` Enregistre (ou remplace) la fabrique d'un fournisseur OAuth. Appelée par les builtins au chargement, et par une application pour ses fournisseurs. #### `requestClientCredentialsToken` ```ts function requestClientCredentialsToken(request: IClientCredentialsRequest): Promise ``` Obtient un jeton d'accès pour un programme, par le flux `client_credentials` (RFC 6749 §4.4), auprès d'un émetteur découvert (RFC 8414). ### Interfaces (11) #### `IClientCredentialsRequest` ```ts interface IClientCredentialsRequest ``` Ce qu'un programme présente pour obtenir un jeton EN SON PROPRE NOM (RFC 6749 §4.4) — un script, un service partenaire, un agent : aucun utilisateur, aucun navigateur. - `readonly issuer: string` — Identifiant de l'émetteur (claim `iss`), en https. - `readonly clientId: string` — Identifiant du client confidentiel (ex. - `readonly clientSecret: string` — Secret du client — obligatoire : ce flux n'existe que pour un client confidentiel. - `readonly clientAuthMethod?: Exclude` — Comment le client s'authentifie. - `readonly scopes?: readonly string[]` — Portées demandées ; aucune par défaut (le serveur applique les siennes). - `readonly resource?: string` — Ressource visée (RFC 8707 §2) — l'audience que le jeton doit porter. - `readonly discoveryUrl?: string` — Adresse où lire les métadonnées, si elle diffère de l'émetteur (cf `IDiscoveryOptions`). - `readonly fetch?: typeof globalThis.fetch` — Implémentation de `fetch` (banc sans réseau). - `readonly timeoutMs?: number` — Délai d'attente de CHAQUE requête (découverte, puis jeton), en millisecondes. #### `IDiscoveredAuthorizationServer` ```ts interface IDiscoveredAuthorizationServer ``` Points d'entrée retenus d'un serveur d'autorisation — le sous-ensemble dont le flux *Authorization Code* a besoin (RFC 8414 §2). - `readonly issuer: string` — Émetteur canonique, vérifié identique à celui interrogé (RFC 8414 §3.3). - `readonly authorizationEndpoint: string` — Point d'autorisation (RFC 6749 §3.1). - `readonly tokenEndpoint: string` — Point de jeton (RFC 6749 §3.2). - `readonly jwksUri: string` — Jeu de clés de signature — la porte d'une future vérification d'ID token. - `readonly codeChallengeMethodsSupported: string[] | null` — Méthodes PKCE annoncées (RFC 7636), ou `null` si le serveur n'en publie aucune. - `readonly issParameterSupported: boolean` — `true` si le serveur ANNONCE émettre le paramètre `iss` dans sa réponse d'autorisation (RFC 9207 §2.3). - `readonly endSessionEndpoint: string | null` — Point de déconnexion initiée par l'application (`end_session_endpoint`, OpenID Connect RP-Initiated Logout 1.0 §2.1), ou `null` si le serveur n'en publie aucun : la déconnexion reste alors locale. - `readonly idTokenSigningAlgValuesSupported: string[] | null` — Algorithmes de signature des ID tokens annoncés (`id_token_signing_alg_values_supported`, OpenID Connect Discovery §3), ou `null` si le serveur n'en publie aucun. #### `IDiscoveryOptions` ```ts interface IDiscoveryOptions ``` Réglages de la découverte — l'injection de `fetch` est la voie pour éprouver sans TLS. - `readonly fetch?: typeof globalThis.fetch` — Implémentation de `fetch` à employer. - `readonly timeoutMs?: number` — Délai d'attente par URL candidate, en millisecondes. - `readonly discoveryUrl?: string` — Adresse où LIRE le document, quand elle diffère de l'émetteur — le service interne d'un cluster (`http://keycloak.sso:8080/realms/x/.well-known/openid-configuration`). #### `IOAuth2ClientOptions` ```ts interface IOAuth2ClientOptions ``` Points d'entrée d'un serveur d'autorisation et identité du client. - `readonly authorizationEndpoint: string` — Point d'autorisation (RFC 6749 §3.1) — où l'utilisateur est redirigé. - `readonly tokenEndpoint: string` — Point de jeton (RFC 6749 §3.2) — où le code est échangé, de serveur à serveur. - `readonly clientId: string` — Identifiant client délivré par le fournisseur. - `readonly clientSecret: string` — Secret client — vide, et seulement vide, quand `clientAuthMethod` vaut `"none"`. - `readonly clientAuthMethod: OAuth2ClientAuthMethod` — Comment ce client s'authentifie au point de jeton. - `readonly redirectUri: string` — URL de redirection exacte, telle qu'enregistrée chez le fournisseur (RFC 9700 §4.1). - `readonly fetch?: typeof globalThis.fetch` — 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 timeoutMs?: number` — Délai d'attente de l'échange, en millisecondes. #### `IOAuthCheck` ```ts interface IOAuthCheck ``` Le résultat d'une sonde. - `readonly name: OAuthCheckName` - `readonly status: OAuthCheckStatus` - `readonly kind?: OAuthFailureKind` — Présent si et seulement si `status === "failed"`. - `readonly message: string` — Phrase destinée à l'opérateur : le constat, puis le geste. #### `IOAuthDiagnosis` ```ts interface IOAuthDiagnosis ``` Le diagnostic d'un fournisseur. - `readonly provider: string` — Nom du fournisseur (`oauth2.providers.`). - `readonly ok: boolean` — `true` si aucune sonde n'a échoué. - `readonly checks: readonly IOAuthCheck[]` #### `IOAuthDiagnosisInput` ```ts interface IOAuthDiagnosisInput ``` Ce que le diagnostic d'un fournisseur doit savoir. - `readonly name: string` — Nom du fournisseur. - `readonly build: () => IOAuthProvider | Promise` — Construit le fournisseur comme pour un login — découverte comprise. - `readonly clientId: string` — Identifiant du client, tel que configuré. - `readonly redirectUri: string` — URL de retour configurée — celle que le fournisseur doit connaître. - `readonly clientAuthMethod?: OAuth2ClientAuthMethod` — Méthode d'authentification déclarée ; `"none"` = client public. - `readonly scopes?: readonly string[]` — Portées configurées ; vides = celles du fournisseur. - `readonly fetch?: typeof globalThis.fetch` — Transport de la sonde d'autorisation. - `readonly timeoutMs?: number` — Délai d'attente de la sonde d'autorisation, en millisecondes. - `readonly pageCheck?: ((html: string) => IOAuthCheck | null)` — Juge la page de connexion que le point d'autorisation sert (ses premiers octets). #### `IOAuthProviderContext` ```ts interface IOAuthProviderContext ``` Contexte de construction d'un fournisseur (secrets et URL issus de la config). - `readonly clientId: string` — Identifiant client (config, issu de l'env de l'app). - `readonly clientSecret: string` — Secret client (config) — jamais loggé ; vide pour un client public. - `readonly clientAuthMethod?: OAuth2ClientAuthMethod` — Comment le client s'authentifie au point de jeton, quand l'application le DÉCLARE ; `undefined` laisse le fournisseur poser son défaut. - `readonly redirectUri: string` — URL de callback exacte (RFC 9700). - `readonly issuer?: string` — Émetteur du fournisseur OIDC (Keycloak : URL du realm, ex. - `readonly discoveryUrl?: string` — Adresse où lire les métadonnées de l'émetteur quand elle diffère de lui (service interne d'un cluster) — cf `IDiscoveryOptions.discoveryUrl`. #### `IOAuthProviderRegistration` ```ts interface IOAuthProviderRegistration ``` Ce qu'une fabrique EXIGE de la configuration — lu au démarrage, avant que le moindre utilisateur ne clique. - `readonly requiresIssuer?: boolean` — `true` si le fournisseur ne peut se construire sans `issuer` dans sa configuration — typiquement un serveur OpenID Connect découvert par son émetteur. #### `IOidcPkceClient` ```ts interface IOidcPkceClient ``` Client d'un fournisseur **OIDC avec PKCE** — surface structurelle que `OAuth2Client` remplit, et qu'un test peut remplacer par un double sans réseau. - `createAuthorizationURL(request: IAuthorizationRequest): URL` - `validateAuthorizationCode(request: ITokenRequest): Promise` #### `IOidcProviderOptions` ```ts interface IOidcProviderOptions ``` Paramètres d'un fournisseur OIDC générique. - `readonly name: string` — Nom du fournisseur (`"google"`, `"keycloak"`...) — porté dans le profil. - `readonly client: IOidcPkceClient` — Client déjà construit sur les points d'entrée du fournisseur. - `readonly issuer: string` — Émetteur attendu (claim `iss`, anti-mix-up RFC 9207). - `readonly issParameterSupported?: boolean` — `true` si l'émetteur ANNONCE le paramètre `iss` — son absence devient alors un refus. - `readonly clientId: string` — Identifiant client — l'audience que l'ID token DOIT porter. - `readonly decodeIdToken: (idToken: string) => object | Promise` — Décodage des claims de l'ID token — synchrone ou non. - `readonly defaultScopes?: string[]` — Scopes par défaut si la config n'en précise aucun. - `readonly endSessionEndpoint?: string | null` — Point de déconnexion du fournisseur (`end_session_endpoint`). - `readonly verifyLogoutTokenSignature?: (logoutToken: string) => Promise<{ issuer: string; payload: Record; } | null>` — Vérifie la SIGNATURE d'un jeton de déconnexion (émetteur, audience, algorithme, `exp`/`iat`) et rend ses claims, ou `null` s'il est refusé ; lève sur une panne. ### Types (4) #### `OAuthCheckName` ```ts type OAuthCheckName = "discovery" | "authorization" | "token" | "theme" ``` Les sondes, dans leur ordre. `theme` n'existe que si l'appelant fournit un `IOAuthDiagnosisInput.pageCheck` ET que la page d'autorisation s'y prête (Keycloak). #### `OAuthCheckStatus` ```ts type OAuthCheckStatus = "ok" | "failed" | "inconclusive" | "skipped" ``` Verdict d'une sonde. `inconclusive` = le serveur a répondu quelque chose qu'on ne sait pas lire — ni un quitus, ni un manquement ; `skipped` = une sonde précédente a rendu celle-ci impossible. #### `OAuthFailureKind` ```ts type OAuthFailureKind = "issuer-mismatch" | "discovery-failed" | "redirect-uri-rejected" | "authorization-refused" | "authorization-unreachable" | "secret-rejected" | "client-rejected" | "token-refused" | "token-unreachable" | "login-theme-mismatch" ``` La cause d'un échec, lisible par une machine (rapport, console, tests). #### `OAuthProviderFactory` ```ts type OAuthProviderFactory = (ctx: IOAuthProviderContext) => IOAuthProvider | Promise ``` Fabrique d'un fournisseur OAuth pour un nom donné. --- [← Toutes les références d'API](../../)