@nodefony/framework 10.0.0-alpha.1

package/dist/types/nodefony/decorators/routerDecorators.d.ts

@@ -0,0 +1,632 @@
+import "reflect-metadata";
+import { TypeController } from "../service/router.js";
+import { RouteOptions } from "../src/Route.js";
+import Controller from "../src/Controller.js";
+import type { ControllerScope } from "../src/Controller.js";
+import { Module } from "nodefony";
+import { ControllerConstructor } from "../src/Route.js";
+import type { SessionIntent } from "@nodefony/http";
+type Constructor<T = {}> = new (...args: any[]) => T;
+/**
+ * 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 {}
+ * ```
+ */
+declare function controllers(targets: TypeController<Controller>[] | TypeController<Controller>): <T extends Constructor<Module>>(constructor: T) => T;
+/**
+ * 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({});
+ *    }
+ *  }
+ */
+declare function controller(prefix: string): <T extends ControllerConstructor & {
+    prefix?: string;
+}>(mycontroller: T) => T;
+/**
+ * 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 });
+ * }
+ */
+declare function route(name: string, options: RouteOptions): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+export declare const HTTP_CODE_METADATA = "route:httpCode";
+export declare const HEADERS_METADATA = "route:responseHeaders";
+export declare const REDIRECT_METADATA = "route:redirect";
+export declare const PARAM_ARGS_METADATA = "route:paramArgs";
+export declare const DOMAIN_CLASS_METADATA = "route:domainClass";
+export declare const DOMAIN_METHOD_METADATA = "route:domainMethod";
+export declare const BYPASS_FIREWALL_CLASS_METADATA = "route:bypassFirewallClass";
+export declare const BYPASS_FIREWALL_METHOD_METADATA = "route:bypassFirewallMethod";
+export declare const USE_SESSION_CLASS_METADATA = "session:useClass";
+export declare const USE_SESSION_METHOD_METADATA = "session:useMethod";
+export type ParamSource = "param" | "body" | "query" | "headers" | "cookie" | "session" | "req" | "res" | "file" | "files" | "user";
+export interface ParamMeta {
+    source: ParamSource;
+    key?: string;
+    index: number;
+    /**
+     * P2.9 — `@Body({ stream: true })` : injecte le **flux brut** de la requête
+     * (`IncomingMessage`, un `Readable`) au lieu du body parsé en mémoire. Permet
+     * de piper un gros upload (vidéo, backup) vers disque/S3 sans pic RAM. Le
+     * pipeline saute le parse busboy/JSON pour la route concernée (cf
+     * `routeExpectsBodyStream` + `handleHttp`).
+     */
+    stream?: boolean;
+}
+export interface RedirectMeta {
+    url: string;
+    statusCode: number;
+}
+/**
+ * Une clause `@IsGranted` : un OU plusieurs attributs (OR interne), sujet
+ * optionnel. `@IsGranted("ROLE_ADMIN")` → `{ anyOf: ["ROLE_ADMIN"] }` ;
+ * `@IsGranted(["A","B"])` → `{ anyOf: ["A","B"] }` (un seul suffit) ;
+ * `@IsGranted("doc.edit", { subject: "id" })` → le param de route `id` est passé
+ * au voter.
+ */
+export interface SecurityClause {
+    /** Attributs en OR — un seul accordé suffit pour valider la clause. */
+    readonly anyOf: readonly string[];
+    /** Nom du paramètre de route passé comme `subject` au voter (optionnel). */
+    readonly subjectParam?: string;
+}
+/**
+ * Exigence d'autorisation **figée** d'une action — calculée UNE fois par route
+ * (fusion classe + méthode) puis gelée sur `RouteActionMeta.security`. Objet
+ * PARTAGÉ entre toutes les requêtes : ne jamais muter. `null` (hors de ce type)
+ * = aucune garde → coût nul sur le hot path.
+ *
+ * Plusieurs `@IsGranted` empilés = `clauses` multiples en **AND** (toutes doivent
+ * passer). `@Anonymous()` ne produit jamais de `SecurityRequirement` (l'action
+ * devient `security: null` = publique).
+ */
+export interface SecurityRequirement {
+    /** Clauses en AND — toutes doivent être accordées (chacune est un OR interne). */
+    readonly clauses: readonly SecurityClause[];
+}
+/**
+ * Directives CSP additionnelles déclarées par une action (`@Csp`) :
+ * `directive → sources` (ex. `{ "frame-src": ["https://youtube.com"] }`).
+ * Structurellement compatible avec `CspFragment` (@nodefony/security) — aucun
+ * import cross-module (0 cycle). Mergé additivement dans le CSP de la réponse
+ * par le firewall, UNIQUEMENT sur les routes qui en déclarent (cold path).
+ */
+export type CspDirectives = Record<string, readonly string[]>;
+/**
+ * Configuration d'idempotence figée d'une action (`@Idempotent`) — calculée une
+ * fois par route (fusion classe + méthode) puis gelée sur `RouteActionMeta.idempotent`.
+ * `null` (hors de ce type) = action non idempotentée → 0 coût hot path.
+ */
+export interface IdempotentMeta {
+    /**
+     * Mode STRICT : une mutation sans `Idempotency-Key` est rejetée (400). Défaut
+     * `true` (`@Idempotent()`). `@Idempotent({ required: false })` = mode souple
+     * (honore la clé si présente, exécute sinon) — sauf en WS, toujours strict.
+     */
+    readonly required: boolean;
+}
+type MethodDecoratorOptions = Omit<RouteOptions, "path" | "method">;
+declare const Get: (path?: string, options?: MethodDecoratorOptions) => (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+declare const Post: (path?: string, options?: MethodDecoratorOptions) => (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+declare const Put: (path?: string, options?: MethodDecoratorOptions) => (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+declare const Delete: (path?: string, options?: MethodDecoratorOptions) => (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+declare const Patch: (path?: string, options?: MethodDecoratorOptions) => (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+declare const Options: (path?: string, options?: MethodDecoratorOptions) => (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+declare const Head: (path?: string, options?: MethodDecoratorOptions) => (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * `@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.
+ */
+declare function All(path?: string, options?: MethodDecoratorOptions): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * 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 });
+ * }
+ * ```
+ */
+declare function HttpCode(statusCode: number): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * 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);
+ * }
+ * ```
+ */
+declare function Header(key: string, value: string): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * 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() {}
+ * ```
+ */
+declare function Redirect(url: string, statusCode?: number): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * 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
+ * }
+ */
+declare function Domain(patterns: string | string[]): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+/**
+ * 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
+ * }
+ */
+declare function BypassFirewall(target: any, propertyKey?: string, descriptor?: PropertyDescriptor): any;
+/**
+ * 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 { ... }
+ */
+declare function Scope(scope: ControllerScope): <T extends {
+    scope?: ControllerScope;
+}>(target: T) => void;
+/** Options déclaratives de `@UseSession` (= forme de l'intent runtime). */
+export type UseSessionOptions = SessionIntent;
+/**
+ * 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
+ * }
+ */
+declare function UseSession(options?: UseSessionOptions): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+/**
+ * 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.
+ */
+declare function resolveSessionIntent(ctor: ControllerConstructor, actionName: string): SessionIntent | 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).
+ */
+declare function IsGranted(attribute: string | readonly string[], options?: {
+    subject?: string;
+}): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+/**
+ * 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é.
+ */
+declare function Anonymous(): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+/**
+ * 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.
+ */
+declare function RequireScope(scope: string | readonly string[]): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+/**
+ * `@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`).
+ */
+declare function Csp(directives: CspDirectives): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+/**
+ * `@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).
+ */
+declare const CsrfProtect: () => (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+/**
+ * `@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).
+ */
+declare const CsrfExempt: () => (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+/**
+ * `@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)
+ * }
+ */
+declare function Idempotent(options?: {
+    required?: boolean;
+}): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+declare const Param: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void;
+declare const Query: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void;
+/**
+ * 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
+ * }
+ * ```
+ */
+declare function Body(keyOrOptions?: string | {
+    stream?: boolean;
+}): (target: object, propertyKey: string, parameterIndex: number) => void;
+declare const Headers: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void;
+declare const Cookie: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void;
+declare const Session: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void;
+/** `@CurrentUser() user: IUser` — injecte l'utilisateur de l'ALS (jamais le credential). */
+declare const CurrentUser: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void;
+declare const Req: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void;
+declare const Res: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void;
+declare const UploadedFile: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void;
+declare const UploadedFiles: (key?: string) => (target: object, propertyKey: string, parameterIndex: number) => void;
+/**
+ * Contexte structurel minimal nécessaire pour résoudre les arguments injectés
+ * par les décorateurs de paramètre. Volontairement découplé de `HttpContext`
+ * (typage par forme) → la résolution est une fonction pure, testable en unit
+ * avec un faux contexte, sans démarrer de serveur. Le `Resolver` lui passe le
+ * vrai `Context`, qui satisfait cette forme.
+ */
+export interface IParamArgContext {
+    /** Variables de route extraites du path (`{name}` → valeur). */
+    paramsMap: Record<string, unknown>;
+    /**
+     * Query de l'invocation courante quand elle ne vient PAS de l'URL du
+     * transport — pont WS-RPC `api.request` (`Resolver.queryOverride`). Prime
+     * sur `request.queryGet` pour `@Query` uniquement (`@Req` reste le brut).
+     */
+    queryOverride?: Record<string, unknown>;
+    request?: {
+        queryGet?: Record<string, unknown>;
+        queryPost?: Record<string, unknown>;
+        queryFile?: unknown[];
+        headers?: Record<string, unknown>;
+        /**
+         * P2.9 — `IncomingMessage` brut (un `Readable`) sous-jacent au wrapper
+         * `HttpRequest`. Injecté tel quel par `@Body({ stream: true })` (le pipeline
+         * n'a pas consommé/parsé ce flux). `undefined` pour les contextes WS.
+         */
+        request?: NodeJS.ReadableStream;
+    } | null;
+    response?: unknown;
+    session?: {
+        get(key: string): unknown;
+    } | null;
+    getRequestCookies(name?: string): unknown;
+}
+/**
+ * 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
+ */
+declare function resolveParamArg(meta: ParamMeta, ctx: IParamArgContext): unknown;
+/**
+ * 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
+ */
+declare function buildParamArgs(metas: ParamMeta[], ctx: IParamArgContext): unknown[];
+/**
+ * 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 })`.
+ */
+declare function routeExpectsBodyStream(routeDef: {
+    controller?: {
+        prototype: object;
+    } | null;
+    classMethod?: string;
+    bodyStream?: boolean;
+}): boolean;
+/**
+ * Snapshot des métadonnées d'action d'une route (`@HttpCode`/`@Header`/
+ * `@Redirect`/paramètres décorés/intent de session), résolu UNE fois par route
+ * puis figé sur `route.actionMeta` (cf {@link resolveActionMeta}). Objet
+ * **PARTAGÉ entre toutes les requêtes** de la route — ne jamais muter.
+ */
+export interface RouteActionMeta {
+    /** Paramètres décorés (`@Param`/`@Body`/`@Query`…) — `null` si aucun. */
+    paramsMeta: ParamMeta[] | null;
+    /** `@Redirect` de l'action — `null` si absent. */
+    redirectMeta: RedirectMeta | null;
+    /** `@HttpCode` de l'action — `null` si absent. */
+    httpCode: number | null;
+    /** Entrées `@Header` pré-dépliées (`Object.entries` fait 1×) — `null` si aucune. */
+    headerEntries: [string, string][] | null;
+    /** Intent `@UseSession`/`@Session` — `null` si la route n'en déclare pas. */
+    sessionIntent: SessionIntent | null;
+    /**
+     * Exigence d'autorisation (`@IsGranted`, fusion classe+méthode) — `null` si
+     * l'action n'est pas gardée (ou `@Anonymous`). `null` = **0 coût** sur le hot
+     * path (ni résolution de service, ni `decide`, ni await). Frozen, partagé.
+     */
+    security: SecurityRequirement | null;
+    /**
+     * Directives CSP additionnelles (`@Csp`, fusion classe+méthode) — `null` si
+     * l'action n'en déclare pas (cas courant → 0 composition CSP). Frozen, partagé.
+     */
+    cspDirectives: CspDirectives | null;
+    /** `@CsrfProtect` (classe ou méthode) → exige le synchronizer token sur la mutation. */
+    csrfProtect: boolean;
+    /** `@CsrfExempt` (classe ou méthode) → la route est hors défense CSRF (auth conservée). */
+    csrfExempt: boolean;
+    /**
+     * Idempotence (`@Idempotent`, fusion classe + méthode) — `null` si l'action
+     * n'est pas décorée (cas courant → **0 coût** sur le hot path : ni résolution de
+     * store, ni `begin`). Frozen, partagé entre requêtes.
+     */
+    idempotent: IdempotentMeta | null;
+}
+/**
+ * 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.
+ */
+declare function extractActionScopes(ctor: {
+    prototype: object;
+}, method: string): string[];
+declare function computeActionMeta(ctor?: {
+    prototype: object;
+} | null, method?: string): RouteActionMeta;
+/**
+ * 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).
+ */
+declare function resolveActionMeta(routeDef: {
+    controller?: {
+        prototype: object;
+    } | null;
+    classMethod?: string;
+    actionMeta?: RouteActionMeta;
+}): RouteActionMeta;
+export { route, controller, controllers, Get, Post, Put, Delete, Patch, Options, Head, All, Domain, BypassFirewall, IsGranted, RequireScope, Anonymous, Csp, CsrfProtect, CsrfExempt, Idempotent, CurrentUser, Scope, UseSession, resolveSessionIntent, HttpCode, Header, Redirect, Param, Body, Query, Headers, Cookie, Session, Req, Res, UploadedFile, UploadedFiles, resolveParamArg, buildParamArgs, routeExpectsBodyStream, computeActionMeta, resolveActionMeta, extractActionScopes, };