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. A Policy is safe for concurrent use by multiple goroutines.

Selectors ¶

Selectors use standard CSS syntax compiled via github.com/andybalholm/cascadia:

tag                     match all <tag> elements
*                       match all elements
tag[attr=value]         exact attribute match
tag[attr^=prefix]       prefix match
tag[attr$=suffix]       suffix match
tag[attr*=substring]    contains match
tag[attr~=word]         space-separated word match
tag[attr=value i]       case-insensitive match (CSS4)
div.ads > a             child combinator (quote when spaces present)
svg animate             descendant: <animate> inside <svg>
#tracking               ID selector
:not([href^=https])     negation pseudo-class

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

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.

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.

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.

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:

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

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 schemeless URLs, * 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 :relative. Comma-separated lists reject a stray comma between entries (e.g. "http,,https") to catch typos.

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) 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.

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

By default, text/html data URIs are recursively sanitized (the HTML5 parser matches the browser), while SVG/XHTML/XML data URIs (image/svg+xml, application/xhtml+xml, */xml, *+xml) are stripped — the HTML5 parser cannot match a browser's XML parser, so they are removed rather than passed through with best-effort sanitization. To recurse an XML/SVG data URI anyway (best-effort, accepting the limitations below), opt in with an allow-content-type rule, e.g.:

allow-content-type img src image/svg+xml

scopes the opt-in to <img src> (a scripting-disabled context in browsers). Other data URIs pass through unchanged unless a content-type rule matches.

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).

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.

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

The css-*-scheme and css-*-content-type TARGET is a comma-separated list of CSS property name patterns or @import. Use * to match all properties and @import. Scheme lists support :relative and * as with 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).

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). 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". Pseudo filtering does not apply to inline style attributes (which have no selectors) or to 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. 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.

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 *

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")
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)

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: with no content-type rule governing the attribute) an earlier scheme rule stripped, 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".

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
                         XML/SVG data URIs; 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.

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.

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.

SVG/XHTML/XML data: URIs are stripped by default rather than recursed, because the HTML5 parser cannot match a browser's XML parser. An allow-content-type rule (e.g. "allow-content-type img src image/svg+xml") opts a given context back into best-effort recursion, accepting the limitation below. When recursing, namespace-prefixed elements (e.g. <a:script xmlns:a="...">) are stripped, but XML custom entity declarations (<!ENTITY x "<script>...">), CDATA sections, and processing instructions cannot be safely sanitized this way — so opt in only for content you trust or contexts where browsers disable scripting (e.g. <img>). See Limitations.

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.

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.

Limitations ¶

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 css-*-scheme rules are active, 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 when css-*-scheme 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.

SVG/XHTML/XML data: URIs cannot be fully sanitized, so they are stripped by default. Browsers parse them with an XML parser; this library uses an HTML5 parser. If you opt a context back into recursion with an allow-content-type rule, sanitization is best-effort only: namespace-prefixed elements are stripped as defense-in-depth, but XML custom entity expansion (<!ENTITY x "<script>...">, then &x;), CDATA sections, and processing instructions are XML-only constructs the HTML5 parser treats as inert text or comments — so an XML-parsing browser may execute content the sanitizer considered safe. Only opt in for trusted content or scripting-disabled contexts (e.g. <img>). The CSS url() path is an exception: SVG/XML data URIs there are left as best-effort recursion because a CSS url() loads in the browser's secure mode (no scripting).

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