fix(postcard,cabana): unsafe site names never stop a send and are refused at save

- postcard.UnsafeText: a text a layout prints is unsafe when, escaped,
  it fails the rendered-HTML checks or holds a script or data URL at a
  scheme boundary ("Big Data: Summit" is safe)
- siteNameFrom/layoutSiteName: an unsafe Branding name falls back to the
  mail.from display name, an unsafe one of those gives no name; one
  rate-limited warning per source (site_name:branding, site_name:mail.from),
  never the value; file version, override, fallback and editor alike
- the Branding preview of an unsafe draft name renders without it
- MailBrandSetting.BeforeValidate: 422 on site_name with
  backend::lang.mail.brand.site_name_unsafe (en/pl)
- settings Put localizes a BeforeValidate refusal's phrase keys, as a
  controller save does
- TestMailSafetySmoke/unsafe_site_name, TestMailBrandSiteName/unsafe_name_refused
This commit is contained in:
Jakub Zych
2026-11-14 15:20:29 +01:00
parent 13ab905f8d
commit 3a725469c6
12 changed files with 180 additions and 16 deletions

File diff suppressed because one or more lines are too long

View File

@@ -1800,11 +1800,16 @@ func (MailBrandSetting) Rules() map[string]string {
var brandColourPattern = regexp.MustCompile(`^#[0-9a-f]{6}$`)
// BeforeValidate trims the site name, lower-cases colours, refuses anything
// but #rrggbb or empty, and checks logo_file_id is null or a library image.
// BeforeValidate trims the site name and refuses a name mail could not show
// (postcard's UnsafeText), lower-cases colours, refuses anything but #rrggbb
// or empty, and checks logo_file_id is null or a library image. One refusal
// lists every field at fault.
func (b *MailBrandSetting) BeforeValidate(tx *gorm.DB) error {
b.SiteName = strings.TrimSpace(b.SiteName)
details := map[string]any{}
if postcard.UnsafeText(b.SiteName) {
details["site_name"] = []string{"backend::lang.mail.brand.site_name_unsafe"}
}
for _, col := range []struct {
name string
value *string

View File

@@ -89,6 +89,31 @@ func TestMailBrandSiteName(t *testing.T) {
t.Errorf("a send without a site name, a logo or a mail.from name has a header row:\n%s", got.HTML)
}
})
t.Run("unsafe_name_refused", func(t *testing.T) {
env.expect(t, http.StatusOK, http.MethodPut, mailBrandPath, root, map[string]any{"site_name": "Acme Mail"})
// A name mail could not show is refused on the field; nothing is stored.
env.expectFieldRefusal(t, http.StatusUnprocessableEntity, http.MethodPut, mailBrandPath, root,
map[string]any{"site_name": "javascript: Acme"}, "site_name", "cannot be shown in mail", false)
var stored cabana.MailBrandSetting
if err := env.gdb.First(&stored, 1).Error; err != nil || stored.SiteName != "Acme Mail" {
t.Fatalf("refused save changed the row: %+v err=%v", stored, err)
}
// The preview of the unsaved draft renders without the name.
if html := brandPreview(t, env, root, map[string]any{"site_name": "javascript: Acme"}); strings.Contains(html, "javascript:") {
t.Errorf("the preview shows the unsafe name:\n%s", html)
}
// Prose with a colon is a name like any other.
env.expect(t, http.StatusOK, http.MethodPut, mailBrandPath, root, map[string]any{"site_name": "Big Data: Summit"})
tmplID := env.mailRowID(t, postcard.TemplatesTable, blogWelcome)
defaultID := env.mailRowID(t, postcard.LayoutsTable, "postcard::mail.layouts.default")
env.expect(t, http.StatusOK, http.MethodPut, fmt.Sprintf("%s/%d", mailTemplatesPath, tmplID), root, templateBody("Witaj, {{ .name }}", "Cześć **{{ .name }}**.", defaultID))
got := sendGrace(t, env, blogWelcome)
if m := headerSpan.FindStringSubmatch(got.HTML); m == nil || m[1] != "Big Data: Summit" {
t.Errorf("sent header does not show the saved site name:\n%s", got.HTML)
}
env.expect(t, http.StatusOK, http.MethodPut, mailBrandPath, root, map[string]any{"site_name": ""})
})
}
// inlineLayoutFiles is the blog fixture whose blog layout carries a style

View File

@@ -264,7 +264,9 @@ func (s SettingsService) Put(ctx context.Context, setting *CompiledSetting, body
}
if hook, ok := model.(lagoon.HasBeforeValidate); ok && hook != nil {
if err := hook.BeforeValidate(tx); err != nil {
return err
// A refusal's phrase keys are localized, as on a
// controller save.
return localizeControllerError(ctx, s.Tr, err)
}
}
rules := settingRules(setting, model)

View File

@@ -703,6 +703,7 @@ mail:
logo_comment: "The built-in layouts show the logo in their header. Your own layouts show it where they use {{ .logoUrl }}."
site_name: "Site name"
site_name_comment: "Shown in the header and footer of the built-in layouts. Leave it empty to use the sender name from mail.from."
site_name_unsafe: "This name cannot be shown in mail. Remove addresses that start with javascript:, vbscript: or data: and text such as onclick=."
body_bg: "Body background"
content_bg: "Content background"
header_color: "Header colour"

View File

@@ -741,6 +741,7 @@ mail:
logo_comment: "Wbudowane układy pokazują logo w nagłówku. Własne układy pokazują je tam, gdzie używają {{ .logoUrl }}."
site_name: "Nazwa witryny"
site_name_comment: "Wyświetlana w nagłówku i stopce wbudowanych układów. Zostaw puste, aby użyć nazwy nadawcy z mail.from."
site_name_unsafe: "Tej nazwy nie można pokazać w wiadomościach. Usuń adresy zaczynające się od javascript:, vbscript: lub data: oraz tekst w rodzaju onclick=."
body_bg: "Główne tło"
content_bg: "Tło treści"
header_color: "Kolor górnego nagłówka"

View File

@@ -289,6 +289,8 @@ The row's `logo_file_id` names a public `system_files` row. Its URL is not store
The row's `site_name` column is `postcard.Brand.SiteName`. The built-in layouts show it in their header (as the logo's alternative text when there is a logo) and footer. While it is empty, and while no Branding row exists, `{{ .siteName }}` is the display name of `mail.from` parsed with `net/mail` (`Acme` for `Acme <no-reply@acme.test>`), or empty when the address has none. The name is HTML-escaped by `html/template` wherever a layout prints it.
A name `postcard.UnsafeText` refuses (a `javascript:`, `vbscript:` or `data:` URL, or text that would read as markup such as `Shop onclick=x`) never reaches a layout and never stops a send: an unsafe Branding name is treated as empty, so the `mail.from` display name is used if that one is safe, and an unsafe `mail.from` display name gives no name. A warning naming the source (`branding` or `mail.from`), never the value, is logged at most once a minute per source. Prose such as `Big Data: Summit` is a name like any other. The Branding preview of an unsaved draft leaves such a name out the same way; the admin's Branding form refuses to save it.
A mail that falls back to its file version because an override failed still gets the Branding.
### Sample values
@@ -412,6 +414,7 @@ A draft is rendered by the code that renders a send, with the mailer's CSS and t
| `postcard.Brand` | The Branding: thirteen colours, `postcard.Brand.LogoURL`, the logo's absolute URL, and `postcard.Brand.SiteName`, the name the built-in layouts show. |
| `postcard.DefaultBrand` | WinterCMS's default mail colours. |
| `postcard.CompileBrandCSS` | Checks a brand's colours and returns the brand CSS compiled from them. |
| `postcard.UnsafeText` | Reports whether a text a layout prints, such as the site name, must be kept out of mail: it holds a `javascript:`, `vbscript:` or `data:` URL, or fails the rendered-HTML safety checks once HTML-escaped. |
| `postcard.Migrations` | The gormigrate set that creates the mail tables; lagoon runs it under the `summercms.postcard` history. |
| `postcard.TemplatesTable`, `postcard.LayoutsTable`, `postcard.PartialsTable`, `postcard.BrandTable`, `postcard.ImageLibraryTable` | The names of the mail tables, for code that defines models over them. |
| `postcard.SyncIndex` | Upserts one index row per file template, layout and partial of a catalog; mirrors the file into rows that are not customized and refreshes `file_hash` and the template's `base_code` on all. |
@@ -467,7 +470,7 @@ mail:
- SummerCMS modules: [backpack](../backpack/README.md), [compass](../compass/README.md), [diary](../diary/README.md) (component logger `postcard` when the app publishes no logger), [pact](../pact/README.md), and the `attach` package of [lagoon](../lagoon/README.md) (`attach.AbsolutePublicURL` and `attach.BlobKey` for the logo's URL; lagoon itself is not imported).
- Third-party: `github.com/wneessen/go-mail` (SMTP), `github.com/yuin/goldmark` (Markdown, and its table extension inside partials), `github.com/vanng822/go-premailer` (CSS inlining, pinned at v1.38.0; see `.planning/notes/2026-11-13-mail-layouts-css-inlining.md`), `golang.org/x/net/html` (tokenizing rendered HTML for the safety checks, already a framework dependency; see `.planning/notes/2026-11-14-mail-url-scheme-check.md`), `gorm.io/gorm` (reading overrides), `github.com/go-gormigrate/gormigrate/v2` (the mail tables' migrations).
- Standard library: `bytes`, `context`, `crypto/rand`, `crypto/sha256`, `database/sql`, `embed`, `encoding/hex`, `errors`, `fmt`, `html/template`, `io/fs`, `log/slog`, `net/mail`, `regexp`, `sort`, `strconv`, `strings`, `sync`, `text/template` (and `text/template/parse`), `time`.
- Standard library: `bytes`, `context`, `crypto/rand`, `crypto/sha256`, `database/sql`, `embed`, `encoding/hex`, `errors`, `fmt`, `html`, `html/template`, `io/fs`, `log/slog`, `net/mail`, `regexp`, `sort`, `strconv`, `strings`, `sync`, `text/template` (and `text/template/parse`), `time`.
- Tests additionally use `github.com/testcontainers/testcontainers-go` (Mailpit and Postgres containers), `gorm.io/driver/postgres` and `github.com/jackc/pgx/v5`.
## Testing

View File

@@ -325,7 +325,9 @@ func (e *Editor) renderBrand(d Draft, ov Overrides, opts renderOptions) (Rendere
return RenderedMessage{}, err
}
opts.brandCSS, opts.logoURL = css, brand.LogoURL
opts.siteName = siteName(&brand, e.m.opts.From)
// An unsafe draft name is left out as a send would leave it out; the
// Branding save is what refuses it.
opts.siteName = e.m.layoutSiteName(&brand)
opts.overrides = ov
sample := sampleMessage()
return e.m.catalog.renderFrom(Message{

View File

@@ -149,11 +149,13 @@ func (m *mailer) render(ctx context.Context, msg Message) (RenderedMessage, erro
// options returns the render options of the file version: mail.css, and
// either the saved Branding (its compiled CSS and its logo) or, while none
// has been saved, mail.brandCss. A Branding whose colours do not compile
// keeps mail.brandCss. The site name is the Branding's, else the display
// name of mail.from.
// keeps mail.brandCss. The site name is layoutSiteName's: the Branding's,
// else the display name of mail.from, leaving out a name that fails the
// safety check. The override render and the override-failure fallback are
// built from these options, so all of them carry the same checked name.
func (m *mailer) options(brand *Brand) renderOptions {
opts := renderOptions{
css: m.opts.CSS, brandCSS: m.opts.BrandCSS, siteName: siteName(brand, m.opts.From), year: time.Now().Year(),
css: m.opts.CSS, brandCSS: m.opts.BrandCSS, siteName: m.layoutSiteName(brand), year: time.Now().Year(),
inline: m.inline, warn: m.warn,
}
if brand == nil {
@@ -172,18 +174,51 @@ func (m *mailer) options(brand *Brand) renderOptions {
// siteName returns the name the built-in layouts show: the Branding's site
// name, trimmed, else the display name of the sender address from, else
// empty.
// empty. A name UnsafeText refuses is skipped.
func siteName(brand *Brand, from string) string {
name, _ := siteNameFrom(brand, from)
return name
}
// siteNameFrom returns the first non-empty candidate UnsafeText accepts, of
// the trimmed Branding site name and the trimmed display name of from. In
// skipped it returns the source ("branding" or "mail.from") of the first
// non-empty candidate it refused.
func siteNameFrom(brand *Brand, from string) (name, skipped string) {
type candidate struct{ source, name string }
var candidates []candidate
if brand != nil {
if name := strings.TrimSpace(brand.SiteName); name != "" {
return name
candidates = append(candidates, candidate{"branding", strings.TrimSpace(brand.SiteName)})
}
if addr, err := netmail.ParseAddress(from); err == nil {
candidates = append(candidates, candidate{"mail.from", strings.TrimSpace(addr.Name)})
}
for _, c := range candidates {
if c.name == "" {
continue
}
if UnsafeText(c.name) {
if skipped == "" {
skipped = c.source
}
continue
}
return c.name, skipped
}
addr, err := netmail.ParseAddress(from)
if err != nil {
return ""
return "", skipped
}
// layoutSiteName is the site name the layouts get for brand and mail.from.
// A name that fails the safety check is left out, so it can never stop a
// send; a warning names its source, never its value, at most once per
// warnInterval.
func (m *mailer) layoutSiteName(brand *Brand) string {
name, skipped := siteNameFrom(brand, m.opts.From)
if skipped != "" {
m.warn("site_name:"+skipped, "postcard: site name left out of the layouts, it fails the mail safety check",
slog.String("source", skipped))
}
return strings.TrimSpace(addr.Name)
return name
}
// overrides asks the source once. A failed lookup (no connection, tables not

View File

@@ -1,11 +1,31 @@
package postcard
import (
"html"
"regexp"
"strings"
xhtml "golang.org/x/net/html"
)
// scriptURLText finds a script URL in text: javascript: or vbscript: at a
// scheme boundary, or data: at a scheme boundary directly followed by a
// non-space character (a data URL). A boundary is the start of the text or a
// character that cannot belong to a URL scheme, so "Metadata: Weekly" and
// "Big Data: Summit" do not match.
var scriptURLText = regexp.MustCompile(`(?i)(?:^|[^a-z0-9+.\-])(?:(?:javascript|vbscript):|data:\S)`)
// UnsafeText reports whether a text that a layout prints, such as the site
// name of the built-in layouts, must be kept out of mail. A text is unsafe
// when, HTML-escaped as html/template prints text, it fails the rendered-HTML
// safety checks (for example event-handler-shaped text such as
// "Shop onclick=x"), or when it holds a script URL: javascript: or vbscript:
// at a scheme boundary, or a data: URL. "Big Data: Summit" is safe;
// "javascript: Acme" is not.
func UnsafeText(s string) bool {
return validateHTML(html.EscapeString(s)) != nil || scriptURLText.MatchString(s)
}
// urlAttributes are the attributes that hold one URL. Their decoded value is
// refused when it starts with a script or data scheme.
var urlAttributes = map[string]bool{

View File

@@ -2,6 +2,7 @@ package postcard
import (
"bytes"
"context"
"log/slog"
"strings"
"testing"
@@ -101,4 +102,71 @@ func TestMailSafetySmoke(t *testing.T) {
}
}
})
t.Run("unsafe_site_name", func(t *testing.T) {
ctx := context.Background()
for _, s := range []string{"", "Acme", "Big Data: Summit", "Metadata: Weekly", "Metadata:Weekly", "Acme <Studio>", "*Acme*", "[x](https://example.com)"} {
if UnsafeText(s) {
t.Errorf("UnsafeText(%q) = true, want false", s)
}
}
for _, s := range []string{"javascript:alert(1)", "javascript: Acme", "JavaScript:x", "Go vbscript:msgbox(1)", "data:text/html,x", "Shop onclick=x"} {
if !UnsafeText(s) {
t.Errorf("UnsafeText(%q) = false, want true", s)
}
}
// An unsafe Branding name is left out; the mail.from name is shown,
// and one warning names the source, never the value.
m, drv := partialsMailer(t, Options{From: "Acme <x@example.com>"}, &Overrides{Brand: &Brand{SiteName: "javascript:alert(1)"}})
logs := captureLog(m)
for range 2 {
msg := sendTemplate(t, m, drv, "acme.blog::mail.welcome", inlineVars)
assertSiteName(t, msg, "Acme")
if strings.Contains(msg.HTML, "javascript:") || strings.Contains(msg.Text, "javascript:") {
t.Errorf("the unsafe name reached the message:\n%s\n%s", msg.HTML, msg.Text)
}
}
out := logs.String()
if n := strings.Count(out, "site name left out of the layouts"); n != 1 {
t.Errorf("%d site name warnings in two sends, want 1:\n%s", n, out)
}
if !strings.Contains(out, "source=branding") || strings.Contains(out, "alert") {
t.Errorf("log = %q, want the source and not the value", out)
}
// Both names unsafe: no name at all, so no header row (no logo) and a
// footer with the year only.
m, drv = partialsMailer(t, Options{From: `"javascript: Acme" <x@example.com>`}, &Overrides{Brand: &Brand{SiteName: "Shop onclick=x"}})
logs = captureLog(m)
msg := sendTemplate(t, m, drv, "acme.blog::mail.welcome", inlineVars)
if _, ok := headerCell(msg.HTML); ok {
t.Errorf("a header row without a name or a logo:\n%s", msg.HTML)
}
if got := footerText(t, msg.HTML); got != copyright() {
t.Errorf("footer = %q, want %q", got, copyright())
}
if out := logs.String(); !strings.Contains(out, "source=branding") || strings.Contains(out, "onclick") {
t.Errorf("log = %q, want the branding source and not the value", out)
}
// The editor: saving a template or a layout under a stored unsafe
// name is not refused; the Branding preview of an unsafe draft name
// renders without it.
ed, _ := newEditor(t, &Overrides{Brand: &Brand{SiteName: "Shop onclick=x"}})
tmpl := Draft{Kind: KindTemplate, Name: editorWelcome, Subject: "Hi {{ .Name }}", Body: "Hi **{{ .Name }}**.", Layout: defaultLayoutName}
if err := ed.Validate(ctx, tmpl); err != nil {
t.Errorf("a template draft under an unsafe stored name was refused: %+v", err)
}
layout := Draft{Kind: KindLayout, Name: defaultLayoutName, HTML: `<div>{{ .Content }}</div>{{ partial "footer" "body" .siteName }}`, Text: "{{ .Content }}"}
if err := ed.Validate(ctx, layout); err != nil {
t.Errorf("a layout draft under an unsafe stored name was refused: %+v", err)
}
preview, err := ed.Preview(ctx, Draft{Kind: KindBrand, Brand: &Brand{SiteName: "javascript:alert(1)"}})
if err != nil {
t.Fatalf("Branding preview of an unsafe name: %v", err)
}
if strings.Contains(preview.HTML, "javascript:") || strings.Contains(preview.Text, "javascript:") {
t.Errorf("the Branding preview shows the unsafe name:\n%s", preview.HTML)
}
})
}