TrustedTypePolicyFactory.createPolicy() — Methode · JavaScript-Referenz

Signatur

TrustedTypePolicyFactory.prototype.createPolicy(policyName, policyOptions)

Beschreibung

Mit createPolicy(), aufgerufen über window.trustedTypes (bzw. self.trustedTypes in Workern), legst du eine benannte Trusted-Types-Richtlinie an. Sie enthält Umwandlungsfunktionen, die unsichere Zeichenketten prüfen oder bereinigen und daraus Objekte vom Typ TrustedHTML, TrustedScript oder TrustedScriptURL machen. Ist die CSP-Direktive require-trusted-types-for 'script' aktiv, nehmen gefährliche DOM-Senken wie innerHTML, eval() oder script.src nur noch solche Objekte an. Normale Zeichenketten werfen dann einen TypeError.

So werden DOM-basierte XSS-Lücken an wenigen, gut prüfbaren Stellen gebündelt: Alle Daten, die in eine Senke fließen, müssen durch eine deiner Richtlinien laufen. Typischerweise legt man eine Richtlinie für die Bereinigung von HTML an (z. B. mit DOMPurify) und eine für erlaubte Skript-URLs.

Mit dem besonderen Namen "default" erstellst du eine Standard-Richtlinie. Der Browser ruft sie automatisch auf, wenn eine normale Zeichenkette an eine Senke übergeben wird. Das hilft bei der Umstellung von Altcode oder Bibliotheken, die noch keine Trusted Types kennen. Welche Namen erlaubt sind und ob ein Name mehrfach vergeben werden darf, legt die CSP-Direktive trusted-types fest.

Parameter

Name	Typ	Default	Beschreibung
$policyName Pflicht	string		Name der Richtlinie. Er muss in der CSP-Direktive `trusted-types` erlaubt sein (sofern diese gesetzt ist). `"default"` legt die Standard-Richtlinie an.
$policyOptions	object	{}	Objekt mit den Umwandlungsfunktionen. Fehlt eine Funktion, wirft der Aufruf der passenden `create*`-Methode einen `TypeError`.
$policyOptions.createHTML	(input: string, ...args: any[]) => string		Wandelt eine Zeichenkette in HTML um, das sicher eingefügt werden kann. Der Rückgabewert wird zu `TrustedHTML`.
$policyOptions.createScript	(input: string, ...args: any[]) => string		Prüft Code für `eval()`, `new Function()` oder `script.textContent`. Der Rückgabewert wird zu `TrustedScript`.
$policyOptions.createScriptURL	(input: string, ...args: any[]) => string		Prüft URLs für `script.src`, `new Worker()`, `importScripts()` usw. Der Rückgabewert wird zu `TrustedScriptURL`.

Rückgabewert

Typ

TrustedTypePolicy

Beschreibung

Die neue Richtlinie mit den Methoden createHTML(), createScript(), createScriptURL() und der Eigenschaft name.

Beispiele

HTML-Richtlinie mit einfachem Escaping

// CSP: require-trusted-types-for 'script'; trusted-types escape-policy
const escapePolicy = trustedTypes.createPolicy('escape-policy', {
  createHTML: (input) => input
    .replaceAll('&', '&amp;')
    .replaceAll('<', '&lt;')
    .replaceAll('>', '&gt;')
});

const userInput = '<img src=x onerror=alert(1)>';
const safe = escapePolicy.createHTML(userInput);

document.querySelector('#ausgabe').innerHTML = safe;
console.log(safe.toString());

Bereinigung mit DOMPurify und Feature-Erkennung

import DOMPurify from 'dompurify';

// Fallback, falls der Browser keine Trusted Types kennt
const sanitizePolicy = window.trustedTypes?.createPolicy('sanitize', {
  createHTML: (dirty) => DOMPurify.sanitize(dirty)
}) ?? { createHTML: (dirty) => DOMPurify.sanitize(dirty) };

const renderKommentar = (html) => {
  document.querySelector('#kommentar').innerHTML = sanitizePolicy.createHTML(html);
};

renderKommentar('<b>Hallo</b><script>alert(1)</script>');
console.log(document.querySelector('#kommentar').innerHTML);

<b>Hallo</b>

Skript-URLs auf eigene Herkunft beschränken

const scriptPolicy = trustedTypes.createPolicy('script-loader', {
  createScriptURL: (url) => {
    const parsed = new URL(url, location.href);
    if (parsed.origin !== location.origin) {
      throw new TypeError(`Unerlaubte Skript-Quelle: ${parsed.origin}`);
    }
    return parsed.href;
  }
});

const script = document.createElement('script');
script.src = scriptPolicy.createScriptURL('/js/widget.js');
document.head.append(script);

try {
  scriptPolicy.createScriptURL('https://evil.example/x.js');
} catch (err) {
  console.log(err.message);
}

Unerlaubte Skript-Quelle: https://evil.example

Standard-Richtlinie für Altcode

trustedTypes.createPolicy('default', {
  createHTML: (input, sink) => {
    console.warn(`Ungeprüfte Zeichenkette an ${sink}`);
    return DOMPurify.sanitize(input);
  }
});

// Altcode mit normaler Zeichenkette läuft jetzt über die Standard-Richtlinie
document.body.innerHTML = '<p>Alt</p>';

Ungeprüfte Zeichenkette an Element innerHTML

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser seit Version 83, Firefox seit 142, Safari seit 26. In älteren Browsern ist window.trustedTypes undefined. Prüfe das also vorher oder nutze das offizielle Polyfill (trusted-types auf npm).
CSP-Fehler: Wenn trusted-types gesetzt ist und der Name dort fehlt, wirft createPolicy() einen TypeError. Das passiert auch, wenn ein Name ein zweites Mal vergeben wird und 'allow-duplicates' nicht erlaubt ist.
Nur so sicher wie die Funktionen: Eine Richtlinie wie createHTML: s => s gibt die Eingabe ungeprüft durch und hebelt den Schutz komplett aus. Bereinige mit bewährten Bibliotheken wie DOMPurify, statt eigene reguläre Ausdrücke zu schreiben.
Richtlinien kapseln: Gib Richtlinien-Objekte nicht global frei (z. B. über window). Wer Zugriff darauf hat, kann beliebige Werte als vertrauenswürdig markieren.
Standard-Richtlinie: Die "default"-Richtlinie bekommt als zusätzliche Argumente den Typnamen und die Senke (z. B. "Element innerHTML"). Gibt sie null oder undefined zurück, wird die Zuweisung blockiert.
Mit Content-Security-Policy-Report-Only kannst du Verstöße zunächst nur protokollieren lassen, bevor du Trusted Types scharf schaltest.

Siehe auch

TrustedTypePolicyFactory.isHTML() TrustedTypePolicyFactory.isScript() TrustedTypePolicyFactory.isScriptURL() TrustedTypePolicyFactory.getAttributeType() TrustedTypePolicyFactory.getPropertyType()