Bloquer les XSS DOM dans React avec Trusted Types
Découvrez comment React 19.3 active Trusted Types contre les XSS DOM avec une politique DOMPurify, des en-têtes CSP et un déploiement progressif en mode rapport.
React 19.3 transmet les objets Trusted Types directement au DOM. Une application React peut donc désormais imposer require-trusted-types-for 'script' et faire passer tout le balisage de dangerouslySetInnerHTML par une politique s’appuyant sur DOMPurify.
Jusqu’à cette version, cette configuration avait tendance à s’effondrer. Vous assainissiez le HTML issu de votre CMS, vous activiez la directive CSP, et React reconvertissait malgré tout en chaîne de caractères la valeur que vous aviez soigneusement typée.
Cet article présente la modification apportée à React, les en-têtes CSP, un module de politique qui fonctionne aussi dans les navigateurs dépourvus de l’API, ainsi qu’un déploiement qui commence en mode report-only. Pour les fondamentaux des XSS, consultez la prévention des XSS dans le contenu généré par les utilisateurs.
Points clés
- Avant React 19.3, React convertissait les valeurs en chaînes avec
'' + value: un objet TrustedHTML fourni àdangerouslySetInnerHTMLatteignait doncinnerHTMLsous forme de simple chaîne, et un navigateur appliquant la politique le rejetait. - Sous
require-trusted-types-for 'script', l’affectation d’une simple chaîne à un sink d’injection tel queinnerHTMLlève une TypeError. - Trusted Types n’assainit rien. L’API impose que le HTML atteigne le sink en passant par une politique que vous avez écrite, et c’est DOMPurify, à l’intérieur de cette politique, qui effectue le nettoyage.
- Déployez d’abord
Content-Security-Policy-Report-Only, corrigez chaque sink signalé, autorisez explicitement les noms de vos politiques avectrusted-types, puis passez en mode bloquant. - Les navigateurs sans Trusted Types n’appliquent aucune restriction : l’assainisseur intégré à votre politique doit donc s’exécuter à chaque appel.
Qu’est-ce qui a changé dans React 19.3 ?
React 19.3 (publié le 9 septembre 2026) transmet les valeurs TrustedHTML, TrustedScript et TrustedScriptURL au DOM sans les convertir. Le navigateur peut alors vérifier qu’elles ont bien été produites par une politique Trusted Types.
Les versions précédentes convertissaient les valeurs en chaînes avec '' + value avant de les transmettre aux API du DOM. Un objet TrustedHTML passé à dangerouslySetInnerHTML atteignait donc innerHTML sous forme de chaîne ordinaire, et un navigateur appliquant la politique le refusait. L’article d’annonce prend innerHTML comme exemple de sink, et dangerouslySetInnerHTML, qui écrit dans innerHTML, préserve désormais l’objet de confiance. Cette même version a également stabilisé les refs de Fragment.
Comment Trusted Types bloque-t-il les XSS DOM ?
L’API Trusted Types ferme les sinks d’injection aux chaînes brutes. Une fois l’API appliquée, des sinks tels que innerHTML ou l’attribut src d’un script n’acceptent plus que des objets typés créés par une politique nommée.
| Type de confiance | Catégorie de sink | Exemple de sink |
|---|---|---|
TrustedHTML | Analyse HTML | Element.innerHTML |
TrustedScript | Texte de script | eval() |
TrustedScriptURL | Chargement de script | HTMLScriptElement.src |
Trusted Types ne nettoie lui-même aucun balisage. Ce qu’il garantit, c’est que chaque valeur parvenant à un sink est passée par une fonction de politique, et c’est dans cette fonction que DOMPurify fait son travail. Le modèle de sécurité s’en trouve modifié : l’assainissement n’est plus une précaution que chaque développeur doit penser à appliquer à chaque point d’appel, mais une règle imposée par le navigateur.
Configurer l’en-tête Content-Security-Policy
Trusted Types s’active avec la directive CSP require-trusted-types-for 'script'. Commencez par envoyer cette directive dans Content-Security-Policy-Report-Only. Dans ce mode, le navigateur signale les violations tout en laissant le code s’exécuter.
Content-Security-Policy-Report-Only: require-trusted-types-for 'script'
Ajoutez un point de terminaison de reporting à l’aide de la directive report-to afin que le navigateur envoie chaque sink en infraction à votre collecteur, au lieu de se contenter de le journaliser dans la console. Une fois que les rapports cessent, passez à l’en-tête bloquant :
Content-Security-Policy: require-trusted-types-for 'script'; trusted-types app-html
require-trusted-types-for fait lever une exception à toute affectation de chaîne à un sink. trusted-types liste les noms de politiques autorisés, et trustedTypes.createPolicy() lève une exception si vous l’appelez avec un nom absent de cette liste. Envoyez ces directives sous forme d’en-têtes de réponse : les navigateurs ne prennent en charge ni l’en-tête report-only ni la directive report-to dans une balise <meta>.
Créer une politique encapsulant DOMPurify
Dans une application React, créez la politique Trusted Types une seule fois, au niveau du module, et importez-la partout où vous en avez besoin. createPolicy() lève une TypeError en cas de nom en double, sauf si 'allow-duplicates' figure dans la directive trusted-types. Le corps d’un composant n’est donc pas le bon endroit pour l’appeler, puisque React effectue de nouveaux rendus des composants et que le StrictMode les invoque deux fois.
// trusted-html.js
import DOMPurify from 'dompurify';
const factory = globalThis.trustedTypes ?? {
createPolicy: (name, rules) => rules,
};
export const htmlPolicy = factory.createPolicy('app-html', {
createHTML: (dirty) =>
DOMPurify.sanitize(dirty, { TRUSTED_TYPES_POLICY: null }),
});
createHTML renvoie une chaîne assainie, que le navigateur encapsule dans un objet TrustedHTML. Le passage de TRUSTED_TYPES_POLICY: null empêche DOMPurify de créer sa propre politique interne dompurify, de sorte que la liste d’autorisation n’a besoin de contenir que app-html. N’utilisez pas RETURN_TRUSTED_TYPE: true dans createHTML, car la fonction de rappel doit renvoyer une simple chaîne.
L’objet de repli reprend l’idée du « tinyfill » de MDN, sous une forme adaptée aux modules ES. Lorsque l’API est absente, createPolicy renvoie votre objet de règles tel quel : htmlPolicy.createHTML() exécute donc toujours DOMPurify et renvoie une chaîne. Le chemin d’exécution est le même partout. Comme le repli est local, le module s’importe aussi sans erreur lors du rendu côté serveur, où trustedTypes n’est pas défini. DOMPurify a toutefois besoin d’une implémentation du DOM pour assainir côté serveur ; son README détaille cette configuration.
DOMPurify propose également un raccourci : appeler DOMPurify.sanitize(dirty, { RETURN_TRUSTED_TYPE: true }) sans définir votre propre politique. La méthode renvoie un objet TrustedHTML lorsque l’API est prise en charge, et vous ajoutez dompurify à la liste d’autorisation (trusted-types app-html dompurify).
Utiliser la politique avec dangerouslySetInnerHTML
À partir de React 19.3, placez la sortie de la politique dans __html : React transmet alors l’objet TrustedHTML à innerHTML sans le modifier.
// Before: under enforcement, the raw string throws a TypeError
<div dangerouslySetInnerHTML={{ __html: html }} />
En mode report-only, cette ligne génère un rapport de violation. En mode bloquant, elle lève une exception.
import { htmlPolicy } from './trusted-html';
export function RichText({ html }) {
return <div dangerouslySetInnerHTML={{ __html: htmlPolicy.createHTML(html) }} />;
}
Faites transiter toute la sortie de votre CMS, de votre Markdown et de votre texte enrichi par RichText (ou par un appel direct à htmlPolicy.createHTML()). Si vous recherchez ultérieurement __html: avec grep, chaque occurrence devrait se trouver à côté d’un appel à la politique.
Déployer Trusted Types en toute sécurité
Un déploiement sûr de Trusted Types se déroule en quatre étapes : signalement uniquement, correction de chaque sink signalé, autorisation explicite des noms de vos politiques, puis application.
- Déployez
Content-Security-Policy-Report-Only: require-trusted-types-for 'script'avec un point de terminaison de reporting. - Corrigez chaque sink signalé en le faisant passer par
htmlPolicy, ou remplacez-le par un sink qui n’exige pas de valeurs de confiance, commetextContent. - Listez dans
trusted-typeschaque nom de politique créé par votre code et vos dépendances. - Passez à l’en-tête bloquant
Content-Security-Policy.
Si du code tiers continue d’affecter des chaînes que vous ne pouvez pas encore corriger, une politique nommée default peut servir de passerelle temporaire. En mode bloquant, le navigateur lui transmet chaque chaîne brute atteignant un sink, et MDN recommande de ne l’utiliser que le temps de migrer du code legacy.
// TEMPORARY: remove before you finish the migration.
import DOMPurify from 'dompurify';
if (globalThis.trustedTypes) {
globalThis.trustedTypes.createPolicy('default', {
createHTML(value) {
console.warn('Untyped HTML reached a sink');
return DOMPurify.sanitize(value, { TRUSTED_TYPES_POLICY: null });
},
});
}
La détection de fonctionnalité évite que le module ne lève une exception dans les navigateurs dépourvus de l’API et lors du rendu côté serveur.
Ajoutez default à trusted-types tant que cette politique existe. Lorsque ses avertissements cessent d’apparaître, supprimez à la fois la politique et l’entrée correspondante de la liste d’autorisation.
Que se passe-t-il dans les navigateurs sans Trusted Types ?
Les navigateurs qui ne prennent pas en charge Trusted Types n’appliquent aucune restriction. Dans ces navigateurs, l’assainisseur intégré à votre politique est le seul rempart entre le HTML non fiable et le DOM. MDN classe window.trustedTypes comme Baseline 2026, nouvellement disponible depuis février 2026 : les versions plus anciennes des navigateurs présentes dans votre trafic n’en disposeront donc pas.
Le repli défini au niveau du module gère ce cas. Les navigateurs non compatibles ignorent l’en-tête et exécutent tout de même DOMPurify.sanitize() à chaque appel. C’est pourquoi la politique doit toujours assainir et ne jamais renvoyer son entrée inchangée.
Conclusion
React 19.3 supprime la conversion en chaîne qui faisait échouer Trusted Types : dangerouslySetInnerHTML peut désormais transporter du HTML produit par une politique et dont le navigateur garantit le contrôle. Déployez d’abord l’en-tête report-only, faites passer chaque affectation à __html par une unique politique s’appuyant sur DOMPurify, puis activez le mode bloquant une fois que les rapports cessent. Appliquez ensuite la même rigueur côté serveur grâce à ces bonnes pratiques de sécurité des API.
FAQ
Que se passe-t-il si une politique Trusted Types par défaut renvoie null ou undefined ?
Le navigateur lève une TypeError au niveau du sink et l'affectation n'a pas lieu. Une politique par défaut qui renvoie null ou undefined ne laisse rien passer : elle échoue de manière sûre (fail closed) et bloque l'écriture au lieu de laisser passer la chaîne d'origine. Une politique par défaut qui renvoie null pour toute entrée constitue d'ailleurs un moyen pratique de repérer les affectations de chaînes résiduelles pendant la migration.
L'utilisation d'un caractère générique ou de allow-duplicates dans la directive trusted-types est-elle sûre ?
Ni l'un ni l'autre n'est un bon choix en production. Un astérisque (*) comme nom de politique autorise n'importe quel nom de politique unique : un script injecté pourrait donc enregistrer sa propre politique et créer des valeurs de confiance. Le mot-clé 'allow-duplicates' permet au code de créer plusieurs politiques portant le même nom, si bien qu'un nom ne correspond plus à une politique unique et connue. Listez plutôt le nom exact de chaque politique créée par votre code et vos dépendances.
Puis-je encore utiliser eval() lorsque Trusted Types est appliqué ?
Oui. Ajoutez le mot-clé 'trusted-types-eval' à votre CSP. Il autorise eval() et les fonctions similaires uniquement dans les navigateurs qui prennent en charge et appliquent Trusted Types. Contrairement à 'unsafe-eval', il maintient ces fonctions bloquées dans les navigateurs sans prise en charge de Trusted Types. Lorsque l'application est active, le code transmis à eval() doit toujours être un TrustedScript, ou une chaîne brute qu'une politique par défaut convertit en TrustedScript. À défaut, l'appel lève une exception.
Gain Debugging Superpowers
Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.
Star on GitHub12k