TrustedScript — Schnittstelle · JavaScript-Referenz

Signatur

interface TrustedScript

Beschreibung

TrustedScript gehört zur Trusted Types API. Ein Objekt dieses Typs kapselt einen String mit JavaScript-Quelltext, der von einer TrustedTypePolicy geprüft oder bereinigt wurde. Es lässt sich nicht direkt mit einem Konstruktor erzeugen, sondern nur über policy.createScript(input).

Ist per Content Security Policy require-trusted-types-for 'script' aktiv, lehnt der Browser einfache Strings an Skript-Sinks ab und wirft einen TypeError. Das betrifft zum Beispiel eval(), new Function(), HTMLScriptElement.text, textContent und innerText von <script>-Elementen sowie String-Argumente von setTimeout()/setInterval(). Diese Sinks nehmen dann nur noch TrustedScript-Objekte an. So lässt sich jede Stelle, an der Code dynamisch erzeugt wird, auf wenige überprüfbare Policies zurückführen.

Das Interface hat zwei Instanzmethoden: toString() und toJSON(). Beide geben den gekapselten Skript-String zurück. Ob ein Wert ein echtes TrustedScript ist, prüfst du mit trustedTypes.isScript(value).

Rückgabewert

Typ

TrustedScript

Beschreibung

Wird von TrustedTypePolicy.prototype.createScript() zurückgegeben; toString() und toJSON() geben den enthaltenen string zurück.

Beispiele

Policy anlegen und TrustedScript erzeugen

// Voraussetzung: CSP-Header
// Content-Security-Policy: require-trusted-types-for 'script'; trusted-types script-policy
const policy = trustedTypes.createPolicy('script-policy', {
  createScript: (input) => {
    // Nur erlaubte, bekannte Snippets durchlassen
    const erlaubt = ['console.log("Hallo")'];
    if (!erlaubt.includes(input)) {
      throw new TypeError('Skript nicht erlaubt: ' + input);
    }
    return input;
  }
});

const trusted = policy.createScript('console.log("Hallo")');
console.log(trustedTypes.isScript(trusted));
console.log(trusted.toString());

true console.log("Hallo")

TrustedScript an ein <script>-Element übergeben

const policy = trustedTypes.createPolicy('inline-loader', {
  createScript: (code) => code // in echten Projekten: prüfen!
});

const script = document.createElement('script');
// Ein einfacher String würde hier bei aktiver CSP einen TypeError auslösen
script.textContent = policy.createScript('window.appReady = true;');
document.head.append(script);

console.log(window.appReady);

true

Feature-Erkennung mit Fallback

const toScript = (code) => {
  if (window.trustedTypes?.createPolicy) {
    const policy = trustedTypes.createPolicy('fallback-script', {
      createScript: (s) => s
    });
    return policy.createScript(code);
  }
  return code; // Browser ohne Trusted Types: normaler String
};

const result = eval(toScript('2 + 3'));
console.log(result);

5

Serialisierung per toJSON()

const policy = trustedTypes.createPolicy('json-demo', {
  createScript: (s) => s
});
const ts = policy.createScript('alert(1)');
console.log(JSON.stringify({ code: ts }));

{"code":"alert(1)"}

// Wichtig · Fallstricke

Kein Konstruktor: new TrustedScript() wirft einen TypeError. Instanzen entstehen nur über createScript() einer Policy.
Die Sicherheit hängt an der Policy: Eine Policy wie createScript: s => s gibt jeden Code ungeprüft durch und macht den Schutz wirkungslos. Solche Durchreich-Policies sollten selten und eng begrenzt sein, zum Beispiel über die CSP-Direktive trusted-types mit festgelegten Policy-Namen.
Schutz vor XSS: Skripte lassen sich kaum sinnvoll „bereinigen“, anders als HTML mit DOMPurify. Besser sind Allowlists oder der vollständige Verzicht auf eval/new Function.
Nur für Skript-Sinks: Für innerHTML ist TrustedHTML nötig, für script.src ist TrustedScriptURL nötig.
eval() zusätzlich freigeben: Die CSP muss dafür zusätzlich 'unsafe-eval' bzw. 'trusted-types-eval' erlauben.
Browser-Unterstützung: Chromium-Browser ab Version 83. Firefox und Safari unterstützen die API erst seit Kurzem. Für ältere Browser gibt es ein Polyfill (w3c/trusted-types) oder eine Feature-Erkennung über window.trustedTypes.
Testen ohne Blockieren: Mit Content-Security-Policy-Report-Only werden Verstöße nur gemeldet, aber nicht blockiert. So lässt sich die API schrittweise einführen.

Siehe auch

eval() TrustedScriptURL TrustedHTML SubtleCrypto USBEndpoint