TrustedTypePolicyFactory.isScriptURL() — Methode · JavaScript-Referenz

Signatur

TrustedTypePolicyFactory.prototype.isScriptURL(value)

Beschreibung

Die Methode isScriptURL() gehört zur TrustedTypePolicyFactory, die global über window.trustedTypes (bzw. self.trustedTypes in Workern) erreichbar ist. Sie gibt true zurück, wenn der übergebene Wert ein gültiges TrustedScriptURL-Objekt ist, also über policy.createScriptURL() einer registrierten Policy entstanden ist.

Gebraucht wird sie vor allem in Bibliotheken und Hilfsfunktionen, die Skript-URLs annehmen, etwa für script.src, new Worker() oder importScripts(). Damit lässt sich unterscheiden, ob ein Wert schon geprüft ist oder erst noch durch eine Policy laufen muss, bevor er einer sogenannten Injection Sink zugewiesen wird.

Wichtig: Die Prüfung schaut auf die interne Markierung des Objekts, nicht auf dessen Inhalt oder Prototyp. Ein normaler String mit einer URL, ein nachgebautes Objekt mit passender toString()-Methode oder ein TrustedHTML-Objekt ergibt immer false. Ein TrustedScriptURL aus einem anderen Realm (z. B. aus einem iframe) erkennt die Methode dagegen korrekt.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	any		Der zu prüfende Wert. Jeder Typ ist erlaubt; nur echte `TrustedScriptURL`-Instanzen ergeben `true`.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn value ein gültiges TrustedScriptURL-Objekt ist, sonst false.

Beispiele

Grundlegende Prüfung

const policy = trustedTypes.createPolicy('script-urls', {
  createScriptURL: (url) => {
    const parsed = new URL(url, location.href);
    if (parsed.origin !== location.origin) {
      throw new TypeError(`Fremde Skript-URL blockiert: ${url}`);
    }
    return parsed.href;
  }
});

const trusted = policy.createScriptURL('/js/app.js');
const plain = '/js/app.js';

console.log(trustedTypes.isScriptURL(trusted));
console.log(trustedTypes.isScriptURL(plain));

true false

Gefälschte Objekte und falsche Trusted-Typen erkennen

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

const fake = { toString: () => '/js/evil.js' };
const html = policy.createHTML('<b>Hallo</b>');

console.log(trustedTypes.isScriptURL(fake));   // nachgebautes Objekt
console.log(trustedTypes.isScriptURL(html));   // TrustedHTML, nicht ScriptURL
console.log(trustedTypes.isScriptURL(policy.createScriptURL('/js/ok.js')));

false false true

Hilfsfunktion zum sicheren Laden von Skripten

const scriptPolicy = trustedTypes.createPolicy('loader', {
  createScriptURL: (url) => {
    const u = new URL(url, location.href);
    const erlaubt = [location.origin, 'https://cdn.example.com'];
    if (!erlaubt.includes(u.origin)) {
      throw new TypeError(`Nicht erlaubt: ${u.origin}`);
    }
    return u.href;
  }
});

const loadScript = (src) => new Promise((resolve, reject) => {
  // Nur ungeprüfte Werte durch die Policy schicken
  const safeSrc = trustedTypes.isScriptURL(src)
    ? src
    : scriptPolicy.createScriptURL(src);

  const script = document.createElement('script');
  script.src = safeSrc;
  script.onload = resolve;
  script.onerror = () => reject(new Error(`Laden fehlgeschlagen: ${src}`));
  document.head.append(script);
});

await loadScript('https://cdn.example.com/lib.js');
console.log('Bibliothek geladen');

Bibliothek geladen

Feature-Erkennung mit Fallback

const isTrustedScriptURL = (value) =>
  typeof trustedTypes !== 'undefined' && trustedTypes.isScriptURL(value);

console.log(isTrustedScriptURL('/js/app.js'));

false

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser (Chrome, Edge, Opera) unterstützen Trusted Types seit Version 83. Firefox und Safari haben die API erst vor Kurzem eingeführt. Ohne Unterstützung ist window.trustedTypes undefined, deshalb vorher auf Verfügbarkeit prüfen oder ein Polyfill wie trusted-types von W3C/Google nutzen.
Die Methode prüft nicht, ob die URL tatsächlich sicher ist. Sie bestätigt nur, dass der Wert durch eine Policy gelaufen ist. Die Sicherheit hängt also ganz von der Logik in createScriptURL ab. Eine Policy, die Eingaben ungeprüft weiterreicht, macht den Schutz wirkungslos.
Unterschiedliche Trusted-Typen sind nicht austauschbar: Für ein TrustedHTML oder TrustedScript liefert isScriptURL() false. Dafür gibt es isHTML() und isScript().
Die Prüfung allein erzwingt nichts. Durchgesetzt wird der Schutz erst durch den CSP-Header Content-Security-Policy: require-trusted-types-for 'script'. Dann führt die Zuweisung eines normalen Strings an script.src zu einem TypeError, sofern keine Standard-Policy (default) greift.
Die Methode ist auch in Web Workern über self.trustedTypes verfügbar.

Siehe auch

TrustedTypePolicyFactory.getPropertyType() TrustedTypePolicyFactory.isScript() TrustedTypePolicyFactory.isHTML() TrustedTypePolicyFactory.createPolicy() TrustedTypePolicyFactory.getAttributeType()