--- title: "Référence d'API — nodefony — oauth" source: docs/api/core/oauth.md url: https://nodefony.github.io/nodefony-core/docs/api/core/oauth/ --- [Documentation](../../../) › [Référence d'API](../../) › [`nodefony`](../) › oauth > Générée depuis les déclarations de types publiées de `nodefony` **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` `import { … } from "nodefony"` — 37 symboles. ### Classes (1) #### `IssuerMismatchError` ```ts class IssuerMismatchError extends Error ``` Refus d'un document de métadonnées qui se déclare d'un AUTRE émetteur que celui interrogé (RFC 8414 §3.3, OpenID Connect Discovery §4.3). - `readonly declaredIssuer: string` — Émetteur que le document déclare, sous sa forme canonique. - `readonly expectedIssuer: string` — Émetteur interrogé, tel que la configuration l'écrit. - `constructor(declared: string, expected: string)` ### Fonctions (16) #### `authorizationServerMetadataPath` ```ts function authorizationServerMetadataPath(issuer: string): string ``` Compose le CHEMIN où PUBLIER ses métadonnées (RFC 8414 §3.1). #### `authorizeProtectedResource` ```ts function authorizeProtectedResource(authorizationHeader: unknown, policy: IProtectedResourcePolicy, verify: IAccessTokenVerifier): Promise ``` Décide du sort d'une requête d'après l'en-tête `Authorization`. #### `buildAuthorizationServerMetadata` ```ts function buildAuthorizationServerMetadata(input: IAuthorizationServerInput): IAuthorizationServerMetadata ``` Compose le document de métadonnées d'émetteur. #### `buildBearerChallenge` ```ts function buildBearerChallenge(challenge: IBearerChallenge): string ``` Compose l'en-tête `WWW-Authenticate` d'un refus. #### `buildProtectedResourceMetadata` ```ts function buildProtectedResourceMetadata(input: IProtectedResourceInput): IProtectedResourceMetadata ``` Compose le document de métadonnées. #### `canonicalIssuer` ```ts function canonicalIssuer(raw: string): string ``` Normalise et contrôle un identifiant d'émetteur (RFC 8414 §2). #### `canonicalResourceUri` ```ts function canonicalResourceUri(raw: string): string ``` Normalise et contrôle une URI canonique de ressource (RFC 8707 §2). #### `extractScopes` ```ts function extractScopes(payload: Record): string[] ``` Extrait les scopes accordés d'une charge utile de jeton d'accès. #### `isBackChannelTransportAllowed` ```ts function isBackChannelTransportAllowed(endpoint: URL, discoveryUrl?: string): boolean ``` Dit si un point d'entrée DE SERVEUR À SERVEUR (jeton, jeu de clés) publié dans un document de métadonnées peut être appelé par son transport. #### `issuerMetadataUrls` ```ts function issuerMetadataUrls(issuer: string): string[] ``` Compose, dans l'ORDRE NORMATIF, les URL où chercher les métadonnées. #### `metadataCandidateUrls` ```ts function metadataCandidateUrls(issuer: string, discoveryUrl?: string): string[] ``` Les URL où lire les métadonnées d'un émetteur : l'adresse déclarée SEULE quand il y en a une, sinon les points bien connus dans l'ordre normatif. #### `missingScopes` ```ts function missingScopes(granted: readonly string[], required: readonly string[]): string[] ``` L'appelant présente-t-il TOUS les scopes exigés ? #### `parseDiscoveryUrl` ```ts function parseDiscoveryUrl(value: string): URL ``` Valide une adresse de découverte déclarée (`discoveryUrl`) — l'endroit où LIRE le document de métadonnées quand il diffère de l'émetteur. #### `protectedResourceMetadataPath` ```ts function protectedResourceMetadataPath(resource: string): string ``` Compose le CHEMIN où publier les métadonnées, à partir de l'URI de la ressource (RFC 9728 §3.1). #### `protectedResourceMetadataUrl` ```ts function protectedResourceMetadataUrl(resource: string): string ``` Compose l'URL ABSOLUE des métadonnées — celle qui part dans le défi. #### `validateIssuerMetadata` ```ts function validateIssuerMetadata(document: unknown, expectedIssuer: string, discoveryUrl?: string): IIssuerMetadata ``` Juge un document de métadonnées reçu. ### Constantes (5) #### `ACCESS_ACCOUNT_RESOLVER` ```ts const ACCESS_ACCOUNT_RESOLVER = "accessAccountResolver" ``` Nom sous lequel un `IAccessAccountResolver` se pose dans le conteneur — même règle que `ACCESS_TOKEN_VERIFIER` : importé des deux côtés, jamais recopié. #### `ACCESS_TOKEN_VERIFIER` ```ts const ACCESS_TOKEN_VERIFIER = "accessTokenVerifier" ``` Nom sous lequel un `IAccessTokenVerifier` se pose dans le conteneur. #### `BearerError` ```ts const BearerError: { readonly INVALID_REQUEST: "invalid_request"; readonly INVALID_TOKEN: "invalid_token"; readonly INSUFFICIENT_SCOPE: "insufficient_scope"; } ``` Codes d'erreur d'un porteur — RFC 6750 §3.1. #### `JWKS_PATH` ```ts const JWKS_PATH = "/.well-known/jwks.json" ``` Chemin conventionnel où Nodefony publie son jeu de clés publiques. #### `ROLES_WITHIN` ```ts const ROLES_WITHIN = "rolesWithin" ``` Nom sous lequel un `IRolesWithin` se pose dans le conteneur — importé des deux côtés, jamais recopié. ### Interfaces (9) #### `IAccessAccount` ```ts interface IAccessAccount ``` Le compte de l'application qu'un principal désigne, prêt à être posé dans la bulle de requête (`RequestContext.run`). - `readonly token: unknown` — Jeton d'authentification du compte — celui que le pare-feu poserait dans une zone (`RequestContext.token`). - `readonly user: IRequestUser` — L'utilisateur du compte, au contrat de `RequestContext.getAuthenticatedUser()`. #### `IAccessPrincipal` ```ts interface IAccessPrincipal ``` Ce qu'une vérification de jeton RÉUSSIE établit. - `issuer: string` — Émetteur VÉRIFIÉ du jeton (`iss`), sous sa forme canonique. - `subject?: string` — Sujet du jeton (`sub`) — pour l'audit, et pour borner ce qu'on rend. - `scopes: readonly string[]` — Scopes réellement accordés. - `expiresAt?: number` — Expiration du jeton (`exp`), en **secondes** epoch — RFC 7519 §4.1.4. - `issuedAt?: number` — Émission du jeton (`iat`), en **secondes** epoch — révocation en masse. - `tokenId?: string` — Identifiant unique du jeton (`jti`) — révocation CIBLÉE avant terme. - `claims?: Readonly>` — Claims VÉRIFIÉS du jeton — signature, émetteur, audience et validité contrôlés par le vérificateur. #### `IAuthorizationServerInput` ```ts interface IAuthorizationServerInput ``` De quoi composer le document — ce que l'application, seule, connaît. - `issuer: string` — Identifiant d'émetteur, tel qu'écrit en configuration. - `jwksPath?: string` — Chemin (ou URL absolue) du jeu de clés. #### `IAuthorizationServerMetadata` ```ts interface IAuthorizationServerMetadata ``` Le document que Nodefony PUBLIE — RFC 8414 §2, réduit à ce qui est vrai. - `issuer: string` — `issuer` — REQUIRED §2, https sans requête ni fragment. - `jwks_uri: string` — `jwks_uri` — OPTIONAL §2, mais c'est la raison d'être du document ici. - `response_types_supported: string[]` — `response_types_supported` — REQUIRED §2, **vide et c'est exact**. - `grant_types_supported: string[]` — `grant_types_supported` — OPTIONAL §2, mais **obligatoire de fait**. #### `IBearerChallenge` ```ts interface IBearerChallenge ``` De quoi composer un défi `WWW-Authenticate`. - `resourceMetadataUrl: string` — URL du document de métadonnées — RFC 9728 §5.1. - `scopes?: readonly string[]` — Scopes nécessaires à l'opération en cours. - `error?: BearerErrorCode` — Code d'erreur, ABSENT quand la requête ne portait aucune information. - `description?: string` — Explication lisible, jamais une cause fine (anti-oracle). #### `IIssuerMetadata` ```ts interface IIssuerMetadata ``` Ce qu'on lit d'un document de métadonnées — deux champs, pas un de plus. - `issuer: string` — Identifiant de l'émetteur, tel que le document se le donne. - `jwksUri: string` — Où récupérer les clés publiques de signature. #### `IProtectedResourceInput` ```ts interface IProtectedResourceInput ``` De quoi composer le document — ce que l'application, seule, connaît. - `resource: string` — URI canonique de la ressource, telle qu'un client l'atteint. - `authorizationServers: readonly string[]` — Au moins un serveur d'autorisation — sinon le document ne mène nulle part. - `scopesSupported?: readonly string[]` — Scopes compris par la ressource (facultatif, mais recommandé). - `resourceName?: string` — Nom lisible par un humain. - `resourceDocumentation?: string` — URL d'une documentation destinée à un humain. #### `IProtectedResourceMetadata` ```ts interface IProtectedResourceMetadata ``` Métadonnées publiées d'une ressource protégée — RFC 9728 §2. - `resource: string` — URI canonique de la ressource — l'audience que les jetons doivent porter. - `authorization_servers: string[]` — Serveurs d'autorisation capables d'émettre un jeton pour elle. - `scopes_supported?: string[]` — Scopes que la ressource comprend — guide le client (RECOMMENDED). - `bearer_methods_supported?: string[]` — Comment présenter le jeton. - `resource_name?: string` — Nom lisible, affiché par le client pendant le consentement. - `resource_documentation?: string` — Où un humain lit ce que fait cette ressource. #### `IProtectedResourcePolicy` ```ts interface IProtectedResourcePolicy ``` Politique appliquée à une requête vers une ressource protégée. - `resource: string` — URI canonique de la ressource — l'audience PUBLIÉE, et la première essayée. - `acceptedResources?: readonly string[]` — Autres URI sous lesquelles CETTE MÊME ressource est joignable, et dont les jetons sont acceptés. - `metadataUrl: string` — URL du document de métadonnées, citée dans chaque refus. - `scopes?: readonly string[]` — Scopes annoncés au client quand on le refuse. - `allowAnonymous: boolean` — Servir une requête sans jeton comme anonyme, au lieu de la refuser. ### Types (6) #### `BearerErrorCode` ```ts type BearerErrorCode = (typeof BearerError)[keyof typeof BearerError] ``` Un des codes de `BearerError`. #### `IAccessAccountResolver` ```ts type IAccessAccountResolver = (principal: IAccessPrincipal) => Promise ``` Ce qui retrouve le compte qu'un principal désigne — implémenté par le module de sécurité, qui porte les comptes, leur liaison et le rattachement des sujets externes. #### `IAccessTokenVerifier` ```ts type IAccessTokenVerifier = (token: string, audience: string) => Promise ``` Ce qui sait valider un jeton — implémenté ailleurs, jamais ici. #### `IRolesWithin` ```ts type IRolesWithin = (owner: string, target: string) => Promise ``` La règle qui autorise un compte à en JOUER un autre : les rôles de `target`, hiérarchie comprise, doivent tous être atteints par ceux de `owner` — jouer un compte ne monte jamais en droits. Implémentée par le module de sécurité, qui porte les comptes et la hiérarchie des rôles. #### `ProtectedResourceOutcome` ```ts type ProtectedResourceOutcome = { outcome: "anonymous"; rejected?: true; } | { outcome: "authenticated"; principal: IAccessPrincipal; } | { outcome: "challenge"; status: 400 | 401; wwwAuthenticate: string; } | { outcome: "unverifiable"; why?: string; } ``` Verdict rendu à la porte — à elle de le traduire en réponse. #### `RolesWithinVerdict` ```ts type RolesWithinVerdict = { ok: true; } | { ok: false; reason: string; } ``` Verdict d'un `IRolesWithin` : l'accord, ou la raison du refus. --- [← Toutes les références d'API](../../)