@nodefony/security 10.0.0-alpha.1

package/dist/types/nodefony/src/net/ssrfGuard.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Indique si une IP (littérale) est **non publique** (donc interdite comme cible
+ * sortante). Une IP syntaxiquement invalide est considérée bloquée (fail-closed).
+ *
+ * `node:net` `BlockList` rabat **nativement** les IPv6 **IPv4-mapped** — toutes
+ * notations confondues (`::ffff:127.0.0.1`, `::ffff:7f00:1`,
+ * `0:0:0:0:0:ffff:127.0.0.1`…) — sur les règles IPv4 : `::ffff:169.254.169.254`
+ * est bloqué sans traitement spécial (vérifié red-team `webhookSsrf.attack`).
+ * ⚠️ NE PAS ajouter `::ffff:0:0/96` à la liste : Node ferait alors matcher TOUTE
+ * adresse IPv4 (faux positif massif → 100 % des webhooks rejetés).
+ *
+ * @param ip - adresse IPv4 ou IPv6 (sans crochets).
+ */
+export declare function isBlockedAddress(ip: string): boolean;
+/** Résolveur DNS injectable (testabilité) — renvoie toutes les IP d'un hôte. */
+export type DnsResolver = (hostname: string) => Promise<string[]>;
+/** Options de validation d'une URL sortante. */
+export interface IAssertPublicUrlOptions {
+    /** Autorise les cibles non publiques (dev/test only). Défaut : `false`. */
+    readonly allowPrivate?: boolean;
+    /** Autorise `http:` en plus de `https:`. Défaut : `false` (https only). */
+    readonly allowHttp?: boolean;
+    /** Résolveur DNS (injectable pour les tests). Défaut : `node:dns`. */
+    readonly resolver?: DnsResolver;
+}
+/** Résultat d'une validation SSRF réussie. */
+export interface IPublicUrlResult {
+    /** URL validée (normalisée). */
+    readonly url: URL;
+    /** IP résolues, toutes publiques — à **pinner** à la connexion. */
+    readonly addresses: string[];
+}
+/**
+ * Valide qu'une URL sortante est sûre (anti-SSRF) : protocole autorisé, pas
+ * d'identifiants embarqués, hôte résolvable, et **toutes** les IP résolues
+ * publiques. Lève {@link SsrfError} (422) sinon.
+ *
+ * @param rawUrl - URL brute à valider.
+ * @param options - politique (https-only, deny private, résolveur).
+ * @returns l'URL normalisée + les IP résolues (pour pinning à la connexion).
+ * @throws SsrfError si l'URL est malformée ou cible une ressource interdite.
+ */
+export declare function assertPublicUrl(rawUrl: string, options?: IAssertPublicUrlOptions): Promise<IPublicUrlResult>;

package/dist/types/nodefony/src/oauth/oauthProviderRegistry.d.ts

@@ -0,0 +1,45 @@
+import type * as Arctic from "arctic";
+import type { IOAuthProvider } from "../../contracts/IOAuthProvider.js";
+/**
+ * Registre de **fabriques de fournisseurs OAuth** — résout un nom configuré
+ * (`oauth2.providers.<name>`) vers un {@link IOAuthProvider}, SANS coupler le
+ * cœur à un fournisseur en dur.
+ *
+ * Convention-frère : `tokenStoreRegistry`, `authenticatorRegistry`,
+ * `webAuthnCredentialStoreRegistry`. Les builtins (`google`, `github`) couvrent
+ * les deux archétypes (OIDC+PKCE / OAuth simple) ; une application enregistre les
+ * ~50 autres fournisseurs `arctic` (Microsoft, Apple, Discord...) ou un
+ * fournisseur maison via {@link registerOAuthProvider}, sans éditer le core.
+ *
+ * @remarks `arctic` n'est ici qu'un **type** : l'instance runtime, chargée
+ * paresseusement par `OAuth2Service` au premier login, est passée à la fabrique
+ * via {@link IOAuthProviderContext.arctic} — zéro import runtime statique.
+ */
+/** Contexte de construction d'un fournisseur (lib arctic chargée + secrets de config). */
+export interface IOAuthProviderContext {
+    /** Module `arctic` chargé paresseusement (les classes de fournisseurs). */
+    readonly arctic: typeof Arctic;
+    /** Identifiant client (config, issu de l'env de l'app). */
+    readonly clientId: string;
+    /** Secret client (config) — jamais loggé. */
+    readonly clientSecret: string;
+    /** URL de callback exacte (RFC 9700). */
+    readonly redirectUri: string;
+    /**
+     * Émetteur/realm des fournisseurs OIDC self-hosted (Keycloak : URL du realm,
+     * ex. `https://kc.example/realms/app`) — `undefined` pour les fournisseurs à
+     * endpoints fixes (Google, GitHub).
+     */
+    readonly issuer?: string;
+}
+/** Fabrique d'un fournisseur OAuth pour un nom donné. */
+export type OAuthProviderFactory = (ctx: IOAuthProviderContext) => IOAuthProvider;
+/**
+ * Enregistre (ou remplace) la fabrique d'un fournisseur OAuth. Appelée par les
+ * builtins au chargement, et par une application pour ses fournisseurs.
+ */
+export declare function registerOAuthProvider(name: string, factory: OAuthProviderFactory): void;
+/** Fabrique d'un fournisseur par nom, ou `undefined` si inconnu. */
+export declare function getOAuthProviderFactory(name: string): OAuthProviderFactory | undefined;
+/** Noms enregistrés (validation boot, introspection Studio, tests). */
+export declare function listOAuthProviders(): string[];

package/dist/types/nodefony/src/oauth/providers/github.d.ts

@@ -0,0 +1,9 @@
+import type { IOAuthProvider } from "../../../contracts/IOAuthProvider.js";
+import type { IOAuthProviderContext } from "../oauthProviderRegistry.js";
+/**
+ * Fournisseur **GitHub** (OAuth 2.0 simple, NON-OIDC). Pas de PKCE, pas d'ID
+ * token : le profil est lu via l'API REST (`/user`), et l'email — souvent privé —
+ * via `/user/emails` (scope `user:email`). GitHub n'émet pas de paramètre `iss`
+ * (`expectedIssuer = null`) : la défense anti-CSRF repose sur le `state`.
+ */
+export declare function createGithubProvider(ctx: IOAuthProviderContext): IOAuthProvider;

package/dist/types/nodefony/src/oauth/providers/oidc.d.ts

@@ -0,0 +1,35 @@
+import type { OAuth2Tokens } from "arctic";
+import type { IOAuthProvider } from "../../../contracts/IOAuthProvider.js";
+/**
+ * Client `arctic` minimal d'un fournisseur **OIDC avec PKCE** — surface
+ * structurelle commune à `Google`, `MicrosoftEntraId`, `Auth0`, `Okta`,
+ * `KeyCloak`... (une instance arctic de ces classes est assignable telle quelle).
+ */
+export interface IOidcPkceClient {
+    createAuthorizationURL(state: string, codeVerifier: string, scopes: string[]): URL;
+    validateAuthorizationCode(code: string, codeVerifier: string): Promise<OAuth2Tokens>;
+}
+/** Paramètres d'un fournisseur OIDC générique. */
+export interface IOidcProviderOptions {
+    /** Nom du fournisseur (`"google"`, `"microsoft"`...) — porté dans le profil. */
+    readonly name: string;
+    /** Instance `arctic` (déjà construite avec les secrets). */
+    readonly client: IOidcPkceClient;
+    /** Émetteur attendu (claim `iss`, anti-mix-up RFC 9207). */
+    readonly issuer: string;
+    /** `arctic.decodeIdToken` (injecté — arctic est chargé paresseusement). */
+    readonly decodeIdToken: (idToken: string) => object;
+    /** Scopes par défaut si la config n'en précise aucun. */
+    readonly defaultScopes?: string[];
+}
+/**
+ * Fabrique un {@link IOAuthProvider} **générique OIDC** — couvre TOUT fournisseur
+ * OpenID Connect sans code spécifique : le profil se lit toujours pareil (claims
+ * standard `sub`/`email`/`email_verified`/`name` de l'ID token). Ajouter un
+ * fournisseur OIDC = une entrée de quelques lignes (nom + classe arctic + issuer),
+ * pas un fichier.
+ *
+ * PKCE S256 systématique (RFC 7636) ; le profil vient de l'ID token signé obtenu
+ * du token endpoint via TLS (décodage suffisant en code flow, RFC 8725).
+ */
+export declare function createOidcProvider(opts: IOidcProviderOptions): IOAuthProvider;

package/dist/types/nodefony/src/realtime/UserRealtimeToken.d.ts

@@ -0,0 +1,62 @@
+import type { IUser } from "@nodefony/user";
+import type { IRealtimeToken } from "./realtimeContracts.js";
+/**
+ * Adaptateur `IUser` → `IRealtimeToken` (jeton realtime).
+ *
+ * Construit UNIQUEMENT pour un utilisateur **authentifié** (le
+ * {@link FirewallRealtimeAuthenticator} ne l'instancie qu'après avoir vérifié
+ * l'identité résolue par le firewall) → `isAuthenticated()` est toujours `true`.
+ * Un visiteur non authentifié reste sur `ANONYMOUS_REALTIME_TOKEN` (posé par le
+ * hub realtime), jamais ici.
+ *
+ * Les rôles ET les scopes sont des **copies** (pas de fuite de la structure
+ * interne de l'utilisateur ni du jeton d'origine). Les deux axes voyagent :
+ * les rôles disent qui l'on est, les scopes ce qu'une clé déléguée a le droit
+ * de faire — et un agent qui perd ses scopes en passant sur la socket perd la
+ * garantie même du mode machine.
+ */
+export declare class UserRealtimeToken implements IRealtimeToken {
+    #private;
+    /**
+     * Mode d'authentification RÉEL de l'identité (`session`, `jwt`, `apikey`…),
+     * repris du jeton que le firewall a posé dans l'ALS.
+     *
+     * Il était jadis figé à `"session"`, ce qui faisait passer un agent authentifié
+     * par JWT pour un utilisateur à cookie — un mensonge sur l'identité, et la
+     * racine du bug qui révoquait les sockets machine à machine.
+     */
+    readonly type: string;
+    /**
+     * @param user - identité authentifiée résolue par le firewall.
+     * @param revalidate - preuve de vie de l'identité, adaptée à son mode.
+     * @param type - mode d'authentification réel (défaut `"session"`).
+     * @param scopes - scopes délégués du jeton d'origine (défaut aucun).
+     */
+    constructor(user: IUser, revalidate?: ((nowMs?: number) => Promise<boolean>) | null, type?: string, scopes?: readonly string[]);
+    /**
+     * Zero Trust : l'identité qui a ouvert cette socket est-elle TOUJOURS vivante ?
+     *
+     * Selon le mode : une session BFF encore ouverte et toujours celle de ce compte
+     * (détecte la déconnexion et le changement de compte sur navigateur partagé),
+     * ou un jeton porteur non expiré et non révoqué. `true` si aucune re-validation
+     * n'a pu être câblée (best-effort, jamais un faux refus).
+     *
+     * @param nowMs - horloge injectable (epoch ms) ; par défaut l'heure courante.
+     *   Sert aux bornes temporelles d'un jeton, et rend le comportement testable
+     *   sans dépendre de l'horloge de la machine.
+     */
+    isValid(nowMs?: number): Promise<boolean>;
+    getUserIdentifier(): string;
+    isAuthenticated(): boolean;
+    getRoles(): string[];
+    /**
+     * Scopes délégués — copie défensive.
+     *
+     * ⚠️ Ils doivent être RÉELS : `ScopeVoter` ne consulte cette liste que pour un
+     * jeton machine. Une liste vide sur un jeton `jwt`/`apikey` ne veut pas dire
+     * « tous les droits », elle veut dire « aucun scope » — donc refus.
+     */
+    getScopes(): string[];
+    getAttribute<T = unknown>(key: string): T | undefined;
+}
+export default UserRealtimeToken;

package/dist/types/nodefony/src/realtime/frameAuthorizer.d.ts

@@ -0,0 +1,171 @@
+import type { FrameAuthorizer, IChannelPolicy, IRealtimeToken } from "./realtimeContracts.js";
+/**
+ * Surface MINIMALE du firewall consommée par le verrou de frame : matcher une
+ * zone par pathname ET vérifier un rôle (hiérarchie comprise). `Firewall` la
+ * satisfait structurellement (`matchPath` + `hasRole` délégué au
+ * `RoleHierarchyWalker`) — typage local pour éviter un cycle d'import
+ * `firewall.ts` ↔ `frameAuthorizer.ts`.
+ */
+export interface IFrameAuthorizerFirewall {
+    matchPath(pathname: string, host?: string): {
+        readonly security: boolean;
+    } | null;
+    /** `true` si l'un des rôles de l'utilisateur couvre `required` (via hiérarchie). */
+    hasRole(userRoles: readonly string[], required: string): boolean;
+}
+/**
+ * Source des politiques de canal DÉCLARÉES côté métier (`@RealtimeChannel`) —
+ * miroir partiel du `realtimeService`. `resolveChannelPolicy` est optionnel : un
+ * hub d'une version antérieure ne l'expose pas (traité comme « pas de politique
+ * métier »).
+ */
+export interface IChannelPolicyResolver {
+    resolveChannelPolicy?(channel: string): IChannelPolicy | null;
+}
+/**
+ * Règle de canal **système** (plateforme) — un préfixe de namespace réservé et
+ * la politique qui s'y applique. Plancher NON contournable par une déclaration
+ * métier (un controller user ne doit pas exposer `syslog:`). Surchargeable par
+ * la config (`defineSecurityConfig().realtimeChannels`).
+ */
+export interface ISystemChannelRule {
+    readonly prefix: string;
+    readonly policy: IChannelPolicy;
+}
+/**
+ * Rapporteur de refus de frame (journal d'audit P6.14) — invoqué UNIQUEMENT
+ * quand le verrou refuse une frame (cold-path : frames refusées rares). Le
+ * chemin autorisé (`return true`) ne l'appelle JAMAIS → 0 allocation sur le
+ * hot-path WS. Le firewall fournit l'implémentation (closure sur son container) ;
+ * absent par défaut (verrou pur, testable sans audit).
+ *
+ * @param surface - cible refusée : pont API souverain (`api.request`) ou canal
+ *   (subscribe/inbound).
+ * @param target  - pathname (api.request) ou nom de canal refusé.
+ * @param reason  - raison machine stable (`zone_protected` | `channel_policy`).
+ * @param token   - jeton WS de l'acteur (lu pour `getUserIdentifier()`).
+ */
+export type FrameDenyReporter = (surface: "api.request" | "channel", target: string, reason: string, token: IRealtimeToken) => void;
+/**
+ * Politique système par défaut des canaux d'**introspection serveur** : réservés
+ * aux administrateurs. DURCISSEMENT Zero Trust (P6) : avant, « authentifié
+ * suffisait » (tout `ROLE_USER` lisait `nodefony:syslog`) ; désormais `ROLE_ADMIN`.
+ * Surchargeable finement par `realtimeChannels` (ex. `ROLE_SECURITY_AUDITOR`).
+ */
+export declare const SYSTEM_CHANNEL_POLICY: IChannelPolicy;
+/**
+ * Namespace d'introspection serveur (observabilité) — s'y abonner expose l'état
+ * interne du pod : journaux (`nodefony:syslog`), base (`nodefony:orm:*`), métriques
+ * et supervision (`nodefony:dashboard`, `nodefony:supervision@<pid>`), sonde de la
+ * socket (`nodefony:socket`), contrôle du pod (`nodefony:kernel:gc` force un GC
+ * bloquant). Liste extensible via la config. Convention transverse Nodefony :
+ * `<module>:health` / `<module>:stats` (gérée à part dans {@link matchSystemPolicy}).
+ *
+ * ⚠️ Couplage ASSUMÉ : security connaît le namespace système de la plateforme
+ * (c'est son rôle de définir la politique) — mais il ne le REDÉCLARE pas : la
+ * constante vient du cœur, comme côté hub.
+ */
+export declare const DEFAULT_SYSTEM_PREFIXES: readonly ["nodefony:"];
+/**
+ * Plancher des canaux de **sécurité** (`nodefony:audit`, P6.14 lot 4) : réservé au
+ * super-admin Nodefony (`ROLE_NODEFONY_ADMIN`) — un cran AU-DESSUS du plancher
+ * d'observabilité générique (`ROLE_ADMIN`). Le journal d'audit du pod ne se lit
+ * pas avec un simple rôle admin applicatif. Cohérent avec le data plane HTTP de
+ * l'audit (`SecurityAdminApi`, lot 3, même rôle).
+ *
+ * Multi-tenant (futur) : `nodefony:audit` reste un canal **plateforme** (pod),
+ * jamais exposé à un user tenant ; l'événement portera le `tenantId` (via l'ALS)
+ * pour permettre un filtrage par tenant quand le chantier multi-tenant arrivera.
+ */
+export declare const SECURITY_CHANNEL_POLICY: IChannelPolicy;
+/**
+ * Politique du canal **MONTANT** des journaux du navigateur
+ * ({@link PLATFORM_INBOUND.syslogUplink}) : authentifié, sans rôle particulier.
+ *
+ * Pourquoi il échappe à {@link SYSTEM_CHANNEL_POLICY} alors qu'il porte la même marque :
+ * ce plancher-là protège la **lecture** de l'état interne du pod — s'abonner à
+ * `nodefony:syslog` fait sortir les journaux du serveur. Le canal montant ne rend rien ;
+ * il ACCEPTE. Lui demander `ROLE_ADMIN` ne le rendrait pas plus sûr, cela le rendrait
+ * inutile : on ne recueillerait que les erreurs survenues chez les administrateurs, quand
+ * tout l'intérêt est de voir celles que subissent les utilisateurs.
+ *
+ * Les dangers propres à une surface d'écriture — noyer le journal, y fabriquer des
+ * pistes — se traitent là où ils se posent : origine forcée par le serveur, débit et
+ * taille bornés par connexion, sévérité plafonnée (`createSyslogUplinkHandler`).
+ *
+ * Le plancher irréductible reste respecté, et non contourné : `authenticated` est exigé,
+ * donc une connexion ANONYME ne pousse rien. Limite assumée, à connaître avant de
+ * chercher un journal qui n'existe pas : **les erreurs d'un visiteur non connecté ne
+ * remontent pas** — celles de la page de connexion, notamment.
+ */
+export declare const UPLINK_CHANNEL_POLICY: IChannelPolicy;
+/**
+ * F2 (revue 0.6) — PLANCHER IRRÉDUCTIBLE du namespace réservé plateforme. Il
+ * couvre tout ce qui expose l'état interne du pod (logs, audit, métriques,
+ * requêtes, supervision) : une règle de config `realtimeChannels` (placée AVANT
+ * les défauts, 1ᵉʳ match gagne) pourrait sinon l'OUVRIR à l'anonyme
+ * (`{ authenticated:false }` ou policy vide). Le plancher garantit qu'un canal de
+ * ce namespace exige TOUJOURS au moins `authenticated` — la config peut RESSERRER
+ * (rôle/scope) ou re-cibler le rôle, jamais DESCENDRE sous authenticated. Le canal
+ * d'audit en fait partie (son défaut ROLE_NODEFONY_ADMIN est déjà au-dessus, mais
+ * le plancher le blinde contre une surcharge de config). Défense structurelle,
+ * fail-closed (cf F1 fail-loud).
+ */
+export declare const RESERVED_FLOOR_PREFIXES: readonly ["nodefony:"];
+/**
+ * Règles système par défaut. Le canal d'audit est placé EN TÊTE (1ᵉʳ match gagne)
+ * avec son plancher super-admin propre ; le reste du namespace plateforme hérite de
+ * {@link SYSTEM_CHANNEL_POLICY}. Le firewall y préfixe les règles issues de la
+ * config (qui gagnent par ordre).
+ */
+export declare const DEFAULT_SYSTEM_RULES: readonly ISystemChannelRule[];
+/**
+ * Construit les règles système à partir d'une liste de namespaces réservés.
+ *
+ * Sépare la LISTE (quels namespaces sont réservés — propriété du hub realtime,
+ * qui sert ces canaux) de la POLITIQUE (quels droits — propriété de la sécurité).
+ * Le firewall appelle donc cette fabrique avec la liste que le hub lui donne, et
+ * ne redéclare rien : un namespace ajouté côté realtime hérite automatiquement
+ * d'une politique, au lieu de rester ouvert sans que personne ne le remarque.
+ *
+ * Le canal d'audit est placé EN TÊTE (premier match gagnant) : son plancher est
+ * plus haut que celui du reste de l'observabilité. Il n'est pas un namespace mais
+ * un canal précis — sa règle n'est donc posée que si la liste reçue le COUVRE : si
+ * le hub cessait un jour de réserver ce territoire, la sécurité cesserait avec lui
+ * de prétendre l'arbitrer, au lieu de garder une règle orpheline.
+ *
+ * @param prefixes - namespaces réservés (ordre indifférent).
+ * @returns les règles, canal d'audit d'abord.
+ */
+export declare function buildSystemRules(prefixes: readonly string[]): readonly ISystemChannelRule[];
+/**
+ * Construit le verrou de frame WS branché sur le hub realtime par le firewall au
+ * boot (`RealtimeService.setFrameAuthorizer`). SYNC, 0 lecture base : lit le
+ * token déjà résolu au handshake et matche la cible de la frame contre la zone
+ * (api.request) ou la politique du canal (subscribe/inbound).
+ *
+ * Trois surfaces gardées :
+ *  - `api.request {path}` (pont API souverain) : re-match de zone HTTP → zone
+ *    protégée + anonyme = refus (autorisation de ZONE, identique à `GET {path}` ;
+ *    la méthode/action est gardée en aval par le router + `@IsGranted`).
+ *  - `subscribe {channel}` : politique de canal (système plancher + déclaration
+ *    métier `@RealtimeChannel` → rôles/scopes).
+ *  - inbound (`method` = canal full-duplex déclaré avec policy) : même politique
+ *    que `subscribe` — un client ne pousse pas sur un canal protégé sans droit.
+ *
+ * Toute autre frame (`ping`, `unsubscribe`, action explicitement ouverte) passe — le verrou
+ * cible les surfaces qui atteignent le data plane / l'observabilité / un canal
+ * protégé.
+ *
+ * @param firewall    - matcher de zone + checker de rôle (le `Firewall`).
+ * @param options     - `channelResolver` (politiques métier déclarées, via le
+ *                      service realtime) + `systemRules` (défauts + config) +
+ *                      `onDeny` (rapporteur d'audit, invoqué sur refus seulement).
+ * @returns un {@link FrameAuthorizer} sync (`true` = frame autorisée).
+ */
+export declare function buildFrameAuthorizer(firewall: IFrameAuthorizerFirewall, options?: {
+    readonly channelResolver?: IChannelPolicyResolver | null;
+    readonly systemRules?: readonly ISystemChannelRule[];
+    readonly onDeny?: FrameDenyReporter;
+}): FrameAuthorizer;
+export default buildFrameAuthorizer;

package/dist/types/nodefony/src/realtime/realtimeContracts.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Miroirs STRUCTURELS des contrats `@nodefony/realtime` — **zéro import** du
+ * module realtime (ni runtime ni type-only).
+ *
+ * POURQUOI : `@nodefony/security` et `@nodefony/realtime` **ne se dépendent pas**
+ * (deux `package.json` disjoints, vérifié). Le câblage du verrou WS se fait par
+ * **nom de service** (`container.get("realtimeService")`), pas par import — donc
+ * security décrit localement la SURFACE qu'il consomme. Le typage structurel de
+ * TypeScript fait le pont : un objet security (authenticator, token) dont la forme
+ * coïncide est accepté à l'exécution par realtime (duck typing). Convention-frère :
+ * `ISessionAuthFlow` (framework décrit la surface http) et le seam realtime↔security
+ * côté realtime (`IRealtimeToken` y est déjà décrit comme « sous-ensemble de IToken »).
+ *
+ * ⚠️ Ces interfaces DOIVENT rester alignées sur celles de
+ * `@nodefony/realtime/nodefony/interfaces/*` — toute dérive de forme casserait le
+ * pont silencieusement (test de compat dans le banc realtime du verrou).
+ */
+/**
+ * Jeton realtime — identité minimale d'une connexion WS (miroir de
+ * `IRealtimeToken`). Posé au handshake, lu en O(1) par le verrou de frame.
+ */
+export interface IRealtimeToken {
+    readonly type: string;
+    getUserIdentifier(): string;
+    isAuthenticated(): boolean;
+    getRoles(): string[];
+    getScopes(): string[];
+    getAttribute<T = unknown>(key: string): T | undefined;
+    /**
+     * Re-validation Zero Trust à l'usage (miroir de `IRealtimeToken` realtime) —
+     * `false` = identité périmée (session morte / compte changé). Optionnel
+     * (absent = valide). Appelé par le pont `api.request` avant l'action data plane.
+     */
+    isValid?(nowMs?: number): boolean | Promise<boolean>;
+}
+/**
+ * Données de handshake WS (miroir de `IRealtimeHandshake`) — DTO neutre passé à
+ * un authenticator. Cookies déjà parsés en `Map<name, value>`.
+ */
+export interface IRealtimeHandshake {
+    readonly headers: Readonly<Record<string, string | string[] | undefined>>;
+    readonly cookies: ReadonlyMap<string, string>;
+    readonly url: string;
+    readonly remoteAddress: string;
+    readonly origin?: string;
+    readonly protocols: readonly string[];
+}
+/**
+ * Stratégie d'auth au handshake WS (miroir de `IRealtimeAuthenticator`,
+ * pattern Symfony `supports/authenticate`).
+ */
+export interface IRealtimeAuthenticator {
+    readonly name: string;
+    supports(handshake: IRealtimeHandshake): boolean;
+    authenticate(handshake: IRealtimeHandshake): Promise<IRealtimeToken>;
+    onSuccess?(handshake: IRealtimeHandshake, token: IRealtimeToken): void;
+    onFailure?(handshake: IRealtimeHandshake, error: Error): void;
+}
+/**
+ * Sélecteur de zone WS (miroir de `IRealtimeAuthenticatorMatcher`) — pattern
+ * d'URL (string|RegExp) + vhost optionnel. Parité avec `ISecuredArea.host`.
+ */
+export interface IRealtimeAuthenticatorMatcher {
+    readonly pattern: string | RegExp;
+    readonly host?: string;
+}
+/**
+ * Verrou de frame (miroir de `FrameAuthorizer`) — SYNC : `true` = frame
+ * autorisée. Lit le token déjà résolu au handshake (0 lecture base par frame).
+ */
+export type FrameAuthorizer = (frame: unknown, token: IRealtimeToken) => boolean;
+/**
+ * Politique d'autorisation d'un **canal** (miroir de `ChannelPolicy` realtime) —
+ * exigences à satisfaire pour `subscribe`/inbound. Toutes les contraintes posées
+ * sont cumulatives (ET) ; un champ absent = pas de contrainte sur cet axe. Une
+ * politique entièrement vide = canal libre (équivaut à `null`).
+ *
+ * Résolue 1× au `subscribe` (cold path : un client s'abonne rarement), comparée
+ * au token déjà chargé au handshake → 0 lecture base. Deux origines : déclaration
+ * **métier** (`@RealtimeChannel(name, opts)`, portée par le hub realtime) et
+ * **plateforme** (`defineSecurityConfig().realtimeChannels` + namespaces système
+ * réservés, portée par security — cf {@link buildFrameAuthorizer}).
+ */
+export interface IChannelPolicy {
+    /** Exige une connexion authentifiée (token non anonyme). */
+    readonly authenticated?: boolean;
+    /** Un de ces rôles suffit (évalué AVEC la hiérarchie de rôles du firewall). */
+    readonly roles?: readonly string[];
+    /** Un de ces scopes suffit (axe API : JWT/clé API ; session BFF n'en porte pas). */
+    readonly scopes?: readonly string[];
+}
+/**
+ * Surface consommée du `realtimeService` (miroir partiel de `RealtimeService`) —
+ * seulement les seams que security câble/lit au boot et au dispatch. Résolu par
+ * nom via le container (`container.get<IRealtimeService>("realtimeService")`).
+ */
+export interface IRealtimeService {
+    /** Seam #2/#3 — enregistre un authenticator pour les handshakes WS matchés. */
+    useAuthenticator(matcher: IRealtimeAuthenticatorMatcher, authenticator: IRealtimeAuthenticator): void;
+    /**
+     * Seam #1 — pose le verrou de frame (hot-path `beforeDispatch`).
+     *
+     * `options.silentProbe` porte la MÊME décision sans rapporter de refus : le
+     * `realtime:welcome` interroge N canaux à chaque connexion pour n'annoncer que
+     * ce qui est obtenable, et passer par le verrou y écrirait N refus au journal
+     * d'audit pour des demandes que personne n'a faites. Optionnel côté appelé :
+     * un module realtime d'une version antérieure l'ignore, et l'annonce reste
+     * alors ce qu'elle était — jamais une erreur.
+     */
+    setFrameAuthorizer(authorizer: FrameAuthorizer | null, options?: {
+        readonly silentProbe?: FrameAuthorizer | null;
+    }): void;
+    /**
+     * Seam #1b — politique de canal **déclarée côté métier** (`@RealtimeChannel`),
+     * agrégée par le hub. `null`/absent = aucune politique métier pour ce canal
+     * (security retombe alors sur sa politique plateforme/système). Optionnel : un
+     * hub d'une version antérieure ne l'expose pas → traité comme `undefined`.
+     */
+    resolveChannelPolicy?(channel: string): IChannelPolicy | null;
+    /**
+     * Namespaces de canaux **réservés à la plateforme**, tels que le hub les connaît
+     * (`syslog:`, `orm:`, `kernel:`…). Le firewall y accroche ses politiques au lieu
+     * d'en tenir un second inventaire : deux listes auraient divergé au premier
+     * namespace ajouté côté realtime, et le namespace neuf serait resté **sans
+     * politique** — un trou silencieux. Le hub possède la liste, la sécurité possède
+     * les rôles.
+     *
+     * Optionnel : un hub d'une version antérieure ne l'expose pas → repli sur la
+     * liste locale ({@link RESERVED_FLOOR_PREFIXES}).
+     */
+    reservedSystemPrefixes?(): readonly string[];
+    /**
+     * Seam canal SYSTÈME (P6.14 lot 4) — enregistre la factory d'un canal plateforme
+     * (`nodefony:audit`) sur le hub, sans qu'aucun controller ne le connaisse. Lazy :
+     * le provider est créé au 1ᵉʳ abonné, `dispose` au dernier. Optionnel : un hub
+     * d'une version antérieure ne l'expose pas → security s'abstient (canal absent).
+     */
+    registerSystemChannel?(channel: string, factory: (channel: string, publish: (channel: string, payload: unknown) => void) => (() => void) | null): void;
+}

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

@@ -0,0 +1,20 @@
+import type { IUser, IUserProvider } from "@nodefony/user";
+/**
+ * Résout l'identité portée par une session (l'identifiant stocké dans le blob)
+ * en utilisateur VIVANT — re-fetch systématique auprès du provider.
+ *
+ * C'est LE choix structurant de la session BFF : la session ne stocke que
+ * l'identifiant, jamais l'utilisateur sérialisé. Rôles toujours frais, et un
+ * compte verrouillé/désactivé entre deux requêtes est rejeté immédiatement
+ * (révocation effective — l'argument décisif face au JWT côté web).
+ *
+ * Partagé par le `SessionAuthenticator` (requêtes en zone) et `AuthFlow.me()`
+ * (hors zone) : une seule source de vérité des contrôles d'état du compte.
+ *
+ * @param provider - source d'identité (`UserService` via le container).
+ * @param identifier - identifiant fonctionnel stocké en session.
+ * @returns l'utilisateur actif.
+ * @throws AuthenticationError (401, message uniforme) — identifiant inconnu,
+ *   compte verrouillé ou désactivé.
+ */
+export declare function resolveSessionIdentity(provider: IUserProvider, identifier: string): Promise<IUser>;

package/dist/types/nodefony/src/throttle/LoginThrottler.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Politique de backoff du throttling de login (NIST SP 800-63B §5.2.2).
+ *
+ * JAMAIS de verrouillage dur : un lockout au N-ième échec offrirait à
+ * l'attaquant un déni de service gratuit sur le compte de sa victime (5 mauvais
+ * essais suffiraient à l'exclure). Le délai PROGRESSIF rend le brute-force
+ * impraticable (le coût croît exponentiellement) sans donner ce levier — le
+ * titulaire légitime attend au pire `capDelayS`, jamais un déblocage admin.
+ */
+export interface ILoginThrottleOptions {
+    /** Échecs consécutifs tolérés sans délai (défaut 3 — fautes de frappe). */
+    freeAttempts?: number;
+    /** Délai (s) après `freeAttempts` — double à chaque échec suivant (défaut 1). */
+    baseDelayS?: number;
+    /** Plafond du délai (s) — défaut 900 (15 min). */
+    capDelayS?: number;
+    /** Borne du nombre d'identifiants suivis (anti-fuite mémoire, défaut 10 000). */
+    maxTracked?: number;
+}
+/**
+ * Limiteur de tentatives de login **en mémoire, par identifiant saisi**.
+ *
+ * La clé est l'identifiant TEL QUE SAISI (existant ou non en base) : un
+ * identifiant martelé est ralenti qu'il corresponde à un compte ou pas — aucun
+ * oracle d'énumération. Par-processus (V1) : en cluster, chaque worker porte son
+ * compteur (l'attaquant gagne ×N workers — acceptable car le backoff est
+ * exponentiel ; un backend partagé type Redis se branchera derrière la même
+ * interface sans toucher l'authenticator).
+ *
+ * Coût borné (règle perf Nodefony) : `Map` allouée LAZY au premier échec (une
+ * app sans échec de login ne paie rien), AUCUN timer — l'expiration est évaluée
+ * à la lecture et les entrées mortes sont purgées par balayage opportuniste
+ * quand la borne `maxTracked` est atteinte (puis éviction FIFO en dernier
+ * recours : ~10 000 × ~100 B ≈ 1 MB au pire).
+ */
+export declare class LoginThrottler {
+    #private;
+    readonly freeAttempts: number;
+    readonly baseDelayS: number;
+    readonly capDelayS: number;
+    readonly maxTracked: number;
+    constructor(options?: ILoginThrottleOptions, now?: () => number);
+    /**
+     * L'identifiant peut-il tenter un login maintenant ?
+     *
+     * @param identifier - identifiant tel que saisi.
+     * @returns `0` si autorisé, sinon les secondes restantes (→ `Retry-After`,
+     *   arrondies à l'entier supérieur).
+     */
+    check(identifier: string): number;
+    /**
+     * Enregistre un échec : au-delà de `freeAttempts`, arme un délai exponentiel
+     * `baseDelayS × 2^(échecs - freeAttempts - 1)`, plafonné à `capDelayS`.
+     *
+     * @param identifier - identifiant tel que saisi.
+     */
+    recordFailure(identifier: string): void;
+    /**
+     * Login réussi : oublie l'identifiant (le délai repart de zéro — NIST :
+     * l'utilisateur légitime ne traîne pas la dette d'un attaquant passé).
+     *
+     * @param identifier - identifiant tel que saisi.
+     */
+    recordSuccess(identifier: string): void;
+    /** Nombre d'identifiants actuellement suivis (introspection / tests). */
+    get trackedCount(): number;
+}
+export default LoginThrottler;

package/dist/types/nodefony/src/token/AnonymousToken.d.ts

@@ -0,0 +1,23 @@
+import type { IUser } from "@nodefony/user";
+import type { IToken } from "../../contracts/IToken.js";
+/**
+ * Token du visiteur non authentifié — Zero Trust : un visiteur EST un utilisateur
+ * anonyme (jamais `null`).
+ *
+ * Porte le singleton gelé `anonymousUser` → **zéro allocation d'utilisateur** par
+ * requête non authentifiée (hot path). Les attributs sont lazy (`null` tant qu'on
+ * n'en pose pas).
+ */
+export declare class AnonymousToken implements IToken {
+    #private;
+    readonly type = "anonymous";
+    getUser(): IUser;
+    getUserIdentifier(): string;
+    isAuthenticated(): boolean;
+    getRoles(): string[];
+    getCredentials(): unknown;
+    getScopes(): string[];
+    getAttribute<T = unknown>(key: string): T | undefined;
+    setAttribute(key: string, value: unknown): void;
+}
+export default AnonymousToken;