TrustedTypePolicy.createHTML() — Methode · JavaScript-Referenz

Signatur

TrustedTypePolicy.prototype.createHTML(input, ...args)

Beschreibung

createHTML() ist der zentrale Baustein, um mit Trusted Types DOM-basiertes XSS zu verhindern. Die Methode ruft die Funktion createHTML auf, die beim Anlegen der Richtlinie über trustedTypes.createPolicy() hinterlegt wurde. Deren Rückgabewert (ein bereinigter String) wird in ein TrustedHTML-Objekt verpackt.

Ist per Content Security Policy require-trusted-types-for 'script' aktiv, akzeptieren sogenannte Injection Sinks wie Element.innerHTML, outerHTML, insertAdjacentHTML(), DOMParser.parseFromString() oder document.write() keine normalen Strings mehr, sondern nur noch TrustedHTML. So wird jede HTML-Zuweisung zwangsläufig über eine geprüfte, zentral auditierbare Richtlinie geführt.

Verwenden Sie createHTML() immer dann, wenn Sie HTML aus nicht vertrauenswürdigen Quellen (Benutzereingaben, API-Antworten, URL-Parameter) ins DOM einfügen müssen. Die eigentliche Sicherheit hängt vollständig von der Bereinigungsfunktion ab – typischerweise ein Sanitizer wie DOMPurify oder ein striktes Escaping.

Zusätzliche Argumente nach input werden unverändert an die Richtlinienfunktion weitergereicht; damit lassen sich z. B. Kontextinformationen oder Optionen übergeben.

Parameter

Name	Typ	Default	Beschreibung
$input Pflicht	string		Der HTML-String, der von der Richtlinie geprüft bzw. bereinigt werden soll. Andere Werte werden in einen String umgewandelt.
$...args	any[]		Beliebige weitere Argumente, die an die `createHTML`-Funktion der Richtlinie weitergegeben werden.

Rückgabewert

Typ

TrustedHTML

Beschreibung

Ein TrustedHTML-Objekt, dessen toString() den von der Richtlinie gelieferten String zurückgibt. Liefert die Richtlinienfunktion null oder undefined, entsteht ein TrustedHTML mit leerem String.

Beispiele

Einfache Escape-Richtlinie

// Maskiert alle spitzen Klammern – ausführbares Markup bleibt als Text sichtbar
const escapePolicy = trustedTypes.createPolicy('escape-html', {
  createHTML: (input) => input.replace(/</g, '&lt;').replace(/>/g, '&gt;')
});

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

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

true <img src=x onerror="alert(1)">

Bereinigung mit DOMPurify vor innerHTML

import DOMPurify from 'dompurify';

const sanitizerPolicy = trustedTypes.createPolicy('dompurify', {
  createHTML: (dirty) => DOMPurify.sanitize(dirty)
});

const renderKommentar = async (id) => {
  const res = await fetch(`/api/kommentare/${id}`);
  const { html } = await res.json();
  // Nur TrustedHTML wird bei aktiver CSP akzeptiert
  document.querySelector('#kommentar').innerHTML = sanitizerPolicy.createHTML(html);
};

renderKommentar(42);

Zusätzliche Argumente und Feature-Erkennung

// Fallback für Browser ohne Trusted Types
const policy = window.trustedTypes?.createPolicy('kontext', {
  createHTML: (input, erlaubteTags = []) => {
    const tags = erlaubteTags.join('|');
    const re = new RegExp(`<(?!\/?(${tags})>)[^>]*>`, 'gi');
    return input.replace(re, '');
  }
}) ?? { createHTML: (s) => s };

const html = policy.createHTML('<b>fett</b><script>x()</script><i>kursiv</i>', ['b', 'i']);
console.log(html.toString());

<b>fett</b>x()<i>kursiv</i>

// Wichtig · Fallstricke

Sicherheit hängt an der Richtlinie: Eine Richtlinie wie createHTML: s => s hebelt den Schutz komplett aus. Selbstgebaute Regex-Filter (wie im dritten Beispiel) sind nur zur Demonstration geeignet – nutzen Sie für echte Bereinigung einen bewährten Sanitizer.
Fehlende Funktion: Wurde die Richtlinie ohne createHTML angelegt, wirft der Aufruf einen TypeError.
CSP: Ohne require-trusted-types-for 'script' werden Strings weiterhin akzeptiert – Trusted Types wirken dann nur freiwillig. Mit der Direktive trusted-types lässt sich festlegen, welche Richtliniennamen überhaupt erstellt werden dürfen; unbekannte Namen führen bei createPolicy() zu einem Fehler.
Browser-Kompatibilität: Vollständig unterstützt in Chromium-Browsern (Chrome, Edge, Opera) ab Version 83; Firefox und Safari ziehen erst nach. Mit window.trustedTypes?.createPolicy erkennen und bei Bedarf Polyfill (trusted-types von W3C) einsetzen.
Ein TrustedHTML-Objekt ist nicht an eine bestimmte Senke gebunden, darf aber nur für HTML-Senken verwendet werden – für Skripte bzw. Skript-URLs gibt es createScript() und createScriptURL().

Siehe auch

TrustedTypePolicy TrustedTypePolicyFactory.createPolicy() TrustedHTML TrustedTypePolicy.createScript() TrustedTypePolicy.createScriptURL() Element.innerHTML new SecurityPolicyViolationEvent()