@nodefony/devkit 10.0.0-alpha.6 → 10.0.0-alpha.8

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

@@ -9,20 +9,26 @@ description: >
   exemplaires. À charger AVANT de modifier une entité déjà en base, ou avant de déployer un schéma
   changé.
   Déclencheurs : "j'ai ajouté un champ à une entité", "la colonne n'existe pas en base",
-  "modifier une table existante", "migration", "migrer le schéma", "orm:migrate", "orm:generate",
-  "la base est en retard", "appliquer les migrations", "déployer un changement de schéma",
-  "comment passer ce modèle en production", "ma base ne correspond plus au code",
-  "no such column", "column does not exist", "erreur SQL après avoir changé une entité",
-  "adopter une base existante", "réparer une migration en échec", "le pod ne devient pas prêt",
-  "comment tester ma migration", "éprouver une migration", "vérifier qu'une migration marche",
-  "prouver que ma migration s'applique", "essayer sans casser ma base", "base d'essai",
-  "rejouer les migrations depuis zéro", "repartir d'une base propre".
+  "modifier une table existante", "migrer le schéma", "orm:migrate", "orm:generate",
+  "appliquer les migrations", "déployer un changement de schéma", "no such column",
+  "column does not exist", "ma base ne correspond plus au code", "adopter une base existante",
+  "réparer une migration en échec", "éprouver une migration sans casser ma base",
+  "rejouer les migrations depuis zéro".
 metadata:
   version: 2
 ---
 
 # Faire évoluer un schéma, et le porter en production
 
+> 🧭 **Tu es arrivé ici directement ? Charge aussi `nodefony-dev`** — il porte la conduite
+> commune (par où commencer, comment prouver que c'est fait) et les pièges qui coûtent une heure,
+> serveur comme front. Cette page-ci ne couvre QUE son geste.
+>
+> Et si une réponse te manque, elle est probablement INSTALLÉE : `rg` ne descend pas dans
+> `node_modules`, donc 70 pages de documentation y paraissent absentes. Une commande les lit, avec
+> la ligne exacte :
+> `node node_modules/@nodefony/devkit/skills/nodefony-dev/scripts/docs.mjs <termes>`.
+
 ## 1. La seule chose à savoir avant tout le reste
 
 **En développement, il n'y a rien à faire.** La base suit le code : la table naît au démarrage, et
@@ -88,6 +94,27 @@ reprendre après une coupure sans lire d'état préalable.
 > dépose un fichier vide et son entrée de journal. Le gabarit déposé explique comment séparer les
 > instructions ; suis-le à la lettre.
 
+**En développement, les deux premiers gestes se disent en un seul** :
+
+```bash
+npx nodefony orm:generate --name ajout_slug --apply
+```
+
+`--apply` ENCHAÎNE `orm:migrate` — il ne rejoue pas l'application pour son compte, donc toutes ses
+gardes valent (refus du destructif sans `--allow-destructive`, verrou, historique). En `--json`, un
+seul document sort : celui de l'application, qui porte le verdict. Le drapeau **n'existe qu'en
+développement** et rien ne le déverrouille ailleurs : hors développement, la migration a été écrite,
+relue et versionnée en amont, et c'est `orm:migrate` seul qui l'applique.
+
+> **Le démarrage bascule tout seul, et il faut le savoir avant d'être surpris.** Tant que
+> l'application ne versionne AUCUNE migration, le démarrage en développement dérive les tables
+> depuis le code (`ddl: "auto"`) : on n'a rien à taper. Dès la première migration écrite, il
+> applique les migrations (`ddl: "migrate"`) et cesse de dériver. C'est ce qui empêche deux
+> fabricants du même schéma de se contredire — le DDL dérivé pose une unicité collée à la colonne,
+> le générateur de migrations raisonne sur un index nommé, et la migration qui tente de retirer le
+> second échoue sur un objet qui n'a jamais existé. Un `ddl` écrit dans la configuration gagne
+> toujours ; sous `NODE_ENV=test`, rien ne change.
+
 ### 🔴 Un champ OBLIGATOIRE sur une table PEUPLÉE — ton moteur ne fait pas ce que tu crois
 
 Ajouter une colonne `NOT NULL` **sans valeur par défaut** à une table qui porte déjà des lignes n'a
@@ -139,15 +166,21 @@ npx nodefony orm:migrate
 d'appliquer ». Il ne refuse pas — il ne lit pas la base et ignore si ta table porte des lignes —,
 mais s'il le signale et que ta table n'est pas vide, la migration échouera.
 
-**À l'étape 3, sur sqlite, attends-toi à un refus `NF_GENERATE_DESTRUCTIVE`** — mesuré sur une
-table de deux lignes. Rendre une colonne obligatoire n'est pas un `ALTER` en sqlite : le moteur
-n'en a pas, alors l'outil RECONSTRUIT la table (`CREATE __new_billets` → `INSERT … SELECT` →
-`DROP TABLE` → `RENAME`). Le `DROP TABLE` est reconnu comme destructeur, et il l'est en général —
-ici il porte sur une table déjà recopiée, une ligne plus haut, dans la même migration. **Relis le
-fichier avant de décider** : si tu y vois l'`INSERT INTO __new_… SELECT … FROM …` juste avant le
-`DROP`, la reconstruction conserve les lignes, et `orm:migrate` l'applique sans broncher (les
-fichiers sont écrits, c'est leur mise en service qui était refusée). Éprouvé de bout en bout :
-deux lignes semées, trois étapes, deux lignes intactes et l'index unique en place.
+**À l'étape 3, sur sqlite, attends-toi à un AVERTISSEMENT `table-rebuild`, pas à un refus.**
+Rendre une colonne obligatoire n'est pas un `ALTER` en sqlite : le moteur n'en a pas, alors la
+table est RECONSTRUITE (`CREATE` une table d'étape → `INSERT … SELECT` → `DROP TABLE` →
+`RENAME`). Ce `DROP TABLE` porte sur une table recopiée une ligne plus haut, dans la même
+migration : l'outil le reconnaît et te le signale — « recrée la table pour modifier une colonne
+(SQLite ne sait pas faire autrement) » — sans rien refuser, à la génération comme à la mise en
+service. Tu n'as donc **pas** besoin de `--allow-destructive` pour une reconstruction.
+
+Ce qui reste à TA charge, et c'est le sens de l'avertissement : **relis l'`INSERT … SELECT`**.
+Une colonne absente de cette recopie serait bel et bien perdue, et aucun automate ne peut le
+deviner à ta place. Éprouvé de bout en bout : deux lignes semées, trois étapes, deux lignes
+intactes et l'index unique en place.
+
+> Un vrai `DROP TABLE` — une table supprimée sans recopie, ou une AUTRE table supprimée dans la
+> même migration — reste refusé. Le verdict porte sur chaque table, pas sur le fichier.
 
 > **Ne jamais** répondre à un échec de migration en refaisant la base. Une migration qui n'est pas
 > passée n'a **rien** changé — sqlite et PostgreSQL l'annulent entière. C'est le fichier qu'il faut

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

@@ -10,11 +10,21 @@ description: >
   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".
 ---
 
 # protect-route — la garde vient du framework, jamais de l'action
 
+> 🧭 **Tu es arrivé ici directement ? Charge aussi `nodefony-dev`** — il porte la conduite
+> commune (par où commencer, comment prouver que c'est fait) et les pièges qui coûtent une heure,
+> serveur comme front. Cette page-ci ne couvre QUE son geste.
+>
+> Et si une réponse te manque, elle est probablement INSTALLÉE : `rg` ne descend pas dans
+> `node_modules`, donc 70 pages de documentation y paraissent absentes. Une commande les lit, avec
+> la ligne exacte :
+> `node node_modules/@nodefony/devkit/skills/nodefony-dev/scripts/docs.mjs <termes>`.
+
 > ⚖️ **La confiance n'exclut pas le contrôle.** Une route qui « répond 403 quand je teste » n'est
 > pas une route protégée. Le seul juge est un appel avec **trois identités**.
 
@@ -33,6 +43,36 @@ Les deux se combinent : la zone décide **qui entre**, la garde décide **qui fa
 async list() { … }
 ```
 
+### Une zone peut exiger un rôle PAR DÉFAUT
+
+Une zone qui ne liste que des authentificateurs exige une **identité**, rien de plus : toute route
+qu'elle couvre est ouverte à **n'importe quel compte connecté**. Pour un espace d'administration,
+c'est un défaut ouvert — l'oubli d'une garde s'y solde par une fuite.
+
+```ts
+areas: {
+  backoffice: {
+    pattern: "^/back-office",
+    authenticators: ["session"],
+    roles: ["ROLE_ADMIN"],   // ← exigé par défaut dans toute la zone
+  },
+}
+```
+
+Les rôles sont en **OU** — un seul suffit — et la hiérarchie s'applique. Un refus est un **403**
+(connecté, mais pas autorisé), jamais un 401. Omettre la clé ne change rien au comportement
+existant.
+
+C'est un **défaut**, pas une exclusivité : une route qui porte sa propre garde (`@IsGranted`)
+décide seule, ce qui laisse exister une page réservée à un autre rôle dans une zone par ailleurs
+fermée. Écris donc le rôle **une fois sur la zone**, et ne le répète sur une route que pour en
+exiger un autre.
+
+🔴 **`@RequireScope` seul ne remplace PAS un rôle.** Un scope dit ce qu'une **clé déléguée** peut
+faire en ton nom ; sur une session humaine il n'a aucune prise. Une route gardée par un scope seul
+n'a donc rien décidé de ton identité — et le rôle de sa zone continue de s'appliquer, ce qui est
+voulu. Les deux axes se cumulent, ils ne se substituent pas.
+
 🔴 **Le `pattern` d'une zone est un PRÉFIXE, jamais la liste des routes du jour.**
 
 ```ts
@@ -45,6 +85,19 @@ 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.
 
+## 🔴 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
+écriture est protégée ». Ces en-têtes sont posés par un NAVIGATEUR ; un programme qui parle en HTTP
+n'en envoie aucun, et la défense de provenance le laisse alors passer — c'est son rôle, elle
+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.
+
 ## 🔴 Ce qu'il ne faut jamais écrire
 
 ```ts
@@ -83,10 +136,14 @@ travail. **Le geste juste est de DÉCLARER l'origine**, jamais de retirer la dé
 
 ```ts
 csrf: {
+  secret: ctx.env.NF_CSRF_SECRET, // la clé que la config pose DÉJÀ — ne la perds pas
   trustedOrigins: ["https://partenaire.example"],
 }
 ```
 
+⚠️ Ce bloc est fait pour être recopié dans `nodefony/config/security.ts`. Recopié **sans** son
+`secret`, il coupe le jeton anti-falsification — en silence, tests verts.
+
 🔴 `@CsrfExempt`, `csrf.enabled: false`, ou couper le contrôle de provenance **résolvent le
 symptôme et ouvrent l'application** : n'importe quel site peut alors faire poster le navigateur
 d'une personne connectée, à son insu et avec ses droits.
@@ -170,9 +227,16 @@ marche, les tests passent, et le diff ne contient aucune faute visible — il co
 | `@BypassFirewall`, `@Anonymous`                     | la route sort de sa zone                       |
 | `anonymous` ajouté aux authentificateurs d'une zone | toute la zone devient publique                 |
 | `rateLimit: { enabled: false }`                     | le bourrage de mots de passe redevient gratuit |
+| `areaRoleExempt: true` sur une route                | elle perd le rôle par défaut de sa zone        |
 
 Relever un **seuil** est un réglage légitime. L'**éteindre** ne l'est pas.
 
+Le dernier de la liste est le plus trompeur : son nom dit bien ce qu'il fait — il **retire** le rôle
+exigé par la zone —, mais il n'installe rien à la place. Posé sur une route qui ne décide pas
+elle-même de son autorisation, il la rend accessible à tout compte connecté, sans erreur ni trace.
+Il est **réservé aux mécanismes internes du framework** ; ce que tu veux, quand une route de ta zone
+doit être plus ouverte, c'est déclarer le rôle qu'elle exige vraiment.
+
 ## Prouver — trois identités, pas une
 
 Le refus d'un anonyme est gratuit : n'importe quelle zone le donne. Ce qui prouve, c'est le
@@ -186,6 +250,20 @@ npx nodefony security:user:add            # un témoin SANS le rôle
 npx nodefony inspect routes --json        # la garde est-elle sur la route qu'on croit ?
 ```
 
+## Utilisateurs et droits : tout existe, n'improvise RIEN
+
+Chaque geste ci-dessus a sa référence INSTALLÉE — une recherche ordinaire ne la voit pas, `rg`
+ne descendant pas dans `node_modules` :
+
+- **Zones, authentificateurs, CSRF, CORS, clés d'API** — `node_modules/@nodefony/security/docs/firewall.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`
+
+N'écris pas ton propre lecteur de session, ne teste pas l'appartenance à un rôle à la main, et
+n'insère jamais un utilisateur directement en base — le mot de passe passe par l'encodeur du
+framework.
+
 ## Voisins
 
 | Besoin                         | Skill                           |