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


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

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

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

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

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

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

```ts
function getTokenStoreFactory(name: string): TokenStoreFactory
```

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

#### `listTokenStores`

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

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

#### `matchesTokenStatus`

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

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

#### `registerTokenStore`

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

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

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

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

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

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

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

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

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

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

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

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

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

```ts
type ITokenCounts = FacetCounts<typeof TOKEN_FACETS>
```

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

#### `TokenStoreFactory`

```ts
type TokenStoreFactory = (ctx: ITokenStoreFactoryContext) => ITokenStore
```

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

---

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