---
title: "Référence d'API — @nodefony/security — authenticator"
source: docs/api/security/authenticator.md
url: https://nodefony.github.io/nodefony-core/docs/api/security/authenticator/
---


[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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
function getAuthenticatorFactory(name: string): AuthenticatorFactory
```

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

#### `listAuthenticatorFactories`

```ts
function listAuthenticatorFactories(): string[]
```

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

#### `peekIssuer`

```ts
function peekIssuer(raw: string): string | null
```

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

#### `registerAuthenticatorFactory`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
type AuthenticatorFactory = (ctx: IAuthenticatorFactoryContext) => IAuthenticator
```

Fabrique d'un authenticator pour un nom donné.

#### `ExternalSubjectPolicy`

```ts
type ExternalSubjectPolicy = "require" | "ephemeral"
```

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

---

[← Toutes les références d'API](../../)