Files
summercms/modules/seaglass

seaglass

HTML sanitizer for stored rich text: a bluemonday allowlist policy that returns clean HTML byte for byte and reports what it removed from the rest.

import "git.golem15.com/golem15/summercms/modules/seaglass"

Name: Glass the sea has worn smooth; rough HTML goes in and only the safe, smooth part comes out.

Overview

seaglass is the framework's one HTML policy for rich text an administrator stores, such as cabana's type: richeditor field. It wraps bluemonday v1.0.27 with the policy the Journal plugin uses for imported WinterCMS content, without that plugin's editor-specific rules. A tokenizing sanitizer checks attributes and URLs the way a browser parses them, so it does not share the bypasses of regex gates (<img src="x"onerror=…>, javascript&#58;, <svg/onload=…>).

The comparison is byte-stable: when the input and the policy's output tokenize to the same HTML tokens, the input itself is returned, so a value that only differs in escaping is never rewritten. Otherwise the policy's output is returned with a report of the removed elements, attributes and comments, which cabana shows to the administrator as save notices.

Role in the framework

A leaf utility with no SummerCMS dependency. cabana runs every richeditor value through it on create and update, top level and inside repeater rows; plugins that serve stored HTML in a public API can run it again on output, for content that was imported without passing the admin save.

Use cases:

  • Sanitize an HTML field on save and tell the editor what was removed.
  • Check that stored HTML is already clean (seaglass.Check), for example in an import report.
  • Sanitize HTML on output in a public API.

Features

  • bluemonday's UGC policy with links kept as written (no rel="nofollow"), tel: links next to http, https, mailto and relative URLs, and the class, dir, microdata, footnote role and inline color, font-size, font-weight and text-align styles imported WinterCMS content uses.
  • Everything else is removed: script, style, iframe, object, embed, form, svg, math, comments, every on* attribute, target, rel, and URLs with any other scheme.
  • seaglass.SanitizeReport returns HTML the policy keeps whole byte for byte with a zero seaglass.Removals; a tag that repeats an attribute is always a change.
  • seaglass.Removals names the removed elements and attributes (at most ten distinct names each, in first-seen order) and counts every removal and every removed comment.

Usage

clean, report := seaglass.SanitizeReport(`<p onclick="x()">Hi</p><script>alert(1)</script>`)
fmt.Println(clean)
fmt.Println(report.Elements, report.Attributes, report.Changed)
// Output:
// <p>Hi</p>
// [script] [onclick] true
for _, stored := range []string{
	`<p class="lead">Hi <a href="tel:+48123">call</a></p>`,
	`<p><a href="javascript:alert(1)">x</a></p>`,
} {
	if err := seaglass.Check(stored); err != nil {
		// stored HTML would change under the policy
		fmt.Println(err)
		continue
	}
	fmt.Println("kept whole")
}
// Output:
// kept whole
// seaglass: HTML contains elements, attributes or URLs that are not allowed

API reference

Identifier Description
seaglass.Sanitize Returns the HTML filtered through the policy: the input itself when the policy keeps all of it.
seaglass.SanitizeReport seaglass.Sanitize with a seaglass.Removals report of what was removed; a zero report exactly when the input is returned.
seaglass.Check Returns an error when the policy would change the HTML, nil when it keeps it whole.
seaglass.Removals What was removed: Elements and Attributes (distinct names), ElementCount and AttributeCount (every removal), Comments, and Changed (the HTML differs from the input).

Dependencies

  • SummerCMS modules: none.
  • Third-party: github.com/microcosm-cc/bluemonday v1.0.27 (the policy; decision note .planning/notes/2026-10-11-framework-html-sanitizer-bluemonday.md), golang.org/x/net/html (the token comparison and the removal report).
  • Standard library: errors, fmt, io, regexp, slices, strings.

Testing

go test ./modules/seaglass/...

The tests run in memory and need no external services.