TrustedTypePolicyFactory.isScript() — Methode · JavaScript-Referenz

Signatur

TrustedTypePolicyFactory.prototype.isScript(value)

Beschreibung

Die Methode isScript() gehört zu TrustedTypePolicyFactory, die über window.trustedTypes (bzw. self.trustedTypes in Workern) erreichbar ist. Sie liefert true, wenn der Wert ein gültiges TrustedScript-Objekt ist, das über policy.createScript() erzeugt wurde. Ein TrustedScript steht für Quelltext, den eine Richtlinie freigegeben hat und der deshalb an Senken wie eval(), new Function() oder HTMLScriptElement.text übergeben werden darf.

Die Prüfung ist fälschungssicher: Sie läuft über interne Slots des Objekts und nicht über instanceof oder den Prototyp. Ein normales Objekt mit passender toString()-Methode oder ein per Object.create(TrustedScript.prototype) nachgebautes Objekt wird daher als false erkannt.

Gedacht ist isScript() für Hilfsfunktionen und Bibliotheken, die sowohl rohe Zeichenketten als auch vertrauenswürdige Typen annehmen. Sie können damit entscheiden, ob ein Wert direkt weitergegeben werden kann oder erst durch eine Richtlinie laufen muss. Für HTML und Skript-URLs gibt es die passenden Gegenstücke isHTML() und isScriptURL().

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	any		Der zu prüfende Wert. Er kann jeden Typ haben; nur echte `TrustedScript`-Instanzen ergeben `true`.

Beispiele

Grundlegende Prüfung

if (window.trustedTypes) {
  const policy = trustedTypes.createPolicy('demo-script', {
    createScript: (input) => input
  });

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

  console.log(trustedTypes.isScript(trusted));            // echtes TrustedScript
  console.log(trustedTypes.isScript('console.log(1)'));   // einfacher String
  console.log(trustedTypes.isScript({ toString: () => 'x' })); // Fälschung
}

true false false

Hilfsfunktion, die nur freigegebenen Code ausführt

const scriptPolicy = window.trustedTypes?.createPolicy('app-scripts', {
  createScript: (code) => {
    // Beispielhafte Freigabe: nur Code aus einer festen Liste
    const erlaubt = ['initWidget()', 'trackPageView()'];
    if (!erlaubt.includes(code)) {
      throw new TypeError(`Nicht freigegebener Code: ${code}`);
    }
    return code;
  }
});

const runInline = (code) => {
  const script = document.createElement('script');
  // Bereits vertrauenswürdig? Dann direkt nutzen, sonst durch die Richtlinie leiten
  script.text = trustedTypes.isScript(code)
    ? code
    : scriptPolicy.createScript(code);
  document.head.append(script);
};

window.initWidget = () => console.log('Widget gestartet');
runInline('initWidget()');

Widget gestartet

Abgrenzung zu anderen Trusted Types

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

const html = policy.createHTML('<b>Hi</b>');
const script = policy.createScript('void 0');
const url = policy.createScriptURL('/app.js');

console.log(trustedTypes.isScript(html));   // TrustedHTML
console.log(trustedTypes.isScript(script)); // TrustedScript
console.log(trustedTypes.isScript(url));    // TrustedScriptURL

false true false

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser unterstützen die Trusted Types API seit Version 83. Safari (ab 26) und Firefox (ab 142) sind erst spät dazugekommen. Prüfen Sie deshalb vorher mit if (window.trustedTypes), ob die API vorhanden ist, oder setzen Sie ein Polyfill ein (z. B. trusted-types von W3C/Google).
Nur ein Typtest, keine Inhaltsprüfung: isScript() prüft nicht, ob der Code harmlos ist. Wie sicher das Ergebnis ist, hängt allein von der createScript-Funktion der Richtlinie ab. Eine Richtlinie, die ihre Eingabe ungeprüft zurückgibt ((s) => s), bietet keinen Schutz vor XSS.
Kein Ersatz für instanceof-Tricks: Mit isScript() lassen sich Objekte nicht fälschen. value instanceof TrustedScript kann dagegen durch manipulierte Prototypen getäuscht werden.
CSP: Die Durchsetzung greift erst mit dem Header Content-Security-Policy: require-trusted-types-for 'script'. Ohne diesen Header funktioniert isScript() zwar, die Senken akzeptieren aber weiterhin rohe Zeichenketten.
Für eval() mit TrustedScript braucht die CSP außerdem 'unsafe-eval' oder 'trusted-types-eval'.

Siehe auch

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