@nodefony/security 10.0.0-alpha.9 → 10.0.0-beta.1

package/dist/nodefony/src/totp/totpCrypto.js

@@ -27,8 +27,8 @@ function base32Encode(buf) {
 	let bits = 0;
 	let value = 0;
 	let out = "";
-	for (let i = 0; i < buf.length; i++) {
-		value = value << 8 | buf[i];
+	for (const byte of buf) {
+		value = value << 8 | byte;
 		bits += 8;
 		while (bits >= 5) {
 			out += BASE32_ALPHABET[value >>> bits - 5 & 31];
@@ -48,9 +48,9 @@ function base32Decode(input) {
 	let bits = 0;
 	let value = 0;
 	const out = [];
-	for (let i = 0; i < clean.length; i++) {
-		const idx = BASE32_ALPHABET.indexOf(clean[i]);
-		if (idx === -1) throw new Error(`base32: caractère invalide « ${clean[i]} »`);
+	for (const char of clean) {
+		const idx = BASE32_ALPHABET.indexOf(char);
+		if (idx === -1) throw new Error(`base32: caractère invalide « ${char} »`);
 		value = value << 5 | idx;
 		bits += 5;
 		if (bits >= 8) {
@@ -85,8 +85,8 @@ function counterBuffer(counter) {
 */
 function hotp(secret, counter, digits = TOTP_DEFAULTS.digits, algorithm = TOTP_DEFAULTS.algorithm) {
 	const hs = createHmac(hmacName(algorithm), secret).update(counterBuffer(counter)).digest();
-	const offset = hs[hs.length - 1] & 15;
-	return (((hs[offset] & 127) << 24 | (hs[offset + 1] & 255) << 16 | (hs[offset + 2] & 255) << 8 | hs[offset + 3] & 255) % 10 ** digits).toString().padStart(digits, "0");
+	const offset = hs.readUInt8(hs.length - 1) & 15;
+	return ((hs.readUInt32BE(offset) & 2147483647) % 10 ** digits).toString().padStart(digits, "0");
 }
 /** Numéro de tranche temporelle `T` (RFC 6238 §4.2) pour un instant donné. */
 function totpCounter(epochSec, step = TOTP_DEFAULTS.step, t0 = TOTP_DEFAULTS.t0) {
@@ -216,8 +216,8 @@ function hashRecoveryCode(code) {
 function matchRecoveryCode(presented, hashes) {
 	const target = Buffer.from(hashRecoveryCode(presented));
 	let found = -1;
-	for (let i = 0; i < hashes.length; i++) {
-		const candidate = Buffer.from(hashes[i]);
+	for (const [i, hash] of hashes.entries()) {
+		const candidate = Buffer.from(hash);
 		if (candidate.length === target.length && timingSafeEqual(candidate, target)) found = i;
 	}
 	return found;

package/dist/nodefony/src/webhook/WebhookDispatcher.js

@@ -78,7 +78,7 @@ var WebhookDispatcher = class {
 	/** Empile une livraison ; **abandonne** (best-effort) si la file est pleine. */
 	#enqueue(job) {
 		if (this.#stopped) return;
-		if (this.#queue === null) this.#queue = [];
+		this.#queue ??= [];
 		if (this.#queue.length >= this.#deps.policy.maxQueue) {
 			this.#dropped++;
 			if (this.#dropped === 1 || this.#dropped % 100 === 0) this.#deps.log(`webhooks: file pleine (${this.#deps.policy.maxQueue}) — ${this.#dropped} livraison(s) abandonnée(s) (best-effort)`);
@@ -100,8 +100,9 @@ var WebhookDispatcher = class {
 	#pump() {
 		if (this.#queue === null || this.#stopped) return;
 		const max = this.#deps.policy.maxConcurrent;
-		while (this.#inFlight < max && this.#queue.length > 0) {
+		while (this.#inFlight < max) {
 			const job = this.#queue.shift();
+			if (job === void 0) break;
 			this.#inFlight++;
 			this.#process(job).finally(() => {
 				this.#inFlight--;
@@ -178,7 +179,7 @@ var WebhookDispatcher = class {
 	/** Replanifie la livraison après backoff (repasse par la file bornée). */
 	#scheduleRetry(job) {
 		if (this.#stopped) return;
-		if (this.#timers === null) this.#timers = /* @__PURE__ */ new Set();
+		this.#timers ??= /* @__PURE__ */ new Set();
 		const cancel = this.#deps.schedule(() => {
 			this.#timers?.delete(cancel);
 			this.#enqueue({

package/dist/types/nodefony/contracts/IAuditEvent.d.ts

@@ -18,7 +18,11 @@
  * filtre qui ne rend jamais rien induit en erreur — cf `studio/.../auditModel.ts`).
  * En câbler une = ajouter son émetteur ICI (l'émetteur), puis la métadonnée
  * d'affichage dans `AUDIT_CATEGORIES`. Émettent réellement : auth, authz, token,
- * session, webauthn, ws, webhook, config (`config.update`).
+ * session, webauthn, ws, webhook, config (`config.update`, `log.debug.*`).
+ *
+ * Un émetteur hors de `@nodefony/security` ne peut pas importer ce type et passe
+ * la catégorie en `string` : `tests/unit/auditCategoryEmitters.test.ts` relit
+ * les sources de tous les paquets pour refuser une catégorie hors contrat.
  */
 export type AuditCategory = "auth" | "authz" | "token" | "session" | "oauth" | "webauthn" | "csrf" | "cors" | "ws" | "webhook" | "config";
 /**
@@ -85,7 +89,7 @@ export interface IAuditEvent {
      */
     flags?: IAuditEventFlags;
     /** Extras applicatifs libres (anti-migration) ; absents par défaut. */
-    metadata?: Record<string, unknown>;
+    metadata?: Record<string, unknown> | undefined;
 }
 /**
  * Champs fournis par l'**émetteur** d'un événement — l'`AuditService` y ajoute

package/dist/types/nodefony/contracts/IFirewall.d.ts

@@ -1,4 +1,4 @@
-import type { ContextType } from "@nodefony/http";
+import type { ContextType, IFirewallGate } from "@nodefony/http";
 import type { IAuthenticator } from "./IAuthenticator.js";
 import type { ISecuredArea } from "./ISecuredArea.js";
 import type { CspFragment } from "../src/csp.js";
@@ -11,7 +11,7 @@ import type { IProtectedResourceInput } from "nodefony";
  * `context.security`. `handleSecurity()` (lazy, seulement si la requête est dans
  * une zone) exécute CORS → headers → authenticators → Zero Trust → CSRF.
  */
-export interface IFirewall {
+export interface IFirewall extends IFirewallGate {
     /** Match rapide de zone (pose `context.security`). `true` si zone capturée. */
     isSecure(context: ContextType): boolean;
     /** Pipeline complet d'authentification de la zone. Rejette (401/403) ou résout. */

package/dist/types/nodefony/contracts/IFirewallDescription.d.ts

@@ -78,11 +78,11 @@ export interface IFirewallDefensesDescription {
         frameguard: "deny" | "sameorigin";
         noSniff: boolean;
         referrerPolicy: string;
-        coop?: string;
-        coep?: string;
-        corp?: string;
-        originAgentCluster?: boolean;
-        permissionsPolicy?: string;
+        coop?: string | undefined;
+        coep?: string | undefined;
+        corp?: string | undefined;
+        originAgentCluster?: boolean | undefined;
+        permissionsPolicy?: string | undefined;
     };
     rateLimit: {
         enabled: boolean;

package/dist/types/nodefony/contracts/ISecuredArea.d.ts

@@ -1,4 +1,4 @@
-import type { ContextType } from "@nodefony/http";
+import type { ContextType, ISecurityZone } from "@nodefony/http";
 /**
  * Zone sécurisée — un pattern d'URL + la liste des authenticators à exécuter.
  *
@@ -7,7 +7,7 @@ import type { ContextType } from "@nodefony/http";
  * `defineSecurityConfig({ areas })` — patterns compilés et triés au boot, conflits
  * détectés au boot (pas au premier match runtime).
  */
-export interface ISecuredArea {
+export interface ISecuredArea extends ISecurityZone {
     /** Nom de la zone (`"main_api"`, `"admin"`…). */
     readonly name: string;
     /** Pattern d'URL compilé. */
@@ -29,7 +29,7 @@ export interface ISecuredArea {
     /** Noms des authenticators à exécuter (sémantique selon {@link mode}). */
     readonly authenticators: readonly string[];
     /** Domaine/vhost de la zone (ex. `admin.exemple.com`). Omis = tous domaines. */
-    readonly host?: string;
+    readonly host?: string | undefined;
     /**
      * URI canonique de la ressource protégée par cette zone — l'**audience**
      * qu'un jeton doit porter pour y être accepté (RFC 8707 §2).
@@ -44,7 +44,7 @@ export interface ISecuredArea {
      * Omise, une zone reste parfaitement utilisable par les authenticators qui
      * n'en ont pas besoin (session, mot de passe, jetons maison).
      */
-    readonly resource?: string;
+    readonly resource?: string | undefined;
     /**
      * Zone valable AUSSI pour le WebSocket (frames `api.request` + `subscribe`),
      * pas seulement HTTP. Défaut `true` (Zero Trust : une zone protégée ferme TOUS

package/dist/types/nodefony/contracts/ITokenStore.d.ts

@@ -27,7 +27,7 @@ export interface IResourcePermission {
     /** Type de ressource (ex. `"repo"`, `"project"`). */
     type: string;
     /** Identifiants ciblés (omis = toutes les ressources de ce type). */
-    ids?: string[];
+    ids?: string[] | undefined;
     /** Permissions accordées sur ces ressources. */
     perms: Array<"read" | "write">;
 }
@@ -36,9 +36,9 @@ export interface ITokenUsage {
     /** Instant d'usage (epoch ms). */
     at: number;
     /** IP source, si disponible. */
-    ip?: string | null;
+    ip?: string | null | undefined;
     /** User-Agent source, si disponible. */
-    userAgent?: string | null;
+    userAgent?: string | null | undefined;
 }
 /**
  * Enregistrement d'un jeton persistant — un PAT (clé API style GitHub) ou un

package/dist/types/nodefony/contracts/ITotpSecretStore.d.ts

@@ -46,13 +46,13 @@ export interface ITotpListQuery extends IPageQuery {
 /** Champs mutables d'un secret TOTP (patch partiel). */
 export interface TotpSecretUpdate {
     /** Confirmation de l'enrôlement (epoch ms) — passe le secret en « actif ». */
-    confirmedAt?: number | null;
+    confirmedAt?: number | null | undefined;
     /** Stock résiduel de codes de récupération hachés (après consommation). */
-    recoveryCodes?: string[];
+    recoveryCodes?: string[] | undefined;
     /** Dernière tranche `T` validée (anti-rejeu RFC 6238 §5.2). */
-    lastUsedStep?: number;
+    lastUsedStep?: number | undefined;
     /** Horodatage du dernier usage réussi (epoch ms). */
-    lastUsedAt?: number;
+    lastUsedAt?: number | undefined;
 }
 /**
  * Store **pluggable** du secret TOTP par utilisateur — découple le cœur du backend

package/dist/types/nodefony/contracts/IWebAuthnCredentialStore.d.ts

@@ -28,7 +28,7 @@ export interface IWebAuthnCredentialSummary {
     /** Compteur de signatures (anti-clone WebAuthn §6.1.1). */
     readonly signCount: number;
     /** Nom donné à l'appareil par l'utilisateur, si renseigné. */
-    readonly nickname?: string;
+    readonly nickname?: string | undefined;
     /** Enrôlement (epoch ms). */
     readonly createdAt: number;
     /** Dernière authentification réussie (epoch ms), ou `null` = jamais servie. */

package/dist/types/nodefony/errors/InvalidTargetError.d.ts

@@ -23,7 +23,7 @@ export declare class InvalidTargetError extends nodefonyError {
     /** Code d'erreur OAuth à rendre au client (RFC 6749 §5.2 / RFC 8707 §2). */
     readonly oauthError = "invalid_target";
     /** Ce que le client a demandé, tel qu'il l'a écrit — pour le journal. */
-    readonly requested?: string;
+    readonly requested?: string | undefined;
     /**
      * @param description - raison, destinée à `error_description` (aucune fuite :
      *          elle qualifie la DEMANDE, jamais la configuration du serveur)

package/dist/types/nodefony/errors/UnverifiableTokenError.d.ts

@@ -27,7 +27,7 @@ import { nodefonyError } from "nodefony";
  */
 export declare class UnverifiableTokenError extends nodefonyError {
     /** Cause technique, destinée au JOURNAL — jamais au client. */
-    readonly detail?: string;
+    readonly detail?: string | undefined;
     /**
      * @param detail - cause technique pour le journal ; n'apparaît jamais dans le
      *          message rendu au client

package/dist/types/nodefony/service/firewall.d.ts

@@ -25,8 +25,9 @@ import type { IFirewallDescription, IRoleHierarchyDescription } from "../contrac
  * d'identité down, câblage manquant) → log ERROR serveur + 401 générique
  * (aucun détail ne fuite au client).
  *
- * Conformité : tout 401 porte un challenge `WWW-Authenticate` (RFC 7235) fourni
- * par le premier authenticator de la zone qui en déclare un.
+ * Conformité : tout 401 porte un challenge `WWW-Authenticate` (RFC 9110
+ * §15.5.2) — celui du premier authenticator de la zone qui en déclare un, sinon
+ * le défi de repli {@link FALLBACK_CHALLENGE}.
  *
  * CORS, CSRF et autorisation par décorateurs viennent se brancher en S4/S5.
  * Toutes les structures sont **lazy** (perf : une app sans zone = zéro alloc).

package/dist/types/nodefony/service/securityHeaders.d.ts

@@ -13,11 +13,11 @@ export interface ISecurityHeadersOptions {
     csp: string;
     cspNonces: boolean;
     referrerPolicy: string;
-    coop?: string;
-    coep?: string;
-    corp?: string;
-    originAgentCluster?: boolean;
-    permissionsPolicy?: string;
+    coop?: string | undefined;
+    coep?: string | undefined;
+    corp?: string | undefined;
+    originAgentCluster?: boolean | undefined;
+    permissionsPolicy?: string | undefined;
 }
 /**
  * En-têtes de sécurité **applicatifs** de Nodefony (couche `@nodefony/security`,

package/dist/types/nodefony/src/SecuredArea.d.ts

@@ -15,9 +15,9 @@ export declare class SecuredArea implements ISecuredArea {
     readonly stateless: boolean;
     readonly mode: "first" | "all";
     readonly authenticators: readonly string[];
-    readonly host?: string;
+    readonly host?: string | undefined;
     readonly realtime: boolean;
-    readonly resource?: string;
+    readonly resource?: string | undefined;
     /**
      * Rôles exigés par défaut dans la zone, ou `null` quand elle n'en exige
      * aucun. `null` plutôt qu'un tableau vide : le hot path teste une référence,

package/dist/types/nodefony/src/authenticator/SessionAuthenticator.d.ts

@@ -14,9 +14,11 @@ import type { IToken } from "../../contracts/IToken.js";
  * démarre jamais rien lui-même. L'identité est re-résolue à CHAQUE requête
  * via {@link resolveSessionIdentity} (rôles frais, révocation immédiate).
  *
- * Pas de `challenge()` : une session absente/expirée donne un 401 nu — le
- * client web redirige vers son écran de login, jamais de popup Basic. Si la
- * zone liste aussi `userpassword`, le firewall pose SON challenge (RFC 7235).
+ * Pas de `challenge()` : sur une zone à session seule, le firewall pose son
+ * défi de repli `Session realm="nodefony"` (RFC 9110 §15.5.2 : tout 401 en
+ * porte un) — schéma inconnu des navigateurs, donc jamais de popup Basic ; le
+ * client web redirige vers son écran de login. Si la zone liste aussi
+ * `userpassword`, le firewall pose SON challenge.
  */
 export declare class SessionAuthenticator implements IAuthenticator {
     #private;

package/dist/types/nodefony/src/oauth/oauth2Client.d.ts

@@ -137,9 +137,9 @@ export interface IOAuth2ClientOptions {
      * Implémentation de `fetch` à employer — la voie pour éprouver l'échange sans
      * réseau, plutôt que de remplacer le `fetch` global du processus.
      */
-    readonly fetch?: typeof globalThis.fetch;
+    readonly fetch?: typeof globalThis.fetch | undefined;
     /** Délai d'attente de l'échange, en millisecondes. */
-    readonly timeoutMs?: number;
+    readonly timeoutMs?: number | undefined;
 }
 /**
  * Client d'un serveur d'autorisation donné : construit l'URL d'autorisation puis

package/dist/types/nodefony/src/oauth/oauthProviderRegistry.d.ts

@@ -33,7 +33,7 @@ export interface IOAuthProviderContext {
      * champ, la forme serait ouverte dans le client et INATTEIGNABLE depuis une
      * application — donc absente.
      */
-    readonly clientAuthMethod?: OAuth2ClientAuthMethod;
+    readonly clientAuthMethod?: OAuth2ClientAuthMethod | undefined;
     /** URL de callback exacte (RFC 9700). */
     readonly redirectUri: string;
     /**
@@ -41,7 +41,7 @@ export interface IOAuthProviderContext {
      * `https://kc.example/realms/app`) — `undefined` pour les fournisseurs dont
      * l'émetteur est connu d'avance (Google) ou qui n'en publient pas (GitHub).
      */
-    readonly issuer?: string;
+    readonly issuer?: string | undefined;
 }
 /**
  * Fabrique d'un fournisseur OAuth pour un nom donné.

package/dist/types/nodefony/src/realtime/realtimeContracts.d.ts

@@ -83,11 +83,11 @@ export type FrameAuthorizer = (frame: unknown, token: IRealtimeToken) => boolean
  */
 export interface IChannelPolicy {
     /** Exige une connexion authentifiée (token non anonyme). */
-    readonly authenticated?: boolean;
+    readonly authenticated?: boolean | undefined;
     /** Un de ces rôles suffit (évalué AVEC la hiérarchie de rôles du firewall). */
-    readonly roles?: readonly string[];
+    readonly roles?: readonly string[] | undefined;
     /** Un de ces scopes suffit (axe API : JWT/clé API ; session BFF n'en porte pas). */
-    readonly scopes?: readonly string[];
+    readonly scopes?: readonly string[] | undefined;
 }
 /**
  * Surface consommée du `realtimeService` (miroir partiel de `RealtimeService`) —

package/dist/types/nodefony/src/token/JwtKeystore.d.ts

@@ -5,9 +5,9 @@ type LogFn = (message: string, severity: string) => void;
 /** Source de clé configurée (`config.jwt.keystore`). */
 interface KeystoreSource {
     /** JWK Set (clés privées) injecté depuis l'env — source `env` (prod). */
-    readonly keySetJson?: string;
+    readonly keySetJson?: string | undefined;
     /** Dossier de persistance `keyset.json` — source `fichier` (opt-in dev/VPS). */
-    readonly dir?: string;
+    readonly dir?: string | undefined;
 }
 /**
  * Le trousseau va-t-il partir dans l'image de conteneur ?

package/dist/types/nodefony/src/token/RemoteJwtVerifier.d.ts

@@ -20,7 +20,7 @@ export interface ITrustedIssuer {
      * une requête au démarrage à froid. Déclaré, il fait autorité : rien n'est
      * découvert.
      */
-    jwksUri?: string;
+    jwksUri?: string | undefined;
     /**
      * Jeu de clés fourni LOCALEMENT — aucune requête, aucune découverte.
      *
@@ -58,7 +58,7 @@ export interface ITrustedIssuer {
      * réglé finement. La séparation entre jetons est déjà assurée par l'audience,
      * qui, elle, n'est pas facultative.
      */
-    typ?: string;
+    typ?: string | undefined;
     /** Claims dont la PRÉSENCE est exigée, en plus de `iss`/`aud`/`sub`. */
     requiredClaims?: readonly string[];
 }

package/dist/types/nodefony/src/token/jwtRuntime.d.ts

@@ -26,3 +26,13 @@ export interface IJwtRuntime {
  * propre audience (`[issuer]`).
  */
 export declare function resolveJwtRuntime(jwt: ISecurityConfig["jwt"]): IJwtRuntime;
+/**
+ * Audience inscrite dans un jeton quand aucune ressource n'est demandée : la
+ * première de la liste blanche. La liste n'est jamais vide après
+ * {@link resolveJwtRuntime} ; un runtime construit à la main qui la laisserait
+ * vide retombe sur la même règle — l'application est sa propre audience.
+ *
+ * @param runtime - paramètres JWT résolus
+ * @returns l'audience par défaut
+ */
+export declare function defaultAudience(runtime: IJwtRuntime): string;

package/docs/api-keys.md

@@ -229,7 +229,7 @@ curl -si https://localhost:5152/api/v1/orders/list | head -1
 > [!WARNING]
 > Le champ `token` de la réponse 201 est la **seule** occasion de lire le secret : il n'est pas
 > stocké, donc pas re-dérivable (`IApiKeyCreated`, `IApiKey.ts:44`). Le listing ultérieur ne
-> renvoie que le `prefix` public (`#toView()`, `apiKeys.ts:393`). Perdue = ré-émise.
+> renvoie que le `prefix` public (`#toView()`, `apiKeys.ts:386`). Perdue = ré-émise.
 
 ## 🔐 Anatomie d'une clé — ce que chaque morceau paie
 
@@ -276,16 +276,16 @@ jamais par le préfixe.
 
 ### Émission — `ApiKeyService.createForSubject()`
 
-`ApiKeyService.createForSubject()` (`apiKeys.ts:128`) est le seul chemin d'émission. Dans l'ordre :
+`ApiKeyService.createForSubject()` (`apiKeys.ts:121`) est le seul chemin d'émission. Dans l'ordre :
 
 1. **Validation du nom** — non vide, ≤ 100 caractères ; sinon `ApiKeyError` 400 (`#normalizeName()`,
-   `apiKeys.ts:337`).
+   `apiKeys.ts:330`).
 2. **Validation des scopes** — tableau de chaînes non vides, dédupliquées, et **⊆ catalogue** si
-   `allowedScopes` est défini ; sinon 400 (`#normalizeScopes()`, `apiKeys.ts:348`).
+   `allowedScopes` est défini ; sinon 400 (`#normalizeScopes()`, `apiKeys.ts:341`).
 3. **Résolution de l'expiration** — `expiresInDays` explicite, sinon le défaut de config, `null` =
-   sans expiration ; une valeur non positive lève un 400 (`#resolveExpiry()`, `apiKeys.ts:370`).
+   sans expiration ; une valeur non positive lève un 400 (`#resolveExpiry()`, `apiKeys.ts:363`).
 4. **Plafond anti-abus** — on ne compte que les clés **actives** (ni révoquées ni expirées) via
-   `#isActive()` (`apiKeys.ts:386`) ; au-delà de `maxPerSubject` → 409 (`apiKeys.ts:55`).
+   `#isActive()` (`apiKeys.ts:379`) ; au-delà de `maxPerSubject` → 409 (`apiKeys.ts:48`).
 5. **Génération** — 32 octets aléatoires, `publicPrefix` et `secretHash` dérivés
    (`generateApiKey()`, `apiKeyFormat.ts:92`).
 6. **Écriture** — le `record` de `kind:"pat"` posé au store par `store.put()` (`apiKeys.ts:177`).
@@ -293,7 +293,7 @@ jamais par le préfixe.
    secret** (`apiKeys.ts:183-189`).
 
 Le service ne connaît pas le store à la construction : il le résout **paresseusement** du container
-au premier usage (`#resolveStore()`, `apiKeys.ts:324`) — indépendant de l'ordre de boot. Store
+au premier usage (`#resolveStore()`, `apiKeys.ts:317`) — indépendant de l'ordre de boot. Store
 absent = **503 explicite**, jamais une 500 opaque.
 
 ### Vérification — `ApiKeyAuthenticator.authenticate()`
@@ -353,7 +353,7 @@ apiKeys: {
 **Ce qu'on observe** : `npx nodefony security:user:add ci-bot` (rôle `ROLE_USER` par défaut), login
 en tant que `ci-bot`, puis émission avec `{"scopes":["orders:read"]}`. Demander
 `{"scopes":["orders:write"]}` renvoie **400 `scope not allowed: orders:write`** — refusé à
-l'émission, pas seulement à l'usage (`#normalizeScopes()`, `apiKeys.ts:348`).
+l'émission, pas seulement à l'usage (`#normalizeScopes()`, `apiKeys.ts:341`).
 
 > [!TIP]
 > Le catalogue `allowedScopes` de la config est un **complément**, pas la source : la console
@@ -368,7 +368,7 @@ doit y avoir **aucune** fenêtre pendant laquelle le job échoue.
 
 **Il n'y a pas de bouton « rotate »** — et c'est délibéré : une rotation atomique impliquerait
 soit deux secrets valides sous le même id (ambigu à auditer), soit une coupure. Le motif est le
-**recouvrement**, rendu possible par le plafond `maxPerSubject` (`apiKeys.ts:55`) :
+**recouvrement**, rendu possible par le plafond `maxPerSubject` (`apiKeys.ts:48`) :
 
 1. Émettre une **seconde** clé (même porteur, mêmes scopes, nom `CI deploy v2`).
 2. Déployer le nouveau secret dans le CI.
@@ -388,8 +388,8 @@ Deux chemins, selon qui agit :
 
 | Qui        | Endpoint                                          | Portée                 | Ancrage                                 |
 | ---------- | ------------------------------------------------- | ---------------------- | --------------------------------------- |
-| Le porteur | `DELETE /nodefony/security/api/keys/{id}`         | **ses** clés seulement | `revokeForSubject()` (`apiKeys.ts:303`) |
-| Un admin   | `POST /nodefony/security/api/apikeys/{id}/revoke` | n'importe quelle clé   | `revokeAnyPat()` (`apiKeys.ts:257`)     |
+| Le porteur | `DELETE /nodefony/security/api/keys/{id}`         | **ses** clés seulement | `revokeForSubject()` (`apiKeys.ts:296`) |
+| Un admin   | `POST /nodefony/security/api/apikeys/{id}/revoke` | n'importe quelle clé   | `revokeAnyPat()` (`apiKeys.ts:250`)     |
 
 **Ce qu'on observe** : la révocation est **idempotente** et prend effet à la requête suivante —
 l'authenticator lit `revokedAt` avant toute autre décision (`ApiKeyAuthenticator.ts:111-118`).
@@ -417,7 +417,7 @@ Trois sources, et il faut connaître les limites de chacune :
 
 1. **L'état** — le listing d'administration paginé, tous porteurs confondus : `GET
 /nodefony/security/api/apikeys` (`SecurityAdminApi.ts:394`), servi par `listPagePat()`
-   (`apiKeys.ts:216`). Filtres `subjectId`, `revoked`, fenêtre `limit`/`offset`/`cursor` et tri
+   (`apiKeys.ts:209`). Filtres `subjectId`, `revoked`, fenêtre `limit`/`offset`/`cursor` et tri
    `order=champ:ASC` (`parseTokenListQuery()`, `SecurityAdminApi.ts:126`), plafonnée à 200 entrées
    (`KEYS_MAX_LIMIT`, `SecurityAdminApi.ts:114`).
 
@@ -596,7 +596,7 @@ révocation ne traverse pas. Le détail de la résolution, des avertissements et
 | Message d'échec uniforme          | OWASP API2:2023 (Broken Auth)          | `INVALID_TOKEN` (`ApiKeyAuthenticator.ts:17`)          |
 | Révocation immédiate côté serveur | OWASP API2:2023                        | `revokedAt` vérifié (`ApiKeyAuthenticator.ts:111-118`) |
 | Entropie du secret (≥ 128 bits)   | NIST SP 800-63B                        | 32 octets aléatoires (`apiKeyFormat.ts:30`)            |
-| Plafond de ressources par acteur  | OWASP API4:2023 (Resource Consumption) | `maxPerSubject` (`apiKeys.ts:55`)                      |
+| Plafond de ressources par acteur  | OWASP API4:2023 (Resource Consumption) | `maxPerSubject` (`apiKeys.ts:48`)                      |
 
 ## ⚡ Performance & mémoire
 
@@ -614,7 +614,7 @@ Le coût par requête authentifiée par clé est **maîtrisé par construction**
   container au premier usage et mémoïsés (`ApiKeyAuthenticator.ts:173`, `apiKeys.ts:268`) — le boot
   ne paie rien si aucune clé n'est jamais présentée.
 - **Jamais N enregistrements en RAM** côté administration : le listing est paginé **au store**
-  (`listPagePat()`, `apiKeys.ts:216`), fenêtre plafonnée à 200 (`SecurityAdminApi.ts:107`).
+  (`listPagePat()`, `apiKeys.ts:209`), fenêtre plafonnée à 200 (`SecurityAdminApi.ts:107`).
 
 Le point de vigilance restant : `createForSubject()` compte les clés actives via `findBySubject()`
 (`ITokenStore.ts:211`), qui charge **toutes** les clés du porteur. C'est borné par `maxPerSubject`
@@ -649,7 +649,7 @@ pas masqué à l'affichage. Voir aussi l'écran **Audit** pour les événements
 | 401 à la création de clé                               | Ces routes exigent une **session** (pas de `bypassFirewall`)                                   | Se connecter d'abord (`/nodefony/security/api/auth/login`)             |
 | Le token clair est introuvable après coup              | Seul `sha256` est stocké — non re-dérivable (`apiKeyFormat.ts:70`)                             | Émettre une nouvelle clé, révoquer l'ancienne                          |
 | 409 « API key limit reached »                          | Plafond de clés **actives** atteint (`apiKeys.ts:144-147`)                                     | Révoquer les clés inutilisées ou relever `maxPerSubject`               |
-| 400 « scope not allowed »                              | Scope hors du catalogue `allowedScopes` (`apiKeys.ts:363`)                                     | Ajouter le scope au catalogue, ou corriger la demande                  |
+| 400 « scope not allowed »                              | Scope hors du catalogue `allowedScopes` (`apiKeys.ts:284`)                                     | Ajouter le scope au catalogue, ou corriger la demande                  |
 | Toutes les clés rejetées après un changement de config | `prefix` modifié → les anciennes ne sont plus reconnues (`authenticatorRegistry.ts:142`)       | Garder le `prefix` STABLE après la première émission                   |
 | Clé valide mais 403 sur la route                       | Autorisation, pas authentification : scope manquant — `ScopeVoter.vote()` (`ScopeVoter.ts:50`) | Émettre une clé portant le scope exigé par `@RequireScope`             |
 | Clé rejetée alors qu'elle n'est ni expirée ni révoquée | Porteur désactivé/verrouillé, ou seuil `invalidBefore` (`ApiKeyAuthenticator.ts:121-124`)      | Réactiver le compte, ou réémettre après le bannissement                |

package/docs/audit.md

@@ -196,7 +196,7 @@ export default ExportController;
 ```
 
 > [!IMPORTANT]
-> `category` est une **union fermée** de sous-systèmes de sécurité (`IAuditEvent.ts:24`) : il n'existe
+> `category` est une **union fermée** de sous-systèmes de sécurité (`IAuditEvent.ts:71`) : il n'existe
 > pas de catégorie « métier ». C'est volontaire — ce journal est celui de la sécurité. Range ton
 > événement dans la catégorie de sécurité qu'il concerne (ici `authz` : un accès privilégié à des
 > données) et laisse `action` porter le vocabulaire métier.
@@ -317,7 +317,7 @@ anti-avalanche en cluster. Chaque
 tour appelle la purge du contrat — `gc()`, voisin de `listPage()` dans le même contrat
 (`IAuditStore.ts:59`) — qui supprime les événements plus vieux que la fenêtre : un `DELETE` par seuil
 côté SQL (`DrizzleAuditStore.ts:256`), un défilement de file tant que l'événement de tête dépasse le
-`threshold` côté mémoire (`MemoryAuditStore.ts:138`).
+`threshold` côté mémoire (`MemoryAuditStore.ts:133`).
 
 Ce qu'on observe dans les logs : `audit gc — 1284 événement(s) purgé(s)` en niveau DEBUG.
 
@@ -332,7 +332,7 @@ La base est indisponible pendant trente secondes. Que se passe-t-il ?
 
 Le choix de Nodefony est explicite : **le métier passe avant la trace**. L'écriture part en
 fire-and-forget — `append()` sans `await`, échec absorbé en log ERROR (`auditService.ts:199`) ; côté SQL, si l'ORM n'est
-pas connecté, `append()` est un no-op assumé (`DrizzleAuditStore.ts:146`). Un login n'échoue jamais
+pas connecté, `append()` est un no-op assumé (`DrizzleAuditStore.ts:152`). Un login n'échoue jamais
 parce que le journal est cassé.
 
 > [!WARNING]
@@ -357,17 +357,22 @@ l'axe de filtrage principal de la console. L'**action** est une chaîne **ouvert
 <!-- prettier-ignore -->
 | Catégorie | Ce qu'elle trace | Actions réellement émises par le framework |
 | --- | --- | --- |
-| `auth` | authentification, chaîne du firewall | `auth.failure` · `auth.unverifiable` · `auth.throttled` · `auth.denied` · `login.success` · `login.failure` · `login.throttled` · `login.mfa_required` · `user.totp_disabled` |
-| `authz` | autorisation (voters, `@IsGranted`) | `access.denied` |
+| `auth` | authentification, chaîne du firewall | `auth.failure` · `auth.unverifiable` · `auth.throttled` · `auth.denied` · `login.success` · `login.failure` · `login.throttled` · `login.mfa_required` · `user.totp_disabled` · `user.password_change_self` (par `@nodefony/user`) |
+| `authz` | autorisation (voters, `@IsGranted`), administration des comptes | `access.denied` · `user.created` · `user.updated` · `user.password_changed` · `user.deleted` (ces quatre-là par `@nodefony/user`) |
 | `token` | jetons longue durée et clés d'API | `token.issued` · `token.reuse_detected` · `apikey.created` · `apikey.revoked` |
-| `session` | cycle de vie de session | `logout` |
+| `session` | cycle de vie de session | `logout` · `session.revoked` (révocation depuis l'administration, par `@nodefony/http`) |
 | `webauthn` | passkeys | `user.passkey_revoked` |
 | `ws` | verrou de frame WebSocket | `frame.denied` |
 | `webhook` | webhooks sortants | `webhook.created` · `webhook.updated` · `webhook.deleted` · `webhook.rotated` · `webhook.revealed` · `webhook.disabled` |
 | `oauth` | login social OAuth2 | _catégorie déclarée, aucune action émise aujourd'hui_ |
 | `csrf` | défense CSRF | _catégorie déclarée, aucune action émise aujourd'hui_ |
 | `cors` | politique CORS | _catégorie déclarée, aucune action émise aujourd'hui_ |
-| `config` | mutation de config runtime depuis Studio | _catégorie déclarée, aucune action émise aujourd'hui_ |
+| `config` | mutation de config runtime depuis Studio | `config.update` · `log.debug.set` · `log.debug.clear` (par `@nodefony/framework`) |
+
+Toute catégorie émise appartient au type `AuditCategory`, y compris depuis un paquet qui ne peut pas
+l'importer (`@nodefony/user`, `@nodefony/framework`) : `tests/unit/auditCategoryEmitters.test.ts`
+relit les sources de tous les paquets et refuse un littéral hors contrat. Un filtre sur les
+catégories déclarées voit donc tout le journal.
 
 Les trois issues possibles (`IAuditEvent.ts:43`) ne sont pas interchangeables : `failure` = **l'acteur
 a échoué une preuve** (mauvais mot de passe, signature invalide) ; `denied` = **une politique a
@@ -377,7 +382,7 @@ Pour un auditeur, la colonne `denied` est celle des tentatives d'accès non auto
 ### `auth` — la chaîne d'authentification
 
 Quatre sorties d'échec du firewall passent par le même helper `Firewall.#recordAuth()`
-(`firewall.ts:900`), qui enrichit l'événement de la provenance et pose la **zone** en `resource` :
+(`firewall.ts:907`), qui enrichit l'événement de la provenance et pose la **zone** en `resource` :
 
 - `auth.throttled` — backoff NIST déclenché, réponse 429 (`firewall.ts:781`) ;
 - `auth.failure` — un credential a été **présenté** et rejeté (`firewall.ts:807`) ;
@@ -460,7 +465,7 @@ Quatre mécanismes, tous prouvés par les tests.
 
 **1. Le chemin nominal n'émet rien.** Ce n'est pas une optimisation, c'est le modèle : le firewall
 n'appelle `#recordAuth()` que depuis ses quatre sorties d'échec, jamais depuis le succès
-(`firewall.ts:900`). Le verrou WS ne tire sa closure `onDeny` que sur refus (`firewall.ts:352`).
+(`firewall.ts:907`). Le verrou WS ne tire sa closure `onDeny` que sur refus (`firewall.ts:358`).
 Prouvé : « frame AUTORISÉE → onDeny JAMAIS appelé » (`auditEmissionHotPath.test.ts:333`).
 
 **2. Audit désactivé = coût nul, pas juste coût faible.** `record()` sort avant toute allocation et
@@ -480,7 +485,7 @@ alloué qu'au premier événement reçu (`auditBridge.ts:62`) ; son minuteur est
 Le pont applique en plus un **coalescing borné** : au plus une frame WS toutes les 250 ms
 (`auditBridge.ts:59`), tampon plafonné à 200 événements (`auditBridge.ts:60`). Sous une rafale
 d'échecs de login, le tampon écrase les plus anciens et compte les omis dans `dropped`
-(`auditBridge.ts:79`) — la console affiche un récapitulatif au lieu de se figer. Superviser ne doit
+(`auditBridge.ts:86`) — la console affiche un récapitulatif au lieu de se figer. Superviser ne doit
 jamais faire tomber ce qu'on supervise.
 
 ## ⚙️ Configuration
@@ -545,7 +550,7 @@ Quatre pièces, quatre responsabilités :
   **`append` est la seule écriture** : ni `update`, ni `delete` ciblé. L'immuabilité EST la garantie
   d'audit.
 - **`createAuditBridge()`** (`auditBridge.ts:53`) — le pont vers le canal WS `nodefony:audit`
-  (`auditBridge.ts:8`), enregistré comme canal **système** par le firewall (`firewall.ts:322`) et donc
+  (`auditBridge.ts:8`), enregistré comme canal **système** par le firewall (`firewall.ts:387`) et donc
   gardé par le plancher `security:` → `ROLE_NODEFONY_ADMIN` (`frameAuthorizer.ts:106`).
 
 ### La lecture paginée — pourquoi un curseur et pas un décalage
@@ -567,7 +572,7 @@ tiennent identiquement :
 
 Le `total` est **refusable** (`withTotal: false`) : un `COUNT` filtré sur une rétention longue se
 paie (`IAuditStore.ts:59`). `hasNext` et `nextCursor` restent fiables dans les deux cas, grâce à une
-ligne de garde `limit + 1` (`DrizzleAuditStore.ts:198`).
+ligne de garde `limit + 1` (`DrizzleAuditStore.ts:225`).
 
 ## Entité de persistance et dialectes pris en charge
 
@@ -632,7 +637,7 @@ Ce que le code garantit, concrètement :
 - **Le typage rend le secret difficile à faire entrer.** `actor` est documenté comme un _libellé
   d'identité_ (`IAuditEvent.ts:82`) et `resource` comme un _descripteur léger_ — « jamais le corps ni
   les en-têtes de la requête » (`IAuditEvent.ts:87`).
-- **La présence remplace la valeur.** `IAuditEventFlags` (`IAuditEvent.ts:49`) ne porte que deux
+- **La présence remplace la valeur.** `IAuditEventFlags` (`IAuditEvent.ts:53`) ne porte que deux
   booléens : un en-tête `Authorization` était-il là, un cookie était-il là. `readAuditContext()`
   les calcule par un simple `Boolean(headers[…])` (`readAuditContext.ts:40`) — la valeur n'est jamais
   copiée.