Trusted Types

Draft Community Group Report,

This version:
https://wicg.github.io/trusted-types/dist/spec/
Issue Tracking:
GitHub
Inline In Spec
Editors:
(Google LLC)
(Google LLC)

Abstract

An API that allows applications to lock down DOM XSS injection sinks to only accept non-spoofable, typed values in place of strings.

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1. Introduction

This section is not normative.

DOM-Based Cross-Site Scripting (DOM XSS) occurs when a web application takes a string value from an attacker-controlled source (e.g. the document URL parameter, or postMessage channel) and passes that value to one of the injection sinks, that eventually causes execution of the script payload controlled by the attacker.

This vulnerability type is prevalent in the web applications for two reasons. For one, it’s easy to introduce - there are over 60 different injection sinks (e.g. Element.innerHTML, or Location.href setters). A lot of those sinks are widely used, and are often passed an attacker-controlled value without the developer realizing it. Secondly, DOM XSS is difficult to prevent. Due to the dynamic nature of JavaScript it’s difficult to ascertain that this vulnerability is not present in a given program - as such, DOM XSS is often missed during manual code reviews, and automated code analysis. As an example, foo[bar] = aString is a statement that potentially introduces DOM XSS.

This document defines Trusted Types - an API that allows applications to lock down DOM XSS injection sinks to only accept non-spoofable, typed values in place of strings. These values can in turn only be created from application-defined policies, allowing the authors to define rules guarding writing values to the DOM, and reducing the DOM XSS attack surface to small, isolated parts of the web application codebase, which are substantially easier to safeguard, monitor and review.

1.1. Goals

1.2. Non-goals

1.3. Use cases

2. Framework

2.1. Injection sinks

This section is not normative.

A DOM XSS injection sink is a function that evaluates an input string value in a way that could result in XSS if that value is untrusted.

Examples of injection sinks include:

An application is vulnerable to DOM XSS if it permits a flow of data from an attacker-controlled source and permits that data to reach an injection sink without appropriate validation, sanitization or escaping.

It’s difficult to determine if DOM XSS is present by analyzing the invocations of injection sinks, as the strings do not carry the information about the provenance of their value. To allow the authors to control values reaching sensitive DOM and JavaScript functions, we introduce Trusted Types.

Note: The exact list of injection sinks covered by this document is defined in § 4 Integrations.

2.2. Trusted Types

We introduce the following list of Trusted Types indicating that a given value is trusted by the authors to be used with an injection sink in a certain context.

Note: Trusted in this context signifies the fact that the application author is confident that a given value can be safely used with an injection sink - she trusts it does not introduce a vulnerability. That does not imply that the value is indeed safe.

Note: This allows the authors to specify the intention when creating a given value, and the user agents to introduce checks based on the type of such value to preserve the authors' intent. For example, if authors intend a value to be used as an HTML snippet, an attempt to load a script from that value would fail.

Note: All Trusted Types wrap over an immutable string, specified when the objects are created. These objects are unforgable in a sense that there is no JavaScript-exposed way to replace the inner string value of a given object - it’s stored in an internal slot with no setter exposed.

Note: All Trusted Types stringifiers return the inner string value. This makes it easy to incrementally migrate the application code into using Trusted Types in place of DOM strings (it’s possible to start producing types in parts of the application, while still using and accepting strings in other parts of the codebase). In that sense, Trusted Types are backwards-compatible with the regular DOM APIs.

2.2.1. TrustedHTML

The TrustedHTML interface represents a string that a developer can confidently insert into an injection sink that will render it as HTML. These objects are immutable wrappers around a string, constructed via a TrustedTypePolicy's createHTML method.

[Exposed=Window]
interface TrustedHTML {
  stringifier;
};

TrustedHTML objects have a [[Data]] internal slot which holds a DOMString. The slot’s value is set when the object is created, and will never change during its lifetime.

To stringify a TrustedHTML object, return the DOMString from its [[Data]] internal slot.

2.2.2. TrustedScript

The TrustedScript interface represents a string with an uncompiled script body that a developer can confidently pass into an injection sink that might lead to executing that script. These objects are immutable wrappers around a string, constructed via a TrustedTypePolicy's createScript method.

[Exposed=Window]
interface TrustedScript {
  stringifier;
};

TrustedScript objects have a [[Data]] internal slot which holds a DOMString. The slot’s value is set when the object is created, and will never change during its lifetime.

To stringify a TrustedScript object, return the DOMString from its [[Data]] internal slot.

2.2.3. TrustedScriptURL

The TrustedScriptURL interface represents a string that a developer can confidently pass into an injection sink that will parse it as a URL of an external script resource. These objects are immutable wrappers around a string, constructed via a TrustedTypePolicy's createScriptURL method.

[Exposed=Window]
interface TrustedScriptURL {
  stringifier;
};

TrustedScriptURL objects have a [[Data]] internal slot which holds a USVString. The slot’s value is set when the object is created, and will never change during its lifetime.

To stringify a TrustedScriptURL object, return the USVString from its [[Data]] internal slot.

2.2.4. TrustedURL

The TrustedURL interface represents a string that a developer can confidently pass into an injection sink that may cause navigation to that URL string. These objects are immutable wrappers around a string, constructed via a TrustedTypePolicy's createURL method.

[Exposed=Window]
interface TrustedURL {
  stringifier;
};

TrustedURL objects have a [[Data]] internal slot which holds a USVString. The slot’s value is set when the object is created, and will never change during its lifetime.

To stringify a TrustedURL object, return the USVString from its [[Data]] internal slot.

2.3. Policies

Trusted Types can only be created via user-defined and immutable policies that define rules for converting a string into a given Trusted Type object. Policies allows the authors to specify custom, programmatic rules that Trusted Types must adhere to.

Authors may define a policy that will sanitize an HTML string, allowing only a subset of tags and attributes that are known not to cause JavaScript execution. Any TrustedHTML object created through this policy can then be safely used in the application, and e.g. passed to innerHTML setter - even if the input value was controlled by the attacker, the policy rules neutralized it to adhere to policy-specific contract.
const sanitizingPolicy = trustedTypes.createPolicy('sanitize-html', {
  createHTML: (input) => myTrustedSanitizer(input, { superSafe: 'ok'}),
});

myDiv.innerHTML = sanitizingPolicy.createHTML(untrustedValue);

Note: Trusted Type objects wrap values that are explicitly trusted by the author. As such, creating a Trusted Type object instance becomes a de facto DOM XSS injection sink, and hence code that creates Trusted Type instances is security-critical. To allow for strict control over Trusted Type object creation we don’t expose the constructors of those directly, but require policy usage.

Multiple policies can be created in a given Realm, allowing the applications to define different rules for different parts of the codebase.

Library initialized with a policy allowing it to load additional scripts from a given host.
const cdnScriptsPolicy = trustedTypes.createPolicy('cdn-scripts', {
  createScriptURL(url) {
    const parsed = new URL(url, document.baseURI);
    if (parsed.origin == 'https://mycdn.example') {
      return url;
    }
    throw new TypeError('invalid URL');
  },
});

myLibrary.init({policy: cdnScriptsPolicy});

Note: As Trusted Type objects can only be created via policies, if enforcement is enabled, only the policy code can introduce a DOM XSS, and hence call-sites of the policies' create* functions are the only security-sensitive code in the entire program. Only this typically small subset of the entire code base needs to be security-reviewed for DOM XSS - there’s no need to monitor or review the injection sinks themselves, as User Agents enforce that those sinks will only accept Trusted Type objects, and these in turn can only be created via policies.

The createPolicy function returns a policy object which create* functions will create Trusted Type objects after applying the policy rules.

Note: While it’s safe to freely use a policy that sanitizes its input anywhere in the application, there might be a need to create lax policies to be used internally, and only to be called with author-controlled input. For example, a client-side HTML templating library, an HTML sanitizer library, or a JS asynchronous code plugin loading subsystem each will likely need full control over HTML or URLs. The API design facilitates that - each policy may only be used if the callsite can obtain a reference to the policy (a return value from createPolicy()). As such, policy references can be treated as capabilities, access to which can be controlled using JavaScript techniques (e.g. via closures, internal function variables, or modules).

Unsafe no-op policy reachable only from within a single code block to ascertain that it’s called only with no attacker-controlled values.
(function renderFootnote() {
  const unsafePolicy = trustedTypes.createPolicy('html', {
    createHTML: input => input,
  });
  const footnote = await fetch('/footnote.html').then(r => r.text());
  footNote.innerHTML = unsafePolicy.createHTML(footnote);
})();

2.3.1. TrustedTypePolicyFactory

TrustedTypePolicyFactory creates policies and verifies that Trusted Type object instances were created via one of the policies.

Note: This factory object is exposed to JavaScript through window.trustedTypes reference - see § 4.1.1 Extensions to the Window interface.

[Exposed=Window] interface TrustedTypePolicyFactory {
    [Unforgeable] TrustedTypePolicy createPolicy(
        DOMString policyName, optional TrustedTypePolicyOptions policyOptions);
    [Unforgeable] sequence<DOMString> getPolicyNames();
    [Unforgeable] boolean isHTML(any value);
    [Unforgeable] boolean isScript(any value);
    [Unforgeable] boolean isScriptURL(any value);
    [Unforgeable] boolean isURL(any value);
    [Unforgeable] readonly attribute TrustedHTML emptyHTML;
    string? getAttributeType(
        DOMString localName, DOMString attribute,
        optional DOMString elementNs = "", optional DOMString attributeNs = "");
    string? getPropertyType(
        DOMString localName, DOMString property,
        optional DOMString elementNs = "");
    readonly attribute TrustedTypePolicy? defaultPolicy;
};

Internal slot [[DefaultPolicy]] may contain a TrustedTypePolicy object, and is initially empty.

Internal slot [[CreatedPolicyNames]] is an ordered set of strings, initially empty.

createPolicy(policyName, policyOptions)

Creates a policy object that will implement the rules passed in the TrustedTypePolicyOptions policyOptions object. The allowed policy names may be restricted by Content Security Policy. If the policy name is not on the whitelist defined in the trusted-types CSP directive, the policy creation fails with a TypeError. Also, if unique policy names are enforced (i.e. trusted-types * is not used), and createPolicy is called more than once with any given policyName, policy creation fails with a TypeError.

// HTTP Response header: Content-Security-Policy: trusted-types foo
trustedTypes.createPolicy("foo", {}); // ok.
trustedTypes.createPolicy("bar", {}); // throws - name not on the whitelist.
trustedTypes.createPolicy("foo", {}); // throws - duplicate name.

Returns the result of executing a Create a Trusted Type Policy algorithm, with the following arguments:

factory
context object
policyName
policyName
options
policyOptions
global
context object's relevant global object
const myPolicy = trustedTypes.createPolicy('myPolicy', {
  // This security-critical code needs a security review;
  // a flaw in this code could cause DOM XSS.
  createHTML(input) { return aSanitizer.sanitize(input) },
  createScriptURL(input) {
    const u = new URL(dirty, document.baseURI);
    if (APPLICATION_CONFIG.scriptOrigins.includes(u.origin)) {
      return u.href;
    }
    throw new Error('Cannot load scripts from this origin');
  },
});

document.querySelector("#foo").innerHTML = myPolicy.createHTML(aValue);
scriptElement.src = myPolicy.createScriptURL(
    'https://scripts.myapp.example/script.js');
getPolicyNames()

This function returns the names of all the policies that were already created.

Returns a new list, comprising of all entries of the [[CreatedPolicyNames]] slot.

trustedTypes.createPolicy('foo', ...);
trustedTypes.createPolicy('bar', ...);
trustedTypes.getPolicyNames(); // ['foo', 'bar']
isHTML(value)

Returns true if value is an instance of TrustedHTML and has its [[Data]] internal slot set, false otherwise.

Note: is* functions are used to check if a given object is truly a legitimate Trusted Type object (i.e. it was created via one of the configured policies). This is to be able to detect a forgery of the objects via e.g. Object.create or prototype chains manipulation.

const html = policy.createHTML('<div>');
trustedTypes.isHTML(html); // true

const fake = Object.create(TrustedHTML.prototype);
trustedTypes.isHTML(fake); // false

trustedTypes.isHTML("<div>plain string</div>"); // false
isScript(value)

Returns true if value is an instance of TrustedScript and has its [[Data]] internal slot set, false otherwise.

isScriptURL(value)

Returns true if value is an instance of TrustedScriptURL and has its [[Data]] internal slot set, false otherwise.

isURL(value)

Returns true if value is an instance of TrustedURL and has its [[Data]] internal slot set, false otherwise.

getPropertyType(localName, attribute, elementNs)

Allows the authors to check if a Trusted Type is required for a given Element's property (IDL attribute).

This function returns the result of the following algorithm:

  1. Set localName to localName in ASCII lowercase.

  2. If elementNs is an empty string, set elementNs to HTML namespace.

  3. Let interface be the element interface for localName and elementNs.

  4. If interface has an IDL attribute member which identifier is attribute, and TrustedTypes IDL extended attribute appears on that attribute, return stringified TrustedTypes's identifier and abort futher steps.

    Note: This also takes into account all members of interface mixins that interface includes.

  5. Return undefined.

trustedTypes.getPropertyType('div', 'innerHTML'); // "TrustedHTML"
trustedTypes.getPropertyType('form', 'formAction'); // "TrustedURL"
trustedTypes.getPropertyType('foo', 'bar'); // undefined
getAtributeType(localName, attribute, elementNs, attributeNs)

Allows the authors to check if, (and if so, which) Trusted Type is required for a given Element's content attribute, such that later on the call to Element.setAttribute passes the correct argument type.

This function returns the result of the following algorithm:

  1. Set localName to localName in ASCII lowercase.

  2. Set attribute to attribute in ASCII lowercase.

  3. If elementNs is an empty string, set elementNs to HTML namespace.

  4. If attributeNs is an empty string, set attributeNs to elementNs’s value.

  5. Let interface be the element interface for localName and elementNs.

  6. If interface does not have an IDL attribute that reflects a content attribute with localName local name and attributeNs namespace, return undefined and abort further steps. Otherwise, let idlAttribute be that IDL attribute.

  7. If TrustedTypes IDL extended attribute appears on idlAttribute, return stringified TrustedTypes's identifier and abort futher steps.

  8. Return undefined.

trustedTypes.getPropertyType('a', 'HREF'); // "TrustedURL"
trustedTypes.getPropertyType('form', 'formaction'); // "TrustedURL"
trustedTypes.getPropertyType('foo', 'bar'); // undefined
emptyHTML, of type TrustedHTML, readonly

is a TrustedHTML object with its [[Data]] internal slot value set to an empty string.

anElement.innerHTML = trustedTypes.emptyHTML; // no need to create a policy
defaultPolicy, of type TrustedTypePolicy, readonly, nullable

Returns the value of [[DefaultPolicy]] internal slot, or null if the slot is empty.

trustedTypes.defaultPolicy === null;  // true
const dp = trustedTypes.createPolicy('default', {});
trustedTypes.defaultPolicy === dp;  // true

2.3.2. TrustedTypePolicy

Policy objects implement a TrustedTypePolicy interface and define a group of functions creating Trusted Type objects. Each of the create* functions converts a string value to a given Trusted Type variant, or throws a TypeError if a conversion of a given value is disallowed.

[Exposed=Window]
interface TrustedTypePolicy {
  [Unforgeable] readonly attribute DOMString name;
  [Unforgeable] TrustedHTML createHTML(DOMString input, any... arguments);
  [Unforgeable] TrustedScript createScript(DOMString input, any... arguments);
  [Unforgeable] TrustedScriptURL createScriptURL(DOMString input, any... arguments);
  [Unforgeable] TrustedURL createURL(DOMString input, any... arguments);
};

Each policy has a name.

Each TrustedTypePolicy object has an [[options]] internal slot, holding the TrustedTypePolicyOptions object describing the actual behavior of the policy.

createHTML(input, ...arguments)

Returns the result of executing the Create a Trusted Type algorithm, with the following arguments:

policy
context object
trustedTypeName
"TrustedHTML"
value
input
arguments
arguments
createScript(input, ...arguments)

Returns the result of executing the Create a Trusted Type algorithm, with the following arguments:

policy
context object
trustedTypeName
"TrustedScript"
value
input
arguments
arguments
createScriptURL(input, ...arguments)

Returns the result of executing the Create a Trusted Type algorithm, with the following arguments:

policy
context object
trustedTypeName
"TrustedScriptURL"
value
input
arguments
arguments
createURL(input, ...arguments)

Returns the result of executing the Create a Trusted Type algorithm, with the following arguments:

policy
context object
trustedTypeName
"TrustedURL"
value
input
arguments
arguments

2.3.3. TrustedTypePolicyOptions

This dictionary holds author-defined functions for converting string values into trusted values. These functions do not create Trusted Type object instances directly - this behavior is provided by TrustedTypePolicy.

dictionary TrustedTypePolicyOptions {
   CreateHTMLCallback? createHTML;
   CreateScriptCallback? createScript;
   CreateURLCallback? createURL;
   CreateScriptURLCallback? createScriptURL;
};
callback CreateHTMLCallback = DOMString (DOMString input);
callback CreateScriptCallback = DOMString (DOMString input);
callback CreateURLCallback = USVString (DOMString input);
callback CreateScriptURLCallback = USVString (DOMString input);

2.3.4. Default policy

This section is not normative.

One of the policies, the policy with a name "default", is special; When an injection sink is passed a string (instead of a Trusted Type object), this policy will be implicitly called by the user agent with the string value as the first argument, and the sink name as a second argument.

This allows the application to define a fallback behavior to use instead of causing a violation. The intention is to allow the applications to recover from an unexpected data flow, and sanitize the potentially attacker-controlled string "as a last resort", or throw if a safe value cannot be created.

If the default policy doesn’t exist, of if it throws, it will cause a CSP violation, and a TypeError will be thrown.

Note: This optional behavior allows for introducing Trusted Type enforcement to applications that are still using legacy code that uses injection sinks. Needless to say, this policy should necessarily be defined with very strict rules not to introduce a DOM XSS vulnerability in unknown parts of the application. In an extreme case, a lax, no-op default policy could bring the application DOM XSS security posture back to the pre-Trusted Types level. If possible, authors should resort to a default policy in a transitional period only, use it to detect and rewrite their dependencies that use injection sinks unsafely and eventually phase out the usage of the default policy entirely.

Note: See § 3.4 Get Trusted Type compliant string for details on how the default policy is applied.

// Content-Security-Policy: trusted-types default

trustedTypes.createPolicy('default', {
  createScriptURL: (s, sink) => {
    console.log("Please refactor.");
    return s + "?default-policy-used&sink=" + encodeURIComponent(sink);
  }
});

aScriptElement.src = "https://cdn.example/script.js";
// Please refactor.
console.log(aScriptElement.src);
// https://cdn.example/script.js?default-policy-used&sink=script.src

2.4. Enforcement

Note: Enforcement is the process of checking that a value has an appropriate type before it reaches an injection sink.

The JavaScript API that allows authors to create policies and Trusted Types objects from them is always available (via trustedTypes). Since injection sinks stringify their security sensitive arguments, and Trusted Type objects stringify to their inner string values, this allows the authors to use Trusted Types in place of strings.

To prevent DOM XSS, on top of the JavaScript code using the Trusted Types, the user agent needs to enforce them i.e. assert that the injection sinks are never called with string values, and Trusted Type values are used instead. This section describes how authors may control this enforcing behavior.

2.4.1. Content Security Policy

Applications may control Trusted Type enforcement via configuring a Content Security Policy. This document defines a new trusted-types Content Security Policy directive that corresponds to Trusted Types rules.

Note: Using CSP mechanisms allows the authors to prepare their application for enforcing Trusted Types via using the Content-Security-Report-Only HTTP Response header.

Note: Most of the enforcement rules are defined as modifications of the algorithms in other specifiactions, see § 4 Integrations.

2.4.2. TrustedTypes extended attribute

Note: This section describes the implementation details of the Trusted Types mechanism. IDL extended attributes are not exposed to the JavasScript code.

To annotate the injection sink functions that require Trusted Types, we introduce [TrustedTypes] IDL extended attribute. Its presence indicates that the relevant construct is to be supplemented with additional Trusted Types enforcement logic.

The TrustedTypes extended attribute takes an identifier as an argument. The only valid values for the identifier are TrustedHTML, TrustedScript, TrustedScriptURL or TrustedURL. This extended attribute must not appear on anything other than an attribute or an operation argument. Additionally, it must not appear on read only attributes.

When the extended attribute appears on an attribute, the setter for that attribute must run the following steps in place of the ones specified in its description:

  1. If context object's relevant global object has a trusted type policy factory:

    Update when workers have TT.

    1. If the context object is an Element, let objectName be the context object's local name; Otherwise, let objectName be the context object's constructor name.

    2. Set sink to the result of concatenating the list « objectName, attribute identifier. » with "." as separator.

      For example, the following annotation and JavaScript code:
      partial interface mixin HTMLHyperlinkElementUtils {
        [CEReactions, TrustedTypes=TrustedURL] stringifier attribute URLString href;
      };
      
      document.createElement('a').href = foo;
      document.createElement('a').setAttribute('HREF', foo);
      

      causes the sink value to be "a.href".

    3. Set value to the result of running the Get Trusted Type compliant string algorithm, passing the following arguments:

    4. If an exception was thrown, rethrow exception and abort further steps.

  2. Run the originally specified steps for this construct, using value as a new value to set.

Note: If the IDL attribute reflects a content attribute, identical steps should be performed when that content attribute is modified by JavaScript code e.g. via Element.setAttribute() function.

When the extended attribute appears on an operation argument, before its operation is invoked, run the following steps:

  1. If context object's relevant global object has a trusted type policy factory:

    Update when workers have TT.

    1. If the context object is an Element, let objectName be the context object's local name; Otherwise, let objectName be the context object's constructor name.

    2. Set sink to the result of concatenating the list « objectName, operation identifier. » with "." as separator.

      For example, the following annotation and JavaScript code:
      partial interface Element {
        void insertAdjacentHTML(DOMString position, [TrustedTypes=TrustedHTML] HTMLString text);
      };
      
      document.createElement('a').insertAdjacentHTML('beforebegin', foo);
      

      causes the sink value to be "a.insertAdjacentHTML".

    3. Set the new argument value to the result of running the Get Trusted Type compliant string algorithm, passing the following arguments:

    4. If an exception was thrown, rethrow exception and abort further steps.

  2. Invoke the originally specified steps for the operation.

3. Algorithms

3.1. Create a Trusted Type Policy

To create a TrustedTypePolicy, given a TrustedTypePolicyFactory (factory), a string (policyName), TrustedTypePolicyOptions dictionary (options), and a global object (global) run these steps:

  1. Let allowedByCSP be the result of executing Should Trusted Type policy creation be blocked by Content Security Policy? algorithm with global, policyName and factory’s [[CreatedPolicyNames]] slot value.

  2. If allowedByCSP is "Blocked", throw a TypeError and abort further steps.

  3. Let policy be a new TrustedTypePolicy object.

  4. Set policy’s name property value to policyName.

  5. Let policyOptions be a new TrustedTypePolicyOptions object.

  6. Set policyOptions createHTML property to option’s createHTML property value.

  7. Set policyOptions createScript property to option’s createScript property value.

  8. Set policyOptions createScriptURL property to option’s createScriptURL property value.

  9. Set policyOptions createURL property to option’s createURL property value.

  10. Set policy’s [[options]] internal slot value to policyOptions.

  11. If the policyName is default, set the factory’s [[DefaultPolicy]] slot value to policy.

  12. Append policyName to factory’s [[CreatedPolicyNames]].

  13. Return policy.

3.2. Get default policy

To get the default policy for a TrustedTypePolicyFactory (factory), execute the following steps:
  1. Return the value of factory’s [[DefaultPolicy]] slot (null if the slot is empty).

3.3. Create a Trusted Type

Given a TrustedTypePolicy policy, a type name trustedTypeName, a string value and a list arguments, execute the following steps:

  1. Let functionName be a function name for the given trustedTypeName, based on the following table:

    Function name Trusted Type name
    "createHTML" "TrustedHTML"
    "createScript" "TrustedScript"
    "createScriptURL" "TrustedScriptURL"
    "createURL" "TrustedURL"
  2. Let options be the value of policy’s [[options]] slot.

  3. Let function be the value of the property in options named functionName.

  4. If function is null, throw a TypeError.

  5. Let policyValue be the result of invoking function with value as a first argument, items of arguments as subsequent arguments, and callback **this** value set to null.

  6. If policyValue is an error, return policyValue and abort the following steps.

  7. Let dataString be the result of stringifying policyValue.

  8. Let trustedObject be a new instance of an interface with a type name trustedTypeName, with its [[Data]] internal slot value set to dataString.

  9. Return trustedObject.

3.4. Get Trusted Type compliant string

This algorithm will return a string that can be assigned to a DOM injection sink, optionally unwrapping it from a matching Trusted Type. It will ensure that the Trusted Type enforcement rules were respected.

Given a TrustedType type (expectedType), a global object (global), TrustedType or a string (input), and a string (sink), run these steps:

  1. Assert: global is a Window.

    Synchronize when TT are added to workers (perhaps use "has a CSP list"?)

  2. Let cspList be the global’s CSP list.

  3. If cspList does not contain a policy which directive set containing a directive with a name "trusted-types", return stringified input and abort these steps.

  4. If input has type expectedType, return stringified input and abort these steps.

  5. Otherwise, execute the following steps:

    1. Let defaultPolicy be the result of executing Get default policy algorithm on global’s trusted type policy factory.

    2. If defaultPolicy is null, abort these steps and resume below.

    3. Let convertedInput be the result of executing Create a Trusted Type algorithm, with the following arguments:

      • defaultPolicy as policy

      • input as value

      • expectedType’s type name as trustedTypeName

      • « sink » as arguments

    4. If convertedInput is an error, abort the following steps.

    5. If convertedInput has type expectedType, then return stringified convertedInput and abort the following steps.

    6. Set input to convertedInput’s value.

  6. Let disposition be the result of executing Should sink type mismatch violation be blocked by Content Security Policy? algorithm, passing global, input as source, and sink.

  7. If disposition is “Allowed”, then return stringified input and abort these steps.

  8. Throw a TypeError.

4. Integrations

typedef (DOMString or TrustedHTML) HTMLString;
typedef (DOMString or TrustedScript) ScriptString;
typedef (USVString or TrustedScriptURL) ScriptURLString;
typedef (USVString or TrustedURL) URLString;
typedef (TrustedHTML or TrustedScript or TrustedScriptURL or TrustedURL) TrustedType;

typedef (([TreatNullAs=EmptyString] DOMString) or TrustedHTML) HTMLStringDefaultsEmpty;

Note: HTMLStringDefaultsEmpty is a non-nullable variant that accepts null on set. Having this separate type allows Web IDL §3.3.22 [TreatNullAs] to attach to DOMString per heycam/webidl#441.

TreatNullAs=EmptyString is confusing. See note "It should not be used in specifications unless ...". For some sinks a null value will result in "", and "null" for others. This already caused problems in the polyfill. <https://github.com/WICG/trusted-types/issues/2>

4.1. Integration with HTML

Window objects have a trusted type policy factory, which is a TrustedTypePolicyFactory object.

Define for workers.

4.1.1. Extensions to the Window interface

This document extends the Window interface defined by HTML:

partial interface mixin Window {
  [Unforgeable] readonly attribute
      TrustedTypePolicyFactory trustedTypes;

  WindowProxy? open(
      [TrustedTypes=TrustedURL] optional URLString url = "about:blank",
      optional DOMString target = "_blank",
      optional ([TreatNullAs=EmptyString] DOMString) features = "");
};

trustedTypes returns the trusted type policy factory of the current Window.

Note: The implementation in Chrome < 78 uses window.TrustedTypes instead of window.trustedTypes.

Remove the note when the API in Chrome is shipped.

4.1.2. Extensions to the Document interface

This document modifies the Document interface defined by HTML:

partial interface mixin Document {
  WindowProxy? open([TrustedTypes=TrustedURL] URLString url, DOMString name, DOMString features);
  [CEReactions] void write([TrustedTypes=TrustedHTML] HTMLString... text);
  [CEReactions] void writeln([TrustedTypes=TrustedHTML] HTMLString... text);
};

Note: This document does not affect the two argument form of document.open.

4.1.3. Extensions to the Location interface

This document modifies the Location interface defined by HTML:

partial interface mixin Location {
  [Unforgeable, TrustedTypes=TrustedURL] stringifier attribute URLString href;
  [Unforgeable] void assign([TrustedTypes=TrustedURL] URLString url);
  [Unforgeable] void replace([TrustedTypes=TrustedURL] URLString url);
};

4.1.4. Enforcement in element attributes

This document modifies following IDL attributes of various DOM elements:

partial interface mixin HTMLScriptElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedScriptURL] attribute ScriptURLString src;
  [CEReactions, TrustedTypes=TrustedScript] attribute ScriptString text;
};

partial interface mixin HTMLIFrameElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedURL] attribute URLString src;
  [CEReactions, TrustedTypes=TrustedHTML] attribute HTMLString srcdoc;
};

partial interface HTMLEmbedElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedScriptURL] attribute ScriptURLString src;
};

partial interface HTMLObjectElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedScriptURL] attribute ScriptURLString data;
  [CEReactions, TrustedTypes=TrustedScriptURL] attribute DOMString codeBase; // obsolete
};

partial interface HTMLFrameElement : HTMLElement { // obsolete
  [CEReactions, TrustedTypes=TrustedURL] attribute URLString src;
};

partial interface HTMLFormElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedURL] attribute URLString action;
};

partial interface HTMLInputElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedURL] attribute URLString formAction;
  [CEReactions, TrustedTypes=TrustedURL] attribute URLString src;
};

partial interface HTMLButtonElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedURL] attribute URLString formAction;
};

partial interface mixin HTMLHyperlinkElementUtils {
  [CEReactions, TrustedTypes=TrustedURL] stringifier attribute URLString href;
};

partial interface HTMLBaseElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedURL] attribute URLString href;
};

// TODO: Add HTMLPortalElement.src from https://github.com/WICG/portals once it’s specced.

4.1.5. Enforcement for script text contents

This document modifies how HTMLScriptElement child text content can be set to allow applications to control dynamically created scripts. It does so by adding the innerText and textContent attributes directly on HTMLScriptElement. The behavior of the attributes remains the same as in their original counterparts, apart from additional behavior triggered by the TrustedTypes extended attribute presence.

partial interface mixin HTMLScriptElement : HTMLElement {
 [CEReactions, TrustedTypes=TrustedScript] attribute [TreatNullAs=EmptyString] ScriptString innerText;
 [CEReactions, TrustedTypes=TrustedScript] attribute ScriptString? textContent;
};

Additionally, this document defines insert text node validation steps for HTMLScriptElement to ascertain that text nodes inserted under HTMLScriptElement elements will satisfy Trusted Types restrictions:

  1. Let text be node’s child text content.

  2. Let convertedText be the result of running Get Trusted Type compliant string, passing parent’s relevant global object as global, TrustedScript as expectedType, text as input and "script.text" as sink. If the algorithm threw an error, rethrow the error.

    Note: If Trusted Types are not enforced, this algorithm will return early and return input unmodified.

  3. Set node’s data to convertedText.

Note: This prevents calling ChildNode.after(aTrustedScript, ...), as the type information is lost before insert is run. To fix that, an additional metadata in Text nodes would be needed. Removed that use case for simplicity.

Trusted Types prevent manipulation of text nodes under script elements.
// Content-Security-Policy: trusted-types *

const s = document.createElement('script');
const text = document.createTextNode('alert(1)');
const p = document.createElement('p');

s.appendChild(p);
s.appendChild(text); // TypeError
p.insertAdjacentText('beforebegin', 'alert(2)'); // TypeError

4.1.6. Enforcement in timer functions

This document modifies the WindowOrWorkerGlobalScope interface mixin:

typedef (ScriptString or Function) TrustedTimerHandler;

partial interface mixin WindowOrWorkerGlobalScope {
  long setTimeout(TrustedTimerHandler handler, optional long timeout = 0, any... arguments);
  long setInterval(TrustedTimerHandler handler, optional long timeout = 0, any... arguments);
};

To the timer initialization steps algorithm, add this step between 7.1 and 7.2:

  1. If the first operation argument is not a Function, or if the first operation argument is a TrustedType, set the first operation argument to the result of executing the Get Trusted Type compliant string algorithm, with

    • global set to the context object's relevant global object.

    • input set to the first method argument, and

    • expectedType set to TrustedScript.

    • sink set to "Window.setInterval" if repeat is true, "Window.setTimeout" otherwise.

      Note: This matches the logic that the extended attribute would apply.

Note: This makes sure that a TrustedScript is passed to timer functions in place of a string when Trusted Types are enforced, but also unconditionally accepts any Function object.

4.1.7. Enforcement in event handler content attributes

This document modifies the attribute change steps for an event handler content attribute.

At the beginning of step 5, insert the following steps:

  1. Let value be the result of executing the Get Trusted Type compliant string algorithm, with the following arguments:

    • value as input,

    • TrustedScript as expectedType,

    • sink being the result of concatenating the list « element’s local name, localName » with "." as a separator.

      Note: For example, document.createElement('div').onclick = value will result in sink being 'div.onclick'.

    • eventTarget’s relevant global object as global,

  2. If the algorithm throws an error, abort these steps.

Note: This also applies to events in Scalable Vector Graphics (SVG) 2 §EventAttributes.

// Content-Security-Policy: trusted-types *

const img = document.createElement('img');
img.setAttribute('onerror', 'alert(1)'); // TypeError

4.2. Integration with SVG

This document modifies the SVGScriptElement interface and SVGURIReference interfaces to enforce Trusted Types on those:

partial interface SVGURIReference {
  [SameObject, TrustedTypes=TrustedURL] readonly attribute SVGAnimatedString href;
};

partial interface mixin SVGScriptElement : SVGElement {
 // overwrites the definition in SVGURIReference.
 [TrustedTypes=TrustedScriptURL] readonly attribute ScriptURLString href;
};

Additionally, this document defines insert text node validation steps for SVGScriptElement to ascertain that text nodes inserted to SVGScriptElement elements will satisfy Trusted Types restrictions:

  1. Let text be node’s child text content.

  2. Let convertedText be the result of running Get Trusted Type compliant string, passing parent’s relevant global object as global, TrustedScript as expectedType, text as input and "script.text" as sink. If the algorithm threw an error, rethrow the error.

    Note: If Trusted Types are not enforced, this algorithm will return early and return input unmodified.

  3. Set node’s data to convertedText.

4.3. Integration with DOM

4.3.1. Text node validation steps

Add the following step at the beginning of step 7 of insert algorithm.

  1. If node is a Text node, run insert text node validation steps for parent, passing node and parent as parameters.

insert text node validation steps may be defined by other specifications.

4.4. Integration with DOM Parsing

This document modifies the following interfaces defined by [DOM-Parsing]:

partial interface Element {
  [CEReactions, TrustedTypes=TrustedHTML] attribute HTMLStringDefaultsEmpty outerHTML;
  [CEReactions] void insertAdjacentHTML(DOMString position, [TrustedTypes=TrustedHTML] HTMLString text);
};

partial interface mixin InnerHTML { // specified in a draft version at https://w3c.github.io/DOM-Parsing/#the-innerhtml-mixin
  [CEReactions, TrustedTypes=TrustedHTML] attribute HTMLStringDefaultsEmpty innerHTML;
};

partial interface Range {
  [CEReactions, NewObject] DocumentFragment createContextualFragment([TrustedTypes=TrustedHTML] HTMLString fragment);
};

[Constructor, Exposed=Window]
interface DOMParser {
  [NewObject] Document parseFromString([TrustedTypes=TrustedHTML] HTMLString str, SupportedType type);
};

4.5. Integration with Content Security Policy

4.5.1. trusted-types directive

This document defines trusted-types - a new Content Security Policy directive.

trusted-types directive configures the Trusted Types framework for all the injection sinks in a current realm. Specifically, it defines which policies (identified by name) can be created, and what should be the behavior when a string value is passed to an injection sink (i.e. should the type-based enforcement be enabled).

The syntax for the directive’s name and value is described by the following ABNF:

directive-name = "trusted-types"
directive-value = serialized-tt-configuration
serialized-tt-configuration = ( tt-expression *( required-ascii-whitespace tt-expression ) )
tt-expression = "*" / tt-policy-name ; In the future, add keywords
tt-policy-name = 1*( %x21-%x26 / %x28-%x29 / %x2B / %x2D-%x3A / %x3C-%x7E )
; Policy name can consist of any VCHAR character, apart from ";", ",", "*" and "'".
Types are enforced at sinks, and only two policies may be created: “one” and “two”.
Content-Security-Policy: trusted-types one two
An empty directive value indicates policies may not be created, and sinks expect Trusted Type values, i.e. no injection sinks can be used at all.
Content-Security-Policy: trusted-types

A value "*" allows for creating policies with any name, including policies with a name that was already used.

Content-Security-Policy: trusted-types *

If the policy named default is present in the list, it refers to the default policy. All strings passed to injection sinks will be passed through it instead of being rejected outright.

Content-Security-Policy: trusted-types one two default

4.5.2. Should sink type mismatch violation be blocked by Content Security Policy?

Given a global object (global), a string (sink) and a string (source) this algorithm returns "Blocked" if the injection sink requires a Trusted Type, and "Allowed" otherwise.

  1. Let result be "Allowed".

  2. For each policy in global’s CSP list:

    1. If policy’s directive set does not contain a directive which name is "trusted-types", skip to the next policy.

    2. Let violation be the result of executing Create a violation object for global, policy, and directive on global, policy and "trusted-types"

    3. Set violation’s resource to "trusted-types-sink".

    4. Let trimmedSource be the substring of source, containing its first 40 characters.

    5. Set violation’s sample to be the result of concatenating the list « sink, trimmedSource « using space ("\x20") as a separator.

    6. Execute Report a violation on violation.

    7. If policy’s disposition is "enforce", then set result to "Blocked".

  3. Return result.

4.5.3. Should Trusted Type policy creation be blocked by Content Security Policy?

Given a global object (global), a string (policyName) and a list of strings (createdPolicyNames), this algorithm returns "Blocked" if the Trusted Type Policy should not be created, and "Allowed" otherwise.

  1. Let result be "Allowed".

  2. For each policy in global’s CSP list:

    1. Let createViolation be false.

    2. If policy’s directive set does not contain a directive which name is "trusted-types", skip to the next policy.

    3. Let directive be the policy’s directive set’s directive which name is "trusted-types"

    4. If directive’s value contains a tt-expression which is a match for a value *, skip to the next policy.

      Note: trusted-types * allows authors to create policies with duplicated names.

    5. If createdPolicyNames contains policyName, set createViolation to true.

    6. If directive’s value does not contain a tt-policy-name, which value is policyName, set createViolation to true.

    7. If createViolation is false, skip to the next policy.

    8. Let violation be the result of executing Create a violation object for global, policy, and directive on global, policy and "trusted-types"

    9. Set violation’s resource to "trusted-types-policy".

    10. Set violation’s sample to the substring of policyName, containing its first 40 characters.

    11. Execute Report a violation on violation.

    12. If policy’s disposition is "enforce", then set result to "Blocked".

  3. Return result.

4.5.4. Violation object changes

Violation object resource also allows "trusted-types-policy" and "trusted-types-sink" as values.

4.5.5. 'trusted-script' keyword

Note: See TC39/ecma262 issue #938 (adding the value to be compiled to algorithm parameters).

Note: EcmaScript code may call Function() and eval cross realm.
let f = new self.top.Function(source);

In this case, the callerRealm’s Window is self and the calleeRealm’s Window is self.top. The Trusted Types portion of this algorithm uses calleeRealm for consistency with other sinks.

// Assigning a string to another Realm’s DOM sink uses that Realm’s default policy.
self.top.body.innerHTML = 'Hello, World!';
// Using another Realm’s builtin Function constructor should analogously use that
// Realm’s default policy.
new self.top.Function('alert(1)')()

This is subtly different from the CSP directive enforcement portion which rejects if either the calleeRealm or callerRealm’s Content-Security-Policy rejects string compilation.

This document modifies the grammar for Content Security Policy Level 3 §keyword-source:

keyword-source = "'self'" / "'unsafe-inline'" / "'unsafe-eval'"
                     / "'strict-dynamic'" / "'unsafe-hashes'" / "'report-sample'"
                     / "'unsafe-allow-redirects'" / "'trusted-script'"

This document modifies the EnsureCSPDoesNotBlockStringCompilation which is reproduced in its entirety below with additions and deletions.

Given two realms (callerRealm and calleeRealm), and a string value (source), this algorithm returns normally

the source string to compile if compilation is allowed, and throws an "EvalError" if not:
  1. Let sourceString be the result of executing the Get Trusted Type compliant string algorithm, with:
    • calleeRealm as global,

    • source as input,

    • "eval" as sink,

    • TrustedScript as expectedType.

  2. If the algorithm throws an error, throw an EvalError.
  3. Let isExempt be the result of executing the IsSourceExempt algorithm with:
  4. Let globals be a list containing calleeRealm’s global object and calleeRealm’s global object.

  5. For each global in globals:

    1. Let result be "Allowed".

    2. For each policy in global’s CSP list:

      1. Let source-list be null.

      2. If policy contains a directive whose name is "script-src", then set source-list to that directive's value.

        Otherwise if policy contains a directive whose name is "default-src", then set source-list to that directive’s value.

      3. If source-list is not null, and does not contain a source expression which is an ASCII case-insensitive match for the string "'unsafe-eval'", and it is the case that (isExempt is not true or source-list does not contain a source expression which is an ASCII case-insensitive match for the string "'trusted-script'") then:

        1. Let violation be the result of executing Content Security Policy Level 3 §create-violation-for-global on global, policy, and "script-src".

        2. Set violation’s resource to "inline".

        3. If source-list contains the expression "'report-sample'", then set violation’s sample to the substring of source sourceString containing its first 40 characters.

        4. Execute Content Security Policy Level 3 §report-violation on violation.

        5. If policy’s disposition is "enforce", then set result to "Blocked".

    3. If result is "Blocked", throw an EvalError exception.

  6. Return sourceString.

Note: returning sourceString means that the string that gets compiled is that returned by any default policy in the course of executing Get Trusted Type compliant string.

This depends on a solution to issue #144 like TC39 HostBeforeCompile

In some cases, the violation "'report-sample'" contain the result of applying the default policy to a string argument which differs. Specifically when, there is a default policy, isExempt is false, and source there is a CSP policy for either the callerRealm or callerRealm that disallows "'unsafe-eval'". Is this a feature or a bug?

Note: The previous algorithm reports violations via both report-uris where callerRealm != calleeRealm. If Get Trusted Type compliant string reports an error, it only reports it via its calleeRealm’s report-uri.

4.5.6. IsSourceExempt Algorithm

The IsSourceExempt algorithm takes a CSP List (cspList) and executes the following steps:

  1. If cspList contains a policy whose directive set contains a directive with a name "trusted-types", return true.

  2. Return false.

Note: This checks whether Trusted Types enforcement would have rejected the input, were it problematic in the callout to Get Trusted Type compliant string.

5. Security Considerations

Trusted Types are not intended to defend against XSS in an actively malicious execution environment. It’s assumed that the application is written by non-malicious authors; the intent is to prevent developer mistakes that could result in security bugs, and not to defend against first-party malicious code actively trying to bypass policy restrictions. Below we enumerate already identified vectors that remain risky even in environments with enforced Trusted Types.

5.1. Cross-document vectors

While the code running in a window in which Trusted Types are enforced cannot dynamically create nodes that would bypass the policy restrictions, it is possible that such nodes can be imported or adopted from documents in other windows, that don’t have the same set of restrictions. In essence - it is possible to bypass Trusted Types if a malicious author creates a setup in which a restricted document colludes with an unrestricted one.

CSP propagation rules (see Content Security Policy Level 3 §initialize-document-csp partially address this issue, as new local scheme documents will inherit the same set of restrictions. To address this issue comprehensively, other mechanisms like Origin Policy should be used to ensure that baseline security rules are applied for the whole origin.

5.2. Deprecated features

Some long-deprecated and rarely used plaform features are not subject to Trusted Types, and could potentially be used by malicious authors to overcome the restrictions:

5.3. Bypass vectors

Mention anchor element properties bypass. <https://github.com/WICG/trusted-types/issues/64>

Mention text/attribute node copy bypass vectors. <https://github.com/WICG/trusted-types/issues/47>

5.4. Best practices for policy design

Trusted Types limit the scope of the code that can introduce DOM XSS vulnerabilities to the implementation of policies. In this design, insecure policies can still enable XSS. Special emphasis needs to be taken by use policies that are either secure for all possible inputs, or limit the access to insecure policies, such that they are only called with non-attacker controlled inputs.

As policies are custom JavaScript code, they may be written in a way that heavily depends on a global state. We advise against this. The policies should be self-contained as much as possible. All objects that may alter security decisions a policy makes effectively become the policy, and should be guarded & reviewed together.

Refer to the external document on secure policy design.

6. Implementation Considerations

6.1. Vendor-specific Extensions and Addons

Restriction imposed by Trusted Types SHOULD NOT interfere with the operation of user-agent features like addons, extensions, or bookmarklets. These kinds of features generally advance the user’s priority over page authors, as espoused in [html-design-principles]. Specifically, extensions SHOULD be able to pass strings to the DOM XSS injection sinks without triggering default policy execution, violation generation, or the rejection of the value.

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSP3]
Mike West. Content Security Policy Level 3. 15 October 2018. WD. URL: https://www.w3.org/TR/CSP3/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[DOM-Parsing]
Travis Leithead. DOM Parsing and Serialization. 17 May 2016. WD. URL: https://www.w3.org/TR/DOM-Parsing/
[Fetch]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[SVG2]
Amelia Bellamy-Royds; et al. Scalable Vector Graphics (SVG) 2. 4 October 2018. CR. URL: https://www.w3.org/TR/SVG2/
[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

Informative References

[HTML-DESIGN-PRINCIPLES]
Anne van Kesteren; Maciej Stachowiak. HTML Design Principles. 26 November 2007. WD. URL: https://www.w3.org/TR/html-design-principles/
[HTML5]
Ian Hickson; et al. HTML5. 27 March 2018. REC. URL: https://www.w3.org/TR/html5/

IDL Index

[Exposed=Window]
interface TrustedHTML {
  stringifier;
};

[Exposed=Window]
interface TrustedScript {
  stringifier;
};

[Exposed=Window]
interface TrustedScriptURL {
  stringifier;
};

[Exposed=Window]
interface TrustedURL {
  stringifier;
};

[Exposed=Window] interface TrustedTypePolicyFactory {
    [Unforgeable] TrustedTypePolicy createPolicy(
        DOMString policyName, optional TrustedTypePolicyOptions policyOptions);
    [Unforgeable] sequence<DOMString> getPolicyNames();
    [Unforgeable] boolean isHTML(any value);
    [Unforgeable] boolean isScript(any value);
    [Unforgeable] boolean isScriptURL(any value);
    [Unforgeable] boolean isURL(any value);
    [Unforgeable] readonly attribute TrustedHTML emptyHTML;
    string? getAttributeType(
        DOMString localName, DOMString attribute,
        optional DOMString elementNs = "", optional DOMString attributeNs = "");
    string? getPropertyType(
        DOMString localName, DOMString property,
        optional DOMString elementNs = "");
    readonly attribute TrustedTypePolicy? defaultPolicy;
};

[Exposed=Window]
interface TrustedTypePolicy {
  [Unforgeable] readonly attribute DOMString name;
  [Unforgeable] TrustedHTML createHTML(DOMString input, any... arguments);
  [Unforgeable] TrustedScript createScript(DOMString input, any... arguments);
  [Unforgeable] TrustedScriptURL createScriptURL(DOMString input, any... arguments);
  [Unforgeable] TrustedURL createURL(DOMString input, any... arguments);
};

dictionary TrustedTypePolicyOptions {
   CreateHTMLCallback? createHTML;
   CreateScriptCallback? createScript;
   CreateURLCallback? createURL;
   CreateScriptURLCallback? createScriptURL;
};
callback CreateHTMLCallback = DOMString (DOMString input);
callback CreateScriptCallback = DOMString (DOMString input);
callback CreateURLCallback = USVString (DOMString input);
callback CreateScriptURLCallback = USVString (DOMString input);

typedef (DOMString or TrustedHTML) HTMLString;
typedef (DOMString or TrustedScript) ScriptString;
typedef (USVString or TrustedScriptURL) ScriptURLString;
typedef (USVString or TrustedURL) URLString;
typedef (TrustedHTML or TrustedScript or TrustedScriptURL or TrustedURL) TrustedType;

typedef (([TreatNullAs=EmptyString] DOMString) or TrustedHTML) HTMLStringDefaultsEmpty;

partial interface mixin Window {
  [Unforgeable] readonly attribute
      TrustedTypePolicyFactory trustedTypes;

  WindowProxy? open(
      [TrustedTypes=TrustedURL] optional URLString url = "about:blank",
      optional DOMString target = "_blank",
      optional ([TreatNullAs=EmptyString] DOMString) features = "");
};

partial interface mixin Document {
  WindowProxy? open([TrustedTypes=TrustedURL] URLString url, DOMString name, DOMString features);
  [CEReactions] void write([TrustedTypes=TrustedHTML] HTMLString... text);
  [CEReactions] void writeln([TrustedTypes=TrustedHTML] HTMLString... text);
};

partial interface mixin Location {
  [Unforgeable, TrustedTypes=TrustedURL] stringifier attribute URLString href;
  [Unforgeable] void assign([TrustedTypes=TrustedURL] URLString url);
  [Unforgeable] void replace([TrustedTypes=TrustedURL] URLString url);
};

partial interface mixin HTMLScriptElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedScriptURL] attribute ScriptURLString src;
  [CEReactions, TrustedTypes=TrustedScript] attribute ScriptString text;
};

partial interface mixin HTMLIFrameElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedURL] attribute URLString src;
  [CEReactions, TrustedTypes=TrustedHTML] attribute HTMLString srcdoc;
};

partial interface HTMLEmbedElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedScriptURL] attribute ScriptURLString src;
};

partial interface HTMLObjectElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedScriptURL] attribute ScriptURLString data;
  [CEReactions, TrustedTypes=TrustedScriptURL] attribute DOMString codeBase; // obsolete
};

partial interface HTMLFrameElement : HTMLElement { // obsolete
  [CEReactions, TrustedTypes=TrustedURL] attribute URLString src;
};

partial interface HTMLFormElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedURL] attribute URLString action;
};

partial interface HTMLInputElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedURL] attribute URLString formAction;
  [CEReactions, TrustedTypes=TrustedURL] attribute URLString src;
};

partial interface HTMLButtonElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedURL] attribute URLString formAction;
};

partial interface mixin HTMLHyperlinkElementUtils {
  [CEReactions, TrustedTypes=TrustedURL] stringifier attribute URLString href;
};

partial interface HTMLBaseElement : HTMLElement {
  [CEReactions, TrustedTypes=TrustedURL] attribute URLString href;
};

// TODO: Add HTMLPortalElement.src from https://github.com/WICG/portals once it’s specced.

partial interface mixin HTMLScriptElement : HTMLElement {
 [CEReactions, TrustedTypes=TrustedScript] attribute [TreatNullAs=EmptyString] ScriptString innerText;
 [CEReactions, TrustedTypes=TrustedScript] attribute ScriptString? textContent;
};

typedef (ScriptString or Function) TrustedTimerHandler;

partial interface mixin WindowOrWorkerGlobalScope {
  long setTimeout(TrustedTimerHandler handler, optional long timeout = 0, any... arguments);
  long setInterval(TrustedTimerHandler handler, optional long timeout = 0, any... arguments);
};

partial interface SVGURIReference {
  [SameObject, TrustedTypes=TrustedURL] readonly attribute SVGAnimatedString href;
};

partial interface mixin SVGScriptElement : SVGElement {
 // overwrites the definition in SVGURIReference.
 [TrustedTypes=TrustedScriptURL] readonly attribute ScriptURLString href;
};

partial interface Element {
  [CEReactions, TrustedTypes=TrustedHTML] attribute HTMLStringDefaultsEmpty outerHTML;
  [CEReactions] void insertAdjacentHTML(DOMString position, [TrustedTypes=TrustedHTML] HTMLString text);
};

partial interface mixin InnerHTML { // specified in a draft version at https://w3c.github.io/DOM-Parsing/#the-innerhtml-mixin
  [CEReactions, TrustedTypes=TrustedHTML] attribute HTMLStringDefaultsEmpty innerHTML;
};

partial interface Range {
  [CEReactions, NewObject] DocumentFragment createContextualFragment([TrustedTypes=TrustedHTML] HTMLString fragment);
};

[Constructor, Exposed=Window]
interface DOMParser {
  [NewObject] Document parseFromString([TrustedTypes=TrustedHTML] HTMLString str, SupportedType type);
};

Issues Index

Update when workers have TT.
Update when workers have TT.
Synchronize when TT are added to workers (perhaps use "has a CSP list"?)
TreatNullAs=EmptyString is confusing. See note "It should not be used in specifications unless ...". For some sinks a null value will result in "", and "null" for others. This already caused problems in the polyfill. <https://github.com/WICG/trusted-types/issues/2>
Define for workers.
Remove the note when the API in Chrome is shipped.
This depends on a solution to issue #144 like TC39 HostBeforeCompile
In some cases, the violation "'report-sample'" contain the result of applying the default policy to a string argument which differs. Specifically when, there is a default policy, isExempt is false, and source there is a CSP policy for either the callerRealm or callerRealm that disallows "'unsafe-eval'". Is this a feature or a bug?
Mention anchor element properties bypass. <https://github.com/WICG/trusted-types/issues/64>
Mention text/attribute node copy bypass vectors. <https://github.com/WICG/trusted-types/issues/47>
Refer to the external document on secure policy design.