Tokens — émission, clés (keystore), rotation et révocation

stable@nodefony/securitymis à jour 2026-10-05

Les authenticators vérifient des jetons ; cette page décrit leur face émission : comment Nodefony signe un access token JWT, gère la clé (keystore Ed25519 + JWKS), fait tourner les refresh tokens avec détection de rejeu (RFC 9700), et révoque — au-dessus d’un ITokenStore pluggable (memory/drizzle/mongoose/redis) désormais paginé pour l’admin. Ancré sur src/packages/@nodefony/security/nodefony/service/tokenService.ts et nodefony/src/token/.

📍 Documentation › Sécurité › Jetons

🧠 Le modèle mental — émission, rotation, révocation#

📖 Lexique#

Qu’est-ce que ce système résout — la faille#

Un JWT est auto-porté : le serveur peut le vérifier sans état. Génial pour la scalabilité, dangereux pour la révocation — un jeton volé reste valide jusqu’à son expiration si rien ne le suit côté serveur. Deux attaques concrètes :

• le vol de refresh token — l’attaquant le rejoue pour obtenir des access frais indéfiniment ;
• l’absence de révocation — bannir un compte ne coupe pas ses jetons déjà émis.

Nodefony répond par un store de vérité côté serveur (denylist jti + invalidBefore + rotation avec détection de rejeu) et une gestion de clé qui ne génère jamais de secret en clair « par défaut » en prod.

La vision Nodefony — un service propriétaire, des endpoints minces#

TokenService est propriétaire du store et du keystore : à TokenService.#build() (tokenService.ts#TokenService.#build), si jwt.enabled ou apiKeys.enabled, il résout le store pluggable, pose tokenStore au container (tokenService.ts#TokenService.#build) puis crée le keystore et pose jwtKeystore (tokenService.ts#TokenService.#build) — consommés par le JwtAuthenticator et les endpoints. Il arme un gc via GcScheduler (timer unref + jitter de phase pour étaler les balayages entre pods, tokenService.ts#TokenService.#build).

Les endpoints HTTP sont des adaptateurs minces portés par @nodefony/framework, couplés par nom de service via le contrat structurel ITokenIssuer — framework n’importe jamais security (TokenAuthController.ts#ITokenIssuer).

Constat clé de cohérence : iss/aud/ttl sont dérivés une seule fois par resolveJwtRuntime() (jwtRuntime.ts#resolveJwtRuntime) et partagés entre l’émetteur et le vérificateur — une divergence ferait tout rejeter. Fonction pure : les deux côtés obtiennent la même valeur sans la partager par référence. issuer omis → "nodefony" (jwtRuntime.ts#resolveJwtRuntime), à surcharger en prod.

Être DÉCOUVRABLE — publier ses clés (RFC 8414)#

Tant que Nodefony émet et vérifie ses propres jetons, iss n’est qu’une chaîne comparée à elle-même. Dès qu’un tiers doit valider une signature émise ici (une autre application Nodefony, un agent, un service), il lui faut deux documents publics :

Les deux sont montées par @nodefony/framework (IssuerMetadataController.ts) uniquement si TokenService.publishedIssuer() répond — soit jwt.enabled, jwt.jwks, et jwt.issuer écrit sous forme d’URL https. Sinon : aucune route (404) et un avertissement au boot.

🔴 L’URL ne se devine pas. Derrière un relais (HAProxy, ingress, CDN), Host et X-Forwarded-* viennent de la requête, donc du client : un document dérivé de l’en-tête ferait servir, par le vrai serveur, l’identité d’un attaquant — et empoisonnerait tout cache mutualisé. L’exploitant l’écrit, comme il écrit son domaine (NF_JWT_ISSUER dans env.ts).

use("@nodefony/security", { jwt: { issuer: ctx.env.NF_JWT_ISSUER } });

Le document publié n’annonce aucun flux d’autorisation (response_types_supported: [], grant_types_supported: []) : Nodefony n’est pas un serveur d’autorisation OAuth 2.1, elle rend seulement ses signatures vérifiables. Omettre grant_types_supported annoncerait ["authorization_code", "implicit"] par défaut (RFC 8414 §2) — deux flux inexistants.

🚀 Démarrage rapide#

Les endpoints d’émission sont FOURNIS#

Dans une app nodefony create app, dès que le module security est chargé avec jwt.enabled (défaut), le framework monte deux routes (mountTokenAuthRoutes(), TokenAuthController.ts#mountTokenAuthRoutes) :

• POST /nodefony/security/api/token — body {username, password, scope?} → couple access/refresh ;
• POST /nodefony/security/api/token/refresh — body {refresh_token} → rotation.

❗ Important

Ces routes n’existent que si @nodefony/security est chargé — sinon 404, zéro surface (framework/index.ts#Framework.onKernelReady). Module chargé mais JWT désactivé : elles existent et répondent 503 Token issuance unavailable (TokenAuthController.ts#TokenAuthController.token). Elles sont bypassFirewall: true (TokenAuthController.ts#mountTokenAuthRoutes) : elles SONT le mécanisme d’émission — protégées, obtenir un token exigerait d’être déjà authentifié (deadlock). Le JWT part en réponse JSON (Bearer), jamais en cookie ni en URL.

La config : une zone protégée par jwt + une clé qui survit au redémarrage#

// nodefony/config/security.ts — la zone API machine + la source de clé
import type { ConfigContext } from "nodefony";
import type { ISecurityConfigInput } from "@nodefony/security";
import type { env } from "../../env";

export const securityConfig = (ctx: ConfigContext<typeof env>) =>
  ({
    jwt: {
      // dev : persiste la clé Ed25519 sous var/ (sinon clé ÉPHÉMÈRE + warning).
      // prod : NF_JWT_KEYSET, la même clé sur tous les pods — voir la section keystore.
      keystore: {
        keySetJson: ctx.env.NF_JWT_KEYSET,
        dir: "var/keys",
      },
    },
    areas: {
      // Le firewall vérifie le Bearer JWT sur CHAQUE requête de la zone.
      api: { pattern: "^/api/v1", authenticators: ["jwt"] },
    },
  }) satisfies ISecurityConfigInput;

Ce que TU écris : le controller scopé#

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

@controller("/api/v1/orders")
class OrdersController extends Controller {
  // Zone `api` : le firewall a déjà validé le JWT (signature, exp, aud/iss,
  // denylist, sujet actif). @RequireScope borne ce que la CLÉ a le droit de
  // faire — un token émis sans `orders:read` reçoit 403, même sujet valide.
  @RequireScope("orders:read")
  @Get("/list")
  async list(@CurrentUser() user: IUser) {
    return this.renderJson({ subject: user.identifier, orders: [] });
  }
}

export default OrdersController;

Ce qu’on observe#

# 0) Un compte (mot de passe demandé MASQUÉ — jamais en dur dans un script)
npx nodefony security:user:add ci-bot

# 1) Grant : credential → couple access/refresh (réponse RFC 6749 §5.1)
curl -s -H 'Content-Type: application/json' \
  -d "{\"username\":\"ci-bot\",\"password\":\"$NF_PASS\",\"scope\":\"orders:read\"}" \
  http://localhost:5151/nodefony/security/api/token
# {"access_token":"eyJ…","refresh_token":"nfr_…","token_type":"Bearer",
#  "expires_in":900,"scope":"orders:read"}

# 2) L'access token en Bearer → 200 (zone api, scope vérifié)
curl -s -H "Authorization: Bearer $ACCESS" \
  http://localhost:5151/api/v1/orders/list
# {"subject":"ci-bot","orders":[]}

# 3) Rotation : le refresh → NOUVEAU couple (l'ancien refresh est révoqué)
curl -s -H 'Content-Type: application/json' \
  -d "{\"refresh_token\":\"$REFRESH\"}" \
  http://localhost:5151/nodefony/security/api/token/refresh

# 4) Rejouer l'ANCIEN refresh → 401 {"error":"invalid_grant"} + famille coupée

Erreurs mappées par duck-typing dans #renderAuthError() (TokenAuthController.ts#TokenAuthController.#renderAuthError) : 401 message uniforme invalid_grant (anti-énumération), 429 avec Retry-After du throttler NIST. Émission indisponible (JWT désactivé, store absent) → 503 isEnabled() (TokenAuthController.ts#ITokenIssuer.isEnabled).

🏗️ Architecture interne — la vie d’un couple access/refresh#

Émission (grant M2M/CLI)#

issueForCredentials() (tokenService.ts#TokenService.issueForCredentials) vérifie l’identifiant/mot de passe via le service users, avec le throttling NIST partagé — ThrottledError avant tout hachage (tokenService.ts#TokenService.issueForCredentials). Chaque tentative échouée est auditée login.failure/login.throttled par #auditGrant() (tokenService.ts#TokenService.#auditGrant). Puis issueTokens() (tokenService.ts#TokenService.issueTokens) produit :

• un access token : JWT signé EdDSA, en-tête typ:"at+jwt" + kid, claims iss/sub/aud/exp (15 min) + jti — #signAccess() (tokenService.ts#TokenService.#signAccess) ;
• un refresh token : secret opaque haute entropie nfr_<32 octets base64url>, stocké haché sha256 (le clair n’existe qu’en réponse, jamais au repos) — #buildRefresh() (tokenService.ts#TokenService.#buildRefresh).

La réponse suit RFC 6749 §5.1 — ITokenResponse (tokenService.ts#ITokenResponse). Tout succès est audité token.issued via recordAudit avec le tokenId corrélable (tokenService.ts#TokenService.runGc).

Rotation & détection de rejeu (RFC 9700 §4.14)#

refresh() (tokenService.ts#TokenService.refresh) est le cœur défensif, dans l’ordre :

1. Lookup par hash — findByHash, refus uniforme si inconnu/mauvais type (tokenService.ts#TokenService.refresh).
2. Détection de rejeu : refresh déjà révoqué re-présenté → revokeFamily coupe toute la famille + audit token.reuse_detected, signal d’attaque fort (tokenService.ts#TokenService.refresh).
3. Expiration expiresAt vérifiée (tokenService.ts#TokenService.refresh).
4. Sujet revérifié — compte disparu/inactif/verrouillé rejeté sans attendre l’exp, #resolveUserForRefresh() (tokenService.ts#TokenService.#resolveUserForRefresh).
5. Downscoping : les scopes du nouveau couple sont ceux de l’ancien, jamais plus — et ils sont REJUGÉS sur les rôles du compte relu (grantableScopes, règle d’administration) : un rôle retiré retire son scope au prochain renouvellement (tokenService.ts#TokenService.#grantableScopes).
6. Rotation : nouveau refresh (même famille), l’ancien chaîné replacedBy + révoqué "rotated" (tokenService.ts#TokenService.refresh). Si rotateRefresh est désactivé, l’access est réémis et le refresh courant reste valide (tokenService.ts#TokenService.refresh).

Mise en situation — ton refresh token a été volé#

Besoin vécu : le refresh d’un poste compromis est exfiltré. Rotation active (défaut) — voici ce que chacun vit, requête par requête :

Si le voleur joue en premier, la rotation lui répond normalement (le serveur ne peut pas encore le distinguer) — mais dès que le légitime rejoue son vieux refresh, le rejeu est détecté et le voleur perd aussi son couple. Dans les deux ordres, l’attaque est bornée à une fenêtre courte et la victime est déconnectée (signal visible) au lieu d’un vol silencieux indéfini.

🔐 Le keystore Ed25519 — la clé ne fuit pas, pas de secret « par défaut » en prod#

JwtKeystore.#load() résout la source de clé par priorité (JwtKeystore.ts#JwtKeystore.#load), pensée pour ne jamais auto-générer une clé en clair silencieusement en prod :

1. env — keySetJson (NF_JWT_KEYSET dans une application générée) : la MÊME clé pour tous les process qui servent l’application (JwtKeystore.ts#JwtKeystore.#load).
2. fichier — dir/keyset.json, généré si absent, en mode 600, par une création exclusive (createSecretExclusive, secretFile.ts#createSecretExclusive) : quand plusieurs workers de nodefony cluster démarrent ensemble, un seul crée la clé et les autres relisent la sienne (JwtKeystore.ts#JwtKeystore.#load). Source de développement, ou d’un serveur unique à disque persistant.
3. mémoire — aucune source → clé éphémère, propre au process (JwtKeystore.ts#JwtKeystore.#load). En développement : un WARNING au premier jeton. En production, un process qui sert refuse de démarrer (§ suivant).

Le JWKS servi par getPublicJWKS() est public — JwtKeystore.ts#JwtKeystore.getPublicJWKS. La composante privée d en est retirée à l’import, par liste BLANCHE de paramètres (#importKeyset(), JwtKeystore.ts#JwtKeystore.#importKeyset, RFC 8037/7517). C’est ce JWKS qu’utilise le vérificateur local (createLocalJWKSet, JwtAuthenticator.ts#JwtAuthenticator.#ensureGetKey), jamais une clé venue du jeton. Le chargement est mémoïsé — #ensureLoaded() (JwtKeystore.ts#JwtKeystore.#ensureLoaded).

Plusieurs pods ou workers — UNE clé pour tous#

Chaque jeton porte le kid de la clé qui l’a signé. Deux process qui ont chacun la leur refusent les jetons l’un de l’autre : derrière un répartiteur, l’utilisateur est déconnecté au hasard (401), et tout redémarrage invalide les jetons en vol.

En production, un process qui SERT sans source partagée refuse de démarrer (#requireSharedSigningKey, tokenService.ts#TokenService.#requireSharedSigningKey), avec le motif et les trois issues dans le journal. Une commande de console (orm:migrate, security:user:add) n’est pas concernée : elle ne signe aucun jeton. Sous nodefony cluster, un worker refusé ne se relance pas — le master arrête le cluster et sort en 78 (ClusterManager.ts#ClusterManager.#onExit), le code d’une faute de configuration.

Le déploiement, de bout en bout :

# 1. Générer la valeur UNE fois par environnement (staging ≠ production)
npx nodefony security:secrets --jwt-keyset > keyset.json

# 2. La ranger dans le gestionnaire de secrets — ici un Secret Kubernetes
kubectl create secret generic app-jwt --from-file=NF_JWT_KEYSET=keyset.json
rm keyset.json   # elle porte la clé PRIVÉE : aucun exemplaire ne traîne

# 3. L'injecter dans CHAQUE pod (extrait du Deployment)
#   env:
#     - name: NF_JWT_KEYSET
#       valueFrom: { secretKeyRef: { name: app-jwt, key: NF_JWT_KEYSET } }

Le câblage, que le gabarit d’application écrit déjà :

jwt: {
  keystore: {
    keySetJson: ctx.env.NF_JWT_KEYSET, // présente : l'emporte partout
    dir: ctx.isProd ? undefined : "var/keys", // développement
  },
},

• Jamais dans un fichier du poste, jamais dans git : en développement la clé vit dans var/keys/ ; une clé privée de production sur un poste n’apporte que le risque de fuir.
• Dans un fichier .env (Docker Compose env_file), l’entourer de quotes simples : NF_JWT_KEYSET='{"active":"…","keys":[…]}'.
• Valeur illisible : la configuration security est refusée au démarrage, le chemin jwt.keystore.keySetJson nommé, la valeur jamais recopiée dans le message.
• Rotation : la valeur est STABLE — la remplacer refuse les jetons en vol. Ajouter la nouvelle clé au tableau keys, la désigner dans active, garder l’ancienne le temps que ses jetons expirent (accessTtlS, refreshTtlS), puis la retirer.

🧩 Le store pluggable — durable par défaut, jamais de faux durable silencieux#

Le contrat et l’enregistrement#

Le tokenStore héberge trois structures : les records (refresh + PAT), la denylist jti et le seuil invalidBefore par porteur (ITokenStore.ts). Les backends s’enregistrent par fabrique — registerTokenStore() (tokenStoreRegistry.ts#registerTokenStore) : les adapters lourds importent import type { ITokenStore } (effacé à la compilation), zéro couplage runtime.

Sa résolution au boot (tokenService.ts#TokenService.#build) suit la doctrine store:"auto" du framework :

• auto (défaut) → suit l’infra database déclarée via resolveAutoStore — borné aux backends réellement enregistrés, repli memory annoncé (tokenService.ts#TokenService.#build) ;
• store explicite inconnu → en prod, boot avorté (fail-loud) ; en dev, brique désactivée et annoncée avec la liste listTokenStores() (tokenService.ts#TokenService.#build) — jamais de fallback memory silencieux pour du durable ;
• store memory en prod → WARNING nommant l’impact : denylist/refresh/clés API per-pod et volatils, révocation non partagée (tokenService.ts#TokenService.#build).

La décision (configuré → résolu, raison) est publiée au kernel par registerStoreResolution() (tokenService.ts#TokenService.#build) — visible dans Studio.

Mise en situation — quel store pour quelle app ?#

Les backends (catalogue)#

Le record — une seule table pour PAT et refresh#

IAccessTokenRecord (ITokenStore.ts#IAccessTokenRecord) est single-table : un même schéma porte PAT et refresh, champs non pertinents à null, horodatages epoch ms (ITokenStore.ts#IAccessTokenRecord). Deux constats de design :

• subjectId est une référence logique souple, PAS une FK SQL : porteur polymorphe (user/service), store multi-backend, découplage des modules — intégrité assurée à l’usage (ITokenStore.ts#IAccessTokenRecord.subjectId) ;
• slots prêts sans migration : resources (permissions fine-grained façon GitHub) et cnf (sender-constrained DPoP/mTLS) (ITokenStore.ts#IAccessTokenRecord.cnf).

Les colonnes par dialecte vivent dans la doc de chaque adapter (règle anti-triple-vérité).

Lister pour l’admin — pagination native#

• listPage() ne matérialise jamais plus d’une page (ITokenStore.ts#ITokenStore.listPage) — capacité par backend : offset + total (SQL/Mongo/mémoire) ou curseur (nextCursor, Redis).
• countTokens() donne le total ; Redis répond -1 (ITokenStore.ts#ITokenStore.countTokens).
• Filtres portables ITokenListQuery : subjectId, kind, revoked (ITokenStore.ts#ITokenListQuery) — prédicat partagé matchesTokenQuery() (MemoryTokenStore.ts#matchesTokenQuery).
• listAll() reste réservé au dump d’incident cross-porteur, cold-path admin (ITokenStore.ts#ITokenStore.listAll).
• Consommateur type : le data plane des clés API — ApiKeyService.listPagePat() (apiKeys.ts#ApiKeyService.listPagePat), jamais un listAll matérialisé.

Révoquer — trois portées#

• Un access avant son exp : denylist denyJti()/isJtiDenied() (ITokenStore.ts#ITokenStore.isJtiDenied).
• Un refresh/PAT : revoke() idempotent, revokeFamily() pour la chaîne de rotation (ITokenStore.ts#ITokenStore.revokeFamily).
• Tout un porteur (logout global, ban) : seuil revokeAllForSubject() — tout access dont iat < invalidBefore est rejeté (ITokenStore.ts#ITokenStore) ; le seuil est monotone, deux logouts successifs ne le reculent pas (MemoryTokenStore.ts#MemoryTokenStore.revokeAllForSubject).

La maintenance (gc)#

Le gc() du store purge la denylist expirée, les records à terme, les PAT révoqués au-delà de la rétention (ITokenStore.ts#ITokenStore.gc). Orchestré par le GcScheduler du service ; runGc() reste public pour un futur worker cron — poser alors gcIntervalS: 0 (tokenService.ts#TokenService.getPublicJWKS).

💡 Astuce

Un refresh révoqué par rotation n’est PAS purgé tout de suite : il est conservé jusqu’à son expiresAt — c’est la fenêtre de détection de rejeu — puis tombe au gc, #isPurgeable() (MemoryTokenStore.ts#MemoryTokenStore.#isPurgeable). Un store local (memory) est par-process : seul SON process peut le purger → ne déléguez le gc au cron QUE pour un store partagé.

⚙️ Configuration#

Tables dérivées du schéma Zod — jwtSchema (config.ts#jwtSchema) et tokenStoreSchema (config.ts#tokenStoreSchema), défauts inclus.

📜 Normes appliquées#

⚡ Performance & mémoire#

• jose importé lazy (dep lourde) : #ensureJose() au premier usage (tokenService.ts#TokenService.#ensureJose) — le boot ne paie rien si le JWT n’est jamais sollicité ; keystore mémoïsé pareil.
• Rien sur le hot path requête : émission et rotation sont des endpoints cold-path ; la vérification (hot path) vit chez le JwtAuthenticator.
• Timers civilisés : GcScheduler unref (n’empêche pas l’arrêt) + jitter anti-balayages simultanés (tokenService.ts#TokenService.#build) ; denylist mémoire bornée par purge amortie (MemoryTokenStore.ts#MemoryTokenStore.restore).
• Jamais N en RAM : listPage() borne toute lecture admin à une page (ITokenStore.ts#ITokenStore.listPage).

📡 Observabilité — Studio#

• Écran Stores (/nodefony/stores) : la résolution du store de jetons (configuré → résolu + raison) publiée par registerStoreResolution() (tokenService.ts#TokenService.#build).
• Écran Audit (/nodefony/audit) : événements token.issued, token.reuse_detected (signal d’attaque), login.failure/login.throttled du grant — corrélables par tokenId.
• Écran ApiKeys : le même store côté PAT, listing paginé serveur.

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

🧪 Tests & couverture#

Cinq 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 : tokenService (émission, rotation, rejeu, downscoping), tokenStore (révocation, denylist, gc, rétention), jwtKeystore (les 3 priorités de source), jwtPipeline (bout en bout signature → vérification), tokenPagination (le banc de contrat piloté par le store mémoire) ;
• banc de contrat : tokenPaginationContract — invariants listPage/countTokens tenus par tous les backends (tri, offset, filtres, curseur) ;
• intégration adapters : token-store + token-pagination chez drizzle (sqlite), mongoose et redis — le MÊME banc rejoué sur chaque backend ;
• e2e base réelle : drizzle sur PostgreSQL et MySQL ;
• manque assumé : pas de banc d’attaque dédié à l’émission (le rejeu est couvert en unit) ni de test de charge sur le grant.

Les bancs sur serveur réel se skippent sans leurs variables d’infra — un skip compte comme vert : lire le bloc gates (scripts/test/vitest/gates.ts, affiché en fin de run) avant de conclure. 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 : api-keys · Authenticators

• La vérification de ces jetons (JWT/PAT) → authenticators

• Le firewall qui applique la zone → firewall · L’autorisation par scopes → authorization

• La doctrine store:"auto" → configuration

• Vue d’ensemble sécurité → index