Authenticators — prouver l'identité (session, mot de passe, JWT, clé API)

stable@nodefony/securitymis à jour 2026-07-19

Un authenticator répond à une seule question : « qui es-tu, et peux-tu le prouver ? ». Il ne décide pas des droits (ça, c’est l’autorisation / les voters) — il établit une identité. Le firewall enchaîne les authenticators déclarés par une zone jusqu’à obtenir une preuve valide, sinon il ferme en 401 (Zero Trust). Nodefony en fournit six intégrés, tous ancrés ici sur le code (src/packages/@nodefony/security/nodefony/src/authenticator/).

📍 Documentation › Sécurité › Authenticators

🧠 Le cycle d’un authenticator#

C’est Firewall.#authenticate() (^{firewall.ts:1112}) qui déroule ce cycle pour chaque maillon de la zone, dans l’ordre déclaré. Le succès pose l’identité dans l’ALS ; l’échec remonte au firewall qui pose le 401 et son challenge — l’authenticator, lui, ne touche jamais à la réponse.

📖 Lexique#

Qu’est-ce qu’un authenticator — et quelle faille il ferme#

Un serveur qui expose des données doit distinguer un appelant légitime d’un inconnu. Le faire « à la main » dans chaque contrôleur, c’est garantir qu’un endpoint finira par être oublié — la faille la plus banale et la plus grave.

Nodefony centralise la preuve d’identité dans le firewall : une zone déclare quelles preuves elle accepte, et rien n’atteint le contrôleur sans être passé par là. Chaque authenticator ferme une classe d’attaque précise — détaillées brique par brique dans le catalogue :

• énumération de comptes (messages d’échec uniformes) ;
• brute-force et DoS par hachage (backoff NIST avant tout hash) ;
• algorithm confusion / injection de clé JWT (allowlist + JWKS local) ;
• jeton volé non révocable (denylist jti, PAT opaque révocable) ;
• identité périmée (sujet re-vérifié à chaque requête).

La vision Nodefony — un contrat, un registre, un firewall agnostique#

Le contrat IAuthenticator#

Tout authenticator implémente le même cycle (^{IAuthenticator.ts:18}), ce qui rend le firewall totalement agnostique de la stratégie :

Le registre pluggable#

Les authenticators sont résolus par nom : Firewall.#instantiateAuthenticators() (^{firewall.ts:402}) interroge getAuthenticatorFactory() (^{authenticatorRegistry.ts:59}) — jamais un if (name === "jwt") dans le firewall, qui trahirait la promesse « pluggable ».

• Les cinq builtins HTTP (anonymous, userpassword, session, jwt, apikey) s’enregistrent à l’import du module via registerAuthenticatorFactory() (^{authenticatorRegistry.ts:72-125}) — donc toujours avant le boot.
• Le sixième, firewall-realtime, n’est pas dans le registre : c’est le firewall qui le câble lui-même au handshake WS des zones protégées (Firewall.#wireRealtime(), ^{firewall.ts:268}).
• La fabrique ne fait que construire ; les résolutions de services coûteuses (users, tokenStore, keystore) restent lazy dans l’instance (cold path).
• Un nom inconnu en config = boot fail-closed — #configError posé + log CRITIC (^{firewall.ts:419}) : jamais de zone « protégée » silencieusement ouverte à cause d’une faute de frappe.

🚀 Démarrage rapide#

Une zone, trois preuves — la même API pour le web et les machines#

Dans une app nodefony create app, on déclare quelles preuves une zone accepte — un objet par nom, validé Zod au boot (areas: z.record(...), ^{config.ts:902}) :

// nodefony.config.ts (extrait)
use("@nodefony/security", {
  areas: {
    // Une seule zone, trois preuves : le navigateur (cookie de session),
    // un service (JWT), un script CI (clé API). `mode: "first"` (défaut) :
    // le premier maillon qui reconnaît la requête authentifie.
    api: {
      pattern: "^/api",
      authenticators: ["session", "jwt", "apikey"],
    },
  },
});

❗ Important

Le login est FOURNI : POST /nodefony/security/api/auth/login (body { username, password } → Set-Cookie de session, ID régénéré anti-fixation), avec logout et me (^{SessionAuthController.ts:37-39}). Pas de LoginController à écrire — tes routes ne font que consommer l’identité.

Ce que TU écris : le controller qui consomme l’identité#

// nodefony/controllers/WhoAmIController.ts — complet, compile tel quel
import {
  controller,
  Controller,
  Get,
  IsGranted,
  CurrentUser,
} from "@nodefony/framework";
import type { IUser } from "@nodefony/user";

@controller("/api/v1")
class WhoAmIController extends Controller {
  // Zone `api` : le firewall a DÉJÀ validé une des trois preuves (session,
  // JWT ou clé API) — sinon 401 avant ce code. @IsGranted ajoute le rôle.
  @IsGranted(["ROLE_USER"])
  @Get("/whoami")
  async whoami(@CurrentUser() user: IUser) {
    // La même réponse quelle que soit la preuve présentée par le client.
    return this.renderJson({ identifier: user.identifier, roles: user.roles });
  }
}

export default WhoAmIController;

Ce qu’on observe#

# 1) Sans preuve : Zero Trust → 401 + challenge du premier maillon qui en déclare
curl -si http://localhost:5151/api/v1/whoami | grep -E "^(HTTP|WWW)"
# HTTP/1.1 401 Unauthorized
# WWW-Authenticate: Bearer

# 2) Web — login BFF (compte dev seedé admin/admin) → cookie de session
curl -si -c /tmp/jar -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin"}' \
  http://localhost:5151/nodefony/security/api/auth/login | head -1
# HTTP/1.1 200 OK

# 3) La même route, deux preuves différentes → la même identité
curl -s -b /tmp/jar http://localhost:5151/api/v1/whoami            # session (web)
curl -s -H 'Authorization: Bearer nf_…' \
  http://localhost:5151/api/v1/whoami                              # clé API (CI)
# {"identifier":"admin","roles":["ROLE_NODEFONY_ADMIN", …]}

Requête par requête, qui répond :

🔐 Les six authenticators intégrés#

⚙️ Composer une zone — ordre, mode, cohabitation#

La liste area.authenticators se lit dans l’ordre, déroulée par Firewall.#authenticate() (^{firewall.ts:1112}) selon le mode de la zone (first par défaut, ^{config.ts:87-92}).

Situation 1 — humains ET machines sur la même API (first)#

Ton back-office est appelé par le navigateur des utilisateurs connectés ET par un script CI. Deux preuves différentes, mêmes routes — c’est la config du Démarrage rapide ci-dessus. Deux règles de lecture :

• un maillon dont supports() est faux est simplement sauté en mode first (^{firewall.ts:1128}) ;
• un credential présenté mais invalide échoue immédiatement — l’échec d’authenticate() remonte, jamais de fallback silencieux vers le maillon suivant (^{firewall.ts:1112}). Une clé API révoquée donne un 401 direct, même si un autre maillon aurait pu réussir.
• aucune preuve présentée sur toute la chaîne → handleSecurity() lève l’AuthenticationError Zero Trust (^{firewall.ts:738}).

Situation 2 — le piège de l’ordre (anonymous toujours EN DERNIER)#

Tu veux « identifié si connecté, sinon visiteur » :

authenticators: ["session", "anonymous"],   // ✅ session d'abord
authenticators: ["anonymous", "session"],   // ❌ anonymous accepte TOUT le monde

⚠️ Attention

AnonymousAuthenticator.supports() accepte toutes les requêtes — placé en premier en mode first, il court-circuite la liste : personne n’est jamais identifié, même avec un cookie valide. L’ordre est ta politique.

Situation 3 — empiler les preuves (all)#

En mode all, chaque maillon est obligatoire : supports() faux = 401 immédiat (^{firewall.ts:937}) et le dernier token de la chaîne porte l’identité (^{firewall.ts:973}) — utile pour exiger une preuve de canal (mTLS) et une identité, ou un « sudo mode » session + re-saisie du mot de passe. Scénario complet côté zones : firewall.

Cohabitation JWT + clé API dans une même zone#

Les deux sont des Bearer, mais Nodefony les discrimine sur la forme — un JWT a la structure compacte a.b.c (COMPACT_JWS, ^{JwtAuthenticator.ts:20}), un PAT porte le préfixe nf_ sans point (looksLikeApiKey, ^{ApiKeyAuthenticator.ts:72}). Chaque supports() ne réclame que son format → aucun conflit, aucune double vérification.

Le fil rouge : le message d’échec uniforme#

Les cinq authenticators vérifiants renvoient le même message ("Invalid credentials" / "Invalid token" / "Invalid session") quelle que soit la cause réelle. Ce n’est pas de la paresse : c’est une défense anti-énumération / anti-oracle.

Distinguer « compte inconnu » de « mot de passe faux », ou « token expiré » de « signature invalide », donnerait à un attaquant une sonde. La cause fine part toujours en log d’audit ; le client n’obtient qu’un 401 + son challenge — posé par le firewall, premier maillon de la zone qui en déclare un (Firewall.#setChallenge(), ^{firewall.ts:1191}).

🧩 Ajouter un authenticator maison#

import { registerAuthenticatorFactory } from "@nodefony/security";

registerAuthenticatorFactory("ldap", ({ container, config }) => {
  return new LdapAuthenticator(() => container.get("ldapClient"));
});
// puis en config : areas.<zone>.authenticators = ["ldap", "anonymous"]

À faire au chargement du module (avant le boot). Trois règles, calquées sur les builtins :

• implémenter le contrat IAuthenticator (^{IAuthenticator.ts:23}) — challenge() seulement si un en-tête WWW-Authenticate a du sens pour la stratégie ;
• renvoyer le message uniforme en cas d’échec (la cause fine part en audit) ;
• laisser les résolutions de services lazy dans l’instance — la fabrique ne fait que construire (^{authenticatorRegistry.ts:29-31}).

📜 Normes appliquées#

<!-- prettier-ignore -->

⚡ Performance & mémoire#

• supports() est un test bon marché (en-tête + regex) — et n’est payé que sur zone protégée (le chemin chaud/froid vit dans le firewall).
• Résolutions lazy : le verifier #resolveVerifier est mémoïsé au premier login (^{UserPasswordAuthenticator.ts:105}) ; keystore, tokenStore et users sont résolus du container au premier usage ; jose est importé lazy (^{JwtAuthenticator.ts:96}).
• anonymous : singleton gelé anonymousUser, zéro allocation d’utilisateur (^{AnonymousToken.ts:9}).
• apikey : écriture lastUsedAt coalescée — pas une écriture par requête (^{ApiKeyAuthenticator.ts:127-133}).
• firewall-realtime : zéro lecture base au handshake — réutilise l’ALS (^{FirewallRealtimeAuthenticator.ts:91}).
• Le throttle NIST avant le hash : un 429 ne coûte aucun argon2.

⚠️ Pièges (symptôme → cause → correction)#

<!-- prettier-ignore -->

🧪 Tests & couverture#

Trois familles couvrent la brique — les chiffres exacts vivent dans la carte de l’aperçu (régénérée par gen-counters.mjs depuis vitest, jamais figée ici) :

• unit (security/tests/unit/) : la chaîne + les modes (authenticators), les défenses JWT RFC 8725 (jwt.attack) et le pipeline JWT bout en bout (jwtPipeline), la clé API — flux, service et forme/CRC (apiKeyAuthenticator, apiKeyService, apiKeyFormat), la session (sessionAuthenticator), le backoff NIST (loginThrottler), le step-up 2FA (mfaStepUp) ;
• intégration (serveur réel, @nodefony/http) : le flux clé API de bout en bout (apikey-flow), un JWT autorisé sur WebSocket (ws-isgranted-jwt) ;
• l’émission des jetons (keystore, tokenStore) est couverte sur la page tokens ; les bancs d’attaque transverses (csrf, cors) sur leurs pages.

Couverture : npm run coverage dans @nodefony/security.

🔗 Pour aller plus loin#

• ⬆️ Retour au hub : Sécurité — vue d’ensemble · Toute la documentation

• 🧭 Pages sœurs : Firewall · Jetons

• Le firewall qui enchaîne les authenticators (zones, modes, en-têtes) → firewall

• L’autorisation (voters, rôles, scopes) après l’authentification → authorization

• Émission/révocation des jetons (keystore, tokenStore) → tokens

• Les autres preuves — flux BFF, pas des authenticators de zone : oauth2 · webauthn · totp

• Vue d’ensemble sécurité → index