@nodefony/http 10.0.0-alpha.1

package/dist/types/nodefony/src/context/websocket/wsLogContent.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Formatage **pur** (0 état, 0 dépendance) du CONTENU d'un message WebSocket pour
+ * le log de trace (Suivi de requête Studio). Séparé de `WebsocketContext` pour
+ * être testable aux limites sans serveur.
+ *
+ * 🔒 Robustesse binaire (cf doc `ws` — `socket.send(data)` accepte
+ * `String | Number | Object | Buffer | ArrayBuffer | TypedArray | DataView |
+ * Buffer[] | Blob`, et l'event `message` livre `Buffer | ArrayBuffer | Buffer[]`).
+ * **Toute** charge binaire est résumée `[binary N B]` — JAMAIS sérialisée
+ * (`JSON.stringify(new Uint8Array(...))` produirait `{"0":..,"1":..}`, énorme et
+ * faux). Seules string et objets « JSON » sont rendus en texte (borné).
+ */
+/** Cap de troncature du contenu loggé (octets/chars). Borne ring + JSONL. */
+export declare const WS_LOG_CONTENT_CAP = 4096;
+/**
+ * Taille en octets d'une charge **binaire** reconnue, ou `-1` si la valeur n'est
+ * pas binaire (→ à traiter en JSON/texte). Couvre tous les types binaires que
+ * `ws` accepte/livre : `Buffer`, `ArrayBuffer`, vues (`TypedArray`/`DataView`),
+ * `Blob` (Node ≥ 18), et `Buffer[]` (fragments — binaire ssi TOUS ses éléments
+ * le sont, sinon c'est un tableau JSON ordinaire).
+ *
+ * @param data - valeur à mesurer.
+ * @returns nombre d'octets, ou `-1` si non binaire.
+ */
+export declare function binaryByteLength(data: unknown): number;
+/**
+ * Formate une charge utile WS en chaîne **bornée** et **sûre** pour le log :
+ *  - `string` → tronquée à `cap` (+ ellipse) ;
+ *  - binaire (cf {@link binaryByteLength}) → `[binary N B]` (jamais de dump) ;
+ *  - `null`/`undefined` → `""` ;
+ *  - objet « JSON » → `JSON.stringify` compact tronqué (cycle, `bigint`, valeur
+ *    non sérialisable → repli `String(...)`).
+ *
+ * @param data - charge utile (RECEIVE/SEND/BROADCAST).
+ * @param cap - longueur max avant troncature (défaut {@link WS_LOG_CONTENT_CAP}).
+ */
+export declare function formatWsLogContent(data: unknown, cap?: number): string;

package/dist/types/nodefony/src/cookies/cookie.d.ts

@@ -0,0 +1,88 @@
+import { StringValue } from "ms";
+import { ContextType } from "../../service/http-kernel.js";
+import type { ICookie as ICookieInterface, ICookieOptions, IWsCookie, PriorityType, SameSiteType } from "../../interfaces/ICookie.js";
+declare module "http" {
+    interface IncomingMessage {
+        cookies: Record<string, Cookie>;
+    }
+}
+declare module "http2" {
+    interface Http2ServerRequest {
+        cookies: Record<string, Cookie>;
+    }
+}
+/**
+ * Options d'un cookie — alias du contrat public {@link ICookieOptions}.
+ *
+ * Conservé sous ce nom parce que `session.ts` et l'historique du module
+ * l'importent ainsi ; ce n'est PAS une seconde définition. Un consommateur
+ * externe nomme le type par `ICookieOptions`, exporté au barrel.
+ */
+export type CookieOptionsType = ICookieOptions;
+declare function parser(strToParse: string): import("cookie").Cookies;
+declare function cookiesParser(context: ContextType): void;
+declare class Cookie implements ICookieInterface {
+    options: CookieOptionsType;
+    name: string;
+    signed?: boolean;
+    value: unknown;
+    originalMaxAge?: number;
+    expires?: Date;
+    maxAge?: number;
+    path?: string;
+    domain: string | undefined;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: SameSiteType;
+    priority?: string;
+    constructor(cookies: Cookie);
+    constructor(name: string, value: unknown, options?: CookieOptionsType);
+    clearCookie(): void;
+    setValue(value: unknown): unknown;
+    setSecure(val: boolean | undefined): boolean;
+    setDomain(): string | undefined;
+    setHttpOnly(val: boolean | undefined): boolean;
+    setPath(val: string | undefined): string | undefined;
+    /**
+     * Normalise l'attribut `SameSite` vers une valeur canonique RFC 6265bis.
+     *
+     * Fallback **`Lax`** (jamais `None`) : `None` désactive la protection CSRF et
+     * impose `Secure` — ce n'est jamais un défaut sûr. Toute entrée inconnue
+     * (ancien `boolean`, casse libre) retombe sur `Lax` (fail-safe).
+     *
+     * @param val - valeur souhaitée (`Strict` / `Lax` / `None`, casse libre).
+     * @returns la forme canonique title-case.
+     */
+    setSameSite(val: SameSiteType | undefined): SameSiteType;
+    setExpires(date: Date | string | number | undefined): Date | undefined;
+    setOriginalMaxAge(ms: number | StringValue): number;
+    setPriority(val: PriorityType): PriorityType;
+    getMaxAge(): number | undefined;
+    toString(): string;
+    /**
+     * Signe une valeur de cookie : `HMAC-SHA256(value)` clé = `secret`, encodé en
+     * base64url (sûr en cookie, pas de `=`/`+`/`/`). Retourne `value.signature`
+     * → la valeur d'origine est PRÉSERVÉE (récupérable via {@link unsign}).
+     *
+     * @param val - valeur en clair à signer.
+     * @param secret - clé HMAC (le secret, JAMAIS la valeur).
+     * @returns `value.base64url(hmac)`.
+     * @throws {TypeError} si `val` n'est pas une string ou `secret` est vide.
+     */
+    sign(val: unknown, secret: string): string;
+    /**
+     * Vérifie et déballe une valeur signée par {@link sign} (tolère le préfixe
+     * `s:`). Comparaison **timing-safe** (`crypto.timingSafeEqual`).
+     *
+     * @param val - valeur signée (`value.signature`, éventuellement préfixée `s:`).
+     *   Défaut : `this.value`.
+     * @param secret - clé HMAC. Défaut : `this.options.secret`.
+     * @returns la valeur en clair si la signature est valide, sinon `false`.
+     * @throws {TypeError} si les types sont invalides ou le secret est vide.
+     */
+    unsign(val?: string, secret?: string): string | false;
+    serialize(): string;
+    serializeWebSocket(): IWsCookie;
+}
+export default Cookie;
+export { cookiesParser, parser };

package/dist/types/nodefony/src/errors/httpError.d.ts

@@ -0,0 +1,15 @@
+import { nodefonyError as NodefonyError } from "nodefony";
+import { ContextType } from "../../service/http-kernel.js";
+import { HttpRequestType, HttpRsponseType } from "../context/http/HttpContext.js";
+declare class HttpError extends NodefonyError {
+    context?: ContextType;
+    response?: HttpRsponseType;
+    request?: HttpRequestType;
+    url?: string;
+    controller?: string;
+    action?: string;
+    jsonResponse?: string;
+    constructor(message?: unknown, code?: number, context?: ContextType);
+    toString(): string;
+}
+export default HttpError;

package/dist/types/nodefony/src/profiler/FrameProfile.d.ts

@@ -0,0 +1,110 @@
+import type { IProfilerQuery } from "nodefony";
+import type { ISecurityTrace, PhaseName, PhaseTiming } from "../../interfaces/IContext.js";
+/**
+ * Zone firewall capturée sur le contexte (`SecuredArea`, lue en structurel :
+ * `@nodefony/http` ne peut pas importer `@nodefony/security`).
+ */
+export interface ProfiledArea {
+    name?: string;
+    security?: boolean;
+    mode?: string;
+    authenticators?: readonly string[];
+}
+/** Ce que le Profiler lit d'un Resolver (route/controller/action). */
+export interface ProfiledResolver {
+    route?: {
+        name?: string;
+    } | null;
+    controller?: {
+        name?: string;
+    } | null;
+    actionName?: string;
+}
+/** Descripteur d'ouverture d'une invocation (ce que le pont connaît d'entrée). */
+export interface FrameProfileInit {
+    /** Identifiant du profil — `<requestId de la connexion>.<n° de frame>`. */
+    requestId: string;
+    /** Type de transport du contexte porteur (`websocket` / `websocket-secure`). */
+    type: string;
+    scheme: string;
+    /** Méthode LOGIQUE de l'invocation (`GET`, `POST`…), pas le transport. */
+    method: string;
+    /** Chemin invoqué par la frame (avec sa query), pas l'URL de la connexion. */
+    url: string;
+    remoteAddress: string | null;
+    traceparent: string | null;
+    /** Zone firewall de la connexion (l'identité de la frame en découle). */
+    security: ProfiledArea | null;
+    /** Décision du firewall au handshake — l'identité que la frame rejoue. */
+    securityTrace: ISecurityTrace | null;
+    /** Mesurer les phases ? (`timing.enabled` du contexte porteur.) */
+    timing: boolean;
+    /** Collecter le SQL ? (profiler dev présent → buffer ORM alloué.) */
+    queries: boolean;
+}
+/**
+ * Profil d'**une invocation** du pont RPC (une frame `api.request`), et non de
+ * la connexion qui la porte.
+ *
+ * Pourquoi un objet séparé du `Context` : un `WebsocketContext` vit pour toute
+ * la **connexion**, alors qu'une socket peut porter des centaines d'invocations,
+ * concurrentes de surcroît. Empiler leurs phases sur le contexte produirait une
+ * timeline **cumulative** (donc fausse) et ferait croître `Context.phases` sans
+ * borne. Le profil naît et meurt donc avec la frame ; il voyage dans l'ALS
+ * (`RequestContext.payload.invocation`), seul canal déjà per-invocation traversé
+ * par le Resolver, le controller et les adapters ORM.
+ *
+ * Il satisfait **structurellement** ce que `Profiler.collect()` lit d'un
+ * contexte : aucune connaissance du transport n'est requise côté Profiler, un
+ * profil de frame s'y collecte comme une requête HTTP (`kind: "ws"`).
+ *
+ * Coût : **rien n'est alloué** quand le profiler dev est absent ET le timing
+ * éteint (production) — le pont n'ouvre alors aucun profil.
+ */
+export declare class FrameProfile {
+    readonly requestId: string;
+    readonly type: string;
+    readonly scheme: string;
+    readonly method: string;
+    readonly url: string;
+    readonly remoteAddress: string | null;
+    readonly traceparent: string | null;
+    readonly security: ProfiledArea | null;
+    readonly securityTrace: ISecurityTrace | null;
+    /** Phases de CETTE frame (vide si le timing est éteint). */
+    readonly phases: PhaseTiming[];
+    /**
+     * Buffer ORM de CETTE frame — `null` hors profiling. C'est ce buffer que le
+     * kernel refusait d'allouer au handshake (il aurait cumulé N messages) : par
+     * invocation, il redevient exact, et le SQL se replace dans le waterfall.
+     */
+    readonly profilerQueries: IProfilerQuery[] | null;
+    /** Resolver de la frame — porte route / controller / action. */
+    resolver: ProfiledResolver | null;
+    /** Statut HTTP-équivalent de l'invocation (200, 403, 404…). */
+    response: {
+        statusCode: number;
+    } | null;
+    error: {
+        message: string;
+    } | null;
+    private readonly timing;
+    constructor(init: FrameProfileInit);
+    /**
+     * Ouvre une phase. Contrairement au `Context`, l'index est un **scan arrière**
+     * (pas de `Map<nom, index>`) : une frame porte une poignée de phases, et une
+     * phase peut être ré-entrante (une action qui en déclenche une autre) — la
+     * table par nom, elle, écraserait la première occurrence.
+     */
+    phaseStart(name: PhaseName): void;
+    /** Ferme la DERNIÈRE phase ouverte de ce nom (idempotent). */
+    phaseEnd(name: PhaseName): void;
+    /**
+     * Fige l'issue de l'invocation (statut + erreur éventuelle) avant collecte.
+     *
+     * @param status - statut HTTP-équivalent (200 ; 403/404/409… pour un refus).
+     * @param error - l'erreur qui a interrompu la frame, le cas échéant.
+     */
+    finish(status: number, error?: unknown): void;
+}
+export default FrameProfile;

package/dist/types/nodefony/src/profiler/Profiler.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Profiler — collecteur **dev-only** de profils de requête, indexé par `requestId`.
+ *
+ * Modèle inversé (≠ ancien monitoring-bundle qui splicait du Twig serveur dans
+ * le body) : le serveur **collecte** un instantané en fin de requête, le client
+ * (debug bar) **rend**. La matière existe déjà dans le `Context` quand le timing
+ * est actif (`phases`, `requestId`, `status`, resolver) → `collect()` ne fait
+ * que SNAPSHOTTER : aucune allocation per-request hors de cette structure, et
+ * **rien** en prod (le module n'instancie pas le Profiler hors dev).
+ *
+ * Stockage = ring buffer borné via l'ordre d'insertion d'une `Map` : à la
+ * capacité, on évince la plus ancienne entrée (première clé). O(1) amorti.
+ *
+ * Corrélation client↔serveur : le framework renvoie déjà `X-Request-Id` sur
+ * chaque réponse → le client lit le header de SON appel AJAX et fetch
+ * `/nodefony/profiler/api/{requestId}`. Zéro modif du pipeline.
+ *
+ * Multi-process : un profil vit sur le worker qui a traité l'appel (fetch même
+ * origine par requestId). Agrégat cluster = Redis (P13).
+ */
+/** Une phase du pipeline, projetée pour le transport (durée résolue). */
+export interface ProfilePhase {
+    name: string;
+    /** Début relatif `performance.now()` (ms) — sert au calcul du waterfall. */
+    startMs: number;
+    /** Durée en ms, `null` si la phase ne s'est pas terminée (erreur). */
+    durationMs: number | null;
+}
+/**
+ * Une requête SQL/NoSQL exécutée pendant la requête HTTP (SEAM ORM — futur).
+ *
+ * Non collecté aujourd'hui : quand `@nodefony/orm-core` arrivera, les adapters
+ * pousseront leurs requêtes dans un buffer per-request dev-only (via l'ALS
+ * `RequestContext.getRequestId()`, déjà en place) que `collect()` lira ici.
+ * Le champ `queries` reste donc `undefined` tant qu'aucun ORM ne pushe → 0 coût.
+ */
+export interface ProfileQuery {
+    /** Requête (SQL ou commande NoSQL), tronquée si volumineuse. */
+    sql: string;
+    /** Début relatif (`performance.now()`) — même horloge que les phases. */
+    startMs?: number;
+    /** Durée d'exécution en ms. */
+    durationMs: number;
+    /** Lignes affectées/retournées, si connu. */
+    rows?: number;
+    /** Connecteur émetteur (`drizzle`, `mongoose`…). */
+    connector?: string;
+}
+/**
+ * Traversée du firewall par cette requête — **ce qui était possible** (la zone :
+ * son nom, si elle est protégée, quels authenticators elle accepte) croisé avec
+ * **ce qui s'est passé** (quel maillon a résolu l'identité, l'issue, le motif
+ * d'un refus).
+ *
+ * Sans cela, une requête qui PASSE est invisible côté sécurité : le chemin de
+ * succès n'émet aucun événement d'audit (choix délibéré — le volume nominal
+ * n'est pas un signal). `undefined` hors zone firewall.
+ */
+export interface ProfileSecurity {
+    /** Nom de la zone traversée. */
+    zone: string | null;
+    /** La zone exige-t-elle une identité (`security: true`) ? */
+    protected: boolean;
+    /** Chaîne d'authenticators : `first` = le premier qui supporte, `all` = MFA. */
+    mode: string | null;
+    /** Authenticators que la zone accepte (ce qui était POSSIBLE). */
+    candidates: string[];
+    /** Authenticator qui a RÉELLEMENT résolu l'identité. */
+    authenticator: string | null;
+    /** `granted` · `anonymous` · `denied` · `failure` · `throttled` · `bypass` · `public`. */
+    outcome: string | null;
+    /** Motif du refus (`no_credentials`, `invalid_credentials`…). */
+    reason: string | null;
+    /** Rôles du token résolu (l'axe autorisation). */
+    roles: string[] | null;
+}
+/** Profil complet d'une requête (HTTP ou message WS), exposé par `get`. */
+export interface ProfileEntry {
+    requestId: string;
+    /** Horodatage de la collecte (`Date.now()`), pour le tri client. */
+    ts: number;
+    kind: "http" | "ws";
+    method: string | null;
+    url: string;
+    scheme: string;
+    status: number | null;
+    /** Durée totale serveur (ms), dérivée des phases. */
+    durationMs: number | null;
+    route: string | null;
+    controller: string | null;
+    action: string | null;
+    remoteAddress: string | null;
+    /** Identité (username) si le firewall l'a injectée, sinon `null`. */
+    user: string | null;
+    /** `traceparent` W3C Trace Context (P2.7) — corrélation distribuée RFC-propre. */
+    traceparent: string | null;
+    error: string | null;
+    phases: ProfilePhase[];
+    /** Requêtes ORM (SEAM futur — `undefined` tant qu'aucun adapter ne pushe). */
+    queries?: ProfileQuery[];
+    /** Traversée du firewall — `undefined` si la requête n'a croisé aucune zone. */
+    security?: ProfileSecurity;
+}
+/** Résumé léger d'un profil pour la liste `recent` (sans les phases). */
+export interface ProfileSummary {
+    requestId: string;
+    ts: number;
+    kind: "http" | "ws";
+    method: string | null;
+    url: string;
+    status: number | null;
+    durationMs: number | null;
+    route: string | null;
+    error: string | null;
+}
+/** Forme structurelle minimale lue sur un `Context` (lecture défensive). */
+interface ProfilableContext {
+    requestId?: string;
+    type?: string;
+    scheme?: string;
+    method?: string | null;
+    url?: string;
+    remoteAddress?: string | null;
+    traceparent?: string | null;
+    error?: {
+        message?: string;
+    } | null;
+    response?: {
+        statusCode?: number;
+    } | null;
+    phases?: ReadonlyArray<{
+        name: string;
+        startMs: number;
+        durationMs?: number;
+    }>;
+    resolver?: {
+        route?: {
+            name?: string;
+        } | null;
+        controller?: {
+            name?: string;
+        } | null;
+        actionName?: string;
+    } | null;
+    /**
+     * Buffer de requêtes ORM rempli pendant la requête (dev-only). Même tableau
+     * que la payload ALS — les adapters ORM y poussent via `RequestContext`.
+     * `null`/absent hors profiling.
+     */
+    profilerQueries?: ProfileQuery[] | null;
+    /**
+     * Zone firewall capturée (`SecuredArea`, posée par `Firewall.isSecure`). Lue
+     * en structurel : `@nodefony/http` ne peut pas importer `@nodefony/security`.
+     */
+    security?: {
+        name?: string;
+        security?: boolean;
+        mode?: string;
+        authenticators?: readonly string[];
+    } | null;
+    /** Décision du firewall sur cette requête (dev-only, cf `ISecurityTrace`). */
+    securityTrace?: {
+        authenticator: string | null;
+        outcome: string;
+        reason: string | null;
+        user: string | null;
+        roles: string[] | null;
+    } | null;
+}
+export declare class Profiler {
+    private readonly _buf;
+    private readonly _cap;
+    constructor(cap?: number);
+    /**
+     * Snapshot un `Context` en fin de requête. Tolérant aux champs absents
+     * (handshake WS, erreur précoce). À appeler AVANT `context.clean()`.
+     *
+     * @param ctx - le Context HTTP/WS terminé (lu en structurel, jamais muté).
+     */
+    collect(ctx: ProfilableContext): void;
+    /** Profil complet d'une requête, ou `undefined` si évincé/inconnu. */
+    get(requestId: string): ProfileEntry | undefined;
+    /**
+     * Résumés des requêtes les plus récentes (récent → ancien), capés à `limit`.
+     */
+    recent(limit?: number): ProfileSummary[];
+    /** Nombre de profils en mémoire. */
+    get size(): number;
+    /** Vide le ring buffer. */
+    clear(): void;
+}
+export default Profiler;

package/dist/types/nodefony/src/proxy/generateProxyConfig.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Générateurs de configuration reverse-proxy (nginx / haproxy) DÉRIVÉE de
+ * l'introspection Nodefony — fonctions PURES (aucun accès kernel/fs), testables
+ * et sérialisables. Le câblage (lecture des services) vit dans la commande CLI
+ * `proxy:generate` ; ici on ne fait que transformer un modèle → texte de conf.
+ *
+ * Résout le « trou statiques multi-modules » : Nodefony sert N dossiers `public/`
+ * (racine + un par module) AU MÊME préfixe `/`. nginx ne sait pas servir N roots
+ * sous `/` → on génère une CHAÎNE de `try_files` via des locations nommées
+ * (root d0 → @r1 → root d1 → … → @nodefony), fallback final vers le backend.
+ */
+/** Un dossier statique servi sous un préfixe d'URL (mount préfixé). */
+export interface ProxyStaticMount {
+    /** Préfixe d'URL (ex. `/_assets/studio/`). */
+    prefix: string;
+    /** Dossier absolu servi. */
+    dir: string;
+}
+/** Modèle d'introspection consommé par les générateurs. */
+export interface ProxyIntrospection {
+    /** `server_name` (hôtes de confiance, IP exclues). Vide → `_` (catch-all). */
+    domains: string[];
+    /** Hôte du backend Nodefony à joindre (ex. `host.docker.internal`). */
+    backendHost: string;
+    /** Port HTTP du backend (clair). */
+    httpPort: number;
+    /** Port HTTPS/2 du backend (re-encrypt). */
+    httpsPort: number;
+    /** Dossiers statiques servis à la racine `/` (ordre = priorité). */
+    staticRoots: string[];
+    /** Montages statiques préfixés (servis tels quels). */
+    mounts: ProxyStaticMount[];
+    /** Port d'écoute du proxy généré (défaut 80). */
+    listen: number;
+    /** Re-chiffrer vers le backend HTTPS (true) ou forward en clair (false). */
+    reencrypt: boolean;
+    /**
+     * Taille maximale d'un corps de requête acceptée par Nodefony, en octets
+     * (`http.maxBodySize`). `0` = ne rien imposer au proxy.
+     *
+     * Sans elle, nginx applique son propre défaut — **1 Mo** — et rend un `413`
+     * que le serveur ne voit jamais : l'application marche en direct et casse
+     * derrière le proxy, sur une limite que personne n'a écrite.
+     */
+    maxBodyBytes: number;
+    /**
+     * Intervalle du heartbeat WebSocket, en millisecondes (`ws.keepaliveInterval`,
+     * `0` = désactivé) — d'où les proxys tirent leur délai de tunnel.
+     *
+     * Une WebSocket est, vue d'un proxy, une connexion SANS trafic entre deux
+     * messages. Ce qui la garde en vie derrière nginx et haproxy, ce sont les
+     * pings du serveur : le délai d'inactivité doit donc être dérivé de leur
+     * intervalle, jamais posé au hasard. Heartbeat désactivé → plus rien ne borne
+     * le silence, et seul un délai franchement long évite de couper des sockets
+     * saines.
+     */
+    keepaliveIntervalMs: number;
+}
+/** Valeurs par défaut d'un modèle d'introspection (complété par la commande). */
+export declare const defaultIntrospection: ProxyIntrospection;
+/**
+ * Génère une configuration nginx complète (reverse-proxy + offload statiques).
+ *
+ * @param intro - modèle d'introspection Nodefony.
+ * @returns le contenu d'un `nginx.conf`.
+ */
+export declare function generateNginxConfig(intro: ProxyIntrospection): string;
+/**
+ * Génère une configuration haproxy (reverse-proxy + Forwarded RFC 7239).
+ * haproxy ne sert PAS de fichiers : les statiques sont proxifiés au backend
+ * (ou désactivés côté serveur via `statics.enabled: false` + un nginx/CDN).
+ *
+ * @param intro - modèle d'introspection Nodefony.
+ * @returns le contenu d'un `haproxy.cfg`.
+ */
+export declare function generateHaproxyConfig(intro: ProxyIntrospection): string;

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

@@ -0,0 +1,98 @@
+/**
+ * Contrat d'un compteur de **rate-limit général par IP** (P0.3) et son verdict.
+ *
+ * À NE PAS confondre avec `security.rateLimit` (backoff de LOGIN NIST, par
+ * identifiant saisi). Ici : plafond de trafic par IP cliente, sur TOUTES les
+ * routes HTTP, matérialisé par les en-têtes `X-RateLimit-*` + un `429` (RFC 6585).
+ *
+ * Le contrat est **SYNCHRONE** à dessein : `hit()` est appelé sur le hot-path de
+ * CHAQUE requête → aucune `Promise`, aucune microtask. Un futur store distribué
+ * (Redis, multi-pod) introduira son propre chemin d'exécution, pas ce contrat.
+ */
+import type { IPage, IPageQuery } from "nodefony";
+/**
+ * Verdict rendu par {@link IRateLimitStore.hit} — porte tout le nécessaire pour
+ * émettre les en-têtes `X-RateLimit-*` (+ `Retry-After` en cas de rejet) sans
+ * relire l'état du store.
+ */
+export interface RateLimitVerdict {
+    /** `true` si la requête dépasse le quota de la fenêtre → réponse `429`. */
+    readonly limited: boolean;
+    /** Plafond de la fenêtre — en-tête `X-RateLimit-Limit`. */
+    readonly limit: number;
+    /** Requêtes restantes dans la fenêtre courante (`X-RateLimit-Remaining`, ≥ 0). */
+    readonly remaining: number;
+    /** Fin de la fenêtre courante, en **ms epoch** (`X-RateLimit-Reset` = `⌈/1000⌉`). */
+    readonly resetAtMs: number;
+    /** Secondes jusqu'au reset (`Retry-After`) ; `0` si la requête n'est pas limitée. */
+    readonly retryAfterS: number;
+}
+/** Options de construction d'un {@link IRateLimitStore}. */
+export interface IRateLimitOptions {
+    /** Largeur de la fenêtre fixe, en **millisecondes**. */
+    readonly windowMs: number;
+    /** Nombre max de requêtes autorisées par clé (IP) et par fenêtre. */
+    readonly max: number;
+    /** Borne mémoire : nombre max de clés (IP) suivies simultanément. */
+    readonly maxTracked: number;
+}
+/**
+ * Une clé (IP) actuellement suivie, telle qu'exposée à l'INTROSPECTION admin —
+ * l'état, jamais le trafic : ni URL, ni en-tête, ni corps. Une IP reste une
+ * donnée personnelle → ce listing est réservé au data plane admin.
+ */
+export interface IRateLimitEntry {
+    /** Clé suivie (IP cliente résolue). */
+    readonly key: string;
+    /** Hits comptés dans la fenêtre courante. */
+    readonly count: number;
+    /** Fin de la fenêtre courante (ms epoch). */
+    readonly resetAtMs: number;
+    /** `true` si la clé a dépassé le plafond de la fenêtre (elle prend des 429). */
+    readonly limited: boolean;
+}
+/**
+ * Requête de listing des clés suivies — {@link IPageQuery} + le seul filtre qui
+ * a un sens ici. `q` (hérité) = préfixe de clé (« 10.0. » pour un sous-réseau),
+ * pas une sous-chaîne : sur une IP, seul le préfixe est signifiant.
+ */
+export interface IRateLimitListQuery extends IPageQuery {
+    /** `true` = seulement les clés au plafond, `false` = seulement les autres. */
+    limited?: boolean;
+}
+/**
+ * Compteur de rate-limit par clé (IP). Implémentation par défaut :
+ * {@link import("./MemoryRateLimitStore").MemoryRateLimitStore} (fenêtre fixe,
+ * en mémoire).
+ */
+export interface IRateLimitStore {
+    /**
+     * Enregistre un hit pour `key` (IP cliente résolue) et renvoie le verdict de
+     * la fenêtre courante. Synchrone, O(1).
+     */
+    hit(key: string): RateLimitVerdict;
+    /**
+     * Purge les fenêtres expirées (`resetAt <= now`). Appelé hors hot-path par le
+     * `GcScheduler` du core.
+     *
+     * @param nowMs - horloge injectable (ms epoch) ; défaut = horloge du store.
+     * @returns le nombre d'entrées purgées.
+     */
+    gc(nowMs?: number): number;
+    /**
+     * Page des clés suivies — introspection admin (« qui me martèle ? »). Ne
+     * matérialise jamais plus d'une page, filtres appliqués au store.
+     *
+     * **Asynchrone** alors que {@link IRateLimitStore.hit} est synchrone : ce
+     * listing est hors hot-path (console admin), et un futur store distribué le
+     * servira par `SCAN`. La contrainte « zéro Promise » ne vaut que pour `hit`.
+     *
+     * Ordre contractuel : `count` DESC (les plus bruyants d'abord — c'est LA
+     * question d'exploitation), départagé par `key` ASC.
+     */
+    listPage(query: IRateLimitListQuery): Promise<IPage<IRateLimitEntry>>;
+    /** Nombre de clés (IP) actuellement suivies — introspection / métrique. */
+    readonly trackedCount: number;
+    /** Total cumulé de requêtes rejetées (`429`) depuis le boot — métrique. */
+    readonly rejectedTotal: number;
+}

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

@@ -0,0 +1,40 @@
+import type { IPage } from "nodefony";
+import type { IRateLimitEntry, IRateLimitListQuery, IRateLimitOptions, IRateLimitStore, RateLimitVerdict } from "./IRateLimitStore.js";
+/**
+ * Store de rate-limit **en mémoire** — algorithme *fixed window* par clé (IP).
+ *
+ * Une entrée par IP `{ count, resetAt }` ; à l'expiration de la fenêtre le
+ * compteur repart à zéro (mutation in-place, 0 alloc pour une IP récurrente).
+ * `hit()` est O(1) (1 `Map.get` + arithmétique), et la `Map` est allouée en
+ * **lazy** au 1ᵉʳ hit → 0 coût mémoire si le rate-limit n'est jamais sollicité.
+ *
+ * Mémoire **bornée** par `maxTracked` : au cap, on purge d'abord les fenêtres
+ * expirées puis on évince en FIFO (ordre d'insertion `Map`). Un {@link gc}
+ * planifiable (GcScheduler du core) fait le ménage hors hot-path.
+ *
+ * ⚠️ Limite assumée (fenêtre fixe) : un pic à cheval sur deux fenêtres peut
+ * laisser passer jusqu'à `2 × max` sur un court intervalle. Acceptable pour une
+ * défense de capacité ; un *sliding window* viendrait en option si nécessaire.
+ */
+export declare class MemoryRateLimitStore implements IRateLimitStore {
+    #private;
+    /**
+     * @param options - fenêtre, plafond, borne mémoire.
+     * @param now - horloge injectable (ms) — `Date.now` par défaut, surchargée en test.
+     */
+    constructor(options: IRateLimitOptions, now?: () => number);
+    hit(key: string): RateLimitVerdict;
+    gc(nowMs?: number): number;
+    /**
+     * {@inheritDoc IRateLimitStore.listPage}
+     *
+     * La collection est déjà en RAM et **bornée par `maxTracked`** (c'est la
+     * nature de ce store) : le tri porte sur des références, seule la page est
+     * matérialisée en objets de sortie. Les fenêtres expirées sont exclues à la
+     * lecture — les montrer ferait passer un compteur mort pour du trafic vivant
+     * (le `gc` les retire plus tard, hors hot-path).
+     */
+    listPage(query: IRateLimitListQuery): Promise<IPage<IRateLimitEntry>>;
+    get trackedCount(): number;
+    get rejectedTotal(): number;
+}