Skip to content

Upstream the Sanitizer API (WIP) #12314

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
zcorpan wants to merge 2 commits into
base: main
Choose a base branch
from
+137 −16
Draft

Upstream the Sanitizer API (WIP) #12314

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d1a1667
Upstream the Sanitizer API
zcorpan Mar 25, 2026
6612b03
Fix build errors, update steps for setHTMLUnsafe
zcorpan Apr 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 137 additions & 16 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11413,7 +11413,8 @@ typedef (<span>HTMLScriptElement</span> or <span>SVGScriptElement</span>) <dfn t

[<span>LegacyOverrideBuiltIns</span>]
partial interface <dfn id="document" data-lt="">Document</dfn> {
static <code>Document</code> <span data-x="dom-parseHTMLUnsafe">parseHTMLUnsafe</span>((<code data-x="tt-trustedhtml">TrustedHTML</code> or DOMString) html);
static <span>Document</span> <span data-x="dom-parseHTMLUnsafe">parseHTMLUnsafe</span>((<span data-x="tt-trustedhtml">TrustedHTML</span> or DOMString) html, optional <span>SetHTMLUnsafeOptions</span> options = {});
static <span>Document</span> <span data-x="dom-parseHTML">parseHTML</span>((<span data-x="tt-trustedhtml">TrustedHTML</span> or DOMString) html, optional <span>SetHTMLOptions</span> options = {});

// <span>resource metadata management</span>
[PutForwards=<span data-x="dom-location-href">href</span>, <span>LegacyUnforgeable</span>] readonly attribute <span>Location</span>? <span data-x="dom-document-location">location</span>;
Expand Down Expand Up @@ -124514,7 +124515,8 @@ document.body.appendChild(frame)</code></pre>
<h3 id="dom-parsing-and-serialization">DOM parsing and serialization APIs</h3>

<pre><code class="idl">partial interface <span id="Element-partial">Element</span> {
[<span>CEReactions</span>] undefined <span data-x="dom-Element-setHTMLUnsafe">setHTMLUnsafe</span>((<code data-x="tt-trustedhtml">TrustedHTML</code> or DOMString) html);
[<span>CEReactions</span>] undefined <span data-x="dom-Element-setHTMLUnsafe">setHTMLUnsafe</span>((<span data-x="tt-trustedhtml">TrustedHTML</span> or DOMString) html, optional <span>SetHTMLUnsafeOptions</span> options = {});
[CEReactions] undefined <span data-x="dom-Element-setHTML">setHTML</span>(DOMString html, optional <span>SetHTMLOptions</span> options = {});
DOMString <span data-x="dom-Element-getHTML">getHTML</span>(optional <span>GetHTMLOptions</span> options = {});

[<span>CEReactions</span>] attribute (<code data-x="tt-trustedhtml">TrustedHTML</code> or [<span>LegacyNullToEmptyString</span>] DOMString) <span data-x="dom-Element-innerHTML">innerHTML</span>;
Expand All @@ -124523,12 +124525,21 @@ document.body.appendChild(frame)</code></pre>
};

partial interface <span id="ShadowRoot-partial">ShadowRoot</span> {
[<span>CEReactions</span>] undefined <span data-x="dom-ShadowRoot-setHTMLUnsafe">setHTMLUnsafe</span>((<code data-x="tt-trustedhtml">TrustedHTML</code> or DOMString) html);
[<span>CEReactions</span>] undefined <span data-x="dom-ShadowRoot-setHTMLUnsafe">setHTMLUnsafe</span>((<span data-x="tt-trustedhtml">TrustedHTML</span> or DOMString) html, optional <span>SetHTMLUnsafeOptions</span> options = {});
[CEReactions] undefined <span data-x="dom-ShadowRoot-setHTML">setHTML</span>(DOMString html, optional <span>SetHTMLOptions</span> options = {});
DOMString <span data-x="dom-ShadowRoot-getHTML">getHTML</span>(optional <span>GetHTMLOptions</span> options = {});

[<span>CEReactions</span>] attribute (<code data-x="tt-trustedhtml">TrustedHTML</code> or [<span>LegacyNullToEmptyString</span>] DOMString) <span data-x="dom-ShadowRoot-innerHTML">innerHTML</span>;
};

enum <dfn enum>SanitizerPresets</dfn> { "<span data-x="dom-SanitizerPresets-default">default</span>" };
dictionary <dfn dictionary>SetHTMLOptions</dfn> {
(<span>Sanitizer</span> or <span>SanitizerConfig</span> or <span>SanitizerPresets</span>) <span data-x="dom-SetHTMLOptions-sanitizer">sanitizer</span> = "<span data-x="dom-SanitizerPresets-default">default</span>";
};
dictionary <dfn dictionary>SetHTMLUnsafeOptions</dfn> {
(<span>Sanitizer</span> or <span>SanitizerConfig</span> or <span>SanitizerPresets</span>) <span data-x="dom-SetHTMLUnsafeOptions-sanitizer">sanitizer</span> = {};
};

dictionary <dfn dictionary>GetHTMLOptions</dfn> {
boolean <dfn dict-member for="GetHTMLOptions" data-x="dom-GetHTMLOptions-serializableShadowRoots">serializableShadowRoots</dfn> = false;
sequence&lt;ShadowRoot> <dfn dict-member for="GetHTMLOptions" data-x="dom-GetHTMLOptions-shadowRoots">shadowRoots</dfn> = [];
Expand Down Expand Up @@ -124706,27 +124717,27 @@ enum <dfn enum>DOMParserSupportedType</dfn> {

<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn
data-x="dom-Element-setHTMLUnsafe">setHTMLUnsafe</span>(<var>html</var>)</code></dt>
data-x="dom-Element-setHTMLUnsafe">setHTMLUnsafe</span>(<var>html</var>, <var>options</var>)</code></dt>

<dd>
<p>Parses <var>html</var> using the HTML parser, and replaces the children of <var>element</var>
<p>Parses <var>html</var> using the HTML parser with options <var>options</var>, and replaces the children of <var>element</var>
with the result. <var>element</var> provides context for the HTML parser.</p>
</dd>

<dt><code data-x=""><var>shadowRoot</var>.<span subdfn
data-x="dom-ShadowRoot-setHTMLUnsafe">setHTMLUnsafe</span>(<var>html</var>)</code></dt>
data-x="dom-ShadowRoot-setHTMLUnsafe">setHTMLUnsafe</span>(<var>html</var>, <var>options</var>)</code></dt>

<dd>
<p>Parses <var>html</var> using the HTML parser, and replaces the children of
<p>Parses <var>html</var> using the HTML parser with options <var>options</var>, and replaces the children of
<var>shadowRoot</var> with the result. <var>shadowRoot</var>'s <span
data-x="concept-DocumentFragment-host">host</span> provides context for the HTML parser.</p>
</dd>

<dt><code data-x=""><var>doc</var> = Document.<span
data-x="dom-parseHTMLUnsafe">parseHTMLUnsafe</span>(<var>html</var>)</code></dt>
data-x="dom-parseHTMLUnsafe">parseHTMLUnsafe</span>(<var>html</var>, <var>options</var>)</code></dt>

<dd>
<p>Parses <var>html</var> using the HTML parser, and returns the resulting
<p>Parses <var>html</var> using the HTML parser with options <var>options</var>, and returns the resulting
<code>Document</code>.</p>

<p>Note that <code>script</code> elements are not evaluated during parsing, and the resulting
Expand All @@ -124743,7 +124754,7 @@ enum <dfn enum>DOMParserSupportedType</dfn> {

<div algorithm>
<p><code>Element</code>'s <dfn method for="Element"><code
data-x="dom-Element-setHTMLUnsafe">setHTMLUnsafe(<var>html</var>)</code></dfn> method steps
data-x="dom-Element-setHTMLUnsafe">setHTMLUnsafe(<var>html</var>, <var>options</var>)</code></dfn> method steps
are:</p>

<ol>
Expand All @@ -124756,14 +124767,14 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
<li><p>Let <var>target</var> be <span>this</span>'s <span>template contents</span> if
<span>this</span> is a <code>template</code> element; otherwise <span>this</span>.</p></li>

<li><p><span>Unsafely set HTML</span> given <var>target</var>, <span>this</span>, and
<var>compliantHTML</var>.</p></li>
<li><p><span>Set and filter HTML</span> given <var>target</var>, <span>this</span>,
<var>compliantHTML</var>, <var>options</var>, and false.</p></li>
</ol>
</div>

<div algorithm>
<p><code>ShadowRoot</code>'s <dfn method for="ShadowRoot"><code
data-x="dom-ShadowRoot-setHTMLUnsafe">setHTMLUnsafe(<var>html</var>)</code></dfn> method steps
data-x="dom-ShadowRoot-setHTMLUnsafe">setHTMLUnsafe(<var>html</var>, <var>options</var>)</code></dfn> method steps
are:</p>

<ol>
Expand All @@ -124773,8 +124784,8 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
object</span>, <var>html</var>, "<code data-x="">ShadowRoot setHTMLUnsafe</code>", and "<code
data-x="">script</code>".</p></li>

<li><p><span>Unsafely set HTML</span> given <span>this</span>, <span>this</span>'s <span
data-x="concept-DocumentFragment-host">shadow host</span>, and <var>compliantHTML</var>.</p></li>
<li><p><span>Set and filter HTML</span> given <var>this</var>, <span>this</span>'s <span
data-x="concept-DocumentFragment-host">shadow host</span>, <var>compliantHTML</var>, <var>options</var>, and false.</p></li>
</ol>
</div>

Expand Down Expand Up @@ -124802,7 +124813,7 @@ enum <dfn enum>DOMParserSupportedType</dfn> {

<div algorithm>
<p>The static <dfn method for="Document"><code
data-x="dom-parseHTMLUnsafe">parseHTMLUnsafe(<var>html</var>)</code></dfn> method steps are:</p>
data-x="dom-parseHTMLUnsafe">parseHTMLUnsafe(<var>html</var>, <var>options</var>)</code></dfn> method steps are:</p>

<ol>
<li><p>Let <var>compliantHTML</var> be the result of invoking the <span
Expand All @@ -124828,12 +124839,48 @@ enum <dfn enum>DOMParserSupportedType</dfn> {
<li><p><span>Parse HTML from a string</span> given <var>document</var> and
<var>compliantHTML</var>.</p></li>

<li><p>Let <var>sanitizer</var> be the result of calling <span>get a sanitizer instance from options</span>
with <var>options</var> and false.</p></li>

<li><p>Call <span>sanitize</span> on <var>document</var> with <var>sanitizer</var> and false.</p></li>

<li><p>Return <var>document</var>.</p></li>
</ol>
</div>

</div>

<!-- https://github.com/WICG/sanitizer-api/commit/c4e328037ab6cd9c753b12694f5dcfc14988dec5 -->

<div hidden>
<!-- TODO -->
<dfn data-x="dom-element-sethtml"></dfn>
<dfn data-x="dom-parsehtml"></dfn>
<dfn data-x="dom-sanitizerpresets-default"></dfn>
<dfn data-x="dom-sethtmloptions-sanitizer"></dfn>
<dfn data-x="dom-sethtmlunsafeoptions-sanitizer"></dfn>
<dfn data-x="dom-shadowroot-sethtml"></dfn>
<dfn data-x="get a sanitizer instance from options"></dfn>
<dfn data-x="sanitize"></dfn>
<dfn data-x="sanitizer"></dfn>
<dfn data-x="sanitizerconfig"></dfn>
<dfn data-x="set and filter html"></dfn>
</div>

<h4>Safe HTML parsing methods</h4>

<dl class="domintro">
<!-- TODO -->
</dl>

<div w-nodev>

<div algorithm>
</div>

</div>


<h4>HTML serialization methods</h4>

<dl class="domintro">
Expand Down Expand Up @@ -125381,6 +125428,80 @@ interface <dfn interface>XMLSerializer</dfn> {

</div>

<h3>HTML sanitization</h3>

<h4>The <code>Sanitizer</code> interface</h4>

<pre><code class="idl">[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 allowAttribute(SanitizerAttribute attribute);
boolean removeAttribute(SanitizerAttribute attribute);
boolean setComments(boolean allow);
boolean setDataAttributes(boolean allow);

// Remove markup that executes script.
boolean removeUnsafe();
};</code></pre>

TODO

<h4>Sanitizer configuration</h4>

<pre><code class="idl">dictionary SanitizerElementNamespace {
required DOMString name;
DOMString? _namespace = "http://www.w3.org/1999/xhtml";
};

// Used by "elements"
dictionary SanitizerElementNamespaceWithAttributes : SanitizerElementNamespace {
sequence&lt;SanitizerAttribute> attributes;
sequence&lt;SanitizerAttribute> removeAttributes;
};

typedef (DOMString or SanitizerElementNamespace) SanitizerElement;
typedef (DOMString or SanitizerElementNamespaceWithAttributes) SanitizerElementWithAttributes;

dictionary SanitizerAttributeNamespace {
required DOMString name;
DOMString? _namespace = null;
};
typedef (DOMString or SanitizerAttributeNamespace) SanitizerAttribute;

dictionary SanitizerConfig {
sequence&lt;SanitizerElementWithAttributes> elements;
sequence&lt;SanitizerElement> removeElements;
sequence&lt;SanitizerElement> replaceWithChildrenElements;

sequence&lt;SanitizerAttribute> attributes;
sequence&lt;SanitizerAttribute> removeAttributes;

boolean comments;
boolean dataAttributes;
};</code></pre>

TODO

<h5>Configuration invariants</h5>

TODO

<h4>Processing model</h4>

TODO ("Algorithms" section)

<h4>Security consideration</h4>

TODO

<h3 split-filename="timers-and-user-prompts" id="timers">Timers</h3>

<p>The <code data-x="dom-setTimeout">setTimeout()</code> and <code
Expand Down
Loading