Signatur
Beschreibung
Die Methode toString() eines TrustedScript-Objekts gibt den Skript-Quelltext zurück, der beim Erzeugen durch die createScript()-Funktion einer TrustedTypePolicy festgelegt wurde. Ein TrustedScript ist ein Wrapper, der dem Browser zeigt, dass der String eine Sicherheitsrichtlinie durchlaufen hat und deshalb an skriptausführende Injection Sinks übergeben werden darf, etwa an eval(), new Function(), HTMLScriptElement.text oder setTimeout() mit einem String-Argument.
Normalerweise ruft man toString() nicht selbst auf. Übergibt man das TrustedScript-Objekt direkt an einen Sink, liest der Browser den Wert intern aus und die Trusted-Types-Prüfung ist erfüllt. Die Methode wird auch implizit aufgerufen, wenn das Objekt in einen String umgewandelt wird, etwa in Template-Literalen, bei der Verkettung mit + oder durch String(obj).
Einsetzen sollte man toString() vor allem zum Debuggen, Protokollieren oder Vergleichen des geprüften Inhalts. Das Ergebnis ist ein normaler String und kein Trusted Type mehr. Ist die CSP-Direktive require-trusted-types-for 'script' aktiv, lehnt der Browser diesen String an einem Sink wieder ab.
Die Methode liefert denselben Wert wie TrustedScript.prototype.toJSON().
Rückgabewert
createScript() erzeugt hat, als gewöhnlicher String.Beispiele
TrustedScript erzeugen und Inhalt auslesen
// Richtlinie, die nur einfache Konfigurations-Snippets erlaubt
const policy = trustedTypes.createPolicy('config-scripts', {
createScript: (input) => {
if (!/^window\.APP_CONFIG = \{.*\};$/.test(input)) {
throw new TypeError('Unerlaubtes Skript');
}
return input;
},
});
const trusted = policy.createScript('window.APP_CONFIG = {"debug":true};');
console.log(trusted instanceof TrustedScript);
console.log(trusted.toString());Direkt an den Sink übergeben statt toString() aufzurufen
const policy = trustedTypes.createPolicy('inline-scripts', {
createScript: (input) => input, // in echten Projekten: prüfen!
});
const trusted = policy.createScript('console.log("Hallo aus TrustedScript");');
const script = document.createElement('script');
// Richtig: das TrustedScript-Objekt selbst zuweisen
script.text = trusted;
document.head.append(script);
// Falsch unter require-trusted-types-for 'script':
// script.text = trusted.toString(); // -> TypeError, da nur ein normaler StringImplizite Umwandlung beim Protokollieren
const policy = trustedTypes.createPolicy('logger-demo', {
createScript: (input) => input.trim(),
});
const trusted = policy.createScript(' doSomething(); ');
// Template-Literal ruft toString() implizit auf
console.log(`Geprüftes Skript: ${trusted}`);
console.log(String(trusted) === trusted.toString());
console.log(typeof trusted.toString());// Wichtig · Fallstricke
- Der Trusted-Status geht verloren: Der zurückgegebene String ist kein
TrustedScriptmehr. Wird er unter aktiver CSPrequire-trusted-types-for 'script'an einen Sink wieeval()oderscript.textübergeben, wirft der Browser einenTypeError, es sei denn, einedefault-Richtlinie greift. Den String also nicht zurück in einen Sink leiten. - Sicherheit:
toString()prüft nichts. Wie sicher der Inhalt ist, hängt allein von der Logik increateScript()ab. Eine Richtlinie, die ihre Eingabe ungeprüft zurückgibt (input => input), hebelt den XSS-Schutz komplett aus. Nutzereingaben sollten nie ungefiltert increateScript()landen. Richtlinien-Namen lassen sich über die CSP-Direktivetrusted-typeseinschränken. - Browser-Kompatibilität: Trusted Types gibt es in Chromium-Browsern seit Version 83. Firefox und Safari unterstützen sie erst seit Kurzem. Für ältere Umgebungen gibt es einen Polyfill (
trusted-typesauf npm). Vor der Nutzung mitif (window.trustedTypes?.createPolicy)prüfen, ob die API vorhanden ist. - Die Methode steht nur in sicheren und unsicheren Fenster- und Worker-Kontexten zur Verfügung, in denen die Trusted Types API implementiert ist.
TrustedScript-Objekte lassen sich nicht direkt mit einem Konstruktor erzeugen, sondern nur über eine Richtlinie.