diff --git a/files/en-us/web/api/trusted_types_api/index.md b/files/en-us/web/api/trusted_types_api/index.md index b81cb4594d74338..9b70d972e888434 100644 --- a/files/en-us/web/api/trusted_types_api/index.md +++ b/files/en-us/web/api/trusted_types_api/index.md @@ -8,30 +8,185 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/ {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}} -The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks. +The **Trusted Types API** gives web developers a way to ensure that input has been passed through a user-specified transformation function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks. Most commonly the transformation function [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input. -## Concepts and Usage +## Concepts and usage -Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions. +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 locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function. +The Trusted Types API distinguishes three sorts of injection sinks: -Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives. +- **HTML sinks**: APIs that interpret their input as HTML, such as {{domxref("Element.innerHTML")}} or {{domxref("Document.write()", "document.write()")}}. These APIs could execute JavaScript if it is embedded in the HTML, for example in {{htmlelement("script")}} tags or event handler attributes. +- **JavaScript sinks**: APIs that interpret their input as JavaScript, such as {{jsxref("Global_Objects/eval", "eval()")}} or {{domxref("HTMLScriptElement.text")}}. +- **JavaScript URL sinks**: APIs that interpret their input as the URL of a script, such as {{domxref("HTMLScriptElement.src")}}. -### Injection Sinks +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. -The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include: +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: -- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}. -- Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}. -- Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}. -- Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute. +- For HTML sinks, the transformation function typically [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input, for example by using a library like [DOMPurify](https://github.com/cure53/DOMPurify). +- For JavaScript and JavaScript URL sinks, the policy may turn off the sinks entirely or allow certain predefined inputs (for example, specific URLs). -Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy. +The Trusted Types API will then ensure that input is passed through the appropriate transformation function before being passed into the sink. -### Trusted Type Policies +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. -A policy is a factory for Trusted Types. Web developers can specify a set of policies used for the creation of typed objects which form the trusted codebase for valid Trusted Type objects. +> [!NOTE] +> +> The Trusted Types API does _not_ itself supply a policy or any transformation functions: the developer defines their own policy, which contains the transformations that they wish to apply. + +The API has two main parts: + +- A JavaScript API enables a developer to sanitize data before passing it to an injection sink. +- Two [CSP](/en-US/docs/Web/HTTP/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 {{domxref("Window.trustedTypes", "Window")}} and {{domxref("WorkerGlobalScope.trustedTypes", "Worker")}} contexts, is used to create {{domxref("TrustedTypePolicy")}} objects. +- A {{domxref("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: + - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML. + - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript. + - {{domxref("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](https://github.com/cure53/DOMPurify) library: + +```js +const policy = trustedTypes.createPolicy("my-policy", { + createHTML: (input) => DOMPurify.sanitize(input), +}); +``` + +Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink: + +```js +const userInput = "

I might be XSS

"; +const element = document.querySelector("#container"); + +const trustedHTML = policy.createHTML(userInput); +element.innerHTML = trustedHTML; +``` + +### 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 {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP). +With this directive set, passing strings into injection sinks will result in a `TypeError` exception: + +```js example-bad +const userInput = "

I might be XSS

"; +const element = document.querySelector("#container"); + +element.innerHTML = userInput; // Throws a TypeError +``` + +Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "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: + +```js +trustedTypes.createPolicy("default", { + createHTML: (value) => { + console.log("Please refactor this code"); + return sanitize(value); + }, +}); +``` + +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: + +```js +const userInput = "

I might be XSS

"; +const element = document.querySelector("#container"); + +element.innerHTML = userInput; +// Logs "Please refactor this code" +// Assigns the result of sanitize(userInput) +``` + +If the default policy returned `null` or `undefined`, then the browser will throw a `TypeError` when assigning the result to the sink: + +```js +trustedTypes.createPolicy("default", { + createHTML: (value) => { + console.log("Please refactor this code"); + return null; + }, +}); + +const userInput = "

I might be XSS

"; +const element = document.querySelector("#container"); + +element.innerHTML = userInput; +// Logs "Please refactor this code" +// Throws a TypeError +``` + +> [!NOTE] +> It's recommended that you use the default policy only while you are transitioning from legacy code that passes input directly to injection sinks, to code that uses trusted types explicitly. + +### Cross-browser support for trusted types + +The Trusted Types API is not yet available in all modern browsers, but it is usable everywhere today thanks to [compatibility aids created by the W3C](https://github.com/w3c/trusted-types/tree/main?tab=readme-ov-file#polyfill). + +- The [_full_ polyfill](https://github.com/w3c/trusted-types/blob/main/src/polyfill/full.js) defines the JavaScript API, attempts to infer the CSP from the current document, and enforces the use of trusted types based on the inferred CSP. +- The [_API only_ polyfill](https://github.com/w3c/trusted-types/blob/main/src/polyfill/api_only.js) defines only the JavaScript API, and does not include the ability to enforce the use of trusted types using a CSP. + +As well as these two polyfills, the W3C provides what it calls a _tinyfill_, which we'll explain in more detail below. + +Note that as long as you have tested your code on a supporting browser with CSP enforcement enabled, then you don't need to use the _full polyfill_ above on other browsers — you can get the same benefits using the _API only polyfill_ or the _tinyfill_. + +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. + +#### Trusted Types tinyfill + +In this section we'll look at how the trusted types tinyfill can protect a website, even though it doesn't add support for trusted types at all. + +The trusted types tinyfill is just this: + +```js +if (typeof trustedTypes == "undefined") + trustedTypes = { createPolicy: (n, rules) => rules }; +``` + +It provides an implementation of `trustedTypes.createPolicy()` which just returns the [`policyOptions`](/en-US/docs/Web/API/TrustedTypePolicyFactory/createPolicy#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: + +```js +const policy = trustedTypes.createPolicy("my-policy", { + createHTML: (input) => DOMPurify.sanitize(input), +}); +``` + +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. + +```js +const userInput = "I might be XSS"; +const element = document.querySelector("#container"); + +const trustedHTML = policy.createHTML(userInput); +// In supporting browsers, trustedHTML is a TrustedHTML object. +// In non-supporting browsers, trustedHTML is a string. + +element.innerHTML = trustedHTML; +// In supporting browsers, this will throw if trustedHTML +// is not a TrustedHTML object. +``` + +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. ## Interfaces diff --git a/files/en-us/web/api/trustedhtml/index.md b/files/en-us/web/api/trustedhtml/index.md index cd6cf14f6aa32ce..57915c3ba12f0e3 100644 --- a/files/en-us/web/api/trustedhtml/index.md +++ b/files/en-us/web/api/trustedhtml/index.md @@ -7,7 +7,7 @@ browser-compat: api.TrustedHTML {{APIRef("Trusted Types API")}}{{AvailableInWorkers}} -The **`TrustedHTML`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks) that will render it as HTML. These objects are created via {{domxref("TrustedTypePolicy.createHTML()")}} and therefore have no constructor. +The **`TrustedHTML`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage) that will render it as HTML. These objects are created via {{domxref("TrustedTypePolicy.createHTML()")}} and therefore have no constructor. The value of a `TrustedHTML` object is set when the object is created and cannot be changed by JavaScript as there is no setter exposed. diff --git a/files/en-us/web/api/trustedscript/index.md b/files/en-us/web/api/trustedscript/index.md index aa347c85fcc5506..019a1b6199bb96c 100644 --- a/files/en-us/web/api/trustedscript/index.md +++ b/files/en-us/web/api/trustedscript/index.md @@ -7,7 +7,7 @@ browser-compat: api.TrustedScript {{APIRef("Trusted Types API")}}{{AvailableInWorkers}} -The **`TrustedScript`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string with an uncompiled script body that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks) that might execute the script. These objects are created via {{domxref("TrustedTypePolicy.createScript","TrustedTypePolicy.createScript()")}} and therefore have no constructor. +The **`TrustedScript`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string with an uncompiled script body that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage) that might execute the script. These objects are created via {{domxref("TrustedTypePolicy.createScript","TrustedTypePolicy.createScript()")}} and therefore have no constructor. The value of a **TrustedScript** object is set when the object is created and cannot be changed by JavaScript as there is no setter exposed. diff --git a/files/en-us/web/api/trustedscript/tostring/index.md b/files/en-us/web/api/trustedscript/tostring/index.md index 1da6cd48b420679..6362aceb73f451f 100644 --- a/files/en-us/web/api/trustedscript/tostring/index.md +++ b/files/en-us/web/api/trustedscript/tostring/index.md @@ -8,7 +8,7 @@ browser-compat: api.TrustedScript.toString {{APIRef("Trusted Types API")}}{{AvailableInWorkers}} -The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks). +The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may be safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage). ## Syntax diff --git a/files/en-us/web/api/trustedscripturl/index.md b/files/en-us/web/api/trustedscripturl/index.md index d22ec4629e05c97..6d321edda8c7f16 100644 --- a/files/en-us/web/api/trustedscripturl/index.md +++ b/files/en-us/web/api/trustedscripturl/index.md @@ -7,7 +7,7 @@ browser-compat: api.TrustedScriptURL {{APIRef("Trusted Types API")}}{{AvailableInWorkers}} -The **`TrustedScriptURL`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks) that will parse it as a URL of an external script. These objects are created via {{domxref("TrustedTypePolicy.createScriptURL","TrustedTypePolicy.createScriptURL()")}} and therefore have no constructor. +The **`TrustedScriptURL`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage) that will parse it as a URL of an external script. These objects are created via {{domxref("TrustedTypePolicy.createScriptURL","TrustedTypePolicy.createScriptURL()")}} and therefore have no constructor. The value of a `TrustedScriptURL` object is set when the object is created and cannot be changed by JavaScript as there is no setter exposed. diff --git a/files/en-us/web/api/trustedscripturl/tostring/index.md b/files/en-us/web/api/trustedscripturl/tostring/index.md index c8ba90514d9cf9d..c6b2ecd1b02c49a 100644 --- a/files/en-us/web/api/trustedscripturl/tostring/index.md +++ b/files/en-us/web/api/trustedscripturl/tostring/index.md @@ -8,7 +8,7 @@ browser-compat: api.TrustedScriptURL.toString {{APIRef("Trusted Types API")}}{{AvailableInWorkers}} -The **`toString()`** method of the {{domxref("TrustedScriptURL")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks). +The **`toString()`** method of the {{domxref("TrustedScriptURL")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage). ## Syntax diff --git a/files/en-us/web/api/trustedtypepolicyfactory/createpolicy/index.md b/files/en-us/web/api/trustedtypepolicyfactory/createpolicy/index.md index dbd72ec80cb4272..631fb38cf6e2a51 100644 --- a/files/en-us/web/api/trustedtypepolicyfactory/createpolicy/index.md +++ b/files/en-us/web/api/trustedtypepolicyfactory/createpolicy/index.md @@ -10,16 +10,6 @@ browser-compat: api.TrustedTypePolicyFactory.createPolicy The **`createPolicy()`** method of the {{domxref("TrustedTypePolicyFactory")}} interface creates a {{domxref("TrustedTypePolicy")}} object that implements the rules passed as `policyOptions`. -### The default policy - -In Chrome a policy with a name of "default" creates a special policy that will be used if a string (rather than a Trusted Type object) is passed to an injection sink. This can be used in a transitional phase while moving from an application that inserted strings into injection sinks. - -> [!NOTE] -> The above behavior is not yet settled in the specification and may change in future. - -> [!WARNING] -> A lax default policy could defeat the purpose of using Trusted Types, and therefore should be defined with strict rules to ensure it cannot be used to run dangerous code. - ## Syntax ```js-nolint @@ -54,6 +44,8 @@ A {{domxref("TrustedTypePolicy")}} object. ## Examples +### Creating a policy for HTML sinks + The below code creates a policy with the name `"myEscapePolicy"` with a function defined for `createHTML()` which sanitizes HTML. ```js @@ -64,9 +56,9 @@ const escapeHTMLPolicy = trustedTypes.createPolicy("myEscapePolicy", { ### Creating a default policy -On a site where Trusted Types are enforced via a Content Security Policy with the [`require-trusted-types-for`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/require-trusted-types-for) directive set to `script`, any injection script that accepts a script expects a Trusted Type object. In the case that a string is inserted instead, the following default policy will be used. +On a site where Trusted Types are enforced via a Content Security Policy with the [`require-trusted-types-for`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/require-trusted-types-for) directive set to `script`, any injection script that accepts a script expects a Trusted Type object. In the case that a string is inserted instead, a [default policy](/en-US/docs/Web/API/Trusted_Types_API#the_default_policy) will be used. -The policy logs a message to the console to remind the developer to refactor this part of the application to use a Trusted Type object. It also appends details of the use of the default policy, type, and injection sink to the returned value. +The default policy logs a message to the console to remind the developer to refactor this part of the application to use a Trusted Type object. It also appends details of the use of the default policy, type, and injection sink to the returned value. ```js trustedTypes.createPolicy("default", { diff --git a/files/en-us/web/api/trustedtypepolicyfactory/defaultpolicy/index.md b/files/en-us/web/api/trustedtypepolicyfactory/defaultpolicy/index.md index 85a4c1d09da9dcc..5d2a08217d7b8fa 100644 --- a/files/en-us/web/api/trustedtypepolicyfactory/defaultpolicy/index.md +++ b/files/en-us/web/api/trustedtypepolicyfactory/defaultpolicy/index.md @@ -10,8 +10,7 @@ browser-compat: api.TrustedTypePolicyFactory.defaultPolicy The **`defaultPolicy`** read-only property of the {{domxref("TrustedTypePolicyFactory")}} interface returns the default {{domxref("TrustedTypePolicy")}} or null if this is empty. -> [!NOTE] -> Information about the creation and use of default policies can be found in the [`createPolicy()`](/en-US/docs/Web/API/TrustedTypePolicyFactory/createPolicy#the_default_policy) documentation. +See [The default policy](/en-US/docs/Web/API/Trusted_Types_API#the_default_policy) for more details. ## Value