@nodefony/framework 10.0.0-alpha.1

package/dist/index.js

@@ -0,0 +1,211 @@
+import config_default, { frameworkConfigSchema } from "./nodefony/config/config.js";
+import { defineFrameworkConfig, frameworkConfigJsonSchema } from "./nodefony/config/defineModuleConfig.js";
+import { getIdempotencyStoreFactory, listIdempotencyBackends, listIdempotencyStores, registerIdempotencyStore } from "./nodefony/src/idempotencyStoreRegistry.js";
+import { RedisIdempotencyStore } from "./nodefony/src/RedisIdempotencyStore.js";
+import { scheduleIdempotencyGc } from "./nodefony/src/idempotencyGc.js";
+import Route from "./nodefony/src/Route.js";
+import Controller from "./nodefony/src/Controller.js";
+import { All, Anonymous, Body, BypassFirewall, Cookie, Csp, CsrfExempt, CsrfProtect, CurrentUser, Delete, Domain, Get, Head, Header, Headers, HttpCode, Idempotent, IsGranted, Options, Param, Patch, Post, Put, Query, Redirect, Req, RequireScope, Res, Scope, Session, UploadedFile, UploadedFiles, UseSession, controller, controllers, route, routeExpectsBodyStream } from "./nodefony/decorators/routerDecorators.js";
+import Resolver from "./nodefony/src/Resolver.js";
+import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import __decorate from "./_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import router_default from "./nodefony/service/router.js";
+import ResourceController from "./nodefony/src/ResourceController.js";
+import AdminApiController from "./nodefony/controller/AdminApiController.js";
+import AdminBroker_default from "./nodefony/service/AdminBroker.js";
+import IdempotencyStore_default from "./nodefony/service/IdempotencyStore.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, { collectProtectedResources, mountProtectedResourceRoutes, protectedResourceRoutePaths } 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 { buildPlaygroundSnapshot } from "./nodefony/src/PlaygroundAdminApi.js";
+import { createFrameworkAdminApi } from "./nodefony/src/FrameworkAdminApi.js";
+import { createSyslogAdminApi } from "./nodefony/src/SyslogAdminApi.js";
+import Eta from "./nodefony/service/Eta.js";
+import path from "node:path";
+import { AUTO_STORE, EMPTY_INFRA, Kernel, Module, readStoreLocation, resolveAutoStore, services } from "nodefony";
+import { mergeResolvers, mergeTypeDefs } from "@graphql-tools/merge";
+import { makeExecutableSchema, mergeSchemas } from "@graphql-tools/schema";
+//#region index.ts
+registerIdempotencyStore("redis", (ctx) => {
+	const redis = ctx.module.kernel?.container?.get("redis");
+	if (!redis) throw new Error("the @nodefony/redis module is not loaded (add use(\"@nodefony/redis\") in nodefony.config.ts)");
+	return new RedisIdempotencyStore(() => redis.getClient("main") ?? null, void 0, void 0, () => typeof redis.keyPrefix === "function" ? redis.keyPrefix("nf:idem") : "nf:idem");
+});
+let Framework = class Framework extends Module {
+	/** Balayage périodique du store d'idempotence SQL (drizzle) — `null` sinon. */
+	#idempotencyGc = null;
+	/**
+	* Store d'idempotence distribué (drizzle/redis) posé au container, retenu pour
+	* rafraîchir sa `location` au `onKernelReady` (à `onKernelBoot` l'ORM n'est pas
+	* encore connecté → `readStoreLocation` vide). `null` = repli mémoire (per-pod).
+	*/
+	#idempotencyStore = null;
+	constructor(kernel) {
+		super("framework", kernel, import.meta.url, config_default);
+	}
+	/** JSON Schema de la config framework → data plane admin (config riche Studio). */
+	configSchema() {
+		return frameworkConfigJsonSchema();
+	}
+	/**
+	* 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`).
+	*/
+	async onKernelRegister() {
+		this.options = defineFrameworkConfig(this.options ?? {});
+		return 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).
+	*/
+	async onKernelBoot() {
+		const configured = this.options?.idempotency?.store ?? AUTO_STORE;
+		let name = configured;
+		let reason = `store explicitement configuré ("${configured}")`;
+		if (name === AUTO_STORE) {
+			const auto = resolveAutoStore("ephemeral", this.kernel?.infra ?? EMPTY_INFRA, listIdempotencyBackends());
+			name = auto.store;
+			reason = auto.reason;
+			this.log(`idempotency.store "auto" → "${name}" (${auto.reason})`, "INFO");
+		}
+		if (name === "memory") {
+			if (this.kernel?.environment === "production") this.log("idempotency.store \"memory\" en PRODUCTION — déduplication per-pod uniquement : un rejeu routé vers un autre pod n'est pas dédupliqué (double-effet possible). Déclarer une infra partagée (NF_REDIS_URL ou NF_DATABASE_URL).", "WARNING");
+			this.kernel?.registerStoreResolution({
+				brick: "idempotency",
+				nature: "ephemeral",
+				configured,
+				resolved: "memory",
+				available: listIdempotencyBackends(),
+				reason,
+				configPath: "framework.idempotency.store"
+			});
+			return this;
+		}
+		try {
+			const factory = getIdempotencyStoreFactory(name);
+			if (!factory) throw new Error(`not registered (known distributed stores: [${listIdempotencyStores().join(", ") || "none"}])`);
+			const store = factory({
+				module: this,
+				config: this.options
+			});
+			this.set("idempotencyStore", store);
+			this.#idempotencyStore = store;
+			this.log(`Idempotency store → "${name}" (distributed)`, "INFO");
+			this.kernel?.registerStoreResolution({
+				brick: "idempotency",
+				nature: "ephemeral",
+				configured,
+				resolved: name,
+				available: listIdempotencyBackends(),
+				reason,
+				configPath: "framework.idempotency.store",
+				location: readStoreLocation(store)
+			});
+			const idem = this.options.idempotency;
+			this.#idempotencyGc = scheduleIdempotencyGc(store, {
+				intervalS: idem.gcIntervalS,
+				jitter: idem.gcJitter,
+				onError: (e) => this.log(e, "WARNING"),
+				log: (m) => this.log(m, "INFO")
+			});
+			if (this.#idempotencyGc) this.kernel?.once("onTerminate", () => this.#idempotencyGc?.stop());
+		} catch (e) {
+			const msg = `[@nodefony/framework] idempotency.store="${name}" failed to initialize: ${e.message}.`;
+			if (this.kernel?.environment === "production") throw new Error(`${msg} A distributed store is mandatory in production.`, { cause: e });
+			this.log(`${msg} Falling back to the per-pod "memory" store (dev/test only; a distributed store is required for a multi-pod cluster).`, "WARNING");
+		}
+		return 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.
+	*/
+	async onKernelReady() {
+		const idemLocation = readStoreLocation(this.#idempotencyStore);
+		if (idemLocation && this.kernel) {
+			const current = this.kernel.storeResolutions.find((r) => r.brick === "idempotency");
+			if (current && !current.location) this.kernel.registerStoreResolution({
+				...current,
+				location: idemLocation
+			});
+		}
+		const broker = this.kernel?.container?.get("adminBroker");
+		if (broker && this.kernel) {
+			if (!broker.has("kernel")) broker.register(createKernelAdminApi(this.kernel));
+			if (!broker.has("framework")) broker.register(createFrameworkAdminApi(broker, { playground: this.kernel.environment === "development" || Boolean(this.kernel.debug) }));
+			if (this.kernel.syslog && !broker.has("syslog")) {
+				const logDir = path.resolve(process.cwd(), this.kernel.options?.log?.dir ?? "logs");
+				broker.register(createSyslogAdminApi(this.kernel.syslog, {
+					logDir,
+					enableFiles: this.kernel.environment !== "production",
+					environment: this.kernel.environment
+				}));
+			}
+			broker.mountAll();
+		}
+		if (this.kernel?.container?.get("authFlow")) mountSessionAuthRoutes(this);
+		if (this.kernel?.container?.get("tokenService")) {
+			mountTokenAuthRoutes(this);
+			const issuer = this.kernel.container.get("tokenService")?.publishedIssuer();
+			if (issuer) mountIssuerMetadataRoutes(this, issuer);
+		}
+		const container = this.kernel?.container;
+		if (container) {
+			const mountedCount = mountProtectedResourceRoutes(this, collectProtectedResources(container));
+			if (mountedCount > 0) this.log(`OAuth resource server — ${mountedCount} protected resource document(s) published (RFC 9728)`, "DEBUG");
+		}
+		if (this.kernel?.container?.get("webauthn")) mountWebAuthnRoutes(this);
+		if (this.kernel?.container?.get("oauth2")) mountOAuth2Routes(this);
+		if (process.env.NF_BENCH_ROUTE === "1") mountBenchRoutes(this);
+		if (this.kernel?.container?.get("apiKeys")) mountApiKeyRoutes(this);
+		if (this.kernel?.container?.get("totp")) mountTotpRoutes(this);
+		return this;
+	}
+};
+Framework = __decorate([services([
+	router_default,
+	Eta,
+	AdminBroker_default,
+	IdempotencyStore_default
+]), __decorateMetadata("design:paramtypes", [typeof Kernel === "undefined" ? Object : Kernel])], Framework);
+const graphql = {
+	mergeSchemas,
+	makeExecutableSchema,
+	mergeResolvers,
+	mergeTypeDefs
+};
+var framework_default = Framework;
+//#endregion
+export { AdminApiController, AdminBroker_default as AdminBroker, All, Anonymous, ApiKeyController, BenchController, Body, BypassFirewall, Controller, Cookie, Csp, CsrfExempt, CsrfProtect, CurrentUser, Delete, Domain, Eta, Get, Head, Header, Headers, HttpCode, Idempotent, IsGranted, IssuerMetadataController, IdempotencyStore_default as MemoryIdempotencyStore, OAuth2Controller, Options, Param, Patch, Post, ProtectedResourceMetadataController, Put, Query, Redirect, Req, RequireScope, Res, Resolver, ResourceController, Route, router_default as Router, Scope, Session, SessionAuthController, TokenAuthController, TotpController, UploadedFile, UploadedFiles, UseSession, WebAuthnController, buildPlaygroundSnapshot, collectProtectedResources, controller, controllers, createFrameworkAdminApi, createKernelAdminApi, createSyslogAdminApi, framework_default as default, defineFrameworkConfig, frameworkConfigJsonSchema, frameworkConfigSchema, getIdempotencyStoreFactory, graphql, listIdempotencyStores, mountApiKeyRoutes, mountBenchRoutes, mountIssuerMetadataRoutes, mountOAuth2Routes, mountProtectedResourceRoutes, mountSessionAuthRoutes, mountTokenAuthRoutes, mountTotpRoutes, mountWebAuthnRoutes, protectedResourceRoutePaths, registerIdempotencyStore, route, routeExpectsBodyStream };

package/dist/nodefony/config/config.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+//#region nodefony/config/config.ts
+/**
+* @nodefony/framework — CONFIGURATION DU MODULE (schéma Zod = source unique).
+*
+* ⭐ TL;DR : CE SCHÉMA EST LA CONFIG. Chaque `.default(...)` = la valeur d'usine ;
+* changer un défaut du module = ÉDITER ICI (et nulle part ailleurs). L'app, elle,
+* surcharge via `use("@nodefony/...", { … })` dans SON `nodefony.config.ts`.
+*
+* RÈGLE D'OR (ADR-0006) : ce fichier porte le **schéma Zod commenté** (type +
+* validation + défaut + doc) ET matérialise les défauts. Aucune valeur n'est
+* re-tapée ailleurs. Le builder (`defineModuleConfig.ts` →
+* `defineFrameworkConfig`) importe le schéma D'ICI (nœud bas : ce fichier
+* n'importe que `zod` → pas de cycle). La config est validée au boot du Module
+* class (hook `onKernelRegister`, cf `index.ts`) → plante propre avec un
+* message clair si la config est invalide, plutôt qu'un `undefined.x`
+* silencieux en runtime.
+*
+* ## Surface volontairement minimale
+*
+* Le framework n'expose presque aucune option : son rôle (Router/Resolver/
+* Controller/décorateurs) est piloté par les décorateurs et le code, pas par la
+* config. Les seules clés réellement consommées dans le source :
+*   - `router` / `adminBroker` — bags d'options de **Service de base** transmis
+*     tels quels aux Services `Router` / `AdminBroker` (4ᵉ arg du `super(...)`).
+*     Aucune forme métier figée → `looseObject` + `optional` (ne RIEN stripper,
+*     absent par défaut = `undefined`, comme avant validation).
+*
+* ## Pureté
+*
+* Aucun `Nodefony.getKernel()` ni `process.env` → sortie déterministe,
+* sérialisable en JSON Schema (`frameworkConfigJsonSchema` dans
+* `defineModuleConfig.ts`) pour Studio.
+*/
+const serviceOptionsSchema = z.looseObject({});
+const idempotencySchema = z.strictObject({
+	store: z.string().default("auto").describe("Backing du cache d'idempotence des mutations (`@Idempotent` + data plane admin). `auto` (défaut) = suit l'infra déclarée (NF_REDIS_URL → redis, sinon NF_DATABASE_URL → drizzle, sinon memory per-pod). `memory` = cache per-pod (la socket reste affine à son pod). Un nom DISTRIBUÉ (`redis`, `drizzle`) est enregistré via `registerIdempotencyStore(name, …)` (auto-register par les adapters) ET résolu au boot → override du défaut mémoire. Un nom EXPLICITE dont l'initialisation échoue AVORTE le boot en PRODUCTION uniquement (fail-loud : pas de dédup silencieuse en cluster) ; en dev/test, WARNING + repli mémoire pour ne pas bloquer une machine sans infra. Reco prod multi-pod : `redis` (SET NX + TTL natif)."),
+	gcIntervalS: z.number().int().min(0).default(600).describe("Intervalle de purge des clés d'idempotence expirées (s), HORS hot-path. N'a d'effet QUE pour un store SANS expiration native (`drizzle` → `DELETE WHERE expiresAt<=now`) ; `redis` (TTL `PX`) et `memory` (purge passive) l'ignorent. 0 = timer désarmé (cron/k8s)."),
+	gcJitter: z.boolean().default(true).describe("Étale le départ du gc d'idempotence par process — anti thundering-herd sur le store SQL partagé en cluster.")
+});
+const frameworkConfigSchema = z.strictObject({
+	router: serviceOptionsSchema.optional().describe("Options transmises au Service `Router` (bag d'options de Service de base : logger, timers…). Loose : non strippées. Absent (défaut) = aucune."),
+	adminBroker: serviceOptionsSchema.optional().describe("Options transmises au Service `AdminBroker` (data plane admin `/nodefony/<ns>/api/*`). Loose : non strippées. Absent (défaut) = aucune."),
+	idempotency: idempotencySchema.default(() => idempotencySchema.parse({})).describe("Idempotence des mutations (anti double-effet). Cf draft-ietf-httpapi-idempotency-key-header.")
+}).describe("Configuration de @nodefony/framework.");
+var config_default = {
+	...frameworkConfigSchema.parse({}),
+	"module-security": { areas: {
+		"nodefony-liveness": {
+			pattern: "^/nodefony/kernel/api/livez$",
+			authenticators: ["session", "anonymous"],
+			realtime: false
+		},
+		"nodefony-admin": {
+			pattern: "^/nodefony/[^/]+/api(/|$)",
+			authenticators: ["session"]
+		}
+	} }
+};
+//#endregion
+export { config_default as default, frameworkConfigSchema };

package/dist/nodefony/config/defineModuleConfig.js

@@ -0,0 +1,36 @@
+import { frameworkConfigSchema } from "./config.js";
+import { parseModuleConfig } from "nodefony";
+import { z } from "zod";
+//#region nodefony/config/defineModuleConfig.ts
+/**
+* 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.
+*/
+function defineFrameworkConfig(config = {}) {
+	return parseModuleConfig(frameworkConfigSchema, config, "@nodefony/framework");
+}
+/**
+* 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`).
+*/
+function frameworkConfigJsonSchema() {
+	return z.toJSONSchema(frameworkConfigSchema);
+}
+//#endregion
+export { defineFrameworkConfig, frameworkConfigJsonSchema };

package/dist/nodefony/controller/AdminApiController.js

@@ -0,0 +1,163 @@
+import Controller from "../src/Controller.js";
+import { computeFingerprint, evaluateIdempotency, resolveIdempotencyKey, resolveIdentity } from "../src/idempotency.js";
+import { RequestContext, RpcError, executeAdminEndpoint } from "nodefony";
+//#region nodefony/controller/AdminApiController.ts
+/**
+* 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).
+*/
+var AdminApiController = 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 instanceId = process.env.NF_INSTANCE_ID ?? String(process.pid);
+	constructor(context) {
+		super("AdminApiController", context);
+	}
+	/**
+	* 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`.
+	*/
+	async dispatch(...args) {
+		const { status, headers, body } = await this.runAdmin(args);
+		if (this.context?.type?.startsWith("websocket")) {
+			if (status >= 400) {
+				const message = body?.error ?? "admin error";
+				throw new RpcError(message, -32e3, {
+					status,
+					body
+				});
+			}
+			return body;
+		}
+		return this.renderJson(body, status, {
+			...headers,
+			"x-nodefony-instance": AdminApiController.instanceId
+		});
+	}
+	/**
+	* 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.
+	*/
+	async runAdmin(args) {
+		const broker = this.get("adminBroker");
+		const name = this.route?.name;
+		const adminRoute = broker && name ? broker.resolve(name) : void 0;
+		if (!adminRoute) return {
+			status: 500,
+			body: {
+				error: "Admin endpoint not registered",
+				route: name ?? null
+			}
+		};
+		return executeAdminEndpoint({
+			endpoint: adminRoute.endpoint,
+			request: this.buildRequest(args),
+			requiredRole: adminRoute.role,
+			gate: (request) => this.idempotencyGate(adminRoute, request),
+			onServerError: (error) => this.log(error, "ERROR")
+		});
+	}
+	/**
+	* 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).
+	*/
+	async idempotencyGate(adminRoute, request) {
+		if (adminRoute.method === "GET") return {};
+		const store = this.get("idempotencyStore");
+		const verdict = await evaluateIdempotency({
+			store,
+			identity: resolveIdentity(request.user),
+			clientKey: request.idempotencyKey,
+			fingerprint: computeFingerprint([
+				adminRoute.name,
+				request.params,
+				request.body ?? null
+			]),
+			isWs: Boolean((this.context?.type)?.startsWith("websocket")),
+			required: false
+		});
+		switch (verdict.kind) {
+			case "reject": return { shortCircuit: {
+				status: verdict.status,
+				body: verdict.detail ? {
+					error: verdict.message,
+					detail: verdict.detail
+				} : { error: verdict.message }
+			} };
+			case "replay": return { shortCircuit: verdict.response };
+			case "guarded": return {
+				onSuccess: (resp) => store?.complete(verdict.key, resp),
+				onFailure: () => store?.abort(verdict.key)
+			};
+			default: return {};
+		}
+	}
+	/** Projette le Context courant en requête admin normalisée. */
+	buildRequest(args) {
+		const names = this.route?.variables ?? [];
+		const params = {};
+		for (let i = 0; i < names.length; i++) {
+			const key = names[i];
+			if (typeof key === "string" && args[i] !== void 0) params[key] = String(args[i]);
+		}
+		const als = RequestContext.get();
+		const user = als?.user ?? null;
+		return {
+			params,
+			query: this.query ?? {},
+			body: als?.body !== void 0 ? als.body : this.queryPost ?? null,
+			user,
+			roles: this.extractRoles(user),
+			requestId: als?.requestId,
+			idempotencyKey: resolveIdempotencyKey(als?.idempotencyKey, this.context?.request?.headers?.["idempotency-key"])
+		};
+	}
+	/** Extrait les rôles de l'utilisateur ALS sans coupler le core à `IUser`. */
+	extractRoles(user) {
+		if (user && typeof user === "object" && "roles" in user) {
+			const roles = user.roles;
+			if (Array.isArray(roles)) return roles.filter((r) => typeof r === "string");
+		}
+		return [];
+	}
+};
+//#endregion
+export { AdminApiController as default };

package/dist/nodefony/controller/ApiKeyController.js

@@ -0,0 +1,151 @@
+import Controller from "../src/Controller.js";
+import router_default from "../service/router.js";
+import { collectDeclaredApiScopes } from "../src/scopeCatalog.js";
+//#region nodefony/controller/ApiKeyController.ts
+let mounted = false;
+/**
+* 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.
+*/
+var ApiKeyController = class extends Controller {
+	constructor(context) {
+		super("ApiKeyController", context);
+	}
+	/** Émission : crée une clé pour le porteur courant → token clair (1×). */
+	async create() {
+		const svc = this.#manager();
+		if (!svc || !svc.isEnabled()) return this.renderJson({ error: "API keys unavailable" }, 503);
+		const subject = await this.#currentSubject();
+		if (subject === null) return this.renderJson({ error: "Unauthorized" }, 401);
+		const body = this.queryPost ?? {};
+		try {
+			const created = await svc.createForSubject(subject, "user", {
+				name: body.name,
+				scopes: body.scopes,
+				expiresInDays: body.expiresInDays
+			});
+			return this.renderJson(created, 201);
+		} catch (e) {
+			return this.#renderApiKeyError(e);
+		}
+	}
+	/**
+	* 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).
+	*/
+	async capabilities() {
+		const svc = this.#manager();
+		if (!svc || !svc.isEnabled()) return this.renderJson({ error: "API keys unavailable" }, 503);
+		const caps = svc.describeCapabilities();
+		return this.renderJson({
+			...caps,
+			declaredScopes: collectDeclaredApiScopes()
+		});
+	}
+	/** Liste les clés du porteur courant (vue publique, sans secret). */
+	async list() {
+		const svc = this.#manager();
+		if (!svc || !svc.isEnabled()) return this.renderJson({ error: "API keys unavailable" }, 503);
+		const subject = await this.#currentSubject();
+		if (subject === null) return this.renderJson({ error: "Unauthorized" }, 401);
+		return this.renderJson({ keys: await svc.listForSubject(subject) });
+	}
+	/** Révocation : seulement une clé DU porteur courant (sinon 404, anti-énumération). */
+	async revoke(id) {
+		const svc = this.#manager();
+		if (!svc || !svc.isEnabled()) return this.renderJson({ error: "API keys unavailable" }, 503);
+		const subject = await this.#currentSubject();
+		if (subject === null) return this.renderJson({ error: "Unauthorized" }, 401);
+		if (typeof id !== "string" || id.length === 0) return this.renderJson({ error: "Not found" }, 404);
+		if (!await svc.revokeForSubject(subject, id)) return this.renderJson({ error: "Not found" }, 404);
+		return this.renderJson({ ok: true });
+	}
+	#manager() {
+		return this.get("apiKeys") ?? null;
+	}
+	#flow() {
+		return this.get("authFlow") ?? null;
+	}
+	/** Identifiant du porteur courant (session BFF revalidée), ou `null` si non authentifié. */
+	async #currentSubject() {
+		const flow = this.#flow();
+		if (!flow) return null;
+		const me = await flow.me(this.context);
+		return me && typeof me.username === "string" ? me.username : null;
+	}
+	#renderApiKeyError(e) {
+		const code = e.code;
+		if (code === 400) {
+			const message = e.message;
+			return this.renderJson({ error: typeof message === "string" ? message : "Bad request" }, 400);
+		}
+		if (code === 409) return this.renderJson({ error: "API key limit reached" }, 409);
+		if (code === 503) return this.renderJson({ error: "API keys unavailable" }, 503);
+		throw e;
+	}
+};
+/**
+* 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é).
+*/
+function mountApiKeyRoutes(frameworkModule) {
+	if (mounted) return;
+	const base = "/nodefony/security/api/keys";
+	const routes = [
+		[
+			"security.apikeys.create",
+			base,
+			"POST",
+			"create"
+		],
+		[
+			"security.apikeys.list",
+			base,
+			"GET",
+			"list"
+		],
+		[
+			"security.apikeys.capabilities",
+			`${base}/capabilities`,
+			"GET",
+			"capabilities"
+		],
+		[
+			"security.apikeys.revoke",
+			`${base}/{id}`,
+			"DELETE",
+			"revoke"
+		]
+	];
+	for (const [name, path, method, classMethod] of routes) router_default.createRoute(name, {
+		path,
+		constructor: ApiKeyController,
+		classMethod,
+		requirements: { methods: [method] }
+	});
+	if (!Object.prototype.hasOwnProperty.call(ApiKeyController.prototype, "module")) router_default.setController(ApiKeyController, frameworkModule);
+	mounted = true;
+}
+//#endregion
+export { ApiKeyController as default, mountApiKeyRoutes };