Trusted Types API

Concepts and usage

Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as injection sinks.

The Trusted Types API distinguishes three sorts of injection sinks:

• HTML sinks: APIs that interpret their input as HTML, such as Element.innerHTML or document.write(). These APIs could execute JavaScript if it is embedded in the HTML, for example in <script> tags or event handler attributes.
• JavaScript sinks: APIs that interpret their input as JavaScript, such as eval() or HTMLScriptElement.text.
• JavaScript URL sinks: APIs that interpret their input as the URL of a script, such as HTMLScriptElement.src.

One of the main defenses against DOM-based XSS attacks is to ensure that input is made safe before being passed to an injection sink.

In the Trusted Types API, a developer defines a policy object, which contains methods that transform input bound for an injection sink so as to make it safe. The policy can define different methods for the different types of sink:

• For HTML sinks, the transformation function typically sanitizes the input, for example by using a library like DOMPurify.
• For JavaScript and JavaScript URL sinks, the policy may turn off the sinks entirely or allow certain predefined inputs (for example, specific URLs).

The Trusted Types API will then ensure that input is passed through the appropriate transformation function before being passed into the sink.

That is, the API enables you to define your policy in one place and then be assured that any data passed to an injection sink has been passed through the policy.

The API has two main parts:

• A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
• Two CSP directives enforce and control the usage of the JavaScript API.

The Trusted Types JavaScript API

In the Trusted Types API:

• The trustedTypes global property, available in both Window and Worker contexts, is used to create TrustedTypePolicy objects.
• A TrustedTypePolicy object is used to create trusted type objects: it will do this by passing the data through a transformation function.
• Trusted type objects represent data that has been through the policy, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to the different sort of injection sink:
  • TrustedHTML is for passing to a sink that will render the data as HTML.
  • TrustedScript is for passing to a sink that will execute the data as JavaScript.
  • TrustedScriptURL is for passing to a sink that will parse the data as a URL to a script.

With this API, instead of passing a string to an injection sink like innerHTML, you use a TrustedTypePolicy to create a TrustedHTML object from the string, then pass that into the sink, and can be sure that the string has been passed through a transformation function.

For example, this code creates a TrustedTypePolicy that can create TrustedHTML objects by sanitizing the input strings with the DOMPurify library:

Next, you can use this policy object to create a TrustedHTML object, and pass that object into the injection sink:

Using a CSP to enforce trusted types

The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into innerHTML.

In order to enforce that a trusted type must always be passed, you include the require-trusted-types-for directive in your CSP. With this directive set, passing strings into injection sinks will result in a TypeError exception:

Additionally, the trusted-types CSP directive can be used to control which policies your code is allowed to create. When you create a policy using trustedTypes.createPolicy(), you pass a name for the policy. The trusted-types CSP directive lists acceptable policy names, so createPolicy() will throw an exception if it is passed a name which was not listed in trusted-types. This prevents some code in your web application from creating a policy that you were not expecting.

The default policy

In the Trusted Types API, you can define a default policy. This helps you find any places in your code where you're still passing strings into injection sinks, so you can rewrite the code to create and pass trusted types instead.

If you create a policy named "default", and your CSP enforces the use of trusted types, then any string argument passed into injection sinks will be automatically passed to this policy. For example, suppose we create a policy like this:

With this policy, if your code assigns a string to innerHTML, the browser will call the policy's createHTML() method and assign its result to the sink:

If the default policy returned null or undefined, then the browser will throw a TypeError when assigning the result to the sink:

Injection sink interfaces

This section provides a list of "direct" injection sink interfaces.

These are the API properties and methods which perform trusted type checks when they are evaluated. They can be passed trusted types (TrustedHTML, TrustedScript, or TrustedScriptURL) as well as strings, and must be passed trusted types when trusted type enforcement is enabled and no default policy is defined.

TrustedHTML

• Document.execCommand() with a commandName of "insertHTML"
• Document.parseHTMLUnsafe()
• Document.write()
• Document.writeln()
• DOMParser.parseFromString()
• Element.innerHTML
• Element.insertAdjacentHTML
• Element.outerHTML
• Element.setHTMLUnsafe()
• HTMLIFrameElement.srcdoc
• Range.createContextualFragment()
• ShadowRoot.innerHTML
• ShadowRoot.setHTMLUnsafe()

TrustedScript

• AsyncFunction() constructor
• AsyncGeneratorFunction() constructor
• eval()
• Element.setAttribute() (value argument)
• Element.setAttributeNS() (value argument)
• Function() constructor
• GeneratorFunction() constructor
• HTMLScriptElement.innerText
• HTMLScriptElement.textContent
• HTMLScriptElement.text
• window.setTimeout() and WorkerGlobalScope.setTimeout() (code argument)
• window.setInterval() and WorkerGlobalScope.setInterval() (code argument)

TrustedScriptURL

• HTMLScriptElement.src
• ServiceWorkerContainer.register()
• SvgAnimatedString.baseVal
• WorkerGlobalScope.importScripts()
• url argument to Worker() constructor
• url argument to SharedWorker() constructor

Indirect injection sinks

Indirect injection sinks are sinks where untrusted strings are injected into the DOM via an intermediate mechanism that doesn't accept or enforce trusted types. These differ from the "direct" Injection sink interfaces listed in the previous section, which run trusted type checks on injected strings when they are called.

For example, the following code sets script element source indirectly. First a text node is created using a string provided by a user, and then a <script> element is constructed and the text node is appended as a child element. Next the script element is added to the document as a child of the <body> element — at this point scripts defined in the original string may be executed.

When the text node is created there is no reason for the browser to assume it is intended to be used as a trusted type source, so trusted types are serialized to string, and are not enforced.

Instead, browsers run the checks when the script element becomes executable — i.e., in this example, when document.body.appendChild(script) is called to add the script element to the document.

The browser will first check if the string used as the script content is trusted. Any operation that allows the text source of a <script> to be modified without explicitly setting a TrustedScript makes it untrusted. The Node.appendChild() method used above is just one example (a number of others are listed in the WPT Live tests at https://wpt.live/trusted-types/script-enforcement-001.html).

If the string is not trusted and trusted types are enforced, the browser will attempt to obtain a TrustedScript from a default policy to use for source instead. If a default policy is not defined, or does not return a TrustedScript, the operation will throw an exception.

Trusted Types tinyfill

The Trusted Types tinyfill helps you work with browsers that don't support the Trusted Types API itself.

The tinyfill is just this:

That is, it provides an implementation of trustedTypes.createPolicy() which just returns the policyOptions object it was passed. The policyOptions object defines sanitization functions for data, and these functions are expected to return strings.

With this tinyfill in place, suppose we create a policy:

In browsers that support trusted types, this will return a TrustedTypePolicy, which will create a TrustedHTML object when we call policy.createHTML(). The TrustedHTML object can then be passed to an injection sink, and we can enforce that the sink received a trusted type, rather than a string.

In browsers that don't support trusted types, this code will return an object with a createHTML() function that sanitizes its input and returns it as a string. The sanitized string can then be passed to an injection sink.

Either way, the injection sink gets sanitized data, and because we could enforce the use of the policy in the supporting browser, we know that this code path goes through the sanitization function in the non-supporting browser, too.

This means that, as long as you have tested your code on a supporting browser with the require-trusted-types-for CSP directive, then the tinyfill is enough to give the same protection even in browsers which don't support the Trusted Types API.

This is because the enforcement forces you to refactor your code to ensure that all data is passed through the Trusted Types API (and therefore has been through a sanitization function) before being passed to an injection sink. If you then run the refactored code in a different browser without enforcement, it will still go through the same code paths, and give you the same protection.

Interfaces

Represents a string to insert into an injection sink that will render it as HTML.

Represents a string to insert into an injection sink that could lead to the script being executed.

Represents a string to insert into an injection sink that will parse it as a URL of an external script resource.

Defines the functions used to create the above Trusted Type objects.

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

Extensions to other interfaces

Returns the TrustedTypePolicyFactory object associated with the global object in the main thread. This is the entry point for using the API in the Window thread.

Returns the TrustedTypePolicyFactory object associated with the global object in a worker.

Extensions to HTTP

Content-Security-Policy directives

Enforces that Trusted Types are passed to DOM XSS injection sinks.

Used to specify an allowlist of Trusted Types policy names.

Content-Security-Policy keywords

Allows eval() and similar functions to be used but only when Trusted Types are supported and enforced.

Examples

In the below example we create a policy that will create TrustedHTML objects using TrustedTypePolicyFactory.createPolicy(). We can then use TrustedTypePolicy.createHTML() to create a sanitized HTML string to be inserted into the document.

The sanitized value can then be used with Element.innerHTML to ensure that no new HTML elements can be injected.

Read more about this example, and discover other ways to sanitize input in the article Prevent DOM-based cross-site scripting vulnerabilities with Trusted Types.

Specifications

Browser compatibility

Enable JavaScript to view this browser compatibility table.

See also

• Prevent DOM-based cross-site scripting vulnerabilities with Trusted Types