Sanitizer API

The Sanitizer API is a browser-native API designed to provide a safe, easy-to-use, and browser-maintained way to sanitize HTML strings. Its primary purpose is to prevent accidental JavaScript execution when rendering user-generated content or client-side templates. By being part of the web platform, the API is updated alongside the browser's parser, ensuring protection against new attack vectors without requiring manual library updates.

Key Characteristics:

• User Input Sanitization: Converts potentially unsafe HTML strings into safe versions that do not trigger inadvertent script execution.
• Browser-Maintained: As an "ever-green" part of the web platform, it benefits from automatic updates to the browser's security and parsing logic.
• Safe Defaults: Designed with a small API surface and sensible defaults to make common sanitization tasks easy and secure by default.

Note on Status: The API is currently being incubated and is not yet finalized. It is moving toward being part of the WHATWG HTML specification.

The Sanitizer API provides two sets of methods for handling HTML: 'safe' methods and 'unsafe' methods.

• Safe methods (setHTML, parseHTML): These remove all script-y content defined by the platform while letting the rest pass. They are designed to prevent XSS.
• Unsafe methods (setHTMLUnsafe, parseHTMLUnsafe): These do not perform sanitization and allow all content, including scripts, to pass through.

Context Awareness:

• setHTML and parseHTML observe the context of the node they are called on. For example, parsing a <tr> inside a <table> element will correctly wrap it in a <tbody>, whereas parsing it on a <div> will result in the row being stripped or flattened depending on the context.
• Security Note: If you call setHTML on a <script> element, it is treated as a no-op to prevent the accidental creation of new script content.

const example = `<b onclick="alert(1)">hello world</b>`;
const element = document.createElement("div");

// Safe: removes the onclick attribute
element.setHTML(example);  // <div><b style="...">hello world</b></div>

// Unsafe: keeps the onclick attribute
element.setHTMLUnsafe(example); // <div><b onclick="alert(1)">hello world</b></div>

// Return a Document instance:
Document.parseHTML(example);  // <html>...<body><b...>...</body></html>

The Sanitizer object is mutable. You can create a base configuration and then use specialized methods to add or remove rules. This is more performant than recreating a new Sanitizer object in a loop.

Available Methods:

• allowElement(x): Adds an element to the allow-list. If x is a dictionary, you can also specify attributes or removeAttributes for that element.
• removeElement(x): Adds an element to the remove-list.
• replaceElementWithChildren(x): Adds an element to the replaceWithChildrenElements list.
• allowAttribute(x): Adds an attribute to the allow-list.
• removeAttribute(x): Adds an attribute to the remove-list.
• setComments(bool): Enables or disables HTML comment nodes.
• setDataAttributes(bool): Enables or disables data attributes.

Note: Adding an item to an allow-list automatically removes it from any existing remove-lists for that type.

const s = new Sanitizer({ elements: ["div", "p", "b"] });
s.allowElement("span");
s.removeElement("b");

// To set element-specific attributes (overwrites previous settings for that element):
s.allowElement({name: "div", attributes: ["id", "class"]});

You can control what the sanitizer allows or removes using the Sanitizer constructor. There are two primary strategies:

1. Allow-list approach: Specify exactly which elements and attributes are permitted. Everything else is removed.
2. Remove-list approach: Specify which removeElements and removeAttributes should be stripped. Everything else is kept (based on platform defaults).

Important Rules:

• You cannot mix an allow-list and a remove-list for the same category (e.g., you cannot have both elements and removeElements in the same config; doing so throws a TypeError).
• You can combine allow-lists with replaceWithChildrenElements lists.

// Allow-list: Only these 5 elements and the 'class' attribute are allowed
const config_allow_some_formatting = new Sanitizer({
  elements: [ "div", "p", "em", "b", "img" ],
  attributes: [ "class" ]
});

// Remove-list: Allows defaults, but strips <style> and 'class'/'style' attributes
const config_disallow_style_definitions = new Sanitizer({
  removeElements: [ "style" ],
  removeAttributes: [ "class", "style" ]
});

The Sanitizer API provides methods to parse and filter HTML strings to prevent XSS (Cross-Site Scripting) attacks. The API is divided into 'safe' methods that enforce a security baseline and 'unsafe' methods that allow arbitrary content if configured to do so.

Safe Methods (Enforce XSS Baseline)

These methods apply a filter and ensure a secure baseline is maintained (e.g., dropping javascript: URLs even if not explicitly configured).

• Element.setHTML(string, {options}): Parses the string using the current element as the context (similar to innerHTML) and replaces the element's children with the sanitized results.
• Document.parseHTML(string, {options}): A static method that creates a new Document instance, parses the string, applies a filter, and returns the document.

Unsafe Methods (No Default Baseline)

These methods do not enforce a security baseline. If no filter is provided in the options, no filtering occurs.

• Element.setHTMLUnsafe(string, {options}): Similar to setHTML, but allows elements like <script> if the filter is configured to permit them.
• Document.parseHTMLUnsafe(string, {options}): A static method that parses the string into a new document without enforcing a baseline or applying a default filter.

// Example of safe usage on an element
const container = document.querySelector('#container');
container.setHTML('<img src=x onerror=alert(1)>', { /* options */ });

// Example of parsing into a new document safely
const doc = Document.parseHTML('<div>Hello</div>', { /* options */ });

// Example of unsafe usage (allows scripts if configured)
const unsafeContainer = document.querySelector('#unsafe');
unsafeContainer.setHTMLUnsafe('<script>alert(1)</script>', { /* options */ });