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

stable

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

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

Classes (5)#

AnonymousToken#

class AnonymousToken implements IToken

Token du visiteur non authentifié — Zero Trust : un visiteur EST un utilisateur anonyme (jamais null).

• readonly type = "anonymous" — Type du token ("anonymous", "userpassword", "jwt", "oauth2", "mtls").
• getUser(): IUser — Utilisateur porté — jamais null (AnonymousUser si non authentifié).
• getUserIdentifier(): string — Identifiant logique de l’utilisateur ("anonymous", "admin"…) — partagé avec IRealtimeToken (le token WS, sous-ensemble transport-neutre, n’a PAS getUser()).
• isAuthenticated(): boolean — true si l’authentification a réussi (≠ anonyme).
• getRoles(): string[] — Rôles plats de l’utilisateur (sans hiérarchie résolue).
• getCredentials(): unknown — Credential brut avant validation (vidé au succès).
• getScopes(): string[] — Scopes accordés (clé API / OAuth) — axe distinct des rôles RBAC.
• getAttribute<T = unknown>(key: string): T — Lecture d’un attribut arbitraire posé par l’authenticator (claims JWT, scopes…).
• setAttribute(key: string, value: unknown): void — Pose un attribut arbitraire (claims, scopes, providerId…).

JwtKeystore#

class JwtKeystore implements IJwtKeystore

Keystore Ed25519 — implémentation de référence d’IJwtKeystore.

• constructor(source: KeystoreSource, log: LogFn)
• getSigningKey(): Promise<IJwtSigningKey> — Clé active de signature.
• getPublicJWKS(): Promise<JSONWebKeySet> — JWKS public (toutes les clés du keyset, paramètres publics uniquement) — passé à createLocalJWKSet pour résoudre la clé de vérification par kid.

MemoryTokenStore#

class MemoryTokenStore implements ITokenStore

Store de jetons en mémoire — implémentation de référence d’ITokenStore.

• readonly sortableFields: readonly [ "createdAt", "name", "subjectId", "id" ] — {@inheritDoc ITokenStore.sortableFields}
• constructor(now?: () => number, retentionRevokedMs?: number)
• put(record: IAccessTokenRecord): Promise<void> — Enregistre (ou remplace) un jeton persistant.
• findById(id: string): Promise<IAccessTokenRecord | null> — Recherche par identifiant (jti/id public).
• findByHash(secretHash: string): Promise<IAccessTokenRecord | null> — Recherche par hash de secret présenté.
• findBySubject(subjectId: string): Promise<IAccessTokenRecord[]> — Tous les jetons d’un porteur (console « mes jetons », révocation ciblée).
• listAll(): Promise<IAccessTokenRecord[]> — Tous les jetons du store, tous porteurs confondus — vue d’ADMINISTRATION cross-porteur (gouvernance / réponse à incident).
• listPage(query: ITokenListQuery): Promise<IPage<IAccessTokenRecord>> — Liste paginée de jetons pour le data plane admin — ne matérialise jamais plus d’une page (contrairement à ITokenStore.listAll, réservé au dump d’incident).
• countTokens(query: ITokenListQuery): Promise<number> — Compte les jetons correspondant aux filtres — base du total de la page (SQL/Mongo COUNT, mémoire length).
• markUsed(id: string, usage: ITokenUsage): Promise<void> — Met à jour lastUsedAt/IP/UA (no-op si l’id est inconnu).
• revoke(id: string, reason: TokenRevokeReason): Promise<void> — Révoque un jeton (pose revokedAt+revokedReason) — idempotent.
• revokeFamily(family: string, reason: TokenRevokeReason): Promise<void> — Révoque TOUTE la famille de rotation (détection de rejeu, RFC 9700).
• denyJti(jti: string, expiresAt: number): Promise<void> — Inscrit un jti d’access sur la denylist jusqu’à expiresAt (epoch ms) — révocation immédiate avant l’exp du JWT.
• isJtiDenied(jti: string): Promise<boolean> — true si le jti est denylisté et non encore expiré.
• revokeAllForSubject(subjectId: string, invalidBefore: number): Promise<void> — Pose le seuil invalidBefore (epoch ms) d’un porteur : tout access auto-porté dont iat < invalidBefore est rejeté.
• getInvalidBefore(subjectId: string): Promise<number | null> — Seuil invalidBefore d’un porteur (epoch ms) ou null si aucun.
• gc(now?: number): Promise<number> — Purge les entrées devenues inutiles : denylist jti expirée, records arrivés à exp, PAT révoqués sans expiration au-delà de la fenêtre de rétention.
• snapshot(): TokenStoreSnapshot — Instantané sérialisable de l’état courant (records + denylist + seuils).
• restore(snapshot: TokenStoreSnapshot): void — Remplace l’état par celui d’un instantané (reconstruit les index dérivés).

RemoteJwtVerifier#

class RemoteJwtVerifier

Vérificateur de jetons d’accès émis par un serveur d’autorisation tiers.

• constructor(options: IRemoteJwtVerifierOptions)
• get size(): number — Nombre d’émetteurs de confiance — pour l’introspection et les journaux.
• verify(token: string, audience: string): Promise<IAccessPrincipal | null> — Vérifie un jeton porté, pour UNE ressource donnée.
• verifyClaims(token: string, audience: string): Promise<{ issuer: string; payload: Jose.JWTPayload; } | null> — Vérifie un jeton et rend ses claims BRUTS — pour un jeton qui n’est pas un jeton d’accès (jeton de déconnexion OpenID Connect, par exemple), dont le sens se lit dans des claims que verify ne remonte …

UserToken#

class UserToken implements IToken

Jeton porteur d’un utilisateur réel — produit par les authenticators à credential (userpassword, puis session/jwt…).

• readonly type: string — Type du token ("anonymous", "userpassword", "jwt", "oauth2", "mtls").
• constructor(type: string, credentials?: unknown)
• promote(user: IUser): this — Marque le jeton authentifié : pose l’utilisateur vérifié et EFFACE le credential.
• getUser(): IUser — Utilisateur porté — jamais null (AnonymousUser si non authentifié).
• getUserIdentifier(): string — Identifiant logique de l’utilisateur ("anonymous", "admin"…) — partagé avec IRealtimeToken (le token WS, sous-ensemble transport-neutre, n’a PAS getUser()).
• isAuthenticated(): boolean — true si l’authentification a réussi (≠ anonyme).
• getRoles(): string[] — Rôles plats de l’utilisateur (sans hiérarchie résolue).
• getCredentials(): unknown — Credential brut avant validation (vidé au succès).
• getScopes(): string[] — Scopes accordés (clé API / OAuth) — axe distinct des rôles RBAC.
• getAttribute<T = unknown>(key: string): T — Lecture d’un attribut arbitraire posé par l’authenticator (claims JWT, scopes…).
• setAttribute(key: string, value: unknown): void — Pose un attribut arbitraire (claims, scopes, providerId…).

Fonctions (7)#

getTokenStoreFactory#

function getTokenStoreFactory(name: string): TokenStoreFactory

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

listTokenStores#

function listTokenStores(): string[]

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

matchesTokenStatus#

function matchesTokenStatus(token: ITokenLifetime, status: TokenStatus, now: number): boolean

true si le jeton correspond au filtre d’état demandé (undefined = tous).

registerTokenStore#

function registerTokenStore(name: string, factory: TokenStoreFactory): void

Enregistre (ou remplace) la fabrique d’un store de jetons. Appelée par le builtin memory au chargement, et par les adapters (drizzle/mongoose/redis) pour les leurs.

resolveJwtRuntime#

function resolveJwtRuntime(jwt: ISecurityConfig["jwt"]): IJwtRuntime

Dérive les paramètres effectifs depuis la config sécurité. issuer omis → "nodefony" (DEVRAIT être surchargé en prod) ; audiences vide → l’app est sa propre audience ([issuer]).

tokenStatusCriteria#

function tokenStatusCriteria(status: ITokenListQuery["status"], now: number): Record<string, unknown>

Fragment de critère portable exprimant l’état de vie d’un jeton — la traduction que les adapters SQL et Mongo partagent au lieu de la réécrire.

tokenStatusOf#

function tokenStatusOf(token: ITokenLifetime, now: number): TokenStatus

La définition de l’état d’un jeton — un seul exemplaire, pour les backends qui évaluent en mémoire (store mémoire, filtrage inline d’un batch SCAN).

Constantes (3)#

TOKEN_DEFAULT_ORDER#

const TOKEN_DEFAULT_ORDER: NonNullable<IPageQuery["order"]>

Ordre contractuel appliqué quand le client n’en demande aucun : les clés les plus récentes d’abord, départagées par identifiant pour rester déterministe à horodatage égal (sans quoi une pagination offset peut sauter ou répéter une ligne entre deux pages).

TOKEN_FACETS#

const TOKEN_FACETS: { readonly total: {}; readonly active: { readonly status: "active"; }; readonly expired: { readonly status: "expired"; }; readonly revoked: { readonly status: "revoked"; }; }

Les facettes des jetons — les questions fermées posées à la collection ENTIÈRE pour les cartes de tête.

TOKEN_SORTABLE_FIELDS#

const TOKEN_SORTABLE_FIELDS: readonly [ "createdAt", "name", "subjectId", "id" ]

Le vocabulaire de tri des jetons, en noms PUBLICS — ceux qu’un client écrit dans l’URL (?order=createdAt:DESC), jamais des noms de colonne.

Interfaces (6)#

IJwtRuntime#

interface IJwtRuntime

Paramètres JWT résolus partagés par l’émetteur (TokenService) et le vérificateur (JwtAuthenticator) — garantit que iss/aud posés à la signature sont EXACTEMENT ceux exigés à la vérification (une divergence = tout rejeté). Fonction pure (pas d’état, pas de kernel) → les deux côtés obtiennent la même valeur sans la partager.

• readonly issuer: string — Émetteur (iss).
• readonly audiences: string[] — Audiences acceptées au verify ; la première sert d’aud à l’émission.
• readonly accessTtlS: number — TTL access token (s).
• readonly refreshTtlS: number — TTL refresh token (s).
• readonly rotateRefresh: boolean — Rotation du refresh à chaque usage (OWASP / RFC 9700).
• readonly alg: "EdDSA" — Algorithme — "EdDSA" (Ed25519).

IRemoteJwtVerifierOptions#

interface IRemoteJwtVerifierOptions

Réglages du vérificateur — au-delà de la liste des émetteurs.

• issuers: readonly ITrustedIssuer[] — Les émetteurs de confiance.
• timeoutMs?: number — Délai maximal d’une requête vers un émetteur (ms).
• cooldownMs?: number — Fenêtre pendant laquelle on ne redemande PAS le jeu de clés (ms).
• cacheMaxAgeMs?: number — Âge maximal du jeu de clés en cache avant rafraîchissement (ms).
• clockToleranceS?: number — Tolérance d’horloge sur exp/nbf (secondes).
• fetch?: typeof globalThis.fetch — Implémentation de fetch — le seul moyen d’éprouver ce code SANS réseau.
• log?: (message: string) => void — Journal d’audit — reçoit la cause FINE, que le client ne voit jamais.

ITokenLifetime#

interface ITokenLifetime

Ce qu’il faut d’un jeton pour en déduire l’état — deux horodatages, rien de plus. Volontairement structural : le store mémoire, le batch Redis et un test s’en servent sans partager de type d’enregistrement.

• readonly revokedAt: number | null — Instant de révocation, ou null si jamais révoqué.
• readonly expiresAt: number | null — Échéance, ou null pour un jeton sans expiration.

ITokenStoreFactoryContext#

interface ITokenStoreFactoryContext

Contexte passé à une fabrique de store : de quoi se construire (résolutions coûteuses en lazy à l’intérieur de l’instance).

• readonly container: Container — Container DI — résolution de services (ORM, redis…).
• readonly config: ISecurityConfig — Config sécurité validée + gelée.

ITrustedIssuer#

interface ITrustedIssuer

Un émetteur en qui l’application accepte de faire confiance.

• issuer: string — Identifiant canonique de l’émetteur (iss attendu dans les jetons).
• jwksUri?: string — Jeu de clés, quand on ne veut pas de découverte.
• discoveryUrl?: string — Adresse où lire les métadonnées quand elle diffère de l’émetteur (service interne d’un cluster).
• localJwks?: () => Promise<Jose.JSONWebKeySet> — Jeu de clés fourni LOCALEMENT — aucune requête, aucune découverte.
• algorithms: readonly string[] — Algorithmes de signature acceptés — allowlist côté serveur.
• typ?: string — Valeur exigée de l’en-tête typ (RFC 9068 : at+jwt), ou rien.
• requiredClaims?: readonly string[] — Claims dont la PRÉSENCE est exigée, en plus de iss/aud/sub.

TokenStoreSnapshot#

interface TokenStoreSnapshot

Instantané sérialisable de l’état d’un store en mémoire — base de la persistance fichier (MemoryTokenStore.snapshot/restore) et de l’inspection. Les index dérivés (par hash/famille/sujet) ne sont PAS sérialisés : ils sont reconstruits depuis records au restore.

• records: IAccessTokenRecord[]
• deniedJti: Array<[ string, number ]>
• invalidBefore: Array<[ string, number ]>

Types (2)#

ITokenCounts#

type ITokenCounts = FacetCounts<typeof TOKEN_FACETS>

Les compteurs rendus par GET /nodefony/security/api/apikeys/stats.

TokenStoreFactory#

type TokenStoreFactory = (ctx: ITokenStoreFactoryContext) => ITokenStore

Fabrique d’un store de jetons pour un nom donné.

← Toutes les références d’API