TrustedTypePolicy.name — Eigenschaft · JavaScript-Referenz

Signatur

TrustedTypePolicy.name

Beschreibung

Jede Trusted-Types-Richtlinie bekommt beim Anlegen mit trustedTypes.createPolicy(name, rules) einen Namen. Die Eigenschaft name gibt genau diesen String zurück. Der Wert ist schreibgeschützt und ändert sich über die Lebensdauer der Richtlinie nicht.

Wichtig ist der Name vor allem für die Content Security Policy: Mit der Direktive trusted-types legt man eine Positivliste fest, welche Richtliniennamen überhaupt erzeugt werden dürfen, z. B. Content-Security-Policy: trusted-types myPolicy dompurify. Will ein Skript eine Richtlinie mit einem anderen Namen anlegen, wirft der Browser einen TypeError.

Im Anwendungscode hilft name beim Protokollieren und Debuggen. So sieht man leicht, welche Richtlinie einen bestimmten TrustedHTML-, TrustedScript- oder TrustedScriptURL-Wert erzeugt hat, oder man prüft, ob eine übergebene Richtlinie die erwartete ist. Der Sonderfall "default" kennzeichnet die Standardrichtlinie. Der Browser ruft sie automatisch auf, wenn ein einfacher String an eine Senke wie innerHTML übergeben wird.

Rückgabewert

Typ

string

Beschreibung

Der Name der Richtlinie, so wie er beim Aufruf von trustedTypes.createPolicy() als erstes Argument übergeben wurde.

Beispiele

Namen einer Richtlinie auslesen

if (window.trustedTypes?.createPolicy) {
  const policy = trustedTypes.createPolicy('escapePolicy', {
    createHTML: (input) => input.replace(/</g, '&lt;').replace(/>/g, '&gt;')
  });

  console.log(policy.name);
}

escapePolicy

Richtlinie beim Protokollieren kennzeichnen

const createLoggingPolicy = (name, sanitize) =>
  trustedTypes.createPolicy(name, {
    createHTML: (input) => {
      const clean = sanitize(input);
      console.debug(`[${name}] HTML bereinigt (${input.length} → ${clean.length} Zeichen)`);
      return clean;
    }
  });

const policy = createLoggingPolicy('commentPolicy', (s) => s.replace(/<script[\s\S]*?<\/script>/gi, ''));
const html = policy.createHTML('<p>Hallo</p><script>alert(1)</script>');

document.querySelector('#kommentar').innerHTML = html;
console.log(`Verwendete Richtlinie: ${policy.name}`);

[commentPolicy] HTML bereinigt (37 → 12 Zeichen) Verwendete Richtlinie: commentPolicy

Standardrichtlinie erkennen

const defaultPolicy = trustedTypes.createPolicy('default', {
  createHTML: (input) => input.replace(/on\w+="[^"]*"/gi, '')
});

console.log(defaultPolicy.name === 'default');
console.log(trustedTypes.defaultPolicy?.name);

true default

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie policy.name = 'x' wird im nicht-strikten Modus stillschweigend ignoriert. Im strikten Modus löst sie einen TypeError aus.
CSP-Positivliste: Setzt die Seite trusted-types ohne 'allow-duplicates', darf jeder Name nur einmal vergeben werden. Ein zweites createPolicy() mit demselben Namen wirft einen TypeError.
Der Name "default" hat eine besondere Bedeutung. Diese Richtlinie wird bei jeder Zuweisung eines einfachen Strings an eine Senke implizit aufgerufen, deshalb sollte man sie sorgfältig umsetzen.
Der Name selbst ist kein Sicherheitsmerkmal. Er dient nur der Kennzeichnung und der CSP-Steuerung. Die Sicherheit hängt allein von den Regelfunktionen der Richtlinie ab.
Kompatibilität: Trusted Types gibt es in Chromium-Browsern seit Version 83. Safari und Firefox haben erst deutlich später nachgezogen. Deshalb vorher mit window.trustedTypes prüfen, ob die API vorhanden ist, oder ein Polyfill einsetzen. Die API steht nur in sicheren Kontexten und Window-/Worker-Umgebungen zur Verfügung, nicht in Node.js.

Siehe auch

HTMLTextAreaElement.name NotRestoredReasons.name BluetoothDevice.name DOMException.name DocumentType.name