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

package/skills/nodefony-devops/references/variables.md

@@ -5,7 +5,7 @@
 ## 1. La commande qui répond, et à laquelle rien ne ment
 
 ```bash
-npx nodefony env            # la cascade des .env, la valeur EFFECTIVE de chaque variable, et sa PROVENANCE
+npx nodefony env            # la valeur EFFECTIVE de chaque variable, et sa PROVENANCE (.env ou process)
 npx nodefony env --json     # le même rapport, pour un script
 ```
 
@@ -19,8 +19,11 @@ npx nodefony inspect schema <module>        # les clés qui EXISTENT, leur type,
 npx nodefony doctor --env production        # ce qui manquerait là-bas, depuis ici
 ```
 
-> 🔴 **`inspect schema` avant d'écrire une clé.** Une clé inconnue n'est pas refusée : elle est
-> **retirée en silence** à la validation. Tu poses le réglage, rien ne change, rien ne le dit.
+> 🔴 **`inspect schema` avant d'écrire une clé.** Une clé inconnue **arrête le démarrage**
+> (code 78) en la nommant — y compris une clé qu'une version du framework a retirée, que tu
+> découvres alors au premier déploiement après un `npm update`. Ce qui reste muet, c'est une
+> **variable** mal orthographiée (`NF_PROT` au lieu de `NF_PORT`) : inconnue, donc ignorée, et
+> seul `npx nodefony env` la montre.
 
 ## 2. Deux grammaires, et elles ne font pas la même chose
 
@@ -54,10 +57,33 @@ booléen, un nombre devient un nombre, `[…]` et `{…}` sont lus en JSON, une
 devient un tableau, le reste reste une chaîne. C'est ce qui évite le piège classique où la chaîne
 `"false"` est convertie en booléen **vrai**.
 
+### `NF_<MODULE>_<RÉGLAGE>` — les noms courts des modules
+
+Un module déclare sur un champ de son schéma le nom court qui le règle (`NF_REDIS_HOST`,
+`NF_REALTIME_DRIVER`…). `npx nodefony env --example` les écrit dans `.env.example`, une section
+par module. Trois règles, toutes au démarrage :
+
+- La valeur est **validée par le schéma** : `NF_REDIS_PORT=abc` arrête le démarrage (78) en
+  nommant la VARIABLE, pas le seul champ.
+- **Nom court ET `NF__…` sur le même champ** : refus du démarrage en production (78) ; en
+  développement, `NF__…` l'emporte avec un avertissement qui nomme les deux.
+- Chaque nom court accepte `<NOM>_FILE` ; une variable vide vaut absente.
+
+### Lire la notice `.env.example`
+
+Chaque variable y porte ses métadonnées : `@required` / `@optional`, `@required=forEnv(production)`,
+`@requiredWhen="…"` (exigée sous condition — `NF_JWT_KEYSET` : « en production, si l'application
+émet des jetons »), `@sensitive`, `@default`, et **`@placement`**, qui dit où la poser en
+production : `platform` (variables du déploiement), `secrets` (gestionnaire de secrets, ou
+`<NOM>_FILE`), `workstation` (le poste seulement — ne la pose pas en production).
+`npm run env:check` échoue (78) quand la notice a dérivé d'`env.ts`.
+
 ## 3. Le suffixe `_FILE` — les secrets montés
 
-**Toute** variable du catalogue accepte un `_FILE`. Le contenu du fichier est lu, retour à la ligne
-final retiré.
+Les variables du catalogue acceptent un `_FILE`, **URL d'infrastructure comprises**
+(`NF_DATABASE_URL_FILE`, `NF_REDIS_URL_FILE`, et leurs alias de plateforme). Le contenu du fichier
+est lu, retour à la ligne final retiré. Une seule règle les tranche toutes : le tableau ci-dessous
+vaut pour l'URL de la base comme pour un secret de session.
 
 ```yaml
 env:
@@ -93,32 +119,41 @@ Les seules qui te concernent au déploiement. Le catalogue complet, c'est `npx n
 
 ### Derrière un frontal — **les plus importantes**
 
-| Variable                     | Rôle                                              | Absente ⇒                                                                            |
-| ---------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `NF__HTTP__TRUSTPROXY`       | Quels intermédiaires sont crus sur leurs en-têtes | **Le schéma constaté est `http`** → cookie `__Host-` non émis, adresse client fausse |
-| `NF__HTTP__TRUSTEDHOSTS`     | Les hôtes servis                                  | Un `Host` étranger n'est pas refusé                                                  |
-| `NF__APP__DOMAINCHECK`       | Contrôle du domaine                               | Pas de contrôle                                                                      |
-| `NF__HTTP__STATICS__ENABLED` | L'application sert-elle les fichiers statiques    | Elle les sert — donc en double avec ton frontal                                      |
+| Variable                     | Rôle                                              | Absente ⇒                                                                                                              |
+| ---------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `NF__HTTP__TRUSTPROXY`       | Quels intermédiaires sont crus sur leurs en-têtes | **Le schéma constaté est `http`** → cookie de session sans `__Host-`, mot de passe refusé `403`, adresse client fausse |
+| `NF__HTTP__TRUSTEDHOSTS`     | Les hôtes servis                                  | Un `Host` étranger n'est pas refusé                                                                                    |
+| `NF__APP__DOMAINCHECK`       | Contrôle du domaine                               | Pas de contrôle                                                                                                        |
+| `NF__HTTP__STATICS__ENABLED` | L'application sert-elle les fichiers statiques    | Elle les sert — donc en double avec ton frontal                                                                        |
 
 ### Données
 
-| Variable          | Rôle                   | Absente ⇒                                            |
-| ----------------- | ---------------------- | ---------------------------------------------------- |
-| `NF_DATABASE_URL` | L'URL de la base       | **Repli sur SQLite local**, dans `var/` — silencieux |
-| `NF_REDIS_URL`    | L'URL du cache partagé | Le cache n'est pas chargé                            |
+| Variable          | Rôle                   | Absente ⇒                                         |
+| ----------------- | ---------------------- | ------------------------------------------------- |
+| `NF_DATABASE_URL` | L'URL de la base       | **Repli sur SQLite local**, dans `var/` — annoncé |
+| `NF_REDIS_URL`    | L'URL du cache partagé | Le cache n'est pas chargé                         |
 
 > Le repli SQLite est le piège d'exploitation classique : l'application **démarre**, sert des
-> requêtes, écrit dans un fichier — et chaque exemplaire a sa propre base. Rien n'est en erreur.
-> `npx nodefony env` le montre en une ligne.
-
-### Secrets — obligatoires en production
-
-| Variable            | Ce qu'il protège                                 |
-| ------------------- | ------------------------------------------------ |
-| `NF_CSRF_SECRET`    | Les jetons anti-CSRF, partagés entre exemplaires |
-| `NF_TOTP_KEY`       | Les secrets de double authentification au repos  |
-| `NF_WEBHOOK_KEY`    | Les signatures de webhooks                       |
-| `NF_ADMIN_PASSWORD` | Le compte d'administration                       |
+> requêtes, écrit dans un fichier — et chaque exemplaire a sa propre base. Il est ANNONCÉ
+> (avertissement au démarrage, point `DB_SQLITE_FALLBACK` dans `npx nodefony status --json`),
+> mais rien n'échoue : lis le bilan du démarrage. Seule exception : si une entité est écrite pour
+> un autre moteur (PostgreSQL, MySQL), le repli est **refusé** et le démarrage s'arrête.
+
+### Secrets — ce qui se passe en production sans eux
+
+| Variable            | Ce qu'il protège                                 | Absente en production ⇒                             |
+| ------------------- | ------------------------------------------------ | --------------------------------------------------- |
+| `NF_CSRF_SECRET`    | Les jetons anti-CSRF, partagés entre exemplaires | **Refus de démarrer** (78)                          |
+| `NF_JWT_KEYSET`     | La clé de signature des jetons, commune à tous   | **Refus de démarrer** si l'app émet des jetons      |
+| `NF_TOTP_KEY`       | Les secrets de double authentification au repos  | Double authentification désactivée (journal CRITIC) |
+| `NF_WEBHOOK_KEY`    | Les signatures de webhooks                       | Webhooks désactivés (journal CRITIC)                |
+| `NF_ADMIN_PASSWORD` | Le compte d'administration, au PREMIER démarrage | Aucun compte créé ; inutile une fois le compte créé |
+
+`NF_JWT_KEYSET` manque presque toujours au premier déploiement : sans elle, un exemplaire qui
+émet des jetons **refuse de démarrer** en production (78) — et deux exemplaires à clés
+différentes refuseraient chacun les jetons de l'autre. `npx nodefony security:secrets --jwt-keyset`
+la produit (une ligne JSON) ; `--env` rend les autres secrets en lignes `CLÉ=valeur`, prêtes pour
+`docker run --env-file` ou un gestionnaire de secrets.
 
 Tous en `_FILE` en production. Détail et rotation → [`secrets.md`](secrets.md).
 
@@ -129,7 +164,7 @@ Tous en `_FILE` en production. Détail et rotation → [`secrets.md`](secrets.md
 | `NF_POD_NAME`                     | Identité de l'exemplaire — **dérive l'identité d'origine du bus temps réel** |
 | `NF_INSTANCE_ID`                  | Identifiant d'exemplaire                                                     |
 | `NF_REALTIME_DRIVER`              | Le transport du bus entre exemplaires                                        |
-| `NF_REALTIME_BACKPLANE_SECRET`    | Scelle les enveloppes échangées sur le bus                                   |
+| `NF_REALTIME_BACKPLANE_SECRET`    | Scelle les enveloppes du bus — moins de 32 caractères arrête le démarrage    |
 | `NF_REALTIME_BACKPLANE_NAMESPACE` | Cloisonne deux applications qui partagent le même bus                        |
 
 > 🔴 **Deux applications sur un même cache, sans espace de noms distinct, se parlent.** Le symptôme
@@ -137,10 +172,10 @@ Tous en `_FILE` en production. Détail et rotation → [`secrets.md`](secrets.md
 
 ### Multi-process sur une seule machine
 
-| Variable     | Rôle                                                     |
-| ------------ | -------------------------------------------------------- |
-| `NF_CLUSTER` | Active le mode multi-process                             |
-| `NF_WORKERS` | Nombre d'exécutants — sinon dérivé des limites du cgroup |
+| Variable     | Rôle                                                                           |
+| ------------ | ------------------------------------------------------------------------------ |
+| `NF_CLUSTER` | Posée par `nodefony cluster` dans chaque worker — **ne pas la poser soi-même** |
+| `NF_WORKERS` | Nombre d'exécutants — sinon dérivé des limites du cgroup                       |
 
 En Kubernetes, **laisse ça tranquille** : un exemplaire = un processus = un pod, et c'est
 l'ordonnanceur qui multiplie. Le mode multi-process sert sur une machine nue.

package/skills/nodefony-migrate-schema/SKILL.md

@@ -259,10 +259,13 @@ neuve ne prouve RIEN de tout ça — elle est vide.
 ```bash
 # sqlite : une copie du fichier. Le chemin par défaut du connecteur `default` est
 # `var/databases/nodefony-drizzle.db` — `orm:migrate:status --json` le confirme.
-cp var/databases/nodefony-drizzle.db /tmp/essai.sqlite
+# La copie va sous `tmp/scratch/` de l'application, pas dans le /tmp du système :
+# c'est un résultat qu'on relit, et il doit disparaître avec le reste de `tmp/`.
+mkdir -p tmp/scratch
+cp var/databases/nodefony-drizzle.db tmp/scratch/essai.sqlite
 # PostgreSQL : CREATE DATABASE app_essai TEMPLATE app;  (ou une restauration de sauvegarde)
 
-export NF_MIGRATE_DATABASE_URL="sqlite:/tmp/essai.sqlite"
+export NF_MIGRATE_DATABASE_URL="sqlite:tmp/scratch/essai.sqlite"
 npx nodefony orm:migrate --json
 ```
 

package/skills/nodefony-migrate-schema/references/verdicts.md

@@ -113,25 +113,26 @@ n'a jamais les deux — c'est le discriminant à tester.
 
 ### Refus d'usage — la demande elle-même
 
-| Code                             | Ce qui s'est passé                                                                                     | Le geste                                                                                                      |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
-| `NF_MIGRATE_UNKNOWN_CONNECTOR`   | aucun connecteur de ce nom                                                                             | le message liste ceux que l'application déclare                                                               |
-| `NF_MIGRATE_UNKNOWN_TAG`         | `--up-to` désigne une migration inconnue                                                               | relire `sources[].pendingTags`                                                                                |
-| `NF_MIGRATE_UNKNOWN_SOURCE`      | `--source` n'est pas déclarée par cette application                                                    | relire `sources[].name`                                                                                       |
-| `NF_MIGRATE_URL_MISMATCH`        | la variable de migration désigne une base d'un AUTRE dialecte                                          | corriger la variable, ou choisir le bon connecteur                                                            |
-| `NF_MIGRATE_NOT_CONFIGURED`      | connecteur SQL non déclaré dans la configuration                                                       | le déclarer pour pouvoir le suivre                                                                            |
-| `NF_MIGRATE_SECONDARY_CONNECTOR` | un connecteur secondaire porte le nom d'un dossier de dialecte (`sqlite`, `postgres`, `mysql`, `meta`) | renommer le connecteur dans `connectors` — un secondaire range ses migrations sous `migrations/<connecteur>/` |
-| `NF_MIGRATE_NO_MIGRATIONS`       | ce connecteur est porté par une base qui ne se migre pas ainsi                                         | rien à migrer ici — ce n'est pas une panne                                                                    |
-| `NF_MIGRATE_NOT_DEVELOPMENT`     | geste réservé au développement, demandé ailleurs                                                       | passer par le travail de déploiement                                                                          |
-| `NF_MIGRATE_DESTRUCTIVE`         | des migrations en attente SUPPRIMENT des données                                                       | relire le fichier produit, puis assumer explicitement                                                         |
-| `NF_MIGRATE_UNAVAILABLE`         | la commande s'est arrêtée sans pouvoir nommer la cause                                                 | constater l'état (`orm:migrate:status`) avant de reprendre                                                    |
-| `NF_MIGRATE_CONFIRM_REQUIRED`    | `orm:reset` demandé hors terminal, ou en sortie machine                                                | relancer avec `--yes` si l'effacement est voulu                                                               |
-| `NF_GENERATE_NAME`               | le nom de migration demandé n'est pas utilisable                                                       | reprendre la suggestion que le message donne                                                                  |
-| `NF_GENERATE_MISSING_ENTITY`     | une entité est enregistrée sans fichier qui la fournisse                                               | `nodefony inspect entities --json` pour la situer                                                             |
-| `NF_GENERATE_FRAMEWORK_TABLE`    | une entité de l'application usurpe une table du framework                                              | la renommer, ou écrire une migration libre (`--custom`)                                                       |
-| `NF_GENERATE_DESTRUCTIVE`        | la migration ÉCRITE supprime des données                                                               | relire le fichier, puis annuler (`git checkout`) ou appliquer — la mise en service a sa propre garde          |
-| `NF_GENERATE_DATABASE_BEHIND`    | rien à écrire, et pourtant la base ne porte pas le schéma                                              | `repair --forget <source>/<tag>` : l'historique affirme une migration jamais exécutée                         |
-| `NF_GENERATE_TOOL_MISSING`       | l'outil de génération n'est pas installé                                                               | l'installer en dépendance de développement                                                                    |
+| Code                             | Ce qui s'est passé                                                                                     | Le geste                                                                                                        |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `NF_MIGRATE_UNKNOWN_CONNECTOR`   | aucun connecteur de ce nom                                                                             | le message liste ceux que l'application déclare                                                                 |
+| `NF_MIGRATE_UNKNOWN_TAG`         | `--up-to` désigne une migration inconnue                                                               | relire `sources[].pendingTags`                                                                                  |
+| `NF_MIGRATE_UNKNOWN_SOURCE`      | `--source` n'est pas déclarée par cette application                                                    | relire `sources[].name`                                                                                         |
+| `NF_MIGRATE_URL_MISMATCH`        | la variable de migration désigne une base d'un AUTRE dialecte                                          | corriger la variable, ou choisir le bon connecteur                                                              |
+| `NF_MIGRATE_NOT_CONFIGURED`      | connecteur SQL non déclaré dans la configuration                                                       | le déclarer pour pouvoir le suivre                                                                              |
+| `NF_MIGRATE_SECONDARY_CONNECTOR` | un connecteur secondaire porte le nom d'un dossier de dialecte (`sqlite`, `postgres`, `mysql`, `meta`) | renommer le connecteur dans `connectors` — un secondaire range ses migrations sous `migrations/<connecteur>/`   |
+| `NF_MIGRATE_NO_MIGRATIONS`       | ce connecteur est porté par une base qui ne se migre pas ainsi                                         | rien à migrer ici — ce n'est pas une panne                                                                      |
+| `NF_MIGRATE_NOT_DEVELOPMENT`     | geste réservé au développement, demandé ailleurs                                                       | passer par le travail de déploiement                                                                            |
+| `NF_MIGRATE_DESTRUCTIVE`         | des migrations en attente SUPPRIMENT des données                                                       | relire le fichier produit, puis assumer explicitement                                                           |
+| `NF_MIGRATE_UNAVAILABLE`         | la commande s'est arrêtée sans pouvoir nommer la cause                                                 | constater l'état (`orm:migrate:status`) avant de reprendre                                                      |
+| `NF_MIGRATE_CONFIRM_REQUIRED`    | `orm:reset` demandé hors terminal, ou en sortie machine                                                | relancer avec `--yes` si l'effacement est voulu                                                                 |
+| `NF_GENERATE_NAME`               | le nom de migration demandé n'est pas utilisable                                                       | reprendre la suggestion que le message donne                                                                    |
+| `NF_GENERATE_MISSING_ENTITY`     | une entité est enregistrée sans fichier qui la fournisse                                               | `nodefony inspect entities --json` pour la situer                                                               |
+| `NF_GENERATE_UNREADABLE_ENTITY`  | rien d'écrit, et un fichier d'entités ne s'importe pas : sa table n'est vue par personne               | corriger la cause nommée (souvent un paquet absent des dépendances), ou sortir le fichier de `nodefony/entity/` |
+| `NF_GENERATE_FRAMEWORK_TABLE`    | une entité de l'application usurpe une table du framework                                              | la renommer, ou écrire une migration libre (`--custom`)                                                         |
+| `NF_GENERATE_DESTRUCTIVE`        | la migration ÉCRITE supprime des données                                                               | relire le fichier, puis annuler (`git checkout`) ou appliquer — la mise en service a sa propre garde            |
+| `NF_GENERATE_DATABASE_BEHIND`    | rien à écrire, et pourtant la base ne porte pas le schéma                                              | `repair --forget <source>/<tag>` : l'historique affirme une migration jamais exécutée                           |
+| `NF_GENERATE_TOOL_MISSING`       | l'outil de génération n'est pas installé                                                               | l'installer en dépendance de développement                                                                      |
 
 ## Un contrat qui ne bougera pas
 

package/skills/nodefony-protect-route/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: nodefony-protect-route
 description: >
-  Réserve une route d'une application Nodefony aux personnes habilitées, par les briques du
-  framework plutôt que par un contrôle écrit à la main dans l'action. Porte les deux étages
-  (zone du pare-feu et garde par route), la hiérarchie de rôles qui évite d'attribuer un rôle de
-  plus, la façon d'ouvrir une route à un partenaire sans démonter la défense anti-falsification,
-  et les gestes qui affaiblissent l'application en silence. À charger AVANT de poser une garde,
-  d'ouvrir une route à un tiers, ou de toucher à la configuration de sécurité.
-  Déclencheurs : "protège cette route", "réserver aux administrateurs", "@IsGranted", "firewall",
-  "zone protégée", "403", "401", "un rôle qui en implique un autre", "roleHierarchy",
-  "un partenaire doit pouvoir poster", "erreur CSRF", "origine refusée", "@CsrfExempt",
-  "@CsrfProtect", "mon POST passe sans jeton", "faut-il protéger une écriture",
-  "API pour un programme", "clé d'API", "désactiver la sécurité pour tester".
+  Réserve une route ou une page d'une application Nodefony aux personnes habilitées, par les
+  briques du framework plutôt que par un contrôle écrit dans l'action. Porte les deux étages
+  (zone du pare-feu et garde par route), la hiérarchie de rôles, le renvoi de l'anonyme vers la
+  page de connexion, l'ouverture à un partenaire sans démonter la défense anti-falsification,
+  les zones des programmes (clé d'API, jeton), et les gestes qui affaiblissent l'application en
+  silence. À charger AVANT de poser une garde, d'ouvrir une route à un tiers, ou de toucher à la
+  sécurité. Se CONNECTER (page, second facteur, retour après connexion) → nodefony-authentication.
+  Déclencheurs : "protège cette route", "réserver aux administrateurs", "@IsGranted",
+  "firewall", "403", "401", "roleHierarchy", "un partenaire doit pouvoir poster", "erreur CSRF",
+  "@CsrfExempt", "mon POST passe sans jeton", "API pour un programme", "clé d'API",
+  "client_credentials", "désactiver la sécurité pour tester".
 ---
 
 # protect-route — la garde vient du framework, jamais de l'action
@@ -85,6 +85,48 @@ pattern: "^/api/account/(profile|invoices)"; // ❌ les routes d'aujourd'hui
 elle a l'air de couvrir l'espace, et l'introspection montre bien une route protégée à côté. Quand
 des routes partagent un préfixe, ne les protège pas une par une.
 
+## Protéger des PAGES — renvoyer l'anonyme vers la connexion
+
+🔴 **La connexion elle-même — page `/login`, son habillage, le client `NodefonyLogin`, le second
+facteur, le retour après connexion, les fournisseurs — est le skill `nodefony-authentication`.**
+N'écris ni page de connexion ni controller de compte : tout est servi. Ici, seulement ce que la
+ZONE décide.
+
+**Conduire l'anonyme à la page** se déclare sur la ZONE, jamais dans l'action :
+
+```ts
+areas: {
+  pages: {
+    pattern: "^/compte(/|$)",
+    authenticators: ["session"],
+    entryPoint: "/login",   // la page du framework (security.loginPage.path)
+  },
+}
+```
+
+| La requête refusée                                                         | Réponse                         |
+| -------------------------------------------------------------------------- | ------------------------------- |
+| navigation (`GET`/`HEAD`, `Accept: text/html`, `Sec-Fetch-Mode: navigate`) | `302` → `/login?from=%2Fcompte` |
+| appel d'API (`Accept: application/json`, `fetch()`)                        | `401`, inchangé                 |
+
+**L'éprouver** : la navigation se joue avec `navigate()` de `nodefony/testing`, JAMAIS avec
+`fetch()` — Node y réécrit `Sec-Fetch-Mode` en `cors`, le pare-feu voit un appel d'API et répond
+`401` sur un code juste. `fetch()` reste l'outil du côté API.
+
+```ts
+import { navigate } from "nodefony/testing";
+import { appBaseUrl } from "./e2e.setup"; // tests/e2e.setup.ts, généré
+
+const res = await navigate(`${appBaseUrl()}/compte`); // 302 → /login?from=%2Fcompte
+```
+
+Le `from` qui revient après la connexion ne se suit JAMAIS sans `safeRedirectPath` — skill
+`nodefony-authentication`.
+
+**Une zone `session` sans `roles`, avec un fournisseur qui crée les comptes à la première
+connexion** (`allowSignup`), est ouverte à quiconque possède un compte chez ce fournisseur.
+`npx nodefony doctor --live` la signale ; pose un rôle sur la zone.
+
 ## 🔴 La PROVENANCE n'est pas une PREUVE D'INTENTION — une mutation exige `@CsrfProtect`
 
 Le raisonnement qui vient, et qui est faux : « le pare-feu vérifie déjà `Sec-Fetch-Site`, donc une
@@ -93,10 +135,12 @@ n'en envoie aucun, et la défense de provenance le laisse alors passer — c'est
 distingue les sites, pas les intentions. Résultat mesuré : un `POST /api/cart/items` sans jeton rend
 `201`, et l'application croit avoir une défense.
 
-Toute action qui ÉCRIT porte donc `@CsrfProtect` explicitement. Le jeton ne se demande à AUCUN
-endpoint : une requête sûre (`GET`) vers la route protégée sème le cookie lisible `csrf-token`, et
-la mutation le rejoue dans l'en-tête `x-csrf-token` — c'est le double-submit, sinon `403`. La
-provenance et le jeton se **cumulent** ; l'une ne remplace jamais l'autre.
+Toute action qui ÉCRIT porte donc `@CsrfProtect` explicitement. N'écris AUCUNE route pour distribuer
+le jeton : `GET /nodefony/security/api/auth/me` le sème déjà (cookie lisible `csrf-token`), comme
+toute requête sûre vers une route décorée — et il vaut pour TOUTES les routes protégées. La
+mutation le rejoue dans l'en-tête `x-csrf-token` — c'est le double-submit, sinon `403`. Un test le
+récupère par `csrfHeaders(base, cookie)` de `nodefony/testing`. La provenance et le jeton se
+**cumulent** ; l'une ne remplace jamais l'autre.
 
 ## 🔴 Ce qu'il ne faut jamais écrire
 
@@ -171,9 +215,16 @@ connecter — ou pire, un mot de passe stocké en clair.
 
 ## Lire l'utilisateur courant
 
-Le paramètre décoré `@CurrentUser()` (typé `IUser` de `@nodefony/user`). L'identité est
-**ré-résolue à chaque requête** : les rôles sont frais, et une révocation prend effet tout de
-suite. N'écris pas ton propre lecteur de session — le tien lira un instantané.
+Dans un controller, **`this.user`** : l'utilisateur CONNECTÉ, ou `null` (anonyme, ou route hors
+de toute zone). Le paramètre décoré `@CurrentUser()` rend le même, `undefined` pour l'anonyme.
+Hors controller (un service), `RequestContext.getAuthenticatedUser()` — `null` hors requête ou
+pour l'anonyme — et `RequestContext.getUserId()` (`string | null`). `RequestContext.getUser()`
+rend l'utilisateur BRUT, anonyme compris : ne t'en sers pas pour décider « qui est connecté ».
+
+L'identité est **ré-résolue à chaque requête** : les rôles sont frais, et une révocation prend
+effet tout de suite. N'écris pas ton propre lecteur de session — le tien lira un instantané. Une
+page PUBLIQUE qui veut savoir qui la visite se place sous une zone
+`authenticators: ["session", "anonymous"]` : hors zone, `this.user` vaut toujours `null`.
 
 ## Un droit métier qui ne se réduit pas à un rôle
 
@@ -190,8 +241,16 @@ d'appartenance à écrire dans l'action.
 
 ## Une API pour un PROGRAMME, pas pour un navigateur
 
-Un service partenaire, un script, un agent ne stockent aucun cookie. **La zone est déjà posée**
-dans le `nodefony/config/security.ts` généré :
+Un service partenaire, un script, un agent ne stockent aucun cookie. Le
+`nodefony/config/security.ts` généré (preset `complete`) pose **deux zones, une par sorte de
+preuve** — choisis selon ce que l'appelant détient, n'en ajoute pas une troisième :
+
+| L'appelant présente                            | Zone      | Préfixe        | Obtenir la preuve                       |
+| ---------------------------------------------- | --------- | -------------- | --------------------------------------- |
+| une **clé d'API** opaque (`nf_…`)              | `machine` | `/api/machine` | `POST /nodefony/security/api/keys`      |
+| un **jeton d'accès** (de l'app ou de Keycloak) | `partner` | `/api/partner` | `npx nodefony app:partner:call` le fait |
+
+### Clé d'API : la zone `machine`
 
 ```ts
 machine: {
@@ -216,6 +275,48 @@ qui ne stocke pas de cookie ne doit rien recevoir qu'il faille stocker.**
 
 Les clés s'émettent par `POST /nodefony/security/api/keys`.
 
+### Jeton d'accès : la zone `partner`, et la commande qui l'éprouve
+
+La zone accepte un jeton signé par l'application (`jwt`) **et** un jeton de Keycloak
+(`external-jwt`) ; les deux s'aiguillent sur l'émetteur, leur ordre ne décide de rien. Une route
+qui tombe sous `/api/partner` est protégée sans rien ajouter. L'exemple qui marche est déjà dans
+l'application — **lis-le avant d'écrire un appelant** :
+
+```bash
+npx nodefony app:partner:call                     # jeton signé par l'app pour `admin` (--as <compte>)
+npx nodefony app:partner:call --issuer keycloak   # client <app>-machine, flux client_credentials
+```
+
+Source : `nodefony/command/PartnerCallCommand.ts` (la commande) et
+`nodefony/controllers/PartnerController.ts` (`GET /api/partner/whoami`, qui rend l'identité ET
+l'émetteur). Un jeton Keycloak s'obtient par `requestClientCredentialsToken` de
+`@nodefony/security` — découverte du point de jeton comprise —, jamais par un `fetch` recopié.
+
+🔴 **L'audience vit en UN endroit.** Un jeton n'ouvre que la zone dont il porte la ressource
+(RFC 8707). `partnerResource(ctx.env)` est lue par la zone (`resource`), par `jwt.audiences` et par
+la commande. Une ressource recopiée à la main finit par différer, et le seul symptôme est un refus
+sans explication. Ouvrir une AUTRE ressource à des jetons, c'est trois gestes, pas un :
+
+| Oublié                                    | Symptôme                                                      |
+| ----------------------------------------- | ------------------------------------------------------------- |
+| la ressource dans `jwt.audiences`         | **400 `invalid_target`** à l'émission du jeton de l'app       |
+| `security:keycloak:realm --write` relancé | **401** du jeton Keycloak : le realm n'inscrit pas l'audience |
+| la `resource` sur la zone                 | l'application **refuse de démarrer** en nommant la zone       |
+
+🔴 **`subjectPolicy: "ephemeral"` s'écrit SUR LA ZONE, jamais dans `resourceServer`.** Le client
+machine de Keycloak n'a pas de compte ici : `ephemeral` l'accepte le temps de la requête, avec les
+seuls `ephemeralRoles` de la zone (`ROLE_PARTNER`). Posé dans `resourceServer.subjectPolicy`
+(global), il ferait accepter un appelant sans compte par **toutes** les zones `external-jwt`. Et
+un rôle fort dans `ephemeralRoles` est accordé à **quiconque** détient un jeton valide du realm.
+
+`whoami` n'exige pas `ROLE_PARTNER` — un compte de l'app ne l'a pas. Pour réserver une action aux
+partenaires : `@IsGranted("ROLE_PARTNER")`.
+
+**Prouver** : `--issuer nodefony` rend 200 sans Keycloak ; `--issuer keycloak` rend 200 avec le
+profil `keycloak` du compose allumé ; et le MÊME jeton machine est refusé (401) sur une zone qui
+garde `subjectPolicy` par défaut (`require`). Chaque échec de la commande sort en code 1 avec le
+geste qui répare — lis-le avant de chercher ailleurs.
+
 ## Les gestes qui affaiblissent en silence
 
 Bloqué par une garde en résolvant autre chose, le réflexe est de la retirer. La fonctionnalité
@@ -244,7 +345,7 @@ Le refus d'un anonyme est gratuit : n'importe quelle zone le donne. Ce qui prouv
 
 ```bash
 npx nodefony security:user:add            # un témoin SANS le rôle
-# 1. anonyme            → refusé (401 ou 403 : les deux sont justes)
+# 1. anonyme            → refusé (401 ou 403 ; 302 vers /login si la zone a un entryPoint)
 # 2. connecté SANS rôle → refusé      ← celui-ci porte l'information
 # 3. administrateur     → servi
 npx nodefony inspect routes --json        # la garde est-elle sur la route qu'on croit ?
@@ -256,6 +357,7 @@ Chaque geste ci-dessus a sa référence INSTALLÉE — une recherche ordinaire n
 ne descendant pas dans `node_modules` :
 
 - **Zones, authentificateurs, CSRF, CORS, clés d'API** — `node_modules/@nodefony/security/docs/firewall.md`
+- **Jeton d'un tiers, `subjectPolicy`, `client_credentials`** — `node_modules/@nodefony/security/docs/external-jwt.md`
 - **`@IsGranted`, voters, hiérarchie de rôles** — `node_modules/@nodefony/security/docs/authorization.md`
 - **Contrat `IUser`, `UserService`, mot de passe** — `node_modules/@nodefony/user/docs/index.md`
 - **Politique de contenu, nonce, HSTS** — `node_modules/@nodefony/security/docs/headers.md`
@@ -271,3 +373,4 @@ framework.
 | Une ressource complète stockée | `nodefony-add-crud`             |
 | Un service métier injectable   | `nodefony-add-service`          |
 | Un flux temps réel réservé     | `nodefony-add-realtime-channel` |
+| Se connecter, second facteur   | `nodefony-authentication`       |

package/skills/nodefony-security-review/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: nodefony-security-review
+description: >
+  Relit la sécurité du code d'une application Nodefony avant le commit : un script sur le diff,
+  puis une grille de jugement. Le script nomme, fichier et ligne, ce
+  qu'un motif suffit à voir — route ouverte à l'anonyme ou hors de toute
+  zone du pare-feu, mutation sans jeton anti-falsification, SQL interpolé, secret écrit ou
+  journalisé, identité brute qui inclut l'anonyme, garde éteinte, redirection ouverte — avec le
+  geste qui corrige et le skill qui le porte ; la grille couvre le droit sur l'objet, les champs
+  renvoyés, les entrées non bornées. À charger AVANT de commiter une route,
+  une requête, un service qui touche des données ou de la configuration de sécurité. Écrire la
+  garde elle-même → `nodefony-protect-route`.
+  Déclencheurs : "c'est sûr ?", "est-ce sécurisé ?", "relis la sécurité avant que je commite", "ma route est-elle
+  protégée ?", "revue de sécurité", "relecture de sécurité", "audit de sécurité de mon code",
+  "y a-t-il une faille", "injection SQL", "secret dans le code", "avant de commiter".
+metadata:
+  version: 1.0.0
+---
+
+# nodefony-security-review — relire avant de commiter, faute par faute
+
+> **Maintenance** : vérité courante, jamais un journal. Éditer en place ; l'historique vit dans
+> `git log`. Pas de `references/`, comme `nodefony-dev` et pour la même raison mesurée : une page
+> de `references/` n'est presque jamais ouverte par un agent, un script cité comme commande l'est.
+> Ce qui doit atteindre un agent s'EXÉCUTE ou vit dans ce corps.
+
+## Passer la main
+
+| Ce que tu fais en réalité                                               | Le skill                  |
+| ----------------------------------------------------------------------- | ------------------------- |
+| Tu poses la garde : zone, rôle, jeton anti-falsification, voter         | `nodefony-protect-route`  |
+| Tu touches à la connexion : identité, second facteur, jeton d'un script | `nodefony-authentication` |
+| Tu codes la fonctionnalité elle-même                                    | `nodefony-dev`            |
+| Tu sors un secret du source : `env.ts`, `.env`, `npx nodefony env`      | `nodefony-dev`            |
+| Quelque chose qui marchait ne marche plus                               | `nodefony-troubleshoot`   |
+| Tu prépares l'image, les secrets du déploiement, le proxy TLS           | `nodefony-devops`         |
+
+## 1. La règle — nommer, trancher, prouver
+
+**Une relecture NOMME chaque point**, avec son fichier et sa ligne : « ça me paraît sûr » n'est
+pas une relecture. Puis elle **tranche** chacun : corrigé, ou justifié par écrit (« cette route est
+publique : c'est la page d'accueil »). Un point ni corrigé ni justifié reste ouvert, et se dit.
+
+**Ne corrige jamais en affaiblissant.** Retirer une garde qui gêne, couper le jeton
+anti-falsification, élargir une zone à l'anonyme, déplacer une URL sous une autre zone : le diff
+redevient silencieux et la faille est plus grande qu'avant. Une URL déjà publiée ne se déplace pas
+— on adapte la ZONE à l'URL (skill `nodefony-protect-route`).
+
+## 2. Le script — ce qu'un motif suffit à voir
+
+```bash
+node node_modules/@nodefony/devkit/skills/nodefony-security-review/scripts/review-diff.mjs
+node node_modules/@nodefony/devkit/skills/nodefony-security-review/scripts/review-diff.mjs --base main
+node node_modules/@nodefony/devkit/skills/nodefony-security-review/scripts/review-diff.mjs --staged
+node node_modules/@nodefony/devkit/skills/nodefony-security-review/scripts/review-diff.mjs --json
+```
+
+Sans option, il relit le **travail en cours** (non commité, fichiers non suivis compris) ; s'il n'y
+en a pas, le **dernier commit** — la première ligne de sa sortie dit toujours ce qu'il a relu.
+`--base main` relit toute une branche. Sorties : `0` rien à signaler · `1` au moins un point ·
+`64` usage · `66` aucun diff lisible (pas un dépôt git : passe un patch avec `--diff`).
+
+Chaque point sort avec son niveau, `fichier:ligne`, la raison et le geste :
+
+- **`FAUTE`** — à corriger. Une faute qu'on garde exige une raison écrite, et elle est rare.
+- **`À JUSTIFIER`** — légitime parfois, jamais par accident : une route publique voulue, une
+  variable lue hors de `env.ts` pour une bonne raison. Corrige, ou écris la raison.
+
+Un secret signalé est **masqué** dans l'extrait (quatre caractères, puis `…`). Ne le recopie pas
+non plus dans ta relecture : nomme sa constante et sa ligne. Une valeur citée dans un compte rendu
+versionné est publiée une fois de plus.
+
+⚠️ **Il croise les routes NOUVELLES avec les zones du pare-feu** lues dans `nodefony/config/` — ce
+que ni `doctor` ni `inspect` ne font. Dans une application générée, la zone `^/api` laisse passer
+l'anonyme : une route ajoutée sous `/api` sans `@IsGranted` répond à n'importe qui, et rien
+d'autre ne le dit. Il ne relit pas les tests (leurs secrets en dur sont des fixtures).
+
+⚠️ **Un outil MCP échappe aux zones.** Ce qu'un module publie par `getMcpTools()` est servi par
+`/nodefony/mcp`, qu'aucune zone du pare-feu ne couvre : tant que `mcp.authorization` n'est pas
+déclaré, seules l'adresse locale et l'origine le gardent. Un outil qui rend des données de compte
+ou qui ÉCRIT se relit comme une route ouverte.
+
+## 3. La grille — ce qu'on cherche, ce qui le montre, ce qui le corrige
+
+| Ce qu'on cherche                                                          | Ce qui le montre                   | Le geste juste                                                                                                                                                     |
+| ------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Une route nouvelle que l'anonyme atteint (zone `anonymous`, ou hors zone) | le script (`route-open`)           | `@IsGranted("ROLE_…")`, ou une zone qui exige une session → `nodefony-protect-route`                                                                               |
+| Une mutation sans `@CsrfProtect` sous une zone à session                  | le script                          | `@CsrfProtect()` ; le client sème le jeton par un `GET` → `nodefony-protect-route`                                                                                 |
+| « Connecté ? » testé sur l'utilisateur brut                               | le script (`raw-identity`)         | `this.user` dans un controller → `nodefony-authentication`                                                                                                         |
+| Une donnée reçue dans du SQL brut                                         | le script                          | le gabarit `` sql`… ${valeur}` `` de drizzle lie la valeur ; jamais `sql.raw` sur une entrée                                                                       |
+| Un secret dans le source, un `.env` dans le diff                          | le script, puis `npx nodefony env` | variable `NF_…` déclarée dans `env.ts`, valeur dans le `.env` du poste, jamais commité ; `npx nodefony env` AVANT et APRÈS prouve qu'elle est lue → `nodefony-dev` |
+| Un mot de passe, un jeton, un cookie dans le journal                      | le script                          | journaliser l'identifiant de l'objet, jamais la valeur                                                                                                             |
+| Une garde éteinte (`rateLimit`, `unsafe-inline`, secret en clair)         | le script                          | régler un seuil, jamais éteindre → `nodefony-protect-route`                                                                                                        |
+| Une redirection vers une adresse reçue                                    | le script                          | `safeRedirectPath(valeur)`, importé de `nodefony`                                                                                                                  |
+| Un chemin de fichier, une commande composés avec une entrée               | le script                          | vérifier que le chemin reste sous sa racine ; `execFile` avec un tableau d'arguments, sans shell                                                                   |
+| Un outil MCP publié (`getMcpTools()`), une porte MCP ouverte au réseau    | le script                          | lecture seule et rien qu'on ne lirait sans compte ; sinon `scopes` + `mcp.authorization` (`node_modules/@nodefony/devkit/docs/index.md`)                           |
+| Ce qui était DÉJÀ ouvert avant ce diff (`@Anonymous`, zone publique)      | `npx nodefony doctor`              | famille « Surface ouverte » : l'inventaire, à relire                                                                                                               |
+| Un secret suivi par git, une variable non déclarée                        | `npx nodefony doctor`              | familles « Secrets hors de git » et « Variables déclarées »                                                                                                        |
+| Une dépendance à vulnérabilité connue                                     | `npm audit --omit=dev`             | monter la version corrigée ; jamais `--force` sans lire ce qu'il casse                                                                                             |
+
+## 4. Ce que seul un jugement tranche
+
+Le script ne voit pas l'intention. Relis ces trois points toi-même, sur chaque route touchée :
+
+1. **Le droit sur l'OBJET.** Un rôle dit « peut éditer des documents », pas « peut éditer CE
+   document ». Une route qui lit un identifiant dans l'URL (`/api/documents/:id`) et renvoie
+   l'enregistrement sans vérifier qu'il appartient à l'appelant laisse chacun lire les données des
+   autres en changeant un nombre. Le geste : un voter, `@IsGranted("doc.edit", { subject: "id" })`
+   → `nodefony-protect-route`.
+2. **Les champs RENVOYÉS.** Rendre l'entité entière (`this.renderJson(user)`) envoie aussi ce
+   qu'on n'a pas choisi — l'empreinte du mot de passe (colonne `password` de `User`), les
+   métadonnées internes, les rôles d'un autre compte.
+   Rends un objet construit champ par champ.
+3. **Les entrées NON BORNÉES.** Une liste sans plafond, une taille de page lue telle quelle, un
+   fichier reçu sans limite de taille : une seule requête suffit à épuiser le serveur. Plafonne
+   (`Math.min(limite, 100)`), et refuse ce qui dépasse plutôt que de le traiter.
+
+## 5. Avant de dire « relu »
+
+1. **Le script est relancé APRÈS les corrections** : il rend `0`, ou chaque point restant porte sa
+   justification écrite dans ta réponse.
+2. **`npx nodefony doctor`** ne signale rien de neuf.
+3. **Une garde ajoutée est PROUVÉE** par trois appels — anonyme refusé, compte sans le rôle refusé,
+   compte avec le rôle servi (skill `nodefony-protect-route`). Le refus de l'anonyme seul ne prouve
+   rien : n'importe quelle zone le donne.
+4. **Nomme ce que tu n'as pas relu** : `npm audit` non lancé, une route dont tu ne sais pas si elle
+   doit être publique. Le dire coûte une ligne ; le taire, une faille.