@nodefony/security 10.0.0-alpha.1

package/README.md

@@ -0,0 +1,182 @@
+# @nodefony/security
+
+Couche de sécurité de Nodefony.
+
+Firewall par zones, authentication (pattern `IAuthenticator`), autorisation (rôles + voters),
+CORS, CSRF, en-têtes de sécurité, JWT, clés API, WebAuthn/passkeys, OAuth2 social, 2FA TOTP,
+webhooks signés, audit persistant. **Modèle d'identité hybride**, **Zero Trust** par défaut.
+Consomme [`@nodefony/user`](https://www.npmjs.com/package/@nodefony/user).
+
+> **Statut** : cœur livré — firewall + zones, session serveur (NIST), JWT (`jose`), WebAuthn,
+> OAuth2 social, CSRF/CORS/en-têtes natifs, clés API/PAT, 2FA TOTP, webhooks, audit persistant,
+> rate-limit, **voters d'autorisation** (`RoleVoter` + `ScopeVoter`, jury affirmatif à véto
+> `DENY`, découverts au boot par le `voterRegistry`) et les décorateurs **`@IsGranted`** et
+> **`@CsrfProtect`**, appliqués par le `Resolver` avant l'action.
+>
+> Reste : ACL fine par ressource (niveau B de `authorization.ts`), journal d'authentification
+> dédié, `rpId` WebAuthn dérivé du `Host` (multi-vhost), `MTlsAuthenticator` (niche). Le serveur
+> d'autorisation OAuth 2.1 est tranché **après** la 10.0.0.
+
+## Principes
+
+- **Pattern `IAuthenticator`** (supports / authenticate / onSuccess) — pas de Bridge/Factory.
+- **Zero Trust** : une zone protégée sans utilisateur authentifié → `401`.
+- **Identité hybride** (révisé 2026-06-06) : le **web/Studio** ouvre une **session serveur**
+  (cookie opaque BFF, révocable, `HttpOnly; Secure; SameSite`) ; les **API/agents** portent leur
+  preuve à chaque requête (**JWT** signé / clé API). Jamais « full stateless » : la session reste
+  la fondation web (révocation immédiate), le JWT est réservé au sans-état machine-à-machine.
+- **Config type-safe** : schéma **Zod** (18 sections, tout `enabled`), **introspectable** (Studio
+  génère son formulaire d'édition). L'app configure via `use("@nodefony/security", { … })`.
+- **En-têtes natifs** (sans la lib `helmet`) — 0 dépendance, nonce CSP par requête.
+
+## Configuration
+
+La sécurité se configure dans le **`nodefony.config.ts`** de l'app via `use()` — colocalisée
+avec le chargement du module, jamais dans un fichier séparé :
+
+```ts
+// nodefony.config.ts
+import { defineConfig, use } from "nodefony";
+
+export default defineConfig((ctx) => ({
+  modules: [
+    "@nodefony/http",
+    "@nodefony/framework",
+    use(
+      "@nodefony/security",
+      {
+        // Hiérarchie de rôles (RBAC) — ROLE_X hérite des rôles listés (DFS au boot).
+        roleHierarchy: { ROLE_ADMIN: ["ROLE_USER"] },
+        // Zones firewall — clé = nom de zone, valeur = pattern + authenticators.
+        areas: {
+          // Web/Studio : session serveur (cookie opaque BFF).
+          admin: { pattern: "^/admin", authenticators: ["session"] },
+          // API machine-à-machine : preuve à chaque requête, aucune session.
+          "api-m2m": {
+            pattern: "^/api",
+            authenticators: ["jwt", "apikey"],
+            stateless: true,
+          },
+        },
+      },
+      { policy: "mandatory" }, // sécurité = requise dès qu'on sert du trafic
+    ),
+  ],
+}));
+```
+
+> Une zone se déclare idéalement **par module** (override `module-security`, dans la config du
+> module) pour vivre au plus près de ses routes. Authenticators fournis : `anonymous`, `session`,
+> `userpassword`, `jwt`, `apikey`, `webauthn`, plus les providers OAuth2. La chaîne est validée
+> au boot (`mode: "first"` par défaut = le premier qui reconnaît authentifie ; `"all"` = tous
+> requis, ex. mTLS + JWT). Config invalide → firewall **fail-closed** (tout rejeté).
+
+Toutes les sections (`cors`, `csrf`, `headers`, `rateLimit`, `jwt`, `apiKeys`, `webhooks`,
+`audit`, `studio`…) ont des **défauts sûrs** et sont **désactivables** via `enabled`.
+Voir [`nodefony/config/config.ts`](https://github.com/nodefony/nodefony-core/blob/claude-ts/src/packages/@nodefony/security/nodefony/config/config.ts) — chaque option y est
+documentée (explication + défaut + reco).
+
+### Sections
+
+<!-- prettier-ignore -->
+| Section | Rôle | Défaut |
+| --- | --- | --- |
+| `encoders` | hash mot de passe | Argon2id (OWASP) ; bcrypt legacy |
+| `roleHierarchy` | héritage de rôles | `{}` (plats) |
+| `areas` | zones firewall (pattern + host + authenticators) | `{}` (aucune route protégée) |
+| `cors` | Cross-Origin | strict (jamais `*`+credentials) |
+| `csrf` | Fetch Metadata (`Sec-Fetch-Site`) + repli Origin (OWASP 2025) | activé ; `strictSameSite:false`, `trustedOrigins:[]` |
+| `headers` | HSTS/CSP+nonces/frameguard/noSniff… (natif) | activé ; avancés (COOP/COEP/CORP…) en option |
+| `rateLimit` | anti brute-force + lockout | activé |
+| `jwt` | jetons API/agents (sans-état) | EdDSA, access 15 min / refresh 7 j, rotation |
+| `apiKeys` | clés API (PAT) hashées | préfixe `nf`, expiry 90 j |
+| `webhooks` | sortants signés HMAC | anti-replay + anti-SSRF |
+| `audit` | journal sécurité (append-only) | activé, stream Studio |
+| `studio` | durcissement console admin | **OFF**, `localhost` (durcissement réservé) |
+
+### CSRF — Fetch Metadata d'abord
+
+La défense CSRF est **globale** (toute requête qui modifie l'état : `POST`/`PUT`/`PATCH`/`DELETE` ;
+les méthodes sûres `GET`/`HEAD`/`OPTIONS` ne sont jamais bloquées). Trois couches, dans l'ordre :
+
+1. **`Sec-Fetch-Site`** (défense primaire) — le navigateur tamponne lui-même la provenance de la
+   requête, un script attaquant ne peut pas la falsifier. `same-origin` et `none` (navigation directe
+   ou client non-navigateur) passent ; `cross-site` est **rejeté en 403**.
+2. **Repli `Origin`/`Referer`** — pour les vieux navigateurs sans `Sec-Fetch-*` : l'origine doit
+   correspondre à l'hôte de l'app. Ni l'un ni l'autre (client non-navigateur) → autorisé (hors vecteur).
+3. **Cookie `SameSite=Lax`** — défense en profondeur sur le cookie de session.
+
+```ts
+csrf: {
+  strictSameSite: false,            // true → bloque aussi les sous-domaines (same-site) : multi-tenant
+  trustedOrigins: ["https://app.example.org"], // alias multi-domaine légitimes (autorisés même cross-site)
+}
+```
+
+> `trustedOrigins` est **distinct** de `cors.origins` : déclarer un simple alias de domaine ne doit pas
+> ouvrir la lecture CORS des réponses au JavaScript tiers. Une origine listée dans `cors.origins` est
+> toutefois aussi acceptée (ce que CORS autorise explicitement n'est pas du CSRF).
+
+Le token synchronizer renforcé (`@CsrfProtect` / `@CsrfExempt`) arrive à l'étape suivante.
+
+### CORS — l'inverse du CSRF
+
+CORS **assouplit** la Same-Origin Policy : il autorise un site tiers à _lire_ la réponse de l'app en
+JavaScript (le CSRF, lui, _empêche_ un tiers de déclencher une mutation). La politique est globale :
+
+- **Preflight** `OPTIONS` (Fetch Standard) court-circuité **avant le routing** → `204` + en-têtes
+  `Access-Control-Allow-*`. Il ne s'authentifie jamais (il ne porte pas de credentials).
+- **Origine autorisée** → l'origine est **reflétée** (`Access-Control-Allow-Origin: <origine>` + `Vary: Origin`).
+  `*` n'est émis que sans `credentials`. Origine non autorisée → aucun en-tête (le navigateur bloque).
+- **`origins:["*"]` + `credentials:true` est refusé au démarrage** (refine Zod) : le navigateur l'interdit,
+  et c'est une faille classique. Pour les credentials, lister les origines explicitement.
+
+### Introspection (Studio)
+
+```ts
+import { securityConfigJsonSchema } from "@nodefony/security";
+const schema = securityConfigJsonSchema(); // JSON Schema → formulaire d'édition Studio
+```
+
+## Journal d'audit (événements de sécurité)
+
+Le journal trace les **transitions d'état** de sécurité (login, refus, jeton émis/révoqué, verrou
+WS) — distinct du log de trafic (1 PDU/requête). Émission **explicite** par point sensible ; le
+**chemin de succès reste muet** (le volume n'est pas un signal), seul l'échec/refus émet (cold-path)
+→ aucun coût ajouté au hot-path nominal. Activé par défaut (`audit.enabled`, OWASP A09), coût nul si
+désactivé. Lecture : `GET /nodefony/security/api/audit/events` (RBAC `ROLE_NODEFONY_ADMIN`).
+
+**Flux temps réel** (lot 4) : canal WS **`nodefony:audit`**, réservé `ROLE_NODEFONY_ADMIN`
+(plancher système, un cran au-dessus de l'observabilité générique `ROLE_ADMIN`). Enregistré comme
+**canal système** sur le hub realtime (servable par tout endpoint, sans couplage à Studio) ;
+**lazy** : le pont ne s'abonne au journal qu'au 1ᵉʳ auditeur connecté et s'en détache au dernier.
+Coalescé (1 frame `{ events, dropped }` toutes les ~250 ms, ring borné) → un pic d'échecs sous
+attaque ne noie pas la console. Un user non habilité qui tente de s'y abonner est refusé **et audité**
+(`frame.denied`).
+
+Un **secret n'entre jamais** dans un événement — seule sa _présence_ est tracée (`flags`).
+
+| `action`               | `category` | `outcome` | Émis par                         |
+| ---------------------- | ---------- | --------- | -------------------------------- |
+| `login.success`        | `auth`     | success   | `AuthFlow` (BFF) / fédéré        |
+| `login.failure`        | `auth`     | failure   | `AuthFlow`, `TokenService` grant |
+| `login.throttled`      | `auth`     | failure   | `AuthFlow`, `TokenService` grant |
+| `logout`               | `session`  | success   | `AuthFlow`                       |
+| `auth.failure`         | `auth`     | failure   | `Firewall` (credential invalide) |
+| `auth.throttled`       | `auth`     | failure   | `Firewall` (backoff NIST)        |
+| `auth.denied`          | `auth`     | denied    | `Firewall` (Zero Trust)          |
+| `access.denied`        | `authz`    | denied    | `Authorization` (voters/RBAC)    |
+| `frame.denied`         | `ws`       | denied    | verrou de frame WS               |
+| `token.issued`         | `token`    | success   | `TokenService`                   |
+| `token.reuse_detected` | `token`    | denied    | `TokenService` (RFC 9700)        |
+| `apikey.created`       | `token`    | success   | `ApiKeyService`                  |
+| `apikey.revoked`       | `token`    | success   | `ApiKeyService`                  |
+
+## Erreurs
+
+- `AuthenticationError` → `401` (non authentifié).
+- `AccessDeniedError` → `403` (authentifié mais non autorisé).
+
+## Licence
+
+CeCILL-B — Christophe CAMENSULI.

package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js

@@ -0,0 +1,9 @@
+//#region \0@oxc-project+runtime@0.148.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+export { __decorate as default };

package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js

@@ -0,0 +1,6 @@
+//#region \0@oxc-project+runtime@0.148.0/helpers/esm/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+//#endregion
+export { __decorateMetadata as default };

package/dist/index.js

@@ -0,0 +1,151 @@
+import config from "./nodefony/config/config.js";
+import { SecuredArea } from "./nodefony/src/SecuredArea.js";
+import { LoginThrottler } from "./nodefony/src/throttle/LoginThrottler.js";
+import { RoleHierarchyWalker } from "./nodefony/src/RoleHierarchyWalker.js";
+import { CsrfTokenManager } from "./nodefony/src/csrfToken.js";
+import { CsrfError } from "./nodefony/errors/CsrfError.js";
+import { Csrf } from "./nodefony/service/csrf.js";
+import { Cors } from "./nodefony/service/cors.js";
+import { SecurityHeaders } from "./nodefony/service/securityHeaders.js";
+import { AuthenticationError } from "./nodefony/errors/AuthenticationError.js";
+import { ThrottledError } from "./nodefony/errors/ThrottledError.js";
+import { UnverifiableTokenError } from "./nodefony/errors/UnverifiableTokenError.js";
+import { defineSecurityConfig, securityConfigJsonSchema } from "./nodefony/config/defineModuleConfig.js";
+import { AnonymousToken } from "./nodefony/src/token/AnonymousToken.js";
+import { AnonymousAuthenticator } from "./nodefony/src/authenticator/AnonymousAuthenticator.js";
+import { UserToken } from "./nodefony/src/token/UserToken.js";
+import { SessionAuthenticator } from "./nodefony/src/authenticator/SessionAuthenticator.js";
+import { UserPasswordAuthenticator } from "./nodefony/src/authenticator/UserPasswordAuthenticator.js";
+import peekIssuer from "./nodefony/src/authenticator/peekIssuer.js";
+import { JwtAuthenticator } from "./nodefony/src/authenticator/JwtAuthenticator.js";
+import { generateApiKey, hashApiKey, looksLikeApiKey, parseApiKey } from "./nodefony/src/apikey/apiKeyFormat.js";
+import { ApiKeyAuthenticator } from "./nodefony/src/authenticator/ApiKeyAuthenticator.js";
+import { ExternalJwtAuthenticator } from "./nodefony/src/authenticator/ExternalJwtAuthenticator.js";
+import { resolveJwtRuntime } from "./nodefony/src/token/jwtRuntime.js";
+import { getAuthenticatorFactory, listAuthenticatorFactories, registerAuthenticatorFactory } from "./nodefony/src/authenticator/authenticatorRegistry.js";
+import { recordAudit } from "./nodefony/src/audit/recordAudit.js";
+import { readAuditContext } from "./nodefony/src/audit/readAuditContext.js";
+import { Firewall } from "./nodefony/service/firewall.js";
+import { AuthFlow } from "./nodefony/service/authFlow.js";
+import { InvalidTargetError } from "./nodefony/errors/InvalidTargetError.js";
+import { TOKEN_DEFAULT_ORDER, TOKEN_SORTABLE_FIELDS } from "./nodefony/src/token/tokenSort.js";
+import { matchesTokenStatus, tokenStatusOf } from "./nodefony/src/token/tokenStatus.js";
+import { MemoryTokenStore } from "./nodefony/src/token/MemoryTokenStore.js";
+import { getTokenStoreFactory, listTokenStores, registerTokenStore } from "./nodefony/src/token/tokenStoreRegistry.js";
+import { JwtKeystore } from "./nodefony/src/token/JwtKeystore.js";
+import { TokenService } from "./nodefony/service/tokenService.js";
+import { RemoteJwtVerifier } from "./nodefony/src/token/RemoteJwtVerifier.js";
+import { AccessTokenVerifierService } from "./nodefony/service/accessTokenVerifier.js";
+import { VoterVote } from "./nodefony/contracts/IAccessVoter.js";
+import { RoleVoter } from "./nodefony/src/voter/RoleVoter.js";
+import { ScopeVoter } from "./nodefony/src/voter/ScopeVoter.js";
+import { listVoterFactories, registerVoterFactory } from "./nodefony/src/voter/voterRegistry.js";
+import { Authorization } from "./nodefony/service/authorization.js";
+import { MemoryWebAuthnCredentialStore } from "./nodefony/src/webauthn/MemoryWebAuthnCredentialStore.js";
+import { getWebAuthnStoreFactory, listWebAuthnStores, registerWebAuthnStore } from "./nodefony/src/webauthn/webAuthnCredentialStoreRegistry.js";
+import { WebAuthnService } from "./nodefony/service/webAuthn.js";
+import { getOAuthProviderFactory, listOAuthProviders, registerOAuthProvider } from "./nodefony/src/oauth/oauthProviderRegistry.js";
+import { OAuth2Service } from "./nodefony/service/oauth2.js";
+import { TOKEN_FACETS } from "./nodefony/src/token/tokenFilters.js";
+import { ApiKeyError } from "./nodefony/errors/ApiKeyError.js";
+import { ApiKeyService } from "./nodefony/service/apiKeys.js";
+import { MemoryAuditStore } from "./nodefony/src/audit/MemoryAuditStore.js";
+import { getAuditStoreFactory, listAuditStores, registerAuditStore } from "./nodefony/src/audit/auditStoreRegistry.js";
+import AuditService from "./nodefony/service/auditService.js";
+import { MemoryTotpSecretStore } from "./nodefony/src/totp/MemoryTotpSecretStore.js";
+import { getTotpStoreFactory, listTotpStores, registerTotpStore } from "./nodefony/src/totp/totpSecretStoreRegistry.js";
+import { decryptSecret, deriveKey, encryptSecret, generateEphemeralKey } from "./nodefony/src/crypto/secretCipher.js";
+import { deriveTotpKey } from "./nodefony/src/totp/totpCipher.js";
+import { base32Decode, totpCode } from "./nodefony/src/totp/totpCrypto.js";
+import { beginTotpEnrollment, confirmTotpEnrollment, disableTotp, totpStatus, verifyTotpLogin } from "./nodefony/src/totp/totpOperations.js";
+import { TotpService } from "./nodefony/service/totp.js";
+import { WEBHOOK_DEFAULT_ORDER, WEBHOOK_SORTABLE_FIELDS } from "./nodefony/src/webhook/webhookSort.js";
+import { MemoryWebhookStore } from "./nodefony/src/webhook/MemoryWebhookStore.js";
+import { getWebhookStoreFactory, listWebhookStores, registerWebhookStore } from "./nodefony/src/webhook/webhookStoreRegistry.js";
+import { SsrfError } from "./nodefony/errors/SsrfError.js";
+import { assertPublicUrl, isBlockedAddress } from "./nodefony/src/net/ssrfGuard.js";
+import { WebhookService } from "./nodefony/service/webhooks.js";
+import SecuritySecrets from "./nodefony/command/security-secrets.js";
+import SecurityUserAdd from "./nodefony/command/security-user-add.js";
+import SecurityUserList from "./nodefony/command/security-user-list.js";
+import SecurityUserDelete from "./nodefony/command/security-user-delete.js";
+import SecurityToken from "./nodefony/command/security-token.js";
+import { createSecurityAdminApi, parseAuditQuery, registerSecurityAdminApi } from "./nodefony/src/admin/SecurityAdminApi.js";
+import { registerUserRevocationCascade } from "./nodefony/src/admin/userRevocationCascade.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 { tokenStatusCriteria } from "./nodefony/src/token/tokenCriteria.js";
+import { AccessDeniedError } from "./nodefony/errors/AccessDeniedError.js";
+import "./nodefony/errors/index.js";
+import "./nodefony/contracts/index.js";
+import { Kernel, Module, services } from "nodefony";
+import { fileURLToPath } from "node:url";
+import { registerUserAdminApi } from "@nodefony/user";
+//#region index.ts
+/**
+* `@nodefony/security` — couche de sécurité de Nodefony (refonte 2026, P6).
+*
+* Identité **hybride** : session serveur cookie opaque (BFF) par défaut web/Studio,
+* JWT réservé API/M2M/agents. Pattern **`IAuthenticator`** + registre de fabriques
+* (pluggable), **Zero Trust** par défaut, config type-safe `defineSecurityConfig()`
+* + Zod validée au boot (fail-closed si invalide). Consomme `@nodefony/user`
+* (IUser/IUserProvider/IPasswordVerifier) — jamais l'inverse.
+*
+* Livré : firewall (zones, mode first|all, challenge RFC 7235), authenticators
+* `anonymous`/`userpassword` (Basic RFC 7617)/`session` (BFF, J3), flux
+* login/logout/me (`AuthFlow`, anti-fixation + throttling partagé).
+* Jwt/oauth2/mtls/apikey, CORS, CSRF, autorisation par décorateurs et data
+* plane Studio arrivent aux sessions suivantes (plan J0→J10).
+*/
+let Security = class Security extends Module {
+	constructor(kernel) {
+		super("security", kernel, fileURLToPath(import.meta.url), config);
+		this.addCommand(SecuritySecrets);
+		this.addCommand(SecurityUserAdd);
+		this.addCommand(SecurityUserList);
+		this.addCommand(SecurityUserDelete);
+		this.addCommand(SecurityToken);
+	}
+	/**
+	* JSON Schema de la config security → data plane admin (config riche Studio).
+	* ⚠️ Les VALEURS effectives des secrets (csrf/jwt/oauth) sont redactées côté
+	* serveur (`safeConfig`) AVANT envoi — le schéma ne décrit que la structure.
+	*/
+	configSchema() {
+		return securityConfigJsonSchema();
+	}
+	/**
+	* Enregistre les data planes admin **sécurité** (`/nodefony/security/api/*`,
+	* P6.14) ET **utilisateur** (`/nodefony/user/api/*`, P6.15) auprès du broker
+	* AVANT que framework ne monte les routes (`onReady`). Le data plane user est
+	* DÉFINI dans `@nodefony/user` (propriétaire du domaine) mais monté ici, car
+	* `@nodefony/user` est une lib pure non-bootable et `security` en dépend déjà.
+	* No-op si le broker est absent (Studio non chargé) ou déjà enregistré.
+	*/
+	async onKernelBoot() {
+		const container = this.kernel?.container;
+		const registry = container?.get("adminBroker");
+		if (registry && container) {
+			registerSecurityAdminApi(registry, container);
+			registerUserAdminApi(registry, container);
+		}
+		if (this.kernel && container) registerUserRevocationCascade(this.kernel, container);
+		return this;
+	}
+};
+Security = __decorate([services([
+	Firewall,
+	AuthFlow,
+	TokenService,
+	AccessTokenVerifierService,
+	ApiKeyService,
+	Authorization,
+	WebAuthnService,
+	OAuth2Service,
+	AuditService,
+	TotpService,
+	WebhookService
+]), __decorateMetadata("design:paramtypes", [typeof Kernel === "undefined" ? Object : Kernel])], Security);
+var security_default = Security;
+//#endregion
+export { AccessDeniedError, AccessTokenVerifierService, AnonymousAuthenticator, AnonymousToken, ApiKeyAuthenticator, ApiKeyError, ApiKeyService, AuditService, AuthFlow, AuthenticationError, Authorization, Cors, Csrf, CsrfError, CsrfTokenManager, ExternalJwtAuthenticator, Firewall, InvalidTargetError, JwtAuthenticator, JwtKeystore, LoginThrottler, MemoryAuditStore, MemoryTokenStore, MemoryTotpSecretStore, MemoryWebAuthnCredentialStore, MemoryWebhookStore, OAuth2Service, RemoteJwtVerifier, RoleHierarchyWalker, RoleVoter, ScopeVoter, SecuredArea, SecurityHeaders, SessionAuthenticator, SsrfError, TOKEN_DEFAULT_ORDER, TOKEN_FACETS, TOKEN_SORTABLE_FIELDS, ThrottledError, TokenService, TotpService, UnverifiableTokenError, UserPasswordAuthenticator, UserToken, VoterVote, WEBHOOK_DEFAULT_ORDER, WEBHOOK_SORTABLE_FIELDS, WebAuthnService, WebhookService, assertPublicUrl, base32Decode, beginTotpEnrollment, confirmTotpEnrollment, createSecurityAdminApi, decryptSecret, security_default as default, defineSecurityConfig, deriveKey, deriveTotpKey, disableTotp, encryptSecret, generateApiKey, generateEphemeralKey, getAuditStoreFactory, getAuthenticatorFactory, getOAuthProviderFactory, getTokenStoreFactory, getTotpStoreFactory, getWebAuthnStoreFactory, getWebhookStoreFactory, hashApiKey, isBlockedAddress, listAuditStores, listAuthenticatorFactories, listOAuthProviders, listTokenStores, listTotpStores, listVoterFactories, listWebAuthnStores, listWebhookStores, looksLikeApiKey, matchesTokenStatus, parseApiKey, parseAuditQuery, peekIssuer, readAuditContext, recordAudit, registerAuditStore, registerAuthenticatorFactory, registerOAuthProvider, registerSecurityAdminApi, registerTokenStore, registerTotpStore, registerVoterFactory, registerWebAuthnStore, registerWebhookStore, resolveJwtRuntime, securityConfigJsonSchema, tokenStatusCriteria, tokenStatusOf, totpCode, totpStatus, verifyTotpLogin };

package/dist/nodefony/command/security-secrets.js

@@ -0,0 +1,158 @@
+import { readIfPresentSync } from "../src/token/secretFile.js";
+import { Command } from "nodefony";
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { appendFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+//#region nodefony/command/security-secrets.ts
+const options = {
+	helpGroup: "COMPTES ET SECRETS",
+	showBanner: false,
+	kernelEvent: "onReady"
+};
+const CYAN = "\x1B[36m";
+const GREEN = "\x1B[32m";
+const YELLOW = "\x1B[33m";
+const DIM = "\x1B[2m";
+const BOLD = "\x1B[1m";
+const RESET = "\x1B[0m";
+/** Les 3 clés générées (nom d'env var → rôle affiché). */
+const KEYS = [
+	"NF_TOTP_KEY",
+	"NF_WEBHOOK_KEY",
+	"NF_CSRF_SECRET"
+];
+/**
+* Ce que chaque secret PROTÈGE, et ce qui casse sans lui.
+*
+* 🔴 Sans ce catalogue, la commande était muette sur l'essentiel : quand les
+* trois clés étaient en place, elle affichait trois « ✓ » et RIEN d'autre — ni
+* les noms, ni les rôles. On ne savait donc ni ce qui avait été généré, ni
+* pourquoi. Un secret qu'on ne comprend pas est un secret qu'on ne fait jamais
+* tourner, et qu'on recopie d'un environnement à l'autre.
+*
+* La conséquence est écrite au présent et pour la PRODUCTION : c'est là qu'une
+* clé absente cesse d'être un avertissement de développement.
+*/
+const ROLES = {
+	NF_TOTP_KEY: {
+		protected: "chiffre le secret 2FA de chaque compte au repos (AES-256-GCM)",
+		without: "2FA désactivé en production — un secret chiffré par une clé éphémère serait illisible au redémarrage"
+	},
+	NF_WEBHOOK_KEY: {
+		protected: "chiffre les secrets de signature des webhooks au repos",
+		without: "webhooks désactivés en production (fail-safe, jamais de signature muette)"
+	},
+	NF_CSRF_SECRET: {
+		protected: "signe les jetons anti-rejeu des mutations (`@CsrfProtect`)",
+		without: "en cluster, le jeton émis par un pod est rejeté par les autres"
+	},
+	"jwt.keystore": {
+		protected: "signe les JWT (clé Ed25519, rotation gérée par le keystore)",
+		without: "chaque process signe avec la sienne : un jeton émis par la CLI est refusé par le serveur"
+	}
+};
+/**
+* `nodefony security:secrets` — génère les clés de chiffrement attendues par le
+* module security (TOTP, webhooks, CSRF) au bon format (32 octets aléatoires,
+* base64) et guide le câblage en 3 FICHIERS (.env → env.ts → nodefony.config.ts).
+* Réponse directe aux warnings « clé ÉPHÉMÈRE générée » du boot.
+*
+* DX anti-confusion (vécu : blocs collés dans le shell → parse error zsh) :
+* - chaque étape nomme son FICHIER et rappelle que rien ne se tape au terminal ;
+* - les étapes déjà faites sont DÉTECTÉES (grep des fichiers du projet) et
+*   affichées `✓` au lieu de redemander un collage ;
+* - `--write` écrit le `.env` (fichier local gitignoré) : ajoute uniquement les
+*   clés ABSENTES, ne remplace jamais une valeur existante (rotation = manuelle).
+* `env.ts` et `nodefony.config.ts` ne sont JAMAIS modifiés (code de l'app).
+*/
+var SecuritySecrets = class extends Command {
+	constructor(cli) {
+		super("security:secrets", "engendre les clés de chiffrement du module security", cli, options);
+		this.addOption("-j, --json", "sortie JSON (scripts/CI)");
+		this.addOption("-w, --write", "écrit les clés manquantes dans le .env du projet (jamais de remplacement)");
+	}
+	/** Racine du projet (kernel booté) — repli cwd. */
+	#root() {
+		return this.kernel?.path ?? process.cwd();
+	}
+	/**
+	* `true` si `.env.local` est SUIVI par git — y écrire des secrets les mènerait
+	* au commit (convention B : `*.local` doit être gitignoré). Best-effort : git
+	* absent / hors repo → `false` (on écrit).
+	*/
+	#dotenvTracked() {
+		try {
+			return spawnSync("git", [
+				"ls-files",
+				"--error-unmatch",
+				".env.local"
+			], {
+				cwd: this.#root(),
+				stdio: "ignore"
+			}).status === 0;
+		} catch {
+			return false;
+		}
+	}
+	/** Contenu d'un fichier du projet, "" si absent/illisible (détection best-effort). */
+	#read(file) {
+		try {
+			return readIfPresentSync(path.resolve(this.#root(), file)) ?? "";
+		} catch {
+			return "";
+		}
+	}
+	async generate(opts) {
+		const gen = () => randomBytes(32).toString("base64");
+		const secrets = {};
+		for (const k of KEYS) secrets[k] = gen();
+		if (opts.json) {
+			process.stdout.write(JSON.stringify(secrets, null, 2) + "\n");
+			return this;
+		}
+		const dotenvLocal = this.#read(".env.local");
+		const dotenv = this.#read(".env") + "\n" + dotenvLocal;
+		const envTs = this.#read("env.ts");
+		const cfgTs = this.#read("nodefony.config.ts");
+		const missingInDotenv = KEYS.filter((k) => !new RegExp(`^\\s*${k}\\s*=`, "m").test(dotenv));
+		const missingInEnvTs = KEYS.filter((k) => !envTs.includes(k));
+		const WIRING = {
+			NF_TOTP_KEY: `     totp:     { encryptionKey: ctx.env.NF_TOTP_KEY },`,
+			NF_WEBHOOK_KEY: `     webhooks: { encryptionKey: ctx.env.NF_WEBHOOK_KEY },`,
+			NF_CSRF_SECRET: `     csrf:     { secret: ctx.env.NF_CSRF_SECRET },`
+		};
+		const missingInCfg = KEYS.filter((k) => !cfgTs.includes(k));
+		const w = (s) => {
+			process.stdout.write(s);
+		};
+		w(`\n${BOLD}🔐 Secrets du module security${RESET} ${DIM}— 4 secrets, 3 fichiers${RESET}\n\n`);
+		for (const [name, role] of Object.entries(ROLES)) w(`  ${(name === "jwt.keystore" ? /keystore\s*:/u.test(cfgTs) : new RegExp(`^\\s*${name}\\s*=`, "m").test(dotenv)) ? "\x1B[32m✓" : "\x1B[33m○"}${RESET} ${BOLD}${name.padEnd(16)}${RESET}${DIM}${role.protected}${RESET}\n    ${DIM}sans → ${role.without}${RESET}\n`);
+		const tokenStillThere = /^\s*NF_MCP_TOKEN\s*=/m.test(dotenvLocal);
+		w(`\n${DIM}  · NF_MCP_TOKEN n'est PAS un secret de cette application, et n'a rien à\n    faire dans cette liste : c'est un jeton qu'elle ÉMET, présenté par un\n    agent pour entrer. Aucun code d'ici ne le lit. Il se pose chez l'agent\n    qui le porte — nodefony security:token --write.${RESET}\n`);
+		if (tokenStillThere) w(`${YELLOW}  ⚠ une ligne NF_MCP_TOKEN traîne encore dans .env.local — rien ne la lit,\n    tu peux la retirer.${RESET}\n`);
+		w(`\n${YELLOW}⚠ rien ne se tape dans le terminal : chaque bloc se colle dans le fichier indiqué.${RESET}\n\n`);
+		w(`${BOLD}1. Fichier ${CYAN}.env.local${RESET}${BOLD} — les valeurs${RESET} ${DIM}(gitignoré ; .env commité = défauts NON-secrets)${RESET}\n`);
+		if (missingInDotenv.length === 0) w(`   ${GREEN}✓ les 3 clés y sont déjà${RESET} ${DIM}(rien à faire — rotation = remplacer la valeur à la main)${RESET}\n\n`);
+		else if (opts.write && this.#dotenvTracked()) w(`   ${YELLOW}⚠ .env.local est suivi par git — je n'y écris PAS de secrets.${RESET}\n   ${DIM}Ajoute \`*.local\` au .gitignore (et \`git rm --cached .env.local\`), puis relance --write ;\n   ou colle les lignes ci-dessous à la main :${RESET}\n\n` + missingInDotenv.map((k) => `   ${k}=${secrets[k]}`).join("\n") + `\n\n`);
+		else if (opts.write) {
+			const block = (dotenvLocal && !dotenvLocal.endsWith("\n") ? "\n" : "") + `# clés security — générées par \`nodefony security:secrets\`\n` + missingInDotenv.map((k) => `${k}=${secrets[k]}`).join("\n") + "\n";
+			appendFileSync(path.resolve(this.#root(), ".env.local"), block);
+			w(`   ${GREEN}✓ écrit dans .env.local${RESET} ${DIM}(${missingInDotenv.join(", ")} — les clés déjà présentes n'ont pas été touchées)${RESET}\n\n`);
+		} else w(`   colle ces lignes ${DIM}(ou relance avec ${RESET}${CYAN}--write${RESET}${DIM} pour que je les écrive)${RESET} :\n\n` + missingInDotenv.map((k) => `   ${k}=${secrets[k]}`).join("\n") + `\n   ${DIM}(en prod : Secret k8s / vault — jamais en git)${RESET}\n\n`);
+		w(`${BOLD}2. Fichier ${CYAN}env.ts${RESET}${BOLD} — la déclaration typée${RESET} ${DIM}(env.ts est le seul lecteur de process.env)${RESET}\n`);
+		if (missingInEnvTs.length === 0) w(`   ${GREEN}✓ déjà déclarées${RESET}\n\n`);
+		else w(`   ajoute dans le defineEnv({ … }) :\n\n` + missingInEnvTs.map((k) => `   ${k}: envString({ optional: true }),`).join("\n") + `\n\n`);
+		w(`${BOLD}3. Fichier ${CYAN}nodefony.config.ts${RESET}${BOLD} — le câblage vers le module security${RESET}\n`);
+		if (missingInCfg.length === 0) w(`   ${GREEN}✓ déjà câblées${RESET}\n\n`);
+		else w("   complète l'entrée security du manifeste modules :\n\n   use(\"@nodefony/security\", {\n" + missingInCfg.map((k) => WIRING[k]).join("\n") + `\n   }),\n\n`);
+		const jwtCable = /keystore\s*:/u.test(cfgTs);
+		w(`${BOLD}4. Fichier ${CYAN}nodefony.config.ts${RESET}${BOLD} — les clés de SIGNATURE des jetons${RESET} ${DIM}(jwt.keystore)${RESET}\n`);
+		if (jwtCable) w(`   ${GREEN}✓ déjà câblées${RESET}\n\n`);
+		else w(`   ${YELLOW}⚠ absentes : chaque process signe avec une clé ÉPHÉMÈRE.${RESET}\n   ${DIM}Un jeton émis par la CLI porte alors un \`kid\` que le serveur ne\n   connaît pas, et il est refusé — et un redémarrage invalide les jetons\n   en vol. Ce n'est pas une valeur à coller : c'est une SOURCE à déclarer.${RESET}\n\n   use("@nodefony/security", {\n     jwt: { keystore: ctx.isProd ? {} : { dir: "var/keys" } },\n   }),\n\n   ${DIM}En production, le dossier n'a pas de sens (pods jetables) : la clé vient\n   de l'environnement — jwt.keystore.keySetJson, injecté par ton gestionnaire\n   de secrets et partagé par tous les pods.${RESET}\n\n`);
+		w(`${DIM}Pourquoi 3 fichiers ? .env.local porte la VALEUR (secret machine, gitignoré —\nle .env commité ne porte que des défauts non-secrets) ; env.ts la DÉCLARE\n(catalogue typé, validé au boot) ; nodefony.config.ts la CÂBLE au module.\nLes étapes 2 et 3 ne se font qu'une fois — ensuite seule l'étape 1 vit.\nL'étape 4 sort de ce schéma, et c'est voulu : un keyset n'est pas une valeur\nqu'on colle, mais une source que le keystore gère (rotation, permissions).${RESET}\n\nRelance le serveur : plus aucun warning « clé ÉPHÉMÈRE » au boot.\n\n`);
+		return this;
+	}
+};
+//#endregion
+export { SecuritySecrets as default };