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

package/dist/types/nodefony/src/Route.d.ts

@@ -2,10 +2,13 @@ import { HTTPMethod, SchemeType, ContextType } from "@nodefony/http";
 import type { IRoute } from "../interfaces/index.js";
 import type { RouteActionMeta } from "../decorators/routerDecorators.js";
 import Controller from "./Controller.js";
+import type { ControllerScope } from "./Controller.js";
 export interface ControllerConstructor {
     new (...args: any[]): Controller;
     /** Prototype de la classe — porte les métadonnées des actions (`@Param`…). */
     readonly prototype: Controller;
+    /** Portée de l'instance (`Controller.scope`, statique hérité). */
+    readonly scope?: ControllerScope;
 }
 /**
  * Options pour la configuration d'une route.
@@ -62,9 +65,25 @@ export interface RouteOptions {
      * exception qui se justifie. Défaut `false`.
      */
     areaRoleExempt?: boolean;
+    /**
+     * Route de REPLI : elle ne sert un chemin que si aucune autre route ne le
+     * sert, quel que soit l'ordre de déclaration.
+     *
+     * Le routeur retient la première route déclarée qui correspond ; un repli à
+     * variable (`/nodefony/{page}`, la page d'une application monopage) déclaré
+     * tôt capturerait donc les routes de même forme des modules chargés après
+     * lui — sans erreur ni avertissement. Les replis sont rangés après toutes les
+     * autres routes, dans leur ordre relatif, à la construction de l'index :
+     * aucun coût par requête. Défaut `false`.
+     */
+    fallback?: boolean;
 }
 export interface RouteRequirements {
     domain?: string | string[] | undefined;
+    /**
+     * Transport exigé : `https`/`wss` refuse un canal clair, `http`/`ws` un
+     * canal chiffré — 403 sinon. Proto transmis par un proxy de confiance compris.
+     */
     scheme?: SchemeType | undefined;
     methods?: HTTPMethod[] | HTTPMethod | undefined;
     protocol?: string | undefined;
@@ -77,7 +96,6 @@ declare class Route implements IRoute {
     classMethod?: string | undefined;
     prefix?: string | undefined;
     method?: HTTPMethod | undefined;
-    schemes?: SchemeType | undefined;
     pattern?: RegExp | undefined;
     variables: string[];
     /**
@@ -115,6 +133,8 @@ declare class Route implements IRoute {
      * pas son rôle par défaut. Cf {@link RouteOptions.areaRoleExempt}.
      */
     areaRoleExempt: boolean;
+    /** Route de repli, résolue après toutes les autres. Cf {@link RouteOptions.fallback}. */
+    fallback: boolean;
     /**
      * P2.9 — Cache mémoïsé : l'action attend-elle le **flux brut** du body
      * (`@Body({ stream:true })`) ? `undefined` = pas encore calculé (résolu au 1er

package/dist/types/nodefony/src/SecurityApiController.d.ts

@@ -0,0 +1,17 @@
+import type { OutgoingHttpHeaders } from "node:http";
+import Controller from "./Controller.js";
+/**
+ * Base des contrôleurs d'authentification (`/nodefony/security/api/*`) : toute
+ * réponse JSON part en `Cache-Control: no-store`.
+ *
+ * Ces réponses portent une identité, un jeton, un secret affiché une seule
+ * fois (clé API, secret TOTP, codes de récupération) ou leur refus. Un cookie
+ * ou un en-tête dans la requête n'empêche pas un cache partagé de STOCKER la
+ * réponse (RFC 9111 §3) ; RFC 6749 §5.1 exige `no-store` sur un jeton. La règle
+ * vit ici, une fois : une action ajoutée à un contrôleur héritier ne peut pas
+ * l'oublier. Un en-tête passé par l'action garde la priorité.
+ */
+declare abstract class SecurityApiController extends Controller {
+    renderJson(obj: unknown, status?: string | number, headers?: OutgoingHttpHeaders): ReturnType<Controller["renderJson"]>;
+}
+export default SecurityApiController;

package/dist/types/nodefony/src/docsReader.d.ts

@@ -74,15 +74,18 @@ export declare function parseFrontmatter(raw: string): {
  * @param modulePath - chemin disque du module (`Module.path`).
  * @returns liste triée (vide si le dossier `docs/` est absent).
  */
-export declare function listModuleDocs(modulePath: string, withGit?: boolean): Promise<DocSummary[]>;
+export declare function listModuleDocs(modulePath: string, withGit?: boolean, frameworkRepository?: boolean): Promise<DocSummary[]>;
 /**
- * Comptage rapide des docs (`*.md`) d'un module — readdir seul, sans lire/parser
- * ni `git`. Pour les KPI/overview (`docsCount`) où seul le nombre importe.
+ * Comptage des docs SERVIES d'un module, sans `git` — pour les KPI/overview
+ * (`docsCount`) où seul le nombre importe. Le frontmatter est lu : le compte
+ * suit la même portée (`publish`) que la liste, sinon le KPI annonce des pages
+ * que l'onglet Docs refuse d'ouvrir.
  *
  * @param modulePath - chemin disque du module (`Module.path`).
- * @returns nombre de fichiers `.md` dans `<modulePath>/docs/` (0 si absent).
+ * @param frameworkRepository - vrai dans le dépôt du framework (pages `core` servies).
+ * @returns nombre de pages servies dans `<modulePath>/docs/` (0 si absent).
  */
-export declare function countModuleDocs(modulePath: string): Promise<number>;
+export declare function countModuleDocs(modulePath: string, frameworkRepository?: boolean): Promise<number>;
 /**
  * Lit une doc module par slug : frontmatter + corps markdown brut.
  *
@@ -91,7 +94,7 @@ export declare function countModuleDocs(modulePath: string): Promise<number>;
  *
  * @returns `null` si slug invalide ou fichier absent.
  */
-export declare function readModuleDoc(modulePath: string, slug: string): Promise<DocContent | null>;
+export declare function readModuleDoc(modulePath: string, slug: string, frameworkRepository?: boolean): Promise<DocContent | null>;
 /** Où un terme cherché apparaît, et la ligne qui le porte. */
 export interface DocSearchMatch {
     /** Ligne (1-indexée) dans le CORPS markdown, frontmatter retiré. */
@@ -167,6 +170,7 @@ export interface DocSearchResult {
 export declare function searchModuleDocs(targets: readonly DocSearchTarget[], query: string, options?: {
     limit?: number | undefined;
     perDoc?: number;
+    frameworkRepository?: boolean;
 }): Promise<DocSearchResult>;
 /**
  * Symboles TS exportés d'un module + descriptions TSDoc, lus depuis

package/dist/types/nodefony/src/idempotency.d.ts

@@ -42,18 +42,20 @@ export type IdempotencyVerdict = {
 export declare function resolveIdempotencyKey(alsKey: unknown, header: unknown): string | undefined;
 /**
  * Identité stable pour **scoper** le cache d'idempotence (anti-IDOR : un
- * utilisateur ne doit jamais rejouer la clé d'un autre). Dérivée de l'utilisateur
- * (`username` / `identifier` / `id`, sans coupler le framework au contrat `IUser`),
- * avec fallback sur l'`userId` de l'ALS. `null` = pas d'identité fiable → l'appelant
- * n'utilise PAS le cache (jamais de partage cross-identité).
+ * utilisateur ne doit jamais rejouer la clé d'un autre) : l'`identifier` de
+ * l'utilisateur AUTHENTIFIÉ de la requête. `null` = pas d'identité fiable →
+ * l'appelant n'utilise PAS le cache (jamais de partage cross-identité).
  *
- * ⚠️ Doit renvoyer la MÊME valeur quel que soit le transport pour un même compte
- * (sinon une mutation tentée en WS puis rejouée en HTTP ne dédoublonnerait pas).
- * D'où la dérivation de `request.user` (posé UNIFORMÉMENT dans l'ALS par les deux
- * transports), et NON de `getUserId()` seul (le firewall HTTP ne le pose pas
- * toujours — vécu S4).
+ * La décision « authentifié ? » est celle du cœur
+ * (`RequestContext.getAuthenticatedUser`) : l'anonyme d'une zone `anonymous`
+ * rend `null`. Lire l'`identifier` de l'utilisateur BRUT faisait partager à
+ * tous les visiteurs anonymes la même identité (`anon.`), donc le même cache.
+ *
+ * Même valeur quel que soit le transport pour un même compte : le pare-feu HTTP
+ * et le pont realtime posent tous deux le jeton et l'utilisateur dans l'ALS —
+ * une mutation tentée en WS puis rejouée en HTTP se dédoublonne.
  */
-export declare function resolveIdentity(user: unknown): string | null;
+export declare function resolveIdentity(): string | null;
 /**
  * Empreinte SHA-256 du **payload** d'une requête (parties sérialisables : nom de
  * route + params + corps). Comparée par le store à l'empreinte mémorisée pour une

package/dist/types/nodefony/src/loginPage.d.ts

@@ -0,0 +1,144 @@
+import { type ILoginPageDescription, type ILoginPageHero, type LoginPageLayout, type LoginPageSkin } from "nodefony";
+/** Fournisseur prêt à afficher : libellé, adresse d'autorisation, icône. */
+export interface ILoginPageViewProvider {
+    /** Ce que l'utilisateur lit : la marque d'un compte grand public, sinon « Compte de l'organisation ». */
+    readonly label: string;
+    /** Petite ligne sous le libellé (`SSO · Keycloak`), ou `null` pour une marque grand public. */
+    readonly caption: string | null;
+    readonly href: string;
+    /** Symbole du sprite d'icônes (`i-key`, `m-github`), quand `image` est nulle. */
+    readonly icon: string;
+    /** Image réglée par l'application (`oauth2.providers.<nom>.icon`), ou `null`. */
+    readonly image: string | null;
+}
+/**
+ * Données du gabarit de la page de connexion — tout ce qu'il affiche, déjà
+ * validé : aucune valeur de la requête n'y entre sans être filtrée.
+ */
+export interface ILoginPageView {
+    /** Nom affiché de l'application. */
+    readonly brand: string;
+    /** Titre de la carte et de l'onglet. */
+    readonly title: string;
+    /** Ligne sous le titre, ou `null` pour la phrase déduite des moyens proposés. */
+    readonly subtitle: string | null;
+    /** Panneau d'illustration : `null` = vitrine Nodefony, `false` = marque seule. */
+    readonly hero: ILoginPageHero | false | null;
+    /** Pied de page affiché ? */
+    readonly footer: boolean;
+    readonly logo: string;
+    readonly skin: LoginPageSkin;
+    readonly layout: LoginPageLayout;
+    /** Fond de page décoré par l'habillage (`<body data-backdrop>`). */
+    readonly backdrop: boolean;
+    /** Thème imposé par `?theme=`, `null` = celui du système. */
+    readonly theme: "light" | "dark" | null;
+    /** Fournisseurs et passkey avant le formulaire (au moins l'un des deux proposé). */
+    readonly ssoFirst: boolean;
+    readonly password: boolean;
+    /** Bouton passkey rendu (masqué tant que le script n'a pas constaté le navigateur). */
+    readonly passkey: boolean;
+    /**
+     * Aucun moyen de connexion : ni formulaire, ni passkey, ni fournisseur
+     * opérationnel. La page le dit au lieu de rendre une carte vide.
+     */
+    readonly empty: boolean;
+    /** Ligne sous le titre : celle de la configuration, sinon déduite des moyens proposés. */
+    readonly lead: string;
+    readonly providers: readonly ILoginPageViewProvider[];
+    /** Destination après connexion, déjà passée par `safeRedirectPath`. */
+    readonly from: string;
+    /**
+     * Sélecteur d'aperçu (habillage, mise en page), ou `null` : rendu seulement
+     * en développement ET quand `loginPage.previewPicker` le demande.
+     */
+    readonly picker: ILoginPagePicker | null;
+    /**
+     * Message d'échec d'une connexion par fournisseur (`?reason=` posé par le
+     * callback OAuth), ou `null`. Texte FIXE : la raison reçue n'est jamais
+     * affichée, et une annulation (`access_denied`) n'en produit aucun.
+     */
+    readonly notice: string | null;
+    readonly styleHref: string;
+    /** Feuille de l'habillage, chargée après {@link styleHref}, ou `null`. */
+    readonly skinHref: string | null;
+    /** Feuille de l'application, chargée après {@link styleHref}, ou `null`. */
+    readonly stylesheetHref: string | null;
+    readonly scriptHref: string;
+    readonly logoHref: string;
+    /** Nonce CSP de la requête, posé sur le `<script>`. */
+    readonly nonce: string;
+}
+/** Le sélecteur d'aperçu : les choix possibles et ceux affichés. */
+export interface ILoginPagePicker {
+    readonly skins: readonly LoginPageSkin[];
+    readonly layouts: readonly LoginPageLayout[];
+    /** Chemin prévenu avant chaque rechargement (`loginPage.previewHook`), ou `null`. */
+    readonly hook: string | null;
+}
+/** Ce que la requête apporte à la page. */
+export interface ILoginPageRequest {
+    /** Valeur brute de `?from=`. */
+    readonly from: unknown;
+    /** Valeur brute de `?theme=`. */
+    readonly theme: unknown;
+    /** Valeur brute de `?reason=`, posée par le callback OAuth sur un échec. */
+    readonly reason?: unknown;
+    /** Valeur brute de `?skin=`, lue seulement quand {@link preview} est vrai. */
+    readonly skin?: unknown;
+    /** Valeur brute de `?layout=`, lue seulement quand {@link preview} est vrai. */
+    readonly layout?: unknown;
+    /**
+     * Aperçu autorisé (développement) : `?skin=` et `?layout=` remplacent la
+     * configuration le temps de la requête. Faux en production, où ils sont ignorés.
+     */
+    readonly preview?: boolean;
+    readonly nonce: string;
+    /** Nom de l'application, quand la configuration ne donne pas de titre. */
+    readonly projectName: string;
+    /** Empreinte des fichiers servis, ajoutée à leur adresse (cache). */
+    readonly assetsVersion: string;
+}
+/**
+ * Mémoïse une ressource chargée de façon asynchrone : le SUCCÈS est gardé, un
+ * ÉCHEC est oublié. Garder la promesse rejetée figerait la panne — la page
+ * répondrait 500 jusqu'au redémarrage, même une fois le fichier corrigé.
+ *
+ * @param load - charge la ressource
+ * @returns la fonction qui la rend, chargée une seule fois tant qu'elle réussit
+ */
+export declare function keepSuccess<T>(load: () => Promise<T>): () => Promise<T>;
+/** Feuille, script et logo de la page, servis sous {@link LOGIN_PAGE_ASSETS_BASE}. */
+export declare const LOGIN_PAGE_ASSET_FILES: {
+    readonly style: "login.css";
+    readonly script: "login.js";
+    readonly logo: "nodefony-logo.svg";
+};
+/** Libellé d'un fournisseur d'organisation : ce qu'il ouvre, pas son logiciel. */
+export declare const ORGANIZATION_ACCOUNT_LABEL = "Compte de l'organisation";
+/** Annonce d'une page sans aucun moyen de connexion. */
+export declare const LOGIN_PAGE_EMPTY_NOTICE = "Aucun moyen de connexion n'est disponible pour le moment. Pr\u00E9venez l'administrateur du site.";
+/**
+ * Prépare les données du gabarit à partir de la description de la page
+ * (security) et de la requête.
+ *
+ * Fonction pure : `from` repasse par `safeRedirectPath` (un chemin hors de
+ * l'origine retombe sur `/`), `theme` n'accepte que `light` ou `dark`,
+ * `skin` et `layout` ne sont lus qu'en aperçu et contre leur liste fermée.
+ *
+ * @param page - description rendue par `authFlow.describeLoginPage()`
+ * @param request - valeurs de la requête, non filtrées
+ * @returns les données du gabarit
+ */
+export declare function buildLoginPageView(page: ILoginPageDescription, request: ILoginPageRequest): ILoginPageView;
+/**
+ * Gabarit Eta de la page de connexion par défaut (balisage F03, feuille
+ * `nodefony/login.css`, script `nodefony/login.js`).
+ *
+ * En chaîne dans le code : un `.eta` posé à côté ne serait pas publié
+ * (`files` du paquet = `dist`, `docs`). Compilé une fois par processus.
+ * Tout passe par `<%= %>` (échappé) ; aucune sortie brute. L'icône
+ * d'empreinte (`i-finger`) reprend `IconFingerprint` de Tabler Icons (MIT),
+ * celle du bouton de Studio : les deux écrans montrent le même geste.
+ */
+export declare const LOGIN_PAGE_TEMPLATE = "<!doctype html>\n<html lang=\"fr\"<% if (it.theme) { %> data-theme=\"<%= it.theme %>\"<% } %>>\n  <head>\n    <meta charset=\"utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n    <meta name=\"color-scheme\" content=\"dark light\" />\n    <meta name=\"robots\" content=\"noindex\" />\n    <title><%= it.title %> \u2014 <%= it.brand %></title>\n    <link rel=\"icon\" href=\"<%= it.logoHref %>\" type=\"image/svg+xml\" />\n<% if (!it.theme) { %>\n    <script nonce=\"<%= it.nonce %>\">try{var t=localStorage.getItem(\"nf-login-theme\");if(t===\"light\"||t===\"dark\")document.documentElement.dataset.theme=t}catch(e){}</script>\n<% } %>\n    <link rel=\"stylesheet\" href=\"<%= it.styleHref %>\" />\n<% if (it.skinHref) { %>\n    <link rel=\"stylesheet\" href=\"<%= it.skinHref %>\" />\n<% } %>\n<% if (it.stylesheetHref) { %>\n    <link rel=\"stylesheet\" href=\"<%= it.stylesheetHref %>\" />\n<% } %>\n    <script type=\"module\" src=\"<%= it.scriptHref %>\" nonce=\"<%= it.nonce %>\"></script>\n  </head>\n  <body data-skin=\"<%= it.skin %>\" data-layout=\"<%= it.layout %>\"<% if (it.backdrop) { %> data-backdrop<% } %><% if (it.ssoFirst) { %> data-sso-first<% } %>>\n    <svg width=\"0\" height=\"0\" style=\"position: absolute\" aria-hidden=\"true\">\n      <symbol id=\"i-user\" viewBox=\"0 0 24 24\"><circle cx=\"12\" cy=\"8\" r=\"3.5\" /><path d=\"M5.5 20a6.5 6.5 0 0 1 13 0\" /></symbol>\n      <symbol id=\"i-lock\" viewBox=\"0 0 24 24\"><rect x=\"5\" y=\"10.5\" width=\"14\" height=\"10\" rx=\"2\" /><path d=\"M8.5 10.5V7.5a3.5 3.5 0 0 1 7 0v3\" /></symbol>\n      <symbol id=\"i-eye\" viewBox=\"0 0 24 24\"><path d=\"M2.5 12S6 5.5 12 5.5 21.5 12 21.5 12 18 18.5 12 18.5 2.5 12 2.5 12Z\" /><circle cx=\"12\" cy=\"12\" r=\"2.8\" /></symbol>\n      <symbol id=\"i-arrow\" viewBox=\"0 0 24 24\"><path d=\"M5 12h14M13 6l6 6-6 6\" /></symbol>\n      <symbol id=\"i-key\" viewBox=\"0 0 24 24\"><circle cx=\"8\" cy=\"15\" r=\"3.8\" /><path d=\"M10.8 12.2 19.5 3.5M16.5 6.5l2.5 2.5M14 9l2 2\" /></symbol>\n      <symbol id=\"i-check\" viewBox=\"0 0 24 24\"><path d=\"M5 12.5l4.5 4.5L19 7.5\" /></symbol>\n      <symbol id=\"i-finger\" viewBox=\"0 0 24 24\"><path d=\"M18.9 7a8 8 0 0 1 1.1 5v1a6 6 0 0 0 .8 3\" /><path d=\"M8 11a4 4 0 0 1 8 0v1a10 10 0 0 0 2 6\" /><path d=\"M12 11v2a14 14 0 0 0 2.5 8\" /><path d=\"M8 15a18 18 0 0 0 1.8 6\" /><path d=\"M4.9 19a22 22 0 0 1-.9-7v-1a8 8 0 0 1 12-6.95\" /></symbol>\n      <symbol id=\"i-sun\" viewBox=\"0 0 24 24\"><circle cx=\"12\" cy=\"12\" r=\"4\" /><path d=\"M12 2.5v2M12 19.5v2M4.6 4.6l1.4 1.4M18 18l1.4 1.4M2.5 12h2M19.5 12h2M4.6 19.4 6 18M18 6l1.4-1.4\" /></symbol>\n      <symbol id=\"i-moon\" viewBox=\"0 0 24 24\"><path d=\"M20 14.5A8 8 0 0 1 9.5 4a8 8 0 1 0 10.5 10.5Z\" /></symbol>\n      <symbol id=\"i-shield\" viewBox=\"0 0 24 24\"><path d=\"M12 3l7.5 3v5.5c0 4.6-3.2 8-7.5 9.5-4.3-1.5-7.5-4.9-7.5-9.5V6z\" /></symbol>\n      <symbol id=\"m-github\" viewBox=\"0 0 16 16\"><path d=\"M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27s1.36.09 2 .27c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8Z\" /></symbol>\n    </svg>\n    <header class=\"nf-strip\">\n      <div class=\"nf-strip-brand\"><img class=\"nf-logo\" src=\"<%= it.logo %>\" alt=\"\" /><%= it.brand %></div>\n    </header>\n    <div class=\"nf-layout\">\n      <aside class=\"nf-hero\" aria-hidden=\"true\">\n        <div class=\"nf-hero-brand\"><img class=\"nf-logo\" src=\"<%= it.logo %>\" alt=\"\" /><%= it.brand %></div>\n<% if (it.hero === null) { %>\n        <div class=\"nf-home\">\n          <img\n            class=\"nf-home-logo\"\n            src=\"<%= it.logoHref %>\"\n            alt=\"\"\n          />\n          <h2>Le framework Node.js fullstack</h2>\n          <p class=\"sub\">\n            Temps r\u00E9el natif \u00B7 d\u00E9veloppement agentic-ready \u00B7 socle TypeScript\n            isomorphe\n          </p>\n          <p class=\"sig\">\n            Une action de contr\u00F4leur. Deux transports. La m\u00EAme session, la m\u00EAme\n            s\u00E9curit\u00E9, le m\u00EAme code.\n          </p>\n          <ul class=\"badges\">\n            <li class=\"agentic\">Agentic ready</li>\n            <li>Node.js \u2265 24.14</li>\n            <li>TypeScript strict</li>\n            <li>ESM only</li>\n            <li>Licence Apache 2.0</li>\n          </ul>\n          <div\n            class=\"install\"\n            role=\"img\"\n            aria-label=\"Commande d'installation : npx nodefony create app\"\n          >\n            <span class=\"p\">$</span><span>npx nodefony create app</span>\n          </div>\n          <div class=\"features\">\n            <div class=\"feature\">\n              <span class=\"ic\"\n                ><svg\n                  viewBox=\"0 0 24 24\"\n                  fill=\"none\"\n                  stroke=\"currentColor\"\n                  stroke-width=\"2\"\n                  stroke-linecap=\"round\"\n                  stroke-linejoin=\"round\"\n                  aria-hidden=\"true\"\n                >\n                  <polygon\n                    points=\"13 2 3 14 12 14 11 22 21 10 12 10 13 2\"\n                  /></svg\n              ></span>\n              <h3>Temps r\u00E9el natif</h3>\n              <p>\n                Le WebSocket n'est pas un ajout : m\u00EAme pipeline, m\u00EAme table de\n                routes, m\u00EAme s\u00E9curit\u00E9 que le HTTP.\n              </p>\n            </div>\n            <div class=\"feature\">\n              <span class=\"ic\"\n                ><svg\n                  viewBox=\"0 0 24 24\"\n                  fill=\"none\"\n                  stroke=\"currentColor\"\n                  stroke-width=\"2\"\n                  stroke-linecap=\"round\"\n                  stroke-linejoin=\"round\"\n                  aria-hidden=\"true\"\n                >\n                  <path d=\"M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z\" />\n                  <path d=\"m9 12 2 2 4-4\" /></svg\n              ></span>\n              <h3>S\u00E9curit\u00E9 par conception</h3>\n              <p>\n                Pare-feu applicatif par zones, Zero Trust, CSRF Fetch Metadata,\n                sessions hybrides, WebAuthn.\n              </p>\n            </div>\n            <div class=\"feature\">\n              <span class=\"ic\"\n                ><svg\n                  viewBox=\"0 0 24 24\"\n                  fill=\"none\"\n                  stroke=\"currentColor\"\n                  stroke-width=\"2\"\n                  stroke-linecap=\"round\"\n                  stroke-linejoin=\"round\"\n                  aria-hidden=\"true\"\n                >\n                  <rect x=\"3\" y=\"3\" width=\"7\" height=\"7\" rx=\"1\" />\n                  <rect x=\"14\" y=\"3\" width=\"7\" height=\"7\" rx=\"1\" />\n                  <rect x=\"3\" y=\"14\" width=\"7\" height=\"7\" rx=\"1\" />\n                  <rect x=\"14\" y=\"14\" width=\"7\" height=\"7\" rx=\"1\" /></svg\n              ></span>\n              <h3>DI & modules</h3>\n              <p>\n                Injection de d\u00E9pendances par d\u00E9corateurs, modules autonomes,\n                configuration valid\u00E9e au boot.\n              </p>\n            </div>\n            <div class=\"feature\">\n              <span class=\"ic\"\n                ><svg\n                  viewBox=\"0 0 24 24\"\n                  fill=\"none\"\n                  stroke=\"currentColor\"\n                  stroke-width=\"2\"\n                  stroke-linecap=\"round\"\n                  stroke-linejoin=\"round\"\n                  aria-hidden=\"true\"\n                >\n                  <circle cx=\"12\" cy=\"12\" r=\"9\" />\n                  <path\n                    d=\"M3 12h18M12 3c2.5 2.6 4 5.7 4 9s-1.5 6.4-4 9c-2.5-2.6-4-5.7-4-9s1.5-6.4 4-9z\"\n                  /></svg\n              ></span>\n              <h3>Socle isomorphe</h3>\n              <p>\n                Le m\u00EAme paquet c\u00F4t\u00E9 serveur et c\u00F4t\u00E9 navigateur : client temps\n                r\u00E9el, r\u00E8gles et types \u00E9crits une fois.\n              </p>\n            </div>\n          </div>\n        </div>\n        <small>Propuls\u00E9 par Nodefony</small>\n<% } else if (it.hero) { %>\n        <div class=\"nf-home\">\n          <h2><%= it.hero.heading %></h2>\n<% if (it.hero.text) { %>\n          <p class=\"sub\"><%= it.hero.text %></p>\n<% } %>\n        </div>\n<% } %>\n      </aside>\n      <main class=\"nf-stage\" data-nf-login data-from=\"<%= it.from %>\">\n        <button type=\"button\" class=\"nf-theme\" data-theme-toggle aria-label=\"Basculer entre th\u00E8me clair et th\u00E8me sombre\"><svg class=\"nf-icon t-sun\" aria-hidden=\"true\"><use href=\"#i-sun\" /></svg><svg class=\"nf-icon t-moon\" aria-hidden=\"true\"><use href=\"#i-moon\" /></svg></button>\n        <section class=\"nf-card\" aria-labelledby=\"nf-title\">\n          <div class=\"nf-head\">\n            <div class=\"nf-brand\"><img class=\"nf-logo\" src=\"<%= it.logo %>\" alt=\"\" /><%= it.brand %></div>\n            <h1 id=\"nf-title\"><%= it.title %></h1>\n            <p class=\"nf-sub\" id=\"nf-sub\"><%= it.lead %></p>\n          </div>\n          <div class=\"nf-body\">\n<% if (it.password) { %>\n            <ol class=\"nf-steps\" aria-label=\"\u00C9tapes\">\n              <li data-tab=\"identifier\" aria-current=\"step\">Identifiant</li>\n              <li data-tab=\"password\">Mot de passe</li>\n              <li data-tab=\"mfa\" hidden>V\u00E9rification</li>\n            </ol>\n            <form data-step=\"identifier\">\n              <div class=\"nf-field\">\n                <label for=\"nf-username\">Identifiant ou adresse e-mail</label>\n                <div class=\"nf-input\">\n                  <svg class=\"nf-icon\" aria-hidden=\"true\"><use href=\"#i-user\" /></svg>\n                  <input id=\"nf-username\" name=\"username\" autocomplete=\"username\" autocapitalize=\"none\" spellcheck=\"false\" required />\n                </div>\n              </div>\n              <button class=\"nf-btn primary\" type=\"submit\">Continuer<svg class=\"nf-icon\" aria-hidden=\"true\"><use href=\"#i-arrow\" /></svg></button>\n            </form>\n            <form data-step=\"password\" hidden>\n              <!-- Compte de l'\u00E9tape pr\u00E9c\u00E9dente, masqu\u00E9 : le gestionnaire de mots de passe\n                   associe le mot de passe \u00E0 CE compte (HTML, jeton \u00AB username \u00BB). -->\n              <input name=\"username\" autocomplete=\"username\" hidden readonly tabindex=\"-1\" />\n              <div class=\"nf-account\">\n                <span class=\"nf-avatar\" aria-hidden=\"true\"></span><span class=\"who\"></span>\n                <button type=\"button\" class=\"nf-link\" data-go=\"identifier\">Changer</button>\n              </div>\n              <div class=\"nf-field\">\n                <div class=\"nf-label-row\"><label for=\"nf-password\">Mot de passe</label></div>\n                <div class=\"nf-input\">\n                  <svg class=\"nf-icon\" aria-hidden=\"true\"><use href=\"#i-lock\" /></svg>\n                  <input id=\"nf-password\" name=\"password\" type=\"password\" autocomplete=\"current-password\" required />\n                  <button type=\"button\" class=\"nf-reveal\" data-reveal aria-label=\"Afficher le mot de passe\" aria-pressed=\"false\"><svg class=\"nf-icon\" aria-hidden=\"true\"><use href=\"#i-eye\" /></svg></button>\n                </div>\n              </div>\n              <button class=\"nf-btn primary\" type=\"submit\">Se connecter<svg class=\"nf-icon\" aria-hidden=\"true\"><use href=\"#i-arrow\" /></svg></button>\n            </form>\n            <form data-step=\"mfa\" hidden>\n              <div class=\"nf-field\">\n                <label id=\"nf-otp-label\">Code \u00E0 6 chiffres</label>\n                <div class=\"nf-otp\" role=\"group\" aria-labelledby=\"nf-otp-label\">\n                  <input inputmode=\"numeric\" maxlength=\"1\" autocomplete=\"one-time-code\" aria-label=\"Chiffre 1\" /><input inputmode=\"numeric\" maxlength=\"1\" aria-label=\"Chiffre 2\" /><input inputmode=\"numeric\" maxlength=\"1\" aria-label=\"Chiffre 3\" /><input inputmode=\"numeric\" maxlength=\"1\" aria-label=\"Chiffre 4\" /><input inputmode=\"numeric\" maxlength=\"1\" aria-label=\"Chiffre 5\" /><input inputmode=\"numeric\" maxlength=\"1\" aria-label=\"Chiffre 6\" />\n                </div>\n              </div>\n              <p class=\"nf-hint\">Le code affich\u00E9 par votre application d'authentification.</p>\n              <button class=\"nf-btn primary\" type=\"submit\">V\u00E9rifier</button>\n            </form>\n<% } %>\n<% if (it.password || it.passkey) { %>\n            <div data-step=\"authenticated\" hidden>\n              <div class=\"nf-done\" role=\"status\">\n                <span class=\"ring\" aria-hidden=\"true\"><svg class=\"nf-icon\"><use href=\"#i-check\" /></svg></span>\n                <strong>Session ouverte</strong><span class=\"dest\"></span>\n                <span class=\"nf-progress\" aria-hidden=\"true\"><span></span></span>\n              </div>\n            </div>\n<% } %>\n<% if (it.providers.length > 0 || it.passkey) { %>\n            <div data-alt>\n<% if (it.password) { %>\n              <div class=\"nf-or\">ou</div>\n<% } %>\n              <div class=\"nf-alt\">\n<% if (it.passkey) { %>\n                <button type=\"button\" class=\"nf-btn span\" data-passkey hidden><svg class=\"nf-icon\" aria-hidden=\"true\"><use href=\"#i-finger\" /></svg>Passkey / empreinte digitale</button>\n<% } %>\n<% it.providers.forEach(function (provider) { %>\n                <a class=\"nf-btn\" href=\"<%= provider.href %>\"><% if (provider.image) { %><img class=\"nf-icon\" src=\"<%= provider.image %>\" alt=\"\" /><% } else { %><svg class=\"<%= provider.icon === 'm-github' ? 'nf-mark' : 'nf-icon' %>\" aria-hidden=\"true\"><use href=\"#<%= provider.icon %>\" /></svg><% } %><% if (provider.caption) { %><span class=\"nf-label\"><%= provider.label %><small><%= provider.caption %></small></span><% } else { %><%= provider.label %><% } %></a>\n<% }) %>\n              </div>\n            </div>\n<% } %>\n            <div class=\"nf-message\" aria-live=\"polite\" data-message><% if (it.empty) { %><p class=\"nf-alert\" role=\"alert\"><span class=\"code\">\u2014</span><span>Aucun moyen de connexion n'est disponible pour le moment. Pr\u00E9venez l'administrateur du site.</span></p><% } else if (it.notice) { %><p class=\"nf-alert\" role=\"alert\"><span class=\"code\">SSO</span><span><%= it.notice %></span></p><% } %></div>\n<% if (it.password || it.passkey) { %>\n            <noscript><p class=\"nf-hint\">Cette page a besoin de JavaScript pour vous connecter.</p></noscript>\n<% } %>\n          </div>\n        </section>\n<% if (it.picker) { %>\n        <form class=\"nf-picker\" method=\"get\" data-preview-picker<% if (it.picker.hook) { %> data-preview-hook=\"<%= it.picker.hook %>\"<% } %> aria-label=\"Aper\u00E7u de la page (d\u00E9veloppement)\">\n          <input type=\"hidden\" name=\"from\" value=\"<%= it.from %>\" />\n          <label>Habillage <select name=\"skin\"><% it.picker.skins.forEach(function (skin) { %><option value=\"<%= skin %>\"<% if (skin === it.skin) { %> selected<% } %>><%= skin %></option><% }) %></select></label>\n          <label>Mise en page <select name=\"layout\"><% it.picker.layouts.forEach(function (layout) { %><option value=\"<%= layout %>\"<% if (layout === it.layout) { %> selected<% } %>><%= layout %></option><% }) %></select></label>\n          <noscript><button type=\"submit\">Appliquer</button></noscript>\n        </form>\n<% } %>\n<% if (it.footer) { %>\n        <div class=\"nf-foot\">\n          <ul class=\"nf-facts\" aria-label=\"Protection de la session\">\n            <li><svg class=\"nf-icon\" aria-hidden=\"true\"><use href=\"#i-shield\" /></svg>cookie HttpOnly</li>\n            <li><svg class=\"nf-icon\" aria-hidden=\"true\"><use href=\"#i-shield\" /></svg>anti-CSRF</li>\n            <li><svg class=\"nf-icon\" aria-hidden=\"true\"><use href=\"#i-shield\" /></svg>CSP stricte</li>\n          </ul>\n          <a class=\"nf-powered\" href=\"https://github.com/nodefony/nodefony-core\" rel=\"noopener noreferrer\"><img class=\"nf-logo nf-logo-mono\" src=\"<%= it.logoHref %>\" alt=\"\" />Propuls\u00E9 par Nodefony</a>\n        </div>\n<% } %>\n      </main>\n    </div>\n  </body>\n</html>\n";

package/dist/types/nodefony/src/requireAuthentication.d.ts

@@ -0,0 +1,29 @@
+import type { IAuthenticationRequirement } from "../decorators/routerDecorators.js";
+/** Vue minimale d'une session : ses métadonnées (contrat de `readSessionAuthentication`). */
+interface IMetaBagReader {
+    getMetaBag(key: string): unknown;
+}
+/**
+ * Ce qui manque à une session pour satisfaire un `@RequireAuthentication` —
+ * fonction PURE : la session, l'exigence et l'heure lui sont données.
+ *
+ * Lit `authAt`/`amr` par `readSessionAuthentication` (contrat du cœur), jamais
+ * le sac de métadonnées à la main. Une session absente, ou qui ne porte pas ces
+ * métadonnées, est REFUSÉE : ne pas savoir n'est pas une preuve.
+ *
+ * @param session - la session de la requête, ou `null`.
+ * @param requirement - l'exigence figée de la route.
+ * @param now - l'heure de la décision, en millisecondes epoch.
+ * @returns la cause du refus en clair, ou `null` quand la session suffit.
+ */
+export declare function authenticationShortfall(session: IMetaBagReader | null, requirement: IAuthenticationRequirement, now: number): string | null;
+/**
+ * Le défi d'un refus « step-up » (RFC 9470 §3) : le schéma de session du
+ * pare-feu, l'erreur normée et l'âge maximal quand la route en fixe un.
+ * `error_description` reste en ASCII, sans guillemet (RFC 6750 §3).
+ *
+ * @param requirement - l'exigence de la route.
+ * @returns la valeur de `WWW-Authenticate`.
+ */
+export declare function stepUpChallenge(requirement: IAuthenticationRequirement): string;
+export {};

package/dist/types/nodefony/src/routeSchema.d.ts

@@ -0,0 +1,112 @@
+import type { Readable } from "node:stream";
+import type { IStandardSchemaV1, InferSchemaOutput, MaybePromise } from "nodefony";
+/**
+ * Le schéma d'une route : un Standard Schema par partie de l'entrée (Zod,
+ * Valibot, ArkType…). Chaque partie est facultative ; une partie déclarée est
+ * validée AVANT l'action, une partie omise est servie brute.
+ *
+ * @example
+ * ```ts
+ * \@Post("/posts", { schema: { body: z.object({ title: z.string() }) } })
+ * create(input: RouteInput<{ body: typeof createPost }>) {
+ *   return this.createResource(input.body);
+ * }
+ * ```
+ */
+export interface IRouteSchema {
+    /** Variables de route (`/posts/{id}`). */
+    readonly params?: IStandardSchemaV1 | undefined;
+    /** Query (`?page=2`) — celle du chemin INVOQUÉ sur le pont WebSocket. */
+    readonly query?: IStandardSchemaV1 | undefined;
+    /**
+     * Corps DÉCODÉ par le transport : JSON, formulaire, ou octets (`Uint8Array`
+     * — un `Buffer` HTTP en est un). Jamais re-sérialisé pour être validé.
+     */
+    readonly body?: IStandardSchemaV1 | undefined;
+    /** En-têtes (clés en minuscules) ; sur WebSocket, ceux du handshake. */
+    readonly headers?: IStandardSchemaV1 | undefined;
+}
+/**
+ * Options de route propres aux DÉCORATEURS (`@route`, `@Get`, `@Post`…) : elles
+ * décrivent l'entrée de l'action et se rangent sur sa méthode. Une route créée
+ * par programme (`Router.createRoute`) ne les accepte pas — elle n'a pas de
+ * décorateur pour les ranger, et les ignorer en silence mentirait.
+ */
+export interface IRouteSchemaOptions {
+    /**
+     * Schéma de l'entrée de l'action. Les parties déclarées sont validées AVANT
+     * l'action (422 sinon), et l'action reçoit un argument unique, `RouteInput`.
+     * Exclusif des décorateurs de paramètre (`@Body`…) sur la même action : le
+     * mélange est refusé au démarrage.
+     */
+    schema?: IRouteSchema | undefined;
+    /**
+     * L'action lit le corps en FLUX (`input.body` est le flux brut de la
+     * requête) : le pipeline ne le lit pas en mémoire — gros envoi sans pic de
+     * mémoire. Remplace `@Body({ stream: true })` pour une action à schéma : il
+     * EXIGE un `schema` (sans lui, le flux ne serait livré à personne) et exclut
+     * `schema.body`. Défaut `false`.
+     */
+    bodyStream?: boolean | undefined;
+}
+/** Parties de l'entrée d'une route, dans l'ordre où elles sont validées. */
+export type RoutePart = keyof IRouteSchema;
+/** Variables de route brutes (une valeur par défaut n'est pas forcément une chaîne). */
+export type RawRouteParams = Readonly<Record<string, unknown>>;
+/** Query brute. */
+export type RawRouteQuery = Readonly<Record<string, unknown>>;
+/** En-têtes bruts, clés en minuscules. */
+export type RawRouteHeaders = Readonly<Record<string, string | string[] | undefined>>;
+/** Type d'une partie : la sortie de son schéma s'il est déclaré, la forme brute sinon. */
+type RoutePartOf<S extends IRouteSchema, K extends RoutePart, Raw> = S[K] extends IStandardSchemaV1 ? InferSchemaOutput<S[K]> : Raw;
+/**
+ * L'argument UNIQUE d'une action à schéma : les quatre apports de la
+ * requête, toujours présents — validés et typés par le schéma quand il les
+ * déclare, servis bruts et typés large sinon.
+ *
+ * @typeParam S - le schéma de la route.
+ * @typeParam Stream - `true` quand la route déclare `bodyStream: true` :
+ *   `body` est alors le flux brut de la requête, jamais lu en mémoire.
+ */
+export type RouteInput<S extends IRouteSchema = IRouteSchema, Stream extends boolean = false> = {
+    params: RoutePartOf<S, "params", RawRouteParams>;
+    query: RoutePartOf<S, "query", RawRouteQuery>;
+    body: Stream extends true ? Readable | undefined : RoutePartOf<S, "body", unknown>;
+    headers: RoutePartOf<S, "headers", RawRouteHeaders>;
+};
+/** L'entrée brute d'une action, avant validation. */
+export type RawRouteInput = {
+    params: unknown;
+    query: unknown;
+    body: unknown;
+    headers: unknown;
+};
+/**
+ * Valide l'entrée d'une action contre son schéma — synchrone tant que chaque
+ * validateur l'est, asynchrone seulement si l'un d'eux rend une promesse.
+ *
+ * Les quatre parties sont toutes validées avant de conclure : un échec rend
+ * en une fois TOUTES les anomalies, chacune rattachée à sa partie. La valeur
+ * d'une partie validée est remplacée par la SORTIE de son schéma (valeurs par
+ * défaut, coercitions) ; la valeur reçue n'est ni copiée ni sérialisée — des
+ * octets décodés par le transport arrivent tels quels au validateur.
+ *
+ * @param schema - le schéma de la route.
+ * @param raw - l'entrée brute, mutée en place (objet propre à la requête).
+ * @returns l'entrée validée, ou sa promesse.
+ * @throws SchemaValidationError (statut 422) quand une partie est invalide —
+ *   de façon synchrone, ou par la promesse rendue.
+ */
+export declare function validateRouteInput(schema: IRouteSchema, raw: RawRouteInput): MaybePromise<RawRouteInput>;
+/**
+ * Refuse, au démarrage, un schéma de route mal formé : partie inconnue (une
+ * faute de frappe — `bodies` — serait sinon ignorée sans un mot), ou valeur
+ * qui n'implémente pas Standard Schema (un appelant JavaScript peut passer
+ * n'importe quoi).
+ *
+ * @param schema - le schéma déclaré.
+ * @param routeName - la route, nommée dans l'erreur.
+ * @throws BootConfigurationError sur la première faute trouvée.
+ */
+export declare function assertRouteSchemaShape(schema: unknown, routeName: string): asserts schema is IRouteSchema;
+export {};