@nodefony/security 10.0.0-alpha.1

package/dist/types/nodefony/contracts/IAuthorizationService.d.ts

@@ -0,0 +1,28 @@
+import type { IToken } from "./IToken.js";
+/**
+ * Service d'autorisation (niveau C de la sécurité, P6) — décide si un token a le
+ * droit d'effectuer une action (`attribute`) sur un sujet (`subject`).
+ *
+ * Distinct de l'authentification (firewall = *QUI es-tu*) : l'autorisation
+ * répond *PEUX-tu faire ça* via un jury de {@link IAccessVoter} agrégé en
+ * **affirmative + DENY veto** (un seul `DENY` bloque ; sinon un `GRANT` suffit ;
+ * silence total → `DENY`, Zero Trust).
+ *
+ * Consommé par les décorateurs (`@IsGranted`, J7) au hook `beforeResolve`, et
+ * par le verrou de frame WS (« 1 garde = N transports ») : la même décision sert
+ * REST et socket sans double implémentation.
+ */
+export interface IAuthorizationService {
+    /**
+     * Le token a-t-il le droit demandé ? `false` = accès refusé (le caller
+     * répond 403).
+     *
+     * @param token - identité résolue par le firewall (jamais `null` — anonyme inclus).
+     * @param attribute - droit demandé : un rôle (`"ROLE_ADMIN"`), une permission
+     *   (`"PERM_project_edit"`) ou un attribut métier libre (`"project.edit"`).
+     * @param subject - objet ciblé (entité, canal, path…) — passé aux voters
+     *   contextuels (ownership, multi-tenant). `undefined` pour un droit global.
+     * @returns `true` si accordé, `false` sinon (DENY veto, ou aucun GRANT).
+     */
+    decide(token: IToken, attribute: string, subject?: unknown): Promise<boolean>;
+}

package/dist/types/nodefony/contracts/IFirewall.d.ts

@@ -0,0 +1,64 @@
+import type { ContextType } from "@nodefony/http";
+import type { IAuthenticator } from "./IAuthenticator.js";
+import type { ISecuredArea } from "./ISecuredArea.js";
+import type { CspFragment } from "../src/csp.js";
+import type { IFirewallDescription, IRoleHierarchyDescription } from "./IFirewallDescription.js";
+import type { IProtectedResourceInput } from "nodefony";
+/**
+ * Orchestrateur de sécurité — branché dans le pipeline HTTP/WS de `@nodefony/http`.
+ *
+ * `isSecure()` (rapide, hot-path) ne fait QUE matcher la zone et poser
+ * `context.security`. `handleSecurity()` (lazy, seulement si la requête est dans
+ * une zone) exécute CORS → headers → authenticators → Zero Trust → CSRF.
+ */
+export interface IFirewall {
+    /** Match rapide de zone (pose `context.security`). `true` si zone capturée. */
+    isSecure(context: ContextType): boolean;
+    /** Pipeline complet d'authentification de la zone. Rejette (401/403) ou résout. */
+    handleSecurity(context: ContextType): Promise<ContextType>;
+    /**
+     * Défense CSRF (Fetch Metadata + repli Origin) sur les méthodes state-changing.
+     * No-op sur les méthodes sûres et hors navigateur. Lève `CsrfError` (403) sinon.
+     */
+    enforceCsrf(context: ContextType): void;
+    /**
+     * Politique CORS : pose les en-têtes `Access-Control-*`. Retourne `204` pour un
+     * preflight `OPTIONS` (à court-circuiter), sinon `undefined`. No-op hors CORS.
+     */
+    handleCors(context: ContextType): number | undefined;
+    /**
+     * Pose les en-têtes de sécurité applicatifs (CSP, Referrer-Policy, COOP/COEP/
+     * CORP, Permissions-Policy) sur la réponse. No-op si désactivés / hors HTTP.
+     */
+    applySecurityHeaders(context: ContextType): void;
+    /**
+     * Déclare des directives CSP additionnelles pour un module (ex. `@nodefony/frontend`
+     * en dev : origines Vite + `'unsafe-eval'`). Fusionnées dans le CSP de base et
+     * recomposées (re-split nonce) au (dé)enregistrement — jamais par requête.
+     */
+    registerCspOrigins(moduleName: string, fragment: CspFragment): void;
+    /** Retire les directives CSP d'un module (ex. `stopDev` du frontend). */
+    unregisterCspOrigins(moduleName: string): void;
+    /** Enregistre un authenticator (appelé par chaque `*Authenticator` au boot). */
+    registerAuthenticator(authenticator: IAuthenticator): void;
+    /** Zone par nom, ou `undefined`. */
+    getArea(name: string): ISecuredArea | undefined;
+    /**
+     * Projection LECTURE SEULE de l'état RUNTIME (zones/authenticators/défenses)
+     * pour le data plane Studio — **secrets exclus** (présence, jamais valeur).
+     * Décrit ce qui TOURNE (pas la config brute). Source de vérité d'introspection.
+     */
+    describe(): IFirewallDescription;
+    /** Hiérarchie de rôles déclarée + résolution transitive (data plane Studio). */
+    describeRoleHierarchy(): IRoleHierarchyDescription;
+    /**
+     * Ressources protégées à publier en RFC 9728 — une par `area.resource`
+     * déclarée, avec les émetteurs de confiance comme serveurs d'autorisation.
+     *
+     * Consommée par `@nodefony/framework` (contrat STRUCTUREL, par nom de
+     * service : framework ne dépend jamais de security) pour monter les documents
+     * que le défi d'un `401` désigne. C'est la MÊME donnée des deux côtés — le
+     * pointeur et le document ne peuvent donc pas diverger.
+     */
+    publishedProtectedResources(): readonly IProtectedResourceInput[];
+}

package/dist/types/nodefony/contracts/IFirewallDescription.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Surface d'INTROSPECTION du firewall (data plane Studio P6.15) — projection
+ * LECTURE SEULE de l'état RUNTIME réel du {@link IFirewall} (zones montées,
+ * authenticators instanciés, défenses résolues), **secrets exclus par
+ * construction** (présence, jamais valeur — règle audit). Distincte de la config
+ * brute : on décrit ce qui TOURNE, pas ce que l'app a écrit (un nom
+ * d'authenticator en typo n'apparaît pas comme « monté »).
+ *
+ * Le front Studio en tient des **types miroir locaux** (frontière isomorphe :
+ * jamais d'import runtime `@nodefony/security` dans le bundle navigateur).
+ */
+/** Une zone sécurisée telle que montée au boot (pattern compilé → source). */
+export interface IFirewallZoneDescription {
+    /** Nom de la zone (`"nodefony-admin"`…). */
+    name: string;
+    /** Pattern d'URL (`RegExp.source`) capturé par la zone. */
+    pattern: string;
+    /** Zone protégée (Zero Trust) ; `false` = zone publique explicite. */
+    security: boolean;
+    /** `true` = chaque requête porte sa preuve (JWT/clé) ; `false` = session BFF possible. */
+    stateless: boolean;
+    /** Chaîne d'authenticators : `first` (le premier qui reconnaît) ou `all` (MFA). */
+    mode: "first" | "all";
+    /** Noms des authenticators exécutés par la zone (sémantique selon `mode`). */
+    authenticators: readonly string[];
+    /** Le pattern `anonymous` est-il listé (anonymat explicite autorisé) ? */
+    allowsAnonymous: boolean;
+    /** Domaine/vhost de la zone, ou `null` (tous domaines). */
+    host: string | null;
+    /** Zone valable aussi pour les frames WebSocket (api.request + subscribe). */
+    realtime: boolean;
+}
+/** Un authenticator : disponible (registre de fabriques) et/ou monté (≥1 zone). */
+export interface IFirewallAuthenticatorDescription {
+    /** Nom logique (`anonymous`/`userpassword`/`session`/`jwt`/`apikey`…). */
+    name: string;
+    /** Référencé par ≥1 zone → instancié au boot (actif sur le pipeline). */
+    mounted: boolean;
+    /** Présent dans le registre de fabriques (utilisable en config). */
+    available: boolean;
+    /** Déclare un challenge `WWW-Authenticate` (RFC 7235). */
+    challenge: boolean;
+}
+/** Défenses transverses résolues (CSRF/CORS/headers/throttle) — sans secret. */
+export interface IFirewallDefensesDescription {
+    csrf: {
+        enabled: boolean;
+        /** Défense primaire Fetch Metadata (`Sec-Fetch-Site`). */
+        fetchMetadata: boolean;
+        /** Repli Origin/Referer (vieux navigateurs). */
+        checkOrigin: boolean;
+        /** Politique stricte same-origin only (multi-tenant). */
+        strictSameSite: boolean;
+        /** Attribut cookie `SameSite`. */
+        sameSite: "Strict" | "Lax" | "None";
+        /** Alias d'origine légitimes (façades multi-domaine). */
+        trustedOrigins: readonly string[];
+        /** Synchronizer token `@CsrfProtect` armé (secret présent OU éphémère dev) — PRÉSENCE, jamais le secret. */
+        synchronizerToken: boolean;
+    };
+    cors: {
+        enabled: boolean;
+        origins: readonly string[];
+        credentials: boolean;
+        methods: readonly string[];
+        allowedHeaders: readonly string[];
+        exposedHeaders: readonly string[];
+        maxAgeS: number;
+    };
+    headers: {
+        enabled: boolean;
+        /** ⚙️ posé par @nodefony/http (transport) — reflété ici pour information. */
+        hsts: boolean;
+        hstsMaxAgeS: number;
+        /** Policy CSP (template `{{nonce}}`) — politique publique, pas un secret. */
+        csp: string;
+        cspNonces: boolean;
+        frameguard: "deny" | "sameorigin";
+        noSniff: boolean;
+        referrerPolicy: string;
+        coop?: string;
+        coep?: string;
+        corp?: string;
+        originAgentCluster?: boolean;
+        permissionsPolicy?: string;
+    };
+    rateLimit: {
+        enabled: boolean;
+        freeAttempts: number;
+        baseDelayS: number;
+        capDelayS: number;
+    };
+}
+/** Photo complète de l'état du firewall. */
+export interface IFirewallDescription {
+    /** Config sécurité valide au boot (sinon le firewall est fail-closed). */
+    configValid: boolean;
+    /** Message d'erreur de config si fail-closed, sinon `null` (jamais de stack — Zero Trust). */
+    configError: string | null;
+    /** Zones montées, triées par spécificité (pattern le plus long d'abord). */
+    zones: IFirewallZoneDescription[];
+    /** Authenticators disponibles/montés (union registre ∪ instanciés). */
+    authenticators: IFirewallAuthenticatorDescription[];
+    /** Défenses résolues, ou `null` si la config est invalide. */
+    defenses: IFirewallDefensesDescription | null;
+}
+/** Un rôle déclaré + ses rôles hérités (résolution transitive du walker). */
+export interface IRoleDescription {
+    /** Rôle déclaré (clé de la hiérarchie). */
+    role: string;
+    /** Tous les rôles atteignables transitivement (hors le rôle lui-même), triés. */
+    inherits: string[];
+}
+/** Hiérarchie de rôles : déclaration brute + résolution aplatie. */
+export interface IRoleHierarchyDescription {
+    /** Déclaration directe (`{ ROLE_ADMIN: ["ROLE_USER"] }`). */
+    hierarchy: Record<string, string[]>;
+    /** Résolution transitive précalculée par le {@link RoleHierarchyWalker}. */
+    roles: IRoleDescription[];
+}

package/dist/types/nodefony/contracts/IJwtKeystore.d.ts

@@ -0,0 +1,40 @@
+import type { JSONWebKeySet } from "jose";
+/**
+ * Clé active de signature résolue par le keystore — la clé privée Ed25519 plus
+ * son `kid` (à poser dans l'en-tête JWT) et l'algorithme JWA.
+ */
+export interface IJwtSigningKey {
+    /** Clé privée Ed25519 (WebCrypto `CryptoKey`) qui signe les jetons. */
+    readonly key: CryptoKey;
+    /** Identifiant de clé = thumbprint RFC 7638 → en-tête JWT `kid` (sélection au verify). */
+    readonly kid: string;
+    /** Algorithme JWA — toujours `"EdDSA"` pour une clé Ed25519 (RFC 8037). */
+    readonly alg: "EdDSA";
+}
+/**
+ * Source du matériel cryptographique de signature des JWT.
+ *
+ * Découple la SIGNATURE de toute persistance concrète : la clé peut venir de
+ * l'environnement (prod cloud), d'un fichier (dev/VPS) ou être éphémère en
+ * mémoire (dev jetable) — le {@link IJwtSigningKey} et le JWKS public exposés
+ * sont identiques. Un keyset porte N clés (rotation) : une seule **signe** (la
+ * clé active), **toutes vérifient** (les jetons en vol signés par une clé encore
+ * présente restent valides).
+ *
+ * ⚠️ Le keystore détient des clés privées — jamais loggué, jamais sérialisé hors
+ * du backend choisi. Le JWKS exposé ne porte QUE des paramètres publics (RFC 8037 /
+ * 7517) : `kty/crv/x/kid/use/alg`, **jamais `d`**.
+ */
+export interface IJwtKeystore {
+    /**
+     * Clé active de signature. Résout (charge ou génère) le keyset au PREMIER
+     * appel (lazy async, mémoïsé) — le coût de boot est nul si le JWT n'est jamais
+     * émis.
+     */
+    getSigningKey(): Promise<IJwtSigningKey>;
+    /**
+     * JWKS **public** (toutes les clés du keyset, paramètres publics uniquement) —
+     * passé à `createLocalJWKSet` pour résoudre la clé de vérification par `kid`.
+     */
+    getPublicJWKS(): Promise<JSONWebKeySet>;
+}

package/dist/types/nodefony/contracts/IOAuthProvider.d.ts

@@ -0,0 +1,51 @@
+import type { OAuth2Tokens } from "arctic";
+import type { IOAuthProfile } from "@nodefony/user";
+/**
+ * Adaptateur d'**un fournisseur OAuth/OIDC**, façade UNIFORME au-dessus d'une
+ * classe `arctic` — masque les divergences entre fournisseurs derrière un contrat
+ * stable consommé par `OAuth2Service` :
+ *
+ * - **PKCE ou non** : Google attend `createAuthorizationURL(state, codeVerifier,
+ *   scopes)` ; GitHub `createAuthorizationURL(state, scopes)` (pas de
+ *   `codeVerifier`). Le flag {@link usesPkce} dit au service s'il doit générer un
+ *   `code_verifier` (RFC 7636).
+ * - **Extraction du profil** : OIDC décode l'ID token (Google) ; non-OIDC appelle
+ *   l'API du fournisseur (GitHub `/user`). Le résultat est toujours normalisé en
+ *   {@link IOAuthProfile}.
+ *
+ * @remarks `arctic` n'est référencé ici qu'en **type** (`import type`, effacé à la
+ * compilation) — l'instance runtime est chargée paresseusement par le service et
+ * injectée aux fabriques. Aucune dépendance runtime n'entre par ce contrat.
+ */
+export interface IOAuthProvider {
+    /**
+     * `true` si le fournisseur exige PKCE (RFC 7636) — le service génère alors un
+     * `code_verifier` et le transmet aux deux méthodes ci-dessous.
+     */
+    readonly usesPkce: boolean;
+    /**
+     * Identifiant d'émetteur attendu pour la défense anti-mix-up (RFC 9207), ou
+     * `null` si le fournisseur n'émet pas le paramètre `iss` (ex. GitHub, non-OIDC).
+     * Quand non-`null`, le service **rejette** une réponse dont l'`iss` diffère ou
+     * manque.
+     */
+    readonly expectedIssuer: string | null;
+    /** Scopes appliqués quand la configuration n'en précise aucun. */
+    readonly defaultScopes: string[];
+    /**
+     * Construit l'URL d'autorisation (étape 1). `codeVerifier` est non-`null`
+     * lorsque {@link usesPkce} ; les fournisseurs sans PKCE l'ignorent.
+     */
+    createAuthorizationURL(state: string, codeVerifier: string | null, scopes: string[]): URL;
+    /**
+     * Échange le `code` d'autorisation contre des jetons (étape 2, canal serveur).
+     * `codeVerifier` doit correspondre à celui de l'étape 1 si {@link usesPkce}.
+     */
+    validateAuthorizationCode(code: string, codeVerifier: string | null): Promise<OAuth2Tokens>;
+    /**
+     * Récupère et **normalise** le profil de l'utilisateur à partir des jetons.
+     *
+     * @throws Si le fournisseur ne renvoie pas d'identifiant stable.
+     */
+    fetchProfile(tokens: OAuth2Tokens): Promise<IOAuthProfile>;
+}

package/dist/types/nodefony/contracts/ISecuredArea.d.ts

@@ -0,0 +1,57 @@
+import type { ContextType } from "@nodefony/http";
+/**
+ * Zone sécurisée — un pattern d'URL + la liste des authenticators à exécuter.
+ *
+ * Le firewall teste chaque zone par ordre de spécificité ; la première dont le
+ * pattern matche capture la requête (`context.security`). Les zones viennent de
+ * `defineSecurityConfig({ areas })` — patterns compilés et triés au boot, conflits
+ * détectés au boot (pas au premier match runtime).
+ */
+export interface ISecuredArea {
+    /** Nom de la zone (`"main_api"`, `"admin"`…). */
+    readonly name: string;
+    /** Pattern d'URL compilé. */
+    readonly pattern: RegExp;
+    /** Zone protégée (Zero Trust) ; `false` = zone publique explicite. */
+    readonly security: boolean;
+    /**
+     * Stratégie d'identité AU-DESSUS du protocole. `false` (défaut) : registre
+     * serveur autorisé — session créée AU LOGIN, cookie opaque révocable (BFF).
+     * `true` : chaque requête porte sa preuve complète (JWT/clé API), session ignorée.
+     */
+    readonly stateless: boolean;
+    /**
+     * Sémantique de la chaîne : `"first"` = le premier authenticator qui
+     * reconnaît la requête authentifie ; `"all"` = tous doivent passer (MFA —
+     * le DERNIER porte l'identité).
+     */
+    readonly mode: "first" | "all";
+    /** Noms des authenticators à exécuter (sémantique selon {@link mode}). */
+    readonly authenticators: readonly string[];
+    /** Domaine/vhost de la zone (ex. `admin.exemple.com`). Omis = tous domaines. */
+    readonly host?: string;
+    /**
+     * URI canonique de la ressource protégée par cette zone — l'**audience**
+     * qu'un jeton doit porter pour y être accepté (RFC 8707 §2).
+     *
+     * Exigée par les authenticators qui vérifient un jeton émis AILLEURS : c'est
+     * la seule chose qui empêche un jeton parfaitement valide, délivré au même
+     * porteur pour un autre service, d'être rejoué ici. Elle s'ÉCRIT et ne se
+     * dérive pas de l'en-tête `Host` — derrière un relais, ce que le processus
+     * croit être son adresse n'est pas ce que le client a demandé, et l'audience
+     * doit être celle que le serveur d'autorisation a inscrite dans le jeton.
+     *
+     * Omise, une zone reste parfaitement utilisable par les authenticators qui
+     * n'en ont pas besoin (session, mot de passe, jetons maison).
+     */
+    readonly resource?: string;
+    /**
+     * Zone valable AUSSI pour le WebSocket (frames `api.request` + `subscribe`),
+     * pas seulement HTTP. Défaut `true` (Zero Trust : une zone protégée ferme TOUS
+     * ses transports) ; `false` = opt-out explicite (zone strictement HTTP). Le
+     * verrou WS consulte la même zone que HTTP (invariant `api.request` ≤ `GET`).
+     */
+    readonly realtime: boolean;
+    /** La requête tombe-t-elle dans cette zone ? (pattern + host éventuel). */
+    match(context: ContextType): boolean;
+}

package/dist/types/nodefony/contracts/IToken.d.ts

@@ -0,0 +1,41 @@
+import type { IUser } from "@nodefony/user";
+/**
+ * Jeton de sécurité — porte l'identité (authentifiée ou non) d'une requête.
+ *
+ * Produit par un {@link IAuthenticator}, propagé via ALS (`RequestContext`) pour
+ * tout le pipeline. Ne contient JAMAIS de credential brut après authentification :
+ * `getCredentials()` est vidé par l'authenticator au succès (anti-fuite mémoire).
+ *
+ * Zero Trust : un visiteur non authentifié reçoit quand même un token (porteur de
+ * l'`AnonymousUser`, `isAuthenticated() === false`) — `getUser()` ne renvoie jamais `null`.
+ */
+export interface IToken {
+    /** Type du token (`"anonymous"`, `"userpassword"`, `"jwt"`, `"oauth2"`, `"mtls"`). */
+    readonly type: string;
+    /** Utilisateur porté — jamais `null` (AnonymousUser si non authentifié). */
+    getUser(): IUser;
+    /**
+     * Identifiant logique de l'utilisateur (`"anonymous"`, `"admin"`…) — partagé
+     * avec `IRealtimeToken` (le token WS, sous-ensemble transport-neutre, n'a PAS
+     * `getUser()`). Le service `authorization` ne lit QUE ce commun → la garde
+     * `@IsGranted` fonctionne à l'identique sur HTTP et WebSocket (« 1 garde = N
+     * transports »).
+     */
+    getUserIdentifier(): string;
+    /** `true` si l'authentification a réussi (≠ anonyme). */
+    isAuthenticated(): boolean;
+    /** Rôles **plats** de l'utilisateur (sans hiérarchie résolue). */
+    getRoles(): string[];
+    /** Credential brut avant validation (vidé au succès). */
+    getCredentials(): unknown;
+    /**
+     * Scopes accordés (clé API / OAuth) — axe **distinct** des rôles RBAC.
+     * Ex. `["repo:read", "user:email"]`. `[]` si aucun. Permet `@RequireScope(...)`
+     * sans confondre avec `@IsGranted('ROLE_*')` (cf GitHub PAT / OAuth scopes).
+     */
+    getScopes(): string[];
+    /** Lecture d'un attribut arbitraire posé par l'authenticator (claims JWT, scopes…). */
+    getAttribute<T = unknown>(key: string): T | undefined;
+    /** Pose un attribut arbitraire (claims, scopes, providerId…). */
+    setAttribute(key: string, value: unknown): void;
+}

package/dist/types/nodefony/contracts/ITokenStore.d.ts

@@ -0,0 +1,240 @@
+/**
+ * État serveur des jetons longue durée (PAT, refresh tokens), denylist des access
+ * tokens révoqués (`jti`) et seuil de révocation **en masse** par porteur.
+ *
+ * Pourquoi un store : un access token signé (JWT) est auto-porté et **non
+ * révocable** avant son `exp`. La sécurité « révocable » du mode hybride (logout
+ * partout, ban, fuite, rotation de refresh) **exige** un état serveur — RFC 9700
+ * §4.14 (rotation + détection de rejeu) + liaison scope/ressource du refresh.
+ * **Pluggable** par backend (mémoire/fichier/ORM/Redis) comme les stores de session.
+ *
+ * Trois structures complémentaires :
+ *  1. **records** ({@link IAccessTokenRecord}) — PAT + refresh persistants ;
+ *  2. **denylist `jti`** — révocation ciblée d'UN access avant son `exp` ;
+ *  3. **seuil par porteur** (`invalidBefore`) — révocation EN MASSE (tout access
+ *     auto-porté émis avant un instant T est rejeté → « déconnexion globale » / ban).
+ */
+import type { IPage, IPageQuery, ISortableSource } from "nodefony";
+/** Raison de révocation d'un jeton — tracée pour l'audit de sécurité. */
+export type TokenRevokeReason = "logout" | "rotated" | "reuse_detected" | "manual" | "compromised" | "subject_disabled" | "expired_cleanup";
+/**
+ * Permission **fine-grained** sur une ressource (modèle GitHub fine-grained PAT).
+ *
+ * **Slot** : non exploité tant que les scopes simples suffisent ; la colonne
+ * existe dès maintenant pour éviter une migration le jour où on l'active.
+ */
+export interface IResourcePermission {
+    /** Type de ressource (ex. `"repo"`, `"project"`). */
+    type: string;
+    /** Identifiants ciblés (omis = toutes les ressources de ce type). */
+    ids?: string[];
+    /** Permissions accordées sur ces ressources. */
+    perms: Array<"read" | "write">;
+}
+/** Contexte d'un usage de jeton (audit « last used »). */
+export interface ITokenUsage {
+    /** Instant d'usage (epoch ms). */
+    at: number;
+    /** IP source, si disponible. */
+    ip?: string | null;
+    /** User-Agent source, si disponible. */
+    userAgent?: string | null;
+}
+/**
+ * Enregistrement d'un jeton persistant — un PAT (clé API style GitHub) ou un
+ * refresh token. Le secret n'est JAMAIS stocké en clair : seul `secretHash` vit
+ * ici (le secret high-entropy est affiché une seule fois à la création).
+ *
+ * Modèle **single-table** : un même schéma porte PAT et refresh ; les champs non
+ * pertinents pour un `kind` valent `null` (ex. `family`/`audience` pour un PAT,
+ * `prefix` pour un refresh opaque). Horodatages en epoch **millisecondes**
+ * (`Date.now()`) ; les claims JWT (secondes, RFC 7519 NumericDate) sont dérivés
+ * à la signature.
+ *
+ * `AccessTokenRow` (forme renvoyée par les repositories ORM) est **identique** à
+ * cette interface → zéro mapping entre le store et l'entité.
+ */
+export interface IAccessTokenRecord {
+    /** Identifiant unique : claim `jti` (refresh) / id public (PAT). */
+    id: string;
+    /** Nature : clé API personnelle (`pat`) ou refresh token (`refresh`). */
+    kind: "pat" | "refresh";
+    /** Libellé humain (« CI deploy », « app mobile ») — affiché dans la console. */
+    name: string;
+    /** Préfixe public affichable (« nf_a1b2c3… ») pour l'UI/lookup ; `null` pour un refresh opaque. */
+    prefix: string | null;
+    /**
+     * Identité du porteur (id d'un utilisateur OU d'un service account).
+     *
+     * ⚠️ **Référence souple volontaire, pas une FK SQL `REFERENCES User(id)`** :
+     *  (1) le porteur est **polymorphe** (`subjectType` user|service, futurs agents) —
+     *      une FK ne pointe que vers une table ;
+     *  (2) le store est **pluggable multi-backend** (tokens Redis/Mongo, users SQL) —
+     *      une FK exigerait même base + même moteur ;
+     *  (3) **découplage modules** — l'entité vit dans `@nodefony/security`, `User`
+     *      dans `@nodefony/user` (user custom permis, `IUser.id` = `string|number`).
+     * Intégrité assurée **à l'usage** (`userProvider.load(subjectId)` → porteur
+     * disparu = jeton rejeté) ; suppression/ban gérés par `revokeAllForSubject`
+     * (révoque + audite + cross-backend, > un `ON DELETE CASCADE`).
+     */
+    subjectId: string;
+    /** Discriminant du porteur (humain vs machine). */
+    subjectType: "user" | "service";
+    /** Organisation/tenant (multi-tenant, façon orgs GitHub) — axe distinct du porteur ; `null` = global. */
+    tenantId: string | null;
+    /** Capacités accordées à ce jeton (⊆ droits du porteur — downscoping). Ex. `["orders:read"]`. */
+    scopes: string[];
+    /** Audiences liées (claim `aud`, RFC 8707/9700) ; `[]` = audience de l'app. Liaison conservée à la rotation. */
+    audience: string[];
+    /** Permissions fine-grained (slot GitHub) ; `null` = portée par les seuls `scopes`. */
+    resources: IResourcePermission[] | null;
+    /** Hash du secret présenté (jamais le secret) — clé de {@link ITokenStore.findByHash}. */
+    secretHash: string;
+    /** Algorithme de hachage du secret (agilité crypto, migration future). Ex. `"sha256"`. */
+    hashAlg: string;
+    /** Client OAuth émetteur (slot OAuth2/arctic) ; `null` = non-OAuth. */
+    clientId: string | null;
+    /** Confirmation sender-constrained : `jkt` (DPoP RFC 9449) / `x5t#S256` (mTLS RFC 8705) ; `null` = bearer simple. */
+    cnf: string | null;
+    /** Famille de rotation : un refresh tourné conserve la famille (reuse detection) ; `null` pour un PAT. */
+    family: string | null;
+    /** `id` du successeur après rotation (chaîne d'audit) ; `null` = feuille active. */
+    replacedBy: string | null;
+    /** Création (epoch ms). */
+    createdAt: number;
+    /** Expiration (epoch ms) ; `null` = sans expiration (PAT longue durée). */
+    expiresAt: number | null;
+    /** Dernier usage (epoch ms) ou `null`. */
+    lastUsedAt: number | null;
+    /** IP du dernier usage (audit « last used from ») ; slot. */
+    lastUsedIp: string | null;
+    /** User-Agent du dernier usage (audit) ; slot. */
+    lastUsedUserAgent: string | null;
+    /** Instant de révocation (epoch ms) ou `null` si actif. */
+    revokedAt: number | null;
+    /** Raison de révocation (audit) ou `null`. */
+    revokedReason: TokenRevokeReason | null;
+    /** Extras applicatifs libres (anti-migration), `{}` par défaut. */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Requête de **listing paginé** de jetons (data plane admin) — le contrat de page
+ * standard du core ({@link IPageQuery}) enrichi des filtres propres aux jetons.
+ * Tous **portables** au `Criteria` (`subjectId` indexé, colonnes simples) → pas de
+ * SQL natif, le helper `paginate()` d'orm-core suffit côté ORM.
+ */
+export interface ITokenListQuery extends IPageQuery {
+    /** Restreint à un porteur (indexé). Omis = tous porteurs. */
+    subjectId?: string;
+    /** Restreint à une nature de jeton. Omis = PAT **et** refresh. */
+    kind?: "pat" | "refresh";
+    /**
+     * Restreint à un **état de vie** du jeton. Omis = tous.
+     *
+     * Les trois valeurs **partitionnent** la collection (tout jeton en a
+     * exactement un) et sont évaluées dans cet ordre : révoqué l'emporte sur
+     * expiré, comme dans la console — une clé révoquée puis arrivée à échéance
+     * reste « révoquée », c'est l'acte d'administration qui compte.
+     *
+     * | Valeur    | Signification                                      |
+     * | --------- | -------------------------------------------------- |
+     * | `revoked` | `revokedAt` renseigné                              |
+     * | `expired` | non révoqué, `expiresAt` dépassé                   |
+     * | `active`  | non révoqué, et sans échéance ou échéance à venir  |
+     *
+     * Remplace l'ancien filtre `revoked` : deux vocabulaires pour le même axe
+     * (« révoqué ou non » et « quel état ») auraient permis `?revoked=false` +
+     * `?status=revoked`, une contradiction qu'un store aurait dû arbitrer — c'est
+     * exactement le défaut qui a rendu des compteurs faux ailleurs.
+     *
+     * **Non portable au `Criteria` générique** : `active` demande « sans échéance
+     * OU échéance future », un OU que le critère AND-only n'exprime pas. Chaque
+     * backend l'implémente donc nativement, comme le filtre `event` des webhooks.
+     */
+    status?: TokenStatus;
+}
+/** État de vie d'un jeton — partition exhaustive, évaluée révoqué → expiré → actif. */
+export type TokenStatus = "active" | "expired" | "revoked";
+/**
+ * Contrat du store de jetons — implémentations enregistrées via
+ * `registerTokenStore`, sélectionnées par config. Toutes les opérations sont
+ * **asynchrones** (un backend ORM/Redis fait des I/O ; la référence mémoire
+ * résout immédiatement).
+ *
+ * Les lectures (`findBy*`) renvoient l'enregistrement **brut** (même révoqué ou
+ * expiré) — la **politique** (rejet, déclenchement de la détection de rejeu) est
+ * du ressort de l'appelant, pas du stockage.
+ */
+export interface ITokenStore extends ISortableSource {
+    /** Enregistre (ou remplace) un jeton persistant. */
+    put(record: IAccessTokenRecord): Promise<void>;
+    /** Recherche par identifiant (`jti`/id public). `null` si absent. */
+    findById(id: string): Promise<IAccessTokenRecord | null>;
+    /** Recherche par hash de secret présenté. `null` si absent. */
+    findByHash(secretHash: string): Promise<IAccessTokenRecord | null>;
+    /** Tous les jetons d'un porteur (console « mes jetons », révocation ciblée). */
+    findBySubject(subjectId: string): Promise<IAccessTokenRecord[]>;
+    /**
+     * **Tous** les jetons du store, tous porteurs confondus — vue
+     * d'ADMINISTRATION cross-porteur (gouvernance / réponse à incident).
+     *
+     * ⚠️ Énumération COMPLÈTE : opération de cold-path réservée à la console admin
+     * (RBAC `ROLE_NODEFONY_ADMIN`), jamais sur le hot-path d'authentification. Un
+     * backend distribué (Redis) l'implémente par SCAN ; à grande échelle, paginer
+     * en amont. Renvoie les records BRUTS (la projection « sans secret » est du
+     * ressort de l'appelant — `ApiKeyService.listAllPat`).
+     */
+    listAll(): Promise<IAccessTokenRecord[]>;
+    /**
+     * Liste **paginée** de jetons pour le data plane admin — ne matérialise **jamais**
+     * plus d'une page (contrairement à {@link ITokenStore.listAll}, réservé au dump
+     * d'incident). Filtres {@link ITokenListQuery} appliqués au store.
+     *
+     * Capacité par backend : **offset + total** (SQL/Mongo/mémoire, tri `createdAt`
+     * DESC déterministe + tiebreaker `id`) ; **curseur** (`nextCursor`, Redis SCAN —
+     * sans total ni ordre global, capacité réduite annoncée). Renvoie les records
+     * BRUTS (la projection « sans secret » = ressort de l'appelant).
+     */
+    listPage(query: ITokenListQuery): Promise<IPage<IAccessTokenRecord>>;
+    /**
+     * Compte les jetons correspondant aux filtres — base du `total` de la page
+     * (SQL/Mongo `COUNT`, mémoire `length`). Redis : `-1` (comptage O(N) refusé).
+     */
+    countTokens(query: ITokenListQuery): Promise<number>;
+    /** Met à jour `lastUsedAt`/IP/UA (no-op si l'id est inconnu). */
+    markUsed(id: string, usage: ITokenUsage): Promise<void>;
+    /** Révoque un jeton (pose `revokedAt`+`revokedReason`) — idempotent. */
+    revoke(id: string, reason: TokenRevokeReason): Promise<void>;
+    /** Révoque TOUTE la famille de rotation (détection de rejeu, RFC 9700). */
+    revokeFamily(family: string, reason: TokenRevokeReason): Promise<void>;
+    /**
+     * Inscrit un `jti` d'access sur la denylist jusqu'à `expiresAt` (epoch ms) —
+     * révocation immédiate avant l'`exp` du JWT. Au-delà, l'entrée est inutile.
+     */
+    denyJti(jti: string, expiresAt: number): Promise<void>;
+    /** `true` si le `jti` est denylisté et non encore expiré. */
+    isJtiDenied(jti: string): Promise<boolean>;
+    /**
+     * Pose le seuil `invalidBefore` (epoch ms) d'un porteur : tout access auto-porté
+     * dont `iat < invalidBefore` est rejeté. Couvre les JWT non stockés sans
+     * denylister chaque `jti` (refresh/PAT se révoquent via `revoke`/`revokeFamily`).
+     */
+    revokeAllForSubject(subjectId: string, invalidBefore: number): Promise<void>;
+    /** Seuil `invalidBefore` d'un porteur (epoch ms) ou `null` si aucun. */
+    getInvalidBefore(subjectId: string): Promise<number | null>;
+    /**
+     * 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. Un
+     * refresh révoqué par rotation est conservé jusqu'à son `exp` (= fenêtre de
+     * détection de rejeu), puis purgé.
+     *
+     * **Déclenchement** : à planifier périodiquement par l'orchestrateur du store
+     * (timer `unref` posé au boot, nettoyé à l'arrêt). Les backends à TTL natif
+     * (Redis `EXPIRE`, Mongo TTL index) gèrent l'expiration eux-mêmes → leur `gc()`
+     * se limite aux cas non couverts par le TTL. **Sans orchestrateur le store
+     * s'accumule** — ne jamais laisser ce seam vide.
+     *
+     * @returns nombre d'entrées purgées.
+     */
+    gc(now?: number): Promise<number>;
+}