@nodefony/http 10.0.0-alpha.1

package/dist/types/nodefony/src/rateLimit/WsConnectionCounter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Compteur de connexions WebSocket CONCURRENTES par IP — backstop opt-in
+ * (F6c, revue 0.6). Distinct du {@link MemoryRateLimitStore} : celui-ci compte un
+ * DÉBIT d'ouverture par fenêtre (handshakes/s) ; celui-là un NOMBRE de sockets
+ * simultanément ouvertes par IP.
+ *
+ * ⚠️ Portée : PAR PROCESS (1 pod). Un vrai plafond global/IP se fait à l'ingress
+ * (nginx `limit_conn`, HAProxy `sc_conn_cur`, annotation k8s) — l'edge voit tout le
+ * trafic, rejette avant que l'app paie le fd + le handshake TLS, et couvre TOUS les
+ * pods. Ce compteur est une défense en profondeur pour le bare-metal/VPS sans
+ * ingress. Cf `wsMaxConnectionsPerIp` (config, opt-in, `null` par défaut).
+ *
+ * Auto-bornée : la Map ne suit que les IP AYANT des sockets ouvertes (bornée par le
+ * nombre de connexions réelles), et se vide au fur et à mesure des fermetures — pas
+ * besoin d'un GC ni d'un `maxTracked` (contrairement au store de débit qui retient
+ * les IP sur toute la fenêtre). Lazy : Map allouée au 1ᵉʳ acquire.
+ */
+export declare class WsConnectionCounter {
+    #private;
+    /** @param max - plafond de connexions concurrentes par IP (entier > 0). */
+    constructor(max: number);
+    /**
+     * Tente de réserver un créneau pour `ip`. `true` = sous le plafond (compteur
+     * incrémenté, appeler {@link release} à la fermeture) ; `false` = plafond atteint
+     * (rien n'est incrémenté, la connexion doit être refusée).
+     */
+    tryAcquire(ip: string): boolean;
+    /** Libère un créneau de `ip` (à la fermeture de la socket). Idempotent-safe. */
+    release(ip: string): void;
+    /** Plafond configuré (par IP). */
+    get max(): number;
+    /** Nombre d'IP actuellement suivies (avec ≥ 1 socket ouverte). */
+    get trackedIps(): number;
+    /** Total de connexions refusées depuis la construction (observabilité). */
+    get rejectedTotal(): number;
+}
+export default WsConnectionCounter;

package/dist/types/nodefony/src/rateLimit/rateLimitFilters.d.ts

@@ -0,0 +1,18 @@
+/**
+ * **Le vocabulaire de filtre du registre de rate-limit**, en noms PUBLICS —
+ * celui que la console écrit dans l'URL (`?limited=true`).
+ *
+ * `limited` répond à la seule question qu'on pose à ce registre en exploitation :
+ * « qui est au plafond en ce moment ? ». Il est booléen STRICT — `?limited=1`
+ * est refusé plutôt que lu comme `false`, ce que faisait la comparaison
+ * `limitedRaw === "true"` : sur un tableau de bord d'incident, une liste vide
+ * obtenue par erreur de syntaxe se lit « aucun client bloqué ».
+ *
+ * `q` n'y figure pas : c'est une clé du contrat de page, lue par
+ * `parsePageQuery`. Le data plane la recopiait à la main — deuxième lecteur du
+ * même paramètre, exactement le motif que ce chantier supprime.
+ */
+export declare const RATE_LIMIT_FILTERS: {
+    /** `true` = seulement les clés au plafond, `false` = seulement les autres. */
+    readonly limited: "boolean";
+};

package/dist/types/nodefony/src/servers/portBinder.d.ts

@@ -0,0 +1,102 @@
+/**
+ * **portBinder** — écoute sur le port désiré, ou sur le prochain port libre.
+ *
+ * Pourquoi ce fichier existe : lancer deux apps Nodefony côte à côte (le repo et
+ * une app générée, deux projets, un banc et une démo…) faisait mourir la seconde
+ * en `EADDRINUSE`. Le port désiré est une PRÉFÉRENCE en développement ; il reste
+ * un CONTRAT en production.
+ *
+ * ## Pourquoi retenter au `listen()` plutôt que sonder d'abord
+ *
+ * La tentation est d'appeler « le port 5151 est-il libre ? » puis de binder. C'est
+ * une **course** (TOCTOU) : entre la réponse et le bind, un autre process peut
+ * prendre le port — et on échoue quand même, après avoir cru le contraire. Le
+ * `listen()` est, lui, **atomique** : soit il réussit, soit le noyau dit
+ * `EADDRINUSE`. On retente donc sur l'échec réel, jamais sur une prédiction.
+ *
+ * ## Pourquoi sauter les ports réservés
+ *
+ * HTTP veut 5151, HTTPS veut 5152. Si 5151 est pris, incrémenter naïvement ferait
+ * voler 5152 à HTTPS — qui se décalerait à son tour, en cascade. Les ports que les
+ * AUTRES serveurs convoitent sont donc sautés d'emblée.
+ *
+ * ## Fail-loud
+ *
+ * Un décalage est TOUJOURS annoncé (`onShift`) : une app qui écoute ailleurs que
+ * là où on l'attend sans le dire est une dégradation silencieuse.
+ */
+import type { AddressInfo } from "node:net";
+/** Serveur écoutable (surface minimale commune `http`/`https`/`http2`). */
+export interface Listenable {
+    listen(port: number, host?: string): unknown;
+    address(): AddressInfo | string | null;
+    once(event: string, listener: (...args: never[]) => void): unknown;
+    removeListener(event: string, listener: (...args: never[]) => void): unknown;
+}
+/** Que faire si le port désiré est occupé. */
+export type PortPolicy = "auto" | "strict";
+/** Nombre de ports essayés après le désiré, en `auto`. */
+export declare const DEFAULT_PORT_RETRY_ATTEMPTS = 20;
+export interface BindPlan {
+    /** Port voulu (config). `0` = le noyau choisit (aucun repli nécessaire). */
+    desired: number;
+    /** Ports convoités par les AUTRES serveurs — jamais volés. */
+    reserved: readonly number[];
+    /** Essais après le désiré. `0` ⇒ comportement strict. */
+    attempts: number;
+}
+export interface BindResult {
+    /** Adresse réellement obtenue (le port peut différer du désiré). */
+    address: AddressInfo;
+    /** Port désiré si l'écoute a dû être décalée, `null` si on l'a obtenu. */
+    shiftedFrom: number | null;
+}
+/**
+ * Politique de port effective.
+ *
+ * Le défaut dépend de l'environnement, et ce n'est pas de la coquetterie :
+ * - **production** → `strict`. Le port y est un contrat (service k8s, ingress,
+ *   sonde de santé). Un bind silencieux ailleurs donnerait un pod déclaré sain
+ *   que personne n'atteint : une panne invisible, le pire des deux mondes.
+ * - **test** → `strict`. Un port occupé veut dire « un serveur est resté debout » ;
+ *   le banc doit s'arrêter, pas viser à côté (il taperait le serveur du voisin).
+ * - **développement** → `auto`. Ici un port pris n'est qu'une nuisance.
+ *
+ * @param environment - `kernel.environment` (normalisé `development`/`production`/`test`).
+ * @param explicit - `servers.portPolicy` s'il est configuré (il gagne toujours).
+ */
+export declare function resolvePortPolicy(environment: string | undefined, explicit?: PortPolicy): PortPolicy;
+/** Forme lue de `kernel.options.servers` (lecture structurelle, pas d'import core). */
+export interface ServersPortConfig {
+    http?: {
+        port?: number;
+    } | false;
+    https?: {
+        port?: number;
+    } | false;
+    portPolicy?: PortPolicy;
+    portRetryAttempts?: number;
+}
+/**
+ * Compose le plan de bind d'un serveur depuis la config du kernel — source UNIQUE
+ * (les deux serveurs l'appellent ; la politique n'est décidée qu'ici).
+ *
+ * @param which - le serveur qu'on borne.
+ * @param servers - `kernel.options.servers`.
+ * @param environment - `kernel.environment` (arbitre le défaut de la politique).
+ */
+export declare function buildBindPlan(which: "http" | "https", servers: ServersPortConfig | undefined, environment: string | undefined): BindPlan;
+/**
+ * Écoute sur `plan.desired`, ou sur le prochain port libre si `attempts > 0`.
+ *
+ * Aucun `error` permanent ne doit être attaché au serveur pendant l'appel : cette
+ * fonction pose ses propres écouteurs le temps du bind et les retire toujours (le
+ * handler d'erreur durable s'installe APRÈS, sur le serveur qui écoute — sinon il
+ * verrait passer les `EADDRINUSE` de repli et croirait à une panne).
+ *
+ * @returns l'adresse obtenue + le port désiré si un décalage a eu lieu.
+ * @throws l'erreur de `listen` : soit un code qui ne dit pas « ce port est pris »
+ *   (`ENOTFOUND`, `EACCES` sous 1024 — cf `isPortUnavailable`), soit un port
+ *   indisponible après épuisement des essais (le fallback n'est PAS infini).
+ */
+export declare function bindWithFallback(server: Listenable, host: string, plan: BindPlan): Promise<BindResult>;

package/dist/types/nodefony/src/session/session.d.ts

@@ -0,0 +1,171 @@
+import Cookie, { CookieOptionsType } from "../cookies/cookie.js";
+import type { ContextType } from "../../service/http-kernel.js";
+import type SessionsService from "../../service/sessions/sessions-service.js";
+import type { ISession, ISessionStorage, ISerializedSession, SessionStatusType, SessionStrategyType, FlashBagType, MetaBagType } from "../../interfaces/ISession.js";
+/**
+ * Options d'une session (sous-ensemble de `module.options.session`).
+ *
+ * Cookie-only : plus de `use_trans_sid`/`use_only_cookies` — un identifiant de
+ * session ne voyage JAMAIS dans l'URL (OWASP Session Management). Plus de
+ * `encrypt`/`hash_function` — l'identifiant est un secret opaque CSPRNG, pas un
+ * hash chiffré « maison ».
+ */
+export type OptionsSessionType = {
+    name?: string;
+    cookie?: CookieOptionsType;
+    /** Strict mode : un identifiant inconnu du storage → nouvelle session (anti-fixation). */
+    strictMode?: boolean;
+    /** Lie la session à l'hôte (méta `host`) — rejette un changement d'origine. */
+    refererCheck?: boolean;
+    /**
+     * Idle timeout (NIST/OWASP, secondes) : inactivité MAX depuis la dernière
+     * activité (`updatedAt`, rafraîchi par le touch). `0`/absent = pas d'expiration
+     * par inactivité. Enforcement serveur ({@link Session.isValidSession} + GC).
+     */
+    idleTimeoutS?: number;
+    /**
+     * Absolute timeout (OWASP, secondes) : durée de vie MAX depuis la création,
+     * indépendante de l'activité. Borne la fenêtre d'exploitation d'un identifiant
+     * volé même sur session active. `0`/absent = désactivé (seul l'idle s'applique).
+     */
+    absoluteTimeoutS?: number;
+};
+/**
+ * Session serveur Nodefony — état persistant lié à une identité, indexé par un
+ * identifiant **opaque** (porté par le cookie) dans un {@link ISessionStorage}
+ * pluggable (File / Redis / SQL). Modèle BFF : le cookie ne transporte qu'un
+ * secret aléatoire, jamais de données ni de JWT.
+ *
+ * Objet **léger** : trois sacs `{}` (attributs / métas / flash)
+ * au lieu d'un `Container` DI par session.
+ *
+ * Dirty-tracking : toute mutation (`set` / `setFlashBag` / `setMetaBag` /
+ * `getFlashBag` qui consomme / …) lève {@link dirty} ; {@link save} n'écrit dans
+ * le storage **que** si `dirty`. Une requête qui ne touche pas la session ne
+ * déclenche aucune écriture (supprime la contention `write`/requête).
+ */
+declare class Session implements ISession {
+    id: string;
+    name: string;
+    status: SessionStatusType;
+    storage: ISessionStorage;
+    manager: SessionsService;
+    saved: boolean;
+    migrated: boolean;
+    /**
+     * Lecture seule (intent `@UseSession({ readOnly })`) : la session est reprise et
+     * lue mais **jamais persistée** — {@link save} devient un no-op. Différenciateur
+     * perf : une route qui ne fait que LIRE la session (afficher le user…) ne paie
+     * aucune écriture storage.
+     */
+    readOnly: boolean;
+    context?: ContextType;
+    created?: Date;
+    updated?: Date;
+    options: OptionsSessionType;
+    cookieSession: Cookie | null;
+    lifetime?: number;
+    user?: string;
+    strategy: SessionStrategyType;
+    /** Sac d'attributs applicatifs (clé/valeur) — exposé via {@link getAttributes}. */
+    private attributesBag;
+    /** Sac de métadonnées techniques (host, ip, ua…) — exposé via {@link getMetas}. */
+    private metaBagStore;
+    /** Sac de messages flash (consommés à la lecture). Public : lu par les storages. */
+    flashBag: FlashBagType;
+    /** Drapeau dirty-tracking — lu via le getter {@link dirty}. */
+    private mutated;
+    constructor(name: string, options: OptionsSessionType, manager: SessionsService);
+    /** Vrai si la session a été mutée sans être encore persistée (dirty-tracking). */
+    get dirty(): boolean;
+    private log;
+    /**
+     * Démarre (ou reprend) la session. Cookie présent → reprise depuis le storage ;
+     * sinon → nouvelle session.
+     *
+     * @param context - contexte HTTP/HTTP2/WS courant.
+     */
+    start(context: ContextType): Promise<this>;
+    /**
+     * Lit l'identifiant opaque du cookie puis reprend la session, ou en crée une
+     * neuve si aucun cookie. Cookie-only : aucun identifiant lu depuis l'URL.
+     */
+    private getSession;
+    /**
+     * Reprend la session `id` depuis le storage. Invalide (→ session neuve) si
+     * introuvable en strict mode, ou expirée/illégitime.
+     */
+    private resume;
+    /**
+     * Crée une session neuve : identifiant opaque CSPRNG, cookie, métadonnées.
+     * Marquée `dirty` (sauf `saveUninitialized:false`) → persistée + `Set-Cookie`
+     * au prochain {@link save}.
+     */
+    create(lifetime: number, id?: string, settingsCookie?: CookieOptionsType): this;
+    /** Génère un identifiant de session opaque (32 octets CSPRNG → base64url). */
+    private generateId;
+    /**
+     * Régénère l'identifiant (nouveau secret opaque) en conservant l'état courant.
+     * Anti session-fixation (OWASP) — appelée à chaque ouverture de session
+     * authentifiée par `AuthFlow.#openSession()` (`@nodefony/security`), qui
+     * détruit ensuite l'ancienne entrée de storage. Repositionne le cookie et
+     * marque la session `dirty`.
+     */
+    regenerateId(): void;
+    /**
+     * Persiste la session **si elle est dirty** (sinon no-op). Réécrit le blob
+     * sérialisé dans le storage, repositionne created/updated, lève l'événement
+     * `onSaveSession`.
+     *
+     * @param user - principal authentifié (string) lié au blob ; défaut courant.
+     */
+    save(user?: string): Promise<this>;
+    /**
+     * Détruit la session courante (storage) et en recrée une neuve (nouvel
+     * identifiant + cookie). État applicatif réinitialisé.
+     */
+    invalidate(lifetime?: number, id?: string, settingsCookie?: CookieOptionsType): Promise<this>;
+    /**
+     * Détruit la session : vide les sacs, supprime l'entrée storage, et (option)
+     * efface le cookie.
+     */
+    destroy(cookieDelete?: boolean): Promise<boolean>;
+    setCookieSession(leftTime: number, options?: CookieOptionsType): Cookie | null;
+    deleteCookieSession(): Cookie | null;
+    isValidSession(_data: ISerializedSession, context: ContextType): boolean;
+    /**
+     * Prolonge l'idle timeout de la session active sur l'activité courante, **de
+     * façon throttlée** (1 écriture par tranche d'idle, jamais par requête) et
+     * **sans réécrire le blob** (write léger `touch` du storage) — l'activité
+     * HTTP/WS réelle, **y compris en lecture seule**, empêche l'expiration d'une
+     * session utilisée (NIST/OWASP : idle « since the last request »). N'affecte
+     * **jamais** l'absolute timeout (borné à la création).
+     *
+     * No-op si : pas active, pas d'entrée storage à prolonger (`!updated`), idle
+     * désactivé, store sans `touch`, ou dernière activité trop récente (throttle =
+     * mi-vie de l'idle). Met à jour `updated` localement → le throttle compte
+     * depuis ce touch.
+     */
+    touchIfNeeded(): Promise<void>;
+    checkSecureReferer(context: ContextType): boolean;
+    private setMetasSession;
+    get(key: string): unknown;
+    set(key: string, value: unknown): unknown;
+    getAttributes(): Record<string, unknown>;
+    getMetaBag(key: string): unknown;
+    setMetaBag(key: string, value: unknown): void;
+    getMetas(): MetaBagType;
+    getFlashBag(key: string): unknown;
+    setFlashBag(key: string, value: unknown): unknown;
+    flashBags(): FlashBagType;
+    clearFlashBag(key: string): void;
+    clearFlashBags(): void;
+    serialize(user?: string): ISerializedSession;
+    deSerialize(data: ISerializedSession): void;
+    /** Réinitialise les trois sacs (attributs, métas, flash) — état vide. */
+    clear(): void;
+    getName(): string;
+    setName(name: string): void;
+    checkStatus(): "restart" | boolean;
+}
+export default Session;

package/dist/types/nodefony/src/session/storage/MemorySessionStorage.d.ts

@@ -0,0 +1,77 @@
+import type { IPage } from "nodefony";
+import type sessionService from "../../../service/sessions/sessions-service.js";
+import type { ISessionStorage, ISerializedSession, ISessionRecord, ISessionListFilter, ISessionListQuery } from "../../../interfaces/ISession.js";
+/**
+ * Store de sessions **en mémoire** (Map process) — implémentation de référence
+ * d'{@link ISessionStorage}, pendant `session` des `Memory*Store` de sécurité.
+ *
+ * **Volatil** : les sessions vivent dans la RAM du process et disparaissent au
+ * redémarrage ET ne sont PAS partagées entre pods/workers. Cible : **tests de
+ * charge** (mesurer le framework sans le goulot disque/SQL), CI, environnements
+ * éphémères. Pour la persistance mono-nœud → `drizzle` (sqlite) ; multi-nœud →
+ * `redis`/`drizzle`/`mongoose`.
+ *
+ * Bornes NIST/OWASP portées par des horodatages internes : `updatedAt` = dernière
+ * activité (idle, rafraîchi par {@link touch}), `createdAt` = création (absolute,
+ * JAMAIS prolongé). Même sémantique que les stores SQL — l'idle glissant et
+ * l'absolute s'appliquent identiquement.
+ */
+declare class MemorySessionStorage implements ISessionStorage {
+    #private;
+    manager: sessionService;
+    idleTimeoutS: number;
+    absoluteTimeoutS: number;
+    /**
+     * Trie sur tout le vocabulaire public : les données sont déjà en RAM, aucun
+     * champ n'est plus coûteux qu'un autre. Aucune traduction — les clés internes
+     * portent déjà ces noms (`id` étant la clé de la Map).
+     */
+    readonly sortableFields: readonly ["updatedAt", "createdAt", "user", "id"];
+    constructor(manager: sessionService);
+    /** Lecture par id — copie superficielle (le consommateur ne mute pas le store). */
+    read(id: string): Promise<ISerializedSession>;
+    start(id: string): Promise<ISerializedSession>;
+    /**
+     * Écrit (upsert) le blob. `createdAt` est FIXÉ à la création et préservé aux
+     * updates (borne absolute) ; `updatedAt` est posé à chaque écriture (borne idle).
+     */
+    write(id: string, data: ISerializedSession): Promise<ISerializedSession>;
+    /** Compte des sessions présentes (+ passe GC comme les autres stores à l'open). */
+    open(): Promise<number>;
+    close(): boolean;
+    destroy(id: string): Promise<boolean>;
+    /**
+     * Prolonge l'idle (timeout glissant) : rafraîchit `updatedAt` SANS toucher
+     * `createdAt` (borne absolute intacte). Session absente (purgée) → no-op.
+     */
+    touch(id: string): Promise<void>;
+    /**
+     * Purge idle (inactivité depuis `updatedAt`) ET absolute (âge depuis `createdAt`,
+     * jamais prolongé). Une borne à 0 = désactivée. Déterministe (synchrone).
+     */
+    gc(idleSeconds?: number, absoluteSeconds?: number): Promise<void>;
+    /** Énumération admin — filtre `user` appliqué en mémoire. */
+    listAll(filter?: ISessionListFilter): Promise<ISessionRecord[]>;
+    /**
+     * Pagination **offset** avec `total` exact, ordre `updatedAt` DESC (id ASC en
+     * départage). Les données étant déjà en RAM par conception, le coût par requête
+     * est celui du tri des **références** filtrées — aucune copie de blob n'est
+     * faite hors de la page rendue.
+     *
+     * **Redaction par construction** (garantie du contrat, pas une optimisation) :
+     * `Attributes`/`flashBag` sortent VIDES, comme chez les stores SQL/NoSQL qui ne
+     * les SELECTent pas. Ici c'est gratuit — on ne recopie simplement pas ces deux
+     * bags — et ça aligne le store mémoire sur la même garantie : un record
+     * d'énumération admin ne porte jamais de donnée métier.
+     */
+    listPage(query: ISessionListQuery): Promise<IPage<ISessionRecord>>;
+    /** `COUNT` filtré — parcourt sans allouer (aucun record matérialisé). */
+    countSessions(query?: Partial<ISessionListQuery>): Promise<number>;
+    /**
+     * `COUNT(DISTINCT user)` en mémoire. Le `Set` est alloué à l'appel et relâché
+     * aussitôt : c'est un chemin d'administration, appelé à l'ouverture d'un
+     * écran, jamais dans le pipeline de requête.
+     */
+    countDistinctUsers(query?: Partial<ISessionListQuery>): Promise<number>;
+}
+export default MemorySessionStorage;

package/dist/types/nodefony/src/session/storage/RevocationGuardStorage.d.ts

@@ -0,0 +1,81 @@
+import type { IPage } from "nodefony";
+import type { ISessionStorage, ISerializedSession, ISessionRecord, ISessionListFilter, ISessionListQuery } from "../../../interfaces/ISession.js";
+/**
+ * Garde-fou de révocation **décoré au-dessus** de n'importe quel
+ * {@link ISessionStorage} (file, drizzle, redis, mongo…). Pose une « pierre
+ * tombale » sur tout id détruit et REFUSE un `write` ultérieur de ce même id
+ * pendant {@link TOMBSTONE_TTL_MS}.
+ *
+ * **Pourquoi ici, pas dans chaque store** : la résurrection est une propriété du
+ * CYCLE DE VIE de session — révoquer une session puis l'autosave de fin de
+ * requête (la requête la portait encore en mémoire, `dirty`) la ré-écrit — et
+ * NON d'un backend particulier. Un seul garde-fou décoré sur le storage actif
+ * couvre donc TOUS les backends, présents et futurs, **sans en modifier aucun**.
+ *
+ * Découvert en live le 2026-06-21 (« révoquer une session ne déconnecte pas ») ;
+ * le store réel était `drizzle`, pas `files` — d'où la décoration générique.
+ *
+ * Couvre deux scénarios :
+ *  - **self** : l'admin révoque SA PROPRE session ; l'autosave de la requête de
+ *    révocation tente de la réécrire → refusé.
+ *  - **race** : un autre client du user révoqué a une requête en vol dont
+ *    l'autosave arrive après la révocation → refusé.
+ *
+ * **Perf** : décorateur **singleton** (1 par service). Délégation directe sur le
+ * hot-path lecture (`read`/`start`/`listAll`) ; `write` ne paie qu'un test
+ * `=== null` tant qu'aucune session n'a été révoquée (Map **lazy**, jamais de
+ * `Date.now()` dans ce cas).
+ */
+declare class RevocationGuardStorage implements ISessionStorage {
+    #private;
+    /** Storage réel décoré — exposé pour l'introspection admin (nom du driver). */
+    readonly inner: ISessionStorage;
+    /**
+     * Énumération admin — (ré)assignée dans le constructeur **uniquement** si le
+     * backend décoré la supporte, pour que `SessionsService.supportsEnumeration`
+     * (`typeof storage.listAll === "function"`) reflète la vraie capacité du store.
+     */
+    listAll?: (filter?: ISessionListFilter) => Promise<ISessionRecord[]>;
+    /**
+     * Touch (prolongation d'idle) — (ré)assignée seulement si le backend décoré la
+     * supporte, pour que `Session.touchIfNeeded` (`typeof storage.touch`) reflète la
+     * vraie capacité. **Respecte la pierre tombale** : ne prolonge JAMAIS une session
+     * révoquée (cohérent avec `write` — une révocation ne doit pas être contournée
+     * par un touch tardif d'une requête en vol).
+     */
+    touch?: (id: string, idleSeconds?: number) => Promise<void>;
+    /**
+     * Énumération admin **paginée** — (ré)assignée seulement si le backend décoré
+     * la supporte, même raison que {@link listAll} : `supportsEnumeration` teste la
+     * présence de la méthode, elle doit donc refléter la vraie capacité du store
+     * décoré et non celle du décorateur.
+     */
+    listPage?: (query: ISessionListQuery) => Promise<IPage<ISessionRecord>>;
+    /** `COUNT` filtré — (ré)assigné seulement si le backend décoré le supporte. */
+    countSessions?: (query?: Partial<ISessionListQuery>) => Promise<number>;
+    /**
+     * `COUNT(DISTINCT user)` — (ré)assigné seulement si le backend décoré le
+     * supporte, même raison que {@link countSessions} : une capacité perdue dans
+     * le décorateur ferait afficher « inconnu » là où la base sait répondre.
+     */
+    countDistinctUsers?: (query?: Partial<ISessionListQuery>) => Promise<number>;
+    /**
+     * Capacité de tri du backend décoré, relayée telle quelle.
+     *
+     * Une capacité qui se PERD dans un décorateur est pire qu'une capacité
+     * absente : elle est déclarée par le store réel, invisible au-dessus, et le
+     * data plane refuse alors (400) un tri que la base sait parfaitement faire.
+     * Comme ce décorateur est posé en production dès qu'une révocation est
+     * possible, l'oubli aurait désactivé le tri **partout**.
+     */
+    readonly sortableFields?: readonly string[];
+    constructor(inner: ISessionStorage);
+    read(id: string): Promise<ISerializedSession>;
+    start(id: string): Promise<ISerializedSession>;
+    open(): Promise<number>;
+    close(): boolean;
+    gc(idleSeconds?: number, absoluteSeconds?: number): Promise<void>;
+    destroy(id: string): Promise<boolean>;
+    write(id: string, data: ISerializedSession): Promise<ISerializedSession>;
+}
+export default RevocationGuardStorage;

package/dist/types/nodefony/src/session/storage/sessionFilters.d.ts

@@ -0,0 +1,102 @@
+import type { FacetCount, FacetCounts } from "nodefony";
+/**
+ * **Le vocabulaire de filtre des sessions**, en noms PUBLICS — celui que la
+ * console d'administration écrit dans l'URL (`?user=alice`).
+ *
+ * Frère de `SESSION_SORTABLE_FIELDS` (`sessionSort.ts`), posé au même endroit
+ * pour la même raison : le vocabulaire appartient au module propriétaire du
+ * contrat, la mécanique de lecture au cœur (`parseFilters`).
+ *
+ * `user` est un filtre **portable par construction** (égalité stricte) : il
+ * s'exprime dans tous les backends — `WHERE` indexé en SQL et Mongo, prédicat en
+ * mémoire, filtre de batch en Redis — donc aucun store n'a besoin de matérialiser
+ * la collection pour l'honorer. C'est la propriété qui justifie qu'il soit au
+ * contrat plutôt que dans une couche de filtrage applicative.
+ *
+ * `tenantId` n'y figure pas parce qu'il appartient au **contrat de page**
+ * (`PAGE_QUERY_KEYS`, réserve multi-tenant) : le déclarer ici en ferait un
+ * second lecteur du même paramètre.
+ */
+export declare const SESSION_FILTERS: {
+    /** Sessions d'un utilisateur donné (égalité stricte sur l'identifiant). */
+    readonly user: "string";
+    /**
+     * `true` = sessions rattachées à un utilisateur, `false` = anonymes, absent =
+     * les deux. Le contrat le définit comme « `user` non vide » — tous les stores
+     * l'honorent déjà (c'est ainsi que `sessions/stats` compte ses facettes).
+     *
+     * Il n'était pas exposé à l'URL, et la console ne pouvait donc pas MONTRER la
+     * population qu'elle affichait en carte : cliquer « Anonymes » demandait un
+     * paramètre que la liste refusait. Une facette n'existe que si le contrat de
+     * liste sait la filtrer — celle-ci le savait partout sauf sur le fil.
+     *
+     * ⚠️ Redondant avec `user` **par construction** (même donnée). Les combiner
+     * de façon contradictoire (`?user=alice&authenticated=false`) rend l'ENSEMBLE
+     * VIDE, jamais la page de l'un des deux — garde posée dans le banc de contrat
+     * partagé, donc rejouée sur les six backends.
+     */
+    readonly authenticated: "boolean";
+};
+/**
+ * **Les facettes des sessions** — les questions fermées que la console pose à la
+ * collection ENTIÈRE, pour ses cartes de tête.
+ *
+ * Distinct de `SESSION_FILTERS`, qui dit ce qu'un client a le droit d'écrire
+ * dans l'URL : une facette n'est pas saisie, elle est posée par le serveur. Les
+ * deux se recoupent par construction — une facette n'existe que si le contrat de
+ * liste sait déjà la filtrer, sinon elle serait un compteur approximatif de plus.
+ *
+ * `authenticated` suffit à couvrir les deux populations : le contrat le définit
+ * comme « `user` non vide », donc `false` rend exactement les sessions anonymes.
+ * Aucune facette n'est déduite d'une soustraction (cf `countFacets`).
+ *
+ * Le décompte d'utilisateurs **distincts** n'est PAS ici : ce n'est pas un
+ * `COUNT` filtré mais une agrégation, qu'un store en curseur ne peut pas rendre.
+ * Il vit en capacité déclarée du backend (`ISessionStorage.countDistinctUsers`).
+ */
+export declare const SESSION_FACETS: {
+    /** Toutes les sessions persistées, sans filtre. */
+    readonly total: {};
+    /** Sessions rattachées à un utilisateur authentifié. */
+    readonly authenticated: {
+        readonly authenticated: true;
+    };
+    /** Sessions anonymes (aucun utilisateur rattaché). */
+    readonly anonymous: {
+        readonly authenticated: false;
+    };
+};
+/**
+ * Ce que l'endpoint de COMPTEURS accepte de filtrer — {@link SESSION_FILTERS}
+ * **moins** le champ que ses facettes décomposent (`authenticated`).
+ *
+ * Le demander ici rendrait une réponse qui se contredit : le total suivrait le
+ * filtre pendant que chaque facette l'écraserait par le sien (« 5 sessions au
+ * total, dont 40 anonymes »). `user` reste : il découpe une AUTRE dimension, et
+ * « combien de sessions pour alice, dont combien d'anonymes ? » est une question
+ * cohérente — qui rend d'ailleurs l'ensemble vide, la réponse honnête.
+ *
+ * Frère de `USER_STATS_FILTERS` / `TOKEN_STATS_FILTERS` / `WEBHOOK_STATS_FILTERS`.
+ * Les sessions n'en avaient pas : `authenticated` n'était exposé nulle part, si
+ * bien que le trou était fermé par accident plutôt que par décision. Ouvrir le
+ * filtre sur la liste — pour que les cartes deviennent cliquables — l'aurait
+ * rouvert du même geste.
+ */
+export declare const SESSION_STATS_FILTERS: {
+    readonly user: "string";
+};
+/**
+ * Les compteurs rendus par `GET /nodefony/http/api/sessions/stats`.
+ *
+ * **Dérivé** de {@link SESSION_FACETS} : ajouter une facette ajoute son champ
+ * ici, et le front qui ne l'affiche pas ne compile plus. Écrire ce type à la
+ * main aurait rendu possible une carte affichant un compteur que le serveur ne
+ * calcule pas — ou l'inverse.
+ *
+ * `users` s'y ajoute à part parce qu'il ne vient pas d'un `COUNT` filtré mais
+ * d'une agrégation, que tous les backends ne savent pas rendre.
+ */
+export type ISessionCounts = FacetCounts<typeof SESSION_FACETS> & {
+    /** Utilisateurs **distincts** ayant au moins une session (`null` si inconnu). */
+    users: FacetCount;
+};

package/dist/types/nodefony/src/session/storage/sessionSort.d.ts

@@ -0,0 +1,45 @@
+import type { IPageQuery } from "nodefony";
+/**
+ * **Le vocabulaire de tri des sessions**, en noms PUBLICS — ceux qu'un client
+ * écrit dans l'URL (`?order=updatedAt:DESC`), jamais des noms de colonne.
+ *
+ * Il vit ici, chez le propriétaire du contrat (`@nodefony/http`), et non dans
+ * chaque backend : c'est ce qui garantit qu'une console offre le même tri que
+ * l'application tourne sur mémoire, SQLite, PostgreSQL ou Mongo. Un store qui
+ * nomme ses colonnes autrement (SQL stocke l'identifiant en `session_id`)
+ * **traduit chez lui** — cf {@link SESSION_COLUMN_ALIASES}.
+ *
+ * - `updatedAt` — dernière activité (l'axe naturel d'une console de sessions).
+ * - `createdAt` — ouverture de la session (« qui s'est connecté en premier »).
+ * - `user` — porteur, pour regrouper les sessions d'un même compte à l'œil.
+ * - `id` — identifiant de session, utile surtout en départage.
+ *
+ * Ce que la liste n'inclut PAS, et pourquoi : `ip` et `ua` ne sont **pas des
+ * champs** mais des entrées du sac de métadonnées (`metaBag`, sérialisé en
+ * JSON). Aucun backend ne peut les ordonner sans matérialiser la collection —
+ * la console les affiche donc en colonnes non triables, au lieu d'offrir un
+ * tri qui serait refusé (SQL) ou coûteux (mémoire).
+ */
+export declare const SESSION_SORTABLE_FIELDS: readonly ["updatedAt", "createdAt", "user", "id"];
+/**
+ * Ordre contractuel appliqué quand le client n'en demande aucun : activité la
+ * plus récente d'abord, départagée par identifiant pour rester **déterministe**
+ * à horodatage égal (sans quoi une pagination peut sauter ou répéter une ligne
+ * entre deux pages).
+ */
+export declare const SESSION_DEFAULT_ORDER: NonNullable<IPageQuery["order"]>;
+/**
+ * Table d'alias des backends dont le schéma nomme l'identifiant de session
+ * `session_id` (SQL comme Mongo) — à passer à `renameOrderFields` (core).
+ *
+ * C'est une **donnée** du schéma, pas du code : la règle « réécrire les noms »
+ * vit au core en un exemplaire, et chaque backend n'apporte que sa table. Sans
+ * cette traduction, `?order=id:ASC` partirait vers une colonne `id` inexistante
+ * — l'erreur ne se verrait qu'à l'exécution, sur le backend concerné seulement.
+ */
+export declare const SESSION_COLUMN_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Ordre par défaut des backends dont le schéma nomme l'identifiant
+ * `session_id` — {@link SESSION_DEFAULT_ORDER} déjà traduit.
+ */
+export declare const SESSION_DEFAULT_ORDER_SQL: NonNullable<IPageQuery["order"]>;