Skip to content

Add html-safe plugin for sanitized HTML rendering - #4918

Open
JeroenBoersma wants to merge 2 commits into
alpinejs:mainfrom
JeroenBoersma:feat/html-safe-plugin
Open

JeroenBoersma wants to merge 2 commits into
alpinejs:mainfrom
JeroenBoersma:feat/html-safe-plugin

Conversation

@JeroenBoersma

Copy link
Copy Markdown
Contributor

Summary

Adds @alpinejs/html-safe, a new plugin registering the x-html-safe
directive: renders HTML through a fixed tag/attribute allowlist instead of
setting innerHTML directly. Works on both the standard and CSP builds — the
plugin itself contains no CSP-specific code, it only calls evaluateLater,
which routes through whichever evaluator core Alpine provides.

This exists because Alpine's CSP build has no x-html directive at all
(rendering arbitrary HTML is exactly what a strict CSP is meant to prevent),
which leaves CSP users with no sanitized-HTML option. x-html-safe is a
distinct directive, not an x-html overwrite, so x-html's own documented
behavior is unaffected on any build.

What's in this MR

  • packages/html-safe/ — the plugin (package.json, builds/, src/index.js)
  • scripts/build.js — registered in the build list
  • tests/cypress/integration/plugins/html-safe.spec.js — 29 tests, all green,
    including two test.csp(...) cases proving it works under CSP and that
    plain x-html is untouched
  • packages/docs/src/en/plugins/html-safe.md — new plugin docs page
  • Cross-links from directives/html.md and advanced/csp.md's CSP
    limitations section
  • README.md — added to the package table

Allowlist

Tags: a, b, i, em, strong, s, u, span, small, mark, abbr, cite, q, sup, sub, br, code, kbd, samp, var, wbr, p, div, h1-h6, ul, ol, li, dl, dt, dd, blockquote, pre, hr, table, thead, tbody, tfoot, tr, th, td, caption, colgroup, col.

id, class, name, style, and all Alpine directives (x-*/:*/@*)
are never allowed on any tag — DOM clobbering, layout attacks, and
attacker-controlled resource loading via Tailwind's arbitrary-value class
syntax, respectively. Full attribute-by-attribute reference in the docs page.

Why we're proposing this

We maintain Hyvä, a Magento frontend built on Alpine, and we're already
shipping this plugin in our own theme to fill the gap left by the CSP
build dropping x-html. We're offering it upstream as a courtesy, in case
it's useful to the Alpine project more broadly, not just to us — sanitized
HTML rendering seems like a generally useful thing for a CSP-focused build
to offer. Not blocking on our end either way: happy to maintain it as a
third-party plugin if it's not a fit for the core project.

Introduces @alpinejs/html-safe, an x-html-safe directive that renders
HTML through a fixed tag/attribute allowlist instead of setting
innerHTML directly. Works on both the standard and CSP builds, and is
intended as a safer alternative to x-html for untrusted content, as
well as the only sanitized-HTML option on the CSP build (which drops
x-html entirely).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant