En-têtes de sécurité — le contrat passé au navigateur

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

Ton serveur ne contrôle pas le navigateur de tes visiteurs — il ne peut que lui donner des ordres, et ces ordres sont des en-têtes HTTP. Une douzaine de lignes ferment des classes entières d’attaques : XSS, clickjacking, sniffing MIME, fuite d’URL, downgrade HTTPS. Nodefony les pose en deux couches, une seule autorité par en-tête : le socle transport (@nodefony/http, dès l’entrée brute — couvre aussi les fichiers statiques et les erreurs) et la couche applicative (@nodefony/security, dans le pipeline — CSP, Referrer-Policy, isolation cross-origin). Ancré sur SecurityHeaders (securityHeaders.ts#SecurityHeaders) et Firewall.applySecurityHeaders() (firewall.ts#Firewall.applySecurityHeaders).

📍 Documentation › Sécurité › En-têtes de sécurité

🧠 Le modèle mental — deux couches, deux moments#

Un en-tête de sécurité n’a de valeur que s’il est sur toutes les réponses. Le piège classique n’est pas d’en oublier un : c’est de le poser de façon inégale — présent sur les routes de contrôleur, absent sur un fichier statique ou une page d’erreur 404, c’est-à-dire exactement là où un attaquant dépose son contenu.

D’où le découpage : ce qui doit couvrir tout ce qui sort du process est posé au plus tôt ; ce qui dépend de la réponse applicative (le CSP, qui doit connaître le nonce, la route et le type de la réponse) est posé au moment où la réponse écrit ses en-têtes : le pare-feu, armé au routage, choisit alors sa politique sur le Content-Type.

Une seule source par en-tête : @nodefony/security ne ré-émet jamais les trois en-têtes transport — c’est écrit noir sur blanc dans le contrat de la couche applicative (ISecurityHeadersOptions, securityHeaders.ts#ISecurityHeadersOptions). Pas de double émission, donc pas de valeurs contradictoires sur la même réponse.

📖 Lexique#

Qu’est-ce que c’est ? — un panneau d’instructions collé sur chaque réponse#

Imagine que tu envoies un colis. Le contenu, c’est ton HTML. Les en-têtes de sécurité, c’est l’étiquette collée dessus : « ne pas ouvrir avec un autre outil que celui-ci », « ne pas transporter dans un autre camion », « interdiction de recopier l’adresse de l’expéditeur ». Le transporteur — le navigateur — les respecte. Sans étiquette, il improvise, et improviser c’est exactement ce qu’un attaquant attend.

Chaque en-tête ferme une faille concrète :

• CSP — un attaquant réussit à injecter <script src="https://evil.tld/x.js"> dans un commentaire de ton site ; sans CSP, le navigateur l’exécute avec la session de la victime.
• X-Frame-Options / frame-ancestors — un site pirate charge ta page « Supprimer mon compte » en iframe invisible sous un bouton « Jouer » : la victime clique, c’est chez toi que ça s’applique.
• nosniff — un avatar téléversé est en réalité du JavaScript ; un navigateur « serviable » devine le type et l’exécute sur ton origine, donc avec tes cookies.
• Referrer-Policy — un clic vers l’extérieur transmet ton URL interne complète (/admin/facture/8123?client=ACME) dans le Referer du site suivant.
• HSTS — sur un Wi-Fi public, la première requête part en clair et peut être interceptée puis maintenue en HTTP ; HSTS mémorisé force le HTTPS avant toute émission.
• COOP / COEP / CORP — isolent ton document des autres origines (fenêtres ouvrantes, ressources embarquées) : réponse aux canaux auxiliaires type Spectre et au vol d’assets par inclusion.

Le détail de chaque en-tête — menace, valeur par défaut, compromis — est dans le catalogue plus bas.

La vision Nodefony — pré-calculé au boot, quasi gratuit par requête#

Un framework qui recalcule ses en-têtes à chaque requête paie ce confort en allocations. Nodefony fait l’inverse : tout ce qui est constant est calculé une fois au démarrage.

• SecurityHeaders (securityHeaders.ts#SecurityHeaders) construit au boot la table des en-têtes constants (Referrer-Policy, COOP/COEP/CORP, Origin-Agent-Cluster, Permissions-Policy, et le CSP quand il est statique) et la gèle avec Object.freeze (securityHeaders.ts#SecurityHeaders.constructor). Par requête, le firewall se contente de la parcourir et de la poser : zéro concaténation, zéro objet créé.
• Côté transport, même principe : HttpKernel.computeSecurityHeaderCaches() (http-kernel.ts#HttpKernel.computeSecurityHeaderCaches) précalcule la chaîne HSTS (max-age, includeSubDomains, preload) au boot ; onHttpRequest (http-kernel.ts#HttpKernel.onHttpRequest) ne fait plus que trois setHeader.
• Le seul coût variable est le nonce CSP, et il est paresseux : Context.cspNonce (Context.ts#Context.#cspNonce) ne tire ses 128 bits (16 octets CSPRNG, en base64) d’un pool amorti (randomFillSync, 4 Ko pour 256 nonces) qu’à la première lecture, puis mémoïse. Une réponse qui n’a aucun script inline à signer ne paie aucun appel crypto.

Le second parti pris est la séparation d’autorité décrite plus haut : un seul émetteur par en-tête, donc un comportement prévisible et testable — le banc live vérifie les deux couches sur la même réponse (security-headers.test.ts).

❗ Important

@nodefony/security est optionnel, pas le socle. Une app Nodefony sans module security émet quand même nosniff, X-Frame-Options et HSTS : c’est du secure-by-default. Ce que tu perds sans security, c’est le CSP, la Referrer-Policy et l’isolation cross-origin.

🚀 Démarrage rapide#

Point de départ : une app générée par nodefony create app. Les en-têtes sont déjà actifs — ce que tu écris ci-dessous, ce sont tes écarts au défaut.

1. Déclarer la politique dans nodefony.config.ts#

// nodefony.config.ts — l'app n'écrit QUE ses écarts ; le reste prend le défaut du framework.
import { defineConfig, use } from "nodefony";

export default defineConfig(() => ({
  modules: [
    "@nodefony/http",
    "@nodefony/framework",
    use("@nodefony/security", {
      headers: {
        // `{{nonce}}` est substitué par un jeton FRAIS à chaque requête (cf plus bas).
        csp:
          "default-src 'self'; script-src 'nonce-{{nonce}}' 'strict-dynamic' 'self'; " +
          "style-src 'self' 'unsafe-inline' 'nonce-{{nonce}}'; style-src-attr 'unsafe-inline'; " +
          "img-src 'self' data:; " +
          "object-src 'none'; base-uri 'self'; form-action 'self'",
        cspNonces: true,
        // Ne fuiter que l'origine, et rien vers un site en clair.
        referrerPolicy: "strict-origin-when-cross-origin",
        // Isolation cross-origin : ABSENTE par défaut, on l'active explicitement.
        coop: "same-origin",
        corp: "same-origin",
        permissionsPolicy: "camera=(), microphone=(), geolocation=()",
      },
    }),
  ],
}));

Les clés sont typées et auto-complétées : le module augmente le registre NodefonyModuleConfig du core (index.ts#nodefony), donc use("@nodefony/security", …) propose les clés et les valeurs d’enum (referrerPolicy, coop, corp…). Une valeur hors enum casse le boot, pas la production.

2. Ce qu’on observe#

# Une PAGE : socle transport + couche applicative complète, sur la MÊME réponse.
curl -sI http://localhost:5151/nodefony/test/html

# HTTP/1.1 200 OK
# X-Content-Type-Options: nosniff              ← transport (@nodefony/http)
# X-Frame-Options: DENY                        ← transport (@nodefony/http)
# Content-Type: text/html; charset=utf-8
# Content-Security-Policy: default-src 'self'; script-src 'nonce-vZ9…' 'strict-dynamic' 'self'; …
# Referrer-Policy: strict-origin-when-cross-origin
# Cross-Origin-Opener-Policy: same-origin
# Cross-Origin-Resource-Policy: same-origin
# Permissions-Policy: camera=(), microphone=(), geolocation=()

# Une réponse d'API : la politique courte, et seulement ce qu'un JSON fait lire.
curl -sI http://localhost:5151/nodefony/test/index

# Content-Type: application/json
# Content-Security-Policy: default-src 'none'; frame-ancestors 'none'
# Referrer-Policy: strict-origin-when-cross-origin
# Cross-Origin-Resource-Policy: same-origin

# Le nonce change à CHAQUE requête — deux appels, deux jetons.
curl -sI http://localhost:5151/nodefony/test/html | grep -o "nonce-[^']*"
curl -sI http://localhost:5151/nodefony/test/html | grep -o "nonce-[^']*"
# nonce-2Qk1r0h8…      (≠)
# nonce-Xa7pLd3f…

# Une URL inexistante : le socle transport est TOUJOURS là (l'applicatif ne s'exécute pas).
curl -sI http://localhost:5151/nodefony/test/__inexistant__ | grep -i x-content-type
# X-Content-Type-Options: nosniff

3. Un besoin ponctuel : élargir le CSP d’UNE route#

Tu dois embarquer une iframe YouTube sur une seule page. Élargir le CSP global serait une faute : tu ouvrirais l’ensemble du site. @Csp déclare l’écart à l’échelle de l’action.

// nodefony/controllers/EmbedController.ts — complet, compile tel quel.
import { controller, Controller, Get, Csp } from "@nodefony/framework";

@controller("/embed")
class EmbedController extends Controller {
  // `frame-src` n'existe QUE sur cette route ; le reste du site garde le CSP strict.
  @Csp({ "frame-src": ["https://www.youtube.com"] })
  @Get("/video")
  video() {
    return this.renderJson({ embed: true });
  }
}

export default EmbedController;

curl -sI http://localhost:5151/embed/video | grep -i content-security-policy
# … ; frame-src https://www.youtube.com      ← ajouté ICI seulement
curl -sI http://localhost:5151/nodefony/test/index | grep -c youtube
# 0                                          ← isolation prouvée (security-headers.test.ts)

🛡️ Le catalogue des en-têtes#

Choisir en cinq secondes — puis le détail dans les cartes.

import { readCspNonce } from "nodefony/client";

const nonce = readCspNonce();
if (nonce) {
  // Une bibliothèque qui réécrit `nonce` avec une valeur vide (`undefined`) écraserait la
  // signature sans un mot : l'affectation d'une valeur vide rend le nonce de la page.
  const base = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "nonce");
  if (base?.get && base.set) {
    const { get, set } = base;
    Object.defineProperty(HTMLStyleElement.prototype, "nonce", {
      configurable: true,
      get() {
        return get.call(this);
      },
      set(value: unknown) {
        const usable =
          typeof value === "string" && value !== "" && value !== "undefined";
        set.call(this, usable ? value : nonce);
      },
    });
  }
  Document.prototype.createElement = new Proxy(
    Document.prototype.createElement,
    {
      apply(target, thisArg, args) {
        const element: unknown = Reflect.apply(target, thisArg, args);
        if (element instanceof HTMLStyleElement) element.nonce = nonce;
        return element;
      },
    },
  );
}

use("@nodefony/security", {
  headers: {
    // Le défaut, sauf `style-src` : plus de nonce pour les styles, scripts inchangés.
    csp:
      "default-src 'self'; script-src 'nonce-{{nonce}}' 'strict-dynamic' 'self'; " +
      "style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; " +
      "connect-src 'self'; worker-src 'self' blob:; object-src 'none'; base-uri 'self'; " +
      "form-action 'self'; upgrade-insecure-requests",
  },
});

// nodefony/config/security.ts
export default (ctx) =>
  ({
    headers: { csp: "" }, // l'application n'envoie plus de CSP : le proxy décide seul
  }) satisfies ISecurityConfigInput;

use("@nodefony/security", {
  headers: {
    csp: "default-src 'self'; script-src 'nonce-{{nonce}}' 'self'; frame-ancestors https://portail.example",
  },
});

⚙️ Configuration — deux sections, deux modules#

Réflexe à acquérir : le nom du module dit qui pose l’en-tête. Chercher frameOptions dans la config security est la première source de confusion sur ce sujet.

Couche applicative — use("@nodefony/security", { headers })#

Dérivé du schéma Zod headersSchema (config.ts#headersSchema).

Socle transport — use("@nodefony/http", { securityHeaders })#

Dérivé de securityHeadersSchema (http/nodefony/config/config.ts#securityHeadersSchema). Ces trois réglages sont éditables à chaud (runtimeMutable) : HttpKernel.onConfigChanged() (http-kernel.ts#HttpKernel.onConfigChanged) recalcule les caches, donc la valeur suivante s’applique sans redémarrage.

⚠️ Attention

Les clés hsts, hstsMaxAgeS, frameguard et noSniff existent dans la config security (config.ts#headersSchema) mais ne pilotent rien : la couche applicative ne les lit pas (securityHeaders.ts#ISecurityHeadersOptions). frameguard est dépréciée (retrait à la prochaine version majeure). Pour changer réellement X-Frame-Options et frame-ancestors, c’est securityHeaders.frameOptions du module http. Même remarque pour hidePoweredBy (config.ts#headersSchema) : Nodefony n’émet aucun X-Powered-By, l’option est un no-op documenté.

🏗️ Le CSP en détail — deux régimes, trois façons de l’étendre#

Régime 1 — CSP statique (0 allocation par requête)#

Si le CSP ne contient pas {{nonce}}, ou si cspNonces est à false, la chaîne est rangée telle quelle dans la table gelée du boot (securityHeaders.ts#SecurityHeaders.constructor). Par requête : une lecture, un setHeader. Rien d’autre.

Détail de robustesse : si tu désactives cspNonces en laissant le placeholder dans la chaîne, le token résiduel 'nonce-{{nonce}}' est purgé (securityHeaders.ts#SecurityHeaders.constructor). Sans ça, tu servirais un CSP contenant un nonce littéral jamais émis — donc un script-src qui bloque tout, y compris tes propres scripts. 'strict-dynamic' part avec lui quand la directive n’a plus ni nonce ni hash : seul, il ferait ignorer 'self' et bloquerait aussi tout. Le code refuse de produire un CSP cassé.

Régime 2 — nonce par requête (la vraie défense anti-XSS)#

Un nonce autorise l’inline que tu as toi-même rendu, et lui seul. Un script injecté par un attaquant ne peut pas deviner la valeur : il est refusé même s’il est syntaxiquement identique.

Le chemin complet, sans surprise :

1. Au boot, la chaîne CSP est pré-découpée autour de {{nonce}} (securityHeaders.ts#SecurityHeaders.constructor). Aucun parsing ni regex n’aura lieu pendant une requête.
2. Par requête, Firewall.applySecurityHeaders() (firewall.ts#Firewall.applySecurityHeaders) lit context.cspNonce — ce qui génère le jeton à cet instant (Context.ts#Context.#cspNonce) — puis appelle SecurityHeaders.cspFor() (securityHeaders.ts#SecurityHeaders.cspFor) : un seul join.
3. Dans la vue, le contrôleur relit context.cspNonce, qui est mémoïsé : l’en-tête et le <script nonce="…"> portent forcément la même valeur. C’est le motif employé par le contrôleur de Studio (StudioController.ts#StudioController.renderStudio).

SecurityHeaders.hasNonce (securityHeaders.ts#SecurityHeaders.hasNonce) est le drapeau qui décide du régime : à false, pas une seule opération crypto. Il n’y a aucun setter pour cspNonce : un jeton serveur doit rester imprévisible, jamais pilotable par le client — contrairement au requestId, qui, lui, accepte une corrélation entrante.

Placement dans le pipeline : applySecurityHeaders est appelé après le resolve et avant le repli statique et le writeHead (http-kernel.ts#HttpKernel.runHttpPipeline). Cet ordre n’est pas cosmétique : il faut que le routeur ait posé les directives @Csp de la route pour pouvoir les fusionner, et il faut être avant l’écriture des en-têtes pour pouvoir en poser.

Quelle politique sur quelle réponse — le type décide#

Une politique de contenu ne protège que ce que le navigateur rend : une page, un SVG, le script d’un worker. Sur un JSON ou une image, elle ne gouverne rien — sauf l’encadrement. Le pare-feu choisit donc la politique au moment où la réponse écrit ses en-têtes, d’après son Content-Type (securityHeaders.ts#responseKindOf, ADR-0024 §C11) :

Pourquoi chaque ligne :

• Le nonce n’est tiré que pour un document. Une réponse d’API ne paie plus le générateur aléatoire, et sa politique passe de ~360 octets à ~40.
• L’encadrement suit la politique complète : avec http.securityHeaders.frameOptions: "SAMEORIGIN", un PDF ou une image que ta page encadre le reste.
• Une page XML est un document : le navigateur la rend. Sous la politique courte, un formulaire injecté n’y relèverait d’aucun form-action — default-src ne couvre ni form-action ni base-uri.
• Un 304 du pipeline ne porte rien : ses en-têtes REMPLACENT ceux de la page gardée en cache (RFC 9111 §4.3.4). Une politique courte y réduirait la page, un nonce neuf la désaccorderait de ses balises. Un fichier statique en 304 porte en revanche la politique de son 200 : le serveur statique écrit ses en-têtes avant de savoir la copie fraîche. C’est sans effet : c’est exactement la politique de son 200, qui ne porte pas de nonce.
• Une réponse sans contenu (204, corps vide) prend la courte, même si un Content-Type y a été posé : rien n’y sera rendu.
• Un fichier statique est rangé d’après son extension. Sans extension connue — l’index.html d’un dossier, ou toute adresse qui finit par / —, il est traité en document : jamais une politique plus faible par défaut. Un document servi ainsi reçoit la politique sans nonce (voir 'strict-dynamic' plus haut).

Ce que l’application écrit n’est jamais réduit :

• une route @Csp sert SA politique quel que soit son type (un frame-ancestors posé sur un PDF) ;
• un en-tête posé à la main par le contrôleur (this.response.setHeader(…)) gagne sur celui du pare-feu ;
• headers.csp: "" coupe toute politique, courte comprise.

Étendre le CSP — quatre portées, une seule mécanique#

headers.cspSources — ajouter sans réécrire. Recopier toute la politique pour y ajouter un hôte la figerait : elle ne suivrait plus le défaut. On déclare plutôt des sources par contribution nommée :

use("@nodefony/security", {
  headers: { cspSources: { cdn: { "img-src": ["https://cdn.example.com"] } } },
});

Indexée par NOM, et non par directive, parce que la fusion de configuration remplace un tableau case par case : un module qui complète la section par module-security sous un autre nom s’ajoute, il n’écrase pas. Une contribution malformée est ignorée et journalisée, l’application démarre ; une source ouverte à tout hôte est gardée (c’est ton choix) et signalée. Sans effet quand csp vaut "".

Les quatre convergent vers mergeCspFragments() (csp.ts#mergeCspFragments), et c’est un merge structuré, pas une concaténation. Pourquoi c’est vital : en CSP, une directive répétée est ignorée après sa première occurrence (W3C CSP Level 3 §3, rationnel documenté csp.ts#CspFragment). Concaténer "script-src 'self'" et "script-src https://cdn" produirait un en-tête où la seconde est purement et simplement jetée — une extension silencieusement sans effet, le pire des deux mondes.

Le merge fusionne donc les sources dans une seule directive, dédoublonnées, base d’abord ; une directive absente est ajoutée en fin. La fonction est pure et déterministe (parseCsp() csp.ts#parseCsp → serializeCsp() csp.ts#serializeCsp), ce qui rend l’en-tête stable d’une requête à l’autre et les tests fiables.

Coût : le merge d’un module est payé une fois, au (dés)enregistrement (Firewall.#rebuildSecurityHeaders(), firewall.ts#Firewall.#rebuildSecurityHeaders), jamais par requête. Le merge d’une route @Csp est payé uniquement sur les routes décorées (SecurityHeaders.cspForExtra(), securityHeaders.ts#SecurityHeaders.cspForExtra) ; le cas courant reste le simple join.

Rapports de violation — voir ce que la politique bloque#

Une politique stricte casse sans bruit : le navigateur bloque une image ou un script, et le serveur n’en sait rien. Par défaut, la politique demande donc ses rapports — report-uri (lu par tous les navigateurs) et report-to nodefony-csp (Reporting API, honorée seulement vers une origine sûre : https ou localhost), avec l’en-tête Reporting-Endpoints qui nomme le groupe :

Content-Security-Policy: …; report-uri /nodefony/security/api/csp-report; report-to nodefony-csp
Reporting-Endpoints: nodefony-csp="/nodefony/security/api/csp-report"

Le navigateur poste ses rapports sur POST /nodefony/security/api/csp-report (CspReportController.ts#CspReportController). Cette porte est publique — le navigateur n’envoie aucun identifiant — donc tout ce qu’elle reçoit est traité comme écrit par un attaquant (cspReports.ts#CspReportCollector) :

• corps lu en flux et borné à 8 Ko (CSP_REPORT_MAX_BYTES), 413 au-delà ;
• deux types de contenu seulement, application/csp-report et application/reports+json ;
• quota par adresse (120 rapports par minute) ;
• URL expurgées de leur requête, de leur fragment et de leurs identifiants — une requête peut porter un jeton ; une URL qui n’est pas HTTP(S) se réduit à son schéma ;
• l’extrait de code n’est jamais gardé : c’est une chaîne de l’attaquant ;
• stockage en mémoire seule, dédoublonné (une répétition incrémente un compteur), 200 violations distinctes au plus ; le journal dit chaque violation neuve une fois, 20 lignes par minute au plus.

La réponse est toujours 204 : l’émetteur n’apprend rien de ce qui a été gardé. L’administrateur lit les violations sur GET /nodefony/security/api/csp-reports (rôle ROLE_NODEFONY_ADMIN), la plus récente d’abord — champs à afficher comme du texte.

Une politique que tu écris avec son propre report-uri ou report-to est servie telle quelle. Une URL qu’un en-tête ne peut pas porter est retirée et journalisée en ERROR — l’application démarre sans rapports plutôt que de ne pas démarrer.

🧩 Extension — déclarer un fragment CSP depuis son module#

Un module qui a besoin d’origines supplémentaires ne doit jamais poser l’en-tête lui-même : il en émettrait un second, et le navigateur applique alors l’intersection la plus stricte — au mieux inefficace, au pire il casse la page. Il déclare son besoin, security fusionne.

// Dans le service d'un module — le firewall est résolu PAR NOM et typé par le
// contrat de @nodefony/http (aucun import de security).
import type { IFirewallGate } from "@nodefony/http";

this.get<IFirewallGate>("firewall")?.registerCspOrigins?.("mon-module", {
  "connect-src": ["https://api.partenaire.tld"],
  "img-src": ["https://cdn.partenaire.tld"],
});

Quatre propriétés à retenir :

• À tout moment : une contribution reçue avant que le firewall ait composé sa politique (onBoot) est gardée, puis fusionnée à la composition (firewall.ts#Firewall.registerCspOrigins) — l’ordre des modules ne décide de rien. Seul le service firewall doit déjà exister : un module qui déclare au démarrage le fait donc à onReady, comme @nodefony/realtime pour une socket servie sur une autre origine (realtime.publicOrigin, RealtimeService.ts#RealtimeService.init).
• Aucun couplage : la résolution par nom de service évite un cycle de dépendances, et registerCspOrigins est optionnel — un module fonctionne dans une app sans security.
• Réversible : Firewall.unregisterCspOrigins() (firewall.ts#Firewall.unregisterCspOrigins) retire le fragment et reconstruit le CSP de base. C’est ce que fait @nodefony/frontend à l’arrêt du serveur Vite.
• Idempotent : la reconstruction repart toujours du headers.csp d’origine (firewall.ts#Firewall.#rebuildSecurityHeaders), jamais d’un CSP déjà fusionné — pas d’accumulation entre deux enregistrements.

L’exemple de référence vit dans le framework : en développement, @nodefony/frontend déclare les origines du serveur Vite et 'unsafe-eval' (exigé par le Fast Refresh de React) via FrontendService.#viteCspFragment() (FrontendService.ts#FrontendService.#viteCspFragment) — ce qui explique qu’un CSP observé en dev soit plus large qu’en production, où ce fragment n’existe pas.

📜 Normes appliquées#

⚡ Performance & mémoire#

Le coût est concentré au boot, par construction :

• En-têtes constants : une seule table, gelée (securityHeaders.ts#SecurityHeaders.constructor). Par requête, une boucle for…in sur un objet de 1 à 6 entrées et autant de setHeader. Aucune allocation.
• CSP statique : rien de plus — la chaîne est dans la table.
• CSP à nonce : un tirage dans le pool plus une concaténation préfixe + nonce + suffixe par requête. C’est le seul coût variable, et il n’existe que si le CSP porte un placeholder : hasNonce (securityHeaders.ts#SecurityHeaders.hasNonce) court-circuite entièrement ce chemin sinon. La paresse de Context.cspNonce (Context.ts#Context.#cspNonce) protège en plus les chemins internes qui n’atteignent jamais le firewall.
• Merge CSP : jamais dans le chemin chaud. Le fragment d’un module est fusionné à l’enregistrement (firewall.ts#Firewall.currentRevalidator) ; celui d’une route ne coûte que sur les routes @Csp.
• Socle transport : trois setHeader sur des chaînes précalculées (http-kernel.ts#HttpKernel.dispatchHttpRequest), avec un test !== null qui annule le coût des en-têtes désactivés.

Le module n’attache aucun écouteur d’événement et ne conserve aucun état par requête : il n’entre pas dans le périmètre du gate mémoire, qu’il ne peut structurellement pas dégrader.

📡 Observabilité — Studio#

L’écran Firewall de Studio affiche la section « En-têtes de sécurité » — pilotée par headers.enabled (FirewallDefenses.tsx#FirewallDefenses) — avec le CSP effectif, l’état du nonce par requête, la Referrer-Policy et les valeurs d’isolation. Les données viennent de Firewall.describe() (firewall.ts#Firewall.describe), qui projette la config sans aucun secret, exposée par GET /nodefony/security/api/firewall.

L’onglet Configuration de Studio rend les mêmes options depuis le schéma Zod — chaque champ y porte sa description, ce qui en fait la référence toujours à jour des défauts.

ℹ️ Note

La ligne « frameguard » de cet écran reflète la valeur réellement ÉMISE par le transport, lue chez le noyau HTTP (firewall.ts#Firewall.describe), pas la clé inerte de la config security. La réponse HTTP elle-même reste la preuve : curl -I tranche en une seconde.

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

🧪 Tests & couverture#

Trois familles couvrent la brique — les compteurs exacts vivent dans la carte de l’aperçu, régénérée depuis vitest :

• Unitaires (@nodefony/security) — securityHeaders.test : la table figée, la séparation transport/applicatif prouvée par l’absence des trois en-têtes transport, les avancés opt-in, les deux régimes CSP, la purge du résiduel, et cspForExtra (fusion, ajout, substitution du nonce) ; csp.test : parse, merge et sérialisation des fragments.

• Intégration sur serveur réel (@nodefony/http, port 5151) — security-headers.test vérifie les deux couches sur une vraie réponse. Quatre invariants y sont prouvés :

  • le socle transport survit à une 404, avec x-content-type-options sur une route inexistante (security-headers.test.ts) ;
  • le CSP applicatif complète cette réponse avec content-security-policy (security-headers.test.ts) ;
  • une route décorée voit sa directive frame-src fusionnée, sans dupliquer img-src (security-headers.test.ts) ;
  • deux requêtes concurrentes reçoivent deux nonces différents (security-headers.test.ts).

  headers.test et security.test couvrent le reste du contrat d’en-têtes.

• Absent, assumé : pas de banc d’attaque dédié à cette brique (contrairement à CSRF, CORS ou l’autorisation, qui ont leur *.attack.test.ts), et pas de test de charge propre — le coût est structurellement nul par requête, et le pipeline complet est déjà couvert par le gate mémoire de @nodefony/http.

Couverture : npm run coverage dans @nodefony/security. Revue de sécurité d’un diff touchant cette brique : skill nodefony-security-review.

🔗 Pour aller plus loin#

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

• 🧭 Pages sœurs : CORS · CSRF

• Le pare-feu qui pose la couche applicative → firewall

• CORS, l’autre famille d’en-têtes (Access-Control-*) → cors

• CSRF, la défense complémentaire contre les requêtes forcées → csrf

• Vue d’ensemble du module → index

• Où les deux couches s’insèrent dans le pipeline → pipeline-requete