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

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/dist/types/nodefony/src/totp/MemoryTotpSecretStore.d.ts

@@ -16,15 +16,6 @@ export declare function matchesTotpQuery(secret: ITotpSecret, query: ITotpListQu
 export interface TotpStoreSnapshot {
     secrets: ITotpSecret[];
 }
-/**
- * Store de secrets TOTP **en mémoire** — implémentation de référence
- * d'{@link ITotpSecretStore}. Clé = `userId` (un secret par utilisateur).
- *
- * 0 dépendance, idéale pour le développement mono-process et les **tests**. NON
- * partagée entre process et **volatile** → en production multi-process, utiliser
- * un adapter ORM ou Redis. Perf : la `Map` n'existe que si le store est instancié
- * (2FA activé), jamais sur le hot path par requête.
- */
 export declare class MemoryTotpSecretStore implements ITotpSecretStore {
     #private;
     findByUser(userId: string): Promise<ITotpSecret | null>;

package/dist/types/nodefony/src/webhook/MemoryWebhookStore.d.ts

@@ -10,14 +10,6 @@ import type { IWebhookEndpoint, WebhookEndpointUpdate } from "../../contracts/IW
  * @returns `true` si l'endpoint appartient à la collection filtrée.
  */
 export declare function matchesWebhookQuery(e: IWebhookEndpoint, query: IWebhookListQuery): boolean;
-/**
- * Store d'endpoints webhook **en mémoire** — défaut dev/test (non persistant :
- * les endpoints sont perdus au redémarrage). En prod, utiliser `drizzle`/
- * `mongoose` (config `webhooks.store`).
- *
- * Map indexée par id (O(1)). Les lectures renvoient une **copie défensive** : le
- * store détient la vérité, un consommateur ne peut pas muter un record en place.
- */
 export declare class MemoryWebhookStore implements IWebhookStore {
     #private;
     /**

package/docs/api-keys.md

@@ -115,7 +115,7 @@ qu'il arrive côté serveur — révoquer exige d'ajouter… un état serveur (d
 lecture qu'on voulait éviter. Une clé d'API vit **des mois** : un jeton auto-porté de six mois qui
 fuite est une porte ouverte de six mois. Le PAT inverse le compromis : sa vérité est dans le store,
 donc `revokedAt` posé = accès coupé à la requête suivante, sans attendre aucune expiration
-(`ApiKeyAuthenticator.authenticate()`, `ApiKeyAuthenticator.ts:107-114`).
+(`ApiKeyAuthenticator.authenticate()`, `ApiKeyAuthenticator.ts:97-104`).
 
 **Ce que Nodefony fait pour que ça reste bon marché** — trois décisions ancrées au code :
 
@@ -193,7 +193,7 @@ export default OrdersController;
 ### 3. Émettre la clé — par l'API, avec une session
 
 L'émission est un **endpoint fourni**, monté seulement si le service `apiKeys` existe
-(`mountApiKeyRoutes()`, `ApiKeyController.ts:191`). Il n'y a **pas** de commande CLI pour créer une
+(`mountApiKeyRoutes()`, `ApiKeyController.ts:192`). Il n'y a **pas** de commande CLI pour créer une
 clé : la création exige une **session BFF** (les routes ne sont pas `bypassFirewall` —
 `ApiKeyController.ts:50-54`), parce que le porteur est **toujours** l'utilisateur courant, jamais un
 paramètre.
@@ -228,8 +228,8 @@ 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:36`). Le listing ultérieur ne
-> renvoie que le `prefix` public (`#toView()`, `apiKeys.ts:393`). Perdue = ré-émise.
+> stocké, donc pas re-dérivable (`IApiKeyCreated`, `IApiKey.ts:44`). Le listing ultérieur ne
+> renvoie que le `prefix` public (`#toView()`, `apiKeys.ts:386`). Perdue = ré-émise.
 
 ## 🔐 Anatomie d'une clé — ce que chaque morceau paie
 
@@ -239,7 +239,7 @@ raison est dans le code (`apiKeyFormat.ts:8-10`) : le charset base64url contient
 
 | Morceau  | Taille               | Secret ? | À quoi ça sert                                                                                     |
 | -------- | -------------------- | :------: | -------------------------------------------------------------------------------------------------- |
-| `prefix` | ≤ 12 car. minuscules |   non    | Marque applicative — discrimine du JWT, aide le secret-scanning (`config.ts:730`)                  |
+| `prefix` | ≤ 12 car. minuscules |   non    | Marque applicative — discrimine du JWT, aide le secret-scanning (`config.ts:736`)                  |
 | `pubid`  | 6 octets → 8 car.    |   non    | Identifiant affichable dans la console (`nf_a1b2c3d4`) — `generateApiKey()` (`apiKeyFormat.ts:92`) |
 | `secret` | 32 octets → 43 car.  | **oui**  | 256 bits d'entropie — `SECRET_BYTES` (`apiKeyFormat.ts:30`)                                        |
 | `crc`    | 4 octets → 6 car.    |   non    | CRC32 du `prefix_pubid+secret` — `crcChunk()` (`apiKeyFormat.ts:63`)                               |
@@ -268,7 +268,7 @@ dépendance ni d'une variation de version Node (`crc32()`, `apiKeyFormat.ts:53`)
 
 Avant même de parser, le firewall doit savoir **quel** authenticator prend la main. C'est
 `looksLikeApiKey()` (`apiKeyFormat.ts:117`) : un simple `startsWith("<prefix>_")`, appelé par
-`ApiKeyAuthenticator.supports()` (`ApiKeyAuthenticator.ts:68`). C'est ce qui rend la cohabitation
+`ApiKeyAuthenticator.supports()` (`ApiKeyAuthenticator.ts:75`). C'est ce qui rend la cohabitation
 `["apikey", "jwt"]` possible dans une même zone — un JWT a la structure `a.b.c`, il ne commence
 jamais par le préfixe.
 
@@ -276,24 +276,24 @@ 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:292`).
+   `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:113`).
+   `#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:147`).
+6. **Écriture** — le `record` de `kind:"pat"` posé au store par `store.put()` (`apiKeys.ts:177`).
 7. **Audit** — `apikey.created`, catégorie `token`, avec l'**id public** et les scopes, **jamais le
-   secret** (`apiKeys.ts:153`).
+   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:268`) — 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()`
@@ -304,12 +304,12 @@ filtre qui coûte plus cher que la précédente :
 | #   | Contrôle                                | Coût            | Ancrage                                               |
 | --- | --------------------------------------- | --------------- | ----------------------------------------------------- |
 | 1   | Bearer présent + préfixe                | regex           | `readBearerHeader()` (`runtime/bearer.ts:68`)         |
-| 2   | Longueur, charset, **CRC**              | CPU local       | `parseApiKey` (`ApiKeyAuthenticator.ts:99`)           |
-| 3   | Lookup par `secretHash`                 | 1 lecture store | `findByHash` (`ApiKeyAuthenticator.ts:105`)           |
-| 4   | `kind:"pat"`, non révoquée, non expirée | en mémoire      | `ApiKeyAuthenticator.ts:107-114`                      |
-| 5   | Porteur banni ? (`invalidBefore`)       | 1 lecture store | `getInvalidBefore` (`ApiKeyAuthenticator.ts:117`)     |
+| 2   | Longueur, charset, **CRC**              | CPU local       | `parseApiKey` (`ApiKeyAuthenticator.ts:103`)          |
+| 3   | Lookup par `secretHash`                 | 1 lecture store | `findByHash` (`ApiKeyAuthenticator.ts:109`)           |
+| 4   | `kind:"pat"`, non révoquée, non expirée | en mémoire      | `ApiKeyAuthenticator.ts:111-118`                      |
+| 5   | Porteur banni ? (`invalidBefore`)       | 1 lecture store | `getInvalidBefore` (`ApiKeyAuthenticator.ts:121`)     |
 | 6   | Compte actif et non verrouillé          | 1 lecture user  | `#resolveUserOrReject` (`ApiKeyAuthenticator.ts:209`) |
-| 7   | `lastUsedAt` (throttlé)                 | 0 ou 1 écriture | `markUsed` (`ApiKeyAuthenticator.ts:133`)             |
+| 7   | `lastUsedAt` (throttlé)                 | 0 ou 1 écriture | `markUsed` (`ApiKeyAuthenticator.ts:187`)             |
 
 Deux points méritent d'être soulignés parce qu'ils décident du niveau de sécurité réel :
 
@@ -324,13 +324,13 @@ Deux points méritent d'être soulignés parce qu'ils décident du niveau de sé
 
 En cas de succès, le jeton est promu et porte trois attributs consommés en aval : `scopes`,
 `apiKeyId` et `tenantId` (`ApiKeyAuthenticator.ts:138-140`). Le challenge renvoyé sur un 401 de la
-zone est un simple `Bearer` (`challenge()`, `ApiKeyAuthenticator.ts:155`).
+zone est un simple `Bearer` (`challenge()`, `ApiKeyAuthenticator.ts:205`).
 
 ### Câblage — d'où viennent le préfixe et le throttle
 
 L'authenticator n'est jamais instancié à la main : le firewall le construit depuis le registre, en
 lui injectant la config effective — `registerAuthenticatorFactory("apikey")`
-(`authenticatorRegistry.ts:117`), qui lit `prefix` et `lastUsedThrottleS`
+(`authenticatorRegistry.ts:137`), qui lit `prefix` et `lastUsedThrottleS`
 (`authenticatorRegistry.ts:143`). Conséquence pratique : changer `apiKeys.prefix` change **à la
 fois** l'émission et la reconnaissance — les anciennes clés ne sont plus reconnues.
 
@@ -353,13 +353,13 @@ 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:292`).
+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
 > propose aussi les scopes **découverts sur tes routes** (`@RequireScope`) par
 > `collectDeclaredApiScopes()` (`scopeCatalog.ts:29`), agrégés dans l'endpoint `capabilities`
-> (`ApiKeyController.ts:96`). Un formulaire de création qui ne ment pas.
+> (`ApiKeyController.ts:97`). Un formulaire de création qui ne ment pas.
 
 ### Faire tourner une clé sans coupure de service
 
@@ -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:113`) :
+**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.
@@ -376,7 +376,7 @@ soit deux secrets valides sous le même id (ambigu à auditer), soit une coupure
 4. **Puis** révoquer la v1.
 
 Ce qui rend l'étape 3 fiable : `lastUsedAt` est écrit de façon **throttlée**, pas à chaque requête —
-la fenêtre par défaut est de 60 s (`lastUsedThrottleS`, `config.ts:746`). Attends donc une minute
+la fenêtre par défaut est de 60 s (`lastUsedThrottleS`, `config.ts:752`). Attends donc une minute
 avant de conclure qu'une clé « ne sert plus ».
 
 ### Révoquer une clé qui a fuité
@@ -388,25 +388,25 @@ 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:247`) |
-| Un admin   | `POST /nodefony/security/api/apikeys/{id}/revoke` | n'importe quelle clé   | `revokeAnyPat()` (`apiKeys.ts:201`)     |
+| 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:107-114`).
+l'authenticator lit `revokedAt` avant toute autre décision (`ApiKeyAuthenticator.ts:111-118`).
 Le banc d'intégration le prouve bout en bout : 200 avant, 401 après
-(`apikey-flow.test.ts:149-157`).
+(`apikey-flow.test.ts:182-191`).
 
 Une propriété de sécurité facile à manquer : si la clé n'existe pas **ou** appartient à quelqu'un
 d'autre, le porteur reçoit un **404 indiscernable**, jamais un 403 (`ApiKeyController.ts:139-142`).
 Un 403 dirait « cette clé existe, mais pas à toi » — assez pour énumérer les identifiants des
-autres. Le banc couvre explicitement cet IDOR (`apikey-flow.test.ts:176`).
+autres. Le banc couvre explicitement cet IDOR (`apikey-flow.test.ts:209`).
 
 > [!WARNING]
 > Si tu dois couper **toutes** les clés d'un porteur d'un coup (compte compromis, départ), ne les
 > révoque pas une par une : pose le seuil `invalidBefore` du porteur
 > (`revokeAllForSubject`, `ITokenStore.ts:261`). L'authenticator rejette alors toute clé créée avant
 > ce seuil : `getInvalidBefore` est comparé au `createdAt` du record
-> (`ApiKeyAuthenticator.ts:117-120`) — y compris pour les clés que tu aurais oubliées.
+> (`ApiKeyAuthenticator.ts:121-124`) — y compris pour les clés que tu aurais oubliées.
 
 ### Auditer qui a utilisé quoi
 
@@ -417,9 +417,9 @@ 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:208`). 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:109`).
+   (`KEYS_MAX_LIMIT`, `SecurityAdminApi.ts:114`).
 
    Le tri n'est accepté que sur les champs que le backend branché **déclare** savoir trier
    (`sortableFields()`, `apiKeys.ts:102` → `ITokenStore.sortableFields`) : `createdAt`, `name`,
@@ -430,30 +430,33 @@ Trois sources, et il faut connaître les limites de chacune :
    du vocabulaire : le placement des valeurs absentes diffère d'un moteur à l'autre, et un tri dont
    l'ordre dépend de la base configurée ne vaut pas mieux qu'un tri absent.
 
-2. **Le journal** — les événements d'audit `apikey.created` (`apiKeys.ts:153`) et `apikey.revoked`
-   (`apiKeys.ts:212` côté admin, `apiKeys.ts:255` côté porteur), catégorie `token`. La révocation
+2. **Le journal** — les événements d'audit `apikey.created` (`apiKeys.ts:183-189`) et `apikey.revoked`
+   (`apiKeys.ts:268-271` côté admin, `apiKeys.ts:311-313` côté porteur), catégorie `token`. La révocation
    admin trace **l'acteur ET le porteur cible** — voir [audit](./audit.md).
-3. **Le dernier usage** — `lastUsedAt` sur chaque clé.
+3. **Le dernier usage** — `lastUsedAt`, avec l'IP et l'agent de ce dernier appel
+   (`lastUsedIp`, `lastUsedUserAgent`, `ITokenStore.ts:135`), écrits ensemble par `markUsed`
+   (`ApiKeyAuthenticator.ts:187`). L'IP est lue par l'accesseur du contexte, qui tient compte des
+   proxys de confiance ; si elle ne peut pas être lue, le champ reste vide sans faire échouer
+   l'authentification.
 
-Ce que tu **n'auras pas** : un journal par requête. `markUsed` est appelé avec le seul horodatage
-(`ApiKeyAuthenticator.ts:133`) ; les champs `lastUsedIp` et `lastUsedUserAgent` du record
-(`ITokenStore.ts:135`) restent donc à `null` — ce sont des **emplacements réservés**, pas des
-données remplies. Pour de la traçabilité par appel, c'est le journal d'audit applicatif qu'il faut
-alimenter, pas le store de jetons.
+Ce que tu **n'auras pas** : un journal par requête. Le dernier usage est **écrasé** à chaque
+écriture, et cette écriture est throttlée (`lastUsedThrottleS`) : entre deux écritures, les appels
+ne laissent aucune trace dans le store. Pour de la traçabilité par appel, c'est le journal d'audit
+applicatif qu'il faut alimenter, pas le store de jetons.
 
 ## ⚙️ Configuration
 
-Table dérivée du schéma Zod `apiKeysSchema` (`config.ts:727`), branché à la racine de la config du
-module (`config.ts:727`). Toutes les valeurs ci-dessous sont les **défauts réels**.
+Table dérivée du schéma Zod `apiKeysSchema` (`config.ts:733`), branché à la racine de la config du
+module (`config.ts:733`). Toutes les valeurs ci-dessous sont les **défauts réels**.
 
 | Option              | Type             | Défaut | Effet                                                                                  |
 | ------------------- | ---------------- | ------ | -------------------------------------------------------------------------------------- |
-| `enabled`           | boolean          | `true` | Coupe l'émission ET le listing (l'authenticator reste déclarable) (`config.ts:533`)    |
-| `prefix`            | string ≤ 12      | `"nf"` | Marque des clés ; minuscules/chiffres — discrimine du JWT (`config.ts:730`)            |
-| `defaultExpiryDays` | number \| null   | `90`   | Expiration appliquée si l'appelant n'en donne pas ; `null` = jamais (`config.ts:739`)  |
-| `lastUsedThrottleS` | number (s)       | `60`   | Coalescence d'écriture de `lastUsedAt` ; `0` = à chaque usage (`config.ts:746`)        |
-| `maxPerSubject`     | number > 0       | `100`  | Plafond de clés **actives** par porteur ; au-delà → 409 (`config.ts:755`)              |
-| `allowedScopes`     | string[] \| null | `null` | Catalogue fermé à la création ; `null` = tout scope non vide accepté (`config.ts:764`) |
+| `enabled`           | boolean          | `true` | Coupe l'émission ET le listing (l'authenticator reste déclarable) (`config.ts:735`)    |
+| `prefix`            | string ≤ 12      | `"nf"` | Marque des clés ; minuscules/chiffres — discrimine du JWT (`config.ts:736`)            |
+| `defaultExpiryDays` | number \| null   | `90`   | Expiration appliquée si l'appelant n'en donne pas ; `null` = jamais (`config.ts:745`)  |
+| `lastUsedThrottleS` | number (s)       | `60`   | Coalescence d'écriture de `lastUsedAt` ; `0` = à chaque usage (`config.ts:752`)        |
+| `maxPerSubject`     | number > 0       | `100`  | Plafond de clés **actives** par porteur ; au-delà → 409 (`config.ts:761`)              |
+| `allowedScopes`     | string[] \| null | `null` | Catalogue fermé à la création ; `null` = tout scope non vide accepté (`config.ts:770`) |
 
 Deux réglages méritent une décision consciente :
 
@@ -468,15 +471,15 @@ Deux réglages méritent une décision consciente :
 ### Les endpoints — deux portées, jamais mélangées
 
 **Console « mes clés »** (le porteur gère les siennes) — montées par `mountApiKeyRoutes()`
-(`ApiKeyController.ts:191`) **seulement si** le service `apiKeys` existe (`framework/index.ts:468`) ;
+(`ApiKeyController.ts:192`) **seulement si** le service `apiKeys` existe (`framework/index.ts:468`) ;
 sinon 404, zéro surface. Aucune n'est `bypassFirewall` : la zone data plane exige la session BFF.
 
 | Méthode  | Chemin                                     | Rôle                                              | Ancrage                                     |
 | -------- | ------------------------------------------ | ------------------------------------------------- | ------------------------------------------- |
-| `POST`   | `/nodefony/security/api/keys`              | Émission → **201** + `token` clair (1×)           | `create()` (`ApiKeyController.ts:65`)       |
-| `GET`    | `/nodefony/security/api/keys`              | Mes clés, sans secret                             | `list()` (`ApiKeyController.ts:113`)        |
-| `GET`    | `/nodefony/security/api/keys/capabilities` | Plafond, scopes proposés, préfixe, durée          | `capabilities()` (`ApiKeyController.ts:96`) |
-| `DELETE` | `/nodefony/security/api/keys/{id}`         | Révoque **ma** clé ; 404 sinon (anti-énumération) | `revoke()` (`ApiKeyController.ts:126`)      |
+| `POST`   | `/nodefony/security/api/keys`              | Émission → **201** + `token` clair (1×)           | `create()` (`ApiKeyController.ts:66`)       |
+| `GET`    | `/nodefony/security/api/keys`              | Mes clés, sans secret                             | `list()` (`ApiKeyController.ts:114`)        |
+| `GET`    | `/nodefony/security/api/keys/capabilities` | Plafond, scopes proposés, préfixe, durée          | `capabilities()` (`ApiKeyController.ts:97`) |
+| `DELETE` | `/nodefony/security/api/keys/{id}`         | Révoque **ma** clé ; 404 sinon (anti-énumération) | `revoke()` (`ApiKeyController.ts:127`)      |
 
 **Administration** (gouvernance, réponse à incident) — data plane `SecurityAdminApi`, RBAC
 `ROLE_NODEFONY_ADMIN` :
@@ -490,7 +493,7 @@ sinon 404, zéro surface. Aucune n'est `bypassFirewall` : la zone data plane exi
 Les deux espaces de chemins sont **disjoints** (`keys` vs `apikeys`) — aucune collision, et une
 console d'admin ne peut pas atterrir par erreur sur l'endpoint personnel.
 
-Codes d'erreur mappés par duck-typing sur `code` (`#renderApiKeyError()`, `ApiKeyController.ts:164`) :
+Codes d'erreur mappés par duck-typing sur `code` (`#renderApiKeyError()`, `ApiKeyController.ts:165`) :
 **400** validation (nom, scope, durée), **409** plafond atteint, **503** clés indisponibles (store
 absent ou `enabled:false`).
 
@@ -514,8 +517,8 @@ import type {
 ```
 
 Les contrats vivent dans `IApiKey.ts` : `IApiKeyView` (`IApiKey.ts:6`), `IApiKeyCreated`
-(`IApiKey.ts:36`), `IApiKeyCapabilities` (`IApiKey.ts:47`), `ICreateApiKeyOptions`
-(`IApiKey.ts:61`). Les signatures détaillées vivent dans le graphe TSDoc (`.ai/symbols.json`) —
+(`IApiKey.ts:44`), `IApiKeyCapabilities` (`IApiKey.ts:55`), `ICreateApiKeyOptions`
+(`IApiKey.ts:69`). Les signatures détaillées vivent dans le graphe TSDoc (`.ai/symbols.json`) —
 cette page explique l'usage, elle ne recopie pas les prototypes.
 
 ## 🧑‍⚖️ Scopes — ce que la clé a le droit de faire
@@ -588,12 +591,12 @@ révocation ne traverse pas. Le détail de la résolution, des avertissements et
 | Schéma `Bearer` (transport)       | RFC 6750 §2.1                          | `readBearerHeader()` (`runtime/bearer.ts:68`)          |
 | `invalid_token` → 401 + challenge | RFC 6750 §3.1 · RFC 7235               | `challenge()` (`ApiKeyAuthenticator.ts:205`)           |
 | Secret **jamais** stocké en clair | OWASP ASVS (secret storage)            | `hashApiKey()` (`apiKeyFormat.ts:70`)                  |
-| Secret montré une seule fois      | Pratique « shown once »                | `IApiKeyCreated.token` (`IApiKey.ts:37`)               |
+| Secret montré une seule fois      | Pratique « shown once »                | `IApiKeyCreated.token` (`IApiKey.ts:46`)               |
 | Anti-énumération des ressources   | OWASP API1:2023 (BOLA/IDOR)            | 404 indiscernable (`ApiKeyController.ts:139-142`)      |
 | 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:107-114`) |
+| 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:113`)                     |
+| Plafond de ressources par acteur  | OWASP API4:2023 (Resource Consumption) | `maxPerSubject` (`apiKeys.ts:48`)                      |
 
 ## ⚡ Performance & mémoire
 
@@ -611,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`
@@ -645,14 +648,13 @@ pas masqué à l'affichage. Voir aussi l'écran **Audit** pour les événements
 | 503 « API keys unavailable »                           | Store non provisionné (`TokenService` absent/désactivé) (`apiKeys.ts:330`)                     | Vérifier `jwt`/`tokenStore` — le `TokenService` pose le store          |
 | 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:113`)                                         | Révoquer les clés inutilisées ou relever `maxPerSubject`               |
-| 400 « scope not allowed »                              | Scope hors du catalogue `allowedScopes` (`apiKeys.ts:292`)                                     | Ajouter le scope au catalogue, ou corriger la demande                  |
+| 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: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:117-120`)      | Réactiver le compte, ou réémettre après le bannissement                |
+| 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                |
 | 404 en révoquant la clé d'un autre porteur             | Anti-énumération volontaire, jamais 403 (`ApiKeyController.ts:139-142`)                        | Attendu — passer par l'endpoint d'administration                       |
 | `lastUsedAt` qui ne bouge pas tout de suite            | Écriture throttlée, 60 s par défaut (`ApiKeyAuthenticator.ts:127-134`)                         | Attendre la fenêtre, ou `lastUsedThrottleS: 0` (coût : 1 écriture/req) |
-| `lastUsedIp` / `lastUsedUserAgent` toujours vides      | `markUsed` n'envoie que l'horodatage (`ApiKeyAuthenticator.ts:133`)                            | Emplacements réservés — tracer par le journal d'audit applicatif       |
 | Révocation sans effet entre pods                       | Store `memory` en production (per-pod)                                                         | Store durable partagé — voir [tokens](./tokens.md)                     |
 | Listing d'admin sans `total` sur Redis                 | Comptage exact refusé (O(N)) — pagination par curseur                                          | Attendu : capacité réduite annoncée, paginer par `nextCursor`          |