Trusted Types

1. Introduction

This section is not normative.

Certain classes of vulnerabilities occur when a web application takes a value from an attacker-controlled source (e.g. the document URL parameter, or postMessage channel) and passes that value, without appropriate sanitization to one of the injection sinks - various Web API functions with powerful capabilities.

These types of issues are traditionally difficult to prevent. Applications commonly call those injection sinks with attacker-controlled values without authors realizing it, since it’s not clear if the input was attacker-controlled when invoking the injection sink. Due to the dynamic nature of JavaScript it’s also difficult to ascertain that such pattern is not present in a given program. It is often missed during manual code reviews, and automated code analysis. As an example, if aString contains untrusted data, foo[bar] = aString is a statement that potentially can trigger a vulnerability, depending on a value of foo and bar.

This document focuses on preventing DOM-Based Cross-Site Scripting that occurs when attacker-controlled data reaches § 2.1.2 DOM XSS injection sinks, as that eventually causes execution of the script payload controlled by the attacker. DOM XSS is prevalent in the web applications as there are over 60 different injection sinks (e.g. Element.innerHTML, or Location.href setters).

This document defines Trusted Types - an API that allows applications to lock down 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 dangerous APIs, reducing the attack surface to small, isolated parts of the web application codebase, which are substantially easier to safeguard, monitor and review.

1.1. Goals

• Minimize the likelihood of client-side vulnerabilities that occur when calling powerful Web APIs with untrusted data - for example, minimize the likelihood of DOM XSS.

• Encourage a design in which security decisions are encapsulated within a small part of the application.

• Reduce security review surface for complex web application codebases.

• Allow the detection of vulnerabilities similar to how regular programming errors are detected and surfaced to the developers, with the assist of dynamic and static analysis tools.

1.2. Non-goals

• Prevent, or mitigate the result of injections into server-side generated markup, in specific reflections into the body of the scripts running in a document. To address server-side XSS vectors, we recommend existing solutions like templating systems or CSP script-src.

• Address resource confinement, e.g. to prevent data exfiltration, or connecting to external sources via [Fetch].

• Control subresource loading. Trusted Types aim to allow the authors to control loading resources that can script the current document, but not other subresources.

• Prevent cross-origin JavaScript execution (for example, Trusted Types don’t guard loading new documents with JavaScript code via data: URLs).

• Prevent malicious authors of the web application’s JavaScript code from being able to bypass the restrictions; attempting to protect against malicious authors would result in an overly complex and not-practical design.

1.3. Use cases

• An author maintains a complex web application written in a framework that uses a secure templating system to generate the UI components. The application also depends on 3rd party client-side libraries that perform auxiliary tasks (e.g. analytics, performance monitoring). To ensure that none of these components introduce DOM XSS vulnerabilities, author defines a Trusted Type policy in the templating library and enables the enforcement for the § 2.1.2 DOM XSS injection sinks.

• A large team maintains a complex client-side application. They create a number of Trusted Types policies that satisfy the security requirements for the application. The team consolidates the policy implementations and the safe abstractions that use them in a small number of heavily reviewed files and requires extra approval for commits that affect these files.

  The need to create trusted values to affect injection sinks, combined with additional scrutiny on changes that affect policy code, incents developers to use safe abstractions instead of writing ad-hoc string composition code when interacting with § 2.1.2 DOM XSS injection sinks.

  When considering the risk of DOM XSS, security auditors find a small attack surface; they focus on the small amount of code that crafts the CSP header and provides the safe abstractions, and ignore the bulk of client-side application code.

• An existing web application interacts with the DOM mostly using XSS-safe patterns (i.e. without using § 2.1.2 DOM XSS injection sinks). In a few places, however, it resorts to using risky patterns like loading additional script using JSONP, calling into innerHTML or eval.

  Review finds that those places do not cause XSS (e.g. because user-controlled data is not part of the input to those sinks), but it’s hard to migrate the application off using these patterns.

  As such, CSP cannot be enforced on this application (without resorting to an unsafe version using 'unsafe-eval' 'unsafe-inline'). Additionally, it’s possible some codebase with DOM XSS flaws was not included in a review, or will be introduced in the future.

  To address this risk, the author converts the reviewed parts to using Trusted Types, and enables Trusted Type enforcement. Additional places using the injection sinks, should they exist in the future, are correctly blocked and reported.

• A security team is tasked with assuring that the client-side heavy application code does not contain XSS vulnerabilities. Since the server side code is homogeneous (it’s mostly an API backend), and the application enforces Trusted Types, the review only focuses on the Trusted Type policies and their rules. Later on the reviewed policy names are allowed in the 'trusted-types' CSP directive, safe for the developers to use.

  Any additional code, including the code of often-changing dependencies, can be excluded from the review, unless it creates a Trusted Type policy. Without it, the code cannot cause a DOM XSS.

2. Framework

2.1. Injection sinks

This section is not normative.

An injection sink is a powerful Web API function that should only be called with trusted, validated or appropriately sanitized input. Calling the injection sink with attacker-controlled (i.e. injected) inputs has undesired consequences and is considered a security vulnerability.

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

It’s difficult to determine if a given application contains such a vulnerability (e.g. if it is vulnerable to DOM XSS) only by analyzing the invocations of injection sinks, as their inputs (usually strings) do not carry the information about their provenance. For example, while the application might intentionally call eval() with dynamically created inputs (e.g. for code obfuscation purposes), calling eval() on strings supplied by the attacker is definitely a security vulnerability - but it’s not easy to distinguish one from the other.

This document organizes the injection sinks into groups, based on the capabilities that sinks in a given group have. Enforcement for groups is controlled via trusted-types-sink-group values.

2.1.1. HTML injection sinks

This section is not normative.

HTML injection sinks parse input strings into a DOM tree. Since HTML parsers can create arbitrary elements, including scripts, and set arbitrary attributes, enabling the enforcement of any trusted-types-sink-group also implies enforcing types for HTML injection sinks.

Examples of HTML injection sinks include:

• Functions that parse & insert HTML strings into the document like Element.innerHTML, Element.outerHTML setter, or Document.write.

• Functions that create a new same-origin Document with caller-controlled markup like parseFromString(),

2.1.2. DOM XSS injection sinks

This section is not normative.

DOM XSS injection sinks evaluate an input string value in a way that could result in DOM XSS if that value is untrusted.

Examples of include:

• Setters for Element attributes that accept a URL of the code to load like HTMLScriptElement.src,

• Setters for Element attributes that accept a code to execute like HTMLScriptElement.text,

• Functions that execute code directly like eval,

• Navigation to 'javascript:' URLs.

Guarding DOM XSS injection sinks is controlled by the trusted-types-sink-group named 'script'.

2.2. Trusted Types

To allow the authors to control values reaching injection sinks, we introduce § 2.2 Trusted Types. 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 unforgeable 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,Worker)]
interface TrustedHTML {
  stringifier;
  DOMString toJSON();
  static TrustedHTML fromLiteral(object templateStringsArray);
};

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.

toJSON() method steps and the stringification behavior steps of a TrustedHTML object are to return the value from its [[Data]] internal slot.

The fromLiteral(object templateStringsArray) method, when invoked, returns the result of executing a Create a Trusted Type from literal algorithm, with TrustedHTML as type and templateStringsArray as template.

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,Worker)]
interface TrustedScript {
  stringifier;
  DOMString toJSON();
  static TrustedScript fromLiteral(object templateStringsArray);
};

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.

toJSON() method steps and the stringification behavior steps of a TrustedScript object are to return the value from its [[Data]] internal slot.

The fromLiteral(object templateStringsArray) method, when invoked, returns the result of executing a Create a Trusted Type from literal algorithm, with TrustedScript as type and templateStringsArray as template.

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,Worker)]
interface TrustedScriptURL {
  stringifier;
  USVString toJSON();
  static TrustedScriptURL fromLiteral(object templateStringsArray);
};

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.

toJSON() method steps and the stringification behavior steps of a TrustedScriptURL object are to return the value from its [[Data]] internal slot.

The fromLiteral(object templateStringsArray) method, when invoked, returns the result of executing a Create a Trusted Type from literal algorithm, with TrustedScriptURL as type and templateStringsArray as template.

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.

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 injection sink, and hence code that creates a 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 authors to create them via policies.

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

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: Trusted Type objects can only be created via policies. If enforcement is enabled, only the policy code can trigger an action of an injection sink and hence call-sites of the policies' create* functions are the only security-sensitive code in the entire program with regards to the actions of the injection sinks. Only this typically small subset of the entire code base needs to be security-reviewed - there’s no need to monitor or review the injection sinks themselves, as User Agents enforce that those sinks will only accept matching 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).

(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 trustedTypes property on the global object - see § 4.3.1 Extensions to the WindowOrWorkerGlobalScope interface.

[Exposed=(Window,Worker)] interface TrustedTypePolicyFactory {
    TrustedTypePolicy createPolicy(
        DOMString policyName, optional TrustedTypePolicyOptions policyOptions = {});
    boolean isHTML(any value);
    boolean isScript(any value);
    boolean isScriptURL(any value);
    readonly attribute TrustedHTML emptyHTML;
    readonly attribute TrustedScript emptyScript;
    DOMString? getAttributeType(
        DOMString tagName,
        DOMString attribute,
        optional DOMString elementNs = "",
        optional DOMString attrNs = "");
    DOMString? getPropertyType(
        DOMString tagName,
        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.

anElement.innerHTML = trustedTypes.emptyHTML; // no need to create a policy

// With native Trusted Types support eval(trustedTypes.emptyScript) will execute and return falsy undefined.
// Without it, eval(trustedTypes.emptyScript) will return a truthy Object.
const supportsTS = !eval(trustedTypes.emptyScript);

eval(supportsTS ? myTrustedScriptObj : myTrustedScriptObj.toString());

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,Worker)]
interface TrustedTypePolicy {
  readonly attribute DOMString name;
  TrustedHTML createHTML(DOMString input, any... arguments);
  TrustedScript createScript(DOMString input, any... arguments);
  TrustedScriptURL createScriptURL(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.

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;
   CreateScriptURLCallback? createScriptURL;
};
callback CreateHTMLCallback = DOMString (DOMString input, any... arguments);
callback CreateScriptCallback = DOMString (DOMString input, any... arguments);
callback CreateScriptURLCallback = USVString (DOMString input, any... arguments);

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 non trusted string value, Trusted Type of the sink and the sink type, respectively.

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 reject a value if a safe value cannot be created. Errors thrown from within a policy are propagated to the application.

If the default policy doesn’t exist, or if its appropriate create* function returns null or undefined, it will cause a CSP violation. In the enforcing mode, an error will be thrown, but in report-only the original value passed to the default policy will be used.

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 bypass the security restrictions in unknown parts of the application. In an extreme case, a lax, no-op default policy defeats all the benefits of using Trusted Types to protect access to injection sinks. 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.5 Get Trusted Type compliant string for details on how the default policy is applied.

// Content-Security-Policy: trusted-types default; require-trusted-types-for 'script'

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

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

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 secure the access to injection sinks, on top of the JavaScript code using the Trusted Types, the user agent needs to enforce them i.e. assert that the injection sinks from a given group are never called with string values, and Trusted Type values are used instead. This section describes how authors may control this enforcing behavior.

Authors may also control their policies by specifying rules around policy creation.

2.4.1. Content Security Policy

Applications may control Trusted Type enforcement via configuring a Content Security Policy. This document defines new directives that correspond to Trusted Types rules. The require-trusted-types-for directive specifies the injection sinks groups, for which the types should be required. The trusted-types directive controls how policies can be created.

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

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

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. If policyName is default and the factory’s [[DefaultPolicy]] slot value is not empty, throw a TypeError and abort further steps.

4. Let policy be a new TrustedTypePolicy object.

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

6. Let policyOptions be a new TrustedTypePolicyOptions object.

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

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

9. Set policyOptions createScriptURL property to option’s createScriptURL 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. 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"

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. If policy’s name is "default" and the policyValue is null or undefined, return policyValue.

   Note: This is used in a Get Trusted Type compliant string algorithm to signal that a value was rejected.

8. Let dataString be the result of stringifying policyValue.

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

10. If trustedObject is a TrustedScript, set its [[HostDefinedCodeLike]] internal slot value to the value in its [[Data]] slot.

    Note: This adds an integration point with dynamic-code-brand-checks proposal.

11. Return trustedObject.

3.3. Create a Trusted Type from literal

Given a TrustedType type type and an object template, execute the following steps:

1. If check templatedness of template returns false, throw a TypeError.

2. If Get(template, "length") is not equal to 1, throw a TypeError.

3. Let templatedValue be the result of Get(template, 0).

4. If type is TrustedHTML, perform the following steps:

   1. Let templateNode be the results of creating an element given "template", the HTML namespace and current global object's associated Document.

   2. Assert: templateNode is HTMLTemplateElement.

   3. Let fragment be the result of invoking fragment parsing algorithm, with templatedValue as markup, and templateNode as a context element.

   4. Set templatedValue to be the result of invoking HTML fragment serialization algorithm, with fragment as the node.

5. Return a new instance of an interface type, with its [[Data]] internal slot value set to templatedValue.

3.4. Check templatedness of an object

To check templatedness of an object value, perform the following steps. They return a boolean value:

1. Let realm be the current Realm Record.

2. For each item of realm.[[TemplateMap]], if item.[[Array]] is value, return true.

3. Return false.

3.5. Get Trusted Type compliant string

This algorithm will return a string that can be used with an 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), a string (sink) and a string (sinkGroup), run these steps:

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

2. If cspList is null or does not contain a policy which directive set containing a directive with a name "require-trusted-types-for", or that directive does not contain a trusted-types-sink-group which is a match for a value sinkGroup, return stringified input and abort these steps.

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

4. Let convertedInput be the result of executing Process value with a default policy with the same arguments as this algorithm.

5. If the algorithm threw an error, rethrow the error and abort the following steps.

6. If convertedInput is null or undefined, execute the following steps:

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

   2. If disposition is “Allowed”, return stringified input and abort further steps.

      Note: This step assures that the default policy rejection will be reported, but ignored in a report-only mode.

   3. Throw a TypeError and abort further steps.

7. Assert: convertedInput has type expectedType.

8. Return stringified convertedInput.

3.6. Process value with a default policy

This algorithm routes a value to be assigned to an injection sink through a default policy, should one exist.

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

1. Let defaultPolicy be the value of global’s trusted type policy factory's [[DefaultPolicy]] slot. If the slot is empty, return null.

2. 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

   • « trustedTypeName, sink » as arguments

3. If the algorithm threw an error, rethrow it. Otherwise, return convertedInput.

3.7. Prepare the script URL and text

Given an HTMLScriptElement (script), this algorithm performs the following steps:

1. If script does not have a src content attribute, set its [[ScriptURL]] internal slot value to null.

2. Otherwise, if script’s [[ScriptURL]] internal slot value is not equal to its src attribute value, set script’s [[ScriptURL]] to the result of executing Get Trusted Type compliant string, with the following arguments:

   • TrustedScriptURL as expectedType,

   • script’s Document's relevant global object as global,

   • script’s src attribute value as input,

   • HTMLScriptElement src as sink,

   • 'script' as sinkGroup.

   If the algorithm threw an error, rethrow the error and abort further steps.

3. If script’s [[ScriptText]] internal slot value is not equal to its child text content, set script’s [[ScriptText]] to the result of executing Get Trusted Type compliant string, with the following arguments:

   • TrustedScriptURL as expectedType,

   • script’s Document's relevant global object as global,

   • script’s child text content attribute value,

   • HTMLScriptElement text as sink,

   • 'script' as sinkGroup.

   If the algorithm threw an error, rethrow the error.

4. Integrations

typedef [StringContext=TrustedHTML] DOMString HTMLString;
typedef [StringContext=TrustedScript] DOMString ScriptString;
typedef [StringContext=TrustedScriptURL] USVString ScriptURLString;
typedef (TrustedHTML or TrustedScript or TrustedScriptURL) TrustedType;

4.1. Integration with WebIDL

Keep in sync with https://github.com/heycam/webidl/pull/841.

4.2. [StringContext]

This specification defines a new [StringContext] extended attribute.

If the [StringContext] extended attribute appears on DOMString or USVString, it modifies how the value is converted to the IDL type, causing additional value validation to adhere to the context the string is used in.

The [StringContext] extended attribute must take an identifier. The identifier must be one of TrustedHTML, TrustedScript and TrustedScriptURL.

Make sure this is OK, otherwise use strings and convert them to TrustedXYZ in this spec only.

[StringContext] extended attribute may only annotate a type of a regular attribute or a regular operation argument. A type annotated with the [StringContext] extended attribute must not appear in a read only attribute. The regular attribute or a regular operation argument that the type annotated with the [StringContext] extended attribute appears in is its related construct.

A type that is not DOMString or USVString must not be associated with the [StringContext] extended attribute.

See the rules for converting ECMAScript values to the IDL types in Web IDL § 3.2.10 DOMString for the specific requirements that the use of [StringContext] entails.

interface Document {
  undefined write([StringContext=html] DOMString... text);
};

4.2.1. Extended attributes applicable to types

The following extended attributes are applicable to types: [AllowShared], [Clamp], [EnforceRange] , [StringContext] and [LegacyNullToEmptyString].

4.2.2. Type conversion

This specification modifies the algorithm implementing the conversion to DOMString in Web IDL § 3.2.10 DOMString:

An ECMAScript value V is converted to an IDL DOMString value by running the following algorithm:

1. If the conversion is to an IDL type associated with the [StringContext] extended attribute, then set V to the result of validate the string in context, passing this, V, the StringContext extended attribute identifier, and the identifier of the [StringContext] extended attribute related construct.

   Note: That algorithm may throw a TypeError.

2. If V is null and the conversion is to an IDL type associated with the [LegacyNullToEmptyString] extended attribute, then return the DOMString value that represents the empty string.

3. Let x be ToString(V).

4. Return the IDL DOMString value that represents the same sequence of code units as the one the ECMAScript String value x represents.

4.2.3. Validate the string in context

This specification adds a following section to Web IDL § 3.5 Security.

Certain algorithms in Web IDL § 3.2 ECMAScript type mapping are defined to validate the string in context on a given value. This check is used to determine whether a given value is appropriate for its StringContext. This validation takes the following four inputs:

1. the platform object on which the operation invocation or attribute access is being done,

2. the value to validate,

3. the StringContext identifier, and

4. the identifier of the operation or attribute.

The algorithm returns an ECMAScript String value, or throws a TypeError.

Note: The HTML Standard defines how the validation is performed. [HTML]

4.3. Integration with HTML

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

4.3.1. Extensions to the WindowOrWorkerGlobalScope interface

This document extends the WindowOrWorkerGlobalScope interface defined by HTML:

partial interface mixin WindowOrWorkerGlobalScope {
  readonly attribute TrustedTypePolicyFactory trustedTypes;
};

The trustedTypes getter steps are to return this's relevant global object's trusted type policy factory.

4.3.2. Extensions to the Document interface

This document modifies the Document interface defined by HTML:

partial interface Document {
  [CEReactions] undefined write(HTMLString... text);
  [CEReactions] undefined writeln(HTMLString... text);
};

4.3.3. Enforcement for scripts

4.3.3.1. Slots with trusted values

Figure out if we can drop [[ScriptURL]] slot after IDL + DOM changes.

This document modifies HTMLScriptElements. Each script has:

[[ScriptURL]] internal slot.

A string, containing the URL to execute the script from that was set through a StringContext compliant sink. Equivalent to src attribute value. Initially null.

[[ScriptText]] internal slot.

A string, containing the body of the script to execute that was set through a StringContext compliant sink. Equivalent to script’s child text content. Initially null.

4.3.3.2. Setting slot values

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 StringContext extended attribute presence.

Note: Using these IDL attributes is the recommended way of dynamically setting URL or a text of a script. Manipulating attribute nodes or text nodes directly will call a default policy on the final value when the script is prepared.

Figure out what to do with script.setAttribute('src'). See DOM#789.

partial interface HTMLScriptElement {
 [CEReactions] attribute [LegacyNullToEmptyString] ScriptString innerText;
 [CEReactions] attribute ScriptString? textContent;
 [CEReactions] attribute ScriptURLString src;
 [CEReactions] attribute ScriptString text;
};

On setting, the innerText, textContent and text IDL attributes perform the regular steps, and then set [[ScriptText]] internal slot value with the stringified value.

On setting, the src IDL attribute performs the usual steps, and then sets [[ScriptURL]] internal slot value to its src content attribute value.

4.3.3.3. Slot value verification

The first few steps of the prepare the script element algorithm are modified as follows:

1. If el’s already started is true, then return.

2. Let parser document be el’s parser document.

3. Set el’s parser document to null.

   This is done so that if parser-inserted script elements fail to run when the parser tries to run them, e.g. because they are empty or specify an unsupported scripting language, another script can later mutate them and cause them to run again.

4. If parser document is non-null and el does not have an async attribute, then set el’s force async to true.

   This is done so that if a parser-inserted script element fails to run when the parser tries to run it, but it is later executed after a script dynamically updates it, it will execute in an async fashion even if the async attribute isn’t set.

5. Execute the Prepare the script URL and text algorithm on el. If that algorithm threw an error, then return.

6. Let source text be el’s child text content. [[ScriptText]] internal slot value.

7. ...

In all subsequent steps, replace checks for src attribute existence with checks for non-null [[ScriptURL]] internal slot value, and replace references of src content attribute value with [[ScriptURL]] internal slot value. For example:

• If el does not have a src content attribute el’s [[ScriptURL]] internal slot value is null , and the Should element’s inline behavior be blocked by Content Security Policy? algorithm returns "Blocked" when given el, "script", and source text, then return.
• If el 's has a src content attribute [[ScriptURL]] internal slot value is not null , then:

• Let src be the value of el’s src attribute [[ScriptURL]] internal slot .

4.3.4. Enforcement in element attributes

This document modifies following IDL attributes of various DOM elements:

partial interface HTMLIFrameElement {
  [CEReactions] attribute HTMLString srcdoc;
};

partial interface HTMLEmbedElement {
  [CEReactions] attribute ScriptURLString src;
};

partial interface HTMLObjectElement {
  [CEReactions] attribute ScriptURLString data;
  [CEReactions] attribute ScriptURLString codeBase; // obsolete
};

4.3.5. 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 this value’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.

   • sinkGroup set to 'script'.

     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.3.6. 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,

   • 'script' as sinkGroup

   • 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 SVG 2 § 15.9 Event attributes.

// Content-Security-Policy: require-trusted-types-for 'script'

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

4.3.7. Validate the string in context

This specification defines the validate the string in context algorithm in HTML § 7.2.1 Integration with IDL.

When validate the string in context is invoked, with platformObject, value, stringContext, and identifier run these steps:

1. If platformObject’s relevant global object has a trusted type policy factory:

   1. Set sink to the result of concatenating the list « platformObject’s identifier, identifier » with " " as separator.

      For example, the following annotation and JavaScript code:

      typedef [StringContext=TrustedHTML] DOMString HTMLString;
      [ Exposed=Window, HTMLConstructor] interface HTMLIFrameElement : HTMLElement {
          attribute HTMLString srcdoc;
      };
      

      document.createElement('iframe').srcdoc = foo;
      document.createElement('iframe').setAttribute('SRCdoc', foo);
      

      causes the sink value to be "HTMLIFrameElement srcdoc".

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

      • value as input,

      • stringContext as expectedType,

      • sink as sink,

      • 'script' as sinkGroup,

      • platformObject’s relevant global object as global.

      Remove hardcoding 'script' when new sink groups are specified.

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

2. Return value.

4.3.8. Web Workers

This specification modifies the Worker constuctors and importScripts function to require ScriptURLString.

[Exposed=(Window,Worker)]
partial interface Worker : EventTarget {
    constructor(ScriptURLString scriptURL, optional WorkerOptions options = {});
};

[Exposed=(Window,Worker)]
partial interface SharedWorker : EventTarget {
  constructor(ScriptURLString scriptURL, optional (DOMString or WorkerOptions) options = {});
};

[Exposed=Worker]
partial interface WorkerGlobalScope : EventTarget {
  undefined importScripts(ScriptURLString... urls);
};

4.4. Integration with Service Workers

This document modifies the IDL for registering service workers, requiring ScriptURLString:

[SecureContext, Exposed=(Window,Worker)]
partial interface ServiceWorkerContainer : EventTarget {
   [NewObject] Promise<ServiceWorkerRegistration> register(ScriptURLString scriptURL, optional RegistrationOptions options = {});
};

4.5. Integration with SVG

This document modifies the SVGAnimatedString interface to enforce Trusted Types:

[Exposed=Window]
partial interface mixin SVGAnimatedString {
           attribute (DOMString or TrustedScriptURL) baseVal;
};

On setting baseVal, the following steps are run:

1. If the reflected attribute’s element is a SVGScriptElement, set value to the result of executing Get Trusted Type compliant string algorithm, with the following arguments:
   • TrustedScriptURL as expectedType,
   • reflected attribute’s Document's relevant global object as global,
   • specified value as input,
   • SVGScriptElement href as sink,
   • 'script' as sinkGroup.
   Otherwise, set value to the specified value.

2. If the reflected attribute is not present, the SVGAnimatedString object is defined to additionally reflect a second, deprecated attribute, and that deprecated attribute is present, then set that deprecated attribute to the specified value value . Otherwise, set the reflected attribute to value the specified value .

Note: SVG does not have a complete script processing model yet. Trusted Types assumes that the attribute and text body modification protections behave similarly to ones for HTML scripts outlined in § 4.3.3 Enforcement for scripts.

4.6. Integration with DOM

This document modifies the Element interface, adding attribute validation steps:

This and other specifications may define attribute validation steps for elements. The algorithm is passed element, localName, value, and namespace.

This document changes the handle attribute changes algorithm, adding the following step at the beginning:

1. Run the attribute validation steps with element, attribute’s local name, newValue and attribute’s namespace. If this throws an exception, then rethrow the exception and abort further steps.

Additionally, this document changes the append an attribute algorithm:

To append an attribute attribute to an element element with a value , run these steps:

1. Handle attribute changes for attribute with element, null, and attribute’s value value .

2. Set attribute’s value to value.

3. Append attribute to element’s attribute list.

4. Set attribute’s element to element.

Callers of this algorithm are changed accordingly.

Remove when DOM #809 is merged.

4.7. Integration with DOM Parsing

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

partial interface Element {
  [CEReactions, LegacyNullToEmptyString] attribute HTMLString outerHTML;
  [CEReactions] undefined insertAdjacentHTML(DOMString position, HTMLString text);
};

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

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

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

4.8. Integration with execCommand

This document modifies the following interfaces defined by the unofficial execCommand document:

partial interface Document {
    [CEReactions, RaisesException] boolean execCommand(DOMString commandId, optional boolean showUI = false, optional (DOMString or TrustedHTML) value = "");
};

The implementation of the insertHTML execCommand passes the unmodified value from its third argument instance to the createContextualFragment() algorithm.

4.9. Integration with Content Security Policy

4.9.1. require-trusted-types-for directive

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

require-trusted-types-for directive configures the Trusted Types framework for all the injection sinks of certain groups in a current realm. Specifically, it defines what should be the behavior when a string value is passed to an injection sink of a given group (i.e. should the type-based enforcement be enabled for such sinks).

Note: Currently, only the enforcement for § 2.1.2 DOM XSS injection sinks is specified.

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

directive-name = "require-trusted-types-for"
directive-value = trusted-types-sink-group *( required-ascii-whitespace trusted-types-sink-group)
trusted-types-sink-group = "'script'"

Content-Security-Policy: require-trusted-types-for 'script'

4.9.1.1. require-trusted-types-for Pre-Navigation check

Given a request (request), a string navigation type and a policy (policy), this algorithm returns "Blocked" if a navigation violates the require-trusted-types-for directive’s constraints and "Allowed" otherwise. This constitutes the require-trusted-types-for directive’s pre-navigation check:

Note: This algorithm assures that the code to be executed by a navigation to a javascript: URL will have to pass through a default policy’s createScript function, in addition to all other restrictions imposed by other CSP directives.

1. If request’s url's scheme is not "javascript", return "Allowed" and abort further steps.

2. Let urlString be the result of running the URL serializer on request’s url.

3. Let encodedScriptSource be the result of removing the leading "javascript:" from urlString.

4. Let convertedScriptSource be the result of executing Process value with a default policy algorithm, with the following arguments:

   • TrustedScript as expectedType

   • request’s clients's global object as global

   • encodedScriptSource as input

   • "Location href" as sink

   If that algorithm threw an error or convertedScriptSource is not a TrustedScript object, return "Blocked" and abort further steps.

5. Set urlString to be the result of prepending "javascript:" to stringified convertedScriptSource.

6. Let newURL be the result of running the URL parser on urlString. If the parser returns a failure, return "Blocked" and abort further steps.

7. Set request’s url to newURL.

   Note: No other CSP directives operate on javascript: URLs in a pre-navigation check. Other directives that check javascript: URLs will operate on the modified URL later, in the inline check.

8. Return "Allowed".

4.9.2. trusted-types directive

This document defines trusted-types - a new Content Security Policy directive. The trusted-types directive controls the creation of Trusted Type policies.

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  / tt-keyword / tt-wildcard
tt-wildcard = "*"
tt-policy-name = 1*( ALPHA / DIGIT / "-" / "#" / "=" / "_" / "/" / "@" / "." / "%")
tt-keyword = "'allow-duplicates'" / "'none'"

Content-Security-Policy: require-trusted-types-for 'script'; trusted-types one two

Content-Security-Policy: trusted-types; require-trusted-types-for 'script'

Keyword 'allow-duplicates' allows for creating policies with a name that was already used.

Content-Security-Policy: trusted-types foo bar 'allow-duplicates'

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.9.3. Should sink type mismatch violation be blocked by Content Security Policy?

Given a global object (global), a string (sink), a string (sinkGroup) 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 "require-trusted-types-for", skip to the next policy.

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

   3. If directive’s value does not contain a trusted-types-sink-group which is a match for a value sinkGroup, skip to the next policy.

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

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

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

   7. Set violation’s sample to be the result of concatenating the list « sink, trimmedSource « using "|" as a separator.

   8. Execute Report a violation on violation.

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

3. Return result.

4.9.4. 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 TrustedTypePolicy 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 only contains a tt-keyword which is a match for a value 'none', set createViolation to true.

      Note: Like in other CSP directives, 'none' keyword will be ignored if other keywords or policy names are present.

   5. If createdPolicyNames contains policyName and directive’s value does not contain a tt-keyword which is a match for a value 'allow-duplicates', set createViolation to true.

      Note: trusted-types policyA policyB 'allow-duplicates' allows authors to create policies with duplicated names.

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

      Note: trusted-types * allows authors to create policies with any unique names. To allow for multiple policies with the same name, use trusted-types * 'allow-duplicates' or don’t set the trusted-types directive at all.

   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.9.5. Violation object changes

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

4.9.6. Support for dynamic code compilation

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

Note: This is based on dynamic-code-brand-checks and assumes additional arguments are passed to this algorithm from ECMAScript. See also TC39/ecma262 issue #938.

let f = new self.top.Function(source);

// 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)')()

Given a realm (calleeRealm), a string (source) , a boolean wasCodeLike and a string compilationSink , this algorithm returns normally the source string to compile if compilation is allowed, and throws an "EvalError" if not:

1. If wasCodeLike is true, let sourceToValidate be a new instance of the TrustedScript interface, with its [[Data]] internal slot value set to source. Otherwise, let sourceToValidate be source.
2. Let sourceString be the result of executing the Get Trusted Type compliant string algorithm, with:

   • calleeRealm as global,

   • sourceToValidate as input,

   • compilationSink as sink,

   • 'script' as sinkGroup,

   • TrustedScript as expectedType.

3. If the algorithm throws an error, throw an EvalError.

4. Let global be a calleeRealm’s global object.

5. Let result be "Allowed".

6. 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'" then:

      1. Let violation be the result of executing Content Security Policy § 2.4.1 Create a violation object for global, policy, and directive 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 § 5.5 Report a violation on violation.

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

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

8. 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.

5. Security Considerations

Trusted Types are not intended to protect access to injection sinks 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. In an extreme case, the restricted document might create a Blob from strings and navigate to it.

CSP propagation rules (see Content Security Policy § 7.8 CSP Inheriting to avoid bypasses partially address this issue, as new local scheme documents will inherit the same set of restrictions, so - for example - script-src restrictions could be used to make sure injections into Blob contents would not execute scripts. 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 platform features are not subject to Trusted Types, and could potentially be used by malicious authors to overcome the restrictions:

• HTML imports

5.3. Plugin navigation

Plugin content may have access to the document that embeds it (or; more broadly, to the origin it was served from), often giving it the same capabilities as DOM XSS. That’s why Trusted Types limit HTMLEmbedElement's src to TrustedScriptURL.

However, it is also possible to navigate an existing object / embed to an arbitrary location, bypassing the TrustedScriptURL restriction.

Since plugin content in the web in general is being phased out for other security reasons, and their navigation model is in flux, we recommend authors to prevent that bypass vector by limiting the plugins altogether with object-src. For example: Content-Security-Policy: object-src: none.

5.4. Script gadgets

While Trusted Types logic is called on many operations that results in creating DOM trees from string, it should not be treated as a mechanism for guarding all DOM tree creation in a document. This is important especially in the presence of script gadgets, where an application reacts to contents of usually benign DOM elements or attributes. Developers using DOM API directly can trigger such gadgets without using Trusted Types. However, in order for the gadget to trigger DOM XSS, it needs to obtain a Trusted Type value via a policy. Authors need to ascertain that the data passed to Trusted Type policies is indeed trustworthy, if the policy rules don’t enforce constraints or validate the data themselves.

5.5. Best practices for policy design

Trusted Types limit the scope of the code that can introduce vulnerabilities via injection sinks to the implementation of policies. In this design, insecure policies can still expose injection sinks to untrusted data. 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. Privacy Considerations

The specification may partially observe and alter the behavior of scripts running within the application, e.g. causing certain operations on injection sinks to fail, or monitoring and changing their effect with a default policy. However, early-running scripts already have this capability by overriding appropriate property descriptors.

It is possible for the application to report violations of Trusted Types restrictions. Violation reports would include the trimmed-down payload passed to the injection sink (40 characters, including the sink name). These feature is reusing the Content Security Policy reporting mechanisms.

7. Implementation Considerations

7.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 injection sinks without triggering default policy execution, violation generation, or the rejection of the value.