@nodefony/framework 10.0.0-alpha.1

package/dist/nodefony/decorators/routerDecorators.js

@@ -0,0 +1,967 @@
+import Controller from "../src/Controller.js";
+import router_default from "../service/router.js";
+import { RequestContext } from "nodefony";
+import "reflect-metadata";
+//#region nodefony/decorators/routerDecorators.ts
+const metadataKey = "routes:definitions";
+/**
+* Noms déjà portés par `Controller` — méthodes ET accesseurs, les siens comme
+* ceux hérités de `Service`. Une action qui en reprend un est refusée à la
+* déclaration (cf `assertActionNameFree`).
+*
+* Résolu PARESSEUSEMENT, et une seule fois : `Controller` participe à un cycle
+* d'import (`Controller` → `Router` → ce module), le lire au chargement du
+* module tomberait dans sa zone morte temporelle. Au premier décorateur d'un
+* controller userland, la classe de base est forcément déjà initialisée.
+*
+* @returns Map `nom → classe qui le porte` (la plus DÉRIVÉE des deux gagne).
+*/
+let reservedActionNames = null;
+const getReservedActionNames = () => {
+	if (reservedActionNames) return reservedActionNames;
+	const reserved = /* @__PURE__ */ new Map();
+	let proto = Controller.prototype;
+	while (proto && proto !== Object.prototype) {
+		const owner = proto.constructor?.name ?? "Controller";
+		for (const key of Object.getOwnPropertyNames(proto)) if (key !== "constructor" && !reserved.has(key)) reserved.set(key, owner);
+		proto = Object.getPrototypeOf(proto);
+	}
+	reservedActionNames = reserved;
+	return reserved;
+};
+/**
+* Refuse, AU MOMENT DE LA DÉCLARATION, une action dont le nom est déjà celui
+* d'un membre de `Controller`.
+*
+* Le langage sanctionne déjà ce conflit, mais tard et sans le nommer : un
+* `remove()` de controller produit un `TS2416` sur une incompatibilité de
+* signature (`Service.remove(name): boolean`), et un `session()` ne produit
+* rien du tout — l'accesseur de la classe de base masque simplement l'action à
+* l'instanciation. La règle posée ici est volontairement plus stricte que
+* TypeScript (elle refuse le nom, sans regarder les signatures) : une règle
+* qu'on peut énoncer en une phrase vaut mieux qu'une règle exacte que
+* personne ne peut anticiper.
+*
+* @param target - Le prototype de la classe qui déclare l'action.
+* @param propertyKey - Le nom de la méthode décorée.
+* @throws Error nommant le membre en conflit et la sortie (renommer l'action).
+*/
+function assertActionNameFree(target, propertyKey) {
+	if (!Object.prototype.isPrototypeOf.call(Controller.prototype, target)) return;
+	const owner = getReservedActionNames().get(propertyKey);
+	if (!owner) return;
+	const className = target.constructor?.name ?? "(anonyme)";
+	throw new Error(`Action « ${propertyKey} » de ${className} : ce nom est RÉSERVÉ par le framework — ${owner} porte déjà un membre « ${propertyKey} », dont tout controller hérite. Le conflit casse la compilation (TS2416) ou masque silencieusement l'action. Renommez la méthode (« ${propertyKey}Action », « ${propertyKey}One »…) : l'URL vient du décorateur, pas du nom de la méthode — seul le nom généré de la route suit (« ${className}::${propertyKey} »).`);
+}
+/**
+* Rattache un ou plusieurs contrôleurs à un module, dont ils suivent le cycle de vie.
+*
+* Décorateur de **classe de module**. L'enregistrement n'a pas lieu à
+* l'évaluation du décorateur mais au hook `onBoot` du kernel : tant que le boot
+* n'a pas eu lieu, les routes déclarées par `@route` sur ces classes n'existent
+* pas encore dans le routeur — un test qui interroge le routeur sans booter ne
+* verra rien. L'enregistrement est tagué au nom du module, de sorte qu'un échec
+* désigne le module fautif au lieu d'un contrôleur anonyme.
+*
+* @param controller - Un contrôleur, ou un tableau de contrôleurs, à rattacher.
+* @returns Le décorateur de classe, qui renvoie le module enrichi du hook.
+* @example
+* ```typescript
+* @controllers([DefaultController, RestController])
+* class TestModule extends Module {}
+* ```
+*/
+function controllers(targets) {
+	return function(constructor) {
+		class NewConstructorControllers extends constructor {
+			constructor(...args) {
+				super(...args);
+				this.hookKernel("onBoot", async () => {
+					return this.initDecoratorControllers();
+				});
+			}
+			async initDecoratorControllers() {
+				const log = (contr) => {
+					router_default.setController(contr, this);
+					this.log(`ADD CONTROLLER : ${contr.name}`, "DEBUG");
+					const declared = router_default.getRoutesForController(contr);
+					if (this.kernel?.debug) for (const r of declared) this.log(`route + ${r.toLogLine()}`, "DEBUG");
+					for (const r of declared) if (r.unreachableChars) this.log(`route INATTEIGNABLE : ${r.name} — le chemin « ${r.path} » contient ${r.unreachableChars.map((c) => `« ${c} »`).join(", ")}, qu'une requête ne porte jamais (encodé par l'analyseur d'URL, ou pris pour un délimiteur). Cette route ne répondra à rien.`, "WARNING");
+				};
+				if (Array.isArray(targets)) for (const contr of targets) log(contr);
+				else log(targets);
+			}
+		}
+		return NewConstructorControllers;
+	};
+}
+/**
+* Declaration Controller
+*
+* @param prefix - prefixage du router du controller.
+* @param options - Les options .
+* @returns Un décorateur de méthode qui peut être utilisé pour annoter une méthode de contrôleur.
+*
+* @example
+* \@controller("/openapi")
+* \@UseSession()
+*  class OpenApiController extends Controller {
+*    constructor(context: Context) {
+*       super("OpenApiController", context);
+*    }
+*    \@route("index-openapi", { path: "" })
+*     index() {
+*      this.render({});
+*    }
+*  }
+*/
+function controller(prefix) {
+	return function(mycontroller) {
+		mycontroller.prefix = prefix;
+		const metadata = Reflect.getMetadata(metadataKey, mycontroller) || {};
+		if (metadata && Object.keys(metadata).length !== 0) {
+			let hasMagic = false;
+			for (const name in metadata) {
+				const options = metadata[name];
+				options.prefix = prefix;
+				if (options.host === void 0) {
+					const methodDomain = Reflect.getMetadata(DOMAIN_METHOD_METADATA, mycontroller, options.classMethod);
+					const classDomain = Reflect.getMetadata(DOMAIN_CLASS_METADATA, mycontroller);
+					const domain = methodDomain ?? classDomain;
+					if (domain) options.host = domain;
+				}
+				if (options.bypassFirewall !== true) {
+					const methodBypass = Reflect.getMetadata(BYPASS_FIREWALL_METHOD_METADATA, mycontroller, options.classMethod);
+					const classBypass = Reflect.getMetadata(BYPASS_FIREWALL_CLASS_METADATA, mycontroller);
+					if (methodBypass === true || classBypass === true) options.bypassFirewall = true;
+				}
+				if (options.path == "*") {
+					hasMagic = {
+						options,
+						name
+					};
+					continue;
+				}
+				router_default.createRoute(name, options);
+			}
+			if (hasMagic) router_default.createRoute(hasMagic.name, hasMagic.options);
+		}
+		Reflect.deleteMetadata(metadataKey, mycontroller);
+		return mycontroller;
+	};
+}
+/**
+* Crée une route avec le nom et les options spécifiés.
+*
+* @param name - Le nom de la route.
+* @param options - Les options de la route.
+* @returns Un décorateur de méthode qui peut être utilisé pour annoter une méthode de contrôleur.
+*
+* @example
+* \@route("myroute", {
+*   path: "/add/{name}",
+*   method: ["GET", "POST"],
+*   defaults: { name: "john" },
+* })
+* method(name: string) {
+*   return this.renderJson({ name });
+* }
+*/
+function route(name, options) {
+	return function(target, propertyKey, descriptor) {
+		assertActionNameFree(target, propertyKey);
+		const className = target.constructor.name;
+		const classMethod = propertyKey;
+		const prefix = options.prefix || null;
+		const path = options.path || "";
+		let filePath;
+		try {
+			const stackTrace = (/* @__PURE__ */ new Error()).stack?.split("\n").slice(2);
+			if (!stackTrace) throw new Error("Erreur lors de l'obtention de la pile d'appels.");
+			const controllerFilePath = extractControllerFilePath(stackTrace);
+			if (!controllerFilePath) throw new Error("Fichier de contrôleur non trouvé dans la pile d'appels.");
+			filePath = controllerFilePath;
+		} catch (error) {
+			filePath = error;
+		}
+		const metadata = Reflect.getMetadata(metadataKey, target.constructor) || {};
+		metadata[name] = {
+			path,
+			filePath,
+			constructor: target.constructor,
+			prefix,
+			className,
+			classMethod,
+			method: options.method,
+			host: options.host,
+			defaults: options.defaults,
+			requirements: options.requirements,
+			bypassFirewall: options.bypassFirewall
+		};
+		Reflect.defineMetadata(metadataKey, metadata, target.constructor);
+		return descriptor;
+	};
+}
+function extractControllerFilePath(stackTrace) {
+	for (const line of stackTrace) {
+		const match = line.match(/\s+at file:\/\/(.*\/controllers?\/.*\.js)/);
+		if (match && match[1]) return match[1];
+	}
+}
+const HTTP_CODE_METADATA = "route:httpCode";
+const HEADERS_METADATA = "route:responseHeaders";
+const REDIRECT_METADATA = "route:redirect";
+const PARAM_ARGS_METADATA = "route:paramArgs";
+const DOMAIN_CLASS_METADATA = "route:domainClass";
+const DOMAIN_METHOD_METADATA = "route:domainMethod";
+const BYPASS_FIREWALL_CLASS_METADATA = "route:bypassFirewallClass";
+const BYPASS_FIREWALL_METHOD_METADATA = "route:bypassFirewallMethod";
+const SECURITY_CLAUSES_METADATA = "nodefony:security:clauses";
+const SECURITY_ANONYMOUS_METADATA = "nodefony:security:anonymous";
+const SECURITY_SCOPES_METADATA = "nodefony:security:scopes";
+const CSP_DIRECTIVES_METADATA = "nodefony:csp:directives";
+const CSRF_PROTECT_METADATA = "nodefony:csrf:protect";
+const CSRF_EXEMPT_METADATA = "nodefony:csrf:exempt";
+const IDEMPOTENT_METADATA = "nodefony:idempotent";
+const USE_SESSION_CLASS_METADATA = "session:useClass";
+const USE_SESSION_METHOD_METADATA = "session:useMethod";
+function httpMethodDecorator(methods) {
+	return function(path = "", options = {}) {
+		return function(target, propertyKey, descriptor) {
+			const name = `${target.constructor.name}::${propertyKey}`;
+			const declaredMethods = options.requirements?.methods;
+			const added = declaredMethods === void 0 ? [] : Array.isArray(declaredMethods) ? declaredMethods : [declaredMethods];
+			const fusion = added.length > 0 ? [.../* @__PURE__ */ new Set([...methods, ...added])] : methods;
+			return route(name, {
+				...options,
+				path,
+				requirements: {
+					...options.requirements,
+					methods: fusion
+				}
+			})(target, propertyKey, descriptor);
+		};
+	};
+}
+const Get = httpMethodDecorator(["GET"]);
+const Post = httpMethodDecorator(["POST"]);
+const Put = httpMethodDecorator(["PUT"]);
+const Delete = httpMethodDecorator(["DELETE"]);
+const Patch = httpMethodDecorator(["PATCH"]);
+const Options = httpMethodDecorator(["OPTIONS"]);
+const Head = httpMethodDecorator(["HEAD"]);
+/**
+* `@All` — route sans restriction de méthode : matche **toutes** les méthodes
+* HTTP (équivalent NestJS `@All()`). N'émet aucun requirement `methods`, donc
+* `Route.matchRequirements` ne lève jamais 405 sur la méthode.
+*/
+function All(path = "", options = {}) {
+	return function(target, propertyKey, descriptor) {
+		return route(`${target.constructor.name}::${propertyKey}`, {
+			...options,
+			path
+		})(target, propertyKey, descriptor);
+	};
+}
+/**
+* Fixe le code de statut HTTP de la réponse d'une action.
+*
+* Décorateur de **méthode**. Le code est posé sur la réponse **avant** que le
+* corps de l'action ne s'exécute (`Resolver._applyResponseMeta`) : l'action
+* garde donc le dernier mot et peut encore le remplacer. Emploie-le pour le
+* statut nominal d'une action — un 201 sur une création — et non pour un statut
+* qui dépend du résultat. La métadonnée n'est lue qu'une fois par route, puis
+* mémorisée : le décorateur ne coûte rien par requête.
+*
+* @param statusCode - Code HTTP appliqué à la réponse (201, 204, 202…).
+* @returns Le décorateur de méthode.
+* @example
+* ```typescript
+* @route("item-create", { path: "/items", method: "POST" })
+* @HttpCode(201)
+* async create() {
+*   return this.renderJson({ id: 42 });
+* }
+* ```
+*/
+function HttpCode(statusCode) {
+	return function(target, propertyKey, descriptor) {
+		Reflect.defineMetadata(HTTP_CODE_METADATA, statusCode, target, propertyKey);
+		return descriptor;
+	};
+}
+/**
+* Ajoute un en-tête à la réponse d'une action.
+*
+* Décorateur de **méthode**, empilable : chaque application ajoute une entrée,
+* la dernière l'emportant sur un même nom d'en-tête. Les en-têtes sont posés
+* avant l'exécution du corps de l'action, qui peut donc encore les modifier.
+* Réserve-le aux en-têtes constants d'une action ; ce qui dépend de la requête
+* s'écrit dans le corps.
+*
+* @param key - Nom de l'en-tête.
+* @param value - Valeur de l'en-tête.
+* @returns Le décorateur de méthode.
+* @example
+* ```typescript
+* @route("feed", { path: "/feed", method: "GET" })
+* @Header("Cache-Control", "public, max-age=3600")
+* async feed() {
+*   return this.renderJson(items);
+* }
+* ```
+*/
+function Header(key, value) {
+	return function(target, propertyKey, descriptor) {
+		const existing = Reflect.getMetadata("route:responseHeaders", target, propertyKey) || {};
+		existing[key] = value;
+		Reflect.defineMetadata(HEADERS_METADATA, existing, target, propertyKey);
+		return descriptor;
+	};
+}
+/**
+* Redirige la réponse d'une action vers une autre URL.
+*
+* Décorateur de **méthode**. ⚠️ Le corps de l'action **est exécuté** : la
+* redirection est portée à côté du résultat et appliquée après coup par le
+* `Resolver`. Ce n'est donc pas un court-circuit — tout effet de bord écrit dans
+* l'action a bien lieu. L'action peut d'ailleurs surcharger la cible ou le code
+* en renvoyant sa propre redirection.
+*
+* @param url - URL cible, absolue ou relative à l'application.
+* @param statusCode - Code HTTP de redirection. Défaut `302` (temporaire) ;
+*   `301` pour un déplacement permanent, `307` pour conserver la méthode.
+* @returns Le décorateur de méthode.
+* @example
+* ```typescript
+* @route("legacy", { path: "/old-path", method: "GET" })
+* @Redirect("/new-path", 301)
+* async oldPath() {}
+* ```
+*/
+function Redirect(url, statusCode = 302) {
+	return function(target, propertyKey, descriptor) {
+		const meta = {
+			url,
+			statusCode
+		};
+		Reflect.defineMetadata(REDIRECT_METADATA, meta, target, propertyKey);
+		return descriptor;
+	};
+}
+/**
+* Restreint une route (décorateur de **méthode**) ou tout un contrôleur
+* (décorateur de **classe**) à un ou plusieurs vhosts. Source de vérité du
+* domaine de routing — le `host` posé ici alimente `Route.host`, compilé en
+* RegExp ancrée/wildcard (matcher partagé `@nodefony/http`). Domaine non servi
+* par la route → 403.
+*
+* Précédence : `@route({ host })` > `@Domain` méthode > `@Domain` classe.
+*
+* Pattern : exact (`"marseille.fr"`) ou wildcard un-label (`"*.cdn.nodefony.com"`).
+*
+* ⚠️ En décorateur de **classe**, placer `@Domain` SOUS `@controller` : les
+* décorateurs de classe s'appliquent de bas en haut, et `@controller` construit
+* les routes — il doit voir le domaine de classe déjà posé.
+*
+* @example
+* \@controller("/")
+* \@Domain("marseille.fr")
+* class MarseilleController extends Controller {
+*   \@Get("/") home() {} // marseille.fr/ → OK ; nodefony.com/ → 403
+* }
+*/
+function Domain(patterns) {
+	const list = Array.isArray(patterns) ? patterns : [patterns];
+	return function(target, propertyKey, descriptor) {
+		if (propertyKey === void 0) {
+			Reflect.defineMetadata(DOMAIN_CLASS_METADATA, list, target);
+			return target;
+		}
+		Reflect.defineMetadata(DOMAIN_METHOD_METADATA, list, target.constructor, propertyKey);
+		return descriptor;
+	};
+}
+/**
+* Déclare une route (décorateur de **méthode**) ou tout un contrôleur
+* (décorateur de **classe**) comme **PUBLIQUE** : le firewall ne s'exécute pas
+* (`Route.bypassFirewall`). Pour la **liveness** (`/health`, `/info` — sondes
+* k8s/monitoring NON authentifiées, ping pré-login), les **webhooks signés**, ou
+* un endpoint d'auth (login). Sucre déclaratif sur l'option
+* `RouteOptions.bypassFirewall` (les deux coexistent ; l'option l'emporte).
+*
+* Précédence : `@Get({ bypassFirewall })` > `@BypassFirewall` méthode > classe.
+* Lu au montage `@controller` (ordre des décorateurs indifférent). **Fail-closed** :
+* un oubli laisse la route GATÉE (401), jamais ouverte par erreur.
+*
+* ⚠️ En décorateur de **classe**, placer `@BypassFirewall` SOUS `@controller`
+* (décorateurs de classe appliqués de bas en haut). Préfigure `@Public`/
+* `@Anonymous` (P6.8b) — sémantique « pas d'auth », qui s'appuiera sur ce primitif.
+*
+* Décorateur SANS argument → **simple, SANS parenthèses** (`@BypassFirewall`,
+* pas `@BypassFirewall()`) : c'est un DRAPEAU, pas une option paramétrée. Une
+* factory (`()`) ne se justifie que pour passer des arguments (cf `@Get("/x")`,
+* `@Domain("host")`).
+*
+* @example
+* \@controller("/nodefony")
+* class StudioController extends Controller {
+*   \@BypassFirewall
+*   \@Get("/studio/api/health") health() {} // public (liveness)
+*   \@Get("/studio/api/stats") stats() {}    // gaté par l'aire data plane
+* }
+*/
+function BypassFirewall(target, propertyKey, descriptor) {
+	if (propertyKey === void 0) {
+		Reflect.defineMetadata(BYPASS_FIREWALL_CLASS_METADATA, true, target);
+		return target;
+	}
+	Reflect.defineMetadata(BYPASS_FIREWALL_METHOD_METADATA, true, target.constructor, propertyKey);
+	return descriptor;
+}
+/**
+* Déclare le scope d'instanciation d'un controller (V4.3) — pose le statique
+* `scope` de la classe (hérité de `Controller`, défaut `"request"`). Lu par le
+* constructor de `Controller` (`new.target`) et par le `Resolver` : 0 Reflect.
+*
+* `@Scope("singleton")` : UNE instance partagée par toutes les requêtes
+* (cache kernel-scoped sur le Router, `initialize()` appelé 1× à la création).
+* **Contrat stateless strict** : l'action ne lit/n'écrit AUCUN état par requête
+* sur `this` — tout passe par les arguments décorés (`@Param`/`@Body`…) et les
+* helpers, qui retrouvent la requête courante via l'ALS (V4.1). Un champ muté
+* par requête sur un singleton = data race silencieuse entre deux requêtes
+* concurrentes. Le défaut per-request reste inchangé (0 breaking legacy).
+*
+* ⚠️ Homonyme : le core `nodefony` exporte aussi `Scope` (le scope DI du
+* `Container`) — celui-ci s'importe depuis `@nodefony/framework`.
+*
+* @example
+* \@Scope("singleton")
+* \@controller("/api/books")
+* class BookController extends ResourceController { ... }
+*/
+function Scope(scope) {
+	return function(target) {
+		target.scope = scope;
+	};
+}
+/**
+* Déclare qu'une route (décorateur de **méthode**) ou tout un contrôleur
+* (décorateur de **classe**) a besoin d'une **session serveur**. C'est l'unique
+* façon d'activer une session (avec la reprise auto d'un cookie existant — L1) :
+* il n'y a plus de `sessionAutoStart` global « démarre partout » (le moteur du
+* ×23). Lazy par défaut — aucune session pour une route qui n'en déclare pas.
+*
+* Précédence : `@UseSession` méthode > `@UseSession` classe. La simple présence
+* d'un paramètre `@Session` sur l'action suffit aussi (intent implicite).
+*
+* - `{ readOnly }` : session lue/reprise mais **jamais persistée** (0 write storage).
+*
+* ⚠️ En décorateur de **classe**, placer `@UseSession` SOUS `@controller`.
+*
+* @example
+* \@controller("/account")
+* \@UseSession()
+* class AccountController extends Controller {
+*   \@Get("/me") @UseSession({ readOnly: true }) me() {} // lecture seule → 0 write
+* }
+*/
+function UseSession(options = {}) {
+	return function(target, propertyKey, descriptor) {
+		if (propertyKey === void 0) {
+			Reflect.defineMetadata(USE_SESSION_CLASS_METADATA, options, target);
+			return target;
+		}
+		Reflect.defineMetadata(USE_SESSION_METHOD_METADATA, options, target.constructor, propertyKey);
+		return descriptor;
+	};
+}
+/**
+* Résout l'intent de session effectif d'une action — lu par le `Resolver` au
+* match, posé sur `context.sessionIntent`, consommé au point d'activation unique
+* (`HttpKernel.startSession`). Combine `@UseSession` classe + méthode (méthode
+* prioritaire) ; à défaut, un paramètre `@Session` déclare un intent implicite.
+*
+* @returns l'intent, ou `null` si la route ne requiert aucune session.
+*/
+function resolveSessionIntent(ctor, actionName) {
+	const classMeta = Reflect.getMetadata(USE_SESSION_CLASS_METADATA, ctor);
+	const methodMeta = Reflect.getMetadata(USE_SESSION_METHOD_METADATA, ctor, actionName);
+	if (classMeta || methodMeta) return {
+		...classMeta,
+		...methodMeta
+	};
+	if (Reflect.getMetadata("route:paramArgs", ctor.prototype, actionName)?.some((p) => p.source === "session")) return {};
+	return null;
+}
+/**
+* Exige une autorisation pour l'action (décorateur de **méthode**) ou tout le
+* contrôleur (décorateur de **classe**).
+*
+* - `@IsGranted("ROLE_ADMIN")` — un attribut (rôle `ROLE_*`, permission, ou
+*   attribut métier résolu par un voter).
+* - `@IsGranted(["ROLE_ADMIN", "ROLE_AUDITOR"])` — **OR** : un seul suffit.
+* - empiler plusieurs `@IsGranted` — **AND** : toutes les clauses doivent passer.
+* - `@IsGranted("doc.edit", { subject: "id" })` — le paramètre de route `id` est
+*   passé comme `subject` au voter (ownership, multi-tenant).
+*
+* Classe + méthode fusionnent en AND. L'évaluation a lieu dans le `Resolver`
+* AVANT l'instanciation du controller (403 court-circuite — Zero Trust). N'écrit
+* QUE des métadonnées (zéro logique sécu ici → 0 import `@nodefony/security`,
+* 0 cycle ; le moteur `authorization` est appelé par nom au runtime).
+*/
+function IsGranted(attribute, options) {
+	const clause = {
+		anyOf: Array.isArray(attribute) ? [...attribute] : [attribute],
+		...options?.subject !== void 0 ? { subjectParam: options.subject } : {}
+	};
+	return function(target, propertyKey, descriptor) {
+		if (propertyKey === void 0) {
+			const existing = Reflect.getMetadata(SECURITY_CLAUSES_METADATA, target) || [];
+			existing.push(clause);
+			Reflect.defineMetadata(SECURITY_CLAUSES_METADATA, existing, target);
+			return target;
+		}
+		const existing = Reflect.getMetadata(SECURITY_CLAUSES_METADATA, target, propertyKey) || [];
+		existing.push(clause);
+		Reflect.defineMetadata(SECURITY_CLAUSES_METADATA, existing, target, propertyKey);
+		return descriptor;
+	};
+}
+/**
+* Déclare une action (méthode) ou un contrôleur (classe) **publique** : skip
+* l'autorisation (override un `@IsGranted` de classe sur cette méthode) ET skip
+* l'authentification (réutilise le mécanisme `@BypassFirewall` → pas de 401 en
+* zone protégée). L'alias lisible de « permitAll » (mental model Spring). Pour un
+* login, une sonde de liveness, une page publique d'un contrôleur par ailleurs
+* protégé.
+*/
+function Anonymous() {
+	return function(target, propertyKey, descriptor) {
+		if (propertyKey === void 0) {
+			Reflect.defineMetadata(SECURITY_ANONYMOUS_METADATA, true, target);
+			Reflect.defineMetadata(BYPASS_FIREWALL_CLASS_METADATA, true, target);
+			return target;
+		}
+		Reflect.defineMetadata(SECURITY_ANONYMOUS_METADATA, true, target.constructor, propertyKey);
+		Reflect.defineMetadata(BYPASS_FIREWALL_METHOD_METADATA, true, target.constructor, propertyKey);
+		return descriptor;
+	};
+}
+/**
+* Exige un **scope** (`api:action`) pour l'action (décorateur de **méthode**) ou
+* tout le contrôleur (décorateur de **classe**). Axe d'autorisation **distinct des
+* rôles** (`@IsGranted`) : un scope **downscope** un jeton MACHINE délégué (clé
+* API, JWT d'agent, OAuth) — il est un **no-op** pour une session humaine, dont
+* les droits sont portés par ses rôles (cf {@link ScopeVoter}).
+*
+* - `@RequireScope("orders:read")` — le jeton doit porter ce scope.
+* - `@RequireScope(["orders:read", "orders:admin"])` — **OR** : un seul suffit.
+* - empiler plusieurs `@RequireScope` — **AND** : tous les scopes requis.
+*
+* Convention d'espace **plat** `api:action` (modèle GitHub PAT classic) : le
+* préfixe avant `:` EST l'API → la découverte au boot regroupe les scopes par API
+* sans catalogue séparé. Classe + méthode fusionnent en AND, et fusionnent AUSSI
+* avec les clauses `@IsGranted` dans le même `SecurityRequirement` (rôle ET scope).
+*
+* N'écrit QUE des métadonnées (zéro logique sécu ici → 0 import `@nodefony/security`,
+* 0 cycle) : la décision est rendue par le `ScopeVoter` au runtime (par nom). La
+* metadata est **dédiée** (≠ `@IsGranted`) pour que la découverte au boot puisse
+* lister les scopes déclarés par route sans les confondre avec les rôles.
+*/
+function RequireScope(scope) {
+	const clause = { anyOf: Array.isArray(scope) ? [...scope] : [scope] };
+	return function(target, propertyKey, descriptor) {
+		if (propertyKey === void 0) {
+			const existing = Reflect.getMetadata(SECURITY_SCOPES_METADATA, target) || [];
+			existing.push(clause);
+			Reflect.defineMetadata(SECURITY_SCOPES_METADATA, existing, target);
+			return target;
+		}
+		const existing = Reflect.getMetadata(SECURITY_SCOPES_METADATA, target, propertyKey) || [];
+		existing.push(clause);
+		Reflect.defineMetadata(SECURITY_SCOPES_METADATA, existing, target, propertyKey);
+		return descriptor;
+	};
+}
+/**
+* Fusion ADDITIVE de deux jeux de directives CSP : les sources d'une même
+* directive sont concaténées (dédupliquées, ordre `a` puis `b`). Pure, sans
+* mutation des entrées. Sert au stacking de `@Csp` et à la fusion classe+méthode.
+*/
+function mergeCspDirectives(a, b) {
+	const out = {};
+	for (const src of [a, b]) {
+		if (!src) continue;
+		for (const name in src) {
+			const list = out[name] ??= [];
+			for (const v of src[name]) if (!list.includes(v)) list.push(v);
+		}
+	}
+	return out;
+}
+/**
+* `@Csp({ "frame-src": [...] })` — déclare des directives CSP **additionnelles**
+* pour l'action (méthode) ou tout le contrôleur (classe). Distinct de
+* `registerCspOrigins` (besoins PERMANENTS d'un module, ex. Vite) : ici c'est le
+* besoin ponctuel d'UNE réponse (embarquer une iframe YouTube, autoriser une CDN).
+*
+* Classe + méthode fusionnent additivement (sources concaténées par directive).
+* Empiler plusieurs `@Csp` fusionne aussi. N'écrit QUE des métadonnées : le merge
+* dans le CSP de la réponse est fait par le firewall, hors hot-path, UNIQUEMENT
+* sur les routes décorées. Calque `@IsGranted` (0 import `@nodefony/security`).
+*/
+function Csp(directives) {
+	return function(target, propertyKey, descriptor) {
+		if (propertyKey === void 0) {
+			const existing = Reflect.getMetadata(CSP_DIRECTIVES_METADATA, target);
+			Reflect.defineMetadata(CSP_DIRECTIVES_METADATA, mergeCspDirectives(existing, directives), target);
+			return target;
+		}
+		const existing = Reflect.getMetadata(CSP_DIRECTIVES_METADATA, target, propertyKey);
+		Reflect.defineMetadata(CSP_DIRECTIVES_METADATA, mergeCspDirectives(existing, directives), target, propertyKey);
+		return descriptor;
+	};
+}
+/**
+* Fabrique d'un marqueur booléen dual classe+méthode (idiome `any` du module).
+* Pose `true` sur le ctor (classe) ou le prototype keyé par nom (méthode).
+*/
+function booleanMarkerDecorator(markerKey) {
+	return function() {
+		return function(target, propertyKey, descriptor) {
+			if (propertyKey === void 0) {
+				Reflect.defineMetadata(markerKey, true, target);
+				return target;
+			}
+			Reflect.defineMetadata(markerKey, true, target, propertyKey);
+			return descriptor;
+		};
+	};
+}
+/**
+* `@CsrfProtect()` — opt-IN à la défense CSRF **synchronizer token** (double-submit
+* signé HMAC) EN PLUS de la défense globale Fetch Metadata/Origin (étape 1, toujours
+* active). Pour les mutations à haute valeur (changement de mot de passe, virement) :
+* une requête sûre vers la route SÈME le cookie lisible `csrf-token` ; la mutation
+* DOIT rejouer ce token dans l'en-tête `x-csrf-token` (sinon 403). Classe = toutes
+* les actions. N'écrit qu'un marqueur (0 import `@nodefony/security`, 0 cycle).
+*/
+const CsrfProtect = booleanMarkerDecorator(CSRF_PROTECT_METADATA);
+/**
+* `@CsrfExempt()` — opt-OUT de la défense CSRF pour une route, **en conservant
+* l'authentification et l'autorisation** (≠ `@Anonymous`/`@BypassFirewall` qui
+* coupent l'auth). Pour un webhook ou une API recevant un POST cross-origin
+* légitime, dont la requête est authentifiée autrement (signature HMAC du provider,
+* clé API). Classe = toutes les actions. Marqueur seul (0 logique sécu ici).
+*/
+const CsrfExempt = booleanMarkerDecorator(CSRF_EXEMPT_METADATA);
+/**
+* `@Idempotent()` — protège une **mutation** (POST/PUT/PATCH/DELETE) d'un
+* controller userland contre le double-effet d'un rejeu (double-clic, reconnexion
+* socket, retry réseau), via une `Idempotency-Key` cliente (modèle Stripe, conforme
+* `draft-ietf-httpapi-idempotency-key-header`). No-op sur les méthodes sûres (GET…).
+*
+* - **STRICT par défaut** : une mutation SANS clé est rejetée **400** (draft §2.7).
+* - `@Idempotent({ required: false })` : mode **souple** — honore la clé si fournie,
+*   exécute sinon. (Une mutation par **socket** reste toujours strict : le WS rejoue.)
+* - clé fournie → dédup complète : rejeu complété → réponse **mémorisée** ; rejeu
+*   concurrent → **409** ; même clé + payload différent → **422**.
+*
+* Décorateur de **méthode** (une action) ou de **classe** (toutes les mutations du
+* controller). Précédence : méthode > classe (comme `@UseSession`). N'écrit QUE des
+* métadonnées (0 import `@nodefony/security`, 0 cycle) ; la porte est appliquée par
+* le `Resolver` (helper partagé `idempotency.ts`, le MÊME que le data plane admin),
+* sur le `idempotencyStore` DI. Coût nul sur une route non décorée (`security: null`).
+*
+* @example
+* \@controller("/api/orders")
+* class OrderController extends Controller {
+*   \@Post("/") @Idempotent() create(@Body() dto: CreateOrder) { ... } // clé obligatoire
+*   \@Patch("/{id}") @Idempotent({ required: false }) update() { ... } // clé optionnelle (HTTP)
+* }
+*/
+function Idempotent(options) {
+	const meta = { required: options?.required ?? true };
+	return function(target, propertyKey, descriptor) {
+		if (propertyKey === void 0) {
+			Reflect.defineMetadata(IDEMPOTENT_METADATA, meta, target);
+			return target;
+		}
+		Reflect.defineMetadata(IDEMPOTENT_METADATA, meta, target, propertyKey);
+		return descriptor;
+	};
+}
+function paramDecoratorFactory(source) {
+	return function(key) {
+		return function(target, propertyKey, parameterIndex) {
+			const existing = Reflect.getMetadata("route:paramArgs", target, propertyKey) || [];
+			existing.push({
+				source,
+				key,
+				index: parameterIndex
+			});
+			Reflect.defineMetadata(PARAM_ARGS_METADATA, existing, target, propertyKey);
+		};
+	};
+}
+const Param = paramDecoratorFactory("param");
+const Query = paramDecoratorFactory("query");
+/**
+* Décorateur de paramètre `@Body` :
+* - `@Body()` → body parsé entier · `@Body("field")` → un champ du body parsé.
+* - `@Body({ stream: true })` → **flux brut** de la requête (`Readable`), sans
+*   parse en mémoire (P2.9 — gros uploads sans pic RAM ; le pipeline saute le
+*   parse busboy/JSON pour cette route).
+*
+* ## Le corps n'est PAS validé — le type écrit ici ne promet rien
+*
+* `@Body()` injecte le corps **tel qu'il a été parsé** : `@Body() dto: CreateOrder`
+* compile, mais rien ne garantit qu'un `CreateOrder` soit arrivé. C'est un choix
+* assumé, pas un oubli — valider ici ne garderait que la porte HTTP, et devrait
+* rester **synchrone** ({@link resolveParamArg} l'est, et le rendre asynchrone
+* taxerait toute requête à paramètres décorés).
+*
+* Où valider, donc :
+*
+* - **Une entité** → les hooks `beforeCreate` / `beforeUpdate` d'
+*   `AbstractCrudService` : ils sont `await`és — donc une règle asynchrone
+*   (unicité en base) y est possible — et ils gardent REST, WebSocket **et** la
+*   CLI d'un seul geste. C'est ce que génère `nodefony create entity`.
+* - **Un cas isolé** → `schema.parse(body)` en première ligne de l'action, sur le
+*   modèle d'`assertPageQuery`. Rien d'autre à écrire : une `ZodError` qui remonte
+*   devient un **422** (RFC 9110 §15.5.21) portant `error.fields` — quel champ,
+*   quel message, quelle règle.
+*
+* Et typer le paramètre avec `z.infer<typeof createXSchema>` plutôt qu'avec
+* `Partial<XRow>` : le premier décrit le contrat d'**entrée**, le second promet la
+* ligne de **table** (`id`, horodatages) que le schéma effacera de toute façon.
+*
+* @example
+* ```ts
+* \@Post("/")
+* async create(\@Body() payload: CreatePost) {
+*   return this.createResource(payload); // le service valide dans beforeCreate
+* }
+* ```
+*/
+function Body(keyOrOptions) {
+	const isOptions = typeof keyOrOptions === "object" && keyOrOptions !== null;
+	const key = isOptions ? void 0 : keyOrOptions;
+	const stream = isOptions ? keyOrOptions.stream === true : false;
+	return function(target, propertyKey, parameterIndex) {
+		const existing = Reflect.getMetadata("route:paramArgs", target, propertyKey) || [];
+		const meta = {
+			source: "body",
+			key,
+			index: parameterIndex
+		};
+		if (stream) meta.stream = true;
+		existing.push(meta);
+		Reflect.defineMetadata(PARAM_ARGS_METADATA, existing, target, propertyKey);
+	};
+}
+const Headers = paramDecoratorFactory("headers");
+const Cookie = paramDecoratorFactory("cookie");
+const Session = paramDecoratorFactory("session");
+/** `@CurrentUser() user: IUser` — injecte l'utilisateur de l'ALS (jamais le credential). */
+const CurrentUser = paramDecoratorFactory("user");
+const Req = paramDecoratorFactory("req");
+const Res = paramDecoratorFactory("res");
+const UploadedFile = paramDecoratorFactory("file");
+const UploadedFiles = paramDecoratorFactory("files");
+/**
+* Résout la valeur d'un unique paramètre décoré depuis le contexte de requête.
+*
+* @param meta - métadonnée posée par le décorateur (source + clé optionnelle)
+* @param ctx - contexte de requête (forme structurelle minimale)
+* @returns la valeur à injecter dans l'argument `meta.index` de l'action
+*/
+function resolveParamArg(meta, ctx) {
+	switch (meta.source) {
+		case "param": return meta.key !== void 0 ? ctx.paramsMap[meta.key] : ctx.paramsMap;
+		case "query": {
+			const qg = ctx.queryOverride ?? ctx.request?.queryGet;
+			return meta.key !== void 0 ? qg?.[meta.key] : qg;
+		}
+		case "body": {
+			if (meta.stream) return ctx.request?.request;
+			const alsBody = RequestContext.get()?.body;
+			if (alsBody !== void 0) return meta.key !== void 0 ? alsBody?.[meta.key] : alsBody;
+			const qp = ctx.request?.queryPost;
+			return meta.key !== void 0 ? qp?.[meta.key] : qp;
+		}
+		case "headers": {
+			const h = ctx.request?.headers;
+			return meta.key !== void 0 ? h?.[meta.key.toLowerCase()] : h;
+		}
+		case "cookie": return ctx.getRequestCookies(meta.key);
+		case "session": return meta.key !== void 0 ? ctx.session?.get(meta.key) : ctx.session;
+		case "req": return ctx.request;
+		case "res": return ctx.response;
+		case "file": return ctx.request?.queryFile?.[0];
+		case "files": return ctx.request?.queryFile;
+		case "user": return RequestContext.getUser();
+		default: return;
+	}
+}
+/**
+* Construit le tableau d'arguments d'une action à partir des métadonnées de
+* paramètres décorés. Chaque valeur est placée à son `index` déclaré (les trous
+* restent `undefined`). Fonction pure — aucun effet de bord, aucune I/O.
+*
+* @param metas - métadonnées de tous les paramètres décorés de l'action
+* @param ctx - contexte de requête (forme structurelle minimale)
+* @returns arguments positionnels à spread dans l'action
+*/
+function buildParamArgs(metas, ctx) {
+	const result = [];
+	for (const meta of metas) result[meta.index] = resolveParamArg(meta, ctx);
+	return result;
+}
+/**
+* P2.9 — Indique si l'action d'une route attend le **flux brut** du body
+* (un paramètre `@Body({ stream:true })`). Le résultat est **mémoïsé** sur
+* `route.bodyStream` : lecture `Reflect` au 1er appel, O(1) ensuite → 0 coût
+* hot-path. Lu **en amont** par `handleHttp` (avant le parse) pour décider de
+* sauter le parse busboy/JSON. Typage structurel (pas d'import `Route` → 0 cycle).
+*
+* @param routeDef - route résolue (porte `controller` + `classMethod` à `onBoot`).
+* @returns `true` si l'action déclare un `@Body({ stream:true })`.
+*/
+function routeExpectsBodyStream(routeDef) {
+	if (routeDef.bodyStream === void 0) {
+		let flag = false;
+		const ctor = routeDef.controller;
+		const method = routeDef.classMethod;
+		if (ctor && method) flag = (Reflect.getMetadata("route:paramArgs", ctor.prototype, method) || []).some((m) => m.source === "body" && m.stream === true);
+		routeDef.bodyStream = flag;
+	}
+	return routeDef.bodyStream;
+}
+const EMPTY_ACTION_META = {
+	paramsMeta: null,
+	redirectMeta: null,
+	httpCode: null,
+	headerEntries: null,
+	sessionIntent: null,
+	security: null,
+	cspDirectives: null,
+	csrfProtect: false,
+	csrfExempt: false,
+	idempotent: null
+};
+/**
+* P5 — Calcule le {@link RouteActionMeta} d'un couple (controller, action) par
+* lecture `Reflect`. Fonction PURE (pas de memo) : utilisée par
+* {@link resolveActionMeta} (routes, mémoïsé) et par le `Resolver` pour le
+* chemin froid du forward (`parsePathernController`, pas de route).
+*/
+/** Lit un tableau de clauses (`@IsGranted`/`@RequireScope`) posé sur une cible Reflect — `[]` si absent. */
+function readClauses(target, propertyKey) {
+	return (propertyKey === void 0 ? Reflect.getMetadata(SECURITY_CLAUSES_METADATA, target) : Reflect.getMetadata(SECURITY_CLAUSES_METADATA, target, propertyKey)) ?? [];
+}
+/** Idem pour les clauses de scope (`@RequireScope`, metadata dédiée) — `[]` si absent. */
+function readScopeClauses(target, propertyKey) {
+	return (propertyKey === void 0 ? Reflect.getMetadata(SECURITY_SCOPES_METADATA, target) : Reflect.getMetadata(SECURITY_SCOPES_METADATA, target, propertyKey)) ?? [];
+}
+/**
+* P6.8 — Liste PLATE des scopes `api:action` déclarés par une action
+* (`@RequireScope`, classe + méthode), **dédupliqués**. Source de la **découverte
+* au boot** : le catalogue de scopes du formulaire de clés API se construit en
+* scannant les routes (cf `collectDeclaredApiScopes`), au lieu d'une config plate
+* qui dérive du code. Lecture `Reflect` directe — **cold path** (introspection à la
+* demande, jamais sur le hot path requête). `[]` si l'action ne déclare aucun scope.
+*/
+function extractActionScopes(ctor, method) {
+	const out = /* @__PURE__ */ new Set();
+	for (const clause of readScopeClauses(ctor.prototype, method)) for (const s of clause.anyOf) out.add(s);
+	for (const clause of readScopeClauses(ctor)) for (const s of clause.anyOf) out.add(s);
+	return [...out];
+}
+/**
+* P6 J7 / P6.8 — Fusionne les clauses `@IsGranted` (rôles) ET `@RequireScope`
+* (scopes) — classe + méthode — en une exigence d'autorisation **figée**, ou
+* `null` si l'action n'est pas gardée. Les deux axes cohabitent dans le même
+* `SecurityRequirement` (clauses en **AND**) → un seul chemin d'enforcement dans
+* le `Resolver`, le bon voter (`RoleVoter`/`ScopeVoter`) répond par attribut.
+* `@Anonymous` (méthode) rend l'action publique (override `@IsGranted`/
+* `@RequireScope` de classe → `null`). Lecture `Reflect` faite UNE fois (via
+* {@link resolveActionMeta} mémoïsé).
+*/
+function computeSecurityRequirement(ctor, method) {
+	if (Reflect.getMetadata(SECURITY_ANONYMOUS_METADATA, ctor, method) === true) return null;
+	const proto = ctor.prototype;
+	const methodClauses = readClauses(proto, method);
+	const methodScopes = readScopeClauses(proto, method);
+	const classAnon = Reflect.getMetadata(SECURITY_ANONYMOUS_METADATA, ctor) === true;
+	const classClauses = classAnon ? [] : readClauses(ctor);
+	const classScopes = classAnon ? [] : readScopeClauses(ctor);
+	const all = [
+		...classClauses,
+		...methodClauses,
+		...classScopes,
+		...methodScopes
+	];
+	if (all.length === 0) return null;
+	return Object.freeze({ clauses: Object.freeze(all) });
+}
+/**
+* P6 — Fusionne les directives `@Csp` (classe + méthode) en un jeu figé, ou
+* `null` si l'action n'en déclare aucune (cas courant → 0 alloc/composition).
+* Lecture `Reflect` faite UNE fois (via {@link resolveActionMeta} mémoïsé).
+*/
+function computeCspDirectives(ctor, method) {
+	const methodDirectives = Reflect.getMetadata(CSP_DIRECTIVES_METADATA, ctor.prototype, method);
+	const classDirectives = Reflect.getMetadata(CSP_DIRECTIVES_METADATA, ctor);
+	if (!classDirectives && !methodDirectives) return null;
+	return Object.freeze(mergeCspDirectives(classDirectives, methodDirectives));
+}
+/**
+* P6.8 — Résout la config `@Idempotent` figée d'une action (méthode prime sur
+* classe, comme `@UseSession`), ou `null` si non décorée. `@Idempotent()` pose
+* `{ required: true }` explicite → la précédence méthode > classe est non ambiguë
+* (une méthode `@Idempotent()` force le mode strict même sous une classe souple).
+* Lecture `Reflect` faite UNE fois (via {@link resolveActionMeta} mémoïsé).
+*/
+function computeIdempotent(ctor, method) {
+	const methodMeta = Reflect.getMetadata(IDEMPOTENT_METADATA, ctor.prototype, method);
+	const classMeta = Reflect.getMetadata(IDEMPOTENT_METADATA, ctor);
+	if (methodMeta === void 0 && classMeta === void 0) return null;
+	return Object.freeze({ required: methodMeta?.required ?? classMeta?.required ?? true });
+}
+function computeActionMeta(ctor, method) {
+	if (!ctor || !method) return EMPTY_ACTION_META;
+	const proto = ctor.prototype;
+	const params = Reflect.getMetadata(PARAM_ARGS_METADATA, proto, method);
+	const redirect = Reflect.getMetadata(REDIRECT_METADATA, proto, method);
+	const httpCode = Reflect.getMetadata(HTTP_CODE_METADATA, proto, method);
+	const headers = Reflect.getMetadata(HEADERS_METADATA, proto, method);
+	return {
+		paramsMeta: params && params.length > 0 ? params : null,
+		redirectMeta: redirect ?? null,
+		httpCode: httpCode ?? null,
+		headerEntries: headers ? Object.entries(headers) : null,
+		sessionIntent: resolveSessionIntent(ctor, method),
+		security: computeSecurityRequirement(ctor, method),
+		cspDirectives: computeCspDirectives(ctor, method),
+		csrfProtect: Reflect.getMetadata(CSRF_PROTECT_METADATA, proto, method) === true || Reflect.getMetadata(CSRF_PROTECT_METADATA, ctor) === true,
+		csrfExempt: Reflect.getMetadata(CSRF_EXEMPT_METADATA, proto, method) === true || Reflect.getMetadata(CSRF_EXEMPT_METADATA, ctor) === true,
+		idempotent: computeIdempotent(ctor, method)
+	};
+}
+/**
+* P5 — Metadata d'action d'une route, **mémoïsées au 1er hit** sur
+* `route.actionMeta` (pattern frère de {@link routeExpectsBodyStream}) :
+* `undefined` = pas encore résolu → 1 lecture `Reflect` par route pour la vie
+* du process, O(1) ensuite. Sort `Reflect.getMetadata` (~6 appels/req) du hot
+* path `match`/`executeAction`. Posé APRÈS `generateId()` (1ʳᵉ requête) → le
+* hash de route et l'introspection Studio restent stables. Typage structurel
+* (pas d'import `Route` → 0 cycle).
+*/
+function resolveActionMeta(routeDef) {
+	if (routeDef.actionMeta === void 0) routeDef.actionMeta = computeActionMeta(routeDef.controller, routeDef.classMethod);
+	return routeDef.actionMeta;
+}
+//#endregion
+export { All, Anonymous, BYPASS_FIREWALL_CLASS_METADATA, BYPASS_FIREWALL_METHOD_METADATA, Body, BypassFirewall, Cookie, Csp, CsrfExempt, CsrfProtect, CurrentUser, DOMAIN_CLASS_METADATA, DOMAIN_METHOD_METADATA, Delete, Domain, Get, HEADERS_METADATA, HTTP_CODE_METADATA, Head, Header, Headers, HttpCode, Idempotent, IsGranted, Options, PARAM_ARGS_METADATA, Param, Patch, Post, Put, Query, REDIRECT_METADATA, Redirect, Req, RequireScope, Res, Scope, Session, USE_SESSION_CLASS_METADATA, USE_SESSION_METHOD_METADATA, UploadedFile, UploadedFiles, UseSession, buildParamArgs, computeActionMeta, controller, controllers, extractActionScopes, resolveActionMeta, resolveParamArg, resolveSessionIntent, route, routeExpectsBodyStream };