@nodefony/security 10.0.0-alpha.1

package/dist/types/nodefony/src/token/JwtKeystore.d.ts

@@ -0,0 +1,43 @@
+import type { JSONWebKeySet } from "jose";
+import type { IJwtKeystore, IJwtSigningKey } from "../../contracts/IJwtKeystore.js";
+/** Journalisation injectée (le keystore n'est pas un Service — il reçoit un log). */
+type LogFn = (message: string, severity: string) => void;
+/** Source de clé configurée (`config.jwt.keystore`). */
+interface KeystoreSource {
+    /** JWK Set (clés privées) injecté depuis l'env — source `env` (prod). */
+    readonly keySetJson?: string;
+    /** Dossier de persistance `keyset.json` — source `fichier` (opt-in dev/VPS). */
+    readonly dir?: string;
+}
+/**
+ * Keystore Ed25519 — implémentation de référence d'{@link IJwtKeystore}.
+ *
+ * Résout la clé de signature selon une **priorité** (jamais d'auto-génération en
+ * clair « par défaut » en prod) :
+ *  1. **env** — `config.jwt.keystore.keySetJson` (JWK Set injecté par l'app depuis
+ *     son catalogue d'env) : prod cloud, secret géré hors-app, même clé sur tous
+ *     les pods.
+ *  2. **fichier** — `config.jwt.keystore.dir/keyset.json` (écrit en mode 600,
+ *     généré si absent) : opt-in dev/VPS mono-machine. Le mode effectif est
+ *     **constaté** après coup : un système de fichiers qui n'applique pas les
+ *     permissions POSIX (NTFS, FAT, NFS sans mapping) déclenche un **warning**
+ *     plutôt qu'une garantie silencieusement fausse.
+ *  3. **mémoire** — aucune source → clé éphémère générée au 1ᵉʳ usage + **warning**
+ *     (perdue au redémarrage = refresh invalidés, incohérente en cluster).
+ *
+ * jose est importé **paresseusement** (dep lourde — règle perf P6) au premier
+ * usage ; le boot ne paie rien si le JWT n'est jamais sollicité. Le chargement
+ * est mémoïsé (une seule résolution concurrente).
+ *
+ * @remarks Race au 1ᵉʳ boot d'un **cluster** sans clé pré-provisionnée : deux
+ * workers peuvent générer puis écrire des clés différentes (le dernier `rename`
+ * gagne). En prod, provisionner la clé hors-bande (`keySetJson`/SecretProvider
+ * P16) élimine ce cas — c'est précisément la source recommandée.
+ */
+export declare class JwtKeystore implements IJwtKeystore {
+    #private;
+    constructor(source: KeystoreSource, log: LogFn);
+    getSigningKey(): Promise<IJwtSigningKey>;
+    getPublicJWKS(): Promise<JSONWebKeySet>;
+}
+export default JwtKeystore;

package/dist/types/nodefony/src/token/MemoryTokenStore.d.ts

@@ -0,0 +1,66 @@
+import type { IPage } from "nodefony";
+import type { IAccessTokenRecord, ITokenListQuery, ITokenStore, ITokenUsage, TokenRevokeReason } from "../../contracts/ITokenStore.js";
+/**
+ * Filtre un record contre une requête de listing — prédicat de RÉFÉRENCE du
+ * contrat, réutilisé par les implémentations qui évaluent en mémoire.
+ *
+ * @param now - instant de référence pour l'état du jeton (`status`). Requis :
+ *   « expiré » n'a pas de sens sans une horloge, et la lire ici ferait dépendre
+ *   le résultat du moment du test plutôt que de la donnée.
+ */
+export declare function matchesTokenQuery(record: IAccessTokenRecord, query: ITokenListQuery, now: number): boolean;
+/**
+ * Instantané sérialisable de l'état d'un store en mémoire — base de la
+ * persistance fichier ({@link 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`.
+ */
+export interface TokenStoreSnapshot {
+    records: IAccessTokenRecord[];
+    deniedJti: Array<[string, number]>;
+    invalidBefore: Array<[string, number]>;
+}
+/**
+ * Store de jetons **en mémoire** — implémentation de référence d'{@link ITokenStore}.
+ *
+ * 0 dépendance, idéale pour le développement mono-process et les **tests**. NON
+ * partagée entre process (pas de cluster) et **volatile** (tout est perdu au
+ * redémarrage) → en production multi-process, utiliser un adapter ORM ou Redis.
+ *
+ * Perf/mémoire : les `Map` n'existent que si le store est instancié (JWT activé),
+ * jamais sur le hot path par requête. La denylist `jti` est bornée par un
+ * **balayage amorti** (purge des entrées expirées tous les 256 ajouts) doublé
+ * d'une expiration paresseuse à la lecture — pas de minuterie, pas de fuite.
+ *
+ * Horloge injectable (`now`) pour des tests déterministes (pattern `LoginThrottler`).
+ */
+export declare class MemoryTokenStore implements ITokenStore {
+    #private;
+    /**
+     * {@inheritDoc ITokenStore.sortableFields}
+     *
+     * Le store mémoire porte l'enregistrement complet : il sait donc trier tout le
+     * vocabulaire public, sans réduction de capacité.
+     */
+    readonly sortableFields: readonly ["createdAt", "name", "subjectId", "id"];
+    constructor(now?: () => number, retentionRevokedMs?: number);
+    put(record: IAccessTokenRecord): Promise<void>;
+    findById(id: string): Promise<IAccessTokenRecord | null>;
+    findByHash(secretHash: string): Promise<IAccessTokenRecord | null>;
+    findBySubject(subjectId: string): Promise<IAccessTokenRecord[]>;
+    listAll(): Promise<IAccessTokenRecord[]>;
+    listPage(query: ITokenListQuery): Promise<IPage<IAccessTokenRecord>>;
+    countTokens(query: ITokenListQuery): Promise<number>;
+    markUsed(id: string, usage: ITokenUsage): Promise<void>;
+    revoke(id: string, reason: TokenRevokeReason): Promise<void>;
+    revokeFamily(family: string, reason: TokenRevokeReason): Promise<void>;
+    denyJti(jti: string, expiresAt: number): Promise<void>;
+    isJtiDenied(jti: string): Promise<boolean>;
+    revokeAllForSubject(subjectId: string, invalidBefore: number): Promise<void>;
+    getInvalidBefore(subjectId: string): Promise<number | null>;
+    gc(now?: number): Promise<number>;
+    /** Instantané sérialisable de l'état courant (records + denylist + seuils). */
+    snapshot(): TokenStoreSnapshot;
+    /** Remplace l'état par celui d'un instantané (reconstruit les index dérivés). */
+    restore(snapshot: TokenStoreSnapshot): void;
+}

package/dist/types/nodefony/src/token/RemoteJwtVerifier.d.ts

@@ -0,0 +1,149 @@
+import type * as Jose from "jose";
+import { type IAccessPrincipal } from "nodefony";
+/**
+ * Un émetteur en qui l'application accepte de faire confiance.
+ *
+ * Le fait qu'il n'y ait pas de valeur par défaut pour `issuer` est le cœur du
+ * dispositif : **la liste des émetteurs est fermée et vient de la
+ * configuration**, jamais d'un jeton. Le `iss` présenté ne sert qu'à choisir
+ * DANS cette liste — il ne peut donc pas désigner un serveur que l'application
+ * n'a pas nommé, et aucune requête sortante ne peut être provoquée par un
+ * appelant anonyme vers une URL de son choix.
+ */
+export interface ITrustedIssuer {
+    /** Identifiant canonique de l'émetteur (`iss` attendu dans les jetons). */
+    issuer: string;
+    /**
+     * Jeu de clés, quand on ne veut pas de découverte.
+     *
+     * Utile pour un émetteur qui ne publie pas de métadonnées, et pour supprimer
+     * une requête au démarrage à froid. Déclaré, il fait autorité : rien n'est
+     * découvert.
+     */
+    jwksUri?: string;
+    /**
+     * Jeu de clés fourni LOCALEMENT — aucune requête, aucune découverte.
+     *
+     * ⭐ **Le cas qui l'exige : l'émetteur, c'est CETTE application.** Elle signe
+     * ses propres jetons, elle a donc déjà les clés publiques en mémoire. Aller
+     * les relire par HTTP chez elle-même ajoute à une opération purement locale
+     * une dépendance au réseau, au DNS et à TLS — et c'est exactement là que ça
+     * casse : en développement, l'application se sert un certificat que le
+     * magasin d'autorités de Node ne connaît pas, si bien que la vérification
+     * échouait en `SELF_SIGNED_CERT_IN_CHAIN` alors que le jeton était parfait,
+     * que la clé était à portée de main, et que `curl` joignait la même URL sans
+     * broncher. En production, le même aller-retour ferait dépendre
+     * l'authentification de l'entrée réseau du pod.
+     *
+     * Appelé à CHAQUE résolution, jamais mémoïsé : une rotation de clés locale
+     * est alors prise en compte sans redémarrage, et le coût — analyser un jeu de
+     * une ou deux clés — est sans commune mesure avec la vérification de
+     * signature qui suit.
+     */
+    localJwks?: () => Promise<Jose.JSONWebKeySet>;
+    /**
+     * Algorithmes de signature acceptés — **allowlist côté serveur**.
+     *
+     * RFC 8725 §3.1 : l'algorithme ne se déduit JAMAIS de l'en-tête du jeton.
+     * Tous asymétriques, et c'est structurel : les clés viennent d'un jeu PUBLIC,
+     * donc accepter un algorithme à secret partagé (`HS*`) laisserait un attaquant
+     * signer avec la clé publique de l'émetteur, que tout le monde peut lire.
+     */
+    algorithms: readonly string[];
+    /**
+     * Valeur exigée de l'en-tête `typ` (RFC 9068 : `at+jwt`), ou rien.
+     *
+     * Non exigé par défaut : le parc réel est très inégal sur ce point, et un
+     * défaut strict serait désactivé en bloc à la première intégration plutôt que
+     * réglé finement. La séparation entre jetons est déjà assurée par l'audience,
+     * qui, elle, n'est pas facultative.
+     */
+    typ?: string;
+    /** Claims dont la PRÉSENCE est exigée, en plus de `iss`/`aud`/`sub`. */
+    requiredClaims?: readonly string[];
+}
+/** Réglages du vérificateur — au-delà de la liste des émetteurs. */
+export interface IRemoteJwtVerifierOptions {
+    /** Les émetteurs de confiance. Vide = le vérificateur ne sert à rien. */
+    issuers: readonly ITrustedIssuer[];
+    /** Délai maximal d'une requête vers un émetteur (ms). */
+    timeoutMs?: number;
+    /** Fenêtre pendant laquelle on ne redemande PAS le jeu de clés (ms). */
+    cooldownMs?: number;
+    /** Âge maximal du jeu de clés en cache avant rafraîchissement (ms). */
+    cacheMaxAgeMs?: number;
+    /** Tolérance d'horloge sur `exp`/`nbf` (secondes). */
+    clockToleranceS?: number;
+    /**
+     * Implémentation de `fetch` — le seul moyen d'éprouver ce code SANS réseau.
+     *
+     * C'est ce qui permet aux tests de jouer une rotation de clés, un émetteur
+     * qui ment sur son identité ou un délai dépassé, de façon déterministe et
+     * sans démarrer quoi que ce soit.
+     */
+    fetch?: typeof globalThis.fetch;
+    /** Journal d'audit — reçoit la cause FINE, que le client ne voit jamais. */
+    log?: (message: string) => void;
+}
+/**
+ * Vérificateur de jetons d'accès émis par un **serveur d'autorisation tiers**.
+ *
+ * C'est la pièce qui manquait pour que le rôle *serveur de ressource* du cœur
+ * (`nodefony/src/oauth/`) soit autre chose qu'un refus poli : il sait publier ce
+ * qu'il protège et dire où prendre un jeton, mais rien, jusqu'ici, ne savait
+ * LIRE ce jeton. `JwtAuthenticator` ne vérifie que les jetons émis par
+ * Nodefony lui-même (jeu de clés local) ; ici, les clés appartiennent à
+ * quelqu'un d'autre, arrivent par le réseau et tournent sans prévenir.
+ *
+ * ## Ce qui vaut garantie
+ *
+ * - **L'audience est obligatoire et vient de l'APPELANT** — jamais du jeton. Un
+ *   jeton parfaitement valide, émis par un émetteur de confiance, pour un AUTRE
+ *   service, est refusé (RFC 8707 §2). C'est la seule chose qui empêche le
+ *   rejeu d'un jeton légitime d'une ressource vers une autre.
+ * - **L'algorithme est imposé par la configuration** (RFC 8725 §3.1), jamais lu
+ *   dans l'en-tête ; `alg: none` n'existe pas pour cette API.
+ * - **Les clés viennent du `jwks_uri` de l'émetteur**, jamais d'un `jku` ou
+ *   d'un `jwk` porté par le jeton (§3.5) — sans quoi un attaquant fournirait
+ *   la clé qui valide sa propre signature.
+ * - **La liste des émetteurs est fermée** : un `iss` inconnu est refusé avant
+ *   toute requête sortante.
+ *
+ * ## Ce que cette classe ne fait pas
+ *
+ * Elle n'établit pas d'utilisateur applicatif : elle rend un sujet et des
+ * scopes. Rattacher ce sujet à un compte local (approvisionnement à la volée,
+ * comptes de service) est une décision d'application, pas de protocole — et
+ * l'entremêler ici rendrait impossible d'accepter un appelant purement machine,
+ * qui est précisément le cas d'usage.
+ *
+ * @see references/rfc/ietf/rfc8707.txt — l'audience, qui LIE un jeton à CE service
+ */
+export declare class RemoteJwtVerifier {
+    #private;
+    /**
+     * @param options - émetteurs de confiance et réglages réseau
+     * @throws Error si un émetteur est invalide, dupliqué, ou déclare un
+     *         algorithme à secret partagé
+     */
+    constructor(options: IRemoteJwtVerifierOptions);
+    /** Nombre d'émetteurs de confiance — pour l'introspection et les journaux. */
+    get size(): number;
+    /**
+     * Vérifie un jeton porté, pour UNE ressource donnée.
+     *
+     * Conforme au contrat `IAccessTokenVerifier` du cœur : un refus est un `null`,
+     * jamais une exception. Les exceptions sont réservées aux pannes — un
+     * émetteur injoignable n'est pas un jeton invalide.
+     *
+     * @param token - le jeton brut, tel que présenté
+     * @param audience - URI canonique de la ressource visée ; le jeton DOIT la
+     *          porter dans `aud`
+     * @returns le principal établi, ou `null` si le jeton est refusé
+     * @throws Error si l'émetteur ne peut pas être joint ou publie un jeu de clés
+     *         inutilisable — la porte doit alors refuser de servir, pas répondre
+     *         « jeton invalide »
+     */
+    verify(token: string, audience: string): Promise<IAccessPrincipal | null>;
+}
+export default RemoteJwtVerifier;

package/dist/types/nodefony/src/token/UserToken.d.ts

@@ -0,0 +1,41 @@
+import type { IUser } from "@nodefony/user";
+import type { IToken } from "../../contracts/IToken.js";
+/**
+ * Jeton porteur d'un utilisateur réel — produit par les authenticators à
+ * credential (`userpassword`, puis `session`/`jwt`...).
+ *
+ * Cycle en deux états, UN SEUL objet alloué par tentative (cold path login) :
+ * 1. `createToken()` → non authentifié : porte le credential brut extrait de la
+ *    requête, `getUser()` rend l'anonyme (jamais `null`, Zero Trust).
+ * 2. `authenticate()` réussit → {@link promote} : l'utilisateur vérifié est posé
+ *    et le credential est **effacé** (anti-fuite : un mot de passe ne doit
+ *    survivre ni en mémoire ni dans un heap dump/log).
+ *
+ * Les attributs (claims, providerId...) sont lazy — `null` tant que rien n'est posé.
+ */
+export declare class UserToken implements IToken {
+    #private;
+    readonly type: string;
+    /**
+     * @param type - type du token (`"userpassword"`, `"session"`, `"jwt"`...).
+     * @param credentials - credential brut extrait de la requête (vidé au succès).
+     */
+    constructor(type: string, credentials?: unknown);
+    /**
+     * Marque le jeton authentifié : pose l'utilisateur vérifié et EFFACE le
+     * credential. Appelé uniquement par l'authenticator au succès.
+     *
+     * @param user - utilisateur vérifié par la source d'identité.
+     * @returns le jeton lui-même (chaînage).
+     */
+    promote(user: IUser): this;
+    getUser(): IUser;
+    getUserIdentifier(): string;
+    isAuthenticated(): boolean;
+    getRoles(): string[];
+    getCredentials(): unknown;
+    getScopes(): string[];
+    getAttribute<T = unknown>(key: string): T | undefined;
+    setAttribute(key: string, value: unknown): void;
+}
+export default UserToken;

package/dist/types/nodefony/src/token/jwtRuntime.d.ts

@@ -0,0 +1,28 @@
+import type { ISecurityConfig } from "../../config/defineModuleConfig.js";
+/**
+ * Paramètres JWT **résolus** partagés par l'émetteur ({@link TokenService}) et le
+ * vérificateur ({@link 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.
+ */
+export interface IJwtRuntime {
+    /** Émetteur (`iss`). */
+    readonly issuer: string;
+    /** Audiences acceptées au verify ; la première sert d'`aud` à l'émission. */
+    readonly audiences: string[];
+    /** TTL access token (s). */
+    readonly accessTtlS: number;
+    /** TTL refresh token (s). */
+    readonly refreshTtlS: number;
+    /** Rotation du refresh à chaque usage (OWASP / RFC 9700). */
+    readonly rotateRefresh: boolean;
+    /** Algorithme — `"EdDSA"` (Ed25519). RS256 = slot non câblé en J4a. */
+    readonly alg: "EdDSA";
+}
+/**
+ * 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]`).
+ */
+export declare function resolveJwtRuntime(jwt: ISecurityConfig["jwt"]): IJwtRuntime;

package/dist/types/nodefony/src/token/secretFile.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Écrire un SECRET sur disque — la seule implémentation du dépôt.
+ *
+ * ## Les trois règles, et ce que chacune évite
+ *
+ * 1. **Ne jamais tester la présence avant de lire.** `existsSync(f) ? read(f)
+ *    : ""` ouvre une fenêtre entre le test et l'usage : le fichier peut
+ *    disparaître, ou devenir un lien vers ailleurs. La forme juste est de lire
+ *    et de traiter `ENOENT` — le système de fichiers répond en une opération ce
+ *    que deux appels ne peuvent pas garantir.
+ * 2. **Écrire en 0600, atomiquement.** Un secret créé au masque par défaut est
+ *    lisible par tous les comptes de la machine, et rien ne le signale. Le
+ *    couple fichier temporaire + `rename` évite en plus qu'un lecteur tombe sur
+ *    un fichier à demi écrit.
+ * 3. **CONSTATER le mode obtenu.** Le mode demandé est une intention, pas une
+ *    garantie : NTFS l'ignore, comme un montage FAT/exFAT ou NFS sans mapping
+ *    d'identité. Une capacité se constate, elle ne se déduit pas de
+ *    `process.platform` — et si la restriction n'a pas pris, il faut le DIRE
+ *    plutôt que laisser croire à une protection.
+ *
+ * ## Pourquoi les deux formes, synchrone et asynchrone
+ *
+ * Le runtime persiste ses clés dans du code asynchrone ; une commande de CLI
+ * écrit un jeton dans un flot synchrone, où introduire une promesse
+ * changerait l'ordre des messages affichés. Les deux formes appliquent le même
+ * raisonnement, écrit ici une seule fois — deux copies divergeraient, et l'on
+ * sait exactement comment : l'une porterait le mode 0600, l'autre non.
+ *
+ * @module
+ */
+/** Mode attendu d'un fichier qui porte un secret : lisible par son seul propriétaire. */
+export declare const MODE_SECRET = 384;
+/**
+ * Le contenu du fichier, ou `null` s'il n'existe pas.
+ *
+ * @throws Toute erreur autre qu'`ENOENT` — un fichier illisible pour cause de
+ *         droits n'est PAS un fichier absent, et le confondre ferait écraser un
+ *         secret existant par un fichier neuf.
+ */
+export declare function readIfPresent(file: string): Promise<string | null>;
+/** Forme synchrone de {@link readIfPresent}. */
+export declare function readIfPresentSync(file: string): string | null;
+/**
+ * Le mode effectif du fichier n'est-il PAS restreint au propriétaire ?
+ *
+ * @returns `null` si le fichier a disparu ou n'est pas interrogeable (le chemin
+ *          d'erreur normal parlera), sinon le mode effectif quand il diffère de
+ *          0600 — et `undefined` quand tout va bien.
+ */
+export declare function modeNonRestreint(file: string): number | null | undefined;
+/** Forme asynchrone de {@link modeNonRestreint}. */
+export declare function modeNonRestreintAsync(file: string): Promise<number | null | undefined>;
+/**
+ * La phrase à journaliser quand la restriction n'a PAS pris.
+ *
+ * Elle nomme la cause probable et ce qui reste à faire : un avertissement qui
+ * dit seulement « mode inattendu » se lit comme du bruit et finit ignoré.
+ */
+export declare function messageNonRestreint(file: string, mode: number): string;
+/**
+ * Écrit un secret : dossier créé, mode 0600, remplacement ATOMIQUE.
+ *
+ * Le mode est posé à la création du temporaire — et non après `rename` — pour
+ * qu'il n'existe à aucun instant un fichier au contenu secret et au masque par
+ * défaut. `chmod` est ensuite réappliqué sur la cible : un `rename` par-dessus
+ * un fichier EXISTANT conserve, sur certains systèmes, le mode de la cible.
+ */
+export declare function writeSecret(file: string, content: string): Promise<void>;
+/** Forme synchrone de {@link writeSecret}. */
+export declare function writeSecretSync(file: string, content: string): void;

package/dist/types/nodefony/src/token/tokenCriteria.d.ts

@@ -0,0 +1,20 @@
+import type { ITokenListQuery } from "../../contracts/ITokenStore.js";
+/**
+ * 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.
+ *
+ * Elle tient dans le `Criteria` d'orm-core depuis que celui-ci porte `$or` :
+ * « utilisable » signifie *sans échéance* **ou** *échéance à venir*, ce qu'aucune
+ * conjonction ne dit. Avant ça, chaque backend serait descendu à son SQL natif —
+ * trois écritures de la même règle, et la divergence pour seule perspective.
+ *
+ * Révoqué l'emporte sur expiré : les deux autres branches exigent donc
+ * explicitement `revokedAt IS NULL`. Sans cette précision, une clé révoquée
+ * **puis** échue compterait dans deux facettes, et la somme dépasserait le total.
+ *
+ * @param status - l'état demandé, ou `undefined` pour ne pas filtrer.
+ * @param now - instant de référence (injecté : un compteur ne doit pas dépendre
+ *   du moment où le test tourne).
+ * @returns le fragment à fusionner dans le critère, vide si aucun filtre.
+ */
+export declare function tokenStatusCriteria(status: ITokenListQuery["status"], now: number): Record<string, unknown>;

package/dist/types/nodefony/src/token/tokenFilters.d.ts

@@ -0,0 +1,76 @@
+import type { FacetCounts } from "nodefony";
+/**
+ * **Le vocabulaire de filtre des jetons**, en noms PUBLICS — ceux qu'un client
+ * écrit dans l'URL (`?status=revoked`), jamais des noms de colonne.
+ *
+ * Frère de `TOKEN_SORTABLE_FIELDS`, et posé pour la même raison : le vocabulaire
+ * appartient au propriétaire du contrat (`@nodefony/security`), la mécanique de
+ * lecture au cœur (`parseFilters`).
+ *
+ * **La différence avec le tri est structurelle.** Un tri est une CAPACITÉ de
+ * backend — Redis ne sait pas trier, donc `sortableFields` se déclare par store.
+ * Un filtre listé ici est une OBLIGATION de tous les backends de jetons : il est
+ * inscrit dans {@link ITokenListQuery}, et le store mémoire, SQL, Mongo comme
+ * Redis l'honorent chacun à sa façon (`WHERE` indexé, prédicat, filtre inline de
+ * batch `SCAN`). Le déclarer par store laisserait croire qu'il est facultatif.
+ *
+ * **Ce qui n'y est PAS, et pourquoi** : `kind`. Il existe bien au contrat, mais
+ * l'endpoint d'administration des clés d'API passe par `listPagePat`, qui impose
+ * `kind: "pat"` (`service/apiKeys.ts:210`). L'exposer donnerait un filtre que le
+ * service écrase en silence — la faute même que ce chantier corrige.
+ */
+export declare const TOKEN_FILTERS: {
+    /** Restreint à un porteur (colonne indexée dans tous les backends SQL). */
+    readonly subjectId: "string";
+    /**
+     * État de vie de la clé — la liste fermée vaut allowlist.
+     *
+     * Remplace l'ancien `revoked: "boolean"`, qui ne distinguait pas une clé
+     * ACTIVE d'une clé ARRIVÉE À ÉCHÉANCE : les deux étaient « non révoquées »,
+     * alors que la première ouvre l'accès et la seconde ne l'ouvre plus. La
+     * console affichait ces deux populations dans des cartes séparées sans
+     * pouvoir les demander au serveur.
+     */
+    readonly status: readonly ["active", "expired", "revoked"];
+};
+/**
+ * **Les facettes des jetons** — les questions fermées posées à la collection
+ * ENTIÈRE pour les cartes de tête.
+ *
+ * Contrairement aux webhooks, les trois états **partitionnent** : un jeton est
+ * dans exactement une case. On les compte tout de même une par une, sans jamais
+ * soustraire — une partition est une propriété du domaine d'aujourd'hui, pas une
+ * garantie du code, et un quatrième état la briserait en silence.
+ */
+export declare const TOKEN_FACETS: {
+    /** Toutes les clés, quel que soit leur état. */
+    readonly total: {};
+    /** Utilisables : ni révoquées, ni arrivées à échéance. */
+    readonly active: {
+        readonly status: "active";
+    };
+    /** Arrivées à échéance sans avoir été révoquées. */
+    readonly expired: {
+        readonly status: "expired";
+    };
+    /** Révoquées par un administrateur. */
+    readonly revoked: {
+        readonly status: "revoked";
+    };
+};
+/** Les compteurs rendus par `GET /nodefony/security/api/apikeys/stats`. */
+export type ITokenCounts = FacetCounts<typeof TOKEN_FACETS>;
+/**
+ * Ce que l'endpoint de COMPTEURS accepte de filtrer — `TOKEN_FILTERS` **moins**
+ * les champs que les facettes décomposent.
+ *
+ * `status` en est retiré : le demander à un endpoint dont les cartes SONT les
+ * états produirait une réponse qui se contredit — un total suivant le filtre, et
+ * chaque facette l'écrasant par le sien. Le refuser dit au client ce qui se
+ * passe ; l'accepter lui montrerait « 5 clés, dont 538 révoquées ».
+ *
+ * Un test verrouille l'accord entre cette liste et {@link TOKEN_FACETS}.
+ */
+export declare const TOKEN_STATS_FILTERS: {
+    readonly subjectId: "string";
+};

package/dist/types/nodefony/src/token/tokenSort.d.ts

@@ -0,0 +1,33 @@
+import type { IPageQuery } from "nodefony";
+/**
+ * **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.
+ *
+ * Il vit ici, chez le propriétaire du contrat (`@nodefony/security`), et non dans
+ * chaque backend : c'est ce qui garantit qu'une console de clés d'API offre le
+ * même tri, que l'application tourne sur mémoire, SQL ou Mongo. Un store dont le
+ * schéma nomme un champ autrement traduit **chez lui** — cf
+ * {@link translateTokenOrderMongo}.
+ *
+ * - `createdAt` — date d'émission, l'axe naturel d'une console de clés ;
+ * - `name` — le libellé humain, ce qu'on lit dans la colonne de gauche ;
+ * - `subjectId` — regroupe les clés d'un même porteur (vue d'administration) ;
+ * - `id` — identifiant public, utile surtout en départage.
+ *
+ * **Ce qui n'y est PAS, et pourquoi** : `lastUsedAt`, `expiresAt` et `revokedAt`
+ * sont *nullables*, et le placement des valeurs absentes n'est pas le même d'un
+ * moteur à l'autre — PostgreSQL range les `NULL` en tête d'un tri `DESC`, SQLite
+ * et MySQL en queue, et le tri en mémoire (`compareByOrder`) les met en queue
+ * dans les deux sens. Les déclarer offrirait donc un tri dont l'ordre
+ * dépendrait de la base configurée, ce qui est exactement ce que ce vocabulaire
+ * existe pour empêcher. Ils s'ouvriront quand la normalisation « absents en
+ * queue » sera portée dans le helper de pagination, pas avant.
+ */
+export declare const TOKEN_SORTABLE_FIELDS: readonly ["createdAt", "name", "subjectId", "id"];
+/**
+ * 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).
+ */
+export declare const TOKEN_DEFAULT_ORDER: NonNullable<IPageQuery["order"]>;

package/dist/types/nodefony/src/token/tokenStatus.d.ts

@@ -0,0 +1,38 @@
+import type { TokenStatus } from "../../contracts/ITokenStore.js";
+/**
+ * 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.
+ */
+export interface ITokenLifetime {
+    /** Instant de révocation, ou `null` si jamais révoqué. */
+    readonly revokedAt: number | null;
+    /** Échéance, ou `null` pour un jeton sans expiration. */
+    readonly expiresAt: number | null;
+}
+/**
+ * **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`).
+ *
+ * L'ordre d'évaluation est significatif : **révoqué l'emporte sur expiré**. Une
+ * clé révoquée puis arrivée à échéance reste « révoquée » — c'est l'acte
+ * d'administration qui décrit ce qui s'est passé, pas l'écoulement du temps.
+ *
+ * Les backends SQL et Mongo n'appellent pas cette fonction (ils traduisent la
+ * condition dans leur langage, sinon il faudrait rapatrier la collection pour la
+ * filtrer) : c'est le banc de contrat partagé qui garantit qu'ils disent la même
+ * chose qu'elle.
+ *
+ * @param token - les deux horodatages du jeton.
+ * @param now - l'instant de référence (injecté : les tests ne dépendent pas de
+ *   l'horloge réelle, et un store porte déjà la sienne).
+ */
+export declare function tokenStatusOf(token: ITokenLifetime, now: number): TokenStatus;
+/**
+ * `true` si le jeton correspond au filtre d'état demandé (`undefined` = tous).
+ *
+ * @param token - les deux horodatages du jeton.
+ * @param status - l'état demandé, ou `undefined` pour ne pas filtrer.
+ * @param now - l'instant de référence.
+ */
+export declare function matchesTokenStatus(token: ITokenLifetime, status: TokenStatus | undefined, now: number): boolean;

package/dist/types/nodefony/src/token/tokenStoreRegistry.d.ts

@@ -0,0 +1,38 @@
+import type { Container } from "nodefony";
+import type { ISecurityConfig } from "../../config/defineModuleConfig.js";
+import type { ITokenStore } from "../../contracts/ITokenStore.js";
+/**
+ * Registre de **fabriques de stores de jetons** — résout le nom configuré
+ * (`security.tokenStore`) vers une instance d'{@link ITokenStore}, SANS coupler
+ * le cœur à un backend en dur.
+ *
+ * Pourquoi : le store est pluggable par contrat (mémoire/fichier/ORM/Redis) ;
+ * un `if (name === "redis")` trahirait cette promesse. Les builtins sans
+ * dépendance (`memory`) s'enregistrent au chargement du module ; les adapters
+ * lourds (`drizzle`, `mongoose`, `redis`) s'enregistrent depuis LEUR module
+ * (inversion de dépendance : ils importent `import type { ITokenStore }`, effacé
+ * à la compilation). Convention-frère : `authenticatorRegistry`, `ormRegistry`,
+ * `SessionsService.registerStorage`.
+ */
+/**
+ * Contexte passé à une fabrique de store : de quoi se construire (résolutions
+ * coûteuses en lazy à l'intérieur de l'instance).
+ */
+export interface ITokenStoreFactoryContext {
+    /** Container DI — résolution de services (ORM, redis...). */
+    readonly container: Container;
+    /** Config sécurité validée + gelée. */
+    readonly config: ISecurityConfig;
+}
+/** Fabrique d'un store de jetons pour un nom donné. */
+export type TokenStoreFactory = (ctx: ITokenStoreFactoryContext) => ITokenStore;
+/**
+ * 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.
+ */
+export declare function registerTokenStore(name: string, factory: TokenStoreFactory): void;
+/** Fabrique d'un store par nom, ou `undefined` si inconnu. */
+export declare function getTokenStoreFactory(name: string): TokenStoreFactory | undefined;
+/** Noms enregistrés (validation boot, introspection Studio, tests). */
+export declare function listTokenStores(): string[];

package/dist/types/nodefony/src/totp/MemoryTotpSecretStore.d.ts

@@ -0,0 +1,43 @@
+import type { IPage } from "nodefony";
+import type { ITotpSecret } from "../../contracts/ITotpSecret.js";
+import type { ITotpEnrollmentSummary, ITotpListQuery, ITotpSecretStore, TotpSecretUpdate } from "../../contracts/ITotpSecretStore.js";
+/**
+ * Projette un secret en vue d'introspection — **le seul endroit** où l'on
+ * décide ce qui sort d'un store TOTP en mémoire. `secretEnc` et les condensats
+ * des codes de récupération n'y figurent pas : seul leur NOMBRE est exposé.
+ *
+ * @param secret - le secret stocké.
+ * @returns la vue publique de l'enrôlement.
+ */
+export declare function toTotpEnrollment(secret: ITotpSecret): ITotpEnrollmentSummary;
+/** Applique les filtres d'{@link ITotpListQuery} — sémantique de RÉFÉRENCE. */
+export declare function matchesTotpQuery(secret: ITotpSecret, query: ITotpListQuery): boolean;
+/** Instantané sérialisable de l'état — base de la persistance fichier. */
+export interface TotpStoreSnapshot {
+    secrets: ITotpSecret[];
+}
+/**
+ * Store de secrets TOTP **en mémoire** — implémentation de référence
+ * d'{@link ITotpSecretStore}. Clé = `userId` (un secret par utilisateur).
+ *
+ * 0 dépendance, idéale pour le développement mono-process et les **tests**. NON
+ * partagée entre process et **volatile** → en production multi-process, utiliser
+ * un adapter ORM ou Redis. Perf : la `Map` n'existe que si le store est instancié
+ * (2FA activé), jamais sur le hot path par requête.
+ */
+export declare class MemoryTotpSecretStore implements ITotpSecretStore {
+    #private;
+    findByUser(userId: string): Promise<ITotpSecret | null>;
+    save(secret: ITotpSecret): Promise<void>;
+    update(userId: string, patch: TotpSecretUpdate): Promise<void>;
+    delete(userId: string): Promise<void>;
+    /** {@inheritDoc ITotpSecretStore.listPage} */
+    listPage(query: ITotpListQuery): Promise<IPage<ITotpEnrollmentSummary>>;
+    /** {@inheritDoc ITotpSecretStore.countEnrollments} */
+    countEnrollments(query: ITotpListQuery): Promise<number>;
+    /** Instantané sérialisable de l'état courant (pour la persistance fichier). */
+    snapshot(): TotpStoreSnapshot;
+    /** Remplace l'état par celui d'un instantané. */
+    restore(snapshot: TotpStoreSnapshot): void;
+}
+export default MemoryTotpSecretStore;