htmlpolicy

Overview ¶

Package htmlpolicy implements a policy-driven HTML, CSS, and SVG sanitizer.

Warning: until this library reaches v1.0.0, the API and policy language are liable to experience breaking changes between releases.

This library was built entirely through vibe coding with Claude Code (https://claude.ai/claude-code).

Unlike sanitizers that hardcode safety rules in library code, htmlpolicy uses declarative policies: plain text files where each line starts with an action verb followed by CSS selectors and optional arguments. Rules are evaluated top-to-bottom with last-match-wins semantics. Anything not matched by a rule passes through unchanged.

Policies can be reviewed, versioned, composed via includes, and swapped without recompiling. This makes htmlpolicy suitable for email rendering pipelines, CMS content filtering, user-generated content sanitization, and any HTML-to-HTML transformation where the rules need to be configurable.

Entry Points ¶

There are five entry points for applying a policy:

• Policy.ApplyHTML sanitizes an HTML fragment (user content to embed in a page).
• Policy.ApplyDocument sanitizes a full HTML document (preserves DOCTYPE/html/head/body).
• Policy.ApplyCSS sanitizes a standalone CSS stylesheet.
• Policy.ApplyInlineCSS sanitizes an inline CSS declaration list (style attribute content).
• ConvertToUTF8 converts content from a detected charset to UTF-8 (call before the others if needed).

All entry points expect UTF-8 input and return UTF-8 output. Input that is not valid UTF-8 is never passed through: every invalid byte sequence is replaced with U+FFFD before anything else reads it, exactly as a browser's UTF-8 decoder does (the WHATWG decoder: one U+FFFD per maximal invalid subpart, so E0 A0 41 becomes U+FFFD "A"), and the call reports the content as modified. This covers embedded data:text/html and data:text/css bodies (whose decoded bytes can be anything) and a URL rewriter's replacements, and it means a UTF-16 byte order mark (FE FF or FF FE, invalid in UTF-8) can never survive to make a browser decode the output as UTF-16; under WithPreserveOriginal such input is always re-serialized. Use ConvertToUTF8 first when the input is in another encoding: the replacement only keeps the sanitizer and the browser reading the same characters, it does not recover the text. Policy.ApplyHTML and Policy.ApplyDocument make sure a browser cannot read that output in another encoding with a different structure, at every depth of embedded content and regardless of policy: every U+001B (ESC — the ISO-2022-JP mode switch, which makes the decoder swallow ASCII quotes and angle brackets) and every U+000E/U+000F (SO/SI, which that decoder turns into U+FFFD, a CSS identifier character) in text, comments and attribute values is replaced with U+007F (DEL, a control character inert in the same places; an attribute whose name holds one is removed) before any rule is evaluated, so selectors, scheme rules and SMIL animation target ids see the DEL the browser will see, and every <meta charset> or <meta http-equiv=content-type> declaring an encoding other than UTF-8 is rewritten to "utf-8". The browser's encoding prescan reads a <meta> anywhere in the bytes, raw text included, and the multi-byte encodings (Shift_JIS, GBK, Big5, …) take ASCII bytes as the second byte of a character, so a <script>, <style>, <xmp>, <iframe> or <plaintext> whose text holds such a <meta> has that text removed, and a comment holding a <meta> that names a charset is dropped. Because the prescan also reads a quoted attribute value inside raw text across the element's end tag (`<style><x y="</style><!--"><meta …>-->`), the rendered output is finally scanned the way the prescan and the tokenizer read it; if a <meta> declaring another encoding is still visible, every comment holding a <meta> and every such raw-text element holding markup is removed, and if that does not help the output is empty. All of these are reported as modifications, and under WithPreserveOriginal input holding a raw ESC, SO or SI byte, or declaring an encoding other than UTF-8 anywhere, is always re-serialized. Policy.ApplyDocument also puts <meta charset="utf-8"> first in the <head> (unless one is already there), whatever the policy says about <meta>, and starts the output with a UTF-8 byte order mark when that <meta> does not end within the first 1024 bytes the encoding prescan reads (a long doctype, leading comments, large <html>/<head> attributes) or the input started with one; a BOM overrides both the transport charset and any <meta>, and a leading BOM in the input is never parsed as body text. A data:text/html URI whose body is re-encoded gets ";charset=utf-8" when it declares no charset (its parameters are replaced by ";charset=utf-8" when they hold quotes, whitespace or empty parts that MIME parsers read differently). (srcdoc needs neither: it is a string, never decoded from bytes.) Policy.ApplyCSS and Policy.ApplyInlineCSS do the same whenever they process the content (the policy has CSS rules or a URL rewriter is set): invalid UTF-8 becomes U+FFFD, ESC, SO and SI become DEL, and a leading @charset declaring an encoding other than UTF-8 is rewritten to @charset "utf-8". (Content they do not process — no CSS rules and no rewriter — is returned unchanged, invalid bytes included.) A Policy is safe for concurrent use by multiple goroutines.

Selectors ¶

Selectors use CSS syntax, compiled via github.com/andybalholm/cascadia. The policy accepts this subset and rejects anything else at parse time:

tag                     match all <tag> elements
*                       match all elements
#tracking               ID selector
.ads                    class selector
tag[attr]               attribute present
tag[attr=value]         exact attribute match
tag[attr~=word]         space-separated word match
tag[attr|=en]           exact match, or prefix followed by "-"
tag[attr^=prefix]       prefix match
tag[attr$=suffix]       suffix match
tag[attr*=substring]    contains match
tag[attr=value i]       i flag (accepted; see below)
"div.ads > a"           child combinator (quote when spaces present)
"svg animate"           descendant: <animate> inside <svg>
"h1 + p"                next-sibling combinator
"h1 ~ p"                subsequent-sibling combinator (see Cost)
:not([href^=https])     negation pseudo-class

The pseudo-classes are :not(), :has() and :haschild() (a selector list; :haschild(x) matches an element with a child matching x), :nth-child(), :nth-last-child(), :nth-of-type() and :nth-last-of-type() (An+B, odd or even), :first-child, :last-child, :first-of-type, :last-of-type, :only-child, :only-of-type, :empty, :root, :lang(), :link, :enabled, :disabled, :checked, :input (input, select, textarea and button), and :hover, :active, :focus, :visited and :target, which never match a static document. Rejected: pseudo-elements (::before), every other pseudo-class (cascadia implements neither :is() nor :where()), namespace prefixes (svg|a, *|*), comments, and cascadia's non-standard extensions — the text matchers :contains(), :containsown(), :matches() and :matchesown(), whose cost grows with the text under every element (div:contains(zzz) over 1 MB of 500-deep <div>s took about 5 seconds), and the attribute operators != (write :not([attr=value])) and #=. A Unicode space that CSS does not treat as whitespace (NBSP, U+2028, …) is an error outside a value: CSS reads it as part of a name, so "td<NBSP>a" would be one never-matching type selector.

Comma-separated selector groups (e.g. "script,style,iframe") compile into a single rule; empty groups are ignored. When a selector contains spaces, quote it so the parser distinguishes it from arguments: strip-tag "svg animate".

Cost: every selector shape is matched in time linear in the document except the subsequent-sibling combinator "~", which cascadia evaluates by scanning all earlier siblings of each element: O(siblings²) per parent (40,000 sibling <p> elements, 440 KB, take about 7 seconds under strip-tag "x ~ p"). Prefer "+", :nth-child or a class; Policy.Lint warns about a "~" combinator.

The parser decodes every CSS escape once and lowercases names and values, and keeps the selector in a canonical form: the text cascadia compiles and Policy.String writes. It has no spaces in lists or around combinators other than the descendant one, every attribute value quoted, and every escape it needs as \HEX followed by a space ("a , b" is written a,b, [title=x\,y] as [title="x,y"], .\31 0 as is). A hex escape of zero, a surrogate or a value past U+10FFFF means U+FFFD, as does a NUL byte or invalid UTF-8 in the selector.

An attribute value need not be quoted ([width=1], [href^=javascript:]). Attribute values follow CSS: whitespace after the operator is ignored ([title= "x y"] is the value "x y"); an unquoted value runs to the first unescaped "]", and in it a backslash escapes the next character ([title=x\,y] and [title=\2c] both mean a comma, [title=x\]] a bracket) and unescaped trailing ASCII whitespace is dropped; only ASCII whitespace separates a trailing i flag — a non-breaking space is part of the value. The i flag adds almost nothing: values are lowercased on both sides, so matching is case-insensitive without it; with it cascadia also folds the few characters lowercasing leaves distinct (ſ matches s). The s flag is rejected, since a case-sensitive match cannot be expressed.

Tag matching is case-insensitive. Attribute value matching normalizes control characters and case internally for security, without modifying the output. This prevents bypasses like " javascript:" evading a [href^=javascript:] prefix check, or JaVaScRiPt: evading case-sensitive matching. The normalization applies to every element a selector inspects — ancestors, siblings and :has() descendants as well as the matched element — so div:has(a[href^=javascript:]) also matches an href of "JAVASCRIPT:…", and div.Ads img matches inside <div class="ads">.

Selectors are matched against the input document as it was before any rule acted on it: an ancestor whose attributes another rule stripped, a preceding sibling another rule removed, or a wrapper that was demoted or unwrapped is still seen as written. With "strip-attr div class", strip-tag "div.ads img" still strips the images, and with "strip-tag script", strip-tag "script + img" still matches the image that followed the script. SMIL animation values are judged against the same view of their target element.

HTML Tag Verbs ¶

Tag verbs determine what happens to matched elements. Each takes a single selector and nothing else — attributes are handled only by the -attr verbs below:

strip-tag SELECTOR[,...]         remove element and all content
comment-out-tag SELECTOR[,...]   wrap in HTML comment
placeholder-tag SELECTOR[,...]   replace with [removed: tag] label
demote-tag SELECTOR[,...]        convert to <div>/<span>
allow-tag SELECTOR[,...]         keep element (attributes still filtered separately)
unwrap-tag SELECTOR[,...]        remove the element's tags but keep its children

Inline elements demote to <span>, all others to <div>. The namespace is cleared, so foreign elements (SVG, MathML) become plain HTML. Inside SVG or MathML content outside an integration point (<foreignObject>, <desc>, <title>, <mi>, <mo>, <mn>, <ms>, <mtext>, HTML <annotation-xml>), where an HTML element cannot appear, demote-tag unwraps the element instead: its children are kept in its place. Demoting an <svg> or <math> root itself does make it a <div>, but its SVG/MathML child elements cannot stay inside an HTML element and are removed by the namespace validation below, so little more than text placed directly in the root survives.

Unwrap removes the wrapper but leaves the children in flow (mirroring how browsers treat unknown elements). The wrapper's attributes are discarded; void/empty elements with no children are stripped. As a catch-all in an allowlist policy, "unwrap-tag *" MUST be paired with explicit strip rules for any element whose presence indicates active content or whose text content should not be visible — at a minimum: script, style, iframe, object, embed, form, input, textarea, select, button, link, base, meta. Without those, raw <script>/<style> text would leak into the output as visible text once the wrapper is removed.

Children of a demoted or unwrapped element are processed before the element is renamed or removed, so selectors match the original structure: with "demote-tag form", strip-tag "form input" still matches the inputs. A selector written against the transformed shape (e.g. "div input" for a demoted form, or "section > b" across an unwrapped wrapper) does not.

A tag verb takes exactly one selector token. A bare second word is an error, because it is almost always a mistake — either an attribute name (use an -attr verb) or an unquoted descendant combinator. To match a descendant combinator, quote the whole selector so the space is unambiguous:

# keep <a>
allow-tag a
# ...and keep its href attribute
allow-attr a href
# strip <a> elements inside <td> (descendant selector)
strip-tag "td a"
# ERROR: unexpected "a" after selector "td"
strip-tag td a

Comments in a policy are full-line only (a line starting with #); a trailing "# …" after a rule is read as part of its arguments.

HTML Attribute Verbs ¶

Attribute verbs filter attributes on matched elements. Attribute name patterns support a trailing * glob: on* matches onclick, onload, etc.

strip-attr SELECTOR ATTR[,...]      strip named attrs
allow-attr SELECTOR ATTR[,...]      allow only named attrs
defang-attr SELECTOR ATTR[,...]     rename to PREFIX-defanged-ATTR

URL Scheme Verbs ¶

Scheme verbs filter URL attributes by the URL's scheme. Use :relative to match document-relative URLs, :protocol-relative to match authority-relative ones, * to match any scheme:

allow-scheme SELECTOR ATTR SCHEME[,...]     allow URLs with listed schemes
strip-scheme SELECTOR ATTR SCHEME[,...]     strip URLs with listed schemes
defang-scheme SELECTOR ATTR SCHEME[,...]    neutralize URLs when scheme matches

For allowlist behavior, pair with a strip-scheme baseline:

strip-scheme * href *
allow-scheme * href https,mailto,:relative

Each scheme must be a valid URL scheme (an ASCII letter followed by letters, digits, "+", "-", or "."), the wildcard *, or one of the two pseudo-schemes :relative and :protocol-relative. Comma-separated lists reject a stray comma between entries (e.g. "http,,https") to catch typos.

A meta refresh URL (<meta http-equiv=refresh content="0;url=...">) is matched as element meta, attribute content, by both scheme and content-type rules. A strip removes the whole content attribute: leaving "0;url=" behind would make the browser reload the current page.

Browsers do not all read a refresh value the same way, so a content value on which they could disagree is removed whatever the policy, before any rule sees it: one whose delay (the text before the first ";", "," or space) is anything but digits and dots — the WHATWG refresh steps ignore such a refresh, but Chromium and WebKit parse the delay as a number, so "0e0;url=…", "+0;url=…" and "-0;url=…" navigate in them — and one whose URL starts or ends with Unicode whitespace (U+3000, U+2003, …), which Chromium and WebKit trim and the URL parser keeps, so that "0;url=\u3000data:text/html,…" is a relative URL to one and a data: document to the other — and one whose quoted URL ends at a different quote for each: the spec ends it at the first matching quote, Chromium and WebKit at the last, so "0;url='data:text/html,hi'<script>…</script>'" carries the script only for them. The removal counts as a change, so such a value is never returned verbatim under WithPreserveOriginal.

SVG presentation attributes that take a CSS image or paint value (fill, stroke, filter, clip-path, mask, marker, marker-start/-mid/-end, cursor) are read as CSS: every url() in the value — including an escape-encoded function name such as \75 rl( — and every string inside image-set(), cross-fade(), image() or src() (vendor-prefixed or not) is a URL matched by scheme rules under the attribute's own name; the most restrictive action wins for the whole attribute. A var(), env() or attr() inside one of those functions, or an attr() anywhere in the value, hides the URL it substitutes, so the attribute is removed whenever the policy has scheme rules. A data: URI in any of those slots is matched by content-type rules under the attribute's name too (most restrictive slot wins: a strip removes the attribute, a defang renames it), and one naming an embedded document — text/html or any XML type — removes the attribute whatever the policy, since such a slot is not recursed. A SMIL animation of one of these attributes is judged keyframe by keyframe the same way.

Relative URLs: :relative vs :protocol-relative ¶

A URL with no scheme is classified as one of two distinct pseudo-schemes, because the two behave nothing alike:

• :relative — a reference resolved against the current document's URL: "/img/logo.png", "logo.png", "#section", "?q=1". It never leaves the page's origin, but it is still a real request to that origin, sent with its cookies — allowed on an auto-fetching attribute such as <img src>, user content can make the viewer's browser issue a same-origin GET such as "/logout" (GET-CSRF).
• :protocol-relative — an authority-relative (commonly "protocol-relative") URL such as "//cdn.example.com/x". It has no scheme of its own, but the browser inherits the containing document's scheme and fetches from the host after the slashes, so on an https page "//evil.example/x" is exactly "https://evil.example/x" — a remote load.

Only :protocol-relative matches the second kind. This matters for the standard allowlist shape, where an author writing :relative means "references to my own origin" and would not expect it to permit an arbitrary remote host:

strip-scheme * * *
# no remote via //host:
allow-scheme * * http,https,:relative
# or, to permit //host:
allow-scheme * * http,https,:relative,:protocol-relative

The wildcard * matches both kinds, so any "strip every scheme" baseline still covers authority-relative URLs. Conversely a rule naming only :relative does not act on them — "strip-scheme * href :relative" leaves "//host/x" alone; add :protocol-relative to cover both.

Classification matches what a browser's URL parser does rather than the literal bytes: tab, LF, and CR are ignored wherever they appear (browsers strip them from URLs), a backslash counts as a slash, and CSS escapes in CSS values are decoded first. So "/\/host", "\\host", "/<tab>/host", and the CSS "url(\2f\2f host)" are all :protocol-relative. When a <base href> is present these URLs are resolved against it before rules run, and are then classified by the resulting real scheme.

A URL with a special scheme (http, https, ws, wss, ftp) that is not followed by "//" — "https:logout", "https:/account/delete", "http:x" — is read two ways by the browser: on a page with the same scheme it is a relative reference (a same-origin request, like :relative), on any other page the missing slashes are ignored and it is an absolute URL whose host follows the colon. It is therefore evaluated both as its scheme and as :relative, and the more restrictive outcome wins: the allowlist above permits "https:logout" only when it allows both https and :relative, and a strip of either strips it. With a <base href> it is resolved first, as the browser does ("https:x.png" against an https base is the relative "x.png"; "http:evil.example/x" against it is "http://evil.example/x").

Every URL is judged under two readings, and again the more restrictive outcome wins. Scheme matching first normalizes fail-closed — it removes zero-width and invisible characters and every C0 control, so "\u200bjavascript:x" and "java\x01script:x" are javascript: URLs to the rules — but a browser does not remove those characters: it stops reading the scheme at them or percent-encodes them. So each URL is also judged as the browser reads it (the URL parser's own input cleanup only): "https:/\u200b/../account/delete" is an https URL to the normalization and, to the browser, the same-origin relative reference "https:/%E2%80%8B/../account/delete" (GET /account/delete), and "ht\x01tps://…" is a relative path. A rule against either reading — a strip of javascript, or of :relative (as the allowlist above implies) — therefore strips the URL. This holds for HTML URL attributes, srcset entries, meta refresh, SVG url() values, SMIL values and CSS url().

defang-scheme is attribute-aware. For href on <a> and <area> (including an SVG <a>'s xlink:href) it prefixes the URL's scheme in place with PREFIX-defanged — for example href="bitcoin:..." becomes href="htmlpolicy-defanged:bitcoin:...". The PREFIX-defanged scheme is registered nowhere, so the link is inert, but the URL stays in href and therefore remains hoverable and copyable. This lets a reader copy or inspect app-protocol links (bitcoin:, tel:, slack:, ...) that the policy does not allowlist. The transform is fail-safe (prefixing only ever breaks a URL, never activates one) and idempotent (a value that already carries the PREFIX-defanged scheme passes through unchanged on re-apply). For every other attribute, defang-scheme renames the attribute to PREFIX-defanged-ATTR (so an auto-loaded resource such as <img src> never fires a request) just like defang-attr.

Multi-URL attributes (srcset, imagesrcset, ping, archive, attributionsrc) get per-URL evaluation — each URL is independently matched against the rule chain — and always use the attribute-rename form (they are auto-loaded, not hovered).

Content-Type Verbs ¶

Content-type verbs control what happens to data URIs based on their MIME type. MIME patterns support a single * wildcard: image/*, *+xml, */xml. The type matched is the one a browser uses: lowercased type/subtype without parameters, and text/plain when the data URI names none or an invalid one (data:,… data:;charset=utf-8,… data:foo,…).

allow-content-type SELECTOR ATTR TYPE[,...]     allow data URIs with listed types
strip-content-type SELECTOR ATTR TYPE[,...]     strip data URIs with listed types
defang-content-type SELECTOR ATTR TYPE[,...]    rename attr when type matches

text/html data URIs are recursively sanitized (the HTML5 parser matches the browser), while XML data URIs — any type a browser parses with its XML parser: image/svg+xml, text/xml, application/xml, application/xhtml+xml, and every other */xml or *+xml type (application/xhtml is treated as XHTML too) — are always stripped. There is no allow-content-type opt-in: the HTML5 parser restructures an XML document (it moves a <td> outside a table, drops a nested <form>, reads <textarea>/<xmp>/<iframe> content as inert text, and models neither DTD entities nor namespace prefixes), so no rule can judge what the browser builds, and an XHTML-namespaced <script> runs inside any XML document, SVG included. This covers URL attributes, srcset/ping entries, meta refresh URLs, SVG url() presentation attributes (fill, filter, mask, cursor, …; there text/html is stripped too, as it is not recursed) and SMIL animated values; inline <svg> elements, and SVG in a CSS url() (see css-*-content-type below), are unaffected. Content-type rules apply at all of those sites, matched under the attribute's name. Policy.Lint warns about an allow-content-type rule whose type list names or globs (image/*, *+xml, *) an XML type. Other data URIs pass through unchanged unless a content-type rule matches.

A text/html document (or any XML type) as a form's action or a button's or input's formaction is always removed, whatever the policy, rather than sanitized: a GET submission appends the form's fields to the URL as a query, and the data: URL processor keeps the query in the document's body, so field names and values the recursion never saw (an attacker's <input type=hidden value="<script>…">) become its markup.

Independently, any data URI declaring a charset the library cannot reproduce faithfully (anything other than UTF-8, US-ASCII, or none — e.g. UTF-7 or UTF-16) is stripped, because the content is decoded to raw bytes and handed to the UTF-8/ASCII HTML5 parser; a browser honoring the declared charset would decode different markup (a charset differential). UTF-8's aliases (unicode-1-1-utf-8, unicode11utf8, unicode20utf8, utf8, x-unicode20utf8) are accepted as equivalent to "utf-8". The body counts too, since a browser lets it override the declared charset: a body starting with a UTF-16 byte order mark, or declaring a different encoding itself (a <meta charset>, an @charset rule, an XML declaration), is stripped the same way. For the same reason a data URI whose content would be sanitized (text/html, text/css) is stripped when a "base64" parameter appears anywhere but last (data:text/html;base64;charset=utf-8,…): the WHATWG data: URL processor reads that body as percent-encoded text, Chromium as base64. A data URI's media type is read the way a browser reads it, after the URL parser has percent-encoded control and non-ASCII bytes: "text/html\u00a0" is the inert type text/html%c2%a0, not text/html. Where such bytes (or percent escapes) would make the type text/html, XML or text/css if trimmed or decoded, the data URI is stripped rather than guessed at.

A data: URI whose recursive sanitization is refused — an XML type, a non-reproducible charset (declared, a UTF-16 BOM, or declared in the body), a base64 parameter that is not the last one, an ambiguous media type, or the recursion-depth limit (16 levels) — has its whole attribute removed rather than left as an empty value: an empty src/href is itself a URL (the document's own), not "no URL". In a meta refresh the whole content attribute is removed, since a residual "0;url=" reloads the document; in a srcset/ping list only that entry is dropped; a SMIL animation left with no value is removed; in CSS the declaration or @import carrying it is dropped (an empty url() would fetch the stylesheet's own URL), and a <link href="data:text/css,…"> loses its href. The same applies to srcdoc past the recursion-depth limit, except when the iframe also carries a src attribute: since srcdoc always overrides src when present, removing srcdoc there would newly activate src (already independently scheme/content-type-filtered), so srcdoc is emptied instead of removed.

CSS Verbs ¶

CSS verbs process style attributes, <style> element contents, data:text/css URIs, and SMIL animated style values. They follow the same last-match-wins semantics as HTML rules. Without CSS rules, CSS content passes through unchanged. HTML scheme rules (strip-scheme etc.) do NOT apply to CSS — use css-*-scheme rules instead. An SVG or MathML <style> is not raw text, so it can have element children; a browser's style sheet reads only the element's own text, so when the policy has CSS rules (or a URL rewriter is set) every other child is removed before the CSS is sanitized.

css-strip PROP[,...]                    strip CSS properties (bare name matches vendor-prefixed variants)
css-allow PROP[,...]                    allow CSS properties
css-defang PROP[,...]                   defang CSS properties (prefix name)
css-strip-value PATTERN                 strip properties matching value pattern
css-defang-value PATTERN                defang properties matching value pattern
css-strip-at NAME[,...]                 strip CSS at-rules (e.g. import, * = all)
css-allow-at NAME[,...]                 allow CSS at-rules
css-defang-at NAME[,...]                defang CSS at-rules (prefix name)
css-strip-scheme TARGET SCHEME[,...]         strip CSS url() values by scheme
css-allow-scheme TARGET SCHEME[,...]         allow CSS url() values by scheme
css-defang-scheme TARGET SCHEME[,...]        defang CSS url() values by scheme
css-strip-content-type TARGET TYPE[,...]     strip CSS url() data: URIs by MIME type
css-allow-content-type TARGET TYPE[,...]     allow CSS url() data: URIs by MIME type
css-defang-content-type TARGET TYPE[,...]    defang CSS url() data: URIs by MIME type
css-strip-pseudo NAME[,...]                  strip selectors using a pseudo-class/element
css-allow-pseudo NAME[,...]                  allow pseudo-classes/elements
css-strip-media FEATURE[:VALUE][,...]        strip @media blocks by media feature
css-allow-media FEATURE[:VALUE][,...]        allow @media blocks by media feature
css-strip-medium TYPE[,...]                  strip media-conditional CSS that can apply to a medium
css-allow-medium TYPE[,...]                  allow media-conditional CSS by medium

The css-*-scheme and css-*-content-type TARGET is a comma-separated list of CSS property name patterns or @import (which matches only @import's URL). Use * to match all properties and every at-rule URL (@import, @namespace, block at-rule preludes). Scheme lists support :relative, :protocol-relative, and * with the same meanings as in HTML scheme rules; content-type TYPE lists use the same MIME patterns as the HTML content-type verbs (a single * wildcard, e.g. image/*, *+xml).

A URL in a custom property (--x: url(…)), or in @property's initial-value descriptor, can reach any property through var(), so it is judged under every property TARGET the policy's css-*-scheme (respectively css-*-content-type) rules name, plus its own name and *, and the most restrictive outcome wins: css-strip-scheme background-image * also strips the URL of --x: url(…); background-image: var(--x), and a rule targeting only the custom property cannot re-allow a URL that a rule for another property strips.

css-*-content-type filters data: URIs found in CSS url() values and @import by their MIME type — the CSS counterpart of the HTML content-type verbs (HTML content-type rules do not apply to CSS). It composes with css-*-scheme as AND (the most restrictive of the two decisions wins). When no css-*-content-type rule matches a url() data: URI, the default applies: text/css is recursively sanitized and SVG/XHTML data: URIs are best-effort recursed (a CSS url() loads in the browser's secure mode, with no scripting) — unlike the same URIs in an HTML attribute, which are always stripped. It applies to url() and @import data: URIs and equally to bare-string URL arguments of image-set()/cross-fade()/image()/src(), which browsers load exactly like url() tokens.

The css-*-pseudo verbs filter CSS selectors (in <style> elements, data:text/css, and standalone Policy.ApplyCSS) by pseudo-class or pseudo-element name. Each comma-separated NAME may carry an optional leading "::" to match pseudo-elements only or ":" to match pseudo-classes only; a bare name (or *) matches either kind. Names support a trailing * glob. The four legacy single-colon pseudo-elements (:before, :after, :first-line, :first-letter) are always treated as pseudo-elements.

When a pseudo with action strip matches anywhere within a complex (comma-separated) selector — including nested inside functional pseudo-classes such as :has(), :is(), :not(), :where() — that entire complex selector is dropped; if every complex selector in a ruleset is dropped, the whole ruleset is removed. This only ever narrows which elements a style applies to. As with other CSS verbs, evaluation is last-match-wins per pseudo and unmatched pseudos pass through, so an allowlist is written as "css-strip-pseudo *" then "css-allow-pseudo hover,focus". An @scope prelude's root and limit selector lists ("@scope (.card:hover) to (.content)") are filtered too: a stripped pseudo in either removes the whole @scope rule, since dropping only a limit selector would widen the scope. Pseudo filtering does not apply to inline style attributes (which have no selectors) or to other at-rule preludes such as @page :first or @keyframes stops.

The css-*-media verbs filter CSS @media query blocks (and @import media conditions) by media feature. Each comma-separated entry is a media feature or media type with an optional ":VALUE", e.g. "prefers-color-scheme:dark", "prefers-*", or "print"; both FEATURE and VALUE support a trailing * glob, omitting ":VALUE" matches the feature regardless of value, and a bare * matches any @media block. When a strip rule matches, the whole @media block (or @import) is removed. Matching is feature-presence based: the prelude is scanned through "not"/"only"/"and"/"or" combinators, so "not (prefers-color-scheme: dark)" is matched on presence, not semantically inverted, and modern range syntax such as "(width >= 600px)" is matched only by feature name, not value. An entry prefixed with "!" (e.g. "!prefers-color-scheme:light") matches only a feature written negated: "not (FEATURE…)", or any feature (and the media type) of a query negated as a whole, "not TYPE and (FEATURE…)" — so "not all and (prefers-color-scheme: light)" counts as a negated light check, while a feature negated twice ("not all and not (…)") does not; unprefixed entries keep matching on presence. This is a narrow form of negation, not full boolean evaluation. For @import, the URL and any layer(…)/supports(…) prefix are skipped before the media condition is scanned. css-*-media is more specific than the @media keyword, so a matching media rule overrides any css-*-at decision for that block (e.g. "css-strip-media *" then "css-allow-media screen" keeps only screen queries). There is no defang variant — like css-*-pseudo, media queries gate block applicability rather than carrying a value to neutralize. Like css-*-pseudo, css-*-media does not apply to inline style attributes (a declaration list has no at-rules) — only to <style> elements, stylesheets (Policy.ApplyCSS), and data:text/css. A bare "css-strip-media *" strips every @media block, and every @import that carries a media condition, but leaves a plain @import (no media condition) to the css-*-at rules.

A common use is forcing light mode by stripping dark-mode overrides ("css-strip-media prefers-color-scheme:dark"); see the strip-dark-mode built-in preset.

The css-*-medium verbs filter media-conditional CSS by media type (medium): "css-strip-medium print" removes every @media block, every @import with a media-query-list, and every <style media="…"> and <link rel=stylesheet media="…"> element whose media query list CAN evaluate true when printing. Each comma-separated TYPE is a media type name (print, screen, speech, or any other identifier) or * for any medium. Unlike css-*-media, which matches on the presence of a feature name, a medium rule evaluates each query's media type and "not": a query can apply to medium M unless its media type is a different type ("screen", "only screen and (color)"), or it is exactly "not M" or "not all". Media features are ignored, so over-matching is the deliberate direction: "all and (update: none)", a features-only query such as "(min-width: 0)", "not screen", "not print and (color)" (= not (print and color)), an empty list ("@media {…}", media="") and any query this library cannot read (a malformed query, which a browser evaluates as "not all") all count as able to apply to every medium. A query list matches when any of its comma-separated queries does, so "screen, print" matches print. Media types are compared ASCII-case-insensitively after CSS escape decoding, and a prelude is re-lexed as emitted first, so comment- or escape-split forms are read the way a browser reads the output. css-*-medium does not touch unconditional CSS (no @media, a plain @import, <style> without a media attribute), which applies to every medium alike.

Evaluation is last-match-wins within the family ("css-strip-medium print" then "css-allow-medium screen" keeps "@media screen, print", which can also apply to screen). Like css-*-media, a matching medium rule is more specific than the @media/@import keyword and overrides css-*-at, so "css-strip-at media" then "css-allow-medium screen" keeps screen blocks. css-*-media and css-*-medium are evaluated independently and combined as AND: a block either family strips is removed, and an allow from one family never re-keeps a block the other strips. The HTML side (<style media>, <link rel=stylesheet media>, any rel list containing "stylesheet", in any namespace) is only governed by css-*-medium; the element is removed whole; the media attribute is read as CSS input (preprocessed and escape-decoded like a stylesheet). It is judged after attribute rules, so a policy that strips or defangs the media attribute itself turns the sheet unconditional (applying on every medium) before css-*-medium sees it. Rule order between the families does not matter. There is no defang variant.

The intended use is removing print beacons ("@media print { body { background: url(https://t.example/printed) } }") with "css-strip-medium print". @page rules (and their margin boxes) apply only to paged media and are not media-conditional blocks; add "css-strip-at page" to remove them too.

Property (css-strip/css-allow/css-defang), at-rule (css-*-at), scheme TARGET (css-*-scheme), and pseudo (css-*-pseudo) NAME matching is vendor-prefix-insensitive: a bare pattern matches both the canonical name and every vendor-prefixed variant, because browsers alias -webkit-foo, -moz-foo, -ms-foo, etc. to foo. So css-strip transform also strips -webkit-transform, css-strip-at keyframes also strips @-webkit-keyframes, and css-strip-pseudo scrollbar also drops ::-webkit-scrollbar. An explicitly hyphen-prefixed pattern (e.g. css-strip -webkit-transform) matches only that single variant — the escape hatch for targeting one vendor. Matching is name-only and never rewrites the surviving bytes; custom property names (--x) are not treated as vendor-prefixed.

CSS allowlist example:

css-strip *
css-allow color,background-color,font-size,font-family,font-weight
css-allow text-align,text-decoration,margin,padding,border
css-strip-value expression(*)
css-strip-value url(*)
css-strip-at *

The url(*) value pattern also matches a bare string argument of a URL-accepting function (image-set("x" 1x), cross-fade(), image(), src()), which browsers load as a URL. A var() argument is not a string and is not matched; css-*-scheme rules are the comprehensive URL guard. The string of image-set()'s type("image/avif") or src()'s integrity("…") is not a URL and is neither matched, scheme-checked, nor passed to a URL rewriter.

A css-*-value pattern not ending in "(*)" matches the whole declaration value: case-insensitively, after CSS escape decoding, and ignoring surrounding whitespace and a trailing !important, so css-strip-value fixed strips position:fixed and position:fixed !important alike.

CSS blocklist example:

css-strip -moz-binding,behavior
css-strip-value expression(*)
css-strip-at import
css-strip-scheme * javascript,vbscript,data,blob

Standalone CSS sanitization is available via Policy.ApplyCSS (stylesheets) and Policy.ApplyInlineCSS (declaration lists).

Other Verbs ¶

prefix NAME                  set the prefix for defang/comment-out names (default "htmlpolicy"; lowercased in defanged attribute and CSS names)
placeholder-label LABEL      customize the label for placeholder (default "removed")
strip-comments               remove HTML comments
include NAME-OR-PATH         inline another policy (loaded via [Resolver])
include builtin:NAME         inline a built-in preset (no [Resolver] needed)

prefix, placeholder-label and strip-comments are policy-global: the last occurrence anywhere in the include tree wins, including one inside an included file or a built-in preset (no built-in preset sets prefix or placeholder-label). An include is not a scope — it is inlined where it appears. Includes nest at most WithMaxIncludeDepth levels deep, and one Parse call expands at most 1024 include directives in total (a file included twice counts twice), so a policy tree that re-includes the same files exponentially fails to parse instead of expanding without bound.

Lines starting with # are comments. Only full-line comments are supported.

Linting ¶

Policy.Lint statically analyzes a compiled policy for likely mistakes (without applying it) and returns advisory Warning values: URL attributes reopened with no scheme baseline; allow-scheme rules that reopen a dangerous scheme (javascript/vbscript, or data: unless a content-type baseline denies unlisted types on the attribute or the reopen names only image/media elements) an earlier scheme rule stripped; allow-content-type rules whose type list names or globs an XML type, which is always stripped regardless; allow-attr rules that reopen a dangerous non-URL attribute (on* handlers, nonce, is, shadowrootmode, srcdoc) an earlier strip-attr removed; css-allow-scheme rules that reopen javascript or data (with no css-*-content-type rule) on CSS url() values after an earlier css-strip-scheme; allow-tag rules that reopen a dangerous element (script, iframe, object, embed, base, meta, link, template, fencedframe, portal) an earlier rule neutralized — in any of the shapes it takes (bare, with the attributes that make it active such as meta http-equiv=refresh or iframe srcdoc, in a document body, an SVG <script>); allow rules that are dead because nothing earlier strips what they permit, so they only restate the passthrough default; rules made dead by a later same-family rule (last match wins by order, so an allow placed before a universal strip never fires); and "unwrap-tag *" used as a catch-all without strip rules for active-content elements. The CLI exposes this as "htmlpolicy -lint", which exits non-zero when a policy produces warnings.

Built-in Presets ¶

The library ships a small set of maintained policy presets, includable as "include builtin:NAME" from any policy with no Resolver configured. They are ordinary policy text — fully inlined by Policy.String, and overridable by any later rule under last-match-wins — so they are a safe, reviewable starting point rather than hidden engine behavior. Upgrading the library picks up preset improvements (e.g. coverage for newly recognized HTML features). Available presets:

builtin:blocklist        strong blocklist baseline (strips active-content
                         elements/attributes, dangerous URL schemes, and
                         data: on auto-fetching attributes; everything
                         else passes through)
builtin:allowlist-base   fail-closed skeleton (strips all elements,
                         attributes, schemes, content types, and CSS;
                         follow it with your own allow rules)
builtin:url-safe         restrict every URL attribute to http, https,
                         mailto, and relative URLs (pair with rules that
                         reopen URL-bearing attributes)
builtin:strip-dark-mode  remove dark-mode signals: prefers-color-scheme
                         dark @media overrides, the color-scheme property
                         and <meta>, and Apple Mail's legacy
                         supported-color-schemes property and <meta>

builtin:strip-dark-mode strips the dark-mode mechanism, not author-chosen colors: a page that defaults to light and adds a dark @media override (the common case) renders light afterward, but a page hardcoded dark with no media query is not repainted. It does not guarantee a light result.

Use BuiltinPolicy to fetch a preset's text in Go and BuiltinPolicyNames to list them. Because allowlist-base reopens nothing on its own, building an allowlist on top of it fails safe: forgetting to re-allow a rule family drops content rather than passing it through.

In document mode (Policy.ApplyDocument, and the embedded documents of srcdoc and data:text/html at every depth) a document's own <html>, <head> and <body> are never removed. Last match wins as for any element; only the effect of a non-allow action differs. When the last matching tag rule is a catch-all — the bare "*" (allowlist-base's strip-tag * baseline), or any selector that, like it, matches every element whatever its name, attributes, position or content: *,script or :not(p) — with an action other than allow-tag, they are kept as document structure with their attributes removed, and their children are judged by their own rules, as if unwrapped — even if an earlier rule named them (allow-tag body followed by strip-tag * still removes <body onload>). When the last matching rule names them, strip-tag, comment-out-tag and placeholder-tag keep the bare element but remove its children and attributes (strip-tag head drops the <meta>, <link> and <style> elements in the head; strip-tag html empties the document), demote-tag and unwrap-tag keep it as structure with its attributes removed, and allow-tag keeps it with its attributes filtered by the attribute rules (a later allow-tag * overrides an earlier strip-tag head). Add "allow-tag html,head,body" (plus allow-attr rules) after any strip-tag * baseline to keep attributes such as <html lang>. A selector that depends on anything about the element — its name, an attribute, an ancestor ("html *"), being the root, first, last or only child (:root, :not(:first-child)) or its content (:empty, :has(…)) — is not a catch-all and counts as naming them, so with strip-tag it empties them (fail-safe; follow it with allow-tag html,head,body to keep the document).

URL Rewriting ¶

WithApplyURLRewriter is an ApplyOption that sets a callback that receives every URL in the sanitized output and can replace it. The rewriter is scoped to a single Apply call, so it may safely close over per-call state (caches, counters, accumulators) without concurrency concerns. The rewriter runs after policy evaluation and base URL resolution. It covers HTML URL attributes, CSS url() values, srcset entries, SVG url() attributes, meta refresh URLs, and SMIL animation values. URLs inside recursively-sanitized data:text/html content are also rewritten. Stripped and defanged URLs are excluded. Fragment-only references, empty URLs, and data: URIs themselves are excluded (but URLs inside data URI content are recursed into). The option also works with Policy.ApplyCSS and Policy.ApplyInlineCSS.

WithOriginalURLAttr preserves the pre-rewrite value of every HTML attribute the rewriter changed as a companion "{prefix}-original-{attrname}" attribute on the same element, so the original URL can be recovered from the output. Pre-existing attributes matching that reserved pattern are stripped from the input first (spoof prevention); WithKeepOriginalURLAttrs opts out of the stripping for trusted re-processing of this library's own prior output.

WithApplyURLPrefetcher is a companion ApplyOption that receives the full set of URLs the rewriter would be called with — same set, same resolved form, same dedup, in document order — once per call, before the rewrite pass. It lets a caller warm a cache (e.g. fetch image and font resources in parallel) that the subsequent synchronous rewriter reads from. Each URLRef carries a live URLContext (including GetAttr) so the caller can inspect sibling attributes when deciding what to fetch.

Output Normalization ¶

By default, Policy.ApplyHTML and Policy.ApplyDocument always re-serialize through Go's HTML5 parser, even when no rules modified the content. This prevents parser-differential attacks. Use WithPreserveOriginal to return the original bytes when no rules match.

This applies at every recursion depth: srcdoc values and recursed data:text/html bodies (in URL attributes, srcset/ping entries, meta refresh and SMIL values) are re-serialized and re-encoded even when no rule fired (base64 bodies stay base64); the modified result still reports only rule changes. WithPreserveOriginal leaves unmodified embedded content verbatim at every depth. (XML data: URIs in HTML attributes are always stripped, so are never re-serialized; SVG/XHTML recursed from a CSS url() is left verbatim unless a rule fired, since a browser parses it as XML and an HTML5 re-serialization could change the document.)

Embedded Content Sanitization ¶

HTML embedded inside attribute values is recursively sanitized: data:text/html URIs, srcdoc attributes, and meta refresh URLs. Recursion depth is limited to 16 levels; at the limit, content is stripped entirely. A data:text/html form action or formaction is removed instead, since the submitted fields join the document (see Content-Type Verbs).

XML data: URIs (image/svg+xml, text/xml, application/xml, application/xhtml+xml, any */xml or *+xml) in those positions — URL attributes, srcset/ping entries, meta refresh URLs, SVG url() presentation attributes and SMIL animated values — are always stripped rather than recursed, because the HTML5 parser cannot match a browser's XML parser; no allow-content-type rule re-enables them (see Content-Type Verbs). See Limitations.

The text of <noscript>, <noframes> and <noembed> (raw text to a scripting-enabled browser, markup to a scripting-disabled one) is parsed as HTML, sanitized by the same rules and written back as escaped text. That text never holds the element's own end tag, which would end the element early in a browser and make the rest live: an SVG or MathML element named noscript, noframes or noembed found there is removed, and an element whose sanitized content would still hold its end tag — a nested element of the same name, or a comment-out-tag comment containing one — is emptied.

Namespace Validation (mXSS Prevention) ¶

After applying policy rules, namespace consistency is validated. Elements whose namespace is invalid for their DOM position are stripped. This prevents mutation XSS attacks where foreign-content elements end up in the wrong namespace after policy actions change the tree structure. Directly under an integration point (SVG foreignObject/desc/title, MathML mi/mo/mn/ms/mtext and an HTML-encoded annotation-xml) a browser builds a foreign element only for <svg> or <math> (and MathML <mglyph>/<malignmark> under mi…mtext), so any other SVG or MathML element there — which an unwrap-tag "foreignobject > svg" would leave, and which would re-parse as HTML (an SVG <style> becoming a live HTML one) — is removed with its subtree.

A <form> nested inside another <form> (which the parser builds only after a </form> it could not honour behind an SVG/MathML boundary) is unwrapped, keeping its content: serialized, its start tag would be ignored on re-parse while its end tag left the outer form open to capture the page content that follows the output. Nested forms inside <template> content are kept.

SVG SMIL Animation Sanitization ¶

SMIL animation elements (<animate>, <set>, etc.) are sanitized by applying the same attribute and scheme policy rules to animated values. This prevents runtime bypasses via attributeName="href" values="javascript:alert(1)". CSS in animated style values is sanitized through the CSS engine.

The rules applied are those of the animation's target element: its parent when href/xlink:href is absent or empty, otherwise the element whose id matches the (percent-decoded) fragment. An animation whose href names no element in the sanitized output — including an id that only exists in the page a fragment is embedded into — is removed, and so is one whose target is not an SVG element (browsers animate only SVG elements, so an animated <iframe srcdoc> or HTML <a href> does nothing) or is itself an animation element (which would retarget that animation at runtime). The id must also be unique: an animation whose target id is held by more than one element anywhere in the sanitized document — inside <template> content and <noscript>/<noframes>/<noembed> content included — is removed, since which holder a browser animates depends on the tree it builds from the output (foster parenting out of a table, scripting mode, a holder removed by sanitization), and the sanitizer would otherwise judge the animation against an element the browser does not animate. Ids are indexed after every other sanitization step has removed what it removes, and the element whose id is referenced must sit in the same template scope as the animation: an animation inside <template> content (such as a declarative shadow root) resolves ids within that content only, and one outside it never resolves into it. SVG <discard> elements, which remove elements at runtime, are always removed.

Each animated value is judged twice against its target: as the target is written, and as it would be with the animated attribute holding that value (the browser gives the element that attribute at runtime). A selector that tests the animated attribute itself therefore applies to an animated value just as to a static one: under strip-scheme "a[href]" href javascript, strip-attr "a[href^=javascript:]" href, or strip-tag "a[href^=javascript:]", <a><set attributeName="href" to="javascript:alert(1)"/></a> loses its javascript: value. The more restrictive reading wins; a value under which the target would match a tag rule other than allow-tag removes the animation, and one under which its attribute rule strips or defangs it is dropped or defanged. Only the target is re-judged: a rule on another element that tests the target's attribute (strip-tag "g:has(a[href^=javascript:])") sees the target as written. The second reading is needed only when some tag, attribute, scheme or content-type selector can read the animated attribute (an attribute selector naming it, .class for class, #id for id, :link for href, :lang for lang, :checked for checked, type and selected, :enabled for href and disabled, :disabled for disabled); then at most 16 distinct values per animation are judged this way, and an animation with more is removed, since judging each one re-runs every selector on the target and an unbounded values= list made sanitization quadratic.

Limitations ¶

Embedded documents — <iframe srcdoc> and data:text/html URIs — are parsed and re-serialized as full documents, so their sanitized form carries an <html><head></head><body> wrapper the browser would build anyway.

In fragment mode, input containing a <body>, <html>, <frameset> or <frame> start tag is always re-serialized (which drops those tokens), even under WithPreserveOriginal, and is reported as modified. Likewise, in both modes and at every depth, input that ends inside an unfinished construct — a tag, attribute value, comment or DOCTYPE cut off by the end of input, an open <script>/<style>/<textarea>/<title>/<xmp>/<iframe>/<noembed>/<noframes>/ <noscript>/<plaintext>, a trailing "<", or an open <svg>/<math> — is always re-serialized and reported as modified. So is top-level input that leaves any element open (`<p>hi<form action=…>`, an open <a href>, <select> or <template>) or the parser's form element pointer set (`<div><form action=…></div>`, which makes a page's following <form> start tag be ignored), which would otherwise capture the content a page places after it; an embedded document has nothing after it and is exempt.

CSS Nesting is supported: nested style rules, and conditional at-rules (@media, @supports, @container, …) nested inside style rules, are sanitized like top-level ones. Malformed nesting may be restructured in the output, but is never passed through unsanitized. In a style attribute, at-rule blocks are dropped (browsers ignore them there).

CSS selectors in <style> elements are not filtered. Attribute selectors combined with url() values can exfiltrate data. The url() scheme filtering mitigates this, but full protection requires stripping <style> elements.

CSS var()/env()/attr() substitution happens at browser computed-value time, not parse time. Known attack vectors are handled (url() in custom properties, @import var(), var() fallback values, var()/env()/attr() in URL-accepting functions). When the policy governs url() at all (css-*-scheme or css-*-content-type rules), var()/env()/attr() inside URL-accepting functions (image-set, -webkit-image-set, cross-fade, image, src) is stripped as a precaution. Bare string arguments inside these functions are evaluated as URLs and run through the full url()-token path: css-*-scheme rules, css-*-content-type rules, and recursive sanitization of data: URI content. CSS escape sequences in the url() (or attr()) function name itself (e.g. \75rl(...), \61ttr(...)) bypass the lexer's URLToken recognition, so whenever css-*-scheme or css-*-content-type rules are active any FunctionToken whose escape-decoded name is "url" causes the declaration to be stripped. attr() with a url-typed substitution — "attr(name url)" or "attr(name type(<url>))" — also causes the declaration to be stripped, since the value of the named HTML attribute would be loaded as a URL at computed time.

XML data: URIs cannot be sanitized, so in HTML attributes (URL attributes, srcset/ping entries, meta refresh URLs, SMIL animated values) they are always stripped, with no opt-in — including harmless ones such as an inline <img src="data:image/svg+xml,…"> icon. Browsers parse them with an XML parser; this library uses an HTML5 parser, which cannot model XML custom entity expansion (<!ENTITY x "<script>...">, then &x;), CDATA sections, processing instructions, namespace prefixes, or the elements an HTML5 parse moves or reads as text. The CSS url() path is the exception: SVG/XHTML data URIs there are best-effort recursed (policy rules applied to the HTML5 parse, the XML-only constructs above not modelled) because a CSS url() loads in the browser's secure static mode (no scripting, no external fetches), where none of those constructs can run.

Hardcoded limits: data URI recursion depth 16, HTML nesting depth 510, CSS nesting depth 32, output size 10x input (configurable via WithMaxOutputFactor, minimum 32KB).