@nodefony/security 10.0.0-alpha.1

package/dist/types/nodefony/src/admin/SecurityAdminApi.d.ts

@@ -0,0 +1,82 @@
+import type { Container } from "nodefony";
+import type { IAdminApi, IAdminRegistry } from "nodefony";
+import type { ITokenListQuery } from "../../contracts/ITokenStore.js";
+import type { IAuditListQuery } from "../../contracts/IAuditStore.js";
+/**
+ * Traduit la query string admin en {@link ITokenListQuery} bornée (`limit` par
+ * défaut 50, cap 200 ; pagination, tri et filtres de {@link TOKEN_FILTERS}).
+ *
+ * **UN SEUL traducteur par dimension, jamais deux.** Pour la page et le tri,
+ * `parsePageQuery` ; pour les filtres, `parseFilters`. En appeler un second sans
+ * son allowlist ferait refuser en 400 ce que le premier venait d'accepter, et
+ * aucun test unitaire ne le verrait (chaque appel est correct isolément).
+ *
+ * Un filtre inconnu ou mal formé est désormais **refusé** (400) au lieu d'être
+ * ignoré : `?status=revoqué` rendait la liste ENTIÈRE, que la console affichait
+ * comme le résultat du filtre demandé.
+ *
+ * @param query - `request.query` du broker admin.
+ * @param sortable - champs que le backend branché sait trier ; un `?order=`
+ *   portant autre chose est refusé en 400 par le traducteur. Liste vide (store à
+ *   curseur, store absent) ⇒ tout tri est refusé, ce qui est la vérité du backend.
+ */
+export declare function parseTokenListQuery(query: Readonly<Record<string, string | string[]>>, sortable: readonly string[]): ITokenListQuery;
+/**
+ * Traduit la query string admin en {@link IAuditListQuery} typée — pagination
+ * par curseur, plus les filtres de {@link AUDIT_FILTERS}.
+ *
+ * Un filtre inconnu ou mal formé est **refusé** (400). Il était auparavant
+ * ignoré, au nom de la robustesse de la console : mais un journal d'audit rendu
+ * ENTIER à qui demandait `?outcome=deneid` n'est pas robuste — c'est la pire
+ * réponse possible à un auditeur, qui lit l'absence de refus comme l'absence
+ * d'incident. Le typage suit la même source : les valeurs viennent de la spec,
+ * il n'y a plus de `as AuditCategory` à écrire ici.
+ *
+ * Le `limit` est **toujours posé** (défaut {@link AUDIT_DEFAULT_LIMIT}, cap du
+ * traducteur) : le contrat de page n'admet pas « tout » ; le store applique en
+ * plus son propre plafond, l'appelant ne peut donc pas s'en servir pour tirer un
+ * journal entier.
+ *
+ * @param query - `request.query` du broker admin.
+ * @returns filtre prêt pour `auditService.listPage`.
+ * @throws `PageQueryError` (400) sur un filtre inconnu ou mal formé.
+ */
+export declare function parseAuditQuery(query: Readonly<Record<string, string | string[]>>): IAuditListQuery;
+/**
+ * Producteur admin (`IAdminApi`) du module sécurité — data plane consommé par
+ * Studio (section Sécurité, P6.15) :
+ *
+ *  - `GET /nodefony/security/api/audit/events` — page filtrée du journal d'audit
+ *    (P6.14 Lot 3 ; `?category&outcome&actor&action&requestId&since&until&limit&cursor`),
+ *    du plus récent au plus ancien, pagination par curseur (`cursor` / `nextCursor`).
+ *  - `GET /nodefony/security/api/firewall` — introspection du firewall (zones,
+ *    authenticators montés, défenses) — état RUNTIME, secrets exclus.
+ *  - `GET /nodefony/security/api/roleHierarchy` — hiérarchie de rôles + résolution.
+ *  - `GET /nodefony/security/api/apikeys` — toutes les clés API (gouvernance),
+ *    `GET …/apikeys/status` — backend du token store (« où on écrit »),
+ *    `POST …/apikeys/{id}/revoke` — révocation par id (réponse à incident).
+ *  - `GET …/users/{id}/passkeys` + `DELETE …/users/{id}/passkeys/{credentialId}`
+ *    — passkeys d'un utilisateur (vue admin sans clé publique) + révocation
+ *    owner-scopée (reset facteur fort, audité).
+ *  - `GET …/users/{id}/totp` + `POST …/users/{id}/totp/disable` — état du 2FA
+ *    TOTP + désactivation (reset facteur fort, audité). Pas d'enrôlement
+ *    cross-user (le secret se scanne sur l'appareil de l'utilisateur).
+ *
+ * **RBAC `ROLE_NODEFONY_ADMIN`** (appliqué par le broker, 403 sinon) — la console
+ * sécurité ne se consulte qu'en administrateur. Handlers **lazy** : ils résolvent
+ * `auditService`/`firewall` à la requête (service désactivable → 503), jamais au
+ * montage. Le namespace `"security"` est distinct des routes classiques
+ * `/nodefony/security/api/keys` (P6.12) — paths disjoints, zéro collision.
+ *
+ * @param container - container du kernel (résolution lazy des services).
+ */
+export declare function createSecurityAdminApi(container: Container): IAdminApi;
+/**
+ * Enregistre le producteur admin sécurité sur le broker — **idempotent** (no-op
+ * si déjà monté). À appeler au `onKernelBoot` du module (avant le montage des
+ * routes par framework à `onKernelReady`). Calque `registerOrmAdminApi`.
+ *
+ * @param registry - broker admin (`container.get("adminBroker")`).
+ * @param container - container du kernel (capturé par le handler lazy).
+ */
+export declare function registerSecurityAdminApi(registry: IAdminRegistry, container: Container): void;

package/dist/types/nodefony/src/admin/WebhookAdminApi.d.ts

@@ -0,0 +1,30 @@
+import type { Container, IAdminEndpoint } from "nodefony";
+import type { IWebhookListQuery } from "../../contracts/IWebhookStore.js";
+/**
+ * Traduit la query string admin en {@link IWebhookListQuery} **bornée**
+ * (`limit` défaut 50, cap 200 ; pagination, tri, et les filtres de
+ * {@link WEBHOOK_FILTERS}). Pagination **offset uniquement** : les trois stores
+ * webhook (memory/drizzle/mongoose) sont offset-pur — aucun curseur ici.
+ *
+ * **UN SEUL traducteur par dimension, jamais deux** : `parsePageQuery` pour la
+ * page et le tri, `parseFilters` pour les filtres. En appeler un second sans son
+ * allowlist ferait refuser en 400 ce que le premier venait d'accepter, et aucun
+ * test unitaire ne le verrait.
+ *
+ * Un filtre inconnu ou mal formé est **refusé** (400) et non plus ignoré :
+ * `?enabled=oui` rendait la liste entière, lue comme « aucun endpoint désactivé ».
+ *
+ * @param query - `request.query` du broker admin.
+ * @param sortable - champs que le backend branché sait trier ; un `?order=`
+ *   portant autre chose est refusé en 400 par le traducteur.
+ */
+export declare function parseWebhookListQuery(query: Readonly<Record<string, string | string[]>>, sortable: readonly string[]): IWebhookListQuery;
+/**
+ * Construit les endpoints admin webhook, à **spreader** dans les
+ * `adminEndpoints()` du producteur `security`. Les handlers résolvent le service
+ * `webhooks` **lazy** (à la requête) → un service désactivé/absent rend 503 (ou
+ * un état honnête en lecture), jamais une erreur au montage.
+ *
+ * @param container - container du kernel (capturé par les handlers lazy).
+ */
+export declare function webhookAdminEndpoints(container: Container): IAdminEndpoint[];

package/dist/types/nodefony/src/admin/adminAudit.d.ts

@@ -0,0 +1,27 @@
+import type { Container } from "nodefony";
+import type { IAuditEventDraft } from "../../contracts/IAuditEvent.js";
+/**
+ * Helpers d'audit PARTAGÉS par les producteurs admin du module sécurité
+ * (`SecurityAdminApi`, `WebhookAdminApi`…). Extraits dans leur propre fichier
+ * pour être consommés par plusieurs producteurs SANS créer de cycle d'import
+ * (un producteur composé ne ré-importe pas le producteur qui le compose).
+ */
+/**
+ * Identité de l'admin appelant (label d'audit) — duck-typing prudent sur
+ * l'`IUser` projeté dans `IAdminRequest.user` (ALS du firewall). Repli
+ * `"admin"` (libellé d'audit, jamais une décision d'autorisation).
+ *
+ * @param user - `request.user` du broker admin.
+ * @returns un libellé d'identité stable, jamais un secret.
+ */
+export declare function adminActor(user: unknown): string;
+/**
+ * Émet un événement d'audit pour une mutation admin (best-effort,
+ * fire-and-forget) — l'audit ne doit jamais bloquer ni faire échouer l'action.
+ * No-op si le service `auditService` est absent. Couplage structurel : `record`
+ * lu défensivement (jamais d'import de la classe concrète).
+ *
+ * @param container - container du kernel.
+ * @param draft - événement (sans `id`/`ts`, posés par le service).
+ */
+export declare function auditAdmin(container: Container, draft: IAuditEventDraft): void;

package/dist/types/nodefony/src/admin/userRevocationCascade.d.ts

@@ -0,0 +1,31 @@
+import type { Container } from "nodefony";
+import { type IUserRevokedEvent } from "@nodefony/user";
+/** Bus d'événements minimal (kernel) capable d'abonner un handler. */
+interface KernelListenerLike {
+    on(event: string, handler: (...args: unknown[]) => void): unknown;
+}
+/**
+ * Cascade de révocation déclenchée par {@link USER_REVOKED_EVENT} : éjecte
+ * **immédiatement** les artefacts d'accès du porteur — ses **sessions** (http,
+ * `destroyByUser`) et ses **jetons/PAT** (`tokenStore.revokeAllForSubject`,
+ * seuil `invalidBefore`). Best-effort par brique (une indispo n'empêche pas
+ * l'autre) — l'accès était DÉJÀ neutralisé par le re-fetch des authenticators,
+ * cette cascade est de la **propreté + défense en profondeur**, jamais l'unique
+ * rempart. `tenantId` du payload est réservé (scoping non câblé en mono-tenant).
+ *
+ * @param container - container du kernel (résolution lazy de `sessions`/`tokenStore`).
+ * @param event - charge utile de l'événement (porteur + raison).
+ * @param now - horloge (epoch ms) injectable pour les tests.
+ */
+export declare function cascadeUserRevocation(container: Container, event: IUserRevokedEvent, now?: number): Promise<void>;
+/**
+ * Abonne la cascade au bus kernel. À appeler au `onKernelBoot` d'un module
+ * bootable (ici `@nodefony/security`). **Extensible** : tout autre module
+ * (webhooks…) peut s'abonner au MÊME `USER_REVOKED_EVENT` pour ses propres
+ * artefacts, sans toucher à ce fichier.
+ *
+ * @param kernel - bus d'événements (kernel) exposant `on`.
+ * @param container - container capturé par le handler.
+ */
+export declare function registerUserRevocationCascade(kernel: KernelListenerLike, container: Container): void;
+export {};

package/dist/types/nodefony/src/apikey/apiKeyFormat.d.ts

@@ -0,0 +1,43 @@
+/** Hash au repos d'une clé présentée (token entier) — `sha256` hex. */
+export declare function hashApiKey(token: string): string;
+/** Résultat d'une génération de clé — le `token` n'est disponible qu'ICI (1×). */
+export interface IGeneratedApiKey {
+    /** Token complet EN CLAIR — à afficher une seule fois, jamais re-dérivable. */
+    token: string;
+    /** Identifiant public (8 car.) — composant de {@link IGeneratedApiKey.publicPrefix}. */
+    pubid: string;
+    /** Préfixe public affichable (`<prefix>_<pubid>`) → `record.prefix`. */
+    publicPrefix: string;
+    /** Hash au repos (`sha256` hex) → `record.secretHash`. */
+    secretHash: string;
+}
+/**
+ * Génère une nouvelle clé API cryptographiquement aléatoire.
+ *
+ * @param prefix - marque applicative (`apiKeys.prefix`).
+ * @returns le token clair + ses dérivés publics/persistants.
+ */
+export declare function generateApiKey(prefix: string): IGeneratedApiKey;
+/** Décomposition validée d'une clé présentée. */
+export interface IParsedApiKey {
+    pubid: string;
+    publicPrefix: string;
+    /** Hash de lookup (`findByHash`) — `sha256` du token entier présenté. */
+    secretHash: string;
+}
+/**
+ * Test **bon marché** (préfixe seul) — discrimine un PAT d'un JWT à l'`supports()`
+ * de l'authenticator, sans calculer le checksum.
+ */
+export declare function looksLikeApiKey(token: string, prefix: string): boolean;
+/**
+ * Valide la **forme** d'une clé présentée et en dérive le hash de lookup —
+ * **sans aucun accès au store**. Rejette (→ `null`) un préfixe absent, une
+ * longueur incorrecte, un charset non base64url ou un **CRC invalide** : autant
+ * de requêtes qui n'atteignent jamais la base (anti-DoS).
+ *
+ * @param token - valeur brute présentée (after `Bearer `).
+ * @param prefix - marque applicative attendue.
+ * @returns la décomposition + le `secretHash` de lookup, ou `null` si malformée.
+ */
+export declare function parseApiKey(token: string, prefix: string): IParsedApiKey | null;

package/dist/types/nodefony/src/audit/MemoryAuditStore.d.ts

@@ -0,0 +1,33 @@
+import type { IPage } from "nodefony";
+import type { IAuditEvent } from "../../contracts/IAuditEvent.js";
+import type { IAuditListQuery, IAuditStore } from "../../contracts/IAuditStore.js";
+/** Instantané sérialisable du journal mémoire (persistance fichier + tests). */
+export interface AuditStoreSnapshot {
+    events: IAuditEvent[];
+}
+/**
+ * Journal d'audit **en mémoire** — implémentation de référence d'{@link IAuditStore}.
+ *
+ * 0 dépendance, idéal pour le dev mono-process et les **tests**. **Volatile**
+ * (perdu au redémarrage) et **non partagé** (per-pod) → en prod multi-process,
+ * brancher un backend ORM/Redis. Le volume est **borné** (`maxEntries`, FIFO : au
+ * delà, le plus ancien tombe) pour ne JAMAIS fuir, doublé d'une purge par âge
+ * ({@link MemoryAuditStore.gc}, rétention). Append-only : aucune mutation d'un
+ * événement déjà journalisé.
+ *
+ * Horloge injectable (`now`) pour des tests déterministes (pattern `MemoryTokenStore`).
+ */
+export declare class MemoryAuditStore implements IAuditStore {
+    #private;
+    constructor(now?: () => number, retentionMs?: number, // 365 jours
+    maxEntries?: number);
+    append(event: IAuditEvent): Promise<void>;
+    listPage(query: IAuditListQuery): Promise<IPage<IAuditEvent>>;
+    gc(now?: number): Promise<number>;
+    /** Nombre d'événements actuellement retenus (introspection / tests). */
+    get size(): number;
+    /** Instantané sérialisable de l'état courant. */
+    snapshot(): AuditStoreSnapshot;
+    /** Remplace l'état par celui d'un instantané. */
+    restore(snapshot: AuditStoreSnapshot): void;
+}

package/dist/types/nodefony/src/audit/auditBridge.d.ts

@@ -0,0 +1,49 @@
+import type { IAuditEvent } from "../../contracts/IAuditEvent.js";
+/**
+ * Canal WS du flux live d'audit (P6.14 lot 4). Le préfixe `security:` le place
+ * sous le plancher `SECURITY_CHANNEL_POLICY` (ROLE_NODEFONY_ADMIN) du verrou de
+ * frame — un user lambda ne peut pas s'y abonner (refus audité `frame.denied`).
+ */
+export declare const SECURITY_AUDIT_CHANNEL: "nodefony:audit";
+/** Source d'événements live — sous-ensemble de `IAuditSink` (slot `subscribe`). */
+export interface IAuditEventSource {
+    subscribe(listener: (event: IAuditEvent) => void): () => void;
+}
+/** Charge poussée sur le canal `nodefony:audit` — batch coalescé + omis. */
+export interface IAuditBatch {
+    events: IAuditEvent[];
+    dropped: number;
+}
+/** Options de coalescing du pont d'audit. */
+export interface AuditBridgeOptions {
+    /** Fenêtre d'agrégation : 1 frame WS au plus toutes les `flushMs`. Défaut 250. */
+    flushMs?: number;
+    /** Cap d'un batch (ring buffer) : au-delà, on garde les + récents et on compte
+     *  les omis. Borne la mémoire ET le nb d'événements envoyés au front. Défaut 200. */
+    maxBatch?: number;
+}
+/**
+ * Pont journal d'audit → canal `nodefony:audit`, **coalescé** (P6.14 lot 4).
+ *
+ * Calque {@link createSyslogBridge} (studio) : au lieu de 1 frame WS par
+ * événement (un pic d'`auth.failure` sous brute-force noierait la console
+ * auditeur), on accumule dans un **ring buffer borné** et on flush **1 frame
+ * agrégée toutes les `flushMs`** : `{ events, dropped }`. Sous surcharge, le ring
+ * écrase les plus vieux et `dropped` indique combien ont été omis → la console
+ * affiche un récap au lieu de se figer (budget borné, dégradable — règle
+ * observabilité « superviser ≠ tomber la prod »).
+ *
+ * **Lazy par construction** (créé par le hub au 1ᵉʳ abonné, `dispose` au dernier) :
+ * tant qu'aucun auditeur n'écoute `nodefony:audit`, ce pont N'EXISTE PAS — aucun
+ * listener sur l'`AuditService`, aucun timer. Au repos avec auditeur connecté mais
+ * sans événement : ring `null`, 0 timer (armé au 1ᵉʳ événement, `unref`).
+ *
+ * @param source  - l'`AuditService` (slot `subscribe`).
+ * @param publish - publication hub (le canal est fourni par la factory).
+ * @param channel - canal de publication (`nodefony:audit`).
+ * @returns dispose() — détache le listener `AuditService` ET désarme le timer.
+ *          OBLIGATOIRE (aucun listener/timer sans cleanup, sinon fuite à chaque
+ *          dernier désabonnement).
+ */
+export declare function createAuditBridge(source: IAuditEventSource, publish: (channel: string, payload: unknown) => void, channel: string, opts?: AuditBridgeOptions): () => void;
+export default createAuditBridge;

package/dist/types/nodefony/src/audit/auditFilters.d.ts

@@ -0,0 +1,56 @@
+import type { AuditCategory, AuditOutcome } from "../../contracts/IAuditEvent.js";
+/**
+ * **Le vocabulaire de filtre du journal d'audit**, en noms PUBLICS — ceux qu'un
+ * auditeur écrit dans l'URL (`?category=authz&outcome=denied&since=…`).
+ *
+ * Les deux énumérations y sont écrites en toutes lettres, et
+ * {@link AUDIT_FILTER_VOCABULARY_IS_COMPLETE} vérifie **à la compilation**
+ * qu'elles couvrent exactement `AuditCategory` et `AuditOutcome`.
+ *
+ * Ce contrôle n'est pas décoratif : la liste qu'il remplace avait DÉJÀ dérivé.
+ * Un `Set` recopié à la main dans le data plane portait dix catégories quand le
+ * type en déclarait onze — `?category=config` tombait donc hors de l'allowlist,
+ * était ignoré en silence, et l'auditeur recevait le journal ENTIER en croyant
+ * lire les seules mutations de configuration. Une liste recopiée ne diverge
+ * jamais bruyamment.
+ *
+ * `actor`, `action` et `requestId` restent des chaînes libres : ce sont des
+ * identifiants produits à l'exécution, aucune allowlist ne peut les connaître.
+ * `since`/`until` sont des horodatages en millisecondes (bornes incluses).
+ */
+export declare const AUDIT_FILTERS: {
+    /** Famille d'événement — la liste EST le type `AuditCategory`. */
+    readonly category: readonly ["auth", "authz", "token", "session", "oauth", "webauthn", "csrf", "cors", "ws", "webhook", "config"];
+    /** Issue — `denied` est le signal d'accès non autorisé. */
+    readonly outcome: readonly ["success", "failure", "denied"];
+    /** Identité de l'acteur (égalité stricte). */
+    readonly actor: "string";
+    /** Nom de l'action auditée (égalité stricte). */
+    readonly action: "string";
+    /** Corrèle toutes les traces d'une même requête. */
+    readonly requestId: "string";
+    /** Borne basse, horodatage en millisecondes. */
+    readonly since: "int";
+    /** Borne haute, horodatage en millisecondes. */
+    readonly until: "int";
+};
+/**
+ * Vrai si les deux ensembles sont EXACTEMENT les mêmes, `never` sinon — donc
+ * inassignable depuis `true`, donc erreur de compilation.
+ *
+ * Les deux sens comptent, et pour des raisons différentes : une valeur en trop
+ * dans la liste ouvrirait un filtre qu'aucun store ne sait honorer ; une valeur
+ * manquante ferait refuser en 400 une catégorie parfaitement légitime — le
+ * contraire du silence d'origine, mais tout aussi faux.
+ */
+type SameValues<A, B> = [A] extends [B] ? [B] extends [A] ? true : never : never;
+/**
+ * Preuve **à la compilation** que le vocabulaire ci-dessus est exactement celui
+ * des types du contrat. Elle remplace la discipline humaine « penser à mettre
+ * les deux à jour », qui avait échoué en silence.
+ */
+export declare const AUDIT_FILTER_VOCABULARY_IS_COMPLETE: [
+    SameValues<(typeof AUDIT_FILTERS.category)[number], AuditCategory>,
+    SameValues<(typeof AUDIT_FILTERS.outcome)[number], AuditOutcome>
+];
+export {};

package/dist/types/nodefony/src/audit/auditStoreRegistry.d.ts

@@ -0,0 +1,37 @@
+import type { Container } from "nodefony";
+import type { ISecurityConfig } from "../../config/defineModuleConfig.js";
+import type { IAuditStore } from "../../contracts/IAuditStore.js";
+/**
+ * Registre de **fabriques de stores d'audit** — résout le nom configuré
+ * (`security.audit.store`) vers une instance d'{@link IAuditStore}, SANS coupler
+ * le cœur à un backend en dur.
+ *
+ * Pourquoi : le journal d'audit est pluggable par contrat (mémoire/ORM/Redis/Loki) ;
+ * un `if (name === "drizzle")` dans le service trahirait cette promesse. Le builtin
+ * sans dépendance (`memory`) s'enregistre au chargement de ce module ; les adapters
+ * lourds (`drizzle`, `mongoose`, `redis`) s'enregistrent depuis LEUR module
+ * (inversion de dépendance : ils importent `import type { IAuditStore }`, effacé à
+ * la compilation → 0 cycle). Convention-frère : `tokenStoreRegistry`,
+ * `webAuthnCredentialStoreRegistry`, `ormRegistry`.
+ */
+/**
+ * Contexte passé à une fabrique de store d'audit : de quoi se construire
+ * (résolutions coûteuses en lazy à l'intérieur de l'instance).
+ */
+export interface IAuditStoreFactoryContext {
+    /** Container DI — résolution de services (ORM, redis...). */
+    readonly container: Container;
+    /** Config sécurité validée + gelée. */
+    readonly config: ISecurityConfig;
+}
+/** Fabrique d'un store d'audit pour un nom donné. */
+export type AuditStoreFactory = (ctx: IAuditStoreFactoryContext) => IAuditStore;
+/**
+ * Enregistre (ou remplace) la fabrique d'un store d'audit. Appelée par le builtin
+ * `memory` au chargement, et par les adapters (drizzle/mongoose/redis) pour les leurs.
+ */
+export declare function registerAuditStore(name: string, factory: AuditStoreFactory): void;
+/** Fabrique d'un store par nom, ou `undefined` si inconnu. */
+export declare function getAuditStoreFactory(name: string): AuditStoreFactory | undefined;
+/** Noms enregistrés (validation boot, introspection Studio, tests). */
+export declare function listAuditStores(): string[];

package/dist/types/nodefony/src/audit/readAuditContext.d.ts

@@ -0,0 +1,17 @@
+import type { IAuditEventFlags } from "../../contracts/IAuditEvent.js";
+/** Métadonnées de provenance extraites d'un contexte, prêtes à enrichir un événement. */
+export interface AuditContextInfo {
+    ip: string | null;
+    userAgent: string | null;
+    requestId: string | null;
+    flags: IAuditEventFlags;
+}
+/**
+ * Extrait IP / User-Agent / requestId + drapeaux de présence (jamais la valeur)
+ * d'un contexte de requête — pour enrichir un événement d'audit avec la
+ * provenance (« d'où vient cette tentative »). Calque {@link JsonAuditLogger}.
+ *
+ * @param context - contexte HTTP/WS courant (typé `unknown` à la frontière).
+ * @returns provenance normalisée ; champs `null` si l'info est absente.
+ */
+export declare function readAuditContext(context: unknown): AuditContextInfo;

package/dist/types/nodefony/src/audit/recordAudit.d.ts

@@ -0,0 +1,13 @@
+import type { Container } from "nodefony";
+import type { IAuditEventDraft } from "../../contracts/IAuditEvent.js";
+/**
+ * Émet un événement d'audit **si** le service est présent — no-op sinon. La
+ * résolution se fait par le container (`auditService`) sur le **cold-path**
+ * (login, refus, révocation) : le coût d'un `Map.get` y est négligeable, et le
+ * journal reste **découplé** (module audit absent ou désactivé → aucun effet,
+ * jamais d'exception qui remonterait dans le flux métier).
+ *
+ * @param container - container du service émetteur (`this.container`).
+ * @param event - brouillon d'événement (l'`AuditService` pose `id` + `ts`).
+ */
+export declare function recordAudit(container: Container | null | undefined, event: IAuditEventDraft): void;

package/dist/types/nodefony/src/authenticator/AnonymousAuthenticator.d.ts

@@ -0,0 +1,26 @@
+import type { ContextType } from "@nodefony/http";
+import type { IAuthenticator } from "../../contracts/IAuthenticator.js";
+import type { IToken } from "../../contracts/IToken.js";
+/**
+ * Acceptation EXPLICITE de l'anonymat dans une zone — le seul authenticator
+ * autorisé à produire un token non authentifié sans déclencher le Zero Trust.
+ *
+ * Ne le lister que volontairement : une zone `authenticators: ["jwt", "anonymous"]`
+ * (mode `first`) signifie « identifié si preuve présente, sinon visiteur anonyme
+ * accepté ». Sans lui, zone protégée + aucune preuve → 401. En mode `all` il
+ * reste utile en DERNIER : « le canal doit être prouvé (ex. mtls), l'identité
+ * utilisateur est optionnelle ».
+ *
+ * Zéro coût : `supports()` accepte tout, le token porte le singleton gelé
+ * `anonymousUser` (aucune allocation d'utilisateur).
+ */
+export declare class AnonymousAuthenticator implements IAuthenticator {
+    readonly name = "anonymous";
+    supports(): boolean;
+    createToken(): Promise<IToken>;
+    /** Toujours un succès — accepter l'anonymat ne vérifie rien. */
+    authenticate(token: IToken): Promise<IToken>;
+    onSuccess(_context: ContextType, _token: IToken): Promise<void>;
+    onFailure(_context: ContextType, _error: Error): Promise<void>;
+}
+export default AnonymousAuthenticator;

package/dist/types/nodefony/src/authenticator/ApiKeyAuthenticator.d.ts

@@ -0,0 +1,74 @@
+import type { Container } from "nodefony";
+import type { ContextType } from "@nodefony/http";
+import type { IAuthenticator } from "../../contracts/IAuthenticator.js";
+import type { IToken } from "../../contracts/IToken.js";
+/** Paramètres effectifs d'un {@link ApiKeyAuthenticator} (dérivés de la config). */
+export interface IApiKeyAuthenticatorRuntime {
+    /** Marque des clés (`apiKeys.prefix`) — discrimine un PAT d'un JWT. */
+    prefix: string;
+    /** Coalescence d'écriture `lastUsedAt` (s) — 0 = écrit à chaque usage. */
+    lastUsedThrottleS: number;
+}
+/**
+ * Authentification par **clé API personnelle (PAT, P6.12)** présentée en
+ * `Authorization: Bearer <prefix>_…` (RFC 6750). Réservée API/CI/scripts — le web
+ * utilise la session BFF.
+ *
+ * Un PAT est un **bearer opaque** (≠ JWT auto-porté) : sa vérité vit côté serveur
+ * (`ITokenStore`), donc il est **révocable immédiatement**. Discrimination du
+ * JWT : le PAT porte le préfixe `<prefix>_` (le JWT a la structure compacte
+ * `a.b.c`) → les deux authenticators cohabitent dans une même zone.
+ *
+ * Défenses :
+ *  - **forme + CRC validés AVANT tout accès au store** ({@link parseApiKey}) →
+ *    une valeur malformée n'atteint jamais la base (anti-DoS) ;
+ *  - lookup par **hash** (`sha256`) — le secret n'existe nulle part au repos ;
+ *  - **révocation** immédiate (`revokedAt`) + **expiration** (`expiresAt`) +
+ *    **ban en masse** du porteur (`invalidBefore` vs `createdAt`) ;
+ *  - **sujet revérifié** à chaque requête (`loadUserByIdentifier` → disparu/
+ *    inactif/verrouillé = rejet) — rôles **frais** (révocation effective) ;
+ *  - message d'échec **uniforme** (anti-énumération).
+ *
+ * Dépendances (store, userProvider) résolues **paresseusement** du container.
+ */
+export declare class ApiKeyAuthenticator implements IAuthenticator {
+    #private;
+    readonly name = "apikey";
+    /**
+     * @param container - container DI (résolution lazy de `tokenStore`/`users`).
+     * @param runtime - préfixe + throttle effectifs (dérivés de `config.apiKeys`).
+     */
+    constructor(container: Container, runtime: IApiKeyAuthenticatorRuntime);
+    /** La requête porte-t-elle un `Authorization: Bearer <prefix>_…` ? (test bon marché) */
+    supports(context: ContextType): boolean;
+    /** Extrait la valeur brute (non vérifiée) → portée par un `UserToken` type `"apikey"`. */
+    createToken(context: ContextType): Promise<IToken>;
+    /**
+     * Valide la clé (forme+CRC, puis store) et résout le sujet — ou lève un 401 au
+     * message uniforme.
+     *
+     * @throws AuthenticationError (401) — clé malformée/inconnue/révoquée/expirée,
+     *   ou sujet disparu/banni.
+     * @throws Error (câblage : store/users absents) — loggée ERROR par le firewall
+     *   puis 401 fail-closed (rien ne fuite au client).
+     */
+    authenticate(token: IToken): Promise<IToken>;
+    /**
+     * Inscrit la trace d'usage de la clé — horodatage, IP et agent.
+     *
+     * C'est ici, et pas dans `authenticate()`, parce que c'est ici qu'on reçoit
+     * le contexte. La provenance se lit par les ACCESSEURS proxy-aware des
+     * contextes concrets (`getRemoteAddress()` dépouille `X-Forwarded-For` selon
+     * `trustProxy`), absents du type de base — duck-typing optionnel, même
+     * approche que `AuthFlow.#openSession()`.
+     *
+     * Rien n'est écrit si `authenticate()` n'a pas posé le marqueur : la fenêtre
+     * de throttle n'était pas dépassée, et le hot path reste sans écriture.
+     */
+    onSuccess(context: ContextType, token: IToken): Promise<void>;
+    /** Slot audit (P6.14) — le 401 + challenge sont posés par le firewall. */
+    onFailure(_context: ContextType, _error: Error): Promise<void>;
+    /** Challenge RFC 6750/7235 posé par le firewall sur les 401 de la zone. */
+    challenge(): string;
+}
+export default ApiKeyAuthenticator;