TrustedTypePolicyFactory — Schnittstelle · JavaScript-Referenz

Signatur

interface TrustedTypePolicyFactory

Beschreibung

TrustedTypePolicyFactory ist der zentrale Einstiegspunkt der Trusted Types API. Einen eigenen Konstruktor gibt es nicht. Die einzige Instanz liegt global unter window.trustedTypes bzw. in Workern unter self.trustedTypes. Über diese Fabrik legst du mit createPolicy() benannte Richtlinien (TrustedTypePolicy) an. Sie wandeln unsichere Zeichenketten kontrolliert in typisierte, vertrauenswürdige Objekte um.

Wirksam wird das Ganze erst mit der CSP-Direktive require-trusted-types-for 'script'. Ist sie aktiv, werfen DOM-Senken für XSS wie innerHTML, outerHTML, insertAdjacentHTML(), eval(), script.src oder document.write() einen TypeError, wenn sie einfache Strings statt Trusted-Type-Objekten bekommen. Mit der Direktive trusted-types legst du fest, welche Namen von Richtlinien erlaubt sind.

Wichtige Mitglieder:

createPolicy(name, options): erstellt eine Richtlinie mit den Funktionen createHTML, createScript und createScriptURL. Der Name "default" erzeugt die Standard-Richtlinie. Sie wird automatisch aufgerufen, sobald ein String an eine Senke übergeben wird.
isHTML(value), isScript(value), isScriptURL(value): prüfen, ob ein Wert ein gültiges, von einer Richtlinie erzeugtes Objekt des jeweiligen Typs ist.
getAttributeType(tagName, attribute, elementNS?, attrNS?) und getPropertyType(tagName, property, elementNS?): geben zurück, welcher Trusted Type für ein Attribut bzw. eine Eigenschaft nötig ist ("TrustedHTML", "TrustedScript", "TrustedScriptURL" oder null).
emptyHTML und emptyScript: fertige, leere TrustedHTML- bzw. TrustedScript-Objekte, z. B. zum Leeren eines Elements ohne eigene Richtlinie.
defaultPolicy: die aktuelle Standard-Richtlinie oder null.

Das Interface brauchst du, wenn du eine Anwendung gegen DOM-basiertes XSS absichern willst. Statt jede Zuweisung einzeln zu prüfen, landet die gesamte Bereinigung in wenigen Richtlinien, die man gezielt prüfen kann.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		(`createPolicy`) Name der Richtlinie. Er muss in der CSP-Direktive `trusted-types` erlaubt sein. `"default"` erzeugt die Standard-Richtlinie.
$options	{ createHTML?: Function, createScript?: Function, createScriptURL?: Function }	{}	(`createPolicy`) Umwandlungsfunktionen. Sie bekommen den Eingabe-String und weitere Argumente und geben den bereinigten String zurück. Fehlt eine Funktion, wirft der entsprechende Aufruf einen `TypeError`.
$value Pflicht	any		(`isHTML`/`isScript`/`isScriptURL`) Der Wert, der geprüft werden soll.
$tagName Pflicht	string		(`getAttributeType`/`getPropertyType`) Name des Elements, z. B. `"script"`.
$attribute \| property Pflicht	string		Name des Attributs (z. B. `"src"`, `"onclick"`) bzw. der DOM-Eigenschaft (z. B. `"innerHTML"`).
$elementNS	string	HTML-Namespace	Namespace des Elements, z. B. für SVG.
$attrNS	string	null	(`getAttributeType`) Namespace des Attributs.

Rückgabewert

Typ

Beschreibung

Hängt vom Mitglied ab: createPolicy() liefert eine TrustedTypePolicy, die is*()-Methoden liefern boolean, get*Type() liefert den Typnamen als string oder null, emptyHTML/emptyScript liefern leere Trusted-Objekte.

Beispiele

Feature-Erkennung und eigene Richtlinie anlegen

// CSP-Header (serverseitig):
// Content-Security-Policy: require-trusted-types-for 'script'; trusted-types escapePolicy

const escapePolicy = window.trustedTypes?.createPolicy('escapePolicy', {
  createHTML: (input) => input
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
});

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

// Fallback für Browser ohne Trusted Types
output.innerHTML = escapePolicy
  ? escapePolicy.createHTML(userInput)
  : userInput.replace(/</g, '&lt;');

console.log(output.textContent);

Trusted-Type-Objekte prüfen mit isHTML()

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

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

console.log(trustedTypes.isHTML(trusted));          // true
console.log(trustedTypes.isHTML('<b>Hallo</b>'));   // false – normaler String
console.log(trustedTypes.isScript(trusted));        // false – falscher Typ
console.log(trustedTypes.isHTML(trustedTypes.emptyHTML)); // true

true false false true

Benötigten Typ für Attribute und Eigenschaften ermitteln

console.log(trustedTypes.getPropertyType('div', 'innerHTML'));
console.log(trustedTypes.getAttributeType('script', 'src'));
console.log(trustedTypes.getAttributeType('div', 'onclick'));
console.log(trustedTypes.getAttributeType('div', 'title'));

// Element leeren, ohne eine Richtlinie zu brauchen
document.body.innerHTML = trustedTypes.emptyHTML;

TrustedHTML TrustedScriptURL TrustedScript null

Standard-Richtlinie für Altcode (mit DOMPurify)

// Fängt alle String-Zuweisungen an Senken ab, z. B. aus Bibliotheken
if (window.trustedTypes && !trustedTypes.defaultPolicy) {
  trustedTypes.createPolicy('default', {
    createHTML: (input, sink) => {
      console.warn('Nicht typisierte Zuweisung an', sink);
      return DOMPurify.sanitize(input);
    }
    // createScript/createScriptURL fehlen -> solche Zuweisungen werden blockiert
  });
}

document.querySelector('#box').innerHTML = '<p onclick="x()">Text</p>';

Nicht typisierte Zuweisung an Element innerHTML

Siehe auch

TrustedTypePolicy TrustedScriptURL CreateMonitor FeaturePolicy TrustedScript