Autorisation — le jury de voters (rôles, scopes, ownership)

stable@nodefony/securitymis à jour 2026-07-19

L’authentification établit qui tu es ; l’autorisation établit ce que tu as le droit de faire. Nodefony décide de chaque accès via un jury de voters : stratégie affirmative + veto DENY, et défaut DENY (Zero Trust — le silence ferme la porte). Deux voters intégrés (role, scope), un contrat ouvert pour la logique métier (ownership, multi-tenant). Ancré sur src/packages/@nodefony/security/nodefony/service/authorization.ts et nodefony/src/voter/.

📍 Documentation › Sécurité › Autorisation

🧠 Le modèle mental — un jury qui vote#

Trois règles, et une seule ferme la porte par défaut :

1. Un DENY suffit à bloquer (veto), et court-circuite le reste du jury.
2. Sinon un GRANT suffit à accorder.
3. Silence total (tous ABSTAIN, ou aucun voter compétent) → DENY. C’est le Zero Trust : on n’accorde jamais « par absence d’objection ».

📖 Lexique#

Qu’est-ce que l’autorisation — et quelle faille elle ferme#

Le contrôle d’accès défaillant est la faille n°1 du top OWASP (A01) : un utilisateur atteint une ressource qui n’est pas la sienne (IDOR), ou une action au-dessus de son niveau (élévation de privilège). La cause récurrente est un contrôle dispersé et optionnel — un endpoint oublie de vérifier.

Nodefony centralise la décision dans un service unique, appelé par les décorateurs (@IsGranted, @RequireScope) sur tous les transports, avec une posture fail-closed : au moindre doute (voter qui plante, silence du jury, moteur absent), c’est refusé — jamais accordé.

Où se situe Nodefony parmi les modèles de contrôle d’accès#

Le contrôle d’accès a plusieurs façons de répondre à « as-tu le droit ? », selon ce sur quoi la décision porte : un rôle porté par le compte (RBAC), des attributs du sujet, de la ressource et du contexte (ABAC), une relation dans un graphe (ReBAC), ou une politique écrite hors du code (XACML, et les moteurs qui s’en inspirent). Ce ne sont pas des concurrents : les systèmes réels en empilent plusieurs.

Nodefony fait du RBAC hiérarchique — des rôles, et une hiérarchie qui dit lesquels en couvrent d’autres, au sens des composantes Core et Hierarchical du modèle NIST (ANSI INCITS 359-2004, révisée 2012). Le reste se branche au jury, décrit plus bas : un voter maison qui lit des attributs fait de l’ABAC, un voter qui interroge un moteur de graphe (OpenFGA, SpiceDB, Ory Keto — famille issue de l’article Zanzibar, Google, 2019) fait du ReBAC.

Ce qui n’est PAS couvert, et qu’il vaut mieux savoir avant de concevoir :

• la séparation des devoirs (deux rôles incompatibles sur un même compte) n’est pas outillée ; elle se joue à l’affectation des rôles, pas à la décision ;
• le filtrage d’une liste — « montre-moi seulement les lignes que j’ai le droit de voir » — ne passe pas par le jury : chaque décision porte sur une ressource. Ce filtrage appartient à ta requête de dépôt ;
• le contexte de la requête (heure, adresse, en-têtes, corps) n’est pas au contrat d’un voter ; ce qui lui parvient, c’est le jeton et le sujet ;
• aucune décision « accordé, à condition que » (les obligations de XACML) : le verdict est binaire.

En pratique, et c’est le cas dans 95 % des applications : des rôles, plus un voter d’ownership pour les cas où le rôle ne suffit pas.

La vision Nodefony — un jury découplé et fail-closed#

Authorization.decide(token, attribute, subject?) (authorization.ts#Authorization.decide) itère les voters, teste supports() en place — zéro allocation par appel (authorization.ts#Authorization.decide) — et applique la stratégie ci-dessus. Points structurants :

• Fail-closed sur erreur : un voter qui throw (lookup DB down, bug) ne fait ni accorder l’accès ni planter la requête en 500 — on refuse cette décision + log ERROR (authorization.ts#Authorization.decide). Même posture que le firewall sur une erreur interne.
• Découverte par registre : les voters sont instanciés une fois au boot par Authorization.#build() (authorization.ts#Authorization.#build) depuis le registre — aucun nom en dur dans le service. Les builtins role/scope s’enregistrent à l’import (voterRegistry.ts).
• Transport-agnostique : l’audit lit getUserIdentifier() (et non getUser()), commun au token HTTP et au token WS IRealtimeToken (authorization.ts#Authorization.#auditDeny).
• Audit asymétrique : tout refus est audité par Authorization.#auditDeny() — WARNING + recordAudit (authorization.ts#Authorization) ; les octrois restent muets (volume, pas un signal). Le refus porte sa raison : veto / abstain / no-voter / error.

🚀 Démarrage rapide#

Déclarer les droits sur tes actions — les trois axes#

Dans une app nodefony create app, la zone secure du scaffold (^/api/secure, voir firewall) authentifie déjà ; ici on décide des droits :

// nodefony/controllers/DocumentController.ts — complet, compile tel quel
import {
  controller,
  Controller,
  Get,
  Post,
  Param,
  IsGranted,
  RequireScope,
  CurrentUser,
} from "@nodefony/framework";
import type { ContextType } from "@nodefony/http";
import type { IUser } from "@nodefony/user";

@controller("/api/secure/documents")
class DocumentController extends Controller {
  constructor(context: ContextType) {
    super("DocumentController", context);
  }

  // Axe RÔLE (« qui tu es ») : réservé aux admins — hiérarchie résolue
  // (ROLE_NODEFONY_ADMIN hérite ROLE_ADMIN → passe aussi).
  @IsGranted("ROLE_ADMIN")
  @Post("/purge")
  purge(@CurrentUser() user: IUser) {
    return this.renderJson({ purgedBy: user.identifier });
  }

  // Axe SCOPE (« ce qu'une CLÉ peut faire ») : bride une clé API / un JWT ;
  // no-op pour une session humaine (ses droits passent par ses rôles).
  @RequireScope("documents:read")
  @Get("/")
  list(@CurrentUser() user: IUser) {
    return this.renderJson({ reader: user.identifier, roles: user.roles });
  }

  // Axe MÉTIER : le param de route `id` part au voter comme `subject`.
  @IsGranted("doc.edit", { subject: "id" })
  @Post("/{id}")
  edit(@Param("id") id: string) {
    return this.renderJson({ edited: id });
  }
}

export default DocumentController;

(Wiring : @controllers([DocumentController]) dans le module de l’app — nodefony create controller le fait pour toi.)

Ce qu’on observe#

# 1) Sans session : le FIREWALL répond 401 — l'autorisation n'a même pas été consultée
curl -si http://localhost:5151/api/secure/documents/ | head -1
# HTTP/1.1 401 Unauthorized

# 2) Session d'un utilisateur ROLE_USER (cookie posé par le login BFF, cf. firewall) :
#    le scope est un no-op pour un humain → 200
curl -s -b /tmp/jar http://localhost:5151/api/secure/documents/
# {"reader":"alice","roles":["ROLE_USER"]}

# 3) Même session sur l'action admin → 403 : authentifié MAIS pas autorisé
curl -si -b /tmp/jar -X POST http://localhost:5151/api/secure/documents/purge | head -1
# HTTP/1.1 403 Forbidden

Le refus laisse une trace côté serveur (jamais côté client) :

WARNING AUTHORIZATION access denied: "alice" → "ROLE_ADMIN" (abstain)

401 vs 403 : 401 = « prouve qui tu es » (authentification, firewall) ; 403 = « je sais qui tu es, tu n’as pas le droit » (autorisation, jury).

Le voter métier — ta règle d’ownership branchée au jury#

Pour l’attribut doc.edit déclaré ci-dessus, on enregistre un voter — découvert automatiquement au boot, aucun changement dans le cœur :

// nodefony/security/DocumentVoter.ts — chargé par le module de l'app (avant le boot)
import { registerVoterFactory, VoterVote } from "@nodefony/security";
import type { IAccessVoter, IToken } from "@nodefony/security";

/** Le repository de TES documents (posé au container par ton module). */
interface IDocumentRepository {
  find(id: string): Promise<{ ownerId: string; archived: boolean } | null>;
}

class DocumentVoter implements IAccessVoter {
  constructor(private readonly repository: () => IDocumentRepository | null) {}

  /** Ne capte QUE `doc.edit` — rôles et scopes restent aux voters intégrés. */
  supports(attribute: string): boolean {
    return attribute === "doc.edit";
  }

  async vote(
    token: IToken,
    _attribute: string,
    subject?: unknown,
  ): Promise<VoterVote> {
    const repo = this.repository();
    const doc =
      repo && typeof subject === "string" ? await repo.find(subject) : null;
    if (!doc) return VoterVote.ABSTAIN; // hors de mon domaine → les autres axes décident
    if (doc.archived) return VoterVote.DENY; // veto EXPLICITE : personne n'édite un archivé
    return doc.ownerId === token.getUserIdentifier()
      ? VoterVote.GRANT
      : VoterVote.ABSTAIN; // pas le sien → le default-DENY du jury ferme
  }
}

// Découvert automatiquement par le service `authorization` au boot.
registerVoterFactory("documentVoter", ({ container }) => {
  // Construction seule ici — la résolution du repository reste lazy.
  return new DocumentVoter(() =>
    container.get<IDocumentRepository>("documentRepository"),
  );
});

Observable : le propriétaire obtient 200 sur POST /api/secure/documents/42 ; un autre utilisateur connecté obtient 403 et le log dit access denied: "bob" → "doc.edit" on 42 (abstain).

⚠️ Attention

Dans un voter métier, renvoie ABSTAIN quand tu ne sais pas te prononcer (document introuvable, attribut hors domaine) — pour laisser les autres axes décider. Réserve DENY au veto explicite (ressource gelée/bannie) : un DENY bat tous les GRANT du même attribut.

🧑‍⚖️ La stratégie du jury en situation#

Situation 1 — rôle OU voter métier ? (l’IDOR ne se ferme pas par un rôle)#

Ton app édite des documents : POST /api/secure/documents/{id} doit être réservé au propriétaire. Or tous tes utilisateurs connectés portent ROLE_USER :

@IsGranted("ROLE_USER")                    // ❌ ferme la porte aux anonymes… mais PAS l'IDOR :
@Post("/{id}") edit() {}                   //    alice peut éditer le document de bob

@IsGranted("doc.edit", { subject: "id" })  // ✅ le jury reçoit l'id → le voter tranche sur la DONNÉE
@Post("/{id}") edit() {}

Règle de choix : un rôle décide d’une catégorie d’action (« qui peut purger ? ») ; un voter métier décide sur la donnée (« CE document est-il le sien ? »). Si la réponse exige un lookup (ownership, tenant, état), c’est un voter.

Situation 2 — le veto DENY (gel légal : personne, même pas le propriétaire)#

Conformité : un document sous gel légal (litige en cours) ne doit être édité par personne — pas même son propriétaire. On ajoute un second voter qui capte le même attribut doc.edit :

class LegalHoldVoter implements IAccessVoter {
  supports(attribute: string): boolean {
    return attribute === "doc.edit";
  }
  async vote(
    _token: IToken,
    _attribute: string,
    subject?: unknown,
  ): Promise<VoterVote> {
    return (await isUnderLegalHold(subject))
      ? VoterVote.DENY
      : VoterVote.ABSTAIN;
  }
}

Dès le DENY, le jury s’arrête — court-circuit, inutile de finir (authorization.ts#Authorization.decide).

Contre-exemple piégeux : le veto ne traverse pas une clause OR. Dans @IsGranted(["ROLE_ADMIN", "doc.edit"]), chaque attribut est un jury séparé (Resolver.ts#Resolver._enforceSecurity) : si ROLE_ADMIN est accordé, doc.edit — et son veto — n’est même pas consulté. Un interdit absolu se porte en clause AND : empiler @IsGranted("ROLE_ADMIN") puis @IsGranted("doc.edit", { subject: "id" }).

Situation 3 — le silence ferme la porte (la typo devient un 403, pas une faille)#

Tu déploies @IsGranted("doc.edti") (faute de frappe), ou tu as oublié d’enregistrer ton voter. Aucun voter compétent → refus par défaut (!granted, authorization.ts#Authorization) : la route répond 403 systématiquement, et le log nomme la cause :

WARNING AUTHORIZATION access denied: "alice" → "doc.edti" (no-voter)

Un framework fail-open aurait laissé passer — la typo serait une faille silencieuse. Ici elle se voit au premier test.

💡 Astuce

La raison entre parenthèses dit quoi corriger : no-voter = aucun voter ne capte l’attribut (typo, voter non enregistré) · abstain = des voters ont regardé, aucun n’a accordé (droit manquant) · veto = un DENY explicite · error = un voter a planté (voir le log ERROR).

🧰 Déclarer l’exigence — @IsGranted, @RequireScope, @Anonymous#

Les décorateurs n’écrivent que des métadonnées (0 import @nodefony/security, 0 cycle) ; le moteur authorization est résolu par nom au runtime (Resolver.ts#Resolver._callWithIdempotency) :

La garde s’évalue dans Resolver.executeAction() AVANT l’instanciation DI du controller — un 403 court-circuite tout, y compris initialize() (_enforceSecurity, Resolver.ts#Resolver._enforceSecurity). Le même executeAction sert le pipeline HTTP et l’invoke WS-RPC : une garde, tous les transports. L’enforcement déroule chaque clause : OR interne via un decide() par attribut, AND entre clauses (Resolver._enforceSecurity(), Resolver.ts#Resolver._enforceSecurity).

❗ Important

Fail-closed intégral : route gardée mais moteur authorization absent (module security non chargé) OU aucune identité résolue (route hors zone firewall) → 403 direct (Resolver.ts#Resolver._callWithIdempotency). Une route gardée doit être couverte par une zone — voir firewall.

🧑‍⚖️ Les voters intégrés — deux axes, un même jury#

Qui OBTIENT un scope — grantableScopes#

Le voter scope contrôle un scope à l’usage : il regarde ce que le jeton porte, jamais comment il l’a obtenu. @RequireScope("vitrine:write") et les scopes d’un outil MCP sont des contrôles d’usage. Reste à décider qui a le droit de recevoir ce scope : sans réponse, l’émetteur de l’application l’accorde à tout compte connecté qui le demande, et le contrôle d’usage ne filtre plus rien.

use("@nodefony/security", {
  grantableScopes: {
    "vitrine:write": ["ROLE_ADMIN"], // un scope exact
    "shop:*": ["ROLE_SHOP"], // une famille
    "shop:refund": ["ROLE_SHOP_MANAGER"], // l'exact l'emporte sur la famille
  },
});

• Clé : un scope exact, ou une famille préfixe:*. Une clé exacte l’emporte sur une famille, la famille la plus longue sur une plus courte ; l’ordre des clés ne décide de rien (ScopeGrantPolicy.rolesFor(), scopeGrants.ts#ScopeGrantPolicy.rolesFor).
• Valeur : les rôles dont un suffit, hiérarchie de rôles comprise. Une liste vide est refusée au démarrage : pour n’accorder un scope à personne, on ne l’expose pas.
• Non déclaré : le scope reste accordé à tout compte connecté. Rien ne change pour une application qui ne déclare rien.
• Refusées au démarrage : admin:read, admin:write et admin:*, réservés au plan d’administration du framework (scopeGrantKeyProblem(), scopeGrants.ts#scopeGrantKeyProblem). Le message nomme la clé et la raison.

Un seul juge pour les deux émetteurs de l’application, et pour les deux familles de scopes (refusedScopes(), scopeGrants.ts#refusedScopes) :

grantableScopes ne borne pas un jeton signé par un émetteur tiers (Keycloak…) : celui-ci accorde selon sa propre politique. Et ce n’est pas une règle de zone : un jeton ne sait pas quelle zone le lira, et security:mcp:token signe sans aucune requête.

Depuis un module. Un module complète la section par module-security dans sa configuration (voir configuration). Un préfixe = un propriétaire : la fusion de configuration fusionne les listes case par case, si bien qu’une clé déclarée à deux endroits mêle les deux listes de rôles.

La hiérarchie de rôles — aplatie et vérifiée au boot#

RoleHierarchyWalker se déclare dans la config (use("@nodefony/security", { roleHierarchy }), voir firewall) et fait deux choses au boot :

• Aplatissement DFS précalculé (#detectCycles() puis #precompute(), RoleHierarchyWalker.ts#RoleHierarchyWalker.#precompute) → RoleHierarchyWalker.hasRole() est O(1) sur le hot path (RoleHierarchyWalker.ts#RoleHierarchyWalker.hasRole).
• Détection de cycles par DFS coloré — un arc vers un nœud « en cours de visite » = cycle, et le boot jette avec le chemin complet A → B → A (RoleHierarchyWalker.ts#RoleHierarchyWalker.#detectCycles) : jamais de boucle infinie silencieuse en production.

🛡️ Le rôle par défaut d’une zone — et ce qu’il n’écrase pas#

Une zone du pare-feu peut exiger un rôle par défaut chez elle (roles, voir firewall). C’est le filet d’un espace d’administration : une route que personne n’a pensé à garder hérite du rôle de sa zone, au lieu d’être ouverte à tout compte connecté.

La précédence est un remplacement, jamais un cumul de rôles : si l’action déclare sa propre garde de rôle, c’est elle qui décide — y compris pour ouvrir plus largement que la zone. C’est voulu : une page réservée à l’exploitant (ROLE_SUPERVISOR) doit rester atteignable dans une zone fermée à l’administrateur de plateforme.

Quatre cas gardent la main, et chacun est une déclaration explicite :

🔴 @RequireScope seul n’est pas une décision d’identité. Un scope dit ce qu’une clé déléguée peut faire en ton nom ; sur une session humaine, le voter de scope accorde sans condition. Une action gardée par un scope seul reste donc soumise au rôle de sa zone — les deux axes se cumulent. Les traiter comme interchangeables ouvrait la route à tout compte connecté.

Le dernier cas mérite d’être compris, parce qu’il ressemble à un trou sans en être un : une frame api.request {path} repasse par la même décision que la requête HTTP équivalente. L’invariant tenu est api.request {path} ≤ GET {path}.

🚪 Trois portes décident — et deux ne passent pas par le jury#

C’est la chose la plus utile à savoir avant d’écrire un voter, et la plus facile à ignorer :

Les trois appliquent la hiérarchie de rôles, donc un même rôle y rend le même verdict. Mais un voter maison — ABAC, ReBAC, ownership — n’est consulté que par la première. Une règle métier qui doit valoir partout se place donc dans le code de l’action, pas seulement dans un voter.

🧩 Étendre le jury — le contrat et le registre#

Le contrat IAccessVoter (IAccessVoter.ts#IAccessVoter) tient en deux méthodes :

• supports(attribute, subject?) — test bon marché : ce voter sait-il décider de cet attribut ? Appelé sur chaque voter à chaque decide().
• vote(token, attribute, subject?) — async (les voters métier font des lookups DB) ; renvoie un VoterVote : GRANT / DENY / ABSTAIN (IAccessVoter.ts#VoterVote).

L’enregistrement passe par le registre — registerVoterFactory(name, factory) (voterRegistry.ts#registerVoterFactory), consommé une fois au boot (listVoterFactories(), voterRegistry.ts#listVoterFactories). La fabrique reçoit { container } et ne fait que construire : les résolutions coûteuses restent lazy dans l’instance (cf. le DocumentVoter du Démarrage rapide).

Pourquoi un registre et pas un scan DI des @injectable : les interfaces TS sont effacées à la compilation — rien à scanner au runtime ; le registre est le marqueur explicite (voterRegistry.ts#IVoterFactoryContext). Convention-frère : authenticatorRegistry, tokenStoreRegistry.

🔌 HTTP et WebSocket — une garde, N transports#

• La même garde : Resolver.executeAction() (Resolver.ts#Resolver.executeAction) est le point unique d’enforcement — pipeline HTTP classique et invoke WS-RPC (pont api.request). Un @IsGranted protège donc l’action quel que soit le transport (prouvé bout en bout par le banc ws-isgranted-jwt).
• Le service ignore le transport : l’audit lit getUserIdentifier(), commun à IToken (HTTP) et IRealtimeToken (WS) (authorization.ts#Authorization.#auditDeny).
• Le verrou de frame (canaux realtime) applique son RBAC par canal avec la même hiérarchie : satisfies() (frameAuthorizer.ts#satisfies) délègue à Firewall.hasRole() (firewall.ts#Firewall.hasRole) — les rôles exigés par un canal héritent comme partout ailleurs.

📜 Normes appliquées#

Ce tableau dit ce que le code fait, pas ce qu’il revendique : Nodefony n’est pas « conforme ANSI 359 » (ni sessions de rôles, ni séparation des devoirs), pas « conforme XACML » (un seul algorithme de combinaison, aucune obligation), et pas « compatible Zanzibar » (pas d’expansion, pas de liste, pas de jeton de cohérence). Ce qu’il offre, c’est de quoi brancher ces moteurs pour une décision ponctuelle.

⚡ Performance & mémoire#

• Hot path à coût nul : une route non gardée porte security: null → 0 lookup, 0 await, 0 alloc (Resolver.ts#Resolver._enforceActionSecurity) ; l’exigence est figée une fois par route et partagée entre requêtes (SecurityRequirement, routerDecorators.ts#SecurityRequirement).
• decide() sans allocation : itération en place des voters (authorization.ts#Authorization.decide), instanciés une seule fois au boot (authorization.ts#Authorization.decide).
• hasRole() O(1) : hiérarchie aplatie au boot, rien de récursif par requête (RoleHierarchyWalker.ts#RoleHierarchyWalker.hasRole).
• Audit = cold path : uniquement sur refus, avec un descripteur léger du sujet — jamais de JSON.stringify aveugle (describeSubject(), authorization.ts#describeSubject).

⚠️ Pièges (symptôme → cause → correction)#

📡 Observabilité — Studio#

Écran Roles (studio/frontend/src/routes/Roles.tsx) : la hiérarchie de rôles consommée par les voters. Écran Audit : les refus du jury (catégorie authz, action access.denied, avec la raison). Écran Firewall : zones et trace de décision — l’amont du jury.

🧪 Tests & couverture#

Quatre familles couvrent la brique — les chiffres exacts vivent dans la carte de l’aperçu (régénérée depuis vitest, jamais figée ici) :

• unit : authorization.test (le jury + la stratégie + le RoleVoter/hiérarchie), scopeVoter (l’axe scope + fail-closed machine), securityDecorators et securityEnforcement (framework : métadonnées + garde du Resolver), realtimeFrameLock (le verrou de frame) ;
• intégration : securityGuard.integration (framework, la garde @IsGranted sur serveur réel), ws-data-plane-auth (http, le pont WS authentifié) ;
• e2e transport : ws-isgranted-jwt (http — @IsGranted bout en bout sur WebSocket + JWT) ;
• attaque : authorization.attack (escalade verticale, cycle DoS, confusion d’attribut, composition d’axes), frameAuthorizer.attack et realtimeFramePollution.attack (frames WS hostiles).

Couverture : npm run coverage dans @nodefony/security.

🔗 Pour aller plus loin#

• ⬆️ Retour au hub : Sécurité — vue d’ensemble · Toute la documentation

• 🧭 Pages sœurs : Firewall · Jetons

• L’authentification qui précède l’autorisation → authenticators

• Le firewall qui pose l’identité et appelle le jury (zones, WS) → firewall

• Vue d’ensemble sécurité → index