nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/kernel/Module.d.ts

@@ -0,0 +1,326 @@
+import Kernel, { ServiceConstructor } from "./Kernel.js";
+import type { IModule, PackageJson } from "../types/IModule.js";
+export type { PackageJson } from "../types/IModule.js";
+import type { IMcpTool } from "../types/IMcpTool.js";
+import type { IKernel } from "../types/IKernel.js";
+import { JSONObject } from "../types/globals.js";
+import Service, { DefaultOptionsService } from "../Service.js";
+import Command from "../command/Command.js";
+import CliKernel from "./CliKernel.js";
+import Pdu, { Severity, Msgid, Message } from "../syslog/Pdu.js";
+import type { Controller } from "@nodefony/framework";
+export type TypeController<T> = new (...args: any[]) => T;
+/**
+ * Unité fonctionnelle de Nodefony — successeur direct du concept "Bundle" (Symfony / Nodefony JS).
+ *
+ * Un Module encapsule un domaine : routes, controllers, services, entités ORM, config, commandes
+ * CLI. Il est instancié par le {@link Kernel} au boot depuis le manifeste `config.modules`
+ * (résolu/chargé à `onPreRegister`). Hérite de {@link Service} → bénéficie du DI Container,
+ * EventEmitter, Syslog.
+ *
+ * Hooks lifecycle disponibles (méthodes prototype obligatoires, jamais arrow ni property init —
+ * `super()` tourne AVANT les initializers) :
+ * - `onKernelRegister()` — phase `onRegister` (modules s'auto-déclarent)
+ * - `onKernelBoot()` — phase `onBoot` (services bootés, connexions ouvertes)
+ * - `onKernelReady()` — phase `onReady` (cross-wiring inter-modules)
+ * - `init(kernel?)` — appelé par {@link Kernel.addModule}, équivalent constructeur async
+ *
+ * @example
+ * ```ts
+ * import { Module, services } from "nodefony";
+ *
+ * // `@services([...])` déclare les services du module ; l'ordre de la liste
+ * // n'importe pas (il est recalculé depuis les dépendances déclarées).
+ * @services([MyService])
+ * export class MyModule extends Module {
+ *   static readonly path: string = import.meta.url;
+ *
+ *   async onKernelBoot(): Promise<this> {
+ *     this.log("Module booted", "INFO");
+ *     return this;
+ *   }
+ * }
+ * ```
+ *
+ * @remarks Le constructor attache TOUJOURS **un** listener, indépendamment des hooks de la
+ *   sous-classe : un `prependOnceListener("onPreBoot")` qui charge le `package.json` du module
+ *   ({@link Module.setEvents}). Les hooks `onKernelRegister/Boot/Ready` ne sont attachés que si la
+ *   sous-classe les définit.
+ */
+declare class Module<TConfig = Record<string, unknown>> extends Service implements IModule {
+    commands: Record<string, Command>;
+    static controllers: Record<string, TypeController<Controller>>;
+    /**
+     * Criticité du module pour la **résilience de boot** (Phase 3). `true` (défaut)
+     * = un échec/timeout d'un de ses hooks lifecycle interrompt le boot **en
+     * production** (le pod crashe → l'orchestrateur le redémarre, cloud-native) et
+     * émet un WARNING **en développement** (le serveur démarre quand même). `false`
+     * = fail-soft partout (le module est optionnel : un échec n'empêche jamais le
+     * boot — ex. studio, fronts de démo, mediasoup, realtime, redis).
+     *
+     * ⚠️ **Statique** (pas une propriété d'instance) : lue dans le constructeur via
+     * `Module.setEvents()`, donc AVANT que les initializers de la sous-classe ne
+     * tournent — une `critical = false` en propriété d'instance arriverait trop
+     * tard. Override déclaratif : `static override critical = false;`.
+     */
+    static critical: boolean;
+    package?: PackageJson;
+    path: string;
+    isApp: boolean;
+    /**
+     * Noms des services enregistrés PAR ce module (via {@link addService},
+     * y compris ceux du décorateur `@services`). Alloué au 1er ajout (lazy).
+     * Sert l'introspection admin (Studio) — qui n'est pas inférable du Container
+     * partagé seul. Cf {@link getServiceNames}.
+     */
+    private _serviceNames;
+    onKernelRegister?(): Promise<this>;
+    onKernelBoot?(): Promise<this>;
+    onKernelReady?(): Promise<this>;
+    init?(kernel?: IKernel): Promise<this>;
+    /**
+     * Outils que ce module ajoute à la porte MCP de l'application — cf
+     * {@link IModule.getMcpTools}.
+     *
+     * Déclaré ici **sans implémentation par défaut**, exactement comme les hooks
+     * de cycle de vie au-dessus : une méthode de base qui rendrait `[]` ferait
+     * payer un appel de fonction par module et par requête `tools/list`, pour
+     * rien. Le collecteur teste la présence avant d'appeler.
+     */
+    getMcpTools?(): IMcpTool[];
+    /**
+     * Initialise le module — appelé par {@link Kernel.addModule}.
+     *
+     * @param name - nom unique du module dans le kernel (key dans `kernel.modules`).
+     * @param kernel - kernel parent (fournit container, syslog, lifecycle events).
+     * @param path - chemin source du module (généralement `import.meta.url`).
+     * @param options - config du module (merge avec defaults via `setParameters("modules.<name>")`).
+     */
+    constructor(name: string, kernel: Kernel, path: string, options: DefaultOptionsService);
+    /**
+     * Schéma JSON (`z.toJSONSchema`) de la configuration du module, ou `null` si le
+     * module n'est pas (encore) migré vers une validation Zod.
+     *
+     * Lu par le data plane admin ({@link KernelAdminApi} endpoint `module/{name}`) :
+     * Studio affiche alors la config en mode « réglages documentés » (clé, type,
+     * défaut, valeurs possibles, état, et valeur effective issue de `options`) au
+     * lieu d'un dump brut clé→valeur. Les flags Nodefony (`reserved`,
+     * `runtimeMutable`, `kernelDerived`, `secret`) attachés via `.meta()` (natif zod) sont
+     * recopiés dans le JSON Schema par `z.toJSONSchema()` et exploités par l'UI.
+     *
+     * Défaut `null` (aucun schéma). Un module migré **override** pour renvoyer son
+     * `xConfigJsonSchema()`. Le core n'importe PAS zod : la sérialisation vit dans
+     * chaque module qui possède son schéma (0 dépendance ajoutée au cœur).
+     *
+     * @returns le JSON Schema de la config du module, ou `null`.
+     */
+    configSchema(): unknown | null;
+    /**
+     * Config **validée + gelée** du module — point d'accès UNIFORME et typé.
+     *
+     * Renvoie `this.options` (l'objet de config du module, réassigné par sa
+     * validation Zod à `onKernelRegister`). Un module se type via
+     * `extends Module<IXConfig>` → `this.config` est alors `IXConfig` sans cast.
+     * Remplace le double idiome historique (`this.options` brut d'un côté,
+     * `this.get("<module>Config")` de l'autre) par un seul accès. Coût nul : le
+     * getter renvoie la référence, aucune allocation ni appel système.
+     *
+     * @returns la config du module, typée `TConfig` (défaut `Record<string, unknown>`).
+     */
+    get config(): TConfig;
+    /**
+     * Résout le chemin source du module (`module.path`) — normalise URL `file://`,
+     * remonte au-dessus de `dist/` si nécessaire.
+     *
+     * @remarks Opération purement LEXICALE, volontairement : l'entrée est déjà absolue
+     *   (`import.meta.url`). Remonter le dossier `dist` passait auparavant par
+     *   `resolve(myPath, "..")`, qui ancre le chemin sur le répertoire courant — donc sous
+     *   Windows y ajoute la lettre de lecteur et normalise les séparateurs. La racine d'un
+     *   module se mettait ainsi à dépendre de l'endroit d'où l'on avait lancé le process.
+     *   `dirname` donne le même résultat sur tout chemin absolu, sans cet ancrage.
+     *
+     * @param myPath - chemin brut (souvent `import.meta.url` de la classe Module).
+     * @returns chemin absolu du dossier source du module.
+     */
+    setPath(myPath: string): string;
+    gePath(name?: string): string;
+    /**
+     * Résout le chemin d'installation d'un module npm via `require.resolve`.
+     *
+     * @param name - nom du package npm (`"@nodefony/http"`, etc.).
+     * @returns chemin absolu vers le dossier du module.
+     */
+    static getModulePath(name: string): string;
+    /**
+     * Câble les hooks lifecycle (`onKernelRegister/Boot/Ready`) sur le kernel parent.
+     *
+     * Appelé une seule fois dans le constructor. Lit les méthodes prototype définies par
+     * la sous-classe et les attache via `kernel.once()`. Si la sous-classe ne définit pas
+     * un hook, il n'est pas attaché (pas de listener orphelin).
+     *
+     * Toujours attache un listener `onPreBoot` (prepend, donc index 0) pour charger le
+     * `package.json` du module. Les overrides de config `Module-<name>`, eux, ne passent
+     * PLUS par ici : ils sont appliqués par `Kernel.applyModuleConfigOverrides()` entre
+     * `onPreRegister` et `onRegister` (raison détaillée dans le corps de la méthode).
+     */
+    setEvents(): void;
+    /**
+     * Pose un hook de cycle de vie du kernel **au nom de ce module** — donc avec sa
+     * politique de boot (propriétaire + criticité), comme les hooks de classe.
+     *
+     * À utiliser partout où un hook est posé « à la main » depuis le module ou
+     * depuis un de ses services (`this.module.hookKernel("onBoot", …)`) plutôt que
+     * `kernel.once(...)` directement. Pourquoi : un listener non tagué n'a pas de
+     * criticité, et {@link Kernel.isBootErrorFatal} traite l'absence de tag comme
+     * **critique**. Un module qui déclare pourtant `static critical = false`
+     * voyait donc son échec interrompre le boot en production — la déclaration ne
+     * portait que sur ses hooks de classe, pas sur ceux de ses services. Le
+     * journal ne pouvait même pas nommer le coupable (`"(anonyme)"`).
+     *
+     * @param event - nom de l'événement de cycle (`onRegister`, `onBoot`, `onReady`…).
+     * @param listener - le hook ; il hérite du nom et de la criticité du module.
+     * @returns le module (chaînable).
+     */
+    hookKernel(event: string, listener: (...args: never[]) => unknown | Promise<unknown>): this;
+    /**
+     * Détecte les overrides de config destinés à d'autres modules (clés `Module-<name>`),
+     * les applique, puis les RETIRE des options du module porteur.
+     *
+     * Permet à un module de surcharger la config d'un autre module sans toucher au code de
+     * ce dernier. Exemple : `Module-http: { port: 8080 }` dans la config de l'app → applique
+     * `{ port: 8080 }` à `@nodefony/http`. Warn si module cible inconnu.
+     *
+     * 🔴 **La clé est CONSOMMÉE.** C'est un ordre de configuration adressé à un
+     * autre module, pas une donnée du module porteur : une fois appliquée, elle
+     * n'a plus rien à faire dans ses options. La garder cassait la validation du
+     * porteur dès lors que son schéma refuse les clés inconnues — et déclarer
+     * `module-*` dans les onze schémas du dépôt aurait recopié onze fois une règle
+     * qui vit ici. Le retrait vaut AUSSI quand la cible est introuvable : la
+     * configuration est morte, elle vient d'être signalée, et rien ne gagne à ce
+     * qu'elle fasse en plus tomber le boot du porteur.
+     *
+     * Personne d'autre ne lit ces clés (`rg` sur `regModuleName` : ce fichier
+     * seul) ; sous l'ancien `z.object` elles disparaissaient de toute façon au
+     * parse, silencieusement — ce retrait rend explicite ce qui se produisait déjà.
+     *
+     * @param deep - merge profond (`true`, défaut) vs shallow (`false`).
+     * @returns options du module courant, débarrassées des clés d'override consommées.
+     */
+    readOverrideModuleConfig(deep?: boolean): DefaultOptionsService;
+    registerService(service: ServiceConstructor, name: string): ServiceConstructor;
+    /**
+     * Instancie un service via l'{@link Injector} et l'enregistre dans le container du module.
+     *
+     * Si le service expose une méthode `init(module)`, elle est appelée après
+     * instanciation (équivalent constructeur async). Warn si un service du même nom existe
+     * déjà (override).
+     *
+     * @param service - constructeur du service (typiquement décoré `@injectable`).
+     * @param args - arguments additionnels passés au constructeur (après les `@inject` resolved).
+     * @returns instance du service prête à l'usage.
+     */
+    addService(service: ServiceConstructor, ...args: any[]): Promise<Service>;
+    /**
+     * Politique d'échec d'un service déclaré via `@services([...])` : la MÊME que
+     * pour le reste du boot — fatal en production (ou sur une erreur de
+     * configuration), fail-soft **ANNONCÉ** ailleurs (agrégé au BootReport, qui
+     * fait dire « boot DÉGRADÉ » au superviseur). Jamais un skip silencieux.
+     *
+     * Appelée par le décorateur `@services`, dont le `catch` se contentait de
+     * logger : l'échec n'atteignait ni la politique de criticité ni le BootReport.
+     *
+     * @param error - l'échec remonté par `addService`/`loadService`.
+     * @param service - le constructeur (ou le chemin) du service fautif.
+     * @throws l'erreur d'origine si l'échec est fatal (production + module critique).
+     */
+    handleServiceBootError(error: unknown, service: string | ServiceConstructor): void;
+    /**
+     * Noms des services enregistrés par ce module (ordre d'ajout).
+     * Vide tant qu'aucun service n'a été ajouté.
+     */
+    getServiceNames(): string[];
+    /**
+     * Charge dynamiquement un service depuis un chemin (`import()`) puis l'enregistre via
+     * {@link addService}.
+     *
+     * @param service - chemin/spécifier du module à importer (URL, npm package, path relatif).
+     * @param args - arguments additionnels passés au constructeur.
+     * @returns instance du service après instanciation + `init()`.
+     */
+    loadService(service: string, ...args: any[]): Promise<Service>;
+    getPackageJson(cwd?: string): Promise<PackageJson>;
+    /**
+     * Récupère un controller enregistré **dans ce module**.
+     *
+     * Le registre `Module.controllers` est process-global mais indexé par clé
+     * **module-scopée** `${module}:${ClassName}` (posée par `Router.setController`),
+     * exactement comme l'identité d'un `forward("module:controller:action")`. Deux
+     * modules peuvent donc porter un controller homonyme sans collision.
+     *
+     * @param name - nom de classe du controller (ex. `"DefaultController"`).
+     * @returns constructeur typé du controller.
+     * @throws Si `name` est falsy ou si le controller n'est pas enregistré pour ce module.
+     */
+    getController<T = Controller>(name: string): TypeController<T>;
+    /**
+     * Retourne les controllers enregistrés **pour ce module** (clés = nom de classe
+     * nu, préfixe module retiré). Vue jetable filtrée depuis le registre global.
+     */
+    getControllers<T = Controller>(): Record<string, TypeController<T>>;
+    /**
+     * Liste les dépendances + peerDependencies du module (depuis son `package.json`).
+     *
+     * @returns array de noms de packages npm. **devDependencies exclus**. Doublons possibles
+     *   si un même package est listé dans `dependencies` ET `peerDependencies`.
+     */
+    getDependencies(): string[];
+    /**
+     * Variante static — extrait les deps depuis un `package.json` arbitraire.
+     *
+     * @param mypackage - objet `package.json` parsé.
+     * @returns array de noms de packages npm (deps + peerDeps, devDeps exclus).
+     */
+    static getPackageDependencies(mypackage: PackageJson): string[];
+    getModuleName(): string | undefined;
+    getModuleVersion(): string | undefined;
+    /**
+     * Enregistre une commande CLI custom rattachée à ce module.
+     *
+     * Pattern legacy `nodefony <name>:<action>` (ex: `nodefony users:add`). Le {@link CliKernel}
+     * doit être disponible (sinon throw `Kernel not ready`). En mode cluster worker, exceptions
+     * non-primary sont silencieusement avalées (retour `void`).
+     *
+     * @param cliCommand - constructeur de la commande (extends `Command`).
+     * @returns instance de la commande enregistrée OU `void` si worker secondaire.
+     * @throws `Error("Kernel not ready")` si `kernel.cli` n'est pas instancié.
+     */
+    addCommand(cliCommand: new (cli: CliKernel) => Command): Command | void;
+    /**
+     * Exécute `npm install` (ou yarn/pnpm) dans le dossier du module.
+     *
+     * @param force - ajoute `--force` à l'install. Défaut `false`.
+     * @returns code de retour du process (0 = succès) ou Error si crash.
+     * @throws Si `packageManager` n'est pas attaché au CliKernel.
+     */
+    install(force?: boolean): Promise<number | Error>;
+    /**
+     * Exécute `npm outdated` dans le dossier du module.
+     *
+     * @returns code de retour du process ou Error si crash.
+     * @throws Si `packageManager` n'est pas attaché au CliKernel.
+     */
+    outdated(): Promise<number | Error>;
+    loadJson(url: string, cwd?: string): Promise<JSONObject>;
+    /**
+     * Surcharge {@link Service.log} — `msgid` défaut = `"MODULE <name>"` pour identifier
+     * les logs de ce module dans le pipeline Syslog.
+     *
+     * @param pci - payload (string, Error, objet — narrower côté lecteur).
+     * @param severity - sévérité RFC 5424 (`"INFO"`, `"ERROR"`, etc.).
+     * @param msgid - catégorie de message. Défaut `"MODULE <name>"`.
+     * @param msg - détail libre optionnel.
+     * @returns le `Pdu` produit (utile pour audit/tests).
+     */
+    log(pci: any, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu;
+}
+export default Module;

package/dist/types/kernel/adminPlane/adminCaller.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Qui appelle le plan d'administration, tel qu'il se PRÉSENTE.
+ *
+ * Ce type existe pour une raison précise : les portes sans HTTP (commande
+ * `inspect`, serveur MCP) fabriquaient un administrateur au lieu de porter une
+ * identité. Le contrôle de rôle s'appliquait donc à un sujet inventé, et tout
+ * porteur d'un jeton accepté obtenait la lecture d'administration complète.
+ *
+ * L'identité se PASSE, elle ne se déduit pas : chaque porte doit dire au nom de
+ * qui elle appelle, et le compilateur l'y oblige.
+ */
+export interface IAdminCaller {
+    /** L'utilisateur, quand la porte en connaît un. */
+    user: unknown | null;
+    /** Ses rôles RÉELS — c'est sur eux que le contrôle d'accès tranche. */
+    roles: readonly string[];
+    /**
+     * Qui c'est, en clair. Sert au refus et au journal : « rôle X requis » sans
+     * dire À QUI il manquait oblige à deviner quelle porte a été empruntée.
+     */
+    label: string;
+}
+/**
+ * L'opérateur qui lance une commande sur sa propre application.
+ *
+ * Il possède déjà le processus : il lit les sources, il édite la configuration,
+ * il peut arrêter le serveur. Lui refuser la lecture d'administration
+ * n'ajouterait aucune barrière — il lui suffirait d'ouvrir un fichier — mais
+ * rendrait la commande inutile. Le rôle est donc accordé ; ce qui compte, c'est
+ * que ce soit ÉNONCÉ ici plutôt que fabriqué en silence au fond d'une lecture.
+ *
+ * @returns l'appelant à présenter depuis une commande locale.
+ */
+export declare function localOperatorCaller(): IAdminCaller;
+/**
+ * Scope d'un jeton ouvrant la LECTURE du plan d'administration.
+ *
+ * Trois valeurs suffisent pour tout le plan (celle-ci, {@link ADMIN_SCOPE_WRITE},
+ * et l'absence de scope pour la topologie) : un scope par endpoint se périmerait
+ * à chaque ajout, et la granularité fine existe déjà pour les API d'une
+ * application, portée par `@RequireScope` sur ses routes.
+ */
+export declare const ADMIN_SCOPE_READ = "admin:read";
+/** Scope d'un jeton ouvrant les MUTATIONS du plan d'administration. */
+export declare const ADMIN_SCOPE_WRITE = "admin:write";
+/**
+ * Traduit les scopes d'un jeton en rôles Nodefony.
+ *
+ * ⚠️ Les deux scopes mènent aujourd'hui au MÊME rôle, et ce n'est pas un
+ * raccourci : le contrôle d'accès du plan d'administration est uniforme — tous
+ * les endpoints exigent `ROLE_NODEFONY_ADMIN`, lectures comme mutations.
+ * Distinguer ici produirait un théâtre d'autorisation : deux scopes séparés qui
+ * ouvrent exactement la même chose, et une promesse que le code ne tient pas.
+ * La séparation deviendra réelle quand `IAdminEndpoint.role` se différenciera.
+ *
+ * Un jeton qui ne porte aucun de ces scopes n'obtient **aucun rôle** : la
+ * vérification d'audience (RFC 8707) prouve que le jeton vise cette ressource,
+ * elle ne dit rien de ce que son porteur a le droit d'y faire.
+ *
+ * ## Rôle et scope — la doctrine, et l'asymétrie qui reste
+ *
+ * Autorisation effective = **droits de l'utilisateur ∧ portée déléguée au
+ * porteur**. Un scope borne ce qu'un TIERS peut faire au nom de quelqu'un ; en
+ * session directe (cookie, Studio) il n'y a pas de tiers, donc rien à borner et
+ * le rôle suffit. Dès qu'un JETON entre en jeu, il y a délégation, et les deux
+ * doivent mordre — c'est ce que fait cette fonction, avec
+ * {@link refusedAdminScopes} qui borne l'autre bout : porter le rôle ne suffit
+ * pas à obtenir le scope, porter le scope ne suffit pas à avoir le rôle.
+ *
+ * ⚠️ **Dette nommée, non fermée** : un jeton présenté sur la porte HTTP
+ * (`ExternalJwtAuthenticator`, `subjectPolicy: "require"`) est rattaché à un
+ * compte local et hérite des rôles de ce compte **sans** intersection avec ses
+ * scopes — les routes du plan d'administration sont montées par le broker, donc
+ * ne portent aucun `@RequireScope`. Le même porteur obtient donc plus par HTTP
+ * que par MCP. Fermer cela suppose que la provenance de l'identité (session ou
+ * jeton) voyage jusqu'au contrôle de rôle, ce qu'elle ne fait pas aujourd'hui.
+ *
+ * ⚠️ Et ce n'est pas du moindre privilège : le plan d'administration n'a qu'UN
+ * rôle, qui ouvre tous ses endpoints. « Fail-closed » — pas de laissez-passer
+ * par défaut — n'est pas « Zero Trust ». La granularité réelle suppose que
+ * `IAdminEndpoint.role` se différencie ; tant qu'il ne l'est pas, découper les
+ * scopes plus finement ne serait qu'un décor.
+ *
+ * @param scopes - scopes accordés par le serveur d'autorisation.
+ * @returns les rôles à présenter, éventuellement aucun.
+ */
+export declare function rolesFromScopes(scopes: readonly string[]): string[];
+/**
+ * Les scopes d'administration demandés que ce porteur **ne peut pas** obtenir.
+ *
+ * Réciproque de {@link rolesFromScopes}, et indispensable avec elle : si un
+ * scope ouvre le plan d'administration, alors l'émetteur ne peut pas le signer
+ * sur simple demande. Sans cette borne, « tout jeton vaut administrateur »
+ * devient « tout jeton QUI DEMANDE vaut administrateur » — le trou change de
+ * forme, pas de taille.
+ *
+ * Ne juge QUE les scopes d'administration du framework. Les scopes d'une
+ * application (`shop:read`, `billing:export`) ne regardent pas Nodefony : c'est
+ * à elle de dire qui peut les obtenir.
+ *
+ * @param requested - scopes demandés au grant (RFC 6749 §3.3).
+ * @param roles - rôles du porteur, tels que son compte les porte.
+ * @returns les scopes à REFUSER — vide si la demande est légitime.
+ */
+export declare function refusedAdminScopes(requested: readonly string[], roles: readonly string[]): string[];

package/dist/types/kernel/adminPlane/adminRbac.d.ts

@@ -0,0 +1,44 @@
+import type { IAdminEndpoint } from "../../types/IAdminApi.js";
+/**
+ * Décision d'autorisation du data plane admin (Studio) — fonction **PURE**,
+ * cœur de la garantie RBAC, testée isolément (zéro dépendance runtime/DI).
+ *
+ * **Fail-closed.** Un endpoint qui exige un rôle (`requiredRole` non vide) n'est
+ * accordé QUE si l'appelant le porte. Un appelant **sans rôle** (`roles=[]` — ex.
+ * compte authentifié non doté, créé via `POST users` sans `roles`) est donc
+ * **rejeté** (403). C'était le **fail-open historique** : le 403 était court-circuité
+ * par une garde `roles.length > 0 &&` — vestige du « mode mock » d'avant P6, quand
+ * aucun rôle n'était injecté. Zero Trust : l'absence de rôle ne vaut pas
+ * laissez-passer. Le firewall (zone `nodefony-admin`) garantit l'AUTHENTIFICATION
+ * en amont ; cette fonction tranche le RÔLE.
+ *
+ * `requiredRole` vide (`""`) ou absent = endpoint **public déclaré**
+ * (`IAdminEndpoint.public`, ex. liveness `livez`) → toujours accordé : le RBAC du
+ * broker est volontairement court-circuité, la protection vit alors dans le firewall.
+ *
+ * @param roles - rôles **bruts** de l'appelant (projection ALS `IAdminRequest.roles`).
+ * @param requiredRole - rôle exigé par la route (`""`/`undefined` = public).
+ * @returns `true` si l'accès est accordé.
+ */
+export declare function isAdminGranted(roles: readonly string[], requiredRole: string | undefined): boolean;
+/**
+ * Rôle exigé par défaut d'un endpoint d'administration qui n'en déclare aucun.
+ *
+ * Le défaut est **restrictif** : un producteur qui oublie de qualifier son
+ * endpoint le publie au rôle d'administrateur, jamais à l'anonyme. Ouvrir plus
+ * large se DÉCLARE (`IAdminEndpoint.public`) et se relit en revue.
+ */
+export declare const ADMIN_DEFAULT_ROLE = "ROLE_NODEFONY_ADMIN";
+/**
+ * Rôle **effectif** d'un endpoint — la règle, à un seul endroit.
+ *
+ * Toutes les portes du plan d'administration (route HTTP montée par le broker,
+ * pont WS-RPC, commande `inspect`, serveur MCP) doivent trancher le même rôle
+ * pour le même endpoint. Deux résolutions séparées finiraient par diverger, et
+ * c'est la porte secondaire — celle qu'on relit le moins — qui deviendrait la
+ * plus permissive.
+ *
+ * @param endpoint - la définition telle que le producteur la déclare.
+ * @returns le rôle exigé, ou `""` pour un endpoint **public déclaré**.
+ */
+export declare function resolveAdminRole(endpoint: Pick<IAdminEndpoint, "public" | "role">): string;

package/dist/types/kernel/adminPlane/catalog.d.ts

@@ -0,0 +1,122 @@
+import type { AdminHttpMethod } from "../../types/IAdminApi.js";
+import type { IAdminBrokerLike } from "../inspect/adminSubjects.js";
+import type { IAdminCaller } from "./adminCaller.js";
+/**
+ * Un endpoint du plan d'administration, tel qu'une porte sans session peut le
+ * proposer — de quoi l'APPELER, rien de plus.
+ *
+ * Ce que porte `params` mérite son existence : les chemins du plan portent des
+ * variables (`module/{name}/docs/{slug}`) et un appelant qui les devine se
+ * trompe une fois sur deux. Les nommer ici coûte une expression régulière et
+ * supprime un aller-retour.
+ */
+export interface IAdminCatalogEntry {
+    /** Producteur (`kernel`, `security`, `orm`…) — premier segment de la route. */
+    namespace: string;
+    /** Chemin déclaré par le producteur, variables comprises. */
+    path: string;
+    /** Méthode — toujours `"GET"` dans ce catalogue, cf {@link adminReadCatalog}. */
+    method: AdminHttpMethod;
+    /** Ce que l'endpoint rend, en une ligne, telle que son auteur l'a écrite. */
+    summary: string;
+    /** Noms des variables du chemin, dans l'ordre où elles apparaissent. */
+    params: readonly string[];
+    /**
+     * Ce que l'endpoint sait faire d'une liste, quand il en rend une.
+     *
+     * Publié parce que le défaut du plan est le REFUS : un tri ou un filtre non
+     * déclaré rend `400`, jamais une liste approximative. Sans cette
+     * publication, un appelant tente `?sort=createdAt`, se fait refuser, et
+     * conclut que l'endpoint est cassé — alors qu'il ne l'a simplement jamais
+     * annoncé. Évalué à la lecture : c'est le store branché au démarrage qui
+     * répond, pas une constante de compilation.
+     */
+    page?: {
+        /** Champs sur lesquels `?sort=` est accepté. */
+        sortable: readonly string[];
+        /** Noms de filtre acceptés, tels que le vocabulaire de l'endpoint les nomme. */
+        filters: readonly string[];
+        /** L'endpoint honore-t-il `?q=` ? */
+        search: boolean;
+    };
+}
+/** Restriction de lecture du catalogue — sans effet sur ce qui est APPELABLE. */
+export interface IAdminCatalogQuery {
+    /** Ne garder qu'un producteur. */
+    namespace?: string;
+    /** Termes cherchés dans le chemin et le résumé ; espaces = termes CUMULATIFS. */
+    q?: string;
+}
+/**
+ * Ce que le catalogue montre, ET ce qu'il a écarté.
+ *
+ * Les compteurs ne sont pas décoratifs : sans eux, une liste de 61 entrées se
+ * lit comme « voilà tout le plan d'administration », et un appelant conclut
+ * qu'une capacité n'existe pas alors qu'elle est seulement hors de portée de
+ * CETTE porte. Un écart se DIT, il ne se devine pas.
+ */
+export interface IAdminCatalogView {
+    /** Les endpoints appelables, groupés par personne — l'ordre de déclaration. */
+    entries: IAdminCatalogEntry[];
+    /** Combien d'endpoints le plan déclare en tout. */
+    total: number;
+    /** Écartés parce que ce sont des mutations (POST/PATCH/PUT/DELETE). */
+    mutations: number;
+    /** Écartés parce qu'ils sont scopés à une session (`public: true`). */
+    selfService: number;
+    /** Écartés faute du rôle exigé par l'endpoint. */
+    denied: number;
+    /** Écartés par la restriction de lecture demandée ({@link IAdminCatalogQuery}). */
+    filtered: number;
+}
+/**
+ * Les endpoints du plan d'administration qu'une porte **sans session** peut
+ * servir à cet appelant — la règle unique dont dépendent `nodefony_admin_list`
+ * ET `nodefony_admin_call`.
+ *
+ * ⭐ **Ce qui est listé est appelable, et rien d'autre ne l'est.** C'est le même
+ * patron que le filtrage des outils MCP à la collecte : un seul point de
+ * décision sert la liste et l'exécution, donc il ne peut pas exister d'entrée
+ * appelable qu'on n'aurait pas annoncée, ni d'entrée annoncée qui refuserait
+ * ensuite. Deux points de décision, c'est celui qu'on relit le moins qui
+ * devient le plus permissif.
+ *
+ * Trois exclusions, toutes comptées et donc dicibles :
+ *
+ * 1. **Les mutations.** L'idempotence des mutations du plan est une porte du
+ *    transport HTTP (`AdminApiController.idempotencyGate`, qui a besoin du
+ *    conteneur) ; l'exécuter d'ici sans elle ferait de cette porte une
+ *    quatrième voie qui perd ce que les autres gardent — précisément ce que
+ *    l'unification de l'exécution vient de supprimer. Elles se compteront tant
+ *    qu'elles ne s'appelleront pas.
+ * 2. **Les endpoints `public: true`.** Ce ne sont pas des endpoints libres :
+ *    ce sont des self-service scopés à `request.user` (`me`, `me/password`,
+ *    `sessions/mine`) ou des sondes d'infrastructure. Une porte sans session
+ *    n'a pas d'utilisateur ; les servir rendrait « les données de personne » au
+ *    mieux, celles d'autrui au pire.
+ * 3. **Ce que le rôle de l'appelant n'ouvre pas** — la même décision que
+ *    l'exécution ({@link isAdminGranted}), prise sur le même rôle résolu
+ *    ({@link resolveAdminRole}), pour que la liste ne promette jamais ce que
+ *    l'appel refuserait.
+ *
+ * @param broker - le service `adminBroker` du conteneur, ou `undefined`.
+ * @param caller - qui demande, avec ses rôles RÉELS.
+ * @param query - restriction de lecture facultative.
+ * @returns les entrées appelables, et le compte de ce qui ne l'est pas.
+ */
+export declare function adminReadCatalog(broker: IAdminBrokerLike | undefined, caller: IAdminCaller, query?: IAdminCatalogQuery): IAdminCatalogView;
+/**
+ * Retrouve une entrée APPELABLE par son couple producteur/chemin.
+ *
+ * Passe par {@link adminReadCatalog} plutôt que de reparcourir le registre :
+ * c'est ce qui garantit que l'appel et la liste tranchent la même chose. Une
+ * seconde traversée « équivalente » serait exactement la divergence que ce
+ * module supprime.
+ *
+ * @param broker - le service `adminBroker` du conteneur, ou `undefined`.
+ * @param caller - qui demande, avec ses rôles RÉELS.
+ * @param namespace - producteur visé.
+ * @param path - chemin visé, tel que le catalogue le nomme (variables comprises).
+ * @returns l'entrée, ou `null` si elle n'est pas appelable par cet appelant.
+ */
+export declare function findAdminReadEntry(broker: IAdminBrokerLike | undefined, caller: IAdminCaller, namespace: string, path: string): IAdminCatalogEntry | null;