@nodefony/security 10.0.0-alpha.1

package/dist/nodefony/service/webhooks.js

@@ -0,0 +1,539 @@
+import { defineSecurityConfig } from "../config/defineModuleConfig.js";
+import { decryptSecret, encryptSecret, generateEphemeralKey } from "../src/crypto/secretCipher.js";
+import { WEBHOOK_FACETS } from "../src/webhook/webhookFilters.js";
+import { getWebhookStoreFactory, listWebhookStores } from "../src/webhook/webhookStoreRegistry.js";
+import { deriveWebhookKey } from "../src/webhook/webhookCipher.js";
+import { assertPublicUrl } from "../src/net/ssrfGuard.js";
+import { WebhookDispatcher } from "../src/webhook/WebhookDispatcher.js";
+import { deliverWebhook } from "../src/webhook/webhookDelivery.js";
+import { AUTO_STORE, EMPTY_INFRA, Service, countFacets, deriveStoreBackend, readStoreLocation, resolveAutoStore } from "nodefony";
+import { randomBytes } from "node:crypto";
+import { Buffer } from "node:buffer";
+import { schemaMismatchOf } from "@nodefony/http";
+//#region nodefony/service/webhooks.ts
+const serviceName = "webhooks";
+/** Historique de livraisons gardé PAR endpoint (ring borné, RAM, par pod). */
+const MAX_DELIVERIES_PER_ENDPOINT = 20;
+/** Corps de requête tronqué dans l'historique (anti-mémoire). */
+const MAX_RECORDED_BODY = 8192;
+/** Retire le secret chiffré → vue publique. */
+function toSummary(endpoint) {
+	const { secretEnc: _omit, ...rest } = endpoint;
+	return rest;
+}
+/** Identifiant public d'endpoint (`wh_<random url-safe>`). */
+function generateId() {
+	return `wh_${randomBytes(12).toString("base64url")}`;
+}
+/** Secret de signature Standard Webhooks (`whsec_<base64 256 bits>`). */
+function generateSecret() {
+	return `whsec_${randomBytes(32).toString("base64")}`;
+}
+/**
+* **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).
+*/
+var WebhookService = class extends Service {
+	module;
+	#config = null;
+	#store = null;
+	#key = null;
+	#ready = false;
+	/** Cache mémoire des endpoints (snapshot sync pour le dispatcher). */
+	#endpoints = null;
+	/** Date (ms) du dernier chargement du cache — borne sa fraîcheur (multi-pod). */
+	#loadedAt = 0;
+	/** Un rechargement est en vol : évite N relectures concurrentes sous rafale. */
+	#reloading = false;
+	/** Dispatcher de livraison (abonné à l'audit) — créé au boot si l'audit existe. */
+	#dispatcher = null;
+	/** Désabonnement de l'audit (appelé à l'arrêt). */
+	#unsubscribe = null;
+	/** Sink d'audit — trace l'auto-désactivation (signal borné, pas chaque échec). */
+	#audit = null;
+	/** Historique de livraisons par endpoint (lazy, ring borné, RAM par pod). */
+	#deliveries = null;
+	constructor(module) {
+		super(serviceName, module.container, module.notificationsCenter, module.options);
+		this.module = module;
+		this.kernel?.once("onBoot", () => this.#build());
+		this.kernel?.once("onTerminate", () => this.#shutdown());
+	}
+	#build() {
+		let config;
+		try {
+			config = defineSecurityConfig(this.options);
+		} catch {
+			return;
+		}
+		if (!config.webhooks.enabled) {
+			this.log("webhooks idle — désactivés en config", "DEBUG");
+			return;
+		}
+		const store = this.#resolveStore(config);
+		if (!store) return;
+		const key = this.#resolveKey(config);
+		if (!key) return;
+		this.#config = config;
+		this.#store = store;
+		this.#key = key;
+		this.#ready = true;
+		this.#reloadSnapshot();
+		this.#attachDispatcher();
+		this.log(`webhooks ready — store "${config.webhooks.store}"`, "DEBUG");
+	}
+	/**
+	* Branche le dispatcher de livraison sur le journal d'audit (abonné). No-op si
+	* l'audit est absent (CRUD seul). Le listener ne fait que filtrer + différer
+	* (jamais de travail bloquant dans le hot-path de `record()`).
+	*/
+	#attachDispatcher() {
+		const audit = this.get("auditService");
+		if (!audit || typeof audit.subscribe !== "function") {
+			this.log("webhooks: auditService absent — dispatcher inactif", "WARNING");
+			return;
+		}
+		this.#audit = audit;
+		this.#dispatcher = new WebhookDispatcher({
+			endpointCount: () => this.endpointCount(),
+			getSnapshot: () => this.getSnapshot(),
+			secretOf: (ep) => this.decryptEndpointSecret(ep).toString("utf8"),
+			policy: this.getDeliveryPolicy(),
+			resolveTarget: (url) => this.#resolveTarget(url),
+			deliver: (url, body, headers, opts) => deliverWebhook(url, body, headers, opts),
+			markDelivery: (id, r) => this.markDelivery(id, r),
+			recordDelivery: (id, rec) => this.#recordDelivery(id, rec),
+			now: () => Date.now(),
+			newMessageId: () => `msg_${randomBytes(12).toString("base64url")}`,
+			schedule: (fn, ms) => {
+				const t = setTimeout(fn, ms);
+				t.unref?.();
+				return () => clearTimeout(t);
+			},
+			log: (m) => this.log(m, "ERROR")
+		});
+		this.#unsubscribe = audit.subscribe((e) => this.#dispatcher.onAuditEvent(e));
+		this.log("webhooks dispatcher abonné à l'audit", "DEBUG");
+	}
+	/** Arrêt propre : désabonnement audit + annulation des retries en vol. */
+	#shutdown() {
+		if (this.#unsubscribe) {
+			this.#unsubscribe();
+			this.#unsubscribe = null;
+		}
+		this.#dispatcher?.shutdown();
+		this.#dispatcher = null;
+	}
+	/** Adapter posé au container (ORM) prioritaire, sinon driver configuré (registre). */
+	#resolveStore(config) {
+		const existing = this.get("webhookStore");
+		if (existing) {
+			this.kernel?.registerStoreResolution({
+				brick: "webhooks",
+				nature: "durable",
+				configured: config.webhooks.store,
+				resolved: deriveStoreBackend(existing),
+				available: listWebhookStores(),
+				reason: "adapter posé au container (infra database déclarée)",
+				configPath: "security.webhooks.store",
+				location: readStoreLocation(existing)
+			});
+			return existing;
+		}
+		let driver = config.webhooks.store;
+		let reason = `store explicitement configuré ("${driver}")`;
+		if (driver === AUTO_STORE) {
+			const auto = resolveAutoStore("durable", this.kernel?.infra ?? EMPTY_INFRA, listWebhookStores());
+			driver = auto.store;
+			reason = auto.reason;
+			this.log(`webhooks.store "auto" → "${driver}" (${auto.reason})`, "INFO");
+		}
+		const factory = getWebhookStoreFactory(driver);
+		if (!factory) {
+			const msg = `webhooks store "${driver}" inconnu (enregistrés : ${listWebhookStores().join(", ") || "aucun"})`;
+			if (this.kernel?.environment === "production") throw new Error(`${msg} — webhooks indisponibles : boot avorté.`);
+			this.log(`${msg} — webhooks indisponibles`, "CRITIC");
+			return null;
+		}
+		if (driver === "memory" && this.kernel?.environment === "production") this.log("webhooks.store \"memory\" en PRODUCTION — abonnements volatils et per-pod : perdus au redémarrage, non partagés entre pods. Déclarer une infra durable (NF_DATABASE_URL).", "WARNING");
+		const store = factory({
+			container: this.container,
+			config
+		});
+		this.container?.set("webhookStore", store);
+		this.kernel?.registerStoreResolution({
+			brick: "webhooks",
+			nature: "durable",
+			configured: config.webhooks.store,
+			resolved: driver,
+			available: listWebhookStores(),
+			reason,
+			configPath: "security.webhooks.store",
+			location: readStoreLocation(store)
+		});
+		return store;
+	}
+	/** Clé AES-256 du secret au repos. Dev : éphémère + WARNING ; prod : fatal (null). */
+	#resolveKey(config) {
+		const material = config.webhooks.encryptionKey;
+		if (material && material.length > 0) return deriveWebhookKey(material);
+		if (this.kernel?.environment === "production") {
+			this.log("webhooks: AUCUNE clé de chiffrement (`security.webhooks.encryptionKey`) en PRODUCTION — webhooks désactivés (un secret chiffré par une clé éphémère serait illisible après redémarrage / sur les autres pods). Fournir une clé depuis l'environnement.", "CRITIC");
+			return null;
+		}
+		this.log("webhooks: aucune clé de chiffrement configurée — clé ÉPHÉMÈRE générée (dev). Les secrets de signature ne survivront pas au redémarrage. Définir `webhooks.encryptionKey` — générer la clé et le câblage : `npx nodefony security:secrets`.", "WARNING");
+		return generateEphemeralKey();
+	}
+	async #reloadSnapshot() {
+		if (!this.#store) return;
+		this.#reloading = true;
+		try {
+			const all = await this.#store.listAll();
+			this.#endpoints = new Map(all.map((e) => [e.id, e]));
+		} catch (e) {
+			if (schemaMismatchOf(e) !== null) this.log("webhooks: la base ne porte pas encore la table des points de livraison — c'est l'état normal avant la première migration. Aucun abonnement chargé ; la lecture sera retentée. Pour savoir où en est le schéma : `nodefony orm:migrate:status`.", "INFO");
+			else this.log(e, "ERROR");
+		} finally {
+			this.#loadedAt = Date.now();
+			this.#reloading = false;
+		}
+	}
+	/**
+	* Borne la fraîcheur du cache d'endpoints — **le seul mécanisme qui rend les
+	* webhooks corrects à plusieurs pods.**
+	*
+	* Le store est partagé, le cache ne l'est pas : un endpoint créé sur le pod A
+	* n'existe pour le pod B qu'après relecture. Sans borne, B ne livrerait rien
+	* pour cet abonnement jusqu'à son redémarrage — et le cas le plus courant est
+	* le pire : des pods démarrés AVANT toute création de webhook court-circuitent
+	* sur `endpointCount() === 0` et ne rechargent jamais.
+	*
+	* Choix : relecture **paresseuse, déclenchée par la lecture**, jamais un timer
+	* — aucun coût quand il ne se passe rien, et le rechargement se paie là où il
+	* sert. Appel non bloquant : la lecture en cours sert le cache courant, la
+	* suivante voit l'état frais. La propagation est donc **éventuelle et bornée**
+	* par `webhooks.snapshotTtlS`, pas immédiate ; c'est écrit dans la config et
+	* dans la doc, jamais supposé.
+	*
+	* Coût hot-path : une soustraction et deux comparaisons, zéro allocation.
+	*/
+	#touchSnapshot() {
+		if (!this.#ready || this.#reloading) return;
+		const ttlMs = (this.#config?.webhooks.snapshotTtlS ?? 30) * 1e3;
+		if (Date.now() - this.#loadedAt < ttlMs) return;
+		this.#reloadSnapshot();
+	}
+	/** Le service est-il opérationnel (activé + store + clé) ? */
+	isReady() {
+		return this.#ready;
+	}
+	/**
+	* 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() {
+		return this.#store?.sortableFields ?? [];
+	}
+	/**
+	* 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.
+	*/
+	async register(input) {
+		this.#assertReady();
+		await this.#assertSafeUrl(input.url);
+		const secret = generateSecret();
+		const now = Date.now();
+		const endpoint = {
+			id: generateId(),
+			url: input.url,
+			secretEnc: encryptSecret(Buffer.from(secret, "utf8"), this.#key),
+			events: [...input.events],
+			enabled: input.enabled ?? true,
+			description: input.description ?? null,
+			tenantId: input.tenantId ?? null,
+			createdBy: input.createdBy ?? null,
+			createdAt: now,
+			updatedAt: now,
+			lastDeliveryAt: null,
+			lastDeliveryStatus: null,
+			lastDeliveryError: null,
+			failureCount: 0,
+			metadata: input.metadata ?? {}
+		};
+		await this.#store.save(endpoint);
+		this.#endpoints?.set(endpoint.id, endpoint);
+		return {
+			endpoint: toSummary(endpoint),
+			secret
+		};
+	}
+	/**
+	* 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.
+	*/
+	async listPage(query) {
+		this.#assertReady();
+		const page = await this.#store.listPage(query);
+		return {
+			...page,
+			items: page.items.map(toSummary)
+		};
+	}
+	/**
+	* 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.
+	*/
+	async countEndpoints(query) {
+		this.#assertReady();
+		return this.#store.countEndpoints(query);
+	}
+	/**
+	* 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).
+	*/
+	async countWebhookFacets(query) {
+		this.#assertReady();
+		return countFacets(WEBHOOK_FACETS, (facet) => this.#store.countEndpoints({
+			...query,
+			...facet
+		}));
+	}
+	/** Un endpoint par id (vue publique), ou `null`. */
+	async getEndpoint(id) {
+		this.#assertReady();
+		const found = await this.#store.findById(id);
+		return found ? toSummary(found) : 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.
+	*/
+	async update(id, patch) {
+		this.#assertReady();
+		const current = await this.#store.findById(id);
+		if (!current) return null;
+		if (patch.url !== void 0 && patch.url !== current.url) await this.#assertSafeUrl(patch.url);
+		const applied = {
+			...patch,
+			updatedAt: Date.now()
+		};
+		await this.#store.update(id, applied);
+		const next = {
+			...current,
+			...applied
+		};
+		this.#endpoints?.set(id, next);
+		return toSummary(next);
+	}
+	/** Active/désactive un endpoint (révocation douce = `false`). */
+	async setEnabled(id, enabled) {
+		return this.update(id, { enabled });
+	}
+	/**
+	* 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.
+	*/
+	async rotateSecret(id) {
+		this.#assertReady();
+		const current = await this.#store.findById(id);
+		if (!current) return null;
+		const secret = generateSecret();
+		const patch = {
+			secretEnc: encryptSecret(Buffer.from(secret, "utf8"), this.#key),
+			updatedAt: Date.now()
+		};
+		await this.#store.update(id, patch);
+		const next = {
+			...current,
+			...patch
+		};
+		this.#endpoints?.set(id, next);
+		return {
+			endpoint: toSummary(next),
+			secret
+		};
+	}
+	/**
+	* Révèle le secret en clair d'un endpoint (réversible — usage admin, à auditer
+	* par l'appelant). `null` si absent.
+	*/
+	async revealSecret(id) {
+		this.#assertReady();
+		const current = await this.#store.findById(id);
+		if (!current) return null;
+		return decryptSecret(current.secretEnc, this.#key).toString("utf8");
+	}
+	/** Supprime un endpoint. Retourne `false` si absent. */
+	async delete(id) {
+		this.#assertReady();
+		if (!await this.#store.findById(id)) return false;
+		await this.#store.delete(id);
+		this.#endpoints?.delete(id);
+		this.#deliveries?.delete(id);
+		return true;
+	}
+	/**
+	* 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) {
+		const ring = this.#deliveries?.get(id);
+		return ring ? [...ring] : [];
+	}
+	/**
+	* Pousse une trace de livraison dans le ring de l'endpoint (lazy alloc, ring
+	* borné `MAX_DELIVERIES_PER_ENDPOINT`, corps tronqué). Appelé par le dispatcher
+	* sur l'issue FINALE d'une livraison.
+	*/
+	#recordDelivery(id, rec) {
+		if (this.#deliveries === null) this.#deliveries = /* @__PURE__ */ new Map();
+		let ring = this.#deliveries.get(id);
+		if (ring === void 0) {
+			ring = [];
+			this.#deliveries.set(id, ring);
+		}
+		const entry = {
+			ts: Date.now(),
+			messageId: rec.messageId,
+			type: rec.type,
+			attempt: rec.attempt,
+			ok: rec.ok,
+			status: rec.status,
+			error: rec.error,
+			durationMs: rec.durationMs,
+			requestBody: rec.requestBody.length > MAX_RECORDED_BODY ? rec.requestBody.slice(0, MAX_RECORDED_BODY) : rec.requestBody,
+			responseBody: rec.responseBody
+		};
+		ring.unshift(entry);
+		if (ring.length > MAX_DELIVERIES_PER_ENDPOINT) ring.length = MAX_DELIVERIES_PER_ENDPOINT;
+	}
+	/** Snapshot mémoire (sync) des endpoints — itération du dispatcher (si >0). */
+	getSnapshot() {
+		this.#touchSnapshot();
+		return this.#endpoints ? [...this.#endpoints.values()] : [];
+	}
+	/**
+	* 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() {
+		this.#touchSnapshot();
+		return this.#endpoints ? this.#endpoints.size : 0;
+	}
+	/** Déchiffre le secret de signature d'un endpoint (pour signer une livraison). */
+	decryptEndpointSecret(endpoint) {
+		this.#assertReady();
+		return decryptSecret(endpoint.secretEnc, this.#key);
+	}
+	/** Politique de livraison (tolérance/retries/timeout…) issue de la config. */
+	getDeliveryPolicy() {
+		this.#assertReady();
+		const w = this.#config.webhooks;
+		return {
+			timestampToleranceS: w.timestampToleranceS,
+			maxRetries: w.maxRetries,
+			autoDisableThreshold: w.autoDisableThreshold,
+			deliveryTimeoutMs: w.deliveryTimeoutMs,
+			maxConcurrent: w.maxConcurrent,
+			maxQueue: w.maxQueue,
+			allowHttp: w.allowHttp,
+			denyPrivateIps: w.denyPrivateIps
+		};
+	}
+	/**
+	* 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.
+	*/
+	async markDelivery(id, result) {
+		if (!this.#ready || !this.#store) return;
+		const current = await this.#store.findById(id);
+		if (!current) return;
+		const failureCount = result.ok ? 0 : current.failureCount + 1;
+		const now = Date.now();
+		const threshold = this.#config.webhooks.autoDisableThreshold;
+		const disable = !result.ok && threshold > 0 && failureCount >= threshold;
+		const patch = {
+			lastDeliveryAt: now,
+			lastDeliveryStatus: result.status,
+			lastDeliveryError: result.error,
+			failureCount,
+			updatedAt: now,
+			...disable ? { enabled: false } : {}
+		};
+		if (disable) {
+			this.log(`webhook ${id} auto-désactivé après ${failureCount} échecs consécutifs`, "WARNING");
+			this.#audit?.record({
+				category: "webhook",
+				action: "webhook.disabled",
+				outcome: "failure",
+				actor: null,
+				resource: id,
+				reason: "max_failures"
+			});
+		}
+		await this.#store.update(id, patch);
+		this.#endpoints?.set(id, {
+			...current,
+			...patch
+		});
+	}
+	#assertReady() {
+		if (!this.#ready || !this.#store || !this.#key) throw new Error("webhooks indisponibles (désactivés ou mal configurés)");
+	}
+	async #assertSafeUrl(url) {
+		const w = this.#config.webhooks;
+		await assertPublicUrl(url, {
+			allowPrivate: !w.denyPrivateIps,
+			allowHttp: w.allowHttp
+		});
+	}
+	/** Re-contrôle SSRF avant livraison → IP validées à pinner (anti-rebinding). */
+	async #resolveTarget(url) {
+		const w = this.#config.webhooks;
+		const { addresses } = await assertPublicUrl(url, {
+			allowPrivate: !w.denyPrivateIps,
+			allowHttp: w.allowHttp
+		});
+		return addresses;
+	}
+};
+//#endregion
+export { WebhookService, WebhookService as default };

package/dist/nodefony/src/RoleHierarchyWalker.js

@@ -0,0 +1,77 @@
+//#region nodefony/src/RoleHierarchyWalker.ts
+/**
+* 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).
+*/
+var RoleHierarchyWalker = class {
+	#flat = /* @__PURE__ */ new Map();
+	constructor(hierarchy = {}) {
+		this.#detectCycles(hierarchy);
+		this.#precompute(hierarchy);
+	}
+	/**
+	* 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, required) {
+		for (const role of userRoles) {
+			if (role === required) return true;
+			if (this.#flat.get(role)?.has(required)) return true;
+		}
+		return false;
+	}
+	/** Ensemble complet des rôles atteignables (plats + hérités). */
+	reachableRoles(userRoles) {
+		const out = new Set(userRoles);
+		for (const role of userRoles) {
+			const inherited = this.#flat.get(role);
+			if (inherited) for (const r of inherited) out.add(r);
+		}
+		return out;
+	}
+	#precompute(hierarchy) {
+		for (const role of Object.keys(hierarchy)) this.#flat.set(role, this.#flatten(role, hierarchy));
+	}
+	#flatten(role, hierarchy) {
+		const out = /* @__PURE__ */ new Set();
+		const stack = [...hierarchy[role] ?? []];
+		while (stack.length) {
+			const current = stack.pop();
+			if (out.has(current)) continue;
+			out.add(current);
+			const children = hierarchy[current];
+			if (children) for (const child of children) stack.push(child);
+		}
+		return out;
+	}
+	#detectCycles(hierarchy) {
+		const WHITE = 0;
+		const GRAY = 1;
+		const BLACK = 2;
+		const color = /* @__PURE__ */ new Map();
+		const path = [];
+		const visit = (node) => {
+			color.set(node, GRAY);
+			path.push(node);
+			for (const next of hierarchy[node] ?? []) {
+				const c = color.get(next) ?? WHITE;
+				if (c === GRAY) {
+					const start = path.indexOf(next);
+					const cycle = [...path.slice(start), next].join(" → ");
+					throw new Error(`RoleHierarchy: cycle détecté — ${cycle}`);
+				}
+				if (c === WHITE && hierarchy[next]) visit(next);
+			}
+			path.pop();
+			color.set(node, BLACK);
+		};
+		for (const node of Object.keys(hierarchy)) if ((color.get(node) ?? WHITE) === WHITE) visit(node);
+	}
+};
+//#endregion
+export { RoleHierarchyWalker, RoleHierarchyWalker as default };

package/dist/nodefony/src/SecuredArea.js

@@ -0,0 +1,51 @@
+//#region nodefony/src/SecuredArea.ts
+/**
+* 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.
+*/
+var SecuredArea = class {
+	name;
+	pattern;
+	security;
+	stateless;
+	mode;
+	authenticators;
+	host;
+	realtime;
+	resource;
+	constructor(name, config) {
+		this.name = name;
+		this.pattern = new RegExp(config.pattern, "u");
+		this.security = config.security;
+		this.stateless = config.stateless;
+		this.mode = config.mode;
+		this.authenticators = config.authenticators;
+		this.host = config.host;
+		this.realtime = config.realtime;
+		this.resource = config.resource;
+	}
+	/**
+	* 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, host) {
+		if (this.host && this.host !== host) return false;
+		return this.pattern.test(pathname);
+	}
+	/** La requête tombe-t-elle dans cette zone ? (host éventuel + pathname). */
+	match(context) {
+		const req = context.request;
+		if (!req) return false;
+		const rp = req.pathname;
+		if (typeof rp === "string") return this.matchPath(rp, context.domain);
+		if (!req.url) return false;
+		const pathname = req.url instanceof URL ? req.url.pathname : String(req.url);
+		return this.matchPath(pathname, context.domain);
+	}
+};
+//#endregion
+export { SecuredArea, SecuredArea as default };