@nodefony/security — la sécurité de bout en bout

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

Le pare-feu applicatif de Nodefony : un modèle par zones, des authenticators enfichables, des voters de droits, et les briques qui vont avec (jetons, passkeys, 2FA, OAuth2, CSRF, CORS, en-têtes, webhooks, audit). Principe directeur : Zero Trust — sur une zone protégée, pas de preuve d’identité valide, pas d’accès. Le même firewall protège HTTP et WebSocket.

📍 Documentation › Sécurité

🧭 Par où commencer#

Quatre parcours selon ce que tu viens faire. L’ordre compte : chaque étape suppose la précédente.

Je découvre la sécurité Nodefony — comprendre le modèle avant de configurer quoi que ce soit.

1. Firewall — zones, Zero Trust, la chaîne de décision. Tout part d’ici.
2. Authenticators — les sept façons de prouver qui appelle.
3. Autorisation — rôles, scopes, voters : ce qu’il a le droit de faire.
4. Jetons — ce qui matérialise une identité prouvée, et comment on la révoque.

Je protège une API pour des machines — scripts, CI, partenaires, agents.

1. Firewall — déclarer la zone et ses authenticators.
2. Clés d’API — émettre, faire tourner, révoquer une clé opaque.
3. Jetons — le JWT quand la vérification doit rester sans état.
4. Jetons d’un émetteur TIERS — accepter Keycloak, Auth0 ou Entra sans leur céder l’application.
5. Autorisation — borner chaque clé par des scopes.

J’ouvre un login à des humains — navigateur, comptes, second facteur.

1. Authenticators — la session BFF, et pourquoi le login est déjà fourni.
2. Page de connexion — la page servie à /login, et comment l’habiller à ton nom.
3. OAuth2 — « se connecter avec GitHub/Google » et le Shadow User.
4. Keycloak — brancher l’annuaire de l’entreprise, du realm au premier login.
5. WebAuthn / passkeys — se connecter sans mot de passe, résistant au phishing.
6. TOTP — le second facteur classique, et l’élévation de privilège (step-up).

J’audite avant une mise en production — la passe qu’on regrette de ne pas avoir faite.

1. En-têtes de sécurité — CSP, HSTS, COOP/COEP : ce que le navigateur applique pour toi.
2. CSRF — empêcher un site tiers d’agir au nom de ton utilisateur.
3. CORS — qui a le droit de lire tes réponses.
4. Journal d’audit — prouver après coup qui a fait quoi.
5. Webhooks — notifier un système tiers sans se faire piéger (SSRF).

🗂️ Les briques du module#

Le tableau pour choisir en cinq secondes ; les cards en dessous pour le détail.

🏛️ Place dans le framework#

Le module consomme @nodefony/user (jamais l’inverse) et n’importe @nodefony/http / framework qu’en type-only, à une exception près : schemaMismatchOf (webhooks.ts), importé de @nodefony/http pour reconnaître une base au schéma en retard avec la même règle que le cœur HTTP, plutôt qu’avec une copie.

🧰 Surface publique#

Services Firewall, AuthFlow, TokenService, ApiKeyService, Authorization, WebAuthnService, OAuth2Service, AuditService, TotpService, WebhookService ; briques SecuredArea, Csrf/CsrfTokenManager, Cors, SecurityHeaders, RoleHierarchyWalker ; voters RoleVoter, ScopeVoter ; les *Authenticator ; stores mémoire et JwtKeystore.

Les signatures exactes vivent dans le graphe généré — jq '.symbols.Firewall' .ai/symbols.json — jamais recopiées ici (elles divergeraient).

🛠️ Gérer les comptes en exploitation#

Sur un serveur, la console d’administration suppose d’y être déjà entré — ce qui est précisément impossible quand on a perdu le mot de passe. Ces commandes sont l’autre porte, et elles s’exécutent sans ouvrir de port (profil console) :

En terminal, le mot de passe est demandé masqué et confirmé ; pour un script, --password <pwd> l’accepte en argument — au prix de l’historique du shell, que la commande rappelle.

Deux garde-fous qui se constatent plutôt qu’ils ne se supposent : le dernier administrateur actif ne se supprime pas (security-user-delete.ts#SecurityUserDelete.generate), et un changement de mot de passe éjecte les accès en cours par la même cascade que la suppression (userRevocationCascade.ts#KernelListenerLike) — on change un mot de passe parce qu’il est perdu ou compromis.

⚙️ Configuration#

Un seul point d’entrée : use("@nodefony/security", { … }) dans nodefony.config.ts, validé par Zod au boot. Blocs : areas (zones + authenticators), cors, csrf, headers, rateLimit (backoff NIST), puis un bloc par brique (jwt, apiKeys, totp, webhooks, audit, passkeys, oauth2). Chaque page de brique détaille son bloc, avec une table dérivée du schéma.

📜 Normes appliquées#

📖 Lexique#

📡 Observabilité — Studio#

Quatre écrans dédiés (@nodefony/studio/frontend/src/routes/) : Firewall (zones et décisions, état runtime), ApiKeys, Audit (journal), Webhooks — plus les pages Roles, Sessions, Login, Users. Data plane admin : SecurityAdminApi / WebhookAdminApi sous /nodefony/security/api/*.

🧪 Tests & couverture#

Le module est le plus testé du framework. Chaque page de brique porte l’inventaire de ses tests (unitaires, intégration, E2E sur base réelle, bancs de contrat, tests d’attaque) et dit ce qui manque — un trou de couverture nommé vaut mieux qu’un chiffre flatteur. Les compteurs sont recomptés à chaque génération, jamais figés dans le texte.

🔗 Pour aller plus loin#

• ⬆️ Remonter : Toute la documentation
• 🧭 Modules voisins : @nodefony/user (l’identité) · @nodefony/http (transport et sessions) · @nodefony/framework (décorateurs @IsGranted, @CurrentUser)
• 🏛️ Transverse : pipeline de requête — où le firewall s’insère exactement dans le trajet d’une requête.
• 📖 Lexique général du framework.