TrustedTypePolicy.createScriptURL() — Methode · JavaScript-Referenz

Signatur

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

Beschreibung

createScriptURL() gehört zur TrustedTypePolicy-Schnittstelle der Trusted Types API. Die Methode reicht die übergebene Zeichenkette (plus eventuelle Zusatzargumente) an die Funktion createScriptURL weiter, die beim Anlegen der Richtlinie mit trustedTypes.createPolicy() hinterlegt wurde. Aus deren Rückgabewert entsteht ein unveränderliches TrustedScriptURL-Objekt.

Die Methode braucht man immer dann, wenn eine Seite per Content-Security-Policy require-trusted-types-for 'script' Trusted Types erzwingt und trotzdem Skripte dynamisch lädt. Sicherheitsrelevante Stellen, die eine Skript-URL entgegennehmen, lehnen dann normale Strings ab. Dazu gehören unter anderem HTMLScriptElement.src, importScripts(), new Worker(), new SharedWorker() und navigator.serviceWorker.register(). Nur ein TrustedScriptURL wird dort akzeptiert.

Die eigentliche Schutzwirkung steckt in der Regelfunktion der Richtlinie: Sie sollte die URL gegen eine Positivliste (Allowlist) von Origins oder Pfaden prüfen und bei nicht erlaubten Werten einen Fehler werfen. Die Methode selbst prüft nichts. Sie garantiert nur, dass jeder Wert über genau diese zentrale, überprüfbare Stelle läuft.

Parameter

Name	Typ	Default	Beschreibung
$input Pflicht	string		Die zu prüfende oder zu bereinigende URL als Zeichenkette. Sie wird als erstes Argument an die Regelfunktion `createScriptURL` der Richtlinie übergeben.
$...args	any		Optionale Zusatzargumente, die unverändert an die Regelfunktion weitergereicht werden, z. B. Kontextinformationen für die Prüfung.

Rückgabewert

Typ

TrustedScriptURL

Beschreibung

Ein TrustedScriptURL-Objekt, das den von der Regelfunktion zurückgegebenen String enthält (mit toString() oder toJSON() abrufbar). Gibt die Regelfunktion null oder undefined zurück, ist der Wert ein leerer String.

Beispiele

Richtlinie mit Allowlist anlegen und Skript laden

// Nur Skripte vom eigenen Origin und einem CDN erlauben
const ERLAUBTE_ORIGINS = [location.origin, 'https://cdn.example.com'];

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

const script = document.createElement('script');
script.src = scriptPolicy.createScriptURL('https://cdn.example.com/lib.js');
document.head.append(script);

console.log(script.src);

https://cdn.example.com/lib.js

Nicht erlaubte URL abfangen

const policy = trustedTypes.createPolicy('strict-urls', {
  createScriptURL: (input) => {
    const url = new URL(input, location.href);
    if (url.origin !== location.origin) {
      throw new TypeError('Nur Same-Origin-Skripte erlaubt');
    }
    return url.href;
  }
});

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

Nur Same-Origin-Skripte erlaubt

Worker mit vertrauenswürdiger URL starten (mit Fallback)

// Fallback für Browser ohne Trusted Types
const workerPolicy = window.trustedTypes?.createPolicy('worker-urls', {
  createScriptURL: (input) => {
    if (!input.startsWith('/workers/')) {
      throw new TypeError('Worker nur aus /workers/ erlaubt');
    }
    return input;
  }
});

const toScriptURL = (url) => workerPolicy ? workerPolicy.createScriptURL(url) : url;

const worker = new Worker(toScriptURL('/workers/rechner.js'));
worker.postMessage({ a: 2, b: 3 });
console.log(workerPolicy?.createScriptURL('/workers/rechner.js') instanceof TrustedScriptURL);

true (in Browsern mit Trusted-Types-Unterstützung)

// Wichtig · Fallstricke

Fehlende Regel: Wurde die Richtlinie ohne createScriptURL-Funktion angelegt, wirft der Aufruf einen TypeError.
Schwache Regeln sind wirkungslos: Eine Regel wie (s) => s hebelt den Schutz vollständig aus. Prüfen Sie Origins mit new URL(), statt Strings zu vergleichen, und sperren Sie data:- und blob:-URLs, falls sie nicht gebraucht werden. Ein naives startsWith('https://cdn.example.com') lässt z. B. auch https://cdn.example.com.evil.net durch.
CSP: Die Durchsetzung greift nur mit dem Header require-trusted-types-for 'script'. Über die Direktive trusted-types legen Sie fest, welche Richtliniennamen angelegt werden dürfen. Ohne Durchsetzung akzeptieren die Zielstellen weiterhin normale Strings.
Kompatibilität: Unterstützt in Chromium-Browsern ab Version 83 und in neueren Safari-Versionen. In Firefox ist die API noch nicht standardmäßig aktiv. Prüfen Sie deshalb mit window.trustedTypes auf Unterstützung oder nutzen Sie ein Polyfill (z. B. trusted-types von W3C/Google).
Die Methode ist nur für Skript-URLs gedacht. Für HTML gibt es createHTML(), für Skript-Quelltext createScript().

Siehe auch

TrustedTypePolicy.createScript() TrustedTypePolicy.createHTML() TrustedTypePolicyFactory.isScriptURL() TrustedTypePolicyFactory.isScript() TrustedTypePolicyFactory.isHTML()