From cd91cf2e6404e833411da592e126ff2dbf947323 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Sat, 14 Nov 2026 15:25:03 +0100 Subject: [PATCH] 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: 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 --- docs/services/mail.md | 2 +- modules/postcard/README.md | 4 ++-- modules/postcard/safety_smoke_test.go | 34 +++++++++++++++++++++++++++ modules/postcard/templates.go | 15 ++++++++---- 4 files changed, 47 insertions(+), 8 deletions(-) diff --git a/docs/services/mail.md b/docs/services/mail.md index 7ac3c4ef..ff2df43c 100644 --- a/docs/services/mail.md +++ b/docs/services/mail.md @@ -20,7 +20,7 @@ Each message gets an HTML part, rendered from the Markdown, and a plain-text par Many mail clients drop a style block, so postcard also copies the CSS onto the elements it styles, as WinterCMS does: after the layout has rendered, every rule of the HTML's style elements is written into the `style` attribute of the elements it matches (with go-premailer), and CSS widths and heights also become `width` and `height` attributes. Classes stay on the elements. Rules that cannot be inlined, such as media queries and `:hover`, stay in a style element in the head; the style block holds only those afterwards. The preview, the test send and real mail are inlined the same way, and the plain-text part is never touched. -A layout keeps its CSS in the style block only when it opts out: a layout file with `disable_auto_inline_css = true` in its header (`1` and `yes` also work), or a layout edited in the admin with **Do not inline CSS** switched on (its CSS tab). The built-in layouts all inline. If the inliner fails on a message, that message is sent with its style block only and a warning is logged; mail is never stopped by it. +A layout keeps its CSS in the style block only when it opts out: a layout file with `disable_auto_inline_css = true` in its header (`1` and `yes` also work), or a layout edited in the admin with **Do not inline CSS** switched on (its CSS tab). The built-in layouts all inline. The safety checks run on the message before inlining, whether or not the layout opts out. If the inliner fails on a message, or its result fails the safety checks, that message is sent with its style block only and a warning is logged; mail is never stopped by it. ## Partials diff --git a/modules/postcard/README.md b/modules/postcard/README.md index d48ac17c..94c45486 100644 --- a/modules/postcard/README.md +++ b/modules/postcard/README.md @@ -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. diff --git a/modules/postcard/safety_smoke_test.go b/modules/postcard/safety_smoke_test.go index ffa35432..e957b98f 100644 --- a/modules/postcard/safety_smoke_test.go +++ b/modules/postcard/safety_smoke_test.go @@ -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, "", `x`, 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) + } + }) } diff --git a/modules/postcard/templates.go b/modules/postcard/templates.go index 46717b70..55bc2168 100644 --- a/modules/postcard/templates.go +++ b/modules/postcard/templates.go @@ -727,10 +727,11 @@ var styleElement = regexp.MustCompile(`(?i)]`) // 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 }