package postcard import ( "bytes" "embed" "fmt" "html/template" "io/fs" "regexp" "strings" "sync" texttemplate "text/template" "github.com/yuin/goldmark" ) const ( builtinPluginID = "postcard" defaultLayoutAlias = "default" defaultLayoutName = "postcard::mail.layouts.default" systemLayoutName = "postcard::mail.layouts.system" minimalLayoutName = "postcard::mail.layouts.minimal" mailPrefix = "mail." assetRoot = "views/mail/" ) // builtinLayoutAliases are the layout aliases every plugin's templates can // use. A plugin's own alias of the same name wins, except default, which is // reserved. var builtinLayoutAliases = map[string]string{ defaultLayoutAlias: defaultLayoutName, "system": systemLayoutName, "minimal": minimalLayoutName, } // builtinPartials are the partials postcard ships, callable by bare name. var builtinPartials = []string{"button", "panel", "subcopy", "table"} var ( dangerousScheme = regexp.MustCompile(`(?i)(?:javascript|vbscript|data):`) eventHandler = regexp.MustCompile(`(?i)\son[a-z]+\s*=`) rawUnsafeTag = regexp.MustCompile(`(?i)<(?:script|iframe|object|embed)\b`) markdown = goldmark.New() ) //go:embed assets/default.htm var defaultLayoutSource string // builtinAssets holds postcard's own layouts and partials. // //go:embed assets var builtinAssets embed.FS // Catalog holds registered mail templates, layouts and partials. type Catalog struct { mu sync.RWMutex templates map[string]*parsedTemplate layouts map[string]*parsedLayout partials map[string]*parsedPartial aliases map[string]map[string]string // pluginID -> short name -> full name } type parsedTemplate struct { name string pluginID string subject string description string layout string // short name from header; empty means default body string } type parsedLayout struct { name string pluginID string headerName string textWrap string htmlWrap string } // parsedPartial is a partial file: the layout file format, a header, a text // section and an HTML section. type parsedPartial struct { name string pluginID string headerName string textWrap string htmlWrap string } // NewCatalog returns a catalog that already contains postcard's built-in // layouts (default, system and minimal) and partials (button, panel, table // and subcopy). It holds no template. func NewCatalog() *Catalog { c := &Catalog{ templates: make(map[string]*parsedTemplate), layouts: make(map[string]*parsedLayout), partials: make(map[string]*parsedPartial), aliases: make(map[string]map[string]string), } layout, err := parseLayout(defaultLayoutName, builtinPluginID, defaultLayoutSource) if err != nil { panic("postcard: default layout: " + err.Error()) } c.layouts[defaultLayoutName] = layout for file, name := range map[string]string{"system": systemLayoutName, "minimal": minimalLayoutName} { raw, err := builtinAssets.ReadFile("assets/" + file + ".htm") if err != nil { panic("postcard: " + file + " layout: " + err.Error()) } layout, err := parseLayout(name, builtinPluginID, string(raw)) if err != nil { panic("postcard: " + file + " layout: " + err.Error()) } c.layouts[name] = layout } for _, short := range builtinPartials { raw, err := builtinAssets.ReadFile("assets/partials/" + short + ".htm") if err != nil { panic("postcard: " + short + " partial: " + err.Error()) } partial, err := parsePartial(builtinPartialPrefix+short, builtinPluginID, string(raw)) if err != nil { panic("postcard: " + short + " partial: " + err.Error()) } c.partials[partial.name] = partial } return c } // Register loads declared dotted template and layout names from fsys. // Each name must be owned by pluginID and map to views/mail/.htm. func (c *Catalog) Register(pluginID string, fsys fs.FS, templates []string, layouts map[string]string) error { if c == nil { return fmt.Errorf("postcard: catalog is nil") } if pluginID == "" { return fmt.Errorf("postcard: plugin id is empty") } c.mu.Lock() defer c.mu.Unlock() alias := make(map[string]string, len(layouts)) for short, full := range layouts { if short == "" || full == "" { return fmt.Errorf("postcard: empty layout alias for %s", pluginID) } if short == defaultLayoutAlias { return fmt.Errorf("postcard: layout alias %q is reserved", short) } if err := assertOwner(pluginID, full); err != nil { return err } if _, exists := c.layouts[full]; exists { return fmt.Errorf("postcard: duplicate layout %s", full) } path, err := assetPath(full) if err != nil { return err } raw, err := fs.ReadFile(fsys, path) if err != nil { return fmt.Errorf("postcard: missing layout %s", full) } parsed, err := parseLayout(full, pluginID, string(raw)) if err != nil { return err } c.layouts[full] = parsed alias[short] = full } if len(alias) > 0 { if c.aliases[pluginID] == nil { c.aliases[pluginID] = make(map[string]string, len(alias)) } for short, full := range alias { if _, exists := c.aliases[pluginID][short]; exists { return fmt.Errorf("postcard: duplicate layout alias %s for %s", short, pluginID) } c.aliases[pluginID][short] = full } } for _, name := range templates { if err := assertOwner(pluginID, name); err != nil { return err } if _, exists := c.templates[name]; exists { return fmt.Errorf("postcard: duplicate template %s", name) } path, err := assetPath(name) if err != nil { return err } raw, err := fs.ReadFile(fsys, path) if err != nil { return fmt.Errorf("postcard: missing template %s", name) } parsed, err := parseTemplateFile(name, pluginID, string(raw)) if err != nil { return err } if err := c.resolveLayoutLocked(parsed); err != nil { return err } c.templates[name] = parsed } return nil } func (c *Catalog) resolveLayoutLocked(t *parsedTemplate) error { short := strings.TrimSpace(t.layout) if short == "" || short == defaultLayoutAlias { t.layout = defaultLayoutAlias return nil } full, ok := c.aliases[t.pluginID][short] if !ok { // Not one of the plugin's own aliases: a built-in layout. full, ok = builtinLayoutAliases[short] } if !ok { return fmt.Errorf("postcard: unknown layout %s", short) } if _, ok := c.layouts[full]; !ok { return fmt.Errorf("postcard: missing layout %s", full) } t.layout = full return nil } func (c *Catalog) lookupTemplate(name string) (*parsedTemplate, error) { c.mu.RLock() defer c.mu.RUnlock() t, ok := c.templates[name] if !ok { return nil, fmt.Errorf("postcard: unknown template %s", name) } return t, nil } // RegisterPartials loads declared partial names from fsys. Each name must // be owned by pluginID, have the form ::mail.partials. and map // to views/mail/partials/.htm. func (c *Catalog) RegisterPartials(pluginID string, fsys fs.FS, partials []string) error { if c == nil { return fmt.Errorf("postcard: catalog is nil") } if pluginID == "" { return fmt.Errorf("postcard: plugin id is empty") } c.mu.Lock() defer c.mu.Unlock() for _, name := range partials { if err := assertOwner(pluginID, name); err != nil { return err } if _, rest, _ := strings.Cut(name, "::"); !strings.HasPrefix(rest, partialSegment) || rest == partialSegment { return fmt.Errorf("postcard: invalid partial name %s (want %s::%s)", name, pluginID, partialSegment) } if _, exists := c.partials[name]; exists { return fmt.Errorf("postcard: duplicate partial %s", name) } path, err := assetPath(name) if err != nil { return err } raw, err := fs.ReadFile(fsys, path) if err != nil { return fmt.Errorf("postcard: missing partial %s", name) } parsed, err := parsePartial(name, pluginID, string(raw)) if err != nil { return err } c.partials[name] = parsed } return nil } func (c *Catalog) lookupPartial(name string) (*parsedPartial, bool) { c.mu.RLock() defer c.mu.RUnlock() p, ok := c.partials[name] return p, ok } func assertOwner(pluginID, fullName string) error { prefix := pluginID + "::" if !strings.HasPrefix(fullName, prefix) { return fmt.Errorf("postcard: template %s is not owned by %s", fullName, pluginID) } return nil } func assetPath(fullName string) (string, error) { _, rest, ok := strings.Cut(fullName, "::") if !ok { return "", fmt.Errorf("postcard: invalid mail name %s", fullName) } after, ok := strings.CutPrefix(rest, mailPrefix) if !ok || after == "" { return "", fmt.Errorf("postcard: invalid mail name %s", fullName) } if strings.Contains(after, "..") || strings.ContainsAny(after, `/\`) { return "", fmt.Errorf("postcard: invalid mail name %s", fullName) } return assetRoot + strings.ReplaceAll(after, ".", "/") + ".htm", nil } func parseTemplateFile(name, pluginID, src string) (*parsedTemplate, error) { header, body, err := splitTwo(src) if err != nil { return nil, fmt.Errorf("postcard: parse %s: %w", name, err) } fields, err := parseINI(header) if err != nil { return nil, fmt.Errorf("postcard: parse %s: %w", name, err) } return &parsedTemplate{ name: name, pluginID: pluginID, subject: fields["subject"], description: fields["description"], layout: fields["layout"], body: strings.TrimSuffix(body, "\n"), }, nil } func parseLayout(name, pluginID, src string) (*parsedLayout, error) { header, textWrap, htmlWrap, err := splitThree(src) if err != nil { return nil, fmt.Errorf("postcard: parse %s: %w", name, err) } fields, err := parseINI(header) if err != nil { return nil, fmt.Errorf("postcard: parse %s: %w", name, err) } return &parsedLayout{ name: name, pluginID: pluginID, headerName: fields["name"], textWrap: strings.TrimSuffix(textWrap, "\n"), htmlWrap: strings.TrimSuffix(htmlWrap, "\n"), }, nil } func parsePartial(name, pluginID, src string) (*parsedPartial, error) { l, err := parseLayout(name, pluginID, src) if err != nil { return nil, err } return &parsedPartial{name: l.name, pluginID: l.pluginID, headerName: l.headerName, textWrap: l.textWrap, htmlWrap: l.htmlWrap}, nil } func splitTwo(src string) (header, body string, err error) { parts, err := splitEQ(src, 2) if err != nil { return "", "", err } return parts[0], parts[1], nil } func splitThree(src string) (header, textWrap, htmlWrap string, err error) { parts, err := splitEQ(src, 3) if err != nil { return "", "", "", err } return parts[0], parts[1], parts[2], nil } func splitEQ(src string, n int) ([]string, error) { src = strings.ReplaceAll(src, "\r\n", "\n") lines := strings.Split(src, "\n") parts := make([]string, 0, n) start := 0 for i, line := range lines { if strings.TrimSpace(line) != "==" { continue } parts = append(parts, strings.Join(lines[start:i], "\n")) start = i + 1 if len(parts) == n-1 { parts = append(parts, strings.Join(lines[start:], "\n")) return parts, nil } } return nil, fmt.Errorf("missing == separator") } func parseINI(header string) (map[string]string, error) { out := make(map[string]string) for _, line := range strings.Split(header, "\n") { line = strings.TrimSpace(line) if line == "" || strings.HasPrefix(line, ";") || strings.HasPrefix(line, "#") { continue } key, val, ok := strings.Cut(line, "=") if !ok { return nil, fmt.Errorf("invalid header line %q", line) } key = strings.ToLower(strings.TrimSpace(key)) val = strings.TrimSpace(val) if len(val) >= 2 { if q := val[0]; (q == '"' || q == '\'') && val[len(val)-1] == q { val = val[1 : len(val)-1] } } if key == "" { return nil, fmt.Errorf("invalid header line %q", line) } out[key] = val } return out, nil } type renderOptions struct { css string brandCSS string // overrides are the database overrides to apply; the zero value renders // the file version. overrides Overrides // warn reports a problem with an override that the render recovered // from. key identifies the problem for rate limiting. Nil drops it. warn func(key, msg string, args ...any) } // renderSource is what one render works from: a file template, or a file // template with its override applied. type renderSource struct { name string // template name, used in parse and execute errors subject string body string layout string // full layout name, the default alias, or an override's layout code // layoutFromOverride marks a layout an override chose: one that resolves // to nothing renders with the default layout instead of failing. layoutFromOverride bool } // render renders msg.Template: the file version, or the file version with // opts.overrides applied. Both go through renderFrom. func (c *Catalog) render(msg Message, opts renderOptions) (RenderedMessage, error) { t, err := c.lookupTemplate(msg.Template) if err != nil { return RenderedMessage{}, err } src := renderSource{name: t.name, subject: t.subject, body: t.body, layout: t.layout} if ov := opts.overrides.Template; ov != nil { src.subject, src.body = ov.Subject, ov.Body if ov.Layout != "" { src.layout, src.layoutFromOverride = ov.Layout, true } } return c.renderFrom(msg, src, opts) } // renderFrom renders src for msg. The caller's non-empty msg.Subject wins // over src.subject. func (c *Catalog) renderFrom(msg Message, src renderSource, opts renderOptions) (RenderedMessage, error) { var out RenderedMessage vars := msg.Vars if vars == nil { vars = map[string]any{} } subjectSrc := src.subject if strings.TrimSpace(msg.Subject) != "" { subjectSrc = msg.Subject } subject, err := execHTML(src.name+".subject", subjectSrc, vars) if err != nil { return out, err } if strings.ContainsAny(subject, "\r\n") { return out, fmt.Errorf("postcard: subject contains CR/LF") } // Partial calls in the body leave tokens that are swapped for the // rendered partials once Markdown has run; see partialRun. partials := newPartialRun(c, opts.overrides.Partials) markdownBody, err := execHTMLFuncs(src.name+".body", src.body, vars, template.FuncMap{"partial": partials.bodyCall}) if err != nil { return out, err } htmlBody, err := markdownHTML(markdownBody) if err != nil { return out, err } htmlBody = partials.swapHTML(htmlBody) textBody := partials.swapText(markdownBody) if err := validateHTML(htmlBody); err != nil { return out, err } layout, err := c.layoutFor(src, opts) if err != nil { return out, err } // A layout's own CSS goes before mail.css in the css slot. css := opts.css if layout.css != "" { css = layout.css if opts.css != "" { css += "\n" + opts.css } } text, err := execTextFuncs(layout.name+".text", layout.textWrap, map[string]any{ "Content": textBody, "Subject": subject, "css": css, "brandCss": opts.brandCSS, }, texttemplate.FuncMap{"partial": partials.textCall}) if err != nil { return out, err } html, err := execHTMLFuncs(layout.name+".html", layout.htmlWrap, map[string]any{ "Content": template.HTML(htmlBody), "Subject": subject, "css": template.CSS(css), "brandCss": template.CSS(opts.brandCSS), }, template.FuncMap{"partial": partials.htmlCall}) if err != nil { return out, err } if err := validateHTML(html); err != nil { return out, err } out = RenderedMessage{ To: append([]string(nil), msg.To...), Cc: append([]string(nil), msg.Cc...), Bcc: append([]string(nil), msg.Bcc...), ReplyTo: msg.ReplyTo, Subject: subject, HTML: html, Text: text, } return out, nil } // renderLayout is the layout one render uses: a file layout, a file layout // with its override applied, or a database-only layout. type renderLayout struct { name string // layout code, used in parse and execute errors textWrap string htmlWrap string css string } // layoutFor returns the layout src renders in. An override of that layout, // or a database-only layout of that code, wins over the file. A layout code // from a template override that names no layout is reported through // opts.warn and replaced by the default layout. func (c *Catalog) layoutFor(src renderSource, opts renderOptions) (renderLayout, error) { code := src.layout if code == "" || code == defaultLayoutAlias { code = defaultLayoutName } layout, ok, err := c.layoutByCode(code, opts.overrides.Layouts) if err != nil || ok { return layout, err } if !src.layoutFromOverride { return renderLayout{}, fmt.Errorf("postcard: missing layout %s", code) } if opts.warn != nil { opts.warn("layout:"+src.name+":"+code, "postcard: override names an unknown layout, using the default layout", "template", src.name, "layout", code) } layout, ok, err = c.layoutByCode(defaultLayoutName, opts.overrides.Layouts) if err == nil && !ok { err = fmt.Errorf("postcard: missing layout %s", defaultLayoutName) } return layout, err } func (c *Catalog) layoutByCode(code string, overrides map[string]LayoutOverride) (renderLayout, bool, error) { if ov, ok := overrides[code]; ok { return renderLayout{name: code, textWrap: ov.Text, htmlWrap: ov.HTML, css: ov.CSS}, true, nil } c.mu.RLock() l, ok := c.layouts[code] c.mu.RUnlock() if !ok { return renderLayout{}, false, nil } return renderLayout{name: l.name, textWrap: l.textWrap, htmlWrap: l.htmlWrap}, true, nil } func markdownHTML(src string) (string, error) { var buf bytes.Buffer if err := markdown.Convert([]byte(src), &buf); err != nil { return "", fmt.Errorf("postcard: markdown: %w", err) } return buf.String(), nil } func validateHTML(html string) error { if rawUnsafeTag.MatchString(html) { return fmt.Errorf("postcard: rendered HTML contains raw unsafe tags") } if eventHandler.MatchString(html) { return fmt.Errorf("postcard: rendered HTML contains event handlers") } if dangerousScheme.MatchString(html) { return fmt.Errorf("postcard: rendered HTML contains a dangerous URL scheme") } return nil } func execHTML(name, src string, data any) (string, error) { return execHTMLFuncs(name, src, data, nil) } func execText(name, src string, data any) (string, error) { return execTextFuncs(name, src, data, nil) } // execHTMLFuncs is execHTML with template funcs; they must be set before // the source is parsed. func execHTMLFuncs(name, src string, data any, funcs template.FuncMap) (string, error) { tmpl, err := template.New(name).Option("missingkey=zero").Funcs(funcs).Parse(src) if err != nil { return "", fmt.Errorf("postcard: parse %s: %w", name, err) } var buf bytes.Buffer if err := tmpl.Execute(&buf, data); err != nil { return "", fmt.Errorf("postcard: execute %s: %w", name, err) } return buf.String(), nil } func execTextFuncs(name, src string, data any, funcs texttemplate.FuncMap) (string, error) { tmpl, err := texttemplate.New(name).Option("missingkey=zero").Funcs(funcs).Parse(src) if err != nil { return "", fmt.Errorf("postcard: parse %s: %w", name, err) } var buf bytes.Buffer if err := tmpl.Execute(&buf, data); err != nil { return "", fmt.Errorf("postcard: execute %s: %w", name, err) } return buf.String(), nil }