@nodefony/http 10.0.0-alpha.1

package/dist/types/nodefony/interfaces/ISession.d.ts

@@ -0,0 +1,283 @@
+import type { IPage, IPageQuery, ISortableSource } from "nodefony";
+import type { ICookie, ICookieOptions } from "./ICookie.js";
+export type SessionStatusType = "none" | "active" | "disabled";
+export type SessionStrategyType = "none" | "migrate" | "invalidate";
+export type FlashBagType = Record<string, unknown>;
+export type MetaBagType = Record<string, unknown>;
+/**
+ * Intent d'activation de session déclaré par une route (décorateur `@UseSession`
+ * de `@nodefony/framework`, ou présence d'un paramètre `@Session`). Lu au point
+ * d'activation **unique** du pipeline (HTTP comme WS) : c'est lui — et non plus un
+ * `sessionAutoStart` global « démarre partout » — qui décide d'ouvrir une session.
+ *
+ * - `readOnly` : la session est lue/reprise mais **jamais persistée** (0 write storage).
+ */
+export interface SessionIntent {
+    readOnly?: boolean;
+}
+/**
+ * Données de session **sérialisées** échangées avec un {@link ISessionStorage}
+ * (blob opaque persisté/restauré). La forme métier riche (ProtoService/bags) est
+ * l'affaire de `Session` ; le storage ne manipule que cette projection JSON-safe.
+ */
+export interface ISerializedSession {
+    Attributes: Record<string, unknown>;
+    metaBag: Record<string, unknown>;
+    flashBag: Record<string, unknown>;
+    user: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+/**
+ * Projection **redactée** d'une session pour l'ADMINISTRATION (data plane Studio,
+ * `/nodefony/http/api/sessions`). Construite par allowlist — **jamais** par `delete`
+ * après coup — donc ne porte par construction ni `Attributes` ni `flashBag` (données
+ * métier potentiellement sensibles), ni l'**id de session brut** (= la valeur du
+ * cookie ; le posséder = être connecté).
+ *
+ * À la place : {@link ISessionSummary.ref}, pseudonyme HMAC stable et **non
+ * réversible** (cf `SessionsService.sessionRef`). Standard « appareils connectés »
+ * GitHub/Google : on montre une référence, jamais le jeton de session.
+ */
+export interface ISessionSummary {
+    /** Pseudonyme `HMAC(secret, id)` tronqué (préfixe `sess_…`). JAMAIS l'id brut. */
+    ref: string;
+    /** Identifiant de l'utilisateur porté par la session (chaîne vide = anonyme). */
+    user: string;
+    /** Vrai si la session porte un utilisateur authentifié (`user` non vide). */
+    authenticated: boolean;
+    /** IP capturée au login (`metaBag.ip`), ou `null` si non capturée / anonyme. */
+    ip: string | null;
+    /** User-Agent capturé au login (`metaBag.ua`), ou `null` si non capturé. */
+    ua: string | null;
+    /** Création de la session (epoch ms), ou `null` si inconnue. */
+    createdAt: number | null;
+    /** Dernière persistance (epoch ms), ou `null` si inconnue. */
+    updatedAt: number | null;
+    /** Réserve multi-tenant (toujours `null` en mono-tenant — slot coût-0). */
+    tenantId: string | null;
+    /**
+     * Vrai si cette entrée est **la session qui porte la requête en cours** — le
+     * « cet appareil » des consoles d'appareils connectés.
+     *
+     * Sans elle, un client qui liste ses sessions ne peut désigner AUCUNE ligne :
+     * ni celle qu'il ne doit pas fermer, ni celle qu'il veut fermer. Deux
+     * conséquences vécues, la même cause : la console d'administration marquait
+     * « vous appartient » toutes les lignes (comparaison sur l'UTILISATEUR, jamais
+     * sur la session), et un banc révoquait « la sienne » en prenant la première
+     * de la liste — c'est-à-dire la plus récente du COMPTE, celle d'un voisin dès
+     * que deux clients partagent l'identité.
+     *
+     * `false` quand la requête ne porte pas de session (invocation CLI, appel
+     * interne) : l'énumération est alors faite par personne, aucune ligne n'est
+     * « celle-ci ».
+     */
+    current: boolean;
+}
+/**
+ * Entrée **brute** d'énumération renvoyée par {@link ISessionStorage.listAll} :
+ * l'id opaque RÉEL + le blob sérialisé. Usage strictement **interne au process**
+ * (le service en a besoin pour calculer le `ref` et révoquer par id) — n'est
+ * JAMAIS sérialisée vers une réponse HTTP : `SessionsService` la projette en
+ * {@link ISessionSummary} (redaction par construction).
+ *
+ * Optimisation côté stores SQL/NoSQL : `data.Attributes`/`data.flashBag` peuvent
+ * être renvoyés vides (les secrets ne quittent alors jamais la base) — seuls
+ * `user`/`metaBag`/timestamps sont nécessaires à la projection.
+ */
+export interface ISessionRecord {
+    /** Identifiant opaque réel de la session (interne — jamais exposé via l'API). */
+    id: string;
+    data: ISerializedSession;
+}
+/**
+ * Filtre d'énumération admin de {@link ISessionStorage.listAll}. Tous les champs
+ * sont optionnels. Un store SQL peut honorer `user` (WHERE indexable) ; les autres
+ * peuvent l'ignorer — `SessionsService.listAllSessions` ré-applique le filtre de
+ * façon défensive. `tenantId` = slot multi-tenant (ignoré en mono-tenant).
+ */
+export interface ISessionListFilter {
+    /** Restreint aux sessions d'un utilisateur (pour « déconnecter partout »). */
+    user?: string;
+    /** Slot multi-tenant — non scopé aujourd'hui (réserve coût-0). */
+    tenantId?: string | null;
+}
+/**
+ * Requête d'énumération **paginée** des sessions — le {@link IPageQuery} standard
+ * de Nodefony étendu des filtres propres au store de session. C'est la forme que
+ * consomme {@link ISessionStorage.listPage} ; `ISessionListFilter` reste la forme
+ * non paginée du dump {@link ISessionStorage.listAll}.
+ *
+ * **Filtres portables par construction** (`user` = égalité, `authenticated` =
+ * `user` non vide) : ils s'expriment dans tous les backends — `WHERE` SQL/Mongo
+ * indexable, prédicat mémoire — donc aucun n'oblige un store à matérialiser la
+ * collection pour filtrer.
+ *
+ * **Tri** : l'ordre du contrat est `updatedAt` DESC (session la plus récemment
+ * active d'abord), départagé par l'id pour rester **déterministe** à horodatage
+ * égal (deux sessions écrites dans la même milliseconde). Un backend curseur
+ * (Redis `SCAN`) n'a pas d'ordre global — il l'annonce, il ne le simule pas.
+ */
+export interface ISessionListQuery extends IPageQuery, ISessionListFilter {
+    /**
+     * Restreint aux sessions **authentifiées** (`true` : `user` non vide) ou
+     * **anonymes** (`false`). Omis = les deux. Sert les KPI de la console admin
+     * sans jamais énumérer (cf {@link ISessionStorage.countSessions}).
+     */
+    authenticated?: boolean;
+}
+/**
+ * Contrat **unique** d'un backend de stockage de session (File, Redis, SQL/Drizzle…).
+ * Source de vérité unifiée — l'ex-doublon `sessionStorageInterface` (any) n'est plus
+ * qu'un alias transitionnel. Enregistré dans le registre IoC `SessionsService.registerStorage`.
+ */
+export interface ISessionStorage extends ISortableSource {
+    read(id: string): Promise<ISerializedSession>;
+    write(id: string, data: ISerializedSession): Promise<ISerializedSession>;
+    start(id: string): Promise<ISerializedSession>;
+    open(): Promise<number>;
+    close(): boolean;
+    destroy(id: string): Promise<boolean>;
+    /**
+     * Purge les sessions expirées sur les **deux bornes** NIST/OWASP : idle
+     * (inactivité depuis `updatedAt`) ET absolute (âge depuis `createdAt`, jamais
+     * prolongé). `absoluteSeconds` omis/0 → seul l'idle s'applique. Hors hot-path
+     * (timer `GcScheduler`). Un store à TTL natif (Redis) peut le laisser no-op
+     * pour l'idle — l'absolute restant honoré à la lecture (`isValidSession`).
+     */
+    gc(idleSeconds?: number, absoluteSeconds?: number): Promise<void>;
+    /**
+     * **Prolonge l'idle timeout** d'une session active (timeout glissant) SANS
+     * réécrire son blob — `UPDATE updatedAt` (SQL), `EXPIRE` (Redis TTL), `utimes`
+     * (fichier). Capacité **optionnelle** : un store qui ne l'implémente pas voit
+     * son idle prolongé uniquement par un vrai `write` (mutation) → dégradation
+     * gracieuse, jamais un breaking.
+     *
+     * Appelé de façon **throttlée** (1 fois par tranche d'idle, jamais par requête)
+     * sur l'activité HTTP/WS — y compris en lecture seule — pour qu'une session
+     * réellement utilisée n'expire pas. N'affecte **jamais** l'absolute timeout
+     * (borné à la création).
+     *
+     * @param id - identifiant opaque de la session.
+     * @param idleSeconds - idle courant (les stores à TTL natif, ex. Redis, en ont
+     *   besoin pour repositionner l'expiration).
+     */
+    touch?(id: string, idleSeconds?: number): Promise<void>;
+    /**
+     * Énumère les sessions persistées — capacité d'**ADMINISTRATION** (gouvernance,
+     * « déconnecter partout »), **optionnelle**. Un backend incapable de lister
+     * (KV sans scan, edge…) l'omet : l'endpoint admin répond alors **501** (refus
+     * honnête), jamais une liste vide trompeuse.
+     *
+     * Renvoie des {@link ISessionRecord} bruts (id réel + blob) — le service les
+     * redacte. Coût **O(N)** assumé (admin, faible fréquence, pas de hot-path) ;
+     * un index inverse `user → [id]` reste une optimisation future.
+     *
+     * @param filter - restriction optionnelle (ex. `user`) ; un store peut l'honorer
+     *   (WHERE SQL) ou l'ignorer (le service ré-applique).
+     */
+    listAll?(filter?: ISessionListFilter): Promise<ISessionRecord[]>;
+    /**
+     * Énumère **une page** de sessions — la capacité d'administration NORMALE
+     * (console, « mes appareils », révocation). Contrairement à {@link listAll},
+     * un store conforme ne matérialise **jamais** plus d'une page : `LIMIT/OFFSET`
+     * SQL, `skip/limit` Mongo, `SCAN` par curseur Redis, tranche mémoire. C'est ce
+     * qui rend le coût d'une requête admin indépendant du nombre de sessions.
+     *
+     * Optionnelle, comme {@link listAll} : un backend incapable d'énumérer l'omet
+     * → l'endpoint admin répond **501** (refus honnête), jamais une page vide
+     * trompeuse.
+     *
+     * **Redaction par construction — garantie du contrat, pas une optimisation** :
+     * les records rendus portent `Attributes` et `flashBag` **vides**. Les données
+     * métier d'une session (potentiellement des secrets) n'ont aucune raison de
+     * traverser la couche d'administration : les stores SQL/NoSQL ne les
+     * sélectionnent pas, les stores mémoire ne les recopient pas. Un appelant qui
+     * oublierait la projection en {@link ISessionSummary} ne peut donc pas les
+     * faire fuiter. (Le dump {@link listAll}, lui, reste libre de les porter.)
+     *
+     * **Deux modes, déclarés par le store dans sa réponse** :
+     * - **offset** — `total` exact (sauf `withTotal:false`) et ordre `updatedAt`
+     *   DESC déterministe ; `nextCursor` absent.
+     * - **curseur** — `nextCursor` à repasser en {@link IPageQuery.cursor}, pas de
+     *   `total` ni d'ordre global, taille de page variable. Le client boucle
+     *   jusqu'à `nextCursor === null`. Capacité réduite **assumée**, pas simulée.
+     *
+     * @param query - page + filtres ({@link ISessionListQuery}).
+     * @returns la page de {@link ISessionRecord} bruts — le service les redacte.
+     */
+    listPage?(query: ISessionListQuery): Promise<IPage<ISessionRecord>>;
+    /**
+     * Compte les sessions correspondant aux filtres, **sans les énumérer** (`COUNT`
+     * natif SQL/Mongo). Alimente les KPI de la console (total, authentifiées vs
+     * anonymes) sans jamais charger de collection.
+     *
+     * @param query - les **filtres** seuls. Un comptage n'a pas de fenêtre : `limit`
+     *   et `offset` n'y ont aucun sens, d'où le `Partial` (le contrat de page rend
+     *   `limit` obligatoire, ce qui obligerait l'appelant à inventer une valeur
+     *   ignorée).
+     * @returns le total exact, ou **`-1`** si le backend ne sait pas compter à coût
+     *   raisonnable (Redis : compter = re-`SCAN` tout le keyspace). `-1` est un
+     *   « je ne sais pas » explicite — l'appelant affiche l'inconnu, il ne l'invente pas.
+     */
+    countSessions?(query?: Partial<ISessionListQuery>): Promise<number>;
+    /**
+     * Compte les utilisateurs **distincts** portant au moins une session active.
+     *
+     * Ce n'est pas un {@link countSessions} avec un filtre de plus : dédupliquer
+     * exige de regrouper, là où compter n'exige que de parcourir. C'est pourquoi
+     * la capacité vit ici, sur le store, et non dans la table de facettes de la
+     * ressource — un `COUNT(DISTINCT …)` est trivial en SQL, direct en Mongo, et
+     * hors de portée d'un backend en curseur.
+     *
+     * Sépare deux nombres que la console confondrait sinon : « 400 sessions » et
+     * « 12 personnes connectées » ne racontent pas la même chose sur un parc.
+     *
+     * @param query - mêmes filtres que {@link countSessions} ; le décompte porte
+     *   sur le sous-ensemble filtré.
+     * @returns le nombre d'utilisateurs distincts, ou **`-1`** si le backend ne
+     *   sait pas agréger (même convention que {@link countSessions}).
+     */
+    countDistinctUsers?(query?: Partial<ISessionListQuery>): Promise<number>;
+}
+export interface ISession {
+    id: string;
+    name: string;
+    status: SessionStatusType;
+    saved: boolean;
+    /** Vrai si la session a été mutée sans être encore persistée (dirty-tracking). */
+    dirty: boolean;
+    /** Lecture seule : la session est reprise mais jamais persistée (0 write storage). */
+    readOnly: boolean;
+    migrated: boolean;
+    cookieSession: ICookie | null | undefined;
+    flashBag: FlashBagType;
+    strategy: SessionStrategyType;
+    created?: Date;
+    updated?: Date;
+    user?: string;
+    lifetime?: number;
+    storage: ISessionStorage;
+    start(context: unknown): Promise<ISession>;
+    save(user?: string): Promise<ISession>;
+    invalidate(lifetime?: number, id?: string, options?: ICookieOptions): Promise<ISession>;
+    destroy(cookieDelete?: boolean): Promise<boolean>;
+    create(lifetime: number, id?: string, options?: ICookieOptions): ISession;
+    /** Régénère un identifiant opaque CSPRNG en conservant l'état (anti session-fixation, appelée au login par `AuthFlow`). */
+    regenerateId(): void;
+    get(key: string): unknown;
+    set(key: string, value: unknown): unknown;
+    getAttributes(): unknown;
+    getMetaBag(key: string): unknown;
+    setMetaBag(key: string, value: unknown): unknown;
+    getMetas(): MetaBagType;
+    getFlashBag(key: string): unknown;
+    setFlashBag(key: string, value: unknown): unknown;
+    flashBags(): FlashBagType;
+    clearFlashBag(key: string): void;
+    clearFlashBags(): void;
+    getName(): string;
+    checkStatus(): "restart" | boolean;
+    serialize(user?: string): ISerializedSession;
+    deSerialize(data: ISerializedSession): void;
+}

package/dist/types/nodefony/interfaces/IUpload.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Forme neutre d'un fichier multipart parsé (temp écrit sur disque), découplée
+ * du parser sous-jacent. Remplace l'ex-couplage à `formidable.File` : le moteur
+ * de parsing (busboy) n'apparaît plus dans le contrat consommé par
+ * `UploadedFile`. Champs alignés sur ce que lit `UploadedFile.create`.
+ */
+export interface IParsedUploadFile {
+    /** Chemin absolu du fichier temporaire écrit sur disque. */
+    filepath: string;
+    /** Nom de fichier temporaire généré (UUID + extension). */
+    newFilename: string;
+    /** Nom de fichier d'origine déclaré par le client (peut être null). */
+    originalFilename: string | null;
+    /** Type MIME déclaré dans la part multipart. */
+    mimetype: string | null;
+    /** Taille réellement écrite sur disque (octets). */
+    size: number;
+    /** Date d'écriture du temporaire. */
+    mtime: Date | null;
+    /** Algorithme de hash appliqué pendant le stream, ou `false` si aucun. */
+    hashAlgorithm: false | "sha1" | "md5" | "sha256";
+    /** Hash hexadécimal du contenu si `hashAlgorithm` configuré, sinon null. */
+    hash: string | null;
+}
+/**
+ * Options du sous-système d'upload (clé de config `upload`). Mappées sur les
+ * `limits` de busboy + la gestion temp/hash propre à Nodefony.
+ */
+export interface IUploadOptions {
+    /** Répertoire de dépôt des fichiers temporaires. */
+    uploadDir?: string;
+    /** Taille max d'UN fichier (octets) — `limits.fileSize` busboy. */
+    maxFileSize?: number;
+    /** Taille max CUMULÉE des fichiers d'une requête (octets) — appliquée par Nodefony. */
+    maxTotalFileSize?: number;
+    /** Nombre max de fichiers — `limits.files` busboy. */
+    maxFiles?: number;
+    /** Nombre max de champs texte — `limits.fields` busboy. */
+    maxFields?: number;
+    /** Taille max d'un champ texte (octets) — `limits.fieldSize` busboy. */
+    maxFieldsSize?: number;
+    /** Hash calculé pendant le stream (défaut `false` = aucun). */
+    hashAlgorithm?: false | "sha1" | "md5" | "sha256";
+    /** Encodage par défaut des parts texte. */
+    encoding?: string;
+}
+export interface IUploadedFile {
+    filename: string;
+    size: number;
+    prettySize: string;
+    mimeType: string | null | undefined;
+    hash: string | null | undefined;
+    hashAlgorithm: false | "sha1" | "md5" | "sha256";
+    lastModifiedDate: Date | null | undefined;
+    move(target: string): IUploadedFile;
+    /** Variante non bloquante de `move()` (recommandée dans le pipeline). */
+    moveAsync(target: string): Promise<IUploadedFile>;
+    getMimeType(): string | null | undefined;
+    getSize(): number;
+    getPrettySize(): string;
+}
+export interface IUploadService {
+    path?: string | unknown;
+    /** Construit un `UploadedFile` en async (stat non bloquant). */
+    createUploadFile(file: unknown, name: string): Promise<IUploadedFile>;
+}

package/dist/types/nodefony/interfaces/index.d.ts

@@ -0,0 +1,7 @@
+export type { ICookie, ICookieOptions, IWsCookie, SameSiteType, PriorityType, } from "./ICookie.js";
+export type { ISession, ISessionStorage, ISerializedSession, SessionIntent, SessionStatusType, SessionStrategyType, FlashBagType, MetaBagType, } from "./ISession.js";
+export type { IUploadedFile, IUploadService, IParsedUploadFile, IUploadOptions, } from "./IUpload.js";
+export type { IRequest, IHttpRequest, IHttp2Request, IWsRequest, HTTPMethodType, } from "./IRequest.js";
+export type { IResponse, IHttpResponse, IWebsocketResponse } from "./IResponse.js";
+export type { IContext, IHttpContext, IWebsocketContext, ServerType, SchemeType, WebSocketStateType, CookiesMap, } from "./IContext.js";
+export type { IHttpKernel } from "./IHttpKernel.js";

package/dist/types/nodefony/service/HttpAdminApi.d.ts

@@ -0,0 +1,18 @@
+import type { Module } from "nodefony";
+import type { IAdminApi } from "nodefony";
+/**
+ * Producteur `IAdminApi` du module **http** — exposé sous `/nodefony/http/api/*`.
+ *
+ * 2ᵉ producteur du data plane admin (le 1er étant le kernel). Démontre le
+ * pattern multi-modules : `@nodefony/http` n'importe QUE le contrat core
+ * (`IAdminApi`) — jamais `@nodefony/framework` (dépendance circulaire). Il
+ * s'enregistre auprès du broker via `IAdminRegistry` récupéré du container.
+ *
+ * Endpoints :
+ *  - `GET /nodefony/http/api/servers` → liste des serveurs réseau + leur état
+ *  - `GET /nodefony/http/api/info`    → résumé (serveurs prêts, ports, schemes)
+ *
+ * @param module - le module http (accès aux services serveur du container).
+ * @returns le contrat admin de http, prêt à `registry.register()`.
+ */
+export declare function createHttpAdminApi(module: Module): IAdminApi;

package/dist/types/nodefony/service/ProfilerAdminApi.d.ts

@@ -0,0 +1,23 @@
+import type { IAdminApi } from "nodefony";
+import type { Profiler } from "../src/profiler/Profiler.js";
+/**
+ * Producteur `IAdminApi` du **profiler** — exposé sous `/nodefony/profiler/api/*`.
+ *
+ * Namespace dédié (≠ replié dans `http`) car le profiling par requête est un
+ * concern transverse : timing par phase, route, user, futur SQL/audit. Il a sa
+ * propre entrée Studio et n'est monté qu'en **dev** (le module n'instancie le
+ * {@link Profiler} qu'hors prod).
+ *
+ * Endpoints :
+ *  - `GET /nodefony/profiler/api/recent`  → derniers profils (résumés, récent → ancien)
+ *  - `GET /nodefony/profiler/api/{id}`    → profil complet (phases) d'un requestId
+ *  - `DELETE /nodefony/profiler/api/recent` → vide le ring buffer
+ *
+ * La debug bar (toute page, dev) lit `X-Request-Id` de SON appel AJAX puis
+ * fetch `/{id}` — corrélation client↔serveur gratuite.
+ *
+ * @param profiler - l'instance partagée du ring buffer (même que le hook kernel).
+ * @returns le contrat admin du profiler, prêt à `registry.register()`.
+ */
+export declare function createProfilerAdminApi(profiler: Profiler): IAdminApi;
+export default createProfilerAdminApi;

package/dist/types/nodefony/service/audit-logger.d.ts

@@ -0,0 +1,143 @@
+import type { Severity } from "nodefony";
+import type { IRequestLogger, IRequestLogEntry } from "../interfaces/IRequestLogger.js";
+import type { IHttpContext, IWebsocketContext } from "../interfaces/IContext.js";
+/**
+ * Canonical audit log entry — 1 JSON PDU per request (P3.1).
+ *
+ * Fed to `context.log()` as a stringified JSON payload. Ingest pipelines
+ * (Vision, Loki, ELK, OpenTelemetry...) can parse it directly without
+ * regex on a colored line.
+ *
+ * Includes P3.3 (severity per HTTP status) for free and exposes phase
+ * timings (P1.1) for downstream trace tools (P3.7).
+ *
+ * Header redaction (P3.4) — Authorization / Cookie / Set-Cookie are
+ * never serialised here. We log presence-only flags instead.
+ */
+export interface AuditLogEntry {
+    ts: string;
+    requestId: string;
+    userId: string | null;
+    type: "http" | "ws";
+    scheme: string;
+    method: string | null;
+    url: string;
+    status: number | null;
+    durationMs: number | null;
+    remoteAddress: string | null;
+    host: string | null;
+    userAgent: string | null;
+    hasAuthorization: boolean;
+    hasCookie: boolean;
+    phases?: {
+        name: string;
+        durationMs: number | null;
+    }[];
+    error?: AuditErrorEntry;
+    protocol?: string | null;
+}
+/**
+ * Enriched error description for audit logs (P3.5).
+ * Includes optional cause chain (Error.cause) and stack (dev only).
+ */
+export interface AuditErrorEntry {
+    name: string;
+    message: string;
+    code?: number;
+    /** nodefonyError's domain classifier when available (P1.5 / Phase 1). */
+    errorType?: string;
+    /** Multi-line stack — dev/development only, omitted in prod for safety. */
+    stack?: string;
+    /** Recursive — capped to depth 5 to avoid pathological cycles. */
+    cause?: AuditErrorEntry;
+}
+/**
+ * Severity derived from HTTP status code — RFC 9110 categories.
+ * 1xx/2xx/3xx → INFO ; 4xx → WARNING ; 5xx → ERROR.
+ * Unknown/missing status → INFO.
+ */
+declare function severityFromStatus(status: number | null | undefined): Severity;
+export interface JsonAuditLoggerOptions {
+    /**
+     * Whether to include `error.stack` and recursive `error.cause.stack`.
+     * Default `process.env.NODE_ENV !== "production"` — auto-hidden in prod.
+     * Override explicitly for stricter security or to enable in staging.
+     */
+    includeStack?: boolean;
+    /**
+     * Max depth for `Error.cause` chain serialisation.
+     * Default `5`. Prevents pathological cycles and oversized log entries.
+     */
+    maxCauseDepth?: number;
+    /**
+     * Sampling rate for nominal (2xx/3xx) audit logs — perf lever on the hot
+     * path (L3). `1` (default) logs every request. `N > 1` logs only 1 in N of
+     * the 2xx/3xx requests, **but always logs `status >= 400` and errored
+     * requests** (you never lose a failure). Counted with a deterministic
+     * counter — no RNG (consistent with the L2 entropy amortisation).
+     *
+     * Skipped requests never reach `renderHttp`, so they cost **zero** object
+     * allocation and zero `JSON.stringify`. Configure via
+     * `kernel.options.log.requestLogger.sampleRate`.
+     */
+    sampleRate?: number;
+    /**
+     * T1 (profil delta vs Express) — audit du chemin NOMINAL (2xx/3xx).
+     * `false` → seules les requêtes en erreur et les `status >= 400` sont
+     * auditées (jamais gâtées — OWASP, faible volume, valeur forensique max).
+     * Résolu AU BOOT par `HttpKernel.applyRequestLoggerFromConfig` depuis
+     * `log.requestLogger.nominal` (`"auto"` défaut = coupé SSI
+     * `log.driver === "null"`, où l'entrée d'audit n'atteint AUCUNE destination
+     * texte — elle coûtait objet + toISOString + stringify + Pdu ring pour rien,
+     * ~5,9 % du profil CPU). Défaut `true` (comportement historique).
+     */
+    nominal?: boolean;
+}
+/**
+ * JSON audit logger — implements IRequestLogger so it slots into
+ * `httpKernel.setRequestLogger(new JsonAuditLogger())`.
+ *
+ * Stateless singleton. Allocates one plain object + one JSON.stringify per
+ * request — acceptable since this is the terminal log path (1 per req).
+ */
+declare class JsonAuditLogger implements IRequestLogger {
+    private readonly includeStack;
+    private readonly maxCauseDepth;
+    /** Sampling divisor for 2xx/3xx logs (`1` = log all). Always ≥ 1. */
+    private readonly sampleRate;
+    /** Deterministic 0-based counter for `1/sampleRate` selection (no RNG). */
+    private sampleCounter;
+    /** T1 — `false` = audit nominal coupé (erreurs/4xx/5xx toujours audités). */
+    private readonly nominalEnabled;
+    constructor(opts?: JsonAuditLoggerOptions);
+    /**
+     * Decide whether the current HTTP request must be logged (audit sampling).
+     *
+     * Always `true` when `sampleRate <= 1`, on errors, and for `status >= 400`
+     * (failures are never sampled out). Otherwise selects 1 in `sampleRate` of
+     * the 2xx/3xx requests with a deterministic counter.
+     *
+     * Called by `Context.logRequest()` **before** `renderHttp`, so a sampled-out
+     * request allocates nothing and runs no `JSON.stringify`.
+     *
+     * @param context - the HTTP context being finalised
+     * @param error - error captured for this request, if any
+     * @returns `true` to render+log the entry, `false` to skip it
+     */
+    shouldSample(context: IHttpContext, error?: Error | null): boolean;
+    renderHttp(context: IHttpContext, error?: Error | null): IRequestLogEntry;
+    renderWebsocket(context: IWebsocketContext, error?: Error | null, acceptedProtocol?: string | null): IRequestLogEntry;
+    /**
+     * Total request duration computed from the first phase startMs to now.
+     * Returns null if timing is disabled (no phases recorded).
+     */
+    private computeDurationMs;
+    /**
+     * Serialise an Error (recursively for `cause` chain) into an AuditErrorEntry.
+     * Stack is included only when `includeStack === true` (dev default).
+     * Cause chain is capped at `maxCauseDepth`.
+     */
+    private serializeError;
+}
+export default JsonAuditLogger;
+export { severityFromStatus };