fix(postcard): an inlined result that fails the safety check sends the style block

- inlineHTML treats a failing post-inline check like an inliner error:
  the un-inlined HTML, which already passed validateHTML, is sent with
  its style block and the rate-limited inline:<layout> warning
- mail is never stopped by the inliner, as the docs promise (WR-05)
- README and docs/services/mail.md describe the check before inlining
- TestMailSafetySmoke/inline_unsafe_output
This commit is contained in:
Jakub Zych
2026-11-14 15:25:03 +01:00
parent 701ce8979d
commit cd91cf2e64
4 changed files with 47 additions and 8 deletions

View File

@@ -183,7 +183,7 @@ A template selects one with `layout = "system"`. A plugin's own alias of the sam
### CSS inlining
After a layout's HTML wrapper has rendered and passed the safety checks, postcard inlines it, as WinterCMS's `MailManager` does with CssToInlineStyles: `github.com/vanng822/go-premailer` with its default options reads the rules of every style element, writes them into the `style` attributes of the matching elements by specificity, mirrors CSS `width` and `height` to the attributes of the same name, keeps `class` attributes, and puts the rules it cannot inline (media queries, pseudo-classes such as `:hover`, selectors with `*`) back in one style element, marked `!important`. The inlined HTML is checked again, so a `javascript:`, `vbscript:` or `data:` address that reaches a `style` attribute fails the render as before. HTML with no style element is left as it is. Preview, test send and sends run the same code; the text part is never changed.
After a layout's HTML wrapper has rendered and passed the safety checks, postcard inlines it, as WinterCMS's `MailManager` does with CssToInlineStyles: `github.com/vanng822/go-premailer` with its default options reads the rules of every style element, writes them into the `style` attributes of the matching elements by specificity, mirrors CSS `width` and `height` to the attributes of the same name, keeps `class` attributes, and puts the rules it cannot inline (media queries, pseudo-classes such as `:hover`, selectors with `*`) back in one style element, marked `!important`. The safety checks run on the decoded markup before inlining, whether or not the layout opts out, so CSS in a style element with a `javascript:`, `vbscript:` or `data:` address is refused there. The inlined HTML is checked again, and an inlined result that fails the check is sent as its style-block version, with the same warning as an inliner error. HTML with no style element is left as it is. Preview, test send and sends run the same code; the text part is never changed.
A layout opts out with WinterCMS's option name, `disable_auto_inline_css`:
@@ -191,7 +191,7 @@ A layout opts out with WinterCMS's option name, `disable_auto_inline_css`:
- a row of `system_mail_layouts` sets the column `disable_auto_inline_css` (`postcard.LayoutOverride.DisableAutoInlineCSS`); `postcard.SyncIndex` mirrors the file's value into rows that are not customized and `postcard.ResetOverride` writes it back;
- a layout draft sets `postcard.Draft.DisableAutoInlineCSS`.
An opted-out layout keeps its style block as rendered. When the inliner fails on a message, the message is sent with its style block only and a warning keyed by the layout is logged at most once a minute.
An opted-out layout keeps its style block as rendered; it passed the same safety checks as an inlined one. When the inliner fails on a message, or its result fails the safety checks, the message is sent with its style block only and a warning keyed by the layout is logged at most once a minute.
Both wrappers of every layout get these keys: `Content`, `Subject`, `css`, `brandCss`, `logoUrl` (see [Branding](#branding)), `siteName` (the Branding's site name, else the display name of `mail.from`, else empty) and `year` (the current year). The default and system layouts call the header only when `logoUrl` or `siteName` is set, and builds the footer line from `year` and `siteName`, `© 2026 Acme`, or `© 2026` without a name. Its text wrapper is the message, a blank line and the footer's text section.

View File

@@ -169,4 +169,38 @@ func TestMailSafetySmoke(t *testing.T) {
t.Errorf("the Branding preview shows the unsafe name:\n%s", preview.HTML)
}
})
t.Run("inline_unsafe_output", func(t *testing.T) {
// An inliner whose output fails the safety check: the checked,
// un-inlined HTML is sent with its style block.
m, drv := partialsMailer(t, Options{}, nil)
m.(*mailer).inline = func(html string) (string, error) {
return strings.Replace(html, "</body>", `<a href="javascript:alert(1)">x</a></body>`, 1), nil
}
logs := captureLog(m)
plainMailer, plainDrv := partialsMailer(t, Options{}, nil)
plainMailer.(*mailer).inline = noInline
plain := sendTemplate(t, plainMailer, plainDrv, "acme.blog::mail.welcome", inlineVars)
for range 2 {
got := sendTemplate(t, m, drv, "acme.blog::mail.welcome", inlineVars)
if strings.Contains(got.HTML, "javascript:") {
t.Errorf("the failing inlined output was sent:\n%s", got.HTML)
}
if !styleElement.MatchString(got.HTML) {
t.Errorf("no style block in the fallback:\n%s", got.HTML)
}
if style := buttonStyle(t, got.HTML); style != "" {
t.Errorf("the button has an inlined style %q", style)
}
if got.HTML != plain.HTML || got.Text != plain.Text {
t.Errorf("the fallback differs from the un-inlined message:\n got %s\nwant %s", got.HTML, plain.HTML)
}
}
out := logs.String()
if n := strings.Count(out, "inlined CSS failed the safety check"); n != 1 {
t.Errorf("%d inline warnings in two sends, want 1:\n%s", n, out)
}
if !strings.Contains(out, "layout="+defaultLayoutName) {
t.Errorf("log = %q, want the layout", out)
}
})
}

View File

@@ -727,10 +727,11 @@ var styleElement = regexp.MustCompile(`(?i)<style[\s>]`)
// inlineHTML copies the CSS of a rendered message onto its elements. HTML
// without a style element has nothing to inline and is returned as it is.
// An inliner error keeps html as it is, with its style block, and is
// reported through opts.warn; mail is never stopped by it. The inlined HTML
// passes the safety checks again, since CSS values now sit in style
// attributes.
// Mail is never stopped by the inliner: an inliner error, or inlined HTML
// that fails the safety checks, keeps html as it is, with its style block,
// and is reported through opts.warn. Sending html is safe: it already passed
// validateHTML in renderParts, which reads decoded attribute values and the
// CSS of style elements whether or not the layout opts out of inlining.
func inlineHTML(html, layout string, opts renderOptions) (string, error) {
if !styleElement.MatchString(html) {
return html, nil
@@ -748,7 +749,11 @@ func inlineHTML(html, layout string, opts renderOptions) (string, error) {
return html, nil
}
if err := validateHTML(inlined); err != nil {
return "", err
if opts.warn != nil {
opts.warn("inline:"+layout, "postcard: inlined CSS failed the safety check, sending the style block only",
"layout", layout, "error", err.Error())
}
return html, nil
}
return inlined, nil
}