@nodefony/http 10.0.0-alpha.1

package/dist/nodefony/service/HttpAdminApi.js

@@ -0,0 +1,376 @@
+import { SESSION_FACETS, SESSION_FILTERS, SESSION_STATS_FILTERS } from "../src/session/storage/sessionFilters.js";
+import { RATE_LIMIT_FILTERS } from "../src/rateLimit/rateLimitFilters.js";
+import { parseFilters, parsePageQuery } from "nodefony";
+//#region nodefony/service/HttpAdminApi.ts
+/** Nom du service HttpKernel dans le container (source unique). */
+const HTTP_KERNEL_SERVICE = "HttpKernel";
+/**
+* `limit`/`offset` du contrat de page, avec l'`offset` **matérialisé** : ces
+* endpoints le renvoient dans leur réponse, où l'absence n'a pas de sens (le
+* client lit « page 1 », pas « pas de décalage »). Le traducteur, lui, laisse
+* `offset` absent quand le client n'en demande pas — c'est le contrat.
+*/
+function pageParams(query) {
+	const parsed = parsePageQuery(query, { searchable: true });
+	return {
+		limit: parsed.limit,
+		offset: parsed.offset ?? 0,
+		...parsed.q !== void 0 ? { q: parsed.q } : {}
+	};
+}
+/**
+* Libellé d'identité de l'admin appelant (pour l'audit) — duck-typing prudent
+* sur l'`IUser` projeté dans `IAdminRequest.user`. Repli `"admin"`.
+*/
+function adminActor(user) {
+	if (user && typeof user === "object") {
+		const u = user;
+		if (typeof u.username === "string" && u.username) return u.username;
+		if (typeof u.identifier === "string" && u.identifier) return u.identifier;
+	}
+	return "admin";
+}
+/**
+* Identifiant de l'appelant authentifié pour le SCOPE self-service — lu sur l'IUser
+* projeté dans `IAdminRequest.user` (= `session.user`, posé au login). `null` si
+* absent/vide → le handler répond 401 (jamais de scope vide qui listerait les
+* sessions anonymes). **Jamais** dérivé d'un paramètre client (anti-IDOR).
+*/
+function currentIdentifier(user) {
+	if (user && typeof user === "object") {
+		const u = user;
+		if (typeof u.identifier === "string" && u.identifier.length > 0) return u.identifier;
+	}
+	return null;
+}
+/**
+* Producteur `IAdminApi` du module **http** — exposé sous `/nodefony/http/api/*`.
+*
+* 2ᵉ producteur du data plane admin (le 1er étant le kernel). Démontre le
+* pattern multi-modules : `@nodefony/http` n'importe QUE le contrat core
+* (`IAdminApi`) — jamais `@nodefony/framework` (dépendance circulaire). Il
+* s'enregistre auprès du broker via `IAdminRegistry` récupéré du container.
+*
+* Endpoints :
+*  - `GET /nodefony/http/api/servers` → liste des serveurs réseau + leur état
+*  - `GET /nodefony/http/api/info`    → résumé (serveurs prêts, ports, schemes)
+*
+* @param module - le module http (accès aux services serveur du container).
+* @returns le contrat admin de http, prêt à `registry.register()`.
+*/
+function createHttpAdminApi(module) {
+	/** Noms des services serveur enregistrés par le module http. */
+	const serverServices = [
+		"server-http",
+		"server-https",
+		"server-websocket",
+		"server-websocket-secure",
+		"server-static"
+	];
+	const readServer = (name) => {
+		const svc = module.get(name);
+		if (!svc) return null;
+		return {
+			service: name,
+			type: svc.type,
+			scheme: svc.scheme,
+			protocol: svc.protocol,
+			address: svc.address,
+			port: svc.port,
+			family: svc.family ?? null,
+			ready: svc.ready ?? false
+		};
+	};
+	const listServers = () => serverServices.map((name) => readServer(name)).filter((s) => s !== null);
+	const descriptor = {
+		label: "HTTP",
+		icon: "network",
+		order: 1
+	};
+	const endpoints = [
+		{
+			path: "servers",
+			summary: "Network servers (http/https/ws/wss/static) with listening state",
+			handler: () => listServers()
+		},
+		{
+			path: "info",
+			summary: "HTTP layer summary — ready servers, ports, schemes",
+			handler: () => {
+				const servers = listServers();
+				const ready = servers.filter((s) => s.ready);
+				return {
+					serversTotal: servers.length,
+					serversReady: ready.length,
+					ports: [...new Set(ready.map((s) => s.port).filter(Boolean))],
+					schemes: [...new Set(ready.map((s) => s.scheme).filter(Boolean))],
+					protocols: [...new Set(ready.map((s) => s.protocol).filter(Boolean))]
+				};
+			}
+		},
+		{
+			path: "rate-limit/list",
+			method: "GET",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Clés (IP) suivies par le rate-limit général, les plus bruyantes d'abord. Paginé serveur : ?limited&q&limit&offset. `enabled:false` = rate-limit désarmé en config (liste vide, pas une erreur).",
+			handler: async (request) => {
+				const { limit, offset, q } = pageParams(request.query);
+				const store = module.get(HTTP_KERNEL_SERVICE)?.rateLimitStore;
+				if (!store) return {
+					enabled: false,
+					trackedCount: 0,
+					rejectedTotal: 0,
+					items: [],
+					total: 0,
+					limit,
+					offset
+				};
+				const page = await store.listPage({
+					limit,
+					offset,
+					...parseFilters(request.query, RATE_LIMIT_FILTERS),
+					...q !== void 0 ? { q } : {}
+				});
+				return {
+					enabled: true,
+					trackedCount: store.trackedCount,
+					rejectedTotal: store.rejectedTotal,
+					items: page.items,
+					total: page.total,
+					limit,
+					offset
+				};
+			}
+		},
+		{
+			path: "sessions",
+			summary: "Session subsystem status + active count (web BFF auth)",
+			handler: async () => {
+				const svc = module.get("sessions");
+				if (!svc) return {
+					enabled: false,
+					active: 0
+				};
+				const inner = svc.storage?.inner ?? null;
+				const storage = inner?.constructor?.name ?? svc.storage?.constructor?.name ?? "none";
+				const driver = svc.options?.store ?? null;
+				const revocationHardened = inner !== null;
+				return {
+					enabled: true,
+					strategy: svc.sessionStrategy ?? null,
+					activation: "intent",
+					name: svc.defaultSessionName ?? null,
+					driver,
+					storage,
+					revocationHardened,
+					idleTimeoutS: svc.options?.idleTimeoutS ?? null,
+					absoluteTimeoutS: svc.options?.absoluteTimeoutS ?? null,
+					savePath: null,
+					active: null
+				};
+			}
+		},
+		{
+			path: "sessions/list",
+			method: "GET",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Sessions actives (ref/user/ip/ua/dates — jamais l'id de session). Paginé côté serveur : ?user&limit&offset. `total` absent et `nextCursor` présent sur un backend à curseur (Redis).",
+			page: {
+				sortable: () => {
+					const svc = module.get("sessions");
+					return svc?.supportsEnumeration() ? svc.sortableFields() : [];
+				},
+				filters: SESSION_FILTERS
+			},
+			handler: async (request) => {
+				const svc = module.get("sessions");
+				if (!svc) return {
+					status: 503,
+					body: { error: "session service unavailable" }
+				};
+				if (!svc.supportsEnumeration()) return {
+					status: 501,
+					body: { error: "session enumeration not supported by storage" }
+				};
+				const pageQuery = parsePageQuery(request.query, { sortable: svc.sortableFields() });
+				const { limit } = pageQuery;
+				const offset = pageQuery.offset ?? 0;
+				const page = await svc.listSessionsPage({
+					limit,
+					offset,
+					...pageQuery.cursor ? { cursor: pageQuery.cursor } : {},
+					...parseFilters(request.query, SESSION_FILTERS),
+					...pageQuery.order ? { order: pageQuery.order } : {}
+				});
+				return {
+					items: page.items,
+					total: page.total,
+					limit,
+					offset,
+					...page.nextCursor !== void 0 ? { nextCursor: page.nextCursor } : {}
+				};
+			}
+		},
+		{
+			path: "sessions/stats",
+			method: "GET",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Compteurs des sessions sur la collection ENTIÈRE (total, authentifiées, anonymes, utilisateurs distincts) — mêmes filtres que sessions/list. Un compteur `null` = le backend ne sait pas le calculer (Redis).",
+			page: {
+				filters: SESSION_STATS_FILTERS,
+				facets: SESSION_FACETS
+			},
+			handler: async (request) => {
+				const svc = module.get("sessions");
+				if (!svc) return {
+					status: 503,
+					body: { error: "session service unavailable" }
+				};
+				if (!svc.supportsEnumeration()) return {
+					status: 501,
+					body: { error: "session enumeration not supported by storage" }
+				};
+				parsePageQuery(request.query, {});
+				return svc.countSessionFacets(parseFilters(request.query, SESSION_STATS_FILTERS));
+			}
+		},
+		{
+			path: "sessions/{ref}/revoke",
+			method: "POST",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Révoque une session par sa référence publique (sess_…). Audité. 404 si la référence ne correspond à aucune session.",
+			handler: async (request) => {
+				const svc = module.get("sessions");
+				if (!svc) return {
+					status: 503,
+					body: { error: "session service unavailable" }
+				};
+				if (!svc.supportsEnumeration()) return {
+					status: 501,
+					body: { error: "session enumeration not supported by storage" }
+				};
+				const ref = request.params.ref;
+				if (typeof ref !== "string" || ref.length === 0) return {
+					status: 404,
+					body: { error: "not found" }
+				};
+				if (!await svc.destroyByRef(ref, adminActor(request.user))) return {
+					status: 404,
+					body: { error: "not found" }
+				};
+				return { ok: true };
+			}
+		},
+		{
+			path: "sessions/revoke-user/{identifier}",
+			method: "POST",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Déconnecte TOUTES les sessions d'un utilisateur (logout everywhere). Audité. Renvoie le nombre de sessions détruites.",
+			handler: async (request) => {
+				const svc = module.get("sessions");
+				if (!svc) return {
+					status: 503,
+					body: { error: "session service unavailable" }
+				};
+				if (!svc.supportsEnumeration()) return {
+					status: 501,
+					body: { error: "session enumeration not supported by storage" }
+				};
+				const identifier = request.params.identifier;
+				if (typeof identifier !== "string" || identifier.length === 0) return {
+					status: 400,
+					body: { error: "identifier required" }
+				};
+				return {
+					ok: true,
+					count: await svc.destroyByUser(identifier, adminActor(request.user))
+				};
+			}
+		},
+		{
+			path: "sessions/mine",
+			method: "GET",
+			public: true,
+			summary: "MES sessions (self-service) — ref/ip/ua/dates, scopées à l'appelant. Paginé côté serveur : ?limit&offset.",
+			page: {
+				sortable: () => {
+					const svc = module.get("sessions");
+					return svc?.supportsEnumeration() ? svc.sortableFields() : [];
+				},
+				filters: {}
+			},
+			handler: async (request) => {
+				const svc = module.get("sessions");
+				if (!svc) return {
+					status: 503,
+					body: { error: "session service unavailable" }
+				};
+				if (!svc.supportsEnumeration()) return {
+					status: 501,
+					body: { error: "session enumeration not supported by storage" }
+				};
+				const identifier = currentIdentifier(request.user);
+				if (!identifier) return {
+					status: 401,
+					body: { error: "unauthenticated" }
+				};
+				const ownQuery = parsePageQuery(request.query, { sortable: svc.sortableFields() });
+				parseFilters(request.query, {});
+				const { limit } = ownQuery;
+				const offset = ownQuery.offset ?? 0;
+				const page = await svc.listOwnSessionsPage(identifier, {
+					limit,
+					offset,
+					...ownQuery.cursor ? { cursor: ownQuery.cursor } : {},
+					...ownQuery.order ? { order: ownQuery.order } : {}
+				});
+				return {
+					items: page.items,
+					total: page.total,
+					limit,
+					offset,
+					...page.nextCursor !== void 0 ? { nextCursor: page.nextCursor } : {}
+				};
+			}
+		},
+		{
+			path: "sessions/mine/{ref}/revoke",
+			method: "POST",
+			public: true,
+			summary: "Révoque UNE de MES sessions par sa référence (sess_…). 404 si la référence n'est pas une de mes sessions. Audité.",
+			handler: async (request) => {
+				const svc = module.get("sessions");
+				if (!svc) return {
+					status: 503,
+					body: { error: "session service unavailable" }
+				};
+				if (!svc.supportsEnumeration()) return {
+					status: 501,
+					body: { error: "session enumeration not supported by storage" }
+				};
+				const identifier = currentIdentifier(request.user);
+				if (!identifier) return {
+					status: 401,
+					body: { error: "unauthenticated" }
+				};
+				const ref = request.params.ref;
+				if (typeof ref !== "string" || ref.length === 0) return {
+					status: 404,
+					body: { error: "not found" }
+				};
+				if (!await svc.destroyOwnByRef(identifier, ref, identifier)) return {
+					status: 404,
+					body: { error: "not found" }
+				};
+				return { ok: true };
+			}
+		}
+	];
+	return {
+		adminNamespace: "http",
+		adminDescriptor: () => descriptor,
+		adminEndpoints: () => endpoints
+	};
+}
+//#endregion
+export { createHttpAdminApi };

package/dist/nodefony/service/ProfilerAdminApi.js

@@ -0,0 +1,73 @@
+//#region nodefony/service/ProfilerAdminApi.ts
+/**
+* Producteur `IAdminApi` du **profiler** — exposé sous `/nodefony/profiler/api/*`.
+*
+* Namespace dédié (≠ replié dans `http`) car le profiling par requête est un
+* concern transverse : timing par phase, route, user, futur SQL/audit. Il a sa
+* propre entrée Studio et n'est monté qu'en **dev** (le module n'instancie le
+* {@link Profiler} qu'hors prod).
+*
+* Endpoints :
+*  - `GET /nodefony/profiler/api/recent`  → derniers profils (résumés, récent → ancien)
+*  - `GET /nodefony/profiler/api/{id}`    → profil complet (phases) d'un requestId
+*  - `DELETE /nodefony/profiler/api/recent` → vide le ring buffer
+*
+* La debug bar (toute page, dev) lit `X-Request-Id` de SON appel AJAX puis
+* fetch `/{id}` — corrélation client↔serveur gratuite.
+*
+* @param profiler - l'instance partagée du ring buffer (même que le hook kernel).
+* @returns le contrat admin du profiler, prêt à `registry.register()`.
+*/
+function createProfilerAdminApi(profiler) {
+	const descriptor = {
+		label: "Profiler",
+		icon: "bug",
+		order: 9
+	};
+	const endpoints = [
+		{
+			path: "recent",
+			summary: "Recent request profiles (summaries, newest first)",
+			handler: ({ query }) => {
+				const raw = query.limit;
+				const n = typeof raw === "string" ? parseInt(raw, 10) : NaN;
+				const limit = Number.isFinite(n) && n > 0 ? Math.min(n, 200) : 60;
+				return {
+					count: profiler.size,
+					entries: profiler.recent(limit)
+				};
+			}
+		},
+		{
+			path: "recent",
+			method: "DELETE",
+			summary: "Clear the profiler ring buffer",
+			handler: () => {
+				profiler.clear();
+				return { cleared: true };
+			}
+		},
+		{
+			path: "{id}",
+			summary: "Full profile (phase timeline) for a requestId",
+			handler: ({ params }) => {
+				const entry = profiler.get(params.id);
+				if (!entry) return {
+					status: 404,
+					body: {
+						error: "Profile not found",
+						requestId: params.id
+					}
+				};
+				return entry;
+			}
+		}
+	];
+	return {
+		adminNamespace: "profiler",
+		adminDescriptor: () => descriptor,
+		adminEndpoints: () => endpoints
+	};
+}
+//#endregion
+export { createProfilerAdminApi, createProfilerAdminApi as default };

package/dist/nodefony/service/audit-logger.js

@@ -0,0 +1,159 @@
+import { RequestContext } from "nodefony";
+import { performance } from "node:perf_hooks";
+//#region nodefony/service/audit-logger.ts
+/**
+* Severity derived from HTTP status code — RFC 9110 categories.
+* 1xx/2xx/3xx → INFO ; 4xx → WARNING ; 5xx → ERROR.
+* Unknown/missing status → INFO.
+*/
+function severityFromStatus(status) {
+	if (!status) return "INFO";
+	if (status >= 500) return "ERROR";
+	if (status >= 400) return "WARNING";
+	return "INFO";
+}
+/**
+* JSON audit logger — implements IRequestLogger so it slots into
+* `httpKernel.setRequestLogger(new JsonAuditLogger())`.
+*
+* Stateless singleton. Allocates one plain object + one JSON.stringify per
+* request — acceptable since this is the terminal log path (1 per req).
+*/
+var JsonAuditLogger = class {
+	includeStack;
+	maxCauseDepth;
+	/** Sampling divisor for 2xx/3xx logs (`1` = log all). Always ≥ 1. */
+	sampleRate;
+	/** Deterministic 0-based counter for `1/sampleRate` selection (no RNG). */
+	sampleCounter = 0;
+	/** T1 — `false` = audit nominal coupé (erreurs/4xx/5xx toujours audités). */
+	nominalEnabled;
+	constructor(opts = {}) {
+		this.includeStack = opts.includeStack ?? process.env.NODE_ENV !== "production";
+		this.maxCauseDepth = opts.maxCauseDepth ?? 5;
+		const rate = opts.sampleRate ?? 1;
+		this.sampleRate = Number.isFinite(rate) && rate >= 1 ? Math.floor(rate) : 1;
+		this.nominalEnabled = opts.nominal ?? true;
+	}
+	/**
+	* Decide whether the current HTTP request must be logged (audit sampling).
+	*
+	* Always `true` when `sampleRate <= 1`, on errors, and for `status >= 400`
+	* (failures are never sampled out). Otherwise selects 1 in `sampleRate` of
+	* the 2xx/3xx requests with a deterministic counter.
+	*
+	* Called by `Context.logRequest()` **before** `renderHttp`, so a sampled-out
+	* request allocates nothing and runs no `JSON.stringify`.
+	*
+	* @param context - the HTTP context being finalised
+	* @param error - error captured for this request, if any
+	* @returns `true` to render+log the entry, `false` to skip it
+	*/
+	shouldSample(context, error) {
+		const ctx = context;
+		if (!this.nominalEnabled) {
+			if (error ?? ctx.error) return true;
+			const status = ctx.response?.statusCode ?? null;
+			return status !== null && status >= 400;
+		}
+		if (this.sampleRate <= 1) return true;
+		if (error ?? ctx.error) return true;
+		const status = ctx.response?.statusCode ?? null;
+		if (status !== null && status >= 400) return true;
+		this.sampleCounter = (this.sampleCounter + 1) % this.sampleRate;
+		return this.sampleCounter === 0;
+	}
+	renderHttp(context, error) {
+		const ctx = context;
+		const status = ctx.response?.statusCode ?? null;
+		const headers = ctx.request?.headers ?? {};
+		const err = error ?? ctx.error ?? null;
+		const entry = {
+			ts: (/* @__PURE__ */ new Date()).toISOString(),
+			requestId: ctx.requestId,
+			userId: RequestContext.getUserId() ?? null,
+			type: "http",
+			scheme: ctx.scheme,
+			method: ctx.method,
+			url: ctx.url,
+			status,
+			durationMs: this.computeDurationMs(ctx.phases),
+			remoteAddress: ctx.remoteAddress ?? null,
+			host: ctx.getHost?.() ?? null,
+			userAgent: ctx.getUserAgent?.() ?? null,
+			hasAuthorization: Boolean(headers["authorization"]),
+			hasCookie: Boolean(headers["cookie"]),
+			phases: ctx.phases.length ? ctx.phases.map((p) => ({
+				name: p.name,
+				durationMs: p.durationMs ?? null
+			})) : void 0,
+			error: err ? this.serializeError(err, 0) : void 0
+		};
+		return {
+			text: JSON.stringify(entry),
+			severity: severityFromStatus(status ?? (err ? 500 : null)),
+			msgid: "audit"
+		};
+	}
+	renderWebsocket(context, error, acceptedProtocol) {
+		const ctx = context;
+		const status = ctx.response?.statusCode ?? null;
+		const headers = ctx.request?.headers ?? {};
+		const entry = {
+			ts: (/* @__PURE__ */ new Date()).toISOString(),
+			requestId: ctx.requestId,
+			userId: RequestContext.getUserId() ?? null,
+			type: "ws",
+			scheme: ctx.scheme,
+			method: ctx.method,
+			url: ctx.url,
+			status,
+			durationMs: this.computeDurationMs(ctx.phases),
+			remoteAddress: ctx.remoteAddress ?? null,
+			host: ctx.getHost?.() ?? null,
+			userAgent: ctx.getUserAgent?.() ?? null,
+			hasAuthorization: Boolean(headers["authorization"]),
+			hasCookie: Boolean(headers["cookie"]),
+			phases: ctx.phases.length ? ctx.phases.map((p) => ({
+				name: p.name,
+				durationMs: p.durationMs ?? null
+			})) : void 0,
+			protocol: acceptedProtocol ?? null,
+			error: error ? this.serializeError(error, 0) : void 0
+		};
+		return {
+			text: JSON.stringify(entry),
+			severity: error ? "ERROR" : "INFO",
+			msgid: "audit"
+		};
+	}
+	/**
+	* Total request duration computed from the first phase startMs to now.
+	* Returns null if timing is disabled (no phases recorded).
+	*/
+	computeDurationMs(phases) {
+		if (!phases.length) return null;
+		const first = phases[0];
+		if (typeof first.startMs !== "number") return null;
+		return performance.now() - first.startMs;
+	}
+	/**
+	* Serialise an Error (recursively for `cause` chain) into an AuditErrorEntry.
+	* Stack is included only when `includeStack === true` (dev default).
+	* Cause chain is capped at `maxCauseDepth`.
+	*/
+	serializeError(err, depth) {
+		const e = err;
+		const entry = {
+			name: e.name ?? "Error",
+			message: e.message ?? String(err)
+		};
+		if (typeof e.code === "number") entry.code = e.code;
+		if (typeof e.errorType === "string") entry.errorType = e.errorType;
+		if (this.includeStack && typeof e.stack === "string") entry.stack = e.stack;
+		if (e.cause && depth + 1 < this.maxCauseDepth) entry.cause = this.serializeError(e.cause, depth + 1);
+		return entry;
+	}
+};
+//#endregion
+export { JsonAuditLogger as default, severityFromStatus };