@nodefony/security 10.0.0-alpha.1

package/dist/nodefony/src/admin/SecurityAdminApi.js

@@ -0,0 +1,495 @@
+import { TOKEN_FACETS, TOKEN_FILTERS, TOKEN_STATS_FILTERS } from "../token/tokenFilters.js";
+import { AUDIT_FILTERS } from "../audit/auditFilters.js";
+import { adminActor, auditAdmin } from "./adminAudit.js";
+import { webhookAdminEndpoints } from "./WebhookAdminApi.js";
+import { parseFilters, parsePageQuery } from "nodefony";
+//#region nodefony/src/admin/SecurityAdminApi.ts
+/**
+* Déduit le **driver** logique d'un store à partir de son nom de classe — le
+* `tokenService` connaît le driver config (`tokenStore.store`) mais ne l'expose
+* pas au container ; on le re-dérive du store réel posé (miroir du pattern
+* `HttpAdminApi.sessions` qui lit `storage.constructor.name`). Mapping fermé sur
+* les implémentations connues ({@link ITokenStore}) ; `null` pour un store tiers
+* inconnu (honnête — on n'invente pas un driver).
+*
+* @param className - `store.constructor.name` (ex. `DrizzleTokenStore`).
+* @returns driver logique, ou `null` si la classe n'est pas reconnue.
+*/
+function tokenStoreDriver(className) {
+	switch (className) {
+		case "MemoryTokenStore": return "memory";
+		case "DrizzleTokenStore":
+		case "MongooseTokenStore": return "orm";
+		case "RedisTokenStore": return "redis";
+		default: return null;
+	}
+}
+/** Défaut/cap de taille de page du listing admin des clés API. */
+const KEYS_DEFAULT_LIMIT = 50;
+const KEYS_MAX_LIMIT = 200;
+/**
+* Traduit la query string admin en {@link ITokenListQuery} bornée (`limit` par
+* défaut 50, cap 200 ; pagination, tri et filtres de {@link TOKEN_FILTERS}).
+*
+* **UN SEUL traducteur par dimension, jamais deux.** Pour la page et le tri,
+* `parsePageQuery` ; pour les filtres, `parseFilters`. En appeler un second sans
+* son allowlist ferait refuser en 400 ce que le premier venait d'accepter, et
+* aucun test unitaire ne le verrait (chaque appel est correct isolément).
+*
+* Un filtre inconnu ou mal formé est désormais **refusé** (400) au lieu d'être
+* ignoré : `?status=revoqué` rendait la liste ENTIÈRE, que la console affichait
+* comme le résultat du filtre demandé.
+*
+* @param query - `request.query` du broker admin.
+* @param sortable - champs que le backend branché sait trier ; un `?order=`
+*   portant autre chose est refusé en 400 par le traducteur. Liste vide (store à
+*   curseur, store absent) ⇒ tout tri est refusé, ce qui est la vérité du backend.
+*/
+function parseTokenListQuery(query, sortable) {
+	const page = parsePageQuery(query, {
+		defaultLimit: KEYS_DEFAULT_LIMIT,
+		maxLimit: KEYS_MAX_LIMIT,
+		sortable
+	});
+	const filters = parseFilters(query, TOKEN_FILTERS);
+	const out = {
+		limit: page.limit,
+		...filters
+	};
+	if (page.offset !== void 0) out.offset = page.offset;
+	if (page.cursor !== void 0) out.cursor = page.cursor;
+	if (page.order !== void 0) out.order = page.order;
+	return out;
+}
+/** Premier param d'une clé (la query admin peut être `string | string[]`). */
+function one(query, key) {
+	const value = query[key];
+	if (value === void 0) return void 0;
+	return Array.isArray(value) ? value[0] : value;
+}
+/** Taille de page du journal d'audit quand l'appelant n'en demande pas. */
+const AUDIT_DEFAULT_LIMIT = 100;
+/**
+* Traduit la query string admin en {@link IAuditListQuery} typée — pagination
+* par curseur, plus les filtres de {@link AUDIT_FILTERS}.
+*
+* Un filtre inconnu ou mal formé est **refusé** (400). Il était auparavant
+* ignoré, au nom de la robustesse de la console : mais un journal d'audit rendu
+* ENTIER à qui demandait `?outcome=deneid` n'est pas robuste — c'est la pire
+* réponse possible à un auditeur, qui lit l'absence de refus comme l'absence
+* d'incident. Le typage suit la même source : les valeurs viennent de la spec,
+* il n'y a plus de `as AuditCategory` à écrire ici.
+*
+* Le `limit` est **toujours posé** (défaut {@link AUDIT_DEFAULT_LIMIT}, cap du
+* traducteur) : le contrat de page n'admet pas « tout » ; le store applique en
+* plus son propre plafond, l'appelant ne peut donc pas s'en servir pour tirer un
+* journal entier.
+*
+* @param query - `request.query` du broker admin.
+* @returns filtre prêt pour `auditService.listPage`.
+* @throws `PageQueryError` (400) sur un filtre inconnu ou mal formé.
+*/
+function parseAuditQuery(query) {
+	const page = parsePageQuery(query, { defaultLimit: AUDIT_DEFAULT_LIMIT });
+	const filter = {
+		limit: page.limit,
+		...parseFilters(query, AUDIT_FILTERS)
+	};
+	if (page.cursor !== void 0) filter.cursor = page.cursor;
+	return filter;
+}
+/** Projette un credential serveur vers sa vue admin (sans `publicKey`/`userId`). */
+function toCredentialView(c) {
+	return {
+		id: c.id,
+		nickname: c.nickname ?? null,
+		transports: c.transports,
+		backupEligible: c.backupEligible,
+		backupState: c.backupState,
+		uvInitialized: c.uvInitialized,
+		createdAt: c.createdAt,
+		lastUsedAt: c.lastUsedAt
+	};
+}
+/**
+* Producteur admin (`IAdminApi`) du module sécurité — data plane consommé par
+* Studio (section Sécurité, P6.15) :
+*
+*  - `GET /nodefony/security/api/audit/events` — page filtrée du journal d'audit
+*    (P6.14 Lot 3 ; `?category&outcome&actor&action&requestId&since&until&limit&cursor`),
+*    du plus récent au plus ancien, pagination par curseur (`cursor` / `nextCursor`).
+*  - `GET /nodefony/security/api/firewall` — introspection du firewall (zones,
+*    authenticators montés, défenses) — état RUNTIME, secrets exclus.
+*  - `GET /nodefony/security/api/roleHierarchy` — hiérarchie de rôles + résolution.
+*  - `GET /nodefony/security/api/apikeys` — toutes les clés API (gouvernance),
+*    `GET …/apikeys/status` — backend du token store (« où on écrit »),
+*    `POST …/apikeys/{id}/revoke` — révocation par id (réponse à incident).
+*  - `GET …/users/{id}/passkeys` + `DELETE …/users/{id}/passkeys/{credentialId}`
+*    — passkeys d'un utilisateur (vue admin sans clé publique) + révocation
+*    owner-scopée (reset facteur fort, audité).
+*  - `GET …/users/{id}/totp` + `POST …/users/{id}/totp/disable` — état du 2FA
+*    TOTP + désactivation (reset facteur fort, audité). Pas d'enrôlement
+*    cross-user (le secret se scanne sur l'appareil de l'utilisateur).
+*
+* **RBAC `ROLE_NODEFONY_ADMIN`** (appliqué par le broker, 403 sinon) — la console
+* sécurité ne se consulte qu'en administrateur. Handlers **lazy** : ils résolvent
+* `auditService`/`firewall` à la requête (service désactivable → 503), jamais au
+* montage. Le namespace `"security"` est distinct des routes classiques
+* `/nodefony/security/api/keys` (P6.12) — paths disjoints, zéro collision.
+*
+* @param container - container du kernel (résolution lazy des services).
+*/
+function createSecurityAdminApi(container) {
+	const endpoints = [
+		{
+			path: "audit/events",
+			method: "GET",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Journal d'audit de sécurité (login/refus/jetons). Filtres : ?category&outcome&actor&action&since&until&limit&cursor (curseur).",
+			handler: async (request) => {
+				const audit = container.get("auditService");
+				if (!audit || !audit.isEnabled()) return {
+					status: 503,
+					body: { error: "audit journal unavailable" }
+				};
+				return audit.listPage(parseAuditQuery(request.query));
+			}
+		},
+		{
+			path: "firewall",
+			method: "GET",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Introspection du firewall : zones (URL/host/authenticators), authenticators montés, défenses (CSRF/CORS/en-têtes/throttle). Secrets exclus (présence, jamais valeur).",
+			handler: () => {
+				const firewall = container.get("firewall");
+				if (!firewall) return {
+					status: 503,
+					body: { error: "firewall unavailable" }
+				};
+				return firewall.describe();
+			}
+		},
+		{
+			path: "roleHierarchy",
+			method: "GET",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Hiérarchie de rôles déclarée + résolution transitive (RoleHierarchyWalker, niveau A de l'autorisation).",
+			handler: () => {
+				const firewall = container.get("firewall");
+				if (!firewall) return {
+					status: 503,
+					body: { error: "firewall unavailable" }
+				};
+				return firewall.describeRoleHierarchy();
+			}
+		},
+		{
+			path: "apikeys",
+			method: "GET",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Clés API (PAT) du système — gouvernance cross-porteur, pagination NATIVE au store (?subjectId&revoked&limit&offset|cursor&order=champ:ASC). Tri limité aux champs que le backend branché déclare savoir trier. Vue publique, sans secret.",
+			page: {
+				sortable: () => {
+					const svc = container.get("apiKeys");
+					return svc?.isEnabled() ? svc.sortableFields() : [];
+				},
+				filters: TOKEN_FILTERS
+			},
+			handler: async (request) => {
+				const svc = container.get("apiKeys");
+				if (!svc || !svc.isEnabled()) return {
+					status: 503,
+					body: { error: "api keys unavailable" }
+				};
+				const page = await svc.listPagePat(parseTokenListQuery(request.query, svc.sortableFields()));
+				return {
+					keys: page.items,
+					total: page.total,
+					limit: page.limit,
+					offset: page.offset,
+					nextCursor: page.nextCursor
+				};
+			}
+		},
+		{
+			path: "apikeys/stats",
+			method: "GET",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Compteurs des clés d'API sur la collection ENTIÈRE (total, actives, expirées, révoquées) — mêmes filtres que la liste. `null` = le backend ne sait pas compter (store Redis en curseur).",
+			page: {
+				filters: TOKEN_STATS_FILTERS,
+				facets: TOKEN_FACETS
+			},
+			handler: async (request) => {
+				const svc = container.get("apiKeys");
+				if (!svc || !svc.isEnabled()) return {
+					status: 503,
+					body: { error: "api keys unavailable" }
+				};
+				parsePageQuery(request.query, {});
+				return svc.countKeyFacets(parseFilters(request.query, TOKEN_STATS_FILTERS));
+			}
+		},
+		{
+			path: "apikeys/status",
+			method: "GET",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Statut du sous-système clés API : « où on écrit » = backend du token store (classe réelle + driver memory/orm/redis). Sans secret.",
+			handler: () => {
+				const enabled = container.get("apiKeys")?.isEnabled() ?? false;
+				const className = container.get("tokenStore")?.constructor?.name;
+				return {
+					enabled,
+					store: className ?? "none",
+					driver: className ? tokenStoreDriver(className) : null
+				};
+			}
+		},
+		{
+			path: "apikeys/{id}/revoke",
+			method: "POST",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Révoque une clé API par id (réponse à incident : clé compromise) — audité (acteur admin + porteur cible). 404 si introuvable.",
+			handler: async (request) => {
+				const svc = container.get("apiKeys");
+				if (!svc || !svc.isEnabled()) return {
+					status: 503,
+					body: { error: "api keys unavailable" }
+				};
+				const id = request.params.id;
+				if (typeof id !== "string" || id.length === 0) return {
+					status: 404,
+					body: { error: "not found" }
+				};
+				const key = await svc.revokeAnyPat(id, adminActor(request.user));
+				if (!key) return {
+					status: 404,
+					body: { error: "not found" }
+				};
+				return {
+					ok: true,
+					key
+				};
+			}
+		},
+		{
+			path: "webauthn/list",
+			method: "GET",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Passkeys de la plateforme (id, porteur, transports, sauvegarde, compteur anti-clone, dates — jamais la clé publique). Paginé serveur : ?userId&backedUp&q&limit&offset. `enabled:false` = passkeys désactivés en config. `total:-1` = backend sans comptage (Redis).",
+			handler: async (request) => {
+				const svc = container.get("webauthn");
+				const pageQuery = parsePageQuery(request.query, {
+					defaultLimit: KEYS_DEFAULT_LIMIT,
+					maxLimit: KEYS_MAX_LIMIT,
+					searchable: true
+				});
+				const limit = pageQuery.limit;
+				const offset = pageQuery.offset ?? 0;
+				if (!svc) return {
+					enabled: false,
+					items: [],
+					total: 0,
+					limit,
+					offset
+				};
+				const userId = one(request.query, "userId");
+				const backedUp = one(request.query, "backedUp");
+				const q = pageQuery.q;
+				const page = await svc.listCredentialsPage({
+					limit,
+					offset,
+					...userId !== void 0 ? { userId } : {},
+					...backedUp === "true" ? { backedUp: true } : backedUp === "false" ? { backedUp: false } : {},
+					...q !== void 0 ? { q } : {}
+				});
+				return {
+					enabled: true,
+					items: page.items,
+					total: page.total,
+					limit,
+					offset
+				};
+			}
+		},
+		{
+			path: "users/{id}/passkeys",
+			method: "GET",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Passkeys (WebAuthn) d'un utilisateur — vue admin SANS clé publique (id/surnom/transports/sauvegarde/UV/dates). 404 si utilisateur inconnu.",
+			handler: async (request) => {
+				const svc = container.get("webauthn");
+				if (!svc) return {
+					status: 503,
+					body: { error: "webauthn unavailable" }
+				};
+				const id = request.params.id;
+				if (typeof id !== "string" || id.length === 0) return {
+					status: 404,
+					body: { error: "not found" }
+				};
+				const users = container.get("users");
+				if (users && !await users.findById(id)) return {
+					status: 404,
+					body: { error: "not found" }
+				};
+				return { credentials: (await svc.listUserCredentials(id)).map(toCredentialView) };
+			}
+		},
+		{
+			path: "users/{id}/passkeys/{credentialId}",
+			method: "DELETE",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Révoque une passkey d'un utilisateur (reset admin) — audité. 404 si la passkey n'existe pas ou n'appartient pas à l'utilisateur (anti-IDOR).",
+			handler: async (request) => {
+				const svc = container.get("webauthn");
+				if (!svc) return {
+					status: 503,
+					body: { error: "webauthn unavailable" }
+				};
+				const id = request.params.id;
+				const credentialId = request.params.credentialId;
+				if (typeof id !== "string" || id.length === 0 || typeof credentialId !== "string" || credentialId.length === 0) return {
+					status: 404,
+					body: { error: "not found" }
+				};
+				if (!await svc.removeUserCredential(id, credentialId)) return {
+					status: 404,
+					body: { error: "not found" }
+				};
+				auditAdmin(container, {
+					category: "webauthn",
+					action: "user.passkey_revoked",
+					outcome: "success",
+					actor: adminActor(request.user),
+					resource: id,
+					metadata: {
+						credentialId,
+						viaAdmin: true
+					}
+				});
+				return { ok: true };
+			}
+		},
+		{
+			path: "totp/list",
+			method: "GET",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Enrôlements 2FA TOTP (userId, paramètres, confirmation, codes de récupération RESTANTS — jamais le secret). Paginé serveur : ?confirmed&q&limit&offset. `enabled:false` = 2FA désactivé en config.",
+			handler: async (request) => {
+				const svc = container.get("totp");
+				const pageQuery = parsePageQuery(request.query, {
+					defaultLimit: KEYS_DEFAULT_LIMIT,
+					maxLimit: KEYS_MAX_LIMIT
+				});
+				const limit = pageQuery.limit;
+				const offset = pageQuery.offset ?? 0;
+				if (!svc) return {
+					enabled: false,
+					items: [],
+					total: 0,
+					limit,
+					offset
+				};
+				const confirmed = one(request.query, "confirmed");
+				const q = one(request.query, "q");
+				const page = await svc.listPage({
+					limit,
+					offset,
+					...confirmed === "true" ? { confirmed: true } : confirmed === "false" ? { confirmed: false } : {},
+					...q !== void 0 ? { q } : {}
+				});
+				return {
+					enabled: true,
+					items: page.items,
+					total: page.total,
+					limit,
+					offset
+				};
+			}
+		},
+		{
+			path: "users/{id}/totp",
+			method: "GET",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "État du 2FA TOTP d'un utilisateur (activé / en attente / codes de récupération restants). 404 si utilisateur inconnu.",
+			handler: async (request) => {
+				const svc = container.get("totp");
+				if (!svc) return {
+					status: 503,
+					body: { error: "totp unavailable" }
+				};
+				const id = request.params.id;
+				if (typeof id !== "string" || id.length === 0) return {
+					status: 404,
+					body: { error: "not found" }
+				};
+				const users = container.get("users");
+				if (users && !await users.findById(id)) return {
+					status: 404,
+					body: { error: "not found" }
+				};
+				return svc.status(id);
+			}
+		},
+		{
+			path: "users/{id}/totp/disable",
+			method: "POST",
+			role: "ROLE_NODEFONY_ADMIN",
+			summary: "Désactive le 2FA TOTP d'un utilisateur (reset admin : appareil perdu) — audité. Idempotent (no-op si déjà désactivé).",
+			handler: async (request) => {
+				const svc = container.get("totp");
+				if (!svc) return {
+					status: 503,
+					body: { error: "totp unavailable" }
+				};
+				const id = request.params.id;
+				if (typeof id !== "string" || id.length === 0) return {
+					status: 404,
+					body: { error: "not found" }
+				};
+				const users = container.get("users");
+				if (users && !await users.findById(id)) return {
+					status: 404,
+					body: { error: "not found" }
+				};
+				await svc.disable(id);
+				auditAdmin(container, {
+					category: "auth",
+					action: "user.totp_disabled",
+					outcome: "success",
+					actor: adminActor(request.user),
+					resource: id,
+					metadata: { viaAdmin: true }
+				});
+				return { ok: true };
+			}
+		},
+		...webhookAdminEndpoints(container)
+	];
+	const descriptor = {
+		label: "Sécurité",
+		icon: "shield-lock",
+		order: 15,
+		role: "ROLE_NODEFONY_ADMIN"
+	};
+	return {
+		adminNamespace: "security",
+		adminDescriptor: () => descriptor,
+		adminEndpoints: () => endpoints
+	};
+}
+/**
+* Enregistre le producteur admin sécurité sur le broker — **idempotent** (no-op
+* si déjà monté). À appeler au `onKernelBoot` du module (avant le montage des
+* routes par framework à `onKernelReady`). Calque `registerOrmAdminApi`.
+*
+* @param registry - broker admin (`container.get("adminBroker")`).
+* @param container - container du kernel (capturé par le handler lazy).
+*/
+function registerSecurityAdminApi(registry, container) {
+	if (registry.has("security")) return;
+	registry.register(createSecurityAdminApi(container));
+}
+//#endregion
+export { createSecurityAdminApi, parseAuditQuery, parseTokenListQuery, registerSecurityAdminApi };