12k
All articles

DOM-XSS in React mit Trusted Types blockieren

Erfahren Sie, wie React 19.3 Trusted Types gegen DOM-XSS mit einer DOMPurify-Richtlinie, CSP-Headern und einer sicheren Einführung im Report-Only-Modus nutzt.

OpenReplay Team
OpenReplay Team
DOM-XSS in React mit Trusted Types blockieren

React 19.3 übergibt Trusted-Types-Objekte unverändert an das DOM. Eine React-App kann damit jetzt require-trusted-types-for 'script' durchsetzen und sämtliches dangerouslySetInnerHTML-Markup über eine Policy auf Basis von DOMPurify leiten.

Bis zu diesem Release scheiterte ein solches Setup in der Regel. Sie haben Ihr CMS-HTML bereinigt und die CSP-Direktive aktiviert, doch React hat Ihren sorgfältig typisierten Wert trotzdem wieder in einen String umgewandelt.

Dieser Artikel behandelt die Änderung in React, die CSP-Header, ein Policy-Modul, das auch in Browsern ohne die API funktioniert, sowie einen Rollout, der im Report-only-Modus beginnt. Grundlagen zu XSS finden Sie unter XSS in nutzergenerierten Inhalten verhindern.

Das Wichtigste in Kürze

  • Vor React 19.3 wandelte React Werte mit '' + value in Strings um. Ein an dangerouslySetInnerHTML übergebenes TrustedHTML-Objekt kam daher als einfacher String bei innerHTML an, und ein Browser mit aktiver Durchsetzung wies ihn zurück.
  • Unter require-trusted-types-for 'script' löst die Zuweisung eines einfachen Strings an einen Injection-Sink wie innerHTML einen TypeError aus.
  • Trusted Types bereinigt selbst nichts. Die API stellt sicher, dass HTML nur über eine von Ihnen geschriebene Policy zum Sink gelangt. Die eigentliche Bereinigung übernimmt DOMPurify innerhalb dieser Policy.
  • Liefern Sie zuerst Content-Security-Policy-Report-Only aus, beheben Sie jeden gemeldeten Sink, setzen Sie Ihre Policy-Namen mit trusted-types auf die Allowlist und aktivieren Sie erst dann die Durchsetzung.
  • Browser ohne Trusted Types setzen nichts durch. Der Sanitizer in Ihrer Policy muss deshalb bei jedem Aufruf ausgeführt werden.

Was hat sich in React 19.3 geändert?

React 19.3 (veröffentlicht am 9. September 2026) übergibt TrustedHTML-, TrustedScript- und TrustedScriptURL-Werte ohne Typumwandlung an das DOM. Der Browser kann dadurch prüfen, ob sie von einer Trusted-Types-Policy erzeugt wurden.

Frühere Versionen wandelten Werte mit '' + value in Strings um, bevor sie an DOM-APIs übergeben wurden. Ein an dangerouslySetInnerHTML übergebenes TrustedHTML-Objekt erreichte innerHTML deshalb als gewöhnlicher String, und ein Browser mit aktiver Durchsetzung lehnte ihn ab. Der Release-Post verwendet innerHTML als Beispiel-Sink. dangerouslySetInnerHTML schreibt in innerHTML und behält das Trusted-Objekt jetzt bei. Mit demselben Release wurden außerdem Fragment-Refs als stabil eingestuft.

Wie blockieren Trusted Types DOM-XSS?

Die Trusted Types API sperrt Injection-Sinks für einfache Strings. Ist sie aktiv, akzeptieren Sinks wie innerHTML oder das src-Attribut eines Skripts nur noch typisierte Objekte, die von einer benannten Policy erzeugt wurden.

Trusted TypeSink-KategorieBeispiel-Sink
TrustedHTMLHTML-ParsingElement.innerHTML
TrustedScriptSkripttexteval()
TrustedScriptURLLaden von SkriptenHTMLScriptElement.src

Trusted Types bereinigt selbst kein Markup. Die API garantiert vielmehr, dass jeder Wert an einem Sink eine Policy-Funktion durchlaufen hat, und in genau dieser Funktion erledigt DOMPurify die Arbeit. Das verändert das Sicherheitsmodell grundlegend: Die Bereinigung ist nicht länger etwas, an das jede Entwicklerin und jeder Entwickler an jeder Aufrufstelle denken muss, sondern etwas, das der Browser erzwingt.

Den Content-Security-Policy-Header setzen

Trusted Types wird über die CSP-Direktive require-trusted-types-for 'script' aktiviert. Senden Sie diese Direktive zunächst im Header Content-Security-Policy-Report-Only. In diesem Modus meldet der Browser Verstöße, führt den Code aber weiterhin aus.

Content-Security-Policy-Report-Only: require-trusted-types-for 'script'

Ergänzen Sie mit der Direktive report-to einen Reporting-Endpunkt. So sendet der Browser jeden verletzenden Sink an Ihren Collector, statt ihn nur in der Konsole zu protokollieren. Sobald keine Reports mehr eingehen, wechseln Sie zum durchsetzenden Header:

Content-Security-Policy: require-trusted-types-for 'script'; trusted-types app-html

require-trusted-types-for sorgt dafür, dass String-Zuweisungen an Sinks einen Fehler auslösen. trusted-types listet die zulässigen Policy-Namen auf. trustedTypes.createPolicy() wirft einen Fehler, wenn Sie die Funktion mit einem Namen aufrufen, der nicht in dieser Liste steht. Senden Sie beide Direktiven als Response-Header, denn Browser unterstützen weder den Report-only-Header noch die Direktive report-to in einem <meta>-Tag.

Eine Policy erstellen, die DOMPurify kapselt

Erstellen Sie die Trusted-Types-Policy in einer React-App genau einmal auf Modulebene und importieren Sie sie überall dort, wo Sie sie benötigen. createPolicy() wirft bei einem doppelten Namen einen TypeError, sofern 'allow-duplicates' nicht in der Direktive trusted-types enthalten ist. Der Rumpf einer Komponente ist daher der falsche Ort dafür, denn React rendert Komponenten erneut, und der StrictMode ruft sie doppelt auf.

// 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 gibt einen bereinigten String zurück, den der Browser in ein TrustedHTML-Objekt verpackt. Mit TRUSTED_TYPES_POLICY: null verhindern Sie, dass DOMPurify eine eigene interne dompurify-Policy anlegt. Auf der Allowlist muss dann nur app-html stehen. Verwenden Sie RETURN_TRUSTED_TYPE: true nicht innerhalb von createHTML, da der Callback einen einfachen String zurückgeben muss.

Das Fallback-Objekt setzt den Tinyfill-Ansatz von MDN in einer für ES-Module geeigneten Form um. Fehlt die API, gibt createPolicy Ihr Regelobjekt unverändert zurück. htmlPolicy.createHTML() führt also weiterhin DOMPurify aus und liefert einen String. Der Codepfad ist damit überall identisch. Da das Fallback lokal definiert ist, lässt sich das Modul auch beim Server-Side Rendering fehlerfrei importieren, wo trustedTypes undefiniert ist. Für die Bereinigung auf dem Server benötigt DOMPurify allerdings eine DOM-Implementierung. Die README von DOMPurify beschreibt dieses Setup.

DOMPurify bietet außerdem eine Abkürzung: Rufen Sie DOMPurify.sanitize(dirty, { RETURN_TRUSTED_TYPE: true }) ohne eigene Policy auf. Wo die API unterstützt wird, erhalten Sie TrustedHTML zurück. In diesem Fall nehmen Sie dompurify in die Allowlist auf (trusted-types app-html dompurify).

Die Policy mit dangerouslySetInnerHTML verwenden

Ab React 19.3 übergeben Sie die Ausgabe der Policy an __html, und React reicht das TrustedHTML-Objekt unverändert an innerHTML weiter.

// Before: under enforcement, the raw string throws a TypeError
<div dangerouslySetInnerHTML={{ __html: html }} />

Im Report-only-Modus erscheint diese Zeile als Verstoß in den Reports. Bei aktiver Durchsetzung wirft sie einen Fehler.

import { htmlPolicy } from './trusted-html';

export function RichText({ html }) {
  return <div dangerouslySetInnerHTML={{ __html: htmlPolicy.createHTML(html) }} />;
}

Leiten Sie sämtliche Ausgaben aus CMS, Markdown und Rich-Text über RichText (oder einen direkten Aufruf von htmlPolicy.createHTML()). Wenn Sie später nach __html: greppen, sollte jeder Treffer neben einem Policy-Aufruf stehen.

Trusted Types sicher ausrollen

Ein sicherer Rollout von Trusted Types umfasst vier Phasen: nur melden, jeden gemeldeten Sink beheben, Policy-Namen auf die Allowlist setzen und schließlich durchsetzen.

  1. Deployen Sie Content-Security-Policy-Report-Only: require-trusted-types-for 'script' zusammen mit einem Reporting-Endpunkt.
  2. Beheben Sie jeden gemeldeten Sink, indem Sie ihn über htmlPolicy leiten, oder ersetzen Sie ihn durch einen Sink, der keine Trusted-Werte benötigt, etwa textContent.
  3. Führen Sie in trusted-types jeden Policy-Namen auf, den Ihr Code und Ihre Abhängigkeiten erzeugen.
  4. Wechseln Sie zum durchsetzenden Content-Security-Policy-Header.

Weist Code von Drittanbietern weiterhin Strings zu, die Sie noch nicht korrigieren können, kann eine Policy namens default als vorübergehende Brücke dienen. Bei aktiver Durchsetzung übergibt der Browser ihr jeden einfachen String, der einen Sink erreicht. MDN empfiehlt, sie nur während der Migration von Legacy-Code einzusetzen.

// 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 });
    },
  });
}

Durch die Feature-Prüfung wirft das Modul weder in Browsern ohne die API noch beim Server-Side Rendering einen Fehler.

Nehmen Sie default in trusted-types auf, solange diese Policy existiert. Sobald keine Warnungen mehr erscheinen, entfernen Sie sowohl die Policy als auch den Allowlist-Eintrag.

Was passiert in Browsern ohne Trusted Types?

Browser ohne Trusted Types setzen nichts durch. Dort steht allein der Sanitizer in Ihrer Policy zwischen nicht vertrauenswürdigem HTML und dem DOM. MDN führt window.trustedTypes als Baseline 2026, neu verfügbar seit Februar 2026. Ältere Browserversionen in Ihrem Traffic unterstützen die API also nicht.

Genau hierfür sorgt das Fallback auf Modulebene: Nicht unterstützende Browser ignorieren den Header, führen aber bei jedem Aufruf weiterhin DOMPurify.sanitize() aus. Deshalb muss die Policy immer bereinigen und darf ihre Eingabe niemals unverändert zurückgeben.

Fazit

React 19.3 entfernt die String-Umwandlung, an der Trusted Types bisher scheiterte. dangerouslySetInnerHTML kann damit jetzt von einer Policy erzeugtes HTML transportieren, das der Browser durchsetzt. Liefern Sie zuerst den Report-only-Header aus, führen Sie jede __html-Zuweisung über eine einzige Policy auf Basis von DOMPurify und aktivieren Sie die Durchsetzung, sobald keine Reports mehr eingehen. Übertragen Sie anschließend dieselbe Disziplin mit diesen Best Practices für API-Sicherheit auf die Serverseite.

FAQ

Was passiert, wenn eine Trusted-Types-Default-Policy null oder undefined zurückgibt?

Der Browser wirft am Sink einen TypeError, und die Zuweisung findet nicht statt. Eine Default-Policy, die null oder undefined zurückgibt, lässt den Wert also nicht einfach durch. Sie schlägt sicher fehl (fail closed) und blockiert den Schreibvorgang, statt den ursprünglichen String durchzulassen. Eine Default-Policy, die für jede Eingabe null zurückgibt, eignet sich während der Migration außerdem gut, um verbliebene String-Zuweisungen aufzuspüren.

Ist es sicher, eine Wildcard oder allow-duplicates in der Direktive trusted-types zu verwenden?

Für den Produktivbetrieb ist beides keine gute Wahl. Ein Stern (*) als Policy-Name erlaubt jeden eindeutigen Policy-Namen, sodass eingeschleustes Skript eine eigene Policy registrieren und Trusted-Werte erzeugen könnte. Das Schlüsselwort 'allow-duplicates' erlaubt es, mehrere Policies mit demselben Namen anzulegen, sodass ein Name nicht mehr eindeutig einer bekannten Policy entspricht. Führen Sie stattdessen jeden exakten Policy-Namen auf, den Ihr Code und Ihre Abhängigkeiten erzeugen.

Kann ich eval() weiterhin verwenden, wenn Trusted Types durchgesetzt wird?

Ja. Ergänzen Sie Ihre CSP um das Schlüsselwort 'trusted-types-eval'. Es erlaubt eval() und vergleichbare Funktionen nur in Browsern, die Trusted Types unterstützen und durchsetzen. Anders als 'unsafe-eval' bleiben diese Funktionen in Browsern ohne Trusted-Types-Unterstützung gesperrt. Bei aktiver Durchsetzung muss der an eval() übergebene Code weiterhin ein TrustedScript sein oder ein einfacher String, den eine Default-Policy in ein solches umwandelt. Andernfalls wirft der Aufruf einen Fehler.

DevTools for the frontend

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

We use cookies to improve your experience. By using our site, you accept cookies.