Firewall — le pare-feu applicatif

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

Pour chaque requête (HTTP comme WebSocket), le firewall répond à trois questions dans l’ordre : est-ce une zone protégée ? qui es-tu ? as-tu le droit ? La politique par défaut est Zero Trust : sur une zone protégée, pas de preuve d’identité valide = 401. Ancré sur src/packages/@nodefony/security/nodefony/service/firewall.ts et les authenticators de nodefony/src/authenticator/.

📍 Documentation › Sécurité › Firewall

🧠 Le modèle mental — chemin chaud, chemin froid#

Le firewall sépare détecter (chaud, sur chaque requête) et décider (froid, seulement zone protégée) — pour ne pas payer l’authentification sur les routes publiques.

Firewall.isSecure() (firewall.ts#Firewall.isSecure) rattache la requête à une zone via Firewall.matchPath() (firewall.ts#Firewall.matchPath) ; Firewall.handleSecurity() (firewall.ts#Firewall.handleSecurity) décide. Les zones sont triées par spécificité dans #build() — list.sort par longueur de motif : le plus long gagne, pas le premier déclaré (firewall.ts#Firewall.#build).

📖 Lexique#

🚀 Démarrage rapide#

Dans une app nodefony create app, le firewall est DÉJÀ actif#

Le scaffold déclare trois zones (main, secure, machine) dans nodefony/config/security.ts, importé par nodefony.config.ts ; en voici deux — c’est la forme canonique (un objet par nom, validé Zod au boot : areas: z.record(...), config.ts#securityConfigSchema) :

// nodefony/config/security.ts
import type { ISecurityConfigInput } from "@nodefony/security";

export const securityConfig = () =>
  ({
    areas: {
      // Zone de TES routes : `session` PUIS `anonymous` → identifié si cookie,
      // sinon visiteur accepté. Hors zone, l'identité n'est JAMAIS résolue.
      main: {
        pattern: "^/api",
        authenticators: ["session", "anonymous"],
      },
      // Zone PROTÉGÉE — pattern PLUS SPÉCIFIQUE que ^/api : le firewall trie
      // par longueur → /api/secure/* tombe ICI. Pas d'`anonymous` : sans
      // session → 401 AVANT ton controller (Zero Trust).
      secure: {
        pattern: "^/api/secure",
        authenticators: ["session"],
      },
    },
    roleHierarchy: {
      ROLE_NODEFONY_ADMIN: ["ROLE_ADMIN", "ROLE_SUPERVISOR", "ROLE_DEV"],
      ROLE_ADMIN: ["ROLE_USER"],
    },
  }) satisfies ISecurityConfigInput;

❗ Important

Hors zone, l’identité n’est JAMAIS résolue — même connecté, une route non couverte par une zone ne sait pas qui tu es. Une route « publique » qui veut connaître l’utilisateur se couvre par ["session", "anonymous"].

Le login est FOURNI : le module security expose le BFF POST /nodefony/security/api/auth/login (body { username, password } → Set-Cookie de session ; AuthFlow.login régénère l’ID de session — anti-fixation OWASP). Pas de LoginController à écrire.

Ce que TU écris : le controller protégé#

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

@controller("/api/secure/account")
class AccountController extends Controller {
  // Zone `secure` : context.user est GARANTI ici (le firewall a authentifié).
  // @IsGranted ajoute l'AUTORISATION : il faut aussi le rôle.
  @IsGranted(["ROLE_USER"])
  @Get("/me")
  async me(@CurrentUser() user: IUser) {
    // identité ré-résolue à chaque requête → rôles frais, révocation immédiate
    return this.renderJson({ identifier: user.identifier, roles: user.roles });
  }
}

export default AccountController;

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

Ce qu’on observe#

# 1) Sans session : Zero Trust → 401 (aucun code à toi n'a tourné)
curl -si http://localhost:5151/api/secure/account/me | head -1
# HTTP/1.1 401 Unauthorized

# 2) Login BFF (compte dev seedé admin/nodefony-dev-42) → cookie de session
curl -si -c /tmp/jar -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"nodefony-dev-42"}' \
  http://localhost:5151/nodefony/security/api/auth/login | head -1
# HTTP/1.1 200 OK

# 3) Rejouer avec le cookie → 200, identité résolue
curl -s -b /tmp/jar http://localhost:5151/api/secure/account/me
# {"identifier":"admin","roles":["ROLE_NODEFONY_ADMIN", …]}

Protéger une API machine (jwt et/ou apikey)#

use("@nodefony/security", {
  areas: {
    // jwt et apikey cohabitent : discriminés par la FORME du bearer (voir plus bas)
    api: {
      pattern: "^/api/v1",
      authenticators: ["jwt", "apikey"],
      mode: "first",
    },
  },
});

Le client envoie l’un ou l’autre :

Authorization: Bearer eyJhbGciOiJFZERTQS␣…␣.␣…␣.␣…        # un JWT (structure a.b.c)
Authorization: Bearer nf_9a2c…                           # une clé API (préfixe nf_)

Protéger des pages : conduire le visiteur à la connexion (entryPoint)#

Sans réglage, un visiteur anonyme qui ouvre une page protégée reçoit un 401 brut. entryPoint lui donne la page de connexion à la place :

use("@nodefony/security", {
  areas: {
    pages: {
      pattern: "^/compte(/|$)",
      authenticators: ["session"],
      entryPoint: "/login", // la page de connexion du framework (loginPage.path)
    },
  },
});

• La page de connexion ramène au chemin demandé (from, requête comprise) une fois connecté. from passe par safeRedirectPath, la garde anti-redirection ouverte du cœur.
• C’est toujours un refus : l’audit enregistre auth.denied / no_credentials, et le hook onAuthFailure se déclenche, comme pour un 401.
• entryPoint doit être un chemin de l’origine : une adresse externe (https://…, //…) est refusée au démarrage.
• La page de connexion elle-même n’est jamais redirigée vers elle-même : si elle tombe dans la zone, sa requête garde son 401.
• Absent (le défaut), tous les clients reçoivent le 401.

🔐 Les authenticators intégrés#

Tous respectent le même contrat (IAuthenticator) : supports(context) (test bon marché : la requête porte-t-elle ce type de credential ?), createToken() (extrait le credential brut), authenticate(token) (valide + promeut, ou lève un 401), challenge() (l’en-tête WWW-Authenticate). Point commun de sécurité : message d’échec uniforme ("Invalid token" / "Invalid credentials") — la cause fine (expiré, révoqué, sujet banni…) part dans l’audit, jamais au client (anti-énumération).

🗝️ stateless — la zone tient-elle un registre ?#

Une zone dit, par ce drapeau, où vit l’identité — et ce n’est pas la même chose que la liste de ses authentificateurs.

Ce que true évite concrètement : sans lui, un appelant qui envoie un cookie inconnu — un client qui recycle un en-tête, un navigateur qui traîne une vieille session, un attaquant qui en fabrique un — fait reprendre puis réécrire une session serveur et repartir un Set-Cookie, y compris quand la réponse est un 401. Un registre pour quelqu’un qui ne le relira jamais.

🔴 stateless: true et "session" dans la même zone est une contradiction, et l’application REFUSE de démarrer en la nommant (SessionAuthenticator.validateArea). Une zone sert un navigateur ou un porteur de preuve. Si les deux publics doivent atteindre la même fonctionnalité, ce sont deux zones — le firewall trie par longueur de motif, donc la plus spécifique gagne.

Une route qui demande une session (@UseSession) sous une zone stateless ne l’emporte pas : la zone est la déclaration de sécurité, elle gagne, et le journal le dit une fois par zone au lieu de laisser chercher pourquoi context.session est nul.

⚙️ Ordre et modes (mode: "first" vs "all")#

La liste area.authenticators se lit dans l’ordre, déroulée par Firewall.#authenticate() (firewall.ts#Firewall.#authenticate). Le mode dit comment la parcourir. Trois situations concrètes :

Situation 1 — humains ET machines sur la même API (first, le mode courant)#

Ton back-office est appelé par le navigateur des utilisateurs connectés ET par un script CI. Deux preuves différentes, mêmes routes :

back: {
  pattern: "^/api/back",
  authenticators: ["session", "apikey"],
  mode: "first",   // (défaut) le PREMIER qui reconnaît la requête authentifie
},

Ce qui se passe, requête par requête :

Situation 2 — le piège de l’ordre (anonymous toujours EN DERNIER)#

Tu veux « identifié si connecté, sinon visiteur » :

authenticators: ["session", "anonymous"],   // ✅ session d'abord
authenticators: ["anonymous", "session"],   // ❌ anonymous accepte TOUT le monde

AnonymousAuthenticator.supports() accepte toutes les requêtes — placé en premier en mode first, il court-circuite la liste : personne n’est jamais identifié, même avec un cookie valide. L’ordre est ta politique.

Situation 3 — le « sudo mode » (all : empiler les preuves)#

Une action destructrice (suppression de compte, rotation des clés) doit exiger la session ET une re-saisie du mot de passe — même logique que GitHub avant une action sensible :

danger: {
  pattern: "^/api/back/danger",
  authenticators: ["session", "userpassword"],
  mode: "all",   // CHAQUE maillon est obligatoire
},

Le client doit présenter les deux preuves dans la même requête (cookie + Authorization: Basic …). Une seule manque → 401. Le dernier token de la chaîne porte l’identité (firewall.ts#Firewall.#authenticate) — ici la preuve mot de passe, la plus fraîche.

💡 Astuce

Un nom d’authenticator inconnu en config fait échouer le boot — Firewall.#instantiateAuthenticators() est fail-closed (firewall.ts#Firewall.#instantiateAuthenticators) : jamais de zone « protégée » silencieusement ouverte à cause d’une faute de frappe.

🧑‍⚖️ Autorisation — rôles, scopes, voters (« as-tu le droit ? »)#

L’authentification dit qui tu es ; l’autorisation dit ce que tu peux faire. On déclare l’exigence sur l’action, un jury de voters tranche. La garde s’applique avant l’instanciation du contrôleur (seam Resolver) — une action protégée ne s’exécute jamais pour un non-autorisé.

@IsGranted(["ROLE_ADMIN"])                 // rôle — OR interne : un seul attribut suffit
@Post("/users") async create() {}

@RequireScope("users:write")               // scope — pour une clé/JWT délégué
@Delete("/users/{id}") async remove(@Param("id") id: string) {}

@IsGranted("doc.edit", { subject: "id" })  // règle métier — le param de route `id` est passé au voter
@Put("/docs/{id}") async edit() {}

Le jury et sa stratégie#

Authorization.decide(token, attribut, subject?) (service/authorization.ts#Authorization.decide) applique une stratégie affirmative + DENY veto, fermée par défaut (Zero Trust) :

• un seul DENY bloque (veto, court-circuit — inutile de finir le jury, authorization.ts#Authorization.decide) ;
• sinon un GRANT suffit ;
• silence total (tous ABSTAIN, ou aucun voter compétent) → DENY (authorization.ts#Authorization) ;
• un voter qui throw → DENY + log ERROR (fail-closed : jamais 500, jamais octroi, authorization.ts#Authorization.decide).

Tout refus est audité (WARNING + recordAudit, authorization.ts#Authorization) ; les octrois restent muets (volume, pas un signal). Les voters sont instanciés une fois au boot via le registre (aucun nom en dur, authorization.ts#Authorization).

Les voters intégrés — deux axes#

• RoleVoter (role, attributs ROLE_*) — GRANT si l’utilisateur a le rôle, hiérarchie résolue ; ABSTAIN sinon, jamais DENY (RoleVoter.vote(), RoleVoter.ts#RoleVoter.vote). Constat : l’absence d’un rôle ne doit pas opposer son veto aux autres axes — c’est le default-DENY du jury qui ferme la porte, pas ce voter. C’est ce qui rend une clause OR (@IsGranted(["A","B"])) possible.
• ScopeVoter (scope, attributs api:action) — un scope ne bride jamais un humain (ScopeVoter.ts) :
  • jeton humain (session/userpassword/anonymous) → GRANT no-op : l’autorisation d’un humain passe par ses rôles ;
  • jeton machine délégué (apikey/jwt/oauth2) → GRANT si le scope exact est présent, ABSTAIN sinon ;
  • fail-closed côté machine : tout type de jeton hors de la liste « non scopable » — présent ou futur (mtls, agent…) — est traité comme scopable, donc bridé par défaut.
  • En une ligne : rôles = qui tu es ; scopes = ce qu’une clé a le droit de faire.

use("@nodefony/security", {
  areas: {
    admin: {
      pattern: "^/back-office(/|$)",
      authenticators: ["session"],
      roles: ["ROLE_ADMIN"], // ← exigé par défaut dans toute la zone
    },
  },
});

La hiérarchie de rôles#

RoleHierarchyWalker (src/RoleHierarchyWalker.ts) : ROLE_ADMIN hérite ROLE_USER, etc. Aplatissement précalculé au boot → hasRole() est O(1) sur le hot path (RoleHierarchyWalker.ts#RoleHierarchyWalker.hasRole), et les cycles sont détectés au boot (throw avec le chemin complet, pas de fail-silent, RoleHierarchyWalker.ts#RoleHierarchyWalker.#detectCycles). La hiérarchie est posée au container par le firewall au boot ; le RoleVoter la lit en lazy.

Voters métier (le vrai pouvoir applicatif)#

Pour une règle qui dépend des données (ownership, tenant, état), on enregistre une fabrique :

import { registerVoterFactory } from "@nodefony/security";

registerVoterFactory(
  "projectVoter",
  ({ container }) => new ProjectVoter(container),
);
// ProjectVoter.supports("doc.edit") → true ; vote(token, "doc.edit", subject) → lookup DB async :
//   l'utilisateur est-il propriétaire/membre du `subject` ? GRANT / DENY / ABSTAIN.

Le voter est découvert automatiquement par le service authorization — aucun changement dans le cœur (registerVoterFactory(), voterRegistry.ts#registerVoterFactory). Pourquoi un registre et pas un scan DI des @injectable : les interfaces TS sont effacées à la compilation — rien à scanner ; le registre est le marqueur explicite (TSDoc du registre, voterRegistry.ts#IVoterFactoryContext). Trois axes (rôles, scopes, métier), un même jury, combinables.

🔌 HTTP et WebSocket — le même firewall#

Firewall.#wireRealtime() (firewall.ts#Firewall.#wireRealtime) câble, pour toute zone protégée realtime !== false (opt-out, firewall.ts#Firewall.#build), le FirewallRealtimeAuthenticator au handshake (firewall.ts#Firewall.#wireRealtime) et un frameAuthorizer (RBAC par canal, firewall.ts#Firewall.#wireRealtime). Même résolution de zone que HTTP. Sur une socket, un refus n’a pas d’en-tête WWW-Authenticate (Firewall.#setChallenge(), firewall.ts#Firewall.#setChallenge) : le code de fermeture suffit.

🛡️ En-têtes de sécurité, CSRF, CORS#

• Firewall.applySecurityHeaders() (firewall.ts#Firewall.applySecurityHeaders) : CSP, Referrer-Policy, COOP/COEP/CORP au-dessus du socle transport de @nodefony/http. Nonce CSP paresseux (hasNonce, firewall.ts#Firewall.enforceCsrf) : alloué seulement si une directive en a besoin.
• Firewall.enforceCsrf() (défense en profondeur, firewall.ts#Firewall.enforceCsrf) : Fetch Metadata (Sec-Fetch-Site) + garde Origin (firewall.ts#Firewall.#startTrace), puis double-submit x-csrf-token ≡ cookie + HMAC (firewall.ts#Firewall.describe).
• Firewall.handleCors() : preflight OPTIONS → 204 (firewall.ts#Firewall.handleCors).

📜 Normes appliquées#

⚡ Performance & mémoire#

Le découpage chaud/froid EST l’optimisation : isSecure() (chaque requête) ne fait qu’un matchPath ; handleSecurity() (throttler, authenticators, nonce CSP, securityTrace) n’est payé que sur zone protégée. Les dépendances des authenticators (keystore, tokenStore, userProvider, verifier, jose) sont résolues paresseusement au premier usage (cold path) ; jose est importé lazy (dep lourde). Le nonce CSP et le securityTrace sont alloués à la demande. Une route publique ne paie quasiment rien.

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

📡 Observabilité — Studio#

Écran Firewall (/nodefony/firewall) : zones, authenticators, décisions (securityTrace). Écran Roles (/nodefony/roles) : hiérarchie de rôles consommée par les voters. Écran ApiKeys (/nodefony/api-keys) : gestion et révocation des PAT.

🧪 Tests & couverture#

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

• unit : firewallChain (la chaîne d’authenticators + modes first/all), securedArea (match pattern/host), firewallIntrospection (l’écran Studio), firewallSecurityTrace (la radiographie de décision) ;
• intégration : firewall-auth (serveur réel : zones + login BFF), securityGuard (la garde @IsGranted au Resolver) ;
• e2e : realtimeFirewallWiring (le câblage WS réel) ;
• attaque : les bancs transverses (csrf, cors, authorization, frames WS) exercent le firewall en conditions hostiles — voir authenticators et authorization.

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 : Authenticators · Autorisation

• Vue du module → index · Autorisation (voters, rôles, scopes) → authorization

• JWT/OAuth2/WebAuthn/TOTP/API keys en détail → pages dédiées du module

• Où le firewall s’insère → pipeline-requete