Window.trustedTypes — Eigenschaft · JavaScript-Referenz

Signatur

Window.trustedTypes

Beschreibung

Die schreibgeschützte Eigenschaft window.trustedTypes liefert die TrustedTypePolicyFactory des aktuellen globalen Objekts. Sie ist der Einstiegspunkt in die Trusted Types API. Mit dieser API lassen sich DOM-basierte XSS-Lücken verhindern: Gefährliche Injection-Sinks wie innerHTML, eval() oder script.src nehmen dann keine einfachen Zeichenketten mehr an, sondern nur noch typisierte Objekte (TrustedHTML, TrustedScript, TrustedScriptURL).

Über die Factory erstellt man mit trustedTypes.createPolicy(name, regeln) benannte Richtlinien. Diese legen fest, wie ein Eingabestring bereinigt oder geprüft wird, bevor er als vertrauenswürdig gilt. Zusätzlich bietet die Factory Hilfsmethoden wie isHTML(), isScript(), isScriptURL(), getAttributeType() und getPropertyType() sowie die Eigenschaften emptyHTML, emptyScript und defaultPolicy.

Durchgesetzt wird das Ganze über den CSP-Header Content-Security-Policy: require-trusted-types-for 'script'. Welche Richtliniennamen erlaubt sind, regelt die Direktive trusted-types. Ohne diese CSP-Direktiven kannst du die API zwar nutzen, der Browser erzwingt dann aber nichts. Die Eigenschaft gibt es auch in Workern als self.trustedTypes (WorkerGlobalScope.trustedTypes).

Rückgabewert

Typ

TrustedTypePolicyFactory

Beschreibung

Das TrustedTypePolicyFactory-Objekt des globalen Kontexts. In Browsern ohne Unterstützung ist die Eigenschaft undefined.

Beispiele

Unterstützung prüfen und Richtlinie anlegen

// Feature-Erkennung: Trusted Types verfügbar?
const policy = window.trustedTypes?.createPolicy('escape-policy', {
  createHTML: (input) => input
    .replaceAll('&', '&amp;')
    .replaceAll('<', '&lt;')
    .replaceAll('>', '&gt;')
});

const userInput = '<img src=x onerror=alert(1)>';
const el = document.querySelector('#ausgabe');

// Mit Richtlinie ein TrustedHTML-Objekt, sonst Fallback auf textContent
if (policy) {
  el.innerHTML = policy.createHTML(userInput);
} else {
  el.textContent = userInput;
}
console.log(el.innerHTML);

Typen prüfen mit isHTML() und emptyHTML

const policy = trustedTypes.createPolicy('demo', {
  createHTML: (s) => s
});

const trusted = policy.createHTML('<b>Hallo</b>');

console.log(trustedTypes.isHTML(trusted));        // echtes TrustedHTML
console.log(trustedTypes.isHTML('<b>Hallo</b>')); // normaler String

// Inhalt leeren, ohne eine Richtlinie zu benötigen
document.body.innerHTML = trustedTypes.emptyHTML;
console.log(trustedTypes.getPropertyType('div', 'innerHTML'));

true false TrustedHTML

Default-Policy als Übergangslösung für Altcode

// Wird automatisch aufgerufen, wenn unter erzwungener CSP ein String an einen Sink geht
if (window.trustedTypes && !trustedTypes.defaultPolicy) {
  trustedTypes.createPolicy('default', {
    createHTML: (value, sink) => {
      console.warn('Unsicherer Sink genutzt:', sink);
      // Hier z. B. DOMPurify.sanitize(value) einsetzen
      return value.replace(/<script[\s\S]*?<\/script>/gi, '');
    },
    createScriptURL: (url) => {
      const u = new URL(url, location.href);
      if (u.origin === location.origin) return u.href;
      throw new TypeError(`Nicht erlaubte Skript-URL: ${url}`);
    }
  });
}

console.log(trustedTypes.defaultPolicy?.name);

default

// Wichtig · Fallstricke

Browser-Kompatibilität: Chrome und Edge unterstützen die API seit Version 83. Firefox und Safari kamen deutlich später hinzu. Prüfe immer mit window.trustedTypes?. oder 'trustedTypes' in window. Für ältere Browser gibt es den Polyfill trusted-types von W3C/Google.
Schutz nur mit CSP: Erst require-trusted-types-for 'script' sorgt dafür, dass Strings an Sinks einen TypeError auslösen. Ohne diese Direktive ist die API rein freiwillig.
Die Richtlinie ist die Sicherheitsgrenze: Eine Richtlinie wie createHTML: s => s bietet keinerlei Schutz. Bereinige Eingaben mit einem geprüften Sanitizer wie DOMPurify und halte die Zahl der Richtlinien klein.
Mit der CSP-Direktive trusted-types meinePolicy legst du fest, welche Namen erlaubt sind. Doppelte Namen erlaubt die CSP nur mit 'allow-duplicates'. Wird ein nicht erlaubter Name verwendet, wirft createPolicy() einen Fehler.
Die Richtlinie 'default' greift automatisch bei jeder String-Zuweisung an einen Sink. Sie eignet sich zur Migration, sollte aber keine Dauerlösung sein.
Mit Content-Security-Policy-Report-Only kannst du Verstöße zunächst nur melden lassen, ohne die Seite zu blockieren.

Siehe auch

Window.status Window.closed Window.cookieStore Window.crypto Window.frames