@nodefony/security 10.0.0-beta.2 → 10.0.0-beta.4

package/docs/obtenir-un-jeton.md

@@ -5,7 +5,7 @@ lang: fr
 module: "@nodefony/security"
 topic: obtenir-un-jeton
 coverageModule: security
-coverageFiles: "security-token,tokenService,secretFile"
+coverageFiles: "security-mcp-token,tokenService,secretFile"
 section: "Sécurité"
 audience: [developer, devops]
 tags:
@@ -33,7 +33,7 @@ source: "src/packages/@nodefony/security/docs/obtenir-un-jeton.md"
 > l'application répond un couple access/refresh. Cette page décrit l'autre voie, celle dont un
 > client MCP ou un script d'exploitation a besoin : **l'application signe elle-même un jeton, en
 > ligne de commande**, sans qu'aucun serveur n'écoute et sans qu'aucun mot de passe ne transite.
-> Ancré sur `src/packages/@nodefony/security/nodefony/command/security-token.ts`.
+> Ancré sur `src/packages/@nodefony/security/nodefony/command/security-mcp-token.ts`.
 
 📍 [Documentation](../../../../../docs/index.md) › [Sécurité](index.md) › **Obtenir un jeton**
 
@@ -43,7 +43,7 @@ Trois questions, et une seule commande y répond.
 
 ```mermaid
 flowchart LR
-  A["nodefony security:token"] --> B{"L'application possède<br/>sa clé de signature"}
+  A["nodefony security:mcp:token"] --> B{"L'application possède<br/>sa clé de signature"}
   B --> C["Jeton signé pour<br/>UNE audience"]
   C --> D["--write : posé où<br/>l'agent le lit"]
   C --> E["--json : capturé<br/>par un script"]
@@ -51,11 +51,11 @@ flowchart LR
 ```
 
 **Aucun serveur n'est en marche.** La commande démarre le noyau jusqu'à `onReady` — services prêts,
-aucune écoute réseau (`security-token.ts:36`). C'est ce qui la rend utilisable quand l'application
+aucune écoute réseau (`security-mcp-token.ts#options`). C'est ce qui la rend utilisable quand l'application
 ne tourne pas, en intégration continue, ou dans un conteneur d'amorçage.
 
 **Le jeton vise une porte, et une seule.** L'audience est celle de la porte visée — la porte MCP par
-défaut, `/nodefony/mcp` (`src/nodefony/src/mcp/protocol.ts:95`). Un jeton d'une autre audience est
+défaut, `/nodefony/mcp` (`src/nodefony/src/cli/aiMcpReport.ts#MCP_ENDPOINT_PATH`). Un jeton d'une autre audience est
 refusé, et c'est toute la raison d'être de la liaison d'audience
 ([RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html)).
 
@@ -69,7 +69,7 @@ refusé, et c'est toute la raison d'être de la liaison d'audience
 - **Audience** — la ressource pour laquelle un jeton est valable. Déclarée par l'émetteur ; un
   porteur ne choisit pas la sienne.
 - **Scope** — un pouvoir nommé, porté par le jeton. `admin:read` lit, `admin:write` mute
-  (`src/nodefony/src/kernel/adminPlane/adminCaller.ts:53`).
+  (`src/nodefony/src/kernel/adminPlane/adminCaller.ts#ADMIN_SCOPE_READ`).
 
 ## Qu'est-ce que ça résout — la faille du `curl` avec mot de passe
 
@@ -85,13 +85,13 @@ pas de mot de passe, pas de réseau — et rien à effacer d'un historique.
 
 ```bash
 # 1) Le jeton, pour la porte MCP de cette application
-npx nodefony security:token
+npx nodefony security:mcp:token
 
 # 2) Le poser là où l'agent le lit — jamais dans un fichier suivi par git
-npx nodefony security:token --write
+npx nodefony security:mcp:token --write
 
 # 3) Pour un script : la sortie machine
-npx nodefony security:token --json
+npx nodefony security:mcp:token --json
 # {
 #   "access_token": "eyJ…",
 #   "resource": "http://localhost:5151/nodefony/mcp",
@@ -125,25 +125,32 @@ Puis `npm run build` — le runtime lit le `dist`, pas la source.
 
 ### Les options, et ce que chacune décide
 
-| Option                 | Défaut                        | Ce qu'elle change                                        |
-| ---------------------- | ----------------------------- | -------------------------------------------------------- |
-| `[identifier]`         | `admin`                       | le compte porteur du jeton                               |
-| `-s, --scope <liste>`  | `admin:read`                  | les pouvoirs demandés — ajouter `admin:write` pour muter |
-| `-r, --resource <uri>` | la porte MCP de l'application | viser une **autre** audience                             |
-| `-a, --agent <noms>`   | ceux détectés                 | quels agents servir — `none` pour aucun                  |
-| `-t, --ttl <minutes>`  | celle de la config (15 min)   | la durée de validité, **bornée à 30 jours**              |
-| `-w, --write`          | proposé en terminal           | poser `NF_MCP_TOKEN` chez les agents présents            |
-| `-j, --json`           | —                             | sortie machine, sans invite                              |
+| Option                 | Défaut                                       | Ce qu'elle change                                        |
+| ---------------------- | -------------------------------------------- | -------------------------------------------------------- |
+| `[identifier]`         | `admin`                                      | le compte porteur du jeton                               |
+| `-s, --scope <liste>`  | `admin:read`                                 | les pouvoirs demandés — ajouter `admin:write` pour muter |
+| `-r, --resource <uri>` | la porte MCP de l'application                | viser une **autre** audience                             |
+| `-a, --agent <noms>`   | ceux détectés                                | quels agents servir — `none` pour aucun                  |
+| `-t, --ttl <minutes>`  | 8 h avec `--write`, sinon la config (15 min) | la durée de validité, **bornée à 30 jours**              |
+| `-w, --write`          | proposé en terminal                          | poser `NF_MCP_TOKEN` chez les agents présents            |
+| `-j, --json`           | —                                            | sortie machine, sans invite                              |
 
 Le plafond de `--ttl` n'est pas décoratif : un jeton posé dans un fichier **est une clé**, et une
-clé se remplace (`security-token.ts:67-84`).
+clé se remplace (`security-mcp-token.ts#ttlSeconds`).
+
+**Posé chez un agent, le jeton vit 8 h par défaut** (`security-mcp-token.ts#tokenTtlSeconds`). L'en-tête d'un
+agent est figé : rien ne le rafraîchit, et le défaut de la configuration (15 min, taillé pour un
+client d'API qui renouvelle son jeton) produisait un 401 au bout d'un quart d'heure. Huit heures
+couvrent une journée de travail et bornent une fuite à quelques heures ; `--ttl` explicite
+l'emporte toujours, et le défaut global `jwt.accessTtlS` ne bouge pas. La commande affiche l'heure
+d'**expiration** (`expires_at` en `--json`) : c'est elle qui explique le 401 du lendemain.
 
 ### Où `--write` pose la valeur
 
-La variable est `NF_MCP_TOKEN` (`src/nodefony/src/cli/aiMcpReport.ts:32`). La commande ne sert que
+La variable est `NF_MCP_TOKEN` (`src/nodefony/src/cli/aiMcpReport.ts#MCP_TOKEN_ENV`). La commande ne sert que
 les agents dont la présence est **constatée** dans le projet — on ne crée pas la configuration d'un
 outil que personne n'utilise ici. La table des cibles vit au cœur
-(`src/nodefony/src/cli/agentTargets.ts:280`) : Claude, Gemini, Vibe, Codex.
+(`src/nodefony/src/cli/agentTargets.ts#AGENT_TARGETS`) : Claude, Gemini, Vibe, Codex.
 
 Deux garanties qui ne se négocient pas :
 
@@ -170,38 +177,128 @@ codex mcp add nodefony --url http://localhost:5151/nodefony/mcp \
 Pour câbler `.mcp.json` d'un seul geste : `npx nodefony ai:mcp --auth`. La déclaration de la porte
 appartient à [devkit](../../devkit/docs/index.md) ; cette page ne fait qu'émettre le porteur.
 
+## 🔐 Ce que la porte vérifie — un jeton de cette application face à une ressource
+
+Une ressource protégée — une porte MCP d'application (`nodefony create controller <nom> --kind mcp
+--expose oauth`), ou la porte de développement quand elle déclare un serveur d'autorisation — ne
+vérifie pas le jeton elle-même : elle le confie au service `accessTokenVerifier`, avec **son** URI
+comme audience. Ce service reconnaît **toujours** l'émetteur de l'application, dès que sa capacité
+JWT est active (`security.jwt.enabled`, vrai par défaut), **sans rien déclarer** dans
+`resourceServer.issuers` (`src/packages/@nodefony/security/nodefony/service/accessTokenVerifier.ts#AccessTokenVerifierService.#build`).
+Une application qui signe un jeton pour sa propre porte peut donc l'y présenter.
+
+**L'aiguillage se fait sur l'émetteur revendiqué, comparé EXACTEMENT** à `security.jwt.issuer`
+(`accessTokenVerifier.ts#AccessTokenVerifierService.#build`). Égal : le jeton est jugé par les règles de l'authentificateur `jwt`,
+par la même fonction (`src/packages/@nodefony/security/nodefony/src/authenticator/JwtAuthenticator.ts#JwtAuthenticator.#verify`).
+Différent : il est jugé par la liste fermée des émetteurs tiers (Keycloak…, voir
+[Accepter les jetons d'un émetteur tiers](external-jwt.md)) — inconnu d'elle, il est refusé sans
+aucune requête sortante.
+
+Un jeton de l'application n'est accepté que si **chaque** contrôle passe, dans cet ordre :
+
+| #   | Contrôle                                                    | Refusé, par exemple                                                                   | Norme                                                                   |
+| --- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| 1   | signature par une clé du jeu LOCAL, algorithme `EdDSA` seul | `alg: none`, `HS256` signé avec la clé publique, clé d'un tiers sous le même `kid`    | [RFC 8725](https://www.rfc-editor.org/rfc/rfc8725.html) §3.1, §3.5      |
+| 2   | `iss` = l'émetteur de l'application                         | `https://app.example/` quand l'émetteur est `https://app.example` (aiguillé ailleurs) | RFC 8725 §3.8                                                           |
+| 3   | `aud` contient l'URI de la porte                            | un jeton émis pour une AUTRE porte de la même application                             | [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html), RFC 8725 §3.9  |
+| 4   | `typ: at+jwt`                                               | un jeton de rafraîchissement présenté comme jeton d'accès, un `typ` absent            | [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068.html), RFC 8725 §3.11 |
+| 5   | `exp` et `nbf`                                              | expiré, pas encore valide                                                             | [RFC 7519](https://www.rfc-editor.org/rfc/rfc7519.html) §4.1.4-5        |
+| 6   | `sub` et `jti` présents                                     | un jeton sans identifiant — donc impossible à révoquer                                |                                                                         |
+| 7   | `jti` absent de la liste de révocation                      | un jeton révoqué individuellement                                                     |                                                                         |
+| 8   | émis APRÈS le seuil `invalidBefore` du compte               | tout jeton antérieur à un changement de mot de passe ou à une déconnexion globale     |                                                                         |
+| 9   | le compte existe, est actif et n'est pas verrouillé         | le jeton d'un compte désactivé, verrouillé ou supprimé                                | RFC 8725 §3.10                                                          |
+
+Les contrôles 7 et 8 viennent **avant** la lecture du compte : un jeton révoqué est refusé sans
+interroger l'annuaire (`JwtAuthenticator.ts#JwtAuthenticator.#verify`). Une PANNE de la liste de révocation est un
+`503` ; une panne de l'annuaire, elle, se lit comme un compte absent — `401`. Dans les deux cas le
+jeton n'est jamais servi : c'est une limite de diagnostic, pas d'accès. Le jeton accepté donne à la porte un principal :
+son sujet (`sub`, l'identifiant du compte local) et ses scopes, qui décident des outils servis.
+
+| Verdict du vérificateur                                        | Réponse de la porte                                            |
+| -------------------------------------------------------------- | -------------------------------------------------------------- |
+| principal                                                      | servi — les outils réservés que ses scopes ouvrent en plus     |
+| refus (l'un des contrôles)                                     | `401` + `WWW-Authenticate`, qui désigne le document RFC 9728   |
+| invérifiable (clés, liste de révocation ou annuaire absents)   | `503`, et le journal crie — jamais un jeton accepté par défaut |
+| aucun vérificateur (capacité JWT coupée, aucun émetteur tiers) | `503`                                                          |
+
+**Révoquer un jeton émis**, c'est révoquer le compte qui le porte : `npx nodefony
+security:user:password <compte>` pose le seuil du contrôle 8 — le prochain appel reçoit `401`, avant
+l'expiration du jeton. C'est éprouvé sur un serveur réel par le banc de vérité du générateur
+(étape « la porte MCP protégée s'ouvre… et se referme révoquée »).
+
+**Ce que la règle n'élargit pas.** Aucun jeton nouveau ne devient valide : l'émetteur ne signe que
+pour les audiences de `jwt.audiences`, et l'audience reste exigée à chaque porte. La zone de
+pare-feu `external-jwt` ne prend, elle, que les jetons des émetteurs qu'ELLE déclare : la règle ne
+lui ouvre rien. Et si `resourceServer.issuers` est mal configurée, **aucun** vérificateur n'est
+posé, jetons de l'application compris — une configuration fausse ne se sert pas à moitié
+(`accessTokenVerifier.ts#AccessTokenVerifierService.#build`).
+
+> ⚠️ **En production, pose `NF_JWT_ISSUER`.** Sans elle, l'émetteur vaut `"nodefony"`, qui n'est
+> pas une URL : les jetons se vérifient, mais l'application ne publie ni ses clés ni ses métadonnées,
+> et une porte qui annonce `https://…` comme serveur d'autorisation désigne une adresse dont
+> l'émetteur réel n'est pas celui des jetons.
+
+Pour une porte d'application, l'audience à déclarer est l'URI publique de la porte. Dans une
+application générée, écris-la **sur place** dans `jwt.audiences` de `nodefony/config/security.ts` :
+
+```typescript
+audiences: ctx.isProd
+  ? []
+  : [
+      // … les audiences du gabarit
+      `${publicBaseUrl(ctx.env)}/api/mcp`,
+    ],
+```
+
+⚠️ N'y importe pas la fonction `…GateResource` du fichier de la porte : ce fichier importe
+`security.ts`, et le cycle ferait lire `publicBaseUrl` avant sa définition — `ReferenceError` au
+démarrage.
+
 ## 🔄 Renouveler — c'est réémettre, pas rafraîchir
 
 Il n'y a pas de refresh token ici : ce jeton est signé hors bande, pour une porte, avec une durée
-courte. Le renouveler, c'est **relancer la commande**. Et comme `--write` ne remplace jamais une
-valeur en place, une rotation se demande :
+courte. Le renouveler, c'est **relancer la commande** : `--write` **remplace** le jeton chez les
+agents qui le portent déjà, sans reposer de question, et ne câble aucun agent nouveau sans le
+proposer (`agentTargets.ts#poseVariable`). Puis relancer l'agent, qui lit sa configuration au
+démarrage.
 
 ```bash
-# 1) retirer l'ancienne valeur là où elle est posée (le fichier est nommé par la commande)
-# 2) réémettre
-npx nodefony security:token --write --ttl 1440
+npx nodefony security:mcp:token --write --ttl 1440
 ```
 
+Un jeton expiré ne casse rien de visible chez l'agent : la porte le sert en **anonyme** et retient
+les outils réservés. `nodefony doctor` le signale dans sa famille « Fraîcheur du build », avec
+cette commande pour geste (`freshness.ts#checkAgentTokens`) — pour les fichiers du projet
+seulement : le dossier de l'utilisateur est partagé entre applications, et `nodefony ai:mcp` en
+rend compte.
+
 Le flux de rotation **avec détection de rejeu** est celui des refresh tokens de la porte HTTP — il
 est décrit dans [tokens](tokens.md), pas ici.
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
-| Symptôme                                                              | Cause                                                                                                                                    | Correction                                                                                     |
-| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `impossible d'émettre un jeton pour cette porte ici`                  | **en développement** : l'audience n'est pas déclarée à l'émetteur — c'est une liste blanche, pas un défaut ouvert                        | `use("@nodefony/security", { jwt: { audiences: ["<la porte>"] } })`, puis `npm run build`      |
-| Le même message, mais l'environnement affiché n'est pas `development` | la porte MCP est servie par un module `policy: "dev"` : **elle n'existe pas** dans cet environnement                                     | `NODE_ENV=development npx nodefony security:token`, ou viser une autre porte avec `--resource` |
-| Le jeton est émis, mais avec **moins** de scopes que demandé          | l'émetteur retire ceux que ce porteur ne peut pas obtenir, et il le dit ([RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) §3.3) | lire le champ `scopes` de la sortie — c'est celui qui fait foi (`security-token.ts:494`)       |
-| L'agent reçoit `401` alors que le jeton vient d'être posé             | la valeur a été écrite dans un dossier que **cet** agent ne lit pas                                                                      | `--agent <nom>` pour viser explicitement, ou l'`export` dans le shell qui lance l'agent        |
-| `--write` ne fait rien et n'écrit aucun fichier                       | aucun agent n'est **constaté** dans ce projet                                                                                            | la commande liste alors les emplacements connus et donne la ligne d'`export`                   |
+| Symptôme                                                              | Cause                                                                                                                                    | Correction                                                                                                         |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `impossible d'émettre un jeton pour cette porte ici`                  | **en développement** : l'audience n'est pas déclarée à l'émetteur — c'est une liste blanche, pas un défaut ouvert                        | `use("@nodefony/security", { jwt: { audiences: ["<la porte>"] } })`, puis `npm run build`                          |
+| Le même message, mais l'environnement affiché n'est pas `development` | la porte MCP est servie par un module `policy: "dev"` : **elle n'existe pas** dans cet environnement                                     | `NODE_ENV=development npx nodefony security:mcp:token`, ou viser une autre porte avec `--resource`                 |
+| Le jeton est émis, mais avec **moins** de scopes que demandé          | l'émetteur retire ceux que ce porteur ne peut pas obtenir, et il le dit ([RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) §3.3) | lire le champ `scopes` de la sortie — c'est celui qui fait foi (`security-mcp-token.ts#SecurityMcpToken.generate`) |
+| L'agent reçoit `401` alors que le jeton vient d'être posé             | la valeur a été écrite dans un dossier que **cet** agent ne lit pas                                                                      | `--agent <nom>` pour viser explicitement, ou l'`export` dans le shell qui lance l'agent                            |
+| `--write` ne fait rien et n'écrit aucun fichier                       | aucun agent n'est **constaté** dans ce projet                                                                                            | la commande liste alors les emplacements connus et donne la ligne d'`export`                                       |
 
 > 🔴 **Le premier réflexe est faux.** Devant un refus, on cherche un serveur éteint — la commande
 > n'en utilise aucun. Le message écarte cette fausse piste dès sa deuxième ligne
-> (`security-token.ts:456-484`) ; il a lui-même été corrigé pour cesser d'accuser une cause unique
+> (`security-mcp-token.ts#SecurityMcpToken.generate`) ; il a lui-même été corrigé pour cesser d'accuser une cause unique
 > qu'il ne constatait pas.
 
 ## 🧪 Tests & couverture
 
+- **unit** : `accessTokenVerifier.attack.test.ts` éprouve la vérification d'un jeton de
+  l'application face à une ressource — chacun des neuf contrôles ci-dessus par un jeton qui le viole,
+  l'aiguillage entre émetteur local et tiers, les entrées hostiles, la configuration fausse — et
+  chacune de ses règles a été vue tomber en la débranchant ;
+- **serveur réel** : le banc de vérité du générateur (`verify-generated.mjs`) ouvre la porte
+  d'une application engendrée avec `security:mcp:token`, la voit refuser un jeton d'une autre audience,
+  puis refuser le premier jeton après `security:user:password` ;
 - **unit** : `securityCommands.test.ts` couvre les deux règles pures de la commande — un jeton
   **mort-né** doit s'annoncer avant d'être copié, et `--ttl` doit s'écrire en minutes, refuser une
   valeur aberrante et se borner à 30 jours (`ttlSeconds` est exportée pour cela).