CharacterData: beforeHTMLUnsafe() method

Syntax

beforeHTMLUnsafe(input)
beforeHTMLUnsafe(input, options)

Parameters

input

A TrustedHTML instance or string defining HTML to be parsed.

options Optional

An options object with the following optional parameters:

sanitizer Optional

A Sanitizer or SanitizerConfig object that defines what elements of the input will be allowed or removed. This can also be a string with the value "default", which applies a Sanitizer with the (XSS-safe) default sanitizer configuration. If not specified, no sanitizer is used.

Note that if you're using the same configuration multiple times, it's expected to be more efficient to use a Sanitizer and modify it when you need to.

runScripts Optional

A boolean value indicating whether any scripts included in the newly inserted HTML should run after inserting. The default is false.

Return value

None (undefined).

Exceptions

TypeError

This is thrown if:

• input is passed a string when Trusted Types are enforced by a CSP and no default policy is defined.
• options.sanitizer is passed a:
  • SanitizerConfig that isn't valid. For example, a configuration that includes both "allowed" and "removed" configuration settings.
  • string that does not have the value "default".
  • value that is not a Sanitizer, SanitizerConfig, or string.
• options.runScripts is true or options.sanitizer is specified when Trusted Types are enforced and no default policy defines createParserOptions — even if input is a TrustedHTML. (Passing a TrustedHTMLParserOptions as options avoids this.)

HierarchyRequestError DOMException

Thrown when the parent element is a Document, an <html> element, a <template> element, or a hostless DocumentFragment.

Description

The beforeHTMLUnsafe() method is used to parse an HTML input into a DocumentFragment, optionally sanitizing it of unwanted elements and attributes, and discarding elements that the HTML specification doesn't allow in the target element (<col> element outside of a <table>). The DocumentFragment is then used to insert into the DOM immediately after the node.

Unlike with Element.innerHTML, declarative shadow roots in the input will be parsed into the DOM. If the string of HTML defines more than one declarative shadow root in a particular shadow host then only the first ShadowRoot is created — subsequent declarations are parsed as <template> elements within that shadow root.

beforeHTMLUnsafe() doesn't perform any sanitization by default, though also does not run scripts by default. If no sanitizer is passed as a parameter, all HTML entities in the input will be injected. It is therefore potentially even less safe than Element.innerHTML, which does not allow <script> execution when parsing.

Related HTML setter APIs

This is part of a series of APIs to set HTML in CharacterData:

Each API type takes the same arguments but allows for ease of inserting the required HTML in the appropriate place and with or without the default sanitizer applied. The unsafe variants allows scripts to be run using the runScripts options.

Similar methods, and more, exist on Element (for example Element.beforeHTMLUnsafe).

Security considerations

The suffix "Unsafe" in the method name indicates that it does not enforce removal of all XSS-unsafe HTML entities (unlike Element.beforeHTML()). While it can do so if used with an appropriate sanitizer, it doesn't have to use an effective sanitizer, or any sanitizer at all! The method is therefore a possible vector for cross-site scripting (XSS) attacks, where potentially unsafe strings provided by a user are injected into the DOM without first being sanitized.

You should mitigate this risk by always passing TrustedHTML objects instead of strings, and enforcing trusted types using the require-trusted-types-for CSP directive. This ensures that the input is passed through a transformation function, which has the chance to sanitize the input to remove potentially dangerous markup (such as <script> elements and event handler attributes), before it is injected.

Using TrustedHTML makes it possible to audit and check that sanitization code is effective in just a few places, rather than scattered across all your injection sinks. You should not have to pass a sanitizer to the method when using TrustedHTML.

If for any reason you can't use TrustedHTML (or even better, beforeHTML()) then the next safest option is to use beforeHTMLUnsafe() with the default sanitizer configuration.

When should beforeHTMLUnsafe() be used?

beforeHTMLUnsafe() should almost never be used if CharacterData.beforeHTML() is available, because there are very few (if any) cases where user-provided HTML input should need to include XSS-unsafe elements. Not only is beforeHTML() safe, but it avoids having to consider trusted types.

Using beforeHTMLUnsafe() might be appropriate if:

• You can't use beforeHTML() or trusted types (for whatever reason) and you want to have the safest possible filtering. In this case you might use beforeHTMLUnsafe() with the default Sanitizer to filter all XSS-unsafe elements.

• You can't use beforeHTML() and the input might contain declarative shadow roots, so you can't use Element.innerHTML.

• You have an edge case where you have to allow HTML input that includes a known set of unsafe HTML entities.

  You can't use beforeHTML() in this case, because it strips all unsafe entities. You could use beforeHTMLUnsafe() without a sanitizer or innerHTML, but that would allow all unsafe entities.

  A better option here is to call beforeHTMLUnsafe() with a sanitizer that allows just those dangerous elements and attributes we actually need. While this is still unsafe, it is safer than allowing all of them.

For the last point, consider a situation where your code relies on being able to use unsafe onclick handlers. The following code shows the effect of the different methods and sanitizers for this case.

const myText = document.querySelector("#myText").firstChild;

const input = "<img src=x onclick=alert('onclick') onerror=alert('onerror')>";

// Safe - removes all XSS-unsafe entities.
myText.beforeHTML(input);

// Removes no event handler attributes
myText.beforeHTMLUnsafe(input);

// Safe - removes all XSS-unsafe entities.
const configSafe = new Sanitizer();
myText.beforeHTMLUnsafe(input, { sanitizer: configSafe });

// Removes all XSS-unsafe entities except `onclick`
const configLessSafe = new Sanitizer();
configLessSafe.allowAttribute("onclick");
myText.beforeHTMLUnsafe(input, { sanitizer: configLessSafe });

Examples

beforeHTMLUnsafe() with Trusted Types

To mitigate the risk of XSS, we'll first create a TrustedHTML object from the string containing the HTML, and then pass that object to beforeHTMLUnsafe(). Since trusted types are not yet supported on all browsers, we define the trusted types tinyfill. This acts as a transparent replacement for the Trusted Types JavaScript API:

if (typeof trustedTypes === "undefined")
  trustedTypes = { createPolicy: (n, rules) => rules };

Next we create a TrustedTypePolicy that defines a createHTML() for transforming an input string into TrustedHTML instances. Commonly implementations of createHTML() use a library such as DOMPurify to sanitize the input as shown below:

const policy = trustedTypes.createPolicy("my-policy", {
  createHTML: (input) => DOMPurify.sanitize(input),
});

Then we use this policy object to create a TrustedHTML object from the potentially unsafe input string:

// The potentially malicious string
const untrustedString = "abc <script>alert(1)<" + "/script> def";
// Create a TrustedHTML instance using the policy
const trustedHTML = policy.createHTML(untrustedString);

Now that we have trustedHTML, the code below shows how you can use it with beforeHTMLUnsafe(). The input has been through the transformation function, so we don't pass a sanitizer to the method.

// Get the myText Element with id "myText"
const myText = document.getElementById("myText").firstChild;

// beforeHTMLUnsafe() with no sanitizer
myText.beforeHTMLUnsafe(trustedHTML);

Using beforeHTMLUnsafe() without Trusted Types

This example demonstrates the case where we aren't using trusted types, so we'll be passing sanitizer arguments.

The code creates an untrusted string and shows a number of ways a sanitizer can be passed to the method.

// The potentially malicious string
const untrustedString = "abc <script>alert(1)<" + "/script> def";

// Get the myText Element with id "myText"
const myText = document.getElementById("myText").firstChild;

// Define custom Sanitizer and use in beforeHTMLUnsafe()
// This allows only elements: div, p, button, script
const sanitizer1 = new Sanitizer({
  elements: ["div", "p", "button", "script"],
});
myText.beforeHTMLUnsafe(untrustedString, { sanitizer: sanitizer1 });

// Define custom SanitizerConfig within beforeHTMLUnsafe()
// Removes the <script> element but allows other potentially unsafe entities.
myText.beforeHTMLUnsafe(untrustedString, {
  sanitizer: { removeElements: ["script"] },
});

Using beforeHTMLUnsafe() with runScripts

This example demonstrates the case when we allow scripts to run using the runScripts option.

// The potentially malicious string
const untrustedString = "<em>Other content</em>";

// Get the myText Element with id "myText"
const myText = document.getElementById("myText").firstChild;

// No sanitizer is passed, so the <script> element is kept
// and also executes the script after insertion.
myText.beforeHTMLUnsafe(untrustedString, {
  runScripts: true,
});

Specifications

Browser compatibility

See also

• CharacterData.beforeHTML()
• Element.beforeHTML() and Element.beforeHTMLUnsafe()
• Element.setHTMLUnsafe()
• Element.innerHTML
• Document.parseHTML() and Document.parseHTMLUnsafe()