security

Fluent Security

Opt-in security toolkit for the Fluent HTML framework. Sanitise untrusted HTML via bluemonday, generate per-request nonces for Content-Security-Policy - and nothing else. Fluent core stays dependency-free; you pay for security only when you need it.

Why a separate package?

Real sanitisation needs a proper HTML parser and a vetted policy engine. Trying to do that with a regex inside the core framework would have been dishonest, and bundling a sanitisation library into every Fluent project would have cost the zero-dependency property Fluent cares about.

Pulling security out into its own package gets both right:

• Fluent core stays small and dependency-free. Projects that want the same minimalism gomponents provides out of the box get exactly that.
• Security becomes first-class when opted in. A real HTML sanitiser, a correct nonce generator, and a clear contract about what each does.
• Follows the ecosystem pattern. Just like fluent-jit, fluent-htmx, tether, and friends - separate package, dropped in when wanted, absent when not.

Install

go get github.com/jpl-au/fluent-security

Requires Fluent (for the node.Node interface) and bluemonday (the sanitiser). Both are resolved automatically by go mod.

Sanitising HTML

Three tiers of control, each returning a node.Node that embeds directly in a Fluent tree:

1. One-line helpers (HTML, PlainText) - sensible defaults, no configuration. Use these for the 90% case.
2. Chainable Cleaner (New, RichText) - sensible defaults you can extend with Allow, AllowClasses, AllowAttr. Hoist one at package scope and share it.
3. Escape hatch (FromPolicy) - wrap any bluemonday policy directly when the chainable API does not express what you need.

You should not need to reach for tier 3 often. The chainable API covers almost every real case. But when it doesn't, the escape hatch is there so you are never stuck.

HTML(input string) node.Node

Permissive policy for rich user-generated content. Keeps the common formatting tags (<p>, <strong>, <em>, <a>, <img> with http/https schemes, lists, headings, ...) and strips scripts, event handlers, iframes, and other attack surfaces.

Use for rendered markdown, rich-text editor output, and any content where the user is expected to provide some HTML structure.

comment := div.New(
    h3.Text(user.Name),
    div.New(security.HTML(user.CommentHTML)).Class("body"),
).Class("comment")

PlainText(input string) node.Node

Strips all HTML tags, keeps only plain text. Special characters (<, >, &, ", ') are escaped into entities, so the result is safe to drop straight into a Fluent tree without a second escape pass.

Use when you want the text content of marked-up input without any markup surviving. Useful for titles, one-line summaries, and places where HTML structure would be a bug rather than a feature.

title := h1.New(security.PlainText(article.RawTitle))

New() *Cleaner

Create a new, empty cleaner. Nothing is permitted until you call Allow, AllowClasses, or AllowAttr. Use this for defining a narrow policy from scratch.

cleaner := security.New().
    Allow("b", "i", "em", "strong").
    AllowAttr("href", "a")

clean := cleaner.Clean(userInput)

RichText() *Cleaner

Create a cleaner pre-configured with the user-generated-content baseline. Chain additional Allow methods to extend it.

// Baseline plus syntax-highlight classes on <code>/<pre>.
var mdCleaner = security.RichText().
    AllowClasses("code", "pre")

// At call sites:
article := div.New(
    h1.Text(art.Title),
    div.New(mdCleaner.Clean(art.Body)).Class("body"),
).Class("article")

*Cleaner is safe for concurrent use once configured. Build it once (typically at package scope) and reuse it across handlers.

FromPolicy(policy *bluemonday.Policy) *Cleaner

Escape hatch. Wraps any bluemonday policy in a *Cleaner, so you keep the Fluent-native integration (node.Node return, concurrent-safe, can be passed as a dependency) while retaining full access to bluemonday's configuration surface.

import "github.com/microcosm-cc/bluemonday"

p := bluemonday.NewPolicy()
// ... any bluemonday configuration you need ...
cleaner := security.FromPolicy(p)

body := div.New(cleaner.Clean(input)).Class("body")

When to reach for this:

• You need a bluemonday feature the chainable API does not expose (e.g. a URL scheme allowlist, a RequireParseableURLs toggle, custom rewrite handlers).
• You already have a bluemonday policy you want to reuse.
• You are migrating from a project that used bluemonday directly and want to adopt fluent-security incrementally.

When not to:

• You just want the UGC baseline plus a few tweaks. Use RichText() and chain Allow* methods instead; it reads more clearly and keeps bluemonday an implementation detail.
• You want to learn the API. Start with the chainable helpers - the documentation surface is smaller and the intent is obvious at each call site.

Content-Security-Policy nonces

Nonce() string

Returns a fresh 128-bit crypto-random value encoded as URL-safe base64 without padding (22 characters). Generate a new one per HTTP request and wire it into two matching places:

nonce := security.Nonce()

// 1. Put it on the inline script/style element via Fluent's method.
page := html.New(
    head.New(
        script.RawText("console.log('hello')").Nonce(nonce),
        style.RawText("body { background: #fff; }").Nonce(nonce),
    ),
    body.New( /* ... */ ),
)

// 2. Declare it in the Content-Security-Policy header.
w.Header().Set(
    "Content-Security-Policy",
    fmt.Sprintf("script-src 'self' 'nonce-%s'; style-src 'self' 'nonce-%s'",
        nonce, nonce),
)

page.Render(w)

The browser will execute only the inline blocks whose nonce attribute matches the value declared in the header. Do not reuse nonces across requests.

Nonce() uses crypto/rand. If the OS entropy source is unavailable it panics rather than returning a predictable value, because a guessable nonce silently defeats CSP. An HTTP handler cannot recover meaningfully from that condition anyway.

What this package does NOT do

• Ad-hoc pattern scanning. An earlier iteration of Fluent shipped a regex "validator" that checked for obvious-bad substrings. It has been removed. A motivated attacker defeats any fixed pattern list via Unicode escapes, string concatenation, or HTML entities. If you want safety, use the tools above; if you want hints, a real linter will serve you better than a fake sanitiser.
• Sanitise inline JavaScript or CSS source. Don't. Use a CSP nonce and treat the block as trusted within that scope.
• Generate CSP headers for you. The right policy depends on your application. Nonce() produces the token; you write the header.

How it composes with Fluent

• Text() and Textf() on Fluent elements already HTML-escape via html.EscapeString. For plain text content, you need nothing from this package.
• RawText() and RawTextf() are unescaped by design. Anything you pass to them is rendered verbatim - sanitise first if the source is untrusted.
• HTML / PlainText / Cleaner.Clean return node.Node values, so they plug into any position in a Fluent tree that accepts a node.

Disclaimer

This package reduces the attack surface of rendering untrusted HTML; it does not eliminate it. Sanitisation is only as complete as the underlying policy engine, and no sanitiser catches every novel technique.

You are still responsible for:

• Applying sanitisation at the right boundary (untrusted source in, safe node out).
• Keeping this package and its upstream dependencies patched.
• Threat modelling and reviewing anything safety-critical yourself.

The MIT licence terms apply - the software is provided "as is", without warranty of any kind. See LICENSE.

Reporting a vulnerability

Please do not open a public issue for security reports. Use GitHub's private vulnerability reporting to disclose the issue privately.

Credits

HTML sanitisation is performed by bluemonday, the work of the bluemonday contributors. This package is a thin Fluent-native adapter over it; the parsing and policy engine are theirs.

Licence

MIT