@nodefony/security 10.0.0-alpha.1

package/dist/types/nodefony/contracts/ITotpSecret.d.ts

@@ -0,0 +1,41 @@
+import type { TotpAlgorithm } from "../src/totp/totpCrypto.js";
+/**
+ * Secret TOTP d'un utilisateur (2FA) — **un seul par utilisateur** (clé = `userId`).
+ *
+ * Le secret partagé `K` est **chiffré au repos** ({@link ITotpSecret.secretEnc}) :
+ * le serveur doit pouvoir le **relire** pour recalculer le code à chaque login →
+ * réversible, donc chiffré (AES-256-GCM), **jamais** haché (≠ mot de passe / clé
+ * API). Les codes de récupération, eux, sont **hachés** (verify-only).
+ */
+export interface ITotpSecret {
+    /** Identifiant de l'utilisateur propriétaire (clé naturelle). */
+    readonly userId: string;
+    /**
+     * Secret partagé `K` **chiffré** (blob opaque : `iv.tag.ciphertext` base64url).
+     * Produit/lu par le service détenteur de la clé — le store ne voit que des octets.
+     */
+    readonly secretEnc: string;
+    /** Fonction HMAC du code (RFC 6238 §1.2). */
+    readonly algorithm: TotpAlgorithm;
+    /** Nombre de chiffres du code. */
+    readonly digits: number;
+    /** Période d'un code en secondes. */
+    readonly period: number;
+    /** Condensats `sha256` des codes de récupération **non encore consommés**. */
+    recoveryCodes: string[];
+    /**
+     * Horodatage de **confirmation** de l'enrôlement (epoch ms), ou `null` tant que
+     * l'utilisateur n'a pas prouvé qu'il lit bien les codes (anti-lock-out).
+     */
+    confirmedAt: number | null;
+    /**
+     * Dernière tranche temporelle `T` ayant validé un code (RFC 6238 §5.2) — un code
+     * déjà consommé dans sa fenêtre **ne doit pas resservir** (anti-rejeu).
+     */
+    lastUsedStep: number | null;
+    /** Horodatage de création (epoch ms). */
+    readonly createdAt: number;
+    /** Horodatage du dernier usage réussi (epoch ms), ou `null`. */
+    lastUsedAt: number | null;
+}
+export default ITotpSecret;

package/dist/types/nodefony/contracts/ITotpSecretStore.d.ts

@@ -0,0 +1,88 @@
+import type { IPage, IPageQuery } from "nodefony";
+import type { ITotpSecret } from "./ITotpSecret.js";
+/**
+ * Vue d'un enrôlement 2FA pour l'INTROSPECTION admin (« qui a activé le 2FA,
+ * qui est resté en attente de confirmation »).
+ *
+ * **Sans secret, par construction du contrat** — ni `secretEnc` (le secret
+ * partagé, réversible : il permettrait de générer les codes de la victime), ni
+ * `recoveryCodes` (leurs condensats, matière à attaque hors ligne). La garantie
+ * porte sur ce qui SORT du store : quel que soit le backend, ces champs ne
+ * peuvent pas remonter par ce chemin, même si un appelant les demandait. Le
+ * NOMBRE de codes restants, lui, est exposé — c'est l'information
+ * d'exploitation (qui se verrouillera au prochain changement d'appareil).
+ */
+export interface ITotpEnrollmentSummary {
+    /** Utilisateur propriétaire. */
+    readonly userId: string;
+    /** Fonction HMAC du code (RFC 6238 §1.2). */
+    readonly algorithm: string;
+    /** Nombre de chiffres du code. */
+    readonly digits: number;
+    /** Période d'un code en secondes. */
+    readonly period: number;
+    /** Confirmation de l'enrôlement (epoch ms), ou `null` = en attente. */
+    readonly confirmedAt: number | null;
+    /** Création de l'enrôlement (epoch ms). */
+    readonly createdAt: number;
+    /** Dernier usage réussi (epoch ms), ou `null` = jamais servi. */
+    readonly lastUsedAt: number | null;
+    /** Nombre de codes de récupération NON consommés (jamais les condensats). */
+    readonly recoveryCodesLeft: number;
+}
+/**
+ * Requête de listing des enrôlements 2FA — {@link IPageQuery} + les filtres qui
+ * ont un sens ici. `q` (hérité) = **préfixe** d'`userId` (retrouver un id
+ * partiel collé depuis la console).
+ */
+export interface ITotpListQuery extends IPageQuery {
+    /**
+     * `true` = enrôlements confirmés seulement, `false` = en attente seulement
+     * (comptes à relancer : un secret jamais confirmé ne protège personne),
+     * omis = les deux.
+     */
+    confirmed?: boolean;
+}
+/** Champs mutables d'un secret TOTP (patch partiel). */
+export interface TotpSecretUpdate {
+    /** Confirmation de l'enrôlement (epoch ms) — passe le secret en « actif ». */
+    confirmedAt?: number | null;
+    /** Stock résiduel de codes de récupération hachés (après consommation). */
+    recoveryCodes?: string[];
+    /** Dernière tranche `T` validée (anti-rejeu RFC 6238 §5.2). */
+    lastUsedStep?: number;
+    /** Horodatage du dernier usage réussi (epoch ms). */
+    lastUsedAt?: number;
+}
+/**
+ * Store **pluggable** du secret TOTP par utilisateur — découple le cœur du backend
+ * de persistance (mémoire / fichier / ORM / Redis). Convention-frère
+ * d'`IWebAuthnCredentialStore` / `ITokenStore` : le builtin `memory` est sans
+ * dépendance, les adapters lourds s'enregistrent depuis leur propre module.
+ *
+ * Modèle **1 secret / utilisateur** (clé = `userId`) — `save` est un **upsert**.
+ */
+export interface ITotpSecretStore {
+    /** Secret TOTP de l'utilisateur, ou `null` si non enrôlé. */
+    findByUser(userId: string): Promise<ITotpSecret | null>;
+    /** Crée ou remplace le secret de l'utilisateur (upsert — ré-enrôlement). */
+    save(secret: ITotpSecret): Promise<void>;
+    /** Applique un patch partiel (confirmation, anti-rejeu, consommation de codes). */
+    update(userId: string, patch: TotpSecretUpdate): Promise<void>;
+    /** Supprime le secret de l'utilisateur (désactivation du 2FA). */
+    delete(userId: string): Promise<void>;
+    /**
+     * Page d'enrôlements 2FA pour le data plane admin — ne matérialise jamais
+     * plus d'une page, filtres appliqués au store, **secrets exclus** (cf
+     * {@link ITotpEnrollmentSummary}).
+     *
+     * Ordre contractuel : `createdAt` DESC, départagé par `userId` ASC.
+     */
+    listPage(query: ITotpListQuery): Promise<IPage<ITotpEnrollmentSummary>>;
+    /**
+     * Nombre d'enrôlements correspondant aux filtres (`COUNT` natif) — le KPI
+     * « couverture 2FA » sans énumérer.
+     */
+    countEnrollments(query: ITotpListQuery): Promise<number>;
+}
+export default ITotpSecretStore;

package/dist/types/nodefony/contracts/IWebAuthnCredential.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Enregistrement d'un **credential WebAuthn / passkey** côté serveur — le
+ * `credentialRecord` de WebAuthn L3 §7.1 (produit par la cérémonie
+ * d'enregistrement, relu et mis à jour à chaque authentification §7.2).
+ *
+ * Le serveur ne stocke QUE de la donnée publique : la clé privée ne quitte
+ * jamais l'authenticator (Touch ID, Windows Hello, clé FIDO…). Une fuite de ce
+ * store ne compromet aucun compte — une clé publique est inexploitable seule.
+ */
+export interface IWebAuthnCredential {
+    /** Identifiant du credential (base64url) — unique, fourni par l'authenticator. */
+    readonly id: string;
+    /** Identifiant de l'utilisateur propriétaire (sub / userHandle applicatif). */
+    readonly userId: string;
+    /** Clé publique **COSE** encodée base64url — vérifie la signature des assertions. */
+    readonly publicKey: string;
+    /**
+     * Compteur de signatures (WebAuthn §6.1.1) — anti-clone : SHOULD croître à
+     * chaque authentification. `0` = authenticator sans compteur (les passkeys
+     * synchronisées iCloud/Google le laissent souvent à 0, ce n'est pas une erreur).
+     */
+    signCount: number;
+    /** Transports annoncés (`usb` | `nfc` | `ble` | `internal` | `hybrid`). */
+    readonly transports: readonly string[];
+    /**
+     * BE flag (Backup Eligibility, §6.1.3) — credential multi-appareils
+     * (synchronisable). Fixé à l'enregistrement, ne change **jamais**.
+     */
+    readonly backupEligible: boolean;
+    /** BS flag (Backup State) — actuellement sauvegardé. Peut évoluer dans le temps. */
+    backupState: boolean;
+    /**
+     * La cérémonie a-t-elle réalisé une **vérification d'utilisateur** (biométrie/
+     * PIN) au moins une fois (`uvInitialized`, §7.2) — base du step-up MFA.
+     */
+    uvInitialized: boolean;
+    /**
+     * Surnom optionnel de la passkey (« MacBook de Chris »).
+     *
+     * ⚠️ **Emplacement réservé — rien ne l'écrit aujourd'hui.** Le champ est porté
+     * par ce contrat, par les trois stores (memory, drizzle, redis) et par la vue
+     * admin de Studio, mais **aucune API publique ne le renseigne** : ni endpoint,
+     * ni setter. En pratique il vaut donc toujours `undefined`, et l'écran retombe
+     * sur son libellé de repli (`Passkey ···1234`).
+     *
+     * Le garder coûte zéro (il traverse déjà toute la chaîne) ; le renseigner
+     * demande une décision produit — un endpoint de renommage, avec la question de
+     * qui a le droit de renommer la passkey de qui.
+     */
+    nickname?: string;
+    /** Création (epoch ms). */
+    readonly createdAt: number;
+    /** Dernière authentification réussie (epoch ms), ou `null` si jamais utilisé. */
+    lastUsedAt: number | null;
+}
+export default IWebAuthnCredential;

package/dist/types/nodefony/contracts/IWebAuthnCredentialStore.d.ts

@@ -0,0 +1,118 @@
+import type { IPage, IPageQuery } from "nodefony";
+import type { IWebAuthnCredential } from "./IWebAuthnCredential.js";
+/**
+ * Vue d'une passkey pour l'INTROSPECTION admin (« quels appareils portent des
+ * passkeys, lesquelles meurent avec leur appareil »).
+ *
+ * **Sans `publicKey`, par construction du contrat.** La clé publique n'est pas un
+ * secret — c'est sa nature d'être publique — mais elle n'a aucune valeur
+ * d'exploitation dans une console : c'est de la matière cryptographique brute que
+ * personne ne lit, et une projection minimale est plus facile à garder juste. Ce
+ * qui S'EXPLOITE est ici : `backupState` (une passkey non sauvegardée disparaît
+ * avec l'appareil → l'utilisateur se verrouille dehors) et `signCount` (le
+ * compteur anti-clone du §6.1.1).
+ */
+export interface IWebAuthnCredentialSummary {
+    /** Identifiant du credential (base64url) — la clé naturelle. */
+    readonly id: string;
+    /** Utilisateur propriétaire. */
+    readonly userId: string;
+    /** Canaux de l'authenticator (`internal`, `hybrid`, `usb`…). */
+    readonly transports: readonly string[];
+    /** Le credential PEUT être sauvegardé/synchronisé (BE flag). */
+    readonly backupEligible: boolean;
+    /** Le credential EST sauvegardé (BS flag) — sinon il meurt avec l'appareil. */
+    readonly backupState: boolean;
+    /** Une vérification utilisateur (biométrie/PIN) a déjà eu lieu. */
+    readonly uvInitialized: boolean;
+    /** Compteur de signatures (anti-clone WebAuthn §6.1.1). */
+    readonly signCount: number;
+    /** Nom donné à l'appareil par l'utilisateur, si renseigné. */
+    readonly nickname?: string;
+    /** Enrôlement (epoch ms). */
+    readonly createdAt: number;
+    /** Dernière authentification réussie (epoch ms), ou `null` = jamais servie. */
+    readonly lastUsedAt: number | null;
+}
+/**
+ * Requête de listing des passkeys — {@link IPageQuery} + les filtres qui ont un
+ * sens ici. `q` (hérité) = **préfixe** d'`userId`.
+ *
+ * ⚠️ À ne pas confondre avec {@link IWebAuthnCredentialStore.findByUser} : ce
+ * listing est le chemin FROID d'introspection admin ; `findByUser` est le chemin
+ * chaud du login, non paginé par nature.
+ */
+export interface IWebAuthnListQuery extends IPageQuery {
+    /** Restreindre à un porteur (sa liste d'appareils). */
+    userId?: string;
+    /**
+     * `true` = passkeys sauvegardées/synchronisées seulement, `false` = celles
+     * liées à un seul appareil (les porteurs à risque de verrouillage), omis = les deux.
+     */
+    backedUp?: boolean;
+}
+/** État mis à jour après une authentification réussie (WebAuthn §7.2). */
+export interface WebAuthnAuthUpdate {
+    /** Nouveau compteur de signatures (anti-clone). */
+    signCount: number;
+    /** Nouvel état de sauvegarde (BS flag). */
+    backupState: boolean;
+    /** UV réalisée durant cette cérémonie. */
+    uvInitialized: boolean;
+    /** Horodatage de l'usage (epoch ms). */
+    lastUsedAt: number;
+}
+/**
+ * Store **pluggable** des credentials WebAuthn — découple le cœur du backend de
+ * persistance (mémoire / ORM / Redis). Convention-frère d'`ITokenStore` :
+ * le builtin `memory` est sans dépendance, les adapters lourds s'enregistrent
+ * depuis leur propre module (inversion de dépendance).
+ */
+export interface IWebAuthnCredentialStore {
+    /** Credential par son id (base64url), ou `null` — résolution à l'authentification. */
+    findById(credentialId: string): Promise<IWebAuthnCredential | null>;
+    /**
+     * Tous les credentials d'un utilisateur — pour `allowCredentials`
+     * (authentification ciblée) et l'UX « mes appareils ».
+     *
+     * **Volontairement NON paginé** : `allowCredentials` doit être COMPLET ou il
+     * est faux — un authenticator dont la passkey manque de la liste ne peut pas
+     * répondre au défi, et le protocole WebAuthn n'offre aucun « page suivante »
+     * (le navigateur reçoit une liste unique et choisit). Ce qui borne cet appel
+     * est le plafond d'enrôlement (`passkeys.maxPerUser`), pas une pagination.
+     */
+    findByUser(userId: string): Promise<IWebAuthnCredential[]>;
+    /**
+     * Nombre de credentials d'un utilisateur — **natif** par backend (`COUNT`,
+     * `countDocuments`, `SCARD`), jamais un `findByUser().length`.
+     *
+     * Sert le plafond d'enrôlement (`passkeys.maxPerUser`) : le chemin
+     * d'enregistrement ne doit pas charger N credentials pour en compter le
+     * nombre, et le plafond est ce qui garantit que {@link findByUser} reste borné.
+     */
+    countByUser(userId: string): Promise<number>;
+    /** Persiste un nouveau credential (fin de la cérémonie d'enregistrement). */
+    save(credential: IWebAuthnCredential): Promise<void>;
+    /** Met à jour l'état post-authentification (compteur, sauvegarde, UV, usage). */
+    update(credentialId: string, patch: WebAuthnAuthUpdate): Promise<void>;
+    /** Révoque un credential (l'utilisateur retire un appareil). */
+    delete(credentialId: string): Promise<void>;
+    /**
+     * Page de passkeys pour le data plane admin — ne matérialise jamais plus d'une
+     * page, filtres appliqués au store, `publicKey` exclue (cf
+     * {@link IWebAuthnCredentialSummary}).
+     *
+     * Ordre contractuel (backends `offset`) : `createdAt` DESC, départagé par `id`
+     * ASC. Les backends **curseur** (Redis, dont l'index par utilisateur est un
+     * Set) n'ont pas d'ordre global : ils rendent des pages de taille variable et
+     * le client boucle sur `nextCursor` — capacité réduite déclarée, pas un défaut.
+     */
+    listPage(query: IWebAuthnListQuery): Promise<IPage<IWebAuthnCredentialSummary>>;
+    /**
+     * Nombre de passkeys correspondant aux filtres (`COUNT` natif), ou **`-1`** si
+     * le backend ne sait pas compter à coût raisonnable (Redis : un total exigerait
+     * un `SCAN` complet O(N) sur un chemin froid — refusé).
+     */
+    countCredentials(query: IWebAuthnListQuery): Promise<number>;
+}
+export default IWebAuthnCredentialStore;

package/dist/types/nodefony/contracts/IWebhookEndpoint.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Endpoint webhook sortant — une **destination** que Nodefony notifie quand un
+ * événement souscrit survient (modèle façon GitHub/Stripe).
+ *
+ * Le `secret` de signature est **chiffré au repos** (réversible, AES-256-GCM) :
+ * contrairement à une clé API (hachée, vérifiée seulement), le serveur doit le
+ * **relire** pour signer chaque livraison (HMAC). Le clair n'est jamais stocké,
+ * seulement {@link secretEnc} (blob opaque).
+ */
+export interface IWebhookEndpoint {
+    /** Identifiant public stable (`wh_<random>`). */
+    readonly id: string;
+    /** URL de destination (validée anti-SSRF à l'enregistrement). */
+    readonly url: string;
+    /** Secret de signature **chiffré** au repos (blob `gcm1.…`). Jamais en clair. */
+    readonly secretEnc: string;
+    /**
+     * Actions d'audit souscrites (ex. `"login.success"`, `"user.created"`).
+     * `"*"` = toutes. La livraison ne part que si l'action de l'événement matche.
+     */
+    readonly events: readonly string[];
+    /** Endpoint actif ? (désactivé = aucune livraison). */
+    readonly enabled: boolean;
+    /** Libellé humain optionnel (console admin). */
+    readonly description: string | null;
+    /** Slot multi-tenant (réservé P17) — `null` = global. */
+    readonly tenantId: string | null;
+    /** Identité de l'admin créateur (soft ref, traçabilité). */
+    readonly createdBy: string | null;
+    /** Création (epoch ms). */
+    readonly createdAt: number;
+    /** Dernière modification (epoch ms). */
+    readonly updatedAt: number;
+    /** Dernière tentative de livraison (epoch ms) ou `null`. */
+    readonly lastDeliveryAt: number | null;
+    /** Code HTTP de la dernière livraison, ou `null` (jamais livré / erreur réseau). */
+    readonly lastDeliveryStatus: number | null;
+    /** Message d'erreur de la dernière livraison, ou `null`. */
+    readonly lastDeliveryError: string | null;
+    /** Échecs consécutifs (auto-désactivation au-delà d'un seuil, façon GitHub). */
+    readonly failureCount: number;
+    /** Métadonnées extensibles (jamais de secret). */
+    readonly metadata: Record<string, unknown>;
+}
+/**
+ * Champs mutables d'un endpoint (PATCH). `id`/`createdAt`/`createdBy`/`tenantId`
+ * sont immuables après création.
+ */
+export type WebhookEndpointUpdate = Partial<Pick<IWebhookEndpoint, "url" | "secretEnc" | "events" | "enabled" | "description" | "updatedAt" | "lastDeliveryAt" | "lastDeliveryStatus" | "lastDeliveryError" | "failureCount" | "metadata">>;
+/**
+ * Vue **publique** d'un endpoint (DTO console admin) — **sans** le secret
+ * chiffré. Le secret en clair n'est renvoyé qu'une fois, à la création/rotation.
+ */
+export type WebhookEndpointSummary = Omit<IWebhookEndpoint, "secretEnc">;
+/**
+ * Trace d'une livraison (historique « récentes », façon GitHub/Stripe) — ce que
+ * Nodefony a **envoyé** à l'endpoint + la **réponse** observée. Stocké en RAM,
+ * borné, **par pod** (observabilité éphémère, non persistée). Aucun secret (le
+ * `webhook-signature` n'en révèle rien ; le corps signé est l'événement public).
+ */
+export interface IWebhookDelivery {
+    /** Horodatage de la tentative (epoch ms). */
+    readonly ts: number;
+    /** `webhook-id` du message livré. */
+    readonly messageId: string;
+    /** Type d'événement (= action d'audit, ex. `login.failure`). */
+    readonly type: string;
+    /** Numéro de tentative (0 = 1ʳᵉ ; > 0 = retry). */
+    readonly attempt: number;
+    /** Livraison acceptée (2xx) ? */
+    readonly ok: boolean;
+    /** Code HTTP, ou `null` (réseau/timeout/SSRF). */
+    readonly status: number | null;
+    /** Message d'erreur, ou `null` si OK. */
+    readonly error: string | null;
+    /** Durée de la tentative (ms). */
+    readonly durationMs: number;
+    /** Corps JSON envoyé (enveloppe `{id,timestamp,type,data}`), tronqué. */
+    readonly requestBody: string;
+    /** Début du corps de réponse du destinataire (tronqué), ou `null`. */
+    readonly responseBody: string | null;
+}

package/dist/types/nodefony/contracts/IWebhookStore.d.ts

@@ -0,0 +1,85 @@
+import type { IPage, IPageQuery, ISortableSource } from "nodefony";
+import type { IWebhookEndpoint, WebhookEndpointUpdate } from "./IWebhookEndpoint.js";
+/**
+ * Requête de **listing paginé** d'endpoints webhook (data plane admin) — le
+ * contrat de page standard du core ({@link IPageQuery}) enrichi des filtres
+ * propres aux endpoints.
+ *
+ * `q` (hérité) = sous-chaîne **insensible à la casse** cherchée dans `url` **ou**
+ * `description` — la question posée par un humain devant la console (« où part
+ * mon webhook stripe ? ») porte sur ces deux champs, jamais sur l'id.
+ */
+export interface IWebhookListQuery extends IPageQuery {
+    /** `true` = actifs seulement, `false` = désactivés seulement, omis = les deux. */
+    enabled?: boolean;
+    /**
+     * Ne garder que les endpoints **abonnés à cet événement** (appartenance au
+     * tableau `events`). Répond à la question d'exploitation « qui écoute
+     * `user.created` ? ». Non portable au `Criteria` générique (containment dans un
+     * tableau JSON) → chaque backend l'implémente nativement.
+     */
+    event?: string;
+    /**
+     * `true` = seulement les endpoints **en échec** (au moins un échec consécutif
+     * courant, `failureCount > 0`), `false` = seulement ceux qui vont bien, omis =
+     * les deux.
+     *
+     * Au contrat plutôt que déduit d'un `order` : c'est la question d'exploitation
+     * la plus fréquente — « qu'est-ce qui casse ? » — et la carte qui l'affiche
+     * doit pouvoir être cliquée pour filtrer le tableau sur la même population.
+     * Portable partout (comparaison sur une colonne entière indexable).
+     */
+    failing?: boolean;
+}
+/**
+ * Persistance des **endpoints webhook** (configuration durable, pas un cache).
+ * Backend interchangeable (Memory dev/test · Drizzle SQL · Mongoose) via le
+ * registre {@link ../src/webhook/webhookStoreRegistry}. **Redis n'est PAS un
+ * store d'endpoints** (config durable ≠ éphémère) — il servira la *queue de
+ * livraison* cross-pod (slice cluster), pas ce contrat.
+ *
+ * Volume attendu : faible (dizaines d'endpoints), lecture fréquente par le
+ * dispatcher (qui en garde un snapshot mémoire), écriture rare (CRUD admin).
+ */
+export interface IWebhookStore extends ISortableSource {
+    /** Insère un nouvel endpoint. */
+    save(endpoint: IWebhookEndpoint): Promise<void>;
+    /** Charge un endpoint par id, ou `null`. */
+    findById(id: string): Promise<IWebhookEndpoint | null>;
+    /** Applique un patch partiel (champs mutables) ; no-op si id absent. */
+    update(id: string, patch: WebhookEndpointUpdate): Promise<void>;
+    /** Supprime un endpoint ; no-op si id absent. */
+    delete(id: string): Promise<void>;
+    /**
+     * **Tous** les endpoints — réservé au **snapshot du dispatcher** (le service
+     * garde en mémoire la table complète des abonnements pour router un événement
+     * sans I/O, et la recharge au boot puis après chaque écriture CRUD).
+     *
+     * ⚠️ Énumération complète assumée **par conception** ici : le dispatcher doit
+     * connaître TOUS les abonnements pour ne pas rater une livraison. C'est un
+     * cold-path (boot + CRUD admin), jamais une requête d'affichage. Pour lister
+     * dans une console, utiliser {@link IWebhookStore.listPage}.
+     */
+    listAll(): Promise<IWebhookEndpoint[]>;
+    /**
+     * Liste **paginée** d'endpoints pour le data plane admin — ne matérialise
+     * jamais plus d'une page, filtres {@link IWebhookListQuery} appliqués **au
+     * store** (jamais après un chargement complet).
+     *
+     * Ordre par défaut : `createdAt` DESC (le plus récent d'abord), départagé par
+     * `id` ASC — sans ce tiebreaker deux endpoints créés dans la même milliseconde
+     * pourraient changer de page entre deux appels et l'un d'eux ne jamais
+     * apparaître. Un `order` explicite le remplace, dans la limite de
+     * {@link IWebhookStore.sortableFields} ; il s'applique **avant** le découpage
+     * en pages, jamais sur la tranche déjà extraite.
+     */
+    listPage(query: IWebhookListQuery): Promise<IPage<IWebhookEndpoint>>;
+    /**
+     * Nombre d'endpoints correspondant aux filtres (`COUNT` natif) — base du
+     * `total` d'une page et des compteurs de la console.
+     *
+     * @returns le compte exact ; `-1` si le backend ne sait pas compter à coût
+     *   raisonnable (« je ne sais pas » explicite, jamais un total inventé).
+     */
+    countEndpoints(query: IWebhookListQuery): Promise<number>;
+}

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

@@ -0,0 +1,9 @@
+export type { IToken } from "./IToken.js";
+export type { IAuthenticator } from "./IAuthenticator.js";
+export type { ISecuredArea } from "./ISecuredArea.js";
+export type { IFirewall } from "./IFirewall.js";
+export type { IAccessVoter } from "./IAccessVoter.js";
+export type { IAuthorizationService } from "./IAuthorizationService.js";
+export { VoterVote } from "./IAccessVoter.js";
+export type { IAccessTokenRecord, ITokenStore, ITokenListQuery, ITokenUsage, IResourcePermission, TokenRevokeReason, TokenStatus, } from "./ITokenStore.js";
+export type { IJwtKeystore, IJwtSigningKey } from "./IJwtKeystore.js";

package/dist/types/nodefony/errors/AccessDeniedError.d.ts

@@ -0,0 +1,10 @@
+import { nodefonyError } from "nodefony";
+/**
+ * Accès refusé — `code = 403`. Levée par l'autorisation (un `@IsGranted` non
+ * satisfait, un voter DENY) : l'utilisateur EST authentifié mais n'a pas le droit.
+ * À distinguer d'{@link AuthenticationError} (401 = pas authentifié).
+ */
+export declare class AccessDeniedError extends nodefonyError {
+    constructor(message?: string | Error);
+}
+export default AccessDeniedError;

package/dist/types/nodefony/errors/ApiKeyError.d.ts

@@ -0,0 +1,17 @@
+import { nodefonyError } from "nodefony";
+/**
+ * Erreur de **gestion** d'une clé API (création/révocation) — porte un `code`
+ * HTTP que l'adaptateur framework mappe par duck-typing (il n'importe jamais les
+ * classes de `@nodefony/security`).
+ *
+ *  - `400` — entrée invalide (nom vide, scope hors catalogue) ;
+ *  - `409` — plafond `apiKeys.maxPerSubject` atteint ;
+ *  - `503` — store de jetons indisponible (clés activées mais non provisionnées).
+ *
+ * Distincte de l'**authentification** d'une clé présentée (→ `AuthenticationError`
+ * 401, message uniforme anti-énumération).
+ */
+export declare class ApiKeyError extends nodefonyError {
+    constructor(message: string, code: 400 | 409 | 503);
+}
+export default ApiKeyError;

package/dist/types/nodefony/errors/AuthenticationError.d.ts

@@ -0,0 +1,10 @@
+import { nodefonyError } from "nodefony";
+/**
+ * Échec d'authentification — `code = 401`. Levée par un {@link IAuthenticator}
+ * quand le credential est absent/invalide, ou par le firewall en Zero Trust
+ * (zone protégée + visiteur anonyme + route sans `@Anonymous`).
+ */
+export declare class AuthenticationError extends nodefonyError {
+    constructor(message?: string | Error);
+}
+export default AuthenticationError;

package/dist/types/nodefony/errors/CsrfError.d.ts

@@ -0,0 +1,19 @@
+import { nodefonyError } from "nodefony";
+/**
+ * Mutation cross-site bloquée — `code = 403` (RFC 9110 §15.5.4 : le serveur a
+ * compris la requête mais refuse de l'honorer).
+ *
+ * Levée par {@link Csrf} sur une méthode state-changing (POST/PUT/PATCH/DELETE)
+ * dont la provenance est tierce : `Sec-Fetch-Site: cross-site` (défense primaire
+ * Fetch Metadata, W3C — infalsifiable par un script attaquant) ou, à défaut de
+ * Fetch Metadata, un `Origin`/`Referer` étranger aux origines de l'app (fallback).
+ *
+ * Le message reste GÉNÉRIQUE : la politique CSRF (en-têtes inspectés, whitelist)
+ * ne fuite jamais au client. Distincte du 401 (qui es-tu ?) et de l'AccessDenied
+ * (autorisé mais rôle insuffisant) : ici l'identité importe peu, c'est la
+ * PROVENANCE de la requête qui est rejetée.
+ */
+export declare class CsrfError extends nodefonyError {
+    constructor(message?: string | Error);
+}
+export default CsrfError;

package/dist/types/nodefony/errors/InvalidTargetError.d.ts

@@ -0,0 +1,34 @@
+import { nodefonyError } from "nodefony";
+/**
+ * La ressource demandée à l'émission ne peut pas être servie — `code = 400`,
+ * code d'erreur OAuth `invalid_target` (RFC 8707 §2).
+ *
+ * Le paramètre `resource` dit POUR QUI le jeton est demandé. Trois raisons de
+ * refuser, et la RFC les couvre d'un seul code : « The requested resource is
+ * invalid, missing, unknown, or malformed. »
+ *
+ * **Pourquoi refuser plutôt qu'ignorer.** Un `resource` accepté puis jeté rend
+ * un jeton parfaitement valide… pour quelqu'un d'autre. Le client croit tenir
+ * une clé pour la porte A, la présente, reçoit un `401`, et n'a aucun moyen de
+ * comprendre que sa demande n'a jamais été honorée : l'erreur se manifeste chez
+ * la ressource, loin de l'endroit où elle a été commise. Refuser à l'émission
+ * met le diagnostic là où la faute est.
+ *
+ * **Le message est constant** et ne nomme pas les audiences acceptées : les
+ * énumérer offrirait la carte des ressources protégées de l'application à qui
+ * possède un simple identifiant. La valeur refusée, elle, vient du client — la
+ * lui rendre ne lui apprend rien.
+ */
+export declare class InvalidTargetError extends nodefonyError {
+    /** Code d'erreur OAuth à rendre au client (RFC 6749 §5.2 / RFC 8707 §2). */
+    readonly oauthError = "invalid_target";
+    /** Ce que le client a demandé, tel qu'il l'a écrit — pour le journal. */
+    readonly requested?: string;
+    /**
+     * @param description - raison, destinée à `error_description` (aucune fuite :
+     *          elle qualifie la DEMANDE, jamais la configuration du serveur)
+     * @param requested - la valeur refusée, pour le journal
+     */
+    constructor(description: string, requested?: string);
+}
+export default InvalidTargetError;

package/dist/types/nodefony/errors/SsrfError.d.ts

@@ -0,0 +1,13 @@
+import { nodefonyError } from "nodefony";
+/**
+ * URL rejetée par la protection SSRF — `code = 422`. Levée quand une URL sortante
+ * (endpoint webhook, fetch applicatif…) est syntaxiquement valide mais cible une
+ * ressource **interdite** : protocole non autorisé, identifiants embarqués, hôte
+ * non résolvable, ou IP non publique (loopback, privée, link-local, métadonnées
+ * cloud `169.254.169.254`…). Sémantique alignée sur GitHub (422 à l'enregistrement
+ * d'un webhook invalide).
+ */
+export declare class SsrfError extends nodefonyError {
+    constructor(message?: string | Error);
+}
+export default SsrfError;

package/dist/types/nodefony/errors/ThrottledError.d.ts

@@ -0,0 +1,16 @@
+import { nodefonyError } from "nodefony";
+/**
+ * Tentatives de login trop rapprochées — `code = 429` (RFC 6585 §4).
+ *
+ * Levée par `UserPasswordAuthenticator` quand le backoff progressif
+ * ({@link LoginThrottler}) bloque encore l'identifiant saisi. Distincte du 401 :
+ * un client légitime doit savoir QU'ATTENDRE (header `Retry-After`, posé par le
+ * firewall), pas re-soumettre en boucle. Le message reste générique — la
+ * politique de throttle (seuils, compteurs) n'est jamais détaillée au client.
+ */
+export declare class ThrottledError extends nodefonyError {
+    /** Secondes restantes avant la prochaine tentative autorisée (header `Retry-After`). */
+    readonly retryAfterS: number;
+    constructor(retryAfterS: number);
+}
+export default ThrottledError;

package/dist/types/nodefony/errors/UnverifiableTokenError.d.ts

@@ -0,0 +1,37 @@
+import { nodefonyError } from "nodefony";
+/**
+ * Le jeton n'a pas pu être VÉRIFIÉ — `code = 503`, et surtout **pas 401**.
+ *
+ * Levée quand ce qui sait valider un jeton est absent ou en panne : aucun
+ * vérificateur posé au conteneur, émetteur injoignable, jeu de clés
+ * inutilisable. Le jeton n'est alors ni valide ni invalide — on n'en sait
+ * rien, et c'est une information différente.
+ *
+ * **Pourquoi une erreur distincte.** Répondre 401 à une panne envoie le client
+ * chercher un autre jeton, qui échouera pareil : la boucle de renouvellement
+ * remplace la panne par une tempête de requêtes, pendant que le tableau de bord
+ * affiche une hausse d'« échecs d'authentification » qui ne désigne aucun
+ * coupable. Le 503 dit la vérité — le service ne peut pas répondre — et le
+ * client légitime attend au lieu d'insister.
+ *
+ * C'est la même distinction que celle tenue par le vérificateur lui-même, où
+ * un refus rend `null` et une panne lève : la porte doit la conserver jusqu'à
+ * la réponse, sinon elle est perdue là où elle sert.
+ *
+ * Le message est **constant**, et c'est structurel : il est rendu au client. La
+ * cause technique — nom de l'émetteur défaillant, URL du jeu de clés, erreur
+ * réseau — vit dans {@link detail}, que seul le journal lit. Composer la cause
+ * dans le message revient à publier la topologie interne de l'authentification
+ * à qui présente un jeton quelconque, et le rendu d'erreur de développement y
+ * ajoute la pile d'appels par-dessus.
+ */
+export declare class UnverifiableTokenError extends nodefonyError {
+    /** Cause technique, destinée au JOURNAL — jamais au client. */
+    readonly detail?: string;
+    /**
+     * @param detail - cause technique pour le journal ; n'apparaît jamais dans le
+     *          message rendu au client
+     */
+    constructor(detail?: string);
+}
+export default UnverifiableTokenError;