Référence d'API — nodefony — oauth

stable

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#

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#

function authorizationServerMetadataPath(issuer: string): string

Compose le CHEMIN où PUBLIER ses métadonnées (RFC 8414 §3.1).

authorizeProtectedResource#

function authorizeProtectedResource(authorizationHeader: unknown, policy: IProtectedResourcePolicy, verify: IAccessTokenVerifier): Promise<ProtectedResourceOutcome>

Décide du sort d’une requête d’après l’en-tête Authorization.

buildAuthorizationServerMetadata#

function buildAuthorizationServerMetadata(input: IAuthorizationServerInput): IAuthorizationServerMetadata

Compose le document de métadonnées d’émetteur.

buildBearerChallenge#

function buildBearerChallenge(challenge: IBearerChallenge): string

Compose l’en-tête WWW-Authenticate d’un refus.

buildProtectedResourceMetadata#

function buildProtectedResourceMetadata(input: IProtectedResourceInput): IProtectedResourceMetadata

Compose le document de métadonnées.

canonicalIssuer#

function canonicalIssuer(raw: string): string

Normalise et contrôle un identifiant d’émetteur (RFC 8414 §2).

canonicalResourceUri#

function canonicalResourceUri(raw: string): string

Normalise et contrôle une URI canonique de ressource (RFC 8707 §2).

extractScopes#

function extractScopes(payload: Record<string, unknown>): string[]

Extrait les scopes accordés d’une charge utile de jeton d’accès.

isBackChannelTransportAllowed#

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#

function issuerMetadataUrls(issuer: string): string[]

Compose, dans l’ORDRE NORMATIF, les URL où chercher les métadonnées.

metadataCandidateUrls#

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#

function missingScopes(granted: readonly string[], required: readonly string[]): string[]

L’appelant présente-t-il TOUS les scopes exigés ?

parseDiscoveryUrl#

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#

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#

function protectedResourceMetadataUrl(resource: string): string

Compose l’URL ABSOLUE des métadonnées — celle qui part dans le défi.

validateIssuerMetadata#

function validateIssuerMetadata(document: unknown, expectedIssuer: string, discoveryUrl?: string): IIssuerMetadata

Juge un document de métadonnées reçu.

Constantes (5)#

ACCESS_ACCOUNT_RESOLVER#

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#

const ACCESS_TOKEN_VERIFIER = "accessTokenVerifier"

Nom sous lequel un IAccessTokenVerifier se pose dans le conteneur.

BearerError#

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#

const JWKS_PATH = "/.well-known/jwks.json"

Chemin conventionnel où Nodefony publie son jeu de clés publiques.

ROLES_WITHIN#

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#

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#

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<Record<string, unknown>> — Claims VÉRIFIÉS du jeton — signature, émetteur, audience et validité contrôlés par le vérificateur.

IAuthorizationServerInput#

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#

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#

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#

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#

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#

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#

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#

type BearerErrorCode = (typeof BearerError)[keyof typeof BearerError]

Un des codes de BearerError.

IAccessAccountResolver#

type IAccessAccountResolver = (principal: IAccessPrincipal) => Promise<IAccessAccount | null>

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#

type IAccessTokenVerifier = (token: string, audience: string) => Promise<IAccessPrincipal | null>

Ce qui sait valider un jeton — implémenté ailleurs, jamais ici.

IRolesWithin#

type IRolesWithin = (owner: string, target: string) => Promise<RolesWithinVerdict>

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#

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#

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