@nodefony/framework 10.0.0-alpha.1

package/dist/nodefony/src/idempotency.js

@@ -0,0 +1,137 @@
+import { RequestContext } from "nodefony";
+import { createHash } from "node:crypto";
+//#region nodefony/src/idempotency.ts
+/**
+* Logique **pure et partagée** de la porte d'idempotence des mutations, conforme à
+* `draft-ietf-httpapi-idempotency-key-header-06`. Source unique de la sémantique
+* (statuts normatifs, scope de clé, fingerprint, bornage) consommée par les DEUX
+* call-sites qui mutent :
+*  - le **data plane admin** (`AdminApiController` — réponse `{status,headers,body}`) ;
+*  - les **controllers userland** décorés `@Idempotent` (seam `Resolver`).
+*
+* Le helper ne connaît AUCUN transport ni format de réponse : il rend un
+* {@link IdempotencyVerdict} neutre que chaque call-site traduit dans son monde
+* (court-circuit HTTP, `RpcError` WS, throw `nodefonyError`…). Garantit que la
+* sémantique IETF est décidée à UN seul endroit (cf retex S4 : statuts décidés
+* depuis la spec, pas de mémoire).
+*/
+/**
+* Méthodes HTTP considérées comme **mutations** (non sûres, RFC 9110 §9.2.1) →
+* éligibles à l'idempotence. Les méthodes sûres (GET/HEAD/OPTIONS/TRACE) et le
+* pseudo-verbe `WEBSOCKET` n'en font pas partie → `@Idempotent` y est un no-op.
+*/
+const MUTATION_METHODS = /* @__PURE__ */ new Set([
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+]);
+/** `true` si la méthode est une mutation éligible à l'idempotence. */
+function isMutationMethod(method) {
+	return method != null && MUTATION_METHODS.has(method.toUpperCase());
+}
+/**
+* Borne d'une clé d'idempotence (convention Stripe). Une clé est un identifiant
+* court (UUID) ; au-delà, elle est traitée comme ABSENTE (anti-DoS du cache borné).
+*/
+const IDEMPOTENCY_KEY_MAX = 255;
+/**
+* Résout la clé d'idempotence d'une requête : posée dans l'ALS par le pont WS
+* (`als.idempotencyKey`) ou lue de l'en-tête HTTP `Idempotency-Key` (clé
+* minuscule côté Node, éventuellement répétée → premier élément). L'ALS prime sur
+* l'en-tête. Une clé > {@link IDEMPOTENCY_KEY_MAX} est traitée comme **absente**
+* (anti-DoS) plutôt que stockée. `undefined` si rien d'exploitable.
+*/
+function resolveIdempotencyKey(alsKey, header) {
+	let raw;
+	if (typeof alsKey === "string" && alsKey) raw = alsKey;
+	else if (typeof header === "string" && header) raw = header;
+	else if (Array.isArray(header) && typeof header[0] === "string" && header[0]) raw = header[0];
+	return raw && raw.length <= 255 ? raw : void 0;
+}
+/**
+* Identité stable pour **scoper** le cache d'idempotence (anti-IDOR : un
+* utilisateur ne doit jamais rejouer la clé d'un autre). Dérivée de l'utilisateur
+* (`username` / `identifier` / `id`, sans coupler le framework au contrat `IUser`),
+* avec fallback sur l'`userId` de l'ALS. `null` = pas d'identité fiable → l'appelant
+* n'utilise PAS le cache (jamais de partage cross-identité).
+*
+* ⚠️ Doit renvoyer la MÊME valeur quel que soit le transport pour un même compte
+* (sinon une mutation tentée en WS puis rejouée en HTTP ne dédoublonnerait pas).
+* D'où la dérivation de `request.user` (posé UNIFORMÉMENT dans l'ALS par les deux
+* transports), et NON de `getUserId()` seul (le firewall HTTP ne le pose pas
+* toujours — vécu S4).
+*/
+function resolveIdentity(user) {
+	if (user && typeof user === "object") {
+		const o = user;
+		for (const v of [
+			o.username,
+			o.identifier,
+			o.id
+		]) if (typeof v === "string" && v) return v;
+	}
+	const uid = RequestContext.getUserId();
+	return typeof uid === "string" && uid ? uid : null;
+}
+/**
+* Empreinte SHA-256 du **payload** d'une requête (parties sérialisables : nom de
+* route + params + corps). Comparée par le store à l'empreinte mémorisée pour une
+* clé : si elle diffère, la clé est réutilisée pour une AUTRE requête → 422
+* (draft §2.4). Hash → empreinte courte (anti-DoS mémoire) + comparaison O(1).
+*/
+function computeFingerprint(parts) {
+	return createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+}
+/**
+* Cœur normatif : à partir de la clé client, de l'identité, du fingerprint et du
+* transport, rend le {@link IdempotencyVerdict} à appliquer. La réservation
+* (`store.begin`) est **atomique** (mono-thread JS côté mémoire, `SET … NX` côté
+* Redis) ; le store peut être sync (mémoire) ou async (distribué) → `begin` est
+* `await`é, d'où le retour `Promise<IdempotencyVerdict>`.
+*
+* Le `required` **effectif** = `required || isWs` : une mutation par socket exige
+* TOUJOURS une clé (le WS reconnecte/rejoue → muter sans garde-fou exposerait au
+* double-effet), tandis qu'en HTTP la clé n'est exigée qu'en mode strict
+* (`@Idempotent()` par défaut). Cela unifie les deux call-sites :
+*  - admin : `required=false` → exige la clé seulement en WS (comportement S4) ;
+*  - `@Idempotent()` : `required=true` (strict) → exige la clé même en HTTP ;
+*  - `@Idempotent({required:false})` : souple en HTTP, mais toujours strict en WS.
+*/
+async function evaluateIdempotency(opts) {
+	const requiredEffective = opts.required || opts.isWs;
+	if (!opts.clientKey) {
+		if (requiredEffective) return {
+			kind: "reject",
+			status: 400,
+			message: opts.isWs ? "Idempotency-Key required for socket mutations" : "Idempotency-Key required"
+		};
+		return { kind: "execute" };
+	}
+	if (!opts.store || !opts.identity) return { kind: "execute" };
+	const key = JSON.stringify([opts.identity, opts.clientKey]);
+	const outcome = await opts.store.begin(key, opts.fingerprint);
+	switch (outcome.state) {
+		case "mismatch": return {
+			kind: "reject",
+			status: 422,
+			message: "Idempotency-Key is already used",
+			detail: "This Idempotency-Key was used with a different payload; a key must not be reused across different requests."
+		};
+		case "in-flight": return {
+			kind: "reject",
+			status: 409,
+			message: "Conflict: an identical request is already in progress"
+		};
+		case "replayed": return {
+			kind: "replay",
+			response: outcome.response
+		};
+		default: return {
+			kind: "guarded",
+			key
+		};
+	}
+}
+//#endregion
+export { IDEMPOTENCY_KEY_MAX, computeFingerprint, evaluateIdempotency, isMutationMethod, resolveIdempotencyKey, resolveIdentity };

package/dist/nodefony/src/idempotencyGc.js

@@ -0,0 +1,32 @@
+import { GcScheduler } from "nodefony";
+//#region nodefony/src/idempotencyGc.ts
+/**
+* Arme un {@link GcScheduler} qui purge périodiquement les entrées expirées d'un
+* store d'idempotence — **UNIQUEMENT si le store expose `gc()`**.
+*
+* Pourquoi ce gating : un store à **expiration native** (`redis` → `SET … PX`) ou à
+* **purge passive** (`memory` → éviction FIFO au cap) **n'expose pas** `gc()` ; les
+* brancher sur un timer serait un no-op coûteux. Seul un store **SQL** (`drizzle`,
+* `DELETE WHERE expiresAt <= now`) en a besoin — et son `gc()` était jusqu'ici
+* **orphelin** (jamais appelé → fuite : les clés mortes s'accumulaient en base).
+* Ce helper ferme ce trou, et l'isole de `onKernelBoot` pour être **testable sans
+* booter un kernel**.
+*
+* @returns le scheduler armé (à `stop()` au shutdown), ou `null` si le store n'a
+*   pas de `gc()` (rien à planifier).
+*/
+function scheduleIdempotencyGc(store, opts) {
+	if (typeof store.gc !== "function") return null;
+	const runGc = store.gc.bind(store);
+	const scheduler = new GcScheduler({
+		intervalS: opts.intervalS,
+		jitter: opts.jitter,
+		run: () => runGc(),
+		onError: opts.onError
+	});
+	const armed = scheduler.start();
+	opts.log?.(armed ? `idempotency gc armed — purge every ${opts.intervalS}s (SQL store exposes gc())` : `idempotency gc disarmed — intervalS=${opts.intervalS} (delegated to cron / external)`);
+	return scheduler;
+}
+//#endregion
+export { scheduleIdempotencyGc };

package/dist/nodefony/src/idempotencyStoreRegistry.js

@@ -0,0 +1,36 @@
+//#region nodefony/src/idempotencyStoreRegistry.ts
+const factories = /* @__PURE__ */ new Map();
+/**
+* Enregistre (ou remplace) la fabrique d'un store d'idempotence distribué.
+* Appelée par l'application pour les adapters (`redis`/`drizzle`).
+*/
+function registerIdempotencyStore(name, factory) {
+	factories.set(name, factory);
+}
+/** Fabrique d'un store par nom, ou `undefined` si inconnu. */
+function getIdempotencyStoreFactory(name) {
+	return factories.get(name);
+}
+/**
+* Noms de stores distribués enregistrés (résolution `auto` + validation boot).
+* N'inclut PAS `"memory"` : dans `resolveAutoStore`, memory est le **fallback**
+* (per-pod), jamais une préférence à sélectionner — l'y mettre fausserait le choix.
+*/
+function listIdempotencyStores() {
+	return [...factories.keys()];
+}
+/**
+* Backends d'idempotence UTILISABLES, pour l'AFFICHAGE (écran Studio « Stores »).
+* Inclut le builtin `"memory"` (toujours présent via `@services`, per-pod) EN TÊTE
+* + les stores distribués enregistrés. Distinct de {@link listIdempotencyStores}
+* (distribués seuls, pour la résolution) : côté Studio, le store résolu doit
+* TOUJOURS figurer dans les backends dispo — sinon `resolved: "memory"` apparaît
+* absent de la liste (incohérence). Convention-frère : les autres briques
+* enregistrent leur builtin `memory` dans leur registre, donc `listXStores()`
+* l'inclut déjà ; idempotency pose son memory hors registre → on le rajoute ici.
+*/
+function listIdempotencyBackends() {
+	return ["memory", ...factories.keys()];
+}
+//#endregion
+export { getIdempotencyStoreFactory, listIdempotencyBackends, listIdempotencyStores, registerIdempotencyStore };

package/dist/nodefony/src/scopeCatalog.js

@@ -0,0 +1,40 @@
+import { extractActionScopes } from "../decorators/routerDecorators.js";
+import router_default from "../service/router.js";
+//#region nodefony/src/scopeCatalog.ts
+/**
+* P6.8 — **Découverte au boot** : scanne TOUTES les routes montées (`Router.routes`)
+* et agrège les scopes déclarés par `@RequireScope`, **regroupés par API** (préfixe
+* avant `:`). C'est la source du formulaire « créer une clé API » de Studio : les
+* scopes proposés DÉRIVENT du code (les routes), au lieu d'une liste plate de config
+* qui se périme dès qu'on ajoute un `@RequireScope` sans penser à la config.
+*
+* **Cold path** : appelé à la demande (ouverture du formulaire), jamais sur le hot
+* path requête. Lecture `Reflect` par route → coût proportionnel au nombre de routes,
+* payé une fois par consultation.
+*
+* @returns les groupes triés par nom d'API (chaque groupe a ses scopes triés).
+*/
+function collectDeclaredApiScopes() {
+	const byApi = /* @__PURE__ */ new Map();
+	for (const route of router_default.routes) {
+		const ctor = route.controller;
+		const method = route.classMethod;
+		if (!ctor || !method) continue;
+		for (const scope of extractActionScopes(ctor, method)) {
+			const i = scope.indexOf(":");
+			const api = i === -1 ? scope : scope.slice(0, i);
+			let set = byApi.get(api);
+			if (set === void 0) {
+				set = /* @__PURE__ */ new Set();
+				byApi.set(api, set);
+			}
+			set.add(scope);
+		}
+	}
+	return [...byApi.keys()].sort().map((api) => ({
+		api,
+		scopes: [...byApi.get(api)].sort()
+	}));
+}
+//#endregion
+export { collectDeclaredApiScopes, collectDeclaredApiScopes as default };

package/dist/nodefony/src/syslogFilters.js

@@ -0,0 +1,51 @@
+import { FLOW_STEPS, SEVERITY_NAMES } from "nodefony";
+//#region nodefony/src/syslogFilters.ts
+/**
+* Ce que le journal sait TRIER — un seul axe, le temps.
+*
+* Le nom est public (celui de la ligne rendue, `ILogRecord.timeStamp`) ; l'axe
+* technique du driver est l'`uid` du Pdu, un compteur monotone d'émission. Les
+* deux disent la même chose, à ceci près que l'`uid` départage deux logs de la
+* MÊME milliseconde — ce qu'un tri sur l'horodatage seul ne saurait pas faire.
+*/
+const SYSLOG_SORTABLE = ["timeStamp"];
+/**
+* Le vocabulaire de filtre du journal — une **donnée**, publiée telle quelle
+* dans le catalogue admin.
+*
+* Il remplace une lecture à la main qui acceptait tout et ne validait rien :
+* `?severity=CRITICAL` (au lieu de `CRITIC`), `?protocol=grpc`, `?flow=nimporte`
+* et même `?severty=ERROR` posaient un critère vide et rendaient le journal
+* ENTIER sous un `200` — la réponse qu'un exploitant lit comme « aucune erreur ».
+*
+* `severity` et `flow` sont **répétables** (`?severity=ERROR&severity=CRITIC`) :
+* c'est le OU dont le viewer a besoin, et la seule raison d'être de la nature
+* `{ each }` du contrat.
+*/
+const SYSLOG_FILTERS = {
+	/** Corrélation log↔requête (ALS) — match exact, la clé de la trace. */
+	requestId: "string",
+	/** Nom de module/service — inclusion insensible à la casse côté driver. */
+	module: "string",
+	/** Catégorie de message (msgid) — inclusion insensible à la casse. */
+	msgid: "string",
+	/** Protocole d'origine ; absent = les deux. */
+	protocol: ["ws", "http"],
+	/**
+	* Sévérités RFC 5424 — l'allowlist EST {@link SEVERITY_NAMES} (source unique
+	* du cœur), jamais une liste recopiée qui finirait par diverger de l'enum.
+	*/
+	severity: { each: SEVERITY_NAMES },
+	/**
+	* Étapes du cycle de vie — l'allowlist est dérivée de la table `FLOW_STEPS`
+	* elle-même : ajouter une étape suffit à la rendre filtrable, et aucune
+	* seconde liste ne peut se périmer.
+	*/
+	flow: { each: Object.keys(FLOW_STEPS) },
+	/** Borne basse d'horodatage (epoch ms, incluse). */
+	from: "int",
+	/** Borne haute d'horodatage (epoch ms, incluse). */
+	to: "int"
+};
+//#endregion
+export { SYSLOG_FILTERS, SYSLOG_SORTABLE };

package/dist/types/index.d.ts

@@ -0,0 +1,96 @@
+import { Kernel, Module } from "nodefony";
+import type { FrameworkConfigInput, FrameworkConfig } 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";
+import Controller from "./nodefony/src/Controller.js";
+import ResourceController from "./nodefony/src/ResourceController.js";
+import Resolver from "./nodefony/src/Resolver.js";
+import AdminBroker from "./nodefony/service/AdminBroker.js";
+import MemoryIdempotencyStore from "./nodefony/service/IdempotencyStore.js";
+import AdminApiController from "./nodefony/controller/AdminApiController.js";
+import SessionAuthController, { mountSessionAuthRoutes } from "./nodefony/controller/SessionAuthController.js";
+import TokenAuthController, { mountTokenAuthRoutes } from "./nodefony/controller/TokenAuthController.js";
+import IssuerMetadataController, { mountIssuerMetadataRoutes } from "./nodefony/controller/IssuerMetadataController.js";
+import ProtectedResourceMetadataController, { mountProtectedResourceRoutes, protectedResourceRoutePaths, collectProtectedResources } from "./nodefony/controller/ProtectedResourceMetadataController.js";
+import WebAuthnController, { mountWebAuthnRoutes } from "./nodefony/controller/WebAuthnController.js";
+import OAuth2Controller, { mountOAuth2Routes } from "./nodefony/controller/OAuth2Controller.js";
+import BenchController, { mountBenchRoutes } from "./nodefony/controller/BenchController.js";
+import ApiKeyController, { mountApiKeyRoutes } from "./nodefony/controller/ApiKeyController.js";
+import TotpController, { mountTotpRoutes } from "./nodefony/controller/TotpController.js";
+import { createKernelAdminApi } from "./nodefony/src/KernelAdminApi.js";
+import { createFrameworkAdminApi } from "./nodefony/src/FrameworkAdminApi.js";
+import { buildPlaygroundSnapshot } from "./nodefony/src/PlaygroundAdminApi.js";
+import { createSyslogAdminApi } from "./nodefony/src/SyslogAdminApi.js";
+import Eta from "./nodefony/service/Eta.js";
+import { mergeResolvers, mergeTypeDefs } from "@graphql-tools/merge";
+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;
+    }
+}
+declare class Framework extends Module<FrameworkConfig> {
+    #private;
+    constructor(kernel: Kernel);
+    /** JSON Schema de la config framework → data plane admin (config riche Studio). */
+    configSchema(): unknown;
+    /**
+     * Phase `onRegister` : valide la config du module via le builder
+     * ({@link defineFrameworkConfig}) AVANT que les `@services` (Router,
+     * AdminBroker — qui lisent `module.options.router`/`.adminBroker`) ne soient
+     * instanciés à `onBoot`. Une config invalide plante proprement ici avec un
+     * message clair, plutôt qu'un `undefined.x` silencieux en runtime
+     * (cf `feedback_config_validation_zod`). La config validée est ré-assignée à
+     * `this.options` (matérialise les défauts, préserve `router`/`adminBroker`).
+     */
+    onKernelRegister(): Promise<this>;
+    /**
+     * Phase `onBoot` (après les `@services` à `onPreBoot` → le défaut mémoire
+     * `idempotencyStore` est déjà enregistré, ET après l'`onPreBoot` des autres
+     * modules → le service `redis` est résoluble) : si la config sélectionne un
+     * store d'idempotence **distribué** (`idempotency.store` ≠ `memory`), le résout
+     * via le registre et **override** le service `idempotencyStore` → toutes les
+     * mutations (`@Idempotent` + data plane admin) dédupliquent cross-pod.
+     *
+     * **Politique en cas d'échec de résolution** (nom inconnu, ou store distribué
+     * qui ne peut pas s'initialiser — ex. `idempotency.store="redis"` sans module
+     * `@nodefony/redis`) :
+     *  - **prod** → **fatal** (rethrow → le module framework est `critical` → boot
+     *    avorté) : en cluster multi-pod, dégrader en silence vers le cache per-pod
+     *    serait du double-effet non dédupliqué (cf « pas de dégradation silencieuse »).
+     *  - **dev/test** (mono-pod) → **WARNING fort + fallback sur le cache mémoire**
+     *    déjà en place : la dédup per-pod suffit hors cluster, et on ne casse PAS le
+     *    framework (= le routeur) pour une option d'infra absente en local. Jamais
+     *    silencieux (le WARNING annonce la dégradation).
+     */
+    onKernelBoot(): Promise<this>;
+    /**
+     * Phase `onReady` (après le boot de tous les modules) : enregistre le
+     * producteur admin du kernel puis monte le data plane `/nodefony/<ns>/api/*`.
+     *
+     * Les autres modules s'enregistrent dans leur `onKernelBoot` / `onKernelReady`
+     * (le module realtime auto-enregistre son producteur `realtime` ici) → tous
+     * présents au moment du `mountAll()` qui clôt cette phase.
+     */
+    onKernelReady(): Promise<this>;
+}
+declare const graphql: {
+    mergeSchemas: typeof mergeSchemas;
+    makeExecutableSchema: typeof makeExecutableSchema;
+    mergeResolvers: typeof mergeResolvers;
+    mergeTypeDefs: typeof mergeTypeDefs;
+};
+export default Framework;
+export { Controller, ResourceController, Route, Router, Resolver, AdminBroker, MemoryIdempotencyStore, AdminApiController, SessionAuthController, mountSessionAuthRoutes, TokenAuthController, mountTokenAuthRoutes, IssuerMetadataController, mountIssuerMetadataRoutes, ProtectedResourceMetadataController, mountProtectedResourceRoutes, protectedResourceRoutePaths, collectProtectedResources, WebAuthnController, mountWebAuthnRoutes, OAuth2Controller, mountOAuth2Routes, BenchController, mountBenchRoutes, ApiKeyController, mountApiKeyRoutes, TotpController, mountTotpRoutes, createKernelAdminApi, createFrameworkAdminApi, createSyslogAdminApi, buildPlaygroundSnapshot, Eta, route, controller, controllers, 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, graphql, registerIdempotencyStore, getIdempotencyStoreFactory, listIdempotencyStores, };
+export { frameworkConfigSchema } from "./nodefony/config/config.js";
+export type { IdempotencyStoreFactory, IIdempotencyStoreFactoryContext, } from "./nodefony/src/idempotencyStoreRegistry.js";
+export type { SecurityClause, SecurityRequirement, CspDirectives, } from "./nodefony/decorators/routerDecorators.js";
+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 { 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

@@ -0,0 +1,41 @@
+import { z } from "zod";
+export declare const frameworkConfigSchema: z.ZodObject<{
+    router: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+    adminBroker: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+    idempotency: z.ZodDefault<z.ZodObject<{
+        store: z.ZodDefault<z.ZodString>;
+        gcIntervalS: z.ZodDefault<z.ZodNumber>;
+        gcJitter: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Type de sortie (config normalisée + défauts appliqués). */
+export type FrameworkConfig = z.infer<typeof frameworkConfigSchema>;
+/** Type d'entrée (toutes sections omissibles — défauts du schéma). */
+export type FrameworkConfigInput = z.input<typeof frameworkConfigSchema>;
+declare const _default: {
+    router?: {
+        [x: string]: unknown;
+    } | undefined;
+    adminBroker?: {
+        [x: string]: unknown;
+    } | undefined;
+    idempotency: {
+        store: string;
+        gcIntervalS: number;
+        gcJitter: boolean;
+    };
+    "module-security": {
+        areas: {
+            "nodefony-liveness": {
+                pattern: string;
+                authenticators: string[];
+                realtime: boolean;
+            };
+            "nodefony-admin": {
+                pattern: string;
+                authenticators: string[];
+            };
+        };
+    };
+};
+export default _default;

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

@@ -0,0 +1,27 @@
+import type { FrameworkConfig, FrameworkConfigInput } from "./config.js";
+/**
+ * Builder type-safe de la configuration de `@nodefony/framework` (PUR — ne
+ * retape JAMAIS un défaut : source unique = `./config.ts`).
+ *
+ * ⭐ TL;DR : MACHINERIE DE BOOT — on n'édite (presque) jamais ce fichier. Même
+ * pattern que `nodefony.config.ts` ↔ `defineConfig()` du core : `config.ts` PORTE
+ * la config (schéma + défauts), `define<X>Config()` la VALIDE au boot (parse +
+ * env + freeze) et publie le JSON Schema Studio.
+ *
+ * Valide la config brute contre le schéma Zod et matérialise les défauts.
+ * Une config invalide échoue avec un message lisible par champ (fail-loud au
+ * boot, plutôt qu'un `undefined.x` silencieux en runtime).
+ *
+ * @param config - configuration brute (sections omises = défauts sûrs).
+ * @returns config validée (défauts matérialisés, `router`/`adminBroker`
+ *   préservés tels quels — bags loose non strippés).
+ * @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;
+/**
+ * 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
+ * `.meta()` sont recopiés par `z.toJSONSchema`).
+ */
+export declare function frameworkConfigJsonSchema(): unknown;

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

@@ -0,0 +1,70 @@
+import type { ContextType } from "@nodefony/http";
+import Controller from "../src/Controller.js";
+/**
+ * Controller pont unique du data plane admin (Studio).
+ *
+ * Toutes les routes `/nodefony/<namespace>/api/*` montées par le broker
+ * pointent vers `AdminApiController.dispatch`. À l'exécution, le controller :
+ *  1. retrouve l'`IAdminRoute` via le nom de route (lookup O(1) du broker) ;
+ *  2. projette le `Context` HTTP en {@link IAdminRequest} (découplage core) ;
+ *  3. applique le RBAC (différé tant que P6/auth n'est pas câblé) ;
+ *  4. appelle le handler du producteur et sérialise le retour en JSON.
+ *
+ * Un seul controller réutilisé pour N endpoints : pas de génération dynamique
+ * de classes, et chaque route reste une vraie `Route` (404/405 du Router OK).
+ */
+declare class AdminApiController extends Controller {
+    /**
+     * Identité de l'instance qui répond — `NF_INSTANCE_ID` (k8s pod, worker)
+     * ou `pid` en fallback. Même convention que les providers realtime Studio.
+     * Calculée une fois (statique) : invariante sur la vie du process.
+     */
+    static readonly instanceId: string;
+    constructor(context: ContextType);
+    /**
+     * Action générique appelée par le Resolver pour toute route admin — DUPLEX
+     * (« API souveraine ») : même exécution sur les deux transports, seul
+     * l'emballage diffère.
+     *
+     *  - **HTTP** : rendu historique inchangé (`renderJson` + status + header
+     *    `x-nodefony-instance`).
+     *  - **Pont WS-RPC `api.request`** : valeur **nue** (le pont l'enveloppe
+     *    `{id, result}` — snapshot ≡ GET par construction) ; statut ≥ 400 →
+     *    {@link RpcError} (`data.status` + `data.body`), symétrie d'un `fetch`
+     *    qui expose son statut. L'identité d'instance n'est pas répétée par
+     *    réponse : une socket est tenue par UN process (info de connexion).
+     *
+     * @param args - variables de route positionnelles (`{id}`…), zippées avec
+     *   `route.variables` pour reconstruire `request.params`.
+     */
+    dispatch(...args: unknown[]): Promise<unknown>;
+    /**
+     * Résout la route admin, puis délègue l'exécution à la porte unique du cœur.
+     *
+     * Le LOOKUP est ce qui reste propre à ce transport : ici par **nom de route**
+     * (le Router l'impose), là où la CLI et le serveur MCP résolvent par couple
+     * namespace/chemin. Tout ce qui suit — autorisation, idempotence, handler,
+     * normalisation, traduction des erreurs — est commun, donc partagé
+     * ({@link executeAdminEndpoint}) : deux implémentations divergeraient, et
+     * c'est la porte la moins relue qui deviendrait la plus permissive.
+     */
+    private runAdmin;
+    /**
+     * Porte d'idempotence d'une **mutation** admin. La sémantique normative
+     * (`draft-ietf-httpapi-idempotency-key-header` : 400 clé requise WS / 409
+     * concurrent / 422 mismatch / rejeu mémorisé, clé scopée identité anti-IDOR,
+     * fingerprint du payload) vit dans le **helper partagé** `idempotency.ts` — le
+     * MÊME que le seam `Resolver` des controllers userland `@Idempotent`. Ici on ne
+     * fait que TRADUIRE le verdict neutre en forme admin (`shortCircuit` immédiat,
+     * ou callbacks `onSuccess`/`onFailure` autour de l'exécution).
+     *
+     * `required: false` → l'admin n'exige la clé qu'en WS (porté par `isWs` dans le
+     * helper) ; en HTTP, une mutation sans clé s'exécute directement (historique).
+     */
+    private idempotencyGate;
+    /** Projette le Context courant en requête admin normalisée. */
+    private buildRequest;
+    /** Extrait les rôles de l'utilisateur ALS sans coupler le core à `IUser`. */
+    private extractRoles;
+}
+export default AdminApiController;

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

@@ -0,0 +1,49 @@
+import type { Module } from "nodefony";
+import type { ContextType } from "@nodefony/http";
+import Controller from "../src/Controller.js";
+/**
+ * Endpoints HTTP de **gestion des clés API personnelles (PAT, P6.12)** — console
+ * « mes clés » façon GitHub, adaptateurs MINCES au-dessus du service `apiKeys`
+ * (`@nodefony/security`) :
+ *
+ *  - `POST   /nodefony/security/api/keys`        — body `{name, scopes?, expiresInDays?}`
+ *    → `201 {id, prefix, name, scopes, token, …}` (le `token` clair n'apparaît qu'ICI)
+ *  - `GET    /nodefony/security/api/keys`        — liste les clés du porteur (sans secret)
+ *  - `DELETE /nodefony/security/api/keys/{id}`   — révoque → `200 {ok:true}` / `404`
+ *    si la clé n'existe pas **ou** appartient à autrui (indiscernable, jamais 403)
+ *
+ * **PAS de `bypassFirewall`** (≠ login/token/oauth) : ces routes vivent DANS la
+ * zone data plane `^/nodefony/[^/]+/api(/|$)` → **session BFF requise**. Le porteur
+ * est TOUJOURS l'utilisateur courant (`authFlow.me`), jamais un paramètre — on ne
+ * crée/révoque jamais une clé pour autrui. Montés seulement si le service `apiKeys`
+ * existe (security chargé + clés activées) → 404, zéro surface, sinon.
+ *
+ * Erreurs mappées par DUCK-TYPING sur `code` (400/409/503) — framework ne peut pas
+ * importer les classes d'erreur de security.
+ */
+declare class ApiKeyController extends Controller {
+    #private;
+    constructor(context: ContextType);
+    /** Émission : crée une clé pour le porteur courant → token clair (1×). */
+    create(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /**
+     * Capacités/contraintes d'émission (plafond, scopes, préfixe, durée par défaut)
+     * — alimente le formulaire de création. Lecture pure, aucune valeur sensible ;
+     * accessible à tout porteur authentifié (zone data plane, session BFF).
+     */
+    capabilities(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /** Liste les clés du porteur courant (vue publique, sans secret). */
+    list(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /** Révocation : seulement une clé DU porteur courant (sinon 404, anti-énumération). */
+    revoke(id: unknown): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+}
+/**
+ * Monte les routes de gestion des clés API — appelé par le module framework à
+ * `onKernelReady`, seulement si le service `apiKeys` est présent.
+ *
+ * Routes nommées `security.apikeys.*` (espace data plane `/nodefony/security/api/*`).
+ * **Aucun `bypassFirewall`** : l'aire data plane (session BFF) les garde — c'est
+ * voulu (gérer ses clés exige d'être authentifié).
+ */
+export declare function mountApiKeyRoutes(frameworkModule: Module): void;
+export default ApiKeyController;

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

@@ -0,0 +1,45 @@
+import type { Module } from "nodefony";
+import type { ContextType } from "@nodefony/http";
+import Controller from "../src/Controller.js";
+/**
+ * Cible de mesure du **pipeline applicatif** — un controller ordinaire qui rend un
+ * corps figé, et rien d'autre.
+ *
+ * **Pourquoi un controller et pas un endpoint du data plane admin** : une route
+ * `/nodefony/<ns>/api/*` traverse, en plus du pipeline, la résolution de zone du
+ * firewall, un authenticator et le broker d'administration. La mesurer et la
+ * comparer à un handler Express nu revient à chronométrer deux choses
+ * différentes — et à imputer au framework le coût de son étage d'administration.
+ * Ce controller emprunte le chemin d'une route applicative normale : routing,
+ * contexte, sérialisation, réponse.
+ *
+ * **Chemin hors aire admin** : `/nodefony/kernel/bench` (deux segments, sans
+ * `/api/`) échappe au pattern `^/nodefony/[^/]+/api(/|$)` de la zone
+ * `nodefony-admin`, donc aucune zone ne s'y applique — pas de 401 à mesurer, et
+ * pas besoin d'ouvrir une zone dédiée. Il évite aussi le repli SPA mono-segment
+ * de Studio (`/nodefony/{page}`).
+ *
+ * **N'existe que sous `NF_BENCH_ROUTE=1`** : zéro surface en production par
+ * défaut. C'est un drapeau d'OUTILLAGE (banc), pas une option applicative — d'où
+ * une variable d'environnement plutôt qu'une clé de configuration.
+ */
+declare class BenchController extends Controller {
+    constructor(context: ContextType);
+    /** Rend le corps figé. Aucune lecture de kernel, aucun I/O, aucune allocation. */
+    index(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /**
+     * Dump de la sonde perf in-situ du http-kernel (`NF_PERF_PROBE=1`) : µs
+     * moyens par requête des postes enterScope / new HttpContext / leaveScope.
+     * Vit ICI (et pas dans `@nodefony/test`, `policy:"dev"`) parce que le décor
+     * de mesure est le mono `production` du banc — où le module test n'existe
+     * pas. `?reset=1` remet les compteurs à zéro (à faire après le warmup, pour
+     * ne pas diluer la mesure avec le code froid).
+     */
+    probe(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+}
+/**
+ * Monte la route de banc — appelée par le module framework, uniquement si
+ * `NF_BENCH_ROUTE=1`.
+ */
+export declare function mountBenchRoutes(frameworkModule: Module): void;
+export default BenchController;