@nodefony/framework 10.0.0-alpha.3 → 10.0.0-alpha.5

package/README.md

@@ -47,4 +47,4 @@ npm run test:integration # intégration (vitest, serveur dev requis : 5151/5152)
 
 ## Licence
 
-CeCILL-B — Christophe CAMENSULI.
+Apache 2.0 — Christophe CAMENSULI.

package/dist/_virtual/{_@oxc-project_runtime@0.148.0 → _@oxc-project_runtime@0.149.0}/helpers/esm/decorate.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.148.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);

package/dist/_virtual/{_@oxc-project_runtime@0.148.0 → _@oxc-project_runtime@0.149.0}/helpers/esm/decorateMetadata.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.148.0/helpers/esm/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorateMetadata.js
 function __decorateMetadata(k, v) {
 	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }

package/dist/index.js

@@ -7,8 +7,8 @@ import Route from "./nodefony/src/Route.js";
 import Controller from "./nodefony/src/Controller.js";
 import { All, Anonymous, Body, BypassFirewall, Cookie, Csp, CsrfExempt, CsrfProtect, CurrentUser, Delete, Domain, Get, Head, Header, Headers, HttpCode, Idempotent, IsGranted, Options, Param, Patch, Post, Put, Query, Redirect, Req, RequireScope, Res, Scope, Session, UploadedFile, UploadedFiles, UseSession, controller, controllers, route, routeExpectsBodyStream } from "./nodefony/decorators/routerDecorators.js";
 import Resolver from "./nodefony/src/Resolver.js";
-import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
-import __decorate from "./_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import __decorate from "./_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorate.js";
 import router_default from "./nodefony/service/router.js";
 import ResourceController from "./nodefony/src/ResourceController.js";
 import AdminApiController from "./nodefony/controller/AdminApiController.js";
@@ -29,7 +29,7 @@ import { createFrameworkAdminApi } from "./nodefony/src/FrameworkAdminApi.js";
 import { createSyslogAdminApi } from "./nodefony/src/SyslogAdminApi.js";
 import Eta from "./nodefony/service/Eta.js";
 import path from "node:path";
-import { AUTO_STORE, EMPTY_INFRA, Kernel, Module, readStoreLocation, resolveAutoStore, services } from "nodefony";
+import { AUTO_STORE, EMPTY_INFRA, Kernel, Module, durableStoreRemedy, readStoreLocation, resolveAutoStore, runNeedsExternalServices, services } from "nodefony";
 import { mergeResolvers, mergeTypeDefs } from "@graphql-tools/merge";
 import { makeExecutableSchema, mergeSchemas } from "@graphql-tools/schema";
 //#region index.ts
@@ -91,13 +91,13 @@ let Framework = class Framework extends Module {
 		let name = configured;
 		let reason = `store explicitement configuré ("${configured}")`;
 		if (name === AUTO_STORE) {
-			const auto = resolveAutoStore("ephemeral", this.kernel?.infra ?? EMPTY_INFRA, listIdempotencyBackends());
+			const auto = resolveAutoStore("ephemeral", this.kernel?.infra ?? EMPTY_INFRA, listIdempotencyBackends(), "memory", runNeedsExternalServices(this.kernel));
 			name = auto.store;
 			reason = auto.reason;
 			this.log(`idempotency.store "auto" → "${name}" (${auto.reason})`, "INFO");
 		}
 		if (name === "memory") {
-			if (this.kernel?.environment === "production") this.log("idempotency.store \"memory\" en PRODUCTION — déduplication per-pod uniquement : un rejeu routé vers un autre pod n'est pas dédupliqué (double-effet possible). Déclarer une infra partagée (NF_REDIS_URL ou NF_DATABASE_URL).", "WARNING");
+			if (this.kernel?.environment === "production") this.log("idempotency.store \"memory\" en PRODUCTION — déduplication per-pod uniquement : un rejeu routé vers un autre pod n'est pas dédupliqué (double-effet possible). " + durableStoreRemedy(runNeedsExternalServices(this.kernel)), "WARNING");
 			this.kernel?.registerStoreResolution({
 				brick: "idempotency",
 				nature: "ephemeral",

package/dist/nodefony/controller/OAuth2Controller.js

@@ -30,13 +30,22 @@ var OAuth2Controller = class extends Controller {
 		super("OAuth2Controller", context);
 	}
 	/**
-	* Liste PUBLIQUE des fournisseurs activés (configurés ET connus du registre).
-	* Consommé par l'UI de login pour n'afficher QUE les boutons opérationnels —
-	* jamais de bouton mort. Aucun secret n'est exposé (uniquement les noms).
+	* Liste PUBLIQUE des fournisseurs à proposer à l'écran de connexion.
+	*
+	* Rend `{ name, label }` : le libellé vient du serveur, seul à connaître la
+	* configuration — un écran ne doit jamais avoir à deviner comment nommer un
+	* fournisseur, ni s'autoriser à en masquer un qu'il ne reconnaît pas. Un
+	* fournisseur déclaré `hidden` n'y figure pas, mais reste autorisable :
+	* masquer n'est pas désactiver. Aucun secret n'est exposé.
 	*/
 	providers() {
 		const svc = this.#service();
-		return this.renderJson({ providers: svc ? svc.listProviders() : [] });
+		if (!svc) return this.renderJson({ providers: [] });
+		const providers = svc.listDisplayProviders ? svc.listDisplayProviders() : svc.listProviders().map((name) => ({
+			name,
+			label: name
+		}));
+		return this.renderJson({ providers });
 	}
 	/** Démarre le flux : URL d'autorisation + état anti-replay en session, 302. */
 	async authorize(provider) {

package/dist/nodefony/service/AdminBroker.js

@@ -1,5 +1,5 @@
-import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorate.js";
 import router_default from "./router.js";
 import AdminApiController from "../controller/AdminApiController.js";
 import { ADMIN_DEFAULT_ROLE, Module, Service, injectable, resolveAdminRole } from "nodefony";

package/dist/nodefony/service/IdempotencyStore.js

@@ -1,5 +1,5 @@
-import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorate.js";
 import { Module, Service, assertPageQuery, injectable } from "nodefony";
 //#region nodefony/service/IdempotencyStore.ts
 const serviceName = "idempotencyStore";

package/dist/nodefony/service/router.js

@@ -1,8 +1,8 @@
 import Route from "../src/Route.js";
 import { routeExpectsBodyStream } from "../decorators/routerDecorators.js";
 import Resolver from "../src/Resolver.js";
-import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorate.js";
 import { Module, Service, injectable } from "nodefony";
 import { HttpError, isDomainAllowed } from "@nodefony/http";
 //#region nodefony/service/router.ts

package/dist/nodefony/src/KernelAdminApi.js

@@ -2,7 +2,7 @@ import { CORE_PACKAGE, checkOutdated, countModuleDocs, listModuleDocs, listModul
 import { getResolvedPath, navigateSchemaNode, nodeFlags, notEditableReason, recipeFor, validateLeafValue } from "./configMutation.js";
 import { createRequire } from "node:module";
 import { join } from "node:path";
-import { GitService, Syslog, applyResolvedPath, collectDevStatus, computeConfigProvenance, defaultAppConfig, extractJsonSchemaDefaults, extractMarkdownSection, getActiveLogDriver, listLogDrivers, outlineMarkdown, parseNfEnvOverrides } from "nodefony";
+import { GitService, Syslog, aggregateProvenance, applyResolvedPath, collectDevStatus, computeConfigProvenance, defaultAppConfig, extractJsonSchemaDefaults, extractMarkdownSection, flattenConfigSchema, getActiveLogDriver, listLogDrivers, outlineMarkdown, parseNfEnvOverrides, readResolvedPath } from "nodefony";
 import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 //#region nodefony/src/KernelAdminApi.ts
@@ -617,6 +617,63 @@ function createKernelAdminApi(kernel) {
 			summary: "Aggregated config of all modules (effective values redacted + JSON Schema + per-field provenance) for the global config page",
 			handler: async () => ({ modules: buildConfigEntries() })
 		},
+		{
+			path: "config/schema",
+			summary: "Assignable config keys of every module (dotted path, type, default, effective value, provenance, description) — the CATALOG, where `config` gives the STATE",
+			handler: (request) => {
+				const wanted = request.query.module;
+				const filter = typeof wanted === "string" ? wanted.toLowerCase() : null;
+				const rows = [];
+				const entries = buildConfigEntries();
+				const matches = (name, key) => name.toLowerCase() === filter || key.toLowerCase() === filter;
+				if (filter !== null) {
+					const entry = entries.find((e) => matches(e.name, e.key));
+					if (!entry || entry.configSchema == null) {
+						const modules = kernel.getModules();
+						const nameOf = (k) => modules[k].getModuleName?.() ?? k;
+						const loadedKey = Object.keys(modules).find((k) => matches(nameOf(k), k));
+						if (loadedKey !== void 0) {
+							const name = nameOf(loadedKey);
+							return {
+								status: 404,
+								body: {
+									error: "Schema not published",
+									module: name,
+									loaded: true,
+									hint: `Le module ${name} est chargé mais ne publie pas son schéma de configuration : ajouter dans son index.ts \`override configSchema(): unknown { return z.toJSONSchema(schema); }\` (schéma Zod de nodefony/config/config.ts). Sans lui, ses clés sont indécouvrables ici.`
+								}
+							};
+						}
+						return {
+							status: 404,
+							body: {
+								error: "Unknown module",
+								module: wanted,
+								available: entries.map((e) => e.name)
+							}
+						};
+					}
+				}
+				for (const entry of entries) {
+					if (filter !== null && entry.name.toLowerCase() !== filter && entry.key.toLowerCase() !== filter) continue;
+					for (const leaf of flattenConfigSchema(entry.configSchema)) {
+						const path = leaf.key.split(".");
+						const note = SECRET_KEY.test(path[path.length - 1]) && !leaf.note.includes("secret") ? [leaf.note, "secret"].filter(Boolean).join(", ") : leaf.note;
+						rows.push({
+							key: leaf.key,
+							module: entry.name,
+							type: leaf.type,
+							default: leaf.default,
+							effective: readResolvedPath(entry.config, path),
+							source: aggregateProvenance(entry.provenance, leaf.key),
+							note,
+							description: leaf.description
+						});
+					}
+				}
+				return rows;
+			}
+		},
 		{
 			path: "stores",
 			summary: "Runtime persistence stores per brick (resolved store, provenance, available backends) + declared infra",

package/dist/nodefony/src/Resolver.js

@@ -1,6 +1,6 @@
 import { buildParamArgs, computeActionMeta, resolveActionMeta, resolveSessionIntent } from "../decorators/routerDecorators.js";
 import { computeFingerprint, evaluateIdempotency, isMutationMethod, resolveIdempotencyKey, resolveIdentity } from "./idempotency.js";
-import { RequestContext, isArray, isPlainObject, isPromise, nodefonyError, typeOf } from "nodefony";
+import { RequestContext, identityHint, isArray, isPlainObject, isPromise, nodefonyError, typeOf } from "nodefony";
 import { Http2Response, HttpResponse, WebsocketResponse } from "@nodefony/http";
 //#region nodefony/src/Resolver.ts
 /**
@@ -292,7 +292,7 @@ var Resolver = class {
 	async _enforceSecurity(req) {
 		const authz = this.context.container?.get("authorization");
 		const token = RequestContext.get()?.token;
-		if (!authz || token === void 0) throw new nodefonyError("Access denied", 403);
+		if (!authz || token === void 0) throw new nodefonyError(this._accessDenied(!authz ? `aucun moteur d'autorisation n'est posé sur cette requête` : "aucune identité n'est résolue sur cette requête — la route est-elle couverte par une zone du firewall ?"), 403);
 		const clauses = req.clauses;
 		for (let i = 0; i < clauses.length; i++) {
 			const clause = clauses[i];
@@ -303,10 +303,27 @@ var Resolver = class {
 				ok = true;
 				break;
 			}
-			if (!ok) throw new nodefonyError("Access denied", 403);
+			if (!ok) throw new nodefonyError(this._accessDenied("l'identité de cette requête ne porte pas les droits exigés par la route (`@IsGranted`)"), 403);
 		}
 	}
 	/**
+	* Le message d'un refus d'autorisation — augmenté du GESTE en développement.
+	*
+	* Refuser correctement ne suffit pas : celui qui vient d'écrire une route
+	* gardée n'a, sans cela, aucun moyen de l'essayer — mesuré, c'est le premier
+	* poste de coût d'un essai réel. La cause et le geste ne franchissent jamais
+	* la production ({@link identityHint} rend `null` hors développement) : le
+	* message y reste le `Access denied` nu qu'il a toujours été, puisque ces
+	* phrases y renseigneraient l'attaquant autant que le développeur.
+	*
+	* @param cause - ce qui a fait échouer l'autorisation, en clair.
+	* @returns le message à porter par l'erreur 403.
+	*/
+	_accessDenied(cause) {
+		const hint = identityHint(this.context.kernel);
+		return hint === null ? "Access denied" : `Access denied — ${cause}. ${hint}`;
+	}
+	/**
 	* Résout un paramètre de route NOMMÉ (`@IsGranted(..., { subject: "id" })`) vers
 	* sa valeur, depuis `route.variables` (noms) + `this.variables` (valeurs déjà
 	* parsées). 0 alloc (indexOf + accès tableau).

package/dist/types/index.d.ts

@@ -1,5 +1,5 @@
 import { Kernel, Module } from "nodefony";
-import type { FrameworkConfigInput, FrameworkConfig } from "./nodefony/config/config.js";
+import type { IFrameworkConfigInput, IFrameworkConfig } from "./nodefony/config/config.js";
 import { getIdempotencyStoreFactory, registerIdempotencyStore, listIdempotencyStores } from "./nodefony/src/idempotencyStoreRegistry.js";
 import Router from "./nodefony/service/router.js";
 import Route from "./nodefony/src/Route.js";
@@ -28,10 +28,10 @@ import { mergeSchemas, makeExecutableSchema } from "@graphql-tools/schema";
 import { controllers, route, controller, Get, Post, Put, Delete, Patch, Options, Head, All, Domain, BypassFirewall, IsGranted, RequireScope, Anonymous, Csp, CsrfProtect, CsrfExempt, Idempotent, CurrentUser, Scope, UseSession, HttpCode, Header, Redirect, Param, Body, Query, Headers, Cookie, Session, Req, Res, UploadedFile, UploadedFiles, routeExpectsBodyStream } from "./nodefony/decorators/routerDecorators.js";
 declare module "nodefony" {
     interface NodefonyModuleConfig {
-        "@nodefony/framework": FrameworkConfigInput;
+        "@nodefony/framework": IFrameworkConfigInput;
     }
 }
-declare class Framework extends Module<FrameworkConfig> {
+declare class Framework extends Module<IFrameworkConfig> {
     #private;
     constructor(kernel: Kernel);
     /** JSON Schema de la config framework → data plane admin (config riche Studio). */
@@ -91,6 +91,6 @@ export type { ControllerScope } from "./nodefony/src/Controller.js";
 export type { FrameworkAdminApiOptions } from "./nodefony/src/FrameworkAdminApi.js";
 export type { PlaygroundAction, PlaygroundController, PlaygroundGuards, PlaygroundParam, } from "./nodefony/src/PlaygroundAdminApi.js";
 export type { IResourceService, IResourceReadOptions, IResourcePageQuery, } from "./nodefony/src/ResourceController.js";
-export type { FrameworkConfig, FrameworkConfigInput, } from "./nodefony/config/config.js";
+export type { IFrameworkConfig, IFrameworkConfigInput, } from "./nodefony/config/config.js";
 export { defineFrameworkConfig, frameworkConfigJsonSchema, } from "./nodefony/config/defineModuleConfig.js";
 export type { IController, IRoute, IResolver, IAdminBroker, IAdminRoute, IIdempotencyStore, IdempotencyOutcome, IdempotentResponse, } from "./nodefony/interfaces/index.js";

package/dist/types/nodefony/config/config.d.ts

@@ -9,9 +9,9 @@ export declare const frameworkConfigSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 /** Type de sortie (config normalisée + défauts appliqués). */
-export type FrameworkConfig = z.infer<typeof frameworkConfigSchema>;
+export type IFrameworkConfig = z.infer<typeof frameworkConfigSchema>;
 /** Type d'entrée (toutes sections omissibles — défauts du schéma). */
-export type FrameworkConfigInput = z.input<typeof frameworkConfigSchema>;
+export type IFrameworkConfigInput = z.input<typeof frameworkConfigSchema>;
 declare const _default: {
     router?: {
         [x: string]: unknown;

package/dist/types/nodefony/config/defineModuleConfig.d.ts

@@ -1,4 +1,4 @@
-import type { FrameworkConfig, FrameworkConfigInput } from "./config.js";
+import type { IFrameworkConfig, IFrameworkConfigInput } from "./config.js";
 /**
  * Builder type-safe de la configuration de `@nodefony/framework` (PUR — ne
  * retape JAMAIS un défaut : source unique = `./config.ts`).
@@ -18,7 +18,7 @@ import type { FrameworkConfig, FrameworkConfigInput } from "./config.js";
  * @throws BootConfigurationError si la config est invalide ou porte une clé
  *   inconnue — le boot s'interrompt, en dev comme en prod.
  */
-export declare function defineFrameworkConfig(config?: FrameworkConfigInput): FrameworkConfig;
+export declare function defineFrameworkConfig(config?: IFrameworkConfigInput): IFrameworkConfig;
 /**
  * JSON Schema introspectable de la config framework — destiné au formulaire
  * d'édition Studio et à la documentation générée (les flags de champ posés via

package/dist/types/nodefony/controller/OAuth2Controller.d.ts

@@ -8,7 +8,18 @@ import Controller from "../src/Controller.js";
  */
 export interface IOAuth2Service {
     isEnabled(): boolean;
+    /** Fournisseurs OPÉRATIONNELS — la garde de `/authorize`, jamais l'affichage. */
     listProviders(): string[];
+    /**
+     * Fournisseurs à AFFICHER, libellés compris. Optionnel à dessein : le
+     * couplage à `@nodefony/security` se fait par NOM, sans liaison de build —
+     * une version du module qui ne l'expose pas encore doit dégrader, pas
+     * casser l'écran de connexion (repli sur {@link listProviders}).
+     */
+    listDisplayProviders?(): {
+        name: string;
+        label: string;
+    }[];
     getRedirects(provider?: string): {
         success: string;
         failure: string;
@@ -63,9 +74,13 @@ declare class OAuth2Controller extends Controller {
     #private;
     constructor(context: ContextType);
     /**
-     * Liste PUBLIQUE des fournisseurs activés (configurés ET connus du registre).
-     * Consommé par l'UI de login pour n'afficher QUE les boutons opérationnels —
-     * jamais de bouton mort. Aucun secret n'est exposé (uniquement les noms).
+     * Liste PUBLIQUE des fournisseurs à proposer à l'écran de connexion.
+     *
+     * Rend `{ name, label }` : le libellé vient du serveur, seul à connaître la
+     * configuration — un écran ne doit jamais avoir à deviner comment nommer un
+     * fournisseur, ni s'autoriser à en masquer un qu'il ne reconnaît pas. Un
+     * fournisseur déclaré `hidden` n'y figure pas, mais reste autorisable :
+     * masquer n'est pas désactiver. Aucun secret n'est exposé.
      */
     providers(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
     /** Démarre le flux : URL d'autorisation + état anti-replay en session, 302. */

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

@@ -38,6 +38,38 @@ export interface IConfigEntry {
      */
     overriddenBy: Record<string, string>;
 }
+/**
+ * Une clé assignable du catalogue de configuration — ce qu'on a le DROIT
+ * d'écrire, par opposition à {@link IConfigEntry} qui dit ce QUI EST écrit.
+ *
+ * Les noms de champs deviennent les en-têtes de colonnes de
+ * `nodefony inspect schema`, et les clés du JSON qu'un agent filtre.
+ */
+export interface ISchemaCatalogRow {
+    /**
+     * Chemin pointé de la clé (`certificates.selfSigned.hash`).
+     *
+     * EN PREMIER, et ce n'est pas cosmétique : le rendu tient la première
+     * colonne pour l'identité de la ligne et ne l'élague jamais, quand il retire
+     * les suivantes si elles valent partout pareil. `module` d'abord aurait donc
+     * fait répéter le nom du module sur les cent fiches d'un lot filtré.
+     */
+    key: string;
+    /** Nom de paquet du module qui porte la clé, tel qu'on l'écrit dans `use()`. */
+    module: string;
+    /** Type déclaré, ou les valeurs de l'énumération quand il y en a une. */
+    type: string;
+    /** Défaut du schéma — `undefined` si le schéma n'en pose aucun. */
+    default?: unknown;
+    /** Valeur résolue au boot, secrets déjà REDACTÉS par `computeConfigEntry`. */
+    effective: unknown;
+    /** D'où vient la valeur effective : `default`, `app`, `env` ou `runtime`. */
+    source: string;
+    /** Ce que les métadonnées disent de la clé (`réservé`, `secret`…), vide sinon. */
+    note: string;
+    /** La phrase du schéma (`.describe()`) — c'est elle qu'on venait chercher. */
+    description: string;
+}
 /**
  * Paquets à essayer pour une clé de module, **dans l'ordre**, et bornés au
  * périmètre du framework.

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

@@ -142,6 +142,20 @@ declare class Resolver implements IResolver {
      * @throws nodefonyError 403 si l'accès est refusé.
      */
     private _enforceSecurity;
+    /**
+     * Le message d'un refus d'autorisation — augmenté du GESTE en développement.
+     *
+     * Refuser correctement ne suffit pas : celui qui vient d'écrire une route
+     * gardée n'a, sans cela, aucun moyen de l'essayer — mesuré, c'est le premier
+     * poste de coût d'un essai réel. La cause et le geste ne franchissent jamais
+     * la production ({@link identityHint} rend `null` hors développement) : le
+     * message y reste le `Access denied` nu qu'il a toujours été, puisque ces
+     * phrases y renseigneraient l'attaquant autant que le développeur.
+     *
+     * @param cause - ce qui a fait échouer l'autorisation, en clair.
+     * @returns le message à porter par l'erreur 403.
+     */
+    private _accessDenied;
     /**
      * Résout un paramètre de route NOMMÉ (`@IsGranted(..., { subject: "id" })`) vers
      * sa valeur, depuis `route.variables` (noms) + `this.variables` (valeurs déjà

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

@@ -1,5 +1,5 @@
 import type { Module, IIdempotencyStore } from "nodefony";
-import type { FrameworkConfig } from "../config/config.js";
+import type { IFrameworkConfig } from "../config/config.js";
 /**
  * Registre de **fabriques de stores d'idempotence DISTRIBUÉS** — résout le nom
  * configuré (`framework.idempotency.store`) vers une instance d'
@@ -29,7 +29,7 @@ export interface IIdempotencyStoreFactoryContext {
     /** Module framework (porte `kernel.container` pour résoudre `redis`, etc.). */
     readonly module: Module;
     /** Config framework validée + gelée. */
-    readonly config: FrameworkConfig;
+    readonly config: IFrameworkConfig;
 }
 /** Fabrique d'un store d'idempotence pour un nom donné. */
 export type IdempotencyStoreFactory = (ctx: IIdempotencyStoreFactoryContext) => IIdempotencyStore;

package/docs/controller.md

@@ -310,7 +310,7 @@ action se tromperait d'objet.
 > frame 2 — pratique pour un état de conversation, piège si tu comptais sur une instance neuve. En
 > HTTP, l'inverse : chaque requête repart d'une instance vierge.
 
-Côté WebSocket, l'ordre est encore plus marqué : `HttpKernel.onConnect()` (`http-kernel.ts:1659`)
+Côté WebSocket, l'ordre est encore plus marqué : `HttpKernel.onConnect()` (`http-kernel.ts:1702`)
 appelle `handleFrontController()` (donc `initialize()`) **avant** `startSession()`
 (`http-kernel.ts:1131`), avant l'acceptation de la socket, et avant le firewall
 (`http-kernel.ts:1457`).
@@ -326,11 +326,11 @@ sont des accesseurs qui dérivent du contexte **vivant**, selon le motif `champ
 | `this.route`     | La route matchée                                   | `Controller.ts:158` |
 | `this.request`   | La requête (HTTP, HTTP/2 ou WS)                    | `Controller.ts:162` |
 | `this.response`  | La réponse du transport                            | `Controller.ts:169` |
-| `this.method`    | La méthode HTTP (ou `WEBSOCKET`)                   | `Controller.ts:178` |
-| `this.queryGet`  | Les paramètres de la query string                  | `Controller.ts:187` |
-| `this.queryPost` | Le corps parsé                                     | `Controller.ts:214` |
-| `this.body`      | Le corps parsé — alias de `queryPost`              | `Controller.ts:229` |
-| `this.queryFile` | Les fichiers uploadés                              | `Controller.ts:205` |
+| `this.method`    | La méthode HTTP (ou `WEBSOCKET`)                   | `Controller.ts:212` |
+| `this.queryGet`  | Les paramètres de la query string                  | `Controller.ts:221` |
+| `this.queryPost` | Le corps parsé                                     | `Controller.ts:248` |
+| `this.body`      | Le corps parsé — alias de `queryPost`              | `Controller.ts:248` |
+| `this.queryFile` | Les fichiers uploadés                              | `Controller.ts:239` |
 | `this.session`   | La session **ou `null`** si elle n'est pas activée | `Controller.ts:229` |
 
 Pourquoi des accesseurs plutôt que des champs recopiés au constructeur : **la fraîcheur et le coût**.
@@ -349,16 +349,16 @@ n'est créée** — donc aucun coût de stockage.
 Deux corollaires :
 
 - Dans `initialize()`, `this.session` vaut `null` (l'activation vient plus tard — étape 6 du cycle).
-- `this.getSession()` (`Controller.ts:394`) ne « démarre » rien : il retourne la session existante,
+- `this.getSession()` (`Controller.ts:496`) ne « démarre » rien : il retourne la session existante,
   ou `undefined`.
 
-Les messages flash s'appuient dessus : `setFlashBag()`/`addFlash()` (`Controller.ts:420`) et
-`getFlashBag()` (`Controller.ts:412`) journalisent une **erreur** et retournent `null` si aucune
+Les messages flash s'appuient dessus : `setFlashBag()`/`addFlash()` (`Controller.ts:530`) et
+`getFlashBag()` (`Controller.ts:514`) journalisent une **erreur** et retournent `null` si aucune
 session n'est active — pas de crash, mais rien n'est mémorisé.
 
 ### Contrôleur `singleton` — quand `this` n'est plus à toi
 
-Par défaut, `Controller.scope` vaut `"request"` (`Controller.ts:119`). Un contrôleur **sans état**
+Par défaut, `Controller.scope` vaut `"request"` (`Controller.ts:196`). Un contrôleur **sans état**
 peut passer en instance unique partagée :
 
 ```typescript
@@ -399,14 +399,14 @@ de ce que tu as retourné :
 | Un `number` / un `boolean` | Auto-JSON scalaire (RFC 8259 §2 : `42`, `true` sont des documents valides) | `Resolver.ts:734` |
 | Un `Buffer` | Envoyé brut | `Resolver.ts:723` |
 | Une `Response` (via un `render*`) | Retournée telle quelle — l'envoi a déjà eu lieu | `Resolver.ts:716` |
-| `void`/`null` **et** statut 204/205/304 | Réponse **vide envoyée** (RFC 9110 : ces statuts n'ont pas de corps) | `NO_BODY_STATUS` (`Resolver.ts:798`) |
+| `void`/`null` **et** statut 204/205/304 | Réponse **vide envoyée** (RFC 9110 : ces statuts n'ont pas de corps) | `NO_BODY_STATUS` (`Resolver.ts:855`) |
 | `void`/`null` avec tout autre statut | `waitAsync` : « l'action enverra plus tard » | `Resolver.ts:801` |
 | Une instance de classe (entité ORM, DTO) | **Non sérialisée** → `waitAsync` (le teardown avertit du blocage) | `Resolver.ts:770-777` |
 
 > [!WARNING]
 > **Le piège n° 1 : `return null` sur un statut à corps.** Le framework l'interprète comme « je
 > répondrai moi-même » et attend — jusqu'au timeout. La distinction se fait sur le **statut** :
-> `NO_BODY_STATUS` (`Resolver.ts:817`) contient 204, 205 et 304. Donc un `@Delete` qui fait
+> `NO_BODY_STATUS` (`Resolver.ts:855`) contient 204, 205 et 304. Donc un `@Delete` qui fait
 > `@HttpCode(204)` puis `return null` répond bien 204 vide ; le même `return null` sans `@HttpCode`
 > laisse la requête pendue.
 
@@ -420,19 +420,19 @@ Quand tu veux piloter l'envoi plutôt que retourner une valeur :
 | Helper                                       | Pour…                                                    | Ancre               |
 | -------------------------------------------- | -------------------------------------------------------- | ------------------- |
 | `renderJson(obj, status?, headers?)`         | JSON explicite avec statut/en-têtes                      | `Controller.ts:379` |
-| `render(data, encoding?, status?, headers?)` | Envoyer un corps quelconque via le contexte              | `Controller.ts:273` |
-| `renderView(path, params, status?)`          | Rendre un template **Eta** (avec les helpers frontend)   | `Controller.ts:308` |
-| `renderResponse(data, encoding?, …)`         | Poser statut + en-têtes, puis envoyer                    | `Controller.ts:290` |
+| `render(data, encoding?, status?, headers?)` | Envoyer un corps quelconque via le contexte              | `Controller.ts:377` |
+| `renderView(path, params, status?)`          | Rendre un template **Eta** (avec les helpers frontend)   | `Controller.ts:410` |
+| `renderResponse(data, encoding?, …)`         | Poser statut + en-têtes, puis envoyer                    | `Controller.ts:392` |
 | `redirect(url, status?, headers?)`           | Rediriger                                                | `Controller.ts:382` |
 | `forward("module:controller:action")`        | Déléguer à une autre action **sans** aller-retour réseau | `Controller.ts:432` |
-| `setContextJson()` / `setContextHtml()`      | Choisir le type de contenu avant d'envoyer               | `Controller.ts:282` |
+| `setContextJson()` / `setContextHtml()`      | Choisir le type de contenu avant d'envoyer               | `Controller.ts:319` |
 
 `renderView()` mesure sa propre phase `render` et injecte automatiquement les aides frontend
 (`frontendTags`, `frontendDocument`, `asset`) dans les variables du template
-(`withFrontendLocals()`, `Controller.ts:345`) — tes propres valeurs restent prioritaires.
+(`withFrontendLocals()`, `Controller.ts:448`) — tes propres valeurs restent prioritaires.
 
 `forward()` re-résout un contrôleur sur le **même** contexte et rappelle son action
-(`Controller.ts:445`) : c'est une délégation interne, la requête cliente reste unique.
+(`Controller.ts:534`) : c'est une délégation interne, la requête cliente reste unique.
 
 > [!TIP]
 > **Redirection : le code par défaut est 302** (Found), pas 301. Un statut absent ou hors de la liste
@@ -448,7 +448,7 @@ Deux besoins distincts, deux helpers.
 
 `renderFileDownload(file, options?, headers?)` (`Controller.ts:473`) pose
 `Content-Disposition: attachment`, `Content-Length`, le type MIME du fichier, puis délègue au moteur
-de flux. Le fichier est résolu **sans bloquer l'event loop** (`getFileAsync()`, `Controller.ts:497`) ;
+de flux. Le fichier est résolu **sans bloquer l'event loop** (`getFileAsync()`, `Controller.ts:586`) ;
 la variante synchrone `getFile()` existe encore mais est marquée obsolète — elle appelle `lstatSync`
 et gèle le process le temps du stat.
 
@@ -465,12 +465,12 @@ plage** (RFC 9110 §14), ce qui permet à un lecteur vidéo de sauter dans le fl
 | Plage hors fichier                            | **416** + `Content-Range: bytes */<taille>` (RFC 9110 §15.5.17) |
 | Syntaxe invalide, multi-plage, unité inconnue | En-tête **ignoré** → 200 complet (jamais un 500)                |
 
-La logique est isolée dans une fonction pure exportée, `parseByteRange()` (`Controller.ts:73`) —
+La logique est isolée dans une fonction pure exportée, `parseByteRange()` (`Controller.ts:107`) —
 donc testable sans serveur.
 
 ### Ce que `streamFile()` garantit
 
-`streamFile()` (`Controller.ts:580`) est le moteur commun. Sa subtilité n'est pas le pipe, c'est le
+`streamFile()` (`Controller.ts:669`) est le moteur commun. Sa subtilité n'est pas le pipe, c'est le
 **nettoyage** : le flux est ouvert avec `autoClose: false`, et un client qui raccroche en plein
 téléchargement laisserait sinon un descripteur de fichier ouvert et une promesse pendue à jamais. Un
 écouteur `close` sur la réponse détruit le flux, ce qui déclenche la fermeture du descripteur et
@@ -578,9 +578,9 @@ code du framework applique — et attend de toi — les règles suivantes :
 
 | Domaine                          | Norme                    | Comment le code s'y conforme                                   |
 | -------------------------------- | ------------------------ | -------------------------------------------------------------- |
-| Statuts sans corps (204/205/304) | RFC 9110 §15.3.5/§15.4.5 | `NO_BODY_STATUS` (`Resolver.ts:817`)                           |
-| Requêtes par plage               | RFC 9110 §14.1.2, §14.2  | `parseByteRange()` (`Controller.ts:73`)                        |
-| Plage insatisfiable → 416        | RFC 9110 §15.5.17        | `renderResponse()` avec 416 (`Controller.ts:304`)              |
+| Statuts sans corps (204/205/304) | RFC 9110 §15.3.5/§15.4.5 | `NO_BODY_STATUS` (`Resolver.ts:855`)                           |
+| Requêtes par plage               | RFC 9110 §14.1.2, §14.2  | `parseByteRange()` (`Controller.ts:107`)                       |
+| Plage insatisfiable → 416        | RFC 9110 §15.5.17        | `renderResponse()` avec 416 (`Controller.ts:392`)              |
 | Redirections                     | RFC 9110 §15.4           | Liste blanche + repli 302 (`Response.ts:534`)                  |
 | Média JSON sans `charset`        | RFC 8259 §11             | Auto-JSON (`Resolver.ts:760`), vérifié par le banc `auto-json` |
 | Scalaire JSON de premier niveau  | RFC 8259 §2              | `number`/`boolean` rendus (`Resolver.ts:734`)                  |
@@ -610,7 +610,7 @@ code du framework applique — et attend de toi — les règles suivantes :
 | WS : l'état d'une frame « bave » sur la suivante | L'instance est partagée par toute la connexion (`Resolver.ts:262`) | Réinitialiser l'état en tête d'action, ou le porter par message |
 | WS : l'action n'est jamais appelée | Route sans transport `WEBSOCKET` déclaré | `requirements: { methods: ["WEBSOCKET"] }` |
 | Contrôleur `singleton` : données d'un autre utilisateur | Champ mutable per-requête sur une instance partagée | Retirer `@Scope("singleton")`, ou passer par les arguments décorés |
-| Event loop figé sur une route de fichier | `getFile()` synchrone (`lstatSync`, `Controller.ts:457`) | Utiliser `getFileAsync()` (`Controller.ts:472`) |
+| Event loop figé sur une route de fichier | `getFile()` synchrone (`lstatSync`, `Controller.ts:546`) | Utiliser `getFileAsync()` (`Controller.ts:586`) |
 
 ## 🧪 Tests & couverture
 

package/docs/decorateurs.md

@@ -298,7 +298,7 @@ d'écriture (`routerDecorators.ts:281`) — sinon un attrape-tout masquerait les
 **`@Scope("singleton")` est un contrat, pas une optimisation.** L'instance étant partagée, l'action
 ne doit lire ni écrire **aucun** état de requête sur `this` : tout passe par les arguments décorés et
 les accesseurs, qui retrouvent la requête courante via l'ALS. Le défaut reste `"request"` — une
-instance par requête (`ControllerScope`, `Controller.ts:110`).
+instance par requête (`ControllerScope`, `Controller.ts:144`).
 
 > [!NOTE]
 > Le core `nodefony` exporte lui aussi un `Scope` (les portées du conteneur d'injection). Celui des
@@ -455,12 +455,12 @@ ne s'auto-promeut pas.
 | `@Header("X-Foo", "bar")` | méthode | Ajoute un en-tête ; **s'empile** (plusieurs `@Header` cumulent, `routerDecorators.ts:580`) | `@Header("Cache-Control","no-store")` |
 | `@Redirect("/url", 302)`  | méthode | Redirige **si** l'action ne renvoie rien (`Redirect()`, `routerDecorators.ts:589`)         | `@Redirect("/login", 302)`            |
 
-Les deux premiers sont appliqués par `Resolver._applyResponseMeta()` (`Resolver.ts:650`) **avant**
+Les deux premiers sont appliqués par `Resolver._applyResponseMeta()` (`Resolver.ts:687`) **avant**
 l'appel de l'action : ton code peut donc les écraser ensuite (`this.renderJson(data, 202)` gagne).
 
 `@Redirect` a une subtilité utile : si l'action **retourne un objet** portant `url` (et
 éventuellement `statusCode`), cet objet **prend le dessus** sur les valeurs du décorateur
-(`Resolver._handleRedirect()`, `Resolver.ts:666`) — la cible peut donc être calculée à l'exécution :
+(`Resolver._handleRedirect()`, `Resolver.ts:703`) — la cible peut donc être calculée à l'exécution :
 
 ```typescript
 @Get("/go")
@@ -620,7 +620,7 @@ Trois faits à retenir :
 - **Les décorateurs de paramètre fonctionnent pareil.** Pour une invocation par socket, le corps de
   la mutation voyage dans l'ALS et **prime** sur le corps HTTP (vide dans ce cas) — c'est traité dans
   `resolveParamArg()` (`routerDecorators.ts:1283`), et `@Query` lit la query du chemin **invoqué**,
-  pas celle du handshake (`Resolver._buildParamArgs()`, `Resolver.ts:637`).
+  pas celle du handshake (`Resolver._buildParamArgs()`, `Resolver.ts:656`).
 - **Les gardes s'appliquent identiquement.** `@IsGranted` protège une action joignable par socket
   exactement comme une action HTTP : la décision est prise avant l'instanciation, quel que soit le
   transport.
@@ -708,7 +708,7 @@ Le `Resolver` consomme ce snapshot dans un ordre qui a du sens sécurité :
 **garde d'abord, instanciation ensuite**. `security !== null` déclenche
 `_enforceSecurity()` (`Resolver.ts:576`) **avant** `newController()` — un `403` n'instancie pas le
 contrôleur et n'exécute pas son `initialize()`. Puis viennent les arguments
-(`_buildParamArgs()`, `Resolver.ts:619`), les métadonnées de réponse
+(`_buildParamArgs()`, `Resolver.ts:656`), les métadonnées de réponse
 (`_applyResponseMeta()`, `Resolver.ts:650`), l'action, et enfin la redirection éventuelle.
 
 Un usage cold path mérite d'être connu : `extractActionScopes()` (`routerDecorators.ts:1476`) parcourt

package/docs/idempotence.md

@@ -345,7 +345,7 @@ Source unique = schéma Zod `idempotencySchema`
 ### Comment `store: "auto"` se résout VRAIMENT
 
 `Framework.onKernelBoot()` (`src/packages/@nodefony/framework/index.ts:189`) délègue à
-`resolveAutoStore("ephemeral", …)` (`src/nodefony/src/config/infra.ts:241`), borné aux backends
+`resolveAutoStore("ephemeral", …)` (`src/nodefony/src/config/infra.ts:289`), borné aux backends
 **réellement enregistrés** (`listIdempotencyBackends()`, `idempotencyStoreRegistry.ts:81`). L'ordre
 réel est le suivant :
 

package/docs/routing.md

@@ -114,7 +114,7 @@ mêmes décorateurs.
 
 **Le routeur passe avant les fichiers statiques.** Une requête qui correspond à une route ne paie
 jamais le `stat` du serveur de fichiers : le repli statique n'est tenté que si la résolution a échoué
-(`serverStatic.handle()`, `http-kernel.ts:1200`).
+(`serverStatic.handle()`, `http-kernel.ts:725`).
 
 > [!NOTE]
 > **Le routage n'a aucune option de configuration.** Le schéma Zod du module n'expose qu'un sac
@@ -569,7 +569,7 @@ alloué par requête.
 | Cible identifiée par l'URI, hôte compris | RFC 9110 §7.2     | hôte vérifié avant la méthode (`Route.match()`, `Route.ts:298`) |
 | 403 sur ressource d'un autre vhost       | RFC 9110 §15.5.4  | `Route.matchHostname()` (`Route.ts:605`)                        |
 | 404 quand rien ne correspond             | RFC 9110 §15.5.5  | après repli statique (`http-kernel.ts:688`)                     |
-| 421 sur `Host` non servi                 | RFC 9110 §15.5.20 | `checkValidDomain()` (`http-kernel.ts:1697`)                    |
+| 421 sur `Host` non servi                 | RFC 9110 §15.5.20 | `checkValidDomain()` (`http-kernel.ts:1740`)                    |
 | Erreur de sous-protocole WS = 1002       | RFC 6455 §7.4     | `Route.matchRequirements()` (`Route.ts:649`)                    |
 | Décodage pourcent des segments           | RFC 3986 §2.1     | `decode()` (`Route.ts:79`)                                      |