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

package/skills/nodefony-authentication/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: nodefony-authentication
+metadata:
+  version: 1.0.0
+description: >
+  Établit QUI est l'utilisateur d'une application Nodefony par ce que le framework sert déjà —
+  page /login et son habillage, client NodefonyLogin, route me, second facteur, connexion
+  récente, retour sûr après connexion, fournisseurs (Keycloak, GitHub), jeton d'un programme —
+  au lieu de le réécrire. À charger AVANT d'écrire un formulaire de connexion, une redirection
+  après login, une lecture de session ou un appel d'API depuis un script. Ce qu'un utilisateur connecté a le DROIT de faire → nodefony-protect-route.
+  Déclencheurs : "ajoute une page de connexion", "formulaire de login", "se connecter", "second
+  facteur", "TOTP", "MFA", "exiger une connexion récente", "ramener l'utilisateur après la
+  connexion", "?from=", "qui est connecté", "déconnexion", "Keycloak", "se connecter avec
+  GitHub", "mon script doit appeler l'API sans formulaire", "jeton d'accès", "202 au login".
+---
+
+# authentication — la connexion est servie, elle ne s'écrit pas
+
+> 🧭 **Tu es arrivé ici directement ? Charge aussi `nodefony-dev`** — il porte la conduite
+> commune (par où commencer, comment prouver que c'est fait). Cette page-ci ne couvre QUE la
+> connexion.
+>
+> Une réponse te manque ? Elle est probablement INSTALLÉE — `rg` ne descend pas dans
+> `node_modules`. `node node_modules/@nodefony/devkit/skills/nodefony-dev/scripts/docs.mjs <termes>`
+> la trouve, avec la ligne exacte.
+
+> **Maintenance** : vérité courante, jamais un journal. Éditer en place ; historique = `git log`.
+
+## 1. Quand m'utiliser / quand passer la main
+
+| Besoin                                                                | Skill                           |
+| --------------------------------------------------------------------- | ------------------------------- |
+| Se connecter, se déconnecter, savoir qui est connecté, second facteur | ici                             |
+| Réserver une route à un rôle, renvoyer l'anonyme vers `/login` (zone) | `nodefony-protect-route`        |
+| La ZONE qui reçoit un programme (`machine`, `partner`), un partenaire | `nodefony-protect-route`        |
+| Une page qui affiche l'état de connexion en temps réel                | `nodefony-add-realtime-channel` |
+| Vérifier à l'écran que la connexion aboutit                           | `nodefony-browser`              |
+
+## 2. 🔴 Ce qui est DÉJÀ servi — n'écris ni page, ni controller de compte
+
+Une application qui charge `@nodefony/security` sert tout ceci :
+
+| Ce qui existe                                                 | Ce que ça fait                                                                                   |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `GET /login`                                                  | la page : identifiant, mot de passe, second facteur, passkey, boutons des fournisseurs           |
+| `POST /nodefony/security/api/auth/login`                      | `{username, password}` → `200` + cookie ; **`202` = second facteur requis, PAS encore connecté** |
+| `POST /nodefony/security/api/auth/login/totp`                 | `{code}` — le code à 6 chiffres (ou un code de récupération) qui achève une connexion en `202`   |
+| `GET /nodefony/security/api/auth/me`                          | **TOUJOURS `200`** : `{ user: null }` sans session, sinon `{ user: { id, identifier, roles } }`  |
+| `POST /nodefony/security/api/auth/logout`                     | idempotent ; rend l'adresse de déconnexion du fournisseur quand la session venait de lui         |
+| `/nodefony/security/api/totp/{enroll,confirm,disable,status}` | le titulaire connecté active ou retire SON second facteur                                        |
+
+- 🔴 **Qui est connecté, côté serveur — deux lignes à retenir, rien d'autre :**
+
+  ```ts
+  this.user; // dans un controller
+  RequestContext.getAuthenticatedUser(); // partout ailleurs (service, hook)
+  ```
+
+  Les deux rendent l'utilisateur connecté, ou `null`. C'est la règle UNIQUE du framework : elle
+  part du jeton que pose le pare-feu, et ses variantes en dérivent — `RequestContext.getUserId()`
+  pour l'`id` seul, `authenticatedUser()` de `@nodefony/user` pour le compte typé `IUser`. Ne lis
+  jamais la session à la main, et pas `RequestContext.getUser()`, qui rend aussi l'anonyme.
+
+- `me` ne teste jamais une session par son code HTTP : il n'y a pas de `401` à attendre. Le
+  champ est `identifier`, pas `username`. Le rechargement d'une page (F5) se restaure avec `me`,
+  jamais avec un état gardé côté navigateur.
+- Ces routes sont montées par `@nodefony/framework`, sous un chemin qui porte le nom de
+  `security` : c'est le piège qui fait conclure qu'elles n'existent pas.
+- Aucune commande CLI n'active le second facteur d'un compte : c'est le titulaire, connecté, qui
+  l'enrôle (`enroll` rend `{secretBase32, otpauthUri}`, `confirm` le valide par un premier code).
+
+## 3. Habiller la page `/login` — sans la réécrire
+
+Quatre niveaux, du plus léger au plus lourd ; prends le premier qui suffit. La section
+`security.loginPage` est **stricte** : une clé mal orthographiée arrête le démarrage.
+
+| Niveau | Geste                                                                                    |
+| ------ | ---------------------------------------------------------------------------------------- |
+| 1      | `skin` (neuf habillages) et `layout`                                                     |
+| 2      | `title`, `heading`, `subtitle`, `logo`, `hero`, `footer`                                 |
+| 3      | `stylesheet` : TA feuille, qui redéfinit les variables `--nf-login-*`                    |
+| 4      | `template` : un gabarit `.eta` à toi — dernier recours, il ne suit plus les mises à jour |
+
+`path` (défaut `/login`) déplace la page ; **toute** redirection du framework la suit, y compris
+l'échec d'un fournisseur quand `oauth2.failureRedirect` est omis. N'écris donc jamais `"/login"`
+en dur dans ton code : `loginPagePath(from)` le compose. Détail :
+`node_modules/@nodefony/security/docs/login-page.md`.
+
+❌ Recopier la feuille de style de la page, ou un nouveau `.eta` pour changer trois couleurs :
+la page cesse de suivre le framework, et le niveau 1 ou 3 suffisait.
+
+## 4. Une connexion dans TON front — `NodefonyLogin`, jamais `fetch`
+
+Le plus souvent, un **bouton** suffit : un lien vers `loginPagePath(from)` (`nodefony/client`),
+qui compose `/login?from=<page>`. La page servie fait le reste.
+
+Un formulaire à toi se bâtit sur `NodefonyLogin` (`nodefony/client`), qui conduit mot de passe,
+second facteur, passkey, fournisseurs et blocage — par la liaison de TON moteur :
+
+| Moteur  | Liaison               | Import             |
+| ------- | --------------------- | ------------------ |
+| React   | `useNodefonyLogin`    | `nodefony/react`   |
+| Vue     | `useNodefonyLogin`    | `nodefony/vue`     |
+| Svelte  | `nodefonyLogin`       | `nodefony/svelte`  |
+| Angular | `injectNodefonyLogin` | `nodefony/angular` |
+
+Elle expose l'état (`getState`, `subscribe`) et les gestes : `login`, `submitMfaCode`,
+`loginWithPasskey`, `loadProviders`, `startProvider`, `me`, `logout`. **Suis l'adresse que rend
+`logout()`** : sinon la session du fournisseur (Keycloak) reste ouverte. Détail :
+`node_modules/nodefony/docs/client.md` (§ NodefonyLogin).
+
+🔴 **Jamais de `fetch` ni d'`axios` vers `/nodefony/security/api/auth/*`** : le `202`, le
+blocage après échecs, le jeton anti-falsification et la passkey sont autant de cas qu'un
+`fetch` écrit à la main oublie — et chacun est une faille ou une panne.
+
+## 5. Le `202` est un DÉFI, pas un succès
+
+```json
+{ "mfaRequired": true, "methods": ["totp"] }
+```
+
+La session ne porte alors qu'un défi en attente : **l'utilisateur n'est pas connecté**. La liste
+`methods` est **ouverte** — d'autres méthodes viendront ; teste l'appartenance
+(`methods.includes(MFA_METHOD_TOTP)`), jamais l'égalité du tableau. Le code s'envoie à
+`login/totp` (ou `submitMfaCode` avec la liaison).
+
+## 6. Ramener l'utilisateur après la connexion — `safeRedirectPath`
+
+Le renvoi de l'anonyme vers la page se déclare sur la ZONE (`entryPoint`, skill
+`nodefony-protect-route`) ; il arrive avec `?from=<page>`. Au retour :
+
+```ts
+import { safeRedirectPath } from "nodefony"; // aussi dans nodefony/client
+const destination = safeRedirectPath(from); // "/" par défaut
+```
+
+🔴 **Un `from` ne se suit JAMAIS sans `safeRedirectPath`.** C'est la seule garde contre la
+redirection ouverte : `?from=https://site-piege.example` ou `?from=//site-piege.example`
+enverrait ton utilisateur ailleurs, connecté. N'écris pas ta propre garde
+(`startsWith("/")`, expression régulière d'URL) : `//hôte` commence par `/`, et c'est
+exactement le contournement qu'elle laisse passer.
+
+## 7. Exiger une connexion RÉCENTE, ou deux facteurs, avant une action sensible
+
+Une étiquette sur la route — n'écris PAS la vérification :
+
+```ts
+import { Post, RequireAuthentication } from "@nodefony/framework";
+
+@Post("/transfers")
+@RequireAuthentication({ maxAge: 300, amr: ["otp"] }) // < 5 min, avec le code TOTP
+transfer() { … }
+```
+
+- `maxAge` en secondes, `amr` = moyens exigés (tous présents) ; l'un ou l'autre suffit.
+- Refus = **401** dont le `WWW-Authenticate` porte `error="insufficient_user_authentication"`
+  (RFC 9470) : « reconnecte-toi », pas « interdit ». Évalué APRÈS `@IsGranted` : un rôle absent
+  reste un 403.
+- Pour LIRE l'information (l'afficher, la journaliser) : `readSessionAuthentication(this.session)`
+  (`nodefony`) → `{ at, amr }` ou `null`. Jamais pour décider à la place de l'étiquette.
+
+| Connexion par       | `amr`            |
+| ------------------- | ---------------- |
+| mot de passe        | `["pwd"]`        |
+| mot de passe + TOTP | `["pwd", "otp"]` |
+| passkey             | `["pop"]`        |
+| fournisseur         | `[]`             |
+
+- Session sans ces métadonnées (ouverte avant, ou altérée) : l'étiquette **refuse**, elle ne devine pas.
+- ❌ `session.getMetaBag("amr")`, ❌ un `if (Date.now() - auth.at > …)` écrit dans l'action : tu
+  recopies une garde que le framework porte, avec ses refus normés.
+- La route doit être sous une zone `session` : hors zone, aucune session n'est reprise et
+  l'étiquette refuse tout le monde.
+
+## 8. Les routes de connexion restent sous le contrôle anti-falsification
+
+`bypassFirewall` sort une route de l'authentification, **pas** du contrôle CSRF : une route de
+connexion à toi reste soumise au jeton. Seul `@CsrfExempt` l'en dispense — et il ouvrirait la
+connexion à n'importe quel site (connexion forcée). Garde le jeton ; `NodefonyLogin` le porte.
+
+## 9. 🔴 En production, un mot de passe en HTTP clair est refusé (`403`)
+
+Avant toute vérification, et la page affiche « doit passer par HTTPS ». Derrière un proxy qui
+termine TLS, déclare-le dans `trustProxy` (config de `@nodefony/http`) — sinon **toutes** les
+connexions échouent. `security.allowInsecureCredentials` n'est pas la correction : elle accepte
+le clair.
+
+## 10. Se connecter par un fournisseur (Keycloak, GitHub…)
+
+Le fournisseur se déclare dans `security.oauth2.providers` ; ses identifiants viennent de
+l'environnement (`NF_KEYCLOAK_*`, `GITHUB_CLIENT_ID`…). Deux commandes, faute de quoi on
+diagnostique un `401` à l'aveugle :
+
+```bash
+npx nodefony security:oauth:doctor [-p keycloak]                 # découverte, URL de retour, secret
+npx nodefony security:keycloak:realm [--write|--check|--apply]   # realm dérivé de TA config
+```
+
+`--write` écrit le realm (rôles, audiences) dans `docker/keycloak/import/`, `--check` sort en 1
+s'il ne suit plus la configuration, `--apply` pose le thème de connexion sur le Keycloak de
+développement. Un `401` avec un jeton Keycloak valide sur une API, c'est presque toujours
+l'audience absente : `--write`, puis réimport. Détail :
+`node_modules/@nodefony/security/docs/keycloak.md`.
+
+## 11. Un PROGRAMME ne remplit jamais le formulaire
+
+Un script, une tâche planifiée, un agent n'ont ni navigateur ni cookie : ils présentent une
+preuve à chaque appel, `Authorization: Bearer …`.
+
+| Preuve                          | L'obtenir                                                           |
+| ------------------------------- | ------------------------------------------------------------------- |
+| clé d'API opaque (`nf_…`)       | `POST /nodefony/security/api/keys` (session d'administration)       |
+| jeton signé par l'application   | `npx nodefony security:mcp:token [compte] --scope … --ttl … --json` |
+| jeton Keycloak (client machine) | `requestClientCredentialsToken` de `@nodefony/security`             |
+
+❌ Un `POST` vers la route de login depuis un script, ou un cookie de session recopié dans sa
+configuration : le premier fait stocker un mot de passe au programme, le second expire et casse
+en silence. La zone qui reçoit ces preuves (`machine`, `partner`, `stateless: true`) et la
+commande qui l'éprouve (`app:partner:call`) → skill `nodefony-protect-route`. Détail :
+`node_modules/@nodefony/security/docs/api-keys.md`, `obtenir-un-jeton.md`.
+
+## 12. Prouver que c'est fait
+
+```bash
+# la page est servie, avec ton habillage (lis son <title>)
+curl -s localhost:5151/login
+# me répond 200 sans session — teste user, pas le code
+curl -s localhost:5151/nodefony/security/api/auth/me
+# le retour refuse une destination étrangère : les deux doivent rendre "/"
+node -e 'import("nodefony").then(({safeRedirectPath:s})=>console.log(s("//evil.example"),s("https://evil.example")))'
+```
+
+Une action « connexion récente » se prouve par trois sessions : mot de passe seul → refusée ;
+mot de passe + TOTP → servie ; la même, ouverte depuis plus longtemps que le délai → refusée.

package/skills/nodefony-browser/SKILL.md

@@ -178,7 +178,7 @@ pour un élément contre son fond. La sonde ne connaît donc aucun sélecteur
 composants.
 
 Réglages par variables d'environnement : `NF_BROWSER_BASE`, `NF_BROWSER_PAGE`, `NF_BROWSER_EXPECT`,
-`NF_BROWSER_LOGIN`, `NF_BROWSER_USER`, `NF_BROWSER_PASSWORD`, `NF_BROWSER_PROBES`
+`NF_BROWSER_LOGIN`, `NF_BROWSER_USER`, `NF_BROWSER_PASSWORD`, `NF_BROWSER_WHOAMI`, `NF_BROWSER_PROBES`
 (`libellé=sélecteur`, séparés par des virgules), `NF_BROWSER_FAMILIES`, `NF_BROWSER_WIDTHS`,
 `NF_BROWSER_SEUIL_LOURD`, `NF_BROWSER_SEUIL_LENT`, `NF_BROWSER_ACTIONS`, `NF_BROWSER_FULLPAGE`. Le détail vit dans l'en-tête de chaque script.
 
@@ -194,8 +194,9 @@ NF_BROWSER_ACTIONS="Nouvelle commande|voir:Moyen de paiement" node node_modules/
 
 Grammaire : `verbe:cible[=valeur]`, séquence séparée par `|`, verbe facultatif (`clic` par défaut),
 cible cherchée d'abord comme **texte visible** puis comme sélecteur CSS. Verbes : `clic` · `double`
-· `droit` (clic droit) · `survol` · `saisir:Nom=valeur` · `touche:Enter` · `voir` · `defiler:600`
-· `attendre`.
+· `droit` (clic droit) · `survol` · `saisir:Nom=valeur` · `choisir:Liste=valeur` (une option d'un
+`<select>`, par sa valeur ou son libellé ; la cible peut être le libellé qui l'enveloppe) ·
+`touche:Enter` · `voir` · `defiler:600` · `attendre`.
 
 - 🔴 **`voir` plutôt qu'un clic pour amener dans la vue** : sur un formulaire, le texte d'une
   question est un `label` — cliquer dessus coche la case qu'il décrit, et tu observes alors un écran
@@ -207,9 +208,12 @@ cible cherchée d'abord comme **texte visible** puis comme sélecteur CSS. Verbe
   faite sur un écran qu'on n'a pas ouvert est pire qu'aucune mesure.
 
 **`NF_BROWSER_LOGIN` n'a pas de défaut** : c'est le chemin du formulaire de connexion de **ton**
-application. Il n'en existe pas d'universel, et deviner enverrait la sonde sur une page inexistante,
-où elle mesurerait un écran d'erreur en croyant s'être authentifiée. Sans lui, un identifiant posé
-fait s'arrêter la sonde avec un message — jamais une mesure fausse.
+application. Une application qui charge `@nodefony/security` sert le sien à **`/login`** (sauf
+`security.loginPage.path` ou `enabled: false`) : pose donc `NF_BROWSER_LOGIN=/login`. La sonde ne
+le devine pas pour autant — deviner l'enverrait, ailleurs, sur une page inexistante, où elle
+mesurerait un écran d'erreur en croyant s'être authentifiée. Sans lui, un identifiant posé fait
+s'arrêter la sonde avec un message — jamais une mesure fausse. Une session reprise se prouve par
+`/nodefony/security/api/auth/me` (`NF_BROWSER_WHOAMI`) : un `{ user: null }` la déclare périmée.
 
 Les sondes de couleur cherchent tes sélecteurs, pas ceux d'une bibliothèque : le thème est lu sur le
 `color-scheme` **calculé** (ce que le moteur applique) et sur `data-theme`. Si ton application marque
@@ -239,6 +243,20 @@ NF_BROWSER_STORAGE="ma-cle-de-theme=light" node .../scripts/inspect.mjs /
 Le champ `theme` de la sortie dit ce qui a été RÉELLEMENT appliqué. Vérifie-le : c'est ainsi qu'on
 sait qu'on a mesuré le bon écran.
 
+### Mesurer sur l'écran que tu veux — téléphone, bureau, grand écran
+
+La sonde mesure en 1 440 × 900 par défaut. Une page juste sur un bureau peut obliger à défiler pour
+atteindre son bouton sur un téléphone, ou flotter perdue sur un écran de 2 560 px :
+
+```bash
+NF_BROWSER_VIEWPORT=mobile-court NF_BROWSER_FAMILIES=pli node .../scripts/inspect.mjs /connexion "Se connecter"
+```
+
+Écrans nommés : `mobile` (390 × 844), `mobile-court` (375 × 667), `tablette` (820 × 1180),
+`bureau` (défaut), `large` (1 920 × 1080), `tres-large` (2 560 × 1440) — ou `LARGEURxHAUTEUR`.
+Sous 600 px de large, l'écran est émulé en **téléphone** (tactile, densité 2), pas seulement rétréci.
+Un nom inconnu est **refusé** (code 64). Le champ `viewport` de la sortie dit l'écran mesuré.
+
 ## Les familles de sondes — activables, jamais un mur de JSON
 
 Le socle ci-dessus sort toujours. Le reste s'active par famille, chacune rendant un **verdict**
@@ -248,15 +266,16 @@ Le socle ci-dessus sort toujours. Le reste s'active par famille, chacune rendant
 NF_BROWSER_FAMILIES=axe,perf,reseau node .../scripts/inspect.mjs /tableau-de-bord "Chiffre d affaires"
 ```
 
-| Famille      | Question à laquelle elle répond                                                                    |
-| ------------ | -------------------------------------------------------------------------------------------------- |
-| **`axe`**    | **Audit WCAG complet par `axe-core` — une centaine de règles, dont le contraste de TOUT le texte** |
-| `a11y`       | Étiquettes, noms accessibles, hiérarchie des titres, cibles < 24 px, arbre d'accessibilité         |
-| `rendu`      | Débordement horizontal, éléments hors viewport, polices RÉELLEMENT chargées                        |
-| `reseau`     | Requêtes, échecs, ressources lourdes et lentes, octets réellement transférés                       |
-| `perf`       | TTFB, FCP, LCP, CLS, tâches longues — verdict sur les seuils Web Vitals                            |
-| `stockage`   | Attributs des cookies et inventaire du Web Storage — **jamais les valeurs**                        |
-| `responsive` | Le débordement horizontal rejoué à plusieurs largeurs (`NF_BROWSER_WIDTHS`)                        |
+| Famille      | Question à laquelle elle répond                                                                       |
+| ------------ | ----------------------------------------------------------------------------------------------------- |
+| **`axe`**    | **Audit WCAG complet par `axe-core` — une centaine de règles, dont le contraste de TOUT le texte**    |
+| `a11y`       | Étiquettes, noms accessibles, hiérarchie des titres, cibles < 24 px, arbre d'accessibilité            |
+| `rendu`      | Débordement horizontal, éléments hors viewport, polices RÉELLEMENT chargées                           |
+| `reseau`     | Requêtes, échecs, ressources lourdes et lentes, octets réellement transférés                          |
+| `perf`       | TTFB, FCP, LCP, CLS, tâches longues — verdict sur les seuils Web Vitals                               |
+| `stockage`   | Attributs des cookies et inventaire du Web Storage — **jamais les valeurs**                           |
+| `responsive` | Le débordement horizontal rejoué à plusieurs largeurs (`NF_BROWSER_WIDTHS`)                           |
+| `pli`        | Faut-il défiler pour AGIR ? Le bouton principal face au bas de l'écran, la place du bloc qui le porte |
 
 `NF_BROWSER_FAMILIES=toutes` active tout ; un nom inconnu est **refusé** (code 64), jamais ignoré.
 Ce que chaque champ veut dire, comment lire un verdict, et **quand chaque famille se trompe** :
@@ -362,6 +381,26 @@ en bout : le message part-il, revient-il, et l'écran le reçoit-il ?
 > lui, vaut pour toute attente que tu écriras : tant qu'elle n'a pas échoué une fois, elle ne
 > discrimine rien.
 
+### Éprouver la REPRISE après une coupure réseau — `NF_BROWSER_CUT`
+
+```bash
+docker exec -e NF_BROWSER_CUT=5000:4000 mon-app-browser node /app/see-screen/watch.mjs /tableau-de-bord 25000
+```
+
+`<début>:<durée>` en millisecondes : le réseau tombe 5 s après l'ouverture de la page, revient 4 s
+plus tard. Chaque socket coupé sort avec `closedAt` et `closeCode` (1006, ce que voit un client
+qui perd le réseau), le bloc `cut` compte les réouvertures refusées pendant la coupure, et le
+socket rouvert montre ses frames : l'accueil, les abonnements rejoués, leur acquittement, puis le
+flux. C'est la seule preuve qu'une page qui perd le réseau **retrouve** ses données.
+
+- **Le serveur est prévenu** (fermeture 1000) : la connexion coupée ne reste pas à demi ouverte
+  chez lui. Une vraie perte de réseau, elle, ne le prévient pas. La sonde éprouve la reprise du
+  client, pas la détection d'un pair mort.
+- **Le relais Vite (`/_vite/`) n'est pas coupé** : son client de rechargement à chaud recharge la
+  page quand il retrouve le serveur. Vous observeriez une page neuve, pas sa reprise.
+- **Les `ERR_INTERNET_DISCONNECTED` de la console pendant la coupure sont attendus.**
+- Une valeur malformée est refusée (code 64), jamais ignorée.
+
 ## Piloter le socket de bout en bout — `socket.mjs`
 
 `watch.mjs` regarde le trafic d'une page ; celui-ci **conduit** : il ouvre un socket temps réel
@@ -387,13 +426,12 @@ Le protocole du fil (les quatre formes de frame), la lecture de chaque verdict
 <!-- prettier-ignore -->
 | Contrainte | Ce qui arrive sinon |
 | --- | --- |
-| Joindre l'app par **`host.docker.internal`** | `localhost` désigne le CONTENEUR, pas ta machine. Et si tu as activé `domainCheck`, ajoute ce nom aux `trustedHosts` en développement : sinon la barrière répond **`421`** alors que le réseau passe. |
+| Joindre l'app par **`host.docker.internal`** | `localhost` désigne le CONTENEUR, pas ta machine. Ce nom est dans les `trustedHosts` de développement d'une application générée (`nodefony.config.ts`, bloc http) ; sans lui, la page annonce ses assets en `127.0.0.1` — le conteneur — et, avec `domainCheck`, la barrière répond **`421`**. |
 | Passer par **HTTPS** | Le cookie de session est `secure` : sur une origine `http://` non-`localhost`, le navigateur le **jette**, et tout revient en **`401`** — ce qui se lit à tort comme un login qui rate. |
-| **Rien à poser** pour rendre Vite joignable | L'origine des assets se dérive du `Host` de ta requête : arriver par `host.docker.internal` suffit — l'allowlist Vite et le WebSocket du rechargement à chaud suivent le même nom, et ton poste reste servi sur `127.0.0.1` en même temps. |
+| Rien à poser pour **Vite** | Nodefony relaie Vite sur l'origine de la page (`/_vite/…`) : scripts, images et WebSocket du rechargement à chaud suivent l'hôte par lequel tu arrives, en HTTPS si la page l'est — pas de contenu mixte, un seul certificat. |
 
-Si la page annonce quand même `127.0.0.1` depuis le conteneur, c'est que le nom ne franchit pas
-`trustedHosts`, ou qu'une `publicOrigin` explicite est configurée dans `nodefony.config.ts` — un
-réglage durable gagne toujours sur une déduction.
+Si un script de la page vise encore `127.0.0.1:5173`, le framework installé précède le relais
+(`@nodefony/frontend` à mettre à jour) : les balises d'une version courante sont relatives.
 
 ## Pièges — chacun a déjà fait conclure faux
 
@@ -418,7 +456,13 @@ réglage durable gagne toujours sur une déduction.
 - **Une capture ne s'écrase pas.** Réutiliser un nom laisse l'ancienne image en place pendant que
   l'appel répond « OK » : tu lis un écran périmé. Les sondes horodatent — ne le contourne pas.
 - **Un état d'authentification sauvegardé peut être périmé** (session expirée, serveur redémarré).
-  Les sondes le constatent et refont le parcours plutôt que de mesurer l'écran de connexion.
+  Les sondes le PROUVENT avant de mesurer : `NF_BROWSER_WHOAMI` (défaut
+  `/nodefony/security/api/auth/me`) doit répondre 2xx SANS `{ user: null }` dans son corps (c'est
+  ainsi qu'il dit « anonyme »), sinon l'état est jeté, la reprise est
+  annoncée sur la sortie d'erreur et le parcours de connexion est rejoué. Attendre un renvoi vers le
+  formulaire ne suffisait pas : une page PUBLIQUE n'en fait jamais, et la sonde mesurait alors en
+  anonyme sans le dire. Application sans `@nodefony/security` : pointer `NF_BROWSER_WHOAMI` sur une
+  route qui rend 401/403 (ou `{ user: null }`) à un anonyme — ou le laisser vide, et la sonde se connecte à chaque fois.
 - **Chaque compte a SON état sauvegardé** (le fichier porte l'identifiant). C'est ce qui permet
   d'enchaîner deux sondes sous deux comptes — comparer ce que voit un administrateur et ce que voit
   un utilisateur ordinaire — sans que la seconde reprenne la session de la première. Sans cela on

package/skills/nodefony-browser/references/socket.md

@@ -36,10 +36,19 @@ Deux frames servent de repères :
 
 ### `welcome`
 
-`receivedAfterMs`, canaux, méthodes, identité. **S'il ne vient jamais** (code de retour 65), les trois
-suspects, dans l'ordre : le chemin du endpoint est faux ; la page n'est pas authentifiée (donner
-`NF_BROWSER_USER` + `NF_BROWSER_LOGIN`) ; l'`Origin` de la page est refusé par le serveur. Le
-réseau qui « passe » n'innocente aucun des trois.
+`verdict`, `receivedAfterMs`, canaux, méthodes, identité. **S'il ne vient jamais** (code de retour
+65), la sortie dit lequel des deux cas :
+
+- **`REFUSÉ AU HANDSHAKE`** — le serveur a répondu autre chose que `101` : la socket ne s'est jamais
+  ouverte, et la sonde le rend tout de suite avec `status`, `afterMs` et la `browserReason` du
+  navigateur (la page ne voit qu'une fermeture `1006` ; le statut, seul le navigateur le connaît).
+  `401` : la page n'est pas authentifiée (donner `NF_BROWSER_USER` + `NF_BROWSER_LOGIN`) ; `403` :
+  le compte n'a pas le rôle, ou l'`Origin` de la page est refusé ; `404` : le chemin du endpoint
+  est faux. Chromium ne nomme pas le code d'un `401` porteur de `WWW-Authenticate` (« HTTP
+  Authentication failed ») : la sonde le traduit.
+- **Rien sur la sortie standard, message « en 8000 ms »** — la socket s'est ouverte mais l'accueil
+  n'est jamais venu : l'endpoint n'est pas un endpoint temps réel Nodefony, ou le serveur ferme
+  après l'ouverture. Le réseau qui « passe » n'innocente rien.
 
 ### `subscription`
 

package/skills/nodefony-browser/references/sondes.md

@@ -164,6 +164,19 @@ pixels, ni tactile, ni `user-agent`. Une media query sur `pointer` ou `hover` ne
 capture PNG est prise AVANT cette famille, à la largeur d'origine : les débordements constatés ici
 ne s'y voient pas.
 
+## `pli` — les proportions, sur l'écran demandé
+
+Sur l'écran de `NF_BROWSER_VIEWPORT` : la hauteur de la page et le défilement (`scrollPx`), le
+débordement en largeur, l'**action principale** (`primary` : libellé, bas en pixels, `marginPx` =
+marge avant le bas de l'écran) et le **bloc** qui la porte (`frame` : taille, part de la largeur et
+de la hauteur de l'écran). `ALERTE` quand il faut défiler pour atteindre l'action, ou que la page
+déborde en largeur — un pied de page sous le pli n'est PAS une alerte.
+
+**Quand elle se trompe** : l'action principale est devinée — le plus GRAND bouton de validation
+visible (un bouton « retour » est aussi un `submit`, jamais le plus large). Sur une page à plusieurs
+formulaires, désigne-la : `NF_BROWSER_PRIMARY="#mon-bouton"`. Le bloc est le plus grand ancêtre de
+l'action resté plus étroit que l'écran : sur une page sans carte, c'est une colonne, pas un cadre.
+
 ## Lire un verdict sans se faire piéger
 
 1. **`ALERTE` n'est pas « cassé »** — c'est « mérite un regard ». Le détail dit lequel.

package/skills/nodefony-browser/scripts/audit.mjs

@@ -19,6 +19,7 @@
  * `@env` NF_BROWSER_LOGIN chemin du formulaire de connexion — aucun défaut deviné
  * `@env` NF_BROWSER_USER identifiant ; sans lui, aucune authentification n'est tentée
  * `@env` NF_BROWSER_PASSWORD mot de passe associé
+ * `@env` NF_BROWSER_COLOR_SCHEME `light` ou `dark` — posé au MOTEUR, seul réglage que l'onglet de Lighthouse reçoit ; sans lui, le thème du système
  * `@env` NF_BROWSER_CATEGORIES catégories à jouer, séparées par des virgules (défaut : toutes celles que ce Lighthouse connaît)
  * `@env` NF_BROWSER_FORMFACTOR `desktop` (défaut) ou `mobile` — un score de performance ne veut RIEN dire sans son appareil
  * `@env` NF_BROWSER_SEUIL_AUDIT score en deçà duquel un audit est retenu, en pourcentage (défaut 90)
@@ -29,10 +30,22 @@
 import { createServer } from "node:net";
 import { mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { mkdtempSync } from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { BASE, LOGIN, PASSWORD, OUTPUT, USER } from "./lib/browser.mjs";
-import { summarizeLighthouse } from "./lib/probes.mjs";
+import {
+  BASE,
+  COLOR_SCHEME,
+  LOGIN,
+  PASSWORD,
+  OUTPUT,
+  USER,
+} from "./lib/browser.mjs";
+import {
+  browserOrder,
+  captureSlug,
+  colorSchemeLaunchArgs,
+  summarizeLighthouse,
+} from "./lib/probes.mjs";
 
 const PAGE = process.argv[2] ?? process.env.NF_BROWSER_PAGE ?? "/";
 const THRESHOLD = Number(process.env.NF_BROWSER_SEUIL_AUDIT ?? 90) / 100;
@@ -85,11 +98,40 @@ const port = await freePort();
 // Profil PERSISTANT : c'est lui qui porte la session entre notre connexion et
 // l'onglet que Lighthouse ouvrira. Jetable — il vit le temps de l'audit.
 const profile = mkdtempSync(path.join(tmpdir(), "nf-audit-"));
-const ctx = await chromium.launchPersistentContext(profile, {
-  channel: "chromium",
-  ignoreHTTPSErrors: true,
-  args: [`--remote-debugging-port=${port}`, "--no-sandbox"],
-});
+// Le navigateur se CONSTATE, dans le même ordre que les autres sondes
+// (`browserOrder` : celui du pilote, puis ceux DÉJÀ posés sur la machine). Un
+// `channel: "chromium"` codé en dur faisait échouer l'audit sur un poste où
+// seul Chrome est installé — là même où `inspect.mjs` passait.
+let ctx = null;
+const failures = [];
+for (const channel of browserOrder(process.env.NF_BROWSER_ENGINE)) {
+  try {
+    ctx = await chromium.launchPersistentContext(profile, {
+      channel,
+      ignoreHTTPSErrors: true,
+      // `null` : le pilote n'émule rien — c'est le réglage du moteur qui
+      // décide, le même pour la connexion et pour l'onglet de Lighthouse.
+      colorScheme: null,
+      args: [
+        `--remote-debugging-port=${port}`,
+        "--no-sandbox",
+        ...colorSchemeLaunchArgs(COLOR_SCHEME),
+      ],
+    });
+    break;
+  } catch (e) {
+    failures.push(`${channel} : ${String(e).split("\n")[0]}`);
+  }
+}
+if (!ctx) {
+  console.error(
+    `Aucun navigateur n'a répondu :\n  ${failures.join("\n  ")}\n` +
+      "Installer celui du pilote (npx playwright install chromium) ou viser un\n" +
+      "navigateur présent : NF_BROWSER_ENGINE=chrome (ou msedge).",
+  );
+  rmSync(profile, { recursive: true, force: true });
+  process.exit(69); // EX_UNAVAILABLE
+}
 
 try {
   const page = ctx.pages()[0] ?? (await ctx.newPage());
@@ -153,17 +195,24 @@ try {
   // vérifier — et à comparer dans le temps.
   mkdirSync(OUTPUT, { recursive: true });
   const stamp = new Date().toISOString().replace(/[:.]/gu, "-").slice(0, 19);
-  const slug = PAGE.replace(/\//gu, "-").replace(/^-/u, "") || "racine";
+  const slug = captureSlug(PAGE);
   const fullPath = path.join(OUTPUT, `lighthouse-${slug}-${stamp}.json`);
   writeFileSync(fullPath, JSON.stringify(lhr), "utf8");
 
   console.log(
     JSON.stringify(
-      { ...summarizeLighthouse(lhr, THRESHOLD), fullReport: fullPath },
+      {
+        ...summarizeLighthouse(lhr, THRESHOLD),
+        colorScheme: COLOR_SCHEME ?? "système",
+        fullReport: fullPath,
+      },
       null,
       2,
     ),
   );
 } finally {
   await ctx.close();
+  // Le profil est jetable : fermé, il ne sert plus à rien et resterait dans le
+  // dossier temporaire du système.
+  rmSync(profile, { recursive: true, force: true });
 }