@nodefony/security 10.0.0-alpha.1

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

@@ -0,0 +1,66 @@
+import { Service, Module } from "nodefony";
+/** Données à porter en session entre `authorize` et `callback` (anti-replay). */
+export interface IOAuthAuthorization {
+    /** URL d'autorisation vers laquelle rediriger l'utilisateur. */
+    readonly url: string;
+    /** `state` anti-CSRF à stocker en session (RFC 9700). */
+    readonly state: string;
+    /** `code_verifier` PKCE à stocker en session, ou `null` (fournisseur sans PKCE). */
+    readonly codeVerifier: string | null;
+}
+/**
+ * **Social login OAuth 2.0** (P6 J9) — orchestrateur du flux *Authorization Code*
+ * au-dessus d'`arctic`.
+ *
+ * Posture OAuth 2.1 (RFC 9700) : Authorization Code uniquement (jamais implicit /
+ * ROPC), **PKCE S256** quand le fournisseur le supporte (RFC 7636), **state**
+ * anti-CSRF, **iss** anti-mix-up (RFC 9207) ; aucun jeton n'atteint le navigateur
+ * (le login produit une **session BFF**, gérée hors de ce service par le
+ * controller + `AuthFlow`).
+ *
+ * `arctic` est **importé paresseusement** au premier login (cold path — jamais au
+ * boot ni par requête), comme `@simplewebauthn`/`jose`. Au boot (si
+ * `oauth2.enabled`) : seule la config est validée et les fournisseurs configurés
+ * sont confrontés au registre (un nom inconnu = WARNING, pas fatal).
+ *
+ * Le service ne touche **ni HTTP ni session** : il rend à l'appelant les éléments
+ * (URL, state, verifier) que le controller persiste en session — testable sans
+ * transport, comme `AuthFlow`.
+ */
+declare class OAuth2Service extends Service {
+    #private;
+    module: Module;
+    constructor(module: Module);
+    /** `true` si le social login est opérationnel (activé + boot OK). */
+    isEnabled(): boolean;
+    /** Noms des fournisseurs configurés ET connus du registre (UI : boutons à afficher). */
+    listProviders(): string[];
+    /**
+     * Redirections post-login (succès / échec) — lues par le controller.
+     * Surcharge PAR FOURNISSEUR si fournie, sinon valeur globale, sinon défaut.
+     */
+    getRedirects(provider?: string): {
+        success: string;
+        failure: string;
+    };
+    /**
+     * Étape 1 — prépare l'URL d'autorisation + les éléments anti-replay à stocker
+     * en session (`state`, et `code_verifier` si PKCE).
+     *
+     * @throws AuthenticationError — fournisseur non configuré / inconnu du registre.
+     */
+    createAuthorization(provider: string): Promise<IOAuthAuthorization>;
+    /**
+     * Étape 2 — valide la réponse, échange le `code`, lit le profil et provisionne
+     * l'utilisateur local (Shadow User). Retourne l'identifiant à ouvrir en session.
+     *
+     * @param returnedIss - paramètre `iss` reçu (anti-mix-up RFC 9207), ou `null`.
+     * @throws AuthenticationError — `iss` invalide, échange refusé, ou provisioning
+     *   impossible (lien inconnu + signup interdit).
+     */
+    exchangeAndProvision(provider: string, code: string, codeVerifier: string | null, returnedIss: string | null): Promise<{
+        identifier: string;
+    }>;
+}
+export default OAuth2Service;
+export { OAuth2Service };

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

@@ -0,0 +1,66 @@
+import { type CspFragment } from "../src/csp.js";
+/**
+ * Sous-ensemble APPLICATIF de la config `headers` (cf defineSecurityConfig).
+ *
+ * `hsts` / `frameguard` / `noSniff` n'y figurent PAS volontairement : ces trois
+ * en-têtes « transport » sont posés par `@nodefony/http` à l'entrée brute
+ * (`onHttpRequest`, AVANT le pipeline) pour couvrir AUSSI les fichiers statiques,
+ * les erreurs précoces et un serveur sans module security (secure-by-default).
+ * `@nodefony/security` ne les ré-émet pas → une seule source par en-tête.
+ */
+export interface ISecurityHeadersOptions {
+    enabled: boolean;
+    csp: string;
+    cspNonces: boolean;
+    referrerPolicy: string;
+    coop?: string;
+    coep?: string;
+    corp?: string;
+    originAgentCluster?: boolean;
+    permissionsPolicy?: string;
+}
+/**
+ * En-têtes de sécurité **applicatifs** de Nodefony (couche `@nodefony/security`,
+ * complémentaire du socle transport de `@nodefony/http`). Pré-calcule une fois au
+ * boot la table d'en-têtes CONSTANTS (CSP statique, Referrer-Policy, isolation
+ * cross-origin COOP/COEP/CORP, Origin-Agent-Cluster, Permissions-Policy) → zéro
+ * alloc, zéro concat par requête (le firewall la pose telle quelle).
+ *
+ * **Étape A+B** : en-têtes constants pré-calculés au boot (Referrer/COOP/…). Pour le
+ * CSP, deux régimes mutuellement exclusifs : **statique** (posé tel quel via `headers`,
+ * 0 alloc/req) OU **nonce par requête** (`cspNonces` + placeholder `{{nonce}}` dans le
+ * CSP) → segments pré-split au boot, recomposés par requête via `cspFor(nonce)` (1
+ * `join`, aucun parse/regex dans le hot-path). Le nonce lui-même vit sur `Context`.
+ *
+ * @see Fetch Metadata · W3C CSP Level 3 · WHATWG (COOP/COEP/CORP).
+ */
+export declare class SecurityHeaders {
+    #private;
+    constructor(o: ISecurityHeadersOptions);
+    /** Table d'en-têtes applicatifs CONSTANTS (figée), posée telle quelle par le firewall. */
+    get headers(): Readonly<Record<string, string>>;
+    /** `true` si le CSP est recomposé par requête avec un nonce (→ `cspFor`). */
+    get hasNonce(): boolean;
+    /**
+     * Recompose le CSP en injectant le `nonce` de la requête aux emplacements
+     * `{{nonce}}`. 1 `join` (segments pré-split au boot). Le nonce est base64 (jamais
+     * `'`/`;`/espace) → aucune évasion possible du token CSP.
+     *
+     * @param nonce - nonce base64 de la requête (`Context.cspNonce`).
+     * @returns la valeur `Content-Security-Policy` à poser sur la réponse.
+     */
+    cspFor(nonce: string): string;
+    /**
+     * Recompose le CSP en fusionnant ADDITIVEMENT les directives `extra` d'une
+     * route (`@Csp`) dans le CSP de base, PUIS en substituant le `nonce`. Le merge
+     * (parse/serialize) n'est payé QUE sur les routes décorées `@Csp` (rares) — le
+     * cas courant reste {@link cspFor} (1 `join`). Une directive déjà présente voit
+     * ses sources complétées (jamais dupliquée — W3C CSP3 §3).
+     *
+     * @param nonce - nonce base64 de la requête (ignoré si le CSP n'a pas de nonce).
+     * @param extra - directives additionnelles de la route (`directive → sources`).
+     * @returns la valeur `Content-Security-Policy` à poser sur la réponse.
+     */
+    cspForExtra(nonce: string, extra: CspFragment): string;
+}
+export default SecurityHeaders;

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

@@ -0,0 +1,103 @@
+import { Service, Module } from "nodefony";
+import type * as Jose from "jose";
+import type { IUser } from "@nodefony/user";
+/**
+ * Réponse d'émission de jetons — nommage RFC 6749 §5.1 (snake_case, JSON).
+ * Le JWT part en `Authorization: Bearer`, JAMAIS en cookie ni en URL.
+ */
+export interface ITokenResponse {
+    access_token: string;
+    refresh_token: string;
+    token_type: "Bearer";
+    /** Durée de vie de l'access token (s). */
+    expires_in: number;
+    /** Scopes accordés (séparés par des espaces). */
+    scope: string;
+}
+/**
+ * Orchestrateur des jetons longue durée (P6 J4) — émission/refresh des JWT +
+ * **maintenance du store** (le seam `ITokenStore.gc()` n'a pas d'autre appelant).
+ *
+ * Au boot (si `jwt.enabled`) : résout le store pluggable (`tokenStore.store`),
+ * crée le keystore Ed25519, les pose au container (`tokenStore`/`jwtKeystore`,
+ * consommés par le `JwtAuthenticator` et les endpoints framework), puis arme un
+ * **timer de gc** `unref` (n'empêche pas l'arrêt) avec **jitter** de phase
+ * (étale les balayages entre process d'un cluster sur un store partagé). À
+ * l'arrêt (`onTerminate`) : `clearInterval`/`clearTimeout`.
+ *
+ * Émission = « password grant » M2M/CLI : credential vérifié par le service
+ * `users` → access (JWT signé, 15 min) + refresh (secret opaque haute entropie,
+ * stocké **haché**). Refresh = rotation + détection de rejeu (RFC 9700 §4.14).
+ */
+declare class TokenService extends Service {
+    #private;
+    module: Module;
+    constructor(module: Module);
+    /** `true` si l'émission JWT (signature + refresh) est opérationnelle. */
+    isEnabled(): boolean;
+    /**
+     * Émetteur sous lequel cette application accepte d'être DÉCOUVERTE, ou `null`.
+     *
+     * C'est la question que pose `@nodefony/framework` au moment de monter (ou
+     * non) `/.well-known/oauth-authorization-server` et `/.well-known/jwks.json` :
+     * il ne lit pas la configuration de sécurité, il obtient une réponse. `null`
+     * = aucune route, donc `404` — pas de document creux, pas de demi-mesure.
+     *
+     * @returns l'émetteur canonique publiable, ou `null` si rien ne doit l'être
+     */
+    publishedIssuer(): string | null;
+    /**
+     * Jeu de clés **publiques** de signature, tel qu'il doit être servi.
+     *
+     * Ne contient que des paramètres publics (RFC 8037/7517) — le keystore ne
+     * sérialise jamais `d`. Rien n'est calculé ici : la route est une porte, la
+     * matière vient du keystore.
+     *
+     * @returns le JWKS public
+     * @throws Error si la capacité JWT n'est pas active (garde de programmation :
+     *         les routes ne sont montées que si {@link publishedIssuer} répond)
+     */
+    getPublicJWKS(): Promise<Jose.JSONWebKeySet>;
+    /**
+     * Une passe de purge du store (`ITokenStore.gc()`) — point d'entrée public d'un
+     * ordonnanceur : le {@link GcScheduler} l'appelle, mais le futur worker cron
+     * (`security:token-gc` / k8s CronJob) peut l'appeler à sa place (poser alors
+     * `tokenStore.gcIntervalS: 0`). L'anti-empilement et la capture d'erreur vivent
+     * dans le GcScheduler (via `onError`) — ici, la passe métier nue.
+     *
+     * ⚠️ Un store **local** (`memory`/`file`) est par-process (mémoires disjointes) :
+     * seul SON process peut le purger → le timer in-process reste indispensable. Un
+     * store **partagé** (ORM) peut être délégué au worker cron (un seul balayage).
+     *
+     * @returns nombre d'entrées purgées.
+     */
+    runGc(): Promise<number>;
+    /**
+     * Émet un couple access/refresh après vérification d'un credential
+     * identifiant/mot de passe (grant M2M/CLI). Throttling NIST partagé si activé.
+     *
+     * @throws ThrottledError (429) — backoff actif.
+     * @throws AuthenticationError (401, message uniforme) — credential invalide.
+     */
+    issueForCredentials(identifier: unknown, password: unknown, requestedScopes?: string[], resource?: unknown): Promise<ITokenResponse>;
+    issueTokens(user: IUser, requestedScopes?: string[], resource?: unknown, accessTtlS?: number): Promise<ITokenResponse>;
+    /**
+     * Rotation d'un refresh token (RFC 9700 §4.14) : valide le refresh présenté,
+     * émet un nouveau couple, révoque l'ancien. Un refresh **déjà révoqué**
+     * re-présenté = rejeu → toute la famille est coupée.
+     *
+     * @param rawRefresh - le refresh token présenté, en clair
+     * @param resource - ressource visée (RFC 8707 §2.2). Sur un `refresh_token`,
+     *          la politique « may limit the acceptable resources to those that
+     *          were originally granted […] or a subset thereof » : un jeton ne
+     *          portant qu'une seule audience, le seul sous-ensemble possible est
+     *          elle-même. Demander autre chose est donc refusé, jamais ignoré —
+     *          sinon la rotation devient le chemin par lequel on obtient une
+     *          audience qu'on n'a pas su demander à l'émission.
+     * @throws AuthenticationError (401) — refresh inconnu/expiré/révoqué, sujet banni.
+     * @throws InvalidTargetError (400) — `resource` demandée ≠ celle accordée
+     */
+    refresh(rawRefresh: unknown, resource?: unknown): Promise<ITokenResponse>;
+}
+export default TokenService;
+export { TokenService };

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

@@ -0,0 +1,58 @@
+import { Service, Module } from "nodefony";
+import type { IPage } from "nodefony";
+import type { ITotpEnrollmentSummary, ITotpListQuery } from "../contracts/ITotpSecretStore.js";
+import { type ITotpEnrollment, type ITotpActivation, type ITotpStatus, type ITotpLoginResult } from "../src/totp/totpOperations.js";
+/**
+ * **2FA TOTP** (P6.17, RFC 6238) — service d'orchestration du second facteur.
+ *
+ * Coquille fine : au boot (si `totp.enabled`) il résout le **store** de secrets
+ * pluggable + la **clé de chiffrement** AES-256-GCM, puis délègue toute la logique
+ * aux opérations pures `totpOperations` (testées sans serveur). Le TOTP est un
+ * facteur de **login step-up** (le code n'est présenté qu'à la connexion, calque
+ * WebAuthn/OAuth), pas un authenticator du firewall — `session.user` n'est posé
+ * qu'une fois le second facteur validé (Zero Trust 401 protège tout le reste).
+ *
+ * **Clé de chiffrement** : le secret TOTP est réversible (le serveur le relit pour
+ * calculer le code) → chiffré, jamais haché. La clé vient de `totp.encryptionKey`
+ * (dérivée HKDF). Absente : en dev une clé **éphémère** est générée + WARNING (les
+ * secrets ne survivent pas au redémarrage) ; en **production** c'est fatal — 2FA
+ * désactivé (une clé éphémère rendrait les secrets illisibles après redémarrage /
+ * sur les autres pods). Politique calquée sur RedisIdempotencyStore.
+ */
+declare class TotpService extends Service {
+    #private;
+    module: Module;
+    constructor(module: Module);
+    /** `true` si le 2FA est opérationnel (activé en config, boot OK). */
+    isEnabled(): boolean;
+    /** Démarre l'enrôlement (secret + QR affichés 1×). */
+    beginEnrollment(userId: string, account: string): Promise<ITotpEnrollment>;
+    /** Confirme l'enrôlement par un 1ᵉʳ code → active + codes de récupération clairs. */
+    confirmEnrollment(userId: string, code: string): Promise<ITotpActivation>;
+    /** Vérifie un second facteur au login (code TOTP ou code de récupération). */
+    verifyLogin(userId: string, code: string): Promise<ITotpLoginResult>;
+    /** Désactive le 2FA d'un utilisateur. */
+    disable(userId: string): Promise<void>;
+    /** État 2FA d'un utilisateur (absent / pending / activé + codes restants). */
+    status(userId: string): Promise<ITotpStatus>;
+    /**
+     * Page d'enrôlements 2FA — pagination **native au store** (jamais un parcours
+     * complet). Vue sans secret ni condensats, garantie par le contrat du store.
+     *
+     * @param query - fenêtre + filtres ({@link ITotpListQuery}).
+     * @returns la page d'enrôlements.
+     */
+    listPage(query: ITotpListQuery): Promise<IPage<ITotpEnrollmentSummary>>;
+    /**
+     * Nombre d'enrôlements correspondant aux filtres — le KPI « couverture 2FA »
+     * sans énumérer.
+     *
+     * @param query - filtres ({@link ITotpListQuery}) ; `limit` ignoré.
+     * @returns le compte exact.
+     */
+    countEnrollments(query: ITotpListQuery): Promise<number>;
+    /** 2FA activé pour cet utilisateur ? (raccourci pour le flow de login). */
+    isEnabledFor(userId: string): Promise<boolean>;
+}
+export default TotpService;
+export { TotpService };

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

@@ -0,0 +1,123 @@
+import { Service, Module } from "nodefony";
+import type { AuthenticationResponseJSON, PublicKeyCredentialCreationOptionsJSON, PublicKeyCredentialRequestOptionsJSON, RegistrationResponseJSON } from "@simplewebauthn/server";
+import type { IPage } from "nodefony";
+import type { IWebAuthnCredential } from "../contracts/IWebAuthnCredential.js";
+import type { IWebAuthnCredentialSummary, IWebAuthnListQuery } from "../contracts/IWebAuthnCredentialStore.js";
+/** Sujet d'une cérémonie d'enregistrement — l'utilisateur qui crée un passkey. */
+export interface IWebAuthnUser {
+    /** Identifiant applicatif stable (sub / username) — devient le `userHandle`. */
+    readonly id: string;
+    /** Nom de compte affiché par l'OS (email, identifiant…). */
+    readonly name: string;
+    /** Nom complet optionnel (UX de l'invite système). */
+    readonly displayName?: string;
+}
+/** Résultat d'une authentification WebAuthn vérifiée. */
+export interface IWebAuthnAssertionResult {
+    /** Le credential résolu (état déjà mis à jour : compteur, sauvegarde, usage). */
+    readonly credential: IWebAuthnCredential;
+    /** Identifiant de l'utilisateur propriétaire du credential. */
+    readonly userId: string;
+}
+/**
+ * **WebAuthn / passkeys** (P6 J9) — orchestrateur des deux cérémonies FIDO2
+ * (WebAuthn L3 §7.1 enregistrement, §7.2 authentification).
+ *
+ * MFA **phishing-resistant** : la clé privée ne quitte jamais l'authenticator
+ * (Touch ID, Windows Hello, clé FIDO). Le serveur ne manipule QUE des clés
+ * publiques + vérifie des signatures. La vérification cryptographique (parsing
+ * CBOR/COSE, signatures ES256/RS256/EdDSA) est déléguée à `@simplewebauthn/server`
+ * (lib auditée de l'écosystème), **importée paresseusement** au 1ᵉʳ usage (cold
+ * path — l'enregistrement/login n'est pas le hot path par requête).
+ *
+ * Au boot (si `passkeys.enabled`) : résout le RP (rpID/rpName/origines depuis la
+ * config, sinon le domaine de l'app) + le store de credentials pluggable
+ * (`webAuthnCredentialStore` du container, sinon le builtin mémoire) et le pose
+ * au container — une application peut donc fournir le sien avant le boot.
+ *
+ * Il n'existe **pas** d'authenticator passkey : `WebAuthnController`
+ * (`@nodefony/framework`) mène les deux cérémonies via ce service, puis
+ * `AuthFlow.establishSessionFor()` ouvre la session BFF ; les requêtes
+ * suivantes sont ré-authentifiées par `SessionAuthenticator`.
+ *
+ * **Anti-rejeu** : le challenge serveur est porté HORS de ce service (en session
+ * BFF par le controller) ; chaque `verify*` reçoit le `expectedChallenge` qu'il
+ * a émis — un challenge n'est jamais réutilisable.
+ */
+declare class WebAuthnService extends Service {
+    #private;
+    module: Module;
+    constructor(module: Module);
+    /** `true` si les cérémonies sont opérationnelles (passkeys activés, boot OK). */
+    isEnabled(): boolean;
+    /**
+     * Prépare les options de `navigator.credentials.create()` — le défi à signer +
+     * les contraintes (RP, type d'attestation, sélection d'authenticator). Le
+     * challenge renvoyé doit être stocké côté serveur (session) par l'appelant.
+     *
+     * `excludeCredentials` liste les passkeys déjà enregistrés du même utilisateur
+     * pour empêcher un double enregistrement sur le même authenticator (§7.1).
+     */
+    generateRegistrationOptions(user: IWebAuthnUser): Promise<PublicKeyCredentialCreationOptionsJSON>;
+    /**
+     * Vérifie la réponse d'enregistrement (challenge, origine, rpIdHash, flags,
+     * format d'attestation) et **persiste** le nouveau credential.
+     *
+     * @param expectedChallenge - le challenge émis par {@link generateRegistrationOptions} (session).
+     * @param userId - propriétaire du credential (utilisateur authentifié/en création).
+     * @param requestOrigin - origine HTTP de la requête (validée si aucune origine n'est configurée).
+     * @throws AuthenticationError (401) — vérification échouée.
+     * @throws WebAuthnError (409) — plafond `passkeys.maxPerUser` atteint.
+     */
+    verifyRegistration(response: RegistrationResponseJSON, expectedChallenge: string, userId: string, requestOrigin?: string): Promise<IWebAuthnCredential>;
+    /**
+     * Prépare les options de `navigator.credentials.get()`. Sans `userId`
+     * (usernameless) : `allowCredentials` est omis → l'authenticator propose ses
+     * passkeys découvrables (UX cible). Avec `userId` : ciblage des credentials
+     * connus de cet utilisateur.
+     *
+     * @param userId - identité **déjà prouvée** (session en cours) et jamais un
+     *   identifiant reçu d'un appelant non authentifié : `allowCredentials`
+     *   révélerait alors qu'un compte porte une passkey et **lesquelles**, or un
+     *   `credentialId` est corrélable entre sites (W3C WebAuthn L3, « Privacy leak
+     *   via credential IDs »). Le controller BFF applique cette règle —
+     *   `WebAuthnController.loginOptions()` ne cible que depuis la session.
+     */
+    generateAuthenticationOptions(userId?: string): Promise<PublicKeyCredentialRequestOptionsJSON>;
+    /**
+     * Vérifie une assertion (signature sur `authData ‖ SHA-256(clientDataJSON)`
+     * avec la clé publique stockée, §7.2) + applique l'état (compteur anti-clone,
+     * sauvegarde, usage). Résout l'utilisateur propriétaire via le credentialId.
+     *
+     * @param expectedChallenge - le challenge émis par {@link generateAuthenticationOptions} (session).
+     * @throws AuthenticationError (401) — credential inconnu ou vérification échouée.
+     */
+    verifyAuthentication(response: AuthenticationResponseJSON, expectedChallenge: string, requestOrigin?: string): Promise<IWebAuthnAssertionResult>;
+    /** Liste les credentials d'un utilisateur (UX « mes appareils »). */
+    listUserCredentials(userId: string): Promise<IWebAuthnCredential[]>;
+    /**
+     * Page de passkeys pour le data plane admin (vue TRANSVERSE : « quels appareils
+     * portent des passkeys sur toute la plateforme »).
+     *
+     * ≠ {@link listUserCredentials}, qui sert la fiche d'UN utilisateur et le chemin
+     * chaud du login. Ici on ne matérialise jamais plus d'une page, et la projection
+     * du store exclut la clé publique.
+     */
+    listCredentialsPage(query: IWebAuthnListQuery): Promise<IPage<IWebAuthnCredentialSummary>>;
+    /**
+     * Nombre de passkeys correspondant aux filtres, ou `-1` si le backend ne sait
+     * pas compter à coût raisonnable (Redis).
+     */
+    countCredentials(query: IWebAuthnListQuery): Promise<number>;
+    /** Révoque un credential (retrait d'un appareil). */
+    removeCredential(credentialId: string): Promise<void>;
+    /**
+     * Supprime un credential **du propriétaire** (self-service, anti-IDOR) : la
+     * suppression n'aboutit que si le credential appartient bien à `userId`, sinon
+     * `false` — 404 indiscernable côté client (on ne révèle pas l'existence d'un
+     * credential d'autrui).
+     */
+    removeUserCredential(userId: string, credentialId: string): Promise<boolean>;
+}
+export default WebAuthnService;
+export { WebAuthnService };

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

@@ -0,0 +1,160 @@
+import { Service, Module } from "nodefony";
+import { type IWebhookCounts } from "../src/webhook/webhookFilters.js";
+import { Buffer } from "node:buffer";
+import type { IPage } from "nodefony";
+import type { IWebhookListQuery } from "../contracts/IWebhookStore.js";
+import type { IWebhookEndpoint, IWebhookDelivery, WebhookEndpointSummary, WebhookEndpointUpdate } from "../contracts/IWebhookEndpoint.js";
+import { type IDeliveryResult } from "../src/webhook/webhookDelivery.js";
+/** Entrée de création d'un endpoint (les champs système sont dérivés). */
+export interface IWebhookRegisterInput {
+    /** URL de destination (validée anti-SSRF). */
+    readonly url: string;
+    /** Actions d'audit souscrites (`"*"` = toutes). */
+    readonly events: readonly string[];
+    /** Libellé humain optionnel. */
+    readonly description?: string | null;
+    /** Actif dès la création ? Défaut : `true`. */
+    readonly enabled?: boolean;
+    /** Identité de l'admin créateur (traçabilité). */
+    readonly createdBy?: string | null;
+    /** Slot multi-tenant (réservé). */
+    readonly tenantId?: string | null;
+    /** Métadonnées extensibles. */
+    readonly metadata?: Record<string, unknown>;
+}
+/** Résultat de création/rotation : le secret en clair n'est exposé qu'ici, **une fois**. */
+export interface IWebhookSecretReveal {
+    /** Endpoint (sans secret chiffré). */
+    readonly endpoint: WebhookEndpointSummary;
+    /** Secret de signature en clair (`whsec_…`) — à communiquer au consommateur. */
+    readonly secret: string;
+}
+/** Politique de livraison lue par le dispatcher (Slice B). */
+export interface IWebhookDeliveryPolicy {
+    readonly timestampToleranceS: number;
+    readonly maxRetries: number;
+    readonly autoDisableThreshold: number;
+    readonly deliveryTimeoutMs: number;
+    readonly maxConcurrent: number;
+    readonly maxQueue: number;
+    readonly allowHttp: boolean;
+    readonly denyPrivateIps: boolean;
+}
+/**
+ * **Webhooks sortants** (P6.13) — service d'orchestration du registre d'endpoints.
+ *
+ * Coquille fine : au boot (si `webhooks.enabled`) il résout le **store**
+ * d'endpoints pluggable + la **clé de chiffrement** des secrets de signature, puis
+ * expose le CRUD (register/list/update/rotate/revoke). Le secret de signature est
+ * **chiffré au repos** (réversible : relu pour signer chaque livraison, jamais
+ * haché). La livraison signée elle-même (Standard Webhooks v1) vit dans le
+ * dispatcher (Slice B), qui consomme {@link getSnapshot}/{@link getSigningKey}.
+ *
+ * Toute URL est validée **anti-SSRF** à l'enregistrement (et re-pinnée à la
+ * livraison). Politique de clé calquée sur TOTP/RedisIdempotencyStore : absente en
+ * dev = clé éphémère + WARNING ; en production = fatal (webhooks désactivés).
+ */
+declare class WebhookService extends Service {
+    #private;
+    module: Module;
+    constructor(module: Module);
+    /** Le service est-il opérationnel (activé + store + clé) ? */
+    isReady(): boolean;
+    /**
+     * Champs de tri que le backend **actuellement branché** sait honorer, en
+     * vocabulaire public. Le data plane admin les passe en allowlist au traducteur
+     * de requête de page : hors de cette liste, un `?order=` est refusé en 400.
+     *
+     * La liste vient du store, jamais d'une constante recopiée ici : un backend
+     * qui ne trierait pas refuserait alors le tri **sans qu'aucune règle
+     * supplémentaire ne soit écrite**. Store absent (webhooks désactivés) ⇒ aucune
+     * capacité annoncée, donc aucun tri promis.
+     *
+     * @returns les champs triables, ou un tableau vide.
+     */
+    sortableFields(): readonly string[];
+    /**
+     * Enregistre un endpoint : valide l'URL (anti-SSRF), génère un secret de
+     * signature, le chiffre au repos. Retourne l'endpoint + le secret **en clair**
+     * (la seule occasion de le lire pour le copier).
+     *
+     * @throws SsrfError si l'URL est invalide / cible non publique.
+     */
+    register(input: IWebhookRegisterInput): Promise<IWebhookSecretReveal>;
+    /**
+     * Page d'endpoints (vue publique, sans secret) — pagination **native au
+     * store** : la console n'a jamais tout le registre en RAM.
+     *
+     * @param query - fenêtre + filtres ({@link IWebhookListQuery}).
+     * @returns la page, chaque endpoint réduit à sa vue publique.
+     */
+    listPage(query: IWebhookListQuery): Promise<IPage<WebhookEndpointSummary>>;
+    /**
+     * Nombre d'endpoints correspondant aux filtres (`COUNT` natif au store).
+     *
+     * @param query - filtres ({@link IWebhookListQuery}) ; `limit` ignoré.
+     * @returns le compte exact, ou `-1` si le backend ne sait pas compter.
+     */
+    countEndpoints(query: IWebhookListQuery): Promise<number>;
+    /**
+     * Les compteurs de tête de la console — posés sur la collection ENTIÈRE, pas
+     * sur la page affichée.
+     *
+     * Un endpoint peut être **actif ET en échec** : les facettes se recoupent, et
+     * aucune n'est déduite d'une autre par soustraction. Chaque compteur vaut
+     * `null` si le backend ne sait pas compter.
+     *
+     * @param query - filtres à appliquer avant comptage (sans fenêtre).
+     */
+    countWebhookFacets(query?: Partial<IWebhookListQuery>): Promise<IWebhookCounts>;
+    /** Un endpoint par id (vue publique), ou `null`. */
+    getEndpoint(id: string): Promise<WebhookEndpointSummary | null>;
+    /**
+     * Met à jour les champs mutables (url/events/enabled/description/metadata).
+     * Une nouvelle `url` est re-validée anti-SSRF. Retourne l'endpoint mis à jour,
+     * ou `null` si absent.
+     */
+    update(id: string, patch: Pick<WebhookEndpointUpdate, "url" | "events" | "enabled" | "description" | "metadata">): Promise<WebhookEndpointSummary | null>;
+    /** Active/désactive un endpoint (révocation douce = `false`). */
+    setEnabled(id: string, enabled: boolean): Promise<WebhookEndpointSummary | null>;
+    /**
+     * Régénère le secret de signature (rotation) et retourne le nouveau en clair.
+     * L'ancien cesse immédiatement d'être valide. `null` si l'endpoint est absent.
+     */
+    rotateSecret(id: string): Promise<IWebhookSecretReveal | null>;
+    /**
+     * Révèle le secret en clair d'un endpoint (réversible — usage admin, à auditer
+     * par l'appelant). `null` si absent.
+     */
+    revealSecret(id: string): Promise<string | null>;
+    /** Supprime un endpoint. Retourne `false` si absent. */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Historique des dernières livraisons d'un endpoint (plus récentes d'abord) —
+     * ce que Nodefony a ENVOYÉ + la réponse observée. RAM, borné, par pod
+     * (observabilité éphémère, non persistée). `[]` si aucune livraison.
+     */
+    listDeliveries(id: string): IWebhookDelivery[];
+    /** Snapshot mémoire (sync) des endpoints — itération du dispatcher (si >0). */
+    getSnapshot(): IWebhookEndpoint[];
+    /**
+     * Nombre d'endpoints (0-alloc) — court-circuit hot-path du dispatcher.
+     *
+     * @remarks C'est ICI que la fraîcheur se joue, pas seulement dans
+     *   {@link getSnapshot} : un pod démarré avant toute création de webhook a un
+     *   cache VIDE, court-circuite sur ce zéro et n'atteindrait jamais le snapshot.
+     */
+    endpointCount(): number;
+    /** Déchiffre le secret de signature d'un endpoint (pour signer une livraison). */
+    decryptEndpointSecret(endpoint: IWebhookEndpoint): Buffer;
+    /** Politique de livraison (tolérance/retries/timeout…) issue de la config. */
+    getDeliveryPolicy(): IWebhookDeliveryPolicy;
+    /**
+     * Enregistre le résultat d'une livraison (appelé par le dispatcher) :
+     * lastDelivery*, compteur d'échecs consécutifs, et **auto-désactivation** de
+     * l'endpoint au-delà du seuil (façon GitHub). Le succès remet le compteur à 0.
+     */
+    markDelivery(id: string, result: IDeliveryResult): Promise<void>;
+}
+export { WebhookService };
+export default WebhookService;

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

@@ -0,0 +1,21 @@
+/**
+ * Résout la hiérarchie de rôles — `ROLE_ADMIN` hérite `ROLE_USER`, etc.
+ *
+ * Aplatissement DFS **précalculé au boot** (lecture O(1) au runtime, hot-path) +
+ * **détection de cycles au boot** (throw avec le chemin complet, pas de fail-silent).
+ * Niveau A de l'autorisation (P6.8).
+ */
+export declare class RoleHierarchyWalker {
+    #private;
+    constructor(hierarchy?: Record<string, readonly string[]>);
+    /**
+     * L'utilisateur (rôles plats) possède-t-il le rôle requis, hiérarchie résolue ?
+     *
+     * @param userRoles - rôles plats de l'utilisateur.
+     * @param required - rôle exigé.
+     */
+    hasRole(userRoles: readonly string[], required: string): boolean;
+    /** Ensemble complet des rôles atteignables (plats + hérités). */
+    reachableRoles(userRoles: readonly string[]): Set<string>;
+}
+export default RoleHierarchyWalker;

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

@@ -0,0 +1,31 @@
+import type { ContextType } from "@nodefony/http";
+import type { ISecuredArea } from "../contracts/ISecuredArea.js";
+import type { ISecurityAreaConfig } from "../config/defineModuleConfig.js";
+/**
+ * Zone sécurisée concrète — pattern d'URL compilé + métadonnées d'authentification.
+ *
+ * Objet **léger** (pas un Service DI : zéro besoin d'event/log par zone, hot-path).
+ * Le firewall en instancie une par entrée `areas` de la config, triées par
+ * spécificité au boot.
+ */
+export declare class SecuredArea implements ISecuredArea {
+    readonly name: string;
+    readonly pattern: RegExp;
+    readonly security: boolean;
+    readonly stateless: boolean;
+    readonly mode: "first" | "all";
+    readonly authenticators: readonly string[];
+    readonly host?: string;
+    readonly realtime: boolean;
+    readonly resource?: string;
+    constructor(name: string, config: ISecurityAreaConfig);
+    /**
+     * Cœur du match — pathname (+ host éventuel) déjà extraits, SANS `context`.
+     * Réutilisable par le verrou WebSocket (une frame n'a qu'un path) : source
+     * UNIQUE de la décision de zone (invariant `api.request {path}` ≤ `GET {path}`).
+     */
+    matchPath(pathname: string, host?: string): boolean;
+    /** La requête tombe-t-elle dans cette zone ? (host éventuel + pathname). */
+    match(context: ContextType): boolean;
+}
+export default SecuredArea;