diff --git a/.planning/phases/35-mail-templates-and-layouts-editor/35-08-SUMMARY.md b/.planning/phases/35-mail-templates-and-layouts-editor/35-08-SUMMARY.md new file mode 100644 index 00000000..623d85d1 --- /dev/null +++ b/.planning/phases/35-mail-templates-and-layouts-editor/35-08-SUMMARY.md @@ -0,0 +1,233 @@ +--- +phase: 35-mail-templates-and-layouts-editor +plan: 08 +subsystem: mail +tags: [postcard, cabana, x/net/html, safety-check, branding, css-inlining, gap-closure] + +requires: + - phase: 35-06 + provides: built-in default/system layouts with header and footer partials, CSS inlining, Branding site name + - phase: 35-07 + provides: TestMailBrandSiteName, site-name preview/send coverage +provides: + - attribute-scoped, entity-decoding URL-scheme check of rendered mail (unsafeMarkup) + - exported postcard.UnsafeText and render-time drop of unsafe site names (layoutSiteName) + - Branding 422 on site_name with backend::lang.mail.brand.site_name_unsafe (en/pl) + - inliner never stops mail (failing inlined result sends the style-block version) + - footer partial text argument; built-in layouts print the site name literally +affects: [35-09, mail, postcard, cabana settings] + +actuals: + tokens: 24825 + tasks: 3 + commits: 6 +plan_head_before: f4613fd26b374d8ffc8ee6a928f8fb3ae5ee08a3 +plan_head_after: 15d3e6fb8d87f7fc4da8788fe83bdc27a6b14bd5 + +tech-stack: + added: [] + patterns: + - "Safety checks of rendered HTML read decoded attribute values through the x/net/html tokenizer; text content is never checked for URL schemes" + - "Text a layout prints from configuration is filtered with postcard.UnsafeText at render time (dropped with a rate-limited, value-free warning) and refused at save" + +key-files: + created: + - modules/postcard/safety.go + - modules/postcard/safety_smoke_test.go + - .planning/notes/2026-11-14-mail-url-scheme-check.md + modified: + - modules/postcard/templates.go + - modules/postcard/editor.go + - modules/postcard/mailer.go + - modules/postcard/assets/partials/footer.htm + - modules/postcard/assets/default.htm + - modules/postcard/assets/system.htm + - modules/cabana/mail_admin.go + - modules/cabana/settings.go + - modules/phrasebook/backend/lang/en/lang.yaml + - modules/phrasebook/backend/lang/pl/lang.yaml + - modules/postcard/README.md + - modules/cabana/README.md + - docs/services/mail.md + - .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md + +key-decisions: + - "URL schemes are checked only in URL-bearing attributes (prefix rule after removing whitespace/control chars), list attributes, style attributes, style elements, comments and meta content, all decoded; text is not a URL (CR-01 root cause, WR-05)" + - "Any attribute whose name starts with on is an event handler (closes )" + - "postcard.UnsafeText: escaped text failing validateHTML, or javascript:/vbscript: at a scheme boundary, or data: followed by a non-space; Big Data: Summit is safe" + - "An unsafe Branding name falls back to the mail.from display name; an unsafe display name gives no name; one warning per source per minute, never the value" + - "An inlined result that fails the safety check is sent un-inlined with the inline: warning; the docs' promise wins over the reviewer's fail-the-render alternative" + - "The footer partial's text argument is printed escaped; the built-in layouts pass the copyright line as text" + - "Settings Put localizes a BeforeValidate refusal's phrase keys, as a controller save does" + +patterns-established: + - "Draft layout CSS is validated wrapped in a style element so the scheme check reads it and the error stays on content_css" + +requirements-completed: [CR-01, WR-01, WR-05, D-10, D-13, D-14] + +coverage: + - id: D1 + description: "Sends on the default and system layouts succeed with mail.from \"Metadata: Weekly\" and Branding \"Big Data: Summit\", file-version and override path, name in header and footer" + requirement: CR-01 + verification: + - kind: unit + ref: "modules/postcard/safety_smoke_test.go#TestMailSafetySmoke/prose_site_name" + status: pass + human_judgment: false + - id: D2 + description: "Entity-encoded javascript: href is refused with inlining on and off; the file version is sent" + requirement: WR-05 + verification: + - kind: unit + ref: "modules/postcard/safety_smoke_test.go#TestMailSafetySmoke/encoded_scheme" + status: pass + human_judgment: false + - id: D3 + description: "Unsafe site names are left out of mail with one value-free warning; editor saves under a stored unsafe name are not refused; Branding preview drops the name" + requirement: D-14 + verification: + - kind: unit + ref: "modules/postcard/safety_smoke_test.go#TestMailSafetySmoke/unsafe_site_name" + status: pass + human_judgment: false + - id: D4 + description: "Branding save of an unsafe site name is a translated 422 on site_name; Big Data: Summit saves and shows in the header" + requirement: D-10 + verification: + - kind: integration + ref: "modules/cabana/mail_brand_layout_postgres_test.go#TestMailBrandSiteName/unsafe_name_refused" + status: pass + human_judgment: false + - id: D5 + description: "An inlined result failing the safety check sends the un-inlined HTML with one inline warning" + requirement: WR-05 + verification: + - kind: unit + ref: "modules/postcard/safety_smoke_test.go#TestMailSafetySmoke/inline_unsafe_output" + status: pass + human_judgment: false + - id: D6 + description: "Footer prints the site name literally (no emphasis, no comment, no link) in HTML and text" + requirement: WR-01 + verification: + - kind: unit + ref: "modules/postcard/safety_smoke_test.go#TestMailSafetySmoke/literal_footer" + status: pass + human_judgment: false + - id: D7 + description: "Field-error rendering of the new 422 in the admin Branding form (no admin/ change; relies on the existing field-line rendering)" + verification: [] + human_judgment: true + rationale: "No admin test asserts the site_name field line for this key; the SPA rendering is visual" + +duration: 24min +completed: 2026-11-14 +status: complete +--- + +# Phase 35 Plan 08: Mail URL scheme check and site name safety (CR-01 gap closure) Summary + +**postcard now checks javascript:/vbscript:/data: only in decoded URL-bearing attributes, CSS, comments and meta content via the x/net/html tokenizer, so prose site names such as "Big Data: Summit" no longer stop mail; unsafe site names are dropped at render (postcard.UnsafeText, rate-limited warning) and refused on the Branding form; the inliner never stops mail; the footer prints the name literally.** + +## Performance + +- **Duration:** 24 min +- **Started:** 2026-11-14T14:05:56Z +- **Completed:** 2026-11-14T14:30:03Z +- **Tasks:** 3 +- **Files modified:** 22 + +## Accomplishments + +- CR-01 root cause closed: `validateHTML` keeps the raw tag and handler regexes and reads everything else through `unsafeMarkup` (decoded attributes). A sender or Branding name with `Metadata:` or `Big Data:` sends on the default and system layouts, on the file, override and fallback paths and in the editor. +- Encoded schemes (`javascript:`) are refused whether or not the layout opts out of inlining (WR-05 decoding half). +- `postcard.UnsafeText` (new exported API) is used at render time (`layoutSiteName`) and at save time (cabana `MailBrandSetting.BeforeValidate`, 422 with en/pl copy). +- The inliner can no longer stop mail that passed the check (WR-05 contradiction); README and docs agree. +- The footer prints the site name literally, escaped, as the header does (WR-01). + +## Task Commits + +1. **Task 1: scheme check in decoded attributes (tracer)**: `274dff44` (docs, decision note), `13ab905f` (fix) +2. **Task 2: unsafe site names never stop a send, refused at save**: `3a725469` (fix), `701ce897` (docs, UI-SPEC) +3. **Task 3: inliner never stops mail; literal footer**: `cd91cf2e` (fix), `15d3e6fb` (fix) + +**Plan metadata:** recorded in the docs(35-08) completion commit. + +## Names for 35-09 + +- Exported: `postcard.UnsafeText(s string) bool` (modules/postcard/safety.go) +- Unexported: `unsafeMarkup(doc string) error`, `hasDangerousScheme(val string) bool`, `urlAttributes`, `urlListAttributes`, `scriptURLText` (safety.go); `siteNameFrom(brand *Brand, from string) (name, skipped string)`, `(*mailer).layoutSiteName(brand *Brand) string`, `siteName` kept with its signature (mailer.go) +- Warning keys and messages: `site_name:branding`, `site_name:mail.from`, "postcard: site name left out of the layouts, it fails the mail safety check" (attr `source`); `inline:`, "postcard: inlined CSS failed the safety check, sending the style block only" (attrs `layout`, `error`) +- Footer partial: `text` argument (plain, escaped in a `

`; verbatim in text); `body` stays Markdown. Default and system layouts call `partial "footer" "text" $copy` (four calls). +- Copy key: `mail.brand.site_name_unsafe` (`backend::lang.mail.brand.site_name_unsafe`), en and pl +- Smoke subtests: `TestMailSafetySmoke/{prose_site_name,encoded_scheme,unsafe_site_name,inline_unsafe_output,literal_footer}`; `TestMailBrandSiteName/unsafe_name_refused` +- Removed subtest: `TestMailBrandSiteName/unsafe_name_current_behaviour` (pinned the old behaviour) +- Fixtures changed in Task 1, and why (each pinned prose as unsafe, which is no longer refused): + - editor_smoke_test.go: the "See the metadata: field." body moved to the valid drafts; the "body scheme" row became "layout scheme" (`href="javascript:alert(1)"` in a layout draft, field `content_html`, rule `unsafe`, message holds the encoded href) + - override_test.go `TestFallback/unsafe_override`: a template override selecting a layout override with the entity-encoded href + - partials_smoke_test.go `TestMailPartialsSmoke/errors` `unsafe_html`: a registered plugin partial `acme.blog::mail.partials.link` whose HTML holds the entity-encoded href + - override_smoke_test.go `TestMailOverrideSmoke/fallback` `unsafe`: body "Click the button onclick= to continue." (fails the unchanged handler regex; goldmark cannot produce a markup-level URL from a body) + +## Files Created/Modified + +- `modules/postcard/safety.go`: tokenizer-based markup check, `UnsafeText` +- `modules/postcard/templates.go`: `validateHTML` delegates schemes to `unsafeMarkup`; `inlineHTML` falls back on a failing post-inline check +- `modules/postcard/editor.go`: draft CSS checked as a style element; `renderBrand` uses `layoutSiteName` +- `modules/postcard/mailer.go`: `siteNameFrom`, `layoutSiteName`, `options` uses it +- `modules/postcard/assets/{partials/footer.htm,default.htm,system.htm}`: footer `text` argument +- `modules/cabana/mail_admin.go`: site_name refusal; `modules/cabana/settings.go`: BeforeValidate refusal localized +- `modules/phrasebook/backend/lang/{en,pl}/lang.yaml`: `mail.brand.site_name_unsafe` +- `modules/postcard/safety_smoke_test.go` (new) and the four fixture files above; `modules/cabana/mail_brand_layout_postgres_test.go` +- `modules/postcard/README.md`, `modules/cabana/README.md`, `docs/services/mail.md`, `.planning/notes/2026-11-14-mail-url-scheme-check.md`, `35-UI-SPEC.md` + +## Decisions Made + +As recorded in the plan's planner decisions and the decision note; no new ones beyond the deviation below. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] Settings Put returned a BeforeValidate refusal with raw phrase keys** +- **Found during:** Task 2 (`TestMailBrandSiteName/unsafe_name_refused`) +- **Issue:** `SettingsService.Put` returned the `*ValidationError` from `BeforeValidate` without localizing it, so the 422 listed `backend::lang.mail.brand.site_name_unsafe` instead of the text (the existing colour and logo refusals had the same problem). The plan assumed crud.go's `localizeDetails` applied; it only does on controller saves. The `SettingsService.Tr` doc comment already promised localized 422 messages. +- **Fix:** wrap the hook error in `localizeControllerError(ctx, s.Tr, err)` in modules/cabana/settings.go (texts without `::` pass through unchanged). +- **Files modified:** modules/cabana/settings.go +- **Verification:** `TestMailBrandSiteName/unsafe_name_refused` passes; full cabana suite (Docker) green +- **Committed in:** `3a725469` + +**2. [Note] RED runs without separate commits** +- As the plan directs (CLAUDE.md forbids failing commits), each RED was run and recorded but landed with its fix. RED evidence was verified `RED_EVIDENCE_OK` with `msd-tools check tdd-red-evidence` for `TestMailSafetySmoke/prose_site_name` (templates.go at HEAD), `/unsafe_site_name`, `/inline_unsafe_output` and `/literal_footer`. go test -v output was converted line by line to Surefire XML for the checker, which reads only TAP or Surefire. + +**3. [Note] layouts_test.go and inline_test.go unchanged** +- Listed in files_modified "only where an assertion depended on the Markdown-rendered footer markup". No assertion did (`

...

` is the same paragraph), so neither file changed. + +--- + +**Total deviations:** 1 auto-fixed (1 bug), 2 notes +**Impact on plan:** The settings fix was needed for the planned translated 422 and also translates the existing colour and logo refusals. No API change. + +## Issues Encountered + +- `gofmt -l` reports modules/cabana/mail_routes.go and modules/postcard/store_postgres_test.go. Both predate this plan, so they were left alone. + +## Verification + +- `go vet ./...`, `go test -short ./...`, `go test ./modules/postcard ./modules/cabana` (Docker) and `cd examples/hello && go test ./...` were green after every code commit. +- `scripts/check-phase35.sh --consumers` passed, and both sibling trees stayed clean. `--additive` passed: `UnsafeText` is the only exported addition. +- `TestCommandsDocumented|TestDocsTree` and `summer docs:build --check` passed. +- go.mod, go.sum, modules/pact, admin/ and modules/boardwalk/dist have no commits since 0aa38db8. Nothing was pushed or tagged. + +## User Setup Required + +None. + +## Next Phase Readiness + +- 35-09 is next: regression and unit tests for the names above, the new names required in `scripts/check-phase35.sh`, and 35-VALIDATION.md rows. + +--- +*Phase: 35-mail-templates-and-layouts-editor* +*Completed: 2026-11-14* + +## Self-Check: PASSED