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

package/dist/types/nodefony/src/oauth/providerDiagnosis.d.ts

@@ -0,0 +1,117 @@
+import type { IOAuthProvider } from "../../contracts/IOAuthProvider.js";
+import { type OAuth2ClientAuthMethod } from "./oauth2Client.js";
+/**
+ * **Diagnostic d'un fournisseur OAuth sans connexion humaine** — dit POURQUOI un
+ * branchement échoue, là où le journal ne montre qu'un 401 ou une page d'erreur
+ * du fournisseur.
+ *
+ * Trois sondes, dans l'ordre où l'une éclaire l'autre :
+ *
+ * 1. **découverte** — le fournisseur se construit comme au premier login
+ *    (métadonnées, émetteur identique RFC 8414 §3.3, PKCE S256 annoncé) ;
+ * 2. **point d'autorisation** — la requête que le bouton enverrait, sans la
+ *    suivre : le serveur accepte-t-il ce client et cette URL de retour ?
+ * 3. **point de jeton** — un code INVENTÉ présenté avec le vrai secret :
+ *    `invalid_grant` prouve que le client s'est authentifié (seul le code est
+ *    refusé), un refus d'authentification prouve le contraire (RFC 6749 §5.2).
+ *
+ * 🔴 **Rien n'est réécrit ici.** Les sondes passent par le fournisseur que la
+ * fabrique construit pour le login — mêmes points d'entrée, même méthode
+ * d'authentification, même URL de retour. Un diagnostic qui reconstruirait sa
+ * propre requête prouverait que SA requête passe, pas celle du login.
+ *
+ * @remarks Chemin froid (une commande, un écran d'administration). La sonde
+ * d'autorisation ouvre côté fournisseur une session de connexion vide, qui
+ * expire seule ; aucun compte n'est touché, aucun jeton n'est émis.
+ */
+/**
+ * Les sondes, dans leur ordre. `theme` n'existe que si l'appelant fournit un
+ * {@link IOAuthDiagnosisInput.pageCheck} ET que la page d'autorisation s'y
+ * prête (Keycloak).
+ */
+export type OAuthCheckName = "discovery" | "authorization" | "token" | "theme";
+/**
+ * Verdict d'une sonde. `inconclusive` = le serveur a répondu quelque chose
+ * qu'on ne sait pas lire — ni un quitus, ni un manquement ; `skipped` = une
+ * sonde précédente a rendu celle-ci impossible.
+ */
+export type OAuthCheckStatus = "ok" | "failed" | "inconclusive" | "skipped";
+/** La cause d'un échec, lisible par une machine (rapport, console, tests). */
+export type OAuthFailureKind = 
+/** Le document de métadonnées se déclare d'un autre émetteur (RFC 8414 §3.3). */
+"issuer-mismatch"
+/** Émetteur injoignable, document absent ou incomplet, PKCE S256 non annoncé. */
+ | "discovery-failed"
+/** Le point d'autorisation refuse l'URL de retour (non enregistrée). */
+ | "redirect-uri-rejected"
+/** Le point d'autorisation refuse la demande pour une autre raison. */
+ | "authorization-refused"
+/** Le point d'autorisation n'a pas répondu. */
+ | "authorization-unreachable"
+/** Le client existe (le point d'autorisation l'accepte), son secret est refusé. */
+ | "secret-rejected"
+/** Authentification du client refusée : client inconnu, ou secret refusé. */
+ | "client-rejected"
+/** Le point de jeton refuse pour une autre raison (flux non autorisé…). */
+ | "token-refused"
+/** Le point de jeton n'a pas répondu. */
+ | "token-unreachable"
+/** La page du fournisseur ne porte pas l'habillage de `/login`. */
+ | "login-theme-mismatch";
+/** Le résultat d'une sonde. */
+export interface IOAuthCheck {
+    readonly name: OAuthCheckName;
+    readonly status: OAuthCheckStatus;
+    /** Présent si et seulement si `status === "failed"`. */
+    readonly kind?: OAuthFailureKind;
+    /** Phrase destinée à l'opérateur : le constat, puis le geste. */
+    readonly message: string;
+}
+/** Le diagnostic d'un fournisseur. */
+export interface IOAuthDiagnosis {
+    /** Nom du fournisseur (`oauth2.providers.<name>`). */
+    readonly provider: string;
+    /** `true` si aucune sonde n'a échoué. Une sonde non concluante ne l'empêche pas. */
+    readonly ok: boolean;
+    readonly checks: readonly IOAuthCheck[];
+}
+/** Ce que le diagnostic d'un fournisseur doit savoir. */
+export interface IOAuthDiagnosisInput {
+    /** Nom du fournisseur. */
+    readonly name: string;
+    /** Construit le fournisseur comme pour un login — découverte comprise. */
+    readonly build: () => IOAuthProvider | Promise<IOAuthProvider>;
+    /** Identifiant du client, tel que configuré. */
+    readonly clientId: string;
+    /** URL de retour configurée — celle que le fournisseur doit connaître. */
+    readonly redirectUri: string;
+    /** Méthode d'authentification déclarée ; `"none"` = client public. */
+    readonly clientAuthMethod?: OAuth2ClientAuthMethod | undefined;
+    /** Portées configurées ; vides = celles du fournisseur. */
+    readonly scopes?: readonly string[] | undefined;
+    /**
+     * Transport de la sonde d'autorisation. Celle du point de jeton passe par le
+     * fournisseur, donc par le transport que SA fabrique a reçu.
+     */
+    readonly fetch?: typeof globalThis.fetch | undefined;
+    /** Délai d'attente de la sonde d'autorisation, en millisecondes. */
+    readonly timeoutMs?: number | undefined;
+    /**
+     * Juge la page de connexion que le point d'autorisation sert (ses premiers
+     * octets). Rend une sonde de plus, ou `null` quand la page ne s'y prête
+     * pas. Le diagnostic reste générique : c'est le kit Keycloak qui sait lire
+     * le thème d'une page de Keycloak.
+     */
+    readonly pageCheck?: ((html: string) => IOAuthCheck | null) | undefined;
+}
+/**
+ * Diagnostique un fournisseur OAuth sans connexion humaine.
+ *
+ * Ne lève jamais : un serveur muet ou hostile devient une sonde en échec, et
+ * les sondes que l'échec rend impossibles sont DITES sautées — un silence ne
+ * vaut pas quitus.
+ *
+ * @param input - fournisseur à construire et configuration à confronter.
+ * @returns les trois sondes et leur verdict.
+ */
+export declare function diagnoseOAuthProvider(input: IOAuthDiagnosisInput): Promise<IOAuthDiagnosis>;

package/dist/types/nodefony/src/oauth/providerRoles.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Traduction des rôles d'un fournisseur d'identité (Keycloak, tout serveur
+ * OpenID Connect) en rôles de l'application.
+ *
+ * Logique PURE, sans réseau ni base : la même fonction sert la connexion par
+ * navigateur (claims du jeton reçu du point de jeton) et l'API (claims d'un
+ * jeton dont la signature vient d'être vérifiée). Deux implémentations
+ * divergeraient — un rôle retiré dans l'annuaire disparaîtrait d'un côté et
+ * survivrait de l'autre.
+ */
+/** Où lire les rôles dans les claims du fournisseur. */
+export type ProviderRoleSource = "client" | "realm" | "groups";
+/** Source par défaut : les rôles du CLIENT — ceux que l'annuaire attribue à CETTE application. */
+export declare const DEFAULT_ROLE_SOURCES: readonly ProviderRoleSource[];
+/**
+ * Préfixe des rôles de PLATEFORME (console d'administration, plan
+ * d'administration) — jamais accordés par un annuaire externe.
+ */
+export declare const PLATFORM_ROLE_PREFIX = "ROLE_NODEFONY_";
+/** `true` si le rôle relève de la plateforme (`ROLE_NODEFONY_*`). */
+export declare function isPlatformRole(role: string): boolean;
+/** Table de correspondance compilée d'UN fournisseur. */
+export interface IProviderRoleMapping {
+    /** Client dont on lit les rôles (`resource_access.<clientId>.roles`). */
+    readonly clientId: string;
+    /** Sources lues, dans l'ordre. */
+    readonly sources: readonly ProviderRoleSource[];
+    /** Rôle du fournisseur → rôle de l'application (objet sans prototype). */
+    readonly table: Readonly<Record<string, string>>;
+}
+/** Ce que la configuration d'un fournisseur apporte à la correspondance. */
+export interface IProviderRoleConfig {
+    readonly clientId: string;
+    readonly roleMapping?: Readonly<Record<string, string>> | undefined;
+    readonly rolesSource?: readonly ProviderRoleSource[] | undefined;
+}
+/**
+ * Compile la table d'un fournisseur — `null` quand il n'en déclare aucune, ce
+ * qui laisse les rôles du compte entièrement locaux (comportement historique).
+ *
+ * @param config - configuration du fournisseur.
+ * @returns la table compilée, ou `null`.
+ */
+export declare function compileProviderRoleMapping(config: IProviderRoleConfig): IProviderRoleMapping | null;
+/**
+ * Rôles de l'application accordés par le fournisseur, d'après ses claims.
+ *
+ * Un rôle du fournisseur absent de la table est IGNORÉ — jamais recopié tel
+ * quel : l'annuaire ne fabrique pas de rôle que l'application n'a pas déclaré.
+ * Plusieurs jeux de claims (jeton d'accès, jeton d'identité) se cumulent : ils
+ * viennent du même émetteur, chacun peut porter une partie des rôles selon
+ * les « mappers » configurés chez lui.
+ *
+ * @param mapping - table compilée du fournisseur.
+ * @param claimSets - claims à lire ; `null`/`undefined` ignorés.
+ * @returns rôles de l'application, triés et sans doublon.
+ */
+export declare function mapProviderRoles(mapping: IProviderRoleMapping, ...claimSets: (Readonly<Record<string, unknown>> | null | undefined)[]): string[];

package/dist/types/nodefony/src/oauth/providers/oidc.d.ts

@@ -1,4 +1,4 @@
-import type { IOAuthProvider } from "../../../contracts/IOAuthProvider.js";
+import type { ILogoutTokenClaims, IOAuthProvider } from "../../../contracts/IOAuthProvider.js";
 import type { IOAuthProviderContext } from "../oauthProviderRegistry.js";
 import { type IAuthorizationRequest, type ITokenRequest, type OAuth2Tokens } from "../oauth2Client.js";
 import { type IDiscoveryOptions } from "../metadata.js";
@@ -30,7 +30,40 @@ export interface IOidcProviderOptions {
     readonly decodeIdToken: (idToken: string) => object | Promise<object>;
     /** Scopes par défaut si la config n'en précise aucun. */
     readonly defaultScopes?: string[];
+    /**
+     * Point de déconnexion du fournisseur (`end_session_endpoint`). Absent ou
+     * `null` : le fournisseur n'offre pas `createLogoutURL`.
+     */
+    readonly endSessionEndpoint?: string | null;
+    /**
+     * Vérifie la SIGNATURE d'un jeton de déconnexion (émetteur, audience,
+     * algorithme, `exp`/`iat`) et rend ses claims, ou `null` s'il est refusé ;
+     * lève sur une panne. Absente : le fournisseur n'offre pas
+     * `verifyLogoutToken`. Le sens du jeton (§2.4) est contrôlé ensuite par
+     * {@link readLogoutTokenClaims}, jamais par cette fonction.
+     */
+    readonly verifyLogoutTokenSignature?: (logoutToken: string) => Promise<{
+        issuer: string;
+        payload: Record<string, unknown>;
+    } | null>;
 }
+/**
+ * Lit ce qu'un jeton de déconnexion DÉSIGNE, une fois sa signature vérifiée —
+ * les points 5 à 7 de la validation (OpenID Connect Back-Channel Logout 1.0
+ * §2.6) : `sub` ou `sid` présent, `events` qui le déclare jeton de
+ * déconnexion, AUCUN `nonce`.
+ *
+ * @remarks Ces gardes ferment la confusion entre jetons (§4.1) : un ID token
+ * du même émetteur, pour le même client, porte une signature tout aussi
+ * valide — c'est `events` qui le distingue, et l'absence de `nonce` qui
+ * empêche le chemin inverse. Fonction PURE, éprouvable sans clé ni réseau.
+ *
+ * @param issuer - émetteur canonique rendu par la vérification de signature.
+ * @param payload - claims vérifiés.
+ * @returns les claims utiles, ou `null` si le jeton n'est pas un jeton de
+ *   déconnexion valide.
+ */
+export declare function readLogoutTokenClaims(issuer: string, payload: Record<string, unknown>): ILogoutTokenClaims | null;
 /**
  * Fabrique un {@link IOAuthProvider} **générique OIDC** — couvre TOUT fournisseur
  * OpenID Connect sans code spécifique : le profil se lit toujours pareil (claims

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

@@ -0,0 +1,36 @@
+import type { ISecurityConfig } from "../config/config.js";
+/** Une zone que la connexion OAuth ouvre à quiconque obtient un compte. */
+export interface IOpenToSignupZone {
+    /** Nom de la zone (`areas.<nom>`). */
+    zone: string;
+    /** Fournisseurs OAuth qui créent les comptes à la volée, triés. */
+    providers: readonly string[];
+    /** Le constat, en une phrase — la MÊME au démarrage, dans la console et dans `doctor`. */
+    message: string;
+    /** Les deux gestes qui le soldent, prêts à taper. */
+    action: string;
+}
+/**
+ * Les zones protégées qui n'exigent aucun rôle alors que la connexion OAuth
+ * crée les comptes à la volée — c'est-à-dire ouvertes à tout compte que le
+ * fournisseur délivre.
+ *
+ * Une zone sans `roles` laisse passer toute identité authentifiée : c'est un
+ * défaut voulu. Il devient un piège quand `oauth2.allowSignup` vaut `true`
+ * (le défaut) : avec Google ou GitHub, « authentifié » veut dire « n'importe
+ * qui sur Internet ». Une zone est donc retenue quand TOUT ceci est vrai :
+ * protégée, sans `anonymous`, sans `roles`, avec `session` (c'est par la
+ * session qu'un compte OAuth entre), et `oauth2` actif avec au moins un
+ * fournisseur et `allowSignup`.
+ *
+ * Le remède est une DÉCLARATION : `roles: ["ROLE_USER"]` ne change rien au
+ * comportement (un compte créé reçoit ce rôle) mais écrit l'intention.
+ *
+ * Calculée au démarrage et dans `describe()`, jamais par requête. C'est la
+ * SEULE implémentation de la règle : `doctor` lit son résultat par le plan
+ * d'administration, il ne la recalcule pas.
+ *
+ * @param config - la configuration de sécurité validée.
+ * @returns les zones concernées, dans l'ordre de déclaration ; vide sinon.
+ */
+export declare function findZonesOpenToSignup(config: Pick<ISecurityConfig, "areas" | "oauth2">): IOpenToSignupZone[];

package/dist/types/nodefony/src/realtime/UserRealtimeToken.d.ts

@@ -31,8 +31,9 @@ export declare class UserRealtimeToken implements IRealtimeToken {
      * @param revalidate - preuve de vie de l'identité, adaptée à son mode.
      * @param type - mode d'authentification réel (défaut `"session"`).
      * @param scopes - scopes délégués du jeton d'origine (défaut aucun).
+     * @param confirmAccount - relecture du compte, payée sur `api.request` seul.
      */
-    constructor(user: IUser, revalidate?: ((nowMs?: number) => Promise<boolean>) | null, type?: string, scopes?: readonly string[]);
+    constructor(user: IUser, revalidate?: ((nowMs?: number) => Promise<boolean>) | null, type?: string, scopes?: readonly string[], confirmAccount?: (() => Promise<boolean>) | null);
     /**
      * Zero Trust : l'identité qui a ouvert cette socket est-elle TOUJOURS vivante ?
      *
@@ -46,6 +47,11 @@ export declare class UserRealtimeToken implements IRealtimeToken {
      *   sans dépendre de l'horloge de la machine.
      */
     isValid(nowMs?: number): Promise<boolean>;
+    /**
+     * Le compte qui a ouvert la socket existe-t-il toujours, actif, et sous le
+     * même `id` immuable ? `true` si aucune confirmation n'est câblée.
+     */
+    confirmAccount(): Promise<boolean>;
     getUserIdentifier(): string;
     isAuthenticated(): boolean;
     getRoles(): string[];

package/dist/types/nodefony/src/realtime/realtimeContracts.d.ts

@@ -32,6 +32,12 @@ export interface IRealtimeToken {
      * (absent = valide). Appelé par le pont `api.request` avant l'action data plane.
      */
     isValid?(nowMs?: number): boolean | Promise<boolean>;
+    /**
+     * Le compte de la socket existe-t-il toujours, actif, sous le même `id` ?
+     * (miroir de `IRealtimeToken.confirmAccount` realtime). Optionnel (absent =
+     * confirmé). Relit l'annuaire : payé sur `api.request` seul, jamais au tick.
+     */
+    confirmAccount?(): Promise<boolean>;
 }
 /**
  * Données de handshake WS (miroir de `IRealtimeHandshake`) — DTO neutre passé à

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

@@ -0,0 +1,27 @@
+import type { IRolesWithin } from "nodefony";
+import type { IUser } from "@nodefony/user";
+import type { RoleHierarchyWalker } from "./RoleHierarchyWalker.js";
+/**
+ * Vue de l'annuaire PLUS permissive que `IUserProvider` (qui promet un
+ * `IUser`) : un fournisseur d'application peut rendre `null` ou `undefined`
+ * au lieu de lever — sans garde, zéro rôle vaudrait accord. Tout
+ * `IUserProvider` la satisfait.
+ */
+export interface IAccountDirectory {
+    loadUserByIdentifier(identifier: string): Promise<IUser | null | undefined>;
+}
+/**
+ * La règle « jouer un autre compte » : les rôles de `target`, hiérarchie
+ * comprise, sont-ils TOUS atteints par ceux de `owner` ? Jouer un compte ne
+ * monte jamais en droits.
+ *
+ * Fermée en cas de doute : un annuaire absent, un compte introuvable — y
+ * compris un sujet externe éphémère, qui n'a pas de compte local — rendent un
+ * refus, jamais un accord. L'annuaire est résolu à l'appel : le service `users`
+ * peut être posé après le pare-feu.
+ *
+ * @param resolveUsers - rend l'annuaire des comptes (`users`), ou `null`
+ * @param hierarchy - la hiérarchie de rôles du pare-feu
+ * @returns la règle, à poser au conteneur sous `ROLES_WITHIN`
+ */
+export declare function rolesWithin(resolveUsers: () => IAccountDirectory | null, hierarchy: RoleHierarchyWalker): IRolesWithin;

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

@@ -0,0 +1,14 @@
+/**
+ * Facteurs d'authentification de Nodefony → méthodes RFC 8176, posées dans la
+ * session à son ouverture. Les clés et leur lecteur sont au cœur
+ * (`readSessionAuthentication`, `nodefony`) ; seule la POLITIQUE de
+ * correspondance vit ici.
+ */
+/**
+ * Valeurs RFC 8176 d'un facteur nommé par un chemin d'authentification.
+ *
+ * @param factor - le facteur tel que l'audit le nomme (`password`, `totp`,
+ *   `recovery`, `webauthn`, `oauth`…)
+ * @returns les méthodes vérifiées localement ; vide pour un facteur délégué
+ */
+export declare function amrForFactor(factor: string): readonly string[];

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

@@ -18,3 +18,25 @@ import type { IUser, IUserProvider } from "@nodefony/user";
  *   compte verrouillé ou désactivé.
  */
 export declare function resolveSessionIdentity(provider: IUserProvider, identifier: string): Promise<IUser>;
+/**
+ * Résout l'identité d'une session DÉJÀ ouverte, en exigeant qu'elle ait été
+ * ouverte pour CE compte — {@link resolveSessionIdentity} plus la liaison à
+ * l'identifiant immuable (`isBoundToAccount`).
+ *
+ * La session range son principal sous l'`identifier`, qu'un compte recréé
+ * (suppression hors framework, restauration, import) peut reprendre : sans la
+ * liaison, la session de l'ancien titulaire ouvrirait le compte du nouveau.
+ * Une session sans liaison est refusée au même titre.
+ *
+ * @param provider - source d'identité (`UserService` via le container).
+ * @param identifier - identifiant fonctionnel stocké en session.
+ * @param boundAccountId - identifiant immuable inscrit à l'ouverture
+ *   (`metaBag`, clé `ACCOUNT_ID_KEY`).
+ * @param boundCredentialsVersion - version des identifiants inscrite à
+ *   l'ouverture (`metaBag`, clé `CREDENTIALS_VERSION_KEY`).
+ * @returns l'utilisateur actif, titulaire de la session.
+ * @throws AuthenticationError (401, message uniforme) — identifiant inconnu,
+ *   compte verrouillé ou désactivé, session ouverte pour un autre compte ou
+ *   avant le dernier changement de mot de passe.
+ */
+export declare function resolveBoundSessionIdentity(provider: IUserProvider, identifier: string, boundAccountId: unknown, boundCredentialsVersion: unknown): Promise<IUser>;

package/dist/types/nodefony/src/token/JwtKeystore.d.ts

@@ -1,4 +1,4 @@
-import type { JSONWebKeySet } from "jose";
+import type { JSONWebKeySet, JWK } from "jose";
 import type { IJwtKeystore, IJwtSigningKey } from "../../contracts/IJwtKeystore.js";
 /** Journalisation injectée (le keystore n'est pas un Service — il reçoit un log). */
 type LogFn = (message: string, severity: string) => void;
@@ -29,6 +29,43 @@ interface KeystoreSource {
  * @returns le message à journaliser, ou `null` quand le dossier est nettoyé.
  */
 export declare function keystoreLeaksIntoImage(dir: string): string | null;
+/** Clé telle que persistée : JWK privé (avec `d`) + métadonnées. */
+export interface IStoredKey extends JWK {
+    kid: string;
+    alg: string;
+    use?: string;
+    createdAt?: number;
+}
+/** Forme du fichier `keyset.json` / de la variable d'env `keySetJson`. */
+export interface IStoredKeySet {
+    /** `kid` de la clé qui signe (les autres ne servent qu'à vérifier). */
+    active: string;
+    keys: IStoredKey[];
+}
+/**
+ * Lit un jeu de clés sérialisé et en vérifie la FORME — la seule lecture du
+ * dépôt, appelée par le keystore ET par la validation de configuration.
+ *
+ * Ne vérifie que la structure (`keys` non vide, un `kid` par clé) : importer
+ * les clés exige `jose`, chargé paresseusement au premier jeton. Les messages
+ * ne recopient JAMAIS la valeur reçue — elle porte une clé privée.
+ *
+ * @param json - le jeu de clés, tel que `NF_JWT_KEYSET` ou `keyset.json` le porte.
+ * @returns le jeu de clés lu.
+ * @throws Error si le JSON est illisible ou la structure incomplète.
+ */
+export declare function parseKeySet(json: string): IStoredKeySet;
+/**
+ * Génère un jeu de clés de signature à partager entre tous les process d'une
+ * application — la valeur de `NF_JWT_KEYSET`.
+ *
+ * Même générateur que celui du keystore (une seule implémentation), sérialisé
+ * en JSON COMPACT : une ligne, sans quote simple, qu'un `.env` porte entre
+ * quotes simples et qu'un gestionnaire de secrets stocke tel quel.
+ *
+ * @returns le jeu de clés sérialisé — il contient la clé PRIVÉE.
+ */
+export declare function generateKeySet(): Promise<string>;
 /**
  * Keystore Ed25519 — implémentation de référence d'{@link IJwtKeystore}.
  *
@@ -49,10 +86,15 @@ export declare function keystoreLeaksIntoImage(dir: string): string | null;
  * usage ; le boot ne paie rien si le JWT n'est jamais sollicité. Le chargement
  * est mémoïsé (une seule résolution concurrente).
  *
- * @remarks Race au 1ᵉʳ boot d'un **cluster** sans clé pré-provisionnée : deux
- * workers peuvent générer puis écrire des clés différentes (le dernier `rename`
- * gagne). En prod, provisionner la clé hors-bande (`keySetJson`/SecretProvider
- * P16) élimine ce cas — c'est précisément la source recommandée.
+ * @remarks Plusieurs process qui servent la MÊME application doivent signer
+ * avec la même clé, sinon un jeton signé par l'un est refusé par l'autre :
+ * - **pods** (aucun disque partagé) → source `env` obligatoire, la même valeur
+ *   injectée partout (`NF_JWT_KEYSET`, générée par `security:secrets`) ;
+ * - **workers de `nodefony cluster`** → la source `env` est héritée au fork ; à
+ *   défaut, la source `fichier` est sûre : la création de `keyset.json` est
+ *   EXCLUSIVE ({@link createSecretExclusive}), un seul worker la génère et les
+ *   autres relisent la sienne ;
+ * - source `mémoire` → une clé par process, jamais cohérente.
  */
 export declare class JwtKeystore implements IJwtKeystore {
     #private;

package/dist/types/nodefony/src/token/RemoteJwtVerifier.d.ts

@@ -21,6 +21,13 @@ export interface ITrustedIssuer {
      * découvert.
      */
     jwksUri?: string | undefined;
+    /**
+     * Adresse où lire les métadonnées quand elle diffère de l'émetteur (service
+     * interne d'un cluster). Le document doit toujours se déclarer de `issuer` ;
+     * le `jwks_uri` peut alors être en `http` sur l'origine exacte de cette
+     * adresse (`isBackChannelTransportAllowed`, cœur).
+     */
+    discoveryUrl?: string | undefined;
     /**
      * Jeu de clés fourni LOCALEMENT — aucune requête, aucune découverte.
      *
@@ -123,8 +130,8 @@ export declare class RemoteJwtVerifier {
     #private;
     /**
      * @param options - émetteurs de confiance et réglages réseau
-     * @throws Error si un émetteur est invalide, dupliqué, ou déclare un
-     *         algorithme à secret partagé
+     * @throws Error si un émetteur est invalide, dupliqué, déclare un
+     *         algorithme à secret partagé ou une `discoveryUrl` invalide
      */
     constructor(options: IRemoteJwtVerifierOptions);
     /** Nombre d'émetteurs de confiance — pour l'introspection et les journaux. */
@@ -145,5 +152,25 @@ export declare class RemoteJwtVerifier {
      *         « jeton invalide »
      */
     verify(token: string, audience: string): Promise<IAccessPrincipal | null>;
+    /**
+     * Vérifie un jeton et rend ses claims BRUTS — pour un jeton qui n'est pas un
+     * jeton d'accès (jeton de déconnexion OpenID Connect, par exemple), dont le
+     * sens se lit dans des claims que {@link verify} ne remonte pas.
+     *
+     * Mêmes garanties et même contrat d'erreur que {@link verify} : signature,
+     * émetteur de la liste fermée, algorithme imposé, audience obligatoire,
+     * claims exigés par l'émetteur ; un refus est un `null`, une panne lève.
+     *
+     * @param token - le jeton brut, tel que présenté
+     * @param audience - audience que le jeton DOIT porter dans `aud`
+     * @returns l'émetteur canonique et les claims vérifiés, ou `null` si le jeton
+     *          est refusé
+     * @throws Error si l'émetteur ne peut pas être joint ou publie un jeu de clés
+     *         inutilisable
+     */
+    verifyClaims(token: string, audience: string): Promise<{
+        issuer: string;
+        payload: Jose.JWTPayload;
+    } | null>;
 }
 export default RemoteJwtVerifier;

package/dist/types/nodefony/src/token/scopeGrants.d.ts

@@ -0,0 +1,77 @@
+import type { RoleHierarchyWalker } from "../RoleHierarchyWalker.js";
+/**
+ * Qui peut OBTENIR un scope d'application : clé = un scope exact ou une
+ * famille `préfixe:*`, valeur = les rôles dont UN suffit.
+ */
+export type IScopeGrants = Readonly<Record<string, readonly string[]>>;
+/**
+ * Un scope demandé et refusé, avec la règle qui l'a refusé.
+ *
+ * `admin` = réservé au plan d'administration du framework
+ * ({@link refusedAdminScopes}) ; `application` = déclaré dans
+ * `grantableScopes` pour des rôles que le porteur n'a pas.
+ */
+export interface IScopeRefusal {
+    scope: string;
+    rule: "admin" | "application";
+}
+/**
+ * Clés que `grantableScopes` refuse : le plan d'administration est jugé par le
+ * framework, et une déclaration ici serait soit sans effet, soit un
+ * assouplissement — deux pièges que rien ne signalerait.
+ */
+export declare const RESERVED_SCOPE_GRANT_KEYS: readonly string[];
+/**
+ * Dit pourquoi une clé de `grantableScopes` est invalide, ou `null` si elle
+ * est acceptable.
+ *
+ * Une clé est un `scope-token` (RFC 6749 §3.3) ; un `*` n'y est admis qu'en
+ * dernière position, juste après `:` (une famille `préfixe:*`).
+ *
+ * @param key - la clé déclarée.
+ * @returns le motif du refus, ou `null`.
+ */
+export declare function scopeGrantKeyProblem(key: string): string | null;
+/**
+ * Politique d'attribution des scopes d'application, compilée une fois au boot.
+ *
+ * Résolution : une clé EXACTE l'emporte sur une famille, et la famille la plus
+ * longue sur une plus courte (`shop:admin:*` > `shop:*`). Le résultat ne dépend
+ * donc pas de l'ordre des clés. Un scope qu'aucune clé ne couvre reste accordé
+ * à tout porteur (comportement historique).
+ */
+export declare class ScopeGrantPolicy {
+    #private;
+    /**
+     * @param grants - la section `grantableScopes`, déjà validée par le schéma.
+     */
+    constructor(grants?: IScopeGrants);
+    /** `true` si aucune clé n'est déclarée — tout scope d'application est accordé. */
+    get isEmpty(): boolean;
+    /**
+     * Les rôles dont UN suffit pour obtenir ce scope.
+     *
+     * @param scope - un scope demandé.
+     * @returns les rôles de la clé la plus spécifique, ou `null` si aucune clé ne
+     *   le couvre (scope libre).
+     */
+    rolesFor(scope: string): readonly string[] | null;
+}
+/**
+ * Les scopes demandés que ce porteur ne peut pas obtenir, avec la règle qui
+ * refuse chacun.
+ *
+ * Seul juge des DEUX familles, appelé par chaque émetteur de l'application
+ * (jeton d'accès, clé API) : la règle d'administration du framework
+ * ({@link refusedAdminScopes}, jugée sur les rôles PLATS du compte, comme le
+ * plan d'administration) et la politique de l'application
+ * ({@link ScopeGrantPolicy}, jugée hiérarchie de rôles comprise, comme un
+ * `@IsGranted`).
+ *
+ * @param requested - scopes demandés (RFC 6749 §3.3).
+ * @param roles - rôles du porteur, tels que son compte les porte.
+ * @param policy - politique compilée de `grantableScopes`.
+ * @param hierarchy - hiérarchie de rôles ; absente, seuls les rôles plats comptent.
+ * @returns les refus, dans l'ordre de la demande — vide si tout est accordé.
+ */
+export declare function refusedScopes(requested: readonly string[], roles: readonly string[], policy: ScopeGrantPolicy, hierarchy: RoleHierarchyWalker | null): IScopeRefusal[];

package/dist/types/nodefony/src/token/secretFile.d.ts

@@ -66,5 +66,27 @@ export declare function messageNonRestreint(file: string, mode: number): string;
  * un fichier EXISTANT conserve, sur certains systèmes, le mode de la cible.
  */
 export declare function writeSecret(file: string, content: string): Promise<void>;
+/**
+ * Crée un secret SEULEMENT s'il n'existe pas encore : 0600, atomique, et un
+ * seul gagnant quand plusieurs process le tentent en même temps.
+ *
+ * ⭐ **Pourquoi pas {@link writeSecret}.** `rename` REMPLACE la cible : deux
+ * workers de `nodefony cluster` qui génèrent chacun une clé au premier boot
+ * l'écrivent tous les deux, le dernier gagne sur le disque — et l'autre garde
+ * en mémoire une clé que plus personne ne connaît. Ici, le temporaire est
+ * publié par un LIEN DUR, que le système refuse (`EEXIST`) si le nom existe :
+ * le perdant le sait, et relit la clé du gagnant. Le lecteur ne voit jamais un
+ * fichier à demi écrit, puisque le lien n'apparaît qu'une fois le contenu complet.
+ *
+ * ⚠️ Un système de fichiers sans liens durs (FAT, exFAT) retombe sur une
+ * création exclusive directe (`wx`) : toujours un seul gagnant, mais un lecteur
+ * concurrent peut lire le fichier pendant son écriture — il lève alors, au lieu
+ * de signer avec une clé divergente.
+ *
+ * @param file - chemin du secret.
+ * @param content - contenu à écrire.
+ * @returns `true` si ce process l'a créé, `false` s'il existait déjà.
+ */
+export declare function createSecretExclusive(file: string, content: string): Promise<boolean>;
 /** Forme synchrone de {@link writeSecret}. */
 export declare function writeSecretSync(file: string, content: string): void;

package/dist/types/nodefony/src/transport/CredentialTransportPolicy.d.ts

@@ -0,0 +1,47 @@
+/** Vue minimale du contexte : seul le scheme EFFECTIF compte. */
+export interface ICredentialTransportContext {
+    /**
+     * Scheme vu par le client — `https` derrière un proxy de confiance qui
+     * termine TLS (`trustProxy` + `X-Forwarded-Proto`), jamais le transport brut.
+     */
+    readonly scheme?: string;
+}
+/** Réglages de la politique, résolus UNE fois au boot du firewall. */
+export interface ICredentialTransportPolicyOptions {
+    /** `true` = un secret reçu hors TLS est refusé (production, sans échappement). */
+    readonly enforce: boolean;
+    /** Journal du premier refus (WARNING) — absent = silencieux. */
+    readonly log?: (message: string) => void;
+}
+/**
+ * Dit si un secret de connexion se refuse : en production, sans échappement
+ * explicite. Seule source de la décision — le firewall la compose au boot.
+ *
+ * @param environment - environnement normalisé du kernel.
+ * @param allowInsecureCredentials - échappement `security.allowInsecureCredentials`.
+ */
+export declare function shouldEnforceCredentialTransport(environment: string | undefined, allowInsecureCredentials: boolean): boolean;
+/**
+ * Refuse, avant toute vérification, un mot de passe ou un code de second
+ * facteur reçu en clair. Une instance partagée au conteneur (`credentialTransport`)
+ * sert TOUTES les portes qui reçoivent un secret : formulaire de session, second
+ * facteur, Basic, émission de jeton — une porte oubliée serait le canal clair.
+ *
+ * La décision se prend sur le scheme EFFECTIF (`context.scheme`) : derrière un
+ * proxy qui termine TLS et déclaré de confiance, il vaut `https` alors que le
+ * pod écoute en HTTP. C'est le cas de la plupart des déploiements ; c'est donc
+ * `trustProxy` que nomme le journal, pas « passez en HTTPS ».
+ */
+export declare class CredentialTransportPolicy {
+    #private;
+    readonly enforce: boolean;
+    constructor(options: ICredentialTransportPolicyOptions);
+    /**
+     * Laisse passer un secret reçu sur TLS, ou n'importe lequel hors production.
+     *
+     * @param context - contexte de la requête qui porte le secret.
+     * @param door - porte qui le reçoit, nommée dans le journal.
+     * @throws InsecureTransportError (403) — secret reçu en clair en production.
+     */
+    assert(context: ICredentialTransportContext, door: string): void;
+}