@nodefony/security 10.0.0-alpha.1

package/dist/types/nodefony/src/totp/totpCipher.d.ts

@@ -0,0 +1,9 @@
+import { Buffer } from "node:buffer";
+import { decryptSecret, encryptSecret, generateEphemeralKey } from "../crypto/secretCipher.js";
+/**
+ * Dérive la clé AES-256 du domaine TOTP via HKDF-SHA256 (RFC 5869).
+ * Déterministe (clé lisible cross-pod). Délègue à {@link deriveKey} avec le
+ * contexte figé du domaine TOTP.
+ */
+export declare function deriveTotpKey(material: string | Buffer): Buffer;
+export { encryptSecret, decryptSecret, generateEphemeralKey };

package/dist/types/nodefony/src/totp/totpCrypto.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Cœur **pur** du 2FA TOTP — RFC 6238 (Time-based OTP) au-dessus de RFC 4226
+ * (HOTP). Aucun I/O, aucun container, aucune persistance → testable sans serveur
+ * et partagé par l'émetteur (enrôlement) et le vérificateur (login step-up).
+ *
+ * **Principe** (RFC 6238 §4) : un secret partagé `K` + un compteur dérivé du
+ * temps `T = ⌊(epochSec − T0) / step⌋` remplacent le compteur incrémental de
+ * HOTP. Les deux parties (serveur, application d'authentification) calculent
+ * `HOTP(K, T) = Truncate(HMAC-SHA-1(K, T))` ; l'horloge fait office de canal de
+ * synchronisation — aucun échange réseau par code.
+ *
+ * **Troncature dynamique** (RFC 4226 §5.3) : l'octet de poids faible du condensat
+ * HMAC fournit un offset `0..15` ; on lit 4 octets à cet offset, on masque le bit
+ * de signe (`0x7f`, pour lever l'ambiguïté signé/non-signé inter-processeur), puis
+ * `code = bin31 mod 10^digits`.
+ *
+ * **Secret** : RFC 4226 R6 exige ≥ 128 bits, RECOMMANDE 160 bits → 20 octets
+ * (= taille du bloc HMAC-SHA-1, optimal). Encodé en base32 RFC 4648 (sans padding)
+ * pour l'URI `otpauth://` que lisent Google Authenticator / Authy / 1Password.
+ */
+/** Algorithmes HMAC admis (RFC 6238 §1.2 : SHA1 par défaut, SHA256/512 optionnels). */
+export type TotpAlgorithm = "SHA1" | "SHA256" | "SHA512";
+/** Paramètres TOTP — défauts interopérables (Google Authenticator). */
+export declare const TOTP_DEFAULTS: {
+    /** Taille du secret en octets (RFC 4226 R6 : 160 bits recommandés). */
+    readonly secretBytes: 20;
+    /** Période d'un code en secondes (RFC 6238 §5.2 : 30 s recommandé). */
+    readonly step: 30;
+    /** Nombre de chiffres du code (RFC 4226 §5.3 : 6 minimum). */
+    readonly digits: 6;
+    /** Fonction de hachage HMAC (compat maximale = SHA1). */
+    readonly algorithm: TotpAlgorithm;
+    /** Origine du décompte des tranches (RFC 6238 : T0 = 0 = epoch Unix). */
+    readonly t0: 0;
+    /**
+     * Tolérance de dérive d'horloge, en nombre de pas de part et d'autre.
+     * RFC 6238 §5.2 : « at most one time step » → ±1 (1 pas = 30 s avant/après).
+     */
+    readonly window: 1;
+};
+/**
+ * Encode des octets en base32 RFC 4648 **sans padding** (`=`) — forme attendue
+ * par les applications d'authentification dans l'URI `otpauth://`.
+ */
+export declare function base32Encode(buf: Buffer): string;
+/**
+ * Décode une chaîne base32 RFC 4648 → octets. Tolérant : ignore espaces,
+ * tirets et padding `=`, insensible à la casse (un secret peut être saisi à la
+ * main par l'utilisateur). Lève si un caractère hors alphabet est rencontré.
+ */
+export declare function base32Decode(input: string): Buffer;
+/** Génère un secret TOTP cryptographiquement aléatoire (défaut 160 bits). */
+export declare function generateTotpSecret(bytes?: number): Buffer;
+/**
+ * HOTP (RFC 4226 §5.3) — `Truncate(HMAC(K, counter))` → code à `digits` chiffres,
+ * complété à gauche par des zéros.
+ *
+ * @param secret - secret partagé `K` (octets bruts).
+ * @param counter - compteur `C` (≥ 0).
+ * @param digits - longueur du code (défaut 6).
+ * @param algorithm - fonction HMAC (défaut SHA1).
+ */
+export declare function hotp(secret: Buffer, counter: number, digits?: number, algorithm?: TotpAlgorithm): string;
+/** Numéro de tranche temporelle `T` (RFC 6238 §4.2) pour un instant donné. */
+export declare function totpCounter(epochSec: number, step?: number, t0?: number): number;
+/** Options de calcul/vérification d'un code TOTP. */
+export interface ITotpOptions {
+    /** Instant de référence en **millisecondes** (défaut : horloge système). */
+    epochMs?: number;
+    step?: number;
+    digits?: number;
+    algorithm?: TotpAlgorithm;
+    t0?: number;
+}
+/**
+ * Calcule le code TOTP courant (RFC 6238 §4) pour un secret donné.
+ *
+ * @param secret - secret partagé `K`.
+ * @returns le code à `digits` chiffres pour la tranche temporelle courante.
+ */
+export declare function totpCode(secret: Buffer, opts?: ITotpOptions): string;
+/** Résultat d'une vérification TOTP — `step` matché = ancre anti-rejeu. */
+export interface ITotpVerifyResult {
+    /** Le code présenté correspond à une tranche de la fenêtre de tolérance. */
+    valid: boolean;
+    /**
+     * Numéro de tranche `T` qui a validé le code (présent si `valid`). À
+     * persister (`lastUsedStep`) pour **refuser tout rejeu** dans la même fenêtre
+     * (RFC 6238 §5.2).
+     */
+    step?: number;
+}
+/**
+ * Vérifie un code TOTP présenté contre une fenêtre de tolérance `±window` pas
+ * (RFC 6238 §5.2). Comparaison en **temps constant** (anti-timing). Retourne la
+ * tranche `T` validée pour permettre à l'appelant d'appliquer l'anti-rejeu.
+ *
+ * @param code - code présenté par l'utilisateur (les espaces sont ignorés).
+ * @param secret - secret partagé `K`.
+ * @param window - nombre de pas de tolérance de part et d'autre (défaut ±1).
+ */
+export declare function verifyTotp(code: string, secret: Buffer, opts?: ITotpOptions & {
+    window?: number;
+}): ITotpVerifyResult;
+/** Champs d'un URI `otpauth://totp/...` (Key Uri Format de facto). */
+export interface IOtpauthParams {
+    /** Émetteur affiché dans l'application (ex. « Nodefony »). */
+    issuer: string;
+    /** Compte (ex. identifiant/email de l'utilisateur). */
+    account: string;
+    /** Secret encodé en base32 RFC 4648. */
+    secretBase32: string;
+    algorithm?: TotpAlgorithm;
+    digits?: number;
+    period?: number;
+}
+/**
+ * Construit l'URI `otpauth://totp/{issuer}:{account}?...` encodé dans le QR code
+ * d'enrôlement. Le label `issuer:account` et le paramètre `issuer` sont tous deux
+ * renseignés (recommandation Key Uri Format pour la compat des lecteurs).
+ */
+export declare function buildOtpauthUri(params: IOtpauthParams): string;
+/**
+ * Tire `count` indices UNIFORMES dans `[0, size)` à partir d'octets aléatoires.
+ *
+ * Le repli direct (`octet % size`) n'est uniforme que si `size` divise 256. Ici
+ * `256 % 30 = 16` : les seize premiers symboles de l'alphabet sortaient une fois
+ * sur neuf-deux-cent-cinquante-sixièmes, les quatorze autres une fois sur huit —
+ * environ 12 % plus souvent pour les premiers.
+ *
+ * L'enjeu réel est modeste (l'entropie tombe de 4,9069 à 4,9044 bit par
+ * caractère, soit 0,025 bit perdu sur les ~49 d'un code) et n'ouvre aucune
+ * attaque praticable. Ce n'est pas la raison de corriger : un tirage biaisé dans
+ * du code cryptographique est une dette qui ne se voit plus une fois écrite, et
+ * dont le coût explose si l'alphabet change un jour pour une taille moins
+ * clémente. Le refus d'échantillon coûte ici quelques octets de plus, une fois
+ * par activation de second facteur.
+ *
+ * @param count - nombre d'indices voulus.
+ * @param size - taille de l'alphabet (2 à 256).
+ * @param source - fournisseur d'octets aléatoires — paramétrable pour que le
+ *          refus d'échantillon soit OBSERVABLE en test, faute de quoi on ne
+ *          prouverait jamais que la garde mord.
+ * @returns exactement `count` indices, uniformément distribués.
+ */
+export declare function unbiasedIndices(count: number, size: number, source?: (n: number) => Buffer): number[];
+/**
+ * Génère `count` codes de récupération à usage unique, lisibles
+ * (`XXXXX-XXXXX`, ~50 bits chacun). À présenter **une seule fois** à
+ * l'utilisateur ; seul leur condensat est persisté ({@link hashRecoveryCode}).
+ */
+export declare function generateRecoveryCodes(count?: number): string[];
+/**
+ * Condensat au repos d'un code de récupération (`sha256` hex). `sha256` suffit
+ * (≈ 50 bits aléatoires non brute-forçables, comme une clé API — pas un mot de
+ * passe humain) ; la normalisation rend la vérification insensible casse/tirets.
+ */
+export declare function hashRecoveryCode(code: string): string;
+/**
+ * Cherche un code de récupération présenté parmi des condensats stockés, en
+ * **temps constant par entrée**. Retourne l'index consommé (à retirer du stock),
+ * ou `-1` si aucun ne correspond.
+ */
+export declare function matchRecoveryCode(presented: string, hashes: readonly string[]): number;

package/dist/types/nodefony/src/totp/totpOperations.d.ts

@@ -0,0 +1,73 @@
+import { Buffer } from "node:buffer";
+import type { ITotpSecretStore } from "../../contracts/ITotpSecretStore.js";
+import { type TotpAlgorithm } from "./totpCrypto.js";
+/**
+ * Dépendances résolues d'une opération TOTP — **injectées** (store, clé de
+ * chiffrement, horloge) pour rendre toute la logique métier testable sans kernel
+ * ni serveur. `TotpService` les résout au boot puis délègue ici (même esprit que
+ * le verdict neutre d'idempotence).
+ */
+export interface ITotpDeps {
+    store: ITotpSecretStore;
+    /** Clé AES-256 de (dé)chiffrement du secret au repos (dérivée par le service). */
+    key: Buffer;
+    /** Horloge en ms — injectable pour les tests ; runtime = `Date.now`. */
+    now: () => number;
+    issuer: string;
+    algorithm: TotpAlgorithm;
+    digits: number;
+    period: number;
+    window: number;
+    recoveryCodesCount: number;
+}
+/** Données d'enrôlement présentées **une seule fois** (QR + saisie manuelle). */
+export interface ITotpEnrollment {
+    /** Secret en base32 (scanné via le QR ou saisi à la main). */
+    secretBase32: string;
+    /** URI `otpauth://` encodé dans le QR code. */
+    otpauthUri: string;
+}
+/** Résultat de l'activation — codes de récupération **clairs**, affichés 1×. */
+export interface ITotpActivation {
+    recoveryCodes: string[];
+}
+/** État 2FA d'un utilisateur (UI self-service / Studio). */
+export interface ITotpStatus {
+    /** 2FA activé (enrôlement confirmé). */
+    enabled: boolean;
+    /** Enrôlement commencé, pas encore confirmé. */
+    pending: boolean;
+    /** Codes de récupération restants (non consommés). */
+    recoveryCodesRemaining: number;
+}
+/** Résultat d'une vérification de second facteur au login. */
+export interface ITotpLoginResult {
+    ok: boolean;
+    /** Méthode ayant validé (utile pour l'audit). */
+    method?: "totp" | "recovery";
+}
+/**
+ * Démarre l'enrôlement : génère un secret aléatoire, le **chiffre** au repos et
+ * l'enregistre en attente de confirmation (`confirmedAt: null`). Retourne le
+ * secret en clair (base32 + URI) — **seul moment** où il est exposé. Idempotent :
+ * un nouvel appel écrase un enrôlement non confirmé (re-scan du QR).
+ */
+export declare function beginTotpEnrollment(deps: ITotpDeps, userId: string, account: string): Promise<ITotpEnrollment>;
+/**
+ * Confirme l'enrôlement : vérifie un 1ᵉʳ code généré par l'app, **active** le 2FA
+ * et génère les codes de récupération (retournés clairs 1×, hachés au repos). Le
+ * step de confirmation est marqué consommé (anti-rejeu). Lève si aucun enrôlement
+ * n'est en cours, s'il est déjà confirmé, ou si le code est invalide (reste pending).
+ */
+export declare function confirmTotpEnrollment(deps: ITotpDeps, userId: string, code: string): Promise<ITotpActivation>;
+/**
+ * Vérifie un second facteur au login : d'abord un code TOTP (fenêtre ±window,
+ * **anti-rejeu** via `lastUsedStep`), à défaut un code de récupération (consommé,
+ * usage unique). Retourne `ok: false` si le 2FA n'est pas activé ou si rien ne
+ * correspond — **jamais d'exception** (chemin d'authentification).
+ */
+export declare function verifyTotpLogin(deps: ITotpDeps, userId: string, code: string): Promise<ITotpLoginResult>;
+/** Désactive le 2FA (retire le secret et les codes de récupération). */
+export declare function disableTotp(deps: ITotpDeps, userId: string): Promise<void>;
+/** État 2FA d'un utilisateur (absent / pending / activé + codes restants). */
+export declare function totpStatus(deps: ITotpDeps, userId: string): Promise<ITotpStatus>;

package/dist/types/nodefony/src/totp/totpSecretStoreRegistry.d.ts

@@ -0,0 +1,27 @@
+import type { Container } from "nodefony";
+import type { ISecurityConfig } from "../../config/defineModuleConfig.js";
+import type { ITotpSecretStore } from "../../contracts/ITotpSecretStore.js";
+/**
+ * Registre de **fabriques de stores de secrets TOTP** — résout un nom (`memory`,
+ * `file`, `drizzle`, `mongoose`, `redis`…) vers une instance, SANS coupler le cœur
+ * à un backend en dur.
+ *
+ * Convention-frère de `webAuthnCredentialStoreRegistry` / `tokenStoreRegistry` :
+ * les builtins sans dépendance (`memory`, `file`) s'enregistrent au chargement du
+ * module ; les adapters lourds s'enregistrent depuis LEUR module (ils importent
+ * `import type { ITotpSecretStore }`, effacé à la compilation → 0 dép runtime).
+ */
+export interface ITotpStoreFactoryContext {
+    /** 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 de secrets TOTP pour un nom donné. */
+export type TotpStoreFactory = (ctx: ITotpStoreFactoryContext) => ITotpSecretStore;
+/** Enregistre (ou remplace) la fabrique d'un store de secrets TOTP. */
+export declare function registerTotpStore(name: string, factory: TotpStoreFactory): void;
+/** Fabrique d'un store par nom, ou `undefined` si inconnu. */
+export declare function getTotpStoreFactory(name: string): TotpStoreFactory | undefined;
+/** Noms enregistrés (validation boot, introspection Studio, tests). */
+export declare function listTotpStores(): string[];

package/dist/types/nodefony/src/voter/RoleVoter.d.ts

@@ -0,0 +1,25 @@
+import type { Container } from "nodefony";
+import type { IAccessVoter } from "../../contracts/IAccessVoter.js";
+import type { IToken } from "../../contracts/IToken.js";
+import { VoterVote } from "../../contracts/IAccessVoter.js";
+/**
+ * Voter built-in **niveau A** — résout les attributs `ROLE_*` via la hiérarchie
+ * de rôles ({@link RoleHierarchyWalker}).
+ *
+ * Vote `GRANT` si l'utilisateur possède le rôle (hiérarchie résolue : `ROLE_ADMIN`
+ * hérite `ROLE_USER`), **`ABSTAIN` sinon** — jamais `DENY` : l'absence d'un rôle
+ * ne doit pas opposer son veto aux autres axes (scope, ownership). C'est le
+ * `default DENY` de l'`AuthorizationService` (tous ABSTAIN → refus) qui ferme la
+ * porte, pas ce voter.
+ *
+ * Lit la hiérarchie depuis le container (`roleHierarchy`, posée par le firewall
+ * au boot) en lazy — un walker vide gère quand même les rôles plats.
+ */
+export declare class RoleVoter implements IAccessVoter {
+    #private;
+    private readonly container;
+    constructor(container: Container);
+    supports(attribute: string): boolean;
+    vote(token: IToken, attribute: string): Promise<VoterVote>;
+}
+export default RoleVoter;

package/dist/types/nodefony/src/voter/ScopeVoter.d.ts

@@ -0,0 +1,30 @@
+import type { IAccessVoter } from "../../contracts/IAccessVoter.js";
+import type { IToken } from "../../contracts/IToken.js";
+import { VoterVote } from "../../contracts/IAccessVoter.js";
+/**
+ * Voter built-in **axe SCOPE** (P6.8) — applique les scopes `api:action` déclarés
+ * par `@RequireScope`. Frère du {@link RoleVoter} sur l'autre axe : les rôles
+ * disent QUI tu es, les scopes disent ce qu'une CLÉ déléguée a le droit de faire.
+ *
+ * `supports()` ne capte QUE la forme conventionnée `api:action` (un `:`, jamais
+ * `ROLE_*`) → aucune collision avec le `RoleVoter` ni un voter métier (`doc.edit`).
+ *
+ * Vote :
+ *  - **jeton non scopable** (humain/anonyme) → `GRANT` : le scope est un no-op,
+ *    l'autorisation de l'humain est portée par ses rôles (`@IsGranted`), pas par
+ *    un downscoping de clé ;
+ *  - **jeton scopable** (clé API / JWT / OAuth) → `GRANT` si le scope exact est
+ *    présent, sinon **`ABSTAIN`** (jamais `DENY` : l'absence d'un scope ne doit pas
+ *    opposer un veto aux autres attributs OR d'une clause — c'est le default-DENY
+ *    de l'`AuthorizationService`, tous ABSTAIN → refus, qui ferme la porte ;
+ *    posture identique au `RoleVoter`).
+ *
+ * Pur : aucune dépendance (ni container, ni I/O) — il ne lit que le jeton déjà
+ * résolu au handshake/à l'authentification. Instancié UNE fois au boot.
+ */
+export declare class ScopeVoter implements IAccessVoter {
+    /** Capte les attributs scope `api:action` — ni `ROLE_*`, ni attribut métier sans `:`. */
+    supports(attribute: string): boolean;
+    vote(token: IToken, attribute: string): Promise<VoterVote>;
+}
+export default ScopeVoter;

package/dist/types/nodefony/src/voter/voterRegistry.d.ts

@@ -0,0 +1,33 @@
+import type { Container } from "nodefony";
+import type { IAccessVoter } from "../../contracts/IAccessVoter.js";
+/**
+ * Registre de **fabriques de voters** — alimente l'`AuthorizationService` au boot
+ * SANS qu'il connaisse le moindre voter en dur.
+ *
+ * Pourquoi un registre (et pas un scan DI « tous les `@injectable` implémentant
+ * `IAccessVoter` ») : les interfaces TypeScript sont **effacées à la compilation**
+ * — rien à scanner au runtime. Le registre EST le marqueur explicite. Un voter
+ * built-in s'enregistre au chargement du module (toujours avant le boot) ; un
+ * voter métier (app/plugin) appelle `registerVoterFactory("projectVoter", …)`
+ * puis il est découvert automatiquement — aucun changement dans le cœur.
+ * Convention-frère : `authenticatorRegistry`, `tokenStoreRegistry`.
+ */
+/**
+ * Contexte passé à une fabrique de voter : le container DI pour résoudre les
+ * services dont le voter a besoin (repository, hiérarchie de rôles…). La fabrique
+ * ne fait QUE construire — les résolutions coûteuses restent lazy dans l'instance.
+ */
+export interface IVoterFactoryContext {
+    /** Container DI — résolution de services (`roleHierarchy`, repositories…). */
+    readonly container: Container;
+}
+/** Fabrique d'un voter pour un nom donné. */
+export type VoterFactory = (ctx: IVoterFactoryContext) => IAccessVoter;
+/**
+ * Enregistre (ou remplace) la fabrique d'un voter. Appelé par les builtins au
+ * chargement du module, et par les apps/plugins pour les leurs (`ProjectVoter`,
+ * `TenantVoter`…).
+ */
+export declare function registerVoterFactory(name: string, factory: VoterFactory): void;
+/** Toutes les fabriques enregistrées (consommées par l'`AuthorizationService`). */
+export declare function listVoterFactories(): ReadonlyMap<string, VoterFactory>;

package/dist/types/nodefony/src/webauthn/MemoryWebAuthnCredentialStore.d.ts

@@ -0,0 +1,39 @@
+import type { IPage } from "nodefony";
+import type { IWebAuthnCredential } from "../../contracts/IWebAuthnCredential.js";
+import type { IWebAuthnCredentialStore, IWebAuthnCredentialSummary, IWebAuthnListQuery, WebAuthnAuthUpdate } from "../../contracts/IWebAuthnCredentialStore.js";
+/**
+ * Projection contractuelle : credential complet → vue admin **sans `publicKey`**.
+ * Partagée par les backends qui matérialisent des credentials en mémoire.
+ */
+export declare function toWebAuthnSummary(c: IWebAuthnCredential): IWebAuthnCredentialSummary;
+/**
+ * Store de credentials WebAuthn **en mémoire** — implémentation de référence
+ * d'{@link IWebAuthnCredentialStore}.
+ *
+ * 0 dépendance, idéale pour le développement mono-process et les **tests**. NON
+ * partagée entre process (pas de cluster) et **volatile** (perdue au
+ * redémarrage) → en production multi-process, utiliser un adapter ORM ou Redis.
+ *
+ * Perf/mémoire : les `Map` n'existent que si le store est instancié (passkeys
+ * activés), jamais sur le hot path par requête HTTP.
+ */
+/** Instantané sérialisable de l'état — base de la persistance fichier. */
+export interface WebAuthnStoreSnapshot {
+    credentials: IWebAuthnCredential[];
+}
+export declare class MemoryWebAuthnCredentialStore implements IWebAuthnCredentialStore {
+    #private;
+    findById(credentialId: string): Promise<IWebAuthnCredential | null>;
+    findByUser(userId: string): Promise<IWebAuthnCredential[]>;
+    countByUser(userId: string): Promise<number>;
+    save(credential: IWebAuthnCredential): Promise<void>;
+    update(credentialId: string, patch: WebAuthnAuthUpdate): Promise<void>;
+    delete(credentialId: string): Promise<void>;
+    listPage(query: IWebAuthnListQuery): Promise<IPage<IWebAuthnCredentialSummary>>;
+    countCredentials(query: IWebAuthnListQuery): Promise<number>;
+    /** Instantané sérialisable de l'état courant (pour la persistance fichier). */
+    snapshot(): WebAuthnStoreSnapshot;
+    /** Remplace l'état par celui d'un instantané (reconstruit l'index par user). */
+    restore(snapshot: WebAuthnStoreSnapshot): void;
+}
+export default MemoryWebAuthnCredentialStore;

package/dist/types/nodefony/src/webauthn/webAuthnCredentialStoreRegistry.d.ts

@@ -0,0 +1,26 @@
+import type { Container } from "nodefony";
+import type { ISecurityConfig } from "../../config/defineModuleConfig.js";
+import type { IWebAuthnCredentialStore } from "../../contracts/IWebAuthnCredentialStore.js";
+/**
+ * Registre de **fabriques de stores de credentials WebAuthn** — résout un nom
+ * (`memory`, `drizzle`, `mongoose`, `redis`…) vers une instance, SANS coupler le
+ * cœur à un backend en dur.
+ *
+ * Convention-frère de `tokenStoreRegistry` : le builtin `memory` s'enregistre au
+ * chargement du module ; les adapters lourds s'enregistrent depuis LEUR module
+ * (ils importent `import type { IWebAuthnCredentialStore }`, effacé à la compilation).
+ */
+export interface IWebAuthnStoreFactoryContext {
+    /** 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 de credentials pour un nom donné. */
+export type WebAuthnStoreFactory = (ctx: IWebAuthnStoreFactoryContext) => IWebAuthnCredentialStore;
+/** Enregistre (ou remplace) la fabrique d'un store de credentials WebAuthn. */
+export declare function registerWebAuthnStore(name: string, factory: WebAuthnStoreFactory): void;
+/** Fabrique d'un store par nom, ou `undefined` si inconnu. */
+export declare function getWebAuthnStoreFactory(name: string): WebAuthnStoreFactory | undefined;
+/** Noms enregistrés (validation boot, introspection Studio, tests). */
+export declare function listWebAuthnStores(): string[];

package/dist/types/nodefony/src/webhook/MemoryWebhookStore.d.ts

@@ -0,0 +1,37 @@
+import type { IPage } from "nodefony";
+import type { IWebhookListQuery, IWebhookStore } from "../../contracts/IWebhookStore.js";
+import type { IWebhookEndpoint, WebhookEndpointUpdate } from "../../contracts/IWebhookEndpoint.js";
+/**
+ * Applique les filtres d'{@link IWebhookListQuery} à un endpoint — sémantique de
+ * RÉFÉRENCE du contrat, partagée par les backends qui filtrent en mémoire.
+ *
+ * @param e - endpoint candidat.
+ * @param query - filtres du listing (les champs omis ne filtrent pas).
+ * @returns `true` si l'endpoint appartient à la collection filtrée.
+ */
+export declare function matchesWebhookQuery(e: IWebhookEndpoint, query: IWebhookListQuery): boolean;
+/**
+ * Store d'endpoints webhook **en mémoire** — défaut dev/test (non persistant :
+ * les endpoints sont perdus au redémarrage). En prod, utiliser `drizzle`/
+ * `mongoose` (config `webhooks.store`).
+ *
+ * Map indexée par id (O(1)). Les lectures renvoient une **copie défensive** : le
+ * store détient la vérité, un consommateur ne peut pas muter un record en place.
+ */
+export declare class MemoryWebhookStore implements IWebhookStore {
+    #private;
+    /**
+     * {@inheritDoc IWebhookStore.sortableFields}
+     *
+     * Le store porte l'endpoint complet : il sait trier tout le vocabulaire
+     * public, sans réduction de capacité.
+     */
+    readonly sortableFields: readonly ["createdAt", "updatedAt", "url", "enabled", "failureCount", "id"];
+    save(endpoint: IWebhookEndpoint): Promise<void>;
+    findById(id: string): Promise<IWebhookEndpoint | null>;
+    update(id: string, patch: WebhookEndpointUpdate): Promise<void>;
+    delete(id: string): Promise<void>;
+    listAll(): Promise<IWebhookEndpoint[]>;
+    listPage(query: IWebhookListQuery): Promise<IPage<IWebhookEndpoint>>;
+    countEndpoints(query: IWebhookListQuery): Promise<number>;
+}

package/dist/types/nodefony/src/webhook/WebhookDispatcher.d.ts

@@ -0,0 +1,69 @@
+import type { IAuditEvent } from "../../contracts/IAuditEvent.js";
+import type { IWebhookEndpoint } from "../../contracts/IWebhookEndpoint.js";
+import type { IWebhookDeliveryPolicy } from "../../service/webhooks.js";
+import type { IDeliveryResult } from "./webhookDelivery.js";
+/** Une souscription matche-t-elle une action d'audit ? `*` = toutes, `x.*` = préfixe. */
+export declare function matchesSubscription(patterns: readonly string[], action: string): boolean;
+/**
+ * Classe le résultat d'une livraison : 2xx = succès ; réseau/timeout/429/408/5xx =
+ * réessayable ; 3xx/4xx (config cliente erronée) = échec définitif (pas de retry).
+ */
+export declare function classifyDelivery(r: IDeliveryResult): "success" | "retry" | "fail";
+/** Backoff exponentiel déterministe (jitter cross-pod = slice Redis cluster). */
+export declare function backoffMs(attempt: number): number;
+/** Trace d'une livraison terminée, poussée à `recordDelivery` (historique). */
+export interface IWebhookDeliveryRecord {
+    readonly messageId: string;
+    readonly type: string;
+    readonly attempt: number;
+    readonly ok: boolean;
+    readonly status: number | null;
+    readonly error: string | null;
+    readonly durationMs: number;
+    readonly requestBody: string;
+    readonly responseBody: string | null;
+}
+/** Dépendances injectées du dispatcher (E/S + temps + politique). */
+export interface IWebhookDispatcherDeps {
+    /** Nombre d'endpoints (0-alloc) — court-circuit hot-path. */
+    endpointCount(): number;
+    /** Snapshot des endpoints (n'est lu que si `endpointCount() > 0`). */
+    getSnapshot(): IWebhookEndpoint[];
+    /** Secret de signature en clair (`whsec_…`) d'un endpoint. */
+    secretOf(endpoint: IWebhookEndpoint): string;
+    /** Politique de livraison (tolérance/retries/timeout/concurrence/file). */
+    readonly policy: IWebhookDeliveryPolicy;
+    /** Re-contrôle SSRF + renvoie les IP à pinner ; **lève** si la cible est interdite. */
+    resolveTarget(url: string): Promise<string[]>;
+    /** Émet la requête HTTP signée (injecté → testable). */
+    deliver(url: string, body: string, headers: Record<string, string>, opts: {
+        timeoutMs: number;
+        addresses: string[];
+        allowHttp: boolean;
+    }): Promise<IDeliveryResult>;
+    /** Met à jour l'endpoint (lastDelivery, failureCount, auto-disable). */
+    markDelivery(id: string, result: IDeliveryResult): void | Promise<void>;
+    /** Enregistre une trace de livraison (historique « récentes », par endpoint). */
+    recordDelivery(id: string, rec: IWebhookDeliveryRecord): void;
+    /** Horloge injectable. */
+    now(): number;
+    /** Génère un `webhook-id` de message. */
+    newMessageId(): string;
+    /** Planifie un retry ; retourne une fonction d'annulation. */
+    schedule(fn: () => void, ms: number): () => void;
+    /** Journalisation (saturation / erreurs inattendues). */
+    log(message: string): void;
+}
+export declare class WebhookDispatcher {
+    #private;
+    constructor(deps: IWebhookDispatcherDeps);
+    /**
+     * Réagit à un événement d'audit. **Hot-path** : court-circuit à coût nul si
+     * aucun endpoint ; sinon filtre et empile (le travail lourd est différé).
+     */
+    onAuditEvent(event: IAuditEvent): void;
+    /** Livraisons abandonnées pour cause de file pleine (observabilité). */
+    droppedCount(): number;
+    /** Arrêt propre : stoppe l'admission, annule les retries, vide la file. */
+    shutdown(): void;
+}

package/dist/types/nodefony/src/webhook/webhookCipher.d.ts

@@ -0,0 +1,8 @@
+import { Buffer } from "node:buffer";
+import { decryptSecret, encryptSecret, generateEphemeralKey } from "../crypto/secretCipher.js";
+/**
+ * Dérive la clé AES-256 du domaine webhook via HKDF-SHA256 (RFC 5869).
+ * Déterministe (clé lisible cross-pod).
+ */
+export declare function deriveWebhookKey(material: string | Buffer): Buffer;
+export { encryptSecret, decryptSecret, generateEphemeralKey };

package/dist/types/nodefony/src/webhook/webhookDelivery.d.ts

@@ -0,0 +1,28 @@
+/** Résultat d'une tentative de livraison. */
+export interface IDeliveryResult {
+    /** Livraison acceptée (2xx) ? */
+    readonly ok: boolean;
+    /** Code HTTP, ou `null` si l'échec est réseau/timeout (pas de réponse). */
+    readonly status: number | null;
+    /** Message d'erreur (réseau/timeout/HTTP non-2xx), ou `null` si OK. */
+    readonly error: string | null;
+    /**
+     * Début du corps de réponse du destinataire (tronqué à {@link RESPONSE_BODY_CAP}),
+     * ou `null` si vide/réseau. Capturé pour l'historique de livraison (debug).
+     */
+    readonly responseBody?: string | null;
+}
+/** Options de transport d'une livraison. */
+export interface IDeliveryOptions {
+    /** Délai max de la tentative (ms). */
+    readonly timeoutMs: number;
+    /** IP validées à **pinner** (la 1ʳᵉ est utilisée) ; vide = résolution normale. */
+    readonly addresses?: readonly string[];
+    /** Autorise `http:` (dev). Défaut : https only. */
+    readonly allowHttp?: boolean;
+}
+/**
+ * POST le corps signé vers l'URL, en pinnant l'IP validée et sans suivre les
+ * redirections. Ne lève jamais : tout échec est encodé dans {@link IDeliveryResult}.
+ */
+export declare function deliverWebhook(url: string, body: string, headers: Record<string, string>, opts: IDeliveryOptions): Promise<IDeliveryResult>;

package/dist/types/nodefony/src/webhook/webhookFilters.d.ts

@@ -0,0 +1,64 @@
+import type { FacetCounts } from "nodefony";
+/**
+ * **Le vocabulaire de filtre des endpoints webhook**, en noms PUBLICS — ceux
+ * qu'un client écrit dans l'URL (`?enabled=false&event=user.created`).
+ *
+ * Frère de `WEBHOOK_SORTABLE_FIELDS`, et posé au même endroit pour la même
+ * raison : le vocabulaire appartient au propriétaire du contrat, la mécanique de
+ * lecture au cœur (`parseFilters`).
+ *
+ * `event` reste une chaîne LIBRE, et non une énumération : le catalogue
+ * d'événements est celui de l'application qui émet, pas du framework. Le refus
+ * porte donc sur la forme (paramètre inconnu, valeur mal formée), jamais sur le
+ * nom d'un événement — le refuser reviendrait à décider à la place de l'app ce
+ * qu'elle a le droit de publier.
+ */
+export declare const WEBHOOK_FILTERS: {
+    /** `true` = actifs seulement, `false` = désactivés seulement, absent = les deux. */
+    readonly enabled: "boolean";
+    /** Endpoints abonnés à CET événement (« qui écoute `user.created` ? »). */
+    readonly event: "string";
+    /** `true` = en échec (`failureCount > 0`), `false` = sains, absent = les deux. */
+    readonly failing: "boolean";
+};
+/**
+ * **Les facettes des endpoints** — les questions fermées que la console pose à
+ * la collection ENTIÈRE pour ses cartes de tête.
+ *
+ * Chacune est un filtre du contrat, et c'est la règle : une carte affiche un
+ * nombre que le tableau doit pouvoir montrer. `failing` recoupe volontairement
+ * `active` et `disabled` — un endpoint peut être actif ET en échec — d'où
+ * l'interdiction de déduire une facette d'une autre par soustraction.
+ */
+export declare const WEBHOOK_FACETS: {
+    /** Tous les endpoints configurés. */
+    readonly total: {};
+    /** Endpoints actifs (le dispatcher leur livre). */
+    readonly active: {
+        readonly enabled: true;
+    };
+    /** Endpoints désactivés — à la main ou par coupe-circuit. */
+    readonly disabled: {
+        readonly enabled: false;
+    };
+    /** Endpoints en échec, actifs ou non. */
+    readonly failing: {
+        readonly failing: true;
+    };
+};
+/** Les compteurs rendus par `GET /nodefony/security/api/webhooks/stats`. */
+export type IWebhookCounts = FacetCounts<typeof WEBHOOK_FACETS>;
+/**
+ * Ce que l'endpoint de COMPTEURS accepte de filtrer — `WEBHOOK_FILTERS` **moins**
+ * les champs que les facettes décomposent (`enabled`, `failing`).
+ *
+ * Les demander ici rendrait une réponse contradictoire : le total suivrait le
+ * filtre pendant que chaque facette l'écraserait par le sien. `event` reste,
+ * parce qu'il découpe une AUTRE dimension — « combien d'endpoints écoutent
+ * `user.created`, et dans quel état sont-ils ? » est une question cohérente.
+ *
+ * Un test verrouille l'accord entre cette liste et {@link WEBHOOK_FACETS}.
+ */
+export declare const WEBHOOK_STATS_FILTERS: {
+    readonly event: "string";
+};