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

stable

Documentation › Référence d’API › @nodefony/security › authenticator

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" — 15 symboles.

Classes (6)#

AnonymousAuthenticator#

class AnonymousAuthenticator implements IAuthenticator

Acceptation EXPLICITE de l’anonymat dans une zone — le seul authenticator autorisé à produire un token non authentifié sans déclencher le Zero Trust.

• readonly name = "anonymous" — Nom logique (référencé dans area.authenticators).
• supports(): boolean — Peut-on extraire un credential de cette requête ?
• createToken(): Promise<IToken> — Construit un token NON authentifié depuis la requête (extraction credential).
• authenticate(token: IToken): Promise<IToken> — Toujours un succès — accepter l’anonymat ne vérifie rien.
• onSuccess(_context: ContextType, _token: IToken): Promise<void> — Hook succès — pose le token (cookie JWT, log audit S1…).
• onFailure(_context: ContextType, _error: Error): Promise<void> — Hook échec — log audit, throttling (J2)… Le 401 + challenge sont posés par le firewall.

ApiKeyAuthenticator#

class ApiKeyAuthenticator implements IAuthenticator

Authentification par clé API personnelle (PAT, P6.12) présentée en Authorization: Bearer <prefix>_… (RFC 6750). Réservée API/CI/scripts — le web utilise la session BFF.

• readonly name = "apikey" — Nom logique (référencé dans area.authenticators).
• constructor(container: Container, runtime: IApiKeyAuthenticatorRuntime)
• supports(context: ContextType): boolean — La requête porte-t-elle un Authorization: Bearer <prefix>_… ?
• createToken(context: ContextType): Promise<IToken> — Extrait la valeur brute (non vérifiée) → portée par un UserToken type "apikey".
• authenticate(token: IToken): Promise<IToken> — Valide la clé (forme+CRC, puis store) et résout le sujet — ou lève un 401 au message uniforme.
• onSuccess(context: ContextType, token: IToken): Promise<void> — Inscrit la trace d’usage de la clé — horodatage, IP et agent.
• onFailure(_context: ContextType, _error: Error): Promise<void> — Slot audit (P6.14) — le 401 + challenge sont posés par le firewall.
• challenge(): string — Challenge RFC 6750/7235 posé par le firewall sur les 401 de la zone.

ExternalJwtAuthenticator#

class ExternalJwtAuthenticator implements IAuthenticator

Authentification par jeton d’accès émis par un serveur d’autorisation TIERS (Keycloak, Auth0, Entra, ou l’émetteur d’une flotte d’agents).

• readonly name = "external-jwt" — Nom logique (référencé dans area.authenticators).
• constructor(container: Container, options: IExternalJwtAuthenticatorOptions)
• supports(context: ContextType): boolean — La requête porte-t-elle un jeton se réclamant d’un émetteur de confiance ?
• createToken(context: ContextType): Promise<IToken> — Extrait le jeton brut ET l’audience de la zone.
• authenticate(token: IToken): Promise<IToken> — Vérifie le jeton auprès de son émetteur, puis rattache le sujet.
• onSuccess(_context: ContextType, _token: IToken): Promise<void> — Slot audit — le firewall enregistre déjà succès et échec par zone.
• onFailure(_context: ContextType, _error: Error): Promise<void> — Slot audit — le 401 et le défi sont posés par le firewall.
• challenge(area?: ISecuredArea): string — Défi RFC 6750 + pointeur RFC 9728, posé par le firewall sur les 401.
• validateArea(area: ISecuredArea): void — Refuse une zone sans ressource — au boot, pas à la première requête.

JwtAuthenticator#

class JwtAuthenticator implements IAuthenticator

Authentification par JWT Bearer (RFC 6750) — réservée API service↔service / agents (le web utilise la session BFF). Vérifie un access token EdDSA signé par le IJwtKeystore du serveur.

• readonly name = "jwt" — Nom logique (référencé dans area.authenticators).
• constructor(container: Container, runtime: IJwtRuntime)
• supports(context: ContextType): boolean — La requête porte-t-elle un Authorization: Bearer <jws> émis par NOUS ?
• createToken(context: ContextType): Promise<IToken> — Extrait le token brut (non vérifié) → porté par un UserToken type "jwt".
• authenticate(token: IToken): Promise<IToken> — Vérifie la signature + les claims du JWT, applique la révocation et résout le sujet — ou lève un 401 au message uniforme.
• verifyForResource(raw: string, audience: string): Promise<IAccessPrincipal | null> — Vérifie un jeton émis par CETTE application pour une ressource protégée nommée par l’appelant — la porte d’une ressource (RFC 8707), pas une zone.
• resolveAccount(principal: IAccessPrincipal): Promise<IUser | null> — Recharge le compte que désigne un principal établi par verifyForResource — pour une ressource protégée qui fait agir un outil au nom du propriétaire du jeton.
• onSuccess(_context: ContextType, _token: IToken): Promise<void> — Slot audit (J4b).
• onFailure(_context: ContextType, _error: Error): Promise<void> — Slot audit (J4b) — le 401 + challenge sont posés par le firewall.
• challenge(): string — Challenge RFC 6750/7235 posé par le firewall sur les 401 de la zone.

SessionAuthenticator#

class SessionAuthenticator implements IAuthenticator

Authentification par session serveur (cookie opaque, modèle BFF) — la preuve des requêtes qui SUIVENT le login (AuthFlow.login, qui a déjà posé l’identifiant dans le blob et régénéré l’ID anti-fixation).

• readonly name = "session" — Nom logique (référencé dans area.authenticators).
• constructor(resolveProvider: () => IUserProvider)
• validateArea(area: ISecuredArea): void — Refuse une zone déclarée SANS REGISTRE — au boot, pas à la première requête.
• supports(context: ContextType): boolean — La requête porte-t-elle une session reprise avec un utilisateur ?
• createToken(context: ContextType): Promise<IToken> — Extrait l’identifiant du blob de session (jamais de secret en jeu).
• authenticate(token: IToken): Promise<IToken> — Re-résout l’identifiant de session en utilisateur vivant et promeut le token.
• onSuccess(context: ContextType, token: IToken): Promise<void> — Pose l’identifiant sur le contexte : la persistance de session du pipeline (saveSession) lie le blob au principal courant (string attendu).
• onFailure(_context: ContextType, _error: Error): Promise<void> — Slot audit (P6.14).

UserPasswordAuthenticator#

class UserPasswordAuthenticator implements IAuthenticator

Authentification par identifiant + mot de passe — schéma HTTP Basic (RFC 7617) : Authorization: Basic base64(identifiant:motdepasse), charset UTF-8, split au PREMIER : (le mot de passe peut en contenir).

• readonly name = "userpassword" — Nom logique (référencé dans area.authenticators).
• constructor(resolveVerifier: () => IPasswordVerifier, throttler?: LoginThrottler | null, transport?: CredentialTransportPolicy | null)
• supports(context: ContextType): boolean — La requête porte-t-elle un en-tête Authorization: Basic ... ?
• createToken(context: ContextType): Promise<IToken> — Décode l’enveloppe Basic — un contenu malformé donne un credential vide (échec uniforme).
• authenticate(token: IToken): Promise<IToken> — Vérifie le credential via le verifier ou lève un 401 au message uniforme.
• onSuccess(_context: ContextType, _token: IToken): Promise<void> — Slot J3 (session BFF au login) — rien à poser pour du Basic pur.
• onFailure(_context: ContextType, _error: Error): Promise<void> — Slot J3+ (audit events).
• challenge(): string — Challenge RFC 9110 §11 posé par le firewall sur les 401 de la zone.

Fonctions (4)#

getAuthenticatorFactory#

function getAuthenticatorFactory(name: string): AuthenticatorFactory

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

listAuthenticatorFactories#

function listAuthenticatorFactories(): string[]

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

peekIssuer#

function peekIssuer(raw: string): string | null

Rend le claim iss d’un JWS compact, sans vérifier quoi que ce soit.

registerAuthenticatorFactory#

function registerAuthenticatorFactory(name: string, factory: AuthenticatorFactory): void

Enregistre (ou remplace) la fabrique d’un authenticator. Appelé par les builtins au chargement du module, et par les plugins pour les leurs (LDAP, SSO maison…).

Interfaces (3)#

IApiKeyAuthenticatorRuntime#

interface IApiKeyAuthenticatorRuntime

Paramètres effectifs d’un ApiKeyAuthenticator (dérivés de la config).

• prefix: string — Marque des clés (apiKeys.prefix) — discrimine un PAT d’un JWT.
• lastUsedThrottleS: number — Coalescence d’écriture lastUsedAt (s) — 0 = écrit à chaque usage.

IAuthenticatorFactoryContext#

interface IAuthenticatorFactoryContext

Contexte passé à une fabrique : tout ce dont un authenticator peut avoir besoin pour se construire. La fabrique ne fait QUE construire — résolutions de services coûteuses en lazy à l’intérieur de l’instance (cold path).

• readonly container: Container — Container DI — résolution de services (users, sessions…).
• readonly config: ISecurityConfig — Config sécurité validée + gelée (sections jwt, passkeys…).

IExternalJwtAuthenticatorOptions#

interface IExternalJwtAuthenticatorOptions

Ce que la fabrique doit fournir à l’authenticator.

• issuers: readonly IExternalIssuerBinding[] — Émetteurs de confiance, et leur politique de sujet.
• subjectPolicy: ExternalSubjectPolicy — Politique de rattachement du sujet à un utilisateur local.
• ephemeralRoles: readonly string[] — Rôles accordés en mode ephemeral.
• oauthProviders?: readonly { name: string; issuer: string; roleMapping?: IProviderRoleMapping | null; }[] — Fournisseurs de CONNEXION (oauth2.providers) qui déclarent leur émetteur.

Types (2)#

AuthenticatorFactory#

type AuthenticatorFactory = (ctx: IAuthenticatorFactoryContext) => IAuthenticator

Fabrique d’un authenticator pour un nom donné.

ExternalSubjectPolicy#

type ExternalSubjectPolicy = "require" | "ephemeral"

Comment le sujet d’un jeton devient un utilisateur de cette application.

← Toutes les références d’API