@nodefony/security 10.0.0-beta.4 → 10.0.0-beta.5

package/dist/nodefony/src/realtime/frameAuthorizer.js

@@ -254,7 +254,7 @@ function authorizeChannel(channel, token, firewall, resolver, systemRules, onDen
 * (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
+*  - `api.request {path}` (pont socket) : 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

package/dist/nodefony/testing/index.js

@@ -0,0 +1,108 @@
+import { RoleHierarchyWalker } from "../src/RoleHierarchyWalker.js";
+import { DEFAULT_SYSTEM_RULES, buildFrameAuthorizer } from "../src/realtime/frameAuthorizer.js";
+// nodefony/testing/index.ts
+/**
+* `@nodefony/security/testing` — **identité d'essai et VRAI verrou de frame**,
+* pour éprouver un canal ou une action temps réel protégés.
+*
+* Le harnais de `@nodefony/realtime/testing` accepte une identité et un verrou,
+* mais n'en fournit aucun : `@nodefony/realtime` ne connaît pas la sécurité.
+* Faute de mieux, une application écrivait un jeton factice et un verrou qui ne
+* regardait que `isAuthenticated()` — son test passait, et n'éprouvait PAS la
+* politique de rôles du canal. Un canal mal protégé y était vert. Deux agents
+* sur deux l'ont fait, en recopiant le jeton que montrait le test généré.
+*
+* Ce module rend les deux pièces, et le verrou rendu est celui du pare-feu —
+* {@link buildFrameAuthorizer}, la même fabrique que le boot branche sur le hub,
+* avec la même hiérarchie de rôles et les mêmes canaux système. Seuls manquent
+* le journal d'audit (un refus en test n'est pas une transition de sécurité) et
+* les ZONES HTTP : une frame `api.request` y passe comme hors de toute zone, et
+* la garde d'une route s'éprouve par HTTP, pas ici.
+*
+* ```ts
+* import { getRealtimeHub } from "@nodefony/realtime";
+* import { createRealtimeHarness } from "@nodefony/realtime/testing";
+* import {
+*   createTestFrameAuthorizer,
+*   createTestIdentity,
+* } from "@nodefony/security/testing";
+*
+* const h = createRealtimeHarness((ctx) => new ChatController(ctx), {
+*   identity: createTestIdentity({ identifier: "alice", roles: ["ROLE_USER"] }),
+*   frameAuthorizer: createTestFrameAuthorizer(getRealtimeHub()),
+* });
+* ```
+*
+* @packageDocumentation
+*/
+/**
+* Une identité de connexion AUTHENTIFIÉE, telle que le pare-feu l'aurait posée
+* au handshake.
+*
+* Pour éprouver un visiteur anonyme, ne rien passer au harnais : il pose alors
+* le jeton anonyme, comme le repli Zero Trust du runtime.
+*
+* @param options - identifiant, rôles, scopes, utilisateur.
+* @returns un jeton à passer en `identity` au harnais temps réel.
+*/
+function createTestIdentity(options = {}) {
+	const identifier = options.identifier ?? "alice";
+	const roles = options.roles ?? ["ROLE_USER"];
+	return new TestToken(identifier, roles, options.scopes ?? [], options.user ?? {
+		identifier,
+		roles: [...roles]
+	});
+}
+/** Le jeton que rend {@link createTestIdentity}. */
+var TestToken = class {
+	identifier;
+	roles;
+	scopes;
+	user;
+	type = "session";
+	constructor(identifier, roles, scopes, user) {
+		this.identifier = identifier;
+		this.roles = roles;
+		this.scopes = scopes;
+		this.user = user;
+	}
+	getUserIdentifier() {
+		return this.identifier;
+	}
+	isAuthenticated() {
+		return true;
+	}
+	getRoles() {
+		return [...this.roles];
+	}
+	getScopes() {
+		return [...this.scopes];
+	}
+	getAttribute(key) {
+		return key === "user" ? this.user : void 0;
+	}
+};
+/**
+* Le VRAI verrou de frame du pare-feu, pour le harnais temps réel.
+*
+* C'est lui qui applique `@RealtimeChannel(nom, { roles })`,
+* `@RealtimeAction(nom, { roles })` et les canaux système : sans lui, une
+* politique déclarée n'est appliquée par personne — en test comme au runtime.
+*
+* @param channels - ce qui connaît les politiques déclarées : le hub temps réel
+*   (`getRealtimeHub()`), lu à CHAQUE frame — les politiques que le controller
+*   enregistre à sa construction y sont donc vues.
+* @param options - hiérarchie de rôles de l'application.
+* @returns le verrou à passer en `frameAuthorizer` au harnais.
+*/
+function createTestFrameAuthorizer(channels, options = {}) {
+	const walker = new RoleHierarchyWalker(options.roleHierarchy ?? {});
+	return buildFrameAuthorizer({
+		matchPath: () => null,
+		hasRole: (userRoles, required) => walker.hasRole(userRoles, required)
+	}, {
+		channelResolver: channels,
+		systemRules: DEFAULT_SYSTEM_RULES
+	});
+}
+export { createTestFrameAuthorizer, createTestIdentity };

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

@@ -39,7 +39,7 @@ export interface ISystemChannelRule {
  * 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
+ * @param surface - cible refusée : pont socket (`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`).
@@ -159,7 +159,7 @@ export declare function buildSystemRules(prefixes: readonly string[]): readonly
  * (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
+ *  - `api.request {path}` (pont socket) : 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

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

@@ -0,0 +1,51 @@
+import { type IChannelPolicyResolver } from "../src/realtime/frameAuthorizer.js";
+import type { FrameAuthorizer, IRealtimeToken } from "../src/realtime/realtimeContracts.js";
+/** L'identité d'essai : qui se connecte, avec quels droits. */
+export interface ITestIdentityOptions {
+    /** Identifiant de l'utilisateur (défaut `"alice"`). */
+    readonly identifier?: string;
+    /** Rôles portés (défaut `["ROLE_USER"]`) — ceux qu'aurait résolus le pare-feu. */
+    readonly roles?: readonly string[];
+    /** Scopes portés (défaut aucun) — l'axe des jetons d'API, pas de la session. */
+    readonly scopes?: readonly string[];
+    /**
+     * L'utilisateur rendu par `@CurrentUser()` et `RequestContext.getUser()`
+     * (défaut `{ identifier, roles }`). Passer l'entité de l'application quand
+     * l'action en lit d'autres champs.
+     */
+    readonly user?: unknown;
+}
+/**
+ * Une identité de connexion AUTHENTIFIÉE, telle que le pare-feu l'aurait posée
+ * au handshake.
+ *
+ * Pour éprouver un visiteur anonyme, ne rien passer au harnais : il pose alors
+ * le jeton anonyme, comme le repli Zero Trust du runtime.
+ *
+ * @param options - identifiant, rôles, scopes, utilisateur.
+ * @returns un jeton à passer en `identity` au harnais temps réel.
+ */
+export declare function createTestIdentity(options?: ITestIdentityOptions): IRealtimeToken;
+/** Écarts au pare-feu d'essai. */
+export interface ITestFrameAuthorizerOptions {
+    /**
+     * Hiérarchie de rôles, à la forme de `roleHierarchy` de la configuration de
+     * sécurité (défaut : aucune). La reprendre de l'application quand un rôle en
+     * couvre un autre — `{ ROLE_ADMIN: ["ROLE_USER"] }`.
+     */
+    readonly roleHierarchy?: Record<string, readonly string[]>;
+}
+/**
+ * Le VRAI verrou de frame du pare-feu, pour le harnais temps réel.
+ *
+ * C'est lui qui applique `@RealtimeChannel(nom, { roles })`,
+ * `@RealtimeAction(nom, { roles })` et les canaux système : sans lui, une
+ * politique déclarée n'est appliquée par personne — en test comme au runtime.
+ *
+ * @param channels - ce qui connaît les politiques déclarées : le hub temps réel
+ *   (`getRealtimeHub()`), lu à CHAQUE frame — les politiques que le controller
+ *   enregistre à sa construction y sont donc vues.
+ * @param options - hiérarchie de rôles de l'application.
+ * @returns le verrou à passer en `frameAuthorizer` au harnais.
+ */
+export declare function createTestFrameAuthorizer(channels: IChannelPolicyResolver, options?: ITestFrameAuthorizerOptions): FrameAuthorizer;

package/docs/webhooks.md

@@ -893,6 +893,15 @@ runtime, zéro cycle. Pour valider ton implémentation, importe le banc de contr
 (`tests/support/webhookPaginationContract.ts`) et branche-le sur ton store : les invariants d'ordre,
 de filtres et de bornes sont alors prouvés, pas supposés.
 
+**Ta fabrique lève quand son backend n'est pas joignable — jamais un registre qui se tait.** Un
+`IWebhookStore` qui, faute de connexion, rend une liste d'abonnements vide ne lève rien et ne
+livre plus rien : les abonnés cessent d'être notifiés, sans une ligne au journal, pendant que la
+configuration affiche ton backend. Le registre livré pour SQL fait l'inverse : sa fabrique passe
+par `resolveConnectedOrm()` (`drizzle/nodefony/registerStores.ts#resolveConnectedOrm`), qui lève
+en nommant la cause — module absent, ordre de démarrage, dialecte — si la connexion n'existe pas.
+Fais de même : vérifie la connexion dans la fabrique, et laisse remonter l'erreur. Ne la rattrape
+pas dans chaque méthode par un `if (!connected) return []`.
+
 ## 📜 Normes appliquées
 
 | Domaine                 | Norme / référence                     | Ancrage                                                                            |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/security",
-  "version": "10.0.0-beta.4",
+  "version": "10.0.0-beta.5",
   "description": "Pare-feu applicatif par zones pour Nodefony : authentification, autorisation par rôles, protection CSRF, journal d'audit",
   "author": "Christophe CAMENSULI <ccamensuli@gmail.com>",
   "main": "./dist/index.js",
@@ -16,6 +16,12 @@
       "types": "./dist/types/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./testing": {
+      "nodefony-source": "./nodefony/testing/index.ts",
+      "types": "./dist/types/nodefony/testing/index.d.ts",
+      "import": "./dist/nodefony/testing/index.js",
+      "default": "./dist/nodefony/testing/index.js"
     }
   },
   "scripts": {
@@ -55,22 +61,22 @@
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@nodefony/framework": "^10.0.0-beta.4",
-    "@nodefony/http": "^10.0.0-beta.4",
-    "@nodefony/user": "^10.0.0-beta.4",
+    "@nodefony/framework": "^10.0.0-beta.5",
+    "@nodefony/http": "^10.0.0-beta.5",
+    "@nodefony/user": "^10.0.0-beta.5",
     "@types/node": "26.6.5",
     "@vitest/coverage-v8": "5.0.5",
-    "nodefony": "^10.0.0-beta.4",
+    "nodefony": "^10.0.0-beta.5",
     "vitest": "5.0.5"
   },
   "license": "Apache-2.0",
   "readmeFilename": "README.md",
   "contributors": [],
   "peerDependencies": {
-    "@nodefony/framework": "^10.0.0-beta.4",
-    "@nodefony/http": "^10.0.0-beta.4",
-    "@nodefony/user": "^10.0.0-beta.4",
-    "nodefony": "^10.0.0-beta.4"
+    "@nodefony/framework": "^10.0.0-beta.5",
+    "@nodefony/http": "^10.0.0-beta.5",
+    "@nodefony/user": "^10.0.0-beta.5",
+    "nodefony": "^10.0.0-beta.5"
   },
   "files": [
     "dist",