TrustedScriptURL.toString() — Methode · JavaScript-Referenz

Signatur

TrustedScriptURL.prototype.toString()

Beschreibung

Die Methode toString() gehört zur Schnittstelle TrustedScriptURL der Trusted Types API. Ein TrustedScriptURL-Objekt entsteht nur über TrustedTypePolicy.createScriptURL(). Es steht für eine URL, die eine Policy geprüft hat und die damit für Injection-Sinks wie HTMLScriptElement.src, Worker() oder importScripts() als sicher gilt. toString() gibt den darin gespeicherten Wert als einfachen String zurück.

Normalerweise ruft man toString() nicht selbst auf. Weist man das Objekt direkt einem Sink zu, nimmt der Browser es als vertrauenswürdig an. Die Methode braucht man vor allem, um den Wert zu protokollieren, zu vergleichen oder an APIs weiterzugeben, die einen echten String verlangen. Auch Template-Literale, String-Verkettung und String(obj) rufen toString() implizit auf.

Wichtig: Der zurückgegebene String ist kein Trusted Type mehr. Setzt die Seite per CSP require-trusted-types-for 'script' durch, lehnt der Browser diesen String an einem Sink ab (oder schickt ihn durch die Default-Policy). Das Ergebnis entspricht dem von TrustedScriptURL.prototype.toJSON().

Rückgabewert

Typ

string

Beschreibung

Die gekapselte Skript-URL als normaler String, genau so, wie die Policy-Funktion createScriptURL sie zurückgegeben hat.

Beispiele

Policy anlegen und URL als String auslesen

// Policy, die nur Skripte vom eigenen CDN erlaubt
const policy = trustedTypes.createPolicy('cdn-scripts', {
  createScriptURL: (input) => {
    const url = new URL(input, location.origin);
    if (url.origin !== 'https://cdn.example.com') {
      throw new TypeError(`Unerlaubte Skript-Quelle: ${url.origin}`);
    }
    return url.href;
  }
});

const trustedUrl = policy.createScriptURL('https://cdn.example.com/lib/app.js');
console.log(trustedUrl.toString());
console.log(typeof trustedUrl.toString());

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

Vertrauenswürdige URL an einen Sink geben und protokollieren

const policy = trustedTypes.createPolicy('loader', {
  createScriptURL: (s) => (s.startsWith('/js/') ? s : (() => { throw new TypeError('Pfad nicht erlaubt'); })())
});

const loadScript = (path) => {
  const trusted = policy.createScriptURL(path);
  const script = document.createElement('script');
  script.src = trusted;            // Objekt direkt übergeben, nicht den String!
  console.log(`Lade Skript: ${trusted}`); // implizites toString()
  document.head.append(script);
};

loadScript('/js/analytics.js');

Lade Skript: /js/analytics.js

Nach toString() ist der Wert nicht mehr vertrauenswürdig

// Voraussetzung: CSP-Header
// Content-Security-Policy: require-trusted-types-for 'script'
const policy = trustedTypes.createPolicy('demo', { createScriptURL: (s) => s });
const trusted = policy.createScriptURL('/js/worker.js');

console.log(trustedTypes.isScriptURL(trusted));            // true
console.log(trustedTypes.isScriptURL(trusted.toString())); // false

try {
  new Worker(trusted.toString()); // einfacher String -> blockiert
} catch (err) {
  console.log(err.name);
}
const worker = new Worker(trusted); // funktioniert

true false TypeError

// Wichtig · Fallstricke

Vertrauensstatus geht verloren: toString() liefert einen einfachen String. Wenn Trusted Types erzwungen werden, nimmt ein Sink diesen String nicht mehr an. Übergib Sinks deshalb immer das TrustedScriptURL-Objekt selbst.
Die Sicherheit hängt an der Policy: Die Methode prüft nichts. Sie gibt nur zurück, was createScriptURL geliefert hat. Eine Policy wie (s) => s bietet keinen Schutz vor XSS. Prüfe Herkunft (Origin), Protokoll (z. B. javascript: oder data: ausschließen) und Pfad.
Implizite Umwandlung: Template-Literale, +-Verkettung und String() rufen toString() automatisch auf. Auch dabei entsteht ein nicht vertrauenswürdiger String.
Browser-Kompatibilität: Trusted Types gibt es in Chromium-basierten Browsern seit Version 83. In Firefox und Safari kam die Unterstützung erst in neueren Versionen. Frag die Unterstützung vorher ab, z. B. mit if (window.trustedTypes?.createPolicy), oder nutze ein Polyfill wie trusted-types von W3C/Google.
Die Trusted Types API steht auch in Web Workern zur Verfügung (self.trustedTypes).

Siehe auch

PushSubscription.toJSON() TrustedScriptURL.toJSON() TrustedScript.toString() TrustedHTML.toString() TrustedScript.toJSON()