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

package/dist/types/nodefony/src/authenticator/ExternalSubjectResolver.d.ts

@@ -0,0 +1,99 @@
+import { type Container } from "nodefony";
+import { type IUser } from "@nodefony/user";
+import type { ISecuredArea } from "../../contracts/ISecuredArea.js";
+import { type ExternalSubjectMapping } from "./externalSubject.js";
+import type { ISecurityConfig } from "../../config/defineModuleConfig.js";
+import { type IProviderRoleMapping } from "../oauth/providerRoles.js";
+/** Comment le sujet d'un jeton devient un utilisateur de cette application. */
+export type ExternalSubjectPolicy = "require" | "ephemeral";
+/** Un émetteur reconnu, et la façon dont ses sujets entrent chez nous. */
+export interface IExternalIssuerBinding {
+    /** Émetteur de confiance, sous sa forme canonique. */
+    issuer: string;
+    /** Comment le `sub` de CET émetteur devient un identifiant local. */
+    subjectMapping: ExternalSubjectMapping;
+}
+/** Ce que la fabrique doit fournir à l'authenticator. */
+export interface IExternalJwtAuthenticatorOptions {
+    /**
+     * Émetteurs de confiance, et leur politique de sujet.
+     *
+     * La liste sert à deux choses, qu'il ne faut pas confondre : reconnaître les
+     * jetons qui relèvent de cet authenticator (aiguillage — elle n'accorde
+     * rien, le vérificateur refait le contrôle sur sa propre liste), et savoir
+     * dans quel espace de noms lire le sujet de chacun.
+     */
+    issuers: readonly IExternalIssuerBinding[];
+    /** Politique de rattachement du sujet à un utilisateur local. */
+    subjectPolicy: ExternalSubjectPolicy;
+    /** Rôles accordés en mode `ephemeral`. */
+    ephemeralRoles: readonly string[];
+    /**
+     * Fournisseurs de CONNEXION (`oauth2.providers`) qui déclarent leur émetteur.
+     *
+     * Quand l'émetteur d'un jeton est celui d'un fournisseur de connexion, la
+     * même personne a pu se connecter par le navigateur : son compte local porte
+     * alors le lien `(fournisseur, sub)`. Le chercher d'abord évite qu'un jeton
+     * d'API désigne un AUTRE compte que la session de son porteur.
+     */
+    oauthProviders?: readonly {
+        name: string;
+        issuer: string;
+        /**
+         * Table de correspondance des rôles du fournisseur, compilée — absente ou
+         * `null` : les rôles du compte lié restent locaux.
+         */
+        roleMapping?: IProviderRoleMapping | null;
+    }[];
+}
+/**
+ * Les options de rattachement des sujets externes, lues dans la configuration
+ * de sécurité — UNE lecture, pour la zone `external-jwt` comme pour le
+ * résolveur de compte d'une ressource protégée.
+ *
+ * @param config - configuration de sécurité validée
+ * @returns émetteurs, politique de sujet, fournisseurs de connexion liables
+ */
+export declare function externalSubjectOptions(config: ISecurityConfig): IExternalJwtAuthenticatorOptions;
+/**
+ * Établit l'utilisateur applicatif que désigne le sujet d'un jeton TIERS —
+ * la décision qui transforme « un annuaire a authentifié ce sujet » en « ce
+ * compte agit chez nous ».
+ *
+ * UNE implémentation, deux consommateurs : la zone `external-jwt` du pare-feu
+ * (`ExternalJwtAuthenticator`) et le résolveur de compte d'une ressource
+ * protégée (porte MCP). Recopiée, la règle d'espace de noms aurait divergé dès
+ * le premier émetteur ajouté — et c'est elle qui empêche un annuaire tiers de
+ * réclamer le compte local `admin`.
+ */
+export declare class ExternalSubjectResolver {
+    #private;
+    /**
+     * @param container - container DI (résolution lazy de `users`)
+     * @param options - émetteurs reconnus et politique de rattachement
+     */
+    constructor(container: Container, options: IExternalJwtAuthenticatorOptions);
+    /**
+     * L'émetteur revendiqué est-il l'un des nôtres ? Ne lève JAMAIS : la valeur
+     * vient d'un jeton que n'importe qui peut forger.
+     *
+     * @param issuer - émetteur lu dans le jeton, non vérifié
+     */
+    recognizes(issuer: string): boolean;
+    /**
+     * Établit l'utilisateur applicatif à partir du sujet d'un jeton VÉRIFIÉ.
+     *
+     * Les deux politiques répondent à deux questions différentes : « qui, chez
+     * nous, est cette personne ? » et « quel pouvoir accorde-t-on à une machine
+     * que l'annuaire a authentifiée ? ».
+     *
+     * @param issuer - émetteur canonique, tel que le vérificateur l'a établi
+     * @param subject - sujet brut (`sub`) chez cet émetteur
+     * @param claims - revendications du jeton (rôles d'annuaire)
+     * @param area - zone qui SURCHARGE la politique, s'il y en a une
+     * @throws AuthenticationError (401) — sujet sans compte local utilisable
+     * @throws UnverifiableTokenError (503) — émetteur vérifié mais absent de la
+     *   table de rattachement : configuration incohérente
+     */
+    resolve(issuer: string, subject: string, claims: Readonly<Record<string, unknown>> | undefined, area?: ISecuredArea): Promise<IUser>;
+}

package/dist/types/nodefony/src/authenticator/FirewallRealtimeAuthenticator.d.ts

@@ -1,3 +1,4 @@
+import type { IUserProvider } from "@nodefony/user";
 import type { IRealtimeAuthenticator, IRealtimeHandshake, IRealtimeToken } from "../realtime/realtimeContracts.js";
 /**
  * Authenticator realtime des identités résolues par le **firewall** — équivalent
@@ -50,8 +51,10 @@ export declare class FirewallRealtimeAuthenticator implements IRealtimeAuthentic
      * @param resolveStore - fournit le store de révocation des jetons (le firewall
      *   passe une closure sur son container). Omis → mode dégradé documenté :
      *   seules les bornes portées par le jeton lui-même sont vérifiables.
+     * @param resolveUsers - fournit l'annuaire des comptes (`users`). Omis → pas
+     *   de confirmation du compte avant `api.request`.
      */
-    constructor(resolveStore?: (() => IRealtimeRevocationStore | null) | null);
+    constructor(resolveStore?: (() => IRealtimeRevocationStore | null) | null, resolveUsers?: (() => IUserProvider | null) | null);
     /** Une identité authentifiée a-t-elle été résolue (par le firewall) au handshake ? */
     supports(_handshake: IRealtimeHandshake): boolean;
     /**

package/dist/types/nodefony/src/authenticator/JwtAuthenticator.d.ts

@@ -1,5 +1,6 @@
-import type { Container } from "nodefony";
+import type { Container, IAccessPrincipal } from "nodefony";
 import type { ContextType } from "@nodefony/http";
+import type { IUser } from "@nodefony/user";
 import type { IAuthenticator } from "../../contracts/IAuthenticator.js";
 import type { IToken } from "../../contracts/IToken.js";
 import type { IJwtRuntime } from "../token/jwtRuntime.js";
@@ -59,6 +60,41 @@ export declare class JwtAuthenticator implements IAuthenticator {
      *   firewall puis 401 fail-closed (rien ne fuite au client).
      */
     authenticate(token: IToken): Promise<IToken>;
+    /**
+     * Vérifie un jeton émis par CETTE application pour une ressource protégée
+     * nommée par l'appelant — la porte d'une ressource (RFC 8707), pas une zone.
+     *
+     * Les MÊMES règles que {@link authenticate}, appliquées par la même fonction :
+     * signature par le keyset local, `iss`, `typ: at+jwt`, révocation ciblée
+     * (`jti`) et en masse (`invalidBefore`), compte encore actif. Seule
+     * l'audience diffère : c'est celle de la ressource qui appelle, et elle est
+     * exigée. Un jeton révoqué, ou celui d'un compte désactivé, n'ouvre donc pas
+     * plus une porte MCP qu'une route — ce que la vérification par le seul jeu de
+     * clés publiques laissait passer jusqu'à l'expiration.
+     *
+     * @param raw - le jeton présenté, brut
+     * @param audience - l'URI canonique de la ressource qui le reçoit
+     * @returns le principal établi, ou `null` pour tout refus (contrat
+     *   `IAccessTokenVerifier` : un refus n'est jamais une exception)
+     * @throws Error si le câblage manque (keystore, store, annuaire) — la porte
+     *   le traduit en `503`, jamais en jeton accepté
+     */
+    verifyForResource(raw: string, audience: string): Promise<IAccessPrincipal | null>;
+    /**
+     * Recharge le compte que désigne un principal établi par
+     * {@link verifyForResource} — pour une ressource protégée qui fait agir un
+     * outil au nom du propriétaire du jeton.
+     *
+     * La MÊME règle que la zone ({@link loadBoundAccount}), rejouée sur les
+     * revendications du principal : le vérificateur ne garde pas le compte qu'il
+     * a lu, et une seconde lecture de l'annuaire est le coût accepté d'un outil
+     * qui la demande — les autres ne la paient pas.
+     *
+     * @param principal - principal d'un jeton émis par CETTE application
+     * @returns le compte, ou `null` s'il n'est pas (ou plus) celui du jeton
+     * @throws Error si l'annuaire des comptes n'est pas câblé
+     */
+    resolveAccount(principal: IAccessPrincipal): Promise<IUser | null>;
     /** Slot audit (J4b). */
     onSuccess(_context: ContextType, _token: IToken): Promise<void>;
     /** Slot audit (J4b) — le 401 + challenge sont posés par le firewall. */

package/dist/types/nodefony/src/net/transportFailure.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Rend un échec de transport LISIBLE : `fetch` (undici) ne dit que
+ * `fetch failed` et range la vraie raison dans `cause` — certificat refusé,
+ * connexion refusée, nom introuvable.
+ *
+ * @param error - ce que `fetch` (ou une bibliothèque qui l'appelle) a levé
+ * @returns `message (CODE : raison)`, ou le message seul faute de cause
+ */
+export declare function describeTransportFailure(error: unknown): string;
+/**
+ * Le remède d'un certificat signé par une autorité que le processus ne
+ * reconnaît pas — `null` pour tout autre échec.
+ *
+ * En développement, Nodefony reconnaît d'office l'autorité qu'il a générée ; en
+ * production jamais, et c'est voulu. Sans ce remède, le journal ne montrait que
+ * `SELF_SIGNED_CERT_IN_CHAIN` : la variable qui le règle n'était écrite que dans
+ * un commentaire du `.env`, fichier qu'un serveur de production n'a pas.
+ *
+ * @param error - ce que `fetch` (ou une bibliothèque qui l'appelle) a levé
+ * @returns une phrase d'action, ou `null`
+ */
+export declare function untrustedAuthorityHint(error: unknown): string | null;

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

@@ -1,11 +1,3 @@
-/**
- * Lecture BORNÉE d'un corps JSON — la brique de transport commune aux trois
- * appels sortants du social login (découverte, point de jeton, API d'un
- * fournisseur non-OIDC).
- *
- * Elle existe parce qu'une borne posée APRÈS `response.text()` ne protège plus
- * rien : le corps est déjà entièrement en mémoire quand on mesure sa longueur.
- */
 /**
  * Lit un corps JSON en refusant de dépasser une taille — la borne est vérifiée
  * PENDANT la lecture, pas après : un corps déjà entièrement en mémoire ne se

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/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/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[];