CharacterData node and its
replace data algorithmThe following features are defined in UI Events: UIEVENTS
@@ -4528,11 +4530,50 @@ a.setAttribute('href', 'https://example.com/'); // change the content attributeannotation-xml elementmath elementmerror elementmfrac elementmi elementmmultiscripts elementmn elementmo elementmover elementmpadded elementmphantom elementmprescripts elementmroot elementmrow elementms elementmspace elementmsqrt elementmstyle elementmsub elementmsubsup elementmsup elementmtable elementmtd elementmtext elementmtr elementmunder elementmunderover elementsemantics elementaccent attributeaccentunder attributecolumnspan attributedepth attributefence attributeform attributeheight attributelargeop attributelspace attributemaxsize attributeminsize attributemovablelimits attributerowspan attributerspace attributeseparator attributestretchy attributesymmetric attributevoffset attributewidth attributeSVGImageElement interfaceSVGScriptElement interfaceSVGSVGElement interfacea elementdesc elementforeignObject elementimage elementscript elementsvg elementtitle elementuse elementa elementanimate elementanimateTransform elementcircle elementdefs elementdesc elementellipse elementforeignObject elementg elementimage elementline elementmarker elementmetadata elementpath elementpolygon elementpolyline elementrect elementscript elementset elementsvg elementtext elementtextPath elementtitle elementtspan elementuse elementaction attributeattributeName attributecx attributecy attributed attributedx attributedy attributeformaction attributeheight attributehref attributelengthAdjust attributemarkerHeight attributemarkerUnits attributemarkerWidth attributemethod attributeorient attributepath attributepathLength attributepoints attributepreserveAspectRatio attributer attributerefX attributerefY attributerotate attributerx attributery attributeside attributespacing attributestartOffset attributetextLength attributeviewBox attributewidth attributex attributex1 attributex2 attributey attributey1 attributey2 attributetext-rendering propertyDocument parseHTMLUnsafe((TrustedHTML or DOMString) html);
+ static Document parseHTMLUnsafe((TrustedHTML or DOMString) html, optional SetHTMLUnsafeOptions options = {});
+ static Document parseHTML((TrustedHTML or DOMString) html, optional SetHTMLOptions options = {});
// resource metadata management
[PutForwards=href, LegacyUnforgeable] readonly attribute Location? location;
@@ -124667,7 +124764,8 @@ document.body.appendChild(frame)
partial interface Element {
- [CEReactions] undefined setHTMLUnsafe((TrustedHTML or DOMString) html);
+ [CEReactions] undefined setHTMLUnsafe((TrustedHTML or DOMString) html, optional SetHTMLUnsafeOptions options = {});
+ [CEReactions] undefined setHTML(DOMString html, optional SetHTMLOptions options = {});
DOMString getHTML(optional GetHTMLOptions options = {});
[CEReactions] attribute (TrustedHTML or [LegacyNullToEmptyString] DOMString) innerHTML;
@@ -124676,12 +124774,21 @@ document.body.appendChild(frame)TrustedHTML or DOMString) html);
+ [CEReactions] undefined setHTMLUnsafe((TrustedHTML or DOMString) html, optional SetHTMLUnsafeOptions options = {});
+ [CEReactions] undefined setHTML(DOMString html, optional SetHTMLOptions options = {});
DOMString getHTML(optional GetHTMLOptions options = {});
[CEReactions] attribute (TrustedHTML or [LegacyNullToEmptyString] DOMString) innerHTML;
};
+enum SanitizerPresets { "default" };
+dictionary SetHTMLOptions {
+ (Sanitizer or SanitizerConfig or SanitizerPresets) sanitizer = "default";
+};
+dictionary SetHTMLUnsafeOptions {
+ (Sanitizer or SanitizerConfig or SanitizerPresets) sanitizer = {};
+};
+
dictionary GetHTMLOptions {
boolean serializableShadowRoots = false;
sequence<ShadowRoot> shadowRoots = [];
@@ -124858,29 +124965,27 @@ enum DOMParserSupportedType {
element.setHTMLUnsafe(html)element.setHTMLUnsafe(html, options)Parses html using the HTML parser, and replaces the children of element - with the result. element provides context for the HTML parser.
+Parses html using the HTML parser with options options, and replaces + the children of element with the result. element provides context for the + HTML parser.
shadowRoot.setHTMLUnsafe(html)shadowRoot.setHTMLUnsafe(html, options)Parses html using the HTML parser, and replaces the children of - shadowRoot with the result. shadowRoot's Parses html using the HTML parser with options options, and replaces + the children of shadowRoot with the result. shadowRoot's host provides context for the HTML parser.
doc = Document.parseHTMLUnsafe(html)doc = Document.parseHTMLUnsafe(html, options)Parses html using the HTML parser, and returns the resulting
- Document.
Parses html using the HTML parser with options options, and returns the
+ resulting Document.
Note that script elements are not evaluated during parsing, and the resulting
document's encoding will always be
@@ -124896,8 +125001,8 @@ enum DOMParserSupportedType {
Element's setHTMLUnsafe(html) method steps
- are:
Let compliantHTML be the result of invoking the DOMParserSupportedType {
Let target be this's template contents if
this is a Unsafely set HTML given target, this, and
- compliantHTML. Set and filter HTML given target, this,
+ compliantHTML, options, and false.template element; otherwise this.
ShadowRoot's setHTMLUnsafe(html) method steps
- are:
Let compliantHTML be the result of invoking the DOMParserSupportedType {
object, html, "ShadowRoot setHTMLUnsafe", and "script".
Unsafely set HTML given this, this's shadow host, and compliantHTML.
Set and filter HTML given this, this's shadow host, compliantHTML, + options, and false.
To unsafely set HTML, given an Element or DocumentFragment
- target, an Element contextElement, and a string
- html:
Element's setHTML(html, options) method
+ steps are:
Let newChildren be the result of the HTML fragment parsing - algorithm given contextElement, html, and true.
Let target be this's template contents if
+ this is a template element; otherwise this.
Let fragment be a new DocumentFragment whose node
- document is contextElement's node document.
Set and filter HTML given target, this, + html, options, and true.
For each node in newChildren, append node to fragment.
ShadowRoot's setHTML(html, options) method
+ steps are:
Replace all with fragment within - target.
Set and filter HTML given this, this's shadow host, html, options, + and true.
The static parseHTMLUnsafe(html) method steps are:
Let compliantHTML be the result of invoking the DOMParserSupportedType {
Parse HTML from a string given document and
compliantHTML. Let sanitizer be the result of calling get a sanitizer instance from
+ options with options and false. Call sanitize on document with sanitizer and
+ false. Return document.
The static parseHTML(html,
+ options) method steps are:
Let document be a new Document, whose content type is "text/html".
Since document does not have a browsing context, scripting + is disabled.
+Set document's allow declarative shadow roots to + true.
Parse HTML from a string given document and + html.
Let sanitizer be the result of calling get a sanitizer instance from + options with options and true.
Call sanitize on document with sanitizer and + true.
Return document.
element.setHTML(html, options)shadowRoot.setHTML(html, options)Parses html using the HTML parser with options options, and replaces + the children of the element or shadow root with the result, which is then sanitized.
+doc = Document.parseHTML(html, options)Parses html using the HTML parser with options options, and returns a
+ new Document containing the result, which is then sanitized.
Web applications often need to work with strings of HTML on the client side, perhaps as part of
+ a client-side templating solution, or perhaps as part of rendering user-generated content. It is
+ difficult to do so in a safe way. The naive approach of joining strings together and stuffing them
+ into an element's innerHTML is fraught with risk, as
+ it can cause script execution in a number of unexpected ways.
Libraries like DOMPurify attempt to manage this problem by carefully parsing and + sanitizing strings before insertion, by constructing a DOM and filtering its members through an + allow-list. This has proven to be a fragile approach, as the parsing APIs exposed to the web don't + always map in reasonable ways to the browser's behavior when actually rendering a string as HTML + in the "real" DOM. Moreover, the libraries need to keep on top of browsers' changing behavior over + time; things that once were safe may turn into time-bombs based on new platform-level + features.
+ +The browser has a fairly good idea of when it is going to execute code. We can improve upon + user-space libraries by teaching the browser how to render HTML from an arbitrary string in a safe + manner, and do so in a way that is much more likely to be maintained and updated along with the + browser's own changing parser implementation. The APIs in this section aim to do just that.
+ +The goals of these APIs are:
+ +Mitigate the risk of DOM-based cross-site scripting attacks by providing developers with + mechanisms for handling user-controlled HTML which prevent direct script execution upon + injection.
Make HTML output safe for use within the current user agent, taking into account its + current understanding of HTML.
Allow developers to override the default set of elements and attributes. Adding certain + elements and attributes can prevent script + gadget attacks.
These APIs offer functionality to parse a string containing HTML into a DOM tree, and to filter + the resulting tree according to a user-supplied configuration. The methods come in two main + flavors:
+ +The "safe" methods will not generate any markup that executes script. That is, they are + intended to be safe from XSS. The "unsafe" methods will parse and filter based on the provided + configuration, but do not have the same safety guarantees by default.
Methods are defined on Element and ShadowRoot and will replace
+ these node's children, and are largely analogous to innerHTML. There are also static methods on the
+ Document, which parse an entire document and are largely analogous to parseFromString().
Sanitizer interface[Exposed=Window]
+interface Sanitizer {
+ constructor(optional (SanitizerConfig or SanitizerPresets) configuration = "default");
+
+ // Query configuration:
+ SanitizerConfig get();
+
+ // Modify a Sanitizer's lists and fields:
+ boolean allowElement(SanitizerElementWithAttributes element);
+ boolean removeElement(SanitizerElement element);
+ boolean replaceElementWithChildren(SanitizerElement element);
+ boolean allowProcessingInstruction(SanitizerProcessingInstruction pi);
+ boolean removeProcessingInstruction(SanitizerProcessingInstruction pi);
+ boolean allowAttribute(SanitizerAttribute attribute);
+ boolean removeAttribute(SanitizerAttribute attribute);
+ boolean setComments(boolean allow);
+ boolean setDataAttributes(boolean allow);
+
+ // Remove markup that executes script.
+ boolean removeUnsafe();
+};config = sanitizer.get()Returns a copy of the sanitizer's configuration.
sanitizer.allowElement(element)Ensures that the sanitizer configuration allows the specified element.
sanitizer.removeElement(element)Ensures that the sanitizer configuration blocks the specified element.
sanitizer.replaceElementWithChildren(element)Configures the sanitizer to remove the specified element but keep its child + nodes.
sanitizer.allowAttribute(attribute)Configures the sanitizer to allow the specified attribute globally.
sanitizer.removeAttribute(attribute)Configures the sanitizer to block the specified attribute globally.
sanitizer.allowProcessingInstruction(pi)Configures the sanitizer to allow the specified processing instruction.
sanitizer.removeProcessingInstruction(pi)Configures the sanitizer to block the specified processing instruction.
sanitizer.setComments(allow)Sets whether the sanitizer preserves comments.
sanitizer.setDataAttributes(allow)Sets whether the sanitizer preserves custom data attributes (e.g., data-*).
sanitizer.removeUnsafe()Modifies the configuration to automatically remove elements and attributes that are + considered unsafe.
A Sanitizer has an associated configuration (a
+ SanitizerConfig).
The new
+ Sanitizer(configuration) constructor steps are:
If configuration is a SanitizerPresets string, then:
+ +Assert: configuration is "default".
Set configuration to the built-in safe default + configuration.
If set a configuration configuration with true and
+ this is false, then throw a TypeError.
The allowProcessingInstruction(pi)
+ method steps are:
Let configuration be this's configuration.
Set pi to the result of canonicalize a sanitizer processing + instruction with pi.
If configuration["processingInstructions"] exists, then:
If configuration["processingInstructions"] contains pi, then return
+ false.
Append pi to
+ configuration["processingInstructions"].
Return true.
Otherwise:
+ +If configuration["removeProcessingInstructions"]
+ contains pi,
+ then:
Remove
+ pi from configuration["removeProcessingInstructions"].
Return true.
Return false.
The removeProcessingInstruction(pi)
+ method steps are:
Let configuration be this's configuration.
Set pi to the result of canonicalize a sanitizer processing + instruction with pi.
If configuration["processingInstructions"] exists, then:
If configuration["processingInstructions"] contains pi, then:
Remove
+ pi from configuration["processingInstructions"].
Return true.
Return false.
Otherwise:
+ +If configuration["removeProcessingInstructions"]
+ contains pi, then
+ return false.
Append pi to
+ configuration["removeProcessingInstructions"].
Return true.
To set a configuration, given a dictionary configuration,
+ a boolean allowCommentsPIsAndDataAttributes, and a Sanitizer
+ sanitizer:
Canonicalize the configuration configuration with + allowCommentsPIsAndDataAttributes.
If configuration is not valid, + then return false.
Set sanitizer's configuration to + configuration.
Return true.
To canonicalize the configuration SanitizerConfig + configuration with a boolean allowCommentsPIsAndDataAttributes:
+ +For each member of configuration + that is a list of strings:
+Replace each string in member with the result of canonicalizing it using the + appropriate algorithm (e.g., canonicalize a sanitizer element or + canonicalize a sanitizer attribute).
If configuration["elements"]
+ exists, then:
For each element in
+ configuration["elements"]:
If element["attributes"] exists, replace each attribute with the result of
+ canonicalize a sanitizer attribute.
If element["removeAttributes"]
+ exists, replace each attribute with the result of
+ canonicalize a sanitizer attribute.
If neither configuration["elements"] nor configuration["removeElements"] exists, then set configuration["removeElements"] to an empty list.
If neither configuration["attributes"] nor configuration["removeAttributes"] exists, then set configuration["removeAttributes"] to an empty
+ list.
If neither configuration["processingInstructions"] nor
+ configuration["removeProcessingInstructions"]
+ exists, then:
If allowCommentsPIsAndDataAttributes is true, then set
+ configuration["removeProcessingInstructions"]
+ to an empty list.
Otherwise, set configuration["processingInstructions"] to an empty
+ list.
If configuration["comments"]
+ does not exist, set it to
+ allowCommentsPIsAndDataAttributes.
If configuration["dataAttributes"] does not exist, set it to allowCommentsPIsAndDataAttributes.
In order to canonicalize a sanitizer element element, run the following + steps:
+ +If element is a string, then return a new
+ SanitizerElementNamespace dictionary with its name member set to element and its
+ _namespace member set to the
+ HTML namespace.
Return element.
In order to canonicalize a sanitizer attribute attribute, run the + following steps:
+ +If attribute is a string, then return a new
+ SanitizerAttributeNamespace dictionary with its name member set to attribute and
+ its _namespace member set to
+ null.
Return attribute.
In order to canonicalize a sanitizer processing instruction pi, run the + following steps:
+ +If pi is a string, then set pi to a new
+ SanitizerProcessingInstruction dictionary with its target member set to
+ pi.
Return pi.
dictionary SanitizerElementNamespace {
+ required DOMString name;
+ DOMString? _namespace = "http://www.w3.org/1999/xhtml";
+};
+
+// Used by "elements"
+dictionary SanitizerElementNamespaceWithAttributes : SanitizerElementNamespace {
+ sequence<SanitizerAttribute> attributes;
+ sequence<SanitizerAttribute> removeAttributes;
+};
+
+typedef (DOMString or SanitizerElementNamespace) SanitizerElement;
+typedef (DOMString or SanitizerElementNamespaceWithAttributes) SanitizerElementWithAttributes;
+
+dictionary SanitizerProcessingInstruction {
+ required DOMString target;
+};
+
+typedef (DOMString or SanitizerProcessingInstruction) SanitizerPI;
+
+dictionary SanitizerAttributeNamespace {
+ required DOMString name;
+ DOMString? _namespace = null;
+};
+typedef (DOMString or SanitizerAttributeNamespace) SanitizerAttribute;
+
+dictionary SanitizerConfig {
+ sequence<SanitizerElementWithAttributes> elements;
+ sequence<SanitizerElement> removeElements;
+ sequence<SanitizerElement> replaceWithChildrenElements;
+
+ sequence<SanitizerProcessingInstruction> processingInstructions;
+ sequence<SanitizerProcessingInstruction> removeProcessingInstructions;
+
+ sequence<SanitizerAttribute> attributes;
+ sequence<SanitizerAttribute> removeAttributes;
+
+ boolean comments;
+ boolean dataAttributes;
+};Configurations can and ought to be modified by developers to suit their purposes. Options are
+ to write a new SanitizerConfig dictionary from scratch, to modify an existing
+ Sanitizer's configuration by using the modifier methods, or to get() an existing Sanitizer's
+ configuration as a dictionary and modify the dictionary and then create a new
+ Sanitizer with it.
An empty configuration allows everything (when called with the "unsafe" methods like setHTMLUnsafe()). A configuration "default" contains a built-in safe default
+ configuration. Note that "safe" and "unsafe" sanitizer methods have different defaults.
Not all configuration dictionaries are valid. A valid configuration avoids redundancy (like + specifying the same element to be allowed twice) and contradictions (like specifying an element to + be both removed and allowed.)
+ +Several conditions need to hold for a configuration to be valid:
+ +Mixing global allow- and remove-lists:
+elements or removeElements can exist, but not both. If
+ both are missing, this is equivalent to removeElements being an empty list.
attributes or removeAttributes can exist, but not both.
+ If both are missing, this is equivalent to removeAttributes being an empty
+ list.
dataAttributes is conceptually
+ an extension of the attributes allow-list.
+ The dataAttributes member is only
+ allowed when an attributes list is
+ used.
Duplicate entries between different global lists:
+There are no duplicate entries (i.e., no same elements) between elements, removeElements, or replaceWithChildrenElements.
There are no duplicate entries (i.e., no same attributes) between attributes or removeAttributes.
Mixing local allow- and remove-lists on the same element:
+When an attributes list exists,
+ both, either or none of the attributes and removeAttributes
+ lists are allowed on the same element.
When a removeAttributes list
+ exists, either or none of the attributes and removeAttributes
+ lists are allowed on the same element, but not both.
Duplicate entries on the same element:
+There are no duplicate entries between attributes and removeAttributes
+ on the same element.
No element from the built-in non-replaceable elements list appears in replaceWithChildrenElements,
+ since replacing these elements with their children could lead to re-parsing issues or invalid
+ node trees.
The elements element allow-list can also
+ specify allowing or removing attributes for a given element. This is meant to mirror this
+ standard's structure, which knows both global attributes as well as local attributes
+ that apply to a specific element. Global and local attributes can be mixed, but note that
+ ambiguous configurations where a particular attribute would be allowed by one list and forbidden
+ by another, are generally invalid.
| + | global attributes |
+ global removeAttributes |
+
|---|---|---|
local attributes |
+ An attribute is allowed if it matches either list. No duplicates are allowed. | +An attribute is only allowed if it's in the local allow list. No duplicate entries between + global remove and local allow lists are allowed. Note that the global remove list has no + function for this particular element, but may well apply to other elements that do not have a + local allow list. | +
local removeAttributes |
+ An attribute is allowed if it's in the global allow-list, but not in the local remove-list. + Local remove must be a subset of the global allow lists. | +An attribute is allowed if it is in neither list. No duplicate entries between global + remove and local remove lists are allowed. | +
Please note the asymmetry where mostly no duplicates between global and per-element lists are + permitted, but in the case of a global allow-list and a per-element remove-list the latter must be + a subset of the former. An excerpt of the table above, only focusing on duplicates, is as + follows:
+ +| + | global attributes |
+ global removeAttributes |
+
|---|---|---|
local attributes |
+ No duplicates are allowed. | +No duplicates are allowed. | +
local removeAttributes |
+ Local remove must be a subset of the global allow lists. | +No duplicates are allowed. | +
The dataAttributes setting allows
+ custom data attributes. The rules above easily extends
+ to custom data attributes if one considers dataAttributes to be an allow-list:
| + | global attributes and dataAttributes set |
+
|---|---|
local attributes |
+ All custom data attributes are allowed. No + custom data attributes may be listed in any + allow-list, as that would mean a duplicate entry. | +
local removeAttributes |
+ A custom data attribute is allowed, unless it's + listed in the local remove-list. No custom data + attribute may be listed in the global allow-list, as that would mean a duplicate + entry. | +
Putting these rules in words:
+ +Duplicates and interactions between global and local lists:
+If a global attributes allow list
+ exists, then all element's local lists:
If a local attributes allow list
+ exists, there may be no duplicate entries between these lists.
If a local removeAttributes
+ remove list exists, then all its entries must also be listed in the global attributes allow list.
If dataAttributes is true,
+ then no custom data attributes may be listed in
+ any of the allow-lists.
If a global removeAttributes
+ remove list exists, then:
If a local attributes allow list
+ exists, there may be no duplicate entries between these lists.
If a local removeAttributes
+ remove list exists, there may be no duplicate entries between these lists.
Not both a local attributes allow list
+ and local removeAttributes
+ remove list exists.
dataAttributes must be
+ false.
The get() method
+ steps are:
Outside of the get() method, the order of
+ the Sanitizer's elements and attributes is unobservable. By explicitly sorting the
+ result of this method, we give implementations the opportunity to optimize by, for example, using
+ unordered sets internally.
Let config be this's configuration.
Assert: config is valid.
If config["elements"] exists, then:
For any element of
+ config["elements"]:
If element["attributes"] exists, then set element["attributes"] to the
+ result of sort in ascending order element["attributes"], with
+ compare sanitizer items.
If element["removeAttributes"]
+ exists, then set element["removeAttributes"]
+ to the result of sort in ascending order
+ element["removeAttributes"],
+ with compare sanitizer items.
Set config["elements"] to
+ the result of sort in ascending order config["elements"], with compare sanitizer
+ items.
Otherwise:
+Set config["removeElements"] to the result of sort in ascending order config["removeElements"], with compare
+ sanitizer items.
If config["replaceWithChildrenElements"]
+ exists, then set config["replaceWithChildrenElements"] to
+ the result of sort in ascending order config["replaceWithChildrenElements"],
+ with compare sanitizer items.
If config["processingInstructions"] exists, then set config["processingInstructions"] to the result
+ of sort in ascending order config["processingInstructions"], with
+ piA["target"] being
+ code unit less than piB["target"].
Otherwise:
+Set config["removeProcessingInstructions"]
+ to the result of sorting config["removeProcessingInstructions"],
+ with piA["target"]
+ being code unit less than piB["target"].
If config["attributes"]
+ exists, then set config["attributes"] to the result of sorting config["attributes"] given compare sanitizer
+ items.
Otherwise:
+Set config["removeAttributes"] to the result of sorting config["removeAttributes"] given compare
+ sanitizer items.
Return config.
To compare sanitizer items itemA and itemB:
+ +Let namespaceA be itemA["_namespace"].
Let namespaceB be itemB["_namespace"].
If namespaceA is null, then:
+If namespaceB is not null, then return true.
Otherwise:
+If namespaceB member is null, then return false.
If namespaceA is code unit less than namespaceB, then + return true.
If namespaceA is not namespaceB, then return false.
If itemA["name"] is
+ code unit less than itemA["name"], return true.
Return false.
The allowElement(element) method steps
+ are:
Let configuration be this's configuration.
Assert: configuration is valid.
Set element to the result of canonicalize a sanitizer element with + attributes with element.
If configuration["elements"]
+ exists, then:
Let modified be the result of removing element from configuration["replaceWithChildrenElements"].
If configuration["attributes"] exists, then:
If element["attributes"] exists, then:
Set element["attributes"] to the
+ result of remove
+ duplicates from element["attributes"].
Set element["attributes"] to the
+ set/difference of
+ element["attributes"] and
+ configuration["attributes"].
If configuration["dataAttributes"] is true, then remove all items item from element["attributes"] where
+ item is a custom data attribute.
If element["removeAttributes"]
+ exists, then:
Set element["removeAttributes"]
+ to the result of removing
+ duplicates from element["removeAttributes"].
Set element["removeAttributes"]
+ to the intersection of
+ element["removeAttributes"]
+ and configuration["attributes"].
Otherwise:
+ +If element["attributes"] exists, then:
Set element["attributes"] to the
+ result of removing
+ duplicates from element["attributes"].
Set element["attributes"] to the
+ set/difference of
+ element["attributes"] and
+ element["removeAttributes"]
+ (or an empty list if it does not exist).
Remove element["removeAttributes"].
Set element["attributes"] to the
+ set/difference of
+ element["attributes"] and
+ configuration["removeAttributes"].
If element["removeAttributes"]
+ exists, then:
Set element["removeAttributes"]
+ to the result of removing
+ duplicates from element["removeAttributes"].
Set element["removeAttributes"]
+ to the difference of
+ element["removeAttributes"]
+ and configuration["removeAttributes"].
If configuration["elements"] does not contain element, then:
Append element to
+ configuration["elements"].
Return true.
Let current element be the item in configuration["elements"] whose name member is element's name member and whose _namespace member is
+ element's _namespace
+ member.
If element is equal to current element, then return + modified.
Remove element from
+ configuration["elements"].
Append element to
+ configuration["elements"].
Return true.
Otherwise:
+ +If element["attributes"] exists or element["removeAttributes"]
+ (or an empty list if it does not exist) is not empty, then return false.
Let modified be the result of removing element from configuration["replaceWithChildrenElements"].
If configuration["removeElements"] does not contain element, then return modified.
Remove element from
+ configuration["removeElements"].
Return true.
The removeElement(element) method steps
+ are to return the result of removing
+ element from this's configuration.
The replaceElementWithChildren(element)
+ method steps are:
Let configuration be this's configuration.
Assert: configuration is valid.
Set element to the result of canonicalize a sanitizer element with + element.
If the built-in non-replaceable elements list contains element, then return false.
Let modified be the result of removing element from configuration["elements"].
If removing element
+ from configuration["removeElements"] is true, then set
+ modified to true.
If configuration["replaceWithChildrenElements"]
+ does not sanitizer config list contains element, then:
Append element to
+ configuration["replaceWithChildrenElements"].
Return true.
Return modified.
The allowAttribute(attribute) method
+ steps are:
Let configuration be this's configuration.
Assert: configuration is valid.
Set attribute to the result of canonicalize a sanitizer attribute + with attribute.
If configuration["attributes"] exists, then:
If configuration["dataAttributes"] is true and
+ attribute is a custom data attribute, then return false.
If configuration["attributes"] contains attribute, then return false.
If configuration["elements"] exists, then:
For each element in
+ configuration["elements"]:
If element["attributes"] (or an
+ empty list if it does not exist) sanitizer config list contains
+ attribute, then remove
+ attribute from element["attributes"].
Append attribute to
+ configuration["attributes"].
Return true.
Otherwise:
+ +If configuration["removeAttributes"] does not contain attribute, then return false.
Remove attribute from
+ configuration["removeAttributes"].
Return true.
The removeAttribute(attribute) method
+ steps are to return the result of remove
+ an attribute with attribute and this's
+ configuration.
The setComments(allow) method steps
+ are:
Let configuration be this's configuration.
Assert: configuration is valid.
If configuration["comments"]
+ exists and is equal to allow, then return
+ false.
Set configuration["comments"] to allow.
Return true.
The setDataAttributes(allow) method
+ steps are:
Let configuration be this's configuration.
Assert: configuration is valid.
If configuration["dataAttributes"] exists and is equal to allow, then return false.
If allow is false and configuration["attributes"] exists, then:
For each element in
+ configuration["elements"] (or an
+ empty list if it does not exist):
Remove all items item from
+ element["attributes"] (or an
+ empty list if it does not exist) where item is a custom data
+ attribute.
Remove all items item from
+ configuration["attributes"]
+ where item is a custom data attribute.
Set configuration["dataAttributes"] to allow.
Return true.
The removeUnsafe() method steps are to update
+ this's configuration with the result of remove unsafe from
+ this's configuration.
To set and filter HTML, given an Element or
+ DocumentFragment target, an Element
+ contextElement, a string html, a dictionary options,
+ and a boolean safe:
If all of the following are true:
+ +safe is true;
contextElement's local name
+ is "script"; and
contextElement's namespace + is the HTML namespace or the SVG namespace,
then return.
+Let sanitizer be the result of calling getting a sanitizer from options given safe.
Let newChildren be the result of parsing a fragment given contextElement, html, and + true.
Let fragment be a new DocumentFragment whose node
+ document is contextElement's node document.
For each node in newChildren, + append node to fragment.
Sanitize fragment given sanitizer and + safe.
Replace all with fragment within + target.
To get a sanitizer instance from options from a dictionary options with a + boolean safe:
+ +Let sanitizerSpec be "default".
If options["sanitizer"]
+ exists, then set sanitizerSpec to
+ options["sanitizer"].
Assert: sanitizerSpec is either a Sanitizer instance,
+ a SanitizerPresets member, or a SanitizerConfig dictionary.
If sanitizerSpec is a string, then:
+ +Assert: sanitizerSpec is "default".
Set sanitizerSpec to the built-in safe default + configuration.
If sanitizerSpec is a dictionary, then:
+ +Let sanitizer be a new Sanitizer instance.
Let inverseSafe be true if safe is false; false otherwise. + +
If the result of setting a configuration
+ sanitizerSpec with (inverseSafe) and sanitizer is false, then
+ throw a TypeError.
Set sanitizerSpec to sanitizer.
Return sanitizerSpec.
To sanitize a node node with a Sanitizer
+ sanitizer and a boolean safe:
Let configuration be sanitizer's + configuration.
Assert: configuration is valid.
If safe is true, then set configuration to the result of calling + remove unsafe on configuration.
Sanitize node given + configuration and safe.
To perform the inner sanitize steps on a Node node, given a
+ SanitizerConfig configuration, and a boolean
+ handleJavascriptNavigationUrls:
For each child of node's children:
+ +Assert: child is a Text, Comment,
+ Element, ProcessingInstruction, or DocumentType
+ node.
If child is a DocumentType node, then
+ continue.
If child is a Text node, then continue.
If child is a Comment node, then:
If configuration["comments"] is not true, then remove child.
If child is a ProcessingInstruction node, then:
Let piTarget be child's target.
If configuration["processingInstructions"] exists, then:
If configuration["processingInstructions"] does
+ not sanitizer config list contains piTarget, then remove child.
Otherwise:
+If configuration["removeProcessingInstructions"]
+ sanitizer config list contains piTarget, then remove child.
Otherwise:
+Let elementName be a SanitizerElementNamespace with + child's local name and namespace.
If configuration["replaceWithChildrenElements"]
+ exists and configuration["replaceWithChildrenElements"]
+ sanitizer config list contains elementName, then:
Assert: node is not a Document.
Sanitize child given + configuration and handleJavascriptNavigationUrls.
Replace all with child's + children within child.
Continue.
If configuration["elements"] exists, then:
If configuration["elements"] does not contain elementName, then remove child and continue.
Otherwise:
+If configuration["removeElements"] contains elementName, then remove child and continue.
If elementName is a template element in the HTML
+ namespace, then sanitize child's
+ template contents given configuration and
+ handleJavascriptNavigationUrls.
If child is a shadow host, then sanitize child's shadow root given + configuration and handleJavascriptNavigationUrls.
Let elementWithLocalAttributes be null.
If configuration["elements"] exists and configuration["elements"] contains elementName, then set
+ elementWithLocalAttributes to configuration["elements"][elementName].
For each attribute in child's + attribute list:
+ +Let attrName be a SanitizerAttributeNamespace with + attribute's local name and + namespace.
If elementWithLocalAttributes["removeAttributes"]
+ exists and elementWithLocalAttributes["removeAttributes"]
+ sanitizer config list contains attrName, then remove an attribute
+ attribute.
Otherwise, if configuration["attributes"] exists, then:
If configuration["attributes"] does not contain attrName and
+ elementWithLocalAttributes["attributes"] does
+ not sanitizer config list contains attrName, and if "data-" is not a prefix of attribute's local name or attribute's namespace is not null or
+ configuration["dataAttributes"] is not true, then
+ remove an attribute
+ attribute.
Otherwise:
+If elementWithLocalAttributes["attributes"] exists and elementWithLocalAttributes["attributes"] does
+ not sanitizer config list contains attrName, then remove attribute
+ from configuration.
Otherwise, if configuration["removeAttributes"] contains attrName, then remove attribute from
+ configuration.
If handleJavascriptNavigationUrls is true, then:
+If the pair (elementName, attrName) matches an entry in the
+ built-in navigating URL attributes list, and if attribute
+ contains a javascript: URL, then remove an attribute
+ attribute.
If child's namespace is
+ the MathML Namespace, attribute's local name is "href",
+ and attribute's namespace is
+ null or the XLink namespace, and attribute contains a
+ javascript: URL, then remove an attribute attribute.
If the built-in animating URL attributes list contains the pair (elementName, attrName), and
+ attribute's value is "href" or "xlink:href", then remove attribute from
+ configuration.
Sanitize child given + configuration and handleJavascriptNavigationUrls.
To determine whether an attribute attribute contains a javascript:
+ URL:
Let url be the result of running the basic URL parser on + attribute's value.
If url is failure, then return false.
Return whether url's scheme is "javascript".
The built-in safe baseline configuration is a SanitizerConfig with its
+ removeElements corresponding to the
+ following table:
| Name + | Namespace + |
|---|---|
embed
+ | HTML + |
frame
+ | HTML + |
iframe
+ | HTML + |
object
+ | HTML + |
script
+ | HTML + |
script
+ | SVG + |
use
+ | SVG + |
and the following removeAttributes
+ list:
onafterprintonauxclickonbeforeinputonbeforematchonbeforeprintonbeforeunloadonbeforetoggleonbluroncanceloncanplayoncanplaythroughonchangeonclickoncloseoncontextlostoncontextmenuoncontextrestoredoncopyoncuechangeoncutondblclickondragondragendondragenterondragleaveondragoverondragstartondropondurationchangeonemptiedonendedonerroronfocusonformdataonhashchangeoninputoninvalidonkeydownonkeypressonkeyuponlanguagechangeonloadonloadeddataonloadedmetadataonloadstartonmessageonmessageerroronmousedownonmouseenteronmouseleaveonmousemoveonmouseoutonmouseoveronmouseuponofflineononlineonpagehideonpagerevealonpageshowonpageswaponpasteonpauseonplayonplayingonpopstateonprogressonratechangeonresetonresizeonrejectionhandledonscrollonscrollendonsecuritypolicyviolationonseekedonseekingonselectonslotchangeonstalledonstorageonsubmitonsuspendontimeupdateontoggleonunhandledrejectiononunloadonvolumechangeonwaitingonwheelThe built-in safe default configuration is a SanitizerConfig with its
+ elements list corresponding to the following
+ table:
| Element + | Namespace + | Allowed Attributes + | |
|---|---|---|---|
a
+ | HTML + | href, hreflang, type
+ | |
abbr
+ | HTML + | + | |
address
+ | HTML + | + | |
article
+ | HTML + | + | |
aside
+ | HTML + | + | |
b
+ | HTML + | + | |
bdi
+ | HTML + | + | |
bdo
+ | HTML + | + | |
blockquote
+ | HTML + | cite
+ | + |
body
+ | HTML + | + | |
br
+ | HTML + | + | |
caption
+ | HTML + | + | |
cite
+ | HTML + | + | |
code
+ | HTML + | + | |
col
+ | HTML + | span
+ | |
colgroup
+ | HTML + | span
+ | |
data
+ | HTML + | value
+ | |
dd
+ | HTML + | + | |
del
+ | HTML + | cite, datetime
+ | |
dfn
+ | HTML + | + | |
div
+ | HTML + | + | |
dl
+ | HTML + | + | |
dt
+ | HTML + | + | |
em
+ | HTML + | + | |
figcaption
+ | HTML + | + | |
figure
+ | HTML + | + | |
footer
+ | HTML + | + | |
h1
+ | HTML + | + | |
h2
+ | HTML + | + | |
h3
+ | HTML + | + | |
h4
+ | HTML + | + | |
h5
+ | HTML + | + | |
h6
+ | HTML + | + | |
head
+ | HTML + | + | |
header
+ | HTML + | + | |
hgroup
+ | HTML + | + | |
hr
+ | HTML + | + | |
html
+ | HTML + | + | |
i
+ | HTML + | + | |
ins
+ | HTML + | cite, datetime
+ | |
kbd
+ | HTML + | + | |
li
+ | HTML + | value
+ | |
main
+ | HTML + | + | |
mark
+ | HTML + | + | |
menu
+ | HTML + | + | |
nav
+ | HTML + | + | |
ol
+ | HTML + | reversed, start, type
+ | |
p
+ | HTML + | + | |
pre
+ | HTML + | + | |
q
+ | HTML + | + | |
rp
+ | HTML + | + | |
rt
+ | HTML + | + | |
ruby
+ | HTML + | + | |
s
+ | HTML + | + | |
samp
+ | HTML + | + | |
search
+ | HTML + | + | |
section
+ | HTML + | + | |
small
+ | HTML + | + | |
span
+ | HTML + | + | |
strong
+ | HTML + | + | |
sub
+ | HTML + | + | |
sup
+ | HTML + | + | |
table
+ | HTML + | + | |
tbody
+ | HTML + | + | |
td
+ | HTML + | colspan, headers, rowspan
+ | |
tfoot
+ | HTML + | + | |
th
+ | HTML + | abbr, colspan, headers, rowspan, scope
+ | |
thead
+ | HTML + | + | |
time
+ | HTML + | datetime
+ | |
title
+ | HTML + | + | |
tr
+ | HTML + | + | |
u
+ | HTML + | + | |
ul
+ | HTML + | + | |
var
+ | HTML + | + | |
wbr
+ | HTML + | + | |
math
+ | MathML + | + | |
merror
+ | MathML + | + | |
mfrac
+ | MathML + | + | |
mi
+ | MathML + | + | |
mmultiscripts
+ | MathML + | + | |
mn
+ | MathML + | + | |
mo
+ | MathML + | fence, form, largeop, lspace, maxsize, minsize, movablelimits, rspace, separator, stretchy, symmetric
+ | |
mover
+ | MathML + | accent
+ | |
mpadded
+ | MathML + | depth, height, lspace, voffset, width
+ | |
mphantom
+ | MathML + | + | |
mprescripts
+ | MathML + | + | |
mroot
+ | MathML + | + | |
mrow
+ | MathML + | + | |
ms
+ | MathML + | + | |
mspace
+ | MathML + | depth, height, width
+ | |
msqrt
+ | MathML + | + | |
mstyle
+ | MathML + | + | |
msub
+ | MathML + | + | |
msubsup
+ | MathML + | + | |
msup
+ | MathML + | + | |
mtable
+ | MathML + | + | |
mtd
+ | MathML + | columnspan, rowspan
+ | |
mtext
+ | MathML + | + | |
mtr
+ | MathML + | + | |
munder
+ | MathML + | accentunder
+ | |
munderover
+ | MathML + | accent, accentunder
+ | |
semantics
+ | MathML + | + | |
a
+ | SVG + | href, hreflang, type
+ | |
circle
+ | SVG + | cx, cy, pathLength, r
+ | |
defs
+ | SVG + | ||
desc
+ | SVG + | ||
ellipse
+ | SVG + | cx, cy, pathLength, rx, ry
+ | |
foreignObject
+ | SVG + | height, width, x, y
+ | |
g
+ | SVG + | ||
line
+ | SVG + | pathLength, x1, x2, y1, y2
+ | |
marker
+ | SVG + | markerHeight, markerUnits, markerWidth, orient, preserveAspectRatio, refX, refY, viewBox
+ | |
metadata
+ | SVG + | ||
path
+ | SVG + | d, pathLength
+ | |
polygon
+ | SVG + | pathLength, points
+ | |
polyline
+ | SVG + | pathLength, points
+ | |
rect
+ | SVG + | height, pathLength, rx, ry, width, x, y
+ | |
svg
+ | SVG + | height, preserveAspectRatio, viewBox, width, x, y
+ | |
text
+ | SVG + | dx, dy, lengthAdjust, rotate, textLength, x, y
+ | |
textPath
+ | SVG + | lengthAdjust, method, path, side, spacing, startOffset, textLength
+ | |
title
+ | SVG + | ||
tspan
+ | SVG + | dx, dy, lengthAdjust, rotate, textLength, x, y
+ |
The built-in navigating URL attributes list corresponds to the following table:
+ +| Element + | Element Namespace + | Attribute + | Attribute Namespace + |
|---|---|---|---|
a
+ | HTML + | href, hreflang, type
+ | + |
area
+ | HTML + | href
+ | + |
base
+ | HTML + | href
+ | + |
button
+ | HTML + | formaction
+ | + |
form
+ | HTML + | action
+ | + |
input
+ | HTML + | formaction
+ | + |
a
+ | SVG + | href
+ | XLink namespace + |
The built-in animating URL attributes list corrsponds to the following table:
+ +| Element + | Element Namespace + | Attribute + |
|---|---|---|
animate
+ | SVG + | attributeName
+ |
animateTransform
+ | SVG + | attributeName
+ |
set
+ | SVG + | attributeName
+ |
To remove an element + element from a SanitizerConfig configuration:
+ +Assert: configuration is valid.
Set element to the result of canonicalize a sanitizer element with + element.
Let modified be the result of removing element from configuration["replaceWithChildrenElements"].
If configuration["elements"]
+ exists, then:
If configuration["elements"] contains element, then:
Remove element from
+ configuration["elements"].
Return true.
Return modified.
Otherwise:
+ +If configuration["removeElements"] contains element, then return modified.
Append element to
+ configuration["removeElements"].
Return true.
To remove an attribute + attribute from a SanitizerConfig configuration:
+ +Assert: configuration is valid.
Set attribute to the result of canonicalize a sanitizer attribute + with attribute.
If configuration["attributes"] exists, then:
Let modified be the result of removing attribute from configuration["attributes"].
If configuration["elements"] exists, then:
For each element of
+ configuration["elements"]:
If element["attributes"] (or an
+ empty list if it does not exist) sanitizer config list contains
+ attribute, then:
Set modified to true.
Remove attribute from
+ element["attributes"].
If element["removeAttributes"]
+ (or an empty list if it does not exist) sanitizer config list contains
+ attribute, then:
Assert: modified is true.
Remove attribute from
+ element["removeAttributes"].
Return modified.
Otherwise:
+ +If configuration["removeAttributes"] contains attribute, then return false.
If configuration["elements"] exists, then:
For each element in
+ configuration["elements"]:
If element["attributes"] (or an
+ empty list if it does not exist) sanitizer config list contains
+ attribute, then remove
+ attribute from element["attributes"].
If element["removeAttributes"]
+ (or an empty list if it does not exist) sanitizer config list contains
+ attribute, then remove
+ attribute from element["removeAttributes"].
Append attribute to
+ configuration["removeAttributes"].
Return true.
To remove unsafe from a SanitizerConfig configuration:
+ +Assert: configuration is valid.
Let result be false.
For each element in built-in safe
+ baseline configuration["removeElements"]:
If removing + element from configuration is true, then set result to + true.
For each attribute in built-in safe
+ baseline configuration["removeAttributes"]:
If removing + attribute from configuration returned true, then set result to + true.
For each attribute that is an event handler content attribute:
+ +If removing + attribute from configuration returned true, then set result to + true.
Return result.
To remove from sanitizer config list given an item and a + list:
+ +Let removed be false.
For each entry of list:
+ +If item's name
+ member is equal to entry's name member and item's _namespace member is equal to
+ entry's _namespace
+ member, then:
Remove entry from + list.
Set removed to true.
Return removed.
To sanitizer config list contains, given an item item and a list + list:
+For each entry of list:
+If item has a target member, and entry
+ has a matching target member,
+ then return true.
Otherwise, if item's name member is equal to entry's
+ name member and item's
+ _namespace member is equal to
+ entry's _namespace
+ member, then return true.
Return false.
To SanitizerConfig/add a name to a list list:
+ +If list sanitizer config list contains name, then + return.
Append name to list.
To check if a list list contains a processing instruction + target given item:
+For each entry of list:
+If item's target member is equal to
+ entry's target
+ member, then return true.
Return false.
To remove prcessing instruction from sanitizer config list, given an item + item and a list list:
+Let removed be false.
For each entry of list:
+If item's target member is equal to
+ entry's target
+ member, then:
remove entry from + list.
Set removed to true.
Return removed.
To canonicalize a sanitizer element with attributes a + SanitizerElementWithAttributes element:
+ +Let result be the result of canonicalize a sanitizer element with + element.
If element is a dictionary, then:
+ +If element["attributes"] exists, then:
Let attributes be an empty list.
For each attribute of
+ element["attributes"]:
Append the result of canonicalize a + sanitizer attribute with attribute to attributes.
Set result["attributes"] to
+ attributes.
If element["removeAttributes"]
+ exists, then:
Let attributes be an empty list.
For each attribute of
+ element["removeAttributes"]:
Append the result of canonicalize a + sanitizer attribute with attribute to attributes.
Set result["removeAttributes"]
+ to attributes.
If neither result["attributes"] nor
+ result["removeAttributes"]
+ exists, then set result["removeAttributes"]
+ to an empty list.
Return result.
To determine whether a canonical SanitizerConfig config is valid:
+ +It's expected that the configuration being passing in has previously been run + through the canonicalize the configuration steps. We will simply assert conditions + that that algorithm is guaranteed to hold.
+ +Assert: config["elements"] exists
+ or config["removeElements"]
+ exists.
If config["elements"] exists and config["removeElements"] exists, then return false.
Assert: Either config["processingInstructions"] exists or config["removeProcessingInstructions"]
+ exists.
If config["processingInstructions"] exists and config["removeProcessingInstructions"]
+ exists, then return false.
Assert: Either config["attributes"] exists or config["removeAttributes"] exists.
If config["attributes"]
+ exists and config["removeAttributes"] exists, then return false.
Assert: All SanitizerElementNamespaceWithAttributes, + SanitizerElementNamespace, SanitizerProcessingInstruction, and + SanitizerAttributeNamespace items in config are canonical, meaning they + have been run through canonicalize a sanitizer element, canonicalize a + sanitizer processing instruction, or canonicalize a sanitizer attribute, as + appropriate.
If config["elements"] exists:
If config["elements"]
+ has duplicates, then return false.
Otherwise:
+If config["removeElements"] has
+ duplicates, then return false.
If config["replaceWithChildrenElements"]
+ exists and has duplicates, then return
+ false.
If config["processingInstructions"] exists:
If config["processingInstructions"] has
+ duplicate targets, then return false.
Otherwise:
+If config["removeProcessingInstructions"]
+ has duplicate targets, then return false.
If config["attributes"]
+ exists:
If config["attributes"]
+ has duplicates, then return false.
Otherwise:
+If config["removeAttributes"] has
+ duplicates, then return false.
If config["replaceWithChildrenElements"]
+ exists:
For each element of
+ config["replaceWithChildrenElements"]:
If the built-in non-replaceable elements list contains element, then return false.
If config["elements"]
+ exists:
If the intersection of
+ config["elements"] and
+ config["replaceWithChildrenElements"]
+ is not empty, then return false.
Otherwise:
+If the intersection of
+ config["removeElements"]
+ and config["replaceWithChildrenElements"]
+ is not empty, then return false.
If config["attributes"]
+ exists:
Assert: config["dataAttributes"] exists.
If config["elements"]
+ exists:
For each element of
+ config["elements"]:
If element["attributes"] exists and element["attributes"]
+ has duplicates, then return false.
If element["removeAttributes"]
+ exists and element["removeAttributes"]
+ has duplicates, then return false.
If the intersection of
+ config["attributes"] and
+ element["attributes"] (or an
+ empty list if it does not exist) is not empty, then return false.
If element["removeAttributes"]
+ (or an empty list if it does not exist) is not a subset of config["attributes"], then return false.
If config["dataAttributes"] is true and
+ element["attributes"]
+ contains a custom data attribute, then return false.
If config["dataAttributes"] is true and
+ config["attributes"] contains a
+ custom data attribute, then return false.
Otherwise:
+If config["elements"]
+ exists:
For each element of
+ config["elements"]:
If element["attributes"] exists and element["removeAttributes"]
+ exists, then return false.
If element["attributes"] exists and element["attributes"]
+ has duplicates, then return false.
If element["removeAttributes"]
+ exists and element["removeAttributes"]
+ has duplicates, then return false.
If the intersection of
+ config["removeAttributes"] and
+ element["attributes"] (or an
+ empty list if it does not exist) is not empty, then return false.
If the intersection of
+ config["removeAttributes"] and
+ element["removeAttributes"]
+ (or an empty list if it does not exist) is not empty, then return false.
If config["dataAttributes"] exists, then return false.
Return true.
A list list has duplicates if it contains two or more items that are + equal.
+To remove duplicates from a + list list, run the following steps:
+ +Let result be an empty list.
For each item of list:
+If result does not contain item, then append + item to result.
Return result.
A list list has duplicate targets if it contains two or more
+ SanitizerProcessingInstruction items with the same target member.
The intersection of sanitizer config lists + A and B containing SanitizerElement or + SanitizerAttribute items is a list containing> all items that are present in both A and B.
+A list A is a subset of a list + B if A contains every + item in B.
+To compute the difference of two lists + A and B:
+ +Let result be an empty list.
For each item of A:
+If B does not contain + item, then append item to + result.
Return result.
The built-in non-replaceable elements list contains elements that must not be + replaced with their children, as doing so can lead to re-parsing issues or an invalid node tree. + It is the following list of SanitizerElementNamespace dictionaries:
+ +{ name: "html", _namespace: HTML namespace
+ }
{ name: "svg", _namespace: SVG namespace
+ }
{ name: "math", _namespace: MathML namespace
+ }
The setTimeout() and