TrustedTypePolicyFactory.getAttributeType() — Methode · JavaScript-Referenz

Signatur

TrustedTypePolicyFactory.prototype.getAttributeType(tagName, attribute, elementNs, attrNs)

Beschreibung

Die Methode getAttributeType() der Schnittstelle TrustedTypePolicyFactory wird über das globale Objekt trustedTypes (window.trustedTypes bzw. self.trustedTypes in Workern) aufgerufen. Sie meldet, ob ein bestimmtes Attribut eines bestimmten Elements eine sogenannte Injection Sink ist. Ist die CSP-Direktive require-trusted-types-for 'script' aktiv, muss man solchen Attributen einen passenden Trusted Type zuweisen.

Als Rückgabewert kommt der Name des geforderten Typs als String, zum Beispiel "TrustedScriptURL" für <script src>, "TrustedHTML" für <iframe srcdoc> oder "TrustedScript" für Event-Handler-Attribute wie onclick. Braucht das Attribut keinen Trusted Type, liefert die Methode null.

Nützlich ist das vor allem für Bibliotheken, Template-Engines und Sanitizer, die Attribute generisch per setAttribute() setzen. Solcher Code kann vorab prüfen, ob ein Wert erst durch eine Policy laufen muss (policy.createHTML(), createScript() oder createScriptURL()), statt eine Liste gefährlicher Attribute selbst fest einzuprogrammieren.

Parameter

Name	Typ	Default	Beschreibung
$tagName Pflicht	string		Name des Elements, z. B. `"script"` oder `"iframe"`. Groß- und Kleinschreibung spielt keine Rolle, der Name wird intern in Kleinbuchstaben umgewandelt.
$attribute Pflicht	string		Name des Attributs, z. B. `"src"`, `"srcdoc"` oder `"onclick"`. Auch hier wird in Kleinbuchstaben umgewandelt.
$elementNs	string	"http://www.w3.org/1999/xhtml"	Namespace des Elements. Fehlt der Wert oder ist er leer, gilt der HTML-Namespace. Für SVG gibt man `"http://www.w3.org/2000/svg"` an.
$attrNs	string \| null	null	Namespace des Attributs, z. B. `"http://www.w3.org/1999/xlink"` für `xlink:href`. Ohne Angabe: kein Namespace.

Rückgabewert

Typ

string | null

Beschreibung

"TrustedHTML", "TrustedScript" oder "TrustedScriptURL", wenn das Attribut einen Trusted Type verlangt, sonst null.

Beispiele

Typische Attribute abfragen

// Funktionserkennung: trustedTypes gibt es nicht in jedem Browser
if (window.trustedTypes) {
  console.log(trustedTypes.getAttributeType('script', 'src'));
  console.log(trustedTypes.getAttributeType('iframe', 'srcdoc'));
  console.log(trustedTypes.getAttributeType('div', 'onclick'));
  console.log(trustedTypes.getAttributeType('img', 'src'));
}

TrustedScriptURL TrustedHTML TrustedScript null

SVG-Elemente mit Namespaces

const SVG_NS = 'http://www.w3.org/2000/svg';
const XLINK_NS = 'http://www.w3.org/1999/xlink';

console.log(trustedTypes.getAttributeType('script', 'href', SVG_NS));
console.log(trustedTypes.getAttributeType('script', 'href', SVG_NS, XLINK_NS));
console.log(trustedTypes.getAttributeType('rect', 'width', SVG_NS));

TrustedScriptURL TrustedScriptURL null

Generisches, Trusted-Types-sicheres setAttribute

// Die Policy prüft bzw. bereinigt Werte, bevor sie in eine Sink gelangen
const policy = trustedTypes.createPolicy('app-attrs', {
  createHTML: (s) => s.replace(/</g, '&lt;'),
  createScript: () => { throw new TypeError('Inline-Skripte sind nicht erlaubt'); },
  createScriptURL: (url) => {
    const u = new URL(url, location.href);
    if (u.origin !== location.origin) throw new TypeError(`Fremde URL: ${url}`);
    return u.href;
  }
});

const creators = {
  TrustedHTML: (v) => policy.createHTML(v),
  TrustedScript: (v) => policy.createScript(v),
  TrustedScriptURL: (v) => policy.createScriptURL(v)
};

const safeSetAttribute = (el, name, value) => {
  const type = trustedTypes.getAttributeType(el.localName, name, el.namespaceURI);
  el.setAttribute(name, type ? creators[type](value) : value);
};

const script = document.createElement('script');
safeSetAttribute(script, 'src', '/js/widget.js');
safeSetAttribute(script, 'async', '');
console.log(script.src);

https://example.com/js/widget.js

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser (Chrome, Edge, Opera) unterstützen die Trusted Types API seit Version 83. Firefox und Safari haben sie erst 2025 eingeführt. Deshalb vorher mit if (window.trustedTypes) prüfen oder ein Polyfill verwenden (z. B. trusted-types von W3C/Google).
Die Methode sagt nur aus, welcher Typ nach der Spezifikation verlangt wird. Ob tatsächlich durchgesetzt wird, hängt von der CSP ab (require-trusted-types-for 'script'). Ohne diese Direktive werden auch einfache Strings angenommen.
Alle Event-Handler-Attribute (on*) liefern "TrustedScript", und zwar bei jedem Element.
Bei SVG und anderen Nicht-HTML-Elementen muss man den Namespace angeben. Sonst wird das Element als HTML-Element ausgewertet, und das Ergebnis kann falsch sein.
Zu Eigenschaften wie innerHTML gibt diese Methode keine Auskunft, dafür gibt es getPropertyType().
Sicherheit: Eine Policy, die Werte einfach ungeprüft durchreicht, hebelt den Schutz vor XSS aus. Policies sollten Werte wirklich prüfen oder bereinigen.

Siehe auch

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