Référence d'API — @nodefony/security — oauth

stable

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#

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<OAuth2Tokens> — É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#

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#

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<string, unknown> — Corps JSON brut de la réponse — donne accès aux extensions du fournisseur.
• constructor(data: Record<string, unknown>)
• 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#

function createCodeChallenge(codeVerifier: string): string

Calcule le code_challenge de la méthode S256 (RFC 7636 §4.2) : BASE64URL(SHA256(ASCII(code_verifier))).

createDiscoveredOidcProvider#

function createDiscoveredOidcProvider(name: string, ctx: IOAuthProviderContext, options?: IDiscoveredOidcOptions): Promise<IOAuthProvider>

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#

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#

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#

function diagnoseOAuthProvider(input: IOAuthDiagnosisInput): Promise<IOAuthDiagnosis>

Diagnostique un fournisseur OAuth sans connexion humaine.

discoverAuthorizationServer#

function discoverAuthorizationServer(rawIssuer: string, options?: IDiscoveryOptions): Promise<IDiscoveredAuthorizationServer>

Interroge un serveur d’autorisation et rend ses points d’entrée.

generateCodeVerifier#

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#

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#

function getOAuthProviderFactory(name: string): OAuthProviderFactory

Fabrique d’un fournisseur par nom, ou undefined si inconnu.

listOAuthProviders#

function listOAuthProviders(): string[]

Noms enregistrés (validation boot, introspection Studio, tests).

oauthProviderRequiresIssuer#

function oauthProviderRequiresIssuer(name: string): boolean

true si le fournisseur nommé a déclaré exiger un émetteur en configuration.

readLogoutTokenClaims#

function readLogoutTokenClaims(issuer: string, payload: Record<string, unknown>): 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#

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#

function requestClientCredentialsToken(request: IClientCredentialsRequest): Promise<OAuth2Tokens>

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#

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<OAuth2ClientAuthMethod, "none"> — 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#

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#

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#

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#

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#

interface IOAuthDiagnosis

Le diagnostic d’un fournisseur.

• readonly provider: string — Nom du fournisseur (oauth2.providers.<name>).
• readonly ok: boolean — true si aucune sonde n’a échoué.
• readonly checks: readonly IOAuthCheck[]

IOAuthDiagnosisInput#

interface IOAuthDiagnosisInput

Ce que le diagnostic d’un fournisseur doit savoir.

• readonly name: string — Nom du fournisseur.
• readonly build: () => IOAuthProvider | Promise<IOAuthProvider> — 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#

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#

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#

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<OAuth2Tokens>

IOidcProviderOptions#

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<object> — 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<string, unknown>; } | 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#

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#

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#

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#

type OAuthProviderFactory = (ctx: IOAuthProviderContext) => IOAuthProvider | Promise<IOAuthProvider>

Fabrique d’un fournisseur OAuth pour un nom donné.

← Toutes les références d’API