TrustedScript.toJSON() — Methode · JavaScript-Referenz

Signatur

TrustedScript.prototype.toJSON()

Beschreibung

Die Methode toJSON() der Schnittstelle TrustedScript gibt eine JSON-taugliche Darstellung des Objekts zurück. Das ist einfach der Skript-Quelltext, der beim Erzeugen über die createScript()-Funktion einer TrustedTypePolicy abgelegt wurde. Das Ergebnis ist ein ganz normaler string.

Normalerweise ruft man toJSON() nicht selbst auf. JSON.stringify() ruft die Methode automatisch auf, sobald ein TrustedScript-Objekt in einer zu serialisierenden Struktur vorkommt. Ohne diese Methode würde das Objekt als leeres Objekt {} serialisiert, weil es keine eigenen aufzählbaren Eigenschaften hat.

Brauchbar ist das vor allem beim Protokollieren, beim Debuggen und beim Übertragen von Konfigurationen, die geprüfte Skript-Schnipsel enthalten, zum Beispiel an einen Worker oder einen Server. Wichtig: Das Ergebnis ist kein TrustedScript mehr, sondern nur noch ein String. Die Schutzwirkung der Trusted Types geht bei der Serialisierung also verloren.

Rückgabewert

Typ

string

Beschreibung

Der gespeicherte Skript-Quelltext. Er ist identisch mit dem Ergebnis von TrustedScript.prototype.toString().

Beispiele

toJSON() direkt aufrufen

// Policy anlegen (setzt Trusted-Types-Unterstützung voraus)
const policy = trustedTypes.createPolicy('script-policy', {
  createScript: (input) => input // hier sollte eine echte Prüfung stehen
});

const trusted = policy.createScript('console.log("Hallo");');
console.log(trusted.toJSON());
console.log(typeof trusted.toJSON());

console.log("Hallo"); string

Automatischer Aufruf durch JSON.stringify()

const policy = trustedTypes.createPolicy('config-policy', {
  createScript: (s) => s
});

const config = {
  name: 'Analytics-Init',
  script: policy.createScript('initTracking({ anonymize: true });')
};

// JSON.stringify ruft TrustedScript.toJSON() selbst auf
console.log(JSON.stringify(config));

{"name":"Analytics-Init","script":"initTracking({ anonymize: true });"}

Nach der Deserialisierung wieder zu TrustedScript machen

const policy = trustedTypes.createPolicy('roundtrip', {
  createScript: (s) => {
    if (/\beval\b/.test(s)) throw new TypeError('Unzulässiges Skript');
    return s;
  }
});

const original = policy.createScript('document.title = "Bereit";');
const json = JSON.stringify({ code: original });

const { code } = JSON.parse(json);
console.log(trustedTypes.isScript(code));        // nur ein String

const restored = policy.createScript(code);      // erneut prüfen
console.log(trustedTypes.isScript(restored));

false true

// Wichtig · Fallstricke

Die Typsicherheit geht verloren: Das Ergebnis ist ein gewöhnlicher String. Wenn die Seite Trusted Types per CSP erzwingt (require-trusted-types-for 'script'), wird dieser String von Senken wie eval(), new Function() oder HTMLScriptElement.text abgelehnt. Nach dem Deserialisieren muss er also erneut über eine Policy laufen.
Sicherheit: Serialisiertes JSON mit Skript-Code kann unterwegs verändert werden, etwa im Speicher, beim Transport oder im localStorage. Solche Daten nie ungeprüft wieder in eine durchlässige Policy geben, sonst droht XSS.
Kompatibilität: Trusted Types werden in Chromium-Browsern seit Version 83 unterstützt. In Firefox (ab 142) und Safari (ab 26) kamen sie erst spät hinzu. Die Unterstützung vor der Nutzung mit if (window.trustedTypes) prüfen oder ein Polyfill einsetzen.
toJSON() und toString() liefern denselben Wert.

Siehe auch

JSON.stringify() LayoutShift.toJSON() TrustedScript.toString() TrustedScriptURL.toJSON() TrustedHTML.toJSON()