Compare commits

..

163 Commits

Author SHA1 Message Date
Jakub Zych
4d3b1e9f62 docs(phase-35): complete phase - UAT 14/14 (real-inbox check passed, G-35-9 framework part resolved) 2026-11-16 10:05:23 +01:00
Jakub Zych
0c24e0e656 test(35): re-verify after quick 261115-cha - 23/23 truths, human_needed (inbox check) 2026-11-16 08:19:09 +01:00
Jakub Zych
419e41fee5 test(35): note G-35-9 framework part closed by quick 261115-cha 2026-11-15 09:11:21 +01:00
Jakub Zych
ed17833ab7 docs(quick-261115-cha): let a mail template use another plugin's layout by full code 2026-11-15 09:11:11 +01:00
Jakub Zych
b8487b028b test(quick-261115-cha): cover cross-plugin mail layouts through overrides, the editor and the index
- TestCrossPluginLayoutOverride: a template override naming the lender's
  layout, a customized lender layout, Editor Validate and Preview
- TestCrossPluginLayoutSync (Docker): SyncIndex points the borrower rows'
  layout_id at the lender's layout row and keeps it on a second run
2026-11-15 09:09:58 +01:00
Jakub Zych
1fb4254291 feat(quick-261115-cha): let a mail template use another plugin's layout by full code
- resolveLayoutLocked: after the plugin's own alias and the built-in
  aliases, a full layout name already in the catalog resolves to itself;
  an unregistered full name fails with a require-the-owner hint
- another plugin's short alias and the short-alias error are unchanged
- TestCrossPluginLayout covers register, send, errors and precedence
- postcard README and docs/services/mail.md describe the rule
2026-11-15 09:08:21 +01:00
Jakub Zych
42ab223e79 test(35): complete UAT - 12 passed, 1 issue 2026-11-15 08:57:50 +01:00
Jakub Zych
358da17aeb docs(quick-261114-p5n): style the user and paymentgateway plugin mail layouts 2026-11-14 18:48:31 +01:00
Jakub Zych
4ef3aa1f90 test(35): seed UAT re-test rows after re-verification 2026-11-14 18:46:48 +01:00
Jakub Zych
3541c9bda3 docs(35): re-verify after quick 261114-p5m - all automated checks pass, human verification needed 2026-11-14 18:46:33 +01:00
Jakub Zych
5735e7c7d5 test(35): reconcile UAT gaps G-35-1 and G-35-8 as resolved by 35-07 2026-11-14 18:38:19 +01:00
Jakub Zych
8fabf87b8a docs(quick-261114-p5m): fix CR-02 residual quoted end tags in the mail URL check 2026-11-14 18:38:18 +01:00
Jakub Zych
f1f284a0f9 test(quick-261114-p5m): pin end tags inside quoted attributes in the mail URL check
- refuse cases for all eight probe payloads (noscript href and handler,
  svg style, title and textarea, noembed, xmp, conditional comment)
- send fallback and editor refusal for the three that survive rendering
- escaped_send subtests check svg title/textarea sends with an x/net/html
  parser oracle, scripting on and off
- accept cases for conditional comments, quoted CSS, a safe noscript
  link and a literal comment opener in an attribute
2026-11-14 18:37:08 +01:00
Jakub Zych
e47d4ae6cf docs(quick-261114-p5m): amend the mail URL scheme note for quoted end tags 2026-11-14 18:25:32 +01:00
Jakub Zych
d6ac0aeb4b fix(quick-261114-p5m): read tags across raw-text and comment ends in the mail URL check
- unsafeMarkupAt runs the existing HTML reading, then a tag reading in
  which attribute quoting alone decides where a tag ends
  (NextIsNotRawText after raw-text start tags, comment openers blanked)
- both readings share unsafeAttrs; existing refusals keep their message
  and snippet
- svg/style end tag inside a quoted attribute is refused at check, save
  and send; README and docs/services/mail.md describe the second reading
2026-11-14 18:25:13 +01:00
Jakub Zych
d8137c17d4 docs(35): align disposition frontmatter with fixed CR-01, CR-02, WR-01 2026-11-14 18:01:43 +01:00
Jakub Zych
c1e8e57e29 docs(35): re-verify after review fixes - CR-02 quoted end-tag residual open 2026-11-14 18:01:32 +01:00
Jakub Zych
7bd0eaaaee docs(35): shorten COVERAGE.md opt-out reason to pass the api-coverage gate 2026-11-14 17:52:00 +01:00
Jakub Zych
35c4081529 docs(35): reconcile disposition for re-titled CR-01, CR-02, WR-01 fixes 2026-11-14 17:47:41 +01:00
Jakub Zych
b729a8a605 docs(35): record code review disposition 2026-11-14 17:46:28 +01:00
Jakub Zych
73843dbf26 docs(35): add code review fix report 2026-11-14 17:46:27 +01:00
Jakub Zych
1d2e7e87fa docs(35): amend the mail URL scheme check note for the review fixes 2026-11-14 17:40:46 +01:00
Jakub Zych
8deb56ff0b fix(35): WR-03 treat data: in a site name as a data URL only with ; or ,
scriptURLText took data: followed by any non-space character as a data
URL, so names such as Data:Lab, Big Data:Summit and data:Science were
refused on the Branding form and dropped from mail, contrary to the docs.
A data URL now needs its optional MIME type and the ; or , every data URL
has. javascript: and vbscript: keep matching with whitespace after the
colon, since such a URL still runs.
2026-11-14 17:40:13 +01:00
Jakub Zych
31de2ff90f fix(35): WR-02 drop the whole-document event-handler regex
validateHTML ran (?i)\son[a-z]+\s*= over the rendered document, text
included, so a variable such as "buy one = get one free" stopped its own
message, and it is what made Online=Shop in the footer a send failure.
The tokenizer walk refuses every on* attribute, and since CR-02 it also
reads raw-text element and comment content as markup, so the regex is
dropped. Text shaped like a handler is now sent; such site names are shown
and saved, and the Branding refusal copy no longer mentions onclick=.
2026-11-14 17:37:52 +01:00
Jakub Zych
baba524caf fix(35): WR-01 strip whitespace before the list, meta, CSS and comment scheme checks
Single-URL attributes removed ASCII whitespace and control characters
before looking for a scheme, the list-valued, meta content, style and
comment checks did not, so values="java	script:..." and a tab-split
meta refresh passed. The stripping is factored out as stripURLSpace and
used by every scheme check.
2026-11-14 17:32:14 +01:00
Jakub Zych
1d481bb02d fix(35): CR-02 check raw-text element and comment content as markup
The tokenizer-only walk read noscript, title, textarea, style, xmp and the
other raw-text elements as one text token and never looked inside, so an
unencoded javascript: link in <noscript> or <svg><title> passed the check
and was sent. A mail client renders with scripting off and parses svg
children as markup, so the raw content of those elements, and comment
data (Outlook conditional comments), is now checked again as markup;
nesting deeper than eight levels is refused.
2026-11-14 17:30:07 +01:00
Jakub Zych
2dbee30530 fix(35): CR-01 check the site name where the layouts print it
UnsafeText checked the escaped name on its own, so a name starting with
on<letters>= (Online=Shop, onboarding=team) passed, was saved, and then
failed every default/system-layout send once the footer printed it after
"© <year> ". The name is now checked in the footer, header span and alt
contexts, so such a name is dropped at render and refused on the Branding
form instead of stopping mail.
2026-11-14 17:25:53 +01:00
Jakub Zych
980ba48764 docs(35): re-verify after gap closure 35-08/35-09 - CR-01 residual and CR-02 open 2026-11-14 16:26:50 +01:00
Jakub Zych
9195bc4822 docs(35): record code review disposition 2026-11-14 16:18:30 +01:00
Jakub Zych
f1d22353ca docs(35): re-review gap closure - CR-01 residual and scheme-check bypass found 2026-11-14 16:18:18 +01:00
Jakub Zych
9ff6e1a2e8 docs(35-09): record plan completion in state and roadmap 2026-11-14 16:09:00 +01:00
Jakub Zych
dce002ee45 docs(35-09): complete site name safety unit tests plan 2026-11-14 16:08:01 +01:00
Jakub Zych
fbbfce0702 docs(35): validation map for the site name safety gap
- CR-01 rows for the send path, the decoded scheme check and the admin side;
  WR-01 and WR-05 rows with their go test commands
- CR-01 status replaces the open item on the Branding site name
- Manual-Only row for the Branding refusal on sm-demo-app; Wave 0 lists the
  three new test files
2026-11-14 16:06:59 +01:00
Jakub Zych
e54be76cf0 test(35): self-test compares the planted consumer's go.mod
- the workspace-modfile case copies the planted consumer's go.mod before the
  modfile run and compares it after with cmp -s (IN-03)
- drops the git status check on the dirty-sibling fixture, which asserted
  against the wrong repository; the replace-line grep stays
2026-11-14 16:00:23 +01:00
Jakub Zych
54617f78d1 test(cabana): unsafe Branding site names refused at save, stored ones never block saves or sends
- TestMailSiteNameSafety: a javascript: site name is a 422 on site_name in en
  and pl and stores nothing; Big Data: Summit and Metadata: Weekly save; the
  Branding preview drops an unsafe draft name; a name stored before the check
  never refuses a template or layout save or stops a send; a mail.from display
  name with a colon shows on the default and system layouts
- the mail screens env reads mail.from from its configuration (default
  unchanged), so a mutate hook can set the sender
- check-phase35.sh DOCKER_TESTS requires TestMailSiteNameSafety
2026-11-14 15:56:18 +01:00
Jakub Zych
446a77efbf test(postcard): decoded URL scheme check, unsafe inlined output and the literal footer
- TestURLSchemeCheck: prose and scheme words in titles or queries pass; every
  URL-bearing attribute, CSS, meta refresh and each entity-encoded or
  whitespace-split script URL is refused with a snippet at the markup; a layout
  override with javascript&#58; falls back to the file version with inlining on
  and off; the editor refuses it on content_html and CSS URLs on content_css
- TestInlineUnsafeOutput: a failing inlined result sends the style-block
  version with one warning per layout
- TestFooterSiteNameLiteral: the footer prints the site name escaped and
  literally on the default and system layouts; body stays Markdown
- check-phase35.sh GO_TESTS requires the three tests
2026-11-14 15:47:35 +01:00
Jakub Zych
e0016e0c0d test(postcard): site names on the built-in layouts never stop a send
- TestSiteNameSend: mail.from "Metadata: Weekly" and Branding "Big Data: Summit"
  show in header, footer and text on the default and system layouts, on the
  file-version, override and override-failure fallback paths
- TestUnsafeSiteNameDropped: unsafe names are left out on every path with one
  value-free warning per source; editor saves and previews are not refused
- TestUnsafeText pins the safe and unsafe texts
- check-phase35.sh GO_TESTS requires them and TestMailSafetySmoke
2026-11-14 15:40:57 +01:00
Jakub Zych
8751f92230 docs(35-08): record plan completion in state and roadmap 2026-11-14 15:32:25 +01:00
Jakub Zych
c4d0bbecc4 docs(35-08): complete mail URL scheme check and site name safety plan 2026-11-14 15:31:10 +01:00
Jakub Zych
15d3e6fb8d fix(postcard): print the site name literally in the built-in layouts' footer
- the footer partial gains a text argument, printed as a paragraph
  through html/template and verbatim in the text part; body stays
  Markdown for callers that pass Markdown on purpose
- the default and system layouts pass the copyright line as text, so
  *Acme*, Acme <Studio> and [x](url) appear as typed, as in the header
  (WR-01)
- README partial table, layouts and Branding paragraphs; docs partials
  table and built-in layouts paragraph
- TestMailSafetySmoke/literal_footer
2026-11-14 15:29:57 +01:00
Jakub Zych
cd91cf2e64 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
2026-11-14 15:25:03 +01:00
Jakub Zych
701ce8979d docs(35): UI-SPEC copy for the unsafe site name refusal 2026-11-14 15:20:45 +01:00
Jakub Zych
3a725469c6 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
2026-11-14 15:20:29 +01:00
Jakub Zych
13ab905f8d fix(postcard): check URL schemes in decoded attribute values, not in text
- validateHTML keeps the raw tag and handler regexes and reads the rest
  through unsafeMarkup: x/net/html tokenizer, decoded attribute values,
  prefix check on URL attributes, whole-value check on CSS, list
  attributes, meta content and comments; any on* attribute is refused
- text is not a URL: "Metadata: Weekly" or "Big Data: Summit" as a site
  name or body text no longer stops a send (CR-01)
- entity-encoded javascript&#58; is refused whether or not the layout
  opts out of inlining (WR-05)
- draft layout CSS is checked as a style element
- fixtures that pinned prose as unsafe now carry markup-level URLs;
  the 35-07 subtest pinning an unsafe stored name is removed
- TestMailSafetySmoke prose_site_name and encoded_scheme
2026-11-14 15:13:35 +01:00
Jakub Zych
274dff4458 docs(35): decision note for the mail URL scheme check and site name safety 2026-11-14 15:05:56 +01:00
Jakub Zych
f4613fd26b docs(35): record gap-closure planning in state 2026-11-14 15:02:40 +01:00
Jakub Zych
6e8cead959 docs(35): plan gap closure for CR-01
Two gap-closure plans confirmed by the user:
- 35-08: URL-scheme check on decoded attribute values instead of the whole
  document, unsafe site names dropped at render with a warning and refused
  on the Branding form (postcard.UnsafeText), the inlined result never
  stops mail, literal site name in the footer (CR-01, WR-01, WR-05)
- 35-09: regression and unit tests, new names required by
  check-phase35.sh, IN-03 self-test fix, validation map
2026-11-14 14:59:30 +01:00
Jakub Zych
0aa38db8b5 docs(35): re-verify phase after gap closure - CR-01 gap found 2026-11-13 22:33:37 +01:00
Jakub Zych
b1f85c2177 docs(35): record code review disposition 2026-11-13 22:23:46 +01:00
Jakub Zych
75669b343f docs(35): add code review report 2026-11-13 22:23:31 +01:00
Jakub Zych
0bef6b3098 docs(35-07): update state and roadmap after plan 35-07 2026-11-13 22:11:33 +01:00
Jakub Zych
d00e2c8d6f docs(35-07): complete gap-closure tests plan
- SUMMARY for the G-35-1 and G-35-8 tests, the read-only consumers stage
  and the validation map
2026-11-13 22:11:03 +01:00
Jakub Zych
a3ce097455 docs(35): validation map for the gap closure
- 35-VALIDATION.md: G-35-1 and G-35-8 rows (postcard unit and Postgres,
  cabana Postgres, SPA, consumers through scratch modfiles); D-05 and the
  default-layout byte-identity rows superseded by the 35-05/35-06 notes;
  manual re-runs of UAT tests 1 and 8 (test 8 scoped to the built-in
  layouts), a real-inbox check and the deferred plugin follow-up check;
  open item: site name not checked for a URL scheme at save time
- 35-UAT.md: closure_note and rerun_scope on G-35-8 (framework part closed,
  plugin part deferred); status and results unchanged
2026-11-13 22:09:53 +01:00
Jakub Zych
a9381165c7 test(admin): mail template locale switcher
- LocaleVariantSwitcher: current flag, option values and locales, the label
  through the control id, the query kept on navigation, no navigation for the
  open version, selection restored when a guard throws, props updates
- FormView: no switcher with one variant; with unsaved edits switching asks
  the unsaved-changes confirm, stays on cancel and opens the sibling on confirm
- check-phase35.sh requires LocaleVariantSwitcher.test.ts (ADMIN_FILES)
2026-11-13 21:38:36 +01:00
Jakub Zych
eed91c821a test(cabana): grouped mail templates, site name and the inlining switch
- TestMailLocaleGroups: one list row per template, customized locales,
  grouped badges and status filter, localeVariants order, labels, states and
  current flag, the default version on a fallback row, save then send, reset,
  drift through the base file, the file version against the base file,
  out-of-group ids, the permission split and locales enabled at run time
- TestMailBrandSiteName: saved trimmed, 255-character limit, preview and send
  header, no header row without a name or a logo, current handling of a name
  holding a URL scheme
- TestMailLayoutInlineOptOut: the switch on a file layout, reset to the file
  value, a custom layout created with the switch off
- check-phase35.sh requires the three names (DOCKER_TESTS)
2026-11-13 21:38:30 +01:00
Jakub Zych
a0dde086d2 test(postcard): locale fallback, built-in layouts, partials and CSS inlining
- TestTemplateBase, TestTemplateFor and TestSendLocaleFallback pin the
  <template>-<locale> resolution and the order the override source is asked
- TestEnsureLocaleRows (Postgres): rows only for non-default locales without
  files, idempotent, customized content kept while file_hash follows the
  base, base_code from SyncIndex, reset of a fallback row, migrations roll back
- TestBuiltinLayoutsLogo, TestHeaderFooterPartials, TestButtonPartial and
  TestSiteName cover the finished default, system and minimal layouts
- TestInlineCSS, TestInlineCSSOptOut and TestInlineFailure cover inlining,
  the per-layout opt-out and the fallback when the inliner fails
- check-phase35.sh requires the new names (GO_TESTS, DOCKER_TESTS)
2026-11-13 21:31:44 +01:00
Jakub Zych
ae13e4dd41 test(35): read-only consumers with a scratch modfile in check-phase35.sh
- consumers stage runs each core plugin with GOWORK=off, GOPROXY=off and
  -mod=mod -modfile=<scratch>/go.mod (its go.sum merged with the framework's),
  so the go-premailer requirement resolves without writing the sibling tree
- workspace_check takes the modfile flags; a sibling whose git status
  --porcelain prints anything before or after the runs is refused
- self-test: planted dirty repository and a modfile resolving the framework
  elsewhere
2026-11-13 21:23:00 +01:00
Jakub Zych
0e97113a4f docs(35-06): update state and roadmap after plan 35-06 2026-11-13 21:19:40 +01:00
Jakub Zych
be9170af53 docs(35-06): complete finished mail layouts and CSS inlining plan 2026-11-13 21:19:04 +01:00
Jakub Zych
f1cebf1d70 docs(35): UI-SPEC copy for inlining, site name and the layout opt-out
- C5: the disable_auto_inline_css switch on the CSS tab with its copy;
  the CSS comment's inlining is now true
- C12: the site_name row after the logo, the changed logo comment and a
  note on the built-in layouts' header and footer, referencing the
  decision note that supersedes D-10's inlining claim
2026-11-13 21:17:30 +01:00
Jakub Zych
09a5338d9a feat(postcard): header, logo, footer and padding in the system and minimal layouts
- system.htm: the header partial (logo or site name) above the card and
  the copyright footer below it; its text wrapper ends with the footer
- brand CSS: the system layout's content cell keeps WinterCMS's 35px
  side padding (the 35px 0 override is gone)
- minimal.htm: the logo above the message when logoUrl is set
- TestMailPartialsSmoke/built_in_layouts covers the three layouts and the
  inlined brand colour on the button in each
- 35-06 Task 3 (G-35-8)
2026-11-13 21:17:02 +01:00
Jakub Zych
d320733510 feat(postcard): inline mail CSS at render with a per-layout opt-out
- github.com/vanng822/go-premailer v1.38.0 (default options) inlines the
  rendered HTML after the safety checks; the result is checked again,
  HTML without a style element is left as it is, an inliner error sends
  the style block only and warns (key inline:<layout>)
- opt-out: layout header key disable_auto_inline_css, the layouts column
  of the same name (migration 202611130003), LayoutFile/LayoutOverride/
  Draft.DisableAutoInlineCSS; SyncIndex mirrors and ResetOverride restores
  the file's value
- cabana layout form switch on the CSS tab, mapped into the layout draft
  and the save validation; en/pl copy
- tests: TestMailPartialsSmoke/inline, TestMailEditorSmoke/inline_flag,
  the layouts switch in TestMailScreensSmoke; CSS-slot tests read the
  style block through a no-op inliner
- 35-06 Task 2 (G-35-8)
2026-11-13 21:12:01 +01:00
Jakub Zych
dcd0ae5338 docs(35): decision note for mail CSS inlining with go-premailer
- go-premailer pinned at v1.38.0, facts checked, MVS changes and the
  indirect modules tidy adds, rejected alternatives
- supersedes D-10's inlining claim and lifts 35-01's default.htm gate;
  Branding gains a site name with the mail.from fallback
- STACK.md Supporting Libraries row
2026-11-13 20:55:30 +01:00
Jakub Zych
093529d45c feat(postcard): finished default layout with logo header, footer and site name
- default.htm ports WinterCMS's default layout: wrapper, header row with
  the Branding logo (or the site name), the inner-body card and a
  copyright footer; its text wrapper ends with the footer
- built-in header and footer partials (logo/body/url, body)
- layouts get siteName (Branding site name, else the display name of
  mail.from) and year; Brand.SiteName and migration
  202611130002_mail_brand_site_name
- cabana Branding form gets site_name (trimmed, max 255), mapped into the
  Branding preview draft; en/pl copy; img.logo brand CSS
- 35-06 Task 1 (G-35-8)
2026-11-13 20:52:52 +01:00
Jakub Zych
fdc2094ffc docs(35-05): update state and roadmap after plan 35-05 2026-11-13 20:43:50 +01:00
Jakub Zych
7a209dee9a docs(35-05): complete mail template locale groups plan 2026-11-13 20:43:18 +01:00
Jakub Zych
1173a5c5a2 docs(35): decision note superseding D-05 and the locale switcher contract 2026-11-13 20:42:06 +01:00
Jakub Zych
e114492bbe build(admin): rebuild the embedded admin for the mail locale switcher 2026-11-13 20:40:18 +01:00
Jakub Zych
67f7164302 feat(cabana): mail templates list grouped by template with per-locale status
Gap G-35-1 (supersedes D-05; D-06 reset and D-07 drift per locale):
- the templates list keeps one row per template (the base row, or the
  lowest variant when only variants ship) with a Customized locales
  column (Default, then locale codes, at most three then +N);
- row states and the status filter aggregate over the template's
  locale versions; the locale filter is removed;
- a not-customized locale without a file shows the base row's current
  subject, body and layout; its info partial says so, its file version
  compares with the base file, and Reset returns it to the base file
  (postcard.ResetOverride accepts a fallback-locale code);
- copy: mail.template.customized_locales, mail.info_locale_default,
  mail.info_locale_fallback (en/pl);
- tests: TestMailScreensSmoke/locales_list, templates and drift updated,
  TestMailDrift on the grouped row, TestMailTemplateFilterScopes.
2026-11-13 20:39:45 +01:00
Jakub Zych
52c9c7eb18 feat(mail): one admin record per mail template with a locale switcher
Gap G-35-1 (supersedes D-05), tracer slice:
- postcard: migration 202611130001_mail_template_base_code (base_code
  column and index); SyncIndex writes base_code; EnsureLocaleRows creates
  the <template>-<locale> rows of locales that ship no file; TemplateBase
  and Catalog.TemplateFor; send, preview and validation resolve a missing
  <template>-<locale> to the locale's customization, else the base's
  customization, else the base file. Names with their own file send as
  before.
- cabana: mail locales are the translator's plus the TranslationWriter's
  enabled locales; sync ensures the locale rows and re-syncs when the
  locale set changes; record lookups admit fallback-locale rows; the
  record title is the base code; RecordMeta.LocaleVariants
  (RecordLocaleVariant) on the show and update responses.
- admin: LocaleVariantSwitcher in the update form header, from
  meta.localeVariants, behind the unsaved-changes confirm.
- tests: TestMailOverrideSmoke/locale_fallback,
  TestMailScreensSmoke/locales, LocaleVariantSwitcher.test.ts.
2026-11-13 20:29:42 +01:00
Jakub Zych
9afe95ccef docs(35): revise gap-closure plans after plan check
- 35-07: record G-35-8 as framework-closed with the plugin part deferred
  (35-VALIDATION.md and a closure note in 35-UAT.md); scope the UAT test 8
  re-run to the built-in layouts; deferred plugin follow-up check
- 35-07: TestInlineCSS dangerous-URL fixture injected past save validation
- 35-06: examples/hello go.mod/go.sum in files_modified
- 35-05: T-35-31 wording matches the locale tag rule (pt-BR)
- 35-05/35-06: tracer tasks may land as green sub-commits
2026-11-13 16:46:05 +01:00
Jakub Zych
293400e61f docs(35): plan gap closure for G-35-1 and G-35-8
Three gap-closure plans confirmed by the user:
- 35-05: one admin record per mail template with a locale switcher (supersedes D-05)
- 35-06: finished built-in layouts, Branding site name, CSS inlining via go-premailer (supersedes D-10's inlining claim)
- 35-07: unit tests for both gaps and a read-only scratch-modfile consumers stage
2026-11-13 16:43:14 +01:00
Jakub Zych
b8c177fca8 docs(35): diagnose UAT gaps G-35-1 and G-35-8 2026-11-13 16:18:28 +01:00
Jakub Zych
9db6a66ca4 test(35): complete UAT - 8 passed, 2 issues 2026-11-13 16:11:26 +01:00
593f99ac70 test(35): persist human verification items as UAT 2026-11-13 14:46:09 +01:00
5eb866b37a docs(35): mark plan 04 complete in STATE and ROADMAP
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 14:31:53 +01:00
fd51f1f523 docs(35-04): complete unit tests and phase gate plan
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 14:31:10 +01:00
ed696bc74e docs(35): drop pending marker from validation status key
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 14:23:57 +01:00
31d019fcc5 docs(35): fill the validation map
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 14:23:48 +01:00
1ae1a9553f test(admin): unit and browser tests for the mail editor fields
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 14:23:28 +01:00
45017039b2 fix(admin): rebuild boardwalk dist after mail preview and insertImage fixes
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 14:23:28 +01:00
52e854a19e fix(admin): skip mail preview requests while the field is off-screen
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 14:21:48 +01:00
275e70b42d fix(admin): encode parentheses in markdown mail image URLs
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 14:21:48 +01:00
cd20540f13 test(cabana): unit tests for mail permissions, save validation, drift, reset, layout delete and test send
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 14:14:08 +01:00
659969b9ac test(postcard): unit tests for overrides, fallback, partials, samples, validation, sync and branding
- Pin override precedence, fallback, partials, samples, draft validation and branding
- Postgres TestStore/TestSync for index sync, drift hashes and reset
- Pact row-state and mail capability method-set pins; attach AbsolutePublicURL cases

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 14:04:14 +01:00
1df2e31dea fix(admin): isolate CodeMirror load for chunk-failure tests
- Route CodeEditorField through codeeditor/load so vitest can mock the chunk
- Keep registry expectations for colorpicker/codeeditor without importing the editor SFC

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:57:16 +01:00
e81cfde7b2 fix(admin): restore suite after colorpicker and codeeditor registration
- Expect colorpicker/codeeditor as registered controls; use notatype for unsupported cases
- Seed DatePicker placeholder from the model value so the calendar opens on that month
- Make CodeEditor chunk-failure mock reject the dynamic import

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:53:44 +01:00
5f62cd6b92 test(35): phase gate script check-phase35.sh
- Fail-closed stages for self-test, go, docker, consumers, admin, docs, marker and additive
- Consumers run sm-user-plugin and sm-paymentgateway-plugin mail tests against this checkout

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:53:44 +01:00
95eed7ad98 docs(35-03): complete mail templates SPA editor plan 2026-11-13 13:43:33 +01:00
f232076531 docs(state): record phase 31.2 context session 2026-11-13 13:41:27 +01:00
b8638aac66 docs(31.2): capture phase context 2026-11-13 13:41:25 +01:00
8969806dc8 fix(phrasebook): add mail.picker copy keys used by the admin image picker
SPA literals for insert/use/upload states and empty/error copy must resolve
in en and pl or the phrasebook SPA key check fails.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:40:49 +01:00
36f3410896 build(admin): rebuild the embedded admin for the mail editor
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:38:48 +01:00
d13340672f feat(admin): footer record actions, deletable flag, mail row states and diff styles
- FormView footer RecordActions when there is no preview; meta.deletable hides Delete
- Partial fields reload after save and record actions; customized/outdated badges
- .summer-diff kit and docs for codeeditor, mailpreview and footer actions

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:37:55 +01:00
aba512800e test(35-03): add failing test for customized and outdated row badges
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:35:48 +01:00
68e1d36fd5 feat(admin): colour picker, mail image field and the image picker with insert
- insertImage escapes markdown/html/css/text snippets per UI-SPEC C4
- MailImagePicker with canUpload-gated upload, radiogroup tiles, insert/choose modes
- ColorPickerField, MailImageField, markdown/codeeditor Insert image wiring

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:34:54 +01:00
48e87b7543 docs(state): record phase 31.1 context session 2026-11-13 13:32:27 +01:00
db88fb15f2 docs(31.1): capture phase context 2026-11-13 13:32:26 +01:00
3e29e6042e test(35-03): add failing tests for insertImage and colorpicker
- insertImage C4 table expects escaped markdown/html/css/text snippets
- ColorPickerField sync cases; stubs return empty until GREEN

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:29:09 +01:00
9975cf4b52 feat(admin): codeeditor field on CodeMirror 6, loaded lazily
- Pin the seven approved CodeMirror/lezer packages exactly; lockfile integrity matches the decision note
- Lazy createCodeEditor with Go {{ }} highlighting, form hotkeys kept, Tab unbound
- Loading skeleton, chunk-failure textarea fallback, read-only pre

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:28:02 +01:00
7e2c01172f test(35-03): add failing tests for codeeditor field
- Browser smoke: Tab leaves, Mod+S/Mod+Enter save, Esc does not cancel
- Happy-dom: loading box, read-only pre, chunk-failure textarea fallback
- Stub field/editor so imports resolve; assertions fail until GREEN

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:24:19 +01:00
ee0bbc27f8 docs(31): record planned phase and patterns 2026-11-13 13:15:24 +01:00
6e0d4bbca7 docs(35): CodeMirror decision note and STACK.md row for the admin code editor
- Document seven exact pins, integrity values, and the too-new flag on @codemirror/view
- Add Admin SPA STACK.md rows linking the decision note before any npm install

Plan 35-03, task 2

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:15:23 +01:00
52204e171d feat(admin): mail preview field with sandboxed HTML and test send
- Add MailPreviewField (POST /mail/preview + /mail/test-send, empty sandbox iframe)
- Register mailpreview as valueless/group-labelled; SettingsFormView FORM_VALUES/FORM_LOCALE
- Smoke tests for srcdoc, sequence guard, 422 keep-last, and 429 Retry-After

Plan 35-03, task 1

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:14:22 +01:00
9ea3159ba2 fix(31): reslice plans after checker feedback 2026-11-13 13:07:56 +01:00
da6bfa9e48 docs(35-02): record plan progress in state and roadmap
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:05:49 +01:00
399ba5fb60 docs(35-02): complete mail screens server plan
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:05:25 +01:00
0c73c8d4f1 feat(cabana): mail preview and test send to yourself
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:02:49 +01:00
4fd2ed07eb feat(cabana): code editor, colour and mail image fields, mail branding and the image library
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 12:53:09 +01:00
b996a8fc83 docs(31): add recording foundation todo and test plans 2026-11-13 12:48:32 +01:00
83f76cc3f7 feat(cabana): mail layouts and partials screens with reset, drift and custom layouts
- Layouts and partials controllers with catalog scoping, reset action and File version diff
- Custom layout create/delete with in-use refusal; meta.deletable and customized/outdated row states
- List schema golden fixtures updated for the two new row-state message keys

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 12:33:20 +01:00
Jakub Zych
7efb9ed7ad feat(cabana): mail templates screen over postcard overrides
- Settings -> Mail -> Mail templates in the internal pseudo-plugin when
  postcard's Mailer is published; system.manage_mail_templates and
  system.manage_mail_layouts registered with no role grants
- MailTemplate/MailLayout models, catalog-scoped list and form, layout
  relation over file and custom layouts, no create or delete
- save stamps is_custom, base_hash and customized_at and validates the
  override through postcard.Editor inside the save transaction
- serve-start postcard.SyncIndex through lagoon.OnDatabase, retried on
  the first mail list request
- copy en/pl, README and docs; TestMailScreensSmoke/templates

Plan 35-02, task 1
2026-11-13 11:45:13 +01:00
Jakub Zych
2acf8e46c4 docs(31): split into 31, 31.1 and 31.2 and record the planning decisions 2026-11-13 11:29:37 +01:00
Jakub Zych
7b25fcff55 docs(phase-31): add validation strategy 2026-11-13 11:21:57 +01:00
Jakub Zych
1bfe0514f8 docs(31): research phase domain 2026-11-13 11:20:52 +01:00
Jakub Zych
533d0d2fcd docs(35-01): record plan decisions in state 2026-11-13 11:11:42 +01:00
Jakub Zych
db86b51a51 docs(35-01): complete mail domain layer plan 2026-11-13 11:11:01 +01:00
Jakub Zych
2bf9081c1b feat(postcard): mail branding and the logo URL
- Brand, DefaultBrand and CompileBrandCSS: thirteen colours, each checked
  as a six-digit hex colour, compiled into CSS for plain elements and the
  built-in layouts and partials
- once the branding row exists its compiled CSS replaces mail.brandCss;
  mail.css still follows, and the file version sent after a failing
  override keeps the Branding
- layouts get logoUrl, built per send from storage.uploads.public_url or
  app.url through attach.AbsolutePublicURL; a logo that cannot be shown is
  left out with a rate-limited warning
- Editor previews and validates a Branding draft (rule colour)

Plan 35-01, task 5.
2026-11-13 11:06:43 +01:00
Jakub Zych
935e4bf64f feat(attach): absolute public URL from config
- attach.AbsolutePublicURL builds the absolute public URL of a blob key from
  storage.uploads.public_url, or from app.url and the public path prefix
- it reads the config only, not the values OpenBucket recorded, so a job
  worker that opened no bucket gets the same URL as serve
- attach.ErrNoAbsoluteURL when neither base is configured

Plan 35-01, task 5.
2026-11-13 11:01:43 +01:00
Jakub Zych
f8fa0f1b4b docs(31): capture phase context 2026-11-13 10:59:36 +01:00
Jakub Zych
495319ee21 feat(postcard): sample values, file hashes, index sync and the draft editor
- sample.<path> header keys and a parse-tree walker that fills every other
  variable with a visible [path] placeholder, nested fields and range
  targets included
- every file entry carries the sha256 of its CRLF-normalized text; the
  catalog lists its files (Templates, Layouts, Partials) for admin code
- SyncIndex upserts one index row per file and never touches the override
  columns of a customized row; ResetOverride returns a row to its file
- Editor validates, previews and test-sends a template, layout or partial
  draft through the render path of Send and reports field and rule
- pact.RowStateCustomized and pact.RowStateOutdated

Plan 35-01, task 4.
2026-11-13 10:57:05 +01:00
Jakub Zych
5df1ec27cf feat(postcard): mail partials, built-in layouts and layout and partial overrides
- pact.HasMailPartials: plugins declare <plugin>::mail.partials.<name>,
  loaded from views/mail/partials/<name>.htm; HasMailTemplates is unchanged
- bodies and layouts call {{ partial "name" "key" value ... }}; a call in a
  Markdown body leaves a per-render random token swapped after goldmark, so
  raw HTML stays disabled for bodies
- built-in partials button, panel, table and subcopy, built-in layouts
  system and minimal next to the unchanged default, reachable by alias
  after a plugin's own aliases
- NewDBSource also reads customized and database-only layouts and
  customized partials; a layout's CSS goes before mail.css

Plan 35-01, task 3.
2026-11-13 10:38:14 +01:00
Jakub Zych
7e5d2c74af feat(postcard): database overrides for mail templates with file fallback
- postcard owns the system_mail_* tables (postcard.Migrations), run by lagoon
  as the framework set summercms.postcard after system_files
- Send asks an OverrideSource once per message; NewDBSource reads the
  customized template row through the *gorm.DB published on the app
- a failed lookup, missing tables or an override that does not render or
  fails the safety checks sends the file version and is logged
- the caller's Message.Subject still wins; Mailer, Message, NewMailer,
  Catalog.Register and BootPlugin keep their signatures

Plan 35-01, task 2 (tracer).
2026-11-13 10:26:10 +01:00
Jakub Zych
3198bbe1aa docs(quick-261108-pe4): beachcomber highlights and field projection 2026-11-08 18:45:54 +01:00
Jakub Zych
7819c6746c feat(beachcomber): search highlights and field projection (quick-261108-pe4)
- Additive: Query.IncludeFields, ExcludeFields and Highlight; left empty,
  the Typesense request is the same as before.
- SearchResult.Hits holds one Hit per id, in step with IDs; SearchPage
  always fills it.
- Snippets are plain-text Segment runs split at private-use highlight tags,
  never HTML; MaxSnippetsPerArray is applied client-side.
- Optional HighlightSearcher capability, checked with SupportsHighlights
  (true for Typesense, false for null and third-party engines).
- README and docs: Highlights sections with the rule that a caller drops
  the hit of every id failing the SQL re-check before showing a snippet.

Targets framework v0.6.4 (additive, no breaking change).
2026-11-08 18:45:29 +01:00
Jakub Zych
6f9b77033f docs(35): create phase plan (4 plans, 4 waves) 2026-11-06 19:43:03 +01:00
Jakub Zych
a0242808a0 docs(35): pattern map and planning-time decisions D-22..D-25 2026-11-06 19:10:23 +01:00
Jakub Zych
9232dc1048 docs(35): research and validation strategy for the mail templates editor 2026-11-06 19:05:34 +01:00
Jakub Zych
a917966d31 docs(quick-261106-kt2): in-process deferred:purge, migrate and queue:clear reuse the published database 2026-11-06 15:38:37 +01:00
Jakub Zych
99abe88b6a fix(conga): queue:clear reuses the app's published database (quick-261106-kt2)
Run in-process on an app that already published its pool, queue:clear failed
with "backpack: duplicate provider for *sql.DB". It now goes through
withAppDB; the CLI path is unchanged.
2026-11-06 15:28:08 +01:00
Jakub Zych
16a20088a3 fix(lagoon): run deferred:purge and the migrate commands on the app's published database (quick-261106-kt2)
The nightly framework entry deferred:purge failed under serve's worker and
schedule:run with "backpack: duplicate provider for *sql.DB": withDB always
opened and published a second pool. It now reuses the published *gorm.DB and
leaves that pool open; the CLI path (nothing published) is unchanged.
2026-11-06 15:23:28 +01:00
Jakub Zych
8ebfedf64c docs(quick-261106-kt1): MCP 401 challenge names only resource_metadata, T-19.7-10 updated 2026-11-06 15:15:03 +01:00
Jakub Zych
609caa4f3f fix(pier): MCP 401 challenge names only resource_metadata
- drop the response-writer wrapper that appended scope="read" to every 401
- the SDK handler now gets the original writer; RequireBearerToken still sets no Scopes
- TestPierTracerSmoke pins the exact challenge for a bad and a missing bearer
- README and docs/services/mcp.md describe the header without a scope parameter
2026-11-06 15:09:10 +01:00
Jakub Zych
ef47baf0a1 docs(quick-261106-jhk): MCP authorize drops OIDC identity scopes for the ChatGPT connector 2026-11-06 14:35:14 +01:00
Jakub Zych
aba678b196 fix(wristband): drop OIDC identity scopes at MCP authorize
Clients that also read the issuer's OpenID Connect discovery document
add openid, profile or email to their MCP authorize request, and the
MCP flavour refused those requests with invalid_scope ("scope contains
an unsupported value"), so they could not connect.

The three identity scopes are now dropped before the allow-list check,
as RFC 6749 section 3.3 lets a server grant fewer scopes than requested.
A request left with no other scope gets the read default. Any other
unknown scope, including a differently cased identity name, is still
refused. The MCP flavour still never grants identity scopes or issues
an id_token, and the metadata document is unchanged.
2026-11-06 14:17:43 +01:00
Jakub Zych
5db032f52f docs(35): UI design contract 2026-11-06 11:56:48 +01:00
Jakub Zych
928ae0097d docs(35): capture phase context 2026-11-06 11:02:13 +01:00
Jakub Zych
c755209964 docs: add phase 35 - mail templates and layouts editor 2026-11-06 10:18:59 +01:00
Jakub Zych
31acec420a docs(quick-261106-e5v): purge token rename leftovers, todo closed 2026-11-06 10:12:29 +01:00
Jakub Zych
d9d57c7411 docs(quick-261106-dv0): shared plugin boot logs at Debug, todo closed 2026-11-06 10:02:16 +01:00
Jakub Zych
8a600ca704 docs(quick-261106-d20): fonoteka.go uploads named after the sniffed type, attach.UploadWriterOptions exported, 2 todos closed 2026-11-06 09:38:19 +01:00
Jakub Zych
903859a131 feat(lagoon/attach): export UploadWriterOptions for blob writers that bypass Store (quick-261106-d20)
- attach.UploadWriterOptions (was the unexported uploadWriterOptions) gives
  code that writes an upload to the bucket itself the same Content-Type and
  Content-Disposition: attachment for non-inline types that attach.Store stores
- writeBlob calls it; Store behaviour unchanged
- TestUploadWriterOptions table test
- lagoon README, docs/database/attachments.md and docs/services/storage.md
  describe it for writers that bypass attach.Store
2026-11-06 09:31:51 +01:00
Jakub Zych
9fa740e8b7 docs: capture todo - blob writers that bypass attach.Store set Content-Disposition 2026-11-06 09:18:55 +01:00
Jakub Zych
895248eef2 docs(quick-batch-261105-oc4): security hardening batch, 5 items, 12 todos closed 2026-11-05 18:46:35 +01:00
Jakub Zych
27c98bf22a fix(lagoon/attach): StaticHandler sends the stored Content-Disposition and nosniff (quick-261105-oc8)
- attach.StaticHandler and attach.StaticHandlerPublic set X-Content-Type-Options: nosniff on every response
- the stored disposition is read with one Attributes call after the is_public gate and sent on GET and HEAD; a value mime.ParseMediaType rejects is sent as attachment
- blobs without a stored disposition are served as before
- lagoon README, storage and attachments docs pages, surf uploads comment updated
2026-11-05 18:13:27 +01:00
Jakub Zych
5aa846c5e8 docs(quick-261105-eab): OIDC grant flows serialized with revoke 2026-11-05 10:42:26 +01:00
Jakub Zych
f9255272c0 docs(phase-20): add security threat verification 2026-11-05 10:17:05 +01:00
Jakub Zych
1b1a553fb6 docs(phase-19.4.1): add security threat verification 2026-11-05 10:12:53 +01:00
Jakub Zych
95cced94fc docs(phase-11.2): add security threat verification 2026-11-05 10:09:29 +01:00
Jakub Zych
71dc0485ee docs(quick-261105-din): fix 32.1 CR-01, consent allow serialized with revoke 2026-11-05 10:00:02 +01:00
Jakub Zych
8c6b3171a8 docs(phase-19.3): add security threat verification 2026-11-05 09:33:44 +01:00
Jakub Zych
7490a310ce docs(phase-34): add security threat verification 2026-11-05 09:32:29 +01:00
Jakub Zych
439a994aac docs(phase-32.1): add security threat verification 2026-11-05 09:30:38 +01:00
Jakub Zych
7b8d205613 docs: add backlog item 999.2, SEO follow-ups after Phase 33 (v0.6.2) 2026-11-05 02:33:31 +01:00
Jakub Zych
1846e98c0f docs(33): phase 33 re-verification after the release (human_needed)
Covers 33-14-SUMMARY.md, the release and deploy logs and the release notes. Release items settled: tags, changelog posts, grzybyfunkcjonalne.pl sitemaps and post head, G1 on the demo; W5 SQL check waived by Jakub. Open: live MCP session, Rich Results Test, visual and admin checks (with grzyby checklist items 3, 5, 6, 7). Seeds 33-UAT.md.
2026-11-05 02:32:51 +01:00
Jakub Zych
7049dffd9a docs(phase-33): tick 33-14 in the roadmap 2026-11-05 02:26:02 +01:00
Jakub Zych
94c47268b5 docs(33-14): complete the tests, gate and release plan 2026-11-05 02:25:43 +01:00
Jakub Zych
6875627fdf docs(33-14): grzybyfunkcjonalne.pl step 12, smoke ok and the 404 log cleared 2026-11-05 02:24:10 +01:00
Jakub Zych
201fd0fbf9 docs(33-14): release log, post-release verification 2026-11-05 02:20:44 +01:00
Jakub Zych
211687f439 docs(33-14): release log, deploys of summercms.io, the demo, bm and grzybyfunkcjonalne.pl 2026-11-05 02:15:17 +01:00
Jakub Zych
ef164dda8e docs(33-14): release log, app pins and pushes 2026-11-05 02:01:35 +01:00
Jakub Zych
143b4dbdca docs(33-14): changelog posts and the layer patch releases 2026-11-05 01:36:02 +01:00
Jakub Zych
8edc869963 docs(33-14): release log, tags pushed and the layer install check failure 2026-11-05 01:25:43 +01:00
348 changed files with 46694 additions and 520 deletions

View File

@@ -46,7 +46,9 @@ Decimal phases appear between their surrounding integers in numeric order.
- [ ] **Phase 19.8: Console commands overhaul** - `diary` logging module, Artisan-grade global flags, help and `list` in `bonfire`, sweep of every command
- [ ] **Phase 20: Demo instance with every shared plugin** - Add the chat family (chat, channels, video calls, chatbots, forum, herald, friends) to the live demo from Phase 19.4.1
- [ ] **Phase 30: Płytarium cutover** - Parity harness green, both real clients run unchanged in production
- [ ] **Phase 31: Chat polish against WavePath clients** - Replay WavePath's chat traffic through `tide` against the ported chat plugins until green
- [ ] **Phase 31: Chat polish against WavePath clients** - `tide` additions, `sm-wavepath-app`, the full PHP recording of WavePath's community routes and the foundation slice green
- [ ] **Phase 31.1: WavePath messaging parity** (INSERTED) - Group chat, channels, DMs, threads, commands and attachments replay green
- [ ] **Phase 31.2: WavePath satellites parity and close-out** (INSERTED) - Presence, push, webhooks, bot, video, guests, forums and notes; zero pending
## Phase Details
@@ -1579,22 +1581,86 @@ Plans:
### Phase 31: Chat polish against WavePath clients
**Goal:** The ported chat and chat satellites carry WavePath's chat traffic exactly as PHP does. The chat routes that WavePath's clients call are recorded with `tide`, replayed against the Go plugins and fixed until green, so that chat, the core feature of WavePath, is not the risk in the WavePath migration.
**Goal:** WavePath's community traffic is recorded from the PHP backend with `tide` and replayed against a Go app, so that chat, the core feature of WavePath, is not the risk in the WavePath migration. This phase delivers the harness and the corpus: the `tide` additions, the `sm-wavepath-app` skeleton, the local PHP stack and scenario, the full PHP recording, and the foundation slice (groups, members, invites, friends, realtime authorization) ported and green. Phases 31.1 and 31.2 port the rest of the corpus (split at planning, 2026-11-13).
**Mode:** mvp
**Depends on:** Phase 19, Phase 19.1, Phase 30 (formerly Phase 19.2; moved 2026-10-18 so the `tide` recording is made just before the WavePath migration, while the PHP routes still move)
**Repos:** `sm-chat-plugin`, `sm-chatchannels-plugin` and the satellite repos; `summercms.go` only for `lighthouse` or `tide` gaps
**Depends on:** Phase 19, Phase 19.1 (formerly Phase 19.2; the Phase 30 dependency was sequencing only and is dropped, 31 D-05)
**Repos:** `sm-wavepath-app` (new); `sm-chat-plugin`, `sm-chatchannels-plugin`, `sm-chatbots-plugin`, `sm-chatvideo-plugin`, `sm-forum-plugin`, `sm-herald-plugin`, `sm-userfriends-plugin`; `sm-user-plugin` (additive only); `summercms.go` only for `tide` or `lighthouse` gaps; `sm-demo-app`, `sm-bm-app` and the vue layers to follow shared-plugin changes; `sm-oauthserver-plugin` for the OIDC parity recording
**Requirements**: TBD
**Success Criteria** (what must be TRUE):
1. A `tide` corpus of the chat, channel, thread, video-room and push routes, recorded from the PHP backend through `vue-wavepath-app`, `wavepath-mcp` and `hubot-wavepath`, replays green against the Go plugins.
2. Realtime events on the `chat`, `video` and `presence:` namespaces match the PHP broadcasts recorded by the `tide` Centrifugo recorder.
3. Behaviour stays neutral to the other consumers of these plugins (QuestStream, Horoskopia, Portal). Framework READMEs and docs still name no application.
1. A `tide` corpus of the whole community surface (31 D-09: every route under `/_wave/api/v1/community`, the guest, push, bot and token routes and the webhook, 196 routes) is recorded from the PHP backend through `vue-wavepath-app` and `hubot-wavepath`, with hand-written cases for the routes no client calls, and replays green against PHP itself.
2. Every writing case of the corpus has a broadcast golden with all publications PHP sent for it, on any namespace (31 D-10), and outbound vendor calls are recorded as upstream sidecars.
3. The foundation slice (groups, members, invites, join, friends, realtime authorization) is `ported` in `sm-wavepath-app` and replays green, broadcasts included. A gate script reports the pending count of the remaining routes and fails closed.
4. Behaviour stays neutral to the other consumers of these plugins: `sm-bm-app` and `sm-demo-app` build and pass their tests with the released plugin versions (31 D-14). Framework READMEs and docs still name no application.
5. The new code has unit tests, delivered in the phase's last plan.
**Plans:** 11 plans
Plans:
**Wave 1**
- [ ] 31-01-PLAN.md — Tide core data contracts: relative masks, cookies, headers, labels, repeat and manifest reference
- [ ] 31-03-PLAN.md — `sm-wavepath-app` skeleton and fail-closed isolated PHP parity stack
- [ ] 31-09-PLAN.md — Folded `vue-chat-layer` slash-command parity fix
- [ ] 31-10-PLAN.md — Folded additive moderation seams for users, friend groups and attachment filenames
**Wave 2**
- [ ] 31-02-PLAN.md — Tide per-case broadcast/upstream sidecars, minted credentials, body comparers and CLI wiring
- [ ] 31-08-PLAN.md — Folded OIDC PHP parity recording in `sm-oauthserver-plugin`
**Wave 3**
- [ ] 31-04-PLAN.md — Scenario on both sides, 196 pending-route manifest, corpus checker, harness and fail-closed gate
**Wave 4**
- [ ] 31-05-PLAN.md — Full 196-route PHP recording with client provenance, publications, upstreams and green self-replay
**Wave 5**
- [ ] 31-06-PLAN.md — Foundation infrastructure: envelope, actor, buckets, contexts, resolvers, authorizers and realtime
**Wave 6**
- [ ] 31-07-PLAN.md — Foundation handlers and lifecycle green: groups, members, invites, join, friends and phase gate
**Wave 7**
- [ ] 31-11-PLAN.md — Unit tests last: tide, app foundation, parity/gate and folded-todo regression matrices
### Phase 31.1: WavePath messaging parity (INSERTED)
**Goal:** The messaging routes of the WavePath corpus recorded in Phase 31 replay green against Go: group chat, channels, direct messages, threads, commands, reactions, emoji, preferences, pins and attachments, including the attachment streaming delta with Range support (31 D-12) released in `sm-chat-plugin`.
**Mode:** mvp
**Depends on:** Phase 31
**Repos:** `sm-wavepath-app`; the shared chat plugin repos for parity fixes; `sm-demo-app`, `sm-bm-app` and the vue layers to follow
**Requirements**: TBD
**Success Criteria** (what must be TRUE):
1. Every group chat, channel, DM, thread, command, reaction, emoji, preference, pin and attachment route of the corpus is `ported` with passing cases, and its broadcast goldens are asserted.
2. Attachment downloads answer Range requests as PHP does (206, 416, `Accept-Ranges`), released as a `sm-chat-plugin` patch tag with a changelog post.
3. `sm-bm-app` and `sm-demo-app` build and pass their tests with the released plugin versions before each plugin tag (31 D-14).
4. The new code has unit tests, delivered in the phase's last plan.
**Plans:** 0 plans
Plans:
- [ ] TBD (run /msd-plan-phase 31 to break down)
- [ ] TBD (run /msd-plan-phase 31.1 to break down)
### Phase 31.2: WavePath satellites parity and close-out (INSERTED)
**Goal:** The rest of the WavePath corpus replays green against Go and the corpus closes at zero pending (31 D-15): presence and status, notifications and push, link unfurl, webhooks, bot REST with the token guard, search, video and guests, forums and shared notes (on a minimal, provisional diary read model).
**Mode:** mvp
**Depends on:** Phase 31.1
**Repos:** `sm-wavepath-app`; the shared plugin repos for parity fixes; `sm-demo-app`, `sm-bm-app` and the vue layers to follow
**Requirements**: TBD
**Success Criteria** (what must be TRUE):
1. Every corpus route is `ported` with passing cases and every broadcast golden and upstream sidecar is asserted. The only non-matching cases are signed entries in the accepted-differences file (31 D-13).
2. The fail-closed gate script in `sm-wavepath-app` passes at zero pending and checks that `sm-bm-app` and `sm-demo-app` build and pass (31 D-15).
3. The security review of the app plugin (guest access, bot and token authentication, webhook, access resolvers) is done and its findings are resolved.
4. The re-record with a drift report can be run unattended (31 D-06).
5. The new code has unit tests, delivered in the phase's last plan.
**Plans:** 0 plans
Plans:
- [ ] TBD (run /msd-plan-phase 31.2 to break down)
### Phase 32: SEO foundation
@@ -1692,7 +1758,7 @@ Plans:
3. The crawler reports SEO issues per URL, and each issue can be fixed through MCP.
4. The new code has unit tests, delivered in the phase's last plan.
**Plans:** 13/16 plans executed
**Plans:** 16/16 plans executed
Plans:
**Wave 1**
@@ -1725,7 +1791,7 @@ Plans:
- [x] 33-13-PLAN.md — grzybyfunkcjonalne.pl on the new sitemap format and the SEO layer; uat deploy by decision
**Wave 9** *(blocked on Wave 8 completion)*
- [ ] 33-14-PLAN.md — unit tests, check-phase33.sh --all, release tags in order, app re-pins, changelog post
- [x] 33-14-PLAN.md — unit tests, check-phase33.sh --all, release tags in order, app re-pins, changelog post
**Wave 10** *(gap closure after the 33-14 release checkpoint; 33-14 Task 4 resumes after both)*
- [x] 33-15-PLAN.md — Go plugins: route report noindex paths and the filter (G1), Journal descriptors per translated locale (G3), crawl lifecycle and addresses, sitemap IndexNow/lock/lastmod/migration/headings, Journal content fixes
@@ -1819,7 +1885,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
| 30. Płytarium cutover | 0/TBD | Not started | - |
| 31. Chat polish against WavePath clients | 0/TBD | Not started | - |
| 32. SEO foundation | 6/6 | In Progress| |
| 33. SEO output, audit and content | 13/14 | In Progress| |
| 33. SEO output, audit and content | 16/16 | In Progress| |
| 34. Plugin marketplace | 6/6 | In Progress| |
## Backlog
@@ -1844,3 +1910,58 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
Plans:
- [ ] TBD (promote with /gsd-review-backlog when ready)
### Phase 999.2: SEO follow-ups after Phase 33, for v0.6.2 (BACKLOG)
**Goal:** Clear what Phase 33 deferred:
- the journal-tag drift warning while tag pages are off (G2), which needs an additive ContentDescriptor field such as `Routable` and signpost.Activate accepting a type without a URL pattern;
- the deferred warnings and info items in 33-REVIEW.md and 33-REVIEW-GAPFIX.md, listed under "Deferred" in 33-15 and 33-16:
- sitemap: types sharing a group slug, no 50 MB byte guard, Additional addresses on another host;
- seo: long crawls held in memory and running past the job timeout, recheck inside an open transaction;
- journal layer: card image `sizes`, the sitemap group home crumb;
- journal plugin: the author login in URLs, the alt batch with locale "" next to the default locale, the settings API's own url check;
- a post-release mode for `check-phase33.sh --consumers`;
- the grzyby DEPLOY.md Verify line expecting `X-Robots-Tag: index, follow`;
- a decision for untranslated locale addresses, which still serve default-locale content under their own canonical: point the canonical at the default locale, or answer 404.
**Requirements:** TBD
**Plans:** 0 plans
Plans:
- [ ] TBD (promote with /msd-review-backlog when ready)
### Phase 35: Mail templates and layouts editor
**Goal:** Administrators edit every mail the application sends from the admin panel, as in WinterCMS's Mail templates screen. System mail and the templates plugins register through `pact.HasMailTemplates` appear in a list. Each template can get a database override of its subject and body, and the override can be reset to the file version. Layouts become admin-editable records assigned to templates, with a few predefined layouts seeded. Images can be uploaded and placed in layouts and templates. postcard renders the override when one exists, otherwise the plugin's file, so mail that already works keeps working.
**Requirements**: TBD
**Depends on:** Phase 34
**Context:** postcard already loads plugin templates and layouts from `views/mail/` (`pact.HasMailTemplates`, `postcard.BootPlugin`); this phase adds the editable database layer, admin screens and image handling on top. To confirm in discussion: partials (WinterCMS mail partials), preview and test send, per-locale variants, and whether the screens live in cabana or in a plugin.
**Plans:** 9/9 plans complete
Plans:
**Wave 1**
- [x] 35-01-PLAN.md — pact `HasMailPartials`, postcard-owned mail tables and migrations, per-send override lookup with file fallback, partials, sample vars, Branding CSS, index sync, Editor API, docs
**Wave 2** *(blocked on Wave 1 completion)*
- [x] 35-02-PLAN.md — cabana Settings → Mail screens, two permission codes, reset/delete rules, drift notice and diff, server field types, preview and own-address test send, OpenAPI, en/pl copy
**Wave 3** *(blocked on Wave 2 completion)*
- [x] 35-03-PLAN.md — admin SPA: CodeMirror decision note and checkpoint, codeeditor/colour/image fields, image picker, mail preview and test send, rebuilt dist
**Wave 4** *(blocked on Wave 3 completion)*
- [x] 35-04-PLAN.md — unit tests for the D-21 list and `scripts/check-phase35.sh` (incl. user and paymentgateway mail tests)
**Wave 5** *(gap closure G-35-1, blocked on Wave 4 completion)*
- [x] 35-05-PLAN.md — one admin record per mail template with a locale switcher, fallback-locale versions, send resolution of `<template>-<locale>`, decision note superseding D-05
**Wave 6** *(gap closure G-35-8, blocked on Wave 5 completion)*
- [x] 35-06-PLAN.md — finished default/system/minimal layouts (logo or site name header, card, footer), Branding site name, CSS inlining via go-premailer with a per-layout opt-out, decision note superseding D-10
**Wave 7** *(gap closure, blocked on Wave 6 completion)*
- [x] 35-07-PLAN.md — unit tests for both gaps and `scripts/check-phase35.sh` with a read-only scratch-modfile consumers stage
**Wave 8** *(gap closure CR-01, blocked on Wave 7 completion)*
- [x] 35-08-PLAN.md — URL-scheme check on decoded attribute values instead of the whole document, a site name never stops a send (dropped with a warning) and an unsafe one is refused on the Branding form, the inlined result never stops mail, literal footer (CR-01, WR-01, WR-05), decision note
**Wave 9** *(gap closure tests, blocked on Wave 8 completion)*
- [x] 35-09-PLAN.md — regression and unit tests for CR-01, WR-01 and WR-05, new names required by `scripts/check-phase35.sh` (plus the IN-03 self-test fix), validation map

View File

@@ -1,19 +1,20 @@
---
msd_state_version: "1.0"
milestone: v1.0
current_phase: "19.7"
current_phase_name: Generic MCP module (INSERTED)
status: verifying
stopped_at: Phase 32 context gathered
last_updated: "2026-10-25T21:26:24.117Z"
last_activity: 2026-10-23
last_activity_desc: "Completed 19.7-08: plugin gap closure, E-1 logo, E-2 member token scopes; paused before 19.7-09"
state_head: 9a76c7ec1c0c17e93e00086231af78648eb40c43
current_phase: 30
current_phase_name: Płytarium cutover
status: planning
stopped_at: Phase 35 complete, ready to plan Phase 30
last_updated: "2026-11-16T09:05:22.965Z"
last_activity: 2026-11-16
last_activity_desc: Phase 35 complete (UAT 14/14), transitioned to Phase 30
state_head: 0c24e0e656c7bbb218e97abeeb8b1ccc43bbc97b
progress:
total_phases: 47
total_phases: 52
completed_phases: 37
total_plans: 242
completed_plans: 238
total_plans: 304
completed_plans: 293
percent: 77
gsd_state_version: "1.0"
milestone_name: milestone
---
@@ -25,22 +26,22 @@ milestone_name: milestone
See: .planning/PROJECT.md (updated 2026-10-22)
**Core value:** An existing WinterCMS-shaped app can be ported plugin by plugin to a single Go binary without its frontend noticing: the PHP version's API contract is the acceptance test.
**Current focus:** Phase 19.7 — Generic MCP module (INSERTED)
**Current focus:** Phase 35 — Mail templates and layouts editor
## Current Position
Phase: 19.7 (Generic MCP module (INSERTED)) — EXECUTING
Plan: 5 of 5
Status: Phase complete — ready for verification
Last activity: 2026-10-23 — Phase 19.7 execution started
Phase: 30 — Płytarium cutover
Plan: Not started
Status: Ready to plan
Last activity: 2026-11-16 — Phase 35 complete (UAT 14/14), transitioned to Phase 30
Progress: [████████░░] 82%
Progress: [████████░░] 77%
## Performance Metrics
**Velocity:**
- Total plans completed: 115
- Total plans completed: 124
- Average duration: 21 min
- Total execution time: 104 min
@@ -68,6 +69,7 @@ Progress: [████████░░] 82%
| 19.4 | 4 | - | - |
| 19.5 | 5 | - | - |
| 19.6.1 | 5 | - | - |
| 35 | 9 | - | - |
**Recent Trend:**
@@ -278,6 +280,50 @@ Progress: [████████░░] 82%
| Phase 19.6.1 P05 | 4 min | 2 tasks | 7 files |
| Phase 19.7 P01 | 52 min | 5 tasks | 64 files |
| Phase 19.7 P02 | 38 min | 4 tasks | 36 files |
| Phase 19.6 P01 | 61min | 5 tasks | 33 files |
| Phase 19.6 P02 | 25min | 3 tasks | 47 files |
| Phase 19.6 P03 | 100min | 6 tasks | 52 files |
| Phase 19.6 P04 | 96 min | 6 tasks | 40 files |
| Phase 32 P01 | 32 min | 4 tasks | 17 files |
| Phase 32 P02 | 37 min | 4 tasks | 34 files |
| Phase 32 P03 | 48 min | 5 tasks | 89 files |
| Phase 32 P04 | 43 min | 4 tasks | 66 files |
| Phase 32 P05 | 45 min | 4 tasks | 51 files |
| Phase 32 P06 | 1h 25m | 5 tasks | 47 files |
| Phase 32.1 P01 | 12 min | 3 tasks | 18 files |
| Phase 32.1 P02 | 17 min | 2 tasks | 6 files |
| Phase 32.1 P03 | 24 min | 4 tasks | 17 files |
| Phase 32.1 P04 | 14 min | 2 tasks | 13 files |
| Phase 34 P01 | 22 min | 5 tasks | 44 files |
| Phase 34 P03 | 51 min | 4 tasks | 70 files |
| Phase 34 P04 | 34 min | 4 tasks | 14 files |
| Phase 34 P05 | 28min | 3 tasks | 33 files |
| Phase 34 P02 | 25min | 5 tasks | 82 files |
| Phase 34 P06 | 40min | 5 tasks | 25 files |
| Phase 33 P01 | 22 min | 4 tasks | 19 files |
| Phase 33 P07 | 25min | 4 tasks | 57 files |
| Phase 33 P02 | 60 min | 4 tasks | 63 files |
| Phase 33 P03 | 43min | 4 tasks | 78 files |
| Phase 33 P08 | 27min | 3 tasks | 68 files |
| Phase 33 P04 | 30min | 3 tasks | 38 files |
| Phase 33 P05 | 70min | 3 tasks | 61 files |
| Phase 33 P09 | 51min | 4 tasks | 88 files |
| Phase 33 P06 | 105min | 4 tasks | 45 files |
| Phase 33 P10 | 75min | 4 tasks | 65 files |
| Phase 33 P11 | 75min | 4 tasks | 72 files |
| Phase 33 P12 | 50min | 3 tasks | 12 files |
| Phase 33 P13 | 105min | 4 tasks | 6 files |
| Phase 33 P16 | 19min | 4 tasks | 41 files |
| Phase 33 P15 | 2h15m | 6 tasks | 70 files |
| Phase 35 P01 | 55 min | 5 tasks | 30 files |
| Phase 35 P02 | 77 | 4 tasks | 66 files |
| Phase 35 P03 | 22min | 6 tasks | 47 files |
| Phase 35 P04 | 90 | 4 tasks | 40 files |
| Phase 35 P05 | 28 min | 3 tasks | 29 files |
| Phase 35 P06 | 33 min | 3 tasks | 34 files |
| Phase 35 P07 | 49 min | 3 tasks | 11 files |
| Phase 35 P08 | 24 min | 3 tasks | 22 files |
| Phase 35 P09 | 31min | 3 tasks | 6 files |
## Accumulated Context
@@ -317,6 +363,11 @@ Progress: [████████░░] 82%
- Phase 32 added: SEO foundation: per-record and global SEO, structured data per page type, sitemap boost and HTML sitemap, pagination, redirects, robots.txt, canonical, meta robots, social tags, headings, hreflang, noindex policy, SSR for headless frontends
- Phase 32 edited: narrowed to framework seams and sm-seo-plugin core (split decided 2026-10-25)
- Phase 33 added: SEO output, audit and content; large phase, lean-planning exception
- Phase 32.1 inserted after Phase 32: MCP OAuth for plugin apps: declared scopes, MCP subject on context, per-client MCP consent (requested by a consuming app's agent-access work) (URGENT)
- Phase 34 added: Plugin marketplace: summercms.io/marketplace, summer plugin:install (registry ID or git URL), read-only admin Plugins screen
- Phase 35 added: Mail templates and layouts editor: DB overrides of plugin-registered mail, editable seeded layouts, images; integer phase so follow-ups land as 35.x
- Phase 31.1 inserted after Phase 31: Phase 31 split at planning (2026-11-13): messaging routes of the WavePath community corpus
- Phase 31.2 inserted after Phase 31: Phase 31 split at planning (2026-11-13): satellites, zero-pending gate (31 D-15) and security review
### Decisions
@@ -954,6 +1005,134 @@ Recent decisions affecting current work:
- [Phase 19.7]: Once the user confirms all in-flight msd-quick tasks are finished: release the framework as the next v0.4.x patch (carrying the quick patches and 19.7 work so far) and tag the held user-plugin fixes; plugins may be tagged mid-phase. Framework v0.5.0 stays reserved for full MCP usability at phase 19.7 completion — User decision 2026-10-23: plugins can be tagged now, framework 0.5 means the MCP phase is finished; wait for the user's word that the last quick agent is done
- [Phase 19.7]: 19.7-02: pier serves 2025-11-25 clients through its own session router over StreamableServerTransport (Redis-shared sessions, D-25) and 2026-07-28 clients through the SDK stateless handler; plan 02 closed without a tag, pier ships opt-in in v0.4.4 (summercms_mcp tag plus mcp.enabled, default off)
- [Phase 19.7]: Released framework v0.4.4 (e2759d6, changelog id 39) and sm-user-plugin v0.1.9 (3828a65; requires v0.4.3); sm-demo-app bumped to user v0.1.9 locally (a25444e, unpushed). Other apps not bumped yet — User go-ahead 2026-10-23 after all quick tasks finished; all release gates green at e2759d6
- [Phase 19.6]: 19.6-01: sm-user-plugin seams built on v0.1.11 (origin/master 50da92c), not v0.1.5; plan 04's additive check uses base 50da92c
- [Phase 19.6]: 19.6-01: the D-07 password-change hook is the existing classes.AccessRevokedEvent (fired in-transaction by reset, change and admin set) with the new (*AccessRevokedEvent).PasswordChanged(); no separate PasswordChangedEvent. sm-mfa-plugin (plan 02) listens to AccessRevokedEvent
- [Phase 19.6]: 19.6-01: device table migration ID is 202610260001_create_device_auth_sessions (after 202610220001 backend links); golem15.user.frontend_url is reused, new keys golem15.user.device_auth.auth_url and .ttl_minutes
- [Phase 19.6]: 19.6-02: sm-mfa-plugin listens on AccessRevokedEvent with PasswordChanged() for D-07 and deletes trusted devices in the password write's transaction
- [Phase 19.6]: 19.6-02: failure cap ignores the caller's in-flight attempt (FailureCapReached inFlight), TOTP step acceptance is a guarded UPDATE in the completion transaction
- [Phase 19.6]: 19.6-02: sm-mfa-plugin migrations 202610220001..05; 202610220006 reserved for plan 03 WebAuthn credentials
- [Phase 19.6]: 19.6-03: sm-demo-app mounts golem15.mfa v0.1.0 (optional, totp and email, social sign-ins unchallenged, no webauthn on the demo); the private sm-mfa-plugin repo means the demo's module-mode release build needs git.golem15.com credentials or a public repo (deferred, user decides)
- [Phase 19.6]: An empty mfa settings list falls back to the configuration (sm-mfa-plugin 71d8f27, released as v0.1.1)
- [Phase 19.6]: Finding F-1 (activate-by-code skips the second factor when require_activation is off) deferred by the user; todo 2026-10-26-activate-by-code-second-factor
- [Phase 32]: D-91 Go shape is the yaml-document form: AdminFormExtension.Fields (AdminFS path) or FieldsYAML (bytes built at boot) carries a fields.yaml-format document with before:/after:/zone: and a tabs: list; pact.AdminFormTab/AdminFormField are not published
- [Phase 32]: Form extension Hide is static for every administrator; Permissions/Visible gate the extension's own fields on schema, show and save
- [Phase 32]: Form extension Save runs after the owner's FormAfter* hooks in the save transaction on every create/update of a visible extension; Load runs on show and in the save response
- [Phase 32]: 32-02: D-92/D-93 Go shapes adopted as planned (P-07 to P-10, incl. optional Match/MatchPath)
- [Phase 32]: 32-02: RecordChange.Locale empty = record's own row; no-op saves fire with empty Changes; reorder fires per moved node
- [Phase 32]: 32-02: signpost MatchPath = first exact match in registration order, else first inexact; Records without func = empty page
- [Phase 32]: 32-02: journal-tag with golem15.journal.tag_pages false resolves to nothing, empty URLs, never matches
- [Phase 32]: 32-04: redirect writes go through one service path (SaveRedirect, AddressChanged, ResolveNotFound) with a save-time loop simulation; resolve is the one-hop redirect decision (normalisation, redirects, strict URLs, then SEO)
- [Phase 32]: 32-04: the robots.txt editor, tester and AI bot switches are fields of the plugin's own form extension on golem15.seo.robots, because an owner-form widget may fill built-in scalar fields only
- [Phase 32]: SEO management API: every admin operation is an MCP tool on a /_seo/api/v1 route with golem15.seo.manage; AdminOperations + parity test guard drift
- [Phase 32]: Batches run in one transaction with per-change savepoints; dry run rolls back, a refused change refuses the whole batch
- [Phase 32]: Undo restores through the service with undo_stale/undo_loop/undo_gone guards; an undo is itself a revision
- [Phase 32]: Import apply token: gzip file + fingerprint signed with HMAC-SHA256 under an app.key-derived key; apply re-runs the preview (transfer.stale)
- [Phase 32]: Demo mount waits for the plugin tag: 32-05-demo-mount.patch carries the mount and the two demo SEO tests for plan 32-06
- [Phase 32]: Released SummerCMS v0.5.1, sm-journal-plugin v0.2.5 and sm-seo-plugin v0.1.0 (pushed); sm-demo-app mounts golem15.seo v0.1.0 (pushed, not deployed)
- [Phase 32]: check-phase32 additive stage compares with the newest tag not containing HEAD, so a post-release run compares with the previous release
- [Phase 32.1]: Empty MCP Options.ScopesSupported resolves to read, write, ai, offline_access, backend; a non-empty list, including DefaultOptions, is used as given
- [Phase 32.1]: Advertised scopes are pact.MCPAdvertisedScopes, not a new method on pact.MCPTokenVerifier
- [Phase 32.1]: Stateless tool calls set callInfo.stateless so MCPCall.SessionID stays empty
- [Phase 32.1]: Implies tests live in the sm-user-plugin root package so go test . runs them
- [Phase 32.1]: OAuth Implies tests load a principal from an in-memory SQL driver so go test -short does not skip
- [Phase 32.1]: 32.1-03 backfill is write-noop-rollback: live MCP grants get a consent row, and Rollback returns nil so a down migration does not delete consents created later.
- [Phase 32.1]: vue-oauth-layer /connect locks read in the UI, omits scopes when consent is already stored, and refetches on 409 backend_link_changed. The new repo is on main with no remote and no tag.
- [Phase 34]: kiosk module: plugin.yaml format, registry v1 wire types and version rules exist once in Go; Task 1 answered as-planned (P34-01..P34-04, v0.6.0 framework minimum)
- [Phase 34]: kiosk.ReadIdentity resolves constant plugin IDs statically (go/parser + go list -m), shared with plugin:add
- [Phase 34]: summer build bakes PluginInfo and FrameworkVersion into plugins.gen.go; generated main calls party.Describe before Activate; metadata failures warn and fall back to IDs
- [Phase 34]: 34-03: the registry API encodes only kiosk wire types; ingest-now and admin live in the site plugin golem15.summercms
- [Phase 34]: 34-03: registry token scope declares GET, HEAD and POST (the framework requires GET in every scope)
- [Phase 34]: 34-03: sm-summercmsio-app go.mod requires summercms v0.6.0 with the site plugin; release needs the v0.6.0 tag and a main.go/plugins.gen.go regeneration
- [Phase 34]: 34-03: marketplace categories content, users, commerce, communication, seo, tools are a contract between the site plugin and the marketplace pages
- [Phase 34]: plugin:install picks the newest release the effective framework allows and never moves the framework; plugin:update applies what resolves and reports the rest
- [Phase 34]: go.work overrides for submodule plugins: app replace target, versioned replace for workspace modules (Go refuses whole-path replaces of them), else a version pin that follows the app's require
- [Phase 34]: 34-05: the Plugins settings entry is added by Registry.Metadata only when backend.view_plugins is declared, the code plugins is free and the principal is allowed (SettingsEntry.Path opens /system/plugins)
- [Phase 34]: 34-05: cabana builds the registry catalog in Activate; registry calls run detached from the request with a 4 s timeout, 4 concurrent lookups, cache 5/15/1 min, and failures are a payload status, never a non-200
- [Phase 34]: 34-05: marketplace entries are limited to plugin-ID-shaped IDs and https icons because the ID ends up in a copied shell command
- [Phase 34]: 34-02 Task 4 answered defer: no app submodule pointer bumps in phase 34; 32 pending gitlinks (5 apps) and the chat/chatbots/chatchannels rebase blockers go to the 34-06 release ledger
- [Phase 34]: 34-02: research F8 applied to chatbots, chatchannels and chatvideo (sm-chat-plugin v0.0.0 -> v0.1.3, local replace kept)
- [Phase 34]: Release: every plugin with a 34-02 plugin.yaml plus sm-summercmsio-plugin gets the next patch tag (v0.1.0 if untagged); no /changelog/plugins posts, the v0.6.0 post and tag message list the bumps
- [Phase 34]: check-phase34.sh skips sm-user-plugin TestRegisterCORSPath via PHASE34_PLUGIN_SKIP (pre-existing, needs an app around it)
- [Phase 33]: 33-01 Task 1: P33-01 descriptor fields and P33-02 FormFieldType.RequestOptions adopted as planned (no renames)
- [Phase 33]: 33-01 Task 1: WR-02 accepted, pact.RecordSaved.Locale stays the request locale's primary tag (released in v0.5.2)
- [Phase 33]: 33-01 Task 1: Phase 33 delivers SummerCMS v0.6.1 (patch, additive); additive and marker stages compare with v0.6.0; plan mentions of v0.5.1/v0.5.2 mean v0.6.0/v0.6.1
- [Phase 33]: 33-07 Task 1 (Jakub 2026-11-04): the shared layer is vue-seo-layer, extended in place from v0.1.1 (no tea repo creation in 33-14; next layer tag v0.2.0)
- [Phase 33]: 33-07: seo.cms is an alias of public.seo.enabled; v0.1.1 config keys and behaviour preserved
- [Phase 33]: 33-07: root-file proxies and the root_files rule apply only after a v0.2.0 site answer; older or unreachable backends keep v0.1.1 behaviour
- [Phase 33]: 33-02: Journal H1 setting default on; EffectiveH1ToH2 = settings row, else golem15.journal.content_h1_to_h2, else true; conversion on every Journal rich-text write path (admin, API/MCP, markdown, import, category pillar text)
- [Phase 33]: 33-02: images/alt defaults dry_run false, fix-headings dry_run true; editor schema keeps H5/H6 while the toolbar offers H2-H4 (or H1-H4)
- [Phase 33]: 33-02: MediaFileName slugs both the editor upload and POST /media/upload (D-85); response shape unchanged
- [Phase 33]: 33-03 Task 1 answered as-proposed (Jakub 2026-11-04): /sitemap.xml index, /sitemap-<slug>-<n>.xml via /_sitemap/files/{file}, XSL removed, one settings singleton, definitions table kept unread
- [Phase 33]: 33-03: sitemap Filter/Listing seam lives in git.golem15.com/golem15/sm-sitemap-plugin/contract (no init); SEO implements contract.Filter, sitemap publishes classes.Listing as contract.Listing
- [Phase 33]: 33-03: sitemap settings validation runs in the controller FormBeforeUpdate (cabana turns BeforeValidate errors into 500)
- [Phase 33]: 33-03: additional address lastmod is a YYYY-MM-DD text field until cabana repeaters accept a datepicker (deferred)
- [Phase 33]: 33-08: the vue-seo-layer build guard runs when pages are resolved (nitro:config fires first); production build and generate fail, nuxt dev and prepare only warn
- [Phase 33]: 33-08: vue-seo-layer app/utils helpers are seo-prefixed (seoPaginationWindow, seoPageHref) because vue-journal-layer auto-imports its own paginationWindow
- [Phase 33]: 33-08: HTML sitemap pages answer 404 unless the CMS site answer has the HTML sitemap on for the locale, 503 with the backend unreachable; an app page at the same path wins
- [Phase 33]: 33-04: the HTML sitemap API answers the contract vue-seo-layer 33-08 reads (groups by file slug: key, slug, title, total, more, entries with children; group page: group, title, page, pages, entries)
- [Phase 33]: 33-04: the HTML sitemap address per locale is a JSONB map (html_paths) edited through the plugin's form extension, not the translation writer
- [Phase 33]: 33-04: News sources is a taglist with custom tags plus a partial listing the values (type:<key>, category:<key>:<id>), checked on save, because taglist options are fixed YAML
- [Phase 33]: 33-04: IndexNow retries 429, 5xx and network errors within five attempts; 400, 403 and 422 are recorded without retry; requests only in production
- [Phase 33]: 33-05: Registry addresses and names per locale live in urls/titles JSONB through the plugin's own form extension (fields url and title), so Match finds a page by any locale's address
- [Phase 33]: 33-05: The registry content type is labelled Site page (pages.type), not Page, to avoid a duplicate SEO settings tab label
- [Phase 33]: 33-05: The sitemap filter decides on production values and also excludes addresses the address rules would 301 (reason redirect)
- [Phase 33]: 33-05: robots.txt names the sitemap plugin's index (ListingSettings.IndexURL) unless golem15.seo.robots_sitemaps is set
- [Phase 33]: 33-05: sm-sitemap-plugin contract.ListingSettings.TypesOff (additive) feeds P1 status.excluded_type
- [Phase 33]: 33-05: Site-cache purge after SEO writes is queued in Service.Record once per transaction (kind seo)
- [Phase 33]: 33-09: vue-journal-layer, vue-menu-layer and vue-faq-layer extend vue-seo-layer through a link dependency during development (33-14 pins the git tag); the journal layer drops @nuxtjs/seo and its sitemap source
- [Phase 33]: 33-09: the post title is h1 while the Journal API reports content_h1_to_h2 on (or absent) and p.journal-post__title while off; journal.postTitleTag overrides; category pillar text follows the category row's setting
- [Phase 33]: 33-09: the deprecated POST /api/__journal__/cache/purge keeps its own helpers: a bare import of vue-seo-layer's .ts library would be externalized by Nitro in git-installed apps
- [Phase 33]: 33-09: Journal related posts opt-in (golem15.journal.related_mode scored, related_count 3-6); scored mode adds previous_in_category/next_in_category; default answer unchanged
- [Phase 33]: 33-09: an app without pages that extends vue-seo-layer sets seo.htmlSitemap false, else the sitemap pages turn the router on
- [Phase 33]: 33-06 Task 4: chromedp approved, pin v0.21.0; gen2brain/webp approved, pin v0.6.4 (Jakub 2026-11-04)
- [Phase 33]: 33-06: every JSON-LD graph carries the full WebSite and publisher nodes
- [Phase 33]: 33-06: site answer home_crumb is {name, url, names} (layer reads name/url; names per locale)
- [Phase 33]: 33-10: chromedp v0.21.0 renders the optional raw-versus-rendered comparison; Chrome's host-resolver-rules list the site hosts first and MAP * ~NOTFOUND last (first matching rule wins)
- [Phase 33]: 33-10: GET /_seo/api/v1/issues reads stored issues (CMS checks refreshed until the first crawl, then the newest crawl's) and defaults to status open
- [Phase 33]: 33-10: crawl issues route to the record type's Tools for content, to seo_ tools for data, else fix code with details.what; no issue has neither
- [Phase 33]: 33-10: the Site audit status filter cannot default to Open (cabana filters have no default); ignored rows are badged, the API defaults to open
- [Phase 33]: 33-11: gen2brain/webp pinned at v0.6.4 in the framework (modules/lagoon/attach/webp only); its fallback is wasm2go-transpiled libwebp, not wazero; importing it makes binaries glibc-dynamic unless built with -tags nodynamic (33-14 decides per app)
- [Phase 33]: 33-11: auto-link locale stored as '' for every locale (not NULL); history subject autolink purges every page (*)
- [Phase 33]: 33-11: E10 internal links omitted for collection and profile kinds and the page registry (Words is a per-record fact)
- [Phase 33]: 33-11: Journal variants carry the original's source_width/source_height on each featured_images[].variants entry; no foreign key to system_files
- [Phase 33]: 33-12: the demo keeps cookie-based Polish (D-13); its /pl/ alternates and sitemap addresses answer 404, so moving to prefix_except_default is a decision for 33-14 before the demo patches are applied
- [Phase 33]: 33-12: demo sitemaps go through Nuxt (vue-seo-layer root files); nginx has no /sitemap*, /_sitemap or /_seo location and check-deploy.sh refuses one
- [Phase 33]: 33-13: grzybyfunkcjonalne.pl deploys after the tags, to production (no separate uat since the 2026-10-31 cutover); en off and the copied Additional addresses removed at the 33-14 release checkpoint
- [Phase 33]: 33-14: the demo moves to prefix_except_default (English at /, Polish at /pl/), reversing D-13
- [Phase 33]: 33-16: vue-seo-layer adds its HTML sitemap pages from a pages:resolved hook registered on ready, after @nuxtjs/i18n has localised the routes (modules:done ran before i18n's handler)
- [Phase 33]: 33-16: the route report drops every noindex entry before cutting routes, so the JSON body stays within the older plugin's 4,113,024 bytes
- [Phase 33]: 33-16: HTML sitemap pages are not registered over an app catch-all unless seo.htmlSitemap.overCatchAll; an app with only app.vue needs no htmlSitemap: false
- [Phase 33]: 33-15: the route report's noindex key replaces the stored noindex set (golem15_seo_noindex_paths) and the SEO sitemap filter leaves those paths out with reason noindex; a changed set asks for a rebuild through contract.Rebuilder
- [Phase 33]: 33-15: Journal descriptors give a locale a URL only when the record has content in it (posts/categories by own translation, tags/authors through a translated published post, default locale always); menu Resolve unchanged
- [Phase 33]: 33-15: a crawl's job owns its terminal status (cancel records cancel_requested_at), finishes on a detached 10-minute context, writes heartbeat_at every minute; RecoverStale ends running rows without a heartbeat for 10 minutes
- [Phase 33]: 33-15: sitemap rebuilds run under pg_advisory_xact_lock(hashtext('golem15.sitemap.rebuild')) around settings, collect and apply; apply never writes a content row's lastmod
- [Phase 33]: 33-15: G2 (journal-tag pattern while tag pages are off) deferred to v0.6.2: signpost.Activate refuses a type without a DefaultPattern starting with /
- [Phase 35]: 35-01 Task 1 answered as-planned: P35-01 schema, P35-02 partial syntax and built-ins, P35-03 sample.* keys, P35-04 layout CSS slot and logoUrl, P35-05 names adopted without changes
- [Phase 35]: 35-01: postcard logs 'override failed, sending the file version' only when the file version then renders; when both fail, the file version's error is returned as before
- [Phase 35]: 35-01: a partial call in a body leaves the token MAILPARTIAL + 32 hex nonce + X<n>X, swapped in one pass after goldmark; raw HTML stays disabled for bodies
- [Phase 35]: 35-01: Editor.Validate refuses a template body whose source holds a script, iframe, object or embed tag, because Markdown would drop it silently at send
- [Phase 35]: 35-01: Branding (compiled CSS and logoUrl) also applies to the file version sent after a failing override; an invalid stored colour keeps mail.brandCss with a warning
- [Phase 35]: 35-01: pact has five row states; cabana keeps only three until 35-02 updates rowStateOrder and docs/backend/lists-and-filters.md
- [Phase 35]: Image list/pick allows either mail permission; upload and Mail images singleton need system.manage_mail_layouts — Planner call for picker split (D-03 / UI-SPEC C4)
- [Phase 35]: Test-send is interactive-only; recipient is always the signed-in administrator email; limit 5/10min via cooler.Attempter — D-16/D-17 and research Pattern 7
- [Phase 35]: GET /mail/images documents AdminMailImagesResponse so meta.canUpload validates under OpenAPI conformance — SuccessMeta cannot carry canUpload; MarketplaceResponse pattern
- [Phase 35]: Task 3 approved all seven CodeMirror pins including @codemirror/view@6.43.15
- [Phase 35]: CodeMirror loads only from codeeditor/editor.ts; meta package and indentWithTab unused
- [Phase 35]: check-phase35 consumers stage runs sibling plugin mail tests read-only against this checkout — D-21 gate must prove core plugins unchanged without writing their trees
- [Phase 35]: D-05 superseded (G-35-1): a mail template is one admin record; locale versions are rows grouped by base_code (migration 202611130001) and opened through a locale switcher (meta.localeVariants); note 2026-11-13-mail-template-locale-groups
- [Phase 35]: postcard resolves a missing <template>-<locale> (two-letter tag, optional subtag, longest registered base) to own customization > base customization > base file; names with files send unchanged
- [Phase 35]: cabana mail locales = translator locales plus TranslationWriter enabled locales; default = writer default else translator locale; templates list one row per template, locale filter removed
- [Phase 35]: 35-06: postcard inlines mail CSS at render with github.com/vanng822/go-premailer v1.38.0 (default options), opt-out via disable_auto_inline_css (layout header key, layouts column, layout form switch); supersedes D-10's inlining claim
- [Phase 35]: 35-06: Branding gains Site name (site_name, Brand.SiteName); empty uses the display name of mail.from; default and system layouts show logo or name in the header and a © year name footer
- [Phase 35]: 35-06: 35-01's default.htm-unchanged gate lifted; default layout is WinterCMS's default layout on new built-in header and footer partials
- [Phase 35]: 35-07: check-phase35.sh consumers run each core plugin through a scratch -modfile (sibling go.sum merged with the framework's, GOWORK=off, GOPROXY=off) and refuse a sibling that is dirty before or after
- [Phase 35]: 35-07: G-35-8 recorded as framework-closed with the plugin part deferred; UAT test 8 re-run scoped to the built-in layouts (default, system) with logo, site name and the button partial
- [Phase 35]: 35-07: Branding site name with a URL scheme stays an open item; TestMailBrandSiteName pins the current behaviour (saved, preview refused)
- [Phase 35]: 35-08: postcard checks URL schemes only in decoded URL-bearing attributes, CSS, comments and meta content (x/net/html tokenizer); text is not a URL, so prose site names no longer stop mail (CR-01)
- [Phase 35]: 35-08: postcard.UnsafeText (new exported API) drops unsafe site names at render with a value-free rate-limited warning and backs the Branding 422 on site_name (mail.brand.site_name_unsafe)
- [Phase 35]: 35-08: an inlined result that fails the safety check is sent un-inlined with the inline:<layout> warning; the footer partial's text argument prints the site name literally
- [Phase 35]: 35-08: cabana settings Put localizes BeforeValidate refusal phrase keys, as controller saves do
- [Phase 35]: 35-09: the mail screens test env reads mail.from from its configuration (default unchanged) so a mutate hook sets the sender
### Pending Todos
@@ -999,13 +1178,11 @@ Recent decisions affecting current work:
- pending: push sm-user-plugin — 12.1-05 Task 3 condition (c) failed (`git ls-remote --tags origin v0.1.3` empty). Push summercms.go master and annotated tag v0.1.3 (local on df5cace) first, then the plugin, then fonoteka.go. Recorded in 12.1-05-SUMMARY.md.
- 16.2-05 open UAT items: re-save HTML post 1 untouched (D-03 evidence vacuous), D-19 category edit check, root vhost install (frame-src), unpublish/delete test post 105
- Phase 19.4: review warnings WR-01..06 are open (19.4-REVIEW-DISPOSITION.md); WR-01 (a replayed code does not revoke rotated refresh tokens) must be fixed before any client enables refresh. Release still pending: tag summercms, bump sm-oauthserver-plugin go.mod to sm-user-plugin v0.1.1 / summercms v0.2.4.
- 19.6-03 Task 6 (1): sm-demo-app plugins/golem15/user carries another session's uncommitted move to v0.1.11; user decision needed before bumping it to v0.1.12
- 19.6-04 Task 5: go-ahead to release sm-mfa-plugin fix 71d8f27 (v0.1.1, demo and bm bumps) and a decision on finding F-1 (activate-by-code without the second factor when require_activation is off)
- 33-02 deferred: lagoon.Validate rejects string/url rule tokens, so the Journal admin settings save answers 500 (pre-existing); framework fix needed for the Headings and links switch in the admin
- 33-14 Task 3 release checkpoint: awaiting Jakub's go-ahead (versions, pushes, posts, deploys)
| 261028-rqb | Admin SPA reload on deploy (todo .planning/todos/pending/2026-10-11-reload-open-apps-when-a-new-version-is-deployed.md, admin half only; site half already shipped in vue-demo-app): boardwalk exposes a build version derived from the embedded dist (header like X-Summer-Build on admin API responses and/or a version endpoint), the admin SPA records the version it booted with and shows a non-blocking reload banner when a newer build is seen (focus/visibility/interval check), plus a reload-once guard on Vite chunk-load errors (vite:preloadError + sessionStorage flag); unit tests; boardwalk README; rebuild admin and commit modules/boardwalk/dist (scripts/check-admin-dist.sh must pass) | 2026-10-28 | c8a22e3 | .planning/quick/261028-rqb-admin-spa-reload-on-deploy-todo-planning-todos-pending-2026 |
| 261028-rqc | Quiet plugin boot logs on console commands like --help, framework side only (todo .planning/todos/pending/2026-10-21-quiet-plugin-boot-logs-on-console-commands.md): help/list/completion style commands must not print plugin Register/Boot Info logs (e.g. raise the default console log level for non-serve introspection commands or defer Boot for them), without hiding logs for serve/worker/migrate; no sm-* plugin edits (plugin-side Info->Debug changes are a separate follow-up); docs for the behaviour | 2026-10-28 | 6c606c6 | .planning/quick/261028-rqc-quiet-plugin-boot-logs-on-console-commands-like-help-framewo |
| 261028-rqd | Console review info findings IN-01..IN-13 and the delegate signal exit code 128+n (todo .planning/todos/pending/2026-10-22-console-review-info-findings.md, review .planning/phases/19.8-console-commands-overhaul/19.8-REVIEW.md); all 14 verified still open on 2026-10-28 in modules/bonfire, modules/diary, cmd/summer, scripts/check-phase19.8.sh; fix each, keep behaviour backward compatible, update docs/console pages and TestDelegateExitCodePassthrough for 128+n | 2026-10-28 | 202d38b | .planning/quick/261028-rqd-console-review-info-findings-in-01-in-13-and-the-delegate-si |
| 261028-rqe | attach.Store writes non-inline types with a non-rendering disposition (todo .planning/todos/pending/2026-10-28-attach-store-public-content-type.md): in modules/lagoon/attach/store.go pass Content-Disposition attachment (blob.WriterOptions) for anything not in an inline-safe raster allow-list (jpeg, png, gif, webp, avif), keep the DB ContentType unchanged, additive and non-breaking; tests; lagoon README and docs/services/storage.md deploy note updated | 2026-10-28 | 4957e5c | .planning/quick/261028-rqe-attach-store-writes-non-inline-types-with-a-non-rendering-di |
| 261028-rqf | Audit-log successful admin action runs with the admin id (todo .planning/todos/pending/admin-action-audit-log.md): in modules/cabana/actions.go runAction log success with admin_id (bouncer.User(ctx).ID), controller, action and kind (toolbar/field), matching the existing bulk/record action log fields; tests | 2026-10-28 | 61d1043 | .planning/quick/261028-rqf-audit-log-successful-admin-action-runs-with-the-admin-id-tod |
| 261028-rqg | Show the administrators holding a role on the Roles screen (todo .planning/todos/pending/roles-screen-holders-list.md, origin .planning/phases/19.6.1-backend-administrators-screen/19.6.1-UAT.md:44): read-only list of holders on the Roles form/preview in modules/cabana backend_roles_admin.go (and admin SPA if needed), superusers hidden from non-superuser editors (D-03), assignment stays on the Administrators form; tests; if admin/ changes, rebuild and commit modules/boardwalk/dist | 2026-10-28 | 653d95a | .planning/quick/261028-rqg-show-the-administrators-holding-a-role-on-the-roles-screen-t |
### Quick Tasks Completed
| # | Description | Date | Commit | Directory |
@@ -1065,9 +1242,36 @@ Recent decisions affecting current work:
| 261022-wah | User plugin opt-in golem15.user.jwt.token_cookie (default off) sets the HttpOnly auth.cookie session cookie on /login, /register and /activate-by-code instead of the body token; a /refresh carried by the auth.cookie cookie rewrites it (sm-user-plugin 846087d, 8bdf2c7, ships v0.5.0; verified) | 2026-10-22 | 846087d, 8bdf2c7 (sm-user-plugin) | [261022-wah-opt-in-httponly-session-cookie-on-user-p](./quick/261022-wah-opt-in-httponly-session-cookie-on-user-p/) |
| 261022-x7a | User plugin golem15.user.password.public_routes (default true): false leaves POST /login, /forgot-password and /reset-password unregistered so they 404 like unknown paths; /register and the rest unchanged (sm-user-plugin 3828a65, ships v0.5.0; verified) | 2026-10-22 | e5dd457 | [261022-x7a-user-plugin-golem15-user-password-public](./quick/261022-x7a-user-plugin-golem15-user-password-public/) |
| 55 | fix(cabana): backend subject events reach pier as *pact.MCPSubjectChanged after commit | 2026-10-23 | 7c43820 | — |
| 261028-fsq | sm-user-plugin MCPDispatch credential carries the personal token id (plugin a1b78b8) | 2026-10-28 | 7c4dbb1 | [261028-fsq-sm-user-plugin-mcpdispatch-credential-ca](./quick/261028-fsq-sm-user-plugin-mcpdispatch-credential-ca/) |
| 261028-pq8 | Fix the four internal/build scaffolder todos (make:plugin vendor path, make:admin-controller output, scaffold header and make:command deps, same-second migration order) | 2026-10-28 | 8bc18c9 | [261028-pq8-fix-the-four-internal-build-scaffolder-t](./quick/261028-pq8-fix-the-four-internal-build-scaffolder-t/) |
| 261028-r16 | Fix the two lagoon todos: stored-upload extension from sniffed MIME (tests + deploy note) and the lagoon README after-commit callback order | 2026-10-28 | 36092f5 | [261028-r16-fix-the-two-lagoon-todos-derive-stored-u](./quick/261028-r16-fix-the-two-lagoon-todos-derive-stored-u/) |
| fast | ensureToolchain keeps an existing toolchain line instead of adding a second one | 2026-10-28 | 6ea2cb7 | — |
| 261028-rqb | Admin SPA reload on deploy (todo .planning/todos/pending/2026-10-11-reload-open-apps-when-a-new-version-is-deployed.md, admin half only; site half already shipped in vue-demo-app): boardwalk exposes a build version derived from the embedded dist (header like X-Summer-Build on admin API responses and/or a version endpoint), the admin SPA records the version it booted with and shows a non-blocking reload banner when a newer build is seen (focus/visibility/interval check), plus a reload-once guard on Vite chunk-load errors (vite:preloadError + sessionStorage flag); unit tests; boardwalk README; rebuild admin and commit modules/boardwalk/dist (scripts/check-admin-dist.sh must pass) | 2026-10-28 | c8a22e3 | .planning/quick/261028-rqb-admin-spa-reload-on-deploy-todo-planning-todos-pending-2026 |
| 261028-rqc | Quiet plugin boot logs on console commands like --help, framework side only (todo .planning/todos/pending/2026-10-21-quiet-plugin-boot-logs-on-console-commands.md): help/list/completion style commands must not print plugin Register/Boot Info logs (e.g. raise the default console log level for non-serve introspection commands or defer Boot for them), without hiding logs for serve/worker/migrate; no sm-* plugin edits (plugin-side Info->Debug changes are a separate follow-up); docs for the behaviour | 2026-10-28 | 6c606c6 | .planning/quick/261028-rqc-quiet-plugin-boot-logs-on-console-commands-like-help-framewo |
| 261028-rqd | Console review info findings IN-01..IN-13 and the delegate signal exit code 128+n (todo .planning/todos/pending/2026-10-22-console-review-info-findings.md, review .planning/phases/19.8-console-commands-overhaul/19.8-REVIEW.md); all 14 verified still open on 2026-10-28 in modules/bonfire, modules/diary, cmd/summer, scripts/check-phase19.8.sh; fix each, keep behaviour backward compatible, update docs/console pages and TestDelegateExitCodePassthrough for 128+n | 2026-10-28 | 202d38b | .planning/quick/261028-rqd-console-review-info-findings-in-01-in-13-and-the-delegate-si |
| 261028-rqe | attach.Store writes non-inline types with a non-rendering disposition (todo .planning/todos/pending/2026-10-28-attach-store-public-content-type.md): in modules/lagoon/attach/store.go pass Content-Disposition attachment (blob.WriterOptions) for anything not in an inline-safe raster allow-list (jpeg, png, gif, webp, avif), keep the DB ContentType unchanged, additive and non-breaking; tests; lagoon README and docs/services/storage.md deploy note updated | 2026-10-28 | 4957e5c | .planning/quick/261028-rqe-attach-store-writes-non-inline-types-with-a-non-rendering-di |
| 261028-rqf | Audit-log successful admin action runs with the admin id (todo .planning/todos/pending/admin-action-audit-log.md): in modules/cabana/actions.go runAction log success with admin_id (bouncer.User(ctx).ID), controller, action and kind (toolbar/field), matching the existing bulk/record action log fields; tests | 2026-10-28 | 61d1043 | .planning/quick/261028-rqf-audit-log-successful-admin-action-runs-with-the-admin-id-tod |
| 261028-rqg | Show the administrators holding a role on the Roles screen (todo .planning/todos/pending/roles-screen-holders-list.md, origin .planning/phases/19.6.1-backend-administrators-screen/19.6.1-UAT.md:44): read-only list of holders on the Roles form/preview in modules/cabana backend_roles_admin.go (and admin SPA if needed), superusers hidden from non-superuser editors (D-03), assignment stays on the Administrators form; tests; if admin/ changes, rebuild and commit modules/boardwalk/dist | 2026-10-28 | 653d95a | .planning/quick/261028-rqg-show-the-administrators-holding-a-role-on-the-roles-screen-t |
| 261028-wqu | summercms.io Changelog dropdown (Framework/Plugins): /changelog = framework category, /changelog/plugins = plugins category; changelog-post.py categories + backfill (sm-summercmsio-app 29dd1b3) | 2026-10-28 | bac8e7e | [261028-wqu-summercms-io-changelog-dropdown-framewor](./quick/261028-wqu-summercms-io-changelog-dropdown-framewor/) |
| 261029-1r3 | Derive the summercms.io landing version from go.mod | 2026-10-29 | app b688a80 | [261029-1r3-derive-the-summercms-io-landing-version-](./quick/261029-1r3-derive-the-summercms-io-landing-version-/) |
| 261029-d9j | User plugin mail locale: normalize Accept-Language, configurable fallback, Polish subjects | 2026-10-29 | user 6bf219f | [261029-d9j-user-plugin-mail-locale-normalize-accept](./quick/261029-d9j-user-plugin-mail-locale-normalize-accept/) |
| 261105-din | Fix 32.1 CR-01: serialize MCP consent allow with revoke under LockUserGrants (sm-oauthserver-plugin 21f5985) | 2026-11-05 | 8c6b317 | [261105-din-fix-32-1-cr-01-serialize-mcp-consent-all](./quick/261105-din-fix-32-1-cr-01-serialize-mcp-consent-all/) |
| 261105-eab | Fix OIDC grant flows racing revoke: resume, refresh, exchange under LockUserGrants (sm-oauthserver-plugin 7b9899f) | 2026-11-05 | f925527 | [261105-eab-fix-oidc-consent-decide-race-with-revoke](./quick/261105-eab-fix-oidc-consent-decide-race-with-revoke/) |
| 261105-oc5 | 2FA hardening (todos 2026-10-26-activate-by-code-second-factor.md and 2026-10-26-mfa-factor-changes-need-reauth.md): sm-user-plugin ActivateByCode runs CheckLoginGates after VerifyActivationCode (finding F-1); sm-mfa-plugin requires password confirmation on factor-changing routes (WR-05) and vue-demo-app security.vue asks for the password | 2026-11-05 | b179e6b | .planning/quick/261105-oc5-2fa-hardening |
| 261105-oc6 | Chatchannels pin policy (todo chatchannels-pin-policy.md): sm-chatchannels-plugin PinMessage/UnpinMessage require CanManageContext or an optional contracts.PinPolicy, and verify the message belongs to the channel conversation; sm-demo-app answers the policy from its moderator group | 2026-11-05 | a042536 | .planning/quick/261105-oc6-chatchannels-pin-policy |
| 261105-oc7 | Chatvideo hardening (todos chatvideo-live-membership.md, chatvideo-dm-only-host-hook.md, chatvideo-incoming-handle-leak.md): sm-chatvideo-plugin honours LiveMembership and removes banned participants from the LiveKit room, adds an optional CanStartCall host hook for a DM-only rule; vue-chatvideo-layer useIncomingCalls closes stale session handles | 2026-11-05 | f996156 | .planning/quick/261105-oc7-chatvideo-hardening |
| 261105-oc8 | lagoon/attach StaticHandler and StaticHandlerPublic send the stored Content-Disposition and X-Content-Type-Options nosniff (todo 2026-10-28-attach-static-handler-disposition.md) | 2026-11-05 | 27c98bf | .planning/quick/261105-oc8-lagoon-attach-statichandler-and-statichandlerpublic-send-the |
| 261105-oc9 | sm-demo-app hardening (todos check-local-jwt-out-of-argv.md, demo-chat-members-read-only.md, demo-nginx-livekit-rtc-only.md, demo-seed-moderation-lists-once.md, demo-vapid-runbook-pipefail.md) | 2026-11-05 | 9595606 | .planning/quick/261105-oc9-sm-demo-app-hardening |
| 261106-d20 | fonoteka.go uploads named after the sniffed type and stored with attach.UploadWriterOptions; framework exports attach.UploadWriterOptions (todos 2026-10-28-fonoteka-uploads-use-disk-extension.md, 2026-11-06-blob-writers-set-content-disposition.md) | 2026-11-06 | 903859a | [261106-d20-fix-stored-xss-in-fonoteka-go-uploads-an](./quick/261106-d20-fix-stored-xss-in-fonoteka-go-uploads-an/) |
| 261106-dv0 | shared plugins log boot details at Debug: paymentgateway operators registered, paymentgatewaysubscriptions registries collected through diary.For (todo 2026-10-28-plugins-log-boot-details-at-debug.md) | 2026-11-06 | 8a88b86, 1df6a26 | [261106-dv0-plugin-boot-logs-at-debug](./quick/261106-dv0-plugin-boot-logs-at-debug/) |
| 261106-e5v | purge token rename leftovers: grzybyfunkcjonalne check-deploy refuses NUXT_SITE_* keys, journal/menu/faq READMEs name NUXT_CACHE_PURGE_TOKEN (todo 2026-10-20-rename-site-cache-purge-env-in-consumers.md) | 2026-11-06 | 4e2cf0c, f61c90a, 128a33d, a53511b | [261106-e5v-purge-token-rename-leftovers](./quick/261106-e5v-purge-token-rename-leftovers/) |
| 261106-jhk | wristband MCP authorize drops OIDC identity scopes (openid, profile, email) so the ChatGPT connector can connect | 2026-11-06 | aba678b | [261106-jhk-wristband-mcp-authorize-ignores-oidc-ide](./quick/261106-jhk-wristband-mcp-authorize-ignores-oidc-ide/) |
| 261106-kt1 | pier MCP 401 challenge names only resource_metadata, so clients request the advertised scopes (write included) | 2026-11-06 | 609caa4 | [261106-kt1-pier-mcp-401-challenge-drops-the-fixed-r](./quick/261106-kt1-pier-mcp-401-challenge-drops-the-fixed-r/) |
| 261106-kt2 | deferred:purge, migrate* and queue:clear reuse the app's published database, so the in-server scheduler no longer fails with duplicate provider for *sql.DB | 2026-11-06 | 99abe88 | [261106-kt2-lagoon-deferred-purge-fails-in-the-sched](./quick/261106-kt2-lagoon-deferred-purge-fails-in-the-sched/) |
| 261108-pe4 | beachcomber highlights and field projection: Query.IncludeFields/ExcludeFields/Highlight, SearchResult.Hits (plain-text segments), HighlightSearcher + SupportsHighlights; Typesense parses v1 highlights | 2026-11-08 | 7819c67 | [261108-pe4-beachcomber-highlights-and-field-project](./quick/261108-pe4-beachcomber-highlights-and-field-project/) |
| 261114-p5m | Fix CR-02 residual: quoted end tags in raw-text elements bypass the postcard scheme check | 2026-11-14 | f1f284a0 | [261114-p5m-fix-cr-02-residual-quoted-end-tags-in-ra](./quick/261114-p5m-fix-cr-02-residual-quoted-end-tags-in-ra/) |
| 261114-p5n | Style the user and paymentgateway plugin mail layouts like the postcard default layout | 2026-11-14 | 4ef3aa1f | [261114-p5n-style-the-user-and-paymentgateway-plugin](./quick/261114-p5n-style-the-user-and-paymentgateway-plugin/) |
| 261115-cha | Let a mail template use another plugin's layout by full code (G-35-9) | 2026-11-15 | b8487b02 | [261115-cha-let-a-mail-template-use-another-plugin-s](./quick/261115-cha-let-a-mail-template-use-another-plugin-s/) |
## Deferred Items
@@ -1079,6 +1283,6 @@ Items acknowledged and carried forward from previous milestone close:
## Session Continuity
Last session: 2026-10-24T14:47:37.432Z
Stopped at: Phase 32 context gathered
Resume file: .planning/phases/32-seo-foundation/32-CONTEXT.md
Last session: 2026-11-14T15:08:11.773Z
Stopped at: Phase 35 complete, ready to plan Phase 30
Resume file: None

View File

@@ -0,0 +1,146 @@
---
status: diagnosed
trigger: "UAT gap G-35-8: logo doesn't appear, only kind of proper layout is System layout (logo doesn't show, Aktywuj konto on activate email doesn't seem to be a button, totally unstyled), other layouts sucks, I expect beautiful and working out of box layouts after this phase."
created: 2026-11-13T00:00:00Z
updated: 2026-11-13T16:05:00Z
goal: find_root_cause_only
---
## Current Focus
bug_class: Bohrbug (deterministic; reproduced outside the SPA with a scratch render, every run)
hypothesis: CONFIRMED — the Phase 35 plumbing works (logoUrl var, brand CSS, button partial), but no shipped content consumes it: no layout prints {{ .logoUrl }}, plugin templates use plain Markdown links instead of the button partial, and the default + plugin layouts are bare stubs without Winter's wrapper/header/card/footer structure.
test: scratch render of golem15.user::mail.activate across user/system/default/minimal layouts with a Brand carrying LogoURL
expecting: logo URL count 0 and `class="button` count 0 in all layouts (observed); button partial call renders a styled button (observed)
next_action: return ROOT CAUSE FOUND (diagnose-only mode)
reasoning_checkpoint:
hypothesis: "Logo/buttons/structure are missing because the shipped layout and template files never reference logoUrl, the button partial, or the wrapper/header/footer classes the brand CSS styles — not because of preview, URL or CSS-delivery failures."
confirming_evidence:
- "grep: logoUrl appears in no .htm layout in postcard, sm-user-plugin or sm-paymentgateway-plugin; only in docs and test-only overrides"
- "scratch render: 0 logo occurrences, 0 class=button in all 4 layouts; brand CSS with saved colour present"
- "same render with {{ partial \"button\" ... }} produces class=\"button button-primary\""
- "plugin layouts are `<div class=\"layout-user|layout-paymentgateway\">{{ .Content }}</div>` (stubs from phases 07-03/18-04); default.htm is `<div class=\"content-body\">` and 35-01 forbade touching it"
falsification_test: "Adding `{{ if .logoUrl }}<img src=\"{{ .logoUrl }}\">{{ end }}` to a layout and rendering with the same Brand must show the logo URL; if it did not, the wiring would be at fault. brand_smoke_test 'logo' subtest already shows it does."
fix_rationale: "Ship finished layouts (Winter default port with header/logo + footer; logo in system) and switch plugin CTAs to the button partial — addresses missing consumers, which is the root cause; plumbing needs no change."
blind_spots: "Did not drive the actual SPA preview with an admin session (used the same postcard render path directly); did not test real mail clients for <style>-only CSS (inlining gap is from Winter parity + known client behaviour, not observed here)."
candidate_causes:
- "code (framework): built-in layouts lack logo slot/header/footer; default layout bare; no CSS inliner"
- "code (plugins): templates use Markdown links; layouts are stubs"
- "config/environment: logo URL base / public file / CSP / sandbox — eliminated"
- "data: demo DB has customized user layout + activate overrides (masks file fixes during verification, not a cause)"
and_gate: "yes — an out-of-box finished mail needs (a) a layout with structure and logo slot AND (b) templates calling the button partial AND (c) brand CSS for those classes (present); real-client rendering additionally needs (d) CSS inlining. Each missing piece alone produces part of the symptom."
## Symptoms
expected: Mail preview renders the template inside a polished, working layout out of the box: branding logo shows, CTA links (e.g. "Aktywuj konto" in user activate) render as styled buttons, every shipped layout (system and plugin layouts like user, paymentgateway) looks finished.
actual: Logo does not appear (system and plugin layouts). "Aktywuj konto" is a plain link, not a button. Only the System layout looks somewhat proper; plugin layouts (user, paymentgateway) are unstyled.
errors: none reported
reproduction: sm-demo-app at http://127.0.0.1:8097/smbackend -> mail templates editor -> preview golem15.user::mail.activate (and paymentgateway templates); branding colours + logo saved beforehand.
started: Phase 35 UAT (first time this feature exists)
extra: test-send text body "Cześć **[Name]**.\n\n[Aktywuj konto]([Link])\n\nKod: [Code]" — template body is markdown with a link.
## Eliminated
- hypothesis: sandboxed preview iframe (sandbox="") or the admin CSP blocks the logo image / inline styles
evidence: sandbox="" does not block images or <style>; admin CSP has no img-src/style-src/default-src; no COEP/CORP; brand CSS demonstrably present in output. The logo <img> is simply absent from the rendered HTML.
timestamp: 2026-11-13T15:40Z
- hypothesis: logo URL is not resolved (file not public, no public_url/app.url, wrong partition key)
evidence: brand row has logo_file_id 556, is_public; computed URL returns 200 image/png; no "mail branding logo" warning in go.log
timestamp: 2026-11-13T15:42Z
- hypothesis: logoUrl is not passed to layouts during preview (preview data wiring)
evidence: Editor.render -> m.options(ov.Brand) sets opts.logoURL; renderParts passes "logoUrl" to text and HTML wrappers (templates.go:620,630); test overrides that print it get the URL (brand_smoke_test)
timestamp: 2026-11-13T15:43Z
- hypothesis: plugin layouts don't receive the brand CSS
evidence: user.htm and paymentgateway.htm both contain <style>{{ .brandCss }}{{ .css }}</style>; repro output contains the compiled brand CSS with the saved #2974d6
timestamp: 2026-11-13T15:45Z
- hypothesis: postcard cannot render buttons (no button partial / unstyled)
evidence: built-in button partial renders class="button button-primary" and brand.css.tmpl styles .button-primary/.positive/.negative with brand colours
timestamp: 2026-11-13T15:47Z
## Evidence
- timestamp: 2026-11-13T15:30Z
checked: knowledge base (.planning/debug/knowledge-base.md) and resolved sessions
found: no knowledge-base.md; resolved sessions unrelated (avatar bucket, category content, etc.)
implication: no known-pattern candidate
- timestamp: 2026-11-13T15:32Z
checked: modules/postcard/assets/{default,system,minimal}.htm
found: none of the three built-in layouts references {{ .logoUrl }}. default.htm body is only `<div class="content-body">{{ .Content }}</div>` (no wrapper table, no header, no footer, class content-body has no CSS rule in brand.css.tmpl). system.htm has the Winter wrapper/content/body/inner-body/content-cell tables + subcopy partial but no header row/logo and no footer row. minimal.htm is bare body.
implication: logo can never appear in any built-in layout; default layout has no card/header/footer structure so it looks unstyled
- timestamp: 2026-11-13T15:33Z
checked: grep logoUrl across postcard, docs, admin, sm-user-plugin, sm-paymentgateway-plugin
found: logoUrl only exists as render var (templates.go:620,630), in README/docs examples (`{{ if .logoUrl }}<img ...>{{ end }}`) and in test-only layout overrides (brand_smoke_test.go:220,329). No shipped .htm layout uses it.
implication: the logo plumbing (store.go -> Brand.LogoURL -> opts.logoURL -> layout var) is wired, but the consumer (a layout that prints it) was never shipped. Tests prove the variable reaches a layout only via test overrides.
- timestamp: 2026-11-13T15:35Z
checked: ../sm-demo-app/plugins/golem15/user/views/mail/layouts/user.htm and paymentgateway/views/mail/layouts/paymentgateway.htm (identical to ../sm-user-plugin, ../sm-paymentgateway-plugin)
found: both are bare: `<style>{{ .brandCss }}{{ .css }}</style>` + `<div class="layout-user">{{ .Content }}</div>` / `<div class="layout-paymentgateway">`. No wrapper/inner-body tables, no header/logo, no footer. Classes layout-user / layout-paymentgateway have no CSS rule anywhere. user.htm text wrap is `-- {{ .Content }} --`.
implication: plugin layouts only get the brand CSS element rules (body bg #f5f8fa, p/a/h colours) — content sits flush on the grey page background with no white card, header or footer: "unstyled"
- timestamp: 2026-11-13T15:36Z
checked: user activate.htm / activate-en.htm / restore / invite templates
found: CTA is plain Markdown link `[Aktywuj konto]({{ .Link }})`; no `{{ partial "button" ... }}` call. layout = "user".
implication: goldmark renders a plain <a>; brand CSS styles <a> only with link colour; nothing makes it a button
- timestamp: 2026-11-13T15:40Z
checked: admin/src/components/form/fields/MailPreviewField.vue + modules/boardwalk/boardwalk.go SetSecurityHeaders
found: preview iframe is `sandbox=""` + srcdoc. Admin CSP = "frame-ancestors 'none'; base-uri 'none'; object-src 'none'; script-src 'self'; form-action 'self'; frame-src 'none'" — no default-src/img-src/style-src. No COEP header anywhere; uploads send no CORP.
implication: sandbox/CSP do not block <img> or inline <style> in the srcdoc preview
- timestamp: 2026-11-13T15:42Z
checked: demo DB (docker sm-demo-pg) system_mail_brand_settings, system_files id 556; curl of the computed logo URL
found: brand row 1 saved (button_primary_bg #2974d6, logo_file_id 556 -> 72368e60b987f6aab7c025.png, is_public t). URL from attach.AbsolutePublicURL(app.url + storage.uploads.public_path_prefix + partition key) = http://127.0.0.1:8097/storage/app/uploads/public/723/68e/60b/72368e60b987f6aab7c025.png -> HTTP 200 image/png. go.log has no "mail branding logo" warning.
implication: logo URL resolution works; Brand.LogoURL is populated for preview and send
- timestamp: 2026-11-13T15:45Z
checked: scratch repro (scratchpad/mailrepro) — postcard.NewCatalog + Register(sm-user-plugin views) + NewMailer with an OverrideSource returning Brand{LogoURL: <above>, ButtonPrimaryBg #2974d6}; send golem15.user::mail.activate in file layout (user), system, default, minimal
found: for all four layouts the HTML contains the compiled brand CSS (#2974d6 present) but 0 occurrences of the logo URL and 0 `class="button`. user layout body = `<div class="layout-user"><p>Cześć <strong>Jan</strong>.</p><p><a href="...">Aktywuj konto</a></p><p>Kod: 123456</p></div>`. system layout = Winter wrapper/inner-body card + subcopy, no header/logo, no footer.
implication: reproduces all three symptoms deterministically outside the SPA (Bohrbug); preview path is not at fault
- timestamp: 2026-11-13T15:47Z
checked: same repro with body `{{ partial "button" "url" .Link "body" "Aktywuj konto" }}` in the user layout
found: renders `<table class="action">...<a href="..." class="button button-primary" target="_blank">Aktywuj konto</a>` and brand CSS has .button/.button-primary rules with the brand colour
implication: button support exists and is styled; the CTA is a plain link only because the plugin templates don't call the partial
- timestamp: 2026-11-13T15:50Z
checked: git show v0.6.4:modules/postcard/{partials.go,templates.go}; sm-user-plugin/go.mod, sm-paymentgateway-plugin/go.mod
found: partials.go absent in v0.6.4; v0.6.4 execHTML parses with no FuncMap (no `partial`). Both plugins `require git.golem15.com/golem15/summercms v0.6.0`.
implication: plugin templates can only adopt `{{ partial "button" }}` together with a require bump to the first tag containing phase 35; on <= v0.6.4 the call fails to parse at send ("function \"partial\" not defined")
- timestamp: 2026-11-13T15:52Z
checked: .planning/phases/35-.../35-01-PLAN.md
found: Task "Assets: port Winter's system layout and the four partials ... default.htm is not touched" with a gate `git diff a024280 --stat -- modules/postcard/assets/default.htm prints nothing`. Task 5 logo test uses "a layout using {{ .logoUrl }}" (test-only override, brand_smoke_test.go:220,329). Task 5 <done> claims "Saving Branding restyles every mail and shows the logo". Plugin layouts never in any phase-35 plan's files list.
implication: the phase delivered the logo slot and partials as plumbing; no shipped layout or plugin template was updated to consume them, and verification checked the plumbing via test overrides, not out-of-box output
- timestamp: 2026-11-13T15:54Z
checked: WinterCMS reference examples/golem15-wintercms-starter/modules/system/views/mail + classes/MailManager.php + plugins/golem15/user/views/mail/activate.htm
found: Winter ships layout-default (wrapper + {% partial 'header' %} with subject + inner-body card + {% partial 'footer' %} "(c) year appName") and layout-system, partials header/footer/button/panel/promotion/subcopy/table. Winter user activate.htm uses `{% partial 'button' url=link type='positive' body %}Confirm account{% endpartial %}` and no plugin layout (default). MailManager::renderTemplate inlines CSS with TijsVerkoyen CssToInlineStyles (layout option disable_auto_inline_css). Winter brand settings have no logo.
implication: postcard ported system layout and 4 partials but not Winter's default layout or header/footer partials; Go user templates dropped Winter's button partial; postcard never inlines CSS (only a <style> block) — fine for the browser preview, a parity gap for real mail clients
- timestamp: 2026-11-13T15:56Z
checked: git history of plugin layouts; other plugins' mail
found: sm-user-plugin layouts/user.htm from 63d6d04 (phase 07-03), paymentgateway layout from dee26dd (phase 18-04) — stubs predating Branding/partials. user.htm text wrap is `-- {{ .Content }} --`. 54 paymentgateway templates use layout paymentgateway with `[Zobacz zamówienie]({{ .orderUrl }}): {{ .orderUrl }}`. sm-mfa-plugin and sm-quizzes-plugin templates have no layout -> postcard default (bare div). KindBrand preview (Branding page) also renders in the default layout.
implication: every out-of-box path except an explicit system-layout choice lands in a bare wrapper
- timestamp: 2026-11-13T15:58Z
checked: demo DB system_mail_layouts / system_mail_templates
found: golem15.user::mail.layouts.user is_custom=t (overridden during UAT test 5, no logoUrl); golem15.user::mail.activate is_custom=t (layout user). Other layouts not customized.
implication: when verifying a fix on sm-demo-app, these two overrides must be reset or the new file versions won't show (drift notice instead)
## Resolution
root_cause: |
(1) Logo: no shipped layout prints {{ .logoUrl }}. The variable is wired end to end (store.go builds an absolute URL that serves 200; mailer.options/Editor.render set opts.logoURL; renderParts passes "logoUrl" to both wrappers), but postcard's default/system/minimal and the plugin layouts user/paymentgateway never use it, there is no header partial, and brand.css.tmpl has no logo rule. Plan 35-01 tested the logo only through test-only layout overrides and pinned default.htm as untouched. The sandbox, CSP and URL resolution were ruled out.
(2) CTA not a button: sm-user-plugin activate/restore/invite (+ -en) use the Markdown link [Aktywuj konto]({{ .Link }}), and the 54 paymentgateway templates use [Zobacz zamówienie]({{ .orderUrl }}): {{ .orderUrl }}. The Go port dropped Winter's {% partial 'button' %}. postcard's built-in button partial works and is styled with the brand colours, but no plugin calls it, and plugins can't until they require a framework tag with phase 35 (they require v0.6.0, and v0.6.4 has no partial func).
(3) Unstyled plugin/default layouts: user.htm and paymentgateway.htm are stubs from phases 07-03 and 18-04 (<div class="layout-*">{{ .Content }}</div>). Neither class has a CSS rule, and neither layout has a wrapper, inner-body card, header or footer. The brand CSS only styles elements and Winter's wrapper classes, so the content sits flush on the grey body background. postcard's default.htm (used by mfa, quizzes and the Branding preview) is just as bare (<div class="content-body">), because only Winter's system layout was ported, not Winter's default layout with its header/footer partials. System looks "kind of proper" because it alone carries the Winter card structure, though it has no header/logo/footer and its content cell has zero horizontal padding.
(4) Contributing, real sends only: postcard places the CSS in a <style> block and never inlines it (Winter runs CssToInlineStyles). The browser preview is fine, but mail clients that ignore or strip head styles will show unstyled mail even after the layouts are fixed.
fix: (diagnose-only; see missing items in return)
verification:
files_changed: []

View File

@@ -0,0 +1,59 @@
# Decision: CodeMirror 6 for the admin `codeeditor` field
**Date:** 2026-11-06
**Status:** Accepted pending human version check (Phase 35 plan 35-03 Task 3)
**Relates to:** `.planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md` (Why CodeMirror 6, Registry Safety), `.planning/phases/35-mail-templates-and-layouts-editor/35-RESEARCH.md` (Package Legitimacy Audit, Pitfall 5), `.planning/research/STACK.md`
## Decision
The admin SPA (`admin/package.json`) adds seven npm **runtime** dependencies with exact pins and a committed `package-lock.json`. They load only from `admin/src/components/form/codeeditor/editor.ts` via a dynamic import in `CodeEditorField.vue`, so CodeMirror lands in its own chunk (same pattern as TipTap).
| Package | Version | Use |
|---------|---------|-----|
| `@codemirror/state` | 6.7.6 | `EditorState` |
| `@codemirror/view` | 6.43.15 | `EditorView`, `keymap`, `lineNumbers`, `MatchDecorator`, `ViewPlugin`, `lineWrapping`, `contentAttributes` |
| `@codemirror/language` | 6.13.1 | `bracketMatching`, `HighlightStyle`, `syntaxHighlighting` |
| `@codemirror/commands` | 6.11.1 | `history`, `historyKeymap`, `defaultKeymap` (without Mod-Enter) |
| `@codemirror/lang-html` | 6.4.12 | `html()` grammar |
| `@codemirror/lang-css` | 6.3.1 | `css()` grammar |
| `@lezer/highlight` | 1.2.5 | `tags` for `HighlightStyle.define` (direct pin; UI-SPEC lists it as transitive) |
**Not used:** the `codemirror` meta package (`basicSetup`), and `indentWithTab` from `@codemirror/commands`.
**Keymap rule (research Pitfall 5):** extensions use `keymap.of([...historyKeymap, ...defaultKeymap.filter((b) => b.key !== 'Mod-Enter')])`. Tab is unbound so focus leaves the editor; Mod+S and Mod+Enter remain the form save hotkeys; Esc does not cancel the form.
## Why
- **MIT, modular, no workers.** CSP stays unchanged (`worker-src` not required). Accessible `contenteditable` surface.
- **Rejected alternatives (UI-SPEC):** Monaco (size, workers), Ace (weaker a11y), a textarea overlay (caret sync), TipTap source mode (rich-text tool, not a code editor).
## Transitive packages
Pulled in by the pins above (not listed as direct dependencies unless already above):
- `@lezer/*` HTML/CSS grammars via `@codemirror/lang-html` / `@codemirror/lang-css`
- `@codemirror/autocomplete` and `@codemirror/lang-javascript` via `@codemirror/lang-html`
- `style-mod`, `w3c-keyname`, `crelt`
- `@marijn/find-cluster-break` (transitive of `@codemirror/state`)
## Legitimacy
Re-checked with read-only `npm view <pkg>@<ver> dist.integrity` on 2026-11-13 before any install. Matches the Phase 35 research Package Legitimacy Audit (maintainer `marijn`, no `postinstall` scripts, high weekly downloads, official CodeMirror / lezer sources).
| Package | Version | `dist.integrity` | Notes |
|---------|---------|------------------|-------|
| `@codemirror/state` | 6.7.6 | `sha512-kAz+AncRtKuIknedxT1bq4XwXv4UowhbkHU1myPrtVb/jZtImWuV5BXzv5vK6i3kYACsdiZiQKFQQ5Mq7elW8w==` | [OK] |
| `@codemirror/view` | 6.43.15 | `sha512-HHsfpqFeHyXLs983pSRe38Xajs0vFWZQ2BuX0m7Ki8w3jZ5iD8cuR3lBz2/5/X53Dhf32SBHKh6rtSTB6tKeGw==` | **[SUS] too-new** — published 2026-10-19 (18 days old on 2026-11-06 audit; past the project's 7-day cooldown). Same maintainer as every other CodeMirror pin. Human checkpoint before install. |
| `@codemirror/language` | 6.13.1 | `sha512-zfvU2r3TyylQLMj/te+5CnQ0rSqZi8B1oTCBbQkagcLW4Xc6imab6qN+pEJhsuNOLaJqiRyBXp9UhWA1DhVvDw==` | [OK] |
| `@codemirror/commands` | 6.11.1 | `sha512-O/4hG3SC1YwcmQ0d2UVNDs+AsaNWd1iHVxbTeEBuqH+6bExAiPK3iS/BvpY6rZGURALv4ZD3sIgcCmRvw3ehBg==` | [OK] |
| `@codemirror/lang-html` | 6.4.12 | `sha512-pw2ReWKUqSkbvh76RAT4NYxiogRu+PWkR2ukAwO9uOgrm8uipkzjtKKtNpyeAQwHOqxEeSvAXZ6vr3AfyB9y/w==` | [OK] |
| `@codemirror/lang-css` | 6.3.1 | `sha512-kr5fwBGiGtmz6l0LSJIbno9QrifNMUusivHbnA1H6Dmqy4HZFte3UAICix1VuKo0lMPKQr2rqB+0BkKi/S3Ejg==` | [OK]; also maintainer `adrianheine` |
| `@lezer/highlight` | 1.2.5 | `sha512-O1GMVKgtf5YspFaRzpmqkVgMtIk2HG9uMAbH6wdAIdNh3TVzCsch/+cRi+6l2//UGDKe6NB9BW3cvuR5ezMQ0w==` | [OK] |
Install only after the Task 3 human gate: `npm --prefix admin install --save-exact` with exactly these pins, then `npm --prefix admin ci` against the committed lockfile. Lockfile integrity for each package must equal the values above.
## Consequences
- Layout and partial HTML/CSS/text editing uses a real editor with Go `{{ ... }}` action highlighting (`cm-summer-action`), without changing the design-system colour tokens.
- A load failure falls back to a monospace textarea that still saves (UI-SPEC C1).
- `@codemirror/view` 6.43.15 may be replaced with 6.43.14 or older if the human checkpoint rejects the too-new flag; update this note and STACK.md in that case before installing.

View File

@@ -0,0 +1,41 @@
# Decision: finished built-in mail layouts and CSS inlining through github.com/vanng822/go-premailer
**Date:** 2026-11-13
**Status:** Accepted
**Context:** Phase 35 UAT gap G-35-8 (35-UAT.md, test 8, severity major), debug session `.planning/debug/mail-layouts-unstyled.md`, Jakub's decision of 2026-11-13 (framework only; the plugin layouts and templates follow after the framework tag), plan 35-06
## What this supersedes
- **D-10's inlining claim.** 35-CONTEXT D-10 says the Branding colours "compile into the brand CSS slot that postcard already inlines". postcard never inlined: it placed the brand CSS and `mail.css` in the layout's style block and nothing more, so mail clients that drop style blocks showed unstyled mail. From this decision on, postcard inlines the CSS at render (below).
- **35-01's "default.htm unchanged" gate.** Plan 35-01 kept `modules/postcard/assets/default.htm` byte-identical (a bare `content-body` block). That gate is lifted: the default layout is now WinterCMS's default layout (wrapper, header with the logo or the name, white card, copyright footer), built on two new built-in partials, `header` and `footer`.
- **D-10's Branding fields.** Branding gains a **Site name** (`site_name` column, `postcard.Brand.SiteName`). Empty, it falls back to the display name of `mail.from` (`Acme` for `Acme <no-reply@acme.test>`). Layouts get it as `{{ .siteName }}`, next to `{{ .year }}`, the current year.
## Decision
- **`github.com/vanng822/go-premailer` pinned at exactly v1.38.0**, package `premailer`, with its default options: `RemoveClasses` false (class attributes stay, so plugin CSS hooks and the leftover style rules still match), `CssToAttributes` true (CSS widths and heights are mirrored to `width`/`height` attributes, as mail clients expect), `KeepBangImportant` false.
- **Where it runs.** In postcard's render path (`renderParts`), so the admin preview, the test send and real sends get the same HTML: after the layout's HTML wrapper has rendered and passed `validateHTML`, the HTML goes through `NewPremailerFromString(...).Transform()`, and the result is checked by `validateHTML` again. The plain-text part is never touched.
- **What it does.** It collects the rules of the document's style elements (the brand CSS, the layout's own CSS and `mail.css`), applies them to the matching elements by specificity, removes the style elements, and puts the rules it cannot inline (media queries, pseudo-classes such as `:hover`, selectors with `*`) back in one style element in the head, marked `!important`. The DOCTYPE line is kept.
- **Error fallback.** An inliner error (or a panic inside it, recovered) never stops mail: the un-inlined HTML is sent with its style block, and a warning keyed `inline:<layout code>` is logged at most once per warn interval (D-14 spirit).
- **Opt-out, with WinterCMS's option name.** A file layout opts out with the header key `disable_auto_inline_css` (`true`, `1` or `yes`, any case); a database layout with the boolean column `disable_auto_inline_css` of `system_mail_layouts` (migration `202611130003_mail_layout_disable_auto_inline_css`), edited by a switch on the layout form's CSS tab. An opted-out layout keeps only its style block. The built-in layouts all inline. This matches `MailManager::renderTemplate` in WinterCMS, which runs CssToInlineStyles unless the layout's `disable_auto_inline_css` option is set.
## Facts checked (2026-11-13)
- **Versions and dates.** `go list -m -versions` lists v1.38.0 as the latest tag. proxy.golang.org reports v1.38.0 published 2026-11-04T18:13:54Z (origin `https://github.com/vanng822/go-premailer`, tag `refs/tags/v1.38.0`, commit `98a25222c9ea2827cfc13dd8f162976703574435`), nine days before this decision and past the 7-day cooldown; v1.37.0 was published 2026-10-02, so releases come roughly monthly. Module sum `h1:nYXopG+L6lcRV6dEAemLLE71bihun3gxgfNJZ9iYm1Q=`, go.mod sum `h1:6Jcm7sYO8ON3J/IIlox2fWq+YPgGopwx7VbETlZRZtY=`, both verified against the checksum database by `go mod download`.
- **Licence and maintainer.** MIT (`LICENSE`: Copyright (c) 2015 Nguyen Van Nhu); maintained by its author since 2015. pkg.go.dev listed 246 importing packages at planning time.
- **Its requirements.** `github.com/PuerkitoBio/goquery` v1.13.0, `github.com/inbucket/html2text` v1.0.0, `github.com/vanng822/css` v1.0.1, `golang.org/x/net` v0.62.0 (and `github.com/stretchr/testify` for its own tests). Its go.mod says `go 1.26.0`; this repository is at go 1.27.0.
- **What MVS changes here** (dry run of `go get` and `go mod tidy` on a scratch copy of go.mod): `golang.org/x/net` v0.58.0 to v0.62.0, `golang.org/x/crypto` v0.57.0 to v0.58.0, `golang.org/x/text` v0.42.0 to v0.43.0, `golang.org/x/term` v0.46.0 to v0.47.0, and the indirect `golang.org/x/sys` v0.48.0 to v0.49.0 and `golang.org/x/sync` v0.23.0 to v0.24.0.
- **Modules `go mod tidy` adds as indirect.** `github.com/PuerkitoBio/goquery` v1.13.0, `github.com/andybalholm/cascadia` v1.3.4, `github.com/inbucket/html2text` v1.0.0, `github.com/vanng822/css` v1.0.1, and through html2text's table rendering `github.com/olekukonko/tablewriter` v1.0.7, `github.com/olekukonko/errors` v1.1.0, `github.com/olekukonko/ll` v0.0.9, `github.com/fatih/color` v1.18.0, `github.com/mattn/go-colorable` v0.1.14, `github.com/mattn/go-isatty` v0.0.20 and `github.com/ssor/bom` v0.0.0-20170718123548-6386211fdfcf. `github.com/gorilla/css` v1.0.1 was already in the module graph.
- **Fit check** (the default layout with the brand CSS and a media query in `mail.css`, before the go.mod change, through a scratch modfile): the DOCTYPE line was kept, class attributes were kept, the button link carried `background-color:#d66829` in its style attribute, the media query stayed in a style element, and the output passed `validateHTML`.
## Consequences
- The framework go.mod requires `github.com/vanng822/go-premailer v1.38.0`; only `modules/postcard/inline.go` imports it. Every binary that links postcard links it, goquery, cascadia, html2text and tablewriter.
- **Follow-up for consumers.** Applications and plugins that build against this checkout with a `replace` (sm-demo-app, sm-user-plugin, sm-paymentgateway-plugin and others) need `go mod tidy` to get the new go.sum lines; until then `go build` and `go test` in them report missing go.sum entries. Their trees are not changed in 35-06; the bump comes after the framework tag.
- The style block of an inlined message holds only the leftover rules, not the brand CSS and `mail.css`. Tests and tools that read the style block for the brand CSS read the style attributes instead, or use a layout that opts out.
- A CSS value an administrator writes is copied into style attributes. `validateHTML` runs on the inlined HTML, so a `javascript:`, `vbscript:` or `data:` address that reaches an attribute fails the render as before (and a failing override falls back to the file version, D-14).
## Rejected alternatives
- **An in-house inliner on `golang.org/x/net/html` with douceur and cascadia.** No new top-level module, but postcard would own selector specificity, cascade order, `!important`, media-query leftovers and the attribute mirroring, with their edge cases.
- **`github.com/aymerick/douceur/inliner`.** Unmaintained since 2016.
- **No inlining.** The UAT gap stays for every client that drops style blocks (several webmail clients and Outlook variants).

View File

@@ -0,0 +1,33 @@
# Decision: one admin record per mail template, locale versions behind a switcher
**Date:** 2026-11-13
**Status:** Accepted (shipped in Phase 35 plan 35-05)
**Context:** `.planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md` gap G-35-1 (UAT test 1, major): "each locale is a separate entry in backend is absolute disaster ... imagine site with 50 locales". User decision of 2026-11-13 confirming the gap-closure plans.
**Relates to:** `35-CONTEXT.md` D-05, D-06, D-07, D-13, D-16; `35-UI-SPEC.md` C16; `modules/postcard/README.md` ("Locale variants", "Index rows, drift and reset"); `modules/cabana/README.md` (mail screens).
## Context
D-05 ("locale variants stay separate templates") made `postcard.SyncIndex` write one `system_mail_templates` row per file (`activate.htm`, `activate-en.htm`), and the cabana Mail templates list showed each row with a locale column and a locale filter. There was no grouping key and no per-locale editing inside one record, so N locales gave N list rows per template, and a locale that ships no file could not be customized at all.
## Decision
D-05 is superseded. A mail template is one admin record; its locale versions are edited behind a locale switcher in the template form. As shipped:
- **Group key.** `system_mail_templates.base_code` (migration `202611130001_mail_template_base_code`, nullable, indexed). It is the code with its locale suffix stripped, by the same rule as `postcard.TemplateLocale` (suffix after a dash in the last dotted segment, one of the mail locales): `postcard.TemplateBase`. A code without such a suffix is its own base. `postcard.SyncIndex` writes it on every template row.
- **Mail locales** (cabana). The phrasebook translator's `Locales("")` plus, when a `cabana.TranslationWriter` is published and answers, its `EnabledLocales`. The default locale is the writer's `DefaultLocale`, else the translator's `Locale()`. The index syncs again when this set changes, so a 50-locale site (locales enabled through a translate plugin) gets 50 entries in the switcher without a restart.
- **Fallback-locale rows.** `postcard.EnsureLocaleRows` gives every base template a row `<base>-<locale>` for every mail locale except the default that ships no file: source, description, subject, body, layout and `file_hash` from the base file, `base_code` the base. The default locale gets no row: the unsuffixed file is its version. Rows are created at sync for all templates and on show for the shown template; nothing is deleted.
- **Variant set and order** (`cabana.RecordMeta.LocaleVariants`, `cabana.RecordLocaleVariant`, on the show and update responses of the mail templates screen only). Default (the unsuffixed file, label `mail.template.locale_default`), then by locale code: every locale with its own file, every other mail locale except the default, and any customized row of a locale that is no longer enabled. A group whose base has no file (only `x-en.htm` shipped) has no Default and no fallback rows. Labels and state words are translated on the server.
- **What a fallback row shows.** Until it is customized, its form shows the default-locale version as it is sent now (the base row's effective subject, body and layout, its customization when there is one). Saving makes it customized with `base_hash` = the base file's hash.
- **Per-locale customize / reset / drift (D-06, D-07).** Each version is its own row with its own `is_custom`, `base_hash` and `file_hash`. A fallback row's `file_hash` follows the base file, so "File changed" shows on it when the base file changes. `postcard.ResetOverride` accepts a fallback-locale code and returns it to the base file. Saves, preview and test send go through `postcard.Editor` exactly as before (D-13, D-16).
- **Send resolution** (postcard, independent of any locale list, so `queue:work` needs no cabana). A name with its own file renders exactly as before. A name the catalog does not hold, of the form `<base>-<tag>` where `<base>` is a registered template and `<tag>` is a two-letter language optionally followed by `-` or `_` and a 2-8 character alphanumeric subtag (case-insensitive, the longest registered base wins), renders the base file with: the name's own customized row, else the base's customized row, else the base file. Any other unknown name keeps the "postcard: unknown template <name>" error. `postcard.Catalog.TemplateFor` exposes the resolved file. Core plugins are unaffected: sm-user-plugin and sm-paymentgateway-plugin send names that have files, and `scripts/check-phase35.sh --consumers` passes unchanged.
- **List.** One row per template (the base row, or the lowest code when only variants ship), a Customized locales column (Default and locale codes of the customized versions, at most three then +N), Customized / File changed badges aggregated over the group, and the status filter applied to the whole template. The locale filter is removed.
## Rejected alternatives
- **Multilingual fields (`mltext` / `mlmarkdown`) in one record.** One row would hold every locale's subject and body, but there would be no per-locale layout, reset or drift, and the send path would need a translate store.
- **A form-level `?locale=` query parameter.** The switcher would edit one record under a locale parameter; FormView would change for every controller, and the per-locale state would still need rows.
- **Rows for a locale created only on its first save.** A locale not yet customized could not be opened, so the switcher could not list it.
## Follow-up (outside this phase)
- Plugins that want per-locale admin versions pass `<template>-<locale>` for every locale they serve. sm-user-plugin's `classes.MailTemplate` maps only `en` today; postcard already resolves a locale without a file to the default-locale version, so passing the suffix for every locale is safe. This belongs to the plugin follow-up after the framework tag.

View File

@@ -0,0 +1,79 @@
# Decision: postcard checks URL schemes in decoded attribute values, never lets a site name stop a send, and prints the footer name literally
**Date:** 2026-11-14
**Status:** Accepted; amended the same day by the review fixes of 35-REVIEW.md (re-review of 35-08/35-09): CR-01 residual, CR-02, WR-01, WR-02, WR-03 (see "Amendment" below); amended again by quick task 261114-p5m (CR-02 residual: an end tag inside a quoted attribute)
**Context:** Phase 35 re-verification gap (35-VERIFICATION.md `gaps:`, the CR-01 regression), 35-REVIEW.md CR-01, WR-01 and WR-05, Jakub's decisions of 2026-11-14 (two plans: this fix in 35-08, then the regression and unit tests in 35-09; WR-01 and WR-05 bundled with CR-01), plan 35-08
## The problem
postcard's `validateHTML` ran `(?i)(?:javascript|vbscript|data):` over the whole rendered document. The built-in layouts print the site name (the Branding Site name, else the display name of `mail.from`) in the header and the footer, so a site name such as `Big Data: Summit` or a sender such as `"Metadata: Weekly" <x@example.com>` failed every send on the default and system layouts. The file version carries the same name, so the override-to-file fallback failed too, and the Editor refused every template and layout save while such a Branding name was stored. An application that sends mail today could stop sending password resets after upgrading, without anyone touching the admin.
Two related findings: the check read undecoded markup, so `href="javascript&#58;..."` in a layout or partial override passed it and was sent as is when the layout opted out of inlining (WR-05), and an inlined result that failed the post-inline check stopped the message although the docs promise the inliner never does (WR-05). The footer rendered the copyright line, and with it the site name, as Markdown (WR-01).
## What this supersedes
- **35-RESEARCH.md Pitfall 8** ("keep the behaviour, it matches sends") and 35-PATTERNS.md "HTML safety gate: reuse them unchanged", for postcard. Prose is no longer treated as a URL.
- **The postcard README sentence** saying that text such as `metadata:` is refused at save.
- **The README sentence** saying an inlined result that fails the safety check fails the render.
- **D-13 itself stands:** `javascript:`, `vbscript:` and `data:` URLs are still refused at save and at send, now also when they are entity-encoded.
- `cabana.RenderMarkdown`'s own regexes (the admin Markdown preview) are out of scope and unchanged.
## Decision
### What the scheme check reads (`unsafeMarkup`, modules/postcard/safety.go)
The rendered HTML is read with `golang.org/x/net/html`'s tokenizer (already a direct framework requirement, used by seaglass, tide and cabana). The tokenizer lower-cases attribute names and decodes character references in attribute values (`&#58;`, `&#x3A;`, `&colon;`, `&#106;`), so the check sees what a mail client sees.
- **Single-URL attributes** (`urlAttributes`): `action`, `background`, `cite`, `codebase`, `data`, `dynsrc`, `formaction`, `href`, `icon`, `longdesc`, `lowsrc`, `manifest`, `poster`, `profile`, `src`, `usemap`, `xlink:href`, and the SVG animation targets `from`, `to`, `by`. A value is refused when, decoded, with every ASCII whitespace and control character (U+0000 to U+0020 and U+007F) removed and lower-cased, it starts with `javascript:`, `vbscript:` or `data:` (`hasDangerousScheme`). Removing whitespace closes tab- and newline-split schemes.
- **List-valued attributes** (`urlListAttributes`: `srcset`, `ping`, `archive`, `values`), **`style` attributes**, the **`content` attribute of `meta` elements**, the **text of `style` elements** and **comment data**: refused when the existing `dangerousScheme` pattern matches anywhere in the decoded value with whitespace and control characters removed (`stripURLSpace`, shared with `hasDangerousScheme`; WR-01), so `values="java&#9;script:..."` is refused. The conservative rule stays for CSS and lists, where prose does not belong.
- **Raw-text elements and comments are checked as markup too** (CR-02). The tokenizer reads the content of `iframe`, `noembed`, `noframes`, `noscript`, `plaintext`, `script`, `style`, `textarea`, `title` and `xmp` as one text token, also after a self-closing start tag. A mail client may parse it as markup (it renders with scripting off, so `noscript` content is markup; inside `svg`/`math` these are foreign elements with markup children), so `unsafeMarkup` checks the raw source of that content, and the data of every comment (Outlook conditional comments), again as markup. Each nested check reads a strictly shorter text; nesting deeper than eight levels (`maxMarkupDepth`) is refused ("rendered HTML nests raw-text elements or comments too deeply"). The raw source, not the decoded text, is re-read, so `&lt;a href=...&gt;` in a `title` stays text. After this HTML reading, `unsafeMarkup` reads the same text once more as tags only (`unsafeTagReading`, quick 261114-p5m): x/net/html's tokenizer with `NextIsNotRawText()` called after every raw-text start tag, and the `<` of each `<!--` blanked to a space (same length, so snippets point into the original). Attribute quoting alone decides where a tag ends, so `<svg><style><a title="</style>" href="javascript:...">` and `<!--[if mso]><a title="-->" href="javascript:...">` are refused. The same attribute checks and messages apply (`unsafeAttrs`, shared by both readings). Both readings run at every depth, both are linear, and the depth limit is unchanged.
- **Text content is not checked for schemes.** It is not a URL; a mail client does not follow it. `metadata:` or `Big Data: Summit` in a body, a header or a footer passes.
- **Event handlers.** The raw-markup regex for `script`/`iframe`/`object`/`embed` tags stays as it is and runs first. Event handlers are attributes only: the tokenizer walk refuses any attribute whose name starts with `on`, with or without whitespace before it (`<img src="x"onerror=...>`), also inside raw-text elements and comments. The whole-document regex for whitespace-prefixed `on*=` is dropped (WR-02): it read text as well, so a variable such as `buy one = get one free` stopped its own message, and the footer's `© <year> Online=Shop` stopped every send (CR-01 residual).
- **Error messages are unchanged** ("rendered HTML contains a dangerous URL scheme", "rendered HTML contains event handlers"). The snippet is the raw markup of the offending token, so an editor error shows the encoded form the administrator wrote.
- **Draft layout CSS** is checked as the content of a style element, so the error stays on `content_css`.
### Site names never stop a send (`postcard.UnsafeText`, `siteNameFrom`, `layoutSiteName`)
- **`postcard.UnsafeText(s string) bool`** (exported, so cabana can refuse a name at save): a text is unsafe when, HTML-escaped with the standard library's `html.EscapeString` as html/template prints text and placed where the built-in layouts print it (after `© 2000 ` in a footer paragraph, in the header span and in the logo's `alt`; `printContext`, CR-01 residual), it fails the rendered-HTML checks, or when it holds a script URL (`scriptURLText`): `javascript:` or `vbscript:` at a scheme boundary (whitespace may follow the colon, since `javascript: alert(1)` still runs), or a data URL: `data:` at a scheme boundary, an optional MIME type and the `;` or `,` every data URL has (WR-03). A scheme boundary is the start of the text or a character that cannot belong to a URL scheme (anything but ASCII letters, digits, `+`, `.` and `-`). Escaped text is never markup, so since the handler regex is gone the rendered-HTML part refuses nothing a layout prints as text; it stays as a guard for a later check that depends on context. `Big Data: Summit`, `Metadata: Weekly`, `Metadata:Weekly`, `Data:Lab`, `Online=Shop` and `Shop onclick=x` are safe; `javascript:alert(1)`, `javascript: Acme`, `data:text/html,x` and `data:,x` are not.
- **Render-time drop.** An unsafe Branding Site name is treated as empty, so the documented fallback applies (the display name of `mail.from`, if that one is safe); an unsafe `mail.from` display name gives no name. This holds on every render path: the file version, the override render built from it, the override-failure fallback and the editor. One warning per source per minute through the mailer's existing rate-limited `warn`, keyed `site_name:branding` or `site_name:mail.from`, message "postcard: site name left out of the layouts, it fails the mail safety check", with the source and never the value.
- **The Branding preview** of an unsaved draft drops the name the same way, so the preview shows what would be sent; the save is what refuses it.
- **Save rule.** cabana's `MailBrandSetting.BeforeValidate` refuses a name `postcard.UnsafeText` refuses: a 422 on `site_name` with `backend::lang.mail.brand.site_name_unsafe`, collected with the colour and logo details. Saving a template or a layout while an unsafe name is stored is not refused (the name is left out of the render).
- **Copy** (`mail.brand.site_name_unsafe`): en "This name cannot be shown in mail. Remove addresses that start with javascript:, vbscript: or data:."; pl "Tej nazwy nie można pokazać w wiadomościach. Usuń adresy zaczynające się od javascript:, vbscript: lub data:." (the "text such as onclick=" clause was dropped with the handler regex, WR-02; 35-UI-SPEC.md and 35-08-PLAN.md still quote the 35-08 copy)
### The inliner never stops mail (WR-05 contradiction)
The documented behaviour wins. The check sees decoded attribute values and style element CSS before inlining, whether or not the layout sets `disable_auto_inline_css`. An inlined result that still fails it is treated like an inliner error: the un-inlined HTML, which passed the check, is sent with its style block, and a warning keyed `inline:<layout>` is logged ("postcard: inlined CSS failed the safety check, sending the style block only").
### The footer prints the name literally (WR-01)
The `footer` partial gains a `text` argument, printed as plain text (a paragraph through html/template in the HTML part, verbatim in the text part); `body` stays Markdown for callers that pass Markdown on purpose. The default and system layouts pass the copyright line as `text`, so `*Acme*`, `Acme <Studio>` and `[x](url)` appear as typed, escaped, as in the header. The footer partial shipped in 35-06 and is in no tag yet (the newest tag, v0.6.4, predates it), so no released override depends on the old call.
## Rejected alternatives
- **Keep the whole-document regex and only guard the site name.** Body text and other configuration text (`metadata:` in a template body, a variable, a partial argument) would keep stopping sends.
- **A bluemonday-based mail sanitizer.** It rewrites instead of refusing, and would need a mail allowlist for style elements, tables and layout attributes. The 2026-10-11 note scopes bluemonday to stored rich text; this check only locates attribute values with x/net/html and keeps postcard's refuse-and-fall-back contract.
- **Failing the render when the inlined result fails the check** (the reviewer's alternative for WR-05). It stops mail that passed the check, contradicts the documented promise and D-14.
- **Re-checking from a raw-text element's content start to the end of the document** (for the CR-02 residual). Inside the recursion it re-reads the rest of the document once per raw-text element and comment, which is quadratic or worse on hostile input.
- **Using the x/net/html parse tree as the check.** It loses the raw snippet the editor shows, reads `xmp` and `noembed` as raw text and ends a conditional comment at the first `-->`, while CR-02 deliberately checks that content as markup.
## Residual risk accepted
- CSS escape sequences inside CSS (`\6a avascript:`) are not decoded. Mail clients do not run script URLs from CSS.
- Re-reading raw-text element and comment content as markup over-refuses in the rare case where a client would read it as text (an HTML-context `textarea` holding markup, a CSS string holding `<a href="javascript:...">`). No mail markup needs either.
- html/template escapes a template's literal `title` and `textarea` text itself, so an `<svg><title><a href=...>` in a layout or body is sent as escaped text; the check refuses the unescaped form wherever else it can appear.
- The tag reading treats comment and raw-text content as markup with quotes honoured. An unbalanced quote inside a comment or raw-text element can therefore join later text into one tag, and text after it that looks like an attribute (`online=yes` after a stray quote) is refused although no reader sees a tag there. No mail markup leaves a quote open in a comment or a style element.
## Amendment (review fixes, 2026-11-14)
The re-review of 35-08/35-09 (35-REVIEW.md, f1d22353) and the re-verification (35-VERIFICATION.md) found two gaps in this decision, fixed in commits `fix(35): CR-01 ...` through `fix(35): WR-03 ...`:
- **CR-01 residual:** `UnsafeText` checked a name on its own, but the footer prints it after `© <year> `, which gave `Online=Shop` the whitespace the handler regex needed; every default/system send failed. First fixed by checking the name in its print context (`printContext`), then removed at the cause with the handler regex (WR-02), so such names are shown and saved.
- **CR-02:** the tokenizer-only walk did not look inside raw-text elements, a regression against the pre-35-08 whole-document regex; now re-read as markup (above).
- **WR-01:** whitespace stripping for every scheme check; **WR-03:** the data-URL shape for site names.
- **CR-02 residual** (35-VERIFICATION.md truth 18, quick 261114-p5m): the re-check read raw-text content only up to the tokenizer's end tag, which an attribute value can contain (`<a title="</style>" href="javascript:...">`). Fixed by the tag reading above; the verifier's conditional-comment advisory (`-->` inside an attribute) is covered by the same reading.
## Consequences
- postcard imports `golang.org/x/net/html` (no go.mod change) and the standard library `html` package.
- `postcard.UnsafeText` is new exported API; `Mailer`, `Catalog.Register` and `pact.HasMailTemplates` keep their signatures.
- Fixtures that pinned prose as unsafe change with the code (editor, fallback, partials and override smoke tests); the 35-07 subtest that pinned an unsafe stored name is replaced by `TestMailBrandSiteName/unsafe_name_refused`.

View File

@@ -0,0 +1,100 @@
---
phase: "11.2"
slug: "ready-to-share-summercms-io-website-and-newsletter-plugin"
status: verified
# threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
threats_open: 0
asvs_level: 1
created: "2026-11-05"
---
# Phase 11.2 — Security
> Per-phase security contract: threat register, accepted risks, and audit trail. The newsletter plugin was not built in this phase (moved to backlog 999.1); no threat in the register concerns it. Evidence roots: FW = `summercms.go`, APP = `../sm-summercmsio-app`, PLUG = `APP/plugins/golem15/summercms`, SITE = `APP/vue-summercmsio-app`. Verified against the current tree; later phases (changelog, marketplace, VPN admin) changed the app, and replaced prongs are noted. T-11.2-SC is declared in all three plans (19 rows, 17 IDs).
---
## Trust Boundaries
| Boundary | Description | Data Crossing |
|----------|-------------|---------------|
| npm registry → build machine | third-party packages run during install and generate | tarballs, git deps, install scripts (high) |
| en.json / terminal.json → rendered HTML | repository copy becomes public HTML | i18n strings, terminal commands (medium) |
| page → visitor clipboard | the Copy button writes text visitors paste into a shell | six shell commands (low) |
| page → third-party origins | any runtime request elsewhere leaks visitor data | IP, Referer (medium) |
| internet → nginx (rome) | untrusted HTTP; TLS terminates here | all public requests (high) |
| nginx → summercms-io on 127.0.0.1:8095 | proxied requests filtered by path and method | path, method, X-Forwarded-For (medium) |
| request path → embedded file map | an untrusted path selects a file and may redirect | URL path, Location (high) |
| site.yaml / CLI flags → docs header HTML | configured URL written into every docs page | site_url, site_label (medium) |
| operator machine → rome | binary and config upload; secrets stay on the server | binary, config (medium) |
| summercms.go → module proxy | a pushed tag becomes immutable public state | release tag (medium) |
| test results → phase sign-off / env gates → integration tests | a gate misreading skips passes untested behaviour | test events, gate variables (medium) |
---
## Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation | Status |
|-----------|----------|-----------|----------|-------------|------------|--------|
| T-11.2-01 | Tampering (XSS) | components rendering en.json | medium | mitigate | no v-html/innerHTML under SITE/app/; inline code via `<i18n-t>` | closed |
| T-11.2-02 | Information disclosure (privacy) | font loading | medium | mitigate | `@nuxt/fonts` build-time download (SITE/nuxt.config.ts:40,64-71); SITE/tests/output.test.ts:218-231 asserts no Google font hosts; built output clean | closed |
| T-11.2-03 | Tampering | Copy button payload | low | accept | AR-11.2-01 | closed |
| T-11.2-04 | Information disclosure | PLUG static.go path resolution | high | mitigate | `path.Clean` + dot-segment 404 + preloaded map only, dotfiles never loaded (static.go:131-183); smoke.sh:230 and static_test.go:155-156 assert `/docs/.summer-docs` 404 | closed |
| T-11.2-05 | Spoofing (open redirect) | /docs and extension-less redirects | medium | mitigate | constant `/docs/` redirect (plugin.go:86); redirect only to an existing mapped name (static.go:178-182); TestStaticRedirectLocations covers `//evil`, `../`, backslash | closed |
| T-11.2-06 | Tampering (MIME sniffing) | static.go headers | low | mitigate | own content-type table first (static.go:30-60); `nosniff` on every file incl. 404s and scripts | closed |
| T-11.2-07 | Elevation of privilege | admin exposure | high | mitigate | public nginx `/backend` → 404 (summercms.io.conf:74-76), binary on loopback, check-deploy.sh:129-130 guards the block; admin only on the VPN vhost (10.8.3.0/24). Replaced since: plugin now has admin controllers (Phase 34) and smoke.sh:225 expects 200 on the binary; the internet-facing control holds | closed |
| T-11.2-08 | Information disclosure | DB password and app key | high | mitigate | empty secrets in committed config; `.env` gitignored, only `*.example` tracked; `.env` root:summercms 0640, never rsynced (DEPLOY.md:195,289) | closed |
| T-11.2-09 | Tampering (XSS) | docs header site_url | medium | mitigate | `checkSiteURL` on yaml key and flag (internal/docsite/load.go:125,145-161,289); `html/template` with plain string; load_test.go rejects `javascript:` and `//` | closed |
| T-11.2-10 | Tampering (clickjacking) | public pages | low | accept | AR-11.2-02 | closed |
| T-11.2-11 | Information disclosure (transport) | nginx | high | mitigate | 80→443 301 except ACME, www→apex, certbot certs, HSTS (summercms.io.conf:20-63); binary binds 127.0.0.1:8095 | closed |
| T-11.2-12 | Denial of service | nginx and binary | medium | mitigate | `limit_except GET HEAD` on `/` (:176-179); site routes GET-only (routes_test.go, smoke POST → 405); preloaded static files; supervisor restart | closed |
| T-11.2-13 | Tampering / Repudiation | v0.1.0 tag | medium | mitigate | blocking-human checkpoint (11.2-02-PLAN.md:318) resolved as defer-tag; no v0.1.0 exists; all tags annotated; CLAUDE.md requires go-ahead | closed |
| T-11.2-14 | Elevation of privilege | runtime account | medium | mitigate | nologin system user, dedicated Postgres role and DB, root-owned install root with only `storage/` writable (DEPLOY.md:173-182); supervisor `user=summercms` | closed |
| T-11.2-15 | Repudiation (false green) | scripts/check-phase11.2.sh | medium | mitigate | detector refuses build failure, no-tests, skip, fail, zero tests, missing named tests (:58-120); unknown flag exits 2 | closed |
| T-11.2-16 | Tampering (silent skip) | build-gated tests and terminal check | medium | mitigate | gate sets `SUMMERCMS_REQUIRE_BUILD=1` and `SUMMERCMS_TERMINAL_CHECK=1`; links_test.go `requireBuild` fails instead of skipping | closed |
| T-11.2-SC (01) | Tampering | pnpm installs | high | mitigate | exact pins, committed lockfile (git deps locked to commits), build allow-list of three packages, `--frozen-lockfile` (APP/scripts/build.sh:121) | closed |
| T-11.2-SC (02) | Tampering | dependency installs | high | mitigate | APP go.mod first-party only; PLUG direct requires (Phase 34) all already in FW go.mod at the same versions; go.sum committed; dirty-tree builds refused (build.sh:80-90) | closed |
| T-11.2-SC (03) | Tampering | dependency installs | low | accept | AR-11.2-03 | closed |
*Status: open · closed · open — below high threshold (non-blocking)*
*Severity: critical > high > medium > low — only open threats at or above workflow.security_block_on count toward threats_open*
*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
---
## Accepted Risks Log
| Risk ID | Threat Ref | Rationale | Accepted By | Date |
|---------|------------|-----------|-------------|------|
| AR-11.2-01 | T-11.2-03 | Payload is the bundled terminal.json, identical to the visible lines; the page only writes to the clipboard and never reads it. | 11.2-01 PLAN | 2026-11-05 |
| AR-11.2-02 | T-11.2-10 | Static marketing and docs pages with no state-changing actions; the admin CSP is deliberately not reused because it blocks Nuxt's inline scripts (D-07). | 11.2-02 PLAN | 2026-11-05 |
| AR-11.2-03 | T-11.2-SC (03) | Tests use the stdlib and the existing node:test runner; no package is added; `pnpm install --frozen-lockfile` reuses 11.2-01's lockfile. | 11.2-03 PLAN | 2026-11-05 |
*Accepted risks do not resurface in future audit runs.*
---
## Notes (non-blocking)
- **Attack surface added after 11.2** (covered by later phases' registers): admin controllers on the binary behind the VPN vhost; `APP/DEPLOY.md:190` ("nginx refuses /backend, so nothing writes runtime config overrides") is stale now that the admin is reachable over the VPN — writes would still fail on the root-owned `config/`. New write routes: `/_journal/api/v1/` (token + throttle) and POST `/api/registry/v1/ingest` (T-34-15/16). Marketplace readme `v-html` is covered by T-34-13.
- **Open review info items:** IN-01..IN-08 (11.2-REVIEW-DISPOSITION.md), none security-relevant beyond IN-07 (links_test.go follows redirects).
- **UAT:** 11.2-UAT.md is still `testing` with tests 1-3 pending; the cutover test expects v0.1.0, which was never created (releases started at v0.1.1). Superseded rather than failed.
---
## Security Audit Trail
| Audit Date | Threats Total | Closed | Open | Run By |
|------------|---------------|--------|------|--------|
| 2026-11-05 | 19 rows (17 IDs) | 19 | 0 | msd-security-auditor (ASVS L1, block_on high; repo contents only, no live-host checks) |
---
## Sign-Off
- [x] All threats have a disposition (mitigate / accept / transfer)
- [x] Accepted risks documented in Accepted Risks Log
- [x] `threats_open: 0` confirmed
- [x] `status: verified` set in frontmatter
**Approval:** verified 2026-11-05

View File

@@ -0,0 +1,142 @@
---
phase: "19.3"
slug: "framework-transport-and-infrastructure-for-wavepath"
status: verified
# threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
threats_open: 0
asvs_level: 1
created: "2026-11-05"
---
# Phase 19.3 — Security
> Per-phase security contract: threat register, accepted risks, and audit trail. Framework paths are relative to the repo root (HEAD `7b8d205`); `seo/` = `../vue-seo-layer`. The shared Nuxt purge route moved after the phase from the faq, menu and journal layers into vue-seo-layer, which all three now extend; T-23, T-29, T-37 and T-43 were verified there. T-19.3-SC is declared once per plan (6 rows, one ID).
---
## Trust Boundaries
| Boundary | Description | Data Crossing |
|----------|-------------|---------------|
| application to Redis | network hop carrying credentials in `redis.url` and shared counters other instances trust | Redis URL, cache entries, rate-limit counters (high) |
| request data to cache and limiter keys | keys can derive from client IPs, user ids or request values | key material (medium) |
| config and environment to boot | CORS, cookie, Turnstile, api-docs, `redis.url`, driver keys, `public_url` validated or reported before serving | config values, secrets (high) |
| browser on a sibling subdomain / SPA origin to the API | credentialed cross-origin requests and the token cookie | session cookie, API answers (high) |
| request to Turnstile middleware | untrusted token and body; siteverify crosses to Cloudflare | Turnstile token, secret (high) |
| jsDelivr CDN to the api-docs page | third-party scripts executed in the app's origin | JS (medium) |
| client upload to attach.Store | untrusted bytes and file name | file content, name (high) |
| bucket or CDN to the browser | stored files served from the app's or a CDN's origin | files (medium) |
| AWS environment to s3blob | credentials outside summer config | AWS credentials (medium) |
| summer.yaml to go build | manifest values become command arguments | build tags (medium) |
| Go app to the site's Nitro purge route | bearer-token POST over loopback or https after admin saves | purge token (high) |
| network to the Nitro purge route | anyone who can reach the site can call the route | purge requests (medium) |
| plugin hooks to the save transaction | hook errors roll back admin writes | hook results (low) |
| Go module proxy to the build | a new test-only module enters go.sum | modules (medium) |
| test harnesses to the network | httptest, miniredis and testcontainers only | test traffic (low) |
| local checkouts to origin | tags and pushes every consumer reads | tags (medium) |
---
## Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation | Status |
|-----------|----------|-----------|----------|-------------|------------|--------|
| T-19.3-01 | Information disclosure | cooler.OpenRedis, Install errors/logs | high | mitigate | cooler/redis.go:15,30-46 fixed error naming `redis.url`, parse error dropped, Addr-only endpoint log; TestOpenRedisRedactsSmoke | closed |
| T-19.3-02 | Denial of service | RateLimitStore during outage | medium | mitigate | ratelimit.go:63-73 attempt timeout + fallback; 500 ms (cooler.go:56); once/min warner (:410-446); memory fallback (surf/serve.go:237) | closed |
| T-19.3-03 | Tampering | Redis key space | medium | mitigate | `<prefix>cache:` / `<prefix>rl:` namespaces; SCAN with escaped glob + UNLINK, no FLUSHDB (rediscache.go:121-146). Residual IN-01 | closed |
| T-19.3-04 | Denial of service | memory cache growth | medium | mitigate | memory.go:40-45 `MaximumSize`, <1 refused; cooler.go:51,304-312 | closed |
| T-19.3-05 | Information disclosure | route:list/tests dialing Redis | low | mitigate | serve.go:83 only `installCooler` caller; router.go:556-566 lookup only; store_lookup_test.go:60 | closed |
| T-19.3-06 | Information disclosure | CORS credentials + `*` | high | mitigate | surf/cors.go:50-51 enforced via LoadCORSConfig and LoadCORSProfiles; TestCORSCredentialsWildcardRefusedSmoke | closed |
| T-19.3-07 | Tampering | shared-cache CORS answers | medium | mitigate | cors.go:240-281 Vary added before the allow check, preflight; :488-503 exact-origin echo | closed |
| T-19.3-08 | Spoofing | token cookie attributes | high | mitigate | bouncer/cookie.go:85-116 Domain validity, production Secure, None requires Secure; HttpOnly hard-coded (:154,:172) | closed |
| T-19.3-09 | Information disclosure | cookie Domain scope | medium | mitigate | cookie.go:82-90 host-only default, Domain opt-in; docs/services/authentication.md:95 | closed |
| T-19.3-10 | Tampering | CSRF on refresh/logout | low | accept | AR-19.3-01. Residual IN-08 | closed |
| T-19.3-11 | Spoofing | Turnstile with no secret | high | mitigate | bouncer/turnstile.go:111-119 production + no secret → 503, success required; production flag from config (router.go:732-733). Residual IN-11 | closed |
| T-19.3-12 | Denial of service | slow siteverify | medium | mitigate | turnstile.go 5 s client + ctx, 4 KiB LimitReader | closed |
| T-19.3-13 | Tampering | body consumed by Turnstile | medium | mitigate | turnstile.go:264-266 read once, restored; body limit wraps route middleware (router.go:513-515); TestTurnstileMiddlewareSmoke. Residual IN-05 | closed |
| T-19.3-14 | Information disclosure | Turnstile secret/token in logs | high | mitigate | secret only in form body; url.Error unwrapped; log carries error text only (turnstile.go:120-241); TestTurnstileNeverLogsSecret | closed |
| T-19.3-15 | Tampering | swagger-ui on jsDelivr | medium | mitigate | surf/apidocs.go:32-66 pinned 5.33.1 with sha384 SRI + crossorigin; nonce-only CSP (:208) | closed |
| T-19.3-16 | Information disclosure | /api-docs surface | low | accept | AR-19.3-02 | closed |
| T-19.3-17 | Tampering (XSS) | api_docs title/spec URL | medium | mitigate | apidocs.go `html/template` contextual escaping (:10,:55-81) | closed |
| T-19.3-18 | Tampering / EoP | stored XSS via disk name | high | mitigate | lagoon/attach/diskext.go:39-77, store.go:170 `DiskExtension(sniffed, ext)`; inline.go:38-44 attachment disposition; storage.md:110-135; TestDiskExtensionTable. Residual IN-07 | closed |
| T-19.3-19 | Information disclosure | public_url exposing files | medium | mitigate | 22-hex random names (store.go:294-300); boot Warn (bucket.go:157-161); storage.md:94 | closed |
| T-19.3-20 | Tampering | build.tags reaching go build | medium | mitigate | internal/build/manifest.go:121-172 validation; build.go:58-78 `exec.CommandContext`, single `-tags=` arg, no shell | closed |
| T-19.3-21 | Repudiation / misconfig | s3:// in an untagged binary | medium | mitigate | attach/bucket.go:106-137 refusal; s3_on.go/s3_off.go; build prints `build tags:` | closed |
| T-19.3-22 | Information disclosure | AWS credentials | medium | mitigate | storage.md:78 no keys in bucket_url/config; no credential keys in attach | closed |
| T-19.3-23 | DoS / Spoofing | shared Nitro purge route | medium | mitigate | seo/server/lib/siteCachePurge.ts:13,54-60 ≥32-char token else 404, proxied → 404, sha256 + timingSafeEqual; purge.post.ts:32-48; route `cache: false` | closed |
| T-19.3-24 | Information disclosure | purge token in Go logs/errors | high | mitigate | cooler/sitecache.go errors/logs name keys, kind, slug, status, host+path only; assertNoToken in sitecache_test.go | closed |
| T-19.3-25 | Information disclosure | token in clear on the network | high | mitigate | sitecache.go:97-132 user info refused, http only to loopback | closed |
| T-19.3-26 | Denial of service | purge breaking saves | medium | mitigate | `WithoutCancel` + 2 s, `lagoon.AfterCommit`, errors logged only (sitecache.go:159,302-309); faq/menu 500-receiver tests | closed |
| T-19.3-27 | Tampering | purge before commit | low | mitigate | AfterCommit (sitecache.go:302-309); `cabana.TxFromContext` in faq, menu, journal site_cache.go | closed |
| T-19.3-28 | Tampering | ReorderAfterSave failing | low | accept | AR-19.3-03 | closed |
| T-19.3-29 | Tampering | three route copies drifting | low | mitigate | superseded: single copy in vue-seo-layer, none left in faq/menu/journal; sha256 pins seo/tests/sitePurge.test.ts:26-39 | closed |
| T-19.3-30 | Repudiation | gate passing on skipped tests | medium | mitigate | scripts/check-phase19.3.sh:195-285 fails on skip/zero/missing; self-test (:357+). See "Gate out of date" | closed |
| T-19.3-31 | Tampering | unverified release | medium | mitigate | 19.3-05 checkpoint; v0.1.27 unmoved on origin, ancestor of v0.2.0 and origin/master | closed |
| T-19.3-32 | Information disclosure | secret-in-logs tests | low | mitigate | TestTurnstileNeverLogsSecret, TestOpenRedisRedactsSmoke, assertNoToken | closed |
| T-19.3-33 | Tampering | profiled-route refusals missing CORS/Vary | medium | mitigate | surf/router.go:462-530 profile wraps recovery/body limit/locale, :905-918 Vary merge; TestCORSProfileHeadersOnRefusals, TestCORSProfileVaryKeptWithHandlerVary | closed |
| T-19.3-34 | Information disclosure | credentialed wildcard/unanchored origins | high | mitigate | cors.go:61-160 anchoring and wildcard host-label rules with probes, per profile; TestCORSCredentialedOriginRules, TestCORSAnchoredPatternNoSuffixMatch. Residual: multi-label public suffix (below) | closed |
| T-19.3-35 | Information disclosure | token forwarded on redirect | high | mitigate | sitecache.go:109-115 `CheckRedirect` → `ErrUseLastResponse`; TestSiteCachePurgeNoRedirect | closed |
| T-19.3-36 | Denial of service | synchronous per-row purges | medium | mitigate | single coalescing worker, Wait, Close drains (sitecache.go:212-277; cooler.go:123-131); async tests | closed |
| T-19.3-37 | Spoofing | allowProxied reachable from the network | medium | mitigate | siteCachePurge.ts:55-59 token check first, `allowProxied !== true` → 404; default false (seo/nuxt.config.ts:58-71); docs/services/caching.md:215 | closed |
| T-19.3-38 | Information disclosure | inferred insecure cookie in production | high | mitigate | cookie.go:107-112 error names `auth.cookie.secure` and `app.url`; TestLoadCookieConfigProductionInferredSecure | closed |
| T-19.3-39 | Information disclosure | zero CookieConfig | medium | mitigate | cookie.go:273-287 zero → Secure, SameSite Lax, used by both handlers; TestZeroCookieConfigDefaults | closed |
| T-19.3-40 | Elevation of privilege | api-docs CSP with host source | medium | mitigate | apidocs.go:65-67,208 nonce-only `script-src`; TestAPIDocsCSPNoHostSource | closed |
| T-19.3-41 | Information disclosure | protected files in a public_url bucket | high | mitigate | attach/store.go:38-42,139-140 refused before body read; boot warning; every bucket via attach.OpenBucket; TestStoreProtectedNeedsPrivateBucket | closed |
| T-19.3-42 | Spoofing | turnstile routes without a secret, unnoticed | medium | mitigate | router.go:710,739-758 one Warn with route count and production flag, never the secret; TestTurnstileEmptySecretWarnsAtBoot. Residual IN-11 | closed |
| T-19.3-43 | Tampering | layer copies drifting | low | mitigate | superseded, as T-19.3-29 | closed |
| T-19.3-44 | Tampering | unverified release / moved tag | medium | mitigate | 19.3-06 checkpoint; v0.2.0 contains 0c8109c and v0.1.27, on origin/master; v0.1.27 unmoved | closed |
| T-19.3-SC (01) | Tampering | go-redis, otter installs | high | mitigate | decision note 2026-10-15-cooler-go-redis-otter.md precedes the go.mod commit; pinned v9.23.0 / v2.3.0 | closed |
| T-19.3-SC (02) | Tampering | installs | high | mitigate | go.mod/go.sum unchanged across the plan; swagger-ui via SRI-pinned CDN | closed |
| T-19.3-SC (03) | Tampering | s3blob / AWS SDK | high | mitigate | gocloud.dev v0.46.0; s3blob only behind `//go:build summercms_s3`; note precedes the go.mod commit | closed |
| T-19.3-SC (04) | Tampering | installs | high | mitigate | framework go.mod unchanged; layer package.json version bumps only; plugin go.mod bumps add only modules the framework already pins | closed |
| T-19.3-SC (05) | Tampering | miniredis install | high | mitigate | human approval recorded (19.3-05-SUMMARY:121-129); pinned v2.40.0; test-only imports | closed |
| T-19.3-SC (06) | Tampering | installs | high | mitigate | go.mod/go.sum unchanged across the plan; layer commits bump versions only | closed |
*Status: open · closed · open — below high threshold (non-blocking)*
*Severity: critical > high > medium > low — only open threats at or above workflow.security_block_on count toward threats_open*
*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
---
## Accepted Risks Log
| Risk ID | Threat Ref | Rationale | Accepted By | Date |
|---------|------------|-----------|-------------|------|
| AR-19.3-01 | T-19.3-10 | Refresh only rotates a cookie (the answer is unreadable cross-origin unless CORS allows that origin); logout CSRF is a forced logout; routes are POST-only and the docs advise JSON or a custom header (authentication.md:97). | 19.3-02 PLAN | 2026-11-05 |
| AR-19.3-02 | T-19.3-16 | /api-docs is off by default; the spec is the app's hand-written public surface (D-16); both routes are public by design (D-17). | 19.3-02 PLAN | 2026-11-05 |
| AR-19.3-03 | T-19.3-28 | The hook runs inside the reorder transaction by design so its failure rolls the reorder back, as FormAfter hooks do; purge hooks never return errors. | 19.3-04 PLAN | 2026-11-05 |
*Accepted risks do not resurface in future audit runs.*
---
## Unregistered Flags and Residual Risk (non-blocking)
1. **Purge token was published in page payloads (fixed after the phase).** The phase's layer versions read the token from `NUXT_SITE_CACHE_PURGE_TOKEN`; nuxt-site-config copies every `NUXT_SITE_*` variable into the public site config. Fixed: the token is now `cachePurge.token` / `NUXT_CACHE_PURGE_TOKEN`, seo/server/plugins/site-cache-purge.ts strips the old keys, and docs/services/caching.md:207 says to rotate. **Action:** confirm every deployment that set the old variable has rotated its token.
2. **Credentialed wildcard on a multi-label public suffix passes boot** (VERIFICATION advisory 1, next to T-19.3-34). `https://*.co.uk` is accepted: `wildcardHostLabel` accepts any non-empty remainder and the probes only cover `.invalid` and `.com`.
3. **Second purge route.** The deprecated `vue-journal-layer/server/api/__journal__/cache/purge.post.ts` predates this phase, still ships, and is not covered by this register.
4. Open review info items from 19.3-REVIEW-DISPOSITION: IN-01 (T-03), IN-05 (T-13), IN-07 (T-18), IN-08 (T-10), IN-11 (T-11/T-42: no log when a published verifier replaces a configured secret).
### Gate out of date
The layers stage of `scripts/check-phase19.3.sh` (lines 175-177, 524) still `cmp`s the purge files inside the faq, menu and journal layers, which moved to vue-seo-layer; that stage would now fail. No threat reopens; T-29/T-43 evidence now comes from vue-seo-layer.
---
## Security Audit Trail
| Audit Date | Threats Total | Closed | Open | Run By |
|------------|---------------|--------|------|--------|
| 2026-11-05 | 50 rows (45 IDs) | 50 | 0 | msd-security-auditor (ASVS L1, block_on high; `go test -short` on cooler, bouncer, surf, lagoon/attach, internal/build: 28 named tests pass, 4 Docker-backed tests not run) |
---
## Sign-Off
- [x] All threats have a disposition (mitigate / accept / transfer)
- [x] Accepted risks documented in Accepted Risks Log
- [x] `threats_open: 0` confirmed
- [x] `status: verified` set in frontmatter
- [ ] Old `NUXT_SITE_CACHE_PURGE_TOKEN` values rotated on every deployment that set them
**Approval:** verified 2026-11-05 (ASVS L1)

View File

@@ -0,0 +1,137 @@
---
phase: "19.4.1"
slug: "early-public-demo-on-demo-summercms-io"
status: verified
# threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
threats_open: 0
asvs_level: 1
created: "2026-11-05"
---
# Phase 19.4.1 — Security
> Per-phase security contract: threat register, accepted risks, and audit trail. Static audit of repository contents (no SSH, no production requests, tests not re-run; test results from the phase gate log and VERIFICATION). Audited: sm-demo-app da03c06 (after Phases 20 and 33), vue-demo-app fe5d38d (the submodule; the sibling `../vue-demo-app` checkout is stale), framework v0.6.1 and the plugin tags go.mod requires. Roots: DEMO = `../sm-demo-app`, VUE = `DEMO/vue-demo-app`, PLG = `DEMO/plugins/golem15`, FW = `summercms.go`.
---
## Trust Boundaries
| Boundary | Description | Data Crossing |
|----------|-------------|---------------|
| ROADMAP.md → client-facing deck | internal phase names include client applications | phase titles and summaries (high) |
| local .env → demo:seed | visitor credentials enter the database | visitor email and password (high) |
| local demo pages → committed screenshots | captures could show secrets or personal data | OIDC and admin PNGs (medium) |
| seeded deck HTML → public deck API | rendered on a public origin | slide HTML (low) |
| internet → nginx (demo.summercms.io) | only allow-listed prefixes reach Go; includes the public login-required `/smbackend` admin (user decision 2026-10-20) | all HTTP traffic, admin login (high) |
| nginx → Go and Nuxt on loopback | trusted proxy 127.0.0.1/32 sets client IP headers | X-Forwarded-For, X-Real-IP (medium) |
| build machine → module proxies and git.golem15.com | tags become immutable inputs for every consumer | plugin tags, go.sum (medium) |
| build machine → rome over SSH | secrets generated on rome or piped, never logged | env values, binaries (high) |
| Stripe → webhook | signed callbacks from the internet | events, Stripe-Signature (high) |
| browser → `/_user/api/v1/register` and `/login` | anonymous, automatable sign-ups and credential attempts | credentials, Turnstile token (high) |
| browser → `/_feedback/api/v1/{key}/submit` | anonymous free text with a public key | name, email, message (medium) |
| Go → Cloudflare siteverify and G15Office | outbound calls carrying secrets | Turnstile secret, G15Office token (high) |
| operator → demo:reset | destructive command on production data | `--force` (high) |
| browser locale cookie → SSR | user-controlled input selecting content | locale value (low) |
| registered user → `/_demo/api/v1/presentations` | untrusted HTML, markdown and settings stored | deck JSON (high) |
| browser → `/api/realtime/token` and `/ws` | authenticated users obtain realtime credentials | JWT, Centrifugo token (high) |
| Centrifugo → `/api/realtime/subscribe` | server-to-server over loopback | X-Centrifugo-Secret, user, channel (high) |
| Go → Centrifugo HTTP API | publishes slide positions | API key, positions (medium) |
| anonymous visitor → `/_demo/api/v1/quizzes` | public read of quiz metadata | slug, title, description, count (medium) |
| test harness → Docker / test fixtures → repositories | throwaway database, test-only secrets | test data (low) |
| check-live.sh → production origin | read-only probes | GETs plus one refused POST (low) |
---
## Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation | Status |
|-----------|----------|-----------|----------|-------------|------------|--------|
| T-19.4.1-01 | Information disclosure | roadmap deck builder | high | mitigate | denylist + case-insensitive `leaks` (DEMO/plugins/demo/roadmap/names.go:8-26); leak check after curated overrides, leaking phases left out, final per-slide guard (deck.go:56-60,143-146); `TestRoadmapNoClientNames` | closed |
| T-19.4.1-02 | Information disclosure | visitor credentials | high | mitigate | `golem15.demo.visitor.*` only, ≥8 chars, never printed (console/seed.go:101-141); empty defaults; dev.sh umask 077, prints key name only; `TestSeedVisitorFromConfig` | closed |
| T-19.4.1-03 | Information disclosure | OIDC screenshots | medium | mitigate | capture-oidc.cjs uses the example client only, never opens the one-time secret screen; user reviewed the images (01 Task 4) | closed |
| T-19.4.1-04 | Tampering | deck HTML | low | accept | AR-19.4.1-01 | closed |
| T-19.4.1-05 | Denial of service | repeated seeding | low | mitigate | old image rows deleted in-tx after import, blobs after commit (console/roadmap_deck.go:109,136-155); `TestSeedRoadmapUpsert` | closed |
| T-19.4.1-06 | Elevation of privilege | admin exposure | high | mitigate | **Re-scoped by the user's decision of 2026-10-20** (the plan's "SSH tunnel only" is superseded): `/backend` → 404 (nginx:78-80), `/smbackend` login-required; `login.max_attempts: 5 / 1 min`; ClientIP takes the rightmost untrusted XFF hop with the Cloudflare real-IP snippet; `X-Robots-Tag noindex`; `TestAdminLoginThrottle`; check-deploy.sh:245-259, check-live.sh:140-150 | closed |
| T-19.4.1-07 | Information disclosure | secrets in repositories | high | mitigate | env examples empty; secret-pattern scan clean in both repos; values generated on rome, 0640 root:summercms-demo, admin password root 0600 (DEPLOY.md). Repo privacy is host-only | closed |
| T-19.4.1-08 | Tampering | one-way plugin tags | medium | mitigate | all 11 phase tags resolve to the commits recorded in the SUMMARYs; scripts/check-pins.sh; `TestGoModRequiresTags` | closed |
| T-19.4.1-09 | Spoofing | Stripe webhook | high | mitigate | signing secret required, `pgstripe.VerifySignature` on raw body (PLG/pgstripe/subscriptions/webhook.go:72-78); empty example. Value on rome is host-only | closed |
| T-19.4.1-10 | Information disclosure | debug pages and permissive CORS | medium | mitigate | production `debug: false`; CORS only `https://demo.summercms.io`; supervisor `SUMMER_ENV="production"`; check-deploy.sh:183 | closed |
| T-19.4.1-11 | Elevation of privilege | unintended Go routes | medium | mitigate | nginx allow-list, `/` GET/HEAD only; check-deploy.sh:268-279 refuses extra `/oauth`, `/.well-known`, `/api` and subscribe locations; PAT APIs `/api/v1/*` unrouted. Narrowed by Phase 19.7 (MCP paths) | closed |
| T-19.4.1-12 | Denial of service | Nuxt site-cache purge | medium | mitigate | purge on 127.0.0.1:3098, no POST reaches Nuxt, route 404s proxied/401s bad token; payload token leak fixed in DEMO 866e58c (`NUXT_CACHE_PURGE_TOKEN`, check-deploy.sh:300-318, smoke checks) | closed |
| T-19.4.1-13 | Information disclosure | credentials on public pages | high | mitigate | empty login fields cleared after submit; FAQ answer "credentials on request"; smoke.sh:256-268 fails on admin links or visitor credentials on 12 SSR pages; check-live `no_admin_link` | closed |
| T-19.4.1-14 | Spoofing | TLS | medium | mitigate | 301 to HTTPS, certbot lineage, HSTS (nginx:50-67); check-live HSTS check. Certificate is host-only | closed |
| T-19.4.1-15 | Denial of service | port collisions | low | mitigate | check-deploy.sh:179-243,364-371 port consistency; port probe on rome is host-only | closed |
| T-19.4.1-16 | Spoofing | bot sign-ups and credential stuffing | high | mitigate | `turnstile: closed`; guard on `/login`, `/register` inside `throttle:user-api`; attempt_limit 5; production without secret → 503 (FW v0.6.1); check-live token-less register → 422; `TestDemoTurnstile` | closed |
| T-19.4.1-17 | Tampering | shared sm-user-plugin behaviour | high | mitigate | default `turnstile: ""` adds nothing, invalid values fail boot (PLG/user/routes.go:63-79); `TestTurnstileRoutes`; no other app sets the key | closed |
| T-19.4.1-18 | Denial of service | contact form spam | medium | mitigate | 10/min per client IP; field limits (message ≤5000); Origin allow-list; no mailer in feedback/demo code | closed |
| T-19.4.1-19 | Information disclosure | Turnstile secret, G15Office token | high | mitigate | empty examples; build-machine secrets file mode 600; values piped over SSH stdin and checked by count only (DEPLOY.md:114-238). File modes host-only | closed |
| T-19.4.1-20 | Tampering | demo:reset deleting kept data | high | mitigate | no-op without `--force`; explicit table list keeps admins, plans, settings, locales, sitemap, OAuth clients; one transaction, blobs after commit; schedule off by default; `TestResetKeepsPlans`; check-local.sh:262-281 | closed |
| T-19.4.1-21 | Tampering | stored XSS via seed or author description | low | mitigate | AuthorCard text interpolation; PostBody `sanitizeJournalHtml` before v-html; curated seed | closed |
| T-19.4.1-22 | Information disclosure | author payload | low | accept | AR-19.4.1-02 (rationale corrected) | closed |
| T-19.4.1-23 | Tampering | locale cookie | low | accept | AR-19.4.1-03 | closed |
| T-19.4.1-24 | Information disclosure | feedback widget key in the page | low | accept | AR-19.4.1-04 | closed |
| T-19.4.1-25 | Tampering | stored XSS and phishing through user decks | high | mitigate | wrapper restricts themes, clears CSS/context, forces unpublished, resets id/hash, 403 on published decks (DEMO/plugins/demo/decks_api.go:38-120); bluemonday sanitize without `<a>` (PLG/presentations/classes/sanitize.go:21-51); reset wipes user decks; `TestDemoDeckWrites`. See residual 3 | closed |
| T-19.4.1-26 | Elevation of privilege | cross-app realtime token reuse | high | mitigate | own Centrifugo with own HMAC secret; HMAC-tagged channels with per-subscribe DB ownership check (PLG/presentations/realtime.go:74-90); guarded token route. Owner-only access clause superseded by Phase 20 (chat community members) | closed |
| T-19.4.1-27 | Spoofing | subscribe proxy | high | mitigate | no nginx location (enforced by check-deploy.sh:273-276, check-live); constant-time `X-Centrifugo-Secret` compare, empty refused (FW lighthouse/centrifugo/handlers.go:112-113); `TestRealtimeRoutes` | closed |
| T-19.4.1-28 | Information disclosure | Centrifugo keys and remote key | high | mitigate | `CHANGE_ME_*` placeholders enforced by check-deploy.sh:213-219; empty env examples; generated on rome 0640; health prints only `api_key_set` | closed |
| T-19.4.1-29 | Spoofing | WebSocket from other sites | medium | mitigate | `allowed_origins: ["https://demo.summercms.io"]`, no insecure/anonymous flags; check-live refuses a foreign Origin | closed |
| T-19.4.1-30 | Denial of service | deck writes and token route | medium | mitigate | 256 KiB body, ≤60 slides, `throttle:20,1`; realtime bucket 120/min per user | closed |
| T-19.4.1-31 | Information disclosure | quiz answers to anonymous visitors | medium | mitigate | public list returns slug, title, description, count only; quiz API behind `jwt.auth`; `TestDemoQuizList` | closed |
| T-19.4.1-32 | Elevation of privilege | another user's decks | medium | mitigate | owner from JWT (`mineCaller`); no owner field, `DisallowUnknownFields`; queries scoped by owner_user_id | closed |
| T-19.4.1-33 | Information disclosure | test fixtures and logs | medium | mitigate | test-only secrets; fake siteverify; smoke uses random tokens and passwords, never echoed | closed |
| T-19.4.1-34 | Tampering | regression of mitigations from plans 01-04 | high | mitigate | pinning test per threat (T-01, 02, 05, 16, 17, 20, 25, 26, 27, 31; smoke/check-live for T-06, T-13); scripts/check-all.sh | closed |
| T-19.4.1-35 | Denial of service | check-live against production | low | accept | AR-19.4.1-05 | closed |
| T-19.4.1-SC | Tampering | npm/pip/cargo installs (plans 01-05) | high | mitigate | only `centrifuge 5.7.3` and `vitest 3.2.7` added, exact pins; `protobufjs: false`; `--frozen-lockfile`, `GOWORK=off`, `GOPRIVATE`; go.sum committed; no replace (go_mod_test.go:31) | closed |
*Status: open · closed · open — below high threshold (non-blocking)*
*Severity: critical > high > medium > low — only open threats at or above workflow.security_block_on count toward threats_open*
*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
---
## Accepted Risks Log
| Risk ID | Threat Ref | Rationale | Accepted By | Date |
|---------|------------|-----------|-------------|------|
| AR-19.4.1-01 | T-19.4.1-04 | Seeded content is curated in the repository and every field passes `classes.Clean` at render; text values are HTML-escaped by the builder (`para()` uses `esc()`). | 19.4.1-01 PLAN | 2026-11-05 |
| AR-19.4.1-02 | T-19.4.1-22 | Plan rationale: "only subtitle, description and avatar are added; email and login data stay out of authorColumns." **Corrected:** `login` is selected (PLG/journal/controllers/api/authors.go:27-28) and published as `slug` when the author slug is empty. Holds in practice: the demo's only author is `summercms-team` (no superuser, no role, unusable password). A post by a real admin without an author slug would publish that admin's login name while `/smbackend` is public. | 19.4.1-03 PLAN (corrected by audit) | 2026-11-05 |
| AR-19.4.1-03 | T-19.4.1-23 | Only en and pl are accepted by the i18n module; any other value falls back to the default. | 19.4.1-03 PLAN | 2026-11-05 |
| AR-19.4.1-04 | T-19.4.1-24 | Public by design; the Origin allow-list and throttles gate it. | 19.4.1-03 PLAN | 2026-11-05 |
| AR-19.4.1-05 | T-19.4.1-35 | A handful of GET requests and one refused POST per run, inside the existing throttles. | 19.4.1-05 PLAN | 2026-11-05 |
*Accepted risks do not resurface in future audit runs.*
---
## Residual Risk and Notes (non-blocking)
1. **T-06 register row is stale in 19.4.1-02-PLAN.md** ("admin only through an SSH tunnel"). The verified mitigation is the login-required public `/smbackend` described above (user decision 2026-10-20; 02-SUMMARY flag `auth-surface`, 03-SUMMARY "Threat model update").
2. **Later phases changed mitigations:** T-11 (Phase 19.7 routes MCP and OAuth metadata paths; check-deploy enforces the narrower list) and T-26 (Phase 20 gives realtime tokens to chat community members; presentations channels still HMAC-tagged and ownership-checked). Belongs in those phases' audits.
3. **The deck wrapper (T-25) is the only public deck write path while** nginx does not route `/api/v1/presentations` **and** demo users lack `golem15.presentations.access_presentations` (needed by the Phase 19.7 presentations MCP tools, incl. `presentations_publish` and deck CSS; no demo group grants it today). If either changes, users get a write path that skips the wrapper's CSS, publish and theme rules.
4. **AR-19.4.1-02 wording** corrected above (author `login` published as slug).
5. **Local-only admin password literal:** DEMO/scripts/dev.sh:48 `ADMIN_PASSWORD=AdminDemo123!` for the local dev admin, reused as a fallback in smoke-seo.sh:74. Not a production credential, but a committed literal in a private repo.
6. **UAT:** 19.4.1-UAT.md is `testing` with 3 pending items. Item 1 (purge token in the payload) is fixed in 866e58c; DEPLOY.md:1046-1055 records the rotation on rome on 2026-10-20 (host-only). Items 2-3 are UAT, not threats.
### Host-only checks (not verifiable from the repos)
Repository privacy on git.golem15.com; rome file modes (`.env`, `site.env` 0640 root:summercms-demo, admin file 0600, centrifugo.json 0640); Stripe and Turnstile secrets present on rome; reset schedule off on rome; certbot certificate and Cloudflare real-IP snippet; port probe; purge-token rotation; build machine's 0600 secrets file.
---
## Security Audit Trail
| Audit Date | Threats Total | Closed | Open | Run By |
|------------|---------------|--------|------|--------|
| 2026-11-05 | 36 | 36 | 0 | msd-security-auditor (ASVS L1, block_on high; static, repo contents only) |
---
## Sign-Off
- [x] All threats have a disposition (mitigate / accept / transfer)
- [x] Accepted risks documented in Accepted Risks Log
- [x] `threats_open: 0` confirmed
- [x] `status: verified` set in frontmatter
- [ ] Host-only checks confirmed on rome / git.golem15.com
**Approval:** verified 2026-11-05 (ASVS L1, repository evidence)

View File

@@ -45,7 +45,7 @@ A third fix found by the tests is functional, not a security gap: c29d228 `fix(p
| T-19.7-07 | `payload` is accepted only for an action with a Prompt, only as a JSON string, trimmed, non-empty and capped in runes; every other record action still refuses a payload; a plain action runs with an empty Value. | F `cabana/actions.go:217`, `:256` | `TestRecordActionPromptSmoke`, `TestRecordActionPrompt`, `TestRecordActionPromptRun` (F) | verified |
| T-19.7-08 | Contributed labels, statuses, messages and URLs render as text and attributes (no `v-html`); a URL opens with `noopener` and the visible link carries `rel="noopener noreferrer"`. | F `admin/src/components/account/AccountContributions.vue` | `admin/tests/account/AccountContributions.test.ts` ("Text, never HTML", URL attributes) (F) | corrected: fixed in 44835e4, 88559d5 (F); was verified (see Corrections) |
| T-19.7-09 | wristband's authorize allow-list is exactly `Options.ScopesSupported`; the default server refuses `backend`; `openid` and unlisted scopes stay refused on the MCP flavour. | F `wristband/authorize.go:31`, `:231` | `TestMCPScopesSmoke`, `TestMCPScopes` (F) | verified |
| T-19.7-10 | Every request re-verifies its bearer (`auth.RequireBearerToken` with pier's resolver); a session never replaces it; a failure is 401 with the RFC 9728 challenge and `scope="read"`. | F `pier/pier.go:235-260`; F `pier/identity.go:144` | `TestPierTracerSmoke` (bad bearer), `TestEndpointGuards` (stream ends after revocation), `TestMCPEndToEnd` "revoked token" (F, D) | verified |
| T-19.7-10 | Every request re-verifies its bearer (`auth.RequireBearerToken` with pier's resolver); a session never replaces it; a failure is 401 with the RFC 9728 challenge naming only `resource_metadata` (no scope parameter since quick 261106-kt1, so clients request the PRM `scopes_supported`). | F `pier/pier.go:256-274`; F `pier/identity.go:144` | `TestPierTracerSmoke` (bad bearer, missing bearer), `TestEndpointGuards` (stream ends after revocation), `TestMCPEndToEnd` "revoked token" (F, D) | verified |
| T-19.7-11 | The session record stores only the binding (`oauth:<client>:<user>` or the personal token id), compared on every POST, GET and DELETE (403 `session_binding`); ids from `rand.Text()`; sliding idle TTL; per-binding cap. | F `pier/session.go:143`, `:211`, `:242`, `:139` | `TestPierSessionsSmoke`, `TestSessions` (Redis and memory) (F) | verified |
| T-19.7-12 | The inner request is built fresh (`httptest.NewRequestWithContext`) with no Authorization or Cookie; identity travels only in the marker; client address, X-Forwarded-For, X-Real-IP and Accept-Language are copied. | F `pier/dispatch.go:159-180` | `TestPierTracerSmoke` (echo route `auth: false`), `TestDispatch` (outer Cookie and Authorization absent) (F) | verified |
| T-19.7-13 | A backend subject exists only with `backend` in the grant AND a link the resolver confirms per request (5 s cache), or an admin `g15_` token behind `mcp.allow_personal_tokens`; the read/write ceiling applies on top; list and call use the same `allowed`. | F `pier/identity.go:152`, `:187-198`; F `pier/filter.go:16`, `:37` | `TestToolsList` (no link, no backend tool; union with a link), `TestPierTracerSmoke` "personal tokens behind the flag", `TestMCPEndToEnd` (no backend tool without the scope) (F, D) | verified |

View File

@@ -0,0 +1,153 @@
---
phase: "20"
slug: "demo-instance-with-every-shared-plugin"
status: verified
# threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
threats_open: 0
asvs_level: 1
created: "2026-11-05"
---
# Phase 20 — Security
> Per-phase security contract: threat register, accepted risks, and audit trail. Static audit of repository contents (no SSH, no ls-remote, no host contact). Audited: sm-demo-app da03c06 with plugin submodules on their tags (chat v0.1.5, forum v0.1.2, moderation v0.1.1, chatvideo/herald/userfriends v0.1.1, chatchannels/chatbots v0.1.0); vue-demo-app pins vue-chat-layer v0.1.1, vue-chatvideo-layer v0.1.1, vue-forum-layer v0.1.0, vue-userfriends-layer v0.1.0. Paths are relative to `../` (the meta repo). One medium threat (T-20-32) is open and non-blocking.
---
## Trust Boundaries
| Boundary | Description | Data Crossing |
|----------|-------------|---------------|
| chat/forum HTTP clients → plugin APIs | message and post bodies untrusted; the saving seam runs before storage | message content, thread title, Markdown, JWT (high) |
| host listeners → plugin services | the host decides refusals; listener errors must not leak internals | saving events, Rejection, errors (medium) |
| admin settings → moderation filter | admins edit lists every message is matched against | banned word/link entries (medium) |
| build machine → git.golem15.com / proxies / origin | tags become immutable inputs of every consumer | tags, pushes, go.sum, pnpm lock (medium) |
| browser → /_demo, /_chat, /_chatchannels, /_chatbots, /_chatvideo, /_forum, /_userfriends | every request untrusted; actor only from the JWT | JWT, JSON, uploads ≤5 MiB (high) |
| Centrifugo subscribe proxy → Go / browser → Centrifugo | client channel names, authorized server-side | channel names, connection tokens, X-Centrifugo-Secret (high) |
| seed/reset commands → DB | trusted operator commands; persona accounts must stay unusable | persona rows, random bcrypt hashes (medium) |
| Go → LiveKit RoomService (loopback) / browser → LiveKit | admin calls signed with the API secret; WebRTC with short-lived join token | admin JWT, join token (TTL 900), media, ICE (high) |
| members' content → other members' browsers | untrusted text, links, cards, content_html, names | rendered content (high) |
| realtime events → incoming-call prompt | server payloads about other users | session_id, conversation_id, caller_name (low) |
| npm / git → layers | third-party (livekit-client) and own layers | packages, lockfile integrity (medium) |
| internet → nginx (Cloudflare) / rome public 7891/tcp, 7892/udp | six API prefixes plus /livekit/; WebRTC media straight to LiveKit | HTTP, WS, SRTP, ICE (high) |
| build machine → rome (SSH) | secrets generated on rome; releases and rsync | binaries, configs (high) |
| demo services ↔ WavePath on the same host | must stay isolated | ports, supervisor programs, LiveKit config (high) |
| test harnesses / browser checks → local and live demo | throwaway accounts, visitor creds, live JWT files | JWTs (0600 files), probe content (medium) |
| build machine → summercms.io | journal token publishing changelog posts | g15_ token (high) |
---
## Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation | Status |
|-----------|----------|-----------|----------|-------------|------------|--------|
| T-20-01 | Tampering | chat write paths that skip the seam | high | mitigate | MessageSaving fired on the only message insert and content update (sm-chat-plugin classes/service.go:314-337, writes.go:267-276); forum equivalents; TestMessageSavingTracer/Rejects. Chatbots announce path inserts without the seam but is unreachable on the demo (Ephemeral commands) | closed |
| T-20-02 | Information disclosure | listener errors in API bodies | medium | mitigate | only Rejection → 422, everything else opaque 500 (chat/forum api/errors.go) on every write handler | closed |
| T-20-03 | Denial of service | filter matching cost | medium | mitigate | QuoteMeta + RE2, recompile only on list change; 500 entries / 200 chars enforced in BeforeValidate | closed |
| T-20-04 | Elevation of privilege | moderation settings screen | medium | mitigate | `PermissionManageSettings`, role `developer`, enforced by cabana | closed |
| T-20-05 | Tampering | one-way module tags | medium | mitigate | all family tags annotated, on origin/main, monotonic | closed |
| T-20-06 | Elevation of privilege | channel creation by members | high | mitigate | `CanManageContext` always false (plugins/demo/classes/chat_context.go:272-274); tests refuse member and moderator | closed |
| T-20-07 | Information disclosure | subscribing to other conversations | high | mitigate | chat/user/video authorizers admit only own or participant channels; all namespaces via subscribe proxy. Residual IN-02 | closed |
| T-20-08 | Spoofing | persona accounts | medium | mitigate | `personas.demo.invalid` emails, random bcrypt hashes never printed; reset reseeds | closed |
| T-20-09 | Elevation of privilege | moderator rights | medium | mitigate | group conversations only, member + moderator group, banned users excluded, live membership required; group seeded empty | closed |
| T-20-10 | Tampering | spam/abuse in chat and forum | high | mitigate | moderation listeners on both seams; rate buckets (chat 120/min, DM 10/min, forum, video-initiate 5/min); Turnstile `closed`; manual demo:reset (schedule off in production). Residual WR-03 | closed |
| T-20-11 | Denial of service | realtime token minting | low | mitigate | JWT + membership guard, 120/min per user | closed |
| T-20-12 | Information disclosure | LiveKit and VAPID secrets (local) | high | mitigate | dev.sh umask 077, names only echoed; empty examples; CHANGE_ME placeholders enforced by check-deploy.sh:391-399 | closed |
| T-20-13 | Denial of service | stale chat-family rows after reset | low | mitigate | reset lists chat-family tables before users; reset tests | closed |
| T-20-14 | Tampering | stored XSS (text, names, URLs) | high | mitigate | vue-chat-layer v-html only through the escaping renderer; safeUrl, rel noopener noreferrer nofollow; linkify on escaped text with honestHttpUrl | closed |
| T-20-15 | Information disclosure | JWT handling in the layer | medium | mitigate | token from auth.token() as Bearer to same-origin bases; no web storage or cookie use | closed |
| T-20-16 | Information disclosure | attachment downloads | medium | mitigate | bearer download, object URL; server checks CanView | closed |
| T-20-17 | Spoofing | slash command answers | low | mitigate | `/` text dispatched, never posted; local ephemeral row marked "only you" | closed |
| T-20-18 | Tampering | layer supply chain | medium | mitigate | exact pins; layers pinned by tag and locked to commits | closed |
| T-20-19 | Denial of service | realtime connections | low | mitigate | single Centrifuge client; bounded polling | closed |
| T-20-20 | Tampering | forum stored XSS | high | mitigate | v-html only on server-rendered content_html; `breakwater.Render` (bluemonday) on write; server-side preview | closed |
| T-20-21 | Spoofing | call joins | high | mitigate | requireParticipant on start/join, token TTL 900, max 4 participants; layer never builds tokens | closed |
| T-20-22 | Information disclosure | camera and microphone | medium | mitigate | media only after handoff/click; disconnect stops tracks; leave on pagehide/unmount | closed |
| T-20-23 | Tampering | incoming-call payloads | low | mitigate | text binding for caller name; positive integer ids only | closed |
| T-20-24 | Denial of service | call spam | medium | mitigate | video-initiate 5/min, max_duration 900, reconcile job; DM-only slot in the UI. Residual IN-01 | closed |
| T-20-25 | Information disclosure | friend enumeration | low | mitigate | generic 422 shown as is; directory = chat picker set | closed |
| T-20-26 | Information disclosure | VAPID private key | high | mitigate | never printed; empty example; no `/_herald` route in Nuxt or nginx, enforced by check-deploy.sh:405-409 | closed |
| T-20-27 | Elevation of privilege | LiveKit co-tenancy with WavePath | high | mitigate | own supervisor program, config, user, ports, key pair; WavePath config untouched (DEPLOY.md:355-410). Host state live-only | closed |
| T-20-28 | Information disclosure | LiveKit, VAPID, Centrifugo secrets (rome) | high | mitigate | generated on rome, `install -m 0640 root:summercms-demo`, written via stdin, unset; placeholders enforced. File modes live-only | closed |
| T-20-29 | Denial of service | open media ports | medium | mitigate | only 7891/tcp and 7892/udp via Vuurmuur; participant and timeout limits. Firewall live-only | closed |
| T-20-30 | Information disclosure | origin IP in ICE candidates | low | accept | AR-20-01 | closed |
| T-20-31 | Elevation of privilege | unintended Go routes | medium | mitigate | six chat-family locations + `/livekit/`, no /_herald, `/backend` 404; check-deploy.sh. Residual IN-06 | closed |
| T-20-32 | Tampering | firewall drift | medium | mitigate | Vuurmuur change and removal documented (DEPLOY.md:467-490), but **no dated rules.conf backup**; DEPLOY.md:475-476 points to a "Probed on rome on 2026-10-31" section (:94-102) that lists no rules | open — below high threshold (non-blocking) |
| T-20-33 | Denial of service | a release breaking the live demo | medium | mitigate | `.prev` binary and site kept, rollback documented, check-live after release; clean-tree builds | closed |
| T-20-34 | Spoofing | signalling WebSocket | low | mitigate | tokens only after requireParticipant (TTL 900); `/rtc/validate` 401 without token | closed |
| T-20-35 | Information disclosure | credentials in tests and check output | medium | mitigate | visitor password read from `.env`, never printed; failures name keys only. Residual IN-03 (argv) | closed |
| T-20-36 | Tampering | regressions behind skipped tests | medium | mitigate | check-all.sh runs suites without `-short`; container start failure fails tests; PLAN verifies count `--- PASS` lines | closed |
| T-20-37 | Denial of service | throwaway accounts on the live demo | low | accept | AR-20-02 (rationale corrected) | closed |
| T-20-38 | Spoofing | banned-link matching | high | mitigate | sm-moderation-plugin normalize.go canonical links (dots, percent-decode, last `@`, port, IDNA, path); TestMatchBypassLinks | closed |
| T-20-39 | Tampering | banned-word matching | high | mitigate | entity decode, NFKC, Cf/Cc drop, space folding, diacritics, markup strip; two passes; TestMatchBypassWords | closed |
| T-20-40 | Tampering | forum Markdown rendered after the check | high | mitigate | PostSaving.HTML carries rendered HTML; demo runs CheckHTML on it; forum, moderation and demo tests | closed |
| T-20-41 | Denial of service | normalising and matching large texts | low | accept | AR-20-03 | closed |
| T-20-42 | Information disclosure | useCall: media after leave | critical | mitigate | per-attempt `stale()` checks at every await; stale branch drops the Room; tests cover seven moments | closed |
| T-20-43 | Elevation of privilege | /call/{id} opened from a link | high | mitigate | confirmation unless an in-memory 60 s single-use handoff exists | closed |
| T-20-44 | Information disclosure | chat store, socket, call prompt after logout | high | mitigate | isolated sign-out steps; reset, disconnect, dismiss wired; communityAuth tests; check-chat.cjs requires `/ws` closed in 5 s | closed |
| T-20-45 | Denial of service | empty ringing session after a failed connect | medium | mitigate | closeFailed ends sessions with ≤1 participant; tests | closed |
| T-20-46 | Spoofing | deceptive hosts in anchors and cards | high | mitigate | `honestHttpUrl` (vue-chat-layer urlGuard.ts:28-48) on every link path; tests | closed |
| T-20-47 | Tampering | release tags | high | mitigate | annotated, on origin/main, monotonic; ls-remote and fast-forward recorded in 20-09-SUMMARY | closed |
| T-20-48 | Information disclosure | live member JWTs | high | mitigate | mode 600/400 required, header via `curl -K -` stdin; delete afterwards documented and recorded. Deletion live-only | closed |
| T-20-49 | Tampering | probe content on the live demo | medium | mitigate | scope limited to own DM and seeded thread; stored probes deleted and reported; controls refused first | closed |
| T-20-50 | Information disclosure | journal token | high | mitigate | changelog-post.py own token file, refuses readable-by-others, never printed | closed |
| T-20-51 | Denial of service | the shared host during a release | medium | mitigate | restarts only the demo programs; rollback; pids recorded. Pid check live-only | closed |
| T-20-52 | Tampering | temporary integration leaking into a release | medium | mitigate | clean-tree builds, GOWORK=off, frozen lockfile; tag-only pins; no go.mod replace | closed |
| T-20-SC | Tampering | npm / Go installs (plans 01-09) | high | mitigate | every new module matches an already-vetted version (sitemap or framework); livekit-client 2.23.0 exact with lock integrity and human checkpoint; `protobufjs: false`; later plans change only golem15 modules and layer tags | closed |
*Status: open · closed · open — below high threshold (non-blocking)*
*Severity: critical > high > medium > low — only open threats at or above workflow.security_block_on count toward threats_open*
*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
---
## Accepted Risks Log
| Risk ID | Threat Ref | Rationale | Accepted By | Date |
|---------|------------|-----------|-------------|------|
| AR-20-01 | T-20-30 | rome already exposes services on its public address; the ICE candidates show it (DEPLOY.md:367-369). | 20-05 PLAN | 2026-11-05 |
| AR-20-02 | T-20-37 | check-live registers no accounts (its token-less register expects 422). **Corrected:** the plan said the reset job removes the human UAT account, but the reset schedule is off in production (DEPLOY.md:945-946, 1006-1009), so UAT accounts stay until someone runs `demo:reset --force` by hand. | 20-09 PLAN (corrected by audit) | 2026-11-05 |
| AR-20-03 | T-20-41 | RE2 is linear, lists are bounded by max_entries and max_entry_length, and the work is two passes over a message the plugins already cap in size. | 20-07 PLAN | 2026-11-05 |
*Accepted risks do not resurface in future audit runs.*
---
## Open Below Threshold
| Threat | Severity | Gap | To close (any one) |
|--------|----------|-----|--------------------|
| T-20-32 | medium | no dated `rules.conf` backup before the Vuurmuur change; DEPLOY.md's substitute reference points at a section without the rules | take a dated `rules.conf.bak-<date>` on rome, record the 15 pre-change RULE lines in DEPLOY.md's "Probed on rome" section, or record an accepted risk |
---
## Unregistered Flags and Residual Risk (non-blocking)
- **Unregistered (20-02):** `GET /_demo/api/v1/chat/members` (sm-demo-app/plugins/demo/chat_api.go) lists every member's name, surname and handle to any member; IN-09 adds that the GET writes handles and builds an unbounded `IN` list (500 above 65535 members). Todo `demo-chat-members-read-only.md`.
- Deferred review items, each with a pending todo: WR-02 (any member can pin/unpin in public channels), WR-03 (profile names, friend-group names and attachment filenames are not moderated), WR-06 (forum/friends clients lack 401 refresh), IN-01 (no server-side DM-only call rule), IN-02 (video join token survives a ban up to 900 s), IN-03 (member JWTs and — found by this audit — the visitor password at check-local.sh:333 in curl argv), IN-04, IN-05, IN-06 (nginx `/livekit/` exposes LiveKit's whole HTTP surface incl. admin-JWT-protected RoomService), IN-07, IN-08 (VAPID runbook without `pipefail`).
- Untracked: the 19.4.1 Centrifugo secrets runbook (DEPLOY.md:327-328) passes secrets as `sed` arguments on rome (not echoed; noted in 20-05 deviation 3, not fixed).
### Host-only checks (not verifiable from the repos)
WavePath LiveKit untouched and pid unchanged (T-20-27, T-20-51); file modes of `livekit.yaml`, `.env`, `centrifugo.json` (T-20-28); the applied Vuurmuur rule (T-20-29, T-20-32); live JWT files deleted (T-20-48); `RESET__ENABLED` count 0.
---
## Security Audit Trail
| Audit Date | Threats Total | Closed | Open | Run By |
|------------|---------------|--------|------|--------|
| 2026-11-05 | 53 | 52 | 1 (medium, non-blocking) | msd-security-auditor (ASVS L1, block_on high; static, repo contents only) |
---
## Sign-Off
- [x] All threats have a disposition (mitigate / accept / transfer)
- [x] Accepted risks documented in Accepted Risks Log
- [x] `threats_open: 0` confirmed
- [x] `status: verified` set in frontmatter
- [ ] T-20-32 closed (backup or recorded rules) or accepted
- [ ] Host-only checks confirmed on rome
**Approval:** verified 2026-11-05 (ASVS L1; T-20-32 open below threshold)

View File

@@ -0,0 +1,161 @@
---
phase: 31-chat-polish-against-wavepath-clients
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- modules/tide/normalize.go
- modules/tide/variables.go
- modules/tide/record.go
- modules/tide/replay.go
- modules/tide/diff.go
- modules/tide/rules.go
- modules/tide/flow.go
- modules/tide/fixture.go
- modules/tide/manifest.go
- modules/tide/rules_test.go
- modules/tide/relative_smoke_test.go
- modules/tide/additions_smoke_test.go
- modules/tide/README.md
- docs/services/parity-testing.md
autonomous: true
requirements: [SC-4, D-06, D-11, D-12]
estimate:
tokens: 150000
raw_tokens: 150000
tasks: 2
confidence: low
must_haves:
truths:
- "Tide core data contracts: relative masks, cookies, headers, labels, repeat and manifest reference is delivered against the frozen PHP corpus and locked decisions."
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
artifacts:
- path: "modules/tide/normalize.go"
provides: "Tide core data contracts: relative masks, cookies, headers, labels, repeat and manifest reference"
key_links:
- from: "modules/tide/normalize.go"
to: "the plan's automated verification"
via: "the named tracer and fail-closed checks"
---
## Phase Goal
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
<objective>
Tide core data contracts: relative masks, cookies, headers, labels, repeat and manifest reference.
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
Output: the artifacts and machine evidence named below.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
</context>
<tasks>
<task type="tracer">
<name>Task 1: Tracer: a relative-time string recorded from a reference server replays against a port on another day (tide gap T-1), documented</name>
<precondition>`go test -count=1 -short ./modules/tide/` passes and `go run ./cmd/summer docs:build --check` prints `docs:build: no problems found` before the change.</precondition>
<files>modules/tide/normalize.go, modules/tide/relative_smoke_test.go, modules/tide/README.md, docs/services/parity-testing.md</files>
<read_first>modules/tide/normalize.go (whole file: maskLeaf, maskDate, isDateKey, disabledPath, the mask constants), modules/tide/normalize_phase13_test.go (the table style and neutral names), modules/tide/roundtrip_test.go (how a test records with RecordFlow against httptest and replays with ReplayFlow), modules/tide/README.md (Features "Replay and diff", API reference), docs/services/parity-testing.md (the masking sentences in "Flows" and "The parity commands"), 31-PATTERNS.md "tide T-1"</read_first>
<action>Per D-11 (every message row of the corpus carries a relative-time string) and SC-4.
1. Red first: write `modules/tide/relative_smoke_test.go` (package `tide`) with `TestRelativeTimeMaskSmoke`. A "reference" `httptest` server answers a JSON body holding an id, a title and a key `updated_at_human` with the value `3 weeks ago`. Record a one-step flow with `RecordFlow`, save it with `SaveFlow`, load it with `LoadFlow`, and replay it with `ReplayFlow` against three "port" servers: one answering `5 weeks ago` (expect no diff), one answering the number 7 at that key (expect exactly one `Diff` whose path ends in that key), and one answering `5 weeks ago` while the step carries a normalize rule disabling that key (expect one `Diff`). Run it and see it fail.
2. `normalize.go`: add a predicate for keys ending in `_human` next to `isDateKey`, and a mask function in the style of `maskDate`: `nil` stays `nil`; a non-empty string becomes a fixed mask token (add a constant next to the date mask token, value `{{relative}}`); anything else (a non-string, an empty string) appends a `Diff` naming the expected shape and returns the value unchanged. Call it from `maskLeaf` after the `disabledPath` check and before the id branch. A mask never hides a wrong shape.
3. `modules/tide/README.md`: in Features "Replay and diff", add one sentence: keys ending in `_human` are relative-time strings compared by shape, and a step can switch the mask off with a `normalize` rule. `docs/services/parity-testing.md`: the same fact where masking of IDs and timestamps is described, with a neutral example.
4. Commit: `feat(tide): compare relative-time strings by shape`.</action>
<verify>
<automated>go vet ./modules/tide/ &amp;&amp; go test -count=1 -short ./modules/tide/ &amp;&amp; go test -count=1 -run '^TestRelativeTimeMaskSmoke$' -v ./modules/tide/ 2&gt;&amp;1 | grep -q -- '^--- PASS: TestRelativeTimeMaskSmoke'</automated>
<fails_when>Non-zero exit: vet or an existing tide test fails, or the `--- PASS: TestRelativeTimeMaskSmoke` line is absent (the test failed, or the filter matched nothing and go printed "no tests to run").</fails_when>
<automated>go run ./cmd/summer docs:build --check 2&gt;&amp;1 | grep -q 'no problems found'</automated>
<fails_when>Non-zero exit: the docs checker printed a problem list instead of `docs:build: no problems found`.</fails_when>
</verify>
<acceptance_criteria>
- `grep -c '_human' modules/tide/normalize.go` prints at least 1 and `grep -c '_human' modules/tide/README.md` prints at least 1.
- `go test -count=1 -run '^TestRelativeTimeMaskSmoke$' -v ./modules/tide/` prints `--- PASS: TestRelativeTimeMaskSmoke`.
- `D="$(git diff 2acf8e4 -- modules/tide docs cmd/summer/parity.go)" &amp;&amp; printf '%s\n' "$D" | grep '^+' | grep -ciE 'wavepath|_wave/|wave_guest|hubot|fonoteka'` prints 0 (the diff is captured first, so a failing git is not read as a clean result).
- `git diff --stat 2acf8e4 -- go.mod go.sum` prints nothing.
</acceptance_criteria>
<done>A fixture whose rows say "3 weeks ago" replays against a backend that says "5 weeks ago", a wrong shape still fails, and the README and the docs page say so.</done>
</task>
<task type="auto" tdd="true">
<name>Task 4: Cookie captures, extra response headers, any client label, repeated requests and the manifest's reference revisions (tide gaps T-6, T-7, T-8, T-10; D-12)</name>
<files>modules/tide/variables.go, modules/tide/record.go, modules/tide/replay.go, modules/tide/diff.go, modules/tide/rules.go, modules/tide/rules_test.go, modules/tide/flow.go, modules/tide/fixture.go, modules/tide/manifest.go, modules/tide/additions_smoke_test.go, modules/tide/README.md, docs/services/parity-testing.md, docs/console/utilities.md</files>
<read_first>modules/tide/variables.go (lines 20-40 the scrub patterns, 265-350 extractCapture, 685-750 the two uses of cookieRe), modules/tide/rules.go (lines 14-16, 50-65, 137-141 filterHeaders joining Set-Cookie with a newline), modules/tide/rules_test.go (lines 54-56), modules/tide/record.go (lines 17-60 the RecordFlow loop, 118-140), modules/tide/replay.go (the step loop and line 109), modules/tide/diff.go (lines 35-80), modules/tide/flow.go (Step, Request, CaptureRule), modules/tide/fixture.go (lines 48, 135-166: the strict loader and writeStep, writeRequest), modules/tide/manifest.go (Manifest, RouteCase, recordRoute's Step literal, mergeHeaders, caseRequest), modules/tide/headers_test.go, modules/tide/capture_test.go (the capture test style), modules/tide/proxy.go (where the client label becomes a directory name), modules/tide/README.md (Features "Capture rules", the Manifest rows), docs/services/parity-testing.md (the capture-source sentence in "The parity commands"), 31-PATTERNS.md "tide T-6" to "tide T-10" and finding F-9</read_first>
<behavior>
- `TestCookieCaptureSmoke` (T-6): a response with two Set-Cookie headers; a rule `from: response.cookie`, `name: session_ref` captures that cookie's value into the store; a missing cookie is the error "missing response cookie session_ref"; the saved fixture holds the placeholder and not the value, in the Set-Cookie header and in a later request's Cookie header; a JWT-shaped value in a cookie of any name that no rule captured refuses the write.
- `TestExtraHeadersSmoke` (T-7): a case with `headers: {Retry-After: present, X-RateLimit-Limit: exact}` records both headers; replay passes when Retry-After differs but is non-empty and X-RateLimit-Limit is equal; it reports `header.X-Ratelimit-Limit` when that value differs and `header.Retry-After` when it is missing; a header that is in no list is not recorded.
- `TestClientLabelSmoke` (T-8): rules with client `bot` and `web-app` load; `nuxt` and `mcp` still load; an empty label, a label with a slash, a dot or an upper-case letter is refused.
- `TestRepeatSmoke` (T-10): a case with `repeat: 3` against a server that answers 200 twice and then 429 records one response with status 429 and the server saw three requests; replay sends three and compares the last; `repeat: 0` and an absent field mean one request; `repeat: 1001` is a validation error; a flow with `repeat` saved and loaded keeps the value.
- `TestManifestReferenceSmoke` (D-12): a manifest with a `reference` map of two entries parses and `Manifest.Reference` holds them; a manifest without it parses; an unknown top-level key is still refused.
</behavior>
<action>Per D-11 (the guest cookie credential, the ten rate-bucket cases, Range and rate-limit headers), D-07 and D-17 (a recording client that is neither of the two existing labels) and D-12.
1. T-6, `variables.go`: add the capture source `response.cookie` to `extractCapture`: parse the recorded `Set-Cookie` value (several cookies are joined with a newline by `filterHeaders`) and return the value of the cookie named `rule.Name`; error text in the style of the other sources. Replace the single-name cookie pattern in the scrubber: detect `name=value` pairs in `Cookie` and `Set-Cookie` headers for any cookie name, mask a value that equals a vars entry with that variable's placeholder, redact in logs as before, and refuse a token-shaped value that is not masked, whatever the cookie is called.
2. T-7, `record.go`, `diff.go`, `replay.go`: `keepResponseHeaders` takes the step and also keeps every header named in `Step.Headers`. `compareHeaders` reads the map values as a mode: empty or `exact` compares the value, `present` requires a non-empty value on both sides; any other mode is a validation error when the flow or manifest is loaded.
3. T-8, `rules.go`: accept any client label matching lower-case letters, digits, hyphen and underscore, 1 to 32 characters, starting with a letter or digit. Keep `ClientNuxt` and `ClientMCP`. Update `rules_test.go:54-56` in the same commit (F-8): the label that used to fail now loads, and the refused shapes are tested instead.
4. T-10, `flow.go`, `fixture.go`, `manifest.go`, `record.go`, `replay.go`: add `Repeat int` (yaml `repeat,omitempty`) to `Step` and to `RouteCase`; `recordRoute` copies it into the step. `RecordFlow` and the replay loop send the request that many times in a row (0 and 1 mean once; above 1000 is refused at validation) and keep, capture from and compare only the last response. Add the field to `writeStep` so a saved flow loads again (F-9).
5. D-12, `manifest.go`: add `Reference map[string]string` (yaml `reference,omitempty`) to `Manifest`, documented as the source revisions of the reference backend the corpus was recorded from (repository name to commit). `ValidateManifest` refuses an empty name or an empty revision.
6. `additions_smoke_test.go`: the behavior block.
7. `modules/tide/README.md`: Features "Capture rules" (the cookie source), "Replay and diff" (header modes), "Manifests" (repeat, reference), the client label rule; API reference rows where a described type gained a field. `docs/services/parity-testing.md`: the capture-source list gains `response.cookie`; one paragraph each for extra headers and for repeat. `docs/console/utilities.md` only if a described flag or behaviour changed.
8. Before the commit run `go vet ./... &amp;&amp; go test -count=1 -short ./...` once for the whole repo and record the result (a failure outside tide, cmd/summer and docs is reported, not fixed). Commit: `feat(tide): cookie captures, extra headers, client labels, repeat and manifest reference`. Then post the g15office comment on task `hgol7otp`.</action>
<verify>
<automated>go vet ./modules/tide/ ./cmd/summer/ &amp;&amp; go test -count=1 -short ./modules/tide/ ./cmd/summer/ &amp;&amp; go test -count=1 -run '^(TestCookieCaptureSmoke|TestExtraHeadersSmoke|TestClientLabelSmoke|TestRepeatSmoke|TestManifestReferenceSmoke)$' -v ./modules/tide/ 2&gt;&amp;1 | grep -c -- '^--- PASS: Test' | grep -qx 5</automated>
<fails_when>Non-zero exit: vet fails, an existing tide or cmd/summer test fails (a fixture or manifest written before this plan no longer loads, the round-trip test breaks), or fewer than five `--- PASS: Test` lines are printed.</fails_when>
<automated>go run ./cmd/summer docs:build --check 2&gt;&amp;1 | grep -q 'no problems found' &amp;&amp; go test -count=1 -run '^TestDocsTree$' -v ./cmd/summer 2&gt;&amp;1 | grep -q -- '^--- PASS: TestDocsTree'</automated>
<fails_when>Non-zero exit: the docs checker reports a problem, or the `--- PASS: TestDocsTree` line is absent.</fails_when>
</verify>
<acceptance_criteria>
- `grep -c '"response.cookie"' modules/tide/variables.go` prints at least 1, and `TestCookieCaptureSmoke` passes with a cookie name that tide's source does not mention.
- `grep -c 'yaml:"repeat,omitempty"' modules/tide/flow.go modules/tide/manifest.go | awk -F: '{s+=$2} END {print s}'` prints 2 and `grep -c 'yaml:"reference,omitempty"' modules/tide/manifest.go` prints 1.
- `go test -count=1 -run '^TestRoundTrip' -v ./modules/tide/ 2>&1 | grep -c '^--- FAIL'` prints 0.
- `D="$(git diff 2acf8e4 -- modules/tide docs cmd/summer/parity.go)" &amp;&amp; printf '%s\n' "$D" | grep '^+' | grep -ciE 'wavepath|_wave/|wave_guest|hubot|fonoteka'` prints 0 (the diff is captured first, so a failing git is not read as a clean result).
- `git diff --stat 2acf8e4 -- go.mod go.sum` prints nothing.
- `git status --porcelain -- modules/tide cmd/summer/parity.go cmd/summer/parity_test.go docs/services/parity-testing.md docs/console/utilities.md` prints nothing (everything committed).
</acceptance_criteria>
<done>A corpus can log in with a cookie that exists only in Set-Cookie, assert rate-limit and range headers, be recorded by a client with any label, hit a rate bucket in one case, and name the commits it was recorded from.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
| automated evidence to completion verdict | missing or skipped work must not look green |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-31-01 | Information disclosure | upstream sidecars with minted credentials (T-4) | high | mitigate | a credential is rewritten only for a declared host, header and scheme; the token itself is never written, only the listed claims; `WriteUpstream` keeps refusing every other unmasked credential; `TestMintedCredentialSmoke` asserts the sidecar holds no JWT-shaped string and that an undeclared host is still refused |
| T-31-02 | Information disclosure | cookie values in fixtures (T-6) | high | mitigate | captured cookie values go to the mode-0600 vars store; the scrubber masks any cookie value equal to a vars entry and refuses a token-shaped cookie value under any name; `TestCookieCaptureSmoke` |
| T-31-06 | Denial of service | `repeat` and `--wait` | low | mitigate | `repeat` is bounded at 1000 and validated on load; `--wait` is a bounded duration and listeners are loopback only |
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
</threat_model>
<verification>
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
</verification>
<success_criteria>
Tide core data contracts: relative masks, cookies, headers, labels, repeat and manifest reference is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
</success_criteria>
<output>
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-01-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
</output>

View File

@@ -0,0 +1,163 @@
---
phase: 31-chat-polish-against-wavepath-clients
plan: 02
type: execute
wave: 2
depends_on: [31-01]
files_modified:
- modules/tide/centrifugo.go
- modules/tide/centrifugo_golden.go
- modules/tide/manifest.go
- modules/tide/upstream.go
- modules/tide/upstream_proxy.go
- modules/tide/centrifugo_test.go
- modules/tide/sidecar_smoke_test.go
- modules/tide/upstream_smoke_test.go
- cmd/summer/parity.go
- cmd/summer/parity_test.go
- modules/tide/README.md
- docs/services/parity-testing.md
- docs/console/utilities.md
autonomous: true
requirements: [SC-2, SC-4, D-06, D-10, D-11]
estimate:
tokens: 180000
raw_tokens: 180000
tasks: 2
confidence: low
must_haves:
truths:
- "Tide per-case broadcast/upstream sidecars, minted credentials, body comparers and CLI wiring is delivered against the frozen PHP corpus and locked decisions."
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
artifacts:
- path: "modules/tide/centrifugo.go"
provides: "Tide per-case broadcast/upstream sidecars, minted credentials, body comparers and CLI wiring"
key_links:
- from: "modules/tide/centrifugo.go"
to: "the plan's automated verification"
via: "the named tracer and fail-closed checks"
---
## Phase Goal
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
<objective>
Tide per-case broadcast/upstream sidecars, minted credentials, body comparers and CLI wiring.
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
Output: the artifacts and machine evidence named below.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
</context>
<tasks>
<task type="auto" tdd="true">
<name>Task 2: One manifest run records a broadcast sidecar and an upstream sidecar for every case, with a reset hook before each (tide gaps T-2, T-3, T-9)</name>
<files>modules/tide/manifest.go, modules/tide/centrifugo.go, modules/tide/centrifugo_golden.go, modules/tide/upstream_proxy.go, modules/tide/centrifugo_test.go, modules/tide/sidecar_smoke_test.go, cmd/summer/parity.go, cmd/summer/parity_test.go, modules/tide/README.md, docs/services/parity-testing.md, docs/console/utilities.md</files>
<read_first>modules/tide/manifest.go (ManifestConfig, RecordManifest, recordRoute, caseFixturePath, ReplayManifest and its per-case loop), modules/tide/centrifugo.go (whole file), modules/tide/centrifugo_golden.go (whole file, and the doc comment of NormalizePublications that lists every rule), modules/tide/upstream_proxy.go (UpstreamProxy, NewUpstreamProxy, scripted, Flush, ListenAndServe), modules/tide/upstream.go (UpstreamPath, WriteUpstream), modules/tide/centrifugo_test.go (lines 17-68: postJSON, the assertions F-8 names), modules/tide/normalize_phase13_test.go (lines 53-60), cmd/summer/parity.go (parityRecordCommand, parityReplayCommand, runParityUpstream, the flag lists), cmd/summer/parity_test.go, modules/tide/README.md (API reference rows for the recorder, goldens and the proxy; "CLI commands"), docs/services/parity-testing.md ("Broadcast goldens", "Upstream exchanges"), docs/console/utilities.md (the parity flag table), 31-PATTERNS.md "tide T-2", "tide T-3", "tide T-9", ../fonoteka.go/parity/broadcast_goldens_test.go (lines 210-241, the unordered comparison this plan generalises; read only)</read_first>
<behavior>
- `TestManifestCaseSidecarsSmoke`: a reference `httptest` server whose POST route publishes one message to the in-process recorder and calls one HTTPS vendor URL through the in-process upstream proxy, and whose GET route does neither. `RecordManifest` over a two-route manifest with `Recorder`, `Upstream` and `BeforeCase` set writes: both fixtures; `BroadcastPath(postFixture)` holding one publication; `UpstreamPath(postFixture)` holding one exchange; no sidecar of either kind for the GET case. The hook was called once per case, in order, with that route and case. `ReplayManifest` in self-check mode with the recorder attached passes, and fails with a publication diff after the sidecar on disk is edited.
- `TestBroadcastPayloadMaskSmoke` (T-3): two publications whose payload holds `edited_at` and `read_at` at depth 2 and 3 with different Carbon dates, and a `created_at_human` with different strings, normalise equal; a date written with a `Z` suffix where the golden has a Carbon offset stays visible as a diff.
- `TestRecorderPresenceAndUnsubscribeSmoke` (T-9): with `RecordUnsubscribe` set, an unsubscribe call is recorded as a `Publication`; with a presence table for one channel, a presence call for that channel answers one client entry per listed user id and another channel answers the empty result; with neither option the behaviour of the existing tests is unchanged.
- `DiffPublicationsUnordered` returns no diff for the same publications in another order and a diff when one body differs.
</behavior>
<action>Per D-10 (a golden for every writing case), D-11 (vendor calls as sidecars) and D-06 (unattended).
1. `centrifugo_golden.go`: add `BroadcastPath(fixturePath string) string` (maps `x.yaml` or `x.yml` to `x.broadcasts.yaml`, mirroring `UpstreamPath`). Add `DiffPublicationsUnordered(expected, actual []Publication) []Diff` (both sides sorted by normalised body, then `DiffPublications`). Add `DiffCaseBroadcasts(fixturePath string, pubs []Publication, store *Store, unordered bool) ([]Diff, error)`: loads the golden at `BroadcastPath(fixturePath)` (a missing file means a golden with zero publications), normalises `pubs` with `NormalizePublications` and diffs. T-3: in `normalizer.walk`, mask every string value under `$.data.payload.` whose key ends in `_at` and that matches the Carbon offset form or an ISO-8601 form, at any depth, and mask keys ending in `_human` under the payload with the Task 1 rule. Keep the id rule as it is (an id becomes a placeholder only when it equals a captured `id:*` variable). Update the doc comment of `NormalizePublications`.
2. `centrifugo.go` (T-9): add two fields to `CentrifugoRecorderOptions`: `RecordUnsubscribe bool` (an `/unsubscribe` call is stored as a `Publication` like a publish) and `Presence map[string][]string` (channel name to user ids; a `/presence` call for a listed channel answers a `result.presence` object with one synthetic client entry per user id, each carrying `client` and `user`; other channels answer the empty result as today). Defaults keep today's behaviour.
3. `upstream_proxy.go`: add `(*UpstreamProxy).Begin(out string) error` (sets the sidecar path of the next `Flush`, clears the recorded exchanges and errors, and makes every script entry available again; for a non-empty `out` the CA directory and the vars file must be outside its directory, as `NewUpstreamProxy` checks for `Out`; an empty `out` resets the proxy and sets no path) and `(*UpstreamProxy).Recorded() int`. `NewUpstreamProxy` accepts an empty `Out` when the proxy is driven through `Begin`; `Flush` with no path set is an error.
4. `manifest.go`: add `type CaseHook func(ctx context.Context, route Route, c RouteCase) error` and four `ManifestConfig` fields: `BeforeCase CaseHook`, `Recorder *CentrifugoRecorder`, `BroadcastSettle time.Duration`, `Upstream *UpstreamProxy`. In `recordRoute`, per case: call `BeforeCase` (an error aborts the run and names the case); `Recorder.Reset()`; `Upstream.Begin(UpstreamPath(dest))`; `RecordFlow`; wait `BroadcastSettle` (default `DefaultBroadcastSettle`); when the recorder holds publications, normalise them, refuse a body containing the API key (as `RecordBroadcasts` does) and write a `BroadcastGolden` named after the case to `BroadcastPath(dest)`; when it holds none, write no sidecar and, under `Update`, remove a stale one; `Upstream.Flush()` only when `Recorded()` is above zero, else remove a stale sidecar under `Update`. In `ReplayManifest`, per case: `BeforeCase`, `Recorder.Reset()`, `Upstream.Begin("")` (on replay the proxy answers from its script and nothing is flushed), replay, settle, and when `Recorder` is set compare with `DiffCaseBroadcasts` (unordered); a publication diff makes the case failing.
5. `cmd/summer/parity.go`: on `parity:record` and `parity:replay`, manifest mode only (each is an error without `--manifest`): `--broadcasts` (true/false: attach a recorder), `--centrifugo-listen` (default `tide.DefaultCentrifugoListen`), `--api-key` (default `$PARITY_CENTRIFUGO_API_KEY`), `--settle` (default `tide.DefaultBroadcastSettle`), `--presence` (a YAML file with one key `channels`, mapping a channel name to a list of user ids; names and ids are expanded with the vars store when the file is loaded), `--record-unsubscribe` (true/false), `--upstream-script` (attach an upstream proxy in script mode), `--upstream-listen` (default `tide.DefaultUpstreamProxyListen`), `--ca-dir`, `--case-hook` (path to an executable file, run directly with no shell before each case, with the environment variables `PARITY_ROUTE_ID`, `PARITY_CASE_ID` and `PARITY_SEED_HOOK`; a missing or non-executable file is refused at start, a non-zero exit aborts the run), `--wait` (a Go duration: after the listeners are bound, wait up to this long for `--target` to accept TCP connections before the first request; default 0). Every listen address must be loopback. The command prints the CA certificate path when a proxy is attached. Update the help text and the examples of both commands.
6. `centrifugo_test.go`: keep the existing assertions for the default options and add the option cases (F-8). `sidecar_smoke_test.go`: the behavior block. `cmd/summer/parity_test.go`: a help-output check that `parity:record` lists `--case-hook`, `--broadcasts` and `--upstream-script`, and that `--broadcasts true` without `--manifest` is an error.
7. `modules/tide/README.md`: Features (per-case sidecars; presence and unsubscribe options; payload-wide masks), API reference rows for `tide.BroadcastPath`, `tide.DiffCaseBroadcasts`, `tide.DiffPublicationsUnordered`, `tide.CaseHook`, `tide.ManifestConfig` and the two new proxy methods, and the changed description of `tide.NormalizePublications`; "CLI commands": a manifest-mode example with the new flags (neutral paths). `docs/services/parity-testing.md`: "Broadcast goldens" gains the per-case sidecar workflow and "Upstream exchanges" the per-case recording. `docs/console/utilities.md`: the flag lists of `parity:record` and `parity:replay`.
8. Commit: `feat(tide): per-case broadcast and upstream sidecars in manifest recording`.</action>
<verify>
<automated>go vet ./modules/tide/ ./cmd/summer/ &amp;&amp; go test -count=1 -short ./modules/tide/ ./cmd/summer/ &amp;&amp; go test -count=1 -run '^(TestManifestCaseSidecarsSmoke|TestBroadcastPayloadMaskSmoke|TestRecorderPresenceAndUnsubscribeSmoke)$' -v ./modules/tide/ 2&gt;&amp;1 | grep -c -- '^--- PASS: Test' | grep -qx 3</automated>
<fails_when>Non-zero exit: vet fails, an existing tide or cmd/summer test fails (including the F-8 assertions and TestDocsTree), or fewer than three `--- PASS: Test` lines are printed for the three named smoke tests.</fails_when>
<automated>go run ./cmd/summer docs:build --check 2&gt;&amp;1 | grep -q 'no problems found'</automated>
<fails_when>Non-zero exit: the docs checker reports an identifier, link, anchor or command name that does not exist.</fails_when>
</verify>
<acceptance_criteria>
- `grep -c 'func BroadcastPath' modules/tide/centrifugo_golden.go` prints 1 and `grep -c 'BeforeCase' modules/tide/manifest.go` prints at least 2.
- `go run ./cmd/summer help parity:record 2>&1 | grep -c -- 'case-hook'` prints at least 1.
- `grep -c 'case-hook' docs/console/utilities.md` prints at least 1 and `grep -c 'tide.BroadcastPath' modules/tide/README.md` prints at least 1.
- `go test -count=1 -run '^TestCentrifugoRecorder' -v ./modules/tide/ 2>&1 | grep -c '^--- FAIL'` prints 0.
- `D="$(git diff 2acf8e4 -- modules/tide docs cmd/summer/parity.go)" &amp;&amp; printf '%s\n' "$D" | grep '^+' | grep -ciE 'wavepath|_wave/|wave_guest|hubot|fonoteka'` prints 0 (the diff is captured first, so a failing git is not read as a clean result).
</acceptance_criteria>
<done>A porter can record a whole manifest with one command and get, next to every fixture, the publications and vendor calls that case caused, each case starting from a reset state; replaying against the reference backend proves the goldens are reproducible.</done>
</task>
<task type="auto" tdd="true">
<name>Task 3: Upstream sidecars hold signed and encrypted vendor calls (tide gaps T-4, T-5)</name>
<files>modules/tide/upstream.go, modules/tide/upstream_proxy.go, modules/tide/upstream_smoke_test.go, modules/tide/README.md, docs/services/parity-testing.md</files>
<read_first>modules/tide/upstream.go (whole file: UpstreamCompareHeaders at 118-128, binaryScalar at 84-116, NewUpstreamFake at 195, RoundTrip at 200-229, compare at 252, WriteUpstream at 573, the credential refusal at 635-638 and fullyMasked and credentialResidueRe at 655-666), modules/tide/upstream_proxy.go (loadUpstreamScript, UpstreamScript, how a recorded request is built around lines 420-450), modules/tide/upstream_test.go (lines 16-60: upstreamTestSidecar, upstreamCall and its send helper, the neutral host), modules/tide/testdata/upstream/post_json.upstream.yaml, modules/tide/README.md (the Upstream rows and the security rules under "CLI commands"), docs/services/parity-testing.md ("Upstream exchanges", "Recording through the proxy", "Replaying offline"), 31-PATTERNS.md "tide T-4, T-5", ../fonoteka.go/parity/upstream_replay_test.go (lines 50-55: the existing callers of NewUpstreamFake whose signature must not change; read only)</read_first>
<behavior>
- `TestMintedCredentialSmoke`: an upstream script declares a minted credential for host `api.example.test`, header `Authorization`, scheme `Bearer`, claims `iss` and `video`. The proxy records a request carrying a bearer JWT. The written sidecar holds no JWT-shaped string; the header value is the scheme followed by a placeholder; the two claims are recorded. The fake accepts a replayed request with a different token whose `iss` and `video` claims match, and reports a problem when `iss` differs or the scheme differs. A request with a bearer token to a host that is not declared still refuses the write with the existing error.
- The same for a header value in the form scheme word, a `t=` parameter holding a JWT and a `k=` parameter holding a key that is in the vars store: the token becomes the placeholder and the key is masked by its variable.
- `TestUpstreamBodyComparerSmoke`: a fake with a comparer registered for a content type receives the expected and the actual body bytes and its returned problems fail `Verify`; with `OpaqueBody` registered, two different non-empty bodies pass and an empty body fails; with no comparer the existing JSON and byte comparison is unchanged.
</behavior>
<action>Per D-11 (LiveKit and web-push calls are recorded and asserted) and threat T-31-01.
1. T-4 in `upstream.go` and `upstream_proxy.go`: add `type MintedCredential struct` with fields `Host` (exact, or with a leading `*.` wildcard), `Header`, `Scheme` (the auth scheme word) and `Claims []string` (JWT claim names compared by value on replay; `exp`, `iat`, `nbf` and `jti` are never compared and are refused in the list). `UpstreamScript` gains a top-level `minted` list, and `UpstreamProxyConfig` gains `Minted []MintedCredential` for callers that build the config in code. When the proxy records a request whose host and header match a declaration and whose value starts with the declared scheme, the first JWT-shaped token in the value is replaced by a fixed placeholder (`{{minted}}`), and the exchange's request records the declaration that matched and the values of the listed claims (decoded from the token's payload without verifying the signature). Add the fields to the sidecar structs, the YAML writer and the strict loader. `WriteUpstream` keeps refusing any credential header that is neither masked by a vars entry nor rewritten by a declaration; do not relax `fullyMasked` for anything else. The fake's `compare`: for a request recorded with a minted declaration, the actual header must have the same scheme and, when claims were recorded, the same claim values; the placeholder is never compared as text.
2. T-5 in `upstream.go`: add `type UpstreamBodyComparer func(expected, actual []byte, contentType string) []string`, `type UpstreamBodyMatch struct` with `Host` (exact or `*.` wildcard, optional) and `ContentType` (prefix, optional; at least one of the two is required), `(*UpstreamFake).SetBodyComparer(match UpstreamBodyMatch, cmp UpstreamBodyComparer)`, and `OpaqueBody` (an `UpstreamBodyComparer` that reports a problem only when exactly one side is empty). `compare` consults the first matching comparer for the body only; headers, method and URL are compared as before. Keep the signature of `NewUpstreamFake`.
3. `upstream_smoke_test.go`: the behavior block, with the builder style and neutral host of `upstream_test.go`.
4. `modules/tide/README.md`: Features and API reference rows for `tide.MintedCredential`, `tide.UpstreamBodyComparer`, `tide.UpstreamBodyMatch`, `tide.OpaqueBody` and the new method on `tide.UpstreamFake`; the security rules gain one sentence: a credential is written only as a variable placeholder or, when declared as minted, as a scheme and a placeholder. `docs/services/parity-testing.md`: "Upstream exchanges" explains minted credentials and body comparers with a neutral vendor.
5. Commit: `feat(tide): minted credentials and body comparers for upstream sidecars`.</action>
<verify>
<automated>go vet ./modules/tide/ &amp;&amp; go test -count=1 -short ./modules/tide/ ./cmd/summer/ &amp;&amp; go test -count=1 -run '^(TestMintedCredentialSmoke|TestUpstreamBodyComparerSmoke)$' -v ./modules/tide/ 2&gt;&amp;1 | grep -c -- '^--- PASS: Test' | grep -qx 2</automated>
<fails_when>Non-zero exit: vet fails, an existing upstream test fails (the default credential refusal changed, or an old sidecar no longer loads), or fewer than two `--- PASS: Test` lines are printed.</fails_when>
<automated>go run ./cmd/summer docs:build --check 2&gt;&amp;1 | grep -q 'no problems found'</automated>
<fails_when>Non-zero exit: the docs checker reports a problem.</fails_when>
</verify>
<acceptance_criteria>
- `grep -c 'type MintedCredential struct' modules/tide/upstream.go modules/tide/upstream_proxy.go | awk -F: '{s+=$2} END {print s}'` prints 1.
- `grep -c 'func (f \*UpstreamFake) SetBodyComparer' modules/tide/upstream.go` prints 1 and `grep -c 'func NewUpstreamFake(s UpstreamSidecar, store \*Store) \*UpstreamFake' modules/tide/upstream.go` prints 1.
- `go test -count=1 -run '^TestUpstream' -v ./modules/tide/ 2>&1 | grep -c '^--- FAIL'` prints 0.
- `grep -c 'tide.MintedCredential' modules/tide/README.md` prints at least 1.
</acceptance_criteria>
<done>A vendor call signed with a fresh token, or carrying an encrypted body, can be recorded without a secret in the sidecar and asserted on replay by scheme, claims and an application-supplied body comparer.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
| automated evidence to completion verdict | missing or skipped work must not look green |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-31-03 | Elevation of privilege | `--case-hook` executes a program | medium | mitigate | the flag takes a path to an executable file and runs it directly with no shell; route and case ids are passed as environment variables, never interpolated into a command line; a missing or non-executable file is refused at start |
| T-31-04 | Spoofing | masks and opaque comparers hiding real differences | medium | mitigate | every mask is shape-checked and emits a `Diff` on a wrong shape; the opaque comparer and every body comparer are opt-in per host or content type; a step can disable the relative-time mask; defaults are unchanged and pinned by the existing tests |
| T-31-05 | Information disclosure | broadcast sidecars | medium | mitigate | the per-case writer reuses the API-key body check of `RecordBroadcasts`; the authorization header is stored as a boolean only; `WriteBroadcastGolden` keeps refusing token-shaped bodies |
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
</threat_model>
<verification>
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
</verification>
<success_criteria>
Tide per-case broadcast/upstream sidecars, minted credentials, body comparers and CLI wiring is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
</success_criteria>
<output>
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-02-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
</output>

View File

@@ -0,0 +1,224 @@
---
phase: 31-chat-polish-against-wavepath-clients
plan: 03
type: execute
wave: 1
depends_on: []
files_modified:
- ../sm-wavepath-app/.gitmodules
- ../sm-wavepath-app/summer.yaml
- ../sm-wavepath-app/go.mod
- ../sm-wavepath-app/go.work
- ../sm-wavepath-app/app/app.go
- ../sm-wavepath-app/plugins/golem15/wavepath/
- ../sm-wavepath-app/config/app.yaml
- ../sm-wavepath-app/parity/pins.env
- ../sm-wavepath-app/parity/parity.env
- ../sm-wavepath-app/parity/php_parity.sh
- ../sm-wavepath-app/parity/case_hook.sh
- ../sm-wavepath-app/scripts/parity-stack.sh
- ../sm-wavepath-app/parity/README.md
- ../sm-wavepath-app/README.md
autonomous: false
requirements: [SC-1, D-01, D-02, D-05, D-08, D-20, D-21]
estimate:
tokens: 200000
raw_tokens: 200000
tasks: 4
confidence: low
must_haves:
truths:
- "sm-wavepath-app skeleton and fail-closed isolated PHP parity stack is delivered against the frozen PHP corpus and locked decisions."
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
artifacts:
- path: "../sm-wavepath-app/.gitmodules"
provides: "sm-wavepath-app skeleton and fail-closed isolated PHP parity stack"
key_links:
- from: "../sm-wavepath-app/.gitmodules"
to: "the plan's automated verification"
via: "the named tracer and fail-closed checks"
---
## Phase Goal
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
<objective>
sm-wavepath-app skeleton and fail-closed isolated PHP parity stack.
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
Output: the artifacts and machine evidence named below.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
</context>
<tasks>
<task type="tracer">
<name>Task 1: Tracer: one route goes from PHP at the pinned commits to a recorded fixture, a green PHP self-replay, a pending manifest entry the Go harness loads and a gate that prints the pending count</name>
<reversibility rating="costly">D-02: the repository name, module path and parity/ layout are what WavePath's agent and every later WavePath phase build on; a rename later touches every import. Task 5 asks before the first push.</reversibility>
<precondition>`../sm-wavepath-app` does not exist; `docker info` answers; `GIT_OPTIONAL_LOCKS=0 git -C /media/nvme/dev/jz/wavepath.org cat-file -t 7c517191879cada7bb50ac05f474f3ac02ad4b98` prints `commit` and `GIT_OPTIONAL_LOCKS=0 git -C /media/nvme/dev/jz/wavepath.org/plugins/golem15/chat cat-file -t fbfbcf98e3392269c6e98801270669dc5d845b3b` prints `commit`.</precondition>
<files>../sm-wavepath-app/.gitignore, ../sm-wavepath-app/.gitmodules, ../sm-wavepath-app/summer.yaml, ../sm-wavepath-app/go.mod, ../sm-wavepath-app/go.sum, ../sm-wavepath-app/go.work, ../sm-wavepath-app/main.go, ../sm-wavepath-app/plugins.gen.go, ../sm-wavepath-app/boot_test.go, ../sm-wavepath-app/config/app.yaml, ../sm-wavepath-app/app/app.go, ../sm-wavepath-app/plugins/golem15/wavepath/go.mod, ../sm-wavepath-app/plugins/golem15/wavepath/plugin.go, ../sm-wavepath-app/plugins/golem15/wavepath/README.md, ../sm-wavepath-app/parity/pins.env, ../sm-wavepath-app/parity/parity.env, ../sm-wavepath-app/parity/php_parity.sh, ../sm-wavepath-app/parity/wavepath_reset.php, ../sm-wavepath-app/parity/fixtureplugin/plugin.go, ../sm-wavepath-app/parity/fixtureplugin/seed.go, ../sm-wavepath-app/parity/manifest.yaml, ../sm-wavepath-app/parity/fixtures/seed/bootstrap.yaml, ../sm-wavepath-app/parity/fixtures/routes/GET___wave_api_v1_community_friends_jwt.yaml, ../sm-wavepath-app/parity/parity_test.go, ../sm-wavepath-app/parity/testmain_test.go, ../sm-wavepath-app/scripts/parity-stack.sh, ../sm-wavepath-app/scripts/check-parity.sh</files>
<read_first>../sm-demo-app/summer.yaml, ../sm-demo-app/go.mod, ../sm-demo-app/go.work, ../sm-demo-app/.gitmodules, ../sm-demo-app/boot_test.go, ../sm-demo-app/testmain_test.go, ../sm-demo-app/plugins/demo/plugin.go (lines 35-126), ../fonoteka.go/go.mod, ../fonoteka.go/go.work, ../fonoteka.go/app/app.go, ../fonoteka.go/parity/php_parity.sh (whole file), ../fonoteka.go/parity/fonoteka_reset.php (lines 1-100 and 640-676), ../fonoteka.go/parity/fixtureplugin/plugin.go, ../fonoteka.go/parity/fonoteka_seed_test.go (lines 1-80 and 600-660), ../fonoteka.go/parity/manifest.yaml (lines 1-40), ../fonoteka.go/parity/parity_test.go (lines 40-210), ../fonoteka.go/parity/synthetic_test.go (lines 36-104), ../fonoteka.go/parity/fixtures/seed/bootstrap.yaml, modules/tide/README.md ("Usage", "CLI commands"), 31-RESEARCH.md ("Recording commit and pins", "PHP stack from outside the checkout", "The sm-wavepath-app skeleton"), 31-PATTERNS.md (the sections for summer.yaml, app/app.go, manifest.yaml, php_parity.sh, wavepath_reset.php, fixtureplugin and parity_test.go). From the PHP contract, read-only with `git show`: the route at `routes.php` line 616 (`GET community/friends`), `controllers/api/CommunityFriendsController.php` (index), `classes/responses/ApiResponse.php`, and the code that issues the session JWT at login</read_first>
<action>Per D-02, D-01, D-08, D-20, D-04, D-21 and D-15.
1. Repository: `git init -b master ../sm-wavepath-app`. `.gitignore` covers the built binary `wavepath`, `tmp/`, `*.vars`, `*.vars.yaml` and editor files. `summer.yaml`: module `git.golem15.com/golem15/sm-wavepath-app`, binary `wavepath`, the eight shared plugin entries in the order of the interfaces block, then `golem15.wavepath` with module `git.golem15.com/golem15/sm-wavepath-app/plugins/golem15/wavepath`. Add the eight shared plugins as submodules at `plugins/golem15/NAME` with `ssu` (or `git submodule add -b BRANCH`), each checked out at the released tag listed in the interfaces block. `go.mod` requires the framework and the plugins at those tags and replaces the framework with `../summercms.go`; `go.work` uses `.`, the eight submodule directories and `./plugins/golem15/wavepath`, and carries the framework replace. Check each plugin's go.mod for other `replace` lines and override any in go.work.
2. App plugin shell `plugins/golem15/wavepath` (own go.mod, package `wavepath`): `const ID = "golem15.wavepath"`, a `Plugin` type holding `*backpack.App`, `Requires()` returning the eight shared plugin ids, `Register` and `Boot` that only store the app, `init()` calling `party.Register`, compile-time assertion for `party.Plugin`. README in the module README structure (H1, one sentence, import line, Overview, Usage, Testing), marked as the start of WavePath's Go app.
3. `app/app.go`: `PluginIDs` (the nine ids) and `Handler` in the shape of fonoteka's, with the nine plugins blank-imported. `config/app.yaml`: the application config the binary and tests load, with test-only values only. Generate `plugins.gen.go` and `main.go` with the `summer build` command (install the CLI with `go install ./cmd/summer` from `summercms.go`, then run `summer build` in the app directory); do not hand-write them. `boot_test.go`: `TestBootAllPlugins` in the shape of the demo's.
4. `parity/pins.env`: `KEY=value` lines for `SUPERPROJECT`, and one `PIN_NAME` per pinned repository (wavepath, chat, chatchannels, chatbots, chatvideo, forum, herald, userfriends, user, websockets, oauthserver, journal, and the three clients), with full 40-character ids read from `git ls-tree 7c517191879cada7bb50ac05f474f3ac02ad4b98` in the checkout. They must agree with the research table; a difference is reported, not resolved silently. `parity/parity.env`: the test-only overlay values as `KEY=value` data: `APP_KEY`, `JWT_SECRET`, `CENTRIFUGO_API_KEY`, `CENTRIFUGO_SECRET` (at least 32 bytes), `CENTRIFUGO_PROXY_SECRET`, a VAPID pair generated once for tests, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET`, `TURNSTILE_SECRET`, `TURNSTILE_SITE_KEY`, and a JWT lifetime long enough for a whole recording run.
5. `parity/php_parity.sh` (bash, `set -euo pipefail`, structure of fonoteka's): variables `WAVEPATH_SRC` (default `/media/nvme/dev/jz/wavepath.org`), `PARITY_ROOT` (default `${XDG_CACHE_HOME:-$HOME/.cache}/summercms/wavepath-parity`), `PARITY_INSTANCE` (default `corpus`), `PHP_ROOT="$PARITY_ROOT/$PARITY_INSTANCE/php"`, vars file `$PARITY_ROOT/$PARITY_INSTANCE/vars.yaml` (mode 0600). Subcommands for the tracer:
- `export`: with `GIT_OPTIONAL_LOCKS=0`, archive the superproject at `SUPERPROJECT` into `PHP_ROOT`, then every gitlink that `git ls-tree -r` lists at that commit (recursively) from its own repository directory at the recorded commit; a missing commit object is a refusal naming the repository (never fetch there). Copy `vendor/` with `rsync -a` (source read-only), and any other untracked directory Composer installed that the application needs to boot. Write `PHP_ROOT/.parity-export` listing each path and commit. Never copy `.env`.
- `db`: start (or reuse) the container `wavepath-parity-mariadb` from the local image `mariadb:11`, published on `127.0.0.1:33306` only, and create the database `wavepath_parity_$PARITY_INSTANCE`.
- `export_env` (a function): refuse a database name without `parity` or a non-loopback host; export `DB_*`, `CACHE_DRIVER=file`, `SESSION_DRIVER=array`, `MAIL_MAILER=array`, `APP_URL`, `APP_DEBUG=false`, `SCOUT_DRIVER=null` and the values of `parity/parity.env` (parsed as data).
- `artisan ARGS`, `reset` (runs `artisan winter:up`, then `artisan tinker --execute` requiring the absolute path of `parity/wavepath_reset.php` with `PARITY_VARS_OUT` set), `serve` (PHP's built-in server on `127.0.0.1:8423` with `-d error_reporting=8191`, cwd `PHP_ROOT`), `rows SELECT` (one SELECT without a semicolon).
- After `export`, assert through `artisan tinker` that the file of `Golem15\Chat\Classes\AttachmentStreamer` lies under `PHP_ROOT`; otherwise print `refuse: PHP loaded chat from outside the parity root` and exit 1.
6. `scripts/parity-stack.sh` in its thinnest form: `up` (mode `readonly`: `BROADCAST_ENABLED=false`, `QUEUE_CONNECTION=database` with no worker, `HTTPS_PROXY` and `https_proxy` set to `http://127.0.0.1:9`, then export, db, reset and serve, recording the process group), `down` (stops this instance's PHP server; the container stays), `self-replay` (runs `summer parity:replay --manifest parity/manifest.yaml --fixtures parity/fixtures --target http://127.0.0.1:8423 --vars VARSFILE --self-check true` and prints its summary line).
7. `parity/wavepath_reset.php`, tracer scope: users `alice@parity.test` and `dave@parity.test` with explicit ids, an accepted friendship between them, id floors with `ALTER TABLE … AUTO_INCREMENT`, the session JWT of alice minted with the application's own token code, and only the vars file as output (`jwt:alice`, `id:alice`, `id:dave`; never echo a value).
8. `parity/fixtureplugin`: the plugin shell (`ID()` `parity.fixtureplugin`, `Requires()` `golem15.wavepath`, constructed in process, never registered) and `Seed(ctx, db, store)` writing the same two users, the friendship and the same variable names, with alice's JWT minted through the user plugin's token service.
9. `parity/manifest.yaml`: version 1, auth groups `jwt`, `guest`, `bot`, `webhook`, `realtime`, the seed spec, and one route: id `GET /_wave/api/v1/community/friends jwt`, status `pending`, seed hook `community`, two cases: `alice` (request header `Cookie: token={{jwt:alice}}`, `Accept: application/json`) and `unauthenticated` (no cookie). Record both from PHP with `summer parity:record --manifest`, then run the self-replay. If the recorded body holds a relative-time string that only plan 31-01's mask can compare and that plan has not committed it yet, record `GET /_wave/api/v1/push/vapid-public-key jwt` as the tracer route instead and say so in the SUMMARY (the friends route is then recorded in plan 31-05).
10. `parity/testmain_test.go` and `parity/parity_test.go`: a testcontainers Postgres (`postgres:16-alpine`) started in `TestMain` after `flag.Parse()` unless `testing.Short()`; `seedHooks` with `community` calling `fixtureplugin.Seed`; `TestParityCorpus` loads and validates the manifest, serves `app.Handler` through `httptest`, loads every fixture of a pending route without sending it, replays every ported route strictly, and logs one line `parity: ported P pending N`. A pending route is never counted as passing.
11. `scripts/check-parity.sh` in its first form: the corpus stage (fixtures of the manifest load), the replay stage (`go test -count=1 -json ./parity`, failing on a failed test, on zero tests and on a missing `TestParityCorpus`), an optional `--self-replay` stage calling `scripts/parity-stack.sh up`, `self-replay` and `down`, and one summary line `check-parity: recorded R/T ported P pending N`. The flags `--allow-unrecorded` and `--allow-pending-foundation` are accepted.
12. Commit in `../sm-wavepath-app` in logical steps (skeleton; PHP stack; scenario seed; manifest and fixture; harness and gate), staging by path.</action>
<verify>
<automated>go -C ../sm-wavepath-app vet . ./app/... ./parity/... ./plugins/golem15/wavepath/... &amp;&amp; go -C ../sm-wavepath-app test -count=1 -short . ./app/... ./plugins/golem15/wavepath/... &amp;&amp; go -C ../sm-wavepath-app test -count=1 -run '^TestBootAllPlugins$' -v . 2&gt;&amp;1 | grep -q -- '^--- PASS: TestBootAllPlugins' &amp;&amp; go -C ../sm-wavepath-app test -count=1 -run '^TestParityCorpus$' -v ./parity 2&gt;&amp;1 | grep -q -- '^--- PASS: TestParityCorpus'</automated>
<fails_when>Non-zero exit: vet or a short test fails, the nine plugins do not boot, or the `--- PASS: TestParityCorpus` line is absent (the manifest or the fixture did not load, Docker was not reachable, or the filter matched nothing).</fails_when>
<automated>OUT="$(../sm-wavepath-app/scripts/check-parity.sh --self-replay --allow-unrecorded --allow-pending-foundation 2&gt;&amp;1)" &amp;&amp; printf '%s\n' "$OUT" | grep -qE 'failing 0 unrecorded 0' &amp;&amp; printf '%s\n' "$OUT" | grep -qE '^check-parity: recorded 1/1 ported 0 pending 1'</automated>
<fails_when>Non-zero exit from the gate (the PHP stack refused or did not boot, the self-replay found a difference), or the output lacks the self-replay line `failing 0 unrecorded 0`, or lacks the summary line `check-parity: recorded 1/1 ported 0 pending 1`.</fails_when>
</verify>
<acceptance_criteria>
- `grep -c '^\[submodule ' ../sm-wavepath-app/.gitmodules` prints 8, and `git -C ../sm-wavepath-app submodule status` prints eight lines, none starting with `+` or `-`.
- `grep -c 'golem15.wavepath' ../sm-wavepath-app/summer.yaml` prints 1; `grep -c 'parity.fixtureplugin' ../sm-wavepath-app/summer.yaml ../sm-wavepath-app/plugins.gen.go ../sm-wavepath-app/app/app.go | awk -F: '{s+=$2} END {print s}'` prints 0.
- The recorded fixture has the `alice` case with status 200 and the `unauthenticated` case with the status PHP answered, and holds no JWT: `grep -cE 'eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.' ../sm-wavepath-app/parity/fixtures/routes/*.yaml | awk -F: '{s+=$2} END {print s}'` prints 0.
- `stat -c %a "${XDG_CACHE_HOME:-$HOME/.cache}/summercms/wavepath-parity/corpus/vars.yaml"` prints 600.
- `grep -vE '^\s*#' ../sm-wavepath-app/parity/php_parity.sh ../sm-wavepath-app/scripts/parity-stack.sh | grep -cE 'worktree add|git (-C [^ ]+ )?(checkout|stash|commit|fetch|pull)|composer (install|update)|(npm|pnpm) (install|ci|add)'` prints 0.
- `git -C ../sm-wavepath-app remote` prints nothing.
</acceptance_criteria>
<done>The application repository exists and boots, the PHP reference backend runs from the pinned commits without touching the other agent's checkout, and one real route is recorded, self-replays green on PHP and is counted as pending by the Go harness and by the gate.</done>
</task>
<task type="auto">
<name>Task 2: The stack fails closed: record mode, instances, snapshot and per-case restore, status and check, and a self-test of every refusal</name>
<precondition>Task 1's verify passed: `../sm-wavepath-app/scripts/parity-stack.sh up` and `down` work in read-only mode.</precondition>
<files>../sm-wavepath-app/scripts/parity-stack.sh, ../sm-wavepath-app/parity/php_parity.sh, ../sm-wavepath-app/parity/case_hook.sh, ../sm-wavepath-app/parity/README.md</files>
<read_first>../sm-wavepath-app/scripts/parity-stack.sh and ../sm-wavepath-app/parity/php_parity.sh (as Task 1 left them), ../fonoteka.go/scripts/dev-stack.sh (lines 1-130 the header contract and helpers; the functions is_loopback, parse_env_file, check_keys, check_services, port_busy, launch, stop_groups, cleanup, up, down, status, check and the dispatch at the end), ../fonoteka.go/parity/php_parity.sh (lines 10-73 and 120-220), 31-RESEARCH.md ("Recommended shape" items 1 to 6, pitfalls 3, 4, 5 and 8), 31-PATTERNS.md ("parity-stack.sh", "Fail-closed scripts", "No Analog Found"). From the PHP contract with `git show`: the config files that name the environment variables for Centrifugo, LiveKit, VAPID, Turnstile, the queue and the cache</read_first>
<action>Per D-08 and D-20, closing threats T-31-08 and T-31-10.
1. `scripts/parity-stack.sh`: a header comment listing every subcommand and environment variable and the rule that lines starting with `refuse:` or `missing:` mean the script stopped and `warn:` lines never stop it. Helpers `say`, `warn`, `refuse`, `fail` in the style of fonoteka's; `set -euo pipefail`; `unset FORCE_COLOR`; a `curl --noproxy '*'` wrapper; env files parsed as `KEY=value` data, never executed. Subcommands:
- `up [--mode readonly|record]`. Mode `record` exports `BROADCAST_DRIVER=centrifugo`, `BROADCAST_ENABLED=true`, `CENTRIFUGO_API_URL=http://127.0.0.1:RECORDER_PORT/api`, `QUEUE_CONNECTION=sync`, `HTTPS_PROXY` and `https_proxy` at `http://127.0.0.1:PROXY_PORT`, `NO_PROXY=127.0.0.1,localhost`, the parity CA through `-d curl.cainfo` and `-d openssl.cafile` on the PHP server, `LIVEKIT_URL=https://livekit.example.test` (a name that never resolves, so a call that bypasses the proxy fails), and the LiveKit, VAPID and Turnstile values of `parity/parity.env`. Before starting PHP it waits up to `PARITY_LISTENER_WAIT` seconds (default 60) for the recorder and the proxy to accept connections and then prints `refuse: recorder not listening on …` or `refuse: upstream proxy not listening on …` and exits 1. Mode `readonly` is Task 1's.
- `down` stops this instance's process groups (TERM, then KILL after 10 seconds); `down --all` also stops the container when no other instance has a pid file.
- `status` lists the instance, mode, ports, database and whether each process answers.
- `check` verifies: the export's `.parity-export` equals `parity/pins.env`; the chat class-path assertion; the database name contains `parity` and the host is loopback; the vars file is mode 0600; the keys of the vars file equal `parity/scenario.vars.keys` once that file exists; in record mode both listeners answer. It prints every failed check and exits 1 if any failed.
- `selftest` runs each refusal against planted input in a scratch directory with no real service: a database name without `parity`, a non-loopback `DB_HOST`, a non-loopback target, record mode with nothing listening, a `pins.env` that differs from the export record, a vars file with mode 0644. Each must print its `refuse:` line and exit non-zero; `selftest` prints `selftest: ok` only when all did.
- Ports per instance: `corpus` uses 8423 (PHP), 8424 (recorder), 8425 (upstream proxy), 8422 (session proxy); any other instance name adds 100 to each. The MariaDB container is shared, one database per instance.
2. `parity/php_parity.sh`: add `snapshot` (dump the instance database after `reset` into `$PARITY_ROOT/$PARITY_INSTANCE/snapshot.sql`, AUTO_INCREMENT floors included) and `restore` (load the snapshot, clear the export's file cache so rate-limit counters start at zero); add `script FILE [ARGS]` (run a PHP file through `artisan tinker` with the overlay, for plan 31-08). Keep the `rows` guard.
3. `parity/case_hook.sh` (executable): reads `PARITY_ROUTE_ID`, `PARITY_CASE_ID` and `PARITY_SEED_HOOK`, calls `php_parity.sh restore`, and applies the case's scenario variant when the reset script defines one for that case id. Exit non-zero on any failure. Measure one restore and write the time into the README.
4. `parity/README.md`: the runbook so far: what the parity root holds, the pins, the two modes, the instance rule, every refusal and what it means, how to bring the stack up and down, and the rule that nothing is written in the PHP checkout.
5. Commit: `feat(parity): fail-closed stack with record mode, instances and per-case restore`.</action>
<verify>
<automated>OUT="$(../sm-wavepath-app/scripts/parity-stack.sh selftest 2&gt;&amp;1)" &amp;&amp; printf '%s\n' "$OUT" | grep -qx 'selftest: ok'</automated>
<fails_when>Non-zero exit, or the line `selftest: ok` is absent: a planted bad input (database name without parity, non-loopback host or target, missing listeners, pin mismatch, vars mode) was accepted.</fails_when>
<automated>( ../sm-wavepath-app/scripts/parity-stack.sh up --mode readonly &amp;&amp; ../sm-wavepath-app/scripts/parity-stack.sh check &amp;&amp; ../sm-wavepath-app/parity/php_parity.sh snapshot &amp;&amp; PARITY_ROUTE_ID=x PARITY_CASE_ID=y PARITY_SEED_HOOK=community ../sm-wavepath-app/parity/case_hook.sh &amp;&amp; OUT="$(../sm-wavepath-app/scripts/parity-stack.sh self-replay 2&gt;&amp;1)" &amp;&amp; printf '%s\n' "$OUT" | grep -q 'failing 0 unrecorded 0'; RC=$?; ../sm-wavepath-app/scripts/parity-stack.sh down; exit $RC )</automated>
<fails_when>Non-zero exit: `up` or `check` printed a `refuse:` line, the snapshot or the case hook failed, or the self-replay after a restore no longer prints `failing 0 unrecorded 0` (the restore does not bring back the recorded state).</fails_when>
</verify>
<acceptance_criteria>
- `PARITY_LISTENER_WAIT=2 ../sm-wavepath-app/scripts/parity-stack.sh up --mode record` with nothing on 8424 exits non-zero and prints a line starting with `refuse: recorder not listening`.
- `grep -c 'refuse:' ../sm-wavepath-app/scripts/parity-stack.sh` prints at least 6.
- `grep -vE '^\s*#' ../sm-wavepath-app/parity/php_parity.sh ../sm-wavepath-app/scripts/parity-stack.sh ../sm-wavepath-app/parity/case_hook.sh | grep -cE 'worktree add|git (-C [^ ]+ )?(checkout|stash|commit|fetch|pull)|composer (install|update)|(npm|pnpm) (install|ci|add)'` prints 0.
- `test -x ../sm-wavepath-app/parity/case_hook.sh` exits 0.
- `docker ps --format '{{.Names}} {{.Ports}}' | grep wavepath-parity-mariadb` shows the port published on `127.0.0.1` only.
</acceptance_criteria>
<done>The stack cannot serve PHP in record mode without the recorder and the proxy, cannot use a database that is not a parity database, and can return to the recorded state before every case.</done>
</task>
<task type="checkpoint:decision" gate="blocking">
<name>Task 5: Go-ahead for the remote of sm-wavepath-app and its module path</name>
<read_first>`git -C ../sm-wavepath-app log --oneline`, the module path in ../sm-wavepath-app/go.mod and summer.yaml, the gate's summary line from Task 4, memory note "sm- repo naming"</read_first>
<acceptance_criteria>
- The user's answer is recorded in the SUMMARY with the confirmed module path and remote URL, or "local".
</acceptance_criteria>
<decision>Create the remote for sm-wavepath-app and push master, and is `git.golem15.com/golem15/sm-wavepath-app` the right module path?</decision>
<context>D-02 rates the repository name, module path and parity/ layout as costly: WavePath's agent and every later WavePath phase build on them, and a rename later touches every import. Right now the repository is a skeleton, so a rename is one `go mod edit` and a small import rewrite. The other applications live under `golem15/` except `sm-bm-app` (`jakub/`). Plans 31-03 to 31-06 work on the local repository either way; a push is not needed to continue. Claude cannot create the repository on git.golem15.com; if you choose to push, the remote must exist first.</context>
<options>
<option id="push">
<name>Keep the path, push to git@git.golem15.com:golem15/sm-wavepath-app.git</name>
<pros>The work is backed up and WavePath's agent can clone it.</pros>
<cons>The name and path are public from now on.</cons>
</option>
<option id="rename">
<name>Another namespace or name (say which), then push</name>
<pros>Fixed while it costs almost nothing.</pros>
<cons>A second remote to create.</cons>
</option>
<option id="local">
<name>Keep it local for now</name>
<pros>Nothing leaves this machine; the decision can wait.</pros>
<cons>No backup; a later rename costs more with every plan.</cons>
</option>
</options>
<resume-signal>Reply "push" (after creating the empty remote), "rename NAMESPACE/NAME" or "local".</resume-signal>
</task>
<task type="auto">
<name>Task 6: Act on the answer: rename if asked, push if allowed, and leave the repository clean</name>
<reversibility rating="costly">A pushed module path is what other checkouts and go.sum files will name; after this point a rename is a coordinated change.</reversibility>
<precondition>Task 5 has an answer.</precondition>
<files>../sm-wavepath-app/go.mod, ../sm-wavepath-app/go.work, ../sm-wavepath-app/summer.yaml, ../sm-wavepath-app/plugins.gen.go, ../sm-wavepath-app/main.go, ../sm-wavepath-app/app/app.go, ../sm-wavepath-app/plugins/golem15/wavepath/go.mod, ../sm-wavepath-app/README.md</files>
<read_first>The Task 5 answer, ../sm-wavepath-app/go.mod, summer.yaml and every Go file that imports the module path (`grep -rl 'sm-wavepath-app' ../sm-wavepath-app --include=*.go --include=*.yaml --include=go.mod --include=go.work`)</read_first>
<action>Per D-02.
- "rename NAMESPACE/NAME": change the module path in `go.mod`, the app plugin's `go.mod`, `summer.yaml` and every import; regenerate `plugins.gen.go` and `main.go` with `summer build`; if the directory name changes too, stop and ask (the plans of this phase name `../sm-wavepath-app`). Run Task 4's first verify command again, commit `chore: module path NAMESPACE/NAME`, then continue as "push" with the new URL.
- "push": `git -C ../sm-wavepath-app remote add origin URL`, `git push -u origin master`, and check that `git ls-remote origin refs/heads/master` equals `git rev-parse HEAD`. A refused push (the remote does not exist, no permission) is reported with the exact message; nothing else is tried.
- "local": add no remote. Record it.
In every case: no tag. Post the g15office comment on task `hgol7otp` (plan 31-03 executed; repository local or pushed).</action>
<verify>
<automated>go -C ../sm-wavepath-app vet . ./app/... ./parity/... ./plugins/golem15/wavepath/... &amp;&amp; go -C ../sm-wavepath-app test -count=1 -short . ./app/... ./plugins/golem15/wavepath/... &amp;&amp; test -z "$(git -C ../sm-wavepath-app status --porcelain)" &amp;&amp; test -z "$(git -C ../sm-wavepath-app tag)"</automated>
<fails_when>Non-zero exit: the repository no longer vets or passes its short tests after a rename, has uncommitted changes, or has a tag.</fails_when>
</verify>
<acceptance_criteria>
- With "push" or "rename": the commit id printed by `git -C ../sm-wavepath-app ls-remote origin refs/heads/master` equals `git -C ../sm-wavepath-app rev-parse HEAD`. With "local": `git -C ../sm-wavepath-app remote` prints nothing.
- The SUMMARY records the answer, the module path and the remote URL or "local".
</acceptance_criteria>
<done>The repository has the name and path the user confirmed, is pushed only if the user said so, and the next plans can work on it.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
| automated evidence to completion verdict | missing or skipped work must not look green |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-31-07 | Tampering | scripts touching the other agent's checkout | high | mitigate | export by `git archive` at commit ids and rsync with the checkout as source only; `GIT_OPTIONAL_LOCKS=0`; acceptance greps the scripts for checkout, stash, commit, fetch, pull, worktree and install commands; the PHP server's cwd and storage are the export |
| T-31-08 | Information disclosure | a recording run reaching real vendors | high | mitigate | record mode refuses to start PHP unless the recorder and the upstream proxy listen; read-only mode sets the HTTPS proxy to a closed loopback port and a queue with no worker; LiveKit uses a host name that never resolves; the overlay holds test-only values from `parity/parity.env`; `selftest` proves the refusals |
| T-31-10 | Tampering | recording against a real database | high | mitigate | the database is a container published on loopback only; the name must contain `parity`; the checkout's `.env` is never read or copied; `selftest` plants a bad name and a non-loopback host |
| T-31-13 | Tampering | recording a version other than the freeze | medium | mitigate | export by the commit ids of `parity/pins.env`; `.parity-export` compared by `check`; the class-path assertion on a class that exists only at the chat pin |
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
</threat_model>
<verification>
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
</verification>
<success_criteria>
sm-wavepath-app skeleton and fail-closed isolated PHP parity stack is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
</success_criteria>
<output>
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-03-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
</output>

View File

@@ -0,0 +1,177 @@
---
phase: 31-chat-polish-against-wavepath-clients
plan: 04
type: execute
wave: 3
depends_on: [31-01, 31-02, 31-03]
files_modified:
- ../sm-wavepath-app/parity/scenario.md
- ../sm-wavepath-app/parity/scenario.vars.keys
- ../sm-wavepath-app/parity/scenario-deferred.txt
- ../sm-wavepath-app/parity/wavepath_reset.php
- ../sm-wavepath-app/parity/fixtureplugin/
- ../sm-wavepath-app/parity/fixtures/seed/bootstrap.yaml
- ../sm-wavepath-app/parity/manifest.yaml
- ../sm-wavepath-app/parity/routes.snapshot
- ../sm-wavepath-app/parity/foundation-routes.txt
- ../sm-wavepath-app/parity/check_corpus.go
- ../sm-wavepath-app/parity/parity_test.go
- ../sm-wavepath-app/parity/harness_test.go
- ../sm-wavepath-app/parity/upstream_replay_test.go
- ../sm-wavepath-app/scripts/check-parity.sh
autonomous: true
requirements: [SC-1, SC-3, D-04, D-09, D-15, D-16, D-18, D-19]
estimate:
tokens: 180000
raw_tokens: 180000
tasks: 2
confidence: low
must_haves:
truths:
- "Scenario on both sides, 196 pending-route manifest, corpus checker, harness and fail-closed gate is delivered against the frozen PHP corpus and locked decisions."
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
artifacts:
- path: "../sm-wavepath-app/parity/scenario.md"
provides: "Scenario on both sides, 196 pending-route manifest, corpus checker, harness and fail-closed gate"
key_links:
- from: "../sm-wavepath-app/parity/scenario.md"
to: "the plan's automated verification"
via: "the named tracer and fail-closed checks"
---
## Phase Goal
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
<objective>
Scenario on both sides, 196 pending-route manifest, corpus checker, harness and fail-closed gate.
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
Output: the artifacts and machine evidence named below.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
</context>
<tasks>
<task type="auto" tdd="true">
<name>Task 3: The whole scenario is seeded on both sides with the same ids and variable names</name>
<files>../sm-wavepath-app/parity/scenario.md, ../sm-wavepath-app/parity/scenario.vars.keys, ../sm-wavepath-app/parity/scenario-deferred.txt, ../sm-wavepath-app/parity/wavepath_reset.php, ../sm-wavepath-app/parity/fixtureplugin/plugin.go, ../sm-wavepath-app/parity/fixtureplugin/seed.go, ../sm-wavepath-app/parity/seed_test.go, ../sm-wavepath-app/parity/fixtures/seed/bootstrap.yaml</files>
<read_first>../sm-wavepath-app/parity/wavepath_reset.php and ../sm-wavepath-app/parity/fixtureplugin/seed.go (as Task 1 left them), ../fonoteka.go/parity/fonoteka_reset.php (whole file), ../fonoteka.go/parity/fonoteka_seed_test.go (lines 1-120 and 600-700), 31-CONTEXT.md (D-04, D-11, D-18, D-19, D-21), 31-RESEARCH.md ("Rate buckets in the corpus", "Route table", "Gap map", "Upstream vendors the corpus reaches", "Pattern 2", pitfalls 2, 4, 6 and 10), the models of the eight shared Go plugins (`../sm-wavepath-app/plugins/golem15/*/models/`) and their test fixture plugins (`fixture_plugin_test.go`) for how rows are created. From the PHP contract with `git show`: the models of the wavepath plugin and of the shared plugins, `Plugin.php` lines 160-558 (what a created group, a new member and a message trigger), and the migrations under `updates/` that add host columns to shared tables</read_first>
<behavior>
- `TestScenarioSeeds` (Docker): `fixtureplugin.Seed` on a migrated database succeeds twice in a row (idempotent) and every seeded row has the id the scenario names.
- `TestScenarioVarsMatch`: the variable names the Go seeder wrote, together with the names in `parity/scenario-deferred.txt`, equal the names in `parity/scenario.vars.keys`; a name missing on one side fails with that name.
- `TestFixtureAbsentFromProduction`: `parity.fixtureplugin` is not in `app.PluginIDs`, `summer.yaml` or `plugins.gen.go`.
- `TestSeededJWTAuthenticates` (Docker): a request to a route of the user plugin behind `jwt.auth` with `Cookie: token=` and the seeded JWT of alice is authenticated as alice.
</behavior>
<action>Per D-04, D-21, D-11 (a user on each side of every access rule), D-18 and D-19.
1. `parity/scenario.md` is the single definition. It names every identity, row and explicit id, and for each the variable it produces (`id:NAME`, `jwt:IDENTITY`, `token:NAME`, `code:NAME`). Minimum content:
- Identities: `alice` (owner of the group `harbor`), `bob` (admin of `harbor`, two push subscriptions, offline), `carol` (member, with a user status), `dave` (no group; accepted friend of alice), `erin` (banned from `harbor`), `frank` (stranger: no friendship, no group), `olive` (member, the one user the presence script reports online), an unclaimed imported member, one user per rate bucket for the ten 429 cases (`rl-wave-api`, `rl-community-join` and so on), and a bot user with a `wave_` token of scope `chat:bot`.
- Groups: `harbor` (closed, with an invite code and a custom code free for the invite cases), `plaza` (open, for the open-join cases), `cellar` (closed, alice is not a member, for denials), each with its chat and channels as the PHP lifecycle creates them.
- Channels of `harbor`: the system default `general`, a private channel, an archived channel, a category, a personal category, pins, a favourite, a muted channel.
- Messages: plain messages, one thread with replies, a message per delete, edit, pin and reaction case, a webhook message, an attachment; no http(s) URL in any message except in the unfurl cases.
- Direct messages: a conversation between alice and dave with a thread.
- Friendships: alice and dave accepted, bob to alice pending, alice to carol sent, each case that changes one having its own row.
- Video: a call link, a channel guest link, a guest session in each state the guest routes need.
- Forum: categories, threads and posts in `harbor`. Notes (D-18): diary entries of alice, one shared publicly and one shared with `harbor`.
- Push: the VAPID test pair and subscriptions whose endpoints are on real public push host names (the PHP endpoint rule resolves them); the subscription key pairs are test-only and listed in the scenario.
- A webhook on `general` with its token, a custom emoji, and the rows the 17 uncalled routes need for a success case each (D-19).
Each access rule of D-11 has an identity on each side of it; the document says which.
2. `parity/wavepath_reset.php`: the whole scenario, idempotent, wiping the scenario's state by id before recreating it, with explicit ids and AUTO_INCREMENT floors per table (steps of 10000000, so ids of different tables never collide when values become variables). Per-case variants are selected by an environment variable naming the case. It mints the session JWT of every identity and writes only the vars file. It never prints a secret.
3. `parity/fixtureplugin/seed.go`: the same rows through the Go plugins' models for every table that exists (the shared plugins' tables, and the user rows), with the same explicit ids, Postgres sequences set to the same floors, and the same variable names written into the `*tide.Store`. The JWTs are minted through the user plugin with the secret from `parity/parity.env`. A scenario row whose host table does not exist yet is not seeded and its variable names go into `parity/scenario-deferred.txt`, one per line with the phase that ports the table (31.1 or 31.2); this plan adds no host table.
4. `parity/scenario.vars.keys`: the sorted variable names, written from a PHP reset run (names only, no values). `parity/fixtures/seed/bootstrap.yaml`: the seed flow without a login step (D-21).
5. `parity/seed_test.go`: the behavior block.
6. Run `scripts/parity-stack.sh up`, `check` (it now compares the vars keys), `php_parity.sh snapshot`, `down`. Commit: `feat(parity): the community scenario on PHP and Go`.</action>
<verify>
<automated>go -C ../sm-wavepath-app vet ./parity/... &amp;&amp; go -C ../sm-wavepath-app test -count=1 -run '^(TestScenarioSeeds|TestScenarioVarsMatch|TestFixtureAbsentFromProduction|TestSeededJWTAuthenticates)$' -v ./parity 2&gt;&amp;1 | grep -c -- '^--- PASS: Test' | grep -qx 4</automated>
<fails_when>Non-zero exit: fewer than four `--- PASS: Test` lines (a seeding error, a variable name on one side only, the fixture plugin listed for production, or the seeded cookie JWT not accepted by the Go guard; a skipped Docker test also yields fewer than four).</fails_when>
<automated>( ../sm-wavepath-app/scripts/parity-stack.sh up --mode readonly &amp;&amp; ../sm-wavepath-app/scripts/parity-stack.sh check; RC=$?; ../sm-wavepath-app/scripts/parity-stack.sh down; exit $RC )</automated>
<fails_when>Non-zero exit: the PHP reset failed on the fresh MariaDB database, or `check` printed a `refuse:` line because the vars file's key set differs from `parity/scenario.vars.keys`.</fails_when>
</verify>
<acceptance_criteria>
- `grep -cE '^(jwt|id):(alice|bob|carol|dave|erin|frank|olive)$' ../sm-wavepath-app/parity/scenario.vars.keys` prints 14.
- `grep -c '^jwt:rl-' ../sm-wavepath-app/parity/scenario.vars.keys` prints at least 8 (the buckets keyed by user; the guest, bot and webhook buckets use their own credentials).
- Every line of `../sm-wavepath-app/parity/scenario-deferred.txt` names a variable and one of `31.1` or `31.2`: `grep -vcE ' (31\.1|31\.2)$' ../sm-wavepath-app/parity/scenario-deferred.txt` prints 0.
- `grep -cE 'eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.' ../sm-wavepath-app/parity/scenario.md ../sm-wavepath-app/parity/scenario.vars.keys ../sm-wavepath-app/parity/wavepath_reset.php | awk -F: '{s+=$2} END {print s}'` prints 0.
</acceptance_criteria>
<done>Both backends start every case from the same named state, and a request can log in on either side with a seeded cookie.</done>
</task>
<task type="auto" tdd="true">
<name>Task 4: The 196-route manifest with every route pending, the corpus checker and snapshot, a harness that can fail, and the complete gate</name>
<files>../sm-wavepath-app/parity/manifest.yaml, ../sm-wavepath-app/parity/routes.snapshot, ../sm-wavepath-app/parity/foundation-routes.txt, ../sm-wavepath-app/parity/check_corpus.go, ../sm-wavepath-app/parity/parity_test.go, ../sm-wavepath-app/parity/harness_test.go, ../sm-wavepath-app/parity/upstream_replay_test.go, ../sm-wavepath-app/scripts/check-parity.sh, ../sm-wavepath-app/parity/README.md, ../sm-wavepath-app/README.md, ../sm-wavepath-app/plugins/golem15/wavepath/plugin_test.go</files>
<read_first>../sm-wavepath-app/parity/manifest.yaml, parity_test.go and scripts/check-parity.sh (as Task 1 left them), ../fonoteka.go/parity/check_corpus.go (whole file: flags at 120-129, run at 138-206, scanSecrets at 437-515, the PHP route parser at 549-648, sanitizeFile at 717, the ported-versus-fixture check at 766-779), ../fonoteka.go/parity/check_corpus_test.go (how the checker is built and tested beside a test package), ../fonoteka.go/parity/routes.snapshot, ../fonoteka.go/parity/parity_test.go (lines 106-310), ../fonoteka.go/parity/synthetic_test.go, ../fonoteka.go/parity/upstream_replay_test.go (whole file), scripts/check-phase19.1.sh (lines 1-80: stages, the go test -json detectors, the self-test stage, the Docker message), ../sm-demo-app/scripts/check-all.sh (lines 42-82), 31-RESEARCH.md ("Count", "Route table", "Consumer gate"), 31-PATTERNS.md ("check_corpus.go", "check-parity.sh", "parity_test.go"). The route file, read-only: `GIT_OPTIONAL_LOCKS=0 git -C /media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath show a08ed0a34d1af72314a3453bb25593c6a1660056:routes.php`</read_first>
<behavior>
- `go run ./parity/check_corpus.go --manifest parity/manifest.yaml --snapshot parity/routes.snapshot --allow-incomplete` (run in the app directory) exits 0 and prints `routes 196` and the recorded and pending counts; with `--routes FILE` it also checks the SHA-256 of the route file against the snapshot and that the parsed ids equal the snapshot.
- It exits non-zero when: the manifest has a route the snapshot lacks or the reverse; a route's auth group differs from the classifier's; `--require-recorded` is set and a case has no fixture; a ported case's manifest status differs from its fixture; `--check-secrets` finds a JWT shape, a `wave_` token, an invite code, a webhook token, a call-link code or a cookie value in a fixture or sidecar that is not an allow-listed test constant.
- `TestParityHarnessCanFail`: over a synthetic manifest and handler, the suite fails for a ported route whose response differs, for a ported route without a fixture, for a ported route with an unknown seed hook and for a mutated recorded response; a pending route is reported as pending and is not in the passing count.
- `TestUpstreamSidecarsAreReplayed`: fails on an upstream sidecar of a ported route that no case replayed (it passes while no route is ported).
- `TestNoWaveRoutesYet` in the app plugin: the shell registers no route (the foundation slice adds them in plans 31-06 and 31-07).
- The gate: `scripts/check-parity.sh --self-test` feeds planted go test -json output (a failed test, zero tests, a skipped required test, a missing required test name) and planted checker output to its detectors and passes only when each is refused.
</behavior>
<action>Per D-09, D-15 as amended by D-16, D-10 (the realtime routes are ordinary routes) and D-05.
1. `parity/check_corpus.go` (`package main`, run with `go run`, built beside the test package the way fonoteka does it): constants for the 194 routes of the route file and the 196 expected ids; the PHP route parser over `Route::group` frames and `Route::` verbs, filtered to the D-09 prefixes (`/_wave/api/v1/community`, `/_wave/api/v1/guest`, `/_wave/api/v1/push`, the four bot and token routes under `/api/v1`, `/hooks/{token}`); the classifier mapping prefix and middleware to `jwt`, `guest`, `bot`, `webhook`; the two realtime ids as extras in group `realtime`. Flags `--manifest`, `--snapshot`, `--routes`, `--fixtures`, `--allow-incomplete`, `--require-recorded`, `--require-clients`, `--check-secrets`, `--foundation FILE` (prints `foundation F pending G`), `--write-snapshot` (writes the snapshot from `--routes`). Route id is `METHOD path auth_group`; a fixture name is the id with slashes and spaces replaced, as `sanitizeFile` does. Secret patterns beyond fonoteka's: `wave_` bearer tokens, 40-character webhook tokens, invite and call-link codes that equal a vars entry, any cookie value; the test-only constants of `parity/parity.env` are allow-listed by exact value.
2. `parity/routes.snapshot`: written once with `--write-snapshot` from the route file at `a08ed0a` (digest and the 196 ids). `parity/manifest.yaml`: all 196 routes, status `pending`, seed hook `community`, the auth group of each, the tracer route keeping its two cases; no other cases yet (plan 31-05 writes them). `parity/foundation-routes.txt`: the 36 foundation-slice route ids, one per line.
3. `parity/parity_test.go`: assert the manifest has 196 routes; one subtest per route; the pending and ported branches as in the tracer; a `coverage` subtest. `parity/harness_test.go`: `TestParityHarnessCanFail` over a synthetic manifest and handler. `parity/upstream_replay_test.go`: the upstream switch (the fake put on each request's context with `fetchguard.WithTransport`; a case without a sidecar gets an empty fake, so any vendor call fails it) and `TestUpstreamSidecarsAreReplayed`, copied from fonoteka's with this suite's names.
4. `scripts/check-parity.sh`, complete: stages `self-test`, `corpus` (the checker with `--check-secrets`, and `--require-recorded` unless `--allow-unrecorded`), `replay` (`go test -count=1 -json ./parity`, parsed: a failed test, a skipped required test, zero tests, a missing required test name or an unreachable Docker daemon fails the stage; required names `TestParityCorpus`, `TestParityHarnessCanFail`, `TestUpstreamSidecarsAreReplayed`, `TestScenarioVarsMatch`, `TestFixtureAbsentFromProduction`), `foundation` (every id in `parity/foundation-routes.txt` is `ported` unless `--allow-pending-foundation`), `consumers` (`sm-bm-app`: `go build ./...` and its tests `TestChatMounted`, `TestRealtimeDefaultDriver`, `TestRealtimeRoutes`, `TestRealtimeConfigDefaults`, `TestRemoteKeyOverride`; `sm-demo-app`: `go vet` and `go test -short` of the root package and `./plugins/demo/...`; directories from `BM_DIR` and `DEMO_DIR` with `../` defaults), optional `--self-replay`. One summary line: `check-parity: recorded R/196 ported P pending N foundation-pending F`. Each allow flag prints `NOT COMPLETE: …` with the count it let through. Exit 0 only when no stage failed.
5. `parity/README.md`: the corpus boundary (D-09), the manifest conventions, the checker's flags, the harness rules (pending never passes), the gate's stages and flags. `README.md` at the root: what the repository is, the plugin list, quick start (`summer build`, `go test -short ./...`), a pointer to `parity/README.md`.
6. Commit in steps: checker and snapshot; manifest; harness; gate and READMEs.</action>
<verify>
<automated>go -C ../sm-wavepath-app vet . ./app/... ./parity/... ./plugins/golem15/wavepath/... &amp;&amp; go -C ../sm-wavepath-app run ./parity/check_corpus.go --manifest parity/manifest.yaml --snapshot parity/routes.snapshot --allow-incomplete --check-secrets --foundation parity/foundation-routes.txt 2&gt;&amp;1 | grep -qx 'routes 196' &amp;&amp; go -C ../sm-wavepath-app test -count=1 -run '^(TestParityCorpus|TestParityHarnessCanFail|TestUpstreamSidecarsAreReplayed)$' -v ./parity 2&gt;&amp;1 | grep -c -- '^--- PASS: Test' | grep -qx 3</automated>
<fails_when>Non-zero exit: vet fails, the checker does not print the line `routes 196` (a route missing, extra or in the wrong group, or a secret found), or fewer than three `--- PASS: Test` lines are printed.</fails_when>
<automated>OUT="$(../sm-wavepath-app/scripts/check-parity.sh --allow-unrecorded --allow-pending-foundation 2&gt;&amp;1)" &amp;&amp; printf '%s\n' "$OUT" | grep -qE '^check-parity: recorded [0-9]+/196 ported 0 pending 196 foundation-pending 36$' &amp;&amp; ! ../sm-wavepath-app/scripts/check-parity.sh &gt;/dev/null 2&gt;&amp;1</automated>
<fails_when>Non-zero exit: the gate with both allow flags failed a stage (self-test, corpus, replay or a consumer build), the summary line is absent or has other counts, or the gate without flags exited 0 although routes are unrecorded and the foundation slice is pending.</fails_when>
</verify>
<acceptance_criteria>
- `grep -c '^ - id: ' ../sm-wavepath-app/parity/manifest.yaml` prints 196 and `grep -c 'status: ported' ../sm-wavepath-app/parity/manifest.yaml` prints 0.
- `wc -l &lt; ../sm-wavepath-app/parity/foundation-routes.txt` prints 36.
- `go -C ../sm-wavepath-app run ./parity/check_corpus.go --manifest parity/manifest.yaml --snapshot parity/routes.snapshot --require-recorded` exits non-zero (195 routes have no fixture yet).
- `../sm-wavepath-app/scripts/check-parity.sh --self-test` exits 0 and prints a line for each planted case it refused.
- `git -C ../sm-wavepath-app status --porcelain` prints nothing.
</acceptance_criteria>
<done>The corpus has its full route list, a checker that ties it to the PHP route file, a replay suite proven able to fail, and a gate that says how many routes are recorded, ported and pending and refuses to pass early.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
| automated evidence to completion verdict | missing or skipped work must not look green |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-31-09 | Information disclosure | secrets in committed fixtures | high | mitigate | captured values live in the mode-0600 vars file under the parity root; the reset script writes only that file; `check_corpus --check-secrets` scans fixtures and sidecars for JWT shapes, `wave_` tokens, webhook tokens, codes and cookie values; `.gitignore` covers vars files |
| T-31-11 | Spoofing | a gate that passes on nothing | high | mitigate | the gate parses `go test -json`, requires named tests, fails on zero tests, skips and a missing Docker daemon; its self-test feeds planted output to each detector; `TestParityHarnessCanFail` proves a pending route is never a pass |
| T-31-12 | Elevation of privilege | the fixture plugin in a production binary | high | mitigate | constructed in process by tests only; never registered with `party.Register`, never in `summer.yaml`, `plugins.gen.go` or `app.PluginIDs`; `TestFixtureAbsentFromProduction` |
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
</threat_model>
<verification>
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
</verification>
<success_criteria>
Scenario on both sides, 196 pending-route manifest, corpus checker, harness and fail-closed gate is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
</success_criteria>
<output>
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-04-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
</output>

View File

@@ -0,0 +1,188 @@
---
phase: 31-chat-polish-against-wavepath-clients
plan: 05
type: execute
wave: 4
depends_on: [31-02, 31-04]
files_modified:
- ../sm-wavepath-app/parity/manifest.yaml
- ../sm-wavepath-app/parity/capture-rules.yaml
- ../sm-wavepath-app/parity/capture_clients.mjs
- ../sm-wavepath-app/parity/record_corpus.sh
- ../sm-wavepath-app/parity/presence.yaml
- ../sm-wavepath-app/parity/accepted-differences.yaml
- ../sm-wavepath-app/parity/README.md
- ../sm-wavepath-app/parity/fixtures/routes/
- ../sm-wavepath-app/parity/upstream/
- ../sm-wavepath-app/parity/parity_test.go
- ../sm-wavepath-app/parity/broadcast_test.go
- ../sm-wavepath-app/parity/upstream_replay_test.go
- ../sm-wavepath-app/scripts/parity-stack.sh
- ../sm-wavepath-app/scripts/check-parity.sh
autonomous: true
requirements: [SC-1, SC-2, D-06, D-07, D-09, D-10, D-11, D-12, D-13, D-17, D-19]
estimate:
tokens: 260000
raw_tokens: 260000
tasks: 3
confidence: low
must_haves:
truths:
- "Full 196-route PHP recording with client provenance, publications, upstreams and green self-replay is delivered against the frozen PHP corpus and locked decisions."
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
artifacts:
- path: "../sm-wavepath-app/parity/manifest.yaml"
provides: "Full 196-route PHP recording with client provenance, publications, upstreams and green self-replay"
key_links:
- from: "../sm-wavepath-app/parity/manifest.yaml"
to: "the plan's automated verification"
via: "the named tracer and fail-closed checks"
---
## Phase Goal
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
<objective>
Full 196-route PHP recording with client provenance, publications, upstreams and green self-replay.
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
Output: the artifacts and machine evidence named below.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
</context>
<tasks>
<task type="tracer">
<name>Task 1: Tracer: one client writing route records its response, every publication and every vendor call, then self-replays green</name>
<precondition>31-01 and 31-02 summaries exist; `scripts/parity-stack.sh selftest` passes; the manifest has 196 routes and the tracer route is still pending.</precondition>
<files>../sm-wavepath-app/parity/capture-rules.yaml, ../sm-wavepath-app/parity/capture_clients.mjs, ../sm-wavepath-app/parity/record_corpus.sh, ../sm-wavepath-app/parity/presence.yaml, ../sm-wavepath-app/parity/manifest.yaml, ../sm-wavepath-app/parity/fixtures/clients/, ../sm-wavepath-app/parity/fixtures/routes/, ../sm-wavepath-app/parity/upstream/scripts/, ../sm-wavepath-app/parity/README.md, ../sm-wavepath-app/scripts/parity-stack.sh</files>
<read_first>../sm-wavepath-app/parity/README.md, manifest.yaml, scenario.md, scenario.vars.keys, capture-rules.yaml if present, scripts/parity-stack.sh, parity/php_parity.sh, parity/case_hook.sh, 31-01-SUMMARY.md, 31-02-SUMMARY.md, 31-03-SUMMARY.md, 31-04-SUMMARY.md, modules/tide/README.md sections for proxy, manifest recording, broadcasts and upstream scripts, ../fonoteka.go/parity/capture_clients.mjs, ../fonoteka.go/parity/capture-rules.yaml, /media/nvme/dev/jz/wavepath.org/vue-wavepath-app/src/stores/channelChatStore.ts and the API module for the selected writing route, /media/nvme/dev/jz/wavepath.org/hubot-wavepath/src/rest.mjs</read_first>
<action>Per D-07, D-10, D-11, D-17, D-20 and D-21.
1. Choose one writing route called by the SPA whose seeded path is short and deterministic; prefer a friendship request or a group update rather than a messaging route reserved for 31.1. Run the SPA through `summer parity:proxy` against the `corpus` PHP instance and capture the exact method, path, headers and body. The script resolves Playwright from the existing client tree and writes nothing there. It starts client processes with environment variables only and tracks and terminates every child.
2. `capture-rules.yaml`: client labels `nuxt` and `hubot`; keep only contract headers; capture server-minted ids/codes/cookies into the mode-0600 vars store; scrub every credential. Add route-specific captures only where the request-only spec cannot carry them. Keep Cookie but never its value.
3. Convert the observed tracer session into a committed request-only spec and merge its success plus D-11 denial/422 cases into the manifest. Use a fresh scenario identity for a rate-bucket case if the selected route has a named secondary bucket.
4. Add the smallest upstream script needed by the route. When no vendor call is expected, the attached proxy remains empty and fails on any unexpected call. Add `presence.yaml` with `olive` online so the online branch is deterministic.
5. `record_corpus.sh`: fail-closed wrapper around stack check, pin/reference check, `summer parity:record` with the manifest, vars, `--broadcasts true`, recorder and proxy loopback addresses, upstream script, presence table, case hook and wait; then `summer parity:replay --self-check true --require-recorded false`. It accepts a route/case selector for the tracer and no selector for the full run. It never evaluates env files as shell.
6. Record the tracer. Require its fixture and, because it writes, its broadcast sidecar. Require an upstream sidecar exactly when the reference made a vendor call. Re-run against PHP and require zero diffs. Document the command and generated files in `parity/README.md`.
7. Commit request/spec/script changes separately from generated fixtures: `feat(parity): capture one community writing route`; `test(parity): record the community tracer from PHP`.</action>
<verify>
<automated>OUT="$(cd ../sm-wavepath-app &amp;&amp; parity/record_corpus.sh --tracer --self-replay 2&gt;&amp;1)" &amp;&amp; printf '%s\n' "$OUT" | grep -qE 'failing 0 unrecorded 0' &amp;&amp; printf '%s\n' "$OUT" | grep -q 'broadcast'</automated>
<fails_when>Non-zero exit, no `failing 0 unrecorded 0` line, or no broadcast evidence: the stack or pin check refused, the observed request did not record, a publication differed, an unexpected vendor call escaped the script, or self-replay was not executed.</fails_when>
<automated>cd ../sm-wavepath-app &amp;&amp; go run ./parity/check_corpus.go --manifest parity/manifest.yaml --snapshot parity/routes.snapshot --allow-incomplete --check-secrets --foundation parity/foundation-routes.txt</automated>
<fails_when>Non-zero exit: the tracer changed the route inventory, wrote a live secret, used an invalid fixture name, or marked a pending route as passed.</fails_when>
</verify>
<acceptance_criteria>
- The tracer's request method, path, request headers and body are byte-for-byte derived from a proxy session, not reconstructed from controller code.
- Its success fixture exists and contains no JWT, session cookie, bot token, webhook token or vendor credential.
- Its `.broadcasts.yaml` exists and contains all publications emitted before the settle interval ended; deleting one publication makes self-replay fail.
- `git -C /media/nvme/dev/jz/wavepath.org status --porcelain` is not run or changed by the scripts; script source contains no checkout, stash, fetch, pull, install or commit command.
</acceptance_criteria>
<done>One real writing path is observed from a real client, recorded with all side effects and self-replays green from committed files.</done>
</task>
<task type="auto">
<name>Task 2: Expand proxy-derived specs and case depth across every route the SPA and bot call</name>
<precondition>The tracer self-replay is green and both clients resolve their existing dependencies without an install.</precondition>
<files>../sm-wavepath-app/parity/capture_clients.mjs, ../sm-wavepath-app/parity/capture-rules.yaml, ../sm-wavepath-app/parity/manifest.yaml, ../sm-wavepath-app/parity/fixtures/clients/, ../sm-wavepath-app/parity/upstream/scripts/, ../sm-wavepath-app/parity/upstream/helpers/, ../sm-wavepath-app/parity/presence.yaml, ../sm-wavepath-app/parity/README.md</files>
<read_first>Task 1 outputs, 31-RESEARCH.md "Route table", "Rate buckets in the corpus", "Routes that none of the three clients calls", "Upstream vendors", /media/nvme/dev/jz/wavepath.org/vue-wavepath-app/src/ request call sites including src/sw.js, /media/nvme/dev/jz/wavepath.org/hubot-wavepath/src/rest.mjs, the pinned PHP route file and controller validation rules through read-only `git show`, modules/tide/README.md minted credentials and body comparers</read_first>
<action>Per D-07, D-09, D-10, D-11 and D-17.
1. Drive named, deterministic SPA journeys over the seeded scenario: group administration, membership and invite paths; chat/channel/DM/thread/commands; reactions, emoji, prefs, pins and attachments; presence/status; forum; notes; push; video and guest. Drive the bot's four REST paths with its seeded token. Capture request sessions only; do not use `wavepath-mcp`.
2. Build a coverage map from every proxy request to one of the 196 manifest ids. Deduplicate the same route shape while preserving materially different client bodies and headers. A request outside D-09 is reported and excluded; a D-09 client-called route with no captured request stops the task.
3. For each captured route add the observed client cases and D-11 depth: unauthenticated, non-member/forbidden or not-found per access rule, UI-triggerable 422, and exactly one repeated 429 case per named rate bucket across the corpus. Do not invent statuses or envelopes; record them.
4. Add script answers for LiveKit Twirp, web-push, unfurl HTML/images, webhook icons and Turnstile. Helpers may decode protobuf or decrypt push payloads using scenario test keys and register a tide body comparer. If push decryption proves impossible (research A6), compare endpoint, headers, non-empty body and request count and record the limitation in README; do not accept arbitrary empty bodies.
5. Prove pinned requests stay inside the upstream proxy before running the broad recording: a planted public hostname resolves to a test address, the proxy sees the original host, and a closed proxy makes the PHP request fail. Keep scenario text free of URLs except explicit unfurl cases.
6. Write client flow provenance into README: client commit, session name, manifest routes covered, and excluded out-of-corpus requests. Commit specs and scripts; generated fixtures remain for Task 3.</action>
<verify>
<automated>cd ../sm-wavepath-app &amp;&amp; node parity/capture_clients.mjs --check-deps &amp;&amp; node parity/capture_clients.mjs --check-coverage --manifest parity/manifest.yaml</automated>
<fails_when>Non-zero exit: existing client dependencies cannot be resolved, a client-called D-09 route lacks a captured request, a session maps to an unknown route, or wavepath-mcp appears as a corpus client.</fails_when>
<automated>cd ../sm-wavepath-app &amp;&amp; parity/record_corpus.sh --check-upstream-confinement</automated>
<fails_when>Non-zero exit: a pinned PHP request bypasses the loopback proxy, loses its host name, accepts a closed proxy, or a script answer does not match the vendor request.</fails_when>
</verify>
<acceptance_criteria>
- Coverage output reports 177 client-called route ids and 17 no-client route ids.
- The manifest contains exactly ten 429 cases, one for each named bucket, with the required repeat count.
- Client source trees have no modified or untracked file caused by capture.
- Every upstream script host is a test/public vendor hostname from the pinned PHP code; no private, production credential or developer endpoint is present.
</acceptance_criteria>
<done>Every client-called corpus route has a proxy-derived request contract and complete denial, validation and rate-limit depth ready for unattended recording.</done>
</task>
<task type="auto">
<name>Task 3: Add the 17 hand-written success specs, record all 196 routes and freeze a green PHP self-replay</name>
<precondition>Task 2 reports exactly 177 client-called and 17 no-client routes, and the stack's pin check matches the reference revisions.</precondition>
<files>../sm-wavepath-app/parity/manifest.yaml, ../sm-wavepath-app/parity/fixtures/routes/, ../sm-wavepath-app/parity/upstream/scripts/, ../sm-wavepath-app/parity/accepted-differences.yaml, ../sm-wavepath-app/parity/parity_test.go, ../sm-wavepath-app/parity/broadcast_test.go, ../sm-wavepath-app/parity/upstream_replay_test.go, ../sm-wavepath-app/parity/README.md, ../sm-wavepath-app/scripts/check-parity.sh</files>
<read_first>Task 2 coverage output, 31-CONTEXT.md D-12/D-13/D-19, 31-RESEARCH.md table of 17 uncalled routes, pinned controllers and validation rules through read-only `git show`, ../fonoteka.go/parity/broadcast_goldens_test.go, ../fonoteka.go/parity/upstream_replay_test.go, ../sm-oauthserver-plugin/testdata/parity/deviations.yaml</read_first>
<action>Per D-06, D-09, D-10, D-11, D-12, D-13 and D-19.
1. Add one request-only success spec for each of the 17 no-client routes: three forum category operations; nine channel category/show/restore/mute operations; five note compatibility routes; webhook ingest; webhook icon (use the exact final list from the coverage map—if the research table's grouping count differs, the route ids, not prose arithmetic, win). Derive bodies from the pinned controller validation rules and scenario rows, then record PHP's actual result. Add denial and validation cases where applicable.
2. Fill `manifest.reference` from the `.parity-export`/pins produced by 31-02: superproject plus wavepath, user, chat, chatchannels, chatbots, chatvideo, forum, herald, userfriends, websockets, oauthserver and journal commits. The recording wrapper refuses any mismatch.
3. Create `accepted-differences.yaml` version 1 with an empty `differences` list and schema comments requiring id, route, case, path, reason, security rationale and sign-off. The replay loader rejects an entry without all fields; no entry is needed for PHP self-replay.
4. Run the full unattended recording from a fresh snapshot. For every writing case require a broadcast sidecar, including an explicit empty golden when the PHP reference emits none. For every case require either the expected upstream sidecar or proof that no upstream call occurred. Capture all generated ids/codes/cookies in the vars store and scan again before commit.
5. Extend parity checks: `TestBroadcastSidecarsAreComplete` rejects an orphan sidecar, a writing case without a golden and an unexpected publication; `TestUpstreamSidecarsAreReplayed` rejects orphans and unexpected calls; `TestPHPFixturesComplete` requires all 196 routes and all cases recorded. Keep all routes pending—the corpus is recorded, not ported.
6. Run PHP self-replay across all fixtures and sidecars. Re-record a nondeterministic case only after fixing its capture/normalization/spec; never edit the expected response. Update README with duration, counts, revisions and the one-command rerun. Commit generated corpus in reviewable groups without mixing code changes.
7. Tighten `scripts/check-parity.sh`: without `--allow-unrecorded`, corpus completeness is mandatory; with `--allow-pending-foundation`, the still-pending foundation is the only allowed incompleteness. It prints `recorded 196/196 ported 0 pending 196 foundation-pending 36` at this point.</action>
<verify>
<automated>cd ../sm-wavepath-app &amp;&amp; parity/record_corpus.sh --self-replay 2&gt;&amp;1 | tee "${TMPDIR:-/tmp}/wavepath-self-replay.log" &amp;&amp; grep -qE 'recorded 196/196.*failing 0.*unrecorded 0' "${TMPDIR:-/tmp}/wavepath-self-replay.log"</automated>
<fails_when>Non-zero exit or missing summary: any route/case is unrecorded, a response/header/publication/vendor call differs, a reference pin differs, a sidecar is absent or orphaned, or a secret scan fails.</fails_when>
<automated>cd ../sm-wavepath-app &amp;&amp; go run ./parity/check_corpus.go --manifest parity/manifest.yaml --snapshot parity/routes.snapshot --require-recorded --require-clients --check-secrets --foundation parity/foundation-routes.txt &amp;&amp; go test -count=1 -run '^(TestPHPFixturesComplete|TestBroadcastSidecarsAreComplete|TestUpstreamSidecarsAreReplayed)$' -v ./parity 2&gt;&amp;1 | grep -c -- '^--- PASS: Test' | grep -qx 3</automated>
<fails_when>Non-zero exit, corpus checker refusal, or fewer than three PASS lines: route/client coverage is incomplete, a secret exists, or fixture/broadcast/upstream completeness is not proven.</fails_when>
<automated>OUT="$(../sm-wavepath-app/scripts/check-parity.sh --allow-pending-foundation 2&gt;&amp;1)" &amp;&amp; printf '%s\n' "$OUT" | grep -qx 'check-parity: recorded 196/196 ported 0 pending 196 foundation-pending 36'</automated>
<fails_when>Non-zero exit or exact summary absent: the fail-closed gate did not run all corpus, replay and consumer stages or accepted an unrecorded case.</fails_when>
</verify>
<acceptance_criteria>
- `manifest.reference` equals the export pins and has no abbreviated commit.
- Exactly 196 manifest route entries have recorded fixtures; exactly 17 are marked with hand-written provenance, and none of those 17 lacks a success case.
- Every writing case has a broadcast sidecar, including an explicit zero-publication golden; every sidecar belongs to one manifest case.
- `accepted-differences.yaml` has zero entries.
- Every route remains `pending`; neither Phase 31.1 nor 31.2 implementation is pulled into this plan.
</acceptance_criteria>
<done>The committed corpus is a complete, secret-free observation of all 196 PHP routes at frozen commits, with publications and vendor calls, and it self-replays green unattended.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
| automated evidence to completion verdict | missing or skipped work must not look green |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-31-14 | Information disclosure | proxy sessions and generated fixtures | high | mitigate | mode-0600 vars store, tide capture and scrub rules, second `check_corpus --check-secrets` scan, exact secret-shape tests, and client source trees remain read-only |
| T-31-15 | Information disclosure | sync PHP jobs reaching real vendors | high | mitigate | stack refuses record mode unless the loopback upstream proxy listens; confinement test proves pinned requests traverse it and a closed proxy fails |
| T-31-16 | Tampering | recording wrong PHP revisions | high | mitigate | manifest.reference is populated from the export pins; stack check compares full commits and refuses before recording |
| T-31-17 | Repudiation | hand-written cases presented as client traffic | medium | mitigate | per-route provenance marks `proxy:nuxt`, `proxy:hubot` or `hand-written:D-19`; coverage check requires exactly the decided 17 hand-written routes |
| T-31-18 | Tampering | missing publications or vendor calls treated as success | high | mitigate | explicit broadcast golden for every writing case, empty fake for cases without upstream sidecars, orphan/completeness tests and PHP self-replay |
| T-31-19 | Denial of service | repeated 429 cases and broad client journeys | medium | mitigate | bounded tide repeat, dedicated identities, snapshot restore per case, loopback-only services and child-process cleanup |
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
</threat_model>
<verification>
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
</verification>
<success_criteria>
Full 196-route PHP recording with client provenance, publications, upstreams and green self-replay is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
</success_criteria>
<output>
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-05-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
</output>

View File

@@ -0,0 +1,122 @@
---
phase: 31-chat-polish-against-wavepath-clients
plan: 06
type: execute
wave: 5
depends_on: [31-05]
files_modified:
- ../sm-wavepath-app/plugins/golem15/wavepath/plugin.go
- ../sm-wavepath-app/plugins/golem15/wavepath/routes.go
- ../sm-wavepath-app/plugins/golem15/wavepath/buckets.go
- ../sm-wavepath-app/plugins/golem15/wavepath/chat.go
- ../sm-wavepath-app/plugins/golem15/wavepath/realtime.go
- ../sm-wavepath-app/plugins/golem15/wavepath/api/response.go
- ../sm-wavepath-app/plugins/golem15/wavepath/api/actor.go
- ../sm-wavepath-app/plugins/golem15/wavepath/classes/context.go
- ../sm-wavepath-app/plugins/golem15/wavepath/classes/channel_access.go
- ../sm-wavepath-app/plugins/golem15/wavepath/classes/forum_access.go
- ../sm-wavepath-app/plugins/golem15/wavepath/classes/authorizer.go
- ../sm-wavepath-app/plugins/golem15/wavepath/updates/
- ../sm-wavepath-app/parity/manifest.yaml
- ../sm-wavepath-app/parity/foundation_smoke_test.go
autonomous: true
requirements: [SC-1, SC-2, D-01, D-03, D-10, D-11, D-16, D-21]
estimate:
tokens: 150000
raw_tokens: 150000
tasks: 2
confidence: low
must_haves:
truths:
- "Foundation infrastructure: envelope, actor, buckets, contexts, resolvers, authorizers and realtime is delivered against the frozen PHP corpus and locked decisions."
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
artifacts:
- path: "../sm-wavepath-app/plugins/golem15/wavepath/plugin.go"
provides: "Foundation infrastructure: envelope, actor, buckets, contexts, resolvers, authorizers and realtime"
key_links:
- from: "../sm-wavepath-app/plugins/golem15/wavepath/plugin.go"
to: "the plan's automated verification"
via: "the named tracer and fail-closed checks"
---
## Phase Goal
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
<objective>
Foundation infrastructure: envelope, actor, buckets, contexts, resolvers, authorizers and realtime.
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
Output: the artifacts and machine evidence named below.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
</context>
<tasks>
<task type="tracer">
<name>Task 1: Tracer: recorded foundation write through envelope, cookie actor, buckets, shared service and broadcast</name>
<files>../sm-wavepath-app/plugins/golem15/wavepath/plugin.go, ../sm-wavepath-app/plugins/golem15/wavepath/routes.go, ../sm-wavepath-app/plugins/golem15/wavepath/buckets.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/response.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/actor.go, ../sm-wavepath-app/plugins/golem15/wavepath/updates/, ../sm-wavepath-app/parity/manifest.yaml, ../sm-wavepath-app/parity/foundation_smoke_test.go</files>
<action>Per D-01, D-03, D-10, D-11 and D-21, select one recorded foundation write with a deterministic publication. Start with a failing TestFoundationTracer that sends the fixture's token cookie through app.Handler and compares response and broadcast sidecar. Implement typed PHP-compatible success/error envelopes, actor/path/body helpers, app-owned wave-api and presence-state buckets, reuse userfriends.JoinBucket, mount only the selected unchanged /_wave path, and call the shared service through a host serializer. Add only migration-backed companion data needed by the route. Mark only the tracer route ported; fix implementation rather than fixtures.</action>
<verify>
<automated>go -C ../sm-wavepath-app vet ./plugins/golem15/wavepath/... ./parity/... &amp;&amp; go -C ../sm-wavepath-app test -count=1 -run '^TestFoundationTracer$' -v ./parity 2&gt;&amp;1 | grep -q -- '^--- PASS: TestFoundationTracer'</automated>
<fails_when>Non-zero exit, a named test does not run, or the expected corpus count is absent.</fails_when>
</verify>
<done>One real foundation write is green end to end with exact PHP envelope, persistence and publications.</done>
</task>
<task type="auto">
<name>Task 2: Contexts, access resolvers, wave/presence authorizers and realtime routes</name>
<files>../sm-wavepath-app/plugins/golem15/wavepath/chat.go, ../sm-wavepath-app/plugins/golem15/wavepath/realtime.go, ../sm-wavepath-app/plugins/golem15/wavepath/classes/context.go, ../sm-wavepath-app/plugins/golem15/wavepath/classes/channel_access.go, ../sm-wavepath-app/plugins/golem15/wavepath/classes/forum_access.go, ../sm-wavepath-app/plugins/golem15/wavepath/classes/authorizer.go, ../sm-wavepath-app/plugins/golem15/wavepath/README.md, ../sm-wavepath-app/parity/manifest.yaml</files>
<action>Per D-03 and D-10, implement the host group context over userfriends membership and roles, use the existing friendgroup alias, and add only the channel alias. Install channel/forum resolvers inside lagoon.OnDatabase and deny on missing database or errors. Read lighthouse channel parsing before implementing strict wave:group:{id} and presence:wave:group:{id} authorizers; register wave once and match recorded info/capabilities. Mount token and subscribe routes with their recorded auth and cache behavior. Mark only the two realtime routes ported after all success and denial fixtures pass.</action>
<verify>
<automated>go -C ../sm-wavepath-app test -count=1 -run 'TestParityCorpus/.+realtime' -v ./parity 2&gt;&amp;1 | grep -q -- '^--- PASS:'</automated>
<fails_when>Non-zero exit, a named test does not run, or the expected corpus count is absent.</fails_when>
</verify>
<done>Foundation infrastructure and both realtime routes match the corpus and deny malformed or cross-group access.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
| automated evidence to completion verdict | missing or skipped work must not look green |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-31-20 | Elevation of privilege | auth-group crossover on /_wave and realtime routes | high | mitigate | route groups use only jwt.auth for member routes; fixtures test guest/bot/invalid credentials; actor rejects backend/zero principals |
| T-31-22 | Elevation of privilege | wave/presence channel authorization | high | mitigate | strict channel parser, runtime membership check, deny on DB/error/malformed input, exact success/denial subscribe fixtures |
| T-31-23 | Denial of service | route and join/presence buckets | medium | mitigate | global bucket ownership checked, named buckets reused instead of duplicated, stacked limits and recorded 429 repeat cases |
| T-31-25 | Spoofing | app host serializer diverges from shared service state | medium | mitigate | handlers derive state from services/models and strict fixture replay; typed structs prevent accidental generic API envelopes |
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
</threat_model>
<verification>
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
</verification>
<success_criteria>
Foundation infrastructure: envelope, actor, buckets, contexts, resolvers, authorizers and realtime is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
</success_criteria>
<output>
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-06-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
</output>

View File

@@ -0,0 +1,120 @@
---
phase: 31-chat-polish-against-wavepath-clients
plan: 07
type: execute
wave: 6
depends_on: [31-06]
files_modified:
- ../sm-wavepath-app/plugins/golem15/wavepath/plugin.go
- ../sm-wavepath-app/plugins/golem15/wavepath/routes.go
- ../sm-wavepath-app/plugins/golem15/wavepath/lifecycle.go
- ../sm-wavepath-app/plugins/golem15/wavepath/api/groups.go
- ../sm-wavepath-app/plugins/golem15/wavepath/api/members.go
- ../sm-wavepath-app/plugins/golem15/wavepath/api/invites.go
- ../sm-wavepath-app/plugins/golem15/wavepath/api/join.go
- ../sm-wavepath-app/plugins/golem15/wavepath/api/friends.go
- ../sm-wavepath-app/plugins/golem15/wavepath/updates/
- ../sm-wavepath-app/parity/manifest.yaml
- ../sm-wavepath-app/parity/parity_test.go
- ../sm-wavepath-app/parity/broadcast_test.go
- ../sm-wavepath-app/parity/foundation_smoke_test.go
- ../sm-wavepath-app/scripts/check-parity.sh
autonomous: true
requirements: [SC-1, SC-2, SC-3, D-03, D-10, D-11, D-13, D-16]
estimate:
tokens: 190000
raw_tokens: 190000
tasks: 2
confidence: low
must_haves:
truths:
- "Foundation handlers and lifecycle green: groups, members, invites, join, friends and phase gate is delivered against the frozen PHP corpus and locked decisions."
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
artifacts:
- path: "../sm-wavepath-app/plugins/golem15/wavepath/plugin.go"
provides: "Foundation handlers and lifecycle green: groups, members, invites, join, friends and phase gate"
key_links:
- from: "../sm-wavepath-app/plugins/golem15/wavepath/plugin.go"
to: "the plan's automated verification"
via: "the named tracer and fail-closed checks"
---
## Phase Goal
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
<objective>
Foundation handlers and lifecycle green: groups, members, invites, join, friends and phase gate.
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
Output: the artifacts and machine evidence named below.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
</context>
<tasks>
<task type="tracer">
<name>Task 1: Port groups, members, invites, join and friends against recorded cases</name>
<files>../sm-wavepath-app/plugins/golem15/wavepath/routes.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/groups.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/members.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/invites.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/join.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/friends.go, ../sm-wavepath-app/plugins/golem15/wavepath/updates/, ../sm-wavepath-app/parity/manifest.yaml, ../sm-wavepath-app/parity/foundation_smoke_test.go</files>
<action>Per D-03, D-11, D-13 and D-16, expand from the tracer one vertical family at a time: groups, members, invites/join, then friends. Use GroupService and FriendshipService for generic operations and app-side transactions for host-only fields without changing shared serializers. Define typed requests/responses from fixtures, preserve nil/empty/conditional keys, scope parent before nested ids, and reproduce recorded 401/403/404/422/429 behavior. Stack wave-api with community-join only where recorded. Mark each family ported only after all of its cases and broadcasts pass; finish with 34 non-realtime foundation routes ported.</action>
<verify>
<automated>go -C ../sm-wavepath-app test -count=1 -run 'TestParityCorpus/.+(groups|members|invites|join|friends)' -v ./parity 2&gt;&amp;1 | tee /tmp/phase31-foundation.log &amp;&amp; ! grep -q -- '^--- FAIL:' /tmp/phase31-foundation.log &amp;&amp; grep -q -- '^--- PASS:' /tmp/phase31-foundation.log</automated>
<fails_when>Non-zero exit, a named test does not run, or the expected corpus count is absent.</fails_when>
</verify>
<done>All group/member/invite/join/friend routes and their denial, validation, rate and publication cases pass.</done>
</task>
<task type="auto">
<name>Task 2: Transactional group lifecycle and foundation-pending zero gate</name>
<files>../sm-wavepath-app/plugins/golem15/wavepath/plugin.go, ../sm-wavepath-app/plugins/golem15/wavepath/lifecycle.go, ../sm-wavepath-app/plugins/golem15/wavepath/README.md, ../sm-wavepath-app/parity/parity_test.go, ../sm-wavepath-app/parity/broadcast_test.go, ../sm-wavepath-app/parity/foundation_smoke_test.go, ../sm-wavepath-app/scripts/check-parity.sh</files>
<action>Per D-03, listen for GroupCreated, MemberJoined/Left and GroupDeleted. Work on ev.Tx so failures roll back; create group chat/default channel once, avoid duplicate owner work, update memberships idempotently, and on delete end video and remove forum/host context in PHP order. Add lifecycle smoke coverage for rows, rollback and publications. Prove exactly foundation-routes.txt is ported and run the gate without allow flags; it must report recorded 196/196, ported 36, pending 160, foundation-pending 0.</action>
<verify>
<automated>OUT="$(../sm-wavepath-app/scripts/check-parity.sh 2&gt;&amp;1)" &amp;&amp; printf '%s\n' "$OUT" | grep -qx 'check-parity: recorded 196/196 ported 36 pending 160 foundation-pending 0'</automated>
<fails_when>Non-zero exit, a named test does not run, or the expected corpus count is absent.</fails_when>
</verify>
<done>Lifecycle is rollback-safe and the Phase 31 foundation gate closes at zero foundation pending while 160 later-phase routes remain pending.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
| automated evidence to completion verdict | missing or skipped work must not look green |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-31-21 | Information disclosure | group/member/invite/friend IDOR | high | mitigate | parent-first scope checks, membership/role gate before nested lookup, recorded 403/404 collapse and cross-group denial cases |
| T-31-24 | Tampering | partial group lifecycle | high | mitigate | listeners use ev.Tx and return errors; create/delete side effects and rollback behavior tested with broadcasts |
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
</threat_model>
<verification>
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
</verification>
<success_criteria>
Foundation handlers and lifecycle green: groups, members, invites, join, friends and phase gate is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
</success_criteria>
<output>
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-07-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
</output>

View File

@@ -0,0 +1,115 @@
---
phase: 31-chat-polish-against-wavepath-clients
plan: 08
type: execute
wave: 2
depends_on: [31-03]
files_modified:
- ../sm-oauthserver-plugin/testdata/parity/flows/
- ../sm-oauthserver-plugin/testdata/parity/seed.json
- ../sm-oauthserver-plugin/testdata/parity/winter-export.jsonl
- ../sm-oauthserver-plugin/testdata/parity/id_token_shape.json
- ../sm-oauthserver-plugin/testdata/parity/README.md
autonomous: true
requirements: [SC-3, D-08, D-20, TODO-OIDC]
estimate:
tokens: 80000
raw_tokens: 80000
tasks: 1
confidence: low
must_haves:
truths:
- "Folded OIDC PHP parity recording in sm-oauthserver-plugin is delivered against the frozen PHP corpus and locked decisions."
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
artifacts:
- path: "../sm-oauthserver-plugin/testdata/parity/flows/"
provides: "Folded OIDC PHP parity recording in sm-oauthserver-plugin"
key_links:
- from: "../sm-oauthserver-plugin/testdata/parity/flows/"
to: "the plan's automated verification"
via: "the named tracer and fail-closed checks"
---
## Phase Goal
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
<objective>
Folded OIDC PHP parity recording in sm-oauthserver-plugin.
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
Output: the artifacts and machine evidence named below.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
</context>
<tasks>
<task type="tracer">
<name>Task 1: Record the ten PHP OIDC flows on the isolated oidc instance and make the existing parity harness mandatory-green</name>
<precondition>31-02's stack supports `PARITY_INSTANCE=oidc`; the pinned oauthserver commit is present; `../sm-oauthserver-plugin/testdata/parity/README.md` lists the ten flows and the plugin's unrelated go.work change is left unstaged.</precondition>
<files>../sm-oauthserver-plugin/testdata/parity/flows/, ../sm-oauthserver-plugin/testdata/parity/seed.json, ../sm-oauthserver-plugin/testdata/parity/winter-export.jsonl, ../sm-oauthserver-plugin/testdata/parity/id_token_shape.json, ../sm-oauthserver-plugin/testdata/parity/README.md</files>
<read_first>../sm-oauthserver-plugin/testdata/parity/README.md (whole file), parity_test.go tests TestPHPParityReplay and TestIDTokenShapeParity, scripts/winter-export.sql, all ten existing request-only flows, 31-03-SUMMARY.md instance/port contract, ../sm-wavepath-app/parity/php_parity.sh and scripts/parity-stack.sh, pinned PHP oauthserver models and migrations through the parity export</read_first>
<action>Per the folded OIDC todo, D-08 and D-20.
1. Start `PARITY_INSTANCE=oidc` with its isolated database/export/ports. Seed one activated parity user and the `Parity RP` client (`https://rp.example.test/callback`, openid/profile/email, active, non-development, no prior consent), and mint the user's session token into `~/.config/summercms/parity-oauthserver.vars` with mode 0600. Add no committed secret.
2. Record, in this exact order and stopping on first failure: discovery, jwks, authorize_errors, login_handoff, consent_allow, consent_silent, token_errors, userinfo_errors, consent_deny, authorizations. Invoke `summer parity:record --spec FLOW --output FLOW --target BASE --vars PRIVATE --update true`; do not pass `--rules`.
3. Remove every Set-Cookie entry from recorded responses. Generate `seed.json`, `winter-export.jsonl` through the runbook's MariaDB export (hashes, not plaintext secrets), and `id_token_shape.json`. Reject a real hostname, token, client secret, authorization code or cookie in any committed file.
4. Run the two mandatory parity tests. Resolve only observed documented differences through the existing deviation mechanism; do not broaden masks. Update the runbook with the automated `oidc` instance steps and exact green output.
5. Commit only testdata paths: `test(oauthserver): record PHP OIDC parity against WavePath`.</action>
<verify>
<automated>PHASE194_REQUIRE_PARITY=1 go -C ../sm-oauthserver-plugin test -count=1 -run '^(TestPHPParityReplay|TestIDTokenShapeParity)$' -v ./... 2&gt;&amp;1 | grep -c -- '^--- PASS: Test' | grep -qx 2</automated>
<fails_when>Non-zero exit or fewer than two PASS lines: a flow is absent/drifted, id-token shape differs, parity is still optional/skipped, or the filter matched nothing.</fails_when>
<automated>test "$(stat -c %a ~/.config/summercms/parity-oauthserver.vars)" = 600 &amp;&amp; ! rg -n 'Set-Cookie|eyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.|client_secret&quot;?\\s*:' ../sm-oauthserver-plugin/testdata/parity/flows ../sm-oauthserver-plugin/testdata/parity/seed.json ../sm-oauthserver-plugin/testdata/parity/winter-export.jsonl</automated>
<fails_when>Non-zero exit: private vars permissions are wrong or a cookie/JWT/client secret appears in committed parity artifacts.</fails_when>
</verify>
<acceptance_criteria>
- All ten named flow files contain recorded responses and retain their request specs.
- No flow contains Set-Cookie; export values are hashes only.
- `git -C ../sm-oauthserver-plugin diff -- go.work` is exactly the pre-existing other-session diff and is not staged.
- Both mandatory parity tests pass without a skip.
</acceptance_criteria>
<done>PHP OIDC behavior is a committed, secret-free reference corpus and the existing Go provider passes it under the mandatory parity flag.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
| automated evidence to completion verdict | missing or skipped work must not look green |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-31-26 | Information disclosure | OIDC recorded flows/export | high | mitigate | private mode-0600 vars, Set-Cookie removal, hashes-only export, token/secret scan and mandatory parity tests |
| T-31-27 | Tampering | OIDC masks hiding a real difference | medium | mitigate | fixed ordered runbook, no `--rules`, existing narrow deviations only and strict `PHASE194_REQUIRE_PARITY=1` |
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
</threat_model>
<verification>
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
</verification>
<success_criteria>
Folded OIDC PHP parity recording in sm-oauthserver-plugin is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
</success_criteria>
<output>
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-08-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
</output>

View File

@@ -0,0 +1,118 @@
---
phase: 31-chat-polish-against-wavepath-clients
plan: 09
type: execute
wave: 1
depends_on: []
files_modified:
- ../vue-chat-layer/app/composables/useChat.ts
- ../vue-chat-layer/tests/store.test.ts
- ../vue-chat-layer/README.md
autonomous: true
requirements: [SC-4, D-22, TODO-SLASH]
estimate:
tokens: 60000
raw_tokens: 60000
tasks: 1
confidence: low
must_haves:
truths:
- "Folded vue-chat-layer slash-command parity fix is delivered against the frozen PHP corpus and locked decisions."
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
artifacts:
- path: "../vue-chat-layer/app/composables/useChat.ts"
provides: "Folded vue-chat-layer slash-command parity fix"
key_links:
- from: "../vue-chat-layer/app/composables/useChat.ts"
to: "the plan's automated verification"
via: "the named tracer and fail-closed checks"
---
## Phase Goal
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
<objective>
Folded vue-chat-layer slash-command parity fix.
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
Output: the artifacts and machine evidence named below.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
</context>
<tasks>
<task type="auto" tdd="true">
<name>Task 2: Match WavePath slash behavior: known dispatch, local unknown refusal with draft retained, and // text escape</name>
<files>../vue-chat-layer/app/composables/useChat.ts, ../vue-chat-layer/tests/store.test.ts, ../vue-chat-layer/README.md</files>
<read_first>31-CONTEXT.md D-22, 31-RESEARCH.md "Slash text that names no command", ../vue-chat-layer/app/composables/useChat.ts send/runCommand/loadCommands and command state, ../vue-chat-layer/tests/store.test.ts existing slash cases and fake API, /media/nvme/dev/jz/wavepath.org/vue-wavepath-app/src/stores/channelChatStore.ts slash branch and MessageComposer handling (read-only)</read_first>
<behavior>
- Known `/demo arg` with catalog trigger `demo` calls dispatch once, does not call message send and clears the draft on success.
- Unknown `/nope arg` with a loaded non-empty catalog calls neither dispatch nor message send, adds the local unknown-command hint and keeps the exact draft.
- `//r/golang is great` calls ordinary message send with `/r/golang is great`, never dispatches, and clears the draft only on send success.
- Bare `/` follows ordinary send; when the loaded catalog is empty, slash text follows WavePath's ordinary-send branch; while catalog is null, load it before deciding and do not race a send against the lookup.
</behavior>
<action>Per D-22.
1. Red first: replace the old server-422 unknown-command expectation with the behavior block. Assert exact draft, dispatch/send call counts, arguments and ephemeral hint. Add the `//`, bare slash, empty catalog and null/loading cases.
2. In `send`, handle `//` before command dispatch: remove exactly one leading slash and pass the remainder through the normal text-send path. Do not mutate the draft until that send succeeds.
3. For one-leading-slash content with a non-empty trigger token, ensure the catalog is loaded. Compare the first token after `/` case-normalized in the same manner as existing command triggers. A known trigger calls `runCommand`; an unknown trigger pushes the existing local error row/hint, returns false and leaves `d.text` untouched. A bare `/` is not a trigger.
4. Preserve the WavePath empty-catalog behavior documented in D-22/research: on a surface whose loaded catalog is empty, slash text uses ordinary message send. Do not silently post unknown slash text when a catalog exists.
5. Update the layer README's command behavior and `//` escape. Commit: `fix(chat-layer): match WavePath slash command handling`.</action>
<verify>
<automated>pnpm --dir ../vue-chat-layer test -- --run 2&gt;&amp;1 | tee "${TMPDIR:-/tmp}/vue-chat-layer-test.log" &amp;&amp; ! grep -qE '(^|[^0-9])([1-9][0-9]*) failed' "${TMPDIR:-/tmp}/vue-chat-layer-test.log"</automated>
<fails_when>Non-zero exit or failed-test count: known/unknown/escape behavior differs, draft handling regressed, or another layer test failed.</fails_when>
<automated>pnpm --dir ../vue-chat-layer run build:playground</automated>
<fails_when>Non-zero exit: the composable's changed types or runtime imports do not build in the layer playground.</fails_when>
</verify>
<acceptance_criteria>
- Unknown `/nope` with a loaded catalog invokes neither API dispatch nor message send and preserves the draft.
- `//text` sends `/text` through the ordinary path.
- No backend or shared Go plugin changes for slash handling.
- README describes all four branches: known, unknown, escape, bare/empty catalog.
</acceptance_criteria>
<done>A user can deliberately post slash-prefixed text with //, while accidental unknown commands are refused locally exactly as WavePath specifies.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
| automated evidence to completion verdict | missing or skipped work must not look green |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-31-28 | Elevation of privilege | slash text dispatched as an unintended command | medium | mitigate | loaded-catalog first-token match; unknown triggers never call dispatch; explicit tests for dispatch/send call counts |
| T-31-29 | Tampering | `//` escape altering more than one slash | low | accept | deterministic one-character removal is directly covered; remaining risk is cosmetic user input, not authorization |
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
</threat_model>
<verification>
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
</verification>
<success_criteria>
Folded vue-chat-layer slash-command parity fix is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
</success_criteria>
<output>
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-09-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
</output>

View File

@@ -0,0 +1,133 @@
---
phase: 31-chat-polish-against-wavepath-clients
plan: 10
type: execute
wave: 1
depends_on: []
files_modified:
- ../sm-chat-plugin/events/events.go
- ../sm-chat-plugin/classes/service.go
- ../sm-chat-plugin/README.md
- ../sm-userfriends-plugin/events/events.go
- ../sm-userfriends-plugin/contracts/rejection.go
- ../sm-userfriends-plugin/classes/group_service.go
- ../sm-userfriends-plugin/api/errors.go
- ../sm-userfriends-plugin/README.md
- ../sm-user-plugin/classes/events.go
- ../sm-user-plugin/contracts/rejection.go
- ../sm-user-plugin/controllers/
- ../sm-user-plugin/README.md
- ../sm-demo-app/plugins/demo/moderation.go
- ../sm-demo-app/plugins/demo/plugin.go
autonomous: true
requirements: [SC-3, D-14, TODO-MODERATION]
estimate:
tokens: 150000
raw_tokens: 150000
tasks: 1
confidence: low
must_haves:
truths:
- "Folded additive moderation seams for users, friend groups and attachment filenames is delivered against the frozen PHP corpus and locked decisions."
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
artifacts:
- path: "../sm-chat-plugin/events/events.go"
provides: "Folded additive moderation seams for users, friend groups and attachment filenames"
key_links:
- from: "../sm-chat-plugin/events/events.go"
to: "the plan's automated verification"
via: "the named tracer and fail-closed checks"
---
## Phase Goal
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
<objective>
Folded additive moderation seams for users, friend groups and attachment filenames.
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
Output: the artifacts and machine evidence named below.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
</context>
<tasks>
<task type="auto" tdd="true">
<name>Task 3: Add additive user/group/filename saving seams and moderate them in the demo without changing listener-free behavior</name>
<files>../sm-chat-plugin/events/events.go, ../sm-chat-plugin/classes/service.go, ../sm-chat-plugin/saving_test.go, ../sm-chat-plugin/README.md, ../sm-userfriends-plugin/events/events.go, ../sm-userfriends-plugin/contracts/rejection.go, ../sm-userfriends-plugin/classes/group_service.go, ../sm-userfriends-plugin/api/errors.go, ../sm-userfriends-plugin/saving_test.go, ../sm-userfriends-plugin/README.md, ../sm-user-plugin/classes/events.go, ../sm-user-plugin/contracts/rejection.go, ../sm-user-plugin/controllers/registration.go, ../sm-user-plugin/controllers/api_controller.go, ../sm-user-plugin/controllers/users_admin_controller.go, ../sm-user-plugin/saving_test.go, ../sm-user-plugin/README.md, ../sm-demo-app/plugins/demo/moderation.go, ../sm-demo-app/plugins/demo/plugin.go, ../sm-demo-app/moderation_test.go, ../sm-demo-app/go.mod, ../sm-demo-app/go.sum, ../sm-demo-app/plugins/golem15/chat, ../sm-demo-app/plugins/golem15/user, ../sm-demo-app/plugins/golem15/userfriends, ../sm-bm-app/plugins/golem15/chat</files>
<read_first>31-PATTERNS.md "Folded todo: saving seams", ../sm-chat-plugin/events/events.go, classes/service.go attachment claim flow, classes/writes.go edit fire, contracts/rejection.go, api/errors.go, saving_test.go; ../sm-forum-plugin/events/events.go and classes/forum_service.go saving event; ../sm-userfriends-plugin/events/events.go, classes/group_service.go create/update/fire, api/errors.go; ../sm-user-plugin/classes/events.go, controllers registration/api/admin write paths and validation writers; ../sm-demo-app/plugins/demo/moderation.go, plugin.go and moderation_test.go; module READMEs</read_first>
<behavior>
- Chat: MessageSaving on create carries the filenames of attachment ids being claimed; no attachments yields an empty slice; rejection field `attachments` returns 422 and stores neither message nor claims; no listener preserves current response and storage.
- Userfriends: GroupSaving fires for create and update after access/required checks but before transaction/write, with op, actor, group id, name and description; Rejection maps to a 422 field; no listener preserves current behavior.
- User: Saving fires before frontend registration/profile update and backend-admin create/update with operation, actor where known, user id, name and surname; Rejection maps to each path's existing 422 field; no listener preserves current behavior.
- Demo: banned content in profile name/surname, group name/description or any claimed attachment filename produces the owning API's 422 and leaves storage unchanged.
</behavior>
<action>Per the moderation folded todo and D-14.
1. Red first in each plugin: table-driven smoke cases from the behavior block, including no-listener compatibility, owning Rejection, plain listener error (500/rollback), event ordering and no post-save event after refusal.
2. Chat: add `AttachmentFilenames []string` (or the final neutral plural name) to `MessageSaving`. In `SendMessageWith`, resolve pending attachment rows owned by the actor and collect basename/original names after validation but before firing; do not claim them yet. Existing listeners see the zero value. Edit events carry no attachment names.
3. Userfriends: add operation constants and `GroupSaving` in `events`, plus value `contracts.Rejection`. Extend the service fire type switch; fire create/update after permission and required checks and before transaction/write. Map Rejection in `api/errors.go`, defaulting an empty field to `name`.
4. User: add `SavingEvent`, operation constants, `FireSavingEvent`, and value Rejection. Fire from frontend registration, profile update and backend-admin create/update after request validation and authorization but before persistence. Include proposed name/surname values, not mutable model pointers. Map a rejection through each handler's existing validation writer.
5. Update all three READMEs in their API-reference/event sections. These are additive exported APIs; no behavior changes without a listener.
6. Demo: register listeners only when each plugin is active. Filter profile fields and group fields with `Filter.Check`; filter each filename and reject field `attachments` on the first refusal. Update plugin/package comments and extend `moderation_test.go` over real HTTP paths with unchanged row counts.
7. Commit plugin changes independently. Point bm/demo submodules locally at candidate commits. Run bm and demo gates before any requested tag. If the user has separately authorized release, push/tag each plugin, post its changelog, then commit consumer pointers separately; otherwise stop at clean local commits and record release-ready hashes.</action>
<verify>
<automated>for r in sm-chat-plugin sm-userfriends-plugin sm-user-plugin; do go -C ../$r vet ./... &amp;&amp; go -C ../$r test -count=1 -short ./... || exit 1; done &amp;&amp; go -C ../sm-chat-plugin test -count=1 -run '^TestMessageSaving' -v . 2&gt;&amp;1 | grep -q -- '^--- PASS:' &amp;&amp; go -C ../sm-userfriends-plugin test -count=1 -run '^TestGroupSaving' -v . 2&gt;&amp;1 | grep -q -- '^--- PASS:' &amp;&amp; go -C ../sm-user-plugin test -count=1 -run '^TestSaving' -v . 2&gt;&amp;1 | grep -q -- '^--- PASS:'</automated>
<fails_when>Non-zero exit or a PASS line absent: a plugin does not vet/test, listener-free behavior changed, a rejection writes data, or a named saving test did not run.</fails_when>
<automated>go -C ../sm-demo-app vet . ./plugins/demo/... &amp;&amp; go -C ../sm-demo-app test -count=1 -run '^TestDemoModeration' -v . 2&gt;&amp;1 | grep -q -- '^--- PASS: TestDemoModeration' &amp;&amp; go -C ../sm-bm-app build ./... &amp;&amp; go -C ../sm-bm-app test -count=1 -run '^(TestChatMounted|TestRealtimeDefaultDriver|TestRealtimeRoutes|TestRealtimeConfigDefaults|TestRemoteKeyOverride)$' -v . 2&gt;&amp;1 | grep -c -- '^--- PASS: Test' | grep -qx 5</automated>
<fails_when>Non-zero exit, demo moderation PASS absent, or bm prints fewer than five PASS lines: the listeners do not reject through HTTP, a consumer fails at candidate commits, or required bm tests did not run.</fails_when>
</verify>
<acceptance_criteria>
- Each plugin has a no-listener compatibility assertion and a refusal-no-write assertion.
- Existing MessageSaving listeners compile unchanged.
- User saving covers frontend and backend-admin writes; group saving covers create/update; filename saving covers claims on message create.
- READMEs name only exported identifiers that exist.
- No tag/push/changelog occurs without explicit authorization.
</acceptance_criteria>
<done>Hosts can moderate all requested names and filenames through additive pre-save events, and the demo proves refusals while unlistened plugins remain compatible.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
| automated evidence to completion verdict | missing or skipped work must not look green |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-31-30 | Tampering | moderation event fires after persistence | high | mitigate | fire after checks and before transaction/write; refusal and plain-error tests assert unchanged row/claim counts |
| T-31-31 | Denial of service | listener recursion or mutable event payload | medium | mitigate | immutable proposed scalar fields/slices, one pre-save fire per operation, no model save from the framework seam |
| T-31-32 | Spoofing | consumer gate tests wrong plugin revision | high | mitigate | local submodule pointers are set to exact candidate commits before bm/demo build/tests; release hashes recorded |
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
</threat_model>
<verification>
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
</verification>
<success_criteria>
Folded additive moderation seams for users, friend groups and attachment filenames is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
</success_criteria>
<output>
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-10-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
</output>

View File

@@ -0,0 +1,188 @@
---
phase: 31-chat-polish-against-wavepath-clients
plan: 11
type: execute
wave: 7
depends_on: [31-01, 31-02, 31-04, 31-05, 31-07, 31-08, 31-09, 31-10]
files_modified:
- modules/tide/
- cmd/summer/parity_test.go
- ../sm-wavepath-app/plugins/golem15/wavepath/
- ../sm-wavepath-app/parity/
- ../sm-wavepath-app/scripts/check-parity.sh
- ../sm-chat-plugin/saving_test.go
- ../sm-userfriends-plugin/saving_test.go
- ../sm-user-plugin/saving_test.go
- ../sm-demo-app/moderation_test.go
- ../vue-chat-layer/tests/store.test.ts
autonomous: true
requirements: [SC-1, SC-2, SC-3, SC-4, D-01, D-03, D-06, D-09, D-10, D-11, D-13, D-14, D-16, D-22]
estimate:
tokens: 260000
raw_tokens: 260000
tasks: 3
confidence: low
scope_exception: "This closing unit-and-gate plan intentionally groups test matrices across the phase; splitting it would violate the project rule that the last plan owns unit coverage and the closing gate."
must_haves:
truths:
- "Unit tests last: tide, app foundation, parity/gate and folded-todo regression matrices is delivered against the frozen PHP corpus and locked decisions."
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
- "The final gate reports recorded 196/196, ported 36, pending 160 and foundation-pending 0."
artifacts:
- path: "modules/tide/"
provides: "Unit tests last: tide, app foundation, parity/gate and folded-todo regression matrices"
key_links:
- from: "modules/tide/"
to: "the plan's automated verification"
via: "the named tracer and fail-closed checks"
---
## Phase Goal
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
<objective>
Unit tests last: tide, app foundation, parity/gate and folded-todo regression matrices.
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
Output: the artifacts and machine evidence named below.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
</context>
<tasks>
<task type="tracer">
<name>Task 1: Tracer test: mutate one foundation case at each side-effect boundary and prove replay and the gate fail closed</name>
<precondition>31-04's gate summary is `recorded 196/196 ported 36 pending 160 foundation-pending 0` and 31-05's repo suites are green.</precondition>
<files>../sm-wavepath-app/parity/parity_test.go, ../sm-wavepath-app/parity/broadcast_test.go, ../sm-wavepath-app/parity/upstream_replay_test.go, ../sm-wavepath-app/parity/gate_test.go, ../sm-wavepath-app/scripts/check-parity.sh</files>
<read_first>31-05-SUMMARY.md fixture/sidecar counts, 31-07-SUMMARY.md tracer route and gate output, parity_test.go, broadcast_test.go, upstream_replay_test.go, scripts/check-parity.sh, ../fonoteka.go/parity/parity_test.go negative subtests, scripts/check-phase19.1.sh self-test detector pattern</read_first>
<action>Per D-10, D-11, D-13 and D-16.
1. Add `TestFoundationParityFailClosed` using a temp copy of the tracer fixture and sidecars. Table cases: response status/body mutation, removed broadcast, extra broadcast, changed broadcast body, removed expected upstream call, extra upstream sidecar/call, route set back to pending, missing seed hook and a planted accepted-difference without sign-off. Each mutation must produce a non-empty error naming route and case; the untouched control passes.
2. Add `TestGateFailClosed` around extracted/testable detector functions or `scripts/check-parity.sh --self-test`: planted go-test JSON for fail, skip, zero tests and missing required name; checker output with unrecorded case, foundation pending, wrong counts/reference, secret residue; consumer command failure. Each is refused.
3. Keep the real gate script's behavior unchanged except for factoring detector helpers and adding checks that mutation tests expose. No allow flag in its normal path.
4. Commit: `test(parity): prove foundation replay and gate fail closed`.</action>
<verify>
<automated>go -C ../sm-wavepath-app test -count=1 -run '^(TestFoundationParityFailClosed|TestGateFailClosed)$' -v ./parity 2&gt;&amp;1 | grep -c -- '^--- PASS: Test' | grep -qx 2</automated>
<fails_when>Non-zero exit or fewer than two PASS lines: an altered response/sidecar/manifest/gate signal was accepted, the untouched control failed, or a named test did not run.</fails_when>
<automated>../sm-wavepath-app/scripts/check-parity.sh --self-test 2&gt;&amp;1 | grep -q 'self-test: ok'</automated>
<fails_when>Non-zero exit or marker absent: at least one planted false-green condition is not rejected by the executable gate.</fails_when>
</verify>
<acceptance_criteria>
- Every table mutation fails for the intended reason and names the route/case or gate stage.
- Committed fixtures and sidecars remain byte-identical; all mutation happens in a temp directory.
- The untouched control traverses response, broadcast and upstream checks and passes.
</acceptance_criteria>
<done>A single end-to-end foundation case proves that no missing or altered observable can produce a green parity or gate verdict.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: Complete table-driven tide, foundation handler, resolver, authorizer, lifecycle and corpus-checker coverage</name>
<files>modules/tide/normalize_test.go, modules/tide/centrifugo_test.go, modules/tide/centrifugo_golden_test.go, modules/tide/manifest_test.go, modules/tide/upstream_test.go, modules/tide/variables_test.go, modules/tide/headers_test.go, modules/tide/rules_test.go, modules/tide/fixture_test.go, cmd/summer/parity_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/response_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/groups_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/members_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/invites_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/friends_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/classes/context_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/classes/authorizer_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/lifecycle_test.go, ../sm-wavepath-app/parity/check_corpus_test.go</files>
<read_first>31-01-SUMMARY.md and 31-02-SUMMARY.md final tide APIs, every tide smoke test and adjacent existing unit tests, cmd/summer/parity_test.go, 31-06-SUMMARY.md and 31-07-SUMMARY.md final handler/type/route names, app-plugin production files, all foundation recorded denial/validation fixtures, parity/check_corpus.go and fonoteka's checker tests</read_first>
<behavior>
- Tide T-1..T-10 and Reference: valid, malformed, disabled/absent/default, strict YAML round-trip and old-format compatibility cases.
- Tide security: undeclared credentials/cookies refused; wrong JWT scheme/claims rejected; body comparer scoped by host/content type; case hook has no shell interpolation; listeners require loopback; repeat bound enforced.
- Foundation handlers: each family has success, malformed JSON, missing actor, role denial, missing/cross-group nested id, validation rejection, nil service/database and unexpected error; exact status, envelope and row-count effects.
- Authorizers/resolvers: malformed channel/context, zero user, absent/error DB, non-member/member/role cases and exact allowed info/capabilities.
- Lifecycle: create is idempotent, owner MemberJoined does not duplicate default channel, member leave/join behavior, delete cleanup, child failure rolls back all changes.
- Corpus checker: route/snapshot/auth mismatch, missing fixture, wrong ported status, missing/orphan broadcast/upstream, every secret pattern, wrong reference commit, missing D-19 provenance and wrong foundation set.
</behavior>
<action>Per SC-4.
1. Replace or extend the 31-01 smoke coverage with table-driven tests in the canonical tide test files. Cover all final exported options and strict loaders/writers; load representative pre-Phase-31 fixtures/manifests/sidecars to prove backward compatibility.
2. Add CLI tests that parse the final record/replay flags, reject their use outside manifest mode, reject non-loopback listeners and non-executable case hooks, and prove hook ids are environment data rather than shell input.
3. Add app-plugin unit matrices with injected services/checks and `httptest`. Use real fixture snippets for exact envelope/key/null behavior, but keep database integration in the existing parity tests.
4. Add resolver/authorizer pure tables and lifecycle transaction tests over testcontainers or the app's test DB. Assert rows and event/publication calls before and after rollback.
5. Extend `check_corpus_test.go` with temp manifests/sidecars for every behavior row. Include all secret forms: JWT, wave token, cookie, invite/webhook/call-link code and minted vendor credential.
6. Commit framework tests separately from app tests: `test(tide): cover Phase 31 recording additions`; `test(wavepath): cover foundation handlers and access`; `test(parity): cover corpus checker failures`.</action>
<verify>
<automated>go vet ./modules/tide/ ./cmd/summer/ &amp;&amp; go test -count=1 -short ./modules/tide/ ./cmd/summer/ &amp;&amp; go test -count=1 -run '^(TestRelative|TestManifest|TestUpstream|TestCookie|TestExtraHeaders|TestClient|TestRepeat|TestCentrifugo)' -v ./modules/tide/ 2&gt;&amp;1 | tee "${TMPDIR:-/tmp}/tide-unit.log" &amp;&amp; grep -q -- '^--- PASS:' "${TMPDIR:-/tmp}/tide-unit.log" &amp;&amp; ! grep -q -- '^--- FAIL:' "${TMPDIR:-/tmp}/tide-unit.log"</automated>
<fails_when>Non-zero exit, no PASS line or any FAIL line: tide/cmd tests do not compile, a compatibility/security/edge table fails, or the filter matched nothing.</fails_when>
<automated>go -C ../sm-wavepath-app vet ./plugins/golem15/wavepath/... ./parity/... &amp;&amp; go -C ../sm-wavepath-app test -count=1 -run '^(Test(Response|Groups|Members|Invites|Friends|Context|Authorize|Lifecycle|CheckCorpus))' -v ./plugins/golem15/wavepath/... ./parity 2&gt;&amp;1 | tee "${TMPDIR:-/tmp}/wavepath-unit.log" &amp;&amp; grep -q -- '^--- PASS:' "${TMPDIR:-/tmp}/wavepath-unit.log" &amp;&amp; ! grep -q -- '^--- FAIL:' "${TMPDIR:-/tmp}/wavepath-unit.log"</automated>
<fails_when>Non-zero exit, no PASS line or any FAIL line: handler/access/lifecycle/checker unit matrices fail, Docker-backed lifecycle setup fails, or named tests did not run.</fails_when>
</verify>
<acceptance_criteria>
- Every behavior bullet has at least one named table row and failure output names the row.
- Old tide fixture/manifest/upstream files from before Phase 31 load unchanged.
- Every high threat T-31-01..T-31-32 that belongs to tide/foundation/checkers has a direct regression test or gate mutation.
- Production changes, if any bug is found, are minimal and listed in the summary.
</acceptance_criteria>
<done>The generic recording toolkit, foundation app plugin and parity checkers have deterministic positive, edge, compatibility and fail-closed unit coverage.</done>
</task>
<task type="auto">
<name>Task 3: Run folded-todo regressions, full foundation gate, consumer suites and framework docs checks</name>
<files>../sm-chat-plugin/saving_test.go, ../sm-userfriends-plugin/saving_test.go, ../sm-user-plugin/saving_test.go, ../sm-demo-app/moderation_test.go, ../vue-chat-layer/tests/store.test.ts, ../sm-wavepath-app/scripts/check-parity.sh</files>
<read_first>31-08-SUMMARY.md, 31-09-SUMMARY.md and 31-10-SUMMARY.md final flow/event/field names and commits, saving tests in all three plugins, demo moderation tests, layer slash tests, 31-VALIDATION.md, project CLAUDE.md commands, scripts/check-parity.sh required test list</read_first>
<action>Per SC-3, SC-4, D-14 and D-22.
1. Expand the three saving test files into tables for every fire path, operation, field default, listener-free control, owning Rejection, plain error and no-write/no-post-event behavior. Expand demo moderation to each requested field and filename position.
2. Keep the slash test matrix explicit for known, unknown, `//`, bare `/`, empty loaded catalog and null/loading catalog; run the full layer suite and playground build.
3. Run each touched plugin's full short suite, demo's root/plugin suite and bm's build/required tests at the exact candidate commits recorded in 31-05.
4. Run `scripts/check-parity.sh` with no allow flags. It must execute corpus completeness, strict ported replay, broadcasts, upstream, foundation, consumers and self-tests and print exactly `recorded 196/196 ported 36 pending 160 foundation-pending 0`.
5. Run framework vet/short tests and both docs checks. Confirm the framework diff contains no consuming-application name and module docs match final tide identifiers/flags.
6. Update `31-VALIDATION.md` status through the validation workflow when execution reaches its sign-off; do not raw-edit STATE.md. Post the Phase 31 g15office progress comment through the configured integration.
7. Commit test-only expansions per repository. Planning/code commits remain separate.</action>
<verify>
<automated>for r in sm-chat-plugin sm-userfriends-plugin sm-user-plugin; do go -C ../$r vet ./... &amp;&amp; go -C ../$r test -count=1 -short ./... || exit 1; done &amp;&amp; go -C ../sm-demo-app vet . ./plugins/demo/... &amp;&amp; go -C ../sm-demo-app test -count=1 -short . ./plugins/demo/... &amp;&amp; go -C ../sm-bm-app build ./... &amp;&amp; go -C ../sm-bm-app test -count=1 -run '^(TestChatMounted|TestRealtimeDefaultDriver|TestRealtimeRoutes|TestRealtimeConfigDefaults|TestRemoteKeyOverride)$' .</automated>
<fails_when>Non-zero exit: a saving seam, demo listener or existing consumer behavior fails at the candidate commits, or a required bm test fails.</fails_when>
<automated>pnpm --dir ../vue-chat-layer test -- --run &amp;&amp; pnpm --dir ../vue-chat-layer run build:playground</automated>
<fails_when>Non-zero exit: any slash regression or existing layer test fails, or the playground does not build.</fails_when>
<automated>OUT="$(../sm-wavepath-app/scripts/check-parity.sh 2&gt;&amp;1)" &amp;&amp; printf '%s\n' "$OUT" | grep -qx 'check-parity: recorded 196/196 ported 36 pending 160 foundation-pending 0'</automated>
<fails_when>Non-zero exit or exact summary absent: a corpus/golden/upstream/foundation/consumer/self-test stage failed, a required test skipped, Docker was unavailable, or an allow flag was needed.</fails_when>
<automated>go vet ./... &amp;&amp; go test -count=1 -short ./... &amp;&amp; go run ./cmd/summer docs:build --check 2&gt;&amp;1 | grep -q 'no problems found' &amp;&amp; go test -count=1 -run '^TestDocsTree$' -v ./cmd/summer 2&gt;&amp;1 | grep -q -- '^--- PASS: TestDocsTree'</automated>
<fails_when>Non-zero exit: framework vet/short tests fail, docs drift or name an absent identifier/command, or TestDocsTree did not run and pass.</fails_when>
</verify>
<acceptance_criteria>
- All folded-todo regression tables pass, including no-listener controls.
- Full gate uses no allow flag and prints the exact 196/36/160/0 counts.
- Framework docs build/check and TestDocsTree pass; no consuming app name was added to framework source/docs/tests.
- Each touched repository is clean for files owned by this phase; unrelated changes remain unstaged.
</acceptance_criteria>
<done>Phase 31's unit suites, consumers, foundation gate and documentation checks are green, with remaining 160 routes explicitly pending for Phases 31.1 and 31.2.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
| automated evidence to completion verdict | missing or skipped work must not look green |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-31-33 | Spoofing | gate passes on zero, skipped or missing tests | high | mitigate | planted go-test JSON detector matrix, exact required test names and PASS/count checks |
| T-31-34 | Tampering | negative tests modify committed corpus | high | mitigate | copy fixture/manifest/sidecar trees to t.TempDir; clean-tree and hash checks after mutation suite |
| T-31-35 | Repudiation | untested threat mitigations | medium | mitigate | map high threats to named unit/gate cases and record command evidence in summary |
| T-31-36 | Spoofing | consumer tests resolve wrong plugin commit | high | mitigate | assert submodule HEAD equals 31-05 candidate hash before bm/demo tests |
| T-31-37 | Denial of service | Docker failure represented as skip | medium | mitigate | TestMain skips only under testing.Short; full gate treats unavailable Docker and skipped required names as failure |
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
</threat_model>
<verification>
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
</verification>
<success_criteria>
Unit tests last: tide, app foundation, parity/gate and folded-todo regression matrices is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
</success_criteria>
<output>
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-11-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
</output>

View File

@@ -0,0 +1,188 @@
# Phase 31: Chat polish against WavePath clients - Context
**Gathered:** 2026-11-13
**Status:** Ready for planning
<domain>
## Phase Boundary
WavePath's community traffic is recorded from the PHP backend with `tide`, replayed against Go, and Go is fixed until the replay is green. "Community traffic" is wider than the roadmap entry's wording (D-09): every route under `/_wave/api/v1/community`, the guest routes, the push routes and the bot and token routes, about 190 routes, plus every realtime publication those routes cause.
The replay target is a new application repo, `sm-wavepath-app`, which mounts the seven shared chat plugins and serves the recorded `/_wave` paths from an in-repo `wavepath` app plugin. That plugin ports only what the recorded routes exercise. It is the start of WavePath's Go app, not the whole app port.
Out of scope:
- The rest of WavePath's backend (diary, practices, trainings, stats, auth, journal, payments, admin screens). They come with the later WavePath phases.
- The MariaDB to Postgres import, the production cutover and the pre-freeze re-record (D-06).
- `electron-wavepath` and `tauri-wavepath-desktop` as separate recording clients. The roadmap names three clients: `vue-wavepath-app`, `wavepath-mcp` and `hubot-wavepath`.
- Any commit in the `wavepath.org` repo (D-08).
**Repos touched:**
- `sm-wavepath-app` (new): app skeleton, `wavepath` app plugin, `parity/` corpus, seeders, recording scripts, the gate script.
- The seven shared plugin repos, for parity fixes and re-freeze deltas: `sm-chat-plugin`, `sm-chatchannels-plugin`, `sm-chatbots-plugin`, `sm-chatvideo-plugin`, `sm-forum-plugin`, `sm-herald-plugin`, `sm-userfriends-plugin`.
- `sm-user-plugin`, only additively and only if a recorded route needs it.
- `summercms.go`, only for `tide` or `lighthouse` gaps.
- `sm-demo-app`, `sm-bm-app` and the vue layers (`vue-chat-layer`, `vue-chatvideo-layer`, `vue-forum-layer`, `vue-userfriends-layer`), to follow shared-plugin changes (D-15) and for the folded todos.
- `sm-oauthserver-plugin`, for the folded OIDC parity recording.
**Roadmap corrections** (make them in the first planning commit):
- "Depends on": remove Phase 30. Keep Phase 19 and Phase 19.1 (D-05).
- "Repos": replace with the list above.
- Success criterion 1: the corpus is the community surface defined in D-09, not only "chat, channel, thread, video-room and push routes".
- Success criterion 2: every publication of every writing step, on any namespace (D-10).
- Success criterion 3: name the gate from D-15. `sm-bm-app` and `sm-demo-app` build and pass their tests with the released plugin versions.
</domain>
<decisions>
## Implementation Decisions
### Replay target and paths
- **D-01:** **Recorded `/_wave` requests replay unchanged against `/_wave` routes served by Go.** A Go app mounts the seven plugins and an in-repo `wavepath` app plugin registers the recorded paths as aliases over the plugin services. `tide` gets no path-rewrite feature, and the plugin test hosts get no `/_wave` aliases. This is the "thin aliases" route that P19 D-07 and P19.1 D-05 left open for the WavePath port.
- **D-02:** **The app is a new sibling repo, `sm-wavepath-app`,** laid out like `fonoteka.go`: `summer.yaml`, shared plugins as git submodules at `plugins/golem15/<name>`, the app plugin in-repo, `parity/` with the manifest, fixtures, capture rules and broadcast goldens, a `replace` of the framework to `../summercms.go` during development. WavePath's own agent later grows the same repo for the rest of the app port. — **Reversibility:** costly — the repo name, module path and `parity/` layout are what WavePath's agent and every later WavePath phase build on.
- **D-03:** **The app plugin ports whatever the recorded routes need, not only aliases.** That includes the controller logic of WavePath's community controllers and the host seams: the channel and forum access resolvers, the bot auth resolver, the herald profile and presence gate, the notification dispatch, the group context adapter and the group lifecycle wiring (a created group spawns its chat and channels, a deleted group ends video and removes the forum context). Routes outside the corpus stay unported.
- **D-04:** **One named scenario, seeded on both sides.** The scenario (users in each role, groups, channels, conversations, an existing thread, pins, a call link, forum content, friendships, a bot, a guest) is defined once. A PHP reset script seeds it into the local WavePath database, and a Go fixture plugin in `sm-wavepath-app` seeds the same rows into Postgres, as `fonoteka.go/parity` does with `fonoteka_reset.php` and `fixtureplugin`. `summer import:winter` is not used here.
### Recording source and timing
- **D-05:** **Phase 31 does not depend on Phase 30.** The user: "phase 30 was meant for plytarium cutover, wavepath is totally separate project". The roadmap dependency was sequencing only.
- **D-06:** **Record now, re-record before the WavePath freeze.** The corpus is recorded from today's PHP and Go is fixed against it. Shortly before the WavePath cutover the whole corpus is re-recorded with a drift report and each drift is resolved (the Phase 30 D-12 pattern). That re-record belongs to the WavePath cutover phase. Phase 31 must leave it runnable unattended.
- **D-07:** **Proxy once, then scripted specs.** The three real clients run through `summer parity:proxy` once to learn the exact requests, headers and bodies they send. Those sessions become committed spec flows that `summer parity:record` re-runs without a person.
- **D-08:** **The PHP backend is the local checkout at `/media/nvme/dev/jz/wavepath.org`,** brought up by a script this phase delivers: the PHP server, its database with the D-04 scenario, Centrifugo pointed at the `tide` recorder, and LiveKit and the push service answered by the `tide` upstream proxy. Nothing is committed in `wavepath.org`. The reset script and the env overlay live in `sm-wavepath-app/parity` and are applied from outside. The phase may check the PHP submodules out at the commits the repo pins and may write to the local dev database.
### Corpus boundary
- **D-09:** **The corpus is WavePath's community surface, about 190 routes:**
- everything under `/_wave/api/v1/community`: `groups` (108 routes, group administration included), `dm`, `threads`, `prefs`, `forums`, `friends`, `notes`, `status`, `join`, `presence`, `call-links`, `call-guest`;
- `/_wave/api/v1/guest/*` (call-link knock, guest session, guest thread and reactions);
- `/_wave/api/v1/push/*`;
- the bot and token routes under `/api/v1` (`conversations`, `conversations/{id}/messages`, `realtime/token`) and the `/hooks/{token}` webhook.
The researcher re-counts from `routes.php` at the recording commit and lists any route under these prefixes that no client calls.
- **D-10:** **Every publication of every writing step is asserted.** Each corpus step that writes gets a broadcast golden with all publications PHP sent for it, on any namespace (`chat`, `video`, `presence:`, `user`, `wave`). Channel authorization (the Centrifugo subscribe proxy and `realtime/token`) is replayed as ordinary routes.
- **D-11:** **Case depth is client paths plus denials.** Per route:
- the cases the clients produced in the proxy sessions;
- one denial per access rule (unauthenticated 401, non-member 403 or 404);
- the validation errors the UI can trigger (422);
- one 429 case per named rate bucket.
Outbound LiveKit and web-push calls are recorded as `tide` upstream sidecars and asserted on replay.
### Drift and fix policy
- **D-12:** **The port contract is re-frozen at the recording commit.** It replaces the commits in P19 D-01 and P19.1 D-01. The WavePath commit and its pinned submodule commits are written into the manifest. Every delta since the old freeze that the corpus exercises is ported in this phase: into the shared Go plugin when the PHP change is in a shared plugin (chat `943b712..fbfbcf9`, attachment streaming with Range support), into the app plugin when it is in `wavepath` (guest threads and guest identity). — **Reversibility:** costly — names and shapes from the new freeze are copied into every app that mounts the shared plugins.
- **D-13:** **Go reproduces PHP's observable behaviour, quirks included.** The one exception is a security defect (data reaching a non-member, a missing access check): Go keeps the safe behaviour, and the case goes into an accepted-differences file with its reason. The user signs off each entry. Precedent: the Phase 19.5 email-proof divergence.
- **D-14:** **The PHP shape wins in the shared plugins; consumers follow.** A parity fix corrects the shared serializer or behaviour itself, so the generic `/_x/api/v1` APIs and the `/_wave` aliases keep one serializer set. Each changed plugin gets a patch tag and a changelog post on `/changelog/plugins`, and `sm-demo-app` and the vue layers are updated in this phase. A renamed or removed field is called out in the release notes. The user's condition: "1 is fine as long as sm-bm-app keeps working". Before any plugin tag, `sm-bm-app` (mounts chat, chatchannels and chatbots, with its own frontend) must build with the new plugin commits, pass its tests (`chat_test.go`, `realtime_test.go`), and have its frontend checked against any renamed or removed field. — **Reversibility:** costly — a changed field in a published plugin API reaches every mounting app and vue layer.
- **D-15:** **The phase closes at zero pending.** Every corpus route is `ported` with passing cases, every broadcast golden is asserted, and the only non-matching cases are signed entries in the accepted-differences file. A fail-closed gate script checks this, and checks that `sm-bm-app` and `sm-demo-app` build and pass. The gate lives in `sm-wavepath-app`, because a script in `summercms.go` would name an application.
### Phase split and research answers (decided at planning, 2026-11-13)
- **D-16:** **The work is split into three phases.** Research sized it at 12 to 15 large plans. Phase 31 is the corpus and harness: the `tide` additions (T-1 to T-10 in `31-RESEARCH.md`), the `sm-wavepath-app` skeleton, the PHP stack and the scenario, the full PHP recording of all 196 routes with broadcast and upstream sidecars, PHP self-replay green, the foundation slice ported (envelope, cookie actor, rate buckets, contexts, resolvers, the `wave` and presence authorizers, the realtime routes, groups, members, invites, join, friends, group lifecycle), the three folded todos and a unit-test plan. Phase 31.1 ports messaging and releases the chat Range delta. Phase 31.2 ports the satellites and closes out. This amends three earlier decisions for Phase 31:
- D-15: the zero-pending gate closes Phase 31.2. In Phase 31 the gate script exists, fails closed on any failing or unrecorded case, and reports the pending count; it requires zero pending only for the foundation slice.
- D-12: the manifest is frozen at the recording commit in Phase 31. The chat attachment Range delta is ported in Phase 31.1 and the guest thread and guest identity delta in Phase 31.2.
- D-13: the accepted-differences file is created in Phase 31 and gets entries as routes are ported; the final sign-off is in Phase 31.2. The security review named under Claude's Discretion runs in Phase 31.2, when the guest, bot, token and webhook code exists.
- **D-17:** **Two recording clients, not three.** `wavepath-mcp` calls no corpus route (it calls only diary, practices, trainings, stats, me and state). The corpus is recorded through `vue-wavepath-app` and `hubot-wavepath`. `wavepath-mcp` is recorded with the rest of the WavePath backend in a later phase. D-09's boundary is unchanged.
- **D-18:** **Shared notes stay in the corpus, on a minimal diary read model.** The app plugin gets a small `DiaryEntry` read model and fixture rows, marked provisional for WavePath's agent to replace when the diary is ported. The notes routes are recorded in Phase 31 and ported in Phase 31.2.
- **D-19:** **All 17 routes that no client calls stay in the corpus.** Each gets one hand-written success case recorded from PHP, plus its denial and validation cases.
- **D-20:** **The PHP stack is isolated from the other agent's work.** [informational] The database is an isolated MariaDB container, not the dev database. The pinned submodule commits (`chat` at `fbfbcf9`, `journal`) are read through a git worktree or export under the parity root, so the `wavepath.org` working tree is not changed at all. This is stricter than D-08 allows.
- **D-21:** **Replay logs in without the auth routes.** [informational] Both seeders mint the session JWTs into the `tide` vars store and requests carry them as the `token` cookie; `/_wave/api/v1/auth/login` stays outside the corpus.
- **D-22:** **The slash fix matches WavePath.** WavePath refuses unknown slash text (the SPA blocks it from the command catalog and keeps the draft; PHP answers 422 `unknown_command`). The layer fix is therefore: check the first token against the command catalog client-side, keep the draft on an unknown command, and support a `//` escape that posts the rest as text. Unknown slash text is not posted as text.
Left for the later phases' own discussion: the search backend for the search cases (Typesense or the null driver) and the attachment `url` rewrite (research recommends app-side).
### Claude's Discretion
- Go package, type and route-handler names in the app plugin, and the layout inside `parity/`.
- The scenario's exact rows, as long as every access rule in D-11 has a user on each side of it.
- How the PHP reset script is run against the checkout without committing there (artisan tinker, a script path, a mounted file).
- The name of the gate script and of the accepted-differences file.
- Whether `tide` needs additions (for example more broadcast normalisation rules for chat payloads). Any such change is generic, documented in `modules/tide/README.md` and names no application.
- The module path and git remote of `sm-wavepath-app`. Creating a remote and pushing need the user's go-ahead.
- Plan count and split, subject to the plan-count checkpoint and "unit tests are the last plan". This is a large phase; say so at the checkpoint and propose a split into decimal phases if the count gets unwieldy.
- Run the security-review agent: the app plugin adds guest access, bot and token authentication, a webhook and access resolvers.
### Folded Todos
- **Record PHP OIDC parity against WavePath before the OIDC cutover** (`2026-10-19-record-php-oidc-parity-against-wavepath.md`, `sm-oauthserver-plugin`). Phase 19.4 shipped the harness but never recorded PHP. The local WavePath stack from D-08 is exactly what the todo's runbook needs, so the recording is done here: follow `../sm-oauthserver-plugin/testdata/parity/README.md` until `PHASE194_REQUIRE_PARITY=1 go test -run '^(TestPHPParityReplay|TestIDTokenShapeParity)$' ./...` passes. It is separate from the community corpus and lives in the plugin repo.
- **Chat messages that start with "/" but name no command are posted as text** (`chat-slash-text-escape.md`, `../vue-chat-layer/app/composables/useChat.ts`). Every text starting with "/" is dispatched as a command and refused. Fix in the layer: dispatch only when the first token is a known trigger from the command catalog, or support a "//" escape. The researcher first checks what `vue-wavepath-app` and the PHP command controller do with such text and matches that.
- **Moderate profile names, friend-group names and chat attachment filenames** (`moderation-profile-group-and-filenames.md`, `../sm-demo-app/plugins/demo/moderation.go`). The demo's filter covers only message content and forum text. Add the checks through additive seams (a user-plugin saving event, a group saving seam in userfriends, filenames on chat's message-saving event). The seams are additive and must leave PHP parity untouched: with no listener, behaviour is unchanged.
</decisions>
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### The contract (PHP, read-only)
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/routes.php` — the route table. Groups at lines 195 (auth), 222 (guest), 252 (JWT API, community routes inside), 948 and 1022 (`/api/v1` token and bot), 1073 (`/hooks`).
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/controllers/api/` — the community controllers whose logic D-03 ports (`CommunityForumController`, `CommunityFriendsController`, `CommunityGroupController`, `CommunityVideoController`, `CommunityCommandController`, `CommunitySharedNoteController`, `BotRestController`, `PushSubscriptionController`).
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/Plugin.php` — seam bindings and group lifecycle wiring (lines 160-460 at the old freeze; re-check at the recording commit).
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/classes/{chatbots,notifications,forum,video}/` — the host implementations of the seams.
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/{chat,chatchannels,chatbots,chatvideo,forum,herald,userfriends}` — the shared plugins. The repo pins chat at `fbfbcf9`; the working tree had it at `943b712` on 2026-11-13.
- `/media/nvme/dev/jz/wavepath.org/vue-wavepath-app/src/`, `/media/nvme/dev/jz/wavepath.org/wavepath-mcp/src/`, `/media/nvme/dev/jz/wavepath.org/hubot-wavepath/src/` — the three clients that are recorded.
- `/media/nvme/dev/jz/wavepath.org/.planning/notes/summercms-framework-asks-for-wavepath.md` — WavePath's hand-off list; section B is what its own agent ports later.
### Prior decisions that still bind
- `.planning/phases/19-chat-and-chatchannels/19-CONTEXT.md` — D-02 (no QuestStream trace), D-06 to D-10 (generic API, one serializer set), D-11 to D-14 (context registry, alias rewrite, festival hooks, deny-all resolvers), D-16 and D-17 (lighthouse namespaces). D-01's commits are superseded by D-12 here.
- `.planning/phases/19.1-chat-satellites/19.1-CONTEXT.md` — D-05 (satellite generic APIs and rate buckets), D-08 (group lifecycle is app wiring), D-10 (push through fetchguard), D-13 to D-15 (LiveKit, reconciler, video events).
- `.planning/phases/30-cutover/30-CONTEXT.md` — D-11 and D-12, the manifest acceptance set and the re-record with a drift report that D-06 and D-15 copy.
- `.planning/notes/2026-10-18-roadmap-reorder-demo-release-wavepath.md` and `.planning/notes/wavepath-framework-asks-division.md` — why this phase opens the WavePath work.
- `.planning/seeds/SEED-261007-0tb-wavepath-port.md` — size of the whole WavePath port.
- `.planning/notes/core-plugins-own-repos.md` — plugin commit, tag and submodule pointer workflow.
### Tooling and patterns to copy
- `modules/tide/README.md` — flows, recording proxy, capture rules, manifests, the Centrifugo recorder and broadcast goldens, upstream sidecars and the upstream recording proxy.
- `../fonoteka.go/parity/` — the model for D-02 and D-04: `manifest.yaml`, `fixtures/`, `capture-rules.yaml`, `capture_clients.mjs`, `fonoteka_reset.php`, `fixtureplugin/`, `broadcast_goldens_test.go`, `upstream/`.
- `../fonoteka.go/scripts/dev-stack.sh` — the fail-closed local stack script, a model for D-08.
- `../sm-demo-app/summer.yaml`, `../sm-demo-app/chat_test.go`, `../sm-demo-app/realtime_test.go` — an app that already mounts all seven plugins.
- `../sm-bm-app/summer.yaml`, `../sm-bm-app/chat_test.go`, `../sm-bm-app/realtime_test.go` — the consumer D-14 protects.
### Folded todos
- `.planning/todos/pending/2026-10-19-record-php-oidc-parity-against-wavepath.md` and `../sm-oauthserver-plugin/testdata/parity/README.md`
- `.planning/todos/pending/chat-slash-text-escape.md`
- `.planning/todos/pending/moderation-profile-group-and-filenames.md`
</canonical_refs>
<code_context>
## Existing Code Insights
### Reusable Assets
- `tide`: everything the recording needs exists (loopback proxy with sessions, spec recording, manifest record and replay, Centrifugo recorder, broadcast goldens, upstream sidecars). It has no request-path rewriting, which D-01 makes unnecessary. Its broadcast normalisation has rules written for album and notification payloads; chat payloads may need generic additions.
- The seven shared plugins, each with a typed service API, a generic `/_x/api/v1` API, a test-only host and `testdata/goldens/` built from PHP fixtures (never from a live PHP backend).
- `sm-demo-app`: mounts all seven plugins and has chat, realtime and video tests; a working reference for wiring contexts and resolvers.
- `lighthouse`: namespaces `chat`, `video` and `user` are registered by the plugins. `presence:` and `wave` belong to the app plugin.
### Established Patterns
- App parity suite in the app repo, `go test ./parity` on testcontainers Postgres, pending never counts as a pass.
- One scenario seeded by a PHP reset script and a Go fixture plugin.
- Fail-closed per-phase gate script.
- Plugin first (commit, push, tag), then the submodule pointer bump in each app as a separate commit.
### Integration Points
- `sm-wavepath-app` registers the group context alias, installs the access resolvers, bot auth, herald profile and presence gate, and wires group lifecycle events to chat, channels, video and forum.
- Consumers of the shared plugins today: `sm-demo-app` (all seven) and `sm-bm-app` (chat, chatchannels, chatbots).
- The local PHP checkout has uncommitted work and belongs to another agent; the recording script must not leave changes in its working tree beyond the submodule checkouts and the dev database.
</code_context>
<specifics>
## Specific Ideas
- "phase 30 was meant for plytarium cutover, wavepath is totally separate project": no ordering against the Płytarium work.
- "local wavepath is there in /media/nvme/dev/jz/wavepath.org we can work with it": use that checkout for the recording.
- "1 is fine as long as sm-bm-app keeps working": `sm-bm-app` is a hard gate on every shared-plugin release.
</specifics>
<deferred>
## Deferred Ideas
- The pre-freeze re-record with a drift report: a task of the WavePath cutover phase (D-06).
- The rest of WavePath's backend and the MariaDB to Postgres import: later WavePath phases, owned with WavePath's agent.
- `electron-wavepath` and `tauri-wavepath-desktop` as recording clients: with the full-surface corpus at the cutover.
- A manual session of the real clients against the Go app: not required to close this phase (D-15); belongs to the cutover.
### Reviewed Todos (not folded)
- The other ten matches were keyword noise and concern other work: the WinterCMS vs SummerCMS benchmark, gate scripts that name applications, changelog previous/next links, the forum and friends 401 refresh, MailBlocker, the menu plugin port, the first password for social accounts, README `src=` fences, the fonoteka README and the translate messages editor.
</deferred>
---
*Phase: 31-chat-polish-against-wavepath-clients*
*Context gathered: 2026-11-13*

View File

@@ -0,0 +1,193 @@
# Phase 31: Chat polish against WavePath clients - Discussion Log
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
**Date:** 2026-11-13
**Phase:** 31-chat-polish-against-wavepath-clients
**Areas discussed:** Replay target and paths, Recording source and timing, Corpus boundary, Drift and fix policy
---
## Todo cross-reference
13 pending todos matched; ten were keyword noise. Three were offered.
| Option | Description | Selected |
|--------|-------------|----------|
| None | Fold nothing | |
| PHP OIDC parity | Record PHP OIDC parity against WavePath (sm-oauthserver-plugin) | ✓ |
| Slash text escape | "/" text that names no command is refused (vue-chat-layer) | ✓ |
| Moderate filenames | Moderate profile names, group names and attachment filenames (sm-demo-app) | ✓ |
**User's choice:** all three folded.
---
## Replay target and paths
### How recorded /_wave traffic reaches the Go plugins
| Option | Description | Selected |
|--------|-------------|----------|
| /_wave aliases in a Go app | App skeleton mounts the plugins and serves the recorded paths, host seams wired | ✓ |
| Path map in tide | Generic rewrite rules in tide, replay against the generic API on a test host | |
| Aliases in plugin test hosts | Each plugin's test host registers /_wave-shaped aliases | |
### Where the app skeleton and corpus live
| Option | Description | Selected |
|--------|-------------|----------|
| New sm-wavepath-app | Sibling repo laid out like fonoteka.go | ✓ |
| Inside the wavepath.org repo | Go directory next to the PHP code | |
| Throwaway parity host | Parity-only module, aliases rewritten later | |
### Diffs caused by Wave controller logic
| Option | Description | Selected |
|--------|-------------|----------|
| Port what chat routes need | App plugin ports controller logic and host seams for the recorded routes | ✓ |
| Thin aliases only | Controller-caused diffs stay pending for the app port | |
| You decide per route | Researcher classifies, planner picks | |
### Starting state
| Option | Description | Selected |
|--------|-------------|----------|
| One scenario, seeded twice | PHP reset script plus Go fixture plugin | ✓ |
| Import the PHP database | summer import:winter into Postgres | |
| Flows build their own state | No shared seed beyond users | |
**User's choice:** the recommended option each time.
---
## Recording source and timing
### When the corpus is recorded
| Option | Description | Selected |
|--------|-------------|----------|
| Now, re-record before cutover | Record from today's PHP, re-record with a drift report before the freeze | ✓ |
| Build now, record later | Binding corpus waits until the migration is near | |
| Wait for Phase 30 | Keep the roadmap order | |
**User's choice:** free text first: "Why would it depend on phase 30, phase 30 was meant for plytarium cutover, wavepath is totally separate project". After the clarification that the dependency was sequencing only, the user chose option 1.
**Notes:** the Phase 30 dependency is removed from the roadmap entry.
### How traffic is captured
| Option | Description | Selected |
|--------|-------------|----------|
| Proxy once, then scripted specs | Learn the real requests through the proxy, commit spec flows | ✓ |
| Real clients through the proxy only | Every recording is a live session | |
| Scripted specs from source | Specs written from the clients' API code | |
### Which PHP backend
| Option | Description | Selected |
|--------|-------------|----------|
| Local stack, scripted | Phase delivers a script that brings up the local checkout | ✓ (as interpreted) |
| Local stack, you start it | User starts the stack | |
| Staging through a tunnel | Deployed staging over SSH | |
**User's choice:** free text: "local wavepath is there in /media/nvme/dev/jz/wavepath.org we can work with it".
**Notes:** recorded as the local checkout, brought up by a script from this phase.
### What may be written in wavepath.org
| Option | Description | Selected |
|--------|-------------|----------|
| Nothing committed there | Reset script and env overlay live in sm-wavepath-app/parity | ✓ |
| A parity/ directory in wavepath.org | Committed on a branch there | |
| Hand it to WavePath's agent | Spec only, implemented by the other agent | |
---
## Corpus boundary
### Neighbouring route groups (multi-select)
| Option | Description | Selected |
|--------|-------------|----------|
| Forum and friends | community/forums (16), community/friends (8) | ✓ |
| Bot and token REST | /api/v1 conversations, realtime/token, /hooks/{token} | ✓ |
| Guest calls and guest thread | /_wave/api/v1/guest/* and community/call-guest | ✓ |
| Shared notes and status | community/notes, status, join | ✓ |
### How much of community/groups
| Option | Description | Selected |
|--------|-------------|----------|
| All of community/* | About 190 routes with guest, push and bot/token | ✓ |
| Chat-facing group routes only | Group administration left to the app port | |
| All, split in two phases | Chat core in 31, the rest in 31.1 | |
### Realtime assertions
| Option | Description | Selected |
|--------|-------------|----------|
| Every publication of every write step | All namespaces, authorization routes replayed | ✓ |
| Only chat, video and presence: | user and wave publications pending | |
| Goldens for a chosen event list | Only events the clients listen to | |
### Case depth
| Option | Description | Selected |
|--------|-------------|----------|
| Client paths plus denials | Client cases, one denial per rule, UI validation errors, upstream sidecars | ✓ |
| Client paths only | Only what the proxy sessions produced | |
| Full matrix | Every role and every rule | |
---
## Drift and fix policy
### Port contract after PHP drift
| Option | Description | Selected |
|--------|-------------|----------|
| Re-freeze at the recording commit | Deltas the corpus exercises are ported in this phase | ✓ |
| Keep the old freeze, park the drift | Drift diffs pending | |
| Record from the old commits | PHP submodules checked out at the frozen commits | |
### PHP quirks and bugs
| Option | Description | Selected |
|--------|-------------|----------|
| Reproduce, except security | Signed accepted-differences file for security defects | ✓ |
| Reproduce everything | Unsafe behaviour fixed on PHP first | |
| Fix obvious bugs in Go | Each listed as an accepted difference | |
### Releasing shared-plugin fixes
| Option | Description | Selected |
|--------|-------------|----------|
| PHP shape wins, layers follow | Patch tags, changelog posts, demo app and vue layers updated | ✓ |
| Additive only in shared plugins | /_wave alias adapts output in the app plugin | |
| Ask per breaking change | Stop on removed, renamed or retyped fields | |
**User's choice:** free text: "1 is fine as long as sm-bm-app keeps working".
**Notes:** sm-bm-app mounts chat, chatchannels and chatbots; it is a hard gate before every plugin tag.
### Closing bar
| Option | Description | Selected |
|--------|-------------|----------|
| Zero pending, signed exceptions | Fail-closed gate, sm-bm-app and sm-demo-app pass | ✓ |
| Chat core green, rest may pend | Named pending list for the next phase | |
| Green plus a manual client session | Adds a manual session of the three clients | |
---
## Claude's Discretion
- Names and layout in the app plugin and `parity/`, the scenario's rows, how the PHP reset script runs from outside the checkout, gate and accepted-differences file names, generic `tide` additions, the module path and remote of `sm-wavepath-app`, plan count and split.
- The gate script lives in `sm-wavepath-app` rather than `summercms.go/scripts`, so that no framework script names an application.
## Deferred Ideas
- Pre-freeze re-record with a drift report (WavePath cutover phase).
- The rest of WavePath's backend and the database import.
- electron and tauri clients as recording clients.
- A manual session of the real clients against the Go app.

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,96 @@
---
phase: "31"
slug: "chat-polish-against-wavepath-clients"
# status lifecycle: draft (seeded by plan-phase) → validated (set by validate-phase §6)
# audit-milestone §5.5 distinguishes NOT-VALIDATED (draft) from PARTIAL (validated + nyquist_compliant: false) (#2117)
status: draft
nyquist_compliant: false
wave_0_complete: false
created: "2026-11-13"
---
# Phase 31 — Validation Strategy
> Per-phase validation contract for feedback sampling during execution.
> Source: `31-RESEARCH.md`, section "Validation Architecture".
---
## Test Infrastructure
| Property | Value |
|----------|-------|
| **Framework** | Go `testing` (testcontainers Postgres for the parity suite); Vitest in the vue layers |
| **Config file** | none in `sm-wavepath-app` yet — Wave 0 creates the repo |
| **Quick run command** | `go vet ./... && go test -short ./...` in each touched repo |
| **Full suite command** | `go vet ./... && go test ./...` in `summercms.go`, `sm-wavepath-app` and each changed plugin; `scripts/check-parity.sh` in `sm-wavepath-app` |
| **Estimated runtime** | quick: under 60 seconds per repo; full with Docker: several minutes |
---
## Sampling Rate
- **After every task commit:** Run `go vet ./... && go test -short ./...` in the touched repo
- **After every plan wave:** Run `go test ./...` (Docker) in the touched repos and `go test ./parity` in `sm-wavepath-app`
- **Before `/msd-verify-work`:** `scripts/check-parity.sh` in `sm-wavepath-app` must be green
- **Max feedback latency:** 60 seconds for the quick run
---
## Per-Task Verification Map
Task IDs are filled in by the planner. The rows below are the behaviours every plan set must cover.
| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
| TBD | TBD | TBD | SC-1 every corpus route recorded from PHP | — | fixtures carry no secrets (`--check-secrets`) | corpus check | `go run ./parity/check_corpus.go --manifest parity/manifest.yaml --routes <routes.php> --require-recorded --check-secrets` | ❌ W0 | ⬜ pending |
| TBD | TBD | TBD | SC-1 Go replays every ported route; pending never passes | — | denial cases (401, 403, 404) replay | integration | `go test ./parity -run TestParityCorpus` | ❌ W0 | ⬜ pending |
| 31-07-T2 | 31-07 | 6 | SC-1 foundation-pending 0 with 160 routes explicitly pending for Phases 31.1/31.2 (D-16) | T-31-24 | fail-closed foundation gate | gate | `scripts/check-parity.sh` | ❌ W0 | ⬜ pending |
| TBD | TBD | TBD | SC-2 publications of each writing case match the golden (D-10) | — | no publication reaches a non-member channel | integration | `go test ./parity -run TestBroadcasts` | ❌ W0 | ⬜ pending |
| TBD | TBD | TBD | SC-2 channel authorization routes replay | — | subscribe proxy and `realtime/token` deny non-members | integration | `go test ./parity -run 'TestParityCorpus/.*realtime'` | ❌ W0 | ⬜ pending |
| TBD | TBD | TBD | D-11 vendor calls match the sidecars | — | N/A | integration | `go test ./parity -run TestUpstreamSidecarsAreReplayed` | ❌ W0 | ⬜ pending |
| TBD | TBD | TBD | SC-3 `sm-bm-app` builds and passes with the new plugin commits (D-14) | — | N/A | integration | `cd ../sm-bm-app && go build ./... && go test ./...` | ✅ | ⬜ pending |
| TBD | TBD | TBD | SC-3 `sm-demo-app` builds and passes | — | N/A | integration | `cd ../sm-demo-app && go test ./...` | ✅ | ⬜ pending |
| TBD | TBD | TBD | SC-3 framework docs name no application | — | N/A | docs check | `summer docs:build --check` and `go test ./cmd/summer -run TestDocsTree` | ✅ | ⬜ pending |
| TBD | TBD | TBD | SC-4 tide additions | — | N/A | unit | `go test ./modules/tide/...` | ✅ (extend) | ⬜ pending |
| 31-11-T2 | 31-11 | 7 | SC-4 foundation app-plugin services | T-31-20, T-31-21, T-31-22, T-31-24 | envelope, cookie actor, buckets, contexts, resolvers, authorizers, realtime, groups/members/invites/join/friends/lifecycle | unit | `go test -short ./plugins/golem15/wavepath/...` | ❌ W0 | ⬜ pending |
| TBD | TBD | TBD | Todo: OIDC parity | — | N/A | integration | `PHASE194_REQUIRE_PARITY=1 go test -count=1 -run '^(TestPHPParityReplay\|TestIDTokenShapeParity)$' ./...` in `sm-oauthserver-plugin` | ✅ (skips today) | ⬜ pending |
| TBD | TBD | TBD | Todo: moderation seams fire and reject | — | with no listener, behaviour is unchanged | unit | `go test -short ./...` in user, userfriends, chat; `go test ./... -run TestModeration` in `sm-demo-app` | partly | ⬜ pending |
| TBD | TBD | TBD | Todo: slash handling in the layer | — | N/A | unit | the layer's Vitest suite (`pnpm --dir ../vue-chat-layer test`) | ✅ (extend) | ⬜ pending |
*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
---
## Wave 0 Requirements
- [ ] `sm-wavepath-app` repo: `go.mod`, `go.work`, submodules, `summer.yaml`
- [ ] `parity/parity_test.go` with a `TestMain` that calls `flag.Parse()` and checks `testing.Short()`
- [ ] `parity/check_corpus.go` and `routes.snapshot`
- [ ] `parity/fixtureplugin` and `wavepath_reset.php` for the scenario
- [ ] `scripts/parity-stack.sh` and `parity/php_parity.sh`
- [ ] `scripts/check-parity.sh`
- [ ] tide tests for each addition (T-1 to T-10 in `31-RESEARCH.md`)
---
## Manual-Only Verifications
| Behavior | Requirement | Why Manual | Test Instructions |
|----------|-------------|------------|-------------------|
| PHP self-replay is green | SC-1 | needs the local PHP stack running; not part of `go test` | bring the stack up with `scripts/parity-stack.sh`, then `summer parity:replay --manifest parity/manifest.yaml --self-check true` |
| Proxy sessions of the real clients | D-07 | done once by a person driving the clients through `summer parity:proxy` | follow the recording runbook in `sm-wavepath-app/parity/README.md` |
| Accepted-differences review for foundation entries | D-13, D-16 | each Phase 31 entry needs the user's signature; final corpus sign-off is Phase 31.2 | review foundation entries before the Phase 31 gate; do not require 31.1/31.2 entries yet |
---
## Validation Sign-Off
- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
- [ ] Wave 0 covers all MISSING references
- [ ] No watch-mode flags
- [ ] Feedback latency < 60s
- [ ] `nyquist_compliant: true` set in frontmatter
**Approval:** pending

View File

@@ -0,0 +1 @@

View File

@@ -0,0 +1,119 @@
# Phase 31.1: WavePath messaging parity - Context
**Gathered:** 2026-11-13
**Status:** Ready for planning
<domain>
## Phase Boundary
The messaging routes of the WavePath corpus recorded in Phase 31 replay green against Go: group chat, channels, direct messages, threads, commands, reactions, emoji, preferences, pins and attachments, including the attachment streaming delta with Range support (31 D-12) released in `sm-chat-plugin`. Broadcast goldens for writing cases are asserted. `sm-bm-app` and `sm-demo-app` build and pass with each released plugin version (31 D-14). Unit tests are the last plan.
Out of scope (Phase 31.2): presence and status, notifications and push, full link-unfurl resolve/jobs, webhook CRUD/ingest, bot REST and token guard, search, video and guests, forums and shared notes, zero-pending close-out and the security review.
**Repos touched:** `sm-wavepath-app` (messaging handlers, row decorator, image proxies); `sm-chat-plugin` (Range streamer release); other shared chat plugins only for parity fixes found by replay; `sm-demo-app`, `sm-bm-app` and vue layers to follow shared-plugin changes.
</domain>
<decisions>
## Implementation Decisions
### Carry-forward from Phase 31 (binding)
- **D-01:** Phase 31 D-01, D-03, D-10, D-11, D-12, D-13, D-14 and D-16 still bind. Thin `/_wave` aliases; app plugin ports controller logic; every writing case has broadcast goldens; case depth is client paths plus denials; Range delta and messaging close this phase; quirks reproduced except security defects; shared-plugin shape wins with the bm/demo consumer gate; whole-corpus zero-pending closes in 31.2.
- **D-02:** Messaging slice scope matches research area E and the roadmap: group chat, channels, DM, threads, commands, host-facing reactions/emoji/prefs/pins/attachments, plus the chat Range release and unit tests.
### Attachment URL in JSON
- **D-03:** **App-side rewrite only.** The WavePath row decorator rewrites attachment `url` to the PHP legacy path; the shared `/_chat` serializer keeps today's Go path. No D-14 field change for bm/demo/layers. — **Reversibility:** reversible — local to the app decorator.
- **D-04:** **Absolute URLs.** Rewritten values match PHP `url(...)`: `{app_base}/api/chat/attachments/{messageId}/{fileId}`.
- **D-05:** **HTTP and broadcasts.** Every `/_wave` JSON body and every chat/`wave` publication that embeds attachments carries the rewritten absolute `url`.
- **D-06:** **Host from app config base URL.** Use the Summer app URL (PHP `APP_URL` equivalent), not the request `Host` header.
### Reactions and thread mute (locked without deep dive)
- **D-07:** **Map reactions onto the existing chat reactions API.** Do not port host `golem15_wavepath_reactions`. Observable `/_wave` shape is adapted in the app decorator as needed. — **Reversibility:** costly — MariaDB import and any later host-table migration must map onto chat reactions instead of a parallel host table.
- **D-08:** **Map thread mute onto chat `ThreadMute`.** Do not keep a separate host `ThreadSubscription` table for mute. — **Reversibility:** costly — same import concern as D-07.
### Image helper routes vs 31.2
- **D-09:** **Port `unfurl-image` and `webhook-icon` GETs in 31.1.** Full link-unfurl resolve/jobs and webhook CRUD/ingest stay in 31.2. Success cases use a seeded cache so chat UI image fetches replay green without the fetch pipeline.
- **D-10:** **Port the full proxy classes now** (`WebhookIconProxy`-equivalent and unfurl image serving) using `fetchguard`, still without CRUD or resolve jobs.
- **D-11:** **No live egress in `go test ./parity`.** Proxy fetches are answered from fixtures and upstream sidecars only.
### Claude's Discretion
- Exact decorator merge order for shared row vs host extras (beyond D-03…D-06).
- Package and type names for the Range streamer and image proxies.
- How seeded unfurl/icon rows are laid out in the Phase 31 scenario without expanding corpus scope.
- Plan count and wave split inside 31.1, subject to lean planning and "unit tests last".
</decisions>
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Prior phase contract
- `.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md` — D-01…D-22; messaging split (D-16); Range in 31.1; consumer gate (D-14).
- `.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md` — area E sizing, attachment URL analysis, Range delta notes, controller inventory, image helper routes.
- `.planning/ROADMAP.md` — Phase 31.1 goal and success criteria.
- `.planning/phases/19-chat-and-chatchannels/19-CONTEXT.md` — shared serializer, context registry, alias rewrite.
- `.planning/notes/core-plugins-own-repos.md` — plugin commit, tag and submodule pointer workflow.
### PHP contract (read-only)
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/routes.php` — messaging, attachment, unfurl-image and webhook-icon routes.
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/controllers/api/CommunityChatController.php` — `unfurlImage`, `webhookIcon`, `serveUnfurlFile`, AttachmentStreamer usage.
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/classes/services/WebhookIconProxy.php` — remote icon proxy behaviour.
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/chat` at pin `fbfbcf9` — `AttachmentStreamer` / Range commits.
### Go assets
- `../sm-chat-plugin/api/download.go` — current download handler (no Range yet).
- `../sm-chat-plugin/classes/serialize.go` — shared message/attachment `url` shape.
- `modules/tide/README.md` — replay, broadcast goldens, upstream sidecars, recorded headers for Range.
- `../sm-bm-app/summer.yaml`, `../sm-bm-app/chat_test.go`, `../sm-bm-app/realtime_test.go` — D-14 consumer gate.
- `../sm-demo-app/summer.yaml`, `../sm-demo-app/chat_test.go` — D-14 consumer gate.
</canonical_refs>
<code_context>
## Existing Code Insights
### Reusable Assets
- `sm-chat-plugin` download path streams via `bucket.NewReader` today; research recommends an exported Range-aware streamer in `classes` shared by plugin and app handlers (`blob.NewRangeReader` available in pinned gocloud).
- WavePath PHP already streams unfurl/webhook-icon through `AttachmentStreamer::forFile` (Range-aware, private inline) — Go should reuse the same streamer for those GETs.
- App row decoration pattern from Phase 19/31: shared serializer base + host merge in the wavepath app plugin.
- `tide` upstream sidecars and broadcast goldens from Phase 31 harness.
### Established Patterns
- Fail-closed parity: pending never counts as pass; phase gate reports messaging pending zero for 31.1 close.
- Plugin first (commit, push, tag), then submodule pointer bumps; changelog post on `/changelog/plugins`.
- PHP quirks win except security defects → accepted-differences (created in Phase 31).
### Integration Points
- Messaging handlers and aliases in `sm-wavepath-app` `wavepath` plugin.
- Range release changes generic `/_chat/api/v1/attachments/...` headers (additive; D-14 still runs).
- Image proxy GETs attach to group/channel/DM message routes already in the messaging controllers.
</code_context>
<specifics>
## Specific Ideas
- User: "2,3 - map into existing api" for reactions and thread mute — prefer chat plugin APIs over host parallel tables even where research favoured host tables for import fidelity.
- Attachment URL: research recommendation (app-side rewrite) accepted as-is.
- Image helpers: prefer full proxy classes early over minimal read models, but keep parity tests offline (fixtures/sidecars).
</specifics>
<deferred>
## Deferred Ideas
- Full link-unfurl resolve pipeline, OG fetch jobs, and webhook CRUD/ingest — Phase 31.2.
- Search backend choice (Typesense vs null driver) — Phase 31.2 discussion (31 D-16 note).
- Presence, status, push, video, guests, forums, notes, bot REST, zero-pending close-out, security review — Phase 31.2.
### Reviewed Todos (not folded)
- Thirteen keyword matches; slash-command escape, moderation seams and OIDC PHP recording already folded into Phase 31. Remaining matches were noise for messaging (changelog prev/next, forum/friends 401 refresh, menu plugin, README fences, fonoteka README, translate messages editor, MailBlocker, social first-password, gate scripts naming apps).
</deferred>
---
*Phase: 31.1-wavepath-messaging-parity*
*Context gathered: 2026-11-13*

View File

@@ -0,0 +1,131 @@
# Phase 31.1: WavePath messaging parity - Discussion Log
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
**Date:** 2026-11-13
**Phase:** 31.1-wavepath-messaging-parity
**Areas discussed:** Attachment URL in JSON, Image helper routes vs 31.2 (Reactions storage and Thread mute mapping locked without deep dive)
---
## Area selection
| Option | Description | Selected |
|--------|-------------|----------|
| Attachment URL in JSON | PHP legacy path vs Go path | ✓ |
| Reactions storage | Host table vs chat API | locked as map-to-existing |
| Thread mute mapping | Host subscription vs chat ThreadMute | locked as map-to-existing |
| Image helper routes vs 31.2 | Port GETs now vs leave pending | ✓ |
**User's choice:** Discuss 1 and 4; for 2 and 3 map into existing API.
**Notes:** No todos folded into 31.1.
---
## Reactions storage (no deep dive)
| Option | Description | Selected |
|--------|-------------|----------|
| Host model | Port `golem15_wavepath_reactions` | |
| Map into existing API | Use chat plugin reactions | ✓ |
**User's choice:** Map into existing API.
**Notes:** Overrides research preference for host tables (import fidelity).
---
## Thread mute mapping (no deep dive)
| Option | Description | Selected |
|--------|-------------|----------|
| Host table | Keep `ThreadSubscription` | |
| Map into existing API | Use chat `ThreadMute` | ✓ |
**User's choice:** Map into existing API.
---
## Attachment URL in JSON
| Option | Description | Selected |
|--------|-------------|----------|
| App-side rewrite only | WavePath decorator; shared `/_chat` unchanged | ✓ |
| Shared serializer change | D-14 release for all consumers | |
| Accepted difference | Leave Go paths in `/_wave` | |
**User's choice:** App-side rewrite only.
| Option | Description | Selected |
|--------|-------------|----------|
| Absolute | Match PHP `url(...)` with host | ✓ |
| Path-only | `/api/chat/attachments/...` | |
| Fixture-driven | Match whatever one golden shows | |
**User's choice:** Absolute.
| Option | Description | Selected |
|--------|-------------|----------|
| HTTP and broadcasts | REST + publications with attachments | ✓ |
| HTTP only | Leave broadcast payloads as shared serializer | |
| You decide | Green replay is enough | |
**User's choice:** HTTP and broadcasts.
| Option | Description | Selected |
|--------|-------------|----------|
| App config base URL | Summer app URL / PHP APP_URL | ✓ |
| Request Host | Build from incoming request | |
| You decide | Fixtures agree | |
**User's choice:** App config base URL.
---
## Image helper routes vs 31.2
| Option | Description | Selected |
|--------|-------------|----------|
| Port the GETs in 31.1 | unfurl-image + webhook-icon; CRUD/jobs later | ✓ |
| Leave pending until 31.2 | Messaging gate ignores them | |
| Port unfurl-image only | webhook-icon with webhooks | |
**User's choice:** Port the GETs in 31.1.
| Option | Description | Selected |
|--------|-------------|----------|
| Seeded cache | Success from fixtures; miss matches PHP | ✓ |
| Always 404 until 31.2 | Only denials in 31.1 | |
| You decide | Green cases | |
**User's choice:** Match PHP with seeded cache.
| Option | Description | Selected |
|--------|-------------|----------|
| Minimal read models only | Fixture rows, no proxy classes | |
| Full proxy classes now | fetchguard proxies; no CRUD/jobs | ✓ |
| You decide | Green GETs | |
**User's choice:** Port the full proxy classes now.
| Option | Description | Selected |
|--------|-------------|----------|
| Fixture / sidecar only | No live egress in parity tests | ✓ |
| Allow live fetchguard | Real HTTP when allow-listed | |
| You decide | No flaky deps | |
**User's choice:** Fixture / sidecar only.
---
## Claude's Discretion
- Decorator merge details beyond the locked URL rewrite rules
- Streamer and proxy type names
- Scenario seed layout for unfurl/icon rows
- Plan count inside the phase
## Deferred Ideas
- Full unfurl resolve/jobs and webhook CRUD → Phase 31.2
- Search backend → Phase 31.2 discussion

View File

@@ -0,0 +1,125 @@
# Phase 31.2: WavePath satellites parity and close-out - Context
**Gathered:** 2026-11-13
**Status:** Ready for planning
<domain>
## Phase Boundary
The rest of the WavePath corpus replays green against Go and the corpus closes at zero pending (31 D-15): presence and status, notifications and push, full link-unfurl resolve/jobs, webhook CRUD/ingest, bot REST with the token guard, search, video and guests (including the guest thread and guest identity freeze delta), forums and shared notes (on the minimal provisional diary read model from 31 D-18). Broadcast goldens and upstream sidecars are asserted. The fail-closed gate in `sm-wavepath-app` requires zero pending and that `sm-bm-app` and `sm-demo-app` build and pass. Accepted-differences are signed off in a batch at close-out. The security review of guest, bot/token, webhook and access resolvers runs as part of that close-out and its findings are resolved before the phase ends. Unit tests are the last plan. The unattended re-record-with-drift path remains runnable (31 D-06); the pre-freeze re-record itself stays a WavePath cutover task.
Out of scope: MariaDB→Postgres import and production cutover; diary/practices/trainings/stats beyond the provisional notes read model; `wavepath-mcp` diary surface; desktop clients as recording clients.
**Repos touched:** `sm-wavepath-app` (satellite handlers, host seams, provisional diary, gate at zero pending); shared plugin repos for parity fixes; `sm-demo-app`, `sm-bm-app` and vue layers to follow; folded vue-forum / vue-userfriends 401 refresh.
</domain>
<decisions>
## Implementation Decisions
### Carry-forward from Phases 31 and 31.1 (binding)
- **D-01:** Phase 31 D-01, D-03, D-06, D-10, D-11, D-12, D-13, D-14, D-15, D-16 and D-18 still bind. Thin `/_wave` aliases; app plugin ports host controller logic; broadcast goldens and upstream sidecars; case depth; freeze at recording commit with guest delta here; quirks except security defects → accepted-differences; shared-plugin shape wins with bm/demo consumer gate; zero pending closes this phase; notes on a minimal provisional `DiaryEntry` read model; re-record path left runnable unattended.
- **D-02:** Phase 31.1 D-03…D-06 (attachment URL rewrite), D-09…D-11 (image helper GETs already ported; no live egress in `go test ./parity`) still bind. Full unfurl resolve/jobs and webhook CRUD/ingest are in this phase and stay parity-offline for tests (see D-04).
### Search backend
- **D-03:** **Typesense on both sides for the search cases.** Run Typesense containers for PHP recording and Go replay so `GET …/search` exercises a real indexed result set, not the null-driver empty response. — **Reversibility:** costly — recording and goldens assume Typesense-backed hits; switching to null later invalidates search fixtures.
### Unfurl resolve and webhook ingest
- **D-04:** **Keep parity offline.** Recording may capture real upstream responses into tidecars once; `go test ./parity` never performs live egress for unfurl resolve/jobs or webhook outbound fetches. Replay answers from fixtures and upstream sidecars only (same rule as 31.1 D-11 for image helpers). — **Reversibility:** reversible — local to the parity harness.
### Satellite port order
- **D-05:** **Port by the suggested bundles, in this order:** (1) presence, status, notifications and push; (2) webhooks, bot REST with token guard, and search; (3) video and guests (including guest thread/identity delta); (4) forums and shared notes; (5) close-out (accepted-differences batch sign-off, security review and findings, zero-pending gate, consumer builds, unit tests last). — **Reversibility:** reversible — plan-wave ordering only.
### Close-out
- **D-06:** **Batch accepted-differences sign-off at the end.** Entries may be drafted while routes are ported, but the user signs the file once at close-out, not route-by-route. — **Reversibility:** reversible — process only.
- **D-07:** **Security review is part of close-out, before the phase is done.** Run it over guest access, bot and token authentication, webhook and access resolvers; resolve findings before the zero-pending gate is accepted as green. Prefer review after the satellite code exists (after bundles 1–4), not before zero pending is reachable. — **Reversibility:** reversible — sequencing only.
### Claude's Discretion
- Exact package/type/handler names inside the app plugin and how provisional diary rows are laid out beyond 31 D-18.
- Typesense image tag and how PHP Scout / Go search wire into the parity stack, as long as D-03 holds.
- Plan count and wave split inside D-05, subject to lean planning and "unit tests last".
- Gate script and accepted-differences file names (already Claude's discretion in Phase 31).
### Folded Todos
- **Single-flight 401 refresh in the forum and friends clients** (`forum-friends-client-401-refresh.md`, `vue-forum-layer` / `vue-userfriends-layer`). Forum and friends hooks never retry on 401; after JWT expiry forum shows "thread not found" while chat still works. Give both clients the chat-shaped `{token, refresh, unauthorized}` auth hook, single-flight refresh-and-retry, and a signed-out message instead of not-found. Fits because forums land in this phase's corpus and the layers must follow shared/forum consumer behaviour.
</decisions>
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Prior phase contract
- `.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md` — D-01…D-22; corpus boundary; D-15/D-16 zero-pending in 31.2; D-18 notes; security review deferred here.
- `.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md` — area F sizing, Pitfall 7 (Typesense vs null), controller inventory, rate buckets.
- `.planning/phases/31.1-wavepath-messaging-parity/31.1-CONTEXT.md` — messaging closed; image helpers offline; attachment URL rewrite; unfurl/webhook full pipeline deferred here.
- `.planning/phases/19.1-chat-satellites/19.1-CONTEXT.md` — herald push, LiveKit, forum, chatbots, userfriends generic APIs and seams.
- `.planning/phases/19-chat-and-chatchannels/19-CONTEXT.md` — serializer, context registry, alias rewrite, lighthouse namespaces.
- `.planning/ROADMAP.md` — Phase 31.2 goal and success criteria.
- `.planning/notes/core-plugins-own-repos.md` — plugin commit, tag and submodule pointer workflow.
- `.planning/notes/2026-10-18-webpush-go.md` — herald webpush-go pin.
- `.planning/notes/2026-10-18-livekit-server-sdk-go.md` — chatvideo LiveKit pin.
### PHP contract (read-only)
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/routes.php` — presence, status, push, unfurl, webhooks, bot/token, search, video, guest, forums, notes.
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/controllers/api/` — community satellite controllers (`CommunityPresenceController`, `CommunityStatusController`, `PushSubscriptionController`, unfurl/webhook controllers, `BotRestController`, search, video/guest, forum, shared notes).
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/Plugin.php` — host seam bindings and group lifecycle.
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/classes/{notifications,forum,video,chatbots}/` — host seam implementations.
### Go / harness assets
- `modules/tide/README.md` — replay, broadcast goldens, upstream sidecars.
- `../sm-herald-plugin/`, `../sm-chatvideo-plugin/`, `../sm-forum-plugin/`, `../sm-chatbots-plugin/`, `../sm-chatchannels-plugin/` — satellite plugins (search indexer / Typesense seam lives with channels research notes).
- `../sm-bm-app/summer.yaml`, `../sm-bm-app/chat_test.go`, `../sm-bm-app/realtime_test.go` — D-14 consumer gate.
- `../sm-demo-app/summer.yaml` and its chat/realtime/video tests — D-14 consumer gate.
- `.planning/todos/pending/forum-friends-client-401-refresh.md` — folded todo.
</canonical_refs>
<code_context>
## Existing Code Insights
### Reusable Assets
- Shared satellite plugins already expose typed services and `/_x/api/v1` APIs; WavePath `/_wave` handlers are thin aliases plus host merge (31 D-01/D-03).
- Herald push through `webpush-go` + fetchguard; chatvideo LiveKit + upstream sidecars; forum Markdown + deny-all resolver — all from Phase 19.1.
- 31.1 image proxies and attachment URL decorator patterns for extending unfurl/webhook host routes.
- `tide` upstream sidecars and broadcast goldens for push and LiveKit assertions.
### Established Patterns
- Fail-closed parity: pending never counts as pass; Phase 31.2 gate requires total zero pending.
- Plugin first (commit, push, tag), then submodule pointer bumps; changelog on `/changelog/plugins`.
- PHP quirks win except security defects → accepted-differences (final batch sign-off this phase).
- No live egress in `go test ./parity` (31.1 D-11 extended by D-04).
### Integration Points
- App plugin: presence/`wave` authorizers, herald profile and presence gate, notification dispatch, bot auth resolver, forum access resolver, video/guest host logic, provisional diary for notes, webhook ingest.
- Typesense containers on the Phase 31 isolated PHP stack and on Go parity for search cases (D-03).
- Folded 401 refresh in `vue-forum-layer` and `vue-userfriends-layer` alongside forum route parity.
</code_context>
<specifics>
## Specific Ideas
- User skipped point-by-point discussion and locked all four gray areas in one reply: Typesense; keep parity offline; suggested satellite order; batch accepted-differences at the end.
- Security review placed in close-out after satellite code exists, findings resolved before phase done.
</specifics>
<deferred>
## Deferred Ideas
- Pre-freeze corpus re-record with drift report — WavePath cutover phase (31 D-06).
- Full diary/practices/trainings/stats and MariaDB import — later WavePath phases.
- `wavepath-mcp` as a recording client — later WavePath backend corpus.
### Reviewed Todos (not folded)
- OIDC PHP parity recording, chat slash-command escape, and moderation seams — already folded into Phase 31.
- Remaining keyword matches were noise for this phase (changelog prev/next, menu plugin, README fences, fonoteka README, translate messages editor, MailBlocker, social first-password, gate scripts naming apps, Winter vs Summer benchmark).
</deferred>
---
*Phase: 31.2-wavepath-satellites-parity-and-close-out*
*Context gathered: 2026-11-13*

View File

@@ -0,0 +1,82 @@
# Phase 31.2: WavePath satellites parity and close-out - Discussion Log
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
**Date:** 2026-11-13
**Phase:** 31.2-wavepath-satellites-parity-and-close-out
**Areas discussed:** Search backend, Unfurl resolve & webhook ingest, Satellite port order, Close-out gates (batch answers; no point-by-point deep dive)
---
## Todos fold-in
| Option | Description | Selected |
|--------|-------------|----------|
| Forum/friends 401 refresh | Single-flight 401 refresh in forum and friends vue layers | ✓ |
| OIDC PHP parity | Already in Phase 31 | |
| Chat slash escape | Already in Phase 31 | |
| Moderation seams | Already in Phase 31 | |
| None | Leave all out | |
**User's choice:** Forum/friends 401 refresh
**Notes:** Folded into 31.2 because forums are in this corpus.
---
## Search backend
| Option | Description | Selected |
|--------|-------------|----------|
| Typesense containers both sides | Real indexed search cases | ✓ |
| SCOUT_DRIVER=null | Empty results; weaker fixture | |
**User's choice:** Typesense
**Notes:** Locked without deep dive ("1 typesense").
---
## Unfurl resolve & webhook ingest
| Option | Description | Selected |
|--------|-------------|----------|
| Keep parity offline | Fixtures + upstream sidecars only in `go test ./parity` | ✓ |
| Controlled live during recording | Live fetch allowed in some harness paths | |
**User's choice:** Keep parity offline
**Notes:** Aligns with 31.1 D-11 for image helpers.
---
## Satellite port order
| Option | Description | Selected |
|--------|-------------|----------|
| Suggested bundles | presence/push → webhooks/bot/search → video/guests → forums/notes → close-out | ✓ |
| Different cut | User-defined reordering | |
**User's choice:** As suggested
**Notes:** No alternative order proposed.
---
## Close-out gates
| Option | Description | Selected |
|--------|-------------|----------|
| Sign accepted-differences as routes land | Continuous sign-off | |
| Batch at the end | One sign-off at close-out | ✓ |
| Security review before vs after zero pending | (clarified in CONTEXT as close-out after code exists, findings before done) | ✓ (batch/close-out) |
**User's choice:** Batch at the end
**Notes:** User answered area 4 as "batch at the end"; security review interpreted as part of that close-out sequence.
---
## the agent's Discretion
- Package/type names, Typesense wiring details under D-03, plan/wave split inside D-05, gate and accepted-differences file names.
## Deferred Ideas
- Pre-freeze re-record (WavePath cutover); full diary backend; wavepath-mcp recording client.

View File

@@ -5,7 +5,7 @@ titles: json
findings:
- id: CR-01
severity: critical
disposition: open
disposition: fixed
title: "An in-flight MCP allow recreates a consent the user just revoked"
- id: WR-01
severity: warning
@@ -31,7 +31,7 @@ findings:
severity: warning
disposition: open
title: "`/connect` can allow a stale request after `?request=` changes"
open: 7
open: 6
total: 7
recorded: 2026-10-28T16:03:08.042Z
---
@@ -40,7 +40,7 @@ recorded: 2026-10-28T16:03:08.042Z
| Finding | Severity | Disposition | Source |
|---------|----------|-------------|--------|
| CR-01 | critical | open | - |
| CR-01 | critical | fixed | sm-oauthserver-plugin 21f5985 (unreleased; ships with the next plugin tag) |
| WR-01 | warning | open | - |
| WR-02 | warning | open | - |
| WR-03 | warning | open | - |

View File

@@ -0,0 +1,100 @@
---
phase: "32.1"
slug: "mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con"
status: verified
# threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
threats_open: 0
asvs_level: 1
created: "2026-11-05"
---
# Phase 32.1 — Security
> Per-phase security contract: threat register, accepted risks, and audit trail. Evidence paths: F = `summercms.go`, U = `sm-user-plugin`, O = `sm-oauthserver-plugin`, V = `vue-oauth-layer`, S = `sm-summercmsio-app` (all under `../`). Baseline for "unchanged" claims: `2cea312`, the commit before the phase.
---
## Trust Boundaries
| Boundary | Description | Data Crossing |
|----------|-------------|---------------|
| MCP client to wristband authorize | Untrusted scope string and redirect cross here; the phase only changes which names are legal | scope string, redirect URI, PKCE challenge (high) |
| pier dispatch to route handler | the handler gets an MCPCall built from the resolved subject, not from tool arguments | subject, client id, token id (high) |
| OAuth grant scopes to MCPAllows / user.scope | the grant is the consented set; Implies may add only names the plugin marked | granted scopes (high) |
| DELETE /oauth/authorizations/{client_id} | a signed-in user names a client; another user's rows must stay | client id, user session (high) |
| Operator config `mcp_scopes` | names enter metadata and the allow-list at boot | scope names (medium) |
| MCP consent JSON to the browser | client name, labels and admin name are attacker-influenced (DCR name, phrase text) | display strings (medium) |
| Page POST back to the consent route | the browser can omit fields; the server intersection is the control | decision, scopes, backend_admin (high) |
| Test output and changelog notes | tokens and authorization codes must not reach logs or the public post | test output, release notes (medium) |
| git push of a release tag | the tag is what other repositories require | tag (low) |
---
## Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation | Status |
|-----------|----------|-----------|----------|-------------|------------|--------|
| T-32.1-01 | Elevation of privilege | wristband resolvedScopes | high | mitigate | F/modules/wristband/server.go:203 `mcpEmptyScopes` (five names incl. backend); :210-218 never widens a non-empty list; used by metadata :194 and authorize.go:29. `DefaultOptions` and OIDC discovery unchanged | closed |
| T-32.1-02 | Elevation of privilege | pier filter.go read/write ceiling | high | mitigate | filter.go and identity.go unchanged since baseline; ceiling identity.go:80-82 `writes()` used at filter.go:66,:75; no `Implies` reference in pier, bouncer or wristband | closed |
| T-32.1-03 | Spoofing | wristband Authorize redirect | high | mitigate | 63d05e8 touched only `allowedAuthorizeScopes`; authorize.go order: client lookup :62-82, exact redirect :84-88, PKCE :95-108, scope parse :110 | closed |
| T-32.1-04 | Information disclosure | pact.MCPCall.Subject.TokenID | medium | mitigate | TokenID rule in pact/README.md:170, pier/README.md:13 and docs; dispatch.go:211-215 adds no log line; subject from `id.subjectFor` :172; audit.go unchanged | closed |
| T-32.1-05 | Elevation of privilege | MCPUserGuard Implies helper | high | mitigate | U/classes/mcp_guard.go:160-175 `mcpEffectiveScopes`: personal tokens unchanged, clone only, read/write Implies only, exact stock scope required, no write-back; both call sites (:94, :145); `CompileAPITokenScopes` rejects backend/offline_access and bad Implies (api_token_scopes.go:139,:148). Residual: WR-01, WR-02 | closed |
| T-32.1-06 | Elevation of privilege | MCP consent upsert | high | mitigate | O/controllers/mcp_consent_api.go: deny → `DenyPending` (:180-183); silent re-grant → `TouchConsent` (:355-358); decision → `replaceMCPConsent` ON CONFLICT sets scopes (:382-389), replace not union. Test `TestMCPConsentReplace`. Residual: WR-03, WR-04 (CR-01 fixed in 21f5985) | closed |
| T-32.1-07 | Elevation of privilege | authorizations.revoke | high | mitigate | O/controllers/authorizations.go:137-163: `LockUserGrants` advisory lock in-tx before deletes of consent, codes and tokens; `MCPSubjectRevoked` after commit. Test `TestMCPRevokeDeletesCode`. CR-01 fixed in 21f5985: the MCP allow takes the same lock | closed |
| T-32.1-08 | Information disclosure | PendingRequest / IssueCode | high | mitigate | F/modules/wristband/consent.go:139-174 `lookupOwnedPending` unchanged, all misses → `ErrPendingNotFound` → 404. Plugin's `mcpPendingClientID` (mcp_consent_api.go:322-332) looks up by request id alone but both callers run it after the owner-checked `PendingRequest` | closed |
| T-32.1-09 | Tampering | grantedScopes when scopes is absent | medium | mitigate | mcp_consent_api.go:247-250 absent scopes = requested set; offline override only when present (:224-226); request struct takes decision, scopes, backend_admin only | closed |
| T-32.1-10 | Information disclosure | consent and revoke logs | medium | mitigate | phase diff `df2eddd..a7743e7` adds no log line in plugin non-test code; error-code sets unchanged | closed |
| T-32.1-11 | Tampering | app/pages/connect.vue | high | mitigate | no `v-html`/innerHTML in V/app/; connect.vue uses text interpolation and attribute bindings; V/tests/connect.test.ts:107-109 asserts no `v-html`. Residual: WR-06 | closed |
| T-32.1-12 | Elevation of privilege | read checkbox | low | accept | AR-32.1-01 | closed |
| T-32.1-13 | Information disclosure | tests and changelog-post.py | medium | mitigate | phase test messages print only codes, error keys, scope lists and ids; notes contain no token prefixes; S/scripts/changelog-post.py:407-411 exits without token, :318-326 refuses a world-readable token file | closed |
| T-32.1-14 | Spoofing | release tags | low | accept | AR-32.1-02 | closed |
*Status: open · closed · open — below high threshold (non-blocking)*
*Severity: critical > high > medium > low — only open threats at or above workflow.security_block_on count toward threats_open*
*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
---
## Accepted Risks Log
| Risk ID | Threat Ref | Rationale | Accepted By | Date |
|---------|------------|-----------|-------------|------|
| AR-32.1-01 | T-32.1-12 | The read checkbox is disabled and the page's own POST includes read. A client that omits read only narrows the grant; the server must not reinsert read because the 422 smoke posts backend alone. Narrowing is not a privilege gain. `grantedScopes` does not special-case read. | 32.1-04-PLAN | 2026-11-05 |
| AR-32.1-02 | T-32.1-14 | Tagging does not change PKCE, redirect matching or the read/write ceiling; the checkpoint is the control on publishing, not a new auth path. | 32.1-05-PLAN | 2026-11-05 |
*Accepted risks do not resurface in future audit runs.*
---
## Residual Risk (open review findings, outside the L1 register)
`32.1-REVIEW-DISPOSITION.md` lists these as `open`. The auditor confirmed each is still present in the code on 2026-11-05. They do not count toward `threats_open` at ASVS L1, but CR-01 would make T-32.1-07 a blocking open threat at L2. CR-01 has since been fixed (sm-oauthserver-plugin 21f5985).
| Finding | Severity | Touches | Gap |
|---------|----------|---------|-----|
| CR-01 | critical | T-32.1-07, T-32.1-06 | Fixed in sm-oauthserver-plugin 21f5985 (2026-11-05, unreleased): `MCPConsentDecide` issues the code and writes the consent in one transaction under `classes.WithinUserGrantsLock` (exclusive `LockUserGrants`, the lock revoke takes); a failed consent write rolls the code back. Tests `TestMCPConsentAllowSerializesWithRevoke`, `TestMCPConsentFailureRollsBackCode`. |
| CR-01 sibling (OIDC) | high | T-32.1-07 | Fixed in sm-oauthserver-plugin 7b9899f (2026-11-05, unreleased): the OIDC decide was already consistent (consent upsert and code in one transaction, ordered against revoke by the consent row lock; pinned by `TestOIDCConsentAllowThenRevoke`), but a silent resume could issue a code after a revoke, a refresh rotation's successor tokens survived a revoke and a code exchange could deadlock with one. The OIDC store now takes the user's grants lock (shared) before its first grant row. Tests `TestOIDCResumeSerializesWithRevoke`, `TestOIDCRefreshSerializesWithRevoke`, `TestOIDCExchangeSerializesWithRevoke`. |
| WR-01, WR-02 | warning | T-32.1-05 | `mcpEffectiveScopes` re-implies a declared scope the user cleared on /connect while read/write remains, and does not intersect the catalog with `golem15.oauthserver.mcp_scopes`. |
| WR-04 | warning | T-32.1-06 | narrowing a consent does not revoke refresh tokens carrying the removed scopes or offline_access. |
| WR-03 | warning | T-32.1-06 | the consent backfill seeds from tokens the verifier would refuse (nil-expiry, inactive/revoked clients, rotated refresh tokens). |
| WR-06 | warning | T-32.1-11 | /connect `load()` has no generation guard; a stale `consent_required:false` can auto-allow a request the user no longer views. |
---
## Security Audit Trail
| Audit Date | Threats Total | Closed | Open | Run By |
|------------|---------------|--------|------|--------|
| 2026-11-05 | 14 | 14 | 0 | msd-security-auditor (ASVS L1, block_on high) |
---
## Sign-Off
- [x] All threats have a disposition (mitigate / accept / transfer)
- [x] Accepted risks documented in Accepted Risks Log
- [x] `threats_open: 0` confirmed
- [x] `status: verified` set in frontmatter
- [x] CR-01 given a disposition in 32.1-REVIEW-DISPOSITION.md (fixed: sm-oauthserver-plugin 21f5985)
**Approval:** verified 2026-11-05 (ASVS L1; CR-01 fixed in sm-oauthserver-plugin 21f5985, unreleased)

View File

@@ -53,3 +53,14 @@ Jakub runs these on https://grzybyfunkcjonalne.pl after the 33-14 deploy (steps
6. **The visual check of the 0.8 card and title markup.** Look at the home page, `/blog`, a category, a post and `/autor/admin`, on desktop and mobile. The post cards are now clickable as a whole and have no "more" link. Check the post title markup, the breadcrumbs at the top of the journal pages, and the footer link "Mapa strony".
7. **Resubmit the sitemap in Search Console.** Submit `https://grzybyfunkcjonalne.pl/sitemap.xml` (same address, now an index) and check that Google reads its files.
8. **libwebp on the server.** Run `ls /usr/lib/x86_64-linux-gnu/libwebp.so*`. If present, the Journal's WebP thumbnails use the fast encoder; if absent, the slower built-in one. Either works with the dynamically linked binary, unless 33-14 builds with `-tags nodynamic`.
## 33-14 deploy (2026-11-05, production, tagged build)
Steps 1 to 11 of DEPLOY.md "SEO pages and sitemaps (Phase 33)" ran on the tagged build (summercms v0.6.1, sm-journal-plugin v0.4.0, sm-sitemap-plugin v0.2.0, sm-seo-plugin v0.2.0, vue-journal-layer v0.8.1, vue-menu-layer v0.5.1, vue-faq-layer v0.5.1, vue-seo-layer v0.2.0; sm-grzybyfunkcjonalne-app 75736b4, static binary with `-tags nodynamic`). Step 5: `en` was already disabled. Step 10: Additional addresses `/` and `/blog` removed. Step 12: `smoke.sh --url … --also urls-production.txt` failed one line, `/autor/admin` expecting the rehearsal author's name "admin" in the title; production shows "Wpisy autora Dawid P. | Grzyby Funkcjonalne". `smoke-seo.sh` and `check-deploy.sh --live` ok. Not rolled back; details and the checklist results in 33-release-log.md, steps 9d and 9e. Open for Jakub: items 3 (SEO › Pages in /gfadmin), 5 (a crawl), 6 (visual check), 7 (Search Console resubmit), and the 404-log cleanup of the smoke entries.
### Step 12 completed (Jakub's answer A: keep the deploy)
- `scripts/urls.txt` checks the `/autor/admin` title by its fixed parts only (sm-grzybyfunkcjonalne-app 0554f3e); the local rehearsal passes (`smoke: ok (129 urls)`).
- Production smoke rerun on the server, as before: `smoke: ok (149 urls)`.
- The 14 smoke entries in the 404 log (first seen since 01:12Z on 2026-11-05) are deleted; older entries are untouched.
- Still Jakub's: check-list items 3, 5, 6 and 7 above.

View File

@@ -0,0 +1,181 @@
---
phase: 33-seo-output-audit-and-content
plan: 14
subsystem: release
tags: [tests, gate, release, tags, changelog, deploy, seo, sitemap, journal, nuxt-layers, nodynamic]
status: complete
requires:
- phase: 33-01..33-13
provides: the phase's framework seams, plugins, layers, app patches and the release checkpoint
- phase: 33-15, 33-16, quick-261104-xae
provides: the gap closure re-verified in 33-VERIFICATION.md (human_needed, no gaps)
provides:
- "Unit tests for all new phase 33 code (SC-4) and the full check-phase33.sh gate (Tasks 1-2)"
- "Tags: summercms v0.6.1; sm-journal-plugin v0.4.0; sm-sitemap-plugin v0.2.0; sm-seo-plugin v0.2.0 (requires sitemap v0.2.0); vue-seo-layer v0.2.0; vue-journal-layer v0.8.0 and v0.8.1; vue-menu-layer v0.5.0 and v0.5.1; vue-faq-layer v0.5.0 and v0.5.1"
- "Content layers declare vue-seo-layer as a ^0.2.0 peer dependency plus a git devDependency (v0.8.1 / v0.5.1); apps list vue-seo-layer#v0.2.0 directly"
- "Apps pinned to the tags and patched: sm-demo-app (Polish under /pl/), sm-summercmsio-app, sm-grzybyfunkcjonalne-app; static release binaries with -tags nodynamic"
- "Changelog posts for the framework and the three Go plugins"
- "Deploys: summercms.io, demo.summercms.io, bm.jakubzych.com, grzybyfunkcjonalne.pl (production)"
affects: [phase-34, v0.6.2-backlog]
actuals:
tokens: 40000
tasks: 4
commits: 7
plan_head_before: 9c11b70
plan_head_after: 6875627
plan_heads_task4:
summercms.go: { before: 9c11b70, after: 6875627, commits: 7, note: "6d14f71 style: gofmt plus six planning-doc commits; this SUMMARY and the ROADMAP commit follow" }
sm-journal-plugin: { before: cf13c60, after: 6823dcc, commits: 2 }
sm-sitemap-plugin: { before: b2b3a1d, after: fdbe593, commits: 1 }
sm-seo-plugin: { before: c71b58e, after: 22f108b, commits: 1 }
vue-journal-layer: { before: 761c7fc, after: f5dc9b2, commits: 2 }
vue-menu-layer: { before: a7602c9, after: dc38f79, commits: 2 }
vue-faq-layer: { before: 5e5950a, after: a092363, commits: 2 }
sm-summercmsio-app: { before: ca06049, after: 395ed78, commits: 5 }
vue-summercmsio-app: { before: f36cbf1, after: 16ab519, commits: 1 }
sm-demo-app: { before: da481c9, after: da03c06, commits: 9 }
vue-demo-app: { before: 9a12701, after: fe5d38d, commits: 1 }
sm-grzybyfunkcjonalne-app: { before: 35d3664, after: 0554f3e, commits: 10 }
vue-grzybyfunkcjonalne-app: { before: e45ffe8, after: 0771c14, commits: 1 }
sm-bm-app: { before: bd7ee84, after: 43f2fc9, commits: 1, note: "push also carried 552cdce, c2a7823, 9dd0fe4 of other sessions (approved)" }
jz.bm: { before: 0dd0185, after: a27a162, commits: 1 }
tech-stack:
added: []
patterns:
- "A Nuxt layer that builds on another git-installed layer declares it as a semver peer dependency and a git devDependency; the app lists both (pnpm 12 refuses git subdependencies by default, blockExoticSubdeps)"
- "Apps that mount the Journal build their release binary with -tags nodynamic, so gen2brain/webp does not link glibc through purego"
- "Smoke expectations that run against production check only the fixed parts of data-dependent text"
key-files:
created:
- .planning/phases/33-seo-output-audit-and-content/33-14-SUMMARY.md
modified:
- .planning/phases/33-seo-output-audit-and-content/33-release-log.md
- .planning/phases/33-seo-output-audit-and-content/33-13-deploy-log.md
- .planning/phases/33-seo-output-audit-and-content/33-14-notes-vue-journal-layer-v0.8.0.md
- .planning/phases/33-seo-output-audit-and-content/33-14-notes-vue-menu-layer-v0.5.0.md
- .planning/phases/33-seo-output-audit-and-content/33-14-notes-vue-faq-layer-v0.5.0.md
- ../vue-journal-layer/scripts/check-git-install.sh
- ../vue-journal-layer/package.json
- ../vue-menu-layer/package.json
- ../vue-faq-layer/package.json
- ../sm-grzybyfunkcjonalne-app/scripts/urls.txt
- ../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh
decisions:
- "Content layers v0.8.1 / v0.5.1 take vue-seo-layer as a ^0.2.0 peer dependency (Jakub, option B); v0.8.0 and v0.5.0 stay published but do not install with pnpm 12 defaults"
- "WebP build option B: every app mounting the Journal builds static with -tags nodynamic"
- "The demo keeps /subscriptions as an Additional address; the route report's noindex list leaves it out (G1 confirmed live)"
- "grzybyfunkcjonalne.pl step 12: keep the deploy and fix the fixture-bound /autor/admin expectation (Jakub, option A)"
- "W5 production SQL length check skipped (Jakub: no production fonoteka)"
---
# Phase 33 Plan 14: Unit tests, the phase gate and the release Summary
**Phase 33 shipped: SummerCMS v0.6.1 with sm-journal-plugin v0.4.0, sm-sitemap-plugin v0.2.0, sm-seo-plugin v0.2.0 and the four SEO-aware Nuxt layers (installable as v0.2.0 / v0.8.1 / v0.5.1 / v0.5.1). Four changelog posts are live. The demo, summercms.io, bm and production grzybyfunkcjonalne.pl run the tagged, statically linked builds, and every smoke ends ok.**
## Performance
- Tasks: 4 of 4. Tasks 1 and 2 (unit tests, gate, VALIDATION) and the Task 3 checkpoint ran earlier. Task 4 (the release) ran on 2026-11-05, about 00:30–01:35 UTC, with two checkpoints in between: the layer dependency and the grzyby smoke.
- Task 4 commits: 7 in summercms.go before this SUMMARY, plus the per-repository commits listed in the frontmatter.
## Accomplishments
Every step is in 33-release-log.md, steps 0 to 10 (TAG lines for all 11 tags).
1. **Pre-checks.**
- gofmt fixes: framework 6d14f71 (15 files, several unformatted since v0.6.0) and sm-journal-plugin b8d98ce.
- `check-phase33.sh --all` green with Docker.
- Every repository is on its default branch, and the patches apply.
2. **Framework v0.6.1** (tag 5db8c61 on 6d14f71), master and tag pushed.
3. **Go plugins.** Each got the framework bump, a regenerated plugin.yaml, its README dependency lines, a GOWORK=off build, vet and `test -short`, then a commit, a tag and a push:
- journal v0.4.0;
- sitemap v0.2.0;
- seo v0.2.0, which also requires sitemap v0.2.0.
4. **Layers.**
- vue-seo-layer v0.2.0.
- journal v0.8.0, menu v0.5.0 and faq v0.5.0 after the link: swap.
- `check-git-install.sh v0.8.0` then failed with ERR_PNPM_EXOTIC_SUBDEP (checkpoint). Under option B the patch releases v0.8.1, v0.5.1 and v0.5.1 make vue-seo-layer a peer dependency.
- `check-git-install.sh v0.8.1` passes, and a scratch app on pnpm defaults installs and builds with the menu and FAQ tags too.
5. **Changelog posts.**
- summercms-0-6-1 (id 66);
- sm-sitemap-plugin-0-2-0 (67);
- sm-seo-plugin-0-2-0 (68);
- sm-journal-plugin-0-4-0 (69).
- All four answer 200, and the plugin posts are listed on /changelog/plugins.
6. **Apps.**
- **sm-summercmsio-app:** framework and journal bumps, the 33-12 changelog patch with the layer pins, and nodynamic. Built in a clean worktree: release v0.6.1, static. Smoke ok.
- **sm-demo-app:** three plugin bumps, the 33-12 patches, then the 33-14 locale patches (Polish under /pl/), nodynamic, and a roadmap sync. Docker tests and check-pins passed; the release build is static; smoke ok.
- **sm-grzybyfunkcjonalne-app:** three plugin bumps and the 33-13 patches, with the Binary row saying "static". nodynamic and a check-deploy fix. Full rehearsal `smoke: ok (128 urls)`, later 129.
- **sm-bm-app:** the frontend build with the robots meta and robots.txt went into jz.bm, then the pointer bump, then the push.
7. **Deploys.**
- **summercms.io:** pg_dump; Journal migrations (2); `journal:image-variants`; public checks ok.
- **Demo:**
- pg_dump; the SEO tokens added without printing them; 15 migrations; the vhost reinstalled after `nginx -t`.
- The "After" block with `/subscriptions` kept. G1 confirmed live: it is left out as noindex.
- `journal:image-variants`, then `check-live` ok and strict `smoke-seo` ok.
- **bm:** pg_dump, binary swap, and the X-Robots-Tag on the live vhost, `/pliki/` included. Verified.
- **grzybyfunkcjonalne.pl:** DEPLOY steps 1 to 12.
- Backups first, then 15 migrations.
- `en` was already disabled.
- seo-settings: 3 changed.
- Route report: 4 routes and 1 noindex path.
- New vhost installed.
- Pages renamed, CSV imported, Additional addresses emptied.
- Rebuild: 74 addresses. 285 WebP variants written.
- Production smoke `ok (149 urls)` after the urls.txt fix; `smoke-seo` ok.
- The smoke's 14 entries in the 404 log removed.
## Deviations from Plan
### Auto-fixed issues
1. **[Rule 1 - Bug] Content layers could not be installed (ERR_PNPM_EXOTIC_SUBDEP).** I stopped at the checkpoint, and Jakub chose B: v0.8.1, v0.5.1 and v0.5.1 declare vue-seo-layer as a peer dependency. check-git-install's scratch app now lists vue-seo-layer at the tag's dev pin.
2. **[Rule 3 - Blocking] grzyby check-deploy.sh looked for the old exact build tag list.** It now requires `summercms_mcp,nodynamic` (75736b4).
3. **[Rule 1 - Bug] grzyby urls.txt `/autor/admin` expected the rehearsal author's name.** Production failed 1 of 148 lines. I stopped without rolling back, and Jakub chose A. The line now checks only the fixed parts of the title (0554f3e). The production rerun is ok.
4. **[Rule 3 - Blocking] The sm-summercmsio-app live checkout carries another session's untracked binary,** which `require_clean` refuses. The release build ran in a clean worktree instead. The journal changelog post was published from a clean worktree at v0.4.0 for the same reason (an untracked go.work.sum).
5. **[Rule 2 - Missing] bm's live vhost location `^~ /pliki/` sets its own add_header.** The header was added there as well, not only in the topics location.
6. **Grzyby Nuxt upload.** The build went to `.output.new` and was swapped at the restart instead of being rsynced over the running `.output`.
7. **Demo DEPLOY "After" block.** It no longer removes `/subscriptions` by hand (G1), per Jakub's instruction.
8. **33-13 patch.** The `plugins/grzyby/go.mod` hunk conflicted only with the v0.6.1 bump and was applied by hand (sitemap require and replace).
### Known follow-ups (not fixed here)
- **`check-phase33.sh --consumers` needs a post-release mode.** It checks the release patches against unpatched app HEADs, so after the release it refuses (`33-12-sm-demo-app.patch does not apply`). Compat passes, and the apps' builds, tests and smokes ran directly.
- **Posts now send `X-Robots-Tag: index, follow`.** vue-seo-layer sends the CMS robots value as a header. The 2026-10-31 cutover check expected no X-Robots-Tag on a post. This is harmless, but the DEPLOY "Verify" line should be updated.
- **The G2 journal-tag drift warning still appears at every Nuxt start** on the demo and on grzyby. It is deferred to v0.6.2.
- **Some gofmt fixes landed in the framework** without a docs change. The docs checker passes.
## Human checks still open (33-VERIFICATION.md)
1. Production grzybyfunkcjonalne.pl, from the 33-13-deploy-log.md check list:
- item 3: SEO › Pages in /gfadmin;
- item 5: a crawl from SEO › Site audit;
- item 6: the visual check on desktop and mobile;
- item 7: resubmit the sitemap in Search Console.
2. SC3 live MCP workflow: a crawl, then dry run and apply from a real client.
3. D-46: Google's Rich Results Test for a post, a category and an FAQ page.
4. Visual checks:
- grzyby;
- the demo on /pl/: the LanguageSwitcher, /pl/mapa-strony and /sitemap, the footer link;
- the new admin screens;
- the Blog Editor outline at 360px (J2).
5. W5 (33-14-risk-max.sql) was skipped by decision.
## For the orchestrator
- **g15office:** post a comment on the phase 33 task. Text: "Phase 33 released: SummerCMS v0.6.1, journal v0.4.0, sitemap v0.2.0, seo v0.2.0, layers seo v0.2.0 / journal v0.8.1 / menu v0.5.1 / faq v0.5.1; demo, summercms.io, bm and grzybyfunkcjonalne.pl deployed; open: human checks listed in 33-14-SUMMARY". Close g15office task w8kupqi3 if it is still open.
- **STATE.md:** updated through the handlers only and not committed. The grzyby blocker is resolved.
## Self-Check: PASSED
- Files: 33-release-log.md, 33-13-deploy-log.md and this SUMMARY exist.
- Tags: all 11 are on their origins (the plan's verify loop printed "tags-ok").
- Package files: no content layer package.json has `link:`.
- Commits:
- summercms.go: 6d14f71, 8edc869, 143b4db, ef164dd, 211687f, 201fd0f and 6875627 are present.
- Every repository: HEAD equals its origin default branch after the pushes. The exception is summercms.go, whose planning-doc commits after the v0.6.1 push are local (6 before this SUMMARY), and it is not pushed.
- Changelog: the four post URLs answer 200.

View File

@@ -13,4 +13,4 @@ Excerpt: FAQ blocks add a FAQPage node to the page's one JSON-LD graph and can r
- **Breaking:** the layer extends vue-seo-layer, and the copied site cache purge route, library and plugin are removed (vue-seo-layer provides them with the same environment variables).
- **Upgrade:** set `NUXT_SEO_API_BASE`, or `seo: { cms: false }` for a site without the SEO plugin. The layer brings vue-seo-layer's HTML sitemap pages (pl `/mapa-strony`, en `/sitemap` by default). An app that renders its pages through a root catch-all (`[...slug].vue`) gets none, so a CMS page at such a path stays visible, unless it sets `seo.htmlSitemap.overCatchAll: true`; an app with its own page at such a path keeps it; `seo: { htmlSitemap: false }` turns them off. When a page shows several FAQs, set `schema` false on all but one.
- Requires vue-seo-layer v0.2.0.
- **Install v0.5.1, not v0.5.0.** vue-seo-layer v0.2.0 is a peer dependency (`^0.2.0`): list `"vue-seo-layer": "git+https://git.golem15.com/golem15/vue-seo-layer.git#v0.2.0"` in the app next to `"vue-faq-layer": "git+https://git.golem15.com/golem15/vue-faq-layer.git#v0.5.1"`. v0.5.0 listed vue-seo-layer as its own git dependency, which pnpm refuses by default (`ERR_PNPM_EXOTIC_SUBDEP`); v0.5.1 is otherwise the same release.

View File

@@ -19,7 +19,7 @@ Excerpt: The journal layer now runs on vue-seo-layer: one H1 per post page, brea
- **Breaking: post cards have one link.** The read-more link and the image link are removed; the whole card is clickable. The post title may be a `p.journal-post__title`, related post cards are `h3`. Adjust app CSS that targets the old elements.
- The shared site cache purge route moved to vue-seo-layer with the same path and variables.
- **Upgrade:** The layer brings vue-seo-layer's HTML sitemap pages (pl `/mapa-strony`, en `/sitemap` by default). An app that renders its pages through a root catch-all (`[...slug].vue`) gets none, so a CMS page at such a path stays visible, unless it sets `seo.htmlSitemap.overCatchAll: true`; an app with its own page at such a path keeps it; `seo: { htmlSitemap: false }` turns them off. Post pages keep `og:type` article and their publish and update times next to the CMS head.
- Requires vue-seo-layer v0.2.0.
- **Install v0.8.1, not v0.8.0.** vue-seo-layer v0.2.0 is a peer dependency (`^0.2.0`): list `"vue-seo-layer": "git+https://git.golem15.com/golem15/vue-seo-layer.git#v0.2.0"` in the app next to `"vue-journal-layer": "git+https://git.golem15.com/golem15/vue-journal-layer.git#v0.8.1"`. v0.8.0 listed vue-seo-layer as its own git dependency, which pnpm refuses by default (`ERR_PNPM_EXOTIC_SUBDEP`); v0.8.1 is otherwise the same release.
## Fixed

View File

@@ -8,4 +8,4 @@ Excerpt: The menu layer now extends vue-seo-layer, so every page of a menu-only
- **Breaking:** `server/api/__site__/cache/purge.post.ts`, `server/lib/siteCachePurge.ts` and `server/plugins/site-cache-purge.ts` are removed from this layer; vue-seo-layer provides the same route, library and plugin with the same environment variables. An app that imported the library from this layer imports it from vue-seo-layer.
- **Upgrade:** set `NUXT_SEO_API_BASE` when the backend is not on `http://127.0.0.1:8096`, or `seo: { cms: false }` for a site without the SEO plugin. The layer brings vue-seo-layer's HTML sitemap pages (pl `/mapa-strony`, en `/sitemap` by default). An app that renders its pages through a root catch-all (`[...slug].vue`) gets none, so a CMS page at such a path stays visible, unless it sets `seo.htmlSitemap.overCatchAll: true`; an app with its own page at such a path keeps it; `seo: { htmlSitemap: false }` turns them off.
- Requires vue-seo-layer v0.2.0.
- **Install v0.5.1, not v0.5.0.** vue-seo-layer v0.2.0 is a peer dependency (`^0.2.0`): list `"vue-seo-layer": "git+https://git.golem15.com/golem15/vue-seo-layer.git#v0.2.0"` in the app next to `"vue-menu-layer": "git+https://git.golem15.com/golem15/vue-menu-layer.git#v0.5.1"`. v0.5.0 listed vue-seo-layer as its own git dependency, which pnpm refuses by default (`ERR_PNPM_EXOTIC_SUBDEP`); v0.5.1 is otherwise the same release.

View File

@@ -0,0 +1,56 @@
---
status: testing
phase: 33-seo-output-audit-and-content
source: [33-VERIFICATION.md]
started: 2026-11-05T01:26:27.413Z
updated: 2026-11-05T01:26:27.413Z
---
## Current Test
number: 1
name: 33-14 Task 4 release steps, in the release-log order: framework v0.6.1, sm-journal-plugin v0.4.0, sm-sitemap-plugin v0.2.0, sm-seo-plugin v0.2.0 (its go.mod must require sm-sitemap-plugin v0.2.0: today it requires v0.1.2, which has no contract package, so GOWORK=off builds fail), vue-seo-layer v0.2.0, then the link:../vue-seo-layer swap in vue-journal-layer, vue-menu-layer and vue-faq-layer, `check-git-install.sh --check-links` over the four layers (must exit 0) and `check-git-install.sh <tag>`, then their tags; app pins and patches (33-12, 33-13, then 33-14-*-locale.patch on the demo); -tags nodynamic in the WebP-linking app builds with the 33-13 DEPLOY.md 'Binary' row corrected; recreate the 33-12 and 33-13 rehearsal databases from their source dumps before the rehearsal (migration 202610280002 was edited); changelog posts
expected: |
Every step logged in 33-release-log.md; release binaries statically linked; nothing tagged off the default branch
awaiting: user response
## Tests
### 1. 33-14 Task 4 release steps, in the release-log order: framework v0.6.1, sm-journal-plugin v0.4.0, sm-sitemap-plugin v0.2.0, sm-seo-plugin v0.2.0 (its go.mod must require sm-sitemap-plugin v0.2.0: today it requires v0.1.2, which has no contract package, so GOWORK=off builds fail), vue-seo-layer v0.2.0, then the link:../vue-seo-layer swap in vue-journal-layer, vue-menu-layer and vue-faq-layer, `check-git-install.sh --check-links` over the four layers (must exit 0) and `check-git-install.sh <tag>`, then their tags; app pins and patches (33-12, 33-13, then 33-14-*-locale.patch on the demo); -tags nodynamic in the WebP-linking app builds with the 33-13 DEPLOY.md 'Binary' row corrected; recreate the 33-12 and 33-13 rehearsal databases from their source dumps before the rehearsal (migration 202610280002 was edited); changelog posts
expected: Every step logged in 33-release-log.md; release binaries statically linked; nothing tagged off the default branch
result: [pending]
### 2. W5 before the v0.6.1 tag: run 33-14-risk-max.sql (read-only) against every production database whose app takes v0.6.1
expected: No row longer than its rule's max, or each listed row shortened or accepted; results logged in 33-release-log.md
result: [pending]
### 3. SC1 production, after the tags (33-13 after-tags decision): deploy grzybyfunkcjonalne.pl per its DEPLOY.md, first the scripts/urls.txt check on the tagged build, then the 33-13-deploy-log.md checklist items 1-8
expected: Every urls.txt line passes; /sitemap.xml is a sitemapindex of sitemap-posts-1, -categories-1, -authors-1, -pages-1 and -images-1; the posts file lists the 62 posts once each with lastmod and no /en/ or hreflang; /sitemap.xsl 404; a post has one canonical, one JSON-LD script, no hreflang=en, breadcrumbs; SEO › Pages and Settings › Sitemaps as listed; a crawl finishes without /en/ 404s or duplicates; GSC reads the index
result: [pending]
### 4. G1 on a deployed site (demo after its patches): check the server log line 'route report: N routes and M noindex paths sent', then that the migrated Additional address /subscriptions (noindex in Nuxt) is excluded with reason noindex on Settings › Sitemaps and absent from sitemap-pages-1.xml without the manual DEPLOY.md removal
expected: The noindex address leaves the XML and HTML sitemaps after the debounced rebuild; a crawl reports no sitemap_noindex for it
result: [pending]
### 5. SC3 live workflow: run a crawl from SEO › Crawls on a deployed site, then from a real Claude client linked over MCP ask it to fix the reported issues with dry_run, review the preview, apply
expected: Every data issue names a tool the client can call (sitemap_update_settings for a noindex Additional address); dry runs write nothing; applying fixes the data issues; fix: code issues are named as template work
result: [pending]
### 6. D-46: Google's Rich Results Test for a post, a category and an FAQ page from the admin's Rich Results link
expected: No errors for BlogPosting, CollectionPage/ItemList and FAQPage
result: [pending]
### 7. Visual check after the deploys: grzyby home, /blog, a category, a post, /autor/admin on desktop and mobile; the demo on prefix_except_default (/pl/... addresses, LanguageSwitcher, /pl/mapa-strony and /sitemap each in its own locale, footer link to the visitor's locale); the new admin screens (SEO tab, Site audit, Crawls with the cancelling state, Auto-links, Pages, Settings › Sitemaps with the headings left empty) including the Blog Editor outline with long headings at 360px (33-02 J2)
expected: Layouts render as in 33-UI-SPEC.md; long outline headings wrap with a hanging indent and are not truncated
result: [pending]
## Summary
total: 7
passed: 0
issues: 0
pending: 7
skipped: 0
blocked: 0
## Gaps

View File

@@ -1,8 +1,8 @@
---
phase: 33-seo-output-audit-and-content
verified: 2026-11-04T23:53:40Z
verified: 2026-11-05T01:29:36Z
status: human_needed
score: "Roadmap success criteria 3/4 verified (SC2, SC3, SC4); SC1 verified at code level, its production part (grzybyfunkcjonalne.pl on the new format) pending the 33-14 Task 4 release. Plan must-haves 226/235 truths verified (202 of 33-01..33-14 plus 23 of 33-15 and 10 of 33-16): 0 failed, 5 pending the release, 3 superseded by Jakub's 2026-11-04 decisions, 1 human (visual)"
score: "Roadmap success criteria 4/4 verified (SC1's production part now evidenced by the release and deploy logs and re-checked live). Plan must-haves 231/235 truths verified: 0 failed, 0 pending the release, 3 superseded by Jakub's 2026-11-04 decisions, 1 human (J2 at 360px, in human item 3)"
covered_files:
- .planning/phases/33-seo-output-audit-and-content/33-01-PLAN.md
- .planning/phases/33-seo-output-audit-and-content/33-01-SUMMARY.md
@@ -30,11 +30,22 @@ covered_files:
- .planning/phases/33-seo-output-audit-and-content/33-12-SUMMARY.md
- .planning/phases/33-seo-output-audit-and-content/33-13-PLAN.md
- .planning/phases/33-seo-output-audit-and-content/33-13-SUMMARY.md
- .planning/phases/33-seo-output-audit-and-content/33-13-deploy-log.md
- .planning/phases/33-seo-output-audit-and-content/33-14-PLAN.md
- .planning/phases/33-seo-output-audit-and-content/33-14-SUMMARY.md
- .planning/phases/33-seo-output-audit-and-content/33-14-notes-sm-journal-plugin-v0.4.0.md
- .planning/phases/33-seo-output-audit-and-content/33-14-notes-sm-seo-plugin-v0.2.0.md
- .planning/phases/33-seo-output-audit-and-content/33-14-notes-sm-sitemap-plugin-v0.2.0.md
- .planning/phases/33-seo-output-audit-and-content/33-14-notes-summercms-v0.6.1.md
- .planning/phases/33-seo-output-audit-and-content/33-14-notes-vue-faq-layer-v0.5.0.md
- .planning/phases/33-seo-output-audit-and-content/33-14-notes-vue-journal-layer-v0.8.0.md
- .planning/phases/33-seo-output-audit-and-content/33-14-notes-vue-menu-layer-v0.5.0.md
- .planning/phases/33-seo-output-audit-and-content/33-14-notes-vue-seo-layer-v0.2.0.md
- .planning/phases/33-seo-output-audit-and-content/33-15-PLAN.md
- .planning/phases/33-seo-output-audit-and-content/33-15-SUMMARY.md
- .planning/phases/33-seo-output-audit-and-content/33-16-PLAN.md
- .planning/phases/33-seo-output-audit-and-content/33-16-SUMMARY.md
- .planning/phases/33-seo-output-audit-and-content/33-release-log.md
- admin/openapi/admin.json
- admin/src/api/schema.d.ts
- docs/backend/field-types.md
@@ -61,41 +72,44 @@ covered_files:
- modules/phrasebook/lang/pl/validation.yaml
- modules/signpost/README.md
- scripts/check-phase33.sh
covered_digest: "v2:sha256:9f0a6381baf9ae704a9f2f164e838bafb0b226dbe0b2b7461fe028436b0532d3"
covered_digest: "v2:sha256:5894be73f12c8d469b5e95fdd10da818daf2a59e0d37d8e9d6e19078eafcf5e9"
behavior_unverified: 0
overrides_applied: 2
overrides_applied: 3
overrides:
- must_have: "G2 (33-08 drift check): no false journal-tag drift warning while golem15.journal.tag_pages is false"
reason: "Log noise only, no must-have violated. The fix needs a framework change: signpost.Activate refuses a menu item type whose DefaultPattern does not start with /, so sm-journal-plugin cannot drop the journal-tag pattern while tag pages are off (an additive pact field such as ContentDescriptor.Routable, or a signpost rule). Deferred to v0.6.2 (deferred-items.md, 33-12 entry and 'From 33-15')"
reason: "Log noise only, no must-have violated. The fix needs a framework change: signpost.Activate refuses a menu item type whose DefaultPattern does not start with /, so sm-journal-plugin cannot drop the journal-tag pattern while tag pages are off (an additive pact field such as ContentDescriptor.Routable, or a signpost rule). Deferred to v0.6.2 (deferred-items.md, 33-12 entry and 'From 33-15'). Still seen at every Nuxt start on the demo and on grzybyfunkcjonalne.pl after the release (33-release-log.md steps 9b and 9d)"
accepted_by: "Jakub Zych"
accepted_at: "2026-11-04"
- must_have: "D-106 / W5: framework v0.6.1 is strictly additive (patch); lagoon.Validate's stricter min/max length check ships in it"
reason: "Kept in v0.6.1 with an explicit 'Changed' entry in 33-14-notes-summercms-v0.6.1.md (a stored value longer than its max fails its next admin save) and a production SQL check (33-14-risk-max.sql) on every production database before the tag"
reason: "Kept in v0.6.1 with an explicit 'Changed' entry in 33-14-notes-summercms-v0.6.1.md (a stored value longer than its max fails its next admin save). The entry is on the published post https://summercms.io/changelog/summercms-0-6-1 (checked 2026-11-05). The production SQL check that was its second condition is waived by the override below"
accepted_by: "Jakub Zych"
accepted_at: "2026-11-04"
- must_have: "W5 before the v0.6.1 tag: run 33-14-risk-max.sql (read-only) against every production database whose app takes v0.6.1"
reason: "Waived by Jakub on 2026-11-05 ('don't mind it'; no production fonoteka, the app the check was written for). Not run on the databases that did take v0.6.1 (summercms.io, demo.summercms.io, grzybyfunkcjonalne.pl); the residual risk is that a stored value longer than its max fails its next admin save until it is shortened, which the published v0.6.1 notes state. Recorded in 33-release-log.md (Task 3 answer) and 33-14-SUMMARY.md"
accepted_by: "Jakub Zych"
accepted_at: "2026-11-05"
re_verification:
previous_status: gaps_found
previous_verified: 2026-11-04T20:20:34Z
previous_commit: 97abc77
previous_score: "Roadmap SC 2/4; plan must-haves 191/202 (2 failed: G3)"
gaps_closed:
- "D-57 / SC2 hreflang: a page without a translation has no hreflang for that locale (G3; sm-journal-plugin 0a62090, TestContentDescriptorsTranslatedLocales on the real descriptor path)"
- "SC1 / D-24: the sitemaps stay consistent with noindex (G1; sm-seo-plugin 9de6b2e, sm-sitemap-plugin 6b67ab7, vue-seo-layer 7a26692; TestNoindexPathsTracer, TestSitemapNoindexTool, routes.test.ts, smoke routereport noindex=)"
previous_status: human_needed
previous_verified: 2026-11-04T23:53:40Z
previous_commit: 9c11b70
previous_score: "Roadmap SC 3/4 (SC1 production part pending the release); plan must-haves 226/235 (5 pending the release, 3 superseded, 1 human)"
gaps_closed: []
gaps_remaining: []
regressions: []
human_items_settled:
- item: 1
test: "33-14 Task 4 release steps"
disposition: "satisfied: 33-release-log.md steps 0-10 and 6b-9f; 11 tags on their origins and on the default branches, checked with git ls-remote in this run"
- item: 2
test: "W5 before the v0.6.1 tag: 33-14-risk-max.sql"
disposition: "accepted override (waived by Jakub, 2026-11-05)"
- item: 3
test: "SC1 production grzybyfunkcjonalne.pl"
disposition: "satisfied for deploy-log checklist items 1, 2, 4 (public part) and 8 and the urls.txt check (production smoke ok, 149 urls; smoke-seo ok); items 1 and 2 re-checked live in this run. Checklist items 3, 5, 6 and 7 move to human item 3 below"
- item: 4
test: "G1 on a deployed site (demo)"
disposition: "satisfied: /subscriptions left out with reason noindex without the manual removal (33-release-log.md step 9b); re-checked live: absent from sitemap-pages-1.xml and from the HTML sitemap's page group, page answers noindex, nofollow"
human_verification:
- test: "33-14 Task 4 release steps, in the release-log order: framework v0.6.1, sm-journal-plugin v0.4.0, sm-sitemap-plugin v0.2.0, sm-seo-plugin v0.2.0 (its go.mod must require sm-sitemap-plugin v0.2.0: today it requires v0.1.2, which has no contract package, so GOWORK=off builds fail), vue-seo-layer v0.2.0, then the link:../vue-seo-layer swap in vue-journal-layer, vue-menu-layer and vue-faq-layer, `check-git-install.sh --check-links` over the four layers (must exit 0) and `check-git-install.sh <tag>`, then their tags; app pins and patches (33-12, 33-13, then 33-14-*-locale.patch on the demo); -tags nodynamic in the WebP-linking app builds with the 33-13 DEPLOY.md 'Binary' row corrected; recreate the 33-12 and 33-13 rehearsal databases from their source dumps before the rehearsal (migration 202610280002 was edited); changelog posts"
expected: "Every step logged in 33-release-log.md; release binaries statically linked; nothing tagged off the default branch"
why_human: "Pending the release by design: Task 4 runs after this verification and needs Jakub's go-ahead for tags, pushes and deploys"
- test: "W5 before the v0.6.1 tag: run 33-14-risk-max.sql (read-only) against every production database whose app takes v0.6.1"
expected: "No row longer than its rule's max, or each listed row shortened or accepted; results logged in 33-release-log.md"
why_human: "Condition of the accepted W5 override; needs production database access"
- test: "SC1 production, after the tags (33-13 after-tags decision): deploy grzybyfunkcjonalne.pl per its DEPLOY.md, first the scripts/urls.txt check on the tagged build, then the 33-13-deploy-log.md checklist items 1-8"
expected: "Every urls.txt line passes; /sitemap.xml is a sitemapindex of sitemap-posts-1, -categories-1, -authors-1, -pages-1 and -images-1; the posts file lists the 62 posts once each with lastmod and no /en/ or hreflang; /sitemap.xsl 404; a post has one canonical, one JSON-LD script, no hreflang=en, breadcrumbs; SEO › Pages and Settings › Sitemaps as listed; a crawl finishes without /en/ 404s or duplicates; GSC reads the index"
why_human: "Pending the release (production deploy after the tags), not a failure"
- test: "G1 on a deployed site (demo after its patches): check the server log line 'route report: N routes and M noindex paths sent', then that the migrated Additional address /subscriptions (noindex in Nuxt) is excluded with reason noindex on Settings › Sitemaps and absent from sitemap-pages-1.xml without the manual DEPLOY.md removal"
expected: "The noindex address leaves the XML and HTML sitemaps after the debounced rebuild; a crawl reports no sitemap_noindex for it"
why_human: "Proven by TestNoindexPathsTracer and the layer smoke on fixtures; the live round trip needs the released versions on a running site"
- test: "SC3 live workflow: run a crawl from SEO › Crawls on a deployed site, then from a real Claude client linked over MCP ask it to fix the reported issues with dry_run, review the preview, apply"
expected: "Every data issue names a tool the client can call (sitemap_update_settings for a noindex Additional address); dry runs write nothing; applying fixes the data issues; fix: code issues are named as template work"
why_human: "External agent-driven workflow (33-VALIDATION.md manual-only row)"
@@ -103,12 +117,115 @@ human_verification:
expected: "No errors for BlogPosting, CollectionPage/ItemList and FAQPage"
why_human: "External Google tool (33-VALIDATION.md manual-only row)"
- test: "Visual check after the deploys: grzyby home, /blog, a category, a post, /autor/admin on desktop and mobile; the demo on prefix_except_default (/pl/... addresses, LanguageSwitcher, /pl/mapa-strony and /sitemap each in its own locale, footer link to the visitor's locale); the new admin screens (SEO tab, Site audit, Crawls with the cancelling state, Auto-links, Pages, Settings › Sitemaps with the headings left empty) including the Blog Editor outline with long headings at 360px (33-02 J2)"
expected: "Layouts render as in 33-UI-SPEC.md; long outline headings wrap with a hanging indent and are not truncated"
why_human: "Visual rendering; element tests run under happy-dom without layout"
expected: "Layouts render as in 33-UI-SPEC.md; long outline headings wrap with a hanging indent and are not truncated. This item also carries the open grzybyfunkcjonalne.pl checklist items of 33-13-deploy-log.md: item 3, SEO › Pages in /gfadmin lists /, /blog (Artykuły), /kontakt and /trwaja-prace (Trwają prace), none Not on the site, SEO tabs with the CSV descriptions (and, from item 4, Settings › Sitemaps shows the five files with their counts); item 5, a crawl from SEO › Site audit finishes with no /en/ 404s and no duplicate sitemap entries; item 6, the 0.8 card and title markup on desktop and mobile (whole-card links, no more link, breadcrumbs, footer Mapa strony); item 7, resubmit https://grzybyfunkcjonalne.pl/sitemap.xml in Search Console and check that Google reads its files"
why_human: "Visual rendering (element tests run under happy-dom without layout), logged-in admin screens on production, and Google Search Console"
---
# Phase 33: SEO output, audit and content Verification Report
**Phase Goal:** As a site editor and as an SEO specialist auditing a SummerCMS site, I want to have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, so that sites are indexed correctly and issues can be fixed through MCP.
**Verified:** 2026-11-05T01:29:36Z
**Status:** human_needed
**Re-verification:** Yes, the second one, after the 33-14 release (Task 4). It covers 33-14-SUMMARY.md, 33-release-log.md, 33-13-deploy-log.md and the 33-14 release notes. The gap-closure re-verification (2026-11-04T23:53:40Z, human_needed, commit 9c11b70) and the initial verification (2026-11-04T20:20:34Z, gaps_found, commit 97abc77) are kept below.
**Mode:** mvp.
## Release re-verification result (2026-11-05T01:29:36Z)
The release happened as the SUMMARY says, as far as read-only checks can see. All 11 tags are on their origins, and each tagged commit is on its repository's default branch. The four changelog posts answer 200. Production grzybyfunkcjonalne.pl serves the new sitemap format and the CMS head. The demo leaves the noindex `/subscriptions` out of both sitemaps, with no manual removal. The framework HEAD has no code change since v0.6.1. `go vet ./...` and `go test -short ./...` pass, and gofmt is clean.
No gap is open. Four of the seven human items in 33-UAT.md are settled here: three by evidence and one by an accepted override. Three stay open for a human: the live MCP session, the Rich Results Test, and the visual and admin checks. The third of these now also carries the open grzybyfunkcjonalne.pl checklist items 3, 5, 6 and 7. Status: human_needed.
### User Flow Coverage
| Step | Expected | Evidence | Status |
|------|----------|----------|--------|
| Editor publishes content | Sitemap index with per-type files, real lastmod, stable numbering | Unchanged from the gap-closure run. Live: grzybyfunkcjonalne.pl/sitemap.xml is a sitemapindex of authors, categories, pages, posts and images; demo.summercms.io/sitemap.xml is an index of 4 files | ✓ |
| Crawler/visitor opens a page | SSR head from the CMS, one JSON-LD @graph, hreflang for translated locales only, breadcrumbs | Live on /blog/blogchaga-wprowadzenie: 1 canonical on the apex, 1 ld+json script (WebSite, Organization, WebPage, BlogPosting, BreadcrumbList, Person, ImageObject), robots `index, follow`, 0 hreflang (site is Polish only), `nav.seo-breadcrumbs` Strona główna › Chaga › post, og:type article | ✓ |
| Nuxt-only noindex page | Leaves the XML and HTML sitemaps | Live on the demo: /subscriptions answers `noindex, nofollow` (header and meta); it is absent from sitemap-pages-1.xml (/, /blog, /chat, /contact, /faq, /forum, /quizzes) and from the "Page" group of /sitemap. Its only link there is the header menu | ✓ |
| SEO specialist runs the audit | Issues per URL, each with an MCP tool or fix: code | Automated as before; live MCP session is human item 1 | ✓ (live MCP session: human) |
| Outcome | "sites are indexed correctly and issues can be fixed through MCP" | Production grzybyfunkcjonalne.pl now runs the tagged build: production smoke `ok (149 urls)`, smoke-seo ok, and the live checks above. Search Console reading the index is human item 3 | ✓ (GSC and the MCP fix loop: human) |
### Roadmap Success Criteria
| # | Truth | Status | Evidence |
|---|-------|--------|----------|
| SC1 | Sitemap index with per-type files, configurable size, stable numbering, real lastmod, consistent with noindex and robots.txt; grzybyfunkcjonalne.pl on the new format | ✓ VERIFIED | Code level as before. Production, checked live in this run: /sitemap.xml is a `<sitemapindex>` of sitemap-authors-1, -categories-1, -pages-1, -posts-1 and -images-1 on the apex. sitemap-posts-1.xml has 62 `<loc>` entries, 62 unique, 62 `<lastmod>`, 0 `/en/`, 0 hreflang. sitemap-pages-1.xml lists /, /blog, /kontakt and /trwaja-prace once each, so the Additional addresses step held. /sitemap.xsl answers 404. /en/blog answers 404. robots.txt has `Sitemap: https://grzybyfunkcjonalne.pl/sitemap.xml`. /mapa-strony answers 200 with 74 links. http and www redirect 301 to the apex. Noindex consistency is proven live on the demo (row above). Logged only, not re-run: the production smoke `ok (149 urls)` after the `/autor/admin` expectation fix (0554f3e), smoke-seo ok and `check-deploy.sh --live` ok (33-release-log.md 9e and 9f) |
| SC2 | Server-side head, one JSON-LD @graph, hreflang, breadcrumbs from the CMS; build fails on an indexable ssr:false route | ✓ VERIFIED | As before, plus the live production post above. The demo strict `smoke-seo` passed after its deploy: 5 hreflang links on a post and a /pl/ alternate answering 200 (33-release-log.md 9b, logged) |
| SC3 | Crawler reports issues per URL, each fixable through MCP | ✓ VERIFIED (automated) | Unchanged. Live client session: human item 1 |
| SC4 | New code has unit tests in the phase's last plan | ✓ VERIFIED | Unchanged. The release pre-check reran `PHASE33_REQUIRE_DOCKER=1 check-phase33.sh --all` green on 6d14f71 (logged, step 0). This run reran the framework's `go vet ./...` and `go test -short ./...` at HEAD: both exit 0 |
**Score:** 4/4 roadmap criteria verified. Plan must-haves: 231/235 truths verified, 0 failed, 0 pending, 3 superseded, 1 human, 0 present-but-behaviour-unverified.
### Truths that were pending the release
| Plan | Truth | Now | Evidence |
|------|-------|-----|----------|
| 33-13 #1 | urls.txt answers every line as before, repeated on the tagged build | ✓ VERIFIED | Tagged-build rehearsal `smoke: ok (128 urls)`, then `ok (129 urls)` after the `/autor/admin` fix. On production, `ok (149 urls)` with urls-production.txt. One line had failed on production because it was bound to the rehearsal's author name ("admin"); the site was fine (release log 9e). The fix checks only the fixed parts of the title (sm-grzybyfunkcjonalne-app 0554f3e, on origin/master) |
| 33-14 #6 | Release order framework → journal → sitemap → seo → vue-seo-layer → content layers → apps; layers pin the tag instead of link: | ✓ VERIFIED | `git ls-remote --tags` in this run found all 11 tags: summercms v0.6.1 (5db8c61 → 6d14f71), sm-journal-plugin v0.4.0 (48aa3ff → 6823dcc), sm-sitemap-plugin v0.2.0 (1188efd → fdbe593), sm-seo-plugin v0.2.0 (adda8a9 → 22f108b), vue-seo-layer v0.2.0 (b69647f → 3868f3d), vue-journal-layer v0.8.0 (7d93f06 → 0a77e6e) and v0.8.1 (5c26b5d → f5dc9b2), vue-menu-layer v0.5.0 (7e90962 → c605384) and v0.5.1 (47b022e → dc38f79), vue-faq-layer v0.5.0 (cae1502 → 9cc7f91) and v0.5.1 (8d46b31 → a092363). Each tagged commit is an ancestor of its origin default branch, and each origin default branch head is the newest tag's commit, so nothing is tagged off the default branch. The tagged go.mod files require summercms v0.6.1, and sm-seo-plugin also requires sm-sitemap-plugin v0.2.0. The tagged v0.8.1/v0.5.1 package.json files have 0 `link:`: vue-seo-layer is a `^0.2.0` peer plus a `#v0.2.0` git devDependency. This is the option-B deviation Jakub chose after v0.8.0 failed `check-git-install.sh` (ERR_PNPM_EXOTIC_SUBDEP); v0.8.0 and v0.5.0 remain published but do not install with pnpm 12 defaults |
| 33-14 #7 | Patches applied after the tags, apps build and test on the tagged versions, demo check-pins | ✓ VERIFIED (logged; pins checked) | Logged in release log 7a–7d: the builds, tests, `check-pins ok (25 modules)`, static `-tags nodynamic` binaries and smokes. Checked in this run: origin/master of sm-summercmsio-app (395ed78), sm-demo-app (da03c06), sm-grzybyfunkcjonalne-app (0554f3e) and sm-bm-app (43f2fc9) equals the logged heads. The three Journal apps require summercms v0.6.1 and journal v0.4.0, and the demo and grzyby also require seo and sitemap v0.2.0. summer.yaml carries `nodynamic`. The frontend pointers are vue-demo-app fe5d38d, vue-grzybyfunkcjonalne-app 0771c14 and vue-summercmsio-app 16ab519 |
| 33-14 #8 | Framework changelog post the same day; token never printed | ✓ VERIFIED (token: judgment, logged) | In this run, https://summercms.io/changelog/summercms-0-6-1, sm-sitemap-plugin-0-2-0, sm-seo-plugin-0-2-0 and sm-journal-plugin-0-4-0 each answer 200 with matching titles. The three plugin posts are linked from /changelog/plugins. The v0.6.1 post carries the W5 "Changed" text and the nodynamic note |
| 33-14 #9 | Every executed release step appended to 33-release-log.md | ✓ VERIFIED | Steps 0–10 plus 6b, 6c, 6d, 7a–7d, 9a–9f are present, with TAG lines for all 11 tags. The failed 6b and 9e steps are recorded with their checkpoint answers |
Totals (235): 226 from the gap-closure run + 5 above = 231 verified. Superseded: 3 (the two uat truths of 33-13 and the uat check of 33-14; Jakub's 2026-11-04 decision, no uat). Human: 1 (J2 at 360px, in human item 3).
Prohibitions, judgment tier (non-authoritative): D-106 "no push, tag, deploy or post without Jakub's go-ahead" holds per the recorded Task 3 answer and the two checkpoint answers (6c, 9f). "The changelog token is never printed" is supported only by the log ("read by the script only, never printed"), and this run cannot observe it.
### Human items of 33-UAT.md
| UAT row | Item | Disposition here |
|---------|------|------------------|
| 1 | 33-14 Task 4 release steps | **Satisfied** by 33-release-log.md and the tag, branch, pin and changelog checks above. One deviation is accepted at a checkpoint: the layers ship as v0.8.1/v0.5.1 with a peer dependency (option B). The rehearsal databases were rebuilt from scratch rather than recreated from dumps: grzyby used a fresh throwaway database with the PHP export, and the demo uses migrate plus demo:seed. That meets the intent, since the edited migration ran on a clean database |
| 2 | W5 SQL check | **Accepted override** (Jakub, 2026-11-05: "don't mind it"; no production fonoteka). Residual risk recorded in the override |
| 3 | SC1 production grzybyfunkcjonalne.pl | **Satisfied** for the urls.txt check and checklist items 1, 2, the public part of 4, and 8 (nodynamic, so the built-in WebP encoder; 285 variants written). Items 1 and 2 were re-checked live. Items 3, 5, 6 and 7 (and the admin files table of item 4) need a human with /gfadmin or Search Console access and move to human item 3 |
| 4 | G1 on the demo | **Satisfied**: the route report sent 7 routes and 20 noindex paths; Settings › Sitemaps reported left_out `{"noindex":1}` (logged, step 9b). Re-checked live as in the flow table. The row's "a crawl reports no sitemap_noindex" follows, because the address is not in any sitemap, and the live crawl itself is part of human item 1 |
| 5 | SC3 live MCP workflow | Open: human item 1 |
| 6 | D-46 Rich Results Test | Open: human item 2 |
| 7 | Visual and admin checks | Open: human item 3, now including grzyby checklist items 3, 5, 6 and 7 |
33-UAT.md is not edited here. Rows 1–4 stay `[pending]` until `/msd-verify-work 33` records them: pass for rows 1, 3 and 4 with this report as evidence, and skipped with the override as reason for row 2. Row 7's text in the UAT file does not list the grzyby checklist items. They are in this report's `human_verification` item 3 and in 33-13-deploy-log.md.
### Behavioral spot-checks (this run, read-only)
| Behavior | Command | Result | Status |
|----------|---------|--------|--------|
| 11 tags on origin | `git ls-remote --tags origin refs/tags/<t> refs/tags/<t>^{}` per repository | All 11 present; tag objects and peeled commits as in the table above | ✓ PASS |
| Tags on the default branch | `git merge-base --is-ancestor <commit> origin/<default>`; `ls-remote` of the default branch | All 11 ancestors; each default branch head equals its newest tag's commit | ✓ PASS |
| Changelog posts | `curl` of the four post URLs and /changelog/plugins | 200 ×5; the three plugin posts are linked from /changelog/plugins | ✓ PASS |
| grzyby sitemaps | `curl` /sitemap.xml, /sitemap-posts-1.xml, /sitemap-pages-1.xml, /sitemap.xsl, /robots.txt, /mapa-strony, /en/blog | index of 5 files; posts 62/62 unique/62 lastmod, 0 /en/, 0 hreflang; pages 4; xsl 404; Sitemap: line; HTML sitemap 200; /en/blog 404 | ✓ PASS |
| grzyby post head | `curl` /blog/blogchaga-wprowadzenie | 200; 1 canonical (apex), 1 ld+json, 0 hreflang, robots index, follow, breadcrumbs, og:type article; header `X-Robots-Tag: index, follow` | ✓ PASS |
| Demo noindex page | `curl` /sitemap-pages-1.xml, /sitemap, /subscriptions | /subscriptions absent from both sitemaps' page lists; page answers `noindex, nofollow` | ✓ PASS |
| Framework unchanged since the tag | `git diff --quiet v0.6.1 HEAD -- ':!.planning'` | no diff; 6d14f71 is formatting only (`git show -w` shows one function literal split over lines) | ✓ PASS |
| Framework regression | `go vet ./...`; `go test -short ./...` | exit 0 and exit 0 | ✓ PASS |
| gofmt leftovers of the previous run | `gofmt -l` over tracked Go files (framework, sm-journal-plugin) | 0 and 0; the two Info rows on sm-journal-plugin formatting are resolved (b8d98ce) | ✓ PASS |
| No debt markers in the release commits | added-line grep for TBD/FIXME/XXX/TODO/HACK over each repository's release diff | none; the one hit is a `mktemp` template `XXXXXX` in vue-journal-layer's check-git-install.sh | ✓ PASS |
Not re-run here: the Docker gate, the app builds and smokes, and the server-side steps (migrations, `journal:image-variants`, 404-log cleanup). They are logged in 33-release-log.md with their outputs.
### Anti-patterns and notes from the release
| Item | Severity | Impact |
|------|----------|--------|
| `check-phase33.sh --consumers` refuses after the release (`33-12-sm-demo-app.patch does not apply`): it checks the release patches against unpatched app HEADs | ⚠️ Warning (follow-up) | `--all` no longer passes as-is on the released state. The script needs a post-release mode or the stage retired; recorded as a known follow-up in 33-14-SUMMARY.md. Not a goal gap: the apps' own builds, tests and smokes ran |
| Posts now send `X-Robots-Tag: index, follow` (seen live) | ℹ️ Info | Harmless; the 2026-10-31 cutover check in grzyby DEPLOY.md expected no header and should be updated |
| G2 journal-tag drift line at every Nuxt start (demo, grzyby) | ℹ️ Info (override) | Deferred to v0.6.2 |
| The tagged plugin go.mod files keep `replace git.golem15.com/golem15/summercms => ../summercms.go` | ℹ️ Info | Same as at their earlier tags; a replace in a dependency's go.mod is ignored by consumers |
| vue-journal-layer v0.8.0, vue-menu-layer v0.5.0 and vue-faq-layer v0.5.0 stay published but fail to install with pnpm 12 defaults | ℹ️ Info | READMEs and notes direct users to v0.8.1/v0.5.1 |
| sm-bm-app stays on framework v0.6.0 | ℹ️ Info | bm mounts no Journal; its noindex deploy was the D-72 part |
| summercms.go planning commits after the v0.6.1 push are local | ℹ️ Info | Planning docs only, not pushed |
| covered_files leaves out the 15 files of 6d14f71 `style: gofmt` | ℹ️ Info | Formatting of files outside the phase's features (cmd/summer, cabana token tests, tide, compass…). They are not covered, so later edits there do not mark this phase stale |
### Gaps Summary
None. The release that the previous run left pending is done and evidenced. W5's SQL check is an accepted override. Three human items remain: the live MCP crawl, dry run and apply; the Rich Results Test; and the visual and admin checks, including grzybyfunkcjonalne.pl checklist items 3, 5, 6 and 7 and the Search Console resubmit.
---
# Gap-closure re-verification (2026-11-04T23:53:40Z, human_needed, commit 9c11b70)
The report below is kept unchanged, with its headings moved down one level. Its human items 1–4 are settled above, and its items 5–7 are the current human items 1–3.
## Phase 33: SEO output, audit and content Verification Report
**Phase Goal:** As a site editor and as an SEO specialist auditing a SummerCMS site, I want to have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, so that sites are indexed correctly and issues can be fixed through MCP.
**Verified:** 2026-11-04T23:53:40Z
**Status:** human_needed
@@ -117,11 +234,11 @@ human_verification:
Repository HEADs checked (none tagged, nothing pushed; commits since the base tag): summercms.go 6e99b18 (84 since v0.6.0, planning docs included), sm-sitemap-plugin b2b3a1d (23 since v0.1.2), sm-seo-plugin c71b58e (37 since v0.1.1), sm-journal-plugin cf13c60 (21 since v0.3.1), vue-seo-layer 3868f3d (24 since v0.1.1), vue-journal-layer 761c7fc (16 since v0.7.1), vue-menu-layer a7602c9 (2 since v0.4.0), vue-faq-layer 5e5950a (4 since v0.4.0).
## Re-verification result (2026-11-04T23:53:40Z)
### Re-verification result (2026-11-04T23:53:40Z)
Both gaps are closed in code, each with a test on the production path. No earlier must-have regressed. The full gate passed again in this run. G2 and W5 are recorded as accepted overrides, following Jakub's decisions of 2026-11-04. What remains is the release (33-14 Task 4) and the checks that can only run after it, so the status is human_needed.
### User Flow Coverage
#### User Flow Coverage
| Step | Expected | Evidence | Status |
|------|----------|----------|--------|
@@ -131,7 +248,7 @@ Both gaps are closed in code, each with a test on the production path. No earlie
| SEO specialist runs the audit | Issues per URL, each with an MCP tool or fix: code | sitemap_noindex on an Additional address names sitemap_update_settings (TestSitemapNoindexTool); the crawl lifecycle is fixed (TestCrawlTimeout, TestCrawlCancelRunning, TestCrawlStaleRecovery, TestCrawlStoreTimeout) | ✓ (live MCP session: human) |
| Outcome | "sites are indexed correctly and issues can be fixed through MCP" | Holds in code and on the fixture and rehearsal sites; production grzybyfunkcjonalne.pl is pending the release | ⚠ pending the release (human) |
### Roadmap Success Criteria
#### Roadmap Success Criteria
| # | Truth | Status | Evidence |
|---|-------|--------|----------|
@@ -142,14 +259,14 @@ Both gaps are closed in code, each with a test on the production path. No earlie
**Score:** 3/4 roadmap criteria verified, SC1's production part pending the release. Plan must-haves: 226/235 truths verified, 0 failed, 0 present-but-behaviour-unverified.
### Previously failed truths
#### Previously failed truths
| Plan | Truth | Now | Evidence |
|------|-------|-----|----------|
| 33-03 #4 | "…xhtml:link alternates for each translated locale…; a locale without a URL gets no alternate…" | ✓ VERIFIED | The Journal descriptors now produce URL "" for untranslated locales on the real path (TestContentDescriptorsTranslatedLocales passed in this run). TestHreflangAlternates (sm-sitemap-plugin b2b3a1d) now uses Journal-shaped records with every enabled locale present; it passed in this run. The fixture-only reliance recorded in the first verification is gone |
| 33-06 #7 | "hreflang comes from one source…; a locale without a translation is absent…" | ✓ VERIFIED | Same descriptor rule; `translatedLocales` (sm-seo-plugin classes/alternates.go:65-79) drops URL ""; TestAlternates (sm-seo-plugin 2a288a9, Journal-shaped records) passed in this run |
### Plan must-haves of the gap-closure plans
#### Plan must-haves of the gap-closure plans
| Plan | Truths | Result | Notes |
|------|--------|--------|-------|
@@ -158,14 +275,14 @@ Both gaps are closed in code, each with a test on the production path. No earlie
Totals (235): 191 earlier + 2 previously failed (now verified) + 23 + 10 = 226 verified. Still pending the release: 5 (33-13 truth 1 repeated on the tags; 33-14 release order, patches with app builds and check-pins, changelog post, release-log steps). Superseded by Jakub's 2026-11-04 decisions: 3 (two uat truths of 33-13, the uat check of 33-14). Human: 1 (J2 at 360px).
### Overrides applied
#### Overrides applied
| Item | Kind | Disposition |
|------|------|-------------|
| G2 false journal-tag drift warning | warning (no must-have violated) | Accepted deferral to v0.6.2 (Jakub, 2026-11-04). It needs a framework change in signpost.Activate or an additive pact field. Not a gap |
| W5 stricter min/max length check in v0.6.1 (D-106 "strictly additive") | judgment-tier prohibition | Accepted for v0.6.1 (Jakub, 2026-11-04). The "Changed" note is present in 33-14-notes-summercms-v0.6.1.md:19, and 33-14-risk-max.sql exists. Running it on production before the tag is human item 2 |
### Review findings in scope
#### Review findings in scope
**33-REVIEW.md, as filtered by the 33-15 and 33-16 plans.** In scope were:
- L1: CR-01, CR-02, WR-01, WR-02 (docs), WR-03, WR-05;
@@ -197,7 +314,7 @@ Out of scope, deferred to the v0.6.2 backlog by the plans (deferred-items.md "Fr
- the info items;
- the verifier warnings W1 to W4.
### Behavioral spot-checks, gate and patches
#### Behavioral spot-checks, gate and patches
| Behavior | Command | Result | Status |
|----------|---------|--------|--------|
@@ -208,7 +325,7 @@ Out of scope, deferred to the v0.6.2 backlog by the plans (deferred-items.md "Fr
| Demo locale patches stacked | scratch worktrees: apply the 33-12 patch, then `git apply --check` of 33-14-*-locale.patch | OK for both; vue-demo-app ends on `strategy: 'prefix_except_default'` with the `/pl/mapa-strony` sitemap path; worktrees removed | ✓ PASS |
| Journal stays additive | `git diff v0.3.1..HEAD` of non-test Go files: removed or changed exported `func` lines | 0; menu_item_types_test.go and the smoke test unchanged since 311c28a | ✓ PASS |
### Anti-patterns and remaining notes
#### Anti-patterns and remaining notes
| File | Pattern | Severity | Impact |
|------|---------|----------|--------|
@@ -224,7 +341,7 @@ Out of scope, deferred to the v0.6.2 backlog by the plans (deferred-items.md "Fr
The first verification's info rows are settled. The stale "Saving Settings › Journal answers 500" entry is now marked resolved (deferred-items.md:14). The W5 warning became the override above.
### Human Verification Required
#### Human Verification Required
These are listed in the frontmatter `human_verification`. Everything except item 7 depends on the release.
1. 33-14 Task 4 release steps: tags in order, the sm-seo-plugin pin, the link: swap with `--check-links`, app pins and patches, `-tags nodynamic` with the DEPLOY.md row fixed, rehearsal databases recreated, changelog posts.
@@ -235,7 +352,7 @@ These are listed in the frontmatter `human_verification`. Everything except item
6. D-46 Rich Results Test.
7. Visual checks (grzyby, demo on prefix_except_default, admin screens, J2 at 360px).
### Gaps Summary
#### Gaps Summary
None. G1 and G3 are closed in code, each with a test on the production path. G2 and W5 are accepted overrides. The phase can proceed to the release step (33-14 Task 4), followed by the human items above.
@@ -455,3 +572,8 @@ _Verifier: Claude (msd-verifier)_
_Re-verified: 2026-11-04T23:53:40Z_
_Verifier: Claude (msd-verifier)_
---
_Re-verified after the release: 2026-11-05T01:29:36Z_
_Verifier: Claude (msd-verifier)_

View File

@@ -2,6 +2,15 @@
The phase's release ledger. Plan 33-01 wrote the planned contents; plan 33-14 executes the releases and appends each step to "Executed steps" as it finishes, so a resumed run confirms each `step <n> done` row and skips it: no tag is created twice, no push is forced, a changelog post is published once. Nothing is pushed or tagged before 33-14 (2026-10-28 release cadence: all tags in 33-14).
## Task 3 answer (Jakub, 2026-11-04/05): release
- **Go-ahead:** release after verification (33-VERIFICATION.md re-verified 9c11b70: human_needed, no gaps).
- **Versions:** summercms v0.6.1, sm-journal-plugin v0.4.0, sm-sitemap-plugin v0.2.0, sm-seo-plugin v0.2.0, vue-seo-layer v0.2.0, vue-journal-layer v0.8.0, vue-menu-layer v0.5.0, vue-faq-layer v0.5.0 (layer package.json versions already bumped).
- **WebP build:** option B. Every app that mounts the Journal (demo, summercms.io, grzyby) builds with `-tags nodynamic` (static); DEPLOY.md keeps or restores "static"; the 33-13 grzyby patch's "dynamically linked" Binary row is reverted.
- **Deploys, all four:** summercms.io (Journal migrations, `journal:image-variants`); the demo on rome (33-12 patches plus the 33-14 locale patches, DEPLOY "Before"/"After" blocks, `journal:image-variants`, G1 check on `/subscriptions`); bm (push sm-bm-app incl. 3 commits from other sessions, deploy per DEPLOY.md, nginx header on the live vhost after `nginx -t`); production grzybyfunkcjonalne.pl last (DEPLOY.md steps 1–12, pg_dump first, step 5 `en` off and step 10 Additional addresses emptied confirmed; urls.txt check on the tagged build first; 33-13-deploy-log.md check list after; `journal:image-variants` once).
- **W5 production SQL check (33-14-risk-max.sql):** skipped by Jakub (no production fonoteka; "don't bother").
- **Changelog:** framework v0.6.1 on /changelog; sm-journal-plugin v0.4.0, sm-sitemap-plugin v0.2.0, sm-seo-plugin v0.2.0 on /changelog/plugins; no layer posts.
## Version base (Jakub, 2026-11-04)
The plan text was written against v0.5.1 / v0.5.2. Tags v0.5.2, v0.5.3 and v0.6.0 were released in the meantime, so:
@@ -66,3 +75,25 @@ Each plugin tag gets a post on summercms.io/changelog/plugins the same day.
| Step | Repository | Action | Result |
|------|------------|--------|--------|
| 0 | all | pre-checks | step 0 done: `gofmt -w` (toolchain go1.27.2) on 15 framework files (several unformatted since v0.6.0), commit 6d14f71 `style: gofmt`, `go build`, `go vet`, `go test -short ./...`, `summer docs:build --check` green; sm-journal-plugin `gofmt -w` controllers/api/posts.go and classes/blog_editor_test.go, commit b8d98ce `style: gofmt`; sitemap and seo `gofmt -l` clean. `PHASE33_REQUIRE_DOCKER=1 scripts/check-phase33.sh --all` exit 0, "Phase 33 gate passed" (self-test, go, plugins, layers, consumers, admin, docs, marker, docker, additive, compat; compat refused sm-feedback, sm-presentations and sm-quizzes at HEAD and at the base alike, as before). Every repository on its default branch, 0 behind origin, its newest tag an ancestor of HEAD. All five app patches pass `git apply --check` on the app HEADs |
| 1 | summercms.go | framework v0.6.1 | step 1 done: annotated tag v0.6.1 (tag object 5db8c61, commit 6d14f71, contains v0.6.0); `git push origin master` 76288cd..6d14f71 (fast-forward, 0 behind after fetch); `git push origin v0.6.1` new tag; `git ls-remote --tags origin v0.6.1` prints 5db8c61. TAG ../summercms.go v0.6.1 |
| 2 | sm-journal-plugin | v0.4.0 | step 2 done: `GOWORK=off GOPRIVATE=git.golem15.com/* go get git.golem15.com/golem15/summercms@v0.6.1` (v0.6.0 => v0.6.1; go.sum unchanged, the module keeps its `replace => ../summercms.go` as at v0.3.1; tracked go.work unchanged since v0.3.1); `summer plugin:manifest` (framework: v0.6.1), `--check` up to date; README dependency line already v0.6.1; `GOWORK=off go build ./... && go vet ./... && go test -short ./...` green; commit 6823dcc `chore: require SummerCMS v0.6.1` (go.mod, plugin.yaml) after b8d98ce `style: gofmt`; annotated tag v0.4.0 (tag object 48aa3ff, commit 6823dcc, contains v0.3.1); `git push origin main` f7bfb33..6823dcc; `git push origin v0.4.0`; ls-remote prints 48aa3ff. TAG ../sm-journal-plugin v0.4.0 |
| 3 | sm-sitemap-plugin | v0.2.0 | step 3 done: `go get git.golem15.com/golem15/summercms@v0.6.1` (GOWORK=off, v0.6.0 => v0.6.1, replace => ../summercms.go kept as at v0.1.2), `summer plugin:manifest` (framework: v0.6.1, `--check` ok), README dependency line (dropped "Until v0.6.1 is tagged…"); `GOWORK=off go build && go vet && go test -short ./...` green; commit fdbe593 `chore: require SummerCMS v0.6.1` (go.mod, plugin.yaml, README.md); annotated tag v0.2.0 (tag object 1188efd, commit fdbe593, contains v0.1.2); `git push origin main` 049f3ee..fdbe593; `git push origin v0.2.0`; ls-remote prints 1188efd. TAG ../sm-sitemap-plugin v0.2.0 |
| 4 | sm-seo-plugin | v0.2.0 | step 4 done: `GOWORK=off go get git.golem15.com/golem15/summercms@v0.6.1 git.golem15.com/golem15/sm-sitemap-plugin@v0.2.0` (sitemap fetched from the pushed tag) and `go mod tidy` (go.sum: v0.2.0 in, v0.1.2 out); `summer plugin:manifest` (framework v0.6.1, golem15.sitemap v0.2.0, `--check` ok); README dependency lines (v0.6.1, sm-sitemap-plugin v0.2.0) and the go.mod/go.work replace sentence corrected; `GOWORK=off go build ./... && go vet ./... && go test -short ./...` green (the GOWORK=off build failed before on v0.1.2's missing contract package); commit 22f108b `chore: require SummerCMS v0.6.1 and sm-sitemap-plugin v0.2.0` (go.mod, go.sum, plugin.yaml, README.md); annotated tag v0.2.0 (tag object adda8a9, commit 22f108b, contains v0.1.1); `git push origin main` 55f5e5d..22f108b; `git push origin v0.2.0`; ls-remote prints adda8a9. TAG ../sm-seo-plugin v0.2.0 |
| 5 | vue-seo-layer | v0.2.0 | step 5 done: package.json version 0.2.0 (bumped earlier), tree clean, layers stage of the gate green; annotated tag v0.2.0 (tag object b69647f, commit 3868f3d, contains v0.1.1); `git push origin main` 7d52c5d..3868f3d; `git push origin v0.2.0`; ls-remote prints b69647f. TAG ../vue-seo-layer v0.2.0 |
| 6 | vue-journal-layer, vue-menu-layer, vue-faq-layer | link: swap and tags | step 6 done (tags), check failed: `"vue-seo-layer": "link:../vue-seo-layer"` replaced by `git+https://git.golem15.com/golem15/vue-seo-layer.git#v0.2.0` in each package.json, `pnpm install` (lockfile pins 3868f3d); `check-git-install.sh --check-links vue-seo-layer vue-journal-layer vue-menu-layer vue-faq-layer` exit 0 ("no local dependencies"); `npm run test` journal 202/0, menu 24/0, faq 19/0 and `build:playground` green in each. Commits `chore: pin vue-seo-layer v0.2.0` (package.json, pnpm-lock.yaml): vue-journal-layer 0a77e6e, vue-menu-layer c605384, vue-faq-layer 9cc7f91. Annotated tags: vue-journal-layer v0.8.0 (tag object 7d93f06, commit 0a77e6e, contains v0.7.1), vue-menu-layer v0.5.0 (7e90962, commit c605384, contains v0.4.0), vue-faq-layer v0.5.0 (cae1502, commit 9cc7f91, contains v0.4.0); main pushed (1dd3176..0a77e6e, ef3a090..c605384, 1f23340..9cc7f91) and the tags pushed, ls-remote prints each. TAG ../vue-journal-layer v0.8.0 TAG ../vue-menu-layer v0.5.0 TAG ../vue-faq-layer v0.5.0 |
| 6b | vue-journal-layer | `check-git-install.sh v0.8.0` | **FAILED, release stopped here.** `pnpm install` in the scratch app ends `ERR_PNPM_EXOTIC_SUBDEP: Exotic dependency "vue-seo-layer" (resolved via git-repository) is not allowed in subdependencies when blockExoticSubdeps is enabled` (pnpm 12.14.0 default). Reproduced in a scratch app that also lists vue-seo-layer#v0.2.0 directly: same error. So every site app that installs vue-journal-layer v0.8.0, vue-menu-layer v0.5.0 or vue-faq-layer v0.5.0 with pnpm 12 defaults fails to install. 33-12/33-13 never saw it (pnpm `overrides` with `link:`). `blockExoticSubdeps: false` in the app's pnpm-workspace.yaml makes the install pass (lockfile-only probe). The established convention for a layer on a layer (vue-chatvideo-layer → vue-chat-layer) is `peerDependencies: "^0.1.0"` plus a `devDependencies` git pin, with the app listing both layers directly, which avoids an exotic subdependency. Decision needed (see 33-14 report): (A) keep the tags and set `blockExoticSubdeps: false` in each app (turns off a pnpm supply-chain guard for all transitive deps), or (B) patch releases vue-journal-layer v0.8.1, vue-menu-layer v0.5.1, vue-faq-layer v0.5.1 with vue-seo-layer as a `^0.2.0` peer and git devDependency (apps add vue-seo-layer#v0.2.0 directly; check-git-install's scratch app lists it too). Pushed tags are not moved or deleted. Not started: app pins and patches, changelog posts, deploys |
| 6c | — | checkpoint answer (Jakub, 2026-11-05) | Layer dependency: option B (patch releases vue-journal-layer v0.8.1, vue-menu-layer v0.5.1, vue-faq-layer v0.5.1 with vue-seo-layer as a `^0.2.0` peer and a git devDependency; apps list vue-seo-layer#v0.2.0 directly). Changelog posts: publish now, before the layer fix |
| 8 | sm-summercmsio-app | changelog posts | step 8 done: `scripts/changelog-post.py publish` with the 33-14 notes (the `Excerpt:` line stripped and passed as `--excerpt`): framework v0.6.1 id=66 https://summercms.io/changelog/summercms-0-6-1 (published_at 2026-11-05T00:17:50Z, the tag's date); sm-sitemap-plugin v0.2.0 id=67 https://summercms.io/changelog/sm-sitemap-plugin-0-2-0; sm-seo-plugin v0.2.0 id=68 https://summercms.io/changelog/sm-seo-plugin-0-2-0; sm-journal-plugin v0.4.0 id=69 https://summercms.io/changelog/sm-journal-plugin-0-4-0 (posted from a detached worktree at v0.4.0, because the live checkout has another session's untracked go.work.sum and the script requires a clean tree; worktree removed). Each `plugin.yaml matches the sources`. All four URLs answer 200; the three plugin posts are listed on /changelog/plugins. No registry token file, so the ingest request was skipped (hourly ingest picks the tags up). The journal token was read by the script only, never printed |
| 6d | vue-journal-layer, vue-menu-layer, vue-faq-layer | patch releases (option B) | step 6d done: vue-seo-layer moved from `dependencies` to `peerDependencies: "^0.2.0"` plus `devDependencies: "git+https://git.golem15.com/golem15/vue-seo-layer.git#v0.2.0"` (the vue-chatvideo-layer convention, checked in that repo), versions 0.8.1 / 0.5.1 / 0.5.1, `pnpm install` (lockfile pins 3868f3d as a dev dependency); READMEs: the install line lists vue-seo-layer#v0.2.0 and the layer tag, a peer-dependency paragraph, an upgrade bullet ("use 0.8.1 / 0.5.1"), the Releasing steps; vue-journal-layer `scripts/check-git-install.sh`: the scratch app lists vue-seo-layer at the tag's devDependencies pin (`SEO_LAYER_SPEC` overrides; a tag without the peer gets none, so v0.8.0 still fails as it should), `--self-test` ok. `--check-links` over the four layers exit 0; `check-phase33.sh --layers` exit 0 (seo 156, journal 202, menu 24, faq 19 TAP pass, 0 fail; four playground builds; smokes; check-git-install self-test). Commits `fix: vue-seo-layer as a peer dependency`: vue-journal-layer f5dc9b2, vue-menu-layer dc38f79, vue-faq-layer a092363. Annotated tags vue-journal-layer v0.8.1 (tag object 5c26b5d, contains v0.8.0), vue-menu-layer v0.5.1 (47b022e, contains v0.5.0), vue-faq-layer v0.5.1 (8d46b31, contains v0.5.0); main pushed (0a77e6e..f5dc9b2, c605384..dc38f79, 9cc7f91..a092363) and the tags pushed; ls-remote prints each. v0.8.0 and v0.5.0 stay as published. `check-git-install.sh v0.8.1` (run from the scratchpad) ends `smoke-ssr: ok (89 checks)`, `check-git-install: ok v0.8.1 f5dc9b2`. Scratch app with pnpm 12.14.0 defaults listing nuxt, vue, vue-seo-layer#v0.2.0, vue-journal-layer#v0.8.1, vue-menu-layer#v0.5.1 and vue-faq-layer#v0.5.1, extending the three: `pnpm install` ok (one vue-seo-layer in the store), `nuxt build` ok. Release-note drafts 33-14-notes-vue-{journal,menu,faq}-layer-*.md name v0.8.1 / v0.5.1 as the versions to install. TAG ../vue-journal-layer v0.8.1 TAG ../vue-menu-layer v0.5.1 TAG ../vue-faq-layer v0.5.1 |
| 7a | sm-summercmsio-app | pins, patch, nodynamic | step 7a done: c96108d `chore: require SummerCMS v0.6.1` (go.mod, go.sum; tidy pruned indirects the framework no longer needs); a40076c `chore: bump journal to v0.4.0` (plugins/golem15/journal 5b38a3b → 6823dcc at v0.4.0, require v0.4.0, gen2brain/webp and purego indirect); vue-summercmsio-app 16ab519 `chore: vue-journal-layer v0.8.1 with vue-seo-layer v0.2.0` (33-12-vue-summercmsio-app.patch applied: changelog `seo: { cms: false, htmlSitemap: false }` and 16 expectation lines; package.json pins; lockfile), pushed f36cbf1..16ab519, then pointer 2e2b881; 90eb7bc `chore: regenerate plugins.gen.go (SummerCMS v0.6.1, journal v0.4.0)`; 395ed78 `build: static binary with -tags nodynamic` (scripts/build.sh both go builds, summer.yaml `build.tags: [nodynamic]`, DEPLOY.md Binary row "static" with the reason). The 33-12-sm-summercmsio-app.patch is the empty note (nothing to apply). Checks: `pnpm test` 83/0 (17 tests read the build output and fail before a build; green after it), build:changelog, `test:changelog` smoke-ssr ok (89 checks), `generate`, `test:marketplace` ok (30 checks); `go vet`, `go test ./...` green. Release build in a clean worktree of 395ed78 with submodules from origin (the live checkout has an untracked self-named binary that `require_clean` refuses; not touched): `scripts/build.sh` → "release v0.6.1", `bin/summercms-io` statically linked, `-tags=nodynamic`; `scripts/smoke.sh` ok; `check-deploy.sh` ok. `git push origin master` ca06049..395ed78 |
| 7b | sm-demo-app | pins, patches, nodynamic | step 7b done: 6cc710e `chore: require SummerCMS v0.6.1`; 51b1d76 `chore: bump journal to v0.4.0`, ca29cd6 `chore: bump sitemap to v0.2.0`, 8113bc3 `chore: bump seo to v0.2.0` (each: submodule at the tag, `GOWORK=off go get` + `go mod tidy`); vue-demo-app fe5d38d `feat: SEO from the CMS and Polish under /pl/` (33-12-vue-demo-app.patch then 33-14-vue-demo-app-locale.patch, pins vue-journal-layer v0.8.1, vue-menu-layer v0.5.1, vue-faq-layer v0.5.1, vue-seo-layer v0.2.0; `pnpm build` ok (build guard passes), `pnpm test` 225/225), pushed 9a12701..fe5d38d; 6686216 pointer bump; 49ae08d (33-12-sm-demo-app.patch then 33-14-sm-demo-app-locale.patch, 18 paths; DEPLOY "After" no longer removes `/subscriptions` by hand: G1 leaves it out as noindex, per Jakub); cc1d71c plugins.gen.go; d2bd3ec `build: static binary with -tags nodynamic` (GO_TAGS and summer.yaml `summercms_mcp,nodynamic`, dev.sh, DEPLOY Binary row "static" with the reason); da03c06 roadmap snapshot (framework 143b4db). Checks: `go vet`, `go test -short`, `go test -tags summercms_mcp -count=1 ./...` (Docker) green; `check-pins` ok (25 modules); `scripts/build.sh` release in the clean live checkout "build: ok release 31f99588d1c9", `bin/demo` statically linked, journal v0.4.0, seo v0.2.0, sitemap v0.2.0, summercms v0.6.1, `-tags=summercms_mcp,nodynamic`; `scripts/smoke.sh bin/demo` ok; `check-deploy.sh` ok. (A scratch worktree build failed on worktree submodule cloning, not on the code; removed.) `git push origin master` da481c9..da03c06. Rehearsal databases: the demo's smoke and tests use fresh databases (migrate + demo:seed), no dump involved |
| 7c | sm-grzybyfunkcjonalne-app | pins, patches, nodynamic | step 7c done: 65d64f6 `chore: require SummerCMS v0.6.1` (go.mod and plugins/grzyby/go.mod); 7f57068 journal v0.4.0, aa1b925 sitemap v0.2.0, c60731b seo v0.2.0 (submodule at the tag, require bumped, tidy; the seo submodule was already mounted at v0.1.1); vue-grzybyfunkcjonalne-app 0771c14 (33-13-vue-grzybyfunkcjonalne-app.patch, pins vue-journal-layer v0.8.1, vue-menu-layer v0.5.1, vue-faq-layer v0.5.1, vue-seo-layer v0.2.0; `pnpm test` 30/0 after the build (3 tests read the build output), `pnpm build`, `smoke:ssr` ok (67 checks), `smoke:ga` ok), pushed e45ffe8..0771c14; 2628e38 pointer; 9eb921b (33-13-sm-grzybyfunkcjonalne-app.patch, 25 paths; its plugins/grzyby/go.mod hunk conflicted only with the v0.6.1 bump and was applied by hand: sitemap require + replace; the DEPLOY Binary row says static with -tags nodynamic instead of "dynamically linked"); bcb4be1 `build: static binary with -tags nodynamic` (build.sh vet and build `-tags summercms_mcp,nodynamic`, summer.yaml); 745b549 plugins.gen.go; 75736b4 `fix(deploy): check-deploy requires the nodynamic build tag` (check-deploy.sh looked for the old exact tag list). Checks: `go vet`, `go test ./... ./plugins/grzyby/...`, `go test -tags summercms_mcp ./...` (Docker) green; `scripts/build.sh` (framework working tree = v0.6.1 code, no non-planning diff) → `bin/grzybyfunkcjonalne` statically linked, summercms v0.6.1, `-tags=summercms_mcp,nodynamic`; `check-deploy.sh` ok; full `scripts/smoke.sh` rehearsal on a fresh throwaway database (migrations including the edited 202610280002, the PHP export, the release steps 4-11) `smoke: ok (128 urls)` (every urls.txt line on the tagged build), then `smoke-seo: ok` (index of 5 files, posts 63, categories 8, authors 1, pages 4). `git push origin master` 35d3664..75736b4 |
| 7d | sm-bm-app | push | step 7d done: the frontend build (`npm ci && npm run build` in frontend/, into plugins/jz/bm/public) adds the robots meta to index.html and robots.txt (assets unchanged); jz.bm a27a162 `build: robots meta and robots.txt (noindex, Disallow)`, pushed a075963..a27a162 (with the earlier unpushed 0dd0185 of another session, which sm-bm-app 9dd0fe4 points at); sm-bm-app 43f2fc9 `chore: bump jz.bm (robots meta and robots.txt in the frontend build)`; `scripts/check-noindex.sh` ok; `go vet`, `go test -short` green; `scripts/build.sh` → "framework v0.6.0 @ c8241c8, app 43f2fc9", statically linked (bm mounts no Journal; it stays on v0.6.0). `git push origin master` pushed 552cdce, c2a7823, 9dd0fe4 (other sessions, approved), bd7ee84 and 43f2fc9 |
| 9a | summercms.io (rome) | deploy | step 9a done: release build of sm-summercmsio-app 395ed78 (clean worktree, static, release v0.6.1, sha256 dfd70d65…); on rome `pg_dump -Fc summercms_io` → /var/backups/summercms/summercms_io-pre-v0.6.1-2026-11-05.dump (root, 0700 dir); upload per DEPLOY.md (config/, bin/summercms-io.new (sha256 matches), changelog/.output.new); `./bin/summercms-io.new migrate` "golem15.journal: 2 applied"; previous binary kept as bin/summercms-io.prev and changelog/.output.prev; swap; `supervisorctl restart summercms-io summercms-io-changelog` both RUNNING; loopback 200 on :8095/, :3095/changelog, :8095/api/registry/v1/plugins, :3095/marketplace. `journal:image-variants`: "Every featured image has its variants." Public checks: 200 for /, /docs/, /changelog, /changelog/plugins, /changelog/rss.xml, the v0.6.1 and journal v0.4.0 posts, /_journal/api/v1/posts, /api/registry/v1/plugins, /marketplace; /backend 404; no purge key in the page; one canonical, one ld+json on a post; /changelog/sitemap 404 (htmlSitemap off) |
| 9b | demo.summercms.io (rome) | deploy | step 9b done: `pg_dump -Fc summercms_demo` → /var/backups/summercms/summercms_demo-pre-v0.6.1-2026-11-05.dump; .env and site.env copied to /root/*.bak-pre-seo; DEPLOY "Before the first release with Phase 33" block as root (0 SEO keys before; 2 tokens added to .env, 4 NUXT_SEO_ lines to site.env, values never printed; NUXT_PUBLIC_SITE_URL/SITEMAP_URL dropped). Upload (config/, bin/demo.new sha256 31f99588… = local release build of da03c06, site/.output.new, /tmp/seo-pages.csv, /tmp/demo.summercms.io.conf). `bin/demo.new migrate`: journal 2, sitemap 5, seo 8 applied; `demo:seed` (decks updated, the rest exists); bin/demo.prev and site/.output.prev kept; swap; restart summercms-demo and summercms-demo-site (RUNNING); `websockets:health` "Configuration OK". Vhost: backup /root/demo.summercms.io.nginx.bak-2026-11-05, install, `nginx -t` ok, reload. Site log: `[vue-seo-layer] route report: 7 routes and 20 noindex paths sent` (and the known G2 journal-tag drift line). "After" block as root, with the amended list: extra_urls before `/`, `/blog`, `/faq`, `/subscriptions`; PUT keeps only `/subscriptions` (200); `sitemap:rebuild` 22 addresses in 4 files; seo-pages.csv import applied (changed 2, refused 0). **G1 live: `/subscriptions` is left out without manual removal** (Settings › Sitemaps left_out `{"noindex":1}`; sitemap-pages-1.xml lists /, /blog, /chat, /contact, /faq, /forum, /quizzes only), so no manual removal. `journal:image-variants`: "Every featured image has its variants." `scripts/check-live.sh https://demo.summercms.io`: check-live: ok. `SMOKE_SEO_STRICT=1 scripts/smoke-seo.sh https://demo.summercms.io` over an SSH tunnel (admin password in a 0600 scratch file, deleted after; tunnel closed): smoke-seo: ok (5 hreflang links on a post, /pl/ alternate 200, 22 sitemap addresses, 0 not 200) |
| 9c | bm.jakubzych.com (rome) | deploy | step 9c done: per the DEPLOY.md "Live install" note (/home/debian/bm, user debian): `pg_dump -Fc bm` → /var/backups/summercms/bm-pre-noindex-2026-11-05.dump; release build of 43f2fc9 (sha256 4712a4cb…, static, framework v0.6.0) uploaded as bin/bm.new with config/ and data/*.json; `migrate` "Nothing to migrate"; bin/bm.prev kept; swap; `supervisorctl restart bm` RUNNING; loopback 200. Live vhost: dated backup /root/bm.jakubzych.com.nginx.bak-2026-11-05, `add_header X-Robots-Tag "noindex, nofollow" always;` added to both server blocks and to the two locations with their own add_header (`= /prezentacje/AW_tematy-prezentacji.html` and also `^~ /pliki/`, which the repository file does not have), `nginx -t` ok, reload. Verify: X-Robots-Tag noindex, nofollow on https /, on the http 301, on the topics page and on /pliki/; /robots.txt `Disallow: /`; the SPA carries the robots meta; /_bm/api/v1/dashboard 401; /bmadmin 200 |
| 9d | grzybyfunkcjonalne.pl (alexandria, production) | deploy, DEPLOY.md "SEO pages and sitemaps (Phase 33)" steps 1-12 | steps 1-11 done, **step 12 smoke: 1 of 148 lines failed (see 9e); stopped, no rollback**. Pre-check: the full local `scripts/smoke.sh` on the tagged build passed (step 7c, `smoke: ok (128 urls)`). 1: root `pg_dump -Fc grzybyfunkcjonalne` → /root/grzybyfunkcjonalne-pre-seo-2026-11-05.dump (58 TABLE DATA entries), copies go/bin/grzybyfunkcjonalne.pre-seo-2026-11-05, nuxt/.output.prev-2026-11-05, go/.env.pre-seo-2026-11-05, nuxt/.env.pre-seo-2026-11-05, vhost /root/grzybyfunkcjonalne.pl.summercms.bak-2026-11-05. 2: upload (binary as .new, sha256 4ecc24a8… matches the local build; config/, scripts/, Nuxt build to nuxt/.output.new instead of over the running .output; deploy/ incl. seo-pages.csv and both vhosts). 3: go/.env `SUMMER_GOLEM15__SITEMAP__SITE_URL` = the SEO site URL; nuxt/.env `NUXT_SEO_API_BASE`, `NUXT_SEO_BACKEND_BASE`; both 404 tokens present (checked by name only, values never printed). 4: `migrate` with the new binary: journal 2, sitemap 5, seo 8; then bin swap (.prev kept). 5: SELECT showed `en` already disabled (en f f, pl t t); the UPDATE ran (2 rows, no change). 6: `grzyby:seo-settings --dry-run` listed exactly settings.page_title_suffix and the two journal-author templates; applied (3 changed). 7: Nuxt build swapped in, both programs restarted (RUNNING), Nuxt log `[vue-seo-layer] route report: 4 routes and 1 noindex paths sent` (plus the known G2 journal-tag drift line); new production vhost installed (sha256 157a5e0b… = deploy file; the live file had matched the previous repository file), `nginx -t` ok, reload. 8-10 through the management API with a temporary `*` token (created for info@golem15.com, never printed, revoked, id 2): /blog → Artykuły, /trwaja-prace → Trwają prace; seo-pages.csv preview changed 4 refused 0, applied; Additional addresses ["/","/blog"] → []. 11: `sitemap:rebuild` 74 addresses; `journal:image-variants` checked 95 featured images, wrote 285 variants, skipped 0 |
| 9e | grzybyfunkcjonalne.pl | step 12 smoke | On the server: `scripts/smoke.sh --url https://grzybyfunkcjonalne.pl --also scripts/urls-production.txt` → `smoke: 1 of 148 urls failed`: `200 /autor/admin contains=<title>Wpisy autora admin | Grzyby Funkcjonalne</title>`; the page answers 200 with `<title>Wpisy autora Dawid P. | Grzyby Funkcjonalne</title>`. Cause: the urls.txt line added by the 33-13 patch assumes the rehearsal's author name ("admin", from `--author-login admin`); in production the author's name is "Dawid P." (also on every post page), and the title follows the applied template `Wpisy autora %title% | %site%`, the PHP site's format. A test expectation bound to fixture data, not a site fault. `scripts/smoke-seo.sh https://grzybyfunkcjonalne.pl` ok; `check-deploy.sh --live` ok. **Not rolled back** (the site is healthy; rollback materials in 9d stay ready); the 404-log cleanup of the smoke entries and the remaining steps wait for Jakub's decision. Read-only checklist (33-13-deploy-log.md): item 1 ok (index of posts, categories, authors, pages, images; posts 62, each once, all with lastmod, no /en/, no hreflang; /sitemap.xsl 404); item 2 ok (CMS title, one canonical on the apex, `index, follow`, one JSON-LD script, no hreflang="en", breadcrumbs Strona główna › Chaga); item 4 partly (HTML sitemap /mapa-strony 200, footer link present, Additional addresses empty, IndexNow not enabled); item 8: libwebp.so.7 is installed, but the binary is built with nodynamic, so the built-in encoder runs. http and www answer 301 to the apex; /backend 404; /gfadmin 200. Note: posts now send `X-Robots-Tag: index, follow` (vue-seo-layer), where the cutover check expected no header |
| 10 | summercms.go | plan verify | The plan's tag check: every TAG line's tag is on its origin ("tags-ok", 7 TAG lines covering 11 tags); no content layer package.json has `link:`. `check-phase33.sh --compat --consumers`: compat PASS (sm-feedback, sm-presentations and sm-quizzes refused at HEAD and base as before); consumers FAIL with `refuse: 33-12-sm-demo-app.patch does not apply to …/sm-demo-app`. That is expected after the release: the stage checks the release patches against unpatched app HEADs, and sm-demo-app now carries the patch (its new files are present). The apps' own builds, tests and smokes ran directly in steps 7a-7c. The consumers stage needs a post-release mode (or retirement) in a follow-up |
| 9f | sm-grzybyfunkcjonalne-app, grzybyfunkcjonalne.pl | Jakub's answer A: keep the deploy, fix the check | step 9f done: scripts/urls.txt `/autor/admin` now checks only the fixed parts of the title (`contains=<title>Wpisy autora` and `contains=| Grzyby Funkcjonalne</title>`, with a comment on why); local full rehearsal `smoke: ok (129 urls)`, `smoke-seo: ok`; commit 0554f3e `fix(smoke): check the author page title without the fixture's author name`, pushed 75736b4..0554f3e; scripts/ rsynced to the server. Production smoke rerun exactly as before (`scripts/smoke.sh --url https://grzybyfunkcjonalne.pl --also scripts/urls-production.txt`): `smoke: ok (149 urls)`. 404 log: the 14 entries first seen since the deploy began (01:12Z onwards, all the smoke's and the checks' negative cases: /sitemap.xsl, /sitemap-tags-1.xml, /blog?page=7, /blog?page=abc, /chaga?page=2, /szukaj?q=cordyceps&page=999, /404, /error, /nieistnieje, /rss, /feed, /blog/badania-nad-cordycepsem, /en/blog, /autor/nobody) deleted through `DELETE /_seo/api/v1/notfound/{id}` (each 200) with a temporary `*` token (never printed, revoked, ids 3 and 4); 0 entries from today remain; older entries (bot probes before the release) left alone. Step 12 of the grzyby deploy is done except the Search Console resubmit (Jakub) |

View File

@@ -0,0 +1,130 @@
---
phase: "34"
slug: "plugin-marketplace"
status: verified
# threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
threats_open: 0
asvs_level: 1
created: "2026-11-05"
---
# Phase 34 — Security
> Per-phase security contract: threat register, accepted risks, and audit trail. Evidence roots: FW = `summercms.go` (master 7b8d205), SITE = `../sm-summercmsio-app/plugins/golem15/summercms` (v0.1.0, 0b3fbf4), APP = `../sm-summercmsio-app`, VUE = `../sm-summercmsio-app/vue-summercmsio-app`. T-34-SC is declared in all six plans and counted once (37 unique threats).
---
## Trust Boundaries
| Boundary | Description | Data Crossing |
|----------|-------------|---------------|
| plugin source → kiosk reader | plugin.go, go.mod and README.md of any directory the CLI is pointed at | Go source, module metadata (high) |
| CLI args → go/git subprocesses | dir and module paths reach `go mod edit`, `go list`, `git describe` | paths, module paths (high) |
| plugin.yaml (module cache / submodule) → summer build | third-party text baked into generated Go source | manifest strings (high) |
| plugin repository → registry and installers | plugin.yaml in a tag is read by summercms.io and `summer plugin:install` | manifest (high) |
| curated git repository → ingester | repository content controlled by plugin maintainers | git objects, README, manifests (high) |
| ingested README → marketplace HTML | third-party markdown rendered on summercms.io | HTML (high) |
| public internet → GET /api/registry/v1 | anonymous, cross-origin readers | listing JSON (low) |
| release script (token) → POST /api/registry/v1/ingest | authenticated, scoped | API token, repo id (high) |
| summercms.io admin → presentation fields and repository URLs | trusted administrators behind the SSH tunnel | URLs, text (medium) |
| registry JSON → CLI → go/git | module paths, versions and repository URLs from a registry | install plan (high) |
| user-supplied git URL → git | private or third-party repositories | URL (high) |
| third-party plugin code → app binary | compiled in after confirmation | Go code (high) |
| CLI → app directory | summer.yaml, go.mod, go.work, .gitmodules, plugins/ | app files (medium) |
| browser (admin SPA) → cabana /plugins endpoints | authenticated administrators | installed list, registry data (medium) |
| cabana → registry | outbound call to an operator-configured URL | registry JSON (medium) |
| registry JSON → admin UI | third-party text shown to administrators | names, descriptions, icons (medium) |
| developer workstation → shared remotes | pushes and tags (user-gated) | commits, tags (medium) |
| tests → developer environment / gate script → sibling repositories | module cache, sibling checkouts, Docker; read-only checks in other repos | test state (low) |
---
## Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation | Status |
|-----------|----------|-----------|----------|-------------|------------|--------|
| T-34-01 | Elevation of privilege | kiosk.ReadIdentity | high | mitigate | FW/modules/kiosk/identity.go:229 AST-only `parser.ParseFile`; `str()` :157-189 accepts constants only; only `go list -m`/`mod download`/`mod edit` run. Test manifest_smoke_test.go:172 | closed |
| T-34-02 | Tampering | exec of go/git with paths/modules | high | mitigate | no shell (derive.go:193-212, plugindirs.go:64,292,335); `--` before positionals (identity.go:443,487; plugindirs.go:63); leading "-" refused (build/manifest.go:497-503, kiosk/manifest.go:145-150) | closed |
| T-34-03 | Tampering | plugin.yaml text in plugins.gen.go | high | mitigate | `strconv.Quote` on every string (build.go:175-251), `format.Source` :254-259; malformed manifest ignored with warning (plugindirs.go:216-236). Test plugininfo_smoke_test.go:142 | closed |
| T-34-04 | Information disclosure | plugins.gen.go | low | mitigate | party.Info has no Dir (party/info.go:26-34) | closed |
| T-34-05 | Denial of service | summer build | medium | mitigate | resolveBuildMeta never fails, ID-only fallback with warning (plugindirs.go:94-109,183-186; build.go:39-42) | closed |
| T-34-06 | Repudiation | stale plugin.yaml | medium | mitigate | kiosk/check.go:77-91 `bytes.Equal` → StaleError, CheckT :107; `--check` at cmd/summer/main.go:474-478 | closed |
| T-34-SC | Tampering | npm/pip/cargo installs (all plans) | high | accept | AR-34-01 | closed |
| T-34-07 | Tampering | hand-edited/stale plugin.yaml | medium | mitigate | plugin.yaml + manifest_test.go calling `kiosk.CheckT` in all 25 plugin repos and sm-pgstripe-plugin/subscriptions | closed |
| T-34-08 | Spoofing | manifest claiming another module/ID | medium | mitigate | module from go.mod, package from dir, ID from plugin.go (derive.go:75-103); ingester re-checks (SITE/registry/ingest.go:283,315-327) | closed |
| T-34-09 | Tampering | app pointers to unpushed commits | high | mitigate | bump commits are gitlinks only (sm-demo-app 5ec5941, APP 668a773); every target SHA on origin default branch with its release tag | closed |
| T-34-10 | Denial of service | consumers resolving unreleased framework minimum | medium | accept | AR-34-02 | closed |
| T-34-11 | Elevation of privilege | ingester git with repo URLs | high | mitigate | SITE/registry/git.go: no shell :87, `GIT_ALLOW_PROTOCOL=https` :21,:75, no system/global config :76-77, no prompt, throwaway HOME; `--` before URLs (ingest.go:191,229,233); https-without-credentials enforced at every write path (models/repository.go:88-136) | closed |
| T-34-12 | Denial of service | malicious repo content | high | mitigate | bare `--filter=blob:none` clone (ingest.go:229); 64 KiB / 512 KiB read caps via LimitReader; per-command timeouts (git.go:85); `RemoveAll(tmp)`; ≤20 manifests per tag | closed |
| T-34-13 | Tampering (XSS) | README on /marketplace | high | mitigate | `breakwater.Render` + Purify at ingest (ingest.go:478; breakwater.go:90-99); page re-sanitizes before v-html and drops markdown (VUE/…/[name].vue:8,24-35,152); smoke asserts `notcontains=alert(` | closed |
| T-34-14 | Spoofing | repo claiming another plugin's ID/module | high | mitigate | curated repos only; identity check ingest.go:315-327; first-listed owner under advisory lock (:428,:449) + UNIQUE plugin_id index. Test registry_smoke_test.go:562 | closed |
| T-34-15 | Elevation of privilege | POST /api/registry/v1/ingest | high | mitigate | `cabana.ResolveBackend` + `Allows(PermissionIngest)` (SITE/controllers/api/registry.go:132-144); uncurated → 404; scope narrowed (token_scopes.go:22); nginx POST-only, 8k body (APP/deploy/nginx/summercms.io.conf:162-177); 4 KiB body cap | closed |
| T-34-16 | Denial of service | ingest-now flooding | medium | mitigate | `throttle:registry-ingest` 10/min (routes_registry.go:37,60-67); unique job by args (ingest.go:569); ls-remote digest before clone | closed |
| T-34-17 | Information disclosure | open CORS on registry API | low | mitigate | `*` origins, GET/HEAD, no credentials (APP/config/http.yaml:16-21); surf refuses credentials with `*` (cors.go:50-51); wire type has no last_error/enabled | closed |
| T-34-18 | Denial of service | public API abuse | medium | mitigate | `throttle:registry-api` 300/min; Cache-Control/ETag/304 (registry.go:208-231); q ≤100, category regex, escaped LIKE (registry/query.go:24-57) | closed |
| T-34-19 | Information disclosure | release script token | medium | mitigate | `read_secret_file` refuses group/world-readable file, never prints (APP/scripts/changelog-post.py:320-328); no journal-token fallback (:338-343); failures report status only | closed |
| T-34-20 | Tampering | stale manifest in published tag | medium | mitigate | `check_plugin_release` (changelog-post.py:354-380): HEAD exactly the tag, clean tree, `plugin:manifest --check`; called before posting (:428) | closed |
| T-34-21 | Denial of service | jobs never run in prod | medium | mitigate | `work_in_serve: true` (APP/config/queue.yaml:5); hourly `--queue` schedule; DEPLOY.md:89,93 checks; smoke.sh:243-249 | closed |
| T-34-22 | Elevation of privilege | registry strings → go get / git clone | high | mitigate | validateStep: `kiosk.ValidVersion`, validateModulePath, package within module (install.go:576-604), called in plan/apply/update/source; https-only no-userinfo repo URLs (source.go:135-152); `go get --`, git `--`; no shell | closed |
| T-34-23 | Elevation of privilege | ext::/file:: via git URL | high | mitigate | `cliGitProtocols = "https:ssh"` (source.go:26) forced in runCLIGit (:46-53); validateGitURL refuses leading "-", `::`, control chars, other schemes, credentials (:83-131) | closed |
| T-34-24 | Tampering | malicious plugin code compiled in | high | accept | AR-34-03 | closed |
| T-34-25 | Tampering | writes outside app root | medium | mitigate | ValidatePluginID / repoNameRe + `underRoot` before move and `submodule add` (source.go:386-474; scaffold.go:581-590) | closed |
| T-34-26 | Denial of service | slow/hostile registry | medium | mitigate | fetchguard TrustedMode, 4 MiB, 10 s (kiosk/client.go:28-29,84-88); no redirects (fetchguard/fetch.go:112); `--offline` | closed |
| T-34-27 | Spoofing | registry pointing at a different module | medium | mitigate | ingester ties module to repo; CLI re-reads plugin.yaml and go.mod from checkout and refuses mismatch (source.go:445-457) | closed |
| T-34-28 | Tampering | summer.yaml damaged by edit | low | mitigate | appendManifestPlugins re-parses and restores original on mismatch (build/manifest.go:206-252) | closed |
| T-34-29 | Elevation of privilege | GET /plugins, /plugins/marketplace | medium | mitigate | backend group (cabana/http.go:345-346); `pluginsPrincipal` 401/403 on `PermissionViewPlugins` (plugins.go:400-438); in security_coverage_test.go:56-57,312-313 | closed |
| T-34-30 | Information disclosure | installed plugin list | low | mitigate | gated by pluginsPrincipal; party.Info has no path | closed |
| T-34-31 | Denial of service | registry slow/down (admin) | medium | mitigate | cabana/plugins.go:132-140 4 s timeout, TTL cache (5m/15m, 1m failures), 4 concurrent, 256 cap; failure answers 200 `unavailable` | closed |
| T-34-32 | Tampering (XSS) | registry text in SPA | medium | mitigate | PluginsView.vue has no v-html, text interpolation only; icons https-only with `referrerpolicy="no-referrer"`; ID regex (plugins.go:147,472,536) | closed |
| T-34-33 | Server-side request forgery | plugins.registry_url | low | accept | AR-34-04 | closed |
| T-34-34 | Tampering | tests writing into siblings/module cache | medium | mitigate | `t.TempDir()` throughout; temp GOMODCACHE (fixtures_test.go:118-122; derive_test.go:283); no `../sm-*` paths in tests | closed |
| T-34-35 | Repudiation | gate passing on silently skipped tests | medium | mitigate | scripts/check-phase34.sh go test -json detector with required names (:142-300); Docker-not-run fails `--all` (:49-51); self-test plants each failure (:416-504) | closed |
| T-34-36 | Information disclosure | release ledger | low | mitigate | 34-release-log.md contains no token values, secrets or Bearer strings | closed |
*Status: open · closed · open — below high threshold (non-blocking)*
*Severity: critical > high > medium > low — only open threats at or above workflow.security_block_on count toward threats_open*
*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
---
## Accepted Risks Log
| Risk ID | Threat Ref | Rationale | Accepted By | Date |
|---------|------------|-----------|-------------|------|
| AR-34-01 | T-34-SC | No package is installed or added: Go modules already required, no new npm dependency, reka-ui already a dependency. Confirmed: FW go.mod/go.sum/admin package files unchanged v0.5.3→v0.6.0; SITE's new requires are all in FW v0.6.0. | 34-01..06 PLAN | 2026-11-05 |
| AR-34-02 | T-34-10 | Plugins are not tagged until v0.6.0 exists (release order in 34-06's ledger); existing tags are never moved. Confirmed by tag timestamps (framework v0.6.0 before every plugin tag). | 34-02 PLAN | 2026-11-05 |
| AR-34-03 | T-34-24 | Inherent to compiled plugins; every addition is printed and needs confirmation or `--yes` (D-09); sumdb verification stays on (GONOSUMDB/GOSUMDB/GOPRIVATE/GOINSECURE never set in non-test code). | 34-04 PLAN | 2026-11-05 |
| AR-34-04 | T-34-33 | `plugins.registry_url` is an operator-configured trusted setting (fetchguard TrustedMode by design), no redirects, size-capped; administrators cannot change it from the admin. | 34-05 PLAN | 2026-11-05 |
*Accepted risks do not resurface in future audit runs.*
---
## Informational (review Info items, not in the register, non-blocking)
34-REVIEW-FIX covered CR and WR findings only. These remain in the code:
- IN-01 (near T-34-15): the ingest endpoint does not require `Content-Type: application/json` (SITE/controllers/api/registry.go:145-149).
- IN-02 (near T-34-22/26/33): `kiosk.NewClient` accepts `http://` registries without a warning (FW/modules/kiosk/client.go:74-76).
- IN-04 (near T-34-14): plugin ID ownership goes to the first repo and is never released.
- IN-06 (near T-34-13): the marketplace detail page binds `:href` from `plugin.repository` without a scheme check (VUE/changelog/app/pages/marketplace/[vendor]/[name].vue:135); every write path canonicalizes to https, so exploiting it needs a direct database write.
- IN-05, IN-07: the Nitro SWR cache is keyed by query string; the admin loads marketplace icons from third-party hosts.
---
## Security Audit Trail
| Audit Date | Threats Total | Closed | Open | Run By |
|------------|---------------|--------|------|--------|
| 2026-11-05 | 37 | 37 | 0 | msd-security-auditor (ASVS L1, block_on high) |
---
## Sign-Off
- [x] All threats have a disposition (mitigate / accept / transfer)
- [x] Accepted risks documented in Accepted Risks Log
- [x] `threats_open: 0` confirmed
- [x] `status: verified` set in frontmatter
**Approval:** verified 2026-11-05

View File

@@ -0,0 +1,516 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- modules/pact/capabilities.go
- modules/pact/README.md
- modules/postcard/store.go
- modules/postcard/mailer.go
- modules/postcard/templates.go
- modules/postcard/partials.go
- modules/postcard/samples.go
- modules/postcard/editor.go
- modules/postcard/brand.go
- modules/postcard/assets/system.htm
- modules/postcard/assets/minimal.htm
- modules/postcard/assets/sample.htm
- modules/postcard/assets/brand.css.tmpl
- modules/postcard/assets/partials/button.htm
- modules/postcard/assets/partials/panel.htm
- modules/postcard/assets/partials/table.htm
- modules/postcard/assets/partials/subcopy.htm
- modules/postcard/override_smoke_test.go
- modules/postcard/partials_smoke_test.go
- modules/postcard/editor_smoke_test.go
- modules/postcard/brand_smoke_test.go
- modules/postcard/README.md
- modules/lagoon/migrations.go
- modules/lagoon/pending_test.go
- modules/lagoon/README.md
- modules/lagoon/attach/absolute.go
- docs/services/mail.md
- docs/services/storage.md
- docs/plugins/registration.md
- docs/database/migrations.md
autonomous: false
requirements: [D-01, D-04, D-05, D-06, D-07, D-08, D-10, D-11, D-12, D-13, D-14, D-15, D-16, D-17, D-19, D-22, D-23, D-24, D-25]
estimate:
tokens: 170000
raw_tokens: 170000
tasks: 5
confidence: low
must_haves:
truths:
- "A customized row in system_mail_templates changes the subject, body and layout of the mail postcard sends in any process that published a *gorm.DB (serve, queue:work, console), with no cabana activation; postcard reads it once per send through NewDBSource, never from a boot-time snapshot (D-01 as amended by D-22, Claude's Discretion: per-send lookup)"
- "Without a customized row the sent mail is byte-identical to the file version, and an app with no published database or with the mail tables missing still sends the file version and logs a rate-limited warning (D-14, research Pitfall 7)"
- "An override that fails to render or fails the safety checks at send time is logged with component postcard and the file version is sent instead; an override whose layout code resolves to nothing renders with postcard's default layout and a warning (D-14)"
- "A caller's non-empty Message.Subject still wins over an override subject, and Mailer, Message, Catalog.Register, BootPlugin and pact.HasMailTemplates keep their exact signatures (D-04, D-12)"
- "Plugins declare partials through the additive pact.HasMailPartials capability; names must be <plugin>::mail.partials.<name> and map to views/mail/partials/<name>.htm; a foreign namespace, a missing file or a duplicate fails BootPlugin with the dotted name; postcard ships the built-in partials button, panel, table and subcopy and the file layouts default (unchanged), system and minimal (D-08, D-12)"
- "`{{ partial \"button\" \"url\" .Link \"body\" \"Go\" }}` in a Markdown body survives goldmark through per-render nonce tokens swapped after conversion, renders the partial's HTML section in the HTML part and its text section in the text part, and works the same in layouts (D-12)"
- "Template headers may declare `sample.<path> = value` keys (case kept after the prefix); files without them parse exactly as before, and previews and save validation fill every other variable with a visible `[path]` placeholder, including nested fields, if/with blocks and range bodies (D-15, research Pitfall 3)"
- "postcard's exported Editor validates a template, layout or partial draft (parse, test render with samples, the existing script/iframe/object/embed, event-handler and javascript:/vbscript:/data: checks, subject CR/LF, unknown layout or partial, a layout without {{ .Content }}) and reports the failing field and rule; Preview and SendDraft render a draft through the same path as Send (D-13, D-16, D-17)"
- "SyncIndex upserts one index row per file template, layout and partial (code unique), mirrors file content into rows that are not customized, always refreshes file_hash, source and description, never deletes rows and never touches a customized row's override columns; ResetOverride clears the override columns of one row and re-mirrors the file (D-06 as amended by D-23, D-05 locale column)"
- "Every file entry carries a sha256 hash of its CRLF-normalized bytes, so a saved override's base_hash can be compared with the current file_hash (D-07)"
- "With no row in system_mail_brand_settings the layout's brandCss slot holds config mail.brandCss; once the row exists, CompileBrandCSS of its colours replaces it, mail.css is still applied, and layouts get `{{ .logoUrl }}` as an absolute URL built at send time from storage.uploads.public_url or app.url (D-10, D-11, D-19, D-24)"
- "postcard registers no built-in template (D-25)"
prohibitions:
- statement: "pact.HasMailTemplates, postcard.Mailer, postcard.Message, postcard.Catalog.Register and postcard.BootPlugin keep their exact signatures; changes are additive only."
status: unresolved
verification: judgment
- statement: "Existing plugin mail renders byte-identically when no override exists (the default layout file and its output are unchanged)."
status: unresolved
verification: judgment
- statement: "goldmark is not switched to unsafe HTML rendering for mail bodies."
status: unresolved
verification: judgment
- statement: "postcard does not import cabana or lagoon, and no override is cached across sends."
status: unresolved
verification: judgment
- statement: "Framework code, READMEs and docs name no consuming application (neutral names such as acme or blog)."
status: unresolved
verification: judgment
artifacts:
- path: "modules/postcard/store.go"
provides: "Migrations, table constants, OverrideSource, NewDBSource, SyncIndex, ResetOverride"
contains: "func NewDBSource("
- path: "modules/postcard/partials.go"
provides: "partial template func, token swap"
contains: "MAILPARTIAL"
- path: "modules/postcard/samples.go"
provides: "sample.* keys and the placeholder walker"
contains: "text/template/parse"
- path: "modules/postcard/editor.go"
provides: "Editor, EditorFrom, Draft, DraftError, Preview, SendDraft"
contains: "func EditorFrom("
- path: "modules/postcard/brand.go"
provides: "Brand, DefaultBrand, CompileBrandCSS"
contains: "func CompileBrandCSS("
- path: "modules/lagoon/attach/absolute.go"
provides: "config-based absolute public URL"
contains: "func AbsolutePublicURL("
- path: "modules/pact/capabilities.go"
provides: "HasMailPartials, RowStateCustomized, RowStateOutdated"
contains: "type HasMailPartials interface"
- path: "modules/postcard/override_smoke_test.go"
provides: "TestMailOverrideSmoke (tracer)"
contains: "func TestMailOverrideSmoke("
key_links:
- from: "modules/postcard/mailer.go"
to: "modules/postcard/store.go"
via: "Activate installs NewDBSource(app); Send calls source.MailOverrides once per message"
pattern: "NewDBSource\\(app\\)"
- from: "modules/lagoon/migrations.go"
to: "modules/postcard/store.go"
via: "framework migration set summercms.postcard"
pattern: "postcard\\.Migrations"
- from: "modules/postcard/brand.go"
to: "modules/lagoon/attach/absolute.go"
via: "logo URL resolved at send time from config"
pattern: "attach\\.AbsolutePublicURL"
- from: "modules/postcard/mailer.go"
to: "modules/pact/capabilities.go"
via: "BootPlugin type-asserts pact.HasMailPartials next to pact.HasMailTemplates"
pattern: "pact\\.HasMailPartials"
---
## Phase Goal
ROADMAP Goal (not in user-story format; no story is invented): administrators edit every mail the application sends from the admin panel, as in WinterCMS's Mail templates screen. postcard renders the override when one exists, otherwise the plugin's file, so mail that already works keeps working. This plan builds the mail-domain half that every other plan consumes: postcard's database layer, partials, sample values, the draft editor API and Branding, with no admin code (D-01, D-22).
Spec-less probe fallback skipped: Phase 35 has no requirement IDs and no SPEC.md, so this plan set derives must_haves from the ROADMAP goal and CONTEXT decisions D-01..D-25 (a visible choice, not an omission). Prohibitions recalled from CONTEXT and CLAUDE.md are authored descriptor-less above.
<objective>
Give postcard an editable database layer that works in every process that sends mail:
- postcard owns the mail tables and their migrations (a framework set in lagoon.migrationSets) and a per-send override lookup with fallback to the file version (D-22, D-14);
- an additive pact.HasMailPartials capability, built-in partials and layouts, and partial calls that survive Markdown (D-12, D-08);
- `sample.<path>` header keys plus a placeholder walker, file hashes for drift, index-row sync and reset (D-15, D-07, D-23);
- an exported Editor that validates, previews and test-sends drafts through the real render path (D-13, D-16, D-17);
- Branding: compiled brand CSS replacing mail.brandCss once saved, and a logo URL built at send time from config (D-10, D-11, D-24).
Purpose: 35-02 (cabana screens) and 35-03 (admin SPA) are thin over this API; putting the read path in postcard keeps overrides effective in queue:work, where cabana never activates (research Pattern 1).
Output: commits in this repository only, code and its docs together per commit group below. Nothing is pushed or tagged.
**Planner decisions recorded here (confirmed or adjusted at Task 1):**
- **P35-01 schema** (Claude's Discretion; D-07 costly). One gormigrate migration `202611060001_create_system_mail_tables` in `postcard.Migrations`, raw SQL like attach.Migrations, history ID `summercms.postcard`, placed after `summercms.attach` in migrationSets:
- `system_mail_layouts`: id SERIAL PK; code TEXT NOT NULL UNIQUE (file layout: its full name containing `::`; database-only layout: `^[a-z0-9-]+$`); source TEXT NULL (owning plugin ID; NULL marks a database-only layout); name TEXT NOT NULL; content_html, content_text, content_css TEXT NOT NULL DEFAULT ''; is_custom BOOLEAN NOT NULL DEFAULT FALSE (file row: override active; database-only row: always TRUE); file_hash TEXT NULL; base_hash TEXT NULL; customized_at TIMESTAMPTZ NULL; created_at, updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW().
- `system_mail_templates`: id; code UNIQUE; source TEXT NOT NULL; locale TEXT NULL; description TEXT NOT NULL DEFAULT ''; subject, body TEXT NOT NULL DEFAULT ''; layout_id INTEGER NULL REFERENCES system_mail_layouts(id) ON DELETE RESTRICT (index); is_custom, file_hash, base_hash, customized_at, timestamps as above.
- `system_mail_partials`: id; code UNIQUE; source TEXT NOT NULL; name TEXT NOT NULL DEFAULT ''; content_html, content_text; is_custom, file_hash, base_hash, customized_at, timestamps.
- `system_mail_brand_settings`: id INTEGER PRIMARY KEY (the settings singleton, row 1); logo_file_id INTEGER NULL; the 13 colour columns of the UI-SPEC Branding table (body_bg, content_bg, header_color, footer_color, heading_color, text_color, link_color, button_text_color, button_primary_bg, button_positive_bg, button_negative_bg, panel_bg, table_border_color) TEXT NOT NULL DEFAULT ''; timestamps.
- `system_mail_image_library`: id SERIAL PK; timestamps (the attachMany host of the image library, never the Branding row, research anti-pattern).
- "Outdated" means `is_custom AND source IS NOT NULL AND base_hash IS DISTINCT FROM file_hash`. Hash: sha256 hex of the raw file bytes with CRLF normalized to LF.
- **P35-02 partial call syntax** (D-12 costly; the syntax becomes text in plugin files and stored overrides): `{{ partial "button" "url" .Link "body" "Activate" "type" "positive" }}`, a template func `partial(name string, kv ...any)` taking key/value pairs. A bare name resolves to `postcard::mail.partials.<name>`; plugin partials use the full name. Unknown name or an odd kv count is a render error (rule `partial`). Inside a partial, `markdown` renders a string through goldmark with the table extension; `partial` is not available inside a partial. Built-in partials: button (url, body, type primary|positive|negative), panel (body), table (body, a Markdown table), subcopy (body). Built-in layouts: default (byte-identical), system (Winter's "System layout" with the automatic-message footer), minimal; plugin templates reach `system` and `minimal` through a fallback after the plugin's own aliases.
- **P35-03 sample keys** (D-15): dotted INI keys in the existing header, `sample.Name = "Ada"`, `sample.order.code = "ZAM-1"`; the part after `sample.` keeps its case; values are strings. A `[sample]` section is not used because released postcard versions reject section lines.
- **P35-04 layout data**: layout CSS (content_css of an override) is prepended to config mail.css in the existing `css` slot, so a layout that renders `{{ .css }}` picks it up and file layouts (no CSS section) are unchanged; layouts get a new `logoUrl` string key next to Content, Subject, css and brandCss.
- **P35-05 names used by 35-02 and 35-03**: permission codes `system.manage_mail_templates` and `system.manage_mail_layouts` (D-03); controller IDs `summercms.cabana.mailtemplates`, `summercms.cabana.maillayouts`, `summercms.cabana.mailpartials`, `summercms.cabana.mailimages`; row states `customized` and `outdated`; admin routes `POST /mail/preview`, `POST /mail/test-send`, `GET /mail/images`, `GET /mail/images/{id}`, `POST /mail/images`; test send limited to 5 per admin per 10 minutes (research A7); the image picker lists for holders of either mail permission and uploads only for `system.manage_mail_layouts` (D-03 planner's call, UI-SPEC C4).
- **Reset semantics** (D-23 amends D-06): reset clears the override columns of the index row and re-mirrors the file; custom layouts are deleted, never reset.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/35-mail-templates-and-layouts-editor/35-CONTEXT.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-RESEARCH.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-PATTERNS.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md
@CLAUDE.md
<interfaces>
modules/postcard/mailer.go: Message{Template, To, Cc, Bcc, ReplyTo, Vars, Subject}; Mailer interface{ Send(ctx, Message) error } (implemented by outside code: keep it); Options{From, CSS, BrandCSS}; unexported mailer{catalog, driver, opts}; NewMailer(cat, driver, opts) Mailer; Activate[P](app, []P) publishes Mailer; driverFromApp reads mail.driver, mail.from, mail.css, mail.brandCss; BootPlugin[P](app, p) type-asserts pact.HasMailTemplates and the published *mailer, then Catalog.Register; moduleLog = diary.For("postcard").
modules/postcard/templates.go: NewCatalog registers postcard::mail.layouts.default from assets/default.htm; Register(pluginID, fsys, templates, layouts) with assertOwner, assetPath (name -> views/mail/<dots as slashes>.htm), duplicate/missing errors; resolveLayoutLocked (plugin aliases only; "default" reserved); parseTemplateFile (subject, description, layout), parseLayout (header name, text, html); splitEQ normalizes CRLF; parseINI lower-cases keys; render(msg, renderOptions{css, brandCSS}) = execHTML subject (CR/LF refused) -> execHTML body -> goldmark -> validateHTML -> layout text (Content = pre-Markdown body) and HTML (Content, Subject, css, brandCss) -> validateHTML; execHTML/execText use missingkey=zero.
modules/postcard/drivers.go: MemoryDriver{Messages()}, validateRendered(msg, requireFrom).
modules/pact/capabilities.go: HasMailTemplates (~1271, unchanged); RowState consts (~1055); ListRowStates doc says values outside the three constants are dropped.
modules/lagoon/migrations.go: migrationSets (~224) lists {"summercms.attach", "system_files", attach.Migrations} first; modules/lagoon/pending_test.go:349 TestMigrateStatusJSON wantSets.
modules/lagoon/attach: PublicURL(key), PublicURLBase(), PublicPathPrefix() (process globals set by OpenBucket, absent in queue:work), BlobKey(diskName), parsePublicURL(raw), defaultPublicPathPrefix "/storage/uploads", File{ID, DiskName, IsPublic, AttachmentType, Field}.
modules/backpack: app.Publish[T](v), app.Lookup[T]() (T, bool); publishing the same T twice is an error.
Import graph: postcard imports backpack, compass, diary, pact; lagoon will import postcard (party already does); postcard must not import lagoon. Internal postcard tests therefore open Postgres with gorm.io/driver/postgres directly (pgx stdlib, as modules/cabana/auth_test.go adminGorm does) and run postcard.Migrations with gormigrate; they never import lagoon.
</interfaces>
</context>
## Execution units and resume points
- Each task ends with the commit(s) listed below, staged by explicit path (never `-A` or `.`). Other sessions may hold uncommitted `.planning/STATE.md`, `.planning/state.json`, `.planning/G15OFFICE.md`, `examples/hello/plugins.gen.go` or cabana edits; leave them alone. Before editing `modules/postcard`, `modules/pact` or `modules/lagoon`, run `git status --short modules/postcard modules/pact modules/lagoon docs` and stop if another session has uncommitted edits there.
- Resume check: `git log --format=%s -F --grep='<subject>'`; present subjects mean the task is done: re-run its `<verify>` and continue with the next one.
- Docker-backed smoke subtests skip under `-short`; run them without `-short` (Docker is available on this host; if the socket is denied, run through `sudo -u golem` per CLAUDE.md).
| Task | Commit subject | Resume point |
|------|----------------|--------------|
| 1 | none (answer recorded in the SUMMARY) | answer recorded |
| 2 | `feat(postcard): database overrides for mail templates with file fallback` | TestMailOverrideSmoke passes |
| 3 | `feat(postcard): mail partials, built-in layouts and layout and partial overrides` | TestMailPartialsSmoke passes |
| 4 | `feat(postcard): sample values, file hashes, index sync and the draft editor` | TestMailEditorSmoke passes |
| 5 | `feat(attach): absolute public URL from config`, then `feat(postcard): mail branding and the logo URL` | TestMailBrandSmoke passes |
<tasks>
<task type="checkpoint:decision" gate="blocking">
<name>Task 1: Confirm the mail schema, the partial call syntax, the sample keys and the names before any code depends on them</name>
<reversibility rating="one-way">After a release, installs hold rows in system_mail_* and admins and plugins write `{{ partial ... }}` calls and `sample.*` keys into stored overrides and plugin files; renaming a table, column or the call syntax then needs a data migration that rewrites stored bodies.</reversibility>
<decision>Adopt P35-01 (schema), P35-02 (partial syntax and built-ins), P35-03 (sample keys), P35-04 (layout CSS slot and logoUrl) and P35-05 (names, limits, picker upload rule) as written in the objective, or adjust them.</decision>
<context>
CONTEXT leaves table names and schema, the partial call syntax, the built-in set, the D-15 mechanism, the extra predefined layouts and the picker upload permission to the planner. D-22..D-25 (2026-11-06) fixed the ownership (postcard), the index-row model, the logo URL timing and the empty template list, but not these names. 35-02 and 35-03 encode every name fixed here (controller IDs, permission codes, routes, row states, column names in fields.yaml), so this is the only point before all of them. D-03, D-07, D-09 and D-12 are already rated costly by the user and are carried through, not re-asked.
</context>
<options>
<option id="as-planned">
<name>Adopt P35-01..P35-05 as written</name>
<pros>Matches the research recommendation and Winter's table names; the partial syntax is a plain Go template call; sample keys stay readable by released postcard versions</pros>
<cons>Freezes the column and call names now</cons>
</option>
<option id="adjust">
<name>Adopt with the changes Jakub states (table or column names, call syntax, built-in set, limits)</name>
<pros>Names fixed before they become stored data</pros>
<cons>The executor records the adjusted names in the SUMMARY; plans 35-02..35-04 use the SUMMARY's names wherever they differ from their text</cons>
</option>
<option id="sample-capability">
<name>Adopt, but declare sample values through an additive pact capability instead of `sample.*` header keys</name>
<pros>Typed sample values (numbers, lists) instead of strings</pros>
<cons>A second new pact capability to support forever; samples live in Go instead of next to the template text</cons>
</option>
</options>
<resume-signal>Reply "as-planned", "adjust: <changes>" or "sample-capability"</resume-signal>
</task>
<task type="tracer">
<name>Task 2: End-to-end "a customized template row changes the mail a process without cabana sends" — templates only, with the file fallback</name>
<reversibility rating="costly">D-07: the hash columns are part of the override table schema; a later change is a new migration.</reversibility>
<files>modules/postcard/store.go, modules/postcard/mailer.go, modules/postcard/templates.go, modules/postcard/override_smoke_test.go, modules/lagoon/migrations.go, modules/lagoon/pending_test.go, modules/lagoon/README.md, modules/postcard/README.md, docs/services/mail.md, docs/database/migrations.md</files>
<read_first>
- modules/postcard/mailer.go and modules/postcard/templates.go (whole files: Send, Activate, BootPlugin, render)
- modules/postcard/mailer_test.go and modules/postcard/templates_test.go (what byte-identity the existing tests pin)
- modules/lagoon/attach/migrations.go (raw-SQL gormigrate migration to copy)
- modules/lagoon/migrations.go (~200-245 migrationSets) and modules/lagoon/pending_test.go (~330-355)
- modules/cabana/auth_test.go (~321-370 adminGorm: testcontainers postgres:16-alpine, pgx, skip under testing.Short)
- modules/postcard/README.md and docs/services/mail.md (sections to extend)
- .planning/phases/35-mail-templates-and-layouts-editor/35-RESEARCH.md (Pattern 1, Pattern 3, Pitfall 1, Pitfall 7)
</read_first>
<action>
Per D-22, D-14 and D-01 (postcard defines the interface and ships the database-backed implementation), using the Task 1 answer for every name:
- `store.go`: exported constants `TemplatesTable`, `LayoutsTable`, `PartialsTable`, `BrandTable`, `ImageLibraryTable` with the P35-01 names; `Migrations []*gormigrate.Migration` with the single P35-01 migration (create all five tables now, so later tasks add no migration; Rollback drops them in reverse dependency order); `OverrideSource` interface with `MailOverrides(ctx context.Context, template string) (Overrides, error)` where an empty template asks for everything except a template override (the editor uses that in Task 4); `Overrides{Template *TemplateOverride; Layouts map[string]LayoutOverride; Partials map[string]PartialOverride}` (Task 5 adds the `Brand *Brand` field; Task 3 fills Layouts and Partials); `TemplateOverride{Subject, Body, Layout string}` where Layout is a layout code; `LayoutOverride{Name, HTML, Text, CSS string}`; `PartialOverride{HTML, Text string}`; `NewDBSource(app *backpack.App) OverrideSource` that looks up `*gorm.DB` through `app.Lookup` on every call (none published: zero Overrides, nil error) and in this task reads only the template row `WHERE code = ? AND is_custom` plus the code of its layout_id row, inside one read-only query or transaction.
- `mailer.go`: add `Overrides OverrideSource` to Options (additive field) and a `source` field to mailer; NewMailer keeps its signature and takes the source from opts; Activate installs `NewDBSource(app)`. In Send, after the existing checks, ask the source once; a lookup error is logged through moduleLog at warning level at most once per minute per distinct error text and the file version is rendered. Render with the override applied; when that render or validation fails and an override was applied, log at error level with keys template and error and the message "postcard: override failed, sending the file version", then render the file version (D-14). A template override whose layout code resolves to no catalog layout renders with postcard's default layout and logs a warning.
- `templates.go`: refactor render so the file version and an override go through one path (subject source, body, effective layout parts) and the file-only output stays byte-identical; the caller's non-empty Message.Subject still wins over both.
- `modules/lagoon/migrations.go`: add `{"summercms.postcard", "mail", postcard.Migrations}` directly after the attach set; update the set list in `modules/lagoon/pending_test.go` TestMigrateStatusJSON to match.
- `override_smoke_test.go` (package postcard, so it may type-assert the published *mailer and read its MemoryDriver): `TestMailOverrideSmoke`, skipped under testing.Short, starts postgres:16-alpine with testcontainers (pattern of cabana adminGorm), opens GORM with gorm.io/driver/postgres over the pgx stdlib connection, runs Migrations with gormigrate, publishes the *gorm.DB on a backpack.App, calls Activate and BootPlugin for a fixture plugin (fstest.MapFS with `acme.blog::mail.welcome` and a layout alias), and has subtests `override` (an is_custom row's subject and body are sent), `file` (no row: output equals a NewMailer without a source), `fallback` (an override body that fails at runtime, such as a call on a missing nested key, sends the file version and logs the error message), `caller_subject`, `missing_table` (table dropped: file version, warning logged) and `no_db` (app without a published DB: file version).
- Docs in the same commit: postcard README (Overview sentence, Features bullet "database overrides", Usage "Overrides from the admin" with the precedence caller Subject > override > file and the fallback rule, API reference rows for every new identifier, Dependencies: gorm and gormigrate), docs/services/mail.md new section "Overrides from the admin", lagoon README framework-set sentence naming `postcard.Migrations` under the `summercms.postcard` history, and docs/database/migrations.md where it lists the framework sets. Use neutral names (acme) only.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/postcard -run 'TestMailOverrideSmoke' -count=1 -v 2>&1 | grep -E '^\s*(--- |FAIL|ok|PASS)' | tail -20</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, "no tests to run", or no "--- PASS: TestMailOverrideSmoke/fallback" line</fails_when>
<automated>go test ./modules/lagoon -run 'TestMigrateStatusJSON' -count=1 2>&1 | tail -3</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go vet ./... && go test -short ./...</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line in the output</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "func NewDBSource(app \*backpack.App) OverrideSource" modules/postcard/store.go` prints one line
- `grep -n "MailOverrides(ctx context.Context, template string) (Overrides, error)" modules/postcard/store.go` prints one line
- `grep -n '"summercms.postcard", "mail", postcard.Migrations' modules/lagoon/migrations.go` prints one line
- `go doc ./modules/postcard Options` lists From, CSS, BrandCSS and Overrides
- `go doc ./modules/postcard Mailer` still shows exactly `Send(ctx context.Context, msg Message) error`
- `go list -deps ./modules/postcard | grep -E 'summercms/modules/(lagoon|cabana)$'` prints nothing
- `grep -n "Overrides from the admin" docs/services/mail.md modules/postcard/README.md` prints at least two lines
</acceptance_criteria>
<done>A customized template row reaches real sends in every process with a database, and anything wrong with it degrades to the file version.</done>
</task>
<task type="auto" tdd="true">
<name>Task 3: Partials and built-in layouts: plugins declare partials, bodies and layouts call them, layout and partial overrides apply at send</name>
<reversibility rating="costly">D-12: HasMailPartials, the <plugin>::mail.partials.<name> naming and the partial call syntax are a published contract plugins implement.</reversibility>
<files>modules/pact/capabilities.go, modules/pact/README.md, modules/postcard/partials.go, modules/postcard/templates.go, modules/postcard/mailer.go, modules/postcard/store.go, modules/postcard/assets/system.htm, modules/postcard/assets/minimal.htm, modules/postcard/assets/partials/button.htm, modules/postcard/assets/partials/panel.htm, modules/postcard/assets/partials/table.htm, modules/postcard/assets/partials/subcopy.htm, modules/postcard/partials_smoke_test.go, modules/postcard/README.md, docs/services/mail.md, docs/plugins/registration.md</files>
<read_first>
- modules/postcard/templates.go and modules/postcard/store.go (Task 2 output)
- modules/pact/capabilities.go (~1260-1280 HasMailTemplates; keep it byte-identical)
- modules/postcard/assets/default.htm (layout file format and the `<style>` slot)
- ../examples/golem15-wintercms-starter/modules/system/views/mail/layout-system.php and partial-button.php, partial-panel.php, partial-table.php, partial-subcopy.php (content to port to Go templates) — read only
- docs/plugins/registration.md (capability table)
- .planning/phases/35-mail-templates-and-layouts-editor/35-RESEARCH.md (Pattern 4, Pitfall 2)
</read_first>
<behavior>
- A plugin implementing pact.HasMailPartials with `acme.blog::mail.partials.note` boots; `acme.other::mail.partials.note` from acme.blog fails with "not owned"; a name without the `mail.partials.` segment, a missing file and a duplicate fail with the dotted name
- A plugin that implements only HasMailPartials (no templates) boots and its partial is callable from another plugin's template
- Body `Hi\n\n{{ partial "button" "url" .Link "body" "Go" }}\n\nBye` renders the button table with href = .Link in the HTML part (no "raw HTML omitted" comment) and `Go <link>` in the text part
- A variable value that contains a forged token (MAILPARTIAL followed by digits) is rendered as text, not replaced
- An odd kv count or an unknown partial is a render error naming the partial
- A template with `layout = system` from a plugin without a `system` alias renders with the built-in system layout; a plugin alias named system still wins
- A fake OverrideSource returning a customized file layout, a database-only layout (template override Layout = its code) and a partial override changes the output accordingly; layout CSS appears before mail.css in the style block
- Existing templates_test.go and mailer_test.go still pass unchanged
</behavior>
<action>
Per D-12 and D-08, with the Task 1 syntax:
- `modules/pact/capabilities.go`: add `HasMailPartials{ MailPartialsFS() fs.FS; MailPartials() []string }` next to HasMailTemplates, with a doc comment naming the file path and namespace rule; HasMailTemplates stays byte-identical. Add a row to modules/pact/README.md.
- `templates.go`: `parsedPartial{name, pluginID, headerName, textWrap, htmlWrap}` (layout file format: header, `==`, text, `==`, HTML), a partials map on Catalog, `(*Catalog) RegisterPartials(pluginID string, fsys fs.FS, partials []string) error` reusing assertOwner, assetPath and the missing/duplicate errors and requiring the `mail.partials.` segment; NewCatalog also registers the built-in layouts `postcard::mail.layouts.system` and `postcard::mail.layouts.minimal` and the partials button, panel, table and subcopy from embedded assets; resolveLayoutLocked tries the plugin's aliases, then the built-in aliases default, system and minimal.
- `mailer.go` BootPlugin: check pact.HasMailTemplates and pact.HasMailPartials independently (each optional) and register partials before templates.
- `partials.go`: the `partial` func per P35-02. In the body pass it renders the partial's text and HTML sections with the kv map as data and returns an alphanumeric token `MAILPARTIAL<nonce><n>` (nonce from crypto/rand, fresh per render); after goldmark the HTML part replaces `<p>TOKEN</p>` and then bare TOKEN with the partial HTML, and the text part (the pre-Markdown body) replaces TOKEN with the partial text. In layouts it returns template.HTML (HTML wrapper) or the text (text wrapper) directly. Partial templates get `markdown` (goldmark plus extension.Table, output validated with validateHTML) and no `partial`. Partial outputs pass validateHTML. Never enable goldmark's unsafe HTML option.
- Assets: port Winter's system layout and the four partials to Go templates with the class names the brand CSS will style (`button button-primary|positive|negative`, `panel`, `table`, `subcopy`); `minimal.htm` is a bare HTML wrapper with the style slot and `{{ .Content }}`. default.htm is not touched.
- Overrides at send: NewDBSource now also reads customized file layouts and every database-only layout (`WHERE is_custom`) into Overrides.Layouts by code, and customized partials into Overrides.Partials by code. A template's effective layout is its override's Layout code or its file layout; a customized file layout or a database-only layout replaces the file wrappers; a partial override replaces that partial's sections. P35-04: a non-empty layout CSS is placed before mail.css in the css slot.
- Write the behavior subtests in `partials_smoke_test.go` (`TestMailPartialsSmoke`, runs under -short: fstest.MapFS fixtures, NewMailer with a fake OverrideSource and a MemoryDriver) first, then implement.
- Docs in the same commit: postcard README (partials, built-in layouts and partials, the call syntax with an acme example, the token rule, API rows for RegisterPartials, LayoutOverride/PartialOverride use), docs/services/mail.md sections "Partials" and "Built-in layouts", docs/plugins/registration.md capability row for pact.HasMailPartials.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/postcard -run 'TestMailPartialsSmoke|TestMailOverrideSmoke' -count=1 -v 2>&1 | grep -E '^\s*(--- |FAIL|ok|PASS)' | tail -30</automated>
<fails_when>a "FAIL" line, "no tests to run", or no "--- PASS: TestMailPartialsSmoke" line</fails_when>
<automated>go doc ./modules/pact HasMailTemplates | grep -cE '^\s+(MailTemplatesFS\(\) fs\.FS|MailTemplates\(\) \[\]string|MailLayouts\(\) map\[string\]string)$'</automated>
<fails_when>non-zero exit or a count other than 3 (HasMailTemplates changed)</fails_when>
<automated>go vet ./... && go test -short ./...</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line in the output</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "type HasMailPartials interface" modules/pact/capabilities.go` prints one line
- `grep -n "pact.HasMailPartials" modules/postcard/mailer.go` prints at least one line
- `grep -n "func (c \*Catalog) RegisterPartials(pluginID string, fsys fs.FS, partials \[\]string) error" modules/postcard/templates.go` prints one line
- `ls modules/postcard/assets/partials/` lists button.htm, panel.htm, subcopy.htm and table.htm
- `git diff a024280 --stat -- modules/postcard/assets/default.htm` prints nothing
- `grep -n "pact.HasMailPartials" docs/plugins/registration.md` prints at least one line
</acceptance_criteria>
<done>Plugins and admins can use reusable mail blocks in bodies and layouts, and customized layouts and partials reach real sends.</done>
</task>
<task type="auto" tdd="true">
<name>Task 4: Sample values, file hashes, index rows and the draft editor: previews and save checks render like real sends</name>
<files>modules/postcard/samples.go, modules/postcard/editor.go, modules/postcard/templates.go, modules/postcard/store.go, modules/postcard/assets/sample.htm, modules/pact/capabilities.go, modules/pact/README.md, modules/postcard/editor_smoke_test.go, modules/postcard/README.md, docs/services/mail.md</files>
<read_first>
- modules/postcard/templates.go, modules/postcard/partials.go, modules/postcard/store.go (Tasks 2-3 output)
- modules/pact/capabilities.go (~1050-1075 RowState and ListRowStates doc)
- ../sm-paymentgateway-plugin/views/mail/order/paid.htm and ../sm-user-plugin/views/mail/activate.htm (real nested, range and if shapes the walker must survive) — read only
- .planning/phases/35-mail-templates-and-layouts-editor/35-RESEARCH.md (Pattern 2, Pattern 5, "Placeholder walker" code example, Pitfalls 3, 8, 10)
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md ("Save validation (D-13)" table: the rules and fields)
</read_first>
<behavior>
- `sample.Name = "Ada"` and `sample.order.code = "ZAM-1"` parse to Samples{"Name": "Ada", "order.code": "ZAM-1"}; a file without sample keys parses exactly as before (subject, description, layout unchanged)
- Placeholder vars for `{{ .Name }} {{ .order.code }} {{ if .employee.first_name }}x{{ end }} {{ range .order.items }}{{ .description }}{{ end }} {{ range .lines }}{{ . }}{{ end }} {{ with .user }}{{ .email }}{{ end }}` render without error as `Ada ZAM-1 x [order.items.description] [lines] [user.email]`
- Validate of a template draft: a parse error gives Rule parse on Field body; `<script>` gives Rule unsafe with the matched snippet in Message; a subject with a newline gives Rule subject_line on subject; an unknown layout code gives Rule layout on layout; an unknown partial gives Rule partial with Name set
- Validate of a layout draft without `{{ .Content }}` in the HTML (or text) wrapper gives Rule no_content on content_html (or content_text); CSS containing a closing style tag gives Rule unsafe on content_css
- Preview of a template draft returns Subject, HTML and Text rendered through the same render path as Send, with samples and placeholders; Preview of a layout draft wraps assets/sample.htm; Preview of a partial draft renders a sample message calling it with placeholder arguments
- SendDraft delivers only to the given address through the mailer's driver with mail.from
- Every TemplateFile, LayoutFile and PartialFile has a 64-hex Hash that is equal for LF and CRLF copies of the same file
- TemplateLocale("acme.blog::mail.welcome-en", ["en","pl"]) is "en"; "acme.blog::mail.cancel-notice" with the same locales is ""
- SyncIndex run twice leaves the same rows and IDs; a customized row keeps its subject, body, layout_id and base_hash while file_hash is refreshed; a database-only layout is untouched; two concurrent SyncIndex calls both succeed; ResetOverride on a customized template restores the file subject, body and layout_id and clears is_custom, base_hash and customized_at
</behavior>
<action>
Per D-15, D-13, D-16, D-17, D-07, D-05 and D-23 (amending D-06):
- `samples.go`: read `sample.<path>` header keys keeping the case after the prefix (parseINI keeps lower-casing other keys); a parse-tree walker over the html/template Tree (text/template/parse) that builds nested maps with `[a.b]` leaves or the sample value, one-element slices for range targets (a map of the fields used in the body, or a string when the body prints the dot), handles if/with/else, with re-rooting, chains and variables, and parses with the partial and markdown funcs present.
- Field names in DraftError.Field are the admin column names 35-02 uses: subject, layout, body for templates; content_html, content_text, content_css for layouts and partials.
- Hashes and the catalog read API in templates.go: sha256 hex of CRLF-normalized bytes on every parsed entry; exported read structs `TemplateFile{Name, PluginID, Subject, Description, Layout, Body, Samples, Source, Hash}`, `LayoutFile{Name, PluginID, Title, Text, HTML, Source, Hash}`, `PartialFile{Name, PluginID, Title, Text, HTML, Source, Hash}` (Source is the normalized raw file text; Layout is the resolved full layout name); methods `Templates()`, `Layouts()`, `Partials()` (sorted by name) and `Template(name)`, `Layout(name)`, `Partial(name)` returning (value, bool); serializers `FormatTemplate(subject, layout, body string) string`, `FormatLayout(name, text, html, css string) string`, `FormatPartial(name, text, html string) string` producing the header plus `==` sections, used by 35-02's diff on both sides; `TemplateLocale(name string, locales []string) string` (suffix after the last dash of the last dotted segment, only when it is one of locales).
- `editor.go`: type `Kind` with `KindTemplate`, `KindLayout`, `KindPartial`, `KindBrand`; `Draft{Kind; Name; Subject, Body, Layout; HTML, Text, CSS string; Brand *Brand}` (Name is the template full name, layout code or partial full name); `DraftError{Field, Rule, Message, Name string}` implementing error, Rule one of parse, render, unsafe, subject_line, layout, partial, no_content (35-02 maps them to `backend::lang.mail.invalid_<rule>`) and colour (Task 5; 35-02 maps it to `backend::lang.colorpicker.invalid`); Message carries only parser, renderer or safety-check text (never a database error or a file path beyond the name), and for the unsafe rule the matched snippet (research Pitfall 8); `Preview{Subject, HTML, Text string}`; `Editor` with `EditorFrom(app *backpack.App) (*Editor, bool)` (from the published *mailer, as BootPlugin finds it), `Catalog() *Catalog`, `Validate(ctx, Draft) *DraftError`, `Preview(ctx, Draft) (Preview, error)` (a *DraftError through errors.As for draft problems), `SendDraft(ctx, Draft, to string) error`. Preview and Validate read the other pieces (layouts, partials, Brand) through the mailer's source with an empty template name, so a preview matches a real send (D-16). Leave the KindBrand preview to Task 5.
- `assets/sample.htm`: the sample Markdown message used to preview layouts (a heading, a paragraph, a button partial call, a panel).
- `store.go`: `SyncIndex(ctx context.Context, db *gorm.DB, cat *Catalog, locales []string) error`: layouts first, then templates (layout_id from the layout row of the resolved layout), then partials; `INSERT ... ON CONFLICT (code) DO UPDATE` that always sets source, description, locale, name (header name for layouts and partials) and file_hash and sets the mirror columns only `WHERE NOT is_custom`; never deletes. `ResetOverride(ctx context.Context, db *gorm.DB, cat *Catalog, kind Kind, code string) error` clears is_custom, base_hash and customized_at on one file-backed row and re-mirrors the file content; it refuses a database-only layout.
- pact: add `RowStateCustomized RowState = "customized"` and `RowStateOutdated RowState = "outdated"` and update the ListRowStates doc comment (five constants); pact README row.
- Write the behavior subtests first in `editor_smoke_test.go` (`TestMailEditorSmoke`: subtests `samples`, `walker`, `validate`, `preview`, `send_draft`, `hash`, `locale` run under -short; `sync` and `reset` use the Postgres helper from override_smoke_test.go and skip under -short), then implement.
- Docs in the same commit: postcard README (Editor API, sample keys, SyncIndex, ResetOverride, Kind, the read structs, TemplateLocale), docs/services/mail.md "Sample values for previews" with an acme example and the placeholder rule; pact README row-state sentence.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/postcard -run 'TestMailEditorSmoke' -count=1 -v 2>&1 | grep -E '^\s*(--- |FAIL|ok|PASS)' | tail -30</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, "no tests to run", or no "--- PASS: TestMailEditorSmoke/sync" or "--- PASS: TestMailEditorSmoke/walker" line</fails_when>
<automated>go vet ./... && go test -short ./...</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line in the output</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "func EditorFrom(app \*backpack.App) (\*Editor, bool)" modules/postcard/editor.go` prints one line
- `grep -n "func SyncIndex(ctx context.Context, db \*gorm.DB, cat \*Catalog, locales \[\]string) error" modules/postcard/store.go` prints one line
- `grep -n "func ResetOverride(" modules/postcard/store.go` prints one line
- `grep -n 'RowStateCustomized RowState = "customized"' modules/pact/capabilities.go` and `grep -n 'RowStateOutdated RowState = "outdated"' modules/pact/capabilities.go` each print one line
- `go doc ./modules/postcard DraftError` lists Field, Rule, Message and Name
- `grep -n "sample\." docs/services/mail.md` prints at least one line
</acceptance_criteria>
<done>The admin layer can list file mail as rows, reset an override, and validate, preview and test-send a draft exactly as postcard would send it.</done>
</task>
<task type="auto" tdd="true">
<name>Task 5: Branding: saved colours replace mail.brandCss and layouts show the logo by an absolute URL built at send time</name>
<files>modules/lagoon/attach/absolute.go, modules/lagoon/README.md, docs/services/storage.md, modules/postcard/brand.go, modules/postcard/assets/brand.css.tmpl, modules/postcard/store.go, modules/postcard/mailer.go, modules/postcard/templates.go, modules/postcard/editor.go, modules/postcard/brand_smoke_test.go, modules/postcard/README.md, docs/services/mail.md</files>
<read_first>
- modules/lagoon/attach/bucket.go (~35-80 PublicURLBase, PublicPathPrefix, parsePublicURL; ~125-160 OpenBucket) and modules/lagoon/attach/thumb.go (~60-100 BlobKey, PublicURL)
- modules/postcard/store.go, modules/postcard/editor.go (Tasks 2-4 output)
- ../examples/golem15-wintercms-starter/modules/system/models/mailbrandsetting/custom.less and ../examples/golem15-wintercms-starter/modules/system/models/MailBrandSetting.php (colour set and defaults) — read only
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md ("Branding page (C12, D-10, D-11)" colour table with defaults)
- .planning/phases/35-mail-templates-and-layouts-editor/35-RESEARCH.md (Pattern 6, Pattern 8, Pitfall 4)
</read_first>
<behavior>
- AbsolutePublicURL with storage.uploads.public_url `https://cdn.example.com/u` returns `https://cdn.example.com/u/<key>`; without it and with app.url `https://acme.test` and the default prefix it returns `https://acme.test/storage/uploads/<key>`; with neither it returns ErrNoAbsoluteURL; it never reads the process globals set by OpenBucket
- CompileBrandCSS(DefaultBrand()) succeeds and contains every default colour; a colour `#ABC`, `red` or one containing a closing style tag returns an error naming the field; an empty colour uses that field's default; upper-case hex is accepted and emitted lower-case
- No brand row: the sent HTML's style block contains config mail.brandCss; a brand row exists: it contains the compiled CSS, not mail.brandCss, and mail.css still follows it
- A brand row with logo_file_id pointing at a public system_files row: a layout using `{{ .logoUrl }}` gets the absolute URL; a missing or non-public file gives an empty logoUrl and a warning, and the mail is still sent
- Editor Preview of a KindBrand draft renders the sample message in the default layout with the draft colours and logo
</behavior>
<action>
Per D-10, D-11, D-19 and D-24:
- `modules/lagoon/attach/absolute.go` (own commit first): `ErrNoAbsoluteURL` and `AbsolutePublicURL(cfg *compass.Config, key string) (string, error)`: storage.uploads.public_url (validated with parsePublicURL) joined with the key by one slash; else app.url (absolute http or https) joined with storage.uploads.public_path_prefix (default `/storage/uploads`) and the key; else ErrNoAbsoluteURL. It reads only cfg, so it gives the same URL in serve and in queue:work (research Pitfall 4). Document it in modules/lagoon/README.md (attach bullet and API row) and docs/services/storage.md in the same commit.
- `brand.go`: `Brand{BodyBg, ContentBg, HeaderColor, FooterColor, HeadingColor, TextColor, LinkColor, ButtonTextColor, ButtonPrimaryBg, ButtonPositiveBg, ButtonNegativeBg, PanelBg, TableBorderColor, LogoURL string}`, `DefaultBrand() Brand` with the UI-SPEC Winter defaults, `CompileBrandCSS(b Brand) (string, error)` validating each colour against `^#[0-9a-f]{6}$` after lower-casing (empty means default) and executing `assets/brand.css.tmpl` (a text/template port of Winter's custom.less styling body, a, h1-h3, p, table and the built-in partial classes button-primary/positive/negative, panel, table and subcopy, so Branding also shows in plugin layouts that only carry wrapper classes).
- Add `Brand *Brand` to Overrides; NewDBSource reads row 1 of the brand table into Overrides.Brand (no row: nil) and, when logo_file_id is set, the system_files row by id with is_public true, then `attach.AbsolutePublicURL(app.Config, attach.BlobKey(disk_name))` into Brand.LogoURL; a missing or non-public file or ErrNoAbsoluteURL gives an empty LogoURL and a rate-limited warning.
- Send and render: a non-nil Brand replaces the brandCss slot with CompileBrandCSS (D-11; a compile error logs and keeps config mail.brandCss); mail.css is unchanged; layouts get `logoUrl` (empty when no brand or no logo). Editor gains the KindBrand preview (sample message, default layout, draft Brand) and Validate for KindBrand reports an invalid colour with Rule colour and the column name (for example button_primary_bg) in Field.
- Write the behavior subtests first in `brand_smoke_test.go` (`TestMailBrandSmoke`: `compile`, `defaults`, `preview` under -short; `precedence` and `logo` with the Postgres helper, skipped under -short) plus an attach case for AbsolutePublicURL inside the same test (no new attach test file), then implement.
- Docs in the same postcard commit: postcard README (Branding, the D-11 precedence in Configuration next to mail.brandCss and mail.css, logoUrl, API rows), docs/services/mail.md section "Branding".
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/postcard -run 'TestMailBrandSmoke' -count=1 -v 2>&1 | grep -E '^\s*(--- |FAIL|ok|PASS)' | tail -20</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, "no tests to run", or no "--- PASS: TestMailBrandSmoke/precedence" or "--- PASS: TestMailBrandSmoke/logo" line</fails_when>
<automated>go test ./modules/postcard/... ./modules/lagoon/... ./modules/pact/... -count=1 2>&1 | tail -8</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go vet ./... && go test -short ./...</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line in the output</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "func AbsolutePublicURL(cfg \*compass.Config, key string) (string, error)" modules/lagoon/attach/absolute.go` prints one line
- `grep -n "attach.AbsolutePublicURL" modules/postcard/store.go` prints at least one line
- `grep -n "func CompileBrandCSS(b Brand) (string, error)" modules/postcard/brand.go` prints one line
- `grep -n '"logoUrl"' modules/postcard/templates.go` prints at least one line
- `grep -n "AbsolutePublicURL" modules/lagoon/README.md docs/services/storage.md` prints at least two lines
- `git log --format=%s -F --grep='feat(attach): absolute public URL from config' --grep='feat(postcard): mail branding and the logo URL'` prints two lines, the postcard one first (newer)
</acceptance_criteria>
<done>Saving Branding restyles every mail and shows the logo, while apps that never open the page keep their configured brand CSS.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| admin-edited database rows → postcard render | subject, body, layout and partial text written by administrators, rendered into mail sent to members |
| template variables (member data) → rendered mail | plugin-supplied values that may contain markup or a forged partial token |
| database → send path | a missing table, a stale row or an outage during a send |
| config → logo URL | storage.uploads.public_url and app.url become links in sent mail |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-35-01 | Tampering | override rendering in Send | high | mitigate | validateHTML (script/iframe/object/embed, event handlers, javascript:/vbscript:/data:) runs on the body, every partial output and the final HTML at send, exactly as for files; TestMailOverrideSmoke/fallback proves a failing override never ships |
| T-35-02 | Tampering | partial tokens in bodies | high | mitigate | per-render crypto/rand nonce in an alphanumeric token, replaced only after goldmark; a forged token in a variable stays text (Task 3 behavior) |
| T-35-03 | Tampering | subject override | medium | mitigate | existing CR/LF refusal at send and Rule subject_line in Validate |
| T-35-04 | Tampering | brand colours into the style block | high | mitigate | strict `^#[0-9a-f]{6}$` before CompileBrandCSS; layout CSS with a closing style tag refused at Validate; validateHTML backstop |
| T-35-05 | Denial of service | per-send lookup | medium | mitigate | any lookup error or missing table renders the file version with a rate-limited warning (TestMailOverrideSmoke/missing_table, no_db) |
| T-35-06 | Information disclosure | DraftError.Message | medium | mitigate | Message carries parser, renderer and safety text only, never database errors or filesystem paths |
| T-35-07 | Spoofing | logo URL host | low | mitigate | URL built from operator config only (public_url validated by parsePublicURL, app.url absolute http/https); never from request headers |
| T-35-08 | Tampering | stale overrides across instances | medium | mitigate | no cache: every send reads the rows (Claude's Discretion: per-send lookup) |
| T-35-SC | Tampering | npm/pip/cargo installs | high | accept | this plan installs no package; every Go dependency used (gorm, gormigrate, goldmark, testcontainers) is already in go.mod |
</threat_model>
<verification>
- `go vet ./... && go test -short ./...` green after every commit; `go test ./modules/postcard/... ./modules/lagoon/... ./modules/pact/...` (Docker) green after Task 5.
- `go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree'` and `go run ./cmd/summer docs:build --check` pass.
- `(cd ../sm-user-plugin && go test -run 'TestMail|TestPolishMailSubjects' ./...)` and `(cd ../sm-paymentgateway-plugin && go test -run 'TestMailCatalog|TestMailTracer|TestMailersMatrixSmoke' ./...)` pass against this checkout (their go.mod replaces the framework with ../summercms.go); nothing in those repositories is changed.
</verification>
<success_criteria>
- postcard owns the mail tables, reads overrides per send and falls back to the file version on any failure.
- Partials, built-in layouts, sample values, hashes, index sync, reset, the Editor and Branding exist with smoke tests and docs.
- pact gained HasMailPartials and two row states additively; HasMailTemplates is unchanged.
- No push, no tag; no file in a sibling repository changed.
</success_criteria>
<output>
Create `.planning/phases/35-mail-templates-and-layouts-editor/35-01-SUMMARY.md` when done; record the Task 1 answer verbatim and every name that differs from this plan's text.
</output>
## Artifacts this phase produces
- Tables (migration `202611060001_create_system_mail_tables`, history `summercms.postcard`): `system_mail_layouts`, `system_mail_templates`, `system_mail_partials`, `system_mail_brand_settings`, `system_mail_image_library`.
- pact: `pact.HasMailPartials`, `pact.RowStateCustomized`, `pact.RowStateOutdated`.
- postcard types: `postcard.OverrideSource`, `postcard.Overrides`, `postcard.TemplateOverride`, `postcard.LayoutOverride`, `postcard.PartialOverride`, `postcard.Brand`, `postcard.Kind`, `postcard.Draft`, `postcard.DraftError`, `postcard.Preview`, `postcard.Editor`, `postcard.TemplateFile`, `postcard.LayoutFile`, `postcard.PartialFile`; field `postcard.Options.Overrides`.
- postcard functions and methods: `postcard.NewDBSource`, `postcard.SyncIndex`, `postcard.ResetOverride`, `postcard.EditorFrom`, `postcard.DefaultBrand`, `postcard.CompileBrandCSS`, `postcard.FormatTemplate`, `postcard.FormatLayout`, `postcard.FormatPartial`, `postcard.TemplateLocale`, `(*Catalog).RegisterPartials`, `(*Catalog).Templates|Layouts|Partials|Template|Layout|Partial`, `(*Editor).Catalog|Validate|Preview|SendDraft`.
- postcard constants and variables: `postcard.Migrations`, `postcard.TemplatesTable`, `postcard.LayoutsTable`, `postcard.PartialsTable`, `postcard.BrandTable`, `postcard.ImageLibraryTable`, `postcard.KindTemplate`, `postcard.KindLayout`, `postcard.KindPartial`, `postcard.KindBrand`.
- attach: `attach.AbsolutePublicURL`, `attach.ErrNoAbsoluteURL`.
- Built-in mail names: `postcard::mail.layouts.system`, `postcard::mail.layouts.minimal`, `postcard::mail.partials.button|panel|table|subcopy`; layout aliases `system`, `minimal` (fallback after plugin aliases).
- Template language: `{{ partial "<name>" key value ... }}`, `markdown` inside partials, layout key `logoUrl`, header keys `sample.<path>`.
- Files: assets `system.htm`, `minimal.htm`, `sample.htm`, `brand.css.tmpl`, `partials/{button,panel,table,subcopy}.htm`; smoke tests `TestMailOverrideSmoke`, `TestMailPartialsSmoke`, `TestMailEditorSmoke`, `TestMailBrandSmoke`.
- Config keys: none new (reads existing `mail.brandCss`, `mail.css`, `storage.uploads.public_url`, `storage.uploads.public_path_prefix`, `app.url`).
## Phase-wide source coverage audit
| Source | ID | Item | Plan | Status |
|--------|----|------|------|--------|
| GOAL | — | Edit every mail from the admin; list, override, reset; editable layouts with predefined ones; images in layouts and templates; override else file | 01-04 | COVERED |
| REQ | — | none mapped (Requirements: TBD); I18N-03 kept satisfied by the consumer-repo checks | 01, 04 | n/a |
| CONTEXT | D-01 | screens in cabana pseudo-plugin; postcard free of admin code | 01 (interface), 02 (screens) | COVERED |
| CONTEXT | D-02 | Settings → Mail entries | 02 | COVERED |
| CONTEXT | D-03 | two permission codes, no default grants, picker for template editors | 02, 03 | COVERED |
| CONTEXT | D-04 | override = subject + body + layout, description read-only | 01, 02 | COVERED |
| CONTEXT | D-05 | locale column and filter | 01 (TemplateLocale, sync), 02 | COVERED |
| CONTEXT | D-06 | reset to file version (as amended by D-23) | 01 (ResetOverride), 02 | COVERED |
| CONTEXT | D-07 | drift hash, notice, file version view/diff | 01 (hashes), 02 | COVERED |
| CONTEXT | D-08 | file + custom layouts, in-use delete refusal, predefined layouts | 01 (system, minimal), 02 | COVERED |
| CONTEXT | D-09 | codeeditor field type | 02 (server), 03 (SPA) | COVERED |
| CONTEXT | D-10 | Branding page with colours and logo | 01 (compile), 02 (page), 03 (fields) | COVERED |
| CONTEXT | D-11 | Branding replaces mail.brandCss once saved | 01 | COVERED |
| CONTEXT | D-12 | partials capability, built-ins, overrides | 01, 02 | COVERED |
| CONTEXT | D-13 | save validation | 01 (Validate), 02 (hooks) | COVERED |
| CONTEXT | D-14 | fallback at send | 01 | COVERED |
| CONTEXT | D-15 | sample variables, [name] placeholders | 01 | COVERED |
| CONTEXT | D-16 | live preview of the draft, sandboxed iframe | 01 (Preview), 02 (route), 03 (field) | COVERED |
| CONTEXT | D-17 | test send to own address, rate-limited | 01 (SendDraft), 02 (route), 03 (button) | COVERED |
| CONTEXT | D-18 | shared image library via attach | 02, 03 | COVERED |
| CONTEXT | D-19 | absolute public URLs | 01 (helper), 02 (library URLs) | COVERED |
| CONTEXT | D-20 | insert button in editors | 03 | COVERED |
| CONTEXT | D-21 | unit tests last, READMEs/docs, OpenAPI and dist gates | 01-03 (docs), 04 (tests, gate) | COVERED |
| CONTEXT | D-22 | postcard owns tables, migrations, per-send lookup | 01 | COVERED |
| CONTEXT | D-23 | index rows synced at serve start; reset clears columns | 01 (SyncIndex), 02 (serve-start call) | COVERED |
| CONTEXT | D-24 | logo URL built at send time from config | 01 | COVERED |
| CONTEXT | D-25 | no built-in template; empty-state text | 01, 02 | COVERED |
| RESEARCH | Pattern 1-3 | store split, index rows, per-send lookup | 01 | COVERED |
| RESEARCH | Pattern 4-6 | partials, samples, Branding | 01 | COVERED |
| RESEARCH | Pattern 7-9 | routes, permissions, rate limit, images, admin wiring | 02, 03 | COVERED |
| RESEARCH | Pitfall 5 | CodeMirror Mod-Enter | 03 | COVERED |
| RESEARCH | Pitfall 6, 9 | validate in FormAfterUpdate; parameterized messages | 02 | COVERED |
| RESEARCH | Package audit | @codemirror/view 6.43.15 [SUS too-new] → human checkpoint | 03 | COVERED |
| CONTEXT | Deferred | hand-written text parts, WYSIWYG body, CID images, arbitrary test recipient, SMTP screen, MailBlocker | — | excluded (deferred) |

View File

@@ -0,0 +1,307 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 01
subsystem: mail
tags: [postcard, mail, gorm, gormigrate, goldmark, html-template, pact, attach, postgres]
# Dependency graph
requires:
- phase: 04-cli-scaffolding-i18n-and-mail
provides: postcard Catalog, Mailer, drivers and pact.HasMailTemplates
- phase: lagoon attach (system_files, public URLs)
provides: attach.Migrations, attach.BlobKey, storage.uploads.* config keys
provides:
- "postcard-owned mail tables (system_mail_templates, _layouts, _partials, _brand_settings, _image_library) as the framework migration set summercms.postcard"
- "per-send override lookup (OverrideSource, NewDBSource) with fallback to the file version"
- "pact.HasMailPartials, the partial template func, built-in partials button/panel/table/subcopy and layouts system/minimal"
- "sample.<path> header keys and the placeholder walker"
- "file hashes, the catalog read API, SyncIndex and ResetOverride"
- "postcard.Editor: Validate, Preview and SendDraft for template, layout, partial and Branding drafts"
- "Branding: Brand, DefaultBrand, CompileBrandCSS, the logoUrl layout key"
- "attach.AbsolutePublicURL and attach.ErrNoAbsoluteURL"
- "pact.RowStateCustomized and pact.RowStateOutdated"
affects: [35-02, 35-03, 35-04, cabana, admin-spa]
# Actuals (#2632)
actuals:
tokens: 69814 # chars/4 over this plan's realized diff (modules/ and docs/, 279256 chars)
tasks: 5 # the Task 1 decision checkpoint and Tasks 2-5
commits: 6 # MEASURED: git rev-list --count; 5 are this plan's, 1 (f8fa0f1 docs(31)) is another session's
plan_head_before: 3198bbe1aa96781b18398a3651b7de6d37939fba
plan_head_after: 2bf9081c1bd8385b45210ead8524eda5512b3ca1
# Tech tracking
tech-stack:
added: []
patterns:
- "A module that lagoon must migrate but that cannot import lagoon ships its own gormigrate set and reads the *gorm.DB through backpack per call"
- "Template funcs that must survive Markdown return a per-render random alphanumeric token, swapped after conversion"
- "Drafts are rendered by the send path with the draft injected as an override, so previews and save checks cannot drift from sends"
key-files:
created:
- modules/postcard/store.go
- modules/postcard/partials.go
- modules/postcard/samples.go
- modules/postcard/editor.go
- modules/postcard/brand.go
- modules/postcard/assets/system.htm
- modules/postcard/assets/minimal.htm
- modules/postcard/assets/sample.htm
- modules/postcard/assets/brand.css.tmpl
- modules/postcard/assets/partials/button.htm
- modules/postcard/assets/partials/panel.htm
- modules/postcard/assets/partials/table.htm
- modules/postcard/assets/partials/subcopy.htm
- modules/postcard/override_smoke_test.go
- modules/postcard/partials_smoke_test.go
- modules/postcard/editor_smoke_test.go
- modules/postcard/brand_smoke_test.go
- modules/lagoon/attach/absolute.go
modified:
- modules/postcard/mailer.go
- modules/postcard/templates.go
- modules/postcard/README.md
- modules/pact/capabilities.go
- modules/pact/README.md
- modules/lagoon/migrations.go
- modules/lagoon/pending_test.go
- modules/lagoon/README.md
- docs/services/mail.md
- docs/services/storage.md
- docs/plugins/registration.md
- docs/database/migrations.md
key-decisions:
- "35-01 Task 1 answered as-planned: P35-01 schema, P35-02 partial syntax and built-ins, P35-03 sample.* keys, P35-04 layout CSS slot and logoUrl, P35-05 names adopted without changes"
- "35-01: postcard logs 'override failed, sending the file version' only when the file version then renders; when both fail, the file version's error is returned as before"
- "35-01: a partial call in a body leaves the token MAILPARTIAL + 32 hex nonce + X<n>X, swapped in one pass after goldmark; raw HTML stays disabled for bodies"
- "35-01: Editor.Validate refuses a template body whose source holds a script, iframe, object or embed tag, because Markdown would drop it silently at send"
- "35-01: Branding (compiled CSS and logoUrl) also applies to the file version sent after a failing override; an invalid stored colour keeps mail.brandCss with a warning"
- "35-01: pact has five row states; cabana keeps only three until 35-02 updates rowStateOrder and docs/backend/lists-and-filters.md"
patterns-established:
- "Override source per send: Send asks OverrideSource once, renders with the result, and renders the files alone when the lookup or the override fails"
- "Typed render errors (part, template, unsafe snippet) keep send error texts unchanged and let the editor report field and rule"
requirements-completed: [D-01, D-04, D-05, D-06, D-07, D-08, D-10, D-11, D-12, D-13, D-14, D-15, D-16, D-17, D-19, D-22, D-23, D-24, D-25]
coverage:
- id: D1
description: "A customized row in system_mail_templates changes the subject, body and layout of the mail a process sends with only postcard.Activate and a published *gorm.DB; no row, no database, missing tables or a failing override send the file version"
requirement: "D-22"
verification:
- kind: integration
ref: "modules/postcard/override_smoke_test.go#TestMailOverrideSmoke (override, override_layout, layouts_and_partials, file, fallback, caller_subject, missing_table, no_db, unknown_template, migrations_roll_back)"
status: pass
- kind: integration
ref: "modules/lagoon/pending_test.go#TestMigrateStatusJSON"
status: pass
human_judgment: false
- id: D2
description: "Plugins declare partials through pact.HasMailPartials; bodies and layouts call them with {{ partial ... }}; built-in partials and the system and minimal layouts; layout and partial overrides apply at send"
requirement: "D-12"
verification:
- kind: unit
ref: "modules/postcard/partials_smoke_test.go#TestMailPartialsSmoke (capability, partials_only_plugin, body, forged_token, errors, built_in_layouts, layout_partials, overrides)"
status: pass
- kind: other
ref: "go doc ./modules/pact HasMailTemplates (three methods, unchanged)"
status: pass
human_judgment: false
- id: D3
description: "sample.<path> header keys, the placeholder walker, file hashes, the catalog read API, TemplateLocale, SyncIndex, ResetOverride, and Editor Validate, Preview and SendDraft for template, layout and partial drafts"
requirement: "D-13"
verification:
- kind: integration
ref: "modules/postcard/editor_smoke_test.go#TestMailEditorSmoke (samples, walker, validate, preview, send_draft, hash, locale, sync, reset)"
status: pass
human_judgment: false
- id: D4
description: "attach.AbsolutePublicURL builds an absolute public URL from configuration alone"
requirement: "D-19"
verification:
- kind: unit
ref: "modules/postcard/brand_smoke_test.go#TestMailBrandSmoke/absolute_url"
status: pass
human_judgment: false
- id: D5
description: "Branding: compiled brand CSS replaces mail.brandCss once the settings row exists, mail.css still follows, layouts get logoUrl built at send time, and the editor previews and validates a Branding draft"
requirement: "D-11"
verification:
- kind: integration
ref: "modules/postcard/brand_smoke_test.go#TestMailBrandSmoke (defaults, compile, preview, precedence, logo)"
status: pass
human_judgment: false
- id: D6
description: "Existing mail renders unchanged when no override exists: the default layout file is untouched and the consumer plugins' mail tests pass against this checkout"
verification:
- kind: unit
ref: "go test -short ./modules/postcard (TestMailRenderSmoke, TestMailLayoutSmoke, TestMailRecipientsAndSafety unchanged)"
status: pass
- kind: other
ref: "(cd ../sm-user-plugin && go test -run 'TestMail|TestPolishMailSubjects' ./...) and (cd ../sm-paymentgateway-plugin && go test -run 'TestMailCatalog|TestMailTracer|TestMailersMatrixSmoke' ./...)"
status: pass
- kind: other
ref: "git diff a024280 --stat -- modules/postcard/assets/default.htm (empty)"
status: pass
human_judgment: false
- id: D7
description: "READMEs and docs pages describe the new API, the mail tables, partials, sample values, the editor and Branding accurately and readably"
verification:
- kind: other
ref: "go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' and summer docs:build --check (identifiers, links, anchors)"
status: pass
human_judgment: true
rationale: "The docs checker proves identifiers and links exist, not that the prose is correct and clear; config keys are reviewed by hand per CLAUDE.md"
# Metrics
duration: 55 min
completed: 2026-11-13
status: complete
---
# Phase 35 Plan 01: Mail domain layer in postcard Summary
**postcard now owns the mail tables and reads template, layout, partial and Branding overrides from Postgres on every send, with file fallback, a partials capability, sample-value placeholders and an Editor that validates, previews and test-sends drafts through the send path**
## Performance
- **Duration:** 55 min (this continuation; the Task 1 checkpoint was handled by the previous agent)
- **Started:** 2026-11-13T09:15:32Z
- **Completed:** 2026-11-13T10:10:00Z
- **Tasks:** 5 of 5 (Task 1 decision checkpoint, Tasks 2-5 executed)
- **Files modified:** 30 (18 created, 12 modified)
## Task 1 answer (recorded verbatim)
The user's response to the Task 1 decision checkpoint: **"as-planned (Recommended)"**
Adopted without adjustment: P35-01 (schema), P35-02 (partial call syntax; built-in partials button, panel, table, subcopy; built-in layouts default, system, minimal), P35-03 (`sample.*` dotted header keys), P35-04 (layout CSS slot and `logoUrl`), P35-05 (permission codes, controller IDs, row states, routes, test-send limit, image picker upload rule) and the reset semantics as written in the plan's objective.
## Accomplishments
- **Database overrides with file fallback (Task 2, tracer).** `postcard.Migrations` creates the five `system_mail_*` tables; lagoon runs it as the framework set `summercms.postcard` after `summercms.attach`. `Mailer.Send` asks an `OverrideSource` once per message; `NewDBSource` looks the `*gorm.DB` up on the app per call and caches nothing. No database, missing tables, a failed lookup or an override that does not render or fails the safety checks sends the file version.
- **Partials and built-in layouts (Task 3).** `pact.HasMailPartials` (additive; `HasMailTemplates` is byte-identical), `Catalog.RegisterPartials`, the `partial` template func in bodies and layouts, `markdown` inside partials, built-in partials and the `system` and `minimal` layouts. Customized and database-only layouts and customized partials apply at send.
- **Samples, hashes, index rows and the Editor (Task 4).** `sample.<path>` header keys, a parse-tree walker that fills every other variable with `[path]`, sha256 hashes of CRLF-normalized files, `SyncIndex`, `ResetOverride`, and `Editor.Validate`, `Preview` and `SendDraft`.
- **Branding (Task 5).** `attach.AbsolutePublicURL`, `Brand`, `DefaultBrand`, `CompileBrandCSS`, the `logoUrl` layout key, the D-11 precedence over `mail.brandCss`, and the Branding draft in the Editor.
## Task Commits
1. **Task 1: decision checkpoint**: no commit (answer recorded above)
2. **Task 2: database overrides (tracer)**: `7e5d2c7` (feat)
3. **Task 3: partials, built-in layouts, layout and partial overrides**: `5df1ec2` (feat)
4. **Task 4: samples, hashes, index sync, draft editor**: `495319e` (feat)
5. **Task 5: Branding**: `935e4bf` (feat(attach)), then `2bf9081` (feat(postcard))
**Plan metadata:** committed together with this summary (docs).
Commit subjects are the ones the plan's "Execution units" table fixes; each body ends with "Plan 35-01, task N". The measured commit count since the plan's base is 6: `f8fa0f1 docs(31): capture phase context` was committed on master by another session during this run and is not part of this plan.
## Verification results
| Check | Result |
|-------|--------|
| `go vet ./... && go test -short ./...` | pass (after every commit) |
| `go test ./modules/postcard/... ./modules/lagoon/... ./modules/pact/...` (Docker) | pass |
| `TestMailOverrideSmoke`, `TestMailPartialsSmoke`, `TestMailEditorSmoke`, `TestMailBrandSmoke` | pass, no skips without `-short` |
| `go test ./cmd/summer -run 'TestCommandsDocumented\|TestDocsTree'`, `summer docs:build --check` | pass ("no problems found") |
| `cd examples/hello && go test ./...` | pass |
| sm-user-plugin `TestMail\|TestPolishMailSubjects` | pass, working tree unchanged |
| sm-paymentgateway-plugin `TestMailCatalog\|TestMailTracer\|TestMailersMatrixSmoke` | pass, working tree unchanged |
| Every task's acceptance criteria | pass |
| Tracer gate after Task 2 (interactive, end-of-phase, automated-only verify) | re-run, pass, continued without a checkpoint |
Not committed, run once as a scratch check: the placeholder walker rendered all 172 real template files found in the sibling plugin repositories without error (research Pitfall 3).
## Names for 35-02, 35-03 and 35-04
Every name fixed by P35-01..P35-05 is as the plan states. Names and behaviours the plan left open, or where the code is more specific than the plan's text:
- **Partial token:** `MAILPARTIAL` + 32 upper-case hex digits + `X<n>X` (the plan wrote `MAILPARTIAL<nonce><n>`); the terminator keeps one token from being a prefix of another.
- **Index on templates:** `system_mail_templates_layout_id_index`.
- **`postcard.Kind` values:** `"template"`, `"layout"`, `"partial"`, `"brand"`.
- **`DraftError.Rule` values:** `parse`, `render`, `unsafe`, `subject_line`, `layout`, `partial`, `no_content`, `colour`. A `partial` call with an odd argument count or a non-string key is `render`, not `partial`; `partial` is only "no such partial" and sets `Name`.
- **`DraftError.Field` for Branding:** the colour's column name (`body_bg` ... `table_border_color`); `Message` is empty for `colour`, `layout`, `no_content` and `subject_line`.
- **`Draft`:** `Layout` empty on a template draft keeps the file's layout. A layout draft with an empty `Name` is rendered under the code `draft`. A Branding draft uses `Draft.Brand`; nil is the default brand.
- **Template drafts need a catalog template:** `Validate` and `Preview` of a `KindTemplate` draft whose `Name` is not registered return rule `render` on `body`.
- **`TemplateLocale`:** matches the longest listed locale after a dash in the last dotted segment, ignoring case, and returns it as spelled in `locales` (so `-pt-BR` works).
- **`FormatLayout`:** a non-empty `css` is appended as a fourth `==` section, for display and comparison only (layout files have no CSS section).
- **`SyncIndex`:** serialized by `pg_advisory_xact_lock(hashtext('summercms.postcard.sync'))`; a row that already matches is not written, so `updated_at` does not move. It returns an error when the tables are missing (35-02 retries on the first list request, as planned).
- **`ResetOverride`:** returns an error for a code the catalog does not hold, for a database-only layout, for `KindBrand`, and when no file-backed row has that code.
- **Layout name:** `SyncIndex` always sets `name` from the file header for file layouts and partials, as the plan says, so `name` is not an override column for them.
- **Sample message:** `assets/sample.htm`, parsed as `postcard::mail.sample`; it is not registered in the catalog and cannot be sent by name.
- **Smoke test names:** `TestMailOverrideSmoke`, `TestMailPartialsSmoke`, `TestMailEditorSmoke`, `TestMailBrandSmoke`. The `-run` patterns in 35-VALIDATION.md (`TestOverride`, `TestStore`, `TestPartial`, `TestSample`, `TestValidateDraft`, `TestBrand`, `TestSync`) match none of them; 35-04 either adds tests under those names or updates the map.
- **Test helper:** `mailPostgres(t)` in `override_smoke_test.go` gives each caller a fresh migrated database on one shared container.
## Decisions Made
- **The override-failure log is written only when the file version then renders.** The plan orders "log, then render the file version". When both renders fail (a caller subject with a line break, for example) the cause is the caller's, so the file version's error is returned and nothing claims a file version was sent.
- **`Validate` checks a template body's source for script, iframe, object and embed tags** in addition to the rendered output. Markdown drops such a tag silently at send, so without the source check the behaviour the plan lists ("`<script>` gives rule unsafe") could not occur for a template body.
- **Branding is part of the file version.** `Overrides.empty()` ignores `Brand`, and the fallback render keeps the compiled CSS and logo.
- **Logo problems travel as warnings on `Overrides`** (an unexported field) and are logged by the mailer through its rate limiter, so the source needs no logger. The files table is read under a savepoint, so a failure there does not lose the other overrides.
- **`NewDBSource` silences GORM's logger for its own queries.** The mailer reports a failed lookup once a minute; GORM's line per send would repeat it.
- **Typed errors keep send texts unchanged.** `renderError`, `tmplError`, `unsafeError` and `partialError` print what the old `fmt.Errorf` calls printed.
## Deviations from Plan
### Auto-fixed Issues
None. No bug, missing critical piece or blocker outside the plan's text came up.
### CLAUDE.md-driven adjustments
**1. [Rule 2 - CLAUDE.md] No separate RED commits for the `tdd="true"` tasks**
- **Found during:** Tasks 3, 4 and 5
- **Issue:** The MSD TDD flow commits a failing test first. CLAUDE.md requires `go vet` and `go test` green at every commit, and the plan's "Execution units" table fixes one commit per task.
- **Adjustment:** Tests were written before the implementation and each task was committed once, green.
- **What was and was not observed:** For Task 3 and Task 5 the test was run against signature-only stubs first and every target subtest failed on its assertions. For **Task 4 no RED run was observed**: the implementation was written straight after the test file and passed on the first run. To check that those tests can fail, five mutations were applied afterwards (placeholder format, sync overwriting a customized subject, sync always writing, hash without CRLF normalization, editor keeping the stored template override); each was caught by the expected subtest and reverted. No `tdd-red-evidence` records were persisted.
### Plan inconsistencies (reported, not changed)
- **`key_links` names `modules/postcard/brand.go` for `attach.AbsolutePublicURL`.** The Task 5 action and its acceptance criterion put the call in `NewDBSource`, so it is in `modules/postcard/store.go`. `brand.go` does not contain the pattern; a mechanical key-link check will report it.
- **`pact.ListRowStates` doc comment now says five constants are kept**, as the plan instructs. cabana's `rowStateOrder` still lists three and drops the two new ones until 35-02 changes it; `docs/backend/lists-and-filters.md` still describes three and is 35-02's to update.
---
**Total deviations:** 1 CLAUDE.md-driven adjustment (commit shape of TDD tasks), 0 auto-fixes.
**Impact on plan:** None on scope or API. The TDD evidence is weaker than the MSD reference asks for on Task 4.
## Issues Encountered
- **One unrelated test failure under load.** `modules/pier` `TestStatelessFanOut` failed once in the first full `go test -short ./...` run and passed alone and in five later full runs. Logged in `deferred-items.md`; not investigated.
- **A hung background command of my own.** A mutation-check script stalled on the shell's interactive `cp` alias while `modules/postcard/samples.go` held a deliberate mutation. I stopped that script (my own two processes), restored the file from the backup taken at the start of the script, confirmed all four backed-up files were identical to their backups, and re-ran the checks non-interactively. Nothing mutated was committed.
- **A concurrent commit on master.** Another session committed `f8fa0f1` between Task 4 and Task 5. It touches only Phase 31 planning files.
## Threat Flags
| Flag | File | Description |
|------|------|-------------|
| threat_flag: mail-relay | modules/postcard/editor.go | `Editor.SendDraft` delivers to whatever single address it is given and applies no recipient rule or rate limit. The plan assigns both to the caller (35-02: the admin's own address, 5 per 10 minutes); until that route exists nothing calls it. |
| threat_flag: dependency-surface | modules/postcard/store.go | postcard now imports `modules/lagoon/attach` (as the plan specifies), which brings gocloud blob and the imaging packages into postcard's import graph. No new module in go.mod. |
The threat register's mitigations are in place: validateHTML on bodies, partial outputs and the final HTML (T-35-01); per-render crypto/rand nonce (T-35-02); CR/LF refusal and rule `subject_line` (T-35-03); strict hex colours and the closing-style check on layout CSS (T-35-04); file version on any lookup error (T-35-05); scrubbed `DraftError.Message` (T-35-06); logo URL from operator config only (T-35-07); no cache (T-35-08).
## Known Stubs
None.
## User Setup Required
None. No external service or new configuration key. An application picks up the new tables with its next `migrate`.
## Next Phase Readiness
- 35-02 can build on the API as listed in its `<interfaces>` block; its precondition (`feat(postcard): mail branding and the logo URL` in the log, `func EditorFrom` in `editor.go`) holds.
- 35-02 owns: cabana's `rowStateOrder`, messages and `docs/backend/lists-and-filters.md` for the two new row states; the serve-start `SyncIndex` call; the recipient rule and rate limit around `SendDraft`.
- Nothing was pushed or tagged. No file in a sibling repository was changed.
## Self-Check: PASSED
- All 18 created files exist on disk.
- Commits `7e5d2c7`, `5df1ec2`, `495319e`, `935e4bf`, `2bf9081` are in `git log`.
- `must_haves.artifacts` patterns are present in their files; of the four `key_links`, three match and the `brand.go` one does not (see "Plan inconsistencies").
---
*Phase: 35-mail-templates-and-layouts-editor*
*Completed: 2026-11-13*

View File

@@ -0,0 +1,472 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 02
type: execute
wave: 2
depends_on: ["35-01"]
files_modified:
- modules/cabana/backend_screens.go
- modules/cabana/mail_admin.go
- modules/cabana/mail_diff.go
- modules/cabana/mail_routes.go
- modules/cabana/field_mail.go
- modules/cabana/http.go
- modules/cabana/form_schema.go
- modules/cabana/crud.go
- modules/cabana/settings.go
- modules/cabana/query.go
- modules/cabana/messages.go
- modules/cabana/relation_field.go
- modules/cabana/admin_openapi.go
- modules/cabana/mail_screens_smoke_test.go
- modules/cabana/phase10_coverage_test.go
- modules/cabana/openapi_conformance_test.go
- modules/cabana/security_coverage_test.go
- modules/cabana/token_routes_test.go
- modules/cabana/backendscreens/controllers/mailtemplates/config_form.yaml
- modules/cabana/backendscreens/controllers/mailtemplates/config_list.yaml
- modules/cabana/backendscreens/controllers/mailtemplates/config_filter.yaml
- modules/cabana/backendscreens/controllers/mailtemplates/_info.htm
- modules/cabana/backendscreens/controllers/mailtemplates/_file_version.htm
- modules/cabana/backendscreens/controllers/maillayouts/config_form.yaml
- modules/cabana/backendscreens/controllers/maillayouts/config_list.yaml
- modules/cabana/backendscreens/controllers/maillayouts/config_filter.yaml
- modules/cabana/backendscreens/controllers/maillayouts/_info.htm
- modules/cabana/backendscreens/controllers/maillayouts/_file_version.htm
- modules/cabana/backendscreens/controllers/mailpartials/config_form.yaml
- modules/cabana/backendscreens/controllers/mailpartials/config_list.yaml
- modules/cabana/backendscreens/controllers/mailpartials/config_filter.yaml
- modules/cabana/backendscreens/controllers/mailpartials/_info.htm
- modules/cabana/backendscreens/controllers/mailpartials/_file_version.htm
- modules/cabana/backendscreens/controllers/mailimages/config_form.yaml
- modules/cabana/backendscreens/models/mailtemplate/fields.yaml
- modules/cabana/backendscreens/models/mailtemplate/columns.yaml
- modules/cabana/backendscreens/models/maillayout/fields.yaml
- modules/cabana/backendscreens/models/maillayout/columns.yaml
- modules/cabana/backendscreens/models/mailpartial/fields.yaml
- modules/cabana/backendscreens/models/mailpartial/columns.yaml
- modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml
- modules/cabana/backendscreens/models/mailimagelibrary/fields.yaml
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- modules/surf/serve.go
- modules/surf/README.md
- admin/openapi/admin.json
- admin/src/api/schema.d.ts
- modules/cabana/README.md
- docs/backend/forms.md
- docs/backend/settings.md
- docs/backend/users-and-permissions.md
- docs/backend/lists-and-filters.md
- docs/services/mail.md
- docs/services/rate-limiting.md
autonomous: true
requirements: [D-01, D-02, D-03, D-04, D-05, D-06, D-07, D-08, D-09, D-10, D-13, D-16, D-17, D-18, D-19, D-23, D-25]
estimate:
tokens: 210000
raw_tokens: 210000
tasks: 4
confidence: low
must_haves:
truths:
- "Every app whose postcard Mailer is published gets five Settings → Mail entries (Mail templates, Mail layouts, Mail partials, Mail branding, Mail images) from cabana's internal pseudo-plugin, with no top-level navigation item and no app or plugin setup (D-01, D-02)"
- "cabana registers `system.manage_mail_templates` (templates list/form, template preview and test send) and `system.manage_mail_layouts` (layouts, partials, Branding, image library) with no role grants; a holder of only the templates code sees one tile and gets 403 on layouts, partials, Branding, image upload and layout or partial preview; the image list and picker answer either code (D-03)"
- "Every file template, layout and partial appears as a row after serve start (postcard.SyncIndex through lagoon.OnDatabase, retried on the first list request when the tables were missing); rows absent from this process's catalog are hidden, database-only layouts are always listed (D-23, D-08)"
- "The templates list shows code, effective subject, description, locale (suffix or Default) and layout, with a locale filter and a Customized / Not customized / File changed status filter; the empty view shows the UI-SPEC empty-state text (D-05, D-25)"
- "Saving a template stores subject, Markdown body and layout (a dropdown over file and custom layouts) as the override, stamps base_hash from the current file hash, and runs postcard's draft validation inside the save transaction; a failure is a 422 field line with the translated rule text and :message, and nothing is saved (D-04, D-13)"
- "Reset to file version, a record action on customized template, file layout and partial rows, clears the override columns and re-mirrors the file; custom layouts are created with a lowercase-dash code and deleted, a delete of one still used by customized templates is a 403 naming the layout and the count, and file rows can never be deleted (D-06 as amended by D-23, D-08)"
- "A customized row whose file changed carries the `customized` and `outdated` row states, the File changed filter finds it, the form shows the drift callout and a File version tab with a line diff of the serialized override against the file, and saving again clears the drift (D-07)"
- "Layouts and partials are edited in the new built-in `codeeditor` field type (`language: html | css | text`, optional size and mailImages), registered in cabana's field registry and the form schema; the layout form has HTML, Plain text, CSS and File version tabs (D-09)"
- "The Branding page is a cabana settings form on system_mail_brand_settings with the 13 colours as `colorpicker` fields and the logo as a `mailimage` field; an invalid colour is a 422 field line, and saving it is what switches mail from mail.brandCss to the compiled colours (D-10, D-11)"
- "Mail images is a singleton screen whose fileupload stores public images through lagoon/attach; GET/POST /mail/images return absolute public URLs from config and refuse with a clear message when neither storage.uploads.public_url nor app.url is set (D-18, D-19, D-24)"
- "POST /mail/preview renders the unsaved draft (template, layout, partial or branding mode) through postcard's Editor with sample values and returns subject, HTML and text; POST /mail/test-send sends the draft only to the signed-in administrator's own email, refuses any recipient in the body, needs the record kind's permission, is interactive-session only and answers 429 with Retry-After after 5 sends per 10 minutes per administrator (D-16, D-17)"
- "admin/openapi/admin.json and admin/src/api/schema.d.ts are regenerated from the annotations, the route inventories list the new routes, and the cabana README and docs pages describe every new screen, permission, route and field type in the same commits (D-21)"
prohibitions:
- statement: "No role is granted system.manage_mail_templates or system.manage_mail_layouts in code or migrations."
status: unresolved
verification: judgment
- statement: "The test-send route accepts no recipient: the address is always the signed-in administrator's own email."
status: unresolved
verification: judgment
- statement: "cabana's mail models carry no postcard rendering logic of their own: validation, preview and sends go through postcard.Editor so previews match real sends."
status: unresolved
verification: judgment
- statement: "Existing controllers see no behaviour change: meta.deletable is omitted unless a mail controller sets it, and the three existing row states keep their order and rendering."
status: unresolved
verification: judgment
- statement: "Framework code, READMEs and docs name no consuming application."
status: unresolved
verification: judgment
artifacts:
- path: "modules/cabana/mail_admin.go"
provides: "mail models, controllers, hooks, row states, reset action, delete refusal"
contains: "PermissionManageMailTemplates"
- path: "modules/cabana/mail_routes.go"
provides: "preview, test-send and image library routes"
contains: "func (s *service) mailTestSend("
- path: "modules/cabana/mail_diff.go"
provides: "bounded LCS line diff for the File version tab"
contains: "func lineDiff("
- path: "modules/cabana/field_mail.go"
provides: "codeeditor, colorpicker, mailimage, mailpreview schema checks"
contains: "codeeditor"
- path: "modules/cabana/mail_screens_smoke_test.go"
provides: "TestMailScreensSmoke (tracer and expansion subtests)"
contains: "func TestMailScreensSmoke("
- path: "modules/cabana/backendscreens/controllers/mailtemplates/config_list.yaml"
provides: "templates list"
contains: "mail.template.list_title"
key_links:
- from: "modules/cabana/mail_admin.go"
to: "modules/postcard/editor.go"
via: "FormAfterUpdate validates through postcard.Editor.Validate"
pattern: "\\.Validate\\(ctx"
- from: "modules/cabana/http.go"
to: "modules/postcard/store.go"
via: "serve-start index sync"
pattern: "postcard\\.SyncIndex"
- from: "modules/cabana/mail_routes.go"
to: "modules/cooler/cooler.go"
via: "per-admin test-send limit through cooler.Attempter, published by surf"
pattern: "cooler\\.Attempter"
- from: "modules/cabana/backend_screens.go"
to: "modules/cabana/mail_admin.go"
via: "pseudo-plugin AdminControllers, Permissions and Settings include the mail screens when postcard.EditorFrom succeeds"
pattern: "postcard\\.EditorFrom"
---
## Phase Goal
ROADMAP Goal (not in user-story format; no story is invented): administrators edit every mail the application sends from the admin panel, as in WinterCMS's Mail templates screen. This plan delivers the server side of the screens on top of 35-01's postcard API: the Settings → Mail entries, two permissions, the templates, layouts and partials screens with reset and drift, Branding, the image library, and the preview and test-send routes the SPA (35-03) calls.
Spec-less probe fallback skipped: no SPEC.md and no requirement IDs; must_haves derive from the ROADMAP goal and CONTEXT D-01..D-25. Names come from 35-01's Task 1 answer (read 35-01-SUMMARY.md; where it differs from this text, the SUMMARY wins).
<objective>
Add the mail screens to cabana's internal pseudo-plugin (D-01, the 19.6.1 pattern):
- templates, layouts, partials and image library controllers over postcard's tables, Branding as a settings model (D-02, D-08, D-10, D-18);
- the two permission codes with no default grants and the picker split (D-03);
- override save with validation, reset, custom layouts with in-use delete refusal, drift states, filters and the File version diff (D-04..D-08, D-13, D-23);
- the built-in field types codeeditor, colorpicker, mailimage and mailpreview on the server (D-09, UI-SPEC C1, C2, C10, C11);
- preview, test-send and image library routes with OpenAPI annotations (D-16, D-17, D-19);
- all UI-SPEC copy in en and pl, the cabana README and docs.
Purpose: 35-03 renders these screens with the generic SPA views plus four field controls; every rule that protects mail (permissions, validation, recipient, rate limit) lives here on the server.
Output: commits in this repository only. Nothing is pushed or tagged.
**Planner decisions recorded here:**
- The mail screens, permissions and settings entries are added only when `postcard.EditorFrom(app)` succeeds (always true in an application, since party.Activate runs postcard.Activate; false in cabana tests that never activate postcard, which therefore see no change).
- Image picker: list and pick for holders of either mail code; upload only for `system.manage_mail_layouts` (D-03 planner's call, UI-SPEC C4 recommendation).
- Test-send limit: 5 per administrator per 10 minutes, key `mail_test:<adminID>`, through `cooler.Attempter` when surf publishes one (Redis store), otherwise an in-process fixed window in cabana (research Pattern 7, A6, A7).
- The custom-layout create form is prefilled from postcard's default layout, injected into the compiled form schema at Activate, so the YAML carries no copy of it (UI-SPEC C5).
- New copy key beyond the UI-SPEC: `mail.images.no_public_url` (EN "Mail images need an absolute address. Set storage.uploads.public_url or app.url in the configuration." PL "Obrazy w wiadomościach wymagają pełnego adresu. Ustaw storage.uploads.public_url lub app.url w konfiguracji.").
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/35-mail-templates-and-layouts-editor/35-CONTEXT.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-RESEARCH.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-PATTERNS.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-01-SUMMARY.md
@.planning/phases/19.6.1-backend-administrators-screen/19.6.1-CONTEXT.md
@CLAUDE.md
<interfaces>
From 35-01 (postcard): Migrations and table constants TemplatesTable, LayoutsTable, PartialsTable, BrandTable, ImageLibraryTable; SyncIndex(ctx, db, cat, locales); ResetOverride(ctx, db, cat, kind, code); EditorFrom(app) (*Editor, bool); Editor.Catalog() / Validate(ctx, Draft) *DraftError / Preview(ctx, Draft) (Preview, error) / SendDraft(ctx, Draft, to); Draft{Kind, Name, Subject, Body, Layout, HTML, Text, CSS, Brand}; Kind consts KindTemplate|KindLayout|KindPartial|KindBrand; DraftError{Field, Rule, Message, Name}; Catalog.Template|Layout|Partial(name) and Templates|Layouts|Partials(); TemplateFile/LayoutFile/PartialFile{..., Source, Hash}; FormatTemplate/FormatLayout/FormatPartial; TemplateLocale(name, locales); Brand, DefaultBrand(), CompileBrandCSS(Brand); attach.AbsolutePublicURL(cfg, key), attach.ErrNoAbsoluteURL; pact.RowStateCustomized, pact.RowStateOutdated.
modules/cabana/backend_screens.go: backendScreens pseudo-plugin (ID summercms.cabana; AdminFS from //go:embed all:backendscreens; AdminControllers, Permissions, Settings); permission/controller constants next to PermissionManageUsers; withBackendScreens.
modules/cabana/backend_users_admin.go: the controller to mirror (interface assertions block, ID/ModelName/ConfigDir/RequiredPermissions/NewRecord, db()/requestDB(ctx)/translator(), AdminFieldRelations for a belongsTo, ListRowStates, FormBeforeDelete, AdminRecordActions, PartialData, FormRules); recordDataExtender (crud.go ~699) and schemaFieldHider (http.go ~894) are unexported seams.
modules/cabana/http.go: Activate (~81) appends the pseudo-plugin; route group (~305-445): `g.Post("/markdown/preview", requireAjax(s.markdownPreview))`, interactiveOnly wrapper for account routes.
modules/cabana/field_markdown.go (~50-80): AdminMarkdownPreviewRequest/Result, the bouncer.User + principal.Backend + tokenRouteGate gate, WriteError with fixed msg constants.
modules/cabana/contracts.go: Allows(principal, required) any-of with superuser bypass (~327); BackendUser{ID, Email, ...}.
modules/cabana/form_schema.go (~24-51): formFieldTypes, formFieldKeys; crud.go (~1518) scalarFormField; settings.go (~96-102) settings refusal list and BeforeValidate hook use (~261).
modules/cabana/query.go (~182) rowStateOrder; messages.go (~42, 61, 163) row-state message keys; relation_field.go (~104) RecordMeta.
modules/cabana/administrators_harness_test.go (~154) newScreensEnv: compass config, lagoon.Publish, phrasebook.Activate, surf.Assemble (does not activate postcard).
modules/surf/serve.go (~230) installCooler publishes Store only for the Redis rate-limit store; modules/cooler/cooler.go (~68) Attempter has exactly surf.Store's method set.
Route inventories that list every admin route: modules/cabana/phase10_coverage_test.go, openapi_conformance_test.go, security_coverage_test.go, token_routes_test.go (grep `/markdown/preview` in each).
</interfaces>
</context>
## Execution units and resume points
- Phase 33 edits cabana concurrently. Before each task run `git status --short modules/cabana modules/phrasebook admin/openapi admin/src/api modules/surf` and stop if another session holds uncommitted edits there; re-check the line numbers named in interfaces before editing.
- Each task ends with the commit listed below, staged by explicit path. Resume check: `git log --format=%s -F --grep='<subject>'`.
- Docker-backed subtests run without `-short` (through `sudo -u golem` if the Docker socket is denied).
| Task | Commit subject | Resume point |
|------|----------------|--------------|
| 1 | `feat(cabana): mail templates screen over postcard overrides` | TestMailScreensSmoke/templates passes |
| 2 | `feat(cabana): mail layouts and partials screens with reset, drift and custom layouts` | TestMailScreensSmoke/layouts passes |
| 3 | `feat(cabana): code editor, colour and mail image fields, mail branding and the image library` | TestMailScreensSmoke/branding passes |
| 4 | `feat(cabana): mail preview and test send to yourself` | TestMailScreensSmoke/test_send passes |
<tasks>
<task type="tracer">
<name>Task 1: End-to-end "an administrator with system.manage_mail_templates opens Settings → Mail templates, saves a subject override and the next mail uses it" — templates only</name>
<reversibility rating="costly">D-03: the permission codes end up in backend_user_roles.permissions and backend_users.permissions JSON on every install that grants them.</reversibility>
<precondition>35-01 is complete: `git log --format=%s -F --grep='feat(postcard): mail branding and the logo URL'` prints one line and `grep -n "func EditorFrom" modules/postcard/editor.go` prints one line</precondition>
<files>modules/cabana/backend_screens.go, modules/cabana/mail_admin.go, modules/cabana/http.go, modules/cabana/backendscreens/controllers/mailtemplates/config_form.yaml, modules/cabana/backendscreens/controllers/mailtemplates/config_list.yaml, modules/cabana/backendscreens/models/mailtemplate/fields.yaml, modules/cabana/backendscreens/models/mailtemplate/columns.yaml, modules/cabana/mail_screens_smoke_test.go, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, modules/cabana/README.md, docs/backend/users-and-permissions.md, docs/services/mail.md</files>
<read_first>
- modules/cabana/backend_screens.go (whole file)
- modules/cabana/backend_users_admin.go (~1-200: assertions, identity, helpers, relations, row states, FormBeforeDelete) and backend_roles_admin.go (a smaller controller)
- modules/cabana/backendscreens/controllers/users/config_form.yaml, config_list.yaml and modules/cabana/backendscreens/models/user/fields.yaml, columns.yaml
- modules/cabana/http.go (~80-150 Activate)
- modules/lagoon/ondatabase.go (OnDatabase: queued errors are returned by Publish, so the hook must not return the sync error)
- modules/cabana/administrators_harness_test.go (~142-360 newScreensEnv, seedAdmin, seedRole, login, request)
- modules/postcard/editor.go and modules/postcard/store.go (35-01 output) and .planning/phases/35-mail-templates-and-layouts-editor/35-01-SUMMARY.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md (C3b, C14, Copywriting "Settings entries and permission catalog", "Lists", "Template form")
</read_first>
<action>
Per D-01, D-02, D-03, D-04, D-05, D-13, D-23 and D-25:
- `backend_screens.go`: exported constants `PermissionManageMailTemplates = "system.manage_mail_templates"`, `PermissionManageMailLayouts = "system.manage_mail_layouts"`, `MailTemplatesControllerID = "summercms.cabana.mailtemplates"`, `MailLayoutsControllerID`, `MailPartialsControllerID`, `MailImagesControllerID` (P35-05 names). The pseudo-plugin holds the *postcard.Editor found by `postcard.EditorFrom(app)` when it is built; only then do AdminControllers, Permissions and Settings include the mail parts. In this task: both permission codes (Tab `backend::lang.permissions.tab_system`, Labels `backend::lang.permissions.manage_mail_templates` / `manage_mail_layouts`, no Roles), the templates controller and the settings link `mail_templates` (category `backend::lang.settings.category_mail`, icon `mail`, order 200, Permissions templates code, Controller MailTemplatesControllerID).
- `mail_admin.go`: model `MailTemplate` (TableName postcard.TemplatesTable; columns per P35-01; belongsTo `layout` through layout_id with a minimal `MailLayout` model, TableName postcard.LayoutsTable, enough for the relation and its name column; Fillable subject, body and the layout foreign key) and controller `mailTemplatesAdmin` (ID, ModelName, ConfigDir `controllers/mailtemplates`, RequiredPermissions templates code, NewRecord) with: AdminFieldRelations for `layout` (belongsTo, LabelColumn name) plus pact.RelationExtendOptionsQuery limiting options to layouts present in this process's catalog or database-only; ListExtendQuery and FormExtendQuery hiding template rows whose code is not in the catalog; FormRecordTitle = code; FormBeforeCreate and FormBeforeDelete refusing with ForbiddenError (templates come from files); FormBeforeUpdate stamping is_custom true, base_hash = the catalog file Hash and customized_at = now; FormAfterUpdate building a postcard Draft (KindTemplate, Name code, Subject, Body, Layout = the code of the assigned layout row) and calling Editor.Validate; a *DraftError becomes a ValidationError on its Field with the text of `backend::lang.mail.invalid_<rule>` translated with :message and :name (build it with the translator as account_tokens.go backendMessageParams does, research Pitfall 9).
- Index sync per D-23: in Activate (when the editor exists) register `lagoon.OnDatabase` with a func that calls postcard.SyncIndex with the app's phrasebook translator locales (`Locales("")`, empty when none is published), logs any error through cabana's logger and returns nil; until a sync has succeeded, the first mail list request in the process retries it.
- YAML: controllers/mailtemplates/config_form.yaml (name `backend::lang.mail.template.name`, form `models/mailtemplate/fields.yaml` in the users-controller path style, no create, update redirect to the update form, Save and close to the list, messages per UI-SPEC C3b); config_list.yaml (title `backend::lang.mail.template.list_title`, recordUrl to update, `toolbar.buttons: []`, no checkboxes, recordsPerPage 20, noRecordsMessage `backend::lang.mail.template.list_empty`, default sort code ascending); models/mailtemplate/columns.yaml (code searchable+sortable, subject searchable, description searchable, locale sortable, layout through the relation's name, customized_at invisible sortable); models/mailtemplate/fields.yaml (subject text left required with comment, layout relation right required without an empty option, body markdown size giant, full) — the `_info`, `_preview` and `_file_version` fields and `mailImages` arrive in Tasks 2-4.
- Copy en and pl (UI-SPEC tables, Polish as the design language): `settings.category_mail`, `permissions.manage_mail_templates[_comment]`, `permissions.manage_mail_layouts[_comment]`, the `mail.template.*` keys used here, `mail.code`, `mail.template.locale_default`.
- `mail_screens_smoke_test.go` (package cabana_test): helper `newMailScreensEnv(t)` that follows newScreensEnv but also calls postcard.Activate and postcard.BootPlugin for a fixture plugin `acme.blog` (fstest.MapFS: `mail.welcome`, `mail.welcome-en`, one layout alias) before surf.Assemble, and runs the index sync; `TestMailScreensSmoke/templates`: a superuser lists templates and sees both rows with locale `en` on the suffixed one; GET schema of the form; PUT a new subject on `acme.blog::mail.welcome` gives 200 and is_custom true; the published postcard Mailer then sends that subject; a PUT with a `<script>` body gives 422 with Details.body and leaves the row unchanged; a role holding only system.manage_mail_layouts gets 403 on the templates list; a role holding only the templates code gets 200; no role in the database gained either code; GET /settings shows exactly one Mail tile for the templates-only role.
- Docs in the same commit: cabana README (Mail screens overview, the two permission codes, the controller ID constants, the serve-start sync), docs/backend/users-and-permissions.md (the two codes, no default grant, what each opens), docs/services/mail.md section "Editing mail in the admin" (which screens exist, what is stored, that the override wins until reset).
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/cabana -run 'TestMailScreensSmoke' -count=1 -v 2>&1 | grep -E '^\s*(--- |FAIL|ok|PASS)' | tail -20</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, "no tests to run", or no "--- PASS: TestMailScreensSmoke/templates" line</fails_when>
<automated>go vet ./... && go test -short ./...</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go test ./modules/cabana -count=1 2>&1 | tail -5</automated>
<fails_when>non-zero exit or a "FAIL" line (existing cabana Postgres tests must stay green)</fails_when>
<automated>go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line in the output</fails_when>
</verify>
<acceptance_criteria>
- `grep -n 'PermissionManageMailTemplates = "system.manage_mail_templates"' modules/cabana/backend_screens.go` and `grep -n 'PermissionManageMailLayouts = "system.manage_mail_layouts"' modules/cabana/backend_screens.go` each print one line
- `grep -n "postcard.EditorFrom" modules/cabana/backend_screens.go modules/cabana/http.go` prints at least one line
- `grep -n "postcard.SyncIndex" modules/cabana/*.go | grep -v _test` prints at least one line
- `grep -n "category_mail" modules/phrasebook/backend/lang/en/lang.yaml modules/phrasebook/backend/lang/pl/lang.yaml` prints two lines
- `grep -rn "manage_mail" modules/cabana/*.go | grep -v _test | grep -n "Roles:"` prints nothing
- `grep -n "system.manage_mail_templates" docs/backend/users-and-permissions.md modules/cabana/README.md` prints at least two lines
</acceptance_criteria>
<done>An administrator can find every file template in Settings → Mail templates, save an override that real sends use, and is refused unsafe content and the wrong permission.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: Layouts and partials screens, reset to the file version, custom layouts with the in-use delete refusal, drift states and the File version diff</name>
<reversibility rating="costly">D-07: the drift states read base_hash and file_hash columns; D-08: the custom-layout code is what template overrides store.</reversibility>
<files>modules/cabana/mail_admin.go, modules/cabana/mail_diff.go, modules/cabana/backend_screens.go, modules/cabana/query.go, modules/cabana/messages.go, modules/cabana/relation_field.go, modules/cabana/crud.go, modules/cabana/backendscreens/controllers/mailtemplates/config_form.yaml, modules/cabana/backendscreens/controllers/mailtemplates/config_list.yaml, modules/cabana/backendscreens/controllers/mailtemplates/config_filter.yaml, modules/cabana/backendscreens/controllers/mailtemplates/_info.htm, modules/cabana/backendscreens/controllers/mailtemplates/_file_version.htm, modules/cabana/backendscreens/controllers/maillayouts/config_form.yaml, modules/cabana/backendscreens/controllers/maillayouts/config_list.yaml, modules/cabana/backendscreens/controllers/maillayouts/config_filter.yaml, modules/cabana/backendscreens/controllers/maillayouts/_info.htm, modules/cabana/backendscreens/controllers/maillayouts/_file_version.htm, modules/cabana/backendscreens/controllers/mailpartials/config_form.yaml, modules/cabana/backendscreens/controllers/mailpartials/config_list.yaml, modules/cabana/backendscreens/controllers/mailpartials/config_filter.yaml, modules/cabana/backendscreens/controllers/mailpartials/_info.htm, modules/cabana/backendscreens/controllers/mailpartials/_file_version.htm, modules/cabana/backendscreens/models/mailtemplate/fields.yaml, modules/cabana/backendscreens/models/maillayout/fields.yaml, modules/cabana/backendscreens/models/maillayout/columns.yaml, modules/cabana/backendscreens/models/mailpartial/fields.yaml, modules/cabana/backendscreens/models/mailpartial/columns.yaml, modules/cabana/mail_screens_smoke_test.go, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, modules/cabana/README.md, docs/backend/lists-and-filters.md, docs/services/mail.md</files>
<read_first>
- modules/cabana/mail_admin.go and mail_screens_smoke_test.go (Task 1 output)
- modules/cabana/backend_users_admin.go (~178-200 ListRowStates, ~199 FormBeforeDelete, ~325 AdminRecordActions, ~422 PartialData) and modules/cabana/backendscreens/controllers/users/config_filter.yaml, _hint.htm
- modules/cabana/partial_render.go (~105-118 allowlist) and modules/cabana/account_tokens.go (~200-230 backendMessageParams)
- modules/cabana/query.go (~160-200), modules/cabana/messages.go (~35-70, ~150-170), modules/cabana/relation_field.go (~95-120), modules/cabana/crud.go (show response that fills RecordMeta.Actions)
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md (C5, C6, C7, C8 items 1-2, C9, C15, Copywriting "Layout form", "Partial form", "Info partial and drift notice", "Record actions and destructive confirmations")
</read_first>
<behavior>
- Layouts list shows postcard's default first, then by name, including system, minimal, the fixture plugin layout and database-only layouts (source shown as Custom); partials list shows the four built-ins and the fixture plugin partial
- Creating a layout with code `promo-2026` and the default layout content succeeds (is_custom true, source NULL); code `Promo 2026` gives 422 mail.layout.code_format on code; a taken code gives mail.layout.code_taken
- Saving a file layout's HTML without {{ .Content }} gives 422 on content_html with the no_content text; saving a valid change marks it customized and the next send uses it
- A template override pointing at the custom layout, then DELETE of that layout: 403 whose message names the layout and the count 1 (CLDR one form); after resetting the template, the delete succeeds; DELETE of a file layout, a template or a partial is 403
- Record action reset on a customized template restores the file subject, body and layout, clears is_custom, and the record's meta.actions no longer offers reset; reset is not offered on a not-customized row nor on a custom layout
- meta.deletable is false for templates, partials and file layouts, true for custom layouts, and absent for every existing controller
- After changing the fixture file's bytes and re-syncing, the customized row carries row states [customized, outdated], the status filter `outdated` returns it, `_info` contains the drift callout and `_file_version` contains summer-diff__add and summer-diff__del lines; saving the row again clears outdated
- lineDiff with 3 lines of context returns the expected add/del/ctx sequence for a small pair and returns no diff (content block only) above the line cap
</behavior>
<action>
Per D-06 (as amended by D-23), D-07, D-08 and D-12 (admins override and reset partials):
- Models `MailLayout` (full columns) and `MailPartial`; controllers `mailLayoutsAdmin` (ConfigDir controllers/maillayouts, RequiredPermissions layouts code) and `mailPartialsAdmin` (controllers/mailpartials, layouts code), with the same catalog-membership query scoping (database-only layouts always included), stamping in FormBeforeUpdate and postcard validation in FormAfterUpdate (KindLayout with Name = code for file layouts and the custom code otherwise; KindPartial) as Task 1. Layouts: create allowed only for custom layouts (FormBeforeCreate checks the code against `^[a-z0-9-]+$` and uniqueness with mail.layout.code_format / code_taken, sets source NULL and is_custom true); code is create-only (hidden and not writable on update through schemaFieldHider and the update rules); default sort default layout first, then name. Partials: no create, no delete.
- Record action `reset` on all three controllers (Label `backend::lang.mail.reset`, Confirm the kind's `mail.<kind>.reset_confirm`, Danger true, Permissions the controller's code, Applies when the row is file-backed and is_custom) whose Run calls postcard.ResetOverride on the action transaction and returns Message `backend::lang.mail.reset_done`. The templates, layouts and partials config_form.yaml declare `recordActions: [reset]`.
- Delete: FormBeforeDelete refuses file-backed rows with ForbiddenError, and a custom layout still referenced by template rows with a ForbiddenError whose Message is `backend::lang.mail.layout.delete_in_use` translated with :name and the CLDR plural for :count (UI-SPEC C15 note: never a ValidationError). The FK ON DELETE RESTRICT stays as the backstop.
- `meta.deletable`: add `Deletable *bool` with json `deletable,omitempty` to RecordMeta and fill it in the show response only for controllers implementing a new unexported cabana interface (mail controllers): false for templates, partials and file layouts, true for custom layouts.
- Row states: rowStateOrder becomes deleted, negative, disabled, customized, outdated; messages.go gains RowStateCustomized / RowStateOutdated (yaml `rowStateCustomized`, `rowStateOutdated`, defaults `backend::lang.messages.list.row_state_customized` / `row_state_outdated`, json keys in the list messages schema); the mail controllers' ListRowStates give customized for is_custom file-backed rows and also outdated when base_hash differs from file_hash; the three config_list.yaml files set `rowStateCustomized: backend::lang.mail.state_customized` and `rowStateOutdated: backend::lang.mail.state_outdated`.
- Filters (config_filter.yaml, scope type with options as the users `trashed` filter): templates `locale` (default plus one option per locale value found, through pact.FilterOptions) and `status` (customized, not_customized, outdated); layouts and partials `status`. Outdated SQL per P35-01.
- Partials `_info.htm` and `_file_version.htm` for each controller (allowlisted tags only; UI-SPEC C7 content and order; the partial usage line shows the exact P35-02 call, a bare name for postcard built-ins and the full name otherwise; variables line lists the file's sample names), fed by PartialData with curated view models (never a GORM model). `mail_diff.go`: `lineDiff(a, b []string, context int) []diffLine` (stdlib LCS, cap 2000 lines per side, above which only the file content block is shown); both sides serialized with postcard.FormatTemplate / FormatLayout / FormatPartial; the content block shows the catalog Source.
- Template fields.yaml gains `_info` (partial, first, full) and `_file_version` (partial, tab `backend::lang.mail.tab_file_version`, context update); layouts and partials fields.yaml per UI-SPEC C5/C6, using `type: textarea` for content_html, content_text and content_css in this task (Task 3 switches them to codeeditor).
- Copy en and pl for every key used: `mail.layout.*`, `mail.partial.*`, `mail.name_field`, `mail.source`, `mail.source_custom`, `mail.customized_at`, the filter and state keys, `mail.info_*`, `mail.drift_*`, `mail.file_*`, `mail.reset`, `mail.reset_done`, the reset confirms, `mail.layout.delete_in_use` (CLDR maps), `mail.invalid_*`, `mail.layout.code_*`, `messages.list.row_state_customized` / `row_state_outdated`.
- Write the behavior subtests first in mail_screens_smoke_test.go (`layouts`, `partials`, `reset`, `delete`, `drift`, `deletable`, `diff`), then implement.
- Docs in the same commit: cabana README (layouts and partials screens, reset, custom layouts, RecordMeta.Deletable, the two new row states), docs/backend/lists-and-filters.md "Row state" (customized and outdated), docs/services/mail.md (layouts, partials, reset and the drift notice in the admin).
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/cabana -run 'TestMailScreensSmoke' -count=1 -v 2>&1 | grep -E '^\s*(--- |FAIL|ok|PASS)' | tail -30</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, "no tests to run", or no "--- PASS: TestMailScreensSmoke/drift" or "--- PASS: TestMailScreensSmoke/delete" line</fails_when>
<automated>go vet ./... && go test -short ./... && go test ./modules/cabana -count=1 2>&1 | tail -5</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line in the output</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "pact.RowStateCustomized, pact.RowStateOutdated" modules/cabana/query.go` prints one line
- `grep -n 'json:"deletable,omitempty"' modules/cabana/relation_field.go` prints one line
- `grep -n "postcard.ResetOverride" modules/cabana/mail_admin.go` prints at least one line
- `grep -n "func lineDiff(" modules/cabana/mail_diff.go` prints one line
- `grep -c "recordActions: \[reset\]" modules/cabana/backendscreens/controllers/mail*/config_form.yaml | grep -c ':1'` prints 3
- `grep -n "delete_in_use" modules/phrasebook/backend/lang/pl/lang.yaml -A 5 | grep -E "few|many"` prints at least two lines
</acceptance_criteria>
<done>Admins can customize, reset and review drift on templates, layouts and partials, create and safely delete their own layouts, and every list shows which records differ from the files.</done>
</task>
<task type="auto" tdd="true">
<name>Task 3: New field types on the server, the Branding page and the mail image library with absolute URLs</name>
<reversibility rating="costly">D-09: `codeeditor` (and colorpicker, mailimage, mailpreview) become published field type names in fields.yaml that plugins may start using.</reversibility>
<files>modules/cabana/field_mail.go, modules/cabana/form_schema.go, modules/cabana/crud.go, modules/cabana/settings.go, modules/cabana/mail_admin.go, modules/cabana/mail_routes.go, modules/cabana/http.go, modules/cabana/backend_screens.go, modules/cabana/admin_openapi.go, modules/cabana/backendscreens/models/mailtemplate/fields.yaml, modules/cabana/backendscreens/models/maillayout/fields.yaml, modules/cabana/backendscreens/models/mailpartial/fields.yaml, modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml, modules/cabana/backendscreens/models/mailimagelibrary/fields.yaml, modules/cabana/backendscreens/controllers/mailimages/config_form.yaml, modules/cabana/mail_screens_smoke_test.go, modules/cabana/phase10_coverage_test.go, modules/cabana/openapi_conformance_test.go, modules/cabana/security_coverage_test.go, modules/cabana/token_routes_test.go, admin/openapi/admin.json, admin/src/api/schema.d.ts, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, modules/cabana/README.md, docs/backend/forms.md, docs/backend/settings.md</files>
<read_first>
- modules/cabana/form_schema.go (~20-60 and the per-type key checks), modules/cabana/crud.go (~1510-1540 scalarFormField, valueFormField), modules/cabana/settings.go (~70-140, ~200-280)
- modules/cabana/field_file.go and modules/cabana/field_type_upload.go (how fileupload attaches to a record: attachment_type, field, is_public, limits), modules/cabana/singleton.go (~41-80)
- modules/cabana/example_settings_test.go (settings registration example) and modules/cabana/admin_openapi.go (swag block style, ~460-480)
- modules/lagoon/attach/store.go (~60-125 Upload, Limits, Store) and modules/lagoon/attach/absolute.go (35-01)
- scripts/check-admin-openapi.sh
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md (C1, C2, C4 permission, C11, C12, C13, C14, C15, Copywriting "Image picker and image fields", "Code editor and colour picker", "Branding page")
</read_first>
<behavior>
- A fields.yaml with `type: codeeditor` and `language: html` compiles; `language: php` or a missing language is a boot error naming controller, field and value; `mailImages: true` is accepted on markdown and codeeditor and is a boot error elsewhere; colorpicker with `availableColors` is a boot error (unknown key)
- The form schema JSON carries `language` and `mailImages` for those fields; codeeditor, colorpicker and mailimage values bind to their columns and round-trip through PUT
- GET /settings/mail_brand on a fresh database returns exists false with the UI-SPEC Winter defaults; PUT with `button_primary_bg: "#D66829"` stores `#d66829` and creates row 1; PUT with `red` gives 422 colorpicker.invalid on that field; PUT with a logo_file_id that is not a library image gives 422 mailimage.missing; before the first PUT a send still uses mail.brandCss and after it the compiled CSS
- GET /mail/images as a templates-only holder lists library images with absolute URLs and meta.canUpload false; as a layouts holder canUpload is true; POST /mail/images as a templates-only holder is 403; as a layouts holder with a PNG it is 201 with an absolute URL and the image is attached to the library row; a non-image upload is 422; with neither storage.uploads.public_url nor app.url configured both routes answer with the mail.images.no_public_url message; GET /mail/images/{id} of an image outside the library is 404
- The Mail images singleton form opens for a layouts holder and shows the images fileupload; it is 403 for a templates-only holder
</behavior>
<action>
Per D-09, D-10, D-11, D-18, D-19, D-20 (server half) and D-24:
- `form_schema.go`: add `codeeditor`, `colorpicker`, `mailimage`, `mailpreview` to formFieldTypes and `language`, `mailImages` to formFieldKeys (mode and size exist); `field_mail.go` holds the checks: codeeditor language in html|css|text (required), mailImages boolean only on markdown and codeeditor, mailpreview mode in template|layout|partial|branding (required), and serializes `language` and `mailImages` into the field schema JSON. `crud.go` scalarFormField also returns true for codeeditor, colorpicker and mailimage; mailpreview is valueless (never bound, never accepted in a save body). `settings.go`: colorpicker, mailimage and mailpreview are allowed on settings forms (not in the refusal list); mailpreview is skipped from Writable.
- Switch the layout and partial content fields to codeeditor per UI-SPEC C5/C6 (html giant with mailImages, text huge, css huge with mailImages; partial html huge with mailImages, text large) and the template body to `mailImages: true`. Inject the create defaults of the layouts form (content_html, content_text, content_css) from the editor's catalog default layout into the compiled form schema at Activate.
- Branding: model `MailBrandSetting` (TableName postcard.BrandTable, the 13 colour columns and logo_file_id, Fillable all of them, Rules all nullable) with a BeforeValidate that lower-cases colours, refuses anything but `^#[0-9a-f]{6}$` or empty with a ValidationError on that field (`backend::lang.colorpicker.invalid`) and checks logo_file_id is null or an image in the library (`backend::lang.mailimage.missing`); settings item `mail_brand` (Label `backend::lang.mail.brand.menu_label`, Description `..._description`, category mail, icon palette, order 230, Permissions layouts code, Form `models/mailbrandsetting/fields.yaml`, NewModel); fields.yaml per UI-SPEC C12 (logo mailimage full, colours colorpicker in the row order with the Winter defaults as `default:`; the `_preview` mailpreview arrives in Task 4).
- Image library: model `MailImageLibrary` (TableName postcard.ImageLibraryTable) with an attachMany `images` relation, public; controller `mailImagesAdmin` implementing pact.AdminSingleton (first-or-create, as singleton.go), ConfigDir controllers/mailimages, RequiredPermissions layouts code, form fields.yaml with `images` fileupload mode image, useCaption true, fileTypes jpg,jpeg,png,gif,webp, maxFilesize 5 MB (planner's value; within http.body_limits.upload_bytes); settings link `mail_images` (icon image, order 240, layouts code, Controller MailImagesControllerID). Also add the settings links `mail_layouts` (icon layout-grid, order 210) and `mail_partials` (icon puzzle, order 220), both layouts code.
- `mail_routes.go` image routes (backend group, auth gate as markdownPreview): `GET /mail/images` (query q, page; 40 per page; filename or title match; newest first; allowed for either code via Allows; item `AdminMailImage{ID, FileName, Title, URL, ThumbURL}` with URL from attach.AbsolutePublicURL on the blob key; meta `canUpload` = Allows(layouts), total, page, perPage), `GET /mail/images/{id}` (404 outside the library), `POST /mail/images` (requireAjax, layouts code only, multipart `file`, attach.Store with Public true and image limits, then attached to the library row as the fileupload field does; 201 with the item). When attach.ErrNoAbsoluteURL, answer 409 with the localized `mail.images.no_public_url` message. swag annotations for all three in admin_openapi.go; run `scripts/check-admin-openapi.sh` to regenerate admin/openapi/admin.json and admin/src/api/schema.d.ts; add the routes and handlers to the four route inventories.
- Copy en and pl: `mail.brand.*`, `mail.images.*` (including no_public_url), `codeeditor.*`, `colorpicker.*`, `mailimage.*`, `mail.picker.*`.
- Write the behavior subtests first (`fields`, `branding`, `images`, `images_permissions`) plus field-schema boot cases, then implement.
- Docs in the same commit: cabana README (field types table rows, Branding, image library routes), docs/backend/forms.md "Field types" and "Field options" rows for codeeditor (language, size, mailImages), colorpicker, mailimage and mailpreview (mode), docs/backend/settings.md (the Mail section entries; colorpicker, mailimage and mailpreview on settings forms; Branding precedence over mail.brandCss).
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/cabana -run 'TestMailScreensSmoke' -count=1 -v 2>&1 | grep -E '^\s*(--- |FAIL|ok|PASS)' | tail -30</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, "no tests to run", or no "--- PASS: TestMailScreensSmoke/branding" or "--- PASS: TestMailScreensSmoke/images_permissions" line</fails_when>
<automated>scripts/check-admin-openapi.sh --check</automated>
<fails_when>non-zero exit (admin.json or schema.d.ts differs from a fresh generation)</fails_when>
<automated>go vet ./... && go test -short ./... && go test ./modules/cabana -count=1 2>&1 | tail -5</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line in the output</fails_when>
</verify>
<acceptance_criteria>
- `grep -n '"codeeditor": {}' modules/cabana/form_schema.go` and `grep -n '"mailImages": {}' modules/cabana/form_schema.go` each print one line
- `grep -n '/mail/images' admin/openapi/admin.json` prints at least two lines
- `grep -n 'mail/images' modules/cabana/security_coverage_test.go modules/cabana/openapi_conformance_test.go` prints at least two lines
- `grep -n "type: codeeditor" modules/cabana/backendscreens/models/maillayout/fields.yaml` prints three lines
- `grep -n "type: colorpicker" modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml | wc -l` prints 13
- `grep -n "codeeditor" docs/backend/forms.md` prints at least one line
</acceptance_criteria>
<done>Layouts and partials have a real code-editor field on the server, Branding is a settings page that switches mail to its colours once saved, and the image library hands out absolute URLs under the agreed permission split.</done>
</task>
<task type="auto" tdd="true">
<name>Task 4: Preview and test send: the draft renders through postcard and goes only to the signed-in administrator, with a per-admin limit</name>
<files>modules/cabana/mail_routes.go, modules/cabana/http.go, modules/cabana/admin_openapi.go, modules/cabana/backendscreens/models/mailtemplate/fields.yaml, modules/cabana/backendscreens/models/maillayout/fields.yaml, modules/cabana/backendscreens/models/mailpartial/fields.yaml, modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml, modules/cabana/mail_screens_smoke_test.go, modules/cabana/phase10_coverage_test.go, modules/cabana/openapi_conformance_test.go, modules/cabana/security_coverage_test.go, modules/cabana/token_routes_test.go, modules/surf/serve.go, modules/surf/README.md, admin/openapi/admin.json, admin/src/api/schema.d.ts, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, modules/cabana/README.md, docs/services/mail.md, docs/services/rate-limiting.md</files>
<read_first>
- modules/cabana/field_markdown.go (~50-80 the route to mirror) and modules/cabana/http.go (route group, interactiveOnly)
- modules/cabana/mail_routes.go (Task 3 output)
- modules/surf/serve.go (~224-245 installCooler) and modules/cooler/cooler.go (~60-75 Attempter)
- modules/surf/limiter.go (how surf answers 429 with Retry-After)
- modules/postcard/editor.go (Preview, SendDraft, DraftError)
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md (C10, C15, Copywriting "Preview and test send")
</read_first>
<behavior>
- POST /mail/preview mode template with id and values {subject, body, layout} returns subject, html and text with sample placeholders; the html contains no script and is what Editor.Preview returned; a draft with an unknown partial returns 422 with details field, rule partial and message
- Mode layout with id 0 renders a new custom layout draft; mode partial renders the sample call; mode branding renders the sample message with the draft colours
- A templates-only holder gets 403 on modes layout, partial and branding and 200 on template; a layouts-only holder gets 403 on template
- POST /mail/test-send as an administrator with email ada@example.test sends one message whose only recipient is ada@example.test (Cc and Bcc empty) and returns that email; a body with a `to`, `email` or `recipient` key is refused before sending; a personal API token request is refused (interactive only)
- The sixth test send within 10 minutes for the same administrator returns 429 with a Retry-After header; another administrator is not limited; the limit uses a published cooler.Attempter when present
- A driver failure returns 5xx with the fixed message and no driver error text
</behavior>
<action>
Per D-16 and D-17:
- `mail_routes.go`: `AdminMailPreviewRequest{Mode string; ID uint64; Values map[string]any}` and `AdminMailPreviewResult{Subject, HTML, Text string}`; handler `mailPreview` (`POST /mail/preview`, requireAjax) with the markdownPreview auth gate, the mode's permission through Allows (template: templates code; layout, partial, branding: layouts code), the record loaded by ID through the controller's FormExtendQuery scope when ID > 0 (its code is the Draft Name; a custom layout create uses ID 0), the values mapped to a postcard Draft (template: subject, body and the `layout` relation value, the selected layout row id, resolved to that row's code; layout: content_html, content_text, content_css, name; partial: content_html, content_text; branding: the colour columns and logo_file_id → absolute URL), then Editor.Preview; a *DraftError answers 422 in the existing error envelope with details `field`, `rule` and `message` and the translated `mail.invalid_<rule>` text as the message; any other error is 500 with a fixed message. `AdminMailTestSendResult{Email string}`; handler `mailTestSend` (`POST /mail/test-send`, interactiveOnly and requireAjax) taking the same request decoded with unknown fields refused, modes template, layout and partial only, the same permission as the mode, the recipient read from the BackendUser row of principal.ID (never from the body), the limit checked before rendering (5 per 10 minutes, key `mail_test:<adminID>`; 429 with Retry-After in seconds as surf does), Editor.SendDraft to that address; a driver error answers 502 with the fixed message `backend::lang.mail.preview.test_failed`.
- Rate-limit store: cabana looks up `cooler.Attempter` from the app per request and falls back to a small in-process fixed-window limiter it owns. `modules/surf/serve.go` installCooler also publishes the Redis-backed store as `cooler.Attempter` (one Publish next to the Store publish), documented in modules/surf/README.md and docs/services/rate-limiting.md.
- YAML: add the mailpreview fields per UI-SPEC: template `_preview` (mode template, label `backend::lang.mail.preview.label`) after body; layouts `_preview_html`, `_preview_text`, `_preview_css` (mode layout) at the end of each tab; partials `_preview_html`, `_preview_text` (mode partial); Branding `_preview` (mode branding, full, comment `backend::lang.mail.brand.preview_comment`).
- swag annotations for both routes in admin_openapi.go (200, 401, 403, 422, 429 for test-send, 502); run `scripts/check-admin-openapi.sh`; add both routes to the four route inventories.
- Copy en and pl: the remaining `mail.preview.*` keys.
- Write the behavior subtests first (`preview`, `preview_permissions`, `test_send`, `test_send_limit`, `test_send_recipient`), then implement.
- Docs in the same commit: cabana README (both routes, the recipient rule, the limit), docs/services/mail.md (preview and test send from the admin; sample values; the limit).
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/cabana -run 'TestMailScreensSmoke' -count=1 -v 2>&1 | grep -E '^\s*(--- |FAIL|ok|PASS)' | tail -30</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, "no tests to run", or no "--- PASS: TestMailScreensSmoke/test_send_limit" or "--- PASS: TestMailScreensSmoke/test_send_recipient" line</fails_when>
<automated>scripts/check-admin-openapi.sh --check</automated>
<fails_when>non-zero exit</fails_when>
<automated>go vet ./... && go test -short ./... && go test ./modules/cabana ./modules/surf -count=1 2>&1 | tail -6</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line in the output</fails_when>
</verify>
<acceptance_criteria>
- `grep -n 'g.Post("/mail/test-send", interactiveOnly(requireAjax(' modules/cabana/http.go` prints one line
- `grep -n "type AdminMailPreviewRequest struct" modules/cabana/mail_routes.go` prints one line and that struct has no field named To, Email or Recipient (`go doc ./modules/cabana AdminMailPreviewRequest` lists only Mode, ID and Values)
- `grep -n "cooler.Attempter" modules/surf/serve.go modules/cabana/mail_routes.go` prints at least two lines
- `grep -n '/mail/preview\|/mail/test-send' admin/openapi/admin.json` prints at least two lines
- `grep -c "type: mailpreview" modules/cabana/backendscreens/models/maillayout/fields.yaml` prints 3
</acceptance_criteria>
<done>Every mail form can preview its unsaved draft through postcard and send a test only to the editing administrator, within a per-admin limit.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| admin browser → cabana mail routes | authenticated administrators with varying permission grants post drafts, uploads and test sends |
| personal API tokens → admin API | token principals reach the generic admin routes |
| cabana → postcard Editor → mail driver | drafts become real outbound mail on test send |
| uploads → public disk | administrator files become public URLs linked from mail |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-35-09 | Elevation of privilege | mail controllers and routes | high | mitigate | RequiredPermissions per controller; Allows per preview mode, test send and image upload; codes declared with no Roles (TestMailScreensSmoke/templates, preview_permissions, images_permissions) |
| T-35-10 | Elevation of privilege | picker upload | medium | mitigate | upload needs system.manage_mail_layouts; list allows either code; canUpload computed on the server |
| T-35-11 | Abuse (spam) | POST /mail/test-send | high | mitigate | recipient read from the administrator's own BackendUser row, unknown body keys refused, interactive sessions only, 5 per 10 minutes per admin through cooler.Attempter (TestMailScreensSmoke/test_send_recipient, test_send_limit) |
| T-35-12 | Tampering | override saves | high | mitigate | FormAfterUpdate runs postcard Editor.Validate inside the save transaction; a ValidationError rolls back (research Pitfall 6) |
| T-35-13 | Tampering | brand colours | high | mitigate | BeforeValidate refuses anything but #rrggbb before the row is written; postcard re-validates at compile |
| T-35-14 | Information disclosure | 422 and 5xx answers | medium | mitigate | 422 carries postcard's DraftError text only; driver and database errors map to fixed messages |
| T-35-15 | Tampering | uploads to the public disk | medium | mitigate | attach.Store with Image true, the jpg/jpeg/png/gif/webp allow-list and a 5 MB limit; public flag set explicitly |
| T-35-16 | Repudiation | override changes | low | accept | customized_at and updated_at record when; per-change author history is out of scope (no audit log exists for other admin records either) |
| T-35-17 | Denial of service | data loss through delete | medium | mitigate | file rows never deletable; in-use custom layouts refused with a count; FK ON DELETE RESTRICT backstop |
| T-35-18 | Spoofing | CSRF on new POST routes | high | mitigate | requireAjax on every POST and the existing admin CSRF/cookie guard; token principals refused on test send |
| T-35-SC | Tampering | npm/pip/cargo installs | high | accept | this plan installs no package |
</threat_model>
<verification>
- `go vet ./... && go test -short ./...` and `go test ./modules/cabana ./modules/surf ./modules/postcard/...` green after every commit.
- `scripts/check-admin-openapi.sh --check` passes after Tasks 3 and 4.
- `go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree'` and `go run ./cmd/summer docs:build --check` pass.
</verification>
<success_criteria>
- Five Settings → Mail screens exist behind two permissions with no default grants.
- Override, reset, custom layouts, drift and the File version diff work over postcard's tables.
- Branding, the image library and the four field types exist on the server; preview and test send are permission-checked, recipient-fixed and rate-limited.
- OpenAPI and schema.d.ts regenerated; README and docs updated in the same commits; nothing pushed or tagged.
</success_criteria>
<output>
Create `.planning/phases/35-mail-templates-and-layouts-editor/35-02-SUMMARY.md` when done; list every route, request/response type and field schema key exactly as shipped (35-03 builds against them).
</output>
## Artifacts this phase produces
- Constants: `cabana.PermissionManageMailTemplates`, `cabana.PermissionManageMailLayouts`, `cabana.MailTemplatesControllerID`, `cabana.MailLayoutsControllerID`, `cabana.MailPartialsControllerID`, `cabana.MailImagesControllerID`.
- Types: `cabana.MailTemplate`, `cabana.MailLayout`, `cabana.MailPartial`, `cabana.MailBrandSetting`, `cabana.MailImageLibrary`, `cabana.AdminMailPreviewRequest`, `cabana.AdminMailPreviewResult`, `cabana.AdminMailTestSendResult`, `cabana.AdminMailImage`; field `cabana.RecordMeta.Deletable`.
- Routes: `POST /mail/preview`, `POST /mail/test-send`, `GET /mail/images`, `GET /mail/images/{id}`, `POST /mail/images` (admin API prefix).
- Controllers: `summercms.cabana.mailtemplates`, `summercms.cabana.maillayouts`, `summercms.cabana.mailpartials`, `summercms.cabana.mailimages`; record action `reset`; settings entries `mail_templates`, `mail_layouts`, `mail_partials`, `mail_brand`, `mail_images` in category `backend::lang.settings.category_mail`.
- Field types: `codeeditor`, `colorpicker`, `mailimage`, `mailpreview`; field keys `language`, `mailImages` (and `mode` on mailpreview).
- List messages: `rowStateCustomized`, `rowStateOutdated`; row states `customized`, `outdated` now honoured by cabana.
- Services: surf publishes `cooler.Attempter` (Redis rate-limit store).
- Copy: `backend::lang.mail.*`, `codeeditor.*`, `colorpicker.*`, `mailimage.*`, `settings.category_mail`, `permissions.manage_mail_*`, `messages.list.row_state_customized|outdated` (en, pl).
- Generated: `admin/openapi/admin.json`, `admin/src/api/schema.d.ts`; test `TestMailScreensSmoke`.
- Config keys: none new.

View File

@@ -0,0 +1,244 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 02
subsystem: mail
tags: [cabana, postcard, mail, admin-api, codeeditor, colorpicker, mailimage, mailpreview, cooler, openapi]
# Dependency graph
requires:
- phase: 35-mail-templates-and-layouts-editor
provides: postcard.Editor Validate/Preview/SendDraft, SyncIndex, ResetOverride, Brand, AbsolutePublicURL, RowStateCustomized/Outdated
provides:
- "Settings → Mail screens (templates, layouts, partials, branding, images) via cabana pseudo-plugin when postcard.EditorFrom succeeds"
- "system.manage_mail_templates and system.manage_mail_layouts with no default role grants"
- "override save/reset, custom layouts with in-use delete refusal, drift row states and File version LCS diff"
- "built-in field types codeeditor, colorpicker, mailimage, mailpreview on the server"
- "GET/POST /mail/images and GET /mail/images/{id} with absolute public URLs"
- "POST /mail/preview and POST /mail/test-send (own-address, interactive-only, 5/10min via cooler.Attempter)"
- "admin OpenAPI + schema.d.ts for the new routes; en/pl mail copy"
affects: [35-03, 35-04, admin-spa, boardwalk]
# Actuals (#2632)
actuals:
tokens: 67849
tasks: 4
commits: 5
plan_head_before: 7efb9ed7ad36478bd9d810f13895893dd9d50020
plan_head_after: 0c73c8d4f13395e6d96721df98d8b8422a547ba3
# Tech tracking
tech-stack:
added: []
patterns:
- "Mail screens register only when postcard.EditorFrom succeeds; tests without a Mailer see no mail controllers"
- "Draft preview/test-send map form values to postcard.Draft; DraftError → 422 details field/rule/message"
- "Test-send limit key mail_test:<adminID> via cooler.Attempter (surf publishes Redis store) with in-process fixed-window fallback"
key-files:
created:
- modules/cabana/mail_admin.go
- modules/cabana/mail_diff.go
- modules/cabana/mail_routes.go
- modules/cabana/field_mail.go
- modules/cabana/mail_screens_smoke_test.go
- modules/cabana/backendscreens/controllers/mailtemplates/
- modules/cabana/backendscreens/controllers/maillayouts/
- modules/cabana/backendscreens/controllers/mailpartials/
- modules/cabana/backendscreens/controllers/mailimages/
- modules/cabana/backendscreens/models/mailtemplate/
- modules/cabana/backendscreens/models/maillayout/
- modules/cabana/backendscreens/models/mailpartial/
- modules/cabana/backendscreens/models/mailbrandsetting/
- modules/cabana/backendscreens/models/mailimagelibrary/
modified:
- modules/cabana/backend_screens.go
- modules/cabana/http.go
- modules/cabana/form_schema.go
- modules/cabana/crud.go
- modules/cabana/settings.go
- modules/cabana/query.go
- modules/cabana/messages.go
- modules/cabana/relation_field.go
- modules/cabana/admin_openapi.go
- modules/cabana/README.md
- modules/surf/serve.go
- modules/surf/README.md
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- admin/openapi/admin.json
- admin/src/api/schema.d.ts
- docs/backend/forms.md
- docs/backend/settings.md
- docs/backend/users-and-permissions.md
- docs/backend/lists-and-filters.md
- docs/services/mail.md
- docs/services/rate-limiting.md
key-decisions:
- "35-02: image list/pick allows either mail permission; upload and Mail images singleton need system.manage_mail_layouts"
- "35-02: test-send is interactive-only, recipient always the BackendUser email of principal.ID, unknown body keys refused by decodeStrictBody"
- "35-02: test-send limit 5 per 10 minutes keyed mail_test:<adminID>; surf publishes cooler.Attempter next to Store when Redis rate-limit is on"
- "35-02: layout create form defaults injected from postcard default layout at Activate (YAML carries no copy)"
- "35-02: GET /mail/images answers AdminMailImagesResponse (custom meta canUpload/total/page/perPage), not Envelope with SuccessMeta"
patterns-established:
- "cabana mail routes gate with Allows + tokenRouteGate; test-send adds interactiveOnly"
- "New mail field types register in formFieldTypes/formFieldKeys; mailpreview is valueless and skipped from Writable"
- "Route inventories (phase10 coverage, OpenAPI conformance, security, token classes) updated in the same commit as new admin routes"
requirements-completed: [D-01, D-02, D-03, D-04, D-05, D-06, D-07, D-08, D-09, D-10, D-13, D-16, D-17, D-18, D-19, D-23, D-25]
coverage:
- id: D1
description: "Mail templates screen lists catalog templates, saves overrides used by real sends, refuses unsafe body and wrong permission"
requirement: "D-04"
verification:
- kind: integration
ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/templates"
status: pass
human_judgment: false
- id: D2
description: "Layouts/partials reset, custom-layout create/delete-in-use, drift states and File version diff"
requirement: "D-07"
verification:
- kind: integration
ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/layouts|reset|delete|drift|diff"
status: pass
human_judgment: false
- id: D3
description: "codeeditor/colorpicker/mailimage fields, Branding settings, image library absolute URLs and permission split"
requirement: "D-09"
verification:
- kind: integration
ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/fields|branding|images|images_permissions"
status: pass
human_judgment: false
- id: D4
description: "Preview and test-send through postcard.Editor; own-address only; per-admin rate limit; interactive-only"
requirement: "D-16"
verification:
- kind: integration
ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/preview|preview_permissions|test_send|test_send_recipient|test_send_limit"
status: pass
human_judgment: false
duration: 77min
completed: 2026-11-13
status: complete
---
# Phase 35 Plan 02: Mail screens server Summary
**Cabana Settings → Mail screens over postcard: templates/layouts/partials with reset and drift, Branding and image library, codeeditor/colorpicker/mailimage/mailpreview, plus preview and own-address test-send with a per-admin limit**
## Performance
- **Duration:** 77 min
- **Started:** 2026-11-13T11:45:13+01:00
- **Completed:** 2026-11-13T13:02:49+01:00
- **Tasks:** 4
- **Files modified:** 66 (modules/, docs/, admin/)
## Accomplishments
- Five Settings → Mail entries behind `system.manage_mail_templates` / `system.manage_mail_layouts` (no default grants), registered only when `postcard.EditorFrom` succeeds.
- Templates, layouts and partials: catalog-scoped lists, override save with Editor.Validate, reset record action, custom layouts with in-use delete refusal, customized/outdated row states and File version LCS diff.
- Server field types `codeeditor`, `colorpicker`, `mailimage`, `mailpreview`; Branding settings form; image library routes with absolute URLs.
- `POST /mail/preview` and interactive-only `POST /mail/test-send` (own email, 5/10 min via `cooler.Attempter` or in-process fallback); OpenAPI regenerated.
## Task Commits
Each task was committed atomically:
1. **Task 1: Mail templates screen** - `7efb9ed7` (feat)
2. **Task 2: Layouts/partials, reset, drift, custom layouts** - `83f76cc3` (feat)
3. **Task 3: Field types, branding, image library** - `4fd2ed07` (feat)
4. **Task 4: Preview and test send** - `0c73c8d4` (feat)
**Plan metadata:** (this SUMMARY commit)
## Shipped contracts (for 35-03)
### Permissions and controller IDs
- `cabana.PermissionManageMailTemplates` = `system.manage_mail_templates`
- `cabana.PermissionManageMailLayouts` = `system.manage_mail_layouts`
- Controllers: `summercms.cabana.mailtemplates` | `maillayouts` | `mailpartials` | `mailimages`
- Settings codes: `mail_templates`, `mail_layouts`, `mail_partials`, `mail_brand`, `mail_images` (category `backend::lang.settings.category_mail`)
### Routes (admin API prefix)
| Method | Path | Notes |
|--------|------|-------|
| GET | `/mail/images` | `AdminMailImagesResponse` (`data[]`, meta `canUpload`/`total`/`page`/`perPage`) |
| GET | `/mail/images/{id}` | `Envelope[AdminMailImage]` |
| POST | `/mail/images` | multipart `file`; layouts permission; 201 |
| POST | `/mail/preview` | `AdminMailPreviewRequest` → `AdminMailPreviewResult` |
| POST | `/mail/test-send` | interactive-only; same request; `AdminMailTestSendResult{email}` |
### Request/response types
- `AdminMailPreviewRequest`: `mode` (`template`\|`layout`\|`partial`\|`branding`), `id` (uint64), `values` (map). No `to`/`email`/`recipient`.
- `AdminMailPreviewResult`: `subject`, `html`, `text`
- `AdminMailTestSendResult`: `email`
- `AdminMailImage`: `id`, `fileName`, `title`, `url`, `thumbUrl`
- `RecordMeta.Deletable` (`*bool`, omitempty) on mail controllers
### Field schema keys
- Types: `codeeditor` (`language`: html\|css\|text; optional `size`, `mailImages`), `colorpicker`, `mailimage`, `mailpreview` (`mode`: template\|layout\|partial\|branding)
- Keys: `language`, `mailImages` (plus existing `mode`/`size`)
- List messages: `rowStateCustomized`, `rowStateOutdated`
### Record action
- `reset` on templates, layouts, partials config_form.yaml (file-backed customized rows)
## Decisions Made
- Image picker: list for either mail code; upload only for layouts (planner call).
- Test-send limit through `cooler.Attempter` when surf publishes Redis store; otherwise cabana's in-process fixed window.
- Layout create defaults injected from the catalog default layout at Activate.
- List endpoint documents `AdminMailImagesResponse` so conformance accepts `canUpload` meta.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 1 - Bug] Conformance/CSRF/schema tests lagged new field types and routes**
- **Found during:** Task 3 close-out
- **Issue:** CSRF unsafe-route count, repeater nested refusal order for codeeditor/mailpreview, datepicker/phase121 mode error text, OpenAPI inventory missing image show/upload and SuccessMeta mismatch for list meta
- **Fix:** Updated expectation strings/counts; added typeKeys for nested refusal; documented `AdminMailImagesResponse`; granted mail perms + `app.url` + library migrate in conform env
- **Files modified:** phase10_csrf_test.go, repeater_test.go, datepicker_*_test.go, phase121_*_test.go, openapi_conformance_test.go, mail_routes.go, admin_openapi.go
- **Verification:** `go test -short ./...` and `TestPhase10OpenAPIConformance` pass
- **Committed in:** `4fd2ed07` (Task 3)
**2. [Rule 2 - Missing Critical] Conform env upload_bytes too small once Mailer published for preview cases**
- **Found during:** Task 4 OpenAPI conformance
- **Issue:** Publishing postcard Mailer activates mailimages; 5 MiB maxFilesize failed boot against 1 MiB upload_bytes
- **Fix:** Raised conform `http.body_limits.upload_bytes` to 8 MiB (same as mail smoke env)
- **Files modified:** openapi_conformance_test.go
- **Verification:** OpenAPI conformance green
- **Committed in:** `0c73c8d4` (Task 4)
---
**Total deviations:** 2 auto-fixed (1 bug, 1 blocking/boot)
**Impact on plan:** Necessary for green inventories and boot; no scope creep.
## Issues Encountered
None beyond the auto-fixes above. Substantial uncommitted Task 3 work was inventoried and reused rather than discarded.
## User Setup Required
None - no external service configuration required. Test-send uses the application's existing mail driver; Redis Attempter is optional (`http.rate_limit.store: redis`).
## Next Phase Readiness
- Server contracts are stable for 35-03 (SPA field controls + mailpreview UX).
- 35-03 can bind to the routes, types and YAML field modes listed above without further server changes for the screens.
---
*Phase: 35-mail-templates-and-layouts-editor*
*Completed: 2026-11-13*

View File

@@ -0,0 +1,440 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 03
type: execute
wave: 3
depends_on: ["35-02"]
files_modified:
- .planning/notes/2026-11-06-admin-code-editor-codemirror.md
- .planning/research/STACK.md
- admin/package.json
- admin/package-lock.json
- admin/src/components/form/registry.ts
- admin/src/components/form/fields/MailPreviewField.vue
- admin/src/components/form/fields/CodeEditorField.vue
- admin/src/components/form/codeeditor/editor.ts
- admin/src/components/form/fields/ColorPickerField.vue
- admin/src/components/form/fields/MailImageField.vue
- admin/src/components/mail/MailImagePicker.vue
- admin/src/components/mail/insertImage.ts
- admin/src/components/form/fields/MarkdownField.vue
- admin/src/components/form/fields/PartialField.vue
- admin/src/views/FormView.vue
- admin/src/views/SettingsFormView.vue
- admin/src/views/ListView.vue
- admin/src/components/list/RowStateBadges.vue
- admin/src/components/list/DataTable.vue
- admin/src/styles/main.css
- admin/src/api/types.ts
- admin/tests/form/mail-smoke.test.ts
- admin/tests/browser/codeeditor-smoke.test.ts
- modules/boardwalk/dist
- docs/backend/admin-spa.md
- docs/backend/forms.md
autonomous: false
requirements: [D-03, D-07, D-08, D-09, D-10, D-11, D-16, D-17, D-18, D-19, D-20, D-21]
estimate:
tokens: 190000
raw_tokens: 190000
tasks: 6
confidence: low
must_haves:
truths:
- "On a template, layout, partial or Branding form, the `mailpreview` field renders the unsaved draft from FORM_VALUES through POST /mail/preview 500 ms after the last change, in an iframe with an empty sandbox attribute and srcdoc bound only to the server's html, with a Plain text tab, the subject row, a sequence guard and the UI-SPEC error states (D-16)"
- "The Send test to me button posts the draft to POST /mail/test-send with no recipient, shows the signed-in administrator's email in its hint and the success toast, and on 429 shows the limit line and stays disabled for Retry-After seconds (D-17)"
- "Layouts and partials are edited in `codeeditor`, a CodeMirror 6 field loaded lazily in its own chunk with html, css or plain-text highlighting, Go template action highlighting, line numbers, bracket matching and history; Tab moves focus out, Mod+S and Mod+Enter still save the form, Esc does not cancel; a load failure falls back to a monospace textarea that still saves (D-09)"
- "The CodeMirror packages are added only after a decision note and a STACK.md row are committed and Jakub has confirmed the versions at a blocking checkpoint, with exact pins and the committed lockfile (CLAUDE.md dependency rule, research Package Legitimacy Audit)"
- "The Insert image button on the template body (markdown with mailImages) and on codeeditor fields with mailImages opens MailImagePicker, which lists the library from the server, uploads only when the server says canUpload, and inserts `![alt](url)`, `<img src=\"url\" alt=\"alt\">`, `url(\"url\")` or the bare URL with the server's absolute URL, escaped per UI-SPEC C4; MarkdownField hides its own preview toggle when mailImages is set (D-18, D-19, D-20, D-03)"
- "The Branding page renders 13 `colorpicker` fields (native swatch plus #rrggbb text) and the `mailimage` logo field (thumbnail, choose, change, remove, missing-image line), and SettingsFormView provides FORM_VALUES and FORM_LOCALE so its preview reads the draft (D-10, D-11)"
- "FormView shows the record's meta.actions (Reset to file version) in the update footer with the danger confirm, hides Delete when meta.deletable is false, and reloads partial fields after every save and record action, so the drift callout and File version diff are never stale; controllers without these keys behave as before (D-06, D-07, D-08)"
- "Lists show the `customized` (neutral outline) and `outdated` (sel tint) badges after the existing three, in that order, with labels from messages.rowStateCustomized and rowStateOutdated; main.css has the `.summer-diff` kit (D-07)"
- "modules/boardwalk/dist is rebuilt from the committed lockfile and passes scripts/check-admin-dist.sh, and the CodeMirror code is in a separate chunk, not in the entry bundle (D-21)"
prohibitions:
- statement: "The SPA never builds or modifies mail HTML: the preview iframe's srcdoc is only the server's rendered html, the iframe has no src and its sandbox attribute is empty."
status: unresolved
verification: judgment
- statement: "The SPA never builds image URLs; it inserts the absolute URL the server returned."
status: unresolved
verification: judgment
- statement: "The `codemirror` meta package (basicSetup) and indentWithTab are not used; no colour token, font, radius or shadow is added to the design system."
status: unresolved
verification: judgment
- statement: "No npm package is installed before the decision note, the STACK.md row and the human checkpoint."
status: unresolved
verification: judgment
- statement: "There is no free-text recipient input anywhere in the mail screens."
status: unresolved
verification: judgment
artifacts:
- path: "admin/src/components/form/fields/MailPreviewField.vue"
provides: "mailpreview control (tracer)"
contains: "sandbox=\"\""
- path: "admin/src/components/form/codeeditor/editor.ts"
provides: "CodeMirror setup, lazy import target"
contains: "Mod-Enter"
- path: "admin/src/components/form/fields/CodeEditorField.vue"
provides: "codeeditor control"
contains: "codeeditor.load_failed"
- path: "admin/src/components/mail/insertImage.ts"
provides: "pure snippet builder"
contains: "export function insertImage"
- path: "admin/src/components/mail/MailImagePicker.vue"
provides: "library picker dialog"
contains: "radiogroup"
- path: ".planning/notes/2026-11-06-admin-code-editor-codemirror.md"
provides: "dependency decision note"
contains: "@codemirror/view"
key_links:
- from: "admin/src/components/form/fields/MailPreviewField.vue"
to: "modules/cabana/mail_routes.go"
via: "api.POST('/mail/preview') and api.POST('/mail/test-send') typed by schema.d.ts"
pattern: "/mail/preview"
- from: "admin/src/components/form/fields/CodeEditorField.vue"
to: "admin/src/components/form/codeeditor/editor.ts"
via: "dynamic import, so CodeMirror stays out of the entry chunk"
pattern: "import\\(.*codeeditor/editor"
- from: "admin/src/components/mail/MailImagePicker.vue"
to: "modules/cabana/mail_routes.go"
via: "GET/POST /mail/images, canUpload from meta"
pattern: "/mail/images"
- from: "admin/src/components/form/registry.ts"
to: "admin/src/components/form/fields/MailPreviewField.vue"
via: "mailpreview registered, valueless and group-labelled"
pattern: "'mailpreview'"
---
## Phase Goal
ROADMAP Goal (not in user-story format; no story is invented): administrators edit every mail the application sends from the admin panel. This plan gives the Vue admin SPA what the generic views cannot render on their own: the live preview and test send, the code editor, the colour and image fields, the image picker, and the small FormView, SettingsFormView and list additions of UI-SPEC C8 and C9, then rebuilds the embedded admin.
Spec-less probe fallback skipped: no SPEC.md and no requirement IDs; must_haves derive from the ROADMAP goal, CONTEXT D-01..D-25 and the approved 35-UI-SPEC.md. Route, type and key names come from 35-02-SUMMARY.md where they differ from this text.
<objective>
Implement UI-SPEC C1-C4, C8-C11 in admin/:
- `mailpreview` with sandboxed srcdoc preview and test send (D-16, D-17);
- `codeeditor` on CodeMirror 6, lazily loaded, after the decision note, the STACK.md row and a blocking version check (D-09; research Package Legitimacy Audit flags @codemirror/view 6.43.15 as too-new);
- `colorpicker`, `mailimage`, MailImagePicker and insertImage, the Insert image button on markdown and codeeditor (D-10, D-18..D-20);
- FormView footer record actions, meta.deletable, partial reload; SettingsFormView FORM_VALUES/FORM_LOCALE; row-state badges; the `.summer-diff` CSS kit (D-06..D-08);
- the rebuilt modules/boardwalk/dist (D-21).
Purpose: with 35-02's server screens, this completes the editor administrators use; nothing here decides permissions, recipients or URLs, which stay on the server.
Output: commits in this repository only; planning docs (decision note, STACK.md) in their own commit, the dist rebuild in its own commit. Nothing is pushed or tagged.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-RESEARCH.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-PATTERNS.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-02-SUMMARY.md
@.planning/notes/2026-10-12-admin-display-sanitizer-dompurify.md
@.planning/notes/2026-10-07-embedded-admin-release-gate.md
@CLAUDE.md
<interfaces>
admin/src/components/form/registry.ts: `renderers` Map (type → component), `valueless` Set (RELATION_MANAGER, widget, partial, fileupload), `groupLabelledTypes` Set, `selfLabelled`, `recordBound`; field components import only from `../control` (never from registry.ts) to avoid an import cycle; header comment carries a per-phase history paragraph.
admin/src/components/form/fields/MarkdownField.vue: PREVIEW_DEBOUNCE_MS, the `sequence` guard, `api.POST('/markdown/preview', ...)`, `refusal(error)` details extraction, controlAttributes/controlClass from ../control.
admin/src/components/form/fields/RichEditorField.vue: lazy import of the TipTap editor with a `bg-skel` loading box (`data-*-loading`, aria-busy) and a failure fallback; toolbar class strings.
admin/src/components/form/formContext.ts: FORM_VALUES, FORM_PATCH, FORM_SESSION, FORM_LOCALE injection keys.
admin/src/views/FormView.vue: provides at ~354-417; `singleton`, `backToPreview` (schema.preview) at ~205-214; footer at ~680-727 with Delete (`mode === 'update' && !singleton`) and onDelete (~546).
admin/src/views/SettingsFormView.vue: provides SETTINGS_SECRETS only (~54).
admin/src/components/form/RecordActions.vue (used by PreviewView; `busy` emit, danger confirm); admin/src/components/relation/RelationPickerModal.vue (dialog shell, search input, chosen tile classes); admin/src/components/form/fields/FileuploadField.vue (tile grid, captions).
admin/src/components/list/RowStateBadges.vue:19 `const ORDER = ['deleted', 'negative', 'disabled']`; DataTable.vue:160 `const ROW_STATES = [...]`; ListView.vue:~108 row-state labels from messages.
From 35-02: POST /mail/preview {mode, id, values} → {subject, html, text}, 422 details {field, rule, message}; POST /mail/test-send same body → {email}, 429 + Retry-After, 502; GET /mail/images?q=&page= → {data: [{id, fileName, title, url, thumbUrl}], meta: {canUpload, total, page, perPage}}, 409 with message when no absolute URL is configured; GET /mail/images/{id}; POST /mail/images multipart `file`; form field schema keys `language`, `mailImages`, `mode`; RecordMeta.deletable; list messages rowStateCustomized / rowStateOutdated.
Admin CSP (modules/boardwalk/boardwalk.go ~61-66) has frame-src 'none'; its comment states a sandboxed srcdoc preview still renders, so no CSP change.
</interfaces>
</context>
## Execution units and resume points
- Before each task run `git status --short admin modules/boardwalk/dist` and stop if another session holds uncommitted edits there.
- Each task ends with the commit(s) listed below, staged by explicit path. Resume check: `git log --format=%s -F --grep='<subject>'`.
- Per task: `npm --prefix admin run test` and `npm --prefix admin run typecheck`; the browser suite needs the Playwright Chromium build already in ~/.cache/ms-playwright.
| Task | Commit subject | Resume point |
|------|----------------|--------------|
| 1 | `feat(admin): mail preview field with sandboxed HTML and test send` | mail-smoke preview cases pass |
| 2 | `docs(35): CodeMirror decision note and STACK.md row for the admin code editor` | note and row committed |
| 3 | none (answer recorded in the SUMMARY) | answer recorded |
| 4 | `feat(admin): codeeditor field on CodeMirror 6, loaded lazily` | codeeditor-smoke passes |
| 5 | `feat(admin): colour picker, mail image field and the image picker with insert` | mail-smoke picker cases pass |
| 6 | `feat(admin): footer record actions, deletable flag, mail row states and diff styles`, then `build(admin): rebuild the embedded admin for the mail editor` | check-admin-dist.sh passes |
<tasks>
<task type="tracer">
<name>Task 1: End-to-end "an administrator edits a template body and sees the rendered mail, then sends a test to their own address" — the mailpreview field over the 35-02 routes</name>
<precondition>35-02 is complete: `grep -n '/mail/preview' admin/src/api/schema.d.ts` prints at least one line</precondition>
<files>admin/src/components/form/fields/MailPreviewField.vue, admin/src/components/form/registry.ts, admin/src/views/SettingsFormView.vue, admin/src/api/types.ts, admin/tests/form/mail-smoke.test.ts</files>
<read_first>
- admin/src/components/form/fields/MarkdownField.vue (whole file: debounce, sequence guard, refusal extraction)
- admin/src/components/form/registry.ts (whole file) and admin/src/components/form/formContext.ts
- admin/src/views/SettingsFormView.vue (whole file) and admin/src/views/FormView.vue (~340-420 provides)
- admin/src/components/form/FormTabs.vue (tab pill class strings) and admin/src/state/useToasts.ts
- admin/tests/form/MarkdownField.test.ts and admin/tests/helpers.ts (how fields are mounted with provides and api mocks)
- .planning/phases/35-mail-templates-and-layouts-editor/35-02-SUMMARY.md (exact request and response shapes)
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md (C10, C15, Copywriting "Preview and test send")
</read_first>
<action>
Per D-16 and D-17 and UI-SPEC C10:
- `MailPreviewField.vue`: reads the whole draft from FORM_VALUES and the record id (0 on create) and posts `{mode: field.mode, id, values}` to `/mail/preview` on mount and 500 ms after the last change, with the MarkdownField sequence guard; while its tab is inactive it sends nothing and renders when the tab becomes active (use the same visibility signal other lazy fields use, or an IntersectionObserver when none exists). Markup and classes exactly per C10: toolbar with the HTML / Plain text switch (FormTabs class strings, role tablist) and the role status line (`mail.preview.rendering`); subject row hidden in branding mode; `<iframe sandbox="" referrerpolicy="no-referrer">` with srcdoc bound only to the html of the latest 2xx answer and the `mail.preview.frame_title` title, white canvas, 640px; the plain-text `pre`; notes (`mail.preview.sample_note` in template mode, `sample_content_note` otherwise, plus the field comment); the error line (`failed` keeping the last render, `failed_first`, `unavailable` on network or 5xx) with :message from the 422 details; the empty-draft state when the mode's content field is blank (no request).
- Test send (not in branding mode): outline small Button with the Send icon and `mail.preview.test_send` / `test_sending`, the hint `mail.preview.test_hint` with :email from the signed-in administrator's session; POST the same payload to `/mail/test-send` (never a recipient); 2xx → toast `mail.preview.test_sent` with the returned email; 429 → inline line `test_limited` with :seconds from Retry-After and the button disabled until then; 422 → inline `test_invalid` with :message; 5xx → danger toast `test_failed`; 403 → danger toast with the server message. No confirm dialog.
- `registry.ts`: register `mailpreview`, add it to `valueless` and `groupLabelledTypes`; add a Phase 35 paragraph to the header history comment. `types.ts`: export any helper types the field needs from schema.d.ts (no hand-written API shapes).
- `SettingsFormView.vue`: `provide(FORM_VALUES, computed(() => values.value))` and `provide(FORM_LOCALE, ...)` as FormView does; no FORM_PATCH or session (UI-SPEC C8 item 4).
- `admin/tests/form/mail-smoke.test.ts` (smoke, happy-dom): mounts MailPreviewField with provided values and a mocked api; asserts the iframe's sandbox attribute is present and empty, there is no src attribute, srcdoc equals the mocked html, a stale answer is dropped by the sequence guard, a 422 after a good render keeps the previous srcdoc and shows the failed line, and a 429 test send disables the button.
Commit as listed in Execution units.
</action>
<verify>
<automated>npm --prefix admin run test -- mail-smoke 2>&1 | tail -8</automated>
<fails_when>non-zero exit, a "FAIL" line, or "No test files found"</fails_when>
<automated>npm --prefix admin run typecheck 2>&1 | tail -3</automated>
<fails_when>non-zero exit or an "error TS" line</fails_when>
<automated>npm --prefix admin run test 2>&1 | tail -6</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n 'sandbox=""' admin/src/components/form/fields/MailPreviewField.vue` prints one line
- `grep -n "'/mail/test-send'" admin/src/components/form/fields/MailPreviewField.vue` prints one line
- `grep -n "'mailpreview'" admin/src/components/form/registry.ts` prints at least two lines (renderer and valueless or group set)
- `grep -n "provide(FORM_VALUES" admin/src/views/SettingsFormView.vue` prints one line
</acceptance_criteria>
<done>Every mail form shows its unsaved draft exactly as postcard renders it and can send a test to the editing administrator.</done>
</task>
<task type="auto">
<name>Task 2: Write the CodeMirror decision note and the STACK.md row before anything is installed</name>
<files>.planning/notes/2026-11-06-admin-code-editor-codemirror.md, .planning/research/STACK.md</files>
<read_first>
- .planning/notes/2026-10-12-admin-display-sanitizer-dompurify.md (structure to mirror: Decision table, Why, Scope, Legitimacy with integrity values)
- .planning/research/STACK.md (~74-84 "Admin SPA (npm) additions")
- .planning/phases/35-mail-templates-and-layouts-editor/35-RESEARCH.md ("Admin SPA (new npm runtime dependencies)", "Package Legitimacy Audit", "CodeMirror setup", Pitfall 5)
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md (Design System "Why CodeMirror 6", Registry Safety)
</read_first>
<action>
Per D-09 and the CLAUDE.md dependency rule ("A new dependency needs a research doc or a phase/decision note naming it"):
- Create `.planning/notes/2026-11-06-admin-code-editor-codemirror.md`: Decision table with the seven direct runtime packages and exact pins (@codemirror/state 6.7.6, @codemirror/view 6.43.15, @codemirror/language 6.13.1, @codemirror/commands 6.11.1, @codemirror/lang-html 6.4.12, @codemirror/lang-css 6.3.1, @lezer/highlight 1.2.5), what each is used for, that they load lazily from `admin/src/components/form/codeeditor/editor.ts` in their own chunk, that the meta package with basicSetup is not used, and the keymap rule (defaultKeymap without Mod-Enter, no indentWithTab, research Pitfall 5); Why (MIT, modular, no workers so the CSP is unchanged, accessible contenteditable; Monaco, Ace, textarea overlay and TipTap rejected per UI-SPEC); the transitive packages (the @lezer grammars, @codemirror/autocomplete and @codemirror/lang-javascript via lang-html, style-mod, w3c-keyname, crelt, @marijn/find-cluster-break); Legitimacy: the research audit table (maintainer marijn, no postinstall scripts, weekly downloads, source repositories), the [SUS] too-new flag on @codemirror/view 6.43.15 (published 2026-10-19, past the 7-day cooldown) and the `dist.integrity` value of each pinned version read with `npm view <pkg>@<version> dist.integrity` (read-only registry queries; no install).
- `.planning/research/STACK.md` "Admin SPA (npm) additions": one row per direct package (or one grouped CodeMirror row listing all seven pins) with purpose "codeeditor field (Phase 35)" and a link to the note.
Commit both as one planning-docs commit, separate from code (CLAUDE.md), as listed in Execution units.
</action>
<verify>
<automated>grep -c "@codemirror/" .planning/notes/2026-11-06-admin-code-editor-codemirror.md && grep -n "codemirror" .planning/research/STACK.md | head -5</automated>
<fails_when>non-zero exit, a count below 6, or no STACK.md line</fails_when>
<automated>git diff --quiet HEAD -- admin/package.json admin/package-lock.json && echo unchanged</automated>
<fails_when>no "unchanged" line (package files must not change in this task)</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "sha512-" .planning/notes/2026-11-06-admin-code-editor-codemirror.md | wc -l` prints at least 7
- `grep -n "6.43.15" .planning/notes/2026-11-06-admin-code-editor-codemirror.md` prints at least one line mentioning the too-new flag
- `git log --format=%H%x09%s -F --grep='docs(35): CodeMirror decision note and STACK.md row for the admin code editor'` prints one line, and `git show --stat --format= <that sha>` lists only the two planning files
</acceptance_criteria>
<done>The dependency is documented and justified before it exists in the repository.</done>
</task>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 3: Jakub confirms the CodeMirror package versions before npm install (legitimacy gate; never auto-approved)</name>
<what-built>The decision note `.planning/notes/2026-11-06-admin-code-editor-codemirror.md` lists the seven pins and their dist.integrity values. Research flagged `@codemirror/view` 6.43.15 [SUS] as too-new (18 days old on 2026-11-06, past the project's 7-day cooldown, same maintainer as every other package).</what-built>
<how-to-verify>
1. Open https://www.npmjs.com/package/@codemirror/view and check that 6.43.15 is published by marijn, has no install scripts and matches the integrity in the note (or decide to pin 6.43.14 or older).
2. Spot-check https://www.npmjs.com/package/@codemirror/state, /@codemirror/language, /@codemirror/commands, /@codemirror/lang-html, /@codemirror/lang-css and /@lezer/highlight against the note's versions.
3. Confirm that installing exactly these pins into admin/ (runtime dependencies, exact versions, committed lockfile) is approved.
</how-to-verify>
<resume-signal>Reply "approved", or "pin @codemirror/view <version>" (the executor updates the note and STACK.md in a follow-up planning commit before installing), or "stop"</resume-signal>
</task>
<task type="auto" tdd="true">
<name>Task 4: The codeeditor field: CodeMirror 6 loaded lazily, Go template actions highlighted, keyboard rules that keep the form's hotkeys and Tab free</name>
<reversibility rating="costly">D-09: the `codeeditor` type, its `language` and `size` keys and its value shape are a published field type plugins may start using.</reversibility>
<precondition>Task 3 answered "approved" or named a pin, recorded in the plan SUMMARY draft</precondition>
<files>admin/package.json, admin/package-lock.json, admin/src/components/form/codeeditor/editor.ts, admin/src/components/form/fields/CodeEditorField.vue, admin/src/components/form/registry.ts, admin/tests/browser/codeeditor-smoke.test.ts, admin/tests/form/mail-smoke.test.ts</files>
<read_first>
- admin/src/components/form/fields/RichEditorField.vue (lazy import, loading skeleton, failure fallback, toolbar classes)
- admin/src/components/form/control.ts (controlAttributes, controlClass, FieldControlProps)
- admin/vitest.browser.config.ts and admin/tests/browser/richeditor-display.test.ts (browser-mode test shape)
- admin/src/views/FormView.vue (the form hotkey handler and how it ignores plain keys inside contenteditable)
- .planning/notes/2026-11-06-admin-code-editor-codemirror.md (Task 2, as confirmed at Task 3)
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md (C1, Color "Code editor syntax colours", Spacing "Code editor by size")
- .planning/phases/35-mail-templates-and-layouts-editor/35-RESEARCH.md ("CodeMirror setup", Pitfall 5)
</read_first>
<behavior>
- The control shows the `bg-skel` loading box (aria-busy true) at the size's height until the chunk loads; size tiny/small/large/huge/giant gives 128/192/320/480/640 px, default large
- A failed import shows the `codeeditor.load_failed` note and a monospace textarea bound to the value; editing it emits update:modelValue
- Typing in the editor emits update:modelValue with the full document; the content element has the control id, aria-labelledby, aria-describedby, aria-invalid and aria-multiline true
- Browser: Tab from inside the editor moves focus to the next control; Mod+S and Mod+Enter inside the editor trigger the form save; Esc inside the editor does not trigger Cancel
- language html and css use their grammars, text uses none and wraps lines; `{{ ... }}` spans carry the cm-summer-action class
- Read-only rendering is a `pre` with the text (or list.empty_value) and loads no CodeMirror
</behavior>
<action>
Per D-09 and UI-SPEC C1:
- Install exactly the pins confirmed at Task 3 with `npm --prefix admin install --save-exact` (runtime dependencies), then `npm --prefix admin ci` to prove the lockfile.
- `codeeditor/editor.ts` (the only module that imports CodeMirror): a `createCodeEditor(parent, options)` factory taking the initial doc, language (html | css | text), height, ids/aria attributes and an onChange callback, returning an object with `view`, `insert(text)` (replaces the main selection, or appends at the end when the editor never had focus, then focuses with the caret after the text) and `destroy()`. Extensions: lineNumbers, bracketMatching, history, the html() or css() grammar or none, a MatchDecorator plus ViewPlugin marking Go template actions with class `cm-summer-action`, `EditorView.lineWrapping` only for text, contentAttributes for the aria wiring, a HighlightStyle and EditorView.theme using only the existing `var(--c-*)` variables per the UI-SPEC syntax table, and `keymap.of([...historyKeymap, ...defaultKeymap without the Mod-Enter binding])`; indentWithTab is not added.
- `CodeEditorField.vue`: wrapper and toolbar markup per C1 (the toolbar renders only when mailImages is set; its Insert image button is wired in Task 5 through the editor's insert), dynamic `import('../codeeditor/editor')` so CodeMirror lands in its own chunk, the loading box and failure fallback copied from RichEditorField, read-only `pre` rendering, destroy on unmount, external value changes (record reload after reset) replace the document without emitting.
- `registry.ts`: register `codeeditor`.
- Write first: `admin/tests/browser/codeeditor-smoke.test.ts` (browser mode: Tab leaves, Mod+S and Mod+Enter reach a form submit handler, Esc does not reach Cancel, typing emits the value) and happy-dom cases in mail-smoke.test.ts for the loading box, the failure fallback (mock the dynamic import to reject) and read-only rendering; then implement.
Commit as listed in Execution units.
</action>
<verify>
<automated>npm --prefix admin run test:browser -- codeeditor-smoke 2>&1 | tail -8</automated>
<fails_when>non-zero exit, a "FAIL" line, or "No test files found"</fails_when>
<automated>npm --prefix admin run test -- mail-smoke 2>&1 | tail -6 && npm --prefix admin run typecheck 2>&1 | tail -3</automated>
<fails_when>non-zero exit, a "FAIL" line or an "error TS" line</fails_when>
<automated>npm --prefix admin ci 2>&1 | tail -3</automated>
<fails_when>non-zero exit or an "npm error" line</fails_when>
</verify>
<acceptance_criteria>
- `node -e "const p=require('./admin/package.json');for(const n of ['@codemirror/state','@codemirror/view','@codemirror/language','@codemirror/commands','@codemirror/lang-html','@codemirror/lang-css','@lezer/highlight'])if(!/^\d+\.\d+\.\d+$/.test(p.dependencies[n]||''))process.exit(1)"` exits 0
- `grep -n "import('../codeeditor/editor')" admin/src/components/form/fields/CodeEditorField.vue` prints one line
- `grep -rln "@codemirror/" admin/src | grep -v codeeditor/editor.ts` prints nothing (type-only imports included: editor.ts is the only module that names a CodeMirror package)
<!-- planner-discipline-allow: @codemirror/ -->
- `grep -n "'codeeditor'" admin/src/components/form/registry.ts` prints at least one line
</acceptance_criteria>
<done>Layout and partial HTML, text and CSS are edited in a real code editor that respects the form's keyboard model.</done>
</task>
<task type="auto" tdd="true">
<name>Task 5: Colour picker, mail image field and the image picker that inserts library images into bodies and code editors</name>
<files>admin/src/components/form/fields/ColorPickerField.vue, admin/src/components/form/fields/MailImageField.vue, admin/src/components/mail/MailImagePicker.vue, admin/src/components/mail/insertImage.ts, admin/src/components/form/fields/MarkdownField.vue, admin/src/components/form/fields/CodeEditorField.vue, admin/src/components/form/registry.ts, admin/tests/form/mail-smoke.test.ts</files>
<read_first>
- admin/src/components/relation/RelationPickerModal.vue (dialog shell, search, chosen tile classes) and admin/src/components/form/fields/FileuploadField.vue (thumbnails, captions, upload error display)
- admin/src/components/form/fields/TextField.vue and MarkdownField.vue (textarea selection handling, preview toggle)
- admin/src/components/form/fields/CodeEditorField.vue (Task 4) and admin/src/components/ui/Button.vue
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md (C2, C3, C4, C11, C12, Copywriting "Image picker and image fields", "Code editor and colour picker")
- .planning/phases/35-mail-templates-and-layouts-editor/35-RESEARCH.md (Pitfall 4: percent-encode URLs with spaces for Markdown)
</read_first>
<behavior>
- insertImage('markdown', 'https://cdn.example.com/a b.png', 'Logo [x]') returns `![Logo \[x\]](https://cdn.example.com/a%20b.png)`; ('html', url, 'a "b" <c>') entity-escapes &, ", < and > in alt and url; ('css', url, alt) returns `url("<url>")`; ('text', url, alt) returns the url
- The picker lists images from GET /mail/images with a 300 ms debounced server search, loads the next page of 40 on scroll, is a radiogroup with arrow-key movement, keeps the primary disabled until a tile is chosen, prefills alt from the caption title in insert mode, and shows the upload row only when meta.canUpload is true; an upload adds the new image first and selected; a 422 upload shows the server message under the row; empty, no-result and load-failed states use the UI-SPEC copy, and a 409 shows the server's message
- The markdown field with mailImages shows Insert image and no Preview toggle; without mailImages it is unchanged; choosing an image inserts the markdown snippet at the textarea selection and the caret lands after it
- A codeeditor with mailImages inserts the html or css snippet through the editor's insert
- ColorPicker: typing `#D66829` updates the swatch and emits the value; a partial value leaves the swatch at the last valid colour; an empty value shows the not-set placeholder and a white swatch
- MailImage: shows the thumbnail and filename for a stored id (GET /mail/images/{id}), Choose opens the picker in choose mode, Remove emits null, a 404 for the stored id shows the mailimage.missing line and the empty icon
</behavior>
<action>
Per D-18, D-19, D-20, D-10 and D-03 (UI-SPEC C2, C3, C4, C11):
- `insertImage.ts`: pure `insertImage(language: 'markdown' | 'html' | 'css' | 'text', url: string, alt: string): string` per the C4 table, percent-encoding spaces and parentheses in Markdown URLs (research Pitfall 4).
- `MailImagePicker.vue`: Reka Dialog with the RelationPickerModal shell, insert and choose modes, search, upload row from `meta.canUpload` only (POST /mail/images, hidden file input with the four image types), the tile grid radiogroup, alt input in insert mode, footer Cancel + primary; never builds a URL, always uses the server's `url`.
- `MarkdownField.vue`: with `mailImages` the Insert image text button replaces the Preview toggle; insertion through insertImage('markdown', ...) at the textarea selection, focus back with the caret after the text, update:modelValue emitted.
- `CodeEditorField.vue`: the toolbar button opens the picker and inserts insertImage(language, ...) through the editor's insert (the fallback textarea uses the selection path).
- `ColorPickerField.vue` per C2 (native swatch with aria-label `colorpicker.pick`, mono hex input with maxlength 7 and the not-set placeholder; no client-side validation beyond the native control). `MailImageField.vue` per C11 (value is the library image id or null, group-labelled).
- `registry.ts`: register `colorpicker` and `mailimage`; add `mailimage` to groupLabelledTypes.
- Write the behavior cases first in mail-smoke.test.ts (insertImage table, picker canUpload both ways, markdown insert and hidden preview toggle, colour sync, mailimage missing), then implement.
Commit as listed in Execution units.
</action>
<verify>
<automated>npm --prefix admin run test -- mail-smoke 2>&1 | tail -8</automated>
<fails_when>non-zero exit, a "FAIL" line, or "No test files found"</fails_when>
<automated>npm --prefix admin run typecheck 2>&1 | tail -3 && npm --prefix admin run test 2>&1 | tail -6</automated>
<fails_when>non-zero exit, an "error TS" line or a "FAIL" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "export function insertImage" admin/src/components/mail/insertImage.ts` prints one line
- `grep -n 'role="radiogroup"' admin/src/components/mail/MailImagePicker.vue` prints one line
- `grep -n "canUpload" admin/src/components/mail/MailImagePicker.vue` prints at least one line
- `grep -n "'colorpicker'\|'mailimage'" admin/src/components/form/registry.ts` prints at least two lines
- `grep -n "mailImages" admin/src/components/form/fields/MarkdownField.vue admin/src/components/form/fields/CodeEditorField.vue` prints at least two lines
</acceptance_criteria>
<done>Administrators pick brand colours and the logo, and place library images into template bodies, layouts and partials without typing a URL.</done>
</task>
<task type="auto" tdd="true">
<name>Task 6: FormView footer record actions, the deletable flag, partial reloads, mail row-state badges and the diff kit, then rebuild the embedded admin</name>
<files>admin/src/views/FormView.vue, admin/src/components/form/fields/PartialField.vue, admin/src/views/ListView.vue, admin/src/components/list/RowStateBadges.vue, admin/src/components/list/DataTable.vue, admin/src/styles/main.css, admin/tests/form/mail-smoke.test.ts, modules/boardwalk/dist, docs/backend/admin-spa.md, docs/backend/forms.md</files>
<read_first>
- admin/src/views/FormView.vue (whole file: footer, onDelete, save path, reload, snapshot reset)
- admin/src/views/PreviewView.vue (RecordActions use and the hintKey reload) and admin/src/components/form/RecordActions.vue
- admin/src/components/form/fields/PartialField.vue and the PartialHost it renders
- admin/src/components/list/RowStateBadges.vue, DataTable.vue (~155-195), ListView.vue (~100-115)
- admin/src/styles/main.css (`@layer components`, `.summer-callout` kit)
- scripts/check-admin-dist.sh and .planning/notes/2026-10-07-embedded-admin-release-gate.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md (C7 CSS kit, C8 items 1-3, C9)
</read_first>
<behavior>
- An update form whose record has meta.actions [reset] and no preview screen shows an outline Reset to file version button after Delete in the footer; its confirm is the danger variant; while it runs every footer button is disabled; after a 2xx the mail.reset_done toast shows, values are replaced, the form is clean and the partial field's reloadKey increments; 409 shows the stale toast and reloads; 403 shows a danger toast
- meta.deletable false hides Delete; true or absent shows it (absent = unchanged behaviour for every existing controller)
- A successful save also increments the partial reloadKey
- RowStateBadges renders deleted, negative, disabled, customized, outdated in that order with the customized outline and outdated sel styles; DataTable keeps text-text (no strike-through) for rows with only the new states; ListView passes the rowStateCustomized and rowStateOutdated labels
</behavior>
<action>
Per D-06 (as amended by D-23), D-07 and D-08 (UI-SPEC C7, C8, C9):
- `FormView.vue`: footer record actions from the show response's meta.actions through the existing RecordActions component in the left group after Delete, only on update and only when the controller has no preview screen (the generic rule in C8 item 1); busy disables every footer button; on success toast, reload the record in place and reset the dirty snapshot; Delete hidden when meta.deletable is false; a `reloadKey` provided to partial fields and bumped after every successful save and record action.
- `PartialField.vue`: re-fetch its partial when the provided reloadKey changes (the PreviewView hintKey mechanism).
- Lists: RowStateBadges ORDER and styles, DataTable ROW_STATES (new states do not change the title style), ListView labels.
- `main.css`: the `.summer-diff`, `.summer-diff__add`, `__del`, `__ctx` rules from UI-SPEC C7 in `@layer components`, existing variables only.
- Write the behavior cases first in mail-smoke.test.ts, then implement. Run `npm --prefix admin run test`, `npm --prefix admin run test:browser`, `npm --prefix admin run typecheck` and `scripts/check-admin-openapi.sh --check`, and commit the source change.
- Docs in the same source commit: docs/backend/admin-spa.md (the code editor's keyboard behaviour next to Keyboard shortcuts; the preview and test-send behaviour) and docs/backend/forms.md (how codeeditor, colorpicker, mailimage and mailpreview look and behave in the admin, footer record actions on forms without a preview screen, meta.deletable).
- Then `npm --prefix admin run build`, stage `modules/boardwalk/dist` by path (it is a directory of generated files; `git add modules/boardwalk/dist` is the explicit path), run `scripts/check-admin-dist.sh`, and commit the rebuild separately as listed in Execution units.
</action>
<verify>
<automated>npm --prefix admin run test 2>&1 | tail -6 && npm --prefix admin run test:browser 2>&1 | tail -6 && npm --prefix admin run typecheck 2>&1 | tail -3</automated>
<fails_when>non-zero exit, a "FAIL" line or an "error TS" line</fails_when>
<automated>scripts/check-admin-openapi.sh --check && scripts/check-admin-dist.sh</automated>
<fails_when>non-zero exit (generated types or the committed dist differ from a fresh build)</fails_when>
<automated>go vet ./... && go test -short ./... && go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "'customized', 'outdated'" admin/src/components/list/RowStateBadges.vue` prints one line
- `grep -n "deletable" admin/src/views/FormView.vue` prints at least one line
- `grep -n "\.summer-diff__add" admin/src/styles/main.css` prints one line
- `grep -l "cm-summer-action" modules/boardwalk/dist/assets/*.js` prints exactly one path and it is not an `index-*.js` entry chunk (CodeMirror lives in its own lazy chunk next to the richeditor's)
- `git log --format=%s -F --grep='build(admin): rebuild the embedded admin for the mail editor'` prints one line, and `git show --stat --format= <that commit>` lists only paths under modules/boardwalk/dist
</acceptance_criteria>
<done>The admin shows reset, delete and drift exactly where the UI contract puts them, and the binary embeds the finished mail editor.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| server-rendered mail HTML → admin browser | a draft may contain hostile markup that rendered on the server |
| image library entries → editors | file names and captions typed by administrators |
| npm registry → admin build | new third-party code in the admin bundle |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-35-19 | Elevation of privilege (stored XSS) | MailPreviewField | high | mitigate | iframe with an empty sandbox (no scripts, no same-origin, no forms, no top navigation), srcdoc only from a 2xx answer, no src, never v-html; server already ran validateHTML; CSP frame-src unchanged (mail-smoke sandbox case) |
| T-35-20 | Tampering | insertImage snippets | medium | mitigate | alt and url escaped per target (markdown brackets, HTML entities), URLs only from the server (mail-smoke insertImage table) |
| T-35-21 | Tampering (supply chain) | CodeMirror packages | high | mitigate | decision note and STACK row first, blocking human checkpoint (never auto-approved) with integrity values, exact pins, committed lockfile, npm ci; lazy chunk limits the surface to the code editor |
| T-35-22 | Abuse | test-send button | medium | mitigate | no recipient input; 429 disables the button for Retry-After; the server enforces the rule regardless |
| T-35-23 | Information disclosure | picker and preview errors | low | mitigate | only server-provided messages and fixed copy are shown; no stack traces |
| T-35-24 | Denial of service (keyboard trap) | codeeditor | low | mitigate | Tab unbound in the editor (WCAG 2.1.2), browser smoke test |
| T-35-SC | Tampering | npm/pip/cargo installs | high | mitigate | package-legitimacy gate (research audit, [SUS] @codemirror/view) + blocking human checkpoint Task 3 before the install in Task 4 |
</threat_model>
<verification>
- `npm --prefix admin run test`, `npm --prefix admin run test:browser` and `npm --prefix admin run typecheck` green after every task that touches admin/.
- `scripts/check-admin-openapi.sh --check` and `scripts/check-admin-dist.sh` pass after Task 6.
- `go vet ./... && go test -short ./...` and the docs checker pass.
</verification>
<success_criteria>
- The four field controls, the picker, the footer actions, the badges and the diff kit match UI-SPEC C1-C4 and C7-C11.
- CodeMirror is documented, human-approved, exactly pinned, lazily loaded.
- modules/boardwalk/dist is rebuilt and passes the dist gate; nothing pushed or tagged.
</success_criteria>
<output>
Create `.planning/phases/35-mail-templates-and-layouts-editor/35-03-SUMMARY.md` when done; record the Task 3 answer verbatim and the installed versions.
</output>
## Artifacts this phase produces
- SPA components: `MailPreviewField.vue`, `CodeEditorField.vue`, `ColorPickerField.vue`, `MailImageField.vue`, `MailImagePicker.vue`; modules `codeeditor/editor.ts` (`createCodeEditor`), `mail/insertImage.ts` (`insertImage`).
- Registry entries: `mailpreview` (valueless, group-labelled), `codeeditor`, `colorpicker`, `mailimage` (group-labelled).
- FormView: footer record actions on forms without a preview screen, `meta.deletable`, partial `reloadKey`; SettingsFormView: `FORM_VALUES` and `FORM_LOCALE` provides.
- Lists: `customized` and `outdated` badges; CSS kit `.summer-diff`, `.summer-diff__add`, `.summer-diff__del`, `.summer-diff__ctx`; editor class `cm-summer-action`.
- npm runtime dependencies (exact pins): `@codemirror/state`, `@codemirror/view`, `@codemirror/language`, `@codemirror/commands`, `@codemirror/lang-html`, `@codemirror/lang-css`, `@lezer/highlight`.
- Planning docs: `.planning/notes/2026-11-06-admin-code-editor-codemirror.md`, STACK.md row.
- Generated: rebuilt `modules/boardwalk/dist`; smoke tests `admin/tests/form/mail-smoke.test.ts`, `admin/tests/browser/codeeditor-smoke.test.ts`.
- Config keys: none.

View File

@@ -0,0 +1,233 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 03
subsystem: ui
tags: [admin, codemirror, mailpreview, mailimage, colorpicker, boardwalk]
requires:
- phase: 35-02
provides: mail preview/test-send/images API routes and OpenAPI types
provides:
- mailpreview field with sandboxed iframe and test send
- codeeditor on CodeMirror 6 (lazy chunk) with approved exact pins
- colorpicker, mailimage, MailImagePicker, insertImage
- FormView footer record actions, meta.deletable, partial reload
- customized/outdated row badges and .summer-diff CSS kit
- rebuilt modules/boardwalk/dist
affects: [35-04, admin SPA mail screens]
actuals:
tokens: 26700
tasks: 6
commits: 15
plan_head_before: 9ea3159ba21668f413b7b2521361a1f6579179d0
plan_head_after: f23207653116e529ffdb10fdc7defb8d3212031b
tech-stack:
added:
- "@codemirror/state@6.7.6"
- "@codemirror/view@6.43.15"
- "@codemirror/language@6.13.1"
- "@codemirror/commands@6.11.1"
- "@codemirror/lang-html@6.4.12"
- "@codemirror/lang-css@6.3.1"
- "@lezer/highlight@1.2.5"
patterns:
- "Lazy CodeMirror chunk via dynamic import('../codeeditor/editor'), TipTap-style"
- "FORM_PARTIAL_RELOAD inject for partial re-fetch after save/action"
key-files:
created:
- admin/src/components/form/fields/MailPreviewField.vue
- admin/src/components/form/fields/CodeEditorField.vue
- admin/src/components/form/codeeditor/editor.ts
- admin/src/components/form/fields/ColorPickerField.vue
- admin/src/components/form/fields/MailImageField.vue
- admin/src/components/mail/MailImagePicker.vue
- admin/src/components/mail/insertImage.ts
- admin/tests/browser/codeeditor-smoke.test.ts
- .planning/notes/2026-11-06-admin-code-editor-codemirror.md
modified:
- admin/package.json
- admin/package-lock.json
- admin/src/components/form/registry.ts
- admin/src/components/form/fields/MarkdownField.vue
- admin/src/views/FormView.vue
- admin/src/views/SettingsFormView.vue
- admin/src/components/list/RowStateBadges.vue
- admin/src/styles/main.css
- modules/boardwalk/dist
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- docs/backend/admin-spa.md
- docs/backend/forms.md
key-decisions:
- "Task 3: Jakub approved all seven CodeMirror/lezer pins including @codemirror/view@6.43.15 (latest stable, past 7-day cooldown); no note/STACK rewrite"
- "CodeMirror loads only from codeeditor/editor.ts; meta package and indentWithTab unused"
patterns-established:
- "Package legitimacy: decision note + STACK row + blocking-human checkpoint before npm install"
- "Mail image URLs always come from the server; insertImage only escapes"
requirements-completed: [D-03, D-07, D-08, D-09, D-10, D-11, D-16, D-17, D-18, D-19, D-20, D-21]
coverage:
- id: D1
description: "mailpreview sandboxed srcdoc preview and test-send with 429 disable"
requirement: D-16
verification:
- kind: unit
ref: admin/tests/form/mail-smoke.test.ts#MailPreviewField
status: pass
human_judgment: false
- id: D2
description: "codeeditor CodeMirror 6 lazy load, Tab/Mod+S/Esc keyboard contract"
requirement: D-09
verification:
- kind: automated_ui
ref: admin/tests/browser/codeeditor-smoke.test.ts
status: pass
- kind: unit
ref: admin/tests/form/mail-smoke.test.ts#CodeEditorField
status: pass
human_judgment: false
- id: D3
description: "CodeMirror packages exactly pinned after human legitimacy gate"
requirement: D-09
verification:
- kind: other
ref: admin/package.json + decision note integrity match
status: pass
human_judgment: true
rationale: "Package legitimacy was a blocking-human checkpoint (Task 3); automation cannot replace that trust step"
- id: D4
description: "colorpicker, mailimage, MailImagePicker, insertImage, markdown mailImages"
requirement: D-18
verification:
- kind: unit
ref: admin/tests/form/mail-smoke.test.ts#insertImage|ColorPicker|MailImage
status: pass
human_judgment: false
- id: D5
description: "FormView footer actions, deletable, partial reload, badges, diff kit, boardwalk dist"
requirement: D-21
verification:
- kind: unit
ref: admin/tests/form/mail-smoke.test.ts#RowStateBadges
status: pass
- kind: other
ref: scripts/check-admin-dist.sh
status: pass
human_judgment: false
duration: 22min
completed: 2026-11-13
status: complete
---
# Phase 35 Plan 03: Mail templates SPA editor Summary
**Admin SPA mail editor: sandboxed mailpreview, CodeMirror codeeditor (human-approved pins), colour/image picker, FormView footer actions, badges, and rebuilt boardwalk dist**
## Performance
- **Duration:** 22 min (continuation from Task 3 checkpoint; wall clock from resume)
- **Started:** 2026-11-13T12:19:03Z
- **Completed:** 2026-11-13T12:41:00Z
- **Tasks:** 6/6
- **Files modified:** ~47 across plan window (includes concurrent phase-31 docs commits in the same HEAD range)
## Accomplishments
- `mailpreview` posts drafts to `/mail/preview` and `/mail/test-send`; iframe uses empty `sandbox` and server `srcdoc` only
- CodeMirror 6 installed after Task 3 approval of all seven exact pins (including `@codemirror/view@6.43.15`); lockfile integrity matches the decision note; lazy `editor-*.js` chunk carries `cm-summer-action`
- `colorpicker`, `mailimage`, `MailImagePicker`, and `insertImage` with markdown/codeeditor Insert image; Preview toggle hidden when `mailImages` is set
- FormView footer RecordActions when there is no preview screen; `meta.deletable === false` hides Delete; partials reload via `FORM_PARTIAL_RELOAD`; customized/outdated badges; `.summer-diff` kit
- `modules/boardwalk/dist` rebuilt and `scripts/check-admin-dist.sh` passes
## Task Commits
1. **Task 1: mailpreview field** - `52204e17` (feat)
2. **Task 2: CodeMirror decision note + STACK.md** - `6e0d4bbc` (docs)
3. **Task 3: human pin approval** - none (answer recorded below)
4. **Task 4 RED: failing codeeditor tests** - `7e2c0117` (test)
5. **Task 4 GREEN: CodeMirror install + codeeditor** - `9975cf4b` (feat)
6. **Task 5 RED: failing insertImage/colorpicker tests** - `3e29e604` (test)
7. **Task 5 GREEN: picker, colour, mailimage, insert** - `68e1d36f` (feat)
8. **Task 6 RED: failing row-badge test** - `aba51280` (test)
9. **Task 6 GREEN: FormView/lists/diff/docs** - `d1334067` (feat)
10. **Task 6 dist rebuild** - `36f34108` (build)
11. **Deviation: mail.picker lang keys** - `8969806d` (fix)
**Plan metadata:** (this SUMMARY commit)
## Task 3 answer (verbatim)
> approved — pin the best versions. Orchestrator judgment: keep all seven pins as in the decision note, including @codemirror/view@6.43.15 (latest stable, maintainer marijn, integrity matches note, now ~25 days old / past 7-day cooldown). No note/STACK rewrite needed unless integrity drifts. Proceed to install exactly those pins in Task 4.
**Installed versions:** `@codemirror/state@6.7.6`, `@codemirror/view@6.43.15`, `@codemirror/language@6.13.1`, `@codemirror/commands@6.11.1`, `@codemirror/lang-html@6.4.12`, `@codemirror/lang-css@6.3.1`, `@lezer/highlight@1.2.5` (exact; lockfile integrity matched the decision note).
## Files Created/Modified
- `admin/src/components/form/fields/MailPreviewField.vue` - live preview + test send
- `admin/src/components/form/fields/CodeEditorField.vue` / `codeeditor/editor.ts` - lazy CodeMirror
- `admin/src/components/mail/insertImage.ts` / `MailImagePicker.vue` - library insert/choose
- `admin/src/components/form/fields/ColorPickerField.vue` / `MailImageField.vue`
- `admin/src/views/FormView.vue` - footer actions, deletable, partial reload
- `modules/boardwalk/dist` - embedded admin rebuild
- `.planning/notes/2026-11-06-admin-code-editor-codemirror.md` - dependency decision
## Decisions Made
- Task 3 approved all seven pins including the [SUS] too-new `@codemirror/view@6.43.15`; no pin downgrade
- CodeMirror confined to `codeeditor/editor.ts` dynamic import (T-35-21 / T-35-SC)
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 2 - Missing Critical] mail.picker phrasebook keys**
- **Found during:** Task 6 verification (`go test ./modules/phrasebook`)
- **Issue:** SPA used UI-SPEC picker keys (`insert`, `use`, `uploading`, empty/error copy) not present in backend lang YAML
- **Fix:** Added en/pl keys under `mail.picker` per UI-SPEC copywriting
- **Files modified:** `modules/phrasebook/backend/lang/en/lang.yaml`, `pl/lang.yaml`
- **Verification:** `go test -short ./modules/phrasebook` and `./...` pass
- **Committed in:** `8969806d`
**2. [Rule 1 - Bug] ColorPicker swatch sync without parent v-model**
- **Found during:** Task 5 tests
- **Issue:** Typing a valid hex did not update `lastValid` until props echoed
- **Fix:** Update `lastValid` in `onText` when HEX matches
- **Files modified:** `ColorPickerField.vue`
- **Committed in:** `68e1d36f`
---
**Total deviations:** 2 auto-fixed (1 missing critical, 1 bug)
**Impact on plan:** Required for phrasebook SPA key gate and colorpicker behaviour; no scope creep
## Issues Encountered
- Concurrent phase-31 docs commits interleaved on `master` during this plan window; staged only 35-03 paths
- Task 1 follow-ups (`rowStateCustomized` / mail-smoke TS2349) already clean at resume; DatepickerField timezone failures left deferred per instructions
## User Setup Required
None - no external service configuration required.
## Next Phase Readiness
- SPA mail editor controls and embedded dist are ready for 35-04 (UAT / remaining phase work)
- Nothing pushed or tagged
## Self-Check: PASSED
- Key files exist: MailPreviewField, CodeEditorField, editor.ts, MailImagePicker, insertImage, decision note, boardwalk dist
- Commits found: 52204e17, 6e0d4bbc, 7e2c0117, 9975cf4b, 3e29e604, 68e1d36f, aba51280, d1334067, 36f34108, 8969806d
- `cm-summer-action` lives in `modules/boardwalk/dist/assets/editor-uDgt9VKj.js` (not an `index-*.js` entry chunk)
---
*Phase: 35-mail-templates-and-layouts-editor*
*Completed: 2026-11-13*

View File

@@ -0,0 +1,339 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 04
type: execute
wave: 4
depends_on: ["35-01", "35-02", "35-03"]
files_modified:
- scripts/check-phase35.sh
- modules/postcard/override_test.go
- modules/postcard/partials_test.go
- modules/postcard/samples_test.go
- modules/postcard/editor_test.go
- modules/postcard/brand_test.go
- modules/postcard/store_postgres_test.go
- modules/pact/capabilities_test.go
- modules/lagoon/attach/absolute_test.go
- modules/cabana/mail_permissions_postgres_test.go
- modules/cabana/mail_lifecycle_postgres_test.go
- modules/cabana/mail_test_send_postgres_test.go
- modules/cabana/mail_unit_test.go
- modules/cabana/field_mail_test.go
- modules/surf/store_lookup_test.go
- admin/tests/form/CodeEditorField.test.ts
- admin/tests/form/MailPreviewField.test.ts
- admin/tests/form/insertImage.test.ts
- admin/tests/form/MailImagePicker.test.ts
- admin/tests/form/ColorPickerField.test.ts
- admin/tests/form/MailImageField.test.ts
- admin/tests/form/FormViewMail.test.ts
- admin/tests/list/RowStateBadges.test.ts
- admin/tests/views/SettingsFormView.test.ts
- admin/tests/browser/codeeditor.test.ts
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
autonomous: true
requirements: [D-21, D-03, D-06, D-07, D-11, D-12, D-13, D-14, D-15, D-17, D-23]
estimate:
tokens: 170000
raw_tokens: 170000
tasks: 4
confidence: low
must_haves:
truths:
- "scripts/check-phase35.sh runs every Phase 35 check by stage (self-test, go, docker, consumers, admin, docs, marker, additive), fails closed on a missing repository, a skipped or missing required test, a zero-match run or a planted failure, and its consumers stage runs the sm-user-plugin and sm-paymentgateway-plugin mail tests against this checkout (D-21, Wave 0 of 35-VALIDATION.md)"
- "Unit tests cover override precedence and reset: an override beats the file, the caller's subject beats the override, no row means the file, and ResetOverride restores the file (D-21, D-14, D-23)"
- "Unit tests cover drift detection: a changed file hash marks a customized row outdated in postcard's sync and in cabana's row states and filter, and saving again clears it (D-21, D-07)"
- "Unit tests cover fallback at send: a render failure, a safety-check failure, a lookup error, a missing table and no database each send the file version, and an unresolved layout code uses the default layout (D-21, D-14)"
- "Unit tests cover save validation: every DraftError rule (parse, render, unsafe, subject_line, layout, partial, no_content, colour) in postcard and its 422 field line with translated text in cabana, including the 55 paymentgateway-shaped and 8 user-shaped real template shapes passing validation with no samples (D-21, D-13, D-15)"
- "Unit tests cover Branding precedence over config: no row uses mail.brandCss, a saved row's compiled CSS replaces it, mail.css still applies, and an invalid colour is refused (D-21, D-11)"
- "Unit tests cover the partial capability: boot errors for a foreign namespace, a missing file, a duplicate and a name outside mail.partials; token forgery; layouts and text parts; pact.HasMailTemplates' method set is pinned unchanged (D-21, D-12)"
- "Unit tests cover the permission split: each controller, preview mode, test-send mode, picker list and upload against templates-only, layouts-only, both and superuser principals, and no role holds either code after migrations (D-21, D-03)"
- "Unit tests cover the test-send recipient restriction and rate limit: only the admin's own email receives mail, a recipient key in the body is refused, token principals are refused, and the sixth send in 10 minutes is a 429 with Retry-After through a fake cooler.Attempter (D-21, D-17)"
- "SPA unit and browser tests cover the codeeditor keyboard rules, insertImage escaping, the picker's canUpload states, the preview sandbox and sequence guard, the footer record actions, meta.deletable and the new row-state badges (D-21)"
- "35-VALIDATION.md's per-decision map is filled with the final commands and statuses, and every Wave 0 item is checked"
prohibitions:
- statement: "No production code changes in this plan except fixes for defects the new tests expose, each recorded as a deviation in the SUMMARY with its own fix commit."
status: unresolved
verification: judgment
- statement: "Tests never write into a sibling repository and never reach the network beyond localhost, httptest servers and testcontainers."
status: unresolved
verification: judgment
- statement: "Nothing is pushed or tagged by this plan (tag only at phase completion, on the default branch, after Jakub's go-ahead)."
status: unresolved
verification: judgment
artifacts:
- path: "scripts/check-phase35.sh"
provides: "phase gate (tracer)"
contains: "--self-test"
- path: "modules/postcard/override_test.go"
provides: "precedence and fallback unit tests"
contains: "func TestOverride"
- path: "modules/cabana/mail_permissions_postgres_test.go"
provides: "permission split tests"
contains: "func TestMailPermissions"
- path: "modules/cabana/mail_test_send_postgres_test.go"
provides: "recipient and rate-limit tests"
contains: "func TestMailTestSend"
- path: "admin/tests/browser/codeeditor.test.ts"
provides: "keyboard tests in a real engine"
contains: "Mod"
key_links:
- from: "scripts/check-phase35.sh"
to: "../sm-paymentgateway-plugin"
via: "consumers stage runs TestMailCatalog, TestMailTracer and TestMailersMatrixSmoke against this checkout"
pattern: "TestMailersMatrixSmoke"
- from: "scripts/check-phase35.sh"
to: "scripts/apisurface/main.go"
via: "additive stage compares exported API with PHASE35_BASE_TAG"
pattern: "apisurface"
---
## Phase Goal
ROADMAP Goal (not in user-story format; no story is invented): administrators edit every mail the application sends from the admin panel, and mail that already works keeps working. Project rule 2 puts unit tests in the last plan of the phase; this plan adds them for the D-21 list and the phase gate that also proves the two core consumer plugins still send their mail unchanged.
Spec-less probe fallback skipped: no SPEC.md and no requirement IDs; must_haves derive from CONTEXT D-21 and the other decisions it lists.
<objective>
- `scripts/check-phase35.sh`: one fail-closed gate over the framework, the admin SPA, the docs and the sibling sm-user-plugin and sm-paymentgateway-plugin mail tests.
- Unit tests for postcard, pact and attach (precedence, reset, drift hashes, fallback, validation, samples, partials, Branding).
- Unit tests for cabana and surf (permission split, save validation, drift states and filter, reset, delete refusal, test-send recipient and limit, locale, diff, field schema checks, the published Attempter).
- SPA unit and browser tests; the filled 35-VALIDATION.md.
Purpose: D-21 and the Nyquist map in 35-VALIDATION.md; the gate is what `/msd-verify-work` runs.
Output: test commits in this repository; one planning-docs commit for 35-VALIDATION.md. No sibling repository is changed; nothing is pushed or tagged.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-RESEARCH.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-01-SUMMARY.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-02-SUMMARY.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-03-SUMMARY.md
@CLAUDE.md
<interfaces>
scripts/check-phase34.sh and scripts/check-phase33.sh: the stage engine to copy (usage, detect_go on go test -json, go_named / go_pkg_named for required names, require_dir "missing <path>", marker_hits, npm_vitest, run_self_test planting, additive_case over scripts/apisurface, docker NOT RUN rule, PHASE*_ALLOW_NO_DOCKER).
Smoke tests left by 35-01..35-03: TestMailOverrideSmoke, TestMailPartialsSmoke, TestMailEditorSmoke, TestMailBrandSmoke (modules/postcard, the Postgres helper lives in override_smoke_test.go), TestMailScreensSmoke and newMailScreensEnv (modules/cabana/mail_screens_smoke_test.go), admin/tests/form/mail-smoke.test.ts, admin/tests/browser/codeeditor-smoke.test.ts.
Consumer tests (run against this checkout through their go.mod `replace git.golem15.com/golem15/summercms => ../summercms.go`): ../sm-user-plugin TestMail (mail_test.go), TestPolishMailSubjects (mail_subjects_test.go); ../sm-paymentgateway-plugin TestMailCatalog, TestMailTracer, TestMailersMatrixSmoke (mail_smoke_test.go; that repo also has a go.work).
Base tag for marker and additive: v0.6.3 (newest tag before the phase), overridable with PHASE35_BASE_TAG.
</interfaces>
</context>
## Execution units and resume points
- Each task ends with the commit listed below, staged by explicit path. Resume check: `git log --format=%s -F --grep='<subject>'`.
- A test that exposes a production defect: fix it in its own `fix(<module>): ...` commit, record it as a deviation in the SUMMARY, then continue.
- Docker-backed tests run without `-short` (through `sudo -u golem` if the Docker socket is denied).
| Task | Commit subject | Resume point |
|------|----------------|--------------|
| 1 | `test(35): phase gate script check-phase35.sh` | `--self-test` passes |
| 2 | `test(postcard): unit tests for overrides, fallback, partials, samples, validation, sync and branding` | postcard tests pass |
| 3 | `test(cabana): unit tests for mail permissions, save validation, drift, reset, layout delete and test send` | cabana mail tests pass |
| 4 | `test(admin): unit and browser tests for the mail editor fields`, then `docs(35): fill the validation map` | `scripts/check-phase35.sh --all` passes |
<tasks>
<task type="tracer">
<name>Task 1: End-to-end "one command runs every Phase 35 check, including the core plugins' mail" — the gate script over the smoke tests plans 01-03 left behind</name>
<files>scripts/check-phase35.sh</files>
<read_first>
- scripts/check-phase34.sh (whole file: stage engine, self-test planting, marker word list, additive comparison)
- scripts/apisurface/main.go
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md and the three plan SUMMARYs (test names and commands that worked)
</read_first>
<action>
Create `scripts/check-phase35.sh` from check-phase34.sh's engine, labelled Phase 35 (mail templates and layouts editor), with stages (each a flag; `--all` runs them in this order; no argument prints usage listing every flag and exits 2):
- `--self-test`: plants a failing go test name, a missing required name, a skipped required test, a marker hit in a scratch repository, an additive removal and an interface method added in planted packages, and a missing repository, and requires each to be detected.
- `--go`: `go vet ./...`, `go test -short ./...`, the Docker-free tests by required name in GO_TESTS (TestMailPartialsSmoke, the -short subtests of TestMailEditorSmoke and TestMailBrandSmoke; Tasks 2 and 3 extend the list), and `cd examples/hello && go test ./...`.
- `--docker`: Docker host only (NOT RUN otherwise, which fails --all unless PHASE35_ALLOW_NO_DOCKER=1): `go test ./...` plus DOCKER_TESTS by required name (TestMailOverrideSmoke, TestMailEditorSmoke, TestMailBrandSmoke, TestMailScreensSmoke, TestMigrateStatusJSON; later tasks extend it).
- `--consumers`: for ../sm-user-plugin and ../sm-paymentgateway-plugin: check that the framework module resolves to this checkout (`go list -m -f '{{.Dir}}' git.golem15.com/golem15/summercms` equals this checkout), `go vet ./...`, and the named mail tests (TestMail and TestPolishMailSubjects; TestMailCatalog, TestMailTracer and TestMailersMatrixSmoke) without -short when Docker answers, each required to run and pass; read-only (no file in those repositories is written).
- `--admin`: `npm --prefix admin run test` with required files (ADMIN_FILES: mail-smoke.test.ts now; Task 4 extends it), `npm --prefix admin run test:browser` with codeeditor-smoke required, `npm --prefix admin run typecheck`, `scripts/check-admin-openapi.sh --check`, `scripts/check-admin-dist.sh`.
- `--docs`: TestDocsTree, TestCommandsDocumented and `go run ./cmd/summer docs:build --check`.
- `--marker`: the lines added since PHASE35_BASE_TAG (default v0.6.3) to non-test Go files, READMEs and docs under modules/, cmd/, internal/ and docs/ name no consuming application (the check-phase34 word list).
- `--additive`: scripts/apisurface of every package under modules/ changed since the base tag keeps every exported line and adds no method to an interface that exists at the tag (pact, postcard, cabana, lagoon/attach and surf only gain elements; this proves pact.HasMailTemplates, postcard.Mailer and Catalog.Register are unchanged).
A stage whose repository or directory is missing fails with `missing <path>`. Commit as listed in Execution units.
</action>
<verify>
<automated>bash scripts/check-phase35.sh --self-test</automated>
<fails_when>non-zero exit, or a planted case reported as undetected</fails_when>
<automated>bash scripts/check-phase35.sh --go --docs --marker --additive</automated>
<fails_when>non-zero exit, or a "FAIL", "missing " or marker hit line</fails_when>
<automated>bash scripts/check-phase35.sh --consumers --admin</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
</verify>
<acceptance_criteria>
- `bash scripts/check-phase35.sh; echo $?` prints a usage naming --self-test, --go, --docker, --consumers, --admin, --docs, --marker, --additive, --all and exits 2
- `grep -n "TestMailersMatrixSmoke" scripts/check-phase35.sh` and `grep -n "TestPolishMailSubjects" scripts/check-phase35.sh` each print at least one line
- `grep -c "missing " scripts/check-phase35.sh` is at least 1
- `git -C ../sm-user-plugin status --short` and `git -C ../sm-paymentgateway-plugin status --short` print the same output before and after a `--consumers` run
</acceptance_criteria>
<done>The phase has one gate that proves the mail editor and the unchanged mail of the core plugins together.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: Unit tests for postcard, pact and attach: precedence, reset, drift hashes, fallback, validation, samples, partials and Branding</name>
<files>modules/postcard/override_test.go, modules/postcard/partials_test.go, modules/postcard/samples_test.go, modules/postcard/editor_test.go, modules/postcard/brand_test.go, modules/postcard/store_postgres_test.go, modules/pact/capabilities_test.go, modules/lagoon/attach/absolute_test.go, scripts/check-phase35.sh</files>
<read_first>
- modules/postcard/*.go and the four *_smoke_test.go files (35-01 output; reuse the Postgres helper and fixtures, do not duplicate the smoke assertions)
- modules/pact/capabilities_test.go (~250-265 TestRowStateValues, ~410-420 the set check)
- ../sm-paymentgateway-plugin/views/mail and ../sm-user-plugin/views/mail (read only: copy the template shapes into testdata of the test, never import those repositories)
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md (test names per decision)
</read_first>
<behavior>
- TestOverride: table over (no row, customized template, customized layout, database-only layout, partial override, caller Subject) with a fake OverrideSource; each asserts the exact subject, HTML fragment and text part
- TestFallback: render failure, unsafe override, lookup error, unresolved layout code (default layout plus warning), DB source with no published DB; each sends exactly one message whose body is the file version; log records carry component postcard
- TestPartial: HasMailPartials boot errors (foreign namespace, missing file, duplicate, name without mail.partials), bare built-in name, full plugin name, odd kv count, unknown name, forged token in a variable, layout use, text part, nonce differs between two renders
- TestSample: case kept after the prefix; old headers unchanged; walker over nested, if/else, with re-rooting, range of maps, range of strings, chains and variables; every real consumer template shape copied into testdata validates with no samples
- TestValidateDraft: every Rule with Field and a Message that contains no filesystem path or SQL text
- TestBrand: compile defaults, refuse bad colours with the field name, empty colour uses default, lower-casing, precedence of a brand row over mail.brandCss with mail.css kept, logoUrl absolute or empty
- TestStore and TestSync (Postgres): NewDBSource reads only is_custom rows; SyncIndex idempotent with stable IDs, concurrent calls, customized row keeps its override columns while file_hash refreshes (drift: base_hash differs), database-only layouts untouched, ResetOverride restores the file and refuses a database-only layout
- TestRowStateValues pins five values; a compile-time and reflect check pins pact.HasMailTemplates to exactly MailTemplatesFS, MailTemplates and MailLayouts and HasMailPartials to MailPartialsFS and MailPartials
- TestAbsolutePublicURL: public_url, app.url with default and custom prefix, neither (ErrNoAbsoluteURL), trailing slashes, a public_url with a query refused
</behavior>
<action>
Per D-21 (and D-11, D-12, D-13, D-14, D-15, D-07, D-23 it covers): write the tests above with the names VALIDATION.md lists (TestOverride*, TestFallback*, TestPartial*, TestSample*, TestValidateDraft*, TestBrand*, TestStore*, TestSync*), table-driven, `-short` for everything that needs no database and testing.Short skips for the Postgres ones (reuse the override_smoke_test.go helper; no TestMain scanning os.Args). Consumer template shapes go into the test as string fixtures with neutral plugin IDs (acme.*), never naming a consuming application. Add the new names to GO_TESTS and DOCKER_TESTS in scripts/check-phase35.sh. Fix production defects only as described in Execution units. Commit as listed.
</action>
<verify>
<automated>go test -short ./modules/postcard/... ./modules/pact/... ./modules/lagoon/attach/... -run 'TestOverride|TestFallback|TestPartial|TestSample|TestValidateDraft|TestBrand|TestRowStateValues|TestAbsolutePublicURL' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -30</automated>
<fails_when>a "FAIL" line, "no tests to run", or no "--- PASS: TestFallback" line</fails_when>
<automated>go test ./modules/postcard -run 'TestStore|TestSync' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -10</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, or no "--- PASS: TestSync" line</fails_when>
<automated>bash scripts/check-phase35.sh --go --docker</automated>
<fails_when>non-zero exit or a "FAIL" or "missing " line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "func TestFallback" modules/postcard/override_test.go` and `grep -n "func TestSync" modules/postcard/store_postgres_test.go` each print at least one line
- `grep -n '"customized"' modules/pact/capabilities_test.go` and `grep -n '"outdated"' modules/pact/capabilities_test.go` each print at least one line
- `git show --stat --format= <the Task 2 test commit sha>` lists only `_test.go` files and scripts/check-phase35.sh; any production change is in a separate `fix(...)` commit recorded as a deviation in the SUMMARY
</acceptance_criteria>
<done>postcard's override, fallback, partial, sample, validation, sync and Branding rules are pinned by unit tests.</done>
</task>
<task type="auto" tdd="true">
<name>Task 3: Unit tests for cabana and surf: permission split, save validation, drift, reset, layout delete, test send, locale, diff and field schema</name>
<files>modules/cabana/mail_permissions_postgres_test.go, modules/cabana/mail_lifecycle_postgres_test.go, modules/cabana/mail_test_send_postgres_test.go, modules/cabana/mail_unit_test.go, modules/cabana/field_mail_test.go, modules/surf/store_lookup_test.go, scripts/check-phase35.sh</files>
<read_first>
- modules/cabana/mail_screens_smoke_test.go (newMailScreensEnv) and modules/cabana/administrators_harness_test.go (seedAdmin, seedRole, login, request)
- modules/cabana/mail_admin.go, mail_routes.go, mail_diff.go, field_mail.go (35-02 output)
- modules/surf/store_lookup_test.go and modules/surf/serve.go (installCooler)
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
</read_first>
<behavior>
- TestMailPermissions: matrix of principals (templates-only, layouts-only, both, superuser, none) × (templates list, form PUT, layouts list, partials list, Branding GET and PUT, image list, image upload, Mail images singleton, preview per mode, test send per mode, settings tiles); expected status per UI-SPEC C14 and D-03; after migrations no role or user permission JSON contains either code
- TestMailSave: each postcard rule becomes a 422 on its field with the translated text and :message filled (en and pl), the row is unchanged afterwards; Branding colour 422 colorpicker.invalid; logo id outside the library 422 mailimage.missing; custom layout code format and taken
- TestMailDrift: base_hash stamped on save; file change plus sync gives [customized, outdated]; the status filter outdated; re-save clears; _info shows the callout only when outdated
- TestMailReset and TestMailLayoutDelete: reset per kind restores the file and removes the action from meta.actions; reset not offered on custom layouts; delete of an in-use custom layout is 403 with name and count in en (one and other) and pl (one, few, many); file rows never deletable; meta.deletable values
- TestMailTestSend: recipient is the admin's email only (Cc and Bcc empty), body with to/email/recipient refused, token principal refused, a fake cooler.Attempter published on the app counts per admin and the sixth call returns 429 with Retry-After, a second admin is independent, the in-process fallback limits without a published Attempter, a failing driver gives 502 with the fixed message
- TestMailLocale (-short): TemplateLocale with enabled and unknown suffixes as cabana computes locales; TestMailDiff (-short): lineDiff context, cap, identical inputs; TestMailFieldSchema (-short): codeeditor language, mailImages placement, mailpreview mode, settings-form acceptance of colorpicker, mailimage and mailpreview
- surf TestInstallCoolerPublishesAttempter: installCooler with the Redis rate-limit store publishes a cooler.Attempter that is the same store as the published Store (miniredis); with the memory store it publishes neither
</behavior>
<action>
Per D-21 (and D-03, D-06, D-07, D-08, D-13, D-17, D-05 it covers): write the tests above with the names VALIDATION.md lists (TestMailPermissions, TestMailSave, TestMailDrift, TestMailReset, TestMailLayoutDelete, TestMailBrand, TestMailTestSend, TestMailLocale) plus TestMailDiff and TestMailFieldSchema, reusing newMailScreensEnv and the 19.6.1 harness helpers; Postgres tests skip under testing.Short. Add the names to GO_TESTS / DOCKER_TESTS in scripts/check-phase35.sh. Fix production defects only as described in Execution units. Commit as listed.
</action>
<verify>
<automated>go test ./modules/cabana -run 'TestMailPermissions|TestMailSave|TestMailDrift|TestMailReset|TestMailLayoutDelete|TestMailBrand|TestMailTestSend' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -30</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, "no tests to run", or no "--- PASS: TestMailTestSend" or "--- PASS: TestMailPermissions" line</fails_when>
<automated>go test -short ./modules/cabana ./modules/surf -run 'TestMailLocale|TestMailDiff|TestMailFieldSchema|TestInstallCoolerPublishesAttempter' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -10</automated>
<fails_when>a "FAIL" line, "no tests to run", or no "--- PASS: TestInstallCoolerPublishesAttempter" or "--- PASS: TestMailDiff" line</fails_when>
<automated>bash scripts/check-phase35.sh --go --docker</automated>
<fails_when>non-zero exit or a "FAIL" or "missing " line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "func TestMailPermissions" modules/cabana/mail_permissions_postgres_test.go` and `grep -n "func TestMailTestSend" modules/cabana/mail_test_send_postgres_test.go` each print one line
- `grep -n "Retry-After" modules/cabana/mail_test_send_postgres_test.go` prints at least one line
- `grep -n "cooler.Attempter" modules/surf/store_lookup_test.go` prints at least one line
- `grep -n "TestMailLayoutDelete" scripts/check-phase35.sh` prints at least one line
</acceptance_criteria>
<done>The permission split, the recipient rule, the limit and every admin-side refusal are pinned by unit tests.</done>
</task>
<task type="auto" tdd="true">
<name>Task 4: SPA unit and browser tests for the mail editor, the filled validation map and the full gate</name>
<files>admin/tests/form/CodeEditorField.test.ts, admin/tests/form/MailPreviewField.test.ts, admin/tests/form/insertImage.test.ts, admin/tests/form/MailImagePicker.test.ts, admin/tests/form/ColorPickerField.test.ts, admin/tests/form/MailImageField.test.ts, admin/tests/form/FormViewMail.test.ts, admin/tests/list/RowStateBadges.test.ts, admin/tests/views/SettingsFormView.test.ts, admin/tests/browser/codeeditor.test.ts, scripts/check-phase35.sh, .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md</files>
<read_first>
- admin/tests/form/mail-smoke.test.ts and admin/tests/browser/codeeditor-smoke.test.ts (35-03 output; extend coverage, do not duplicate)
- admin/tests/form/RichEditorField.test.ts, admin/tests/form/FormView.test.ts, admin/tests/list/RowStateBadges.test.ts, admin/tests/views/SettingsFormView.test.ts (mount patterns, api mocks)
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md (UI Considerations rows marked backstop: footer reset, meta.deletable, codeeditor keyboard, insertImage, mailpreview failure and sandbox)
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
</read_first>
<behavior>
- codeeditor (browser): Tab and Shift+Tab leave the editor; Mod+S and Mod+Enter save; Esc does not cancel; undo and redo through history; the Go action decoration on `{{ .Name }}`; text wraps, html does not
- CodeEditorField (happy-dom): heights per size, loading box, failure fallback textarea saves, read-only pre, external value replacement without an emit
- insertImage: the full C4 table plus spaces and parentheses in URLs and empty alt
- MailPreviewField: sandbox empty and no src, srcdoc only from 2xx, sequence guard, failed and failed_first and unavailable, empty draft sends nothing, inactive tab sends nothing, test send 2xx toast with email, 429 seconds and disabled button, 422 inline, 5xx toast, branding mode without subject row and test send
- MailImagePicker: canUpload true and false, empty-library copy per mode, no results, load failed, 409 server message, upload success selects the new tile, 422 upload line, primary disabled until chosen, radiogroup keys, alt prefill in insert mode only
- ColorPickerField and MailImageField: per UI-SPEC C2 and C11
- FormViewMail: footer reset with danger confirm, busy disables the footer, success toast plus reload plus clean form plus reloadKey bump, 409 and 403 paths, meta.deletable false/true/absent, no footer actions on a controller with a preview screen
- RowStateBadges: five states in order with the two new styles; SettingsFormView: FORM_VALUES and FORM_LOCALE provided
</behavior>
<action>
Per D-21: write the SPA tests above (happy-dom unit tests under admin/tests/form, list and views; the browser test under admin/tests/browser), add every new file to ADMIN_FILES and codeeditor to the required browser files in scripts/check-phase35.sh, and commit as listed. Then fill 35-VALIDATION.md: every per-decision row gets the final command and status, the Wave 0 items are checked (or name the plan that delivered them), `wave_0_complete: true` and `nyquist_compliant: true` in its front matter when every row is green, and commit it as a separate planning-docs commit. Finally run `bash scripts/check-phase35.sh --all` (with PHASE35_ALLOW_NO_DOCKER=1 only if Docker is unavailable, recorded in the SUMMARY).
</action>
<verify>
<automated>npm --prefix admin run test 2>&1 | tail -6 && npm --prefix admin run test:browser 2>&1 | tail -6</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>bash scripts/check-phase35.sh --all</automated>
<fails_when>non-zero exit, a "FAIL", "missing ", "NOT RUN" (without the allow variable) or marker hit line</fails_when>
</verify>
<acceptance_criteria>
- `ls admin/tests/form/insertImage.test.ts admin/tests/form/MailPreviewField.test.ts admin/tests/browser/codeeditor.test.ts` lists all three
- `grep -n "nyquist_compliant: true" .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md` prints one line
- `grep -c "⬜ pending" .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md` prints 0
- `git log --format=%s -F --grep='docs(35): fill the validation map'` prints one line, and `git show --stat --format= <that commit>` lists only 35-VALIDATION.md
</acceptance_criteria>
<done>The mail editor's UI rules are pinned by tests, the validation map is complete and the phase gate is green.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| gate script → sibling repositories | the consumers stage runs go commands inside ../sm-user-plugin and ../sm-paymentgateway-plugin |
| tests → Docker | testcontainers start Postgres containers on the host |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-35-25 | Tampering | consumers stage | medium | mitigate | read-only commands (go list, go vet, go test); acceptance compares `git status --short` of both repositories before and after a run |
| T-35-26 | Repudiation | a gate that passes on zero tests | high | mitigate | go test -json detection fails on skips, zero matches, "no tests to run" and missing required names; self-test plants each case |
| T-35-27 | Elevation of privilege | security regressions after the phase | high | mitigate | TestMailPermissions, TestMailTestSend and the preview sandbox tests pin T-35-09, T-35-11 and T-35-19 so a regression fails the gate |
| T-35-28 | Information disclosure | test fixtures | low | mitigate | fixtures use neutral plugin IDs and example.test addresses; the marker stage refuses consuming-application names |
| T-35-SC | Tampering | npm/pip/cargo installs | high | accept | this plan installs no package |
</threat_model>
<verification>
- `bash scripts/check-phase35.sh --all` green (Docker host), including the consumers stage.
- `go vet ./... && go test ./...`, `npm --prefix admin run test`, `npm --prefix admin run test:browser`, `npm --prefix admin run typecheck`, `scripts/check-admin-openapi.sh --check`, `scripts/check-admin-dist.sh`, `summer docs:build --check` green.
</verification>
<success_criteria>
- Every D-21 item has named unit tests; SPA backstop rows of the UI-SPEC have tests.
- check-phase35.sh exists, fails closed, and proves the two core plugins' mail unchanged.
- 35-VALIDATION.md is complete; nothing pushed or tagged; no sibling repository changed.
</success_criteria>
<output>
Create `.planning/phases/35-mail-templates-and-layouts-editor/35-04-SUMMARY.md` when done; list every deviation fix commit and the final `--all` result.
</output>
## Artifacts this phase produces
- Script: `scripts/check-phase35.sh` with `--self-test`, `--go`, `--docker`, `--consumers`, `--admin`, `--docs`, `--marker`, `--additive`, `--all`; environment `PHASE35_BASE_TAG`, `PHASE35_ALLOW_NO_DOCKER`.
- Go tests: `TestOverride*`, `TestFallback*`, `TestPartial*`, `TestSample*`, `TestValidateDraft*`, `TestBrand*`, `TestStore*`, `TestSync*`, `TestAbsolutePublicURL`, updated `TestRowStateValues`, `TestMailPermissions`, `TestMailSave`, `TestMailDrift`, `TestMailReset`, `TestMailLayoutDelete`, `TestMailBrand`, `TestMailTestSend`, `TestMailLocale`, `TestMailDiff`, `TestMailFieldSchema`, `TestInstallCoolerPublishesAttempter`.
- SPA tests: `CodeEditorField.test.ts`, `MailPreviewField.test.ts`, `insertImage.test.ts`, `MailImagePicker.test.ts`, `ColorPickerField.test.ts`, `MailImageField.test.ts`, `FormViewMail.test.ts`, updated `RowStateBadges.test.ts` and `SettingsFormView.test.ts`, browser `codeeditor.test.ts`.
- Planning: filled `35-VALIDATION.md`.
- No new exported identifiers, config keys or dependencies.

View File

@@ -0,0 +1,169 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 04
subsystem: testing
tags: [postcard, cabana, surf, vitest, check-phase35, nyquist]
requires:
- phase: 35-01
provides: postcard override/partial/brand/editor smoke and DB helpers
- phase: 35-02
provides: cabana mail admin API and newMailScreensEnv harness
- phase: 35-03
provides: SPA mail fields, codeeditor, boardwalk dist
provides:
- scripts/check-phase35.sh fail-closed phase gate
- postcard/pact/attach unit tests for D-21 override/fallback/partials/samples/brand/sync
- cabana/surf unit tests for permissions, save, drift, reset, layout delete, test-send, Attempter
- SPA unit and browser tests for mail editor fields
- filled 35-VALIDATION.md (nyquist_compliant: true)
affects: [msd-verify-work, phase-35-complete]
actuals:
tokens: 45000
tasks: 4
commits: 11
plan_head_before: 95eed7ad9814004c6c894e659b45bb74c65801b4
plan_head_after: c7e7fcc6a0edb5f3157643f4024d96dca5530d2a
tech-stack:
added: []
patterns:
- "check-phase35.sh stages mirror check-phase34 (self-test/go/docker/consumers/admin/docs/marker/additive)"
- "mailEnv drift via second process keep:true + changed MapFS"
- "MailPreviewField IntersectionObserver gates preview POSTs on inactive tabs"
key-files:
created:
- scripts/check-phase35.sh
- modules/postcard/override_test.go
- modules/postcard/partials_test.go
- modules/postcard/samples_test.go
- modules/postcard/editor_test.go
- modules/postcard/brand_test.go
- modules/postcard/store_postgres_test.go
- modules/cabana/mail_permissions_postgres_test.go
- modules/cabana/mail_lifecycle_postgres_test.go
- modules/cabana/mail_test_send_postgres_test.go
- modules/cabana/mail_unit_test.go
- modules/cabana/field_mail_test.go
- admin/tests/form/CodeEditorField.test.ts
- admin/tests/form/MailPreviewField.test.ts
- admin/tests/form/insertImage.test.ts
- admin/tests/form/MailImagePicker.test.ts
- admin/tests/form/ColorPickerField.test.ts
- admin/tests/form/MailImageField.test.ts
- admin/tests/form/FormViewMail.test.ts
- admin/tests/browser/codeeditor.test.ts
modified:
- modules/pact/capabilities_test.go
- modules/lagoon/attach/absolute_test.go
- modules/surf/store_lookup_test.go
- admin/tests/list/RowStateBadges.test.ts
- admin/tests/views/SettingsFormView.test.ts
- admin/src/components/mail/insertImage.ts
- admin/src/components/form/fields/MailPreviewField.vue
- modules/boardwalk/dist
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
key-decisions:
- "Consumer mail tests run as package `.` (not `./...`) so detect_go sees named tests"
- "Inactive-tab preview uses IntersectionObserver; document.hidden is not the signal"
patterns-established:
- "Phase gate consumers stage is read-only against sibling plugin checkouts"
- "Deviation fixes for SPA defects found by unit tests get their own fix(...) commits before the test commit"
requirements-completed: [D-21, D-03, D-06, D-07, D-11, D-12, D-13, D-14, D-15, D-17, D-23]
coverage:
- id: D1
description: "fail-closed check-phase35.sh covering framework, admin, docs, consumers"
requirement: D-21
verification:
- kind: other
ref: "bash scripts/check-phase35.sh --all"
status: pass
human_judgment: false
- id: D2
description: "postcard override/fallback/partial/sample/brand/store/sync unit tests"
requirement: D-21
verification:
- kind: unit
ref: "go test ./modules/postcard -run 'TestOverride|TestFallback|TestPartial|TestSample|TestValidateDraft|TestBrand|TestStore|TestSync'"
status: pass
human_judgment: false
- id: D3
description: "cabana permission/save/drift/reset/layout-delete/test-send and surf Attempter"
requirement: D-21
verification:
- kind: unit
ref: "go test ./modules/cabana -run 'TestMailPermissions|TestMailSave|TestMailDrift|TestMailReset|TestMailLayoutDelete|TestMailBrand|TestMailTestSend'"
status: pass
- kind: unit
ref: "go test -short ./modules/surf -run TestInstallCoolerPublishesAttempter"
status: pass
human_judgment: false
- id: D4
description: "SPA mail editor unit and browser tests; filled validation map"
requirement: D-21
verification:
- kind: automated_ui
ref: "npm --prefix admin run test / test:browser"
status: pass
- kind: other
ref: ".planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md nyquist_compliant: true"
status: pass
human_judgment: false
duration: ~90min
completed: 2026-11-13
status: complete
---
# Phase 35 Plan 04: Unit tests and phase gate
**D-21 coverage and `scripts/check-phase35.sh --all` are green**, including sibling sm-user and sm-paymentgateway mail tests against this checkout.
## Performance
- **Duration:** ~90 min
- **Tasks:** 4
- **Commits:** 11 (gate, postcard, cabana, three admin fixes + dist, SPA tests, two validation docs)
## Accomplishments
- Fail-closed `scripts/check-phase35.sh` with self-test, go, docker, consumers, admin, docs, marker, additive stages
- Postcard/pact/attach unit tests for override precedence, fallback, partials, samples, validation, branding, sync
- Cabana/surf unit tests for permission split, save 422s, drift, reset, layout delete, test-send limits, Attempter publish
- SPA unit + browser tests for codeeditor, mailpreview, insertImage, picker, color/mailimage, FormView reset/deletable, badges
- `35-VALIDATION.md` filled; `nyquist_compliant: true`, `wave_0_complete: true`
## Deviations from plan
| Commit | Why |
|--------|-----|
| `e81cfde7` fix(admin): restore suite after colorpicker and codeeditor registration | Task 1/2 gate `--admin` failed on existing suite after Phase 35 field registration |
| `1df2e31d` fix(admin): isolate CodeMirror load for chunk-failure tests | Chunk-failure mock needed `codeeditor/load.ts` indirection |
| `275e70b4` fix(admin): encode parentheses in markdown mail image URLs | `encodeURIComponent` leaves `()`; UI-SPEC C4 / insertImage tests required `%28`/`%29` |
| `52e854a1` + `45017039` fix(admin): skip off-screen preview + rebuild dist | Inactive-tab rule (UI-SPEC C10) was missing; IntersectionObserver added |
## Task commits
1. `5f62cd6b` test(35): phase gate script check-phase35.sh
2. `659969b9` test(postcard): unit tests for overrides, fallback, partials, samples, validation, sync and branding
3. `cd20540f` test(cabana): unit tests for mail permissions, save validation, drift, reset, layout delete and test send
4. `1ae1a955` test(admin): unit and browser tests for the mail editor fields
5. `31d019fc` docs(35): fill the validation map (+ `ed696bc7` status-key cleanup)
## Gate result
`bash scripts/check-phase35.sh --all` → **Phase 35 gate passed** (Docker host available; `PHASE35_ALLOW_NO_DOCKER` unset).
## Self-Check: PASSED
- Acceptance greps for Task 1–4 subjects and artifacts
- `--all` green including consumers and docker stages
- No sibling repository dirty from consumers stage
- Nothing pushed or tagged

View File

@@ -0,0 +1,352 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 05
type: execute
wave: 5
depends_on: ["35-04"]
gap_closure: true
gap_ids: [G-35-1]
files_modified:
- modules/postcard/store.go
- modules/postcard/templates.go
- modules/postcard/mailer.go
- modules/postcard/editor.go
- modules/postcard/override_smoke_test.go
- modules/postcard/README.md
- modules/cabana/mail_admin.go
- modules/cabana/mail_routes.go
- modules/cabana/crud.go
- modules/cabana/relation_field.go
- modules/cabana/backendscreens/models/mailtemplate/columns.yaml
- modules/cabana/backendscreens/controllers/mailtemplates/config_filter.yaml
- modules/cabana/backendscreens/controllers/mailtemplates/_info.htm
- modules/cabana/mail_screens_smoke_test.go
- modules/cabana/mail_unit_test.go
- modules/cabana/README.md
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- admin/openapi/admin.json
- admin/src/api/schema.d.ts
- admin/src/views/FormView.vue
- admin/src/components/form/LocaleVariantSwitcher.vue
- admin/tests/form/LocaleVariantSwitcher.test.ts
- modules/boardwalk/dist
- docs/services/mail.md
- docs/backend/forms.md
- .planning/notes/2026-11-13-mail-template-locale-groups.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md
autonomous: true
requirements: [G-35-1, D-05, D-06, D-07, D-13, D-16]
estimate:
tokens: 150000
raw_tokens: 150000
tasks: 3
confidence: low
must_haves:
truths:
- "Settings → Mail templates shows one row per template (its base code, the locale suffix stripped), however many locales the application has; acme.blog::mail.welcome and acme.blog::mail.welcome-en are one row (G-35-1, supersedes D-05)"
- "Each list row says which locales are customized (Customized locales column), and carries the Customized / File changed badges when any of its locales is customized / drifted; the status filter works on the whole template (D-07)"
- "The template form has a locale switcher listing Default, every locale with its own file, and every other application locale; choosing one opens that locale's version in the same screen, behind the existing unsaved-changes confirm"
- "A locale with neither a file nor a customization shows the default-locale version (what that locale sends today); saving it creates that locale's own customized version; Reset to file version returns it to the default-locale version; File changed shows when the file it was based on changes (D-06, D-07)"
- "Sending <template>-<locale> uses that locale's file or customization first, then the default-locale customization, then the default-locale file; sending a name that has its own file is unchanged, so sm-user-plugin and sm-paymentgateway-plugin send exactly as before"
- "Saves, preview and test send of any locale go through postcard's Editor exactly as before (D-13, D-16)"
- "D-05 is superseded by a decision note and the UI-SPEC carries the locale switcher contract"
prohibitions:
- statement: "pact.HasMailTemplates, postcard.Mailer, Message, Catalog.Register, OverrideSource and SyncIndex keep their signatures; every postcard and cabana API change is additive (check-phase35.sh additive stage)."
status: unresolved
verification: automated
- statement: "No file in a sibling repository (sm-user-plugin, sm-paymentgateway-plugin or any other) is changed by this plan."
status: unresolved
verification: judgment
- statement: "Nothing is pushed or tagged."
status: unresolved
verification: judgment
artifacts:
- path: "modules/postcard/store.go"
provides: "base_code migration and EnsureLocaleRows"
contains: "func EnsureLocaleRows"
- path: "modules/postcard/templates.go"
provides: "TemplateBase and Catalog.TemplateFor"
contains: "func (c *Catalog) TemplateFor"
- path: "modules/cabana/relation_field.go"
provides: "RecordMeta.LocaleVariants"
contains: "LocaleVariants"
- path: "admin/src/components/form/LocaleVariantSwitcher.vue"
provides: "locale switcher in the update form"
contains: "data-locale-variant"
- path: ".planning/notes/2026-11-13-mail-template-locale-groups.md"
provides: "decision note superseding D-05"
contains: "D-05"
key_links:
- from: "modules/postcard/mailer.go"
to: "modules/postcard/templates.go"
via: "render resolves a fallback-locale name to its base file through the catalog resolver"
pattern: "TemplateFor|resolveTemplate"
- from: "modules/cabana/mail_admin.go"
to: "modules/postcard/store.go"
via: "the index sync and the show hook create the fallback-locale rows"
pattern: "postcard.EnsureLocaleRows"
- from: "admin/src/views/FormView.vue"
to: "admin/src/components/form/LocaleVariantSwitcher.vue"
via: "FormView renders the switcher from meta.localeVariants"
pattern: "localeVariants"
---
## Phase Goal
ROADMAP Goal (not in user-story format; no story is invented): administrators edit every mail the application sends from the admin panel. This gap-closure plan fixes UAT gap G-35-1: locale variants of one template were separate list rows (D-05), which does not scale to a site with many locales. After this plan a template is one record with a locale switcher, and a locale that ships no file can still get its own customized version.
Source: 35-UAT.md (G-35-1, test 1, severity major), user decision of 2026-11-13 confirming three gap-closure plans (this one is framework only; the decision note supersedes D-05).
<objective>
Turn mail templates into one admin record per template with per-locale versions:
- postcard groups template rows by a base code, creates rows for application locales that ship no file, and resolves `<template>-<locale>` at send time to that locale's file or customization first, then the default-locale version;
- cabana lists one row per template with the customized locales and grouped row states, and the template form shows a locale switcher; customized / reset / drift status stays per locale;
- the SPA renders the switcher from a new `meta.localeVariants` on the record response;
- a decision note supersedes D-05 and the UI-SPEC gets the switcher contract.
Purpose: a site with 50 locales gets one row per template, not 50, and administrators can write mail for locales the plugins never shipped.
Output: commits in this repository only (code, one dist rebuild, one planning-docs commit). Nothing in sibling repositories, nothing pushed or tagged.
**Planner decisions recorded here (Claude's discretion within the user's 2026-11-13 decision):**
- **Group key.** `base_code` is the template code with a locale suffix stripped, using the same rule as `postcard.TemplateLocale` (suffix after a dash in the last dotted segment, one of the mail locales). A code without such a suffix is its own base.
- **Mail locales** (cabana): the phrasebook translator's `Locales("")` (today's source) plus, when a `cabana.TranslationWriter` is published and answers, its `EnabledLocales`; the default locale is the writer's `DefaultLocale` when published, otherwise the translator's `Locale()`. This is what makes a 50-locale site (locales enabled through a translate plugin) show 50 entries in the switcher.
- **Variants of one template** (switcher order): Default (the unsuffixed file, labelled with the existing `mail.template.locale_default`), then by locale code: every locale with its own file, every other mail locale except the default ("fallback locale": no file, a row created by `postcard.EnsureLocaleRows`), and any customized row of a locale that is no longer enabled. The default locale gets no fallback row because the unsuffixed file already is the default-locale version. A group whose base has no file (only `x-en.htm` shipped) has no Default and no fallback rows.
- **Send resolution** (postcard, independent of any locale list, so `queue:work` needs no cabana): a name with its own file renders exactly as today. A name the catalog does not hold of the form `<base>-<tag>`, where `<base>` is a registered template and `<tag>` is a two-letter language optionally followed by `-` or `_` and a 2–8 character alphanumeric subtag (case-insensitive; the longest registered base wins), renders the base file with: the name's own customized row, else the base's customized row, else nothing (the base file). Any other unknown name fails with today's "unknown template" error text.
- **What a not-customized fallback row shows**: the default-locale version as it is sent now (the base row's effective subject, body and layout), substituted into the show response; saving it makes the row customized with `base_hash` = the base file's hash; its `file_hash` follows the base file, so drift shows when the default file changes; reset returns it to the base file.
- **Switcher data** travels on the show response as `meta.localeVariants` (`cabana.RecordMeta.LocaleVariants`, omitempty), set through an unexported controller interface like `recordDeletable`, so no other controller's payload changes. Labels and state words are translated on the server; the SPA shows them as text.
- **The list locale filter is removed** (one row per template makes it meaningless); the status filter stays and applies to the whole template.
- New copy keys (en/pl, Polish as design language): `form.locale_variant` ("Language" / "Język"), `mail.template.customized_locales` ("Customized locales" / "Dostosowane języki"), `mail.info_locale_default` ("Default version: sent for every locale that has neither its own file nor a customized version." / "Wersja domyślna: wysyłana dla każdego języka, który nie ma własnego pliku ani dostosowanej wersji."), `mail.info_locale_fallback` ("Locale :locale has no file of its own. Until you customize it, the default version is sent." / "Język :locale nie ma własnego pliku. Dopóki go nie dostosujesz, wysyłana jest wersja domyślna.").
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-CONTEXT.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-01-SUMMARY.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-02-SUMMARY.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-03-SUMMARY.md
@CLAUDE.md
<interfaces>
postcard (35-01):
- modules/postcard/templates.go: `lookupTemplate(name)` (~243) is the one lookup that send, preview and validation go through; `(*Catalog).render` (~492); `TemplateFile` (~760); `(*Catalog).Template(name)` (~862); `TemplateLocale(name, locales)` (~924) is the suffix rule to reuse.
- modules/postcard/mailer.go: `(*mailer).render` (~103) pre-checks `lookupTemplate(msg.Template)` then asks `m.overrides(ctx, msg.Template)` (~157) once; `Send` doc comment (~67) says postcard performs no locale selection.
- modules/postcard/store.go: `Migrations` (~37, one migration today); `dbSource.MailOverrides` (~209) reads `WHERE t.code = ? AND t.is_custom`; `syncLockKey` + `SyncIndex(ctx, db, cat, locales)` (~341-436) upserts one row per file with `locale = TemplateLocale(...)`; `ResetOverride` (~452) refuses a code `cat.Template` does not hold.
- modules/postcard/editor.go: `renderTemplate` (~209) calls `cat.lookupTemplate(d.Name)` and uses its samples.
- modules/postcard/override_smoke_test.go: `mailPostgres(t)`, `bootMailApp`; subtest `migrations_roll_back` (~531) calls `RollbackLast` once and expects no mail table left (must roll back every migration once a second one exists); `unknown_template` (~523) must keep its error text.
cabana (35-02):
- modules/cabana/mail_admin.go: `locales()` (~166), `sync` (~172), `syncOnDatabase` (~185), `ensureSynced` (~194); `MailTemplate` model (~283) and its `FilterScopes`/`FilterScope` (~304-320); `scopeTemplates` (~438), `ListExtendQuery`, `FormExtendQuery`, `ListExtendRecords` (~459, Default label), `ListRowStates` (~491), `FilterOptions` (~505), `AdminRecordActions` reset (~525), `PartialData` (~537), `FormBeforeUpdate` (~573, `catalog().Template(t.Code)`), `FormAfterUpdate` (~594); `recordDeletable` interface (~643); `mailInfoView` (~1302).
- modules/cabana/mail_routes.go: `mailTemplateDraft` (~507) refuses a code `editor.Catalog().Template` does not hold.
- modules/cabana/crud.go: `ShowRecord` (~517) sets `Meta.Deletable` through `recordDeletable` (~553); `recordDataExtender` (~697) lets this package's controllers add or replace keys in the record data.
- modules/cabana/relation_field.go: `RecordMeta` (~104) with `Deletable *bool` as the precedent for a controller-decided meta key.
- modules/cabana/field_ml.go: `TranslationWriter` (~24: `DefaultLocale`, `EnabledLocales`); modules/cabana/http.go `enabledContentLocales` (~1182) shows the lookup.
- modules/phrasebook/translator.go: `Locale()` (~143), `Locales(prefix)` (~544).
- modules/cabana/mail_screens_smoke_test.go: `newMailScreensEnvWith` (~152) with fixture plugin acme.blog (`blogWelcome`, `blogWelcomeEn` ~45); subtest `templates` (~252) asserts the locale column; `drift` (~542) uses the locale filter.
admin (35-03):
- admin/src/views/FormView.vue: record meta read (~266-268, `deletable`), header with title and FormTabs (~695-710), `onBeforeRouteLeave`/`onBeforeRouteUpdate(guard)` (~664) with the unsaved-changes confirm.
- admin/src/App.vue keys the RouterView by path, so navigating to another record id remounts FormView (fresh load).
- admin/src/api/types.ts: `RecordMeta = Schemas['cabana.RecordMeta']` (regenerated by scripts/check-admin-openapi.sh).
</interfaces>
</context>
## Execution units and resume points
- Other sessions edit cabana and the SPA concurrently. Before each task run `git status --short modules/postcard modules/cabana modules/phrasebook admin modules/boardwalk docs` and stop if another session holds uncommitted edits in files this task touches; re-check the line numbers in `<interfaces>` before editing.
- Stage files by explicit path; never `git add -A`. Code and planning docs go in separate commits. Each commit keeps `go vet ./...` and `go test ./...` green.
- Docker-backed tests run without `-short` (through `sudo -u golem` if the Docker socket is denied although the user is in the docker group).
- Resume check: `git log --format=%s -F --grep='<subject>'`.
- The tracer task (Task 1) is large under the lean-planning rule. It may land as several sub-commits (for example postcard, then cabana, then admin) as long as each one keeps `go vet ./...` and `go test ./...` green and carries its own README/docs changes. The last sub-commit uses the subject listed below, so the resume check still works.
| Task | Commit subject | Resume point |
|------|----------------|--------------|
| 1 | `feat(mail): one admin record per mail template with a locale switcher` | TestMailScreensSmoke/locales and TestMailOverrideSmoke/locale_fallback pass |
| 2 | `feat(cabana): mail templates list grouped by template with per-locale status` then `build(admin): rebuild the embedded admin for the mail locale switcher` | TestMailScreensSmoke/locales_list passes; scripts/check-admin-dist.sh passes |
| 3 | `docs(35): decision note superseding D-05 and the locale switcher contract` | the note exists and 35-UI-SPEC.md has the C16 section |
<tasks>
<task type="tracer">
<name>Task 1: End-to-end "an administrator opens acme.blog::mail.welcome, switches to a locale without a file (de), saves a subject, and sending acme.blog::mail.welcome-de uses it" — one fallback locale only</name>
<reversibility rating="costly">The base_code column and the fallback-locale rows are part of postcard's table schema (a gormigrate migration on every install); RecordMeta.LocaleVariants is a published admin API field.</reversibility>
<precondition>35-04 is complete: `git log --format=%s -F --grep='test(35): phase gate script check-phase35.sh'` prints one line, and `grep -n "func SyncIndex" modules/postcard/store.go` prints one line</precondition>
<files>modules/postcard/store.go, modules/postcard/templates.go, modules/postcard/mailer.go, modules/postcard/editor.go, modules/postcard/override_smoke_test.go, modules/postcard/README.md, modules/cabana/mail_admin.go, modules/cabana/mail_routes.go, modules/cabana/crud.go, modules/cabana/relation_field.go, modules/cabana/mail_screens_smoke_test.go, modules/cabana/README.md, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, admin/openapi/admin.json, admin/src/api/schema.d.ts, admin/src/views/FormView.vue, admin/src/components/form/LocaleVariantSwitcher.vue, admin/tests/form/LocaleVariantSwitcher.test.ts, docs/services/mail.md, docs/backend/forms.md</files>
<read_first>
- modules/postcard/templates.go (whole file), modules/postcard/mailer.go (~60-175), modules/postcard/store.go (whole file), modules/postcard/editor.go (~185-240)
- modules/postcard/override_smoke_test.go (~1-120 helpers, ~281-315 override subtest, ~523-548)
- modules/cabana/mail_admin.go (~1-660), modules/cabana/mail_routes.go (~488-660), modules/cabana/crud.go (~505-560 and ~697-755), modules/cabana/relation_field.go (~95-125), modules/cabana/field_ml.go (~1-40), modules/cabana/http.go (~1175-1205)
- modules/cabana/mail_screens_smoke_test.go (~1-260)
- admin/src/views/FormView.vue (~80-120, ~250-290, ~620-720), admin/src/components/form/fields/MLField.vue (the locale select markup and classes to copy), admin/tests/form/FormViewMail.test.ts (mount helpers)
- .planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md (G-35-1)
</read_first>
<action>
Supersedes D-05 per the user's 2026-11-13 decision (G-35-1); D-13 and D-16 paths are reused unchanged. Build the thinnest complete path through postcard, cabana and the SPA:
- postcard, store.go: append migration `202611130001_mail_template_base_code` adding nullable `base_code TEXT` to the templates table plus an index `system_mail_templates_base_code_index`; its Rollback drops both. `SyncIndex` writes `base_code` (the new `TemplateBase`, with the same locales it already receives) and its WHERE clause also refreshes a row whose base_code differs. New exported `EnsureLocaleRows(ctx, db, cat, defaultLocale string, locales []string, bases ...string) error`: for every catalog template that is a base (TemplateBase(name) == name; all of them when `bases` is empty, else only those listed) and every locale in `locales` other than `defaultLocale` for which the catalog has no `<base>-<locale>` file, upsert a row with code `<base>-<locale>`, source = the base's plugin ID, locale, base_code = base, description, subject, body and layout_id from the base file, file_hash = the base file's hash; on conflict a customized row keeps its content columns while file_hash, description and base_code follow the base; a matching row is not written; no row is deleted; it takes the same advisory lock as SyncIndex. `ResetOverride` is untouched in this task (Task 2).
- postcard, templates.go: exported `TemplateBase(name string, locales []string) string` (the name without the suffix TemplateLocale finds, else the name) and `(*Catalog) TemplateFor(name string) (TemplateFile, bool)` returning the file a name renders from: its own file, or, for a fallback-locale name per this plan's send-resolution rule, the base template's file (the returned Name is the base's, which is how callers tell the two apart). Route every internal send/preview/validate lookup that today calls lookupTemplate with a message or draft name through one unexported resolver implementing the same rule; the "postcard: unknown template <name>" text is unchanged for names that resolve to nothing.
- postcard, mailer.go: when the resolver maps msg.Template to a different base, ask the override source for msg.Template first and, when that returns no template override, for the base and take only its template override (layouts, partials and Branding are identical in both answers). Render the base file with that override. Update the Send doc comment: postcard still picks no locale; it resolves a missing `<template>-<locale>` to the default-locale version.
- postcard, editor.go: template drafts accept a fallback-locale name (resolver), using the base file's samples.
- postcard tests (smoke, Postgres): new subtest `locale_fallback` in TestMailOverrideSmoke: with a customized row for `acme.blog::mail.welcome-de` (created through EnsureLocaleRows then updated is_custom) Send of `welcome-de` uses its subject; Send of `welcome-fr` (no row) sends the base file, and after customizing the base row it sends the base customization; Send of `welcome-en` (own file) is unchanged; Send of `acme.blog::mail.missing-de` keeps the unknown-template error. Update `migrations_roll_back` to roll back every migration (one RollbackLast per entry of Migrations) before asserting no mail table is left.
- cabana, mail_admin.go: replace `locales()` by a `mailLocales(ctx)` returning the default and the union described in this plan's decisions (translator plus TranslationWriter when published). `sync` calls SyncIndex and then EnsureLocaleRows for all bases, remembers the locale set it synced with, and `ensureSynced` re-syncs when the current set differs. `FormExtendQuery` (record lookups) admits every row whose code is a catalog template or whose base_code is a catalog template's base (fallback rows); `ListExtendQuery` is unchanged in this task. `FormRecordTitle` shows the row's base code. `FormBeforeUpdate` stamps base_hash/file_hash from `catalog().TemplateFor(t.Code)` (the base file's hash for a fallback row). The mail templates controller implements a new unexported interface (sibling of recordDeletable, e.g. `recordLocaleVariants`) that first calls EnsureLocaleRows for this record's base only (idempotent; it keeps a newly enabled locale reachable without a restart) and then returns the variants of the record's group in the switcher order of this plan, each with the row id, locale, a translated label (`mail.template.locale_default` for Default, else the locale code), translated state words (`mail.state_customized`, `mail.state_outdated`) and Current for the open row.
- cabana, mail_routes.go: `mailTemplateDraft` accepts a code `TemplateFor` resolves (preview and test send of a fallback row).
- cabana, relation_field.go + crud.go: `RecordMeta.LocaleVariants []RecordLocaleVariant` with json `localeVariants,omitempty`; exported `RecordLocaleVariant{ID uint, Locale string, Label string, States []string, Current bool}` (json camelCase); ShowRecord fills it inside its transaction when the controller implements the unexported interface. Regenerate `admin/openapi/admin.json` and `admin/src/api/schema.d.ts` with `scripts/check-admin-openapi.sh`.
- SPA: new `admin/src/components/form/LocaleVariantSwitcher.vue`: a labelled native select (label text `backend::lang.form.locale_variant`, markup and classes copied from MLField's locale select, attribute `data-locale-variant`), one option per variant with the text "Label" or "Label — state, state", the current one selected. On change it router-pushes the same route with the chosen id; when the navigation is refused (unsaved-changes confirm cancelled) it puts the selection back. FormView reads `record.meta.localeVariants` next to `deletable` and renders the switcher in the header under the title when there are two or more variants. Copy `form.locale_variant` en/pl in the phrasebook.
- Tests in this task (smoke): `TestMailScreensSmoke/locales` in mail_screens_smoke_test.go, on an env with a fake TranslationWriter published (EnabledLocales pl, en, de; DefaultLocale pl): GET of welcome's update record returns localeVariants Default (current), de (no states), en; GET of the de id shows code-based title welcome; PUT a subject on the de row gives 200 and is_custom; the published Mailer's Send of `acme.blog::mail.welcome-de` uses that subject and Send of `acme.blog::mail.welcome` does not; POST /mail/preview for the de id answers 200. `admin/tests/form/LocaleVariantSwitcher.test.ts`: renders options with labels and states, marks the current one, pushes the sibling id on change and restores the selection when the push is rejected.
- Docs in the same commit (CLAUDE.md documentation rules): postcard README (API reference rows for TemplateBase, Catalog.TemplateFor and EnsureLocaleRows; the send-resolution rule in Usage; the base_code column under "Index rows, drift and reset"), cabana README (RecordMeta.LocaleVariants row, the mail locales source), docs/services/mail.md ("Sending": replace the "postcard does not pick a locale" paragraph with the resolution rule and the dash-suffix convention), docs/backend/forms.md (`meta.localeVariants` next to `meta.deletable`).
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/postcard -run 'TestMailOverrideSmoke' -count=1 -v 2>&1 | grep -E '^\s*(--- |FAIL|ok|PASS)' | tail -20</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, or no "--- PASS: TestMailOverrideSmoke/locale_fallback" line</fails_when>
<automated>go test ./modules/cabana -run 'TestMailScreensSmoke' -count=1 -v 2>&1 | grep -E '^\s*(--- |FAIL|ok|PASS)' | tail -30</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, or no "--- PASS: TestMailScreensSmoke/locales" line</fails_when>
<automated>npm --prefix admin run test -- tests/form/LocaleVariantSwitcher.test.ts tests/form/FormViewMail.test.ts 2>&1 | tail -8 && npm --prefix admin run typecheck</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go vet ./... && go test -short ./... && bash scripts/check-admin-openapi.sh --check</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "202611130001_mail_template_base_code" modules/postcard/store.go` prints one line
- `grep -n "^func EnsureLocaleRows\|^func TemplateBase\|^func (c \*Catalog) TemplateFor" modules/postcard/*.go` prints three lines
- `grep -n "localeVariants,omitempty" modules/cabana/relation_field.go` prints one line and `grep -c "localeVariants" admin/openapi/admin.json` prints a number above 0
- `grep -n "postcard.EnsureLocaleRows" modules/cabana/mail_admin.go` prints at least two lines (sync and the show hook)
- `grep -n "LocaleVariantSwitcher" admin/src/views/FormView.vue` prints at least one line
- `grep -n "locale_variant" modules/phrasebook/backend/lang/en/lang.yaml modules/phrasebook/backend/lang/pl/lang.yaml` prints two lines
- `grep -n "EnsureLocaleRows\|TemplateFor" modules/postcard/README.md` prints at least two lines
</acceptance_criteria>
<done>An administrator can open a template, switch to a locale that ships no file, save its own version, and mail sent for that locale uses it, while every file-backed name sends as before.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: One list row per template with customized locales and grouped states; per-locale info, file version, show and reset for fallback locales; dist rebuild</name>
<reversibility rating="reversible">List presentation and partial content only; no schema or published API change beyond Task 1.</reversibility>
<files>modules/postcard/store.go, modules/postcard/README.md, modules/cabana/mail_admin.go, modules/cabana/backendscreens/models/mailtemplate/columns.yaml, modules/cabana/backendscreens/controllers/mailtemplates/config_filter.yaml, modules/cabana/backendscreens/controllers/mailtemplates/_info.htm, modules/cabana/mail_screens_smoke_test.go, modules/cabana/mail_unit_test.go, modules/cabana/README.md, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, docs/services/mail.md, modules/boardwalk/dist</files>
<behavior>
- The templates list of the fixture (welcome, welcome-en, a fallback de row) has exactly one row for welcome; its Customized locales value is empty, then "de" after the de row is saved, then "Default, de" after the base is saved too
- Saving only the de row gives the welcome list row the customized badge; a changed base file after that gives it the outdated badge too; the status filter customized / not_customized / outdated returns the welcome row accordingly
- GET of a not-customized de row returns the base row's current subject, body and layout (the base customization when there is one); after a de save it returns de's own values
- The info partial of a de row says the fallback line with :locale de; of the Default row the default line; the file version partial of a de row compares with the base file
- The reset record action on a customized de row returns it to not customized and its show to the default version; ResetOverride of a fallback code no longer errors
- The list config no longer declares a locale filter scope, and `FilterOptions` no longer serves one
</behavior>
<read_first>
- modules/cabana/mail_admin.go (~281-330 model and filter scopes, ~438-610, ~654-760 status helpers and reset action, ~1290-1420 info/file version views)
- modules/cabana/backendscreens/models/mailtemplate/columns.yaml, controllers/mailtemplates/config_filter.yaml, _info.htm, _file_version.htm
- modules/cabana/list_schema.go (~280-290: a `gorm:"-"` field filled by ListExtendRecords is an unstored, unsortable column)
- modules/postcard/store.go ResetOverride (~452-497)
- modules/cabana/mail_screens_smoke_test.go (Task 1's locales subtest, ~252-300 templates, ~542-600 drift)
</read_first>
<action>
Per G-35-1 (supersedes D-05; D-06 reset and D-07 drift now per locale):
- List scope: `ListExtendQuery` keeps one representative row per group: the base row when the base has a file, otherwise the group's lowest code (computed in Go from the catalog and the current mail locales); search, sort and paging work on those rows as before.
- Columns: replace the locale column with `customized_locales` (label `mail.template.customized_locales`), an unstored `gorm:"-"` field on MailTemplate filled in ListExtendRecords from one grouped query over the page's base codes: the labels of the customized rows (Default for the base, else the locale code) joined by ", ", at most three then " +N"; empty when none. Keep code, subject, description, layout and customized_at.
- Row states: `ListRowStates` aggregates per group (one grouped query per page): customized when any row of the group is customized, outdated when any customized row's base_hash differs from its file_hash. The status filter applies to the group (base_code in / not in the set of customized, resp. outdated, groups). Remove the locale scope from config_filter.yaml and the locale branch of FilterScopes, FilterScope and FilterOptions; drop the now-unused Default label code in ListExtendRecords.
- Show: a not-customized fallback row's show data carries the base row's current subject, body and layout (and the layout relation label), through the existing recordDataExtender seam or an equivalent unexported seam, so the form shows what that locale sends now.
- Partials: `_info` adds, for a group with two or more variants, `mail.info_locale_default` on the Default row and `mail.info_locale_fallback` (:locale) on a fallback row; a fallback row's file line names the base file. `_file_version` of a fallback row compares the override with the base file (TemplateFor) and, when not customized, shows the base file under the existing not-customized text.
- Reset: `postcard.ResetOverride(KindTemplate, code)` accepts a fallback-locale code (TemplateFor): it writes the base file's subject, body, layout and hash and clears the override columns; the record action's Applies stays "customized". Update the postcard README reset paragraph in this commit.
- Copy en/pl: `mail.template.customized_locales`, `mail.info_locale_default`, `mail.info_locale_fallback` with this plan's texts.
- Tests (smoke): `TestMailScreensSmoke/locales_list` covering the behavior list; update `templates` (no locale column; one welcome row) and `drift` (no locale filter); in mail_unit_test.go drop or rewrite any test of the removed locale filter options (TestMailLocale of TemplateLocale itself stays).
- Docs in the same commit: cabana README (Mail templates paragraph: one row per template, customized locales column, the switcher, the status filter only; the TestMailScreensSmoke description), docs/services/mail.md ("Editing mail in the admin": replace the "one row per file" sentence).
- Then rebuild the embedded admin (`npm --prefix admin ci` when node_modules is missing, `npm --prefix admin run build`), commit `modules/boardwalk/dist` alone with the build subject, and run `scripts/check-admin-dist.sh`.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/cabana -run 'TestMailScreensSmoke|TestMailLocale|TestMailDrift|TestMailReset|TestMailSave' -count=1 -v 2>&1 | grep -E '^\s*(--- FAIL|--- SKIP|FAIL|ok|PASS)|locales_list' | tail -20</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, or no "--- PASS: TestMailScreensSmoke/locales_list" line</fails_when>
<automated>go vet ./... && go test -short ./... && go test ./modules/postcard ./modules/cabana -count=1 2>&1 | tail -4</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>bash scripts/check-admin-dist.sh && go run ./cmd/summer docs:build --check 2>&1 | tail -3</automated>
<fails_when>non-zero exit or an "unknown identifier" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "customized_locales" modules/cabana/backendscreens/models/mailtemplate/columns.yaml` prints one line
- `grep -c "scope:" modules/cabana/backendscreens/controllers/mailtemplates/config_filter.yaml` prints 1
- `grep -n "info_locale_fallback\|info_locale_default" modules/cabana/backendscreens/controllers/mailtemplates/_info.htm` prints at least one line
- `grep -n "customized_locales\|info_locale_fallback" modules/phrasebook/backend/lang/pl/lang.yaml` prints at least two lines
- `git log -1 --format=%s -- modules/boardwalk/dist` prints `build(admin): rebuild the embedded admin for the mail locale switcher`
</acceptance_criteria>
<done>The templates list has one row per template whatever the number of locales, each locale has its own customized / reset / drift status inside the one record, and the embedded admin carries the switcher.</done>
</task>
<task type="auto">
<name>Task 3: Decision note superseding D-05 and the UI-SPEC locale switcher contract</name>
<files>.planning/notes/2026-11-13-mail-template-locale-groups.md, .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md</files>
<read_first>
- .planning/notes/2026-11-06-admin-code-editor-codemirror.md (note format: Date, Status, Context, Decision, Rejected alternatives)
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md sections "Lists", "C3b. Template form", "C9" and the UI Considerations rows on the locale filter
- Task 1 and Task 2 commits (`git show --stat HEAD~2..HEAD`) and the SUMMARY notes of what shipped
</read_first>
<action>
Planning docs only, one commit, separate from code (CLAUDE.md):
- `.planning/notes/2026-11-13-mail-template-locale-groups.md` (Status: Accepted; Context: 35-UAT G-35-1, user decision 2026-11-13): states that D-05 ("locale variants stay separate templates") is superseded; records as shipped the group key (base_code), the mail-locales source (translator plus TranslationWriter, default locale), the variant set and order, fallback-locale rows and what they show, per-locale customize / reset / drift, the send-resolution rule with its tag pattern and the unchanged behaviour for names with files (core plugins unaffected), the removed locale filter, `RecordMeta.LocaleVariants`; rejected alternatives: multilingual fields (mltext/mlmarkdown) in one record (no per-locale layout, reset or drift), a form-level `?locale=` query parameter (FormView changes for every controller), rows for every locale created only on first save (a locale not yet customized could not be opened). Follow-up (out of this phase): plugins that want per-locale admin versions pass `<template>-<locale>` for every locale (sm-user-plugin's MailTemplate maps only en today); postcard resolves a missing file to the default-locale version.
- 35-UI-SPEC.md: add a section "C16. Template locale switcher (gap closure G-35-1, supersedes the D-05 parts of C3b)" with the switcher markup (labelled native select from MLField, `data-locale-variant`, option text "Label — states"), placement (header under the title, two or more variants), navigation and the unsaved-changes confirm, the variant order, the list changes (one row per template, Customized locales column, no locale filter, grouped badges), the info lines and the four new copy keys with en/pl text; mark the superseded rows in "Lists", C3b and the UI Considerations table with "superseded by C16" rather than deleting them.
Commit as listed in Execution units.
</action>
<verify>
<automated>test -f .planning/notes/2026-11-13-mail-template-locale-groups.md && grep -c "D-05" .planning/notes/2026-11-13-mail-template-locale-groups.md && grep -n "C16" .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md | head -3</automated>
<fails_when>non-zero exit, a count of 0, or no C16 line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "superseded" .planning/notes/2026-11-13-mail-template-locale-groups.md` prints at least one line
- `grep -c "superseded by C16" .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md` prints a number above 0
- `git log -1 --format=%s -- .planning/notes/2026-11-13-mail-template-locale-groups.md` prints the Task 3 subject and that commit touches no file outside .planning/
</acceptance_criteria>
<done>The superseded decision and the shipped switcher contract are on record for verification and later phases.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| admin browser → cabana mail template routes | administrators holding system.manage_mail_templates read and save template rows, now including fallback-locale rows |
| plugin code → postcard Send | plugins pass template names; a name without a file now resolves to its base |
| cabana show hook → database | a GET may insert missing fallback-locale index rows |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-35-29 | Elevation of privilege | locale variant ids in meta.localeVariants | medium | mitigate | the switcher only lists rows of the same group; every id is still loaded through the controller's RequiredPermissions and FormExtendQuery scope (catalog templates and their fallback rows), so an id outside the catalog is a 404 (TestMailScreensSmoke/locales) |
| T-35-30 | Tampering | fallback-locale saves | high | mitigate | FormAfterUpdate validates through postcard Editor.Validate exactly as file rows (D-13); a refused draft rolls the save back |
| T-35-31 | Spoofing | send-time name resolution | low | mitigate | only a locale tag after a dash (a two-letter language, optionally followed by `-` or `_` and a 2–8 character alphanumeric subtag, such as de or pt-BR), on a registered base of the same name, resolves; the base is in the same plugin namespace, so no plugin can reach another plugin's template through a suffix; other unknown names keep the unknown-template error |
| T-35-32 | Denial of service | EnsureLocaleRows on show and sync | low | mitigate | the show hook ensures only its own group; the full ensure runs at sync under the shared advisory lock; inserts are idempotent and bounded by templates × locales |
| T-35-33 | Information disclosure | localeVariants labels | low | accept | labels are locale codes and state words the administrator already sees in the list |
| T-35-SC | Tampering | npm/pip/cargo installs | high | accept | this plan installs no package (npm ci only restores the committed lockfile) |
</threat_model>
<verification>
- `go vet ./... && go test -short ./...` and `go test ./modules/postcard ./modules/cabana` green after every code commit.
- `scripts/check-admin-openapi.sh --check` and `scripts/check-admin-dist.sh` pass after Task 2.
- `npm --prefix admin run test` and `npm --prefix admin run typecheck` pass.
- `go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree'` and `go run ./cmd/summer docs:build --check` pass.
- `bash scripts/check-phase35.sh --consumers --additive` passes (core plugins send unchanged; postcard and cabana changes additive).
</verification>
<success_criteria>
- One list row per template; customized locales and grouped badges shown; locale filter gone.
- Locale switcher in the template form; per-locale customize, reset and drift; fallback locales show and send the default version until customized.
- Send of `<template>-<locale>` resolves file → customization → default customization → default file; file-backed names unchanged.
- D-05 superseded on record; UI-SPEC C16 added; READMEs and docs updated in the code commits; nothing pushed or tagged.
</success_criteria>
<output>
Create `.planning/phases/35-mail-templates-and-layouts-editor/35-05-SUMMARY.md` when done; list the exact exported names (TemplateBase, Catalog.TemplateFor, EnsureLocaleRows, RecordMeta.LocaleVariants, RecordLocaleVariant), the migration ID, the copy keys and the test names, because 35-06 and 35-07 build on them.
</output>
## Follow-ups outside this phase (not planned here)
- sm-user-plugin: `classes.MailTemplate` could pass `<base>-<locale>` for every resolved locale (not only en) so per-locale admin versions apply to its mail; postcard already resolves a locale without a file to the default version. This belongs to the plugin follow-up after the framework tag, together with the button partial and layout work of G-35-8.
- sm-demo-app: before re-running UAT test 1, reset the UAT overrides of `golem15.user::mail.activate` and `golem15.user::mail.layouts.user` (35-UAT G-35-8 "Demo" item).
</content>
</invoke>

View File

@@ -0,0 +1,246 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 05
subsystem: mail
tags: [postcard, cabana, admin-spa, mail-templates, locales, gormigrate, vue]
requires:
- phase: 35-mail-templates-and-layouts-editor
provides: "35-01 postcard index rows/editor, 35-02 cabana mail screens, 35-03 admin SPA mail UI, 35-04 check-phase35.sh"
provides:
- "postcard: migration 202611130001_mail_template_base_code (base_code column + system_mail_templates_base_code_index)"
- "postcard.TemplateBase, postcard.Catalog.TemplateFor, postcard.EnsureLocaleRows"
- "postcard send resolution of <template>-<locale> without a file: own customization, else base customization, else base file"
- "postcard.ResetOverride accepts a fallback-locale template code"
- "cabana.RecordMeta.LocaleVariants + cabana.RecordLocaleVariant (show and update responses of the mail templates screen)"
- "cabana.MailTemplate.BaseCode and CustomizedLocales (unstored list column)"
- "Mail templates list: one row per template, Customized locales column, grouped badges and status filter, no locale filter"
- "admin LocaleVariantSwitcher (data-locale-variant) in the FormView header"
- "decision note .planning/notes/2026-11-13-mail-template-locale-groups.md superseding D-05; 35-UI-SPEC C16"
affects: [35-06, 35-07, sm-user-plugin follow-up, sm-demo-app UAT re-run]
actuals:
tokens: 36600
tasks: 3
commits: 4
plan_head_before: 9afe95ccef37455e7b9c9923a91ad469a5e2212c
plan_head_after: 1173a5c5a230f174afdb2be9d5f0bafa50188ad4
tech-stack:
added: []
patterns:
- "Controller-decided record meta through unexported cabana interfaces (recordLocaleVariants, recordShowAdjuster), next to recordDeletable"
- "Send-time locale fallback in postcard with no locale list: <base>-<tag> resolves to the registered base"
key-files:
created:
- admin/src/components/form/LocaleVariantSwitcher.vue
- admin/tests/form/LocaleVariantSwitcher.test.ts
- .planning/notes/2026-11-13-mail-template-locale-groups.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-05-task2-red-evidence.json
modified:
- modules/postcard/store.go
- modules/postcard/templates.go
- modules/postcard/mailer.go
- modules/postcard/editor.go
- modules/postcard/override_smoke_test.go
- modules/postcard/README.md
- modules/cabana/mail_admin.go
- modules/cabana/mail_routes.go
- modules/cabana/crud.go
- modules/cabana/relation_field.go
- modules/cabana/mail_screens_smoke_test.go
- modules/cabana/mail_lifecycle_postgres_test.go
- modules/cabana/mail_unit_test.go
- modules/cabana/README.md
- modules/cabana/backendscreens/models/mailtemplate/columns.yaml
- modules/cabana/backendscreens/controllers/mailtemplates/config_filter.yaml
- modules/cabana/backendscreens/controllers/mailtemplates/_info.htm
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- admin/openapi/admin.json
- admin/src/api/schema.d.ts
- admin/src/views/FormView.vue
- admin/tests/form/FormViewMail.test.ts
- modules/boardwalk/dist
- docs/services/mail.md
- docs/backend/forms.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md
key-decisions:
- "D-05 superseded (G-35-1): a mail template is one admin record; locale versions are rows grouped by base_code and opened through a locale switcher"
- "Mail locales = translator Locales(\"\") plus TranslationWriter.EnabledLocales when published; default = writer DefaultLocale, else translator Locale(); a changed locale set re-syncs the index"
- "postcard resolves <template>-<tag> (two-letter language, optional -/_ 2-8 char subtag, longest registered base) to the base file with own customization > base customization > file; names with files unchanged"
- "EnsureLocaleRows only creates a row for a code the send rule resolves to that base, so admin rows and sends cannot disagree"
- "meta.localeVariants is also sent on the update response so the switcher's state words are fresh after a save"
- "Locale filter removed; status filter and badges aggregate over the template's versions"
patterns-established:
- "recordShowAdjuster: a controller may change the loaded record before projection on show only (no write)"
requirements-completed: [G-35-1, D-05, D-06, D-07, D-13, D-16]
coverage:
- id: D1
description: "Send of <template>-<locale> uses that locale's customization, else the default-locale customization, else the default file; file-backed names unchanged; unknown names keep the error"
requirement: G-35-1
verification:
- kind: integration
ref: "modules/postcard/override_smoke_test.go#TestMailOverrideSmoke/locale_fallback"
status: pass
- kind: integration
ref: "bash scripts/check-phase35.sh --consumers --additive"
status: pass
human_judgment: false
- id: D2
description: "Template form locale switcher from meta.localeVariants; saving a locale without a file creates its own version that the next send uses; preview of that version works; out-of-catalog ids are 404"
requirement: G-35-1
verification:
- kind: integration
ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/locales"
status: pass
- kind: unit
ref: "admin/tests/form/LocaleVariantSwitcher.test.ts"
status: pass
- kind: unit
ref: "admin/tests/form/FormViewMail.test.ts#shows the locale switcher from meta.localeVariants when there are two or more"
status: pass
human_judgment: false
- id: D3
description: "Templates list has one row per template with Customized locales, grouped badges and status filter; no locale filter; per-locale show, info, file version, drift and reset"
requirement: D-07
verification:
- kind: integration
ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/locales_list"
status: pass
- kind: integration
ref: "modules/cabana/mail_lifecycle_postgres_test.go#TestMailDrift"
status: pass
- kind: unit
ref: "modules/cabana/mail_unit_test.go#TestMailTemplateFilterScopes"
status: pass
human_judgment: false
- id: D4
description: "The switcher and the grouped list read well in the real admin (placement under the title, option text, a site with many locales)"
verification: []
human_judgment: true
rationale: "Visual placement and readability of the switcher and the Customized locales column in the embedded admin are judged in UAT (re-run of 35-UAT test 1 on sm-demo-app)"
duration: 28min
completed: 2026-11-13
status: complete
---
# Phase 35 Plan 05: Mail template locale groups (G-35-1) Summary
**Mail templates are one admin record each: postcard groups rows by `base_code`, creates rows for locales without a file and resolves `<template>-<locale>` at send time to the default-locale version, cabana lists one row per template with customized locales and serves `meta.localeVariants`, and the admin form switches versions through a Language select.**
## Performance
- **Duration:** 28 min
- **Started:** 2026-11-13T19:14:28Z
- **Completed:** 2026-11-13T19:42:30Z
- **Tasks:** 3
- **Files modified:** 29 (plus the rebuilt `modules/boardwalk/dist`)
## Accomplishments
- postcard: migration `202611130001_mail_template_base_code`; `postcard.TemplateBase`, `postcard.Catalog.TemplateFor`, `postcard.EnsureLocaleRows`; one unexported resolver (`resolveTemplate`) for send, preview and validation; the mailer asks the override source for the locale name first and then the base; `postcard.ResetOverride` accepts a fallback-locale code.
- cabana: mail locales from the translator plus a published `TranslationWriter` (re-sync when the set changes); record lookups admit fallback rows; base-code record title; `RecordMeta.LocaleVariants` / `RecordLocaleVariant`; one list row per template with `customized_locales`, grouped row states and status filter; the locale filter is gone; a not-customized locale without a file shows the base row's current version; info lines `mail.info_locale_default` / `mail.info_locale_fallback`.
- admin: `LocaleVariantSwitcher.vue` (native select, `data-locale-variant`, unsaved-changes confirm, selection restored on refusal); embedded admin rebuilt.
- Decision note superseding D-05 and UI-SPEC section C16 (superseded rows marked).
## Task Commits
1. **Task 1: tracer, one admin record per template with a locale switcher** - `52c9c7eb` (feat)
2. **Task 2: grouped list, per-locale status, dist rebuild** - `67f71643` (feat), `e114492b` (build)
3. **Task 3: decision note and UI-SPEC C16** - `1173a5c5` (docs)
## Exported names, IDs and copy keys (for 35-06 / 35-07)
- postcard: `TemplateBase(name, locales)`, `(*Catalog).TemplateFor(name) (TemplateFile, bool)`, `EnsureLocaleRows(ctx, db, cat, defaultLocale, locales, bases...)`; migration ID `202611130001_mail_template_base_code`; index `system_mail_templates_base_code_index`.
- cabana: `RecordMeta.LocaleVariants []RecordLocaleVariant` (json `localeVariants,omitempty`), `RecordLocaleVariant{ID, Locale, Label, States, Current}`; `MailTemplate.BaseCode`, `MailTemplate.CustomizedLocales` (`gorm:"-:all;column:customized_locales"`).
- Copy (en/pl): `form.locale_variant` (Language / Język), `mail.template.customized_locales` (Customized locales / Dostosowane języki), `mail.info_locale_default`, `mail.info_locale_fallback` (`:locale`).
- Tests: `TestMailOverrideSmoke/locale_fallback`, `TestMailOverrideSmoke/migrations_roll_back` (rolls back every migration), `TestMailScreensSmoke/locales`, `TestMailScreensSmoke/locales_list`, `TestMailDrift` (grouped row), `TestMailTemplateFilterScopes`, `admin/tests/form/LocaleVariantSwitcher.test.ts`, FormViewMail switcher case.
## Decisions Made
- `EnsureLocaleRows` skips a locale whose `<base>-<locale>` code the send rule would not resolve to that base (for example a three-letter language code), so a row in the admin always matches what a send uses.
- `meta.localeVariants` is filled on the update response as well as the show response, so the switcher's state words (Customized) are current after a save without a reload.
- The variant states array is always present (`[]` when none), which keeps the SPA free of null checks.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 1 - Bug] copy key placed under the wrong YAML section**
- **Found during:** Task 1 verification (`go test -short ./...`, TestPhase10SPAKeysResolve)
- **Issue:** `form.locale_variant` was first inserted under `messages.form`, so `backend::lang.form.locale_variant` did not resolve.
- **Fix:** moved it to the top-level `form:` section in en and pl.
- **Files modified:** modules/phrasebook/backend/lang/{en,pl}/lang.yaml
- **Committed in:** 52c9c7eb
**2. [Rule 2 - Missing functionality] switcher states after a save**
- **Found during:** Task 1 (FormView wiring)
- **Issue:** the plan fills `meta.localeVariants` on show only; the save response replaces the record meta, so the switcher would keep pre-save states (a saved locale would not show Customized).
- **Fix:** `CRUDService.save` fills `LocaleVariants` on update for controllers implementing `recordLocaleVariants`; FormView keeps the previous list when a response carries none. Documented in `RecordMeta.LocaleVariants`, the cabana README and docs/backend/forms.md.
- **Files modified:** modules/cabana/crud.go, modules/cabana/relation_field.go, admin/src/views/FormView.vue
- **Committed in:** 52c9c7eb
**3. [Rule 3 - Blocking] TestMailDrift asserted the per-row list**
- **Found during:** Task 2 GREEN run
- **Issue:** `mail_lifecycle_postgres_test.go` (not in the plan's file list) expected the drifted `welcome-en` row in the outdated filter and its own row states.
- **Fix:** it now checks the welcome row (Customized locales `en`, states on the base row id).
- **Files modified:** modules/cabana/mail_lifecycle_postgres_test.go
- **Committed in:** 67f71643
**4. [Rule 2 - Missing test] FormView wiring test and filter-scope unit test**
- **Found during:** Tasks 1 and 2
- **Fix:** added a FormViewMail case (switcher rendered from `meta.localeVariants` with two variants, absent otherwise) and `TestMailTemplateFilterScopes`.
- **Committed in:** 52c9c7eb, 67f71643
**5. [gofmt] mail_admin.go reformatted**
- `gofmt -w` also realigned the pre-existing `MailBrandSetting` struct tags (whitespace only). Committed in 67f71643.
---
**Total deviations:** 5 (1 bug, 2 missing functionality/tests, 1 blocking, 1 formatting)
**Impact on plan:** no scope change; all API changes stay additive (check-phase35.sh additive passed).
## TDD Gate Compliance
Task 2 (`tdd="true"`): the RED tests (`TestMailScreensSmoke/locales_list`, the updated `templates` and `drift` subtests, `TestMailTemplateFilterScopes`) were written first and failed on their target assertions (`templates list filters = filterLocalelocale,filterStatusstatus`, `MailTemplate filter scopes = filterLocale,filterStatus`). Two gaps against the MSD TDD gate:
- **No separate `test(35-05)` RED commit.** The project rule "keep `go vet` and `go test ./...` green at every commit" (CLAUDE.md) takes precedence, so the tests landed with the implementation in `67f71643`.
- **The RED evidence checker returned INVALID_RED (`zero_tests_discovered`).** `msd-tools check tdd-red-evidence` parses only TAP and Surefire XML, and the record in `35-05-task2-red-evidence.json` holds the raw `go test -v` output of the real failing run. The record was kept as captured, not reformatted. The failure itself is genuine and reproducible by reverting `67f71643`'s non-test files.
## Issues Encountered
- Prettier reports style differences in `FormView.vue` and `FormViewMail.test.ts`; they were present before this plan and the admin has no prettier config or lint gate, so nothing was changed.
- `modules/postcard/store_postgres_test.go`, `modules/cabana/mail_routes.go` have pre-existing gofmt differences unrelated to this plan; left untouched.
## Known Stubs
None.
## Threat Flags
None beyond the plan's threat model (T-35-29..33: fallback ids go through the same permission and FormExtendQuery scope, an orphan row id is a 404 in `TestMailScreensSmoke/locales`; fallback saves are validated by `postcard.Editor.Validate`; the send rule only resolves a locale tag on a registered base in the same plugin namespace; the show hook ensures only its own group under a savepoint).
## User Setup Required
None - no external service configuration required.
## Next Phase Readiness
- 35-06 / 35-07 can build on the exported names above.
- Before re-running UAT test 1 on sm-demo-app: rebuild the app on this framework commit; the index re-syncs on start and creates the locale rows. sm-user-plugin passes only `-en` today, so per-locale admin versions apply to its mail once the plugin passes `<template>-<locale>` for every locale (plugin follow-up, outside this phase).
- Nothing was pushed or tagged; no sibling repository was changed.
---
*Phase: 35-mail-templates-and-layouts-editor*
*Completed: 2026-11-13*
## Self-Check: PASSED
All created files exist; commits 52c9c7eb, 67f71643, e114492b and 1173a5c5 are in the history; Task 1-3 acceptance criteria re-run green; plan verification: go vet, go test -short ./..., go test ./modules/postcard ./modules/cabana, check-admin-openapi.sh --check, check-admin-dist.sh, admin test (114 files) and typecheck, docs:build --check, check-phase35.sh --consumers --additive all pass.

View File

@@ -0,0 +1,9 @@
{
"command": "go test ./modules/cabana -run 'TestMailScreensSmoke/locales_list' -count=1 -v",
"exitCode": 1,
"output": " mail_screens_smoke_test.go:432: templates list filters = filterLocalelocale,filterStatusstatus\n--- FAIL: TestMailScreensSmoke (4.52s)\n --- FAIL: TestMailScreensSmoke/locales_list (0.05s)\nFAIL\nFAIL\tgit.golem15.com/golem15/summercms/modules/cabana\t4.605s\nFAIL\n",
"targetTest": "TestMailScreensSmoke/locales_list",
"targetFile": "modules/cabana/mail_screens_smoke_test.go",
"expected": "the templates list schema has no locale filter (only the status filter), one list row per template with customized_locales and grouped row states",
"actual": "templates list filters = filterLocalelocale,filterStatusstatus (the locale filter scope is still declared)"
}

View File

@@ -0,0 +1,365 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 06
type: execute
wave: 6
depends_on: ["35-05"]
gap_closure: true
gap_ids: [G-35-8]
files_modified:
- modules/postcard/assets/default.htm
- modules/postcard/assets/system.htm
- modules/postcard/assets/minimal.htm
- modules/postcard/assets/brand.css.tmpl
- modules/postcard/assets/partials/header.htm
- modules/postcard/assets/partials/footer.htm
- modules/postcard/templates.go
- modules/postcard/partials.go
- modules/postcard/mailer.go
- modules/postcard/brand.go
- modules/postcard/store.go
- modules/postcard/editor.go
- modules/postcard/inline.go
- modules/postcard/brand_smoke_test.go
- modules/postcard/partials_smoke_test.go
- modules/postcard/override_smoke_test.go
- modules/postcard/override_test.go
- modules/postcard/mailer_test.go
- modules/postcard/README.md
- go.mod
- go.sum
- examples/hello/go.mod
- examples/hello/go.sum
- modules/cabana/mail_admin.go
- modules/cabana/mail_routes.go
- modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml
- modules/cabana/backendscreens/models/maillayout/fields.yaml
- modules/cabana/mail_screens_smoke_test.go
- modules/cabana/README.md
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- docs/services/mail.md
- .planning/research/STACK.md
- .planning/notes/2026-11-13-mail-layouts-css-inlining.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md
autonomous: true
requirements: [G-35-8, D-10, D-11, D-12, D-14]
estimate:
tokens: 130000
raw_tokens: 130000
tasks: 3
confidence: low
must_haves:
truths:
- "A template previewed or sent in the default layout shows a white card on the body background, a header with the Branding logo (or the site name when no logo is set) and a footer with the copyright year and site name, as WinterCMS's default layout does (G-35-8)"
- "The system layout has the same header (logo or name) and footer and its content cell has side padding; the minimal layout shows the logo above the message when one is set (G-35-8)"
- "Mail branding has a Site name field; when it is empty the display name of mail.from is used; the header, footer and the logo's alt text use it (supersedes part of D-10)"
- "Sent and previewed HTML carries the brand and layout CSS inline on each element (the button partial's link has the brand button colour in its style attribute), so mail clients that drop the style block still show the design; rules that cannot be inlined (media queries) stay in a style block (supersedes D-10's inlining claim)"
- "A layout opts out of inlining with the file header key disable_auto_inline_css or the layout form's switch, and then keeps only its style block (WinterCMS parity)"
- "A failing inliner never stops mail: the message is sent with the style block only and a rate-limited warning is logged (D-14 spirit)"
- "Mail that works today keeps working: sm-user-plugin and sm-paymentgateway-plugin mail tests pass against this checkout without any change to those repositories"
prohibitions:
- statement: "No file in sm-user-plugin, sm-paymentgateway-plugin or any other sibling repository is changed; plugin layouts, templates and go.mod bumps are the follow-up after the framework tag."
status: unresolved
verification: judgment
- statement: "The new Go dependency is github.com/vanng822/go-premailer pinned exactly at v1.38.0, recorded in a decision note and a STACK.md row committed before go.mod changes; no other new direct dependency."
status: unresolved
verification: automated
- statement: "Every postcard and cabana API change is additive (check-phase35.sh additive stage); pact is untouched."
status: unresolved
verification: automated
- statement: "Nothing is pushed or tagged."
status: unresolved
verification: judgment
artifacts:
- path: "modules/postcard/assets/default.htm"
provides: "WinterCMS default layout port with header, card and footer"
contains: "layout-default"
- path: "modules/postcard/assets/partials/header.htm"
provides: "built-in header partial (logo or name)"
contains: "logo"
- path: "modules/postcard/inline.go"
provides: "CSS inlining at render"
contains: "premailer"
- path: ".planning/notes/2026-11-13-mail-layouts-css-inlining.md"
provides: "decision note: go-premailer, supersedes D-10 inlining claim and the 35-01 default.htm gate"
contains: "go-premailer"
key_links:
- from: "modules/postcard/templates.go"
to: "modules/postcard/inline.go"
via: "renderParts inlines the HTML wrapper output unless the layout opts out"
pattern: "inlineCSS"
- from: "modules/postcard/mailer.go"
to: "modules/postcard/assets/default.htm"
via: "siteName and year layout keys feed the header and footer partial calls"
pattern: "siteName"
- from: "modules/postcard/store.go"
to: "modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml"
via: "the site_name column of the branding row is the Branding form's Site name field"
pattern: "site_name"
---
## Phase Goal
ROADMAP Goal (not in user-story format; no story is invented): administrators edit every mail the application sends from the admin panel, and the mail looks finished out of the box. This gap-closure plan fixes the framework part of UAT gap G-35-8: no shipped layout printed the logo, the default layout was a bare block, the system layout had no header, footer or side padding, and CSS was never inlined although D-10 and the UI-SPEC said it was.
Source: 35-UAT.md (G-35-8, test 8, severity major), .planning/debug/mail-layouts-unstyled.md (root cause), user decision of 2026-11-13 (framework only; plugin layouts and templates follow after the framework tag).
<objective>
- Port WinterCMS's default layout (wrapper, header with logo or name, white card, footer) to postcard's `default.htm` and its text wrapper, with built-in `header` and `footer` partials.
- Give the header and footer a display name: a new Site name in Mail branding, falling back to the display name of `mail.from`.
- Finish `system.htm` (header, logo, footer, side padding) and `minimal.htm` (logo), and the brand CSS rules they need.
- Inline CSS onto elements at render through github.com/vanng822/go-premailer, with a per-layout opt-out (file header key and layout form switch), recorded in a decision note and STACK.md.
- Update the postcard and cabana READMEs, docs/services/mail.md and the UI-SPEC texts; the decision note supersedes D-10's inlining claim and lifts 35-01's "default.htm unchanged" gate.
Purpose: an application that never touches the mail screens sends good-looking mail, and Branding (colours, logo, name) shows in every built-in layout, in the preview and in real mail clients.
Output: commits in this repository only (code, planning docs separately). Nothing in sibling repositories, nothing pushed or tagged.
**Planner decisions recorded here (Claude's discretion within the user's 2026-11-13 decision):**
- **Layout keys.** Both wrappers of every layout get two new keys next to `Content`, `Subject`, `css`, `brandCss` and `logoUrl`: `siteName` (Branding Site name, else the display name of `mail.from` parsed with net/mail, else empty) and `year` (the current year at render).
- **Header partial** `postcard::mail.partials.header` (callable as `header`): arguments `logo` (URL), `body` (name), optional `url` (link around logo or name). HTML: a table row with `td.header` holding `img.logo` (alt = body) when logo is set, else a `span` with the name; text section: the name. **Footer partial** `footer`: argument `body` rendered as Markdown inside Winter's `table.footer` row; text section: a rule line and the body.
- **Footer text is language-neutral**: `© <year> <siteName>` (just `© <year>` when there is no name). Winter's English "All rights reserved." is left out because a built-in layout serves every locale; an administrator can override the layout.
- **Header shows logo or name, not the subject** (Winter shows the subject; the user asked for logo or name). The header row is omitted when there is neither.
- **Inlining** runs inside postcard's render path, so preview, test send and real sends match: after the HTML wrapper renders and passes the safety checks, unless the layout opts out, the HTML is passed through go-premailer with its default options (CSS also mirrored to attributes such as bgcolor/width; classes kept so plugin CSS hooks still match), and the final HTML is checked again. An inliner error keeps the un-inlined HTML and logs a rate-limited warning. The text part is never touched.
- **Opt-out** keeps WinterCMS's option name: file layout header key `disable_auto_inline_css` (true, 1 or yes, any case) and a boolean column of the same name on the layouts table, edited by a switch on the layout form's CSS tab. Built-in layouts all inline.
- **New copy** (en/pl): `mail.brand.site_name` ("Site name" / "Nazwa witryny"), `mail.brand.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." / "Wyświetlana w nagłówku i stopce wbudowanych układów. Zostaw puste, aby użyć nazwy nadawcy z mail.from."), `mail.layout.disable_inline_css` ("Do not inline CSS" / "Nie wstawiaj CSS do elementów"), `mail.layout.disable_inline_css_comment` ("By default the CSS is also copied into each element's style attribute, so mail clients that drop the style block still show it. Turn this on to keep the style block only." / "Domyślnie CSS jest też kopiowany do atrybutu style każdego elementu, aby klienty poczty usuwające blok stylów nadal go pokazywały. Włącz, aby zostawić tylko blok stylów."); changed: `mail.brand.logo_comment` ("The built-in layouts show the logo in their header. Your own layouts show it where they use {{ .logoUrl }}." / "Wbudowane układy pokazują logo w nagłówku. Własne układy pokazują je tam, gdzie używają {{ .logoUrl }}.").
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md
@.planning/debug/mail-layouts-unstyled.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-CONTEXT.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-01-SUMMARY.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-05-SUMMARY.md
@CLAUDE.md
<interfaces>
- modules/postcard/assets/: default.htm (bare `content-body` block today), system.htm (Winter wrapper/content/body/inner-body/content-cell tables and the subcopy partial, no header/footer), minimal.htm (bare body), brand.css.tmpl (Winter rules incl. `.header`, `.footer`, `.button-*`; `.wrapper.layout-system .content-cell { padding: 35px 0; }` removes the side padding), partials/{button,panel,subcopy,table}.htm (header `name`, `==` text `==` HTML).
- WinterCMS reference: ../examples/golem15-wintercms-starter/modules/system/views/mail/layout-default.php, layout-system.php, partial-header.php, partial-footer.php; modules/system/classes/MailManager.php renderTemplate (~173-199: CssToInlineStyles unless the layout option disable_auto_inline_css).
- modules/postcard/templates.go: `builtinPartials` (~41), `NewCatalog` (~105) loads built-in layouts and partials, `parseLayout` (~345, header keys via parseINI), `renderOptions` (~465: css, brandCSS, logoURL, overrides, warn), `renderParts` (~571: HTML wrapper exec ~625, validateHTML ~635), `renderLayout` (~652), `layoutByCode` (~687), `LayoutFile` (~777), `FormatLayout` (~904).
- modules/postcard/mailer.go: `Options.From`, `(*mailer).options(brand)` (~139) builds renderOptions from config and Branding; `warn` (~183) is rate-limited.
- modules/postcard/brand.go: `Brand` (colours + LogoURL), `DefaultBrand`, `CompileBrandCSS` (only colours reach the CSS).
- modules/postcard/store.go: `Migrations` (35-05 added `202611130001_mail_template_base_code`), `LayoutOverride{Name, HTML, Text, CSS}` (~177), `dbSource.MailOverrides` layouts query (~248), `dbSource.brand` (~281), `SyncIndex` layouts upsert (~369), `ResetOverride` layouts (~471).
- modules/postcard/editor.go: `Draft` (~30), `renderLayout` (~240), `renderBrand` (~313) sets brandCSS and logoURL from the draft.
- Tests asserting today's default layout markup (`content-body`): brand_smoke_test.go (~194), override_smoke_test.go (~322, ~334), override_test.go (~189), mailer_test.go (~91); partials_smoke_test.go (~351) asserts the minimal layout's exact body.
- modules/cabana/mail_admin.go: `MailBrandSetting` (~1475, Fillable, Rules, BeforeValidate), `MailLayout` (~333, Fillable ~773); modules/cabana/mail_routes.go `mailLayoutDraft` (~535), `mailBrandDraft` (~574).
- modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml (logo first, then colours, then `_preview`), models/maillayout/fields.yaml (CSS tab: `content_css`, `_preview_css`).
- Sibling consumers use `replace git.golem15.com/golem15/summercms => ../summercms.go`; their go.sum lacks any new module, so checks against this checkout must use a scratch `-modfile` copy (never write their go.mod/go.sum).
- go-premailer (checked at planning, 2026-11-13): module github.com/vanng822/go-premailer, package `premailer`, v1.38.0 published 2026-11-04 (v1.37.0 2026-10-02; roughly monthly releases), MIT, imported by 246 packages; API `NewPremailerFromString(doc string, options *Options) (Premailer, error)`, `Premailer.Transform() (string, error)`, `NewOptions(...)` with `RemoveClasses` (false), `CssToAttributes` (true), `KeepBangImportant`; it collects the document's style elements, applies rules by specificity and puts rules it cannot inline back in a style element. Its go.mod requires PuerkitoBio/goquery v1.13.0, inbucket/html2text v1.0.0, vanng822/css v1.0.1 and golang.org/x/net v0.62.0 (this repository is at v0.58.0, so MVS raises x/net).
</interfaces>
</context>
## Execution units and resume points
- Other sessions edit postcard, cabana and docs concurrently. Before each task run `git status --short modules/postcard modules/cabana modules/phrasebook docs go.mod go.sum .planning/research` and stop if another session holds uncommitted edits in files this task touches. `examples/hello/plugins.gen.go` carries another session's edit: never stage it.
- Stage by explicit path; code and planning docs in separate commits; `go vet ./...` and `go test ./...` green at every code commit. Docker-backed tests without `-short` (through `sudo -u golem` if the socket is denied).
- Resume check: `git log --format=%s -F --grep='<subject>'`.
- The tracer task (Task 1) is large under the lean-planning rule. It may land as several sub-commits (for example postcard, then cabana) as long as each one keeps `go vet ./...` and `go test ./...` green and carries its own README/docs changes. The last sub-commit uses the subject listed below.
| Task | Commit subject | Resume point |
|------|----------------|--------------|
| 1 | `feat(postcard): finished default layout with logo header, footer and site name` | TestMailBrandSmoke/default_layout passes |
| 2 | `docs(35): decision note for mail CSS inlining with go-premailer` then `feat(postcard): inline mail CSS at render with a per-layout opt-out` | TestMailPartialsSmoke/inline passes; consumers pass with a scratch modfile |
| 3 | `feat(postcard): header, logo, footer and padding in the system and minimal layouts` then `docs(35): UI-SPEC copy for inlining, site name and the layout opt-out` | TestMailPartialsSmoke/built_in_layouts passes; UI-SPEC updated |
<tasks>
<task type="tracer">
<name>Task 1: End-to-end "Branding with a logo and a site name is saved, and a template previewed and sent in the default layout shows the logo header, the white card, a styled button and the footer" — default layout only</name>
<reversibility rating="costly">The site_name column is a migration on postcard's branding table; the header and footer partial names and the siteName/year layout keys become part of the published layout format plugins and administrators write against.</reversibility>
<precondition>35-05 is complete: `git log --format=%s -F --grep='docs(35): decision note superseding D-05'` prints one line</precondition>
<files>modules/postcard/assets/default.htm, modules/postcard/assets/partials/header.htm, modules/postcard/assets/partials/footer.htm, modules/postcard/assets/brand.css.tmpl, modules/postcard/templates.go, modules/postcard/partials.go, modules/postcard/mailer.go, modules/postcard/brand.go, modules/postcard/store.go, modules/postcard/editor.go, modules/postcard/brand_smoke_test.go, modules/postcard/override_smoke_test.go, modules/postcard/override_test.go, modules/postcard/mailer_test.go, modules/postcard/README.md, modules/cabana/mail_admin.go, modules/cabana/mail_routes.go, modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml, modules/cabana/mail_screens_smoke_test.go, modules/cabana/README.md, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, docs/services/mail.md</files>
<read_first>
- ../examples/golem15-wintercms-starter/modules/system/views/mail/layout-default.php, partial-header.php, partial-footer.php (structure to port)
- modules/postcard/assets/ (all files), modules/postcard/templates.go (~21-140 and ~465-700), modules/postcard/partials.go (how built-in partials are named and called), modules/postcard/mailer.go (~37-155), modules/postcard/brand.go, modules/postcard/store.go (~37-130 Migrations, ~279-338 brand), modules/postcard/editor.go (~305-330)
- modules/postcard/brand_smoke_test.go (~150-240 and the logo subtest), the assertions listed in interfaces
- modules/cabana/mail_admin.go (~1470-1560), modules/cabana/mail_routes.go (~570-620), modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml
- .planning/debug/mail-layouts-unstyled.md (Resolution)
</read_first>
<action>
Lifts the 35-01 "default.htm unchanged" gate per the user's 2026-11-13 decision; extends D-10's Branding with a site name; D-11 precedence and D-12 partials are reused unchanged.
- postcard, brand.go: `Brand.SiteName string` (doc: shown by the built-in layouts' header and footer; not part of the CSS); CompileBrandCSS ignores it.
- postcard, store.go: append migration `202611130002_mail_brand_site_name` adding `site_name TEXT NOT NULL DEFAULT ''` to the branding table (Rollback drops it); `dbSource.brand` reads it into Brand.SiteName.
- postcard, templates.go/mailer.go: renderOptions gains `siteName` and `year`; `(*mailer).options` sets siteName from the trimmed Brand.SiteName when non-empty, else from the display name of `Options.From` (net/mail.ParseAddress; empty on error or no name), and year from the current time; renderParts passes `siteName` and `year` to both wrappers. Editor.renderBrand uses the draft brand's SiteName with the same From fallback.
- postcard, partials: add `header` and `footer` to the built-in partials with the argument contract in this plan's decisions; files `assets/partials/header.htm` and `assets/partials/footer.htm` in the file format (`name = "Header"` / `"Footer"`, `==` text, `==` HTML), HTML ported from Winter's partial-header/partial-footer (img.logo inside `td.header`, optionally wrapped in a link when `url` is given; footer `table.footer` with a `td.content-cell` holding the Markdown body).
- postcard, assets/default.htm: port Winter's layout-default: viewport meta, the existing style block, `table.wrapper.layout-default`; the header partial call when logoUrl or siteName is set; the content/body/inner-body/content-cell card holding Content; the footer partial with the language-neutral copyright. Text wrapper: Content, a blank line, the footer partial's text form. Keep `name = "Default"`.
- postcard, brand.css.tmpl: an `img.logo` rule (border 0, display inline-block, max-width 200px, max-height 60px, height auto, so the aspect ratio is kept) and `.header` spacing that fits a logo.
- Update every test that asserted the old bare `content-body` block (interfaces list) to the new card markup, in this commit. New subtest `TestMailBrandSmoke/default_layout`: a template using the button partial, sent with a Brand carrying LogoURL and SiteName, gives HTML with the logo URL in an `img` whose alt is the site name inside `td.header`, `class="inner-body"`, `class="button button-primary"` and `© <current year> <SiteName>`; with no logo the header holds the name in a span; with no Branding row and From "Acme <no-reply@acme.test>" header and footer say Acme; with no name and no logo there is no header row and the footer says only the year.
- cabana: `MailBrandSetting.SiteName` (column site_name) in Fillable and Rules (`nullable|max:255`), trimmed in BeforeValidate; fields.yaml `site_name` (text, span left, label/comment keys) right after the logo; `mailBrandDraft` maps `site_name` so the Branding preview shows it. Extend `TestMailScreensSmoke/branding`: saving site_name persists it and POST /mail/preview mode branding with values carrying site_name returns HTML containing it.
- Copy en/pl: `mail.brand.site_name`, `mail.brand.site_name_comment`, the changed `mail.brand.logo_comment` (texts in this plan's decisions).
- Docs in the same commit: postcard README (Built-in layouts table: default = Winter's default layout with header, card and footer; the header and footer partials and their arguments; layout keys `siteName` and `year`; Branding: Brand.SiteName and the mail.from fallback), cabana README (Branding fields include site_name), docs/services/mail.md (Built-in layouts, Partials, Branding).
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/postcard -run 'TestMailBrandSmoke|TestMailOverrideSmoke|TestMailPartialsSmoke|TestMailRenderSmoke|TestMailLayoutSmoke' -count=1 -v 2>&1 | grep -E '^\s*(--- FAIL|--- SKIP|FAIL|ok|PASS)|default_layout' | tail -20</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, or no "--- PASS: TestMailBrandSmoke/default_layout" line</fails_when>
<automated>go test ./modules/cabana -run 'TestMailScreensSmoke' -count=1 2>&1 | tail -3</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go vet ./... && go test -short ./... && (cd examples/hello && go test ./... 2>&1 | tail -3)</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "layout-default" modules/postcard/assets/default.htm` prints at least one line and `grep -n 'partial "header"' modules/postcard/assets/default.htm` prints one line
- `grep -n "202611130002_mail_brand_site_name" modules/postcard/store.go` prints one line
- `grep -n "SiteName" modules/postcard/brand.go` prints at least one line and `grep -n "siteName" modules/postcard/templates.go` prints at least two lines
- `grep -n "site_name" modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml` prints one line
- `grep -n "site_name" modules/phrasebook/backend/lang/en/lang.yaml modules/phrasebook/backend/lang/pl/lang.yaml` prints at least two lines
- `grep -n "siteName" modules/postcard/README.md docs/services/mail.md` prints at least two lines
</acceptance_criteria>
<done>Out of the box, mail in the default layout shows the Branding logo or the site name, a white card, a styled button and a footer, in the preview and in sent mail.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: Decision note and STACK row for go-premailer, then CSS inlining at render with the per-layout opt-out</name>
<reversibility rating="costly">A new Go module in the framework's go.mod that every application and plugin building against postcard must carry in go.sum; the disable_auto_inline_css column and header key are part of the layout format.</reversibility>
<files>.planning/notes/2026-11-13-mail-layouts-css-inlining.md, .planning/research/STACK.md, go.mod, go.sum, examples/hello/go.mod, examples/hello/go.sum, modules/postcard/inline.go, modules/postcard/templates.go, modules/postcard/store.go, modules/postcard/editor.go, modules/postcard/partials_smoke_test.go, modules/postcard/brand_smoke_test.go, modules/postcard/override_smoke_test.go, modules/postcard/override_test.go, modules/postcard/mailer_test.go, modules/postcard/README.md, modules/cabana/mail_admin.go, modules/cabana/mail_routes.go, modules/cabana/backendscreens/models/maillayout/fields.yaml, modules/cabana/mail_screens_smoke_test.go, modules/cabana/README.md, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, docs/services/mail.md</files>
<behavior>
- The default layout's HTML after render has a style attribute on the button partial's link containing the brand primary colour, keeps the DOCTYPE line, keeps class attributes, and still passes postcard's safety checks
- A media-query rule in a layout's CSS ends up in a style element of the output, not on elements
- A file layout with header key disable_auto_inline_css = true renders with its style block and no inlined style attribute on the button; a database layout with the column set does the same; a layout draft with the flag previews the same way
- An inliner error (forced through a test seam) sends the un-inlined HTML and logs one warning
- The plain-text part is identical with and without inlining
</behavior>
<read_first>
- .planning/notes/2026-10-28-webp-gen2brain.md (dependency note format) and .planning/research/STACK.md "Supporting Libraries" table
- ../examples/golem15-wintercms-starter/modules/system/classes/MailManager.php (~173-199)
- modules/postcard/templates.go (~345-365 parseLayout, ~565-700 renderParts/renderLayout/layoutByCode, ~777-786 LayoutFile), modules/postcard/store.go (~170-190 LayoutOverride, ~240-256, ~369-388, ~471-478), modules/postcard/editor.go (~28-50 Draft, ~240-270 renderLayout)
- modules/cabana/mail_admin.go (~333-350 MailLayout, ~769-780 Fillable, layout FormBeforeUpdate), modules/cabana/mail_routes.go (~535-556 mailLayoutDraft), modules/cabana/backendscreens/models/maillayout/fields.yaml
- scripts/check-phase35.sh run_consumers and workspace_check (how consumers resolve this checkout)
</read_first>
<action>
Supersedes D-10's claim that postcard already inlines the brand CSS (it only placed it in a style block); WinterCMS parity with MailManager::renderTemplate.
- First, planning docs commit: verify the module before writing (`go list -m -versions github.com/vanng822/go-premailer`; `go mod download -json github.com/vanng822/go-premailer@v1.38.0` for Time and Origin; the LICENSE is MIT; v1.38.0 was published at least 7 days ago). Write `.planning/notes/2026-11-13-mail-layouts-css-inlining.md` (Status: Accepted; Context: 35-UAT G-35-8, debug session mail-layouts-unstyled, user decision 2026-11-13) recording: D-10's inlining sentence superseded; 35-01's "default.htm unchanged" gate lifted (default layout is now Winter's default layout with header and footer partials); Branding gains Site name with the mail.from fallback; the inlining decision (go-premailer exactly v1.38.0, default options, where it runs, error fallback, opt-out name and places); facts checked (publish dates, licence, maintainer, importers, its requirements, the x/net raise from v0.58.0 to what MVS selects, the transitive modules `go mod tidy` adds); the consequence that applications and plugins building with a `replace` to this checkout need `go mod tidy` (follow-up); rejected alternatives: an in-house inliner on x/net/html with douceur and cascadia (selector specificity and edge cases to own), github.com/aymerick/douceur/inliner (unmaintained since 2016), no inlining (UAT gap stays for clients that drop style blocks). Add a "Supporting Libraries" row to .planning/research/STACK.md naming the note. Commit these two files alone with the first subject.
- Then code: `go get github.com/vanng822/go-premailer@v1.38.0` and `go mod tidy` (commit go.mod and go.sum; if examples/hello needs go.sum lines, tidy and stage examples/hello/go.mod and examples/hello/go.sum by path, never examples/hello/plugins.gen.go, which holds another session's edit). If the module fails a fit check that its options cannot fix (lost DOCTYPE, output failing validateHTML, an error on the brand CSS selectors), stop and report instead of swapping libraries or hand-rolling.
- `modules/postcard/inline.go`: unexported `inlineCSS(html string) (string, error)` wrapping NewPremailerFromString + Transform with default options.
- templates.go: parseLayout reads `disable_auto_inline_css`; `LayoutFile.DisableAutoInlineCSS bool`; renderLayout carries the flag from the file or the override; renderParts, after the HTML wrapper passed validateHTML, inlines unless the flag is set, keeps the un-inlined HTML and calls opts.warn (key `inline:<layout code>`) on an inliner error, and runs validateHTML on the final HTML.
- store.go: append migration `202611130003_mail_layout_disable_auto_inline_css` (boolean NOT NULL DEFAULT FALSE on the layouts table); `LayoutOverride.DisableAutoInlineCSS bool` read by MailOverrides; SyncIndex mirrors the file header value for rows that are not customized; ResetOverride writes the file's value back.
- editor.go: `Draft.DisableAutoInlineCSS bool`, applied to layout drafts.
- cabana: `MailLayout.DisableAutoInlineCSS` in Fillable; maillayout fields.yaml gets a `disable_auto_inline_css` switch on the CSS tab above `content_css` with the label/comment keys; mailLayoutDraft maps it; a new custom layout starts with it off. Copy en/pl `mail.layout.disable_inline_css[_comment]`.
- Tests: update existing assertions that the inlined output changes (style attributes on elements, serializer differences) in this commit; new subtest `TestMailPartialsSmoke/inline` for the behavior list; extend `TestMailScreensSmoke/layouts` with a saved switch whose next send keeps the button without an inlined style attribute.
- Consumers without writing their trees: for each of ../sm-user-plugin and ../sm-paymentgateway-plugin copy go.mod and go.sum into a fresh scratch directory and run their named mail tests with `-mod=mod -modfile=<scratch>/go.mod` (after confirming with `go list -m -mod=mod -modfile=<scratch>/go.mod -f '{{.Replace.Dir}}' git.golem15.com/golem15/summercms` that the framework resolves to this checkout); `git -C <repo> status --porcelain` must stay empty.
- Docs in the same code commit: postcard README (Features and Usage: CSS inlined at render, the opt-out key and column, LayoutFile/LayoutOverride/Draft fields, error fallback; Dependencies: go-premailer), cabana README (layout form switch), docs/services/mail.md (Templates and layouts: style block plus inlining; the opt-out).
Commit as listed in Execution units (planning docs commit first, then the code commit).
</action>
<verify>
<automated>go test ./modules/postcard -count=1 -v -run 'TestMailPartialsSmoke' 2>&1 | grep -E '^\s*(--- FAIL|--- SKIP|FAIL|ok|PASS)|/inline' | tail -12</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, or no "--- PASS: TestMailPartialsSmoke/inline" line</fails_when>
<automated>go vet ./... && go test -short ./... && go test ./modules/postcard ./modules/cabana -count=1 2>&1 | tail -4 && (cd examples/hello && go test ./... 2>&1 | tail -3)</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>for r in ../sm-user-plugin ../sm-paymentgateway-plugin; do S=$(mktemp -d) && cp "$r/go.mod" "$r/go.sum" "$S"/ && (cd "$r" && go list -m -mod=mod -modfile="$S/go.mod" -f '{{.Replace.Dir}}' git.golem15.com/golem15/summercms) || exit 1; done; S=$(mktemp -d) && cp ../sm-user-plugin/go.mod ../sm-user-plugin/go.sum "$S"/ && (cd ../sm-user-plugin && go test -mod=mod -modfile="$S/go.mod" -short -count=1 -run '^(TestMail|TestPolishMailSubjects)$' . 2>&1 | tail -3); S=$(mktemp -d) && cp ../sm-paymentgateway-plugin/go.mod ../sm-paymentgateway-plugin/go.sum "$S"/ && (cd ../sm-paymentgateway-plugin && go test -mod=mod -modfile="$S/go.mod" -short -count=1 -run '^(TestMailCatalog|TestMailTracer|TestMailersMatrixSmoke)$' . 2>&1 | tail -3); git -C ../sm-user-plugin status --porcelain; git -C ../sm-paymentgateway-plugin status --porcelain</automated>
<fails_when>a "FAIL" line, a Replace.Dir that is not this checkout, or any porcelain output from either sibling repository</fails_when>
<automated>go run ./cmd/summer docs:build --check 2>&1 | tail -3 && bash scripts/check-phase35.sh --additive</automated>
<fails_when>non-zero exit or an "unknown identifier" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "github.com/vanng822/go-premailer v1.38.0" go.mod` prints one line
- `grep -n "go-premailer" .planning/research/STACK.md` prints at least one line and `.planning/notes/2026-11-13-mail-layouts-css-inlining.md` contains "D-10"
- `git log --format=%s -- .planning/notes/2026-11-13-mail-layouts-css-inlining.md` lists the docs subject on a commit older than the one that changed go.mod (`git log --format=%s -1 -- go.mod` is the feat subject)
- `grep -n "202611130003_mail_layout_disable_auto_inline_css" modules/postcard/store.go` prints one line
- `grep -n "disable_auto_inline_css" modules/cabana/backendscreens/models/maillayout/fields.yaml` prints one line
- `grep -n "go-premailer" modules/postcard/README.md` prints at least one line
</acceptance_criteria>
<done>Mail reaches clients with the design on every element unless the layout opts out, the dependency is on record before it entered go.mod, and the core plugins still pass against this checkout without being touched.</done>
</task>
<task type="auto" tdd="true">
<name>Task 3: Header, logo, footer and side padding in the system layout, logo in the minimal layout; UI-SPEC copy for inlining, site name and the opt-out</name>
<reversibility rating="reversible">Built-in asset markup and CSS only; the UI-SPEC text is documentation.</reversibility>
<files>modules/postcard/assets/system.htm, modules/postcard/assets/minimal.htm, modules/postcard/assets/brand.css.tmpl, modules/postcard/partials_smoke_test.go, modules/postcard/README.md, docs/services/mail.md, .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md</files>
<behavior>
- The system layout with a logo renders `img.logo` in `td.header` above the card, a footer row with the copyright line, and its content cell keeps the 35px side padding (no rule overrides it to 0)
- The system layout with no logo and a site name shows the name in the header
- The minimal layout with a logo shows the logo image above the message; without a logo its body holds only the message as before
- All three built-in layouts render the button partial with the brand button class and, after inlining, the brand colour on the link
</behavior>
<read_first>
- ../examples/golem15-wintercms-starter/modules/system/views/mail/layout-system.php
- modules/postcard/assets/system.htm, minimal.htm, brand.css.tmpl (as left by Tasks 1 and 2)
- modules/postcard/partials_smoke_test.go `built_in_layouts` subtest (~340-360)
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md sections C5 (CSS comment), C12 (Branding table), "Branding page" copy table and the `mail.brand.logo_comment` row
</read_first>
<action>
Finishes G-35-8 for the framework's built-in layouts (D-08's predefined layouts; D-10 Branding shown everywhere):
- system.htm: add the header partial call (logo or site name, same guard as default.htm) as the first row of `table.wrapper`, keep the card with Content and the subcopy, add the footer partial row after the card; text wrapper keeps its automatic-message line and ends with the footer's text form.
- brand.css.tmpl: drop the rule that sets the system layout's content cell padding to `35px 0` so the Winter `.content-cell` padding (35px) applies; check `.footer` and `.footer .content-cell` spacing against Winter's footer and keep the footer text centred.
- minimal.htm: when logoUrl is set, an `img.logo` (alt = siteName) in a paragraph above Content; nothing else changes.
- Tests: update `TestMailPartialsSmoke/built_in_layouts` for the behavior list (its exact-body assertion on the minimal layout becomes the without-logo case).
- Docs in the code commit: postcard README Built-in layouts table rows for system and minimal; docs/services/mail.md Built-in layouts.
- Then a planning-docs commit for 35-UI-SPEC.md: C5 CSS comment now true (inlining) plus a row for the `disable_auto_inline_css` switch on the CSS tab with its copy; C12 Branding table gets the `site_name` row after the logo with its copy, and the changed `mail.brand.logo_comment` text; a short note under C12 that the built-in layouts show logo or site name in the header and the copyright footer, referencing `.planning/notes/2026-11-13-mail-layouts-css-inlining.md` as superseding D-10's inlining claim.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/postcard -count=1 -v -run 'TestMailPartialsSmoke' 2>&1 | grep -E '^\s*(--- FAIL|--- SKIP|FAIL|ok|PASS)|built_in_layouts' | tail -12</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, or no "--- PASS: TestMailPartialsSmoke/built_in_layouts" line</fails_when>
<automated>go vet ./... && go test -short ./... && go test ./modules/postcard ./modules/cabana -count=1 2>&1 | tail -4 && go run ./cmd/summer docs:build --check 2>&1 | tail -3</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n 'partial "header"' modules/postcard/assets/system.htm` and `grep -n 'partial "footer"' modules/postcard/assets/system.htm` each print one line
- `grep -n "logoUrl" modules/postcard/assets/minimal.htm` prints at least one line
- `grep -c "layout-system .content-cell" modules/postcard/assets/brand.css.tmpl` prints 0
- `grep -n "site_name" .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md` and `grep -n "disable_auto_inline_css" .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md` each print at least one line
</acceptance_criteria>
<done>Every built-in layout (default, system, minimal) shows the Branding logo or name, and the design contract describes inlining, the site name and the opt-out as shipped.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| admin browser → Branding settings | administrators with system.manage_mail_layouts set the site name shown in every mail |
| admin browser → layout overrides | administrators write layout HTML and CSS that the inliner now copies onto elements |
| Go module proxy → go.mod | a new third-party module enters the framework binary |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-35-34 | Tampering | site name in layouts | medium | mitigate | the name reaches mail only through html/template (HTML-escaped, alt attribute contextually escaped) and the text template of the text part; it never goes into a header line; saved trimmed with max 255 characters (TestMailBrandSmoke/default_layout, TestMailScreensSmoke/branding) |
| T-35-35 | Tampering | CSS moved onto elements by the inliner | high | mitigate | layout CSS keeps the closing-style and dangerous-scheme checks at save; validateHTML runs on the final inlined HTML at every render, so a javascript:/vbscript:/data: URL that reaches a style attribute fails the render and the file version is sent (D-14) |
| T-35-36 | Denial of service | inliner on large or odd HTML | low | mitigate | content is administrator-authored and per message; an inliner error falls back to the un-inlined HTML with a rate-limited warning, mail is never blocked |
| T-35-37 | Tampering | github.com/vanng822/go-premailer and its requirements | medium | mitigate | exact pin v1.38.0 (published 2026-11-04, past the 7-day cooldown), go.sum verified against the checksum database, MIT licence and maintainer checked and recorded in the decision note before go.mod changes; transitive modules listed in the note |
| T-35-38 | Information disclosure | mail.from display name fallback | low | accept | the display name is already in every message's From header |
| T-35-SC | Tampering | npm/pip/cargo installs | high | accept | this plan installs no npm, pip or cargo package; the Go module is T-35-37 |
</threat_model>
<verification>
- `go vet ./... && go test -short ./...`, `go test ./modules/postcard ./modules/cabana` and `cd examples/hello && go test ./...` green after every code commit.
- Consumer mail tests of sm-user-plugin and sm-paymentgateway-plugin pass through a scratch `-modfile` with their working trees unchanged. Until 35-07 Task 1 bakes that into the gate, `bash scripts/check-phase35.sh --consumers` (and so `--all`) is expected to fail on the siblings' missing go.sum lines for go-premailer; that is not a regression of this plan, but run the scratch-modfile command in Task 2's verify instead.
- `go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree'`, `go run ./cmd/summer docs:build --check` and `bash scripts/check-phase35.sh --additive` pass.
- No change under admin/ is expected; if one was needed, `npm --prefix admin run build`, the dist commit and `scripts/check-admin-dist.sh` are required (CLAUDE.md).
</verification>
<success_criteria>
- default, system and minimal layouts are finished (logo or name header, card, footer, padding) and the button partial is styled in all of them.
- Branding has Site name with the mail.from fallback.
- CSS is inlined at render with a per-layout opt-out; go-premailer recorded in a decision note and STACK.md before it entered go.mod.
- READMEs, docs and UI-SPEC describe what ships; D-10's inlining claim and the 35-01 default.htm gate are superseded on record; nothing pushed or tagged.
</success_criteria>
<output>
Create `.planning/phases/35-mail-templates-and-layouts-editor/35-06-SUMMARY.md` when done; list the migration IDs, the new layout keys, partial arguments, the exported fields (Brand.SiteName, LayoutFile/LayoutOverride/Draft DisableAutoInlineCSS), the exact go.mod changes (direct and indirect), the copy keys and the test names, because 35-07 tests them.
</output>
## Follow-ups outside this phase (not planned here)
After the framework release tag that contains 35-05 and 35-06 (tag only at phase completion, on the default branch, with Jakub's go-ahead):
- sm-user-plugin: bump the framework requirement (and `go mod tidy` for go-premailer); activate/restore/invite (+ -en) use `{{ partial "button" ... }}` instead of Markdown links; replace `layouts/user.htm` with a full layout built on the framework's structure and partials, keeping the name; fix its text wrapper.
- sm-paymentgateway-plugin: bump the framework requirement; order templates use the button partial and drop the duplicated URL; replace `layouts/paymentgateway.htm` keeping the name.
- Applications building with a `replace` to this checkout (sm-demo-app and others) run `go mod tidy` to pick up go-premailer's go.sum lines.
- sm-demo-app: reset the UAT overrides of `golem15.user::mail.layouts.user` and `golem15.user::mail.activate` before re-running UAT test 8. After this phase that re-run covers the built-in layouts only (35-07 records G-35-8 as framework-closed). The activate CTA rendering as a button and the finished user/paymentgateway layouts are checked after the plugin follow-up.
</content>
</invoke>

View File

@@ -0,0 +1,289 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 06
subsystem: mail
tags: [postcard, cabana, mail-layouts, branding, css-inlining, go-premailer, gap-closure]
status: complete
requires:
- phase: 35-05
provides: TemplateBase / Catalog.TemplateFor / EnsureLocaleRows and migration 202611130001_mail_template_base_code (built on, not changed)
provides:
- WinterCMS default layout port (header with logo or site name, white card, copyright footer) in postcard's default.htm
- built-in header and footer partials
- layout keys siteName and year
- Brand.SiteName (Branding Site name, mail.from display-name fallback) and the site_name column
- CSS inlining at render through github.com/vanng822/go-premailer v1.38.0, with the per-layout disable_auto_inline_css opt-out
- finished system layout (header, footer, side padding) and minimal layout (logo)
affects: [35-07, sm-user-plugin follow-up, sm-paymentgateway-plugin follow-up, consumers with a replace to this checkout]
actuals:
tokens: 38920
tasks: 3
commits: 5
plan_head_before: fdc2094ffc01ea21eea80c944820d3357ffed589
plan_head_after: f1cebf1d70f3ba70da6c08c6f90ad86992242d78
tech-stack:
added:
- "github.com/vanng822/go-premailer v1.38.0 (direct)"
patterns:
- "Inline after render: validateHTML, then go-premailer, then validateHTML again; HTML without a style element is left as it is; an inliner error keeps the style block and warns (rate-limited)"
- "Per-layout opt-out mirrored in three places: file header key, layouts column, Draft field"
- "Tests that check what fills the CSS slots use a no-op inliner seam (mailer.inline) or the opt-out flag"
key-files:
created:
- modules/postcard/inline.go
- modules/postcard/assets/partials/header.htm
- modules/postcard/assets/partials/footer.htm
- .planning/notes/2026-11-13-mail-layouts-css-inlining.md
modified:
- modules/postcard/assets/default.htm
- modules/postcard/assets/system.htm
- modules/postcard/assets/minimal.htm
- modules/postcard/assets/brand.css.tmpl
- modules/postcard/templates.go
- modules/postcard/mailer.go
- modules/postcard/brand.go
- modules/postcard/store.go
- modules/postcard/editor.go
- modules/cabana/mail_admin.go
- modules/cabana/mail_routes.go
- modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml
- modules/cabana/backendscreens/models/maillayout/fields.yaml
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- go.mod
- go.sum
- .planning/research/STACK.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md
key-decisions:
- "CSS inlining runs inside postcard's render path with go-premailer v1.38.0 default options, so preview, test send and sends match; supersedes D-10's inlining claim"
- "Layouts opt out of inlining with disable_auto_inline_css (file header key, layouts column, layout form switch), WinterCMS's option name; built-in layouts all inline"
- "Branding gains Site name; empty falls back to the display name of mail.from; the default and system layouts show logo or name in the header and a language-neutral footer (© year name)"
- "HTML without a style element is not passed through the inliner: x/net/html would re-serialise it (attribute order, html/head/body wrappers) with nothing to inline"
- "35-01's default.htm-unchanged gate is lifted; the default layout is WinterCMS's default layout built on the new header and footer partials"
patterns-established:
- "Mail layout keys: Content, Subject, css, brandCss, logoUrl, siteName, year"
- "Header partial arguments: logo, body, url (optional); footer partial argument: body (Markdown)"
requirements-completed: [G-35-8, D-10, D-11, D-12, D-14]
coverage:
- id: D1
description: "Default layout ports WinterCMS's default layout: header with the Branding logo (alt = site name) or the site name, inner-body card, styled button, footer with © year and site name; mail.from fallback; no header row without name and logo"
requirement: G-35-8
verification:
- kind: unit
ref: "modules/postcard/brand_smoke_test.go#TestMailBrandSmoke/default_layout"
status: pass
human_judgment: false
- id: D2
description: "Branding Site name: site_name column (migration 202611130002), Brand.SiteName read by the DB source, cabana form field (trimmed, max 255), Branding preview shows it"
requirement: D-10
verification:
- kind: integration
ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/branding"
status: pass
- kind: integration
ref: "modules/postcard/brand_smoke_test.go#TestMailBrandSmoke/precedence"
status: pass
human_judgment: false
- id: D3
description: "CSS inlined at render (button carries the brand colour inline, DOCTYPE and classes kept, media query stays in a style element), per-layout opt-out from file header, DB column and draft, inliner error falls back with one warning, text part unchanged"
requirement: D-14
verification:
- kind: unit
ref: "modules/postcard/partials_smoke_test.go#TestMailPartialsSmoke/inline"
status: pass
- kind: integration
ref: "modules/postcard/editor_smoke_test.go#TestMailEditorSmoke/inline_flag"
status: pass
- kind: integration
ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/layouts"
status: pass
human_judgment: false
- id: D4
description: "System layout has the header, footer and 35px side padding; minimal layout shows the logo above the message; all three built-in layouts render the button with the inlined brand colour"
requirement: D-12
verification:
- kind: unit
ref: "modules/postcard/partials_smoke_test.go#TestMailPartialsSmoke/built_in_layouts"
status: pass
human_judgment: false
- id: D5
description: "sm-user-plugin and sm-paymentgateway-plugin mail tests pass against this checkout through scratch modfiles, their trees unchanged"
requirement: D-11
verification:
- kind: other
ref: "go test -mod=mod -modfile=<scratch>/go.mod (sm-user-plugin: TestMail, TestPolishMailSubjects -short; sm-paymentgateway-plugin with GOWORK=off: TestMailCatalog, TestMailTracer, TestMailersMatrixSmoke without -short); git status --porcelain empty in both"
status: pass
human_judgment: false
- id: D6
description: "Mail in the built-in layouts looks finished in real mail clients and the admin preview (UAT test 8 re-run for the built-in layouts)"
requirement: G-35-8
verification: []
human_judgment: true
rationale: "Visual rendering across mail clients (webmail, Outlook) and the admin preview needs a human; automated tests assert markup and inlined styles only"
duration: 33min
completed: 2026-11-13
---
# Phase 35 Plan 06: Finished built-in mail layouts and CSS inlining Summary
**WinterCMS's default layout (logo or site-name header, white card, © year footer) in postcard's default, system and minimal layouts, a Branding Site name with the mail.from fallback, and CSS inlined onto elements at render through go-premailer v1.38.0, with a per-layout disable_auto_inline_css opt-out (G-35-8)**
## Performance
- **Duration:** 33 min
- **Started:** 2026-11-13T19:44:45Z
- **Completed:** 2026-11-13T20:17:36Z
- **Tasks:** 3
- **Files modified:** 34
## Accomplishments
- `default.htm` is WinterCMS's default layout: `table.wrapper.layout-default`, the `header` partial with `img.logo` (alt = site name) or the name in a span, the `inner-body` card, and the `footer` partial with `© <year> <site name>` (or `© <year>`). Its text wrapper ends with the footer's text section.
- `system.htm` has the same header and footer, and its content cell keeps WinterCMS's 35px side padding. `minimal.htm` shows the logo above the message.
- Branding has a Site name (`site_name`, `Brand.SiteName`). When it is empty, the display name of `mail.from` is used. The cabana form field, the en/pl copy and the Branding preview all carry it.
- postcard inlines the rendered HTML with go-premailer in preview, test send and sends. The DOCTYPE and classes are kept, and media queries stay in a style element. Each layout can opt out through a file header key, a database column (with a CSS-tab switch in the layout form) or `Draft.DisableAutoInlineCSS`. An inliner error sends the style block only and logs a rate-limited warning.
- The decision note and the STACK.md row went in before go.mod changed. The core consumer plugins pass against this checkout without any change to their trees.
## Task Commits
1. **Task 1: default layout with header, footer and site name (tracer)** - `093529d4` (feat)
2. **Task 2: decision note and STACK row** - `dcd0ae53` (docs); **CSS inlining with the per-layout opt-out** - `d3207335` (feat)
3. **Task 3: system and minimal layouts** - `09a5338d` (feat); **UI-SPEC copy** - `f1cebf1d` (docs)
**Plan metadata:** recorded in the SUMMARY commit (docs)
## Interfaces for 35-07
- **Migrations:** `202611130002_mail_brand_site_name` (`system_mail_brand_settings.site_name TEXT NOT NULL DEFAULT ''`), `202611130003_mail_layout_disable_auto_inline_css` (`system_mail_layouts.disable_auto_inline_css BOOLEAN NOT NULL DEFAULT FALSE`). Both roll back by dropping the column.
- **Layout keys (both wrappers):** `Content`, `Subject`, `css`, `brandCss`, `logoUrl`, plus the new `siteName` (Branding site name trimmed, else the `net/mail` display name of `mail.from`, else empty) and `year` (int, the current year).
- **Partials:** `header` (`postcard::mail.partials.header`), with arguments `logo` (URL), `body` (name) and `url` (optional link). Its HTML is `<tr><td class="header">` holding `img.logo` (alt = body), or `<span>body</span>` when there is no logo. Its text is the name. `footer` (`postcard::mail.partials.footer`) takes `body` (Markdown). Its HTML is a `<tr>` with `table.footer` and `td.content-cell`; its text is a line of 19 dashes followed by the body. `builtinPartials` now has 6 entries, so SyncIndex writes 2 more partial rows.
- **Exported fields:** `Brand.SiteName`, `LayoutFile.DisableAutoInlineCSS`, `LayoutOverride.DisableAutoInlineCSS`, `Draft.DisableAutoInlineCSS`, `cabana.MailBrandSetting.SiteName`, `cabana.MailLayout.DisableAutoInlineCSS`.
- **Header key / column:** `disable_auto_inline_css` (`true`, `1` or `yes`, any case). SyncIndex mirrors it into rows that are not customized, and ResetOverride writes the file's value back.
- **go.mod:** direct `github.com/vanng822/go-premailer v1.38.0`. Raised: `golang.org/x/net` v0.58.0→v0.62.0, `golang.org/x/crypto` v0.57.0→v0.58.0, `golang.org/x/text` v0.42.0→v0.43.0, `golang.org/x/term` v0.46.0→v0.47.0. Indirect, raised: `golang.org/x/sys` v0.48.0→v0.49.0, `golang.org/x/sync` v0.23.0→v0.24.0. Indirect, added: `github.com/PuerkitoBio/goquery` v1.13.0, `github.com/andybalholm/cascadia` v1.3.4, `github.com/inbucket/html2text` v1.0.0, `github.com/vanng822/css` v1.0.1, `github.com/olekukonko/tablewriter` v1.0.7, `github.com/olekukonko/errors` v1.1.0, `github.com/olekukonko/ll` v0.0.9, `github.com/fatih/color` v1.18.0, `github.com/mattn/go-colorable` v0.1.14, `github.com/mattn/go-isatty` v0.0.20, `github.com/ssor/bom` v0.0.0-20170718123548-6386211fdfcf. examples/hello/go.mod and go.sum are unchanged.
- **Copy keys (en/pl):** new `mail.brand.site_name`, `mail.brand.site_name_comment`, `mail.layout.disable_inline_css`, `mail.layout.disable_inline_css_comment`; changed `mail.brand.logo_comment`.
- **Tests:** `TestMailBrandSmoke/default_layout` (new), `TestMailPartialsSmoke/inline` (new), `TestMailPartialsSmoke/built_in_layouts` (rewritten), `TestMailEditorSmoke/inline_flag` (new, Docker), `TestMailScreensSmoke/branding` and `/layouts` (extended), `TestMailBrandSmoke/precedence` (now checks site_name too). Test seams are `mailer.inline` (unexported; nil means `inlineCSS`), `noInline`, `unstyled`, `buttonStyle` and `copyright` in the postcard tests.
## Files Created/Modified
- `modules/postcard/inline.go` wraps go-premailer and turns a panic into an error.
- `modules/postcard/assets/{default,system,minimal}.htm` are the finished built-in layouts. `assets/partials/{header,footer}.htm` are the new partials. `brand.css.tmpl` gains the `img.logo` rule and loses the `.wrapper.layout-system .content-cell` override.
- `modules/postcard/templates.go` holds the siteName/year keys, the opt-out parse (`headerBool`, `disableInlineKey`) and the `inlineHTML` step in `renderParts`.
- `modules/postcard/mailer.go` holds the `siteName` fallback. `options` now passes `inline` and `warn` to the file version as well.
- `modules/postcard/store.go` has the two migrations, the site_name read, the opt-out read, SyncIndex mirroring and the reset.
- `modules/postcard/editor.go` handles the brand draft site name and the layout draft opt-out.
- `modules/cabana/*`: `MailBrandSetting.SiteName`, `MailLayout.DisableAutoInlineCSS`, the draft mapping (`boolValue`), the form fields and the save validation with the opt-out.
- The docs are the postcard and cabana READMEs and `docs/services/mail.md` (CSS inlining section, built-in layouts, partials, Branding). The planning docs are the decision note, STACK.md and 35-UI-SPEC.md (C5, C12).
## Decisions Made
- Inlining uses go-premailer's default options: classes are kept and widths and heights are mirrored to attributes. Leftover rules go back into one style element in the head, marked `!important`, so after inlining the style block holds only those rules.
- HTML with no style element skips the inliner. There is nothing to inline, and x/net/html v0.62 would otherwise re-serialise the fragment (attribute order, html/head/body wrappers).
- Inliner warnings are now logged on the file-version path too: `mailer.options` sets `warn`, which used to be set only on the override path.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 2 - Missing critical] A panic in the inliner becomes an error**
- **Found during:** Task 2
- **Issue:** goquery or the CSS parser could panic on unusual HTML, and a panic would stop the send (T-35-36).
- **Fix:** `inlineCSS` recovers the panic and returns an error, which takes the style-block fallback and logs a warning.
- **Files modified:** modules/postcard/inline.go
- **Committed in:** d3207335
**2. [Rule 1 - Bug] HTML without a style element is no longer re-serialised**
- **Found during:** Task 2
- **Issue:** Fragments with no CSS, such as `<main>{{ .Content }}</main>`, came back wrapped in html/head/body with their attributes reordered, although nothing had been inlined.
- **Fix:** `inlineHTML` returns the HTML as it is when it has no `<style` element.
- **Files modified:** modules/postcard/templates.go
- **Committed in:** d3207335
**3. [Rule 2 - Missing critical] The inliner warning is logged for the file version**
- **Found during:** Task 2
- **Issue:** `opts.warn` was nil on the file-version path, so an inliner failure in ordinary mail went unlogged.
- **Fix:** `mailer.options` sets `warn: m.warn` and `inline: m.inline`.
- **Files modified:** modules/postcard/mailer.go
- **Committed in:** d3207335
**4. [Rule 2 - Correctness] Layout save validation renders with the opt-out**
- **Found during:** Task 2
- **Issue:** cabana's save validation built the layout draft without the switch, so the result it checked could differ from what is sent.
- **Fix:** The `mailLayoutsAdmin.validate` draft carries `DisableAutoInlineCSS`. The `boolValue` helper reads the switch from preview payloads.
- **Files modified:** modules/cabana/mail_admin.go, modules/cabana/mail_routes.go
- **Committed in:** d3207335
**5. [Rule 3 - Blocking] The consumer check needed GOWORK=off for sm-paymentgateway-plugin**
- **Found during:** Task 2 verify
- **Issue:** That repository has a go.work, and `-modfile` is refused in workspace mode.
- **Fix:** Ran its check with `GOWORK=off`. Its go.mod also replaces the framework with `../summercms.go` (Replace.Dir confirmed). Its TestMailTracer and TestMailersMatrixSmoke skip under `-short`, so they were also run without `-short` (Docker), and they pass. `git status --porcelain` stayed empty in both repositories.
**6. [Test seam] The no-op inliner is a mailer field, not a package variable**
- **Found during:** Task 2
- **Issue:** Swapping a package variable would race with parallel tests (TestBrand uses t.Parallel).
- **Fix:** Added the unexported field `mailer.inline`. Tests that check what fills the CSS slots (style block contents and order) use `noInline` or the opt-out flag. Tests of the delivered markup compare HTML with its `style` attributes stripped.
**7. [CLAUDE.md] The TDD RED phase was verified but not committed on its own**
- **Found during:** Tasks 2 and 3
- **Issue:** CLAUDE.md requires `go test ./...` to be green at every commit, so a separate failing `test(...)` commit is not allowed.
- **Fix:** RED was run and checked with `msd_run check tdd-red-evidence`; both runs returned `RED_EVIDENCE_OK`. The records are `35-06-task2-red-evidence.json` and `35-06-task3-red-evidence.json` in the session scratchpad, built from go test JSON converted to JUnit. Each test landed with its implementation in the plan's listed feat commit. Before that, Task 2's struct fields were added with no behaviour so the RED test compiled.
**8. [Acceptance wording] Two grep criteria print more lines than "one"**
- `grep -n "site_name" .../mailbrandsetting/fields.yaml` prints 3 lines: the field key, plus the label and comment keys `mail.brand.site_name[_comment]` the plan prescribes.
- `grep -n 'partial "footer"' modules/postcard/assets/system.htm` prints 2 lines, one per wrapper. The plan's action requires both: the text wrapper "ends with the footer's text form".
- Both criteria are met in substance; the counts follow from the plan's own copy keys and text wrapper.
**9. [Scope] examples/hello go.mod and go.sum are unchanged**
- `go mod tidy` there would have rewritten about 90 unrelated lines of an already stale go.mod. The module builds and tests through go.work as it is (`go test ./...` passes), so it needed no go.sum lines.
---
**Total deviations:** 9 (3 Rule 2, 1 Rule 1, 1 Rule 3, 1 test-seam choice, 1 CLAUDE.md-driven TDD commit shape, 2 notes on acceptance wording and scope).
**Impact on plan:** The fixes make inlining safer and keep it from changing mail that has no CSS. The scope is unchanged, and nothing in a sibling repository was touched.
## TDD Gate Compliance
There is no separate `test(35-06)` RED commit. CLAUDE.md requires `go vet ./...` and `go test ./...` to be green at every commit. RED was verified before GREEN for both TDD tasks, with `RED_EVIDENCE_OK` from `check tdd-red-evidence`; the target tests were `TestMailPartialsSmoke/inline` and `TestMailPartialsSmoke/built_in_layouts`. The tests are committed in the feat commits d3207335 and 09a5338d.
## Issues Encountered
- x/net/html v0.62 (raised by MVS) re-serialises the inlined HTML. Attribute order can change (for example `class` before `href` on the button), `<tbody>` is inserted, and void elements end with `/>`. Assertions on exact markup were moved to style-stripped comparisons. The consumer plugins' mail tests pass unchanged.
- gofmt already reported `modules/cabana/mail_routes.go` and `modules/postcard/store_postgres_test.go` before this plan; this plan added no new gofmt diffs. They were not logged to deferred-items.md, because another session holds uncommitted edits in that file.
## Threat Flags
| Flag | File | Description |
|------|------|-------------|
| threat_flag: availability | modules/postcard/templates.go (validateHTML) | validateHTML scans all rendered HTML, text included, for `javascript:`, `vbscript:` and `data:`. A Branding site name (or a `mail.from` display name) containing such text would make every message in the default and system layouts fail to render. Nothing checks the name for this at save time; cabana only trims it and caps it at 255 characters. An administrator would have to type it. Worth a save-time check in 35-07 or later. |
## Known Stubs
None.
## User Setup Required
None. No external service configuration is required. Follow-up outside this phase: consumers that build with a `replace` to this checkout need `go mod tidy` to pick up go-premailer's go.sum lines (see the decision note).
## Next Phase Readiness
- 35-07 can record G-35-8 as closed in the framework and bake the scratch-modfile consumer check into `check-phase35.sh --consumers`. Until then, `--consumers` fails on the siblings' missing go.sum lines, as the plan expected.
- The plugin follow-up (user and paymentgateway layouts and templates, go.mod bumps) waits for the framework tag.
## Self-Check: PASSED
- Created files exist: modules/postcard/inline.go, modules/postcard/assets/partials/header.htm, modules/postcard/assets/partials/footer.htm, .planning/notes/2026-11-13-mail-layouts-css-inlining.md.
- Commits exist: 093529d4, dcd0ae53, d3207335, 09a5338d, f1cebf1d.
- The decision note commit (dcd0ae53) is older than the go.mod commit (d3207335, the feat subject).
- `go vet ./...`, `go test -short ./...`, `go test ./modules/postcard ./modules/cabana` (Docker), `cd examples/hello && go test ./...`, `docs:build --check`, `TestCommandsDocumented|TestDocsTree`, `check-phase35.sh --additive` and `check-admin-openapi.sh --check` all pass.
---
*Phase: 35-mail-templates-and-layouts-editor*
*Completed: 2026-11-13*

View File

@@ -0,0 +1,289 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 07
type: execute
wave: 7
depends_on: ["35-05", "35-06"]
gap_closure: true
gap_ids: [G-35-1, G-35-8]
files_modified:
- scripts/check-phase35.sh
- modules/postcard/locale_test.go
- modules/postcard/locale_postgres_test.go
- modules/postcard/layouts_test.go
- modules/postcard/inline_test.go
- modules/cabana/mail_locale_postgres_test.go
- modules/cabana/mail_brand_layout_postgres_test.go
- admin/tests/form/LocaleVariantSwitcher.test.ts
- admin/tests/form/FormViewMail.test.ts
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md
autonomous: true
requirements: [G-35-1, G-35-8, D-21]
estimate:
tokens: 110000
raw_tokens: 110000
tasks: 3
confidence: low
must_haves:
truths:
- "scripts/check-phase35.sh runs the consumer plugins through a scratch -modfile so it stays read-only with the new go-premailer requirement, refuses when a sibling tree becomes dirty, requires every new test by name, and --all passes (D-21)"
- "Unit tests cover locale grouping: TemplateBase and Catalog.TemplateFor rules (own file, fallback tag, pt-BR, longest base, non-locale suffixes, unknown names), the send order code-<locale> customization → default customization → default file with file-backed names unchanged, EnsureLocaleRows (rows only for non-default locales without files, idempotent, customized content kept, file_hash following the base), base_code in SyncIndex and reset of a fallback code (G-35-1)"
- "Unit tests cover the admin side of locale grouping: one list row per template, the customized-locales value, grouped badges and status filter, localeVariants order, labels, states and current flag, the default version shown on a not-customized fallback row, save then send, reset, drift through the base file, the file version against the base file, out-of-group ids and the permission split on fallback rows (G-35-1)"
- "Unit tests show a logo img (alt = site name) in the header of the default and system layouts and above the message in the minimal layout whenever Branding has a logo, the site name or nothing when it does not, the mail.from display-name fallback, and the footer's year and name (G-35-8)"
- "Unit tests show the button partial's output (class, href, type variants) in every built-in layout, CSS inlined onto elements with the DOCTYPE kept and media queries left in a style block, the plain-text part unchanged, the safety check on the inlined output, the per-layout opt-out (file header key, override column, layout draft, layout form switch) and the fallback when the inliner fails (G-35-8)"
- "SPA tests cover the locale switcher (options, current, navigation, restored selection when the unsaved-changes confirm is cancelled) and FormView showing it only with two or more variants (G-35-1)"
- "go vet ./... and go test ./... stay green; 35-VALIDATION.md maps G-35-1 and G-35-8"
- "G-35-8 is recorded as framework-closed with its plugin part deferred, in 35-VALIDATION.md and in a closure note on the G-35-8 entry of 35-UAT.md. The re-run of UAT test 8 is scoped to what this phase ships: preview a template in the default and system layouts with a Branding logo and Site name and a body override that calls the button partial. The activate CTA as a button and the finished user/paymentgateway layouts are listed as a deferred follow-up check for the plugin follow-up after the framework tag."
prohibitions:
- statement: "No production code changes except fixes for defects the new tests expose, each in its own fix commit and recorded as a deviation in the SUMMARY."
status: unresolved
verification: judgment
- statement: "Tests and the gate never write into a sibling repository (git status --porcelain of sm-user-plugin and sm-paymentgateway-plugin stays empty) and never reach the network beyond localhost, httptest servers and testcontainers."
status: unresolved
verification: automated
- statement: "Nothing is pushed or tagged (tag only at phase completion, on the default branch, after Jakub's go-ahead)."
status: unresolved
verification: judgment
artifacts:
- path: "scripts/check-phase35.sh"
provides: "phase gate including the gap-closure tests (tracer)"
contains: "modfile"
- path: "modules/postcard/locale_test.go"
provides: "locale resolution unit tests"
contains: "func TestTemplateFor"
- path: "modules/postcard/inline_test.go"
provides: "CSS inlining and opt-out tests"
contains: "func TestInlineCSSOptOut"
- path: "modules/cabana/mail_locale_postgres_test.go"
provides: "grouped templates admin tests"
contains: "func TestMailLocaleGroups"
key_links:
- from: "scripts/check-phase35.sh"
to: "../sm-user-plugin"
via: "consumers stage runs the mail tests with a scratch -modfile copy of go.mod and go.sum"
pattern: "modfile"
- from: "scripts/check-phase35.sh"
to: "modules/cabana/mail_locale_postgres_test.go"
via: "DOCKER_TESTS requires TestMailLocaleGroups by name"
pattern: "TestMailLocaleGroups"
- from: "modules/postcard/layouts_test.go"
to: "modules/postcard/assets/default.htm"
via: "logo, header and footer assertions on the built-in layouts"
pattern: "TestBuiltinLayoutsLogo"
---
## Phase Goal
ROADMAP Goal (not in user-story format; no story is invented): administrators edit every mail the application sends from the admin panel, and mail that already works keeps working. Project rule 2 puts unit tests in the last plan of the phase; this plan is the last plan of the 35 gap closure and proves G-35-1 (35-05) and G-35-8 (35-06) with unit tests and the extended phase gate.
<objective>
- `scripts/check-phase35.sh`: a read-only scratch-modfile consumers stage (the core plugins' go.sum does not carry go-premailer yet), a dirty-tree refusal, and every new test required by name.
- postcard unit tests for locale resolution and fallback rows, built-in layouts (logo, header, footer, site name), the button partial and CSS inlining with its opt-out and failure fallback.
- cabana Postgres tests for the grouped templates screen, the Branding site name and the layout inlining switch; SPA tests for the locale switcher.
- `--all` green; 35-VALIDATION.md updated; G-35-8 recorded as framework-closed with the plugin part deferred (35-VALIDATION.md and a closure note in 35-UAT.md), with a UAT test 8 re-run scoped to the built-in layouts.
Purpose: D-21's "unit tests last" rule for the gap closure; the gate is what `/msd-verify-work` runs before UAT tests 1 and 8 are re-checked.
Output: test and gate-script commits in this repository; one planning-docs commit for 35-VALIDATION.md. No sibling repository is changed; nothing is pushed or tagged.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-05-SUMMARY.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-06-SUMMARY.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-04-SUMMARY.md
@CLAUDE.md
<interfaces>
- Names to test come from 35-05-SUMMARY.md and 35-06-SUMMARY.md (where they differ from this plan, the SUMMARY wins): postcard.TemplateBase, (*Catalog).TemplateFor, postcard.EnsureLocaleRows, migration IDs 202611130001..003, Brand.SiteName, LayoutFile/LayoutOverride/Draft DisableAutoInlineCSS, layout keys siteName and year, built-in partials header and footer, unexported inlineCSS; cabana.RecordMeta.LocaleVariants / RecordLocaleVariant, MailTemplate customized_locales, MailBrandSetting.SiteName, MailLayout.DisableAutoInlineCSS; SPA LocaleVariantSwitcher.vue.
- Existing helpers: modules/postcard/override_smoke_test.go `mailPostgres(t)` (fresh migrated database per call) and `bootMailApp`; modules/postcard/override_test.go fake OverrideSource patterns; modules/cabana/mail_screens_smoke_test.go `newMailScreensEnvWith(t, mailEnvOptions{files, keep, mutate})` with fixture plugin acme.blog (`blogWelcome`, `blogWelcomeEn`), the fake TranslationWriter 35-05 added for the locales subtest, login/request helpers; admin/tests/form/FormViewMail.test.ts mount and router helpers.
- scripts/check-phase35.sh: GO_TESTS (Docker-free, never skip under -short), DOCKER_TESTS, ADMIN_FILES, ADMIN_BROWSER_FILES, USER_MAIL_TESTS, PAYMENTGATEWAY_MAIL_TESTS (~60-125); `go_named` anchors names (`^(A|B)$`, ~277); `workspace_check` (~348) runs `go list -m` in the sibling; `run_consumers` (~597) runs workspace_check, `go_vet` and `go_named` per sibling; `run_self_test` (~418) plants cases; `scratch_init`/`scratch_cleanup` (~685-700); `run_all` prints "Phase 35 gate passed" (~789).
- 35-06 Task 2 ran the consumer tests by hand with `-mod=mod -modfile=<scratch>/go.mod` and checked `Replace.Dir`; that is the command shape to bake in.
- Existing test names that must not be reused: TestOverride, TestFallback, TestPartial, TestSample, TestValidateDraft, TestBrand, TestStore, TestSync, TestMailLocale, TestMailDiff, TestMailFieldSchema, TestMailPermissions, TestMailSave, TestMailDrift, TestMailReset, TestMailLayoutDelete, TestMailBrand, TestMailTestSend and the *Smoke tests.
</interfaces>
</context>
## Execution units and resume points
- Before each task run `git status --short modules/postcard modules/cabana admin/tests scripts` and stop if another session holds uncommitted edits in files this task touches.
- Stage by explicit path. Tests are written against the shipped code; a defect a test exposes gets its own `fix(<module>): ...` commit before the test commit, recorded as a deviation. `go vet ./...` and `go test ./...` green at every commit. Docker-backed tests without `-short` (through `sudo -u golem` if the socket is denied).
- Each test task adds its new names to the gate's required arrays in the same commit as the tests, so the gate never requires a test that does not exist yet.
- Resume check: `git log --format=%s -F --grep='<subject>'`.
| Task | Commit subject | Resume point |
|------|----------------|--------------|
| 1 | `test(35): read-only consumers with a scratch modfile in check-phase35.sh` | `--self-test` and `--consumers` pass, sibling trees clean |
| 2 | `test(postcard): locale fallback, built-in layouts, partials and CSS inlining` | `--go` passes with the new names |
| 3 | `test(cabana): grouped mail templates, site name and the inlining switch`, `test(admin): mail template locale switcher`, then `docs(35): validation map for the gap closure` | `bash scripts/check-phase35.sh --all` passes |
<tasks>
<task type="tracer">
<name>Task 1: End-to-end "one command proves the gap closure leaves the core plugins' mail working, with the new go-premailer requirement, without writing their trees" — the consumers stage only</name>
<files>scripts/check-phase35.sh</files>
<read_first>
- scripts/check-phase35.sh (whole file)
- .planning/phases/35-mail-templates-and-layouts-editor/35-06-SUMMARY.md (the scratch-modfile command that worked, the go.mod changes)
</read_first>
<action>
Per D-21:
- Consumers stage: for each sibling, copy its go.mod and go.sum into a scratch directory created through the existing scratch helpers (removed by scratch_cleanup) and pass `-mod=mod -modfile=<scratch>/go.mod` to workspace_check's `go list -m`, to `go vet ./...` and to the named mail tests, so the framework's new requirement resolves without writing the sibling tree; after the runs, refuse with a `refuse:` line when `git -C <sibling> status --porcelain` prints anything. Keep the Docker rule (no -short when Docker answers). Update the stage's header comment.
- Self-test: add a planted case proving the dirty-tree refusal (a scratch git repository with an untracked file), and a planted case proving workspace_check under a modfile refuses a framework that resolves elsewhere; every existing self-test case stays green.
Commit as listed in Execution units.
</action>
<verify>
<automated>bash scripts/check-phase35.sh --self-test 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a planted case reported as undetected</fails_when>
<automated>bash scripts/check-phase35.sh --consumers 2>&1 | tail -6; git -C ../sm-user-plugin status --porcelain; git -C ../sm-paymentgateway-plugin status --porcelain</automated>
<fails_when>a "refuse:" or "FAIL" line, no "phase35 consumers passed" line, or any porcelain output</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "modfile" scripts/check-phase35.sh` prints at least two lines
- `grep -n "status --porcelain" scripts/check-phase35.sh` prints at least one line
</acceptance_criteria>
<done>The gate proves the core plugins still send their mail against this checkout, read-only, even though their go.sum does not yet know go-premailer.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: postcard unit tests for locale resolution, fallback rows, built-in layouts, partials and CSS inlining</name>
<files>modules/postcard/locale_test.go, modules/postcard/locale_postgres_test.go, modules/postcard/layouts_test.go, modules/postcard/inline_test.go, scripts/check-phase35.sh</files>
<behavior>
- TestTemplateBase: welcome-en with locales en, pl gives welcome; welcome-pt-BR with pt-BR gives welcome; cancel-notice (not a locale) gives itself; a name without "::" gives itself
- TestTemplateFor: an own file returns itself; welcome-de (no file) returns the welcome file; welcome-pt-BR resolves per the shipped tag rule; order-paid-en picks order-paid over order when both exist; welcome-now, missing-de and a name in another namespace return false
- TestSendLocaleFallback (fake OverrideSource recording the names asked): welcome-de with a de override sends it; without it the welcome override; without both the welcome file; welcome-en (own file) asks only for welcome-en and is unchanged; the unknown-template error text is unchanged
- TestEnsureLocaleRows (Postgres): with locales pl, en, de and default pl over a catalog holding welcome and welcome-en, exactly one row welcome-de is created (none for pl or en) with base_code welcome and the base file's hash; a second run writes nothing (updated_at unchanged); a customized welcome-de keeps its subject when the base file changes while its file_hash follows; SyncIndex writes base_code for welcome-en; ResetOverride of welcome-de restores the base file content and clears the override; every migration rolls back and re-applies
- TestBuiltinLayoutsLogo: default, system and minimal with a Brand logo show an img with that URL and alt = site name (header cell in default and system, above the message in minimal); without a logo none shows it; without logo and with a name the default and system headers show the name; with neither, no header row
- TestHeaderFooterPartials: header with logo, with name only, with url (link wraps the content); footer holds © plus the current year and the name, or only the year; their text forms
- TestButtonPartial: class button button-primary by default, button-positive and button-negative with type, href is the url, the text form is "body <url>", in the default, system and minimal layouts
- TestSiteName: Brand.SiteName wins; empty uses the display name of mail.from; From without a display name or unparsable gives an empty name
- TestInlineCSS: the button link carries the brand primary colour in its style attribute; the DOCTYPE line is kept; a media-query rule from layout CSS stays in a style element; the text part equals the text part of the same message with inlining off; a layout override whose CSS holds a javascript: URL fails the safety check (before or after inlining) and the file version is sent. That override is a raw fixture that never passed save validation: it is injected through the `fakeOverrides` OverrideSource and checked with `assertFileFallback`, as TestFallback's unsafe_override case does, because Editor.Validate would refuse it at save
- TestInlineCSSOptOut: file layout header key, LayoutOverride column and layout draft each leave the button without an inlined style while the style block remains
- TestInlineFailure: an inliner error (through the seam 35-06 shipped, or a package-level variable swapped in the test) sends the un-inlined HTML and logs one warning per key per minute
</behavior>
<read_first>
- .planning/phases/35-mail-templates-and-layouts-editor/35-05-SUMMARY.md and 35-06-SUMMARY.md (exact names, seams, test helpers)
- modules/postcard/templates.go, mailer.go, store.go, inline.go (as shipped)
- modules/postcard/override_test.go and override_smoke_test.go helpers; modules/postcard/brand_test.go (table-test style)
</read_first>
<action>
Per D-21 (unit tests last) for G-35-1 and G-35-8. Docker-free tests (every test above except TestEnsureLocaleRows) never call t.Skip under -short; TestEnsureLocaleRows lives in locale_postgres_test.go, skips under -short like the other Postgres tests and uses `mailPostgres(t)`. Use small fstest.MapFS catalogs; compare HTML with substring and attribute checks, not whole-document equality. Put the year expectation on time.Now().Year() (or the clock seam 35-06 shipped). If a behavior above differs from what 35-05/35-06 recorded as shipped, the SUMMARY wins and the test follows it; a real defect gets its own fix commit first. In the same commit add the ten Docker-free names to GO_TESTS (./modules/postcard:TestTemplateBase … TestInlineFailure) and ./modules/postcard:TestEnsureLocaleRows to DOCKER_TESTS.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test -short ./modules/postcard -count=1 -run '^(TestTemplateBase|TestTemplateFor|TestSendLocaleFallback|TestBuiltinLayoutsLogo|TestHeaderFooterPartials|TestButtonPartial|TestSiteName|TestInlineCSS|TestInlineCSSOptOut|TestInlineFailure)$' -v 2>&1 | grep -E '^(--- |FAIL|ok|PASS)' | tail -20</automated>
<fails_when>a "FAIL" or "--- SKIP" line, or fewer than ten "--- PASS" lines</fails_when>
<automated>go test ./modules/postcard -count=1 -run '^TestEnsureLocaleRows$' -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -5 && go vet ./... && go test -short ./... && bash scripts/check-phase35.sh --go 2>&1 | tail -4</automated>
<fails_when>non-zero exit, a "FAIL", "refuse:" or "--- SKIP" line, or no "--- PASS: TestEnsureLocaleRows" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -c "^func Test" modules/postcard/locale_test.go modules/postcard/layouts_test.go modules/postcard/inline_test.go modules/postcard/locale_postgres_test.go` totals at least 11
- `grep -n "t.Skip" modules/postcard/locale_test.go modules/postcard/layouts_test.go modules/postcard/inline_test.go` prints nothing
- `grep -n "TestInlineCSSOptOut\|TestEnsureLocaleRows" scripts/check-phase35.sh` prints at least two lines
</acceptance_criteria>
<done>Every postcard behavior of the gap closure is pinned by a named unit test that runs in the fast loop, plus one Postgres test for the fallback rows, all required by the gate.</done>
</task>
<task type="auto" tdd="true">
<name>Task 3: cabana Postgres tests and SPA tests for grouped templates, the site name and the inlining switch; gate --all; validation map</name>
<files>modules/cabana/mail_locale_postgres_test.go, modules/cabana/mail_brand_layout_postgres_test.go, admin/tests/form/LocaleVariantSwitcher.test.ts, admin/tests/form/FormViewMail.test.ts, scripts/check-phase35.sh, .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md, .planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md</files>
<behavior>
- TestMailLocaleGroups: with a fake TranslationWriter (pl, en, de; default pl) the list has one welcome row; customized_locales is empty, then "de", then "Default, de"; badges and the status filter follow any customized / drifted row of the group; GET of the welcome record returns localeVariants Default (current), de, en in that order with translated labels and states; a not-customized de row shows the base row's current subject, body and layout (the base customization when present); PUT on de then Send of welcome-de uses it; the reset action on de returns the default version; a changed base file marks de outdated; the file version partial of de compares with the base file; the info partial of de holds the fallback line; an id outside the catalog is 404; a role with only system.manage_mail_layouts gets 403 on the de id; a newly enabled locale (writer answers fr too) appears in localeVariants on the next GET without a restart; the locale-set change re-syncs the list
- TestMailBrandSiteName: saving site_name persists it trimmed; more than 255 characters is a 422 on site_name; preview mode branding shows the name in the header; with no logo and no name the preview has no header row
- TestMailLayoutInlineOptOut: saving the switch on a file layout makes its next send keep the button without an inlined style; reset restores the file value; a custom layout created with the switch off inlines
- LocaleVariantSwitcher.test.ts: one option per variant with "Label — states" text, the current one selected, change pushes the sibling id, a rejected navigation restores the selection, the select has an accessible label
- FormViewMail.test.ts: FormView renders the switcher only when meta.localeVariants has two or more entries; with unsaved edits switching asks the existing confirm and stays on cancel
</behavior>
<read_first>
- .planning/phases/35-mail-templates-and-layouts-editor/35-05-SUMMARY.md and 35-06-SUMMARY.md
- modules/cabana/mail_screens_smoke_test.go (env, fixture, fake TranslationWriter, request helpers) and modules/cabana/mail_lifecycle_postgres_test.go (style of 35-04's Postgres tests)
- admin/tests/form/FormViewMail.test.ts, admin/tests/form/LocaleVariantSwitcher.test.ts (35-05 smoke), admin/src/components/form/LocaleVariantSwitcher.vue
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
</read_first>
<action>
Per D-21 for G-35-1 and G-35-8:
- The two Go files are Postgres tests in package cabana_test that skip under -short like the existing mail Postgres tests and reuse newMailScreensEnvWith; build a second process over a changed MapFS with `keep: true` for the drift case, as the drift subtest does. Add ./modules/cabana:TestMailLocaleGroups, TestMailBrandSiteName and TestMailLayoutInlineOptOut to DOCKER_TESTS in the same commit.
- Extend the 35-05 smoke vitest file rather than duplicating it; add tests/form/LocaleVariantSwitcher.test.ts to ADMIN_FILES in the admin test commit. Admin source is not changed by this task; a defect gets its own fix commit (and, if admin source changed, the dist rebuild commit and scripts/check-admin-dist.sh per CLAUDE.md).
- Run `bash scripts/check-phase35.sh --all` (Docker host; PHASE35_ALLOW_NO_DOCKER only when no daemon answers, which must then be stated in the SUMMARY).
- Planning-docs commit:
- 35-VALIDATION.md rows for G-35-1 (locale grouping: postcard unit + Postgres, cabana Postgres, SPA) and G-35-8 (layouts, partials, inlining, site name, consumers with the scratch modfile).
- In 35-VALIDATION.md, mark the D-05 row and the "default layout output unchanged" byte-identity row as superseded by the decision notes of 35-05 and 35-06.
- Record G-35-8 as framework-closed with its plugin part deferred: the plugin templates' CTA through the button partial, the replaced user/paymentgateway layouts and the plugins' framework bump.
- Manual-Only rows:
- Re-run UAT test 1 on sm-demo-app.
- Re-run UAT test 8 on sm-demo-app, scoped to the built-in layouts. First reset the UAT overrides of golem15.user::mail.activate and golem15.user::mail.layouts.user. Save Branding with a logo and a Site name. Then preview a template switched to the default layout, and to the system layout, with a body override that calls the button partial. Expect the logo header (or the name), the white card, the styled button and the footer.
- A real-inbox check of inlined mail.
- A "deferred follow-up check" row: the activate CTA renders as a button and the user/paymentgateway layouts look finished, checked after the plugin follow-up ships.
- 35-UAT.md: append to the G-35-8 entry under Gaps, without changing `status`, the test results or the Summary counts (those belong to /msd-verify-work):
- a `closure_note` line: framework part closed by 35-05..35-07 (built-in layouts, logo, site name, button partial support, CSS inlining); plugin part deferred to the follow-up after the framework tag;
- a `rerun_scope` line: the scoped test 8 re-run above, plus the deferred plugin check.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/cabana -count=1 -run '^(TestMailLocaleGroups|TestMailBrandSiteName|TestMailLayoutInlineOptOut)$' -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -8</automated>
<fails_when>a "FAIL" or "--- SKIP" line, or fewer than three "--- PASS" lines</fails_when>
<automated>npm --prefix admin run test -- tests/form/LocaleVariantSwitcher.test.ts tests/form/FormViewMail.test.ts 2>&1 | tail -8 && npm --prefix admin run typecheck && go vet ./... && go test -short ./...</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>bash scripts/check-phase35.sh --all 2>&1 | tail -15; git -C ../sm-user-plugin status --porcelain; git -C ../sm-paymentgateway-plugin status --porcelain</automated>
<fails_when>a "refuse:" line, no "Phase 35 gate passed" line, or any porcelain output</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "^func TestMailLocaleGroups\|^func TestMailBrandSiteName\|^func TestMailLayoutInlineOptOut" modules/cabana/*_test.go` prints three lines
- `grep -c "localeVariants" admin/tests/form/FormViewMail.test.ts` prints a number above 0
- `grep -n "TestMailLocaleGroups\|LocaleVariantSwitcher.test.ts" scripts/check-phase35.sh` prints at least two lines
- `grep -n "G-35-1\|G-35-8" .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md` prints at least two lines
- `grep -n "closure_note\|rerun_scope" .planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md` prints at least two lines, and `grep -n "^status: diagnosed" .planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md` still prints one line
- `grep -in "deferred" .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md` prints at least one line naming the plugin follow-up check
</acceptance_criteria>
<done>The admin side of both gaps is pinned by named tests, one command proves the whole gap closure plus the unchanged core plugins, and the validation map records how.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| gate script → sibling repositories | the consumers stage builds and tests code in repositories this phase must not change |
| tests → Docker | Postgres tests start containers on the local daemon |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-35-39 | Tampering | consumers stage with a new framework dependency | medium | mitigate | scratch -modfile copies of go.mod/go.sum, a workspace_check that the framework resolves to this checkout, and a refusal when either sibling's git status is not clean (self-test planted cases) |
| T-35-40 | Repudiation | skipped or missing tests passing the gate | medium | mitigate | every new test is required by name; detect_go refuses skips, zero matches and missing names (existing rules) |
| T-35-SC | Tampering | npm/pip/cargo installs | high | accept | this plan installs no package |
</threat_model>
<verification>
- `go vet ./... && go test ./...` green; `npm --prefix admin run test`, `test:browser` and `typecheck` green.
- `bash scripts/check-phase35.sh --all` passes; sibling working trees unchanged.
- 35-VALIDATION.md maps both gaps.
</verification>
<success_criteria>
- Named unit tests pin G-35-1 and G-35-8 behaviour in postcard, cabana and the SPA.
- The phase gate requires them and stays read-only against the core plugins with the new dependency.
- G-35-8 is recorded as framework-closed with the plugin part deferred (35-VALIDATION.md and the 35-UAT.md closure note).
- Ready for `/msd-verify-work 35`: re-run UAT test 1 in full; re-run test 8 scoped to the built-in layouts (default and system, with logo, Site name and the button partial in a body override) after resetting the two UAT overrides; the plugin CTA and plugin layouts stay a deferred follow-up check. Nothing pushed or tagged.
</success_criteria>
<output>
Create `.planning/phases/35-mail-templates-and-layouts-editor/35-07-SUMMARY.md` when done, with the gate output summary, the list of required test names and any fix commits recorded as deviations.
</output>
## Follow-ups outside this phase (not planned here)
- Plugin follow-up after the framework tag (sm-user-plugin, sm-paymentgateway-plugin): framework requirement bump with `go mod tidy`, button partial in their templates, full layouts keeping their names, per-locale template names; once their go.sum carries go-premailer, the scratch modfile in the consumers stage is a no-op and can stay.
</content>
</invoke>

View File

@@ -0,0 +1,265 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 07
subsystem: testing
tags: [postcard, cabana, admin-spa, mail-templates, locales, css-inlining, go-premailer, gate, gap-closure]
status: complete
requires:
- phase: 35-05
provides: TemplateBase, Catalog.TemplateFor, EnsureLocaleRows, migration 202611130001, RecordMeta.LocaleVariants, LocaleVariantSwitcher.vue
- phase: 35-06
provides: finished built-in layouts, header/footer partials, Brand.SiteName, CSS inlining with disable_auto_inline_css, the mailer.inline seam, migrations 202611130002-3
provides:
- "check-phase35.sh consumers stage: read-only scratch -modfile runs (GOWORK=off, GOPROXY=off, sibling go.sum merged with the framework's), dirty-sibling refusal before and after, two new self-test planted cases"
- "postcard unit tests: TestTemplateBase, TestTemplateFor, TestSendLocaleFallback, TestBuiltinLayoutsLogo, TestHeaderFooterPartials, TestButtonPartial, TestSiteName, TestInlineCSS, TestInlineCSSOptOut, TestInlineFailure; Postgres: TestEnsureLocaleRows"
- "cabana Postgres tests: TestMailLocaleGroups, TestMailBrandSiteName, TestMailLayoutInlineOptOut"
- "SPA tests: LocaleVariantSwitcher.test.ts extended (9 cases), FormViewMail.test.ts (one-variant case, unsaved-changes confirm on switching)"
- "35-VALIDATION.md G-35-1/G-35-8 rows, superseded D-05 and byte-identity rows, manual and deferred checks; 35-UAT.md G-35-8 closure_note and rerun_scope"
affects: [35 verify-work, UAT test 1 and 8 re-runs, sm-user-plugin follow-up, sm-paymentgateway-plugin follow-up]
actuals:
tokens: 21300
tasks: 3
commits: 5
plan_head_before: 0e97113a4f4d513a7d3fdbab28cf7687112e2f6c
plan_head_after: a3ce097455c244bc2e6c2fa886239e84547494f0
tech-stack:
added: []
patterns:
- "Gate consumers stage: scratch -modfile copy of a sibling's go.mod with its go.sum merged with the framework's, GOWORK=off and GOPROXY=off, git status --porcelain checked before and after"
- "Inlined-HTML assertions by tag and attribute (htmlTags/withClass helpers in layouts_test.go), never whole-markup equality"
- "Recording OverrideSource (recordingOverrides) to pin the order a send asks for overrides"
key-files:
created:
- modules/postcard/locale_test.go
- modules/postcard/locale_postgres_test.go
- modules/postcard/layouts_test.go
- modules/postcard/inline_test.go
- modules/cabana/mail_locale_postgres_test.go
- modules/cabana/mail_brand_layout_postgres_test.go
modified:
- scripts/check-phase35.sh
- admin/tests/form/LocaleVariantSwitcher.test.ts
- admin/tests/form/FormViewMail.test.ts
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md
key-decisions:
- "The consumers stage merges the framework's go.sum into each sibling's scratch go.sum and runs with GOPROXY=off, so go-premailer resolves from verified hashes and the module cache without network or writes to the sibling"
- "The dirty-sibling check runs before and after the consumer runs; a sibling with uncommitted changes is refused up front instead of after the tests"
- "G-35-8 is recorded as framework-closed with the plugin part deferred; the UAT test 8 re-run is scoped to the built-in layouts"
- "The unsafe Branding site name (URL scheme) stays an open item: TestMailBrandSiteName pins the current behaviour (saved as typed, preview refused) without a production change"
patterns-established:
- "Each gap-closure test name is added to the gate's required arrays in the same commit as the test"
requirements-completed: [G-35-1, G-35-8, D-21]
coverage:
- id: D1
description: "Phase gate stays read-only against the core plugins with the new go-premailer requirement: scratch modfiles, framework resolves to this checkout, dirty-tree refusal, planted self-test cases"
requirement: D-21
verification:
- kind: other
ref: "bash scripts/check-phase35.sh --self-test (dirty-sibling, workspace-modfile)"
status: pass
- kind: other
ref: "bash scripts/check-phase35.sh --consumers; git status --porcelain of sm-user-plugin and sm-paymentgateway-plugin empty"
status: pass
human_judgment: false
- id: D2
description: "Locale resolution and fallback rows in postcard: TemplateBase/TemplateFor rules, send order own customization > base customization > base file, EnsureLocaleRows, base_code, reset of a fallback code, migrations roll back"
requirement: G-35-1
verification:
- kind: unit
ref: "modules/postcard/locale_test.go#TestTemplateBase, TestTemplateFor, TestSendLocaleFallback"
status: pass
- kind: integration
ref: "modules/postcard/locale_postgres_test.go#TestEnsureLocaleRows"
status: pass
human_judgment: false
- id: D3
description: "Grouped mail templates in the admin API: one row per template, customized locales, grouped states and filter, localeVariants, fallback row default version, save/send/reset/drift, file version against the base, 404 outside the group, permission split, locales enabled at run time"
requirement: G-35-1
verification:
- kind: integration
ref: "modules/cabana/mail_locale_postgres_test.go#TestMailLocaleGroups"
status: pass
human_judgment: false
- id: D4
description: "Locale switcher in the SPA: options, current, navigation, restored selection; FormView shows it with two or more variants and asks the unsaved-changes confirm"
requirement: G-35-1
verification:
- kind: unit
ref: "admin/tests/form/LocaleVariantSwitcher.test.ts"
status: pass
- kind: unit
ref: "admin/tests/form/FormViewMail.test.ts#asks the unsaved-changes confirm before switching locale and stays on cancel"
status: pass
human_judgment: false
- id: D5
description: "Built-in layouts: logo img with alt = site name in default/system headers and above the message in minimal, site name or nothing without a logo, header/footer partials, button partial in every built-in layout, site name with the mail.from fallback"
requirement: G-35-8
verification:
- kind: unit
ref: "modules/postcard/layouts_test.go#TestBuiltinLayoutsLogo, TestHeaderFooterPartials, TestButtonPartial, TestSiteName"
status: pass
human_judgment: false
- id: D6
description: "CSS inlining: brand colour on the button, DOCTYPE kept, media query in a style block, text part unchanged, safety check, per-layout opt-out, inliner failure fallback with rate-limited warning"
requirement: G-35-8
verification:
- kind: unit
ref: "modules/postcard/inline_test.go#TestInlineCSS, TestInlineCSSOptOut, TestInlineFailure"
status: pass
human_judgment: false
- id: D7
description: "Admin side of G-35-8: Branding site name (trimmed, max 255, preview and send header, no header row without name or logo) and the layout form's inlining switch (file layout, reset, custom layout)"
requirement: G-35-8
verification:
- kind: integration
ref: "modules/cabana/mail_brand_layout_postgres_test.go#TestMailBrandSiteName, TestMailLayoutInlineOptOut"
status: pass
human_judgment: false
- id: D8
description: "Whole gap closure proven by one command"
requirement: D-21
verification:
- kind: other
ref: "bash scripts/check-phase35.sh --all (Phase 35 gate passed)"
status: pass
human_judgment: false
- id: D9
description: "UAT test 1 re-run and UAT test 8 re-run scoped to the built-in layouts on sm-demo-app; real-inbox check of inlined mail; deferred plugin follow-up check"
verification: []
human_judgment: true
rationale: "Visual placement of the switcher and rendering of the layouts in the admin preview and real mail clients need a human (35-VALIDATION.md Manual-Only rows)"
duration: 49min
completed: 2026-11-13
---
# Phase 35 Plan 07: Gap-closure tests for G-35-1 and G-35-8 Summary
**Named unit, Postgres and SPA tests pin the mail template locale groups (G-35-1) and the finished built-in layouts with CSS inlining (G-35-8). The phase gate requires every one of them by name and runs the core plugins read-only through scratch `-modfile` copies, offline. `--all` passes.**
## Performance
- **Duration:** 49 min
- **Started:** 2026-11-13T20:20:50Z
- **Completed:** 2026-11-13T21:09:57Z
- **Tasks:** 3
- **Files modified:** 11 (6 created)
## Accomplishments
- `scripts/check-phase35.sh --consumers` copies each sibling's go.mod into a scratch directory, with a go.sum that merges the sibling's and the framework's. It runs `workspace_check`, `go vet` and the named mail tests with `GOWORK=off GOPROXY=off -mod=mod -modfile=<scratch>/go.mod`. A sibling whose `git status --porcelain` prints anything before or after the runs is refused. The self-test plants a dirty repository and a consumer whose scratch modfile resolves the framework elsewhere; the second case is refused only because the modfile is read.
- postcard: ten Docker-free tests and one Postgres test cover locale resolution, the order overrides are asked for, fallback rows, the logo, header and footer, the button partial, the site name, inlining, the opt-out and the inliner-failure fallback.
- cabana: three Postgres tests cover the grouped templates screen, the Branding site name and the layout inlining switch.
- SPA: the switcher test now has 9 cases, and FormViewMail gains the one-variant case and the unsaved-changes confirm on switching locale.
- 35-VALIDATION.md and 35-UAT.md record G-35-8 as framework-closed with the plugin part deferred, and scope the UAT test 8 re-run.
## Required test names added to the gate
- **GO_TESTS (Docker-free, never skip under -short):** `./modules/postcard:` TestTemplateBase, TestTemplateFor, TestSendLocaleFallback, TestBuiltinLayoutsLogo, TestHeaderFooterPartials, TestButtonPartial, TestSiteName, TestInlineCSS, TestInlineCSSOptOut, TestInlineFailure
- **DOCKER_TESTS:** `./modules/postcard:TestEnsureLocaleRows`, `./modules/cabana:` TestMailLocaleGroups, TestMailBrandSiteName, TestMailLayoutInlineOptOut
- **ADMIN_FILES:** `tests/form/LocaleVariantSwitcher.test.ts` (FormViewMail.test.ts was already required)
## Gate output
The fourth `bash scripts/check-phase35.sh --all` run passed: PASS self-test, go, consumers, admin (vitest 1679 passed, browser 13 passed, typecheck, openapi, dist), docs, marker, additive (8 packages against v0.6.3), docker (`go test ./...` plus the named Postgres tests). It printed "Phase 35 gate passed", and both sibling trees stayed clean. Docker answered directly, so PHASE35_ALLOW_NO_DOCKER was not used.
The earlier runs each failed once on a test this plan does not touch (see Issues Encountered).
## Task Commits
1. **Task 1: read-only consumers with a scratch modfile (tracer)** - `ae13e4dd` (test)
2. **Task 2: postcard unit tests** - `a0dde086` (test)
3. **Task 3: cabana Postgres tests** - `eed91c82` (test); **SPA tests** - `a9381165` (test); **validation map** - `a3ce0974` (docs)
## Files Created/Modified
- `scripts/check-phase35.sh` - the consumers stage (scratch modfile, clean check), the new self-test cases and the required names.
- `modules/postcard/locale_test.go` - TemplateBase, TemplateFor and the send order through a recording OverrideSource.
- `modules/postcard/locale_postgres_test.go` - EnsureLocaleRows, SyncIndex base_code, reset of a fallback code and the migration rollback.
- `modules/postcard/layouts_test.go` - the logo, header and footer, the button partial and the site name, with the tag and attribute helpers.
- `modules/postcard/inline_test.go` - inlining, the opt-out (file key, column, draft) and the inliner failure.
- `modules/cabana/mail_locale_postgres_test.go` - TestMailLocaleGroups, with a mutable TranslationWriter.
- `modules/cabana/mail_brand_layout_postgres_test.go` - TestMailBrandSiteName and TestMailLayoutInlineOptOut.
- `admin/tests/form/LocaleVariantSwitcher.test.ts` and `admin/tests/form/FormViewMail.test.ts` - the switcher cases and the FormView confirm.
- `35-VALIDATION.md` and `35-UAT.md` - the planning docs.
## Decisions Made
- The scratch go.sum merges the framework's go.sum, and the consumer runs use `GOPROXY=off`. This keeps the gate offline: a missing module fails loudly instead of being downloaded.
- The sibling clean check also runs before the consumer runs. A sibling another session is editing is refused up front, so the gate never tests foreign work in progress.
- Tests that assert on delivered HTML read tags by attribute. Inlining re-serialises the markup (attribute order, added style attributes), so whole-markup comparison would be brittle.
## Deviations from Plan
### Auto-fixed Issues
None. No test exposed a production defect, and no production code changed.
### Notes
**1. [Test scope] TestEnsureLocaleRows checks `bases` with a template name that is not in the catalog.**
- The plan does not cover `bases`. I first tried a file-backed locale variant as the base, but `TemplateBase` with a locale list that leaves out `en` treats `welcome-en` as a base of its own, so that check would have been misleading. Passing a name that is not in the catalog shows plainly that `bases` limits the run.
**2. [Scope] Unsafe site name documented, not fixed.**
- `TestMailBrandSiteName/unsafe_name_current_behaviour` pins the current behaviour: a name holding `javascript:` is saved, and the Branding preview refuses it with 422. The save-time check stays an open item, as the orchestrator directed.
**3. [Verification] Mutation checks stand in for RED.**
- Each new postcard test file was run against temporarily broken assets or code: the header row removed, the minimal alt changed, the button type ignored, the header span removed, the opt-out ignored, and the validation of the inlined output skipped. The tests failed every time, and each file was restored with `git checkout -- <file>`.
---
**Total deviations:** 0 auto-fixed; 3 notes (test scope, documented open item, verification method).
**Impact on plan:** none. The plan's files and commits are as written, and nothing outside it changed.
## TDD Gate Compliance
Tasks 2 and 3 carry `tdd="true"`, but they test behaviour 35-05 and 35-06 already shipped. Each new test therefore passed on its first run (an "unexpected GREEN" that is expected here), and there is no separate `test(...)` RED commit followed by a `feat(...)` commit. Mutation runs, which break the shipped asset or code and confirm the test fails, show the tests are not vacuous (Note 3). CLAUDE.md's green-at-every-commit rule also rules out failing commits.
## Issues Encountered
- **Flaky, unrelated: `modules/surf` TestStreamingRoute.** Its access-log assertion failed once under the load of the full `go test ./...` in the docker stage. It passes 5 times in a row in isolation, and on the standalone docker stage and the final `--all` run. It dates from 19.7-05, and no surf file changed in this phase.
- **Flaky, unrelated: admin `test:browser` code-editor suites.** Twice in `--all`, `codeeditor.test.ts` and `codeeditor-smoke.test.ts` failed to import ("Failed to fetch dynamically imported module", no assertion failure). They pass when run alone, after `npm run test`, through `--prefix` from the repository root, and in the admin stage alone and the final `--all` runs. I could not reproduce it on demand.
- Both flaky tests are listed here rather than in `deferred-items.md`, because another session holds uncommitted edits in that file.
- `modules/postcard/store_postgres_test.go` already had a gofmt difference before this plan; the new files are gofmt-clean.
## Open Items
- **The Branding site name is not checked for a URL scheme at save time** (35-06 threat flag). A name holding `javascript:`, `vbscript:` or `data:` is saved as typed, and the preview refuses it (pinned by a test). From `mailer.render`, which applies the Branding to the file version too, every send in the built-in layouts would then fail until the name is changed; no test exercises that send path. A save-time check (cabana validation, or a postcard `Editor.Validate` brand rule) is a follow-up outside this plan.
- **Plugin follow-up after the framework tag (G-35-8 plugin part):** sm-user-plugin and sm-paymentgateway-plugin need the framework bump with `go mod tidy`, the button partial in their templates and finished layouts. The deferred follow-up check is in 35-VALIDATION.md.
## Known Stubs
None.
## Threat Flags
None. These are test and gate changes only. T-35-39 is mitigated: scratch modfiles, `workspace_check` under the modfile, and the dirty-tree refusal, with planted self-test cases. T-35-40 is mitigated: every new name is required, and `detect_go` refuses skips, zero matches and missing names.
## User Setup Required
None.
## Next Phase Readiness
- Ready for `/msd-verify-work 35`: re-run UAT test 1 in full. Re-run test 8 scoped to the built-in layouts, after resetting the UAT overrides of `golem15.user::mail.activate` and `golem15.user::mail.layouts.user`. The plugin CTA and the plugin layouts stay a deferred follow-up check.
- Nothing was pushed or tagged. No sibling repository changed.
---
*Phase: 35-mail-templates-and-layouts-editor*
*Completed: 2026-11-13*
## Self-Check: PASSED
- Created files exist: the 4 postcard test files, the 2 cabana test files and this SUMMARY.
- Commits exist: ae13e4dd, a0dde086, eed91c82, a9381165, a3ce0974.
- Acceptance criteria re-run: `modfile` 21 lines and `status --porcelain` 5 lines in the gate; 11 `func Test` across the postcard files; no `t.Skip` in the Docker-free files; the required names are present in the gate; the 3 cabana test functions exist; `localeVariants` appears 6 times in FormViewMail.test.ts; the G-35-1 and G-35-8 rows, closure_note, rerun_scope and the deferred follow-up row are present; `status: diagnosed` is unchanged in 35-UAT.md.
- Plan verification: `go vet ./...`, `go test -short ./...`, the full `go test ./...` (docker stage), the admin test, test:browser and typecheck all pass, and `bash scripts/check-phase35.sh --all` printed "Phase 35 gate passed"; both sibling trees are clean.

View File

@@ -0,0 +1,431 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 08
type: execute
wave: 8
depends_on: ["35-06", "35-07"]
gap_closure: true
gap_ids: [CR-01]
files_modified:
- .planning/notes/2026-11-14-mail-url-scheme-check.md
- modules/postcard/safety.go
- 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/postcard/safety_smoke_test.go
- modules/postcard/editor_smoke_test.go
- modules/postcard/override_test.go
- modules/postcard/partials_smoke_test.go
- modules/postcard/override_smoke_test.go
- modules/postcard/layouts_test.go
- modules/postcard/inline_test.go
- modules/postcard/README.md
- modules/cabana/mail_admin.go
- modules/cabana/mail_brand_layout_postgres_test.go
- modules/cabana/README.md
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- docs/services/mail.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md
autonomous: true
requirements: [CR-01, WR-01, WR-05, D-10, D-13, D-14]
estimate:
tokens: 110000
raw_tokens: 110000
tasks: 3
confidence: low
must_haves:
truths:
- "Mail that already works keeps working: an application that sends mail today keeps sending it after upgrading, and no admin-saved Branding value can stop mail on the built-in layouts (CR-01; roadmap goal clause; 35-06 must-have; D-14 'a failing override never stops mail')"
- "A send on the default layout and on the system layout succeeds with mail.from \"Metadata: Weekly\" <x@example.com> and with Branding Site name 'Big Data: Summit', on the file-version path and on the override path, and the name shows in the header and the footer (CR-01)"
- "A site name that would fail the safety check (javascript:alert(1), javascript: Acme, an event-handler-shaped text, or a mail.from display name holding one) is left out of the header and footer at render time with one rate-limited warning naming its source, never its value, and the send succeeds on the override path, the file-version path, the override-failure fallback and in the editor (D-14)"
- "Saving such a name on the Branding form is a 422 on site_name with the translated en/pl message backend::lang.mail.brand.site_name_unsafe; saving a template or a layout while an unsafe name is stored is not refused (D-10, D-13)"
- "The URL-scheme check of rendered HTML looks only at URL-bearing attribute values, style attributes, style elements, comments and meta content, after decoding character references: body text such as 'metadata:' or 'Big Data: Summit' passes, while href=\"javascript&#58;...\" is refused whether or not the layout opts out of inlining (WR-05, D-13)"
- "An inlined result that fails the safety check never stops the message: the already-checked un-inlined HTML is sent with its style block and a rate-limited warning, as docs/services/mail.md promises (WR-05, D-14)"
- "The footer of the default and system layouts prints the site name literally and HTML-escaped, as the header does: *Acme*, Acme <Studio> and [x](url) are not turned into emphasis, an HTML comment or a link (WR-01)"
- "sm-user-plugin and sm-paymentgateway-plugin mail tests still pass against this checkout, read-only (check-phase35.sh --consumers)"
prohibitions:
- statement: "No file in sm-user-plugin, sm-paymentgateway-plugin or any other sibling repository is changed."
status: unresolved
verification: judgment
- statement: "Nothing is pushed or tagged (tag only at phase completion, on the default branch, after Jakub's go-ahead)."
status: unresolved
verification: judgment
- statement: "No breaking change to the mail API the core plugins use: modules/pact is untouched, postcard.Mailer, Catalog.Register and pact.HasMailTemplates keep their signatures, and every postcard and cabana API change is additive (check-phase35.sh --additive)."
status: unresolved
verification: automated
- statement: "No new dependency: go.mod and go.sum are unchanged; the tokenizer is golang.org/x/net/html, already a direct requirement, and the escaping is the standard library html package."
status: unresolved
verification: automated
- statement: "admin/ and modules/boardwalk/dist are unchanged; the 422 on site_name surfaces through the existing field-error rendering."
status: unresolved
verification: automated
- statement: "Framework code, docs and tests name no consuming application."
status: unresolved
verification: judgment
artifacts:
- path: "modules/postcard/safety.go"
provides: "attribute-scoped, entity-decoding URL-scheme check and the exported postcard.UnsafeText"
contains: "func UnsafeText"
- path: "modules/postcard/safety_smoke_test.go"
provides: "smoke test for the gap closure (prose names, encoded schemes, unsafe names, literal footer, unsafe inlined output)"
contains: "func TestMailSafetySmoke"
- path: ".planning/notes/2026-11-14-mail-url-scheme-check.md"
provides: "decision note: anchored and decoded scheme check, site-name rule, post-inline behaviour, literal footer"
contains: "WR-05"
- path: "modules/postcard/assets/partials/footer.htm"
provides: "footer partial with a plain-text argument"
contains: ".text"
key_links:
- from: "modules/postcard/templates.go"
to: "modules/postcard/safety.go"
via: "validateHTML runs the tokenizer walk instead of the whole-document scheme regex"
pattern: "unsafeMarkup"
- from: "modules/postcard/mailer.go"
to: "modules/postcard/safety.go"
via: "options and the Branding preview take the site name through layoutSiteName, which drops a name UnsafeText refuses"
pattern: "layoutSiteName"
- from: "modules/cabana/mail_admin.go"
to: "modules/postcard/safety.go"
via: "MailBrandSetting.BeforeValidate refuses a site name postcard.UnsafeText refuses"
pattern: "postcard.UnsafeText"
- from: "modules/postcard/assets/default.htm"
to: "modules/postcard/assets/partials/footer.htm"
via: "the copyright line is passed as the footer's text argument"
pattern: "partial \"footer\" \"text\""
---
## Phase Goal
ROADMAP Goal (not in user-story format; no story is invented): administrators edit every mail the application sends from the admin panel, and postcard renders the override or the file "so mail that already works keeps working". This gap-closure plan fixes the one goal-blocking gap of the 2026-11-13 re-verification (35-VERIFICATION.md `gaps:`; 35-REVIEW.md CR-01), with WR-01 and WR-05 bundled as the user confirmed.
Gap truth (35-VERIFICATION.md): "Mail that already works keeps working: an application that sends mail today keeps sending it after upgrading, and no admin-saved Branding value can stop mail on the built-in layouts."
Source: 35-VERIFICATION.md (gap, CR-01 regression), 35-REVIEW.md (CR-01, WR-01, WR-05), user decisions of 2026-11-14 (two plans: this fix, then 35-09 with the regression and unit tests). Spec-less probe fallback: skipped, the phase has no requirement IDs to probe (visible skip).
<objective>
- Anchor postcard's URL-scheme check to URL-bearing attribute values, style attributes, style elements, comments and meta content, read through golang.org/x/net/html's tokenizer so attribute values are entity-decoded (CR-01 root cause, WR-05).
- Never let a site name fail a send: an unsafe Branding Site name or mail.from display name is left out of the layouts with a rate-limited warning, on every render path (CR-01, D-14).
- Refuse an unsafe Site name on the Branding form with a 422 on site_name and a translated en/pl message, through an exported postcard helper (CR-01, D-10, D-13).
- Keep the docs' promise that the inliner never stops mail: an inlined result that fails the check sends the un-inlined, already-checked HTML (WR-05).
- Print the site name literally in the footer, as in the header (WR-01).
- Record the decisions in a note; update the postcard and cabana READMEs, docs/services/mail.md and the UI-SPEC copy in the same commits as the changes they describe.
Purpose: an application whose sender name or Branding name contains ordinary text such as "Metadata:" or "Big Data:" keeps sending password resets and every other mail on the built-in layouts, and no Branding value an administrator can save stops mail.
Output: commits in this repository only (code and planning docs in separate commits). Nothing in sibling repositories, nothing pushed or tagged.
**Planner decisions recorded here (Claude's discretion within the user's 2026-11-14 decisions):**
- **What the scheme check reads.** Single-URL attributes (`action`, `background`, `cite`, `codebase`, `data`, `dynsrc`, `formaction`, `href`, `icon`, `longdesc`, `lowsrc`, `manifest`, `poster`, `profile`, `src`, `usemap`, `xlink:href`, and SVG animation targets `from`, `to`, `by`) are refused when their decoded value, with every ASCII whitespace and control character removed and lower-cased, starts with `javascript:`, `vbscript:` or `data:`. List-valued attributes (`srcset`, `ping`, `archive`, `values`), `style` attributes, the `content` attribute of `meta` elements, the text of `style` elements and comment data are refused when the existing `dangerousScheme` pattern matches anywhere in them (the conservative rule stays for CSS, where prose does not belong). Text content is not checked for schemes: it is not a URL. Error messages are unchanged.
- **Event handlers.** The raw-markup regexes for script/iframe/object/embed tags and for whitespace-prefixed `on*=` stay as they are. The tokenizer walk additionally refuses any attribute whose name starts with `on`, which closes the `<img src="x"onerror=...>` form the regex misses (planner addition, T-35-47; no legitimate mail markup uses such an attribute).
- **Unsafe site name** (`postcard.UnsafeText`): a text is unsafe when, HTML-escaped as html/template prints text, it fails the rendered-HTML 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 `data:` at a scheme boundary directly followed by a non-space character (a data URL). A scheme boundary is the start of the text or a character that cannot belong to a URL scheme (anything but ASCII letters, digits, `+`, `.` and `-`). So `Big Data: Summit`, `Metadata: Weekly` and `Metadata:Weekly` are safe; `javascript:alert(1)`, `javascript: Acme` and `data:text/html,x` are not.
- **Render-time drop.** An unsafe Branding Site name is treated as empty, so the documented fallback applies (the display name of mail.from, if that one is safe); an unsafe mail.from display name gives no name. One warning per source per minute through the mailer's existing rate-limited `warn`, keyed `site_name:branding` or `site_name:mail.from`, logging the source and never the value. The Branding preview of an unsaved draft drops the name the same way (the save is what refuses it), so the preview shows what would be sent.
- **Post-inline failure** (WR-05 contradiction): the documented behaviour wins. The check now sees decoded attribute values and style element CSS before inlining, regardless of `disable_auto_inline_css`; an inlined result that still fails it is treated like an inliner error: the un-inlined HTML (which passed the check) is sent with its style block and the existing `inline:<layout>` warning. The README sentence that said such a result "fails the render" is corrected; the reviewer's alternative (fail the render, change the docs) is rejected in the note because it stops mail that passed the check.
- **Footer.** The `footer` partial gains a `text` argument printed as plain text (`<p>` through html/template in HTML, verbatim in the text part); `body` stays Markdown for callers that pass Markdown on purpose. The default and system layouts pass the copyright line as `text`. The footer partial shipped in 35-06 and is not in any tag yet (newest tag v0.6.4 predates it), so no released override depends on the old call.
- **Copy (en/pl)** `mail.brand.site_name_unsafe`: "This name cannot be shown in mail. Remove addresses that start with javascript:, vbscript: or data: and text such as onclick=." / "Tej nazwy nie można pokazać w wiadomościach. Usuń adresy zaczynające się od javascript:, vbscript: lub data: oraz tekst w rodzaju onclick=."
- **Assumption delta:** 35-RESEARCH.md Pitfall 8 ("keep the behaviour, it matches sends") and 35-PATTERNS.md "HTML safety gate: reuse them unchanged" are superseded for postcard by the user's 2026-11-14 decision; cabana.RenderMarkdown's own regexes (admin Markdown preview) are out of scope and unchanged.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/35-mail-templates-and-layouts-editor/35-VERIFICATION.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-REVIEW.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-CONTEXT.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-06-SUMMARY.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-07-SUMMARY.md
@CLAUDE.md
<interfaces>
- modules/postcard/templates.go: `dangerousScheme`, `eventHandler`, `rawUnsafeTag` (~44-47); `renderParts` (~629-720: body `validateHTML` ~658, layout HTML `validateHTML` ~701, then `inlineHTML` unless `layout.disableInline` ~704); `inlineHTML` (~731-751: inliner error warns and keeps the HTML; a failing check on the inlined output returns an error today); `validateHTML` (~813-824: raw tags, handlers, then the whole-document scheme regex); `snippetAt` (~828); `unsafeError{msg, snippet}` (~608).
- modules/postcard/partials.go: partial HTML output and the partial `markdown` func output pass `validateHTML` (~122, ~215).
- modules/postcard/editor.go: `renderLayout` checks draft CSS with `closingStyle` then `validateHTML(d.CSS)` (~243-250, error on `content_css`); `renderBrand` sets `opts.siteName = siteName(&brand, e.m.opts.From)` (~316-332); `Editor.render` builds opts with `m.options(ov.Brand)` (~191-209); `draftErrorFor` maps `unsafeError` to rule `unsafe` with its snippet (~394-436).
- modules/postcard/mailer.go: `render` builds `file := m.options(ov.Brand)` and the override render from it, then falls back to `file` (~110-147); `options` sets `siteName: siteName(brand, m.opts.From)` (~154-171); `siteName(brand *Brand, from string) string` (~176-187); `warn(key, msg string, args ...any)` rate-limited per key per minute (~217).
- modules/postcard/assets/default.htm and system.htm build `$copy` from `.year` and `.siteName` and pass it to the `footer` partial in both wrappers (default.htm lines 5 and 34, system.htm lines 9 and 39); assets/partials/footer.htm prints `{{ .body }}` in text and `{{ markdown .body }}` in HTML; partials/header.htm prints the name escaped.
- modules/cabana/mail_admin.go: `MailBrandSetting` (~1749), `Rules` (`site_name: nullable|max:255`, ~1781), `BeforeValidate` (~1805: trims site_name, collects `details[...] = []string{"backend::lang.<key>"}` and returns `&ValidationError{Details: details}`); crud.go `localizeDetails` translates those keys.
- Tests pinned to the old whole-document behaviour (must change with the code): modules/postcard/editor_smoke_test.go validate case "body scheme" (~217, prose `metadata:` expected unsafe); modules/postcard/override_test.go `TestFallback/unsafe_override` (~150-154, prose body); modules/postcard/partials_smoke_test.go `TestMailPartialsSmoke/errors` case `unsafe_html` (~327, prose in a panel body); modules/postcard/override_smoke_test.go `TestMailOverrideSmoke/fallback` case `unsafe` (~434, prose body, Postgres); modules/cabana/mail_brand_layout_postgres_test.go the last `TestMailBrandSiteName` subtest (~93-103, pins an unsafe name as saved and the preview as 422).
- Tests that keep passing and need no change: templates_test.go and mailer_test.go "unsafe vars stay out of HTML" (the dangerous value sits in a Markdown link target, which goldmark drops); inline_test.go `TestInlineCSS/safety_check` (a style-attribute URL in a direct `validateHTML` call, and a style-element URL caught before inlining).
- Test helpers: partials_smoke_test.go `fakeOverrides`, `partialsMailer`, `sendTemplate`, `copyright`; override_test.go `assertFileFallback`, `acmeBlog`, `fileWelcome`; layouts_test.go `brandedSend`, `headerCell`, `footerText`, `logoSpan`; inline_test.go `noInline`, `buttonStyle`, `styleBlock`, `defaultLayoutWithCSS`; editor_smoke_test.go `newEditor`; mailer field `log` (capture warnings) and `inline` (inliner seam). cabana: `newMailScreensEnv`, `env.expect`, `env.expectFieldRefusal(t, status, method, path, token, body, field, want, inMessage)`, `brandPreview`, `headerSpan`, `sendGrace`, `mailBrandPath`, `templateBody`, `env.mailRowID`.
- golang.org/x/net/html (v0.62.0, direct requirement; used by modules/seaglass, modules/tide, modules/cabana): `NewTokenizer(io.Reader)`, `Next()` token types `ErrorToken`, `TextToken`, `StartTagToken`, `EndTagToken`, `SelfClosingTagToken`, `CommentToken`, `DoctypeToken`; `Raw()` (raw bytes of the current token, read before `Token()`); `Token()` returns lower-cased attribute keys and attribute values with character references decoded; style contents arrive as one raw text token.
- Existing decision note format: .planning/notes/2026-11-13-mail-layouts-css-inlining.md; the sanitizer note that scopes bluemonday to stored rich text: .planning/notes/2026-10-11-framework-html-sanitizer-bluemonday.md.
</interfaces>
</context>
## Execution units and resume points
- Other sessions work in this repository. Before each task run `git status --short modules/postcard modules/cabana modules/phrasebook docs .planning/notes .planning/phases/35-mail-templates-and-layouts-editor` and stop if another session holds uncommitted edits in a file this task touches. Never stage `examples/hello/plugins.gen.go`, `.planning/G15OFFICE.md`, `.planning/state.json` or `.planning/phases/35-mail-templates-and-layouts-editor/deferred-items.md` (other sessions' edits).
- Stage by explicit path; code and planning docs in separate commits; no co-author tags. `go vet ./...` and `go test ./...` green at every code commit, including the Docker-backed Postgres tests (run them without `-short`; if the Docker socket is denied, run through `sudo -u golem`).
- TDD tasks: verify RED before GREEN, but land each test with its fix in the listed fix commit (CLAUDE.md forbids failing commits), as 35-06 did.
- Resume check: `git log --format=%s -F --grep='<subject>'`.
| Task | Commit subject | Resume point |
|------|----------------|--------------|
| 1 | `docs(35): decision note for the mail URL scheme check and site name safety` then `fix(postcard): check URL schemes in decoded attribute values, not in text` | TestMailSafetySmoke/prose_site_name and /encoded_scheme pass |
| 2 | `fix(postcard,cabana): unsafe site names never stop a send and are refused at save` then `docs(35): UI-SPEC copy for the unsafe site name refusal` | TestMailBrandSiteName/unsafe_name_refused passes |
| 3 | `fix(postcard): an inlined result that fails the safety check sends the style block` then `fix(postcard): print the site name literally in the built-in layouts' footer` | TestMailSafetySmoke/inline_unsafe_output and /literal_footer pass |
<tasks>
<task type="tracer">
<name>Task 1: End-to-end "an application whose mail.from display name is 'Metadata: Weekly' sends a template on the default and on the system layout" — the send path's scheme check only</name>
<precondition>35-07 is complete: `git merge-base --is-ancestor a3ce0974 HEAD` exits 0</precondition>
<reversibility rating="reversible">Changes what the render-time check accepts and refuses; no schema, no exported API, no stored data; reverting the fix commit restores the old check.</reversibility>
<files>.planning/notes/2026-11-14-mail-url-scheme-check.md, modules/postcard/safety.go, modules/postcard/templates.go, modules/postcard/editor.go, modules/postcard/safety_smoke_test.go, modules/postcard/editor_smoke_test.go, modules/postcard/override_test.go, modules/postcard/partials_smoke_test.go, modules/postcard/override_smoke_test.go, modules/cabana/mail_brand_layout_postgres_test.go, modules/postcard/README.md, docs/services/mail.md</files>
<read_first>
- .planning/phases/35-mail-templates-and-layouts-editor/35-REVIEW.md (CR-01, WR-05) and 35-VERIFICATION.md (`gaps:` block)
- modules/postcard/templates.go (~41-50, ~606-614, ~629-760, ~805-832)
- modules/postcard/partials.go (~108-126, ~206-220)
- modules/postcard/editor.go (~236-273, ~391-436)
- the fixtures listed in interfaces: modules/postcard/editor_smoke_test.go (~180-240), modules/postcard/override_test.go (~140-200), modules/postcard/partials_smoke_test.go (~78-140, ~318-345), modules/postcard/override_smoke_test.go (~420-450), modules/cabana/mail_brand_layout_postgres_test.go (~25-104)
- modules/seaglass/seaglass.go (~140-190, how this repository drives the x/net/html tokenizer)
- .planning/notes/2026-11-13-mail-layouts-css-inlining.md (note format) and .planning/notes/2026-10-11-framework-html-sanitizer-bluemonday.md (scope of the sanitizer decision)
- modules/postcard/README.md (~23-36, ~355-372, ~466-472) and docs/services/mail.md (~11-24, ~150-158)
</read_first>
<action>
Closes the root cause of CR-01 and the decoding half of WR-05; D-13's refusal of javascript:/vbscript:/data: URLs is kept, prose is no longer treated as a URL.
- First a planning-docs commit, alone, with the first subject: `.planning/notes/2026-11-14-mail-url-scheme-check.md` (Status: Accepted; Context: 35-VERIFICATION.md gap and 35-REVIEW.md CR-01, WR-01, WR-05; user decisions of 2026-11-14). Record every decision in this plan's "Planner decisions" list (what the check reads and how values are normalized, the on-attribute rule, the UnsafeText rule, the render-time drop and its warning, the post-inline behaviour, the footer text argument, the copy keys). Record what it supersedes: 35-RESEARCH.md Pitfall 8 "keep the behaviour" and the postcard README sentence saying text such as metadata: is refused at save; D-13 itself stands. Rejected alternatives: keep the whole-document regex and only guard the site name (body text and other configuration text keep stopping sends); a bluemonday-based mail sanitizer (it rewrites instead of refusing and would need a mail allowlist for style elements, tables and layout attributes; the 2026-10-11 note scopes bluemonday to stored rich text, and this check only locates attribute values with x/net/html, already a direct requirement); failing the render when the inlined result fails the check (stops mail that passed the check, contradicts the documented promise and D-14). Residual risk accepted: CSS escape sequences inside CSS are not decoded (mail clients do not run script URLs from CSS).
- New file modules/postcard/safety.go (package postcard), importing golang.org/x/net/html under the alias `xhtml`:
- `urlAttributes` (single-URL attribute names) and `urlListAttributes` (srcset, ping, archive, values), both as listed in the planner decisions.
- `hasDangerousScheme(val string) bool`: removes every ASCII whitespace and control character (U+0000 to U+0020 and U+007F) from the decoded value, lower-cases it, and reports whether it starts with `javascript:`, `vbscript:` or `data:`.
- `unsafeMarkup(doc string) error`: tokenizes doc with `xhtml.NewTokenizer(strings.NewReader(doc))`, keeps each token's byte offset from the length of `Raw()` (read before `Token()`), and stops at the first ErrorToken. For start and self-closing tag tokens it checks every attribute of `Token()` (keys lower-cased, values decoded): a name beginning with `on` gives an `unsafeError` with msg "rendered HTML contains event handlers"; a name in urlAttributes whose value `hasDangerousScheme` gives msg "rendered HTML contains a dangerous URL scheme"; a name in urlListAttributes, a `style` attribute, or the `content` attribute of a `meta` element whose decoded value `dangerousScheme` matches anywhere gives the same scheme msg. It tracks whether it is inside a `style` element and checks those text tokens with `dangerousScheme`; it checks comment token data with `dangerousScheme`; other text is not checked. The snippet is `snippetAt(doc, [start, end])` of the offending token, so `DraftError.Message` shows the raw markup (for example the encoded form). Doc comments say what is read and why text is not.
- templates.go `validateHTML`: keep the `rawUnsafeTag` and `eventHandler` checks on the raw markup unchanged and first, and replace the whole-document `dangerousScheme.FindStringIndex` call with `unsafeMarkup(html)`. `dangerousScheme` keeps its pattern; update its comment and the one on `validateHTML` to say where it now applies. `inlineHTML` is not changed in this task.
- editor.go `renderLayout`: check the draft CSS as the content of a style element (`validateHTML` over the CSS wrapped in an opening and a closing style tag), after the existing `closingStyle` check, so the scheme check still reads it and the error stays on `content_css` (bare CSS text would otherwise no longer be checked).
- Fixtures pinned to the old whole-document behaviour, changed in the same fix commit so `go test ./...` stays green:
- editor_smoke_test.go: the prose body draft ("See the metadata: field.") now validates. Move it into the valid-drafts loop, and replace the "body scheme" row with a "layout scheme" row: a layout draft whose HTML holds an anchor with an `href` of `javascript&#58;alert(1)` gives field `content_html`, rule `unsafe`, and a message holding the encoded href.
- override_test.go `TestFallback/unsafe_override`: replace the prose body with a template override that selects a layout override (same `fakeOverrides`) whose HTML wrapper holds an anchor with that entity-encoded href; `assertFileFallback` still holds.
- partials_smoke_test.go `TestMailPartialsSmoke/errors` case `unsafe_html`: prose in a panel body passes now. Make the partial's own output carry a markup-level dangerous URL (register, for that case, a plugin partial whose HTML holds the entity-encoded href, called from the body) and keep the expected "dangerous".
- override_smoke_test.go `TestMailOverrideSmoke/fallback` case `unsafe`: a template body cannot produce a markup-level URL (goldmark drops raw HTML and dangerous link targets), so use a body whose rendered HTML still fails the unchanged handler check: a sentence with event-handler-shaped text such as " onclick=". Keep the case comment accurate; the file-version and log assertions are unchanged.
- mail_brand_layout_postgres_test.go: delete the 35-07 subtest of TestMailBrandSiteName that pinned an unsafe name as saved and refused by the preview. Its premise (name text failing the scheme check) is gone; Task 2 adds its replacement, `unsafe_name_refused`.
- Smoke test modules/postcard/safety_smoke_test.go, `TestMailSafetySmoke` (Docker-free, no t.Skip, package postcard). Subtests:
- `prose_site_name`: an fstest.MapFS catalog in the acme.blog namespace with one template on layout `default` and one on `system`. Send with Options.From `"Metadata: Weekly" <x@example.com>` and no Branding; then with `fakeOverrides` Brand SiteName "Big Data: Summit"; then with a template override present as well (override path). Every Send returns nil and the HTML holds the name. A body with "See the metadata: field." sends too.
- `encoded_scheme`: a layout override whose HTML holds the entity-encoded javascript: href, with DisableAutoInlineCSS false and then true: the file version is sent both times and the encoded form never reaches the driver.
- Docs in the same fix commit:
- postcard README: the Features "Safety checks" bullet (schemes are checked in URL-bearing attributes, style attributes, style elements, comments and meta content, after decoding character references; tags and event handlers as before, plus any attribute whose name starts with on); the Editing drafts `unsafe` row and the paragraph after it (replace the sentence that says text such as metadata: is refused with: text is not a URL, so prose such as metadata: or Big Data: Summit passes, and an encoded javascript&#58; is decoded and refused); Dependencies, Third-party: golang.org/x/net/html (tokenizing rendered HTML for the safety checks, already a framework dependency).
- docs/services/mail.md: the Sending paragraph about rejected HTML, in the same terms.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test -short ./modules/postcard -count=1 -run '^TestMailSafetySmoke$' -v 2>&1 | grep -E '^\s*(--- FAIL|--- SKIP|--- PASS|FAIL|ok)' | tail -12</automated>
<fails_when>a "FAIL" or "--- SKIP" line, or no "--- PASS: TestMailSafetySmoke/prose_site_name" or "--- PASS: TestMailSafetySmoke/encoded_scheme" line</fails_when>
<automated>go vet ./... && go test -short ./... && go test ./modules/postcard ./modules/cabana -count=1 2>&1 | tail -4 && (cd examples/hello && go test ./... 2>&1 | tail -3)</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>bash scripts/check-phase35.sh --consumers 2>&1 | tail -6; git -C ../sm-user-plugin status --porcelain; git -C ../sm-paymentgateway-plugin status --porcelain</automated>
<fails_when>a "refuse:" or "FAIL" line, no "phase35 consumers passed" line, or any porcelain output</fails_when>
<automated>go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "^func unsafeMarkup\|^func hasDangerousScheme" modules/postcard/safety.go` prints two lines and `grep -n "golang.org/x/net/html" modules/postcard/safety.go` prints one line
- `grep -n "unsafeMarkup(" modules/postcard/templates.go` prints at least one line
- `grep -rhn 'unsafe_name_current_behaviour' modules/cabana | grep -vE '^[0-9]+:\s*//'` prints nothing
- `grep -n "^func TestMailSafetySmoke" modules/postcard/safety_smoke_test.go` prints one line and `grep -n "t.Skip" modules/postcard/safety_smoke_test.go` prints nothing
- `grep -n "x/net/html" modules/postcard/README.md` prints at least one line
- `git log --format=%s -1 -- .planning/notes/2026-11-14-mail-url-scheme-check.md` prints the docs(35) subject, on a commit older than the fix commit (`git log --format=%s -1 -- modules/postcard/safety.go` prints the fix subject)
- `git status --porcelain -- go.mod go.sum` prints nothing and `git log --oneline 0aa38db8..HEAD -- go.mod go.sum modules/pact admin modules/boardwalk/dist` prints nothing
</acceptance_criteria>
<done>A sender name or Branding name with ordinary text such as "Metadata:" or "Big Data:" no longer stops mail on the built-in layouts, while URLs with a javascript:, vbscript: or data: scheme, encoded or not, are still refused in every attribute that carries one.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: An unsafe site name never stops a send and is refused at save — postcard.UnsafeText, the render-time drop, the Branding 422, en/pl copy</name>
<reversibility rating="costly">postcard.UnsafeText becomes exported framework API that other modules and applications may call; the phrase key backend::lang.mail.brand.site_name_unsafe is published copy.</reversibility>
<files>modules/postcard/safety.go, modules/postcard/mailer.go, modules/postcard/editor.go, modules/postcard/safety_smoke_test.go, modules/cabana/mail_admin.go, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, modules/cabana/mail_brand_layout_postgres_test.go, modules/postcard/README.md, modules/cabana/README.md, docs/services/mail.md, .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md</files>
<behavior>
- UnsafeText: "", "Acme", "Big Data: Summit", "Metadata: Weekly", "Metadata:Weekly", "Acme <Studio>", "*Acme*" and "[x](https://example.com)" are safe; "javascript:alert(1)", "javascript: Acme", "JavaScript:x", "Go vbscript:msgbox(1)", "data:text/html,x" and "Shop onclick=x" are unsafe
- Branding SiteName "javascript:alert(1)" with mail.from "Acme <x@example.com>": a send on the default layout succeeds, the header and footer show Acme, neither the HTML nor the text part holds "javascript:", and one warning naming source=branding is logged; a second send within a minute logs no second warning
- Branding SiteName unsafe and the mail.from display name unsafe: the send succeeds with no header row (no logo) and a footer with the year only
- Editor.Validate of a template draft and of a layout draft under a stored unsafe Branding name returns nil; Editor.Preview of a Branding draft with an unsafe name renders without it
- PUT of the Branding settings with site_name "javascript: Acme" is a 422 on site_name with the translated text and stores nothing; "Big Data: Summit" saves and a send on the default layout shows it in the header
</behavior>
<read_first>
- modules/postcard/safety.go (as left by Task 1)
- modules/postcard/mailer.go (~107-222) and modules/postcard/editor.go (~189-210, ~314-332)
- modules/postcard/layouts_test.go `TestSiteName` (~362-393), so its existing cases keep passing
- modules/cabana/mail_admin.go (~1747-1851) and modules/cabana/crud.go (~104-150, localizeDetails)
- modules/phrasebook/backend/lang/en/lang.yaml and pl/lang.yaml (the `mail:` → `brand:` block with site_name and site_name_comment)
- modules/cabana/mail_brand_layout_postgres_test.go (whole file) and modules/cabana/administrators_harness_test.go (~458-482, expectFieldRefusal)
- modules/postcard/README.md Branding section (~257-293) and API reference (~385-436); modules/cabana/README.md Mail screens bullet (Branding part); docs/services/mail.md Branding (~74-89)
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md Branding page table (~421-430), C15 (~872-888) and the state table rows for Branding (~966-967)
</read_first>
<action>
Closes CR-01's "a site name never fails a send" and "save-time refusal" items. D-14 (mail never stops over an override) is extended to the Branding name; D-10's Branding gets a save rule; D-13 save validation is unchanged for templates and layouts.
- safety.go: exported `UnsafeText(s string) bool`. Rule per the planner decisions: unsafe when `validateHTML` fails on the text escaped with the standard library's `html.EscapeString`, or when the unexported regexp `scriptURLText` matches. `scriptURLText` holds javascript: or vbscript: at a scheme boundary, or data: at a scheme boundary directly followed by a non-space character; a boundary is the start of the text or a character other than an ASCII letter, digit, `+`, `.` or `-`. For example `(?i)(?:^|[^a-z0-9+.\-])(?:(?:javascript|vbscript):|data:\S)`. The doc comment says what it is for (text a layout prints, such as the site name), names both rules and gives "Big Data: Summit" as a safe example.
- mailer.go:
- New unexported `siteNameFrom(brand *Brand, from string) (name, skipped string)`. The candidates, in order, are the trimmed Brand.SiteName (when brand is non-nil) and the trimmed display name of from (net/mail.ParseAddress, nothing on an error). It returns the first non-empty candidate UnsafeText accepts, and in skipped the source ("branding" or "mail.from") of the first non-empty candidate it refused.
- `siteName(brand, from)` keeps its signature and returns siteNameFrom's name, so TestSiteName's cases keep passing.
- New method `(*mailer).layoutSiteName(brand *Brand) string` calls siteNameFrom with m.opts.From. When skipped is set it calls `m.warn` with key "site_name:"+skipped, message "postcard: site name left out of the layouts, it fails the mail safety check" and `slog.String("source", skipped)`, never the value.
- `(*mailer).options` uses layoutSiteName. The file version, the override render built from it and the override-failure fallback therefore all carry the same checked name. Update the comments of options and siteName.
- editor.go `renderBrand`: set `opts.siteName` from `e.m.layoutSiteName(&brand)`. The Branding preview of an unsafe draft name then renders without it; the save is what refuses it.
- cabana mail_admin.go `MailBrandSetting.BeforeValidate`: after the trim, when `postcard.UnsafeText(b.SiteName)` is true, set `details["site_name"]` to `backend::lang.mail.brand.site_name_unsafe`, collected with the colour and logo details so one 422 lists them all. Update the doc comment. Rules stay `nullable|max:255`.
- Copy: add `site_name_unsafe` under `mail.brand`, after `site_name_comment`, in modules/phrasebook/backend/lang/en/lang.yaml and pl/lang.yaml, with the en/pl texts from the planner decisions.
- Tests (smoke, in this fix commit):
- TestMailBrandSiteName gains subtest `unsafe_name_refused`. `env.expectFieldRefusal` returns 422 on site_name, containing "cannot be shown in mail", for "javascript: Acme", and the stored row keeps its previous name. `brandPreview` with that name answers 200, and its HTML holds no "javascript:". PUT of "Big Data: Summit" answers 200, and the welcome template, moved to the default layout as in the `send` subtest, shows it in the header span. site_name is cleared at the end.
- TestMailSafetySmoke gains subtest `unsafe_site_name` (the behavior items above for the mailer and the editor, with warnings captured through the mailer's `log` field).
- Docs in the same fix commit:
- postcard README: the Branding section (an unsafe name is left out of the layouts with a warning naming its source, and the mail.from fallback applies); the API reference row for `postcard.UnsafeText`; Dependencies, Standard library: add `html`.
- cabana README: the Branding part of the Mail screens bullet (a name `postcard.UnsafeText` refuses is a 422 on site_name with backend::lang.mail.brand.site_name_unsafe).
- docs/services/mail.md Branding paragraph: which names are refused at save, and that a name stored earlier is left out of mail.
- Then a planning-docs commit for 35-UI-SPEC.md:
- a Branding page table row for the refusal copy (key mail.brand.site_name_unsafe, en, pl);
- a C15 row: Unsafe site name | Branding save | 422, Details.site_name | Field line | mail.brand.site_name_unsafe;
- a state-table row: error | Branding unsafe site name | covered | field line, nothing stored, the preview shows the mail without the name.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test -short ./modules/postcard -count=1 -run '^(TestMailSafetySmoke|TestSiteName)$' -v 2>&1 | grep -E '^\s*(--- FAIL|--- SKIP|--- PASS|FAIL|ok)' | tail -12</automated>
<fails_when>a "FAIL" or "--- SKIP" line, or no "--- PASS: TestMailSafetySmoke/unsafe_site_name" or "--- PASS: TestSiteName" line</fails_when>
<automated>go test ./modules/cabana -count=1 -run '^TestMailBrandSiteName$' -v 2>&1 | grep -E '^\s*(--- FAIL|--- SKIP|--- PASS|FAIL|ok)' | tail -10</automated>
<fails_when>a "FAIL" or "--- SKIP" line, or no "--- PASS: TestMailBrandSiteName/unsafe_name_refused" line</fails_when>
<automated>go vet ./... && go test -short ./... && go test ./modules/postcard ./modules/cabana -count=1 2>&1 | tail -4</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5 && bash scripts/check-phase35.sh --additive 2>&1 | tail -3</automated>
<fails_when>non-zero exit, or a "FAIL", "refuse:" or "unknown identifier" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "^func UnsafeText" modules/postcard/safety.go` prints one line
- `grep -n "layoutSiteName" modules/postcard/mailer.go modules/postcard/editor.go` prints at least three lines (definition, options, renderBrand)
- `grep -n "postcard.UnsafeText" modules/cabana/mail_admin.go` prints one line
- `grep -n "site_name_unsafe" modules/phrasebook/backend/lang/en/lang.yaml modules/phrasebook/backend/lang/pl/lang.yaml` prints two lines
- `grep -n "postcard.UnsafeText" modules/postcard/README.md modules/cabana/README.md` prints at least two lines
- `grep -n "site_name_unsafe" .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md` prints at least two lines
- `git status --porcelain -- go.mod go.sum` prints nothing
</acceptance_criteria>
<done>No Branding value an administrator can save, and no mail.from display name, can stop mail on the built-in layouts: an unsafe name is refused on the form and, if stored earlier, is left out of the mail with one warning, while prose names save and send.</done>
</task>
<task type="auto" tdd="true">
<name>Task 3: The inlined result never stops mail and the footer prints the site name literally (WR-05 contradiction, WR-01)</name>
<reversibility rating="costly">The footer partial's text argument becomes part of the published partial contract administrators write overrides against; the post-inline change is code only.</reversibility>
<files>modules/postcard/templates.go, modules/postcard/assets/partials/footer.htm, modules/postcard/assets/default.htm, modules/postcard/assets/system.htm, modules/postcard/safety_smoke_test.go, modules/postcard/layouts_test.go, modules/postcard/inline_test.go, modules/postcard/README.md, docs/services/mail.md</files>
<behavior>
- With the mailer's inliner seam returning HTML that holds an anchor with a javascript: href, the send succeeds with the un-inlined HTML (style element present, no inlined style attribute on the button, no "javascript:"), one warning keyed inline:<layout> is logged, and the text part equals the text part sent with inlining off
- With Branding SiteName `*Acme*`, the footer of the default and system layouts reads `© <year> *Acme*` with no em element; `Acme <Studio>` appears escaped with no "raw HTML omitted" comment; `[x](https://example.com)` appears literally with no anchor inside the footer table; the header span shows the same text
- The text part's footer is the dashes line followed by the copyright line with the name verbatim
- The footer partial called with body only still renders that body as Markdown
</behavior>
<read_first>
- modules/postcard/templates.go (~722-751 inlineHTML) and inline_test.go (~190-230 TestInlineFailure)
- modules/postcard/assets/partials/footer.htm, assets/default.htm, assets/system.htm, assets/partials/header.htm
- modules/postcard/layouts_test.go (`footerText` ~195, `TestHeaderFooterPartials` ~212-300)
- modules/postcard/README.md CSS inlining (~184-206, including the partial table) and Branding (~290); docs/services/mail.md CSS inlining (~19-24), Partials table (~45-58), Built-in layouts (~60-73)
</read_first>
<action>
WR-05: the docs' promise wins (decision note). WR-01: the name is literal in the footer, as in the header.
- templates.go `inlineHTML`: when `validateHTML` fails on the inlined output, call opts.warn with key "inline:"+layout, message "postcard: inlined CSS failed the safety check, sending the style block only" and the layout and error args, then return the un-inlined html with a nil error, exactly as for an inliner error. Rewrite the doc comment: the input already passed validateHTML in renderParts, which now reads decoded attribute values and the CSS of style elements whether or not the layout opts out, so sending it is safe; mail is never stopped by the inliner. Commit with the first Task 3 subject, together with subtest `TestMailSafetySmoke/inline_unsafe_output` (the first behavior item) and the README and docs sentences below about inlining.
- footer.htm: add a `text` argument. The HTML section prints a paragraph holding `.text` through html/template when text is set and otherwise keeps the Markdown rendering of `.body`. The text section prints `.text` when set, otherwise `.body`, after the dashes line. The name header stays "Footer".
- default.htm and system.htm: in both wrappers of both layouts (four calls), pass the copyright line to the footer partial as its `text` argument instead of its `body` argument.
- Tests: adjust layouts_test.go or inline_test.go only where an assertion depended on the Markdown-rendered footer markup (the visible "© <year> <name>" text stays the same). Add subtest `TestMailSafetySmoke/literal_footer` (the footer behavior items). Commit with the second Task 3 subject, together with the README and docs changes below about the footer.
- Docs, each in the commit of the change it describes:
- postcard README: the CSS inlining paragraph (replace the sentence that says the inlined HTML failing the check fails the render with: the check runs on the decoded markup before inlining, whether or not the layout opts out, and an inlined result that fails it is sent as its style-block version with the same warning); the opt-out paragraph's failure sentence; the partial table's footer row (`text`, plain and printed escaped, or `body`, Markdown); the layouts paragraph (the footer line is passed as `text`); the Branding sentence about escaping, which is now true in header and footer.
- docs/services/mail.md: the CSS inlining paragraph (same rule), the Partials table footer row, and the Built-in layouts paragraph.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test -short ./modules/postcard -count=1 -run '^(TestMailSafetySmoke|TestHeaderFooterPartials|TestBuiltinLayoutsLogo|TestSiteName|TestInlineCSS|TestInlineCSSOptOut|TestInlineFailure)$' -v 2>&1 | grep -E '^\s*(--- FAIL|--- SKIP|--- PASS|FAIL|ok)' | tail -24</automated>
<fails_when>a "FAIL" or "--- SKIP" line, or no "--- PASS: TestMailSafetySmoke/inline_unsafe_output" or "--- PASS: TestMailSafetySmoke/literal_footer" line</fails_when>
<automated>go vet ./... && go test -short ./... && go test ./modules/postcard ./modules/cabana -count=1 2>&1 | tail -4 && (cd examples/hello && go test ./... 2>&1 | tail -3)</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>bash scripts/check-phase35.sh --consumers 2>&1 | tail -6; git -C ../sm-user-plugin status --porcelain; git -C ../sm-paymentgateway-plugin status --porcelain</automated>
<fails_when>a "refuse:" or "FAIL" line, no "phase35 consumers passed" line, or any porcelain output</fails_when>
<automated>go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5 && bash scripts/check-phase35.sh --additive 2>&1 | tail -3</automated>
<fails_when>non-zero exit, or a "FAIL", "refuse:" or "unknown identifier" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -c 'partial "footer" "text"' modules/postcard/assets/default.htm` prints 2 and `grep -c 'partial "footer" "text"' modules/postcard/assets/system.htm` prints 2
- `grep -c 'partial "footer" "body"' modules/postcard/assets/default.htm modules/postcard/assets/system.htm` prints 0 for each file
- `grep -c "\.text" modules/postcard/assets/partials/footer.htm` prints at least 2
- `grep -n "inlined CSS failed the safety check" modules/postcard/templates.go` prints one line
- `grep -n "fails the render as before" modules/postcard/README.md` prints nothing
- `git log --oneline 0aa38db8..HEAD -- go.mod go.sum modules/pact admin modules/boardwalk/dist` prints nothing
</acceptance_criteria>
<done>The inliner can no longer stop a message that passed the safety check, the docs say the same thing in both places, and the footer shows the site name exactly as typed, escaped, like the header.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| admin browser → layouts, partials, template overrides | administrators with system.manage_mail_layouts or system.manage_mail_templates write raw layout and partial HTML and Markdown bodies that reach every recipient |
| admin browser → Branding settings | administrators with system.manage_mail_layouts set the site name printed in every built-in-layout mail |
| application config → mail.from | the display name reaches every layout without any admin action |
| rendered mail → recipients' mail clients | HTML leaves the system; a script URL in it is stored XSS in webmail |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-35-41 | Tampering | URL-bearing attributes in rendered mail (href, src, action, formaction, background, poster, xlink:href, srcset, SVG animation targets) | high | mitigate | `unsafeMarkup` checks every such attribute of the rendered body, partial outputs and layout HTML at save (Editor.Validate) and at send, before inlining; prefix rule after removing whitespace and control characters; list attributes checked anywhere (TestMailSafetySmoke/encoded_scheme; TestURLSchemeCheck in 35-09) |
| T-35-42 | Tampering | entity-encoded schemes (`javascript&#58;`, `&#x3A;`, `&colon;`, `&#106;avascript:`, tab-split) bypassing the check, notably with disable_auto_inline_css on (WR-05) | high | mitigate | the x/net/html tokenizer decodes attribute values before the check; the check runs on the pre-inline HTML whatever the opt-out (TestMailSafetySmoke/encoded_scheme with the switch on and off) |
| T-35-43 | Tampering | CSS contexts (style attributes, style elements, layout CSS drafts) carrying url(javascript:/vbscript:/data:) | medium | mitigate | conservative whole-value pattern over decoded style attributes and style element text; draft CSS checked as a style element so the error stays on content_css; CSS escape sequences are not decoded, accepted because mail clients do not run script URLs from CSS (recorded in the decision note) |
| T-35-44 | Denial of service | Branding Site name or mail.from display name stopping every send on the default and system layouts, file version included (CR-01) | high | mitigate | prose no longer matches (anchored check); `postcard.UnsafeText` refuses an unsafe name at save (422 on site_name); `layoutSiteName` drops an unsafe stored or configured name on every render path (file version, override, override-failure fallback, editor) with a rate-limited warning |
| T-35-45 | Denial of service | an inlined result failing the safety check stopping the message (WR-05) | medium | mitigate | the already-checked un-inlined HTML is sent with its style block and the rate-limited inline:<layout> warning (TestMailSafetySmoke/inline_unsafe_output) |
| T-35-46 | Tampering | site name parsed as Markdown in the footer: a `[x](https://evil.example)` link or lost text in every mail (WR-01) | medium | mitigate | the built-in layouts pass the copyright line as the footer's text argument, printed through html/template (TestMailSafetySmoke/literal_footer) |
| T-35-47 | Elevation of privilege | an event-handler attribute without leading whitespace (`<img src="x"onerror=...>`) missed by the raw regex | medium | mitigate | the tokenizer walk refuses every attribute whose name starts with on (planner addition) |
| T-35-48 | Information disclosure | warnings about a dropped site name | low | accept | the warning names the source (branding or mail.from) only, never the value, and is rate-limited per minute per key |
| T-35-SC | Tampering | npm/pip/cargo installs | high | accept | this plan installs no npm, pip or cargo package and adds no Go module (golang.org/x/net/html is already a direct requirement; go.mod and go.sum unchanged) |
</threat_model>
<verification>
- `go vet ./... && go test -short ./...`, `go test ./modules/postcard ./modules/cabana` (Docker) and `cd examples/hello && go test ./...` green after every code commit.
- `bash scripts/check-phase35.sh --consumers` passes with both sibling trees clean; `bash scripts/check-phase35.sh --additive` passes (UnsafeText is the only exported addition).
- `go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree'` and `go run ./cmd/summer docs:build --check` pass.
- go.mod, go.sum, modules/pact, admin/ and modules/boardwalk/dist have no commits since 0aa38db8.
- The full `bash scripts/check-phase35.sh --all` is run in 35-09 after the new tests are required by name.
</verification>
<success_criteria>
- Sends on the default and system layouts succeed with mail.from "Metadata: Weekly" <x@example.com> and with Branding Site name "Big Data: Summit".
- An unsafe site name is refused on the Branding form (422 on site_name, en/pl text) and, when stored or configured anyway, is left out of the mail with a warning while the send succeeds.
- URL schemes are checked in decoded attribute values and CSS, never in text; entity-encoded schemes are refused with inlining on and off.
- An inlined result that fails the check is sent as its style-block version; the README and docs/services/mail.md agree.
- The footer prints the site name literally.
- Decision note, READMEs, docs and UI-SPEC describe what ships; nothing pushed or tagged; no sibling repository changed.
</success_criteria>
<output>
Create `.planning/phases/35-mail-templates-and-layouts-editor/35-08-SUMMARY.md` when done. List the exact names 35-09 tests: `postcard.UnsafeText`, `unsafeMarkup`, `hasDangerousScheme`, `urlAttributes`, `urlListAttributes`, `scriptURLText`, `siteNameFrom`, `layoutSiteName`, the warning keys and messages, the footer `text` argument, the copy key, the smoke subtests, the fixtures changed in Task 1 and why, and any deviation (including a RED run without a separate commit).
</output>
## Artifacts this phase produces
| Kind | Name | Where |
|------|------|-------|
| File (new) | `.planning/notes/2026-11-14-mail-url-scheme-check.md` | decision note (Task 1, first commit) |
| File (new) | `modules/postcard/safety.go` | Task 1, extended in Task 2 |
| Exported function | `postcard.UnsafeText(s string) bool` | modules/postcard/safety.go (Task 2) |
| Unexported function | `unsafeMarkup(doc string) error` | modules/postcard/safety.go (Task 1) |
| Unexported function | `hasDangerousScheme(val string) bool` | modules/postcard/safety.go (Task 1) |
| Unexported vars | `urlAttributes`, `urlListAttributes`, `scriptURLText` | modules/postcard/safety.go (Tasks 1, 2) |
| Changed function | `validateHTML` (scheme check through `unsafeMarkup`; tag and handler regexes unchanged) | modules/postcard/templates.go (Task 1) |
| Changed function | `inlineHTML` (an inlined result failing the check is sent un-inlined with a warning) | modules/postcard/templates.go (Task 3) |
| Changed function | `(*Editor).renderLayout` (draft CSS checked as a style element), `(*Editor).renderBrand` (uses `layoutSiteName`) | modules/postcard/editor.go (Tasks 1, 2) |
| Unexported function | `siteNameFrom(brand *Brand, from string) (name, skipped string)` | modules/postcard/mailer.go (Task 2) |
| Unexported method | `(*mailer).layoutSiteName(brand *Brand) string` | modules/postcard/mailer.go (Task 2) |
| Kept function | `siteName(brand *Brand, from string) string` (same signature, now skips unsafe candidates) | modules/postcard/mailer.go (Task 2) |
| Warning keys / messages | `site_name:branding`, `site_name:mail.from` — "postcard: site name left out of the layouts, it fails the mail safety check"; `inline:<layout>` — "postcard: inlined CSS failed the safety check, sending the style block only" | modules/postcard (Tasks 2, 3) |
| Partial argument | `footer` partial `text` (plain, escaped); `body` stays Markdown | modules/postcard/assets/partials/footer.htm (Task 3) |
| Layout change | default and system layouts pass the copyright line as `text` | modules/postcard/assets/default.htm, system.htm (Task 3) |
| Validation rule | `MailBrandSetting.BeforeValidate` refuses `postcard.UnsafeText` names on `site_name` | modules/cabana/mail_admin.go (Task 2) |
| Message key | `mail.brand.site_name_unsafe` (`backend::lang.mail.brand.site_name_unsafe`), en and pl | modules/phrasebook/backend/lang/{en,pl}/lang.yaml (Task 2) |
| Smoke test | `TestMailSafetySmoke` with subtests `prose_site_name`, `encoded_scheme` (Task 1), `unsafe_site_name` (Task 2), `inline_unsafe_output`, `literal_footer` (Task 3) | modules/postcard/safety_smoke_test.go (new) |
| Smoke subtest | `TestMailBrandSiteName/unsafe_name_refused` | modules/cabana/mail_brand_layout_postgres_test.go (Task 2) |
| Removed subtest | `TestMailBrandSiteName/unsafe_name_current_behaviour` (pinned the old behaviour in 35-07) | modules/cabana/mail_brand_layout_postgres_test.go (Task 1) |
| Changed fixtures | editor_smoke_test.go "body scheme" row → "layout scheme" row plus the prose body as a valid draft; `TestFallback/unsafe_override`; `TestMailPartialsSmoke/errors` `unsafe_html`; `TestMailOverrideSmoke/fallback` `unsafe` | modules/postcard (Task 1) |
| Docs | postcard README (Features, CSS inlining, partials table, layouts, Branding, Editing drafts, API reference, Dependencies), cabana README (Branding), docs/services/mail.md (Sending, CSS inlining, Partials, Built-in layouts, Branding) | Tasks 1-3 |
| Planning docs | 35-UI-SPEC.md Branding copy row, C15 row, state row for the unsafe site name | Task 2, second commit |
## Follow-ups outside this plan (not planned here)
- 35-09: regression and unit tests for everything above, the new names required by `scripts/check-phase35.sh`, and the 35-VALIDATION.md rows.
- The remaining advisory findings of 35-REVIEW.md (WR-02, WR-03, WR-04, IN-01, IN-02, IN-04) are not in the user's scope for this gap closure; the unanchored `\son[a-z]+\s*=` handler regex (prose such as " online = " still fails) is unchanged.

View File

@@ -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 <img src=x\"onerror=...>)"
- "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:<layout> 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&#58; 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&#58;`) 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:<layout>`, "postcard: inlined CSS failed the safety check, sending the style block only" (attrs `layout`, `error`)
- Footer partial: `text` argument (plain, escaped in a `<p>`; 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&#58;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 (`<p>...</p>` 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

View File

@@ -0,0 +1,333 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 09
type: execute
wave: 9
depends_on: ["35-08"]
gap_closure: true
gap_ids: [CR-01]
files_modified:
- modules/postcard/sitename_test.go
- modules/postcard/safety_test.go
- modules/cabana/mail_site_name_postgres_test.go
- scripts/check-phase35.sh
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
autonomous: true
requirements: [CR-01, WR-01, WR-05, D-13, D-14, D-21]
estimate:
tokens: 95000
raw_tokens: 95000
tasks: 3
confidence: low
must_haves:
truths:
- "Mail that already works keeps working: an application that sends mail today keeps sending it after upgrading, and no admin-saved Branding value can stop mail on the built-in layouts; one gate command (check-phase35.sh --all) proves it (CR-01, D-21)"
- "Named Docker-free unit tests prove: sends on the default and system layouts succeed with mail.from \"Metadata: Weekly\" <x@example.com> and with Branding SiteName 'Big Data: Summit'; an unsafe site name (javascript:alert(1)) is dropped at render time with one rate-limited warning and the send succeeds on the file-version path, the override path and the override-failure fallback; Editor validation under an unsafe stored name succeeds (D-14)"
- "A cabana Postgres test proves a Branding save of an unsafe name is a 422 on site_name with the en and the pl text and stores nothing, prose names save, and a template save, a layout save and a send under a previously stored unsafe name are not refused (D-13)"
- "The 35-07 subtest that pinned an unsafe site name as saved and refused by the preview is gone, replaced by tests of the new behaviour"
- "Unit tests prove the anchored, decoded scheme check: body text 'metadata:' passes; href=\"javascript:...\", src=\"data:...\", entity-encoded href=\"javascript&#58;...\" and its &#x3A;, &colon;, &#106; and tab-split forms are refused, through a send with inlining on and with it off; an inlined result that fails the check is sent as its style-block version with one warning (WR-05)"
- "Unit tests prove the footer of the default and system layouts prints *Acme*, Acme <Studio> and [x](url) literally and escaped, with no em element, no HTML comment and no link (WR-01)"
- "scripts/check-phase35.sh requires every new test by name; its self-test compares the planted consumer's go.mod with a copy taken before the run (IN-03); 35-VALIDATION.md maps CR-01, WR-01 and WR-05 and records the site-name open item as closed"
prohibitions:
- statement: "No production code changes except fixes for defects the new tests expose, each in its own fix commit and recorded as a deviation in the SUMMARY."
status: unresolved
verification: judgment
- statement: "Tests and the gate never write a sibling repository (git status --porcelain of sm-user-plugin and sm-paymentgateway-plugin stays empty) and never reach the network beyond localhost, httptest servers and testcontainers."
status: unresolved
verification: automated
- statement: "No new dependency: go.mod and go.sum are unchanged."
status: unresolved
verification: automated
- statement: "Nothing is pushed or tagged (tag only at phase completion, on the default branch, after Jakub's go-ahead)."
status: unresolved
verification: judgment
artifacts:
- path: "modules/postcard/sitename_test.go"
provides: "site-name send regressions, the render-time drop, UnsafeText rules, the literal footer"
contains: "func TestUnsafeSiteNameDropped"
- path: "modules/postcard/safety_test.go"
provides: "anchored and decoded URL-scheme check, unsafe inlined output"
contains: "func TestURLSchemeCheck"
- path: "modules/cabana/mail_site_name_postgres_test.go"
provides: "Branding refusal and stored-unsafe-name saves and sends"
contains: "func TestMailSiteNameSafety"
- path: "scripts/check-phase35.sh"
provides: "phase gate requiring the new names"
contains: "TestMailSiteNameSafety"
key_links:
- from: "scripts/check-phase35.sh"
to: "modules/postcard/sitename_test.go"
via: "GO_TESTS requires TestSiteNameSend, TestUnsafeSiteNameDropped, TestUnsafeText and TestFooterSiteNameLiteral by name"
pattern: "TestUnsafeSiteNameDropped"
- from: "scripts/check-phase35.sh"
to: "modules/cabana/mail_site_name_postgres_test.go"
via: "DOCKER_TESTS requires TestMailSiteNameSafety by name"
pattern: "TestMailSiteNameSafety"
- from: "modules/postcard/safety_test.go"
to: "modules/postcard/safety.go"
via: "validateHTML and sends through layout overrides exercise unsafeMarkup"
pattern: "TestURLSchemeCheck"
---
## Phase Goal
ROADMAP Goal (not in user-story format; no story is invented): administrators edit every mail the application sends from the admin panel, and mail that already works keeps working. Project rule 2 puts unit tests in the last plan of the phase; this plan is the last plan of the CR-01 gap closure and proves 35-08 with regression and unit tests and the extended phase gate (D-21).
Gap truth (35-VERIFICATION.md): "Mail that already works keeps working: an application that sends mail today keeps sending it after upgrading, and no admin-saved Branding value can stop mail on the built-in layouts."
Spec-less probe fallback: skipped, the phase has no requirement IDs to probe (visible skip).
<objective>
- postcard Docker-free tests for the verifier's regressions: prose site names on the default and system layouts (mail.from and Branding), the render-time drop of an unsafe name on every path, `postcard.UnsafeText`, the anchored and decoded scheme check with inlining on and off, the unsafe inlined result, the literal footer.
- A cabana Postgres test for the Branding 422 (en and pl), prose names, and template/layout saves and sends under a previously stored unsafe name.
- `scripts/check-phase35.sh` requires every new name; the IN-03 self-test assertion compares the planted consumer's go.mod; `--all` passes.
- 35-VALIDATION.md maps CR-01, WR-01 and WR-05 and closes the site-name open item.
Purpose: D-21's "unit tests last" for the CR-01 gap closure; the gate is what `/msd-verify-work 35` re-runs before the pending human items.
Output: test and gate-script commits in this repository and one planning-docs commit for 35-VALIDATION.md. No sibling repository is changed; nothing is pushed or tagged.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/35-mail-templates-and-layouts-editor/35-08-SUMMARY.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-08-PLAN.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-VERIFICATION.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
@CLAUDE.md
<interfaces>
- Names under test come from 35-08-SUMMARY.md (where it differs from this plan, the SUMMARY wins): `postcard.UnsafeText`, unexported `unsafeMarkup`, `hasDangerousScheme`, `urlAttributes`, `urlListAttributes`, `scriptURLText`, `siteNameFrom`, `(*mailer).layoutSiteName`, `siteName`; warning keys `site_name:branding`, `site_name:mail.from`, `inline:<layout>`; footer partial argument `text`; copy key `backend::lang.mail.brand.site_name_unsafe`; smoke test `TestMailSafetySmoke` (subtests prose_site_name, encoded_scheme, unsafe_site_name, inline_unsafe_output, literal_footer) and `TestMailBrandSiteName/unsafe_name_refused`.
- postcard test helpers (package postcard): partials_smoke_test.go `fakeOverrides{ov}`, `partialsMailer(t, opts, ov)`, `sendTemplate(t, m, drv, name, vars)`, `copyright()`; override_test.go `assertFileFallback(t, cat, file, opts, wantLog)`, `acmeBlog`, `fileWelcome(t)`; layouts_test.go `brandedSend(t, brand, from, template)`, `headerCell(html)`, `footerText(t, html)`, `logoSpan`, `htmlTags`/`withClass`; inline_test.go `noInline`, `buttonStyle`, `styleBlock`, `defaultLayoutWithCSS(css, optOut)`; editor_smoke_test.go `newEditor(t, ov)`; mailer fields `log` (a `*slog.Logger` to capture warnings) and `inline` (inliner seam).
- cabana test helpers (package cabana_test, Postgres, skip under -short like the other mail Postgres tests): mail_screens_smoke_test.go `newMailScreensEnv(t, mutate func(*compass.Config))`, `newMailScreensEnvWith(t, mailEnvOptions{files, keep, mutate, writer})`, `env.admin(t, name, superuser, roles)`, `env.expect`, `env.call`, `env.gdb`, `env.mailRowID`; administrators_harness_test.go `env.expectFieldRefusal(t, status, method, path, token, body, field, want, inMessage)`, `errorEnvelope`, `detailHas`; mail_locale_postgres_test.go `getInLanguage` (Accept-Language pattern), `sendGrace(t, env, name)`; mail_brand_layout_postgres_test.go `brandPreview`, `headerSpan`, `mailBrandPath`, `templateBody`, `mailTemplatesPath`; `postcard.BrandTable`, `postcard.TemplatesTable`, `postcard.LayoutsTable`; fixture template `blogWelcome`.
- scripts/check-phase35.sh: `GO_TESTS` (Docker-free names, never skip under -short, ~74-100), `DOCKER_TESTS` (~103-122), `go_pkg_named` anchors names; `self_test_consumers` (~569-616) holds the IN-03 assertion (~611) in the workspace-modfile case; `run_go` prints "phase35 go passed"; `run_all` prints "Phase 35 gate passed".
- Existing test names that must not be reused: TestSiteName, TestBuiltinLayoutsLogo, TestHeaderFooterPartials, TestButtonPartial, TestInlineCSS, TestInlineCSSOptOut, TestInlineFailure, TestMailSafetySmoke, TestMailBrandSiteName, TestMailLayoutInlineOptOut, TestOverride, TestFallback, TestValidateDraft and the *Smoke tests.
</interfaces>
</context>
## Execution units and resume points
- Before each task run `git status --short modules/postcard modules/cabana scripts .planning/phases/35-mail-templates-and-layouts-editor` and stop if another session holds uncommitted edits in files this task touches. Never stage `examples/hello/plugins.gen.go`, `.planning/G15OFFICE.md`, `.planning/state.json` or `.planning/phases/35-mail-templates-and-layouts-editor/deferred-items.md`.
- Stage by explicit path; no co-author tags. Tests are written against the shipped 35-08 code; a defect a test exposes gets its own `fix(<module>): ...` commit before the test commit, recorded as a deviation. `go vet ./...` and `go test ./...` green at every commit. Docker-backed tests run without `-short` (through `sudo -u golem` if the Docker socket is denied).
- Each test task adds its new names to the gate's required arrays in the same commit as the tests, so the gate never requires a test that does not exist yet.
- Tests pin shipped behaviour, so a first green run is expected; show they are not vacuous with mutation runs (break the rule under test temporarily, see the test fail, restore with `git checkout -- <file>`), as 35-07 did, and record them in the SUMMARY.
- Resume check: `git log --format=%s -F --grep='<subject>'`.
| Task | Commit subject | Resume point |
|------|----------------|--------------|
| 1 | `test(postcard): site names on the built-in layouts never stop a send` | `--go` passes with TestSiteNameSend, TestUnsafeSiteNameDropped, TestUnsafeText, TestMailSafetySmoke required |
| 2 | `test(postcard): decoded URL scheme check, unsafe inlined output and the literal footer` | `--go` passes with TestURLSchemeCheck, TestInlineUnsafeOutput, TestFooterSiteNameLiteral required |
| 3 | `test(cabana): unsafe Branding site names refused at save, stored ones never block saves or sends`, `test(35): self-test compares the planted consumer's go.mod`, then `docs(35): validation map for the site name safety gap` | `bash scripts/check-phase35.sh --all` passes |
<tasks>
<task type="tracer">
<name>Task 1: End-to-end "one gate command proves mail keeps sending with prose and unsafe site names on the built-in layouts" — the site-name tests and their gate entries only</name>
<precondition>35-08 is complete: `.planning/phases/35-mail-templates-and-layouts-editor/35-08-SUMMARY.md` exists and `git log --format=%s -F --grep='fix(postcard,cabana): unsafe site names never stop a send'` prints one line</precondition>
<files>modules/postcard/sitename_test.go, scripts/check-phase35.sh</files>
<behavior>
- TestSiteNameSend: an fstest.MapFS catalog with one template on layout default and one on system; with Options.From "\"Metadata: Weekly\" <x@example.com>" and no Branding, and again with fakeOverrides Brand SiteName "Big Data: Summit", Send returns nil for both layouts; the header span and the footer text (copyright() plus the name) carry the name and the text part holds it; this holds on the file-version path (Brand only), on the override path (a template override present) and on the override-failure fallback (an override reading a field of a variable the caller does not pass falls back to the file version, which carries the name); a body holding "See the metadata: field." sends and keeps that text
- TestUnsafeSiteNameDropped: Branding SiteName "javascript:alert(1)" with Options.From "Acme <x@example.com>" sends on both layouts with Acme in header and footer, and neither the HTML nor the text part holds "javascript:"; two sends within a minute log exactly one warning, carrying source=branding and not the value; with Branding "javascript: Acme" and From "\"vbscript:x\" <x@example.com>" the send succeeds with no header row and a footer holding only the year; "Shop onclick=x" as the Branding name is dropped the same way; all three render paths (file version, override, override-failure fallback) succeed without the unsafe name; Editor.Validate of a template draft and of a layout draft under the unsafe Branding returns nil; Editor.Preview of a Branding draft with SiteName "javascript: Acme" renders without the name and without an error
- TestUnsafeText: safe for "", "Acme", "Big Data: Summit", "Metadata: Weekly", "Metadata:Weekly", "Data: Summit", "Acme <Studio>", "*Acme*", "[x](https://example.com)"; unsafe for "javascript:alert(1)", "javascript: Acme", "JAVASCRIPT:x", "Go vbscript:msgbox(1)", "data:text/html,x", "Shop data:x", "Shop onclick=x", "x onload = 1"
</behavior>
<read_first>
- .planning/phases/35-mail-templates-and-layouts-editor/35-08-SUMMARY.md (exact names, warning texts, deviations)
- modules/postcard/safety.go, modules/postcard/mailer.go (render, options, siteNameFrom, layoutSiteName, warn), modules/postcard/editor.go (render, renderBrand)
- modules/postcard/safety_smoke_test.go (what the smoke test already covers; extend, do not duplicate)
- modules/postcard/layouts_test.go (helpers and TestSiteName), modules/postcard/partials_smoke_test.go (~78-140 helpers), modules/postcard/override_test.go (~140-230 assertFileFallback), modules/postcard/inline_test.go (~190-230, warning capture through mailer.log)
- scripts/check-phase35.sh (~70-125 arrays, ~300-345 go_named/go_pkg_named, ~666-674 run_go)
</read_first>
<action>
Per D-21 (unit tests last) and D-14 (mail never stops over a failing override, extended by 35-08 to the site name):
- New file modules/postcard/sitename_test.go in package postcard, with `TestSiteNameSend`, `TestUnsafeSiteNameDropped` and `TestUnsafeText` for the behavior list above.
- Docker-free: never call t.Skip, use small fstest.MapFS catalogs, and compare HTML by tag and attribute (the inliner re-serializes markup), never by whole-document equality. Capture warnings by setting the mailer's `log` field to a text handler over a buffer, then count the lines that hold the 35-08 warning text.
- Use table subtests named after the layout and the path (for example `default/file_version`, `system/override_fallback`), so a failure names its case.
- In the same commit add `./modules/postcard:TestMailSafetySmoke`, `./modules/postcard:TestSiteNameSend`, `./modules/postcard:TestUnsafeSiteNameDropped` and `./modules/postcard:TestUnsafeText` to `GO_TESTS` in scripts/check-phase35.sh.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test -short ./modules/postcard -count=1 -run '^(TestSiteNameSend|TestUnsafeSiteNameDropped|TestUnsafeText|TestMailSafetySmoke)$' -v 2>&1 | grep -E '^(--- |FAIL|ok|PASS)' | tail -12</automated>
<fails_when>a "FAIL" or "--- SKIP" line, or fewer than four "--- PASS" lines</fails_when>
<automated>go vet ./... && go test -short ./... && bash scripts/check-phase35.sh --go 2>&1 | tail -4</automated>
<fails_when>non-zero exit, a "refuse:" or "FAIL" line, or no "phase35 go passed" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -c "^func Test\(SiteNameSend\|UnsafeSiteNameDropped\|UnsafeText\)(" modules/postcard/sitename_test.go` prints 3
- `grep -n "t.Skip" modules/postcard/sitename_test.go` prints nothing
- `grep -n "Metadata: Weekly\|Big Data: Summit" modules/postcard/sitename_test.go` prints at least two lines
- `grep -n "TestSiteNameSend\|TestUnsafeSiteNameDropped\|TestUnsafeText\|TestMailSafetySmoke" scripts/check-phase35.sh` prints at least four lines
</acceptance_criteria>
<done>The verifier's send-path regressions (prose names from mail.from and from Branding, an unsafe name on every render path) are pinned by named tests the gate's go stage requires.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: Unit tests for the anchored, decoded scheme check, the unsafe inlined result and the literal footer</name>
<files>modules/postcard/safety_test.go, modules/postcard/sitename_test.go, scripts/check-phase35.sh</files>
<behavior>
- TestURLSchemeCheck accepts (validateHTML returns nil): a paragraph "See the metadata: field", a paragraph "Big Data: Summit", an img with alt "Data: Summit" and an https src, a td with title "javascript: tips", an anchor whose https href holds "javascript:x" in its query string
- TestURLSchemeCheck refuses with "dangerous URL scheme": href javascript:alert(1); href " JavaScript:alert(1)"; src data:image/png;base64,AAAA; href vbscript:msgbox(1); form action, button formaction, table background and video poster with javascript:x; an svg anchor with xlink:href javascript:x; img srcset "a.png 1x, javascript:x 2x"; a style attribute with url(javascript:x) and with url(&#34;javascript:x&#34;); a style element holding url(data:image/png;base64,AA); a meta refresh whose content holds url=javascript:x; the encoded hrefs javascript&#58;alert(1), javascript&#x3A;alert(1), javascript&colon;alert(1), &#106;avascript:alert(1), java&#9;script:alert(1) and java&#x0A;script:alert(1)
- TestURLSchemeCheck refuses with "event handlers": an img whose src is followed by onerror with no whitespace in between
- TestURLSchemeCheck, send path: a layout override whose HTML holds an anchor with href javascript&#58;alert(1) makes the send fall back to the file version (assertFileFallback), with DisableAutoInlineCSS false and with it true, and the encoded form never reaches the driver
- TestURLSchemeCheck, editor: that layout draft fails Editor.Validate on content_html with rule unsafe for both opt-out values; a layout draft whose CSS holds url(javascript:x) fails on content_css with rule unsafe; a template draft whose body is "See the metadata: field." validates
- TestInlineUnsafeOutput: with the mailer's inline seam returning HTML that holds an anchor with a javascript: href, Send returns nil; the sent HTML has a style element, no inlined style attribute on the button and no "javascript:"; one warning keyed inline:<layout> is logged across two sends within a minute; the text part equals the text part of the same message sent with noInline
- TestFooterSiteNameLiteral: for the default and the system layout with Branding SiteName `*Acme*`, `Acme <Studio>` and `[x](https://example.com)`, footerText equals copyright() plus a space plus the name; the footer table holds no em element, no "raw HTML omitted" comment and no anchor; the header span shows the same text; the text part's footer line holds the name verbatim; the footer partial called with body only still renders Markdown (a `*b*` body gives an em element)
</behavior>
<read_first>
- .planning/phases/35-mail-templates-and-layouts-editor/35-08-SUMMARY.md
- modules/postcard/safety.go, modules/postcard/templates.go (validateHTML, inlineHTML), modules/postcard/editor.go (renderLayout, draftErrorFor)
- modules/postcard/assets/partials/footer.htm, assets/default.htm, assets/system.htm (as left by 35-08)
- modules/postcard/inline_test.go (TestInlineCSS, TestInlineFailure helpers), modules/postcard/editor_smoke_test.go (DraftError field and rule assertions), modules/postcard/layouts_test.go (footerText, headerCell)
- modules/postcard/sitename_test.go (as left by Task 1)
</read_first>
<action>
Per D-21 and D-13 (the safety checks D-13 names still refuse javascript:/vbscript:/data: URLs, now read from decoded attribute values), for WR-05 and WR-01:
- New file modules/postcard/safety_test.go (package postcard) with `TestURLSchemeCheck` (table subtests for the accept and refuse lists, then send-path and editor subtests) and `TestInlineUnsafeOutput`.
- Add `TestFooterSiteNameLiteral` to modules/postcard/sitename_test.go.
- The refuse table checks the error text (the unsafeError message) and that the snippet points at the offending markup, as `DraftError.Message` shows it.
- Docker-free, no t.Skip; assert by tag and attribute.
- In the same commit add `./modules/postcard:TestURLSchemeCheck`, `./modules/postcard:TestInlineUnsafeOutput` and `./modules/postcard:TestFooterSiteNameLiteral` to `GO_TESTS`.
- If a case exposes a defect in 35-08's code (for example an attribute missing from `urlAttributes`), fix it in its own `fix(postcard): ...` commit first, with the README and docs line it affects, and record the deviation.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test -short ./modules/postcard -count=1 -run '^(TestURLSchemeCheck|TestInlineUnsafeOutput|TestFooterSiteNameLiteral)$' -v 2>&1 | grep -E '^(--- |FAIL|ok|PASS)' | tail -10</automated>
<fails_when>a "FAIL" or "--- SKIP" line, or fewer than three "--- PASS" lines</fails_when>
<automated>go vet ./... && go test -short ./... && go test ./modules/postcard -count=1 2>&1 | tail -3 && bash scripts/check-phase35.sh --go 2>&1 | tail -4</automated>
<fails_when>non-zero exit, a "refuse:" or "FAIL" line, or no "phase35 go passed" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -c "^func Test\(URLSchemeCheck\|InlineUnsafeOutput\)(" modules/postcard/safety_test.go` prints 2 and `grep -c "^func TestFooterSiteNameLiteral(" modules/postcard/sitename_test.go` prints 1
- `grep -n "t.Skip" modules/postcard/safety_test.go modules/postcard/sitename_test.go` prints nothing
- `grep -c "&#58;\|&#x3A;\|&colon;\|&#106;" modules/postcard/safety_test.go` prints at least 4
- `grep -n "TestURLSchemeCheck\|TestInlineUnsafeOutput\|TestFooterSiteNameLiteral" scripts/check-phase35.sh` prints at least three lines
</acceptance_criteria>
<done>The scheme check's new boundaries (prose passes, every encoded form and every URL-bearing attribute is refused, inlining on or off), the style-block fallback for an unsafe inlined result and the literal footer are pinned by named tests in the fast loop.</done>
</task>
<task type="auto" tdd="true">
<name>Task 3: cabana Postgres test for the Branding refusal and stored unsafe names; IN-03 self-test fix; gate --all; validation map</name>
<files>modules/cabana/mail_site_name_postgres_test.go, scripts/check-phase35.sh, .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md</files>
<behavior>
- TestMailSiteNameSafety/refused_on_save: PUT of the Branding settings with site_name "javascript: Acme" is a 422 whose Details.site_name holds the en text ("cannot be shown in mail"), and the same request with Accept-Language pl holds the pl text ("nie można pokazać"); the stored row keeps its previous site_name
- TestMailSiteNameSafety/prose_names_saved: "Big Data: Summit" and "Metadata: Weekly" each save with 200 and are stored as typed
- TestMailSiteNameSafety/preview_drops_unsafe_name: POST /mail/preview mode branding with site_name "javascript: Acme" answers 200 and its HTML holds no "javascript:" and no header span with that text
- TestMailSiteNameSafety/stored_unsafe_name_saves: with "javascript: Acme" written straight into the branding row (as data saved before the fix would be), a PUT of the welcome template moved to the default layout answers 200, and a PUT of the default layout's override answers 200
- TestMailSiteNameSafety/stored_unsafe_name_send: with that stored name, a send of the welcome template on the default layout succeeds and its HTML holds no "javascript:"
- TestMailSiteNameSafety/mail_from_prose_name: with mail.from set to "\"Metadata: Weekly\" <x@example.com>" in the environment's configuration and no Branding name, sends of the welcome template on the default and on the system layout succeed and the header span reads "Metadata: Weekly"
- check-phase35.sh --self-test still prints "PASS self-test workspace-modfile", now proving the planted consumer's go.mod is byte-identical before and after the modfile run
</behavior>
<read_first>
- .planning/phases/35-mail-templates-and-layouts-editor/35-08-SUMMARY.md
- modules/cabana/mail_brand_layout_postgres_test.go (style, helpers, the unsafe_name_refused smoke subtest from 35-08) and modules/cabana/mail_screens_smoke_test.go (~126-200 env construction, mutate)
- modules/cabana/mail_locale_postgres_test.go (~54-80 getInLanguage, sendGrace), modules/cabana/administrators_harness_test.go (~458-482)
- modules/cabana/mail_admin.go MailBrandSetting.BeforeValidate (as left by 35-08)
- scripts/check-phase35.sh `self_test_consumers` (~569-616) and DOCKER_TESTS (~103-122)
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md (whole file)
</read_first>
<action>
Per D-21 and D-13:
- New file modules/cabana/mail_site_name_postgres_test.go (package cabana_test) with `TestMailSiteNameSafety` and the six subtests above.
- It is a Postgres test that skips under -short like the other mail Postgres tests and reuses `newMailScreensEnv`.
- Write the stored unsafe name through `env.gdb` on `postcard.BrandTable` (the form refuses it now).
- Build the mail.from case in its own environment through the `mutate` hook.
- Use the Accept-Language pattern of `getInLanguage` for the pl request.
- In the same commit add `./modules/cabana:TestMailSiteNameSafety` to `DOCKER_TESTS`, with the first Task 3 subject.
- Separate commit (IN-03, second subject): in `self_test_consumers`' workspace-modfile case, copy the planted consumer's go.mod to the scratch area before the modfile run and compare it after with `cmp -s`. Keep the replace-line grep, and drop the git-status clause on the dirty-sibling fixture repository (it asserted against the wrong repository). The case keeps its PASS line and its refuse text.
- Run `bash scripts/check-phase35.sh --all` on a Docker host. Use PHASE35_ALLOW_NO_DOCKER only when no daemon answers, and then state it in the SUMMARY.
- Planning-docs commit for 35-VALIDATION.md:
- CR-01 rows: site names on the send path (postcard unit: TestSiteNameSend, TestUnsafeSiteNameDropped, TestUnsafeText, TestMailSafetySmoke); the anchored and decoded scheme check and the unsafe inlined result (postcard unit: TestURLSchemeCheck, TestInlineUnsafeOutput); the admin side (cabana Postgres: TestMailSiteNameSafety, TestMailBrandSiteName).
- A WR-01 row (TestFooterSiteNameLiteral) and a WR-05 row (TestURLSchemeCheck send and editor subtests, TestInlineUnsafeOutput), each with its exact `go test` command.
- Replace the paragraph that records the Branding site name as an open item with a "CR-01 status" line: closed by 35-08 and 35-09, decision note `.planning/notes/2026-11-14-mail-url-scheme-check.md`.
- Add a Manual-Only row: on sm-demo-app, typing "javascript: Acme" as the Branding Site name and saving shows the refusal line under the field, and "Big Data: Summit" saves and shows in the preview header and footer.
- Extend the Wave 0 list with the three new test files.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/cabana -count=1 -run '^TestMailSiteNameSafety$' -v 2>&1 | grep -E '^\s*(--- |FAIL|ok)' | tail -12</automated>
<fails_when>a "FAIL" or "--- SKIP" line, or no "--- PASS: TestMailSiteNameSafety" line, or fewer than six subtest "--- PASS" lines</fails_when>
<automated>bash scripts/check-phase35.sh --self-test 2>&1 | tail -5</automated>
<fails_when>non-zero exit, a "refuse:" line, or no "PASS self-test workspace-modfile" line in the full output</fails_when>
<automated>bash scripts/check-phase35.sh --all 2>&1 | tail -15; git -C ../sm-user-plugin status --porcelain; git -C ../sm-paymentgateway-plugin status --porcelain</automated>
<fails_when>a "refuse:" or "FAIL" line, no "Phase 35 gate passed" line, or any porcelain output</fails_when>
</verify>
<acceptance_criteria>
- `grep -c "^func TestMailSiteNameSafety(" modules/cabana/mail_site_name_postgres_test.go` prints 1
- `grep -rhn 'unsafe_name_current_behaviour' modules/cabana | grep -vE '^[0-9]+:\s*//'` prints nothing
- `grep -n "TestMailSiteNameSafety" scripts/check-phase35.sh` prints at least one line
- `sed -n '/^self_test_consumers()/,/^}/p' scripts/check-phase35.sh | grep -v '^\s*#' | grep -c 'status --porcelain -- go.mod'` prints 0 and `sed -n '/^self_test_consumers()/,/^}/p' scripts/check-phase35.sh | grep -c "cmp -s"` prints at least 1
- `grep -c "CR-01" .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md` prints at least 3, and `grep -n "WR-01\|WR-05" .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md` prints at least two lines
- `grep -n "CR-01 status" .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md` prints one line
- `git status --porcelain -- go.mod go.sum` prints nothing
</acceptance_criteria>
<done>The admin side of CR-01 is pinned by a named Postgres test, one command proves the whole gap closure plus the unchanged core plugins, the self-test checks the right file, and the validation map records how.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| gate script → sibling repositories | the consumers stage builds and tests code in repositories this phase must not change |
| tests → Docker | Postgres tests start containers on the local daemon |
| tests → stored Branding row | a test writes an unsafe name straight into the database to model data saved before the fix |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-35-49 | Repudiation | regression tests that skip, match nothing or go missing while the gate passes | medium | mitigate | every new name is required in GO_TESTS or DOCKER_TESTS; detect_go refuses skips, zero matches and missing names (existing rules); Docker-free files contain no t.Skip (acceptance criteria) |
| T-35-50 | Tampering | the gate self-test asserting against the wrong repository, so a write to the planted consumer's go.mod passes (IN-03) | low | mitigate | cmp -s of the planted consumer's go.mod against a copy taken before the modfile run |
| T-35-51 | Tampering | tests or the gate writing a sibling repository | medium | mitigate | consumers stage stays read-only through scratch modfiles; git status --porcelain of both siblings checked before and after (verify) |
| T-35-52 | Tampering | the direct write of an unsafe name leaking into other tests on the shared database | low | mitigate | newMailScreensEnv empties the mail tables per environment; the test clears site_name at the end of the subtests that set it |
| T-35-SC | Tampering | npm/pip/cargo installs | high | accept | this plan installs no package and adds no Go module |
</threat_model>
<verification>
- `go vet ./... && go test ./...` green (Docker), and `go test -short ./...` green.
- `bash scripts/check-phase35.sh --all` passes; sibling working trees unchanged.
- 35-VALIDATION.md maps CR-01, WR-01 and WR-05; the site-name open item is recorded as closed.
- go.mod and go.sum unchanged; no production file changed except recorded `fix(...)` deviations.
</verification>
<success_criteria>
- Named tests pin the verifier's regressions: prose site names send on the default and system layouts (mail.from and Branding), an unsafe name is dropped with a warning on every render path, a Branding save of an unsafe name is a 422 on site_name, and a template or layout save under a stored unsafe name is not refused.
- The scheme check, the unsafe inlined result and the literal footer are pinned with inlining on and off.
- The gate requires every new name, its self-test checks the planted consumer's go.mod, and `--all` passes.
- Ready for `/msd-verify-work 35`: re-verify the CR-01 gap, then run the pending human items in 35-VERIFICATION.md (UAT test 1 re-run, scoped UAT test 8 re-run, real-inbox check, judgment-tier prohibitions) and the new Manual-Only row. Nothing pushed or tagged.
</success_criteria>
<output>
Create `.planning/phases/35-mail-templates-and-layouts-editor/35-09-SUMMARY.md` when done, with the gate output summary, the list of required test names, the mutation runs that stand in for RED, and any fix commits recorded as deviations.
</output>
## Artifacts this phase produces
| Kind | Name | Where |
|------|------|-------|
| File (new) | `modules/postcard/sitename_test.go` | Tasks 1, 2 |
| Test | `TestSiteNameSend` | modules/postcard/sitename_test.go (Task 1) |
| Test | `TestUnsafeSiteNameDropped` | modules/postcard/sitename_test.go (Task 1) |
| Test | `TestUnsafeText` | modules/postcard/sitename_test.go (Task 1) |
| Test | `TestFooterSiteNameLiteral` | modules/postcard/sitename_test.go (Task 2) |
| File (new) | `modules/postcard/safety_test.go` | Task 2 |
| Test | `TestURLSchemeCheck` | modules/postcard/safety_test.go (Task 2) |
| Test | `TestInlineUnsafeOutput` | modules/postcard/safety_test.go (Task 2) |
| File (new) | `modules/cabana/mail_site_name_postgres_test.go` | Task 3 |
| Test | `TestMailSiteNameSafety` with subtests `refused_on_save`, `prose_names_saved`, `preview_drops_unsafe_name`, `stored_unsafe_name_saves`, `stored_unsafe_name_send`, `mail_from_prose_name` | modules/cabana/mail_site_name_postgres_test.go (Task 3) |
| Gate entries | GO_TESTS: `./modules/postcard:` TestMailSafetySmoke, TestSiteNameSend, TestUnsafeSiteNameDropped, TestUnsafeText, TestURLSchemeCheck, TestInlineUnsafeOutput, TestFooterSiteNameLiteral; DOCKER_TESTS: `./modules/cabana:TestMailSiteNameSafety` | scripts/check-phase35.sh (Tasks 1-3) |
| Gate fix | `self_test_consumers` workspace-modfile case compares the planted consumer's go.mod with `cmp -s` (IN-03) | scripts/check-phase35.sh (Task 3) |
| Planning doc | 35-VALIDATION.md CR-01, WR-01, WR-05 rows, "CR-01 status" line, Manual-Only row for the Branding refusal, Wave 0 entries | Task 3, last commit |
## Follow-ups outside this plan (not planned here)
- `/msd-verify-work 35`: re-verification of the CR-01 gap, then the pending human items of 35-VERIFICATION.md.
- Plugin follow-up after the framework tag (sm-user-plugin, sm-paymentgateway-plugin), unchanged from 35-06/35-07.
- 35-REVIEW.md advisories WR-02, WR-03, WR-04, IN-01, IN-02, IN-04 stay outside this gap closure.

View File

@@ -0,0 +1,234 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 09
subsystem: mail
tags: [postcard, cabana, tests, gate, gap-closure, CR-01]
requires:
- phase: 35-08
provides: decoded URL-scheme check (unsafeMarkup), postcard.UnsafeText, render-time site-name drop, Branding 422, inliner fallback, literal footer
provides:
- named Docker-free regression tests for site names on the send path, the scheme check, the unsafe inlined result and the literal footer
- cabana Postgres test for the Branding refusal and names stored before the check
- check-phase35.sh requires every new name; IN-03 self-test compares the planted consumer's go.mod
- 35-VALIDATION.md CR-01, WR-01, WR-05 rows and the CR-01 status line
affects: [35-verify-work, mail, postcard, cabana]
actuals:
tokens: 9052
tasks: 3
commits: 5
plan_head_before: 8751f922307fe476961a5e97e1525b8bbff84c52
plan_head_after: fbbfce07024f162c30e8ce4d44a7e0984a7a4b46
tech-stack:
added: []
patterns:
- "Tests that pin shipped behaviour show they are not vacuous through mutation runs (break the rule, see the named test fail, restore with git checkout)"
- "Site-name tests are table subtests named <layout>/<source or case>/<render path>"
key-files:
created:
- modules/postcard/sitename_test.go
- modules/postcard/safety_test.go
- modules/cabana/mail_site_name_postgres_test.go
modified:
- modules/cabana/mail_screens_smoke_test.go
- scripts/check-phase35.sh
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
key-decisions:
- "The mail screens test env reads mail.from from its configuration (default noreply@example.test unchanged), so a mutate hook sets the sender; the plan assumed it already did"
patterns-established:
- "A Postgres test models data saved before a save-time check by writing the row through env.gdb and clearing it in t.Cleanup"
requirements-completed: [CR-01, WR-01, WR-05, D-13, D-14, D-21]
coverage:
- id: D1
description: "Prose site names from mail.from and Branding send on the default and system layouts on the file-version, override and override-failure fallback paths"
requirement: CR-01
verification:
- kind: unit
ref: "modules/postcard/sitename_test.go#TestSiteNameSend"
status: pass
human_judgment: false
- id: D2
description: "Unsafe site names are dropped on every render path with one value-free warning; editor validate and preview are not refused"
requirement: D-14
verification:
- kind: unit
ref: "modules/postcard/sitename_test.go#TestUnsafeSiteNameDropped"
status: pass
- kind: unit
ref: "modules/postcard/sitename_test.go#TestUnsafeText"
status: pass
human_judgment: false
- id: D3
description: "Anchored, decoded scheme check: prose passes, every URL-bearing attribute and encoded form refused, send and editor with inlining on and off"
requirement: WR-05
verification:
- kind: unit
ref: "modules/postcard/safety_test.go#TestURLSchemeCheck"
status: pass
human_judgment: false
- id: D4
description: "An inlined result that fails the check sends the style-block version with one warning per layout"
requirement: WR-05
verification:
- kind: unit
ref: "modules/postcard/safety_test.go#TestInlineUnsafeOutput"
status: pass
human_judgment: false
- id: D5
description: "Footer prints the site name literally and escaped; body argument stays Markdown"
requirement: WR-01
verification:
- kind: unit
ref: "modules/postcard/sitename_test.go#TestFooterSiteNameLiteral"
status: pass
human_judgment: false
- id: D6
description: "Branding 422 on site_name in en and pl, prose names save, stored unsafe names never block saves or sends, mail.from prose name shows"
requirement: D-13
verification:
- kind: integration
ref: "modules/cabana/mail_site_name_postgres_test.go#TestMailSiteNameSafety"
status: pass
human_judgment: false
- id: D7
description: "Branding refusal line under the Site name field in the embedded admin"
verification: []
human_judgment: true
rationale: "Visual; recorded as a Manual-Only row in 35-VALIDATION.md for /msd-verify-work 35"
duration: 31min
completed: 2026-11-14
status: complete
---
# Phase 35 Plan 09: Unit tests for the CR-01 site name safety fix Summary
**Seven named postcard tests and one cabana Postgres test pin the 35-08 fix (prose site names send on every render path, unsafe ones are dropped or refused at save, decoded scheme check, style-block fallback, literal footer). Fourteen mutation runs prove they are not vacuous, and `check-phase35.sh --all` requires every name and passes with Docker.**
## Performance
- **Duration:** 31 min
- **Started:** 2026-11-14T14:35:52Z
- **Completed:** 2026-11-14T15:07:06Z
- **Tasks:** 3
- **Files modified:** 6
## Accomplishments
- `TestSiteNameSend`, `TestUnsafeSiteNameDropped`, `TestUnsafeText` (Task 1, tracer) cover the verifier's regression on a small MapFS catalog. Subtests are named `<layout>/<source|case>/<file_version|override|override_fallback>`.
- `TestURLSchemeCheck` covers 5 accepts and 21 refuses, each refuse checked for its error text and for a snippet that points at the markup. It also covers the send path through `assertFileFallback` and the editor, each with inlining on and off. `TestInlineUnsafeOutput` uses plain and entity-encoded links and checks the per-layout warning key. `TestFooterSiteNameLiteral` covers the footer (Task 2).
- `TestMailSiteNameSafety` covers the admin side with six subtests: `refused_on_save` (en and pl), `prose_names_saved`, `preview_drops_unsafe_name`, `stored_unsafe_name_saves`, `stored_unsafe_name_send` and `mail_from_prose_name` (Task 3).
- IN-03: the self-test's workspace-modfile case now compares the planted consumer's go.mod with `cmp -s` against a copy taken before the run.
- 35-VALIDATION.md maps CR-01 (3 rows), WR-01 and WR-05, closes the open item with a "CR-01 status" line, and adds a Manual-Only row for the Branding refusal and the Wave 0 entry.
## Task Commits
1. **Task 1: site-name send tests (tracer)**: `e0016e0c` test(postcard): site names on the built-in layouts never stop a send
2. **Task 2: scheme check, unsafe inlined output, literal footer**: `446a77ef` test(postcard): decoded URL scheme check, unsafe inlined output and the literal footer
3. **Task 3: cabana test, IN-03, validation map**: `54617f78` test(cabana): unsafe Branding site names refused at save, stored ones never block saves or sends; `e54be76c` test(35): self-test compares the planted consumer's go.mod; `fbbfce07` docs(35): validation map for the site name safety gap
**Plan metadata:** recorded in the docs(35-09) completion commit.
## Required test names (scripts/check-phase35.sh)
- GO_TESTS (new): `./modules/postcard:` TestMailSafetySmoke, TestSiteNameSend, TestUnsafeSiteNameDropped, TestUnsafeText, TestURLSchemeCheck, TestInlineUnsafeOutput, TestFooterSiteNameLiteral
- DOCKER_TESTS (new): `./modules/cabana:TestMailSiteNameSafety`
## Gate output
`bash scripts/check-phase35.sh --all` exit 0, with the Docker daemon up (PHASE35_ALLOW_NO_DOCKER not used):
- PASS self-test (includes `PASS self-test workspace-modfile`), go (24 postcard top-level tests by name), consumers, admin, docs, marker, additive (8 packages against v0.6.3), docker (full `go test ./...`, 12 cabana top-level tests by name, no skips)
- "Phase 35 gate passed"
- `git status --porcelain` of sm-user-plugin and sm-paymentgateway-plugin was empty before and after; go.mod and go.sum unchanged
## Mutation runs (stand-ins for RED)
Each test was green on its first run, as expected for tests of shipped code. Each mutation was applied, run, and then restored with `git checkout -- <file>`:
| # | Mutation | Failing tests |
|---|----------|---------------|
| M1 | validateHTML checks dangerousScheme over the whole document (35-06 rule) | TestSiteNameSend (all 14 subtests), TestUnsafeText |
| M2 | UnsafeText always false | TestUnsafeText, TestUnsafeSiteNameDropped (handler, mail_from_source, ...) |
| M3 | scriptURLText without the scheme boundary | TestUnsafeText, TestSiteNameSend (mail_from) |
| M4 | site-name warning not rate-limited | TestUnsafeSiteNameDropped (warning count) |
| M5 | formaction, background, poster, xlink:href dropped from urlAttributes | TestURLSchemeCheck refuse/{button_formaction,table_background,video_poster,svg_xlink_href} |
| M6 | hasDangerousScheme keeps whitespace and case | TestURLSchemeCheck refuse/{href_space_mixed_case,tab_split,newline_split} |
| M7 | text tokens checked for schemes | TestURLSchemeCheck accept/prose_*, editor/*; TestSiteNameSend |
| M8 | an inlined result that fails the check stops the send | TestInlineUnsafeOutput/{plain,encoded} |
| M9 | footer partial renders text as Markdown | TestFooterSiteNameLiteral (all 6 layout cases, partial/text_literal) |
| M10 | Branding BeforeValidate accepts unsafe names | TestMailSiteNameSafety/refused_on_save |
| M11 | layouts get the Branding name unfiltered | TestMailSiteNameSafety/{preview_drops_unsafe_name,stored_unsafe_name_send} |
| M12 | settings refusal returned unlocalized | TestMailSiteNameSafety/refused_on_save |
| M13 | pre-35-08 behaviour (M1 + M11) | TestMailSiteNameSafety: 5 of 6 subtests, including stored_unsafe_name_saves |
| M14 | env mailer ignores mail.from (helper before the deviation) | TestMailSiteNameSafety/mail_from_prose_name |
| M15 | self-test: the modfile run appends to the planted consumer's go.mod | `refuse: self-test the modfile run wrote the planted consumer's go.mod` |
M11 alone leaves `stored_unsafe_name_saves` green, because the decoded check no longer reads text. A stored name could only refuse a save with both halves of the old code in place, which is what M13 restores.
## Files Created/Modified
- `modules/postcard/sitename_test.go`: TestSiteNameSend, TestUnsafeSiteNameDropped, TestUnsafeText, TestFooterSiteNameLiteral, fixture `siteNameMailer`
- `modules/postcard/safety_test.go`: TestURLSchemeCheck, TestInlineUnsafeOutput
- `modules/cabana/mail_site_name_postgres_test.go`: TestMailSiteNameSafety, helpers `storedSiteName`, `putInLanguage`, `moveWelcome`
- `modules/cabana/mail_screens_smoke_test.go`: env mailer From read from `mail.from` (deviation 1)
- `scripts/check-phase35.sh`: GO_TESTS/DOCKER_TESTS entries, IN-03 `cmp -s`
- `.planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md`
## Decisions Made
- The mail screens env takes its sender from `mail.from` in its configuration (see deviation 1).
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 3 - Blocking] The mail screens env ignored mail.from**
- **Found during:** Task 3 (`mail_from_prose_name`)
- **Issue:** `newMailScreensEnvWith` built the mailer with a hard-coded `From: "noreply@example.test"`, so the plan's "mail.from through the mutate hook" never reached the mailer.
- **Fix:** the env sets `mail.from` to `noreply@example.test` before `mutate` and builds the mailer with `cfg.String("mail.from")`. Every other mail test sees the same sender as before. This is a test-helper change, not production code. The full cabana Docker suite is green.
- **Files modified:** modules/cabana/mail_screens_smoke_test.go
- **Verification:** M14 above; `go test ./modules/cabana` (Docker) green
- **Committed in:** `54617f78`
**2. [Note] No production defects found**
- None of the new tests exposed a defect in the 35-08 code, so no `fix(...)` commits were needed. The prohibition on production changes holds: only test files, the gate script and the validation doc changed.
---
**Total deviations:** 1 auto-fixed (blocking, test helper), 1 note
**Impact on plan:** none on scope; the mail.from case runs in its own environment as planned.
## TDD Gate Compliance
Tasks 2 and 3 carry `tdd="true"`, but they pin code 35-08 already shipped, so no failing commit was possible (CLAUDE.md keeps every commit green). As the plan directs, the mutation runs M1-M15 above stand in for RED. Each one shows a named test failing against broken code and passing against the shipped code.
## Issues Encountered
- `gofmt -l` still lists modules/postcard/store_postgres_test.go and modules/cabana/mail_routes.go. Both predate this plan and were left alone, as in 35-08.
## Verification
- `go vet ./...` and `go test -short ./...` were green after every code commit. `go test ./modules/postcard` and `go test ./modules/cabana` (Docker) were green, and `check-phase35.sh --all` ran the full `go test ./...`.
- Acceptance greps: 3 `func Test` lines in sitename_test.go for Task 1 and 1 for the footer; 2 in safety_test.go; 1 in the cabana file; no `t.Skip` in the Docker-free files; 7 encoded-colon lines in safety_test.go; no non-comment `unsafe_name_current_behaviour` in modules/cabana; no non-comment `status --porcelain -- go.mod` and 1 `cmp -s` in `self_test_consumers`; 6 CR-01 lines, 2 WR-01/WR-05 lines and 1 "CR-01 status" line in 35-VALIDATION.md.
- Nothing pushed or tagged; no sibling repository changed.
## User Setup Required
None.
## Next Phase Readiness
- Ready for `/msd-verify-work 35`. It re-verifies the CR-01 gap, then runs the pending human items in 35-VERIFICATION.md (UAT test 1 re-run, scoped UAT test 8 re-run, real-inbox check, judgment-tier prohibitions) and the new Manual-Only row for the Branding refusal.
---
*Phase: 35-mail-templates-and-layouts-editor*
*Completed: 2026-11-14*
## Self-Check: PASSED

View File

@@ -0,0 +1,193 @@
# Phase 35: Mail templates and layouts editor - Context
**Gathered:** 2026-11-06
**Status:** Ready for planning
<domain>
## Phase Boundary
Administrators edit the mail the application sends from the admin panel, as in WinterCMS's Mail templates screen:
- Every template registered through `pact.HasMailTemplates` (and postcard's built-in mail) is listed.
- Each template, layout and partial can get a database override, and the override can be reset to the file version.
- Admins can create custom layouts.
- A Branding page holds structured colours and a logo.
- A shared image library holds uploaded images.
- Drafts can be previewed and test-sent.
postcard renders the override when one exists and the plugin's file otherwise, so mail that already works keeps working with no change to apps or plugins.
Not in this phase: mail driver/SMTP settings screens, MailBlocker, newsletters/bulk mail, a WYSIWYG mail body.
</domain>
<decisions>
## Implementation Decisions
### Placement and permissions
- **D-01:** The screens live **inside cabana**, as an internal pseudo-plugin. This is the same pattern as Administrators/Roles in 19.6.1 (`modules/cabana/backend_screens.go`, `modules/cabana/backendscreens/`). Every app gets them with no setup. postcard stays free of admin and cabana code; cabana (or a thin glue layer) supplies postcard with the DB-backed layer through an interface postcard defines.
- **D-02:** **Navigation: a "Mail" section in Settings**, with entries for Mail templates, Mail layouts, Mail partials, Mail branding and Mail images. Links use `pact.HasSettings`, as in 19.6.1 D-02. There is no top-level nav item.
- **D-03:** **Two permission codes**, registered by the cabana pseudo-plugin:
- `system.manage_mail_templates` covers the templates list/form, template preview and test send.
- `system.manage_mail_layouts` covers layouts, partials, Branding and the image library, because these change every mail.
Neither code is granted to any role by default (as in 19.6.1 D-04). Only superusers reach the screens until someone grants a code. The image library and its insert picker must also be usable from the template form by holders of `system.manage_mail_templates`, either read/pick only or with upload too (planner's call, stated in the plan). — **Reversibility:** costly — the codes end up stored in `backend_user_roles.permissions` / `backend_users.permissions` JSON on every install that grants them.
### Editing model: templates
- **D-04:** **A template override stores subject + Markdown body + layout.**
- The body stays Markdown with Go `html/template` variables (`{{ .name }}`), the same format as the file.
- The plain-text part is still derived from the body; there is no hand-written text part.
- The layout is a dropdown over all layouts (file and custom).
- Description stays file-owned and read-only.
- **D-05:** **Locale variants stay separate templates.** `activate.htm` and `activate-en.htm` are their own rows. The list has a locale column, parsed from the suffix convention postcard already uses, plus a locale filter. There is no grouping and no new locale model.
- **D-06:** **Reset to the file version** deletes the override row, on templates, file layouts and file partials alike.
- **D-07:** **Drift notice.** When an override is saved, it stores a hash of the file content it was based on. If the plugin file later changes (for example after a plugin upgrade), the override keeps winning, but the list and the form flag "file changed since override". The form offers a way to view the current file version (a diff if cheap) and the reset button. — **Reversibility:** costly — the hash column is part of the override table schema (migration).
### Editing model: layouts, Branding, partials
- **D-08:** **Layouts use the same override model as templates.**
- Every file layout is listed: postcard's built-in default plus plugin layouts such as sm-user-plugin `layouts/user.htm` and paymentgateway `layouts/paymentgateway.htm`.
- Each file layout can get a DB override with reset.
- Admins can also **create custom layouts** that exist only in the DB. Custom layouts can be deleted (not reset); deleting one still assigned to template overrides is refused, with a count of those templates.
- "Seeded predefined layouts" means a couple of framework-shipped file layouts, for example the existing default plus one or two more such as system/minimal (the planner picks the set). They are not rows copied into the DB at boot.
- **D-09:** **Layouts are edited in a new `codeeditor` form field type**, Winter-style, with syntax highlighting for HTML/CSS/text. It is added to cabana's field registry and to the admin SPA. The layout form has tabs for the HTML wrapper, the text wrapper and the CSS/header. The field type is reusable by later phases. — **Reversibility:** costly — a published field type name in `fields.yaml` that plugins may start using.
- **D-10:** **Branding page**, as in Winter's mail brand settings.
- It is a settings page (cabana settings model) with Winter's brand colour set: body/content background, text, link, the button primary/positive/negative colours, and header/footer colours.
- It also has a **logo** upload, exposed to layouts as `{{ .logoUrl }}`.
- The colours compile into the brand CSS slot that postcard already inlines.
- **D-11:** **Precedence: Branding replaces config brandCss.** While no Branding record has been saved, `mail.brandCss` from config is used, so existing apps are unchanged. Once Branding is saved, its compiled CSS replaces `mail.brandCss`. `mail.css` is unaffected and still applied.
- **D-12:** **Mail partials are in scope, with file + DB override like templates.**
- Files live at `views/mail/partials/<name>.htm` and are named `<plugin>::mail.partials.<name>`.
- Plugins declare them through a **new additive optional pact capability**. `pact.HasMailTemplates` is not changed: core plugins must not break.
- Partials are used from template bodies and layouts through a Go template call (the planner picks the exact syntax or helper).
- A few built-in partials ship with postcard (button, panel, table).
- Admins override and reset partials; editing them needs `system.manage_mail_layouts`.
— **Reversibility:** costly — a published pact capability and naming convention that plugins implement.
### Validation and send-time safety
- **D-13:** **Saves are validated.** Saving a template, layout or partial override parses it, test-renders it with the sample vars (D-15) and runs postcard's existing safety checks (script/iframe/object/embed, inline handlers, `javascript:`/`vbscript:`/`data:` URLs, CR/LF in the subject). Failures are field validation errors.
- **D-14:** **Fallback at send.** If an override still fails to render at send time (for example a variable missing at runtime), postcard logs the failure and sends the file version, so mail delivery doesn't stop. A template with no file (impossible for templates; custom layouts only) falls back to the default layout.
### Preview and test send
- **D-15:** **Sample variables**: plugins may add optional sample values to a template file. One option is a sample section in the INI header; another is an additive capability (planner's call). Variables without a sample render as a visible placeholder such as `[name]`. Existing template files work unchanged.
- **D-16:** **Live preview of the unsaved draft.** The template, layout and partial forms render the current draft through postcard with sample vars. The HTML part is shown in a **sandboxed iframe**, and a tab shows the plain-text part. Rendering happens on the server through postcard, so preview matches real sends.
- **D-17:** **Test send to my own address only.** A button sends the current draft (with sample vars) to the signed-in admin's email through the configured driver. It needs the same permission as editing that record and is rate-limited per admin. There is no free-text recipient field.
### Images
- **D-18:** **A shared mail image library.** A "Mail images" list stores images through `lagoon/attach` on the public disk. Any template, layout or partial can use them, and the Branding logo also uses this storage.
- **D-19:** **Delivery via absolute public URLs.** `<img src>` uses the attachment's absolute public URL, built from `storage.uploads.public_url` / `app.url`. No CID inline parts; postcard's `RenderedMessage` and drivers are unchanged.
- **D-20:** **An insert button in the editors.** A picker next to the markdown editor (template bodies) and the codeeditor (layouts/partials) inserts `![alt](url)` or `<img src="url" alt="">` for a chosen library image.
### Quality gates
- **D-21:** Unit tests are the last plan (project rule). They cover:
- override precedence and reset;
- drift detection;
- fallback at send;
- save validation;
- Branding precedence over config;
- the partial capability (boot errors, namespace rule);
- the permission split;
- the test-send recipient restriction and rate limit.
The postcard and cabana READMEs and the affected `docs/` pages are updated in the same commits as API/config/permission changes. The `admin/` changes regenerate `admin/openapi/admin.json` + `schema.d.ts` (`scripts/check-admin-openapi.sh`) and rebuild the committed `modules/boardwalk/dist` (`scripts/check-admin-dist.sh`).
### Planning-time amendments (2026-11-06, confirmed by the user after research)
- **D-22:** postcard, not cabana, owns the mail tables, their migrations (a framework set in `lagoon.migrationSets`, like `attach.Migrations`) and the per-send override lookup, because `queue:work` sends mail in a process where cabana never activates. cabana still owns the screens, permissions and controllers (D-01 otherwise unchanged).
- **D-23:** Every file template, layout and partial gets an index row (Winter `syncAll` style), synced from the file catalog at serve start. Reset (D-06) clears the override columns on that row instead of deleting it; custom layouts are still deleted.
- **D-24:** The Branding logo's absolute URL is built at send time from config (`storage.uploads.public_url` / `app.url`) through a config-based attach helper, not stored at save.
- **D-25:** postcard ships no built-in template; the templates list keeps the UI-SPEC empty-state text.
### Claude's Discretion
- Table names and schema (one overrides table per kind, or a shared one), as long as it is Postgres/GORM with gormigrate migrations owned by the cabana pseudo-plugin, or by postcard if the planner justifies it.
- Exact partial call syntax and the built-in partial set beyond button/panel/table.
- Which extra predefined file layouts ship (D-08).
- Whether the image picker on the template form needs `manage_mail_layouts` for uploads (D-03 note).
- How postcard learns about overrides: a lookup interface checked per send, or a cache invalidated on save. It must be correct with several app instances, so per-send lookup or explicit invalidation, never a stale boot-time snapshot.
- How the SPA codeeditor is built (the library choice needs a STACK.md/decision note per the dependency rule).
- The plan split (lean planning: present the count before writing PLAN.md files).
</decisions>
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Mail layer
- `modules/postcard/README.md` covers the current template/layout format, catalog, drivers, safety checks and config keys (`mail.css`, `mail.brandCss`).
- `modules/postcard/templates.go` and `modules/postcard/mailer.go` hold `Catalog.Register`, `Mailer.Send`, `Activate` and `BootPlugin`, which are the integration point for the override layer.
- `modules/postcard/assets/default.htm` is the built-in default layout (header `==` text `==` HTML).
- `modules/pact/capabilities.go` §`HasMailTemplates` (around line 1271) must stay unchanged; partials and samples go in new additive capabilities.
### Admin patterns
- `.planning/phases/19.6.1-backend-administrators-screen/19.6.1-CONTEXT.md` covers the cabana internal pseudo-plugin, permission codes registered by cabana, Settings placement via `pact.HasSettings`, and no default role grant.
- `modules/cabana/backend_screens.go` and `modules/cabana/backendscreens/` hold the internal pseudo-plugin and the YAML controllers to mirror.
- `modules/cabana/settings.go` holds the settings model pattern for the Branding page.
- `modules/cabana/field_markdown.go`, `modules/cabana/field_file.go` and `modules/cabana/field_type.go` are where the new `codeeditor` field and the image picker hook in.
- `admin/src/components/form/fields/` holds the SPA field widgets (MarkdownField, FileuploadField); the new CodeEditorField goes here.
- `.planning/notes/2026-10-07-embedded-admin-release-gate.md` is the dist rebuild gate for `admin/` changes.
### Storage and URLs
- `modules/lagoon/attach/bucket.go` provides `PublicURLBase` (`storage.uploads.public_url`) for absolute image URLs.
- `.planning/research/STACK.md` holds the decided dependency set; a code-editor JS library must be added here or in a decision note.
### Reference implementation (WinterCMS)
- `../examples/golem15-wintercms-starter` covers Winter's System → Mail templates/layouts/partials/brand settings (`modules/system/models/MailTemplate.php`, `MailLayout.php`, `MailPartial.php`, `MailBrandSetting.php`) for field sets and behaviour parity.
### Existing mail consumers (must keep working unchanged)
- `../sm-user-plugin/views/mail/` (including `layouts/user.htm` and the locale variants) and `../sm-paymentgateway-plugin/views/mail/` (including `layouts/paymentgateway.htm`).
</canonical_refs>
<code_context>
## Existing Code Insights
### Reusable Assets
- `postcard.Catalog` already parses the INI header + `==` file format and resolves layout aliases. Overrides should reuse the same parser so DB content and files share one format.
- postcard's safety checker (rendered-HTML rejection, header CR/LF) is reused for save validation (D-13) and preview.
- The cabana internal pseudo-plugin (19.6.1) has permission registration, Settings links and YAML controllers.
- The cabana settings model plus `settings_secret.go` patterns cover the Branding page.
- `lagoon/attach` handles uploads, public disk storage and `PublicURLBase`.
- The SPA's `PreviewView.vue` and `FormView.vue` are where the preview pane and test-send action go.
### Established Patterns
- Plugins can only register names in their own namespace (`<plugin>::mail.*`). Partials follow the same rule.
- Boot errors for missing files, duplicates and unknown aliases. The new partial capability fails the same way.
- Postgres only, GORM + per-plugin gormigrate migrations; YAML via `goccy/go-yaml`.
- Standard library first; any new dependency (code editor in the SPA) needs a research/decision note.
- A docs checker enforces that README/docs identifiers exist.
### Integration Points
- postcard's render path (`Mailer.Send`) consults an override source before the file catalog, with fallback per D-14.
- `postcard.Activate` / brand CSS resolution consults the Branding record (D-11).
- The cabana field registry plus the SPA `FieldRenderer.vue` gain `codeeditor`.
- `pact` gets an additive capability for partials (and possibly sample vars).
</code_context>
<specifics>
## Specific Ideas
- The user explicitly wants **both** Winter's structured Branding page (colours, logo) **and** codeeditor-based layouts, "as WinterCMS kind of has it".
- Winter parity is the guide for field sets (brand colours, template/layout/partial forms) and for keeping `system.manage_mail_templates` as the code name.
</specifics>
<deferred>
## Deferred Ideas
- Hand-written plain-text template parts (Winter's `content_text`), not needed now.
- A WYSIWYG/rich-editor mail body.
- CID-embedded inline images (only absolute URLs in v1).
- Test send to an arbitrary address.
- Mail driver/SMTP configuration screen in the admin.
### Reviewed Todos (not folded)
- **Port MailBlocker and the block-mail checkbox** (`.planning/todos/pending/mailblocker-with-mailing.md`): kept separate. It is a send-path feature owned by sm-user-plugin (MailBlocker table, check before send, `block_mail` checkbox) and stays a todo for later mail work.
</deferred>
---
*Phase: 35-mail-templates-and-layouts-editor*
*Context gathered: 2026-11-06*

View File

@@ -0,0 +1,91 @@
# Phase 35: Mail templates and layouts editor - Discussion Log
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
**Date:** 2026-11-06
**Phase:** 35-mail-templates-and-layouts-editor
**Areas discussed:** Placement & permissions, Editing model, Preview & test send, Images
---
## Todo cross-reference
| Option | Description | Selected |
|--------|-------------|----------|
| Keep it separate | MailBlocker stays a todo for the later mail work | ✓ |
| Fold it in | Widens the scope to sm-user-plugin and the send path | |
## Placement & permissions
| Option | Description | Selected |
|--------|-------------|----------|
| Inside cabana | Internal pseudo-plugin, the 19.6.1 pattern | ✓ |
| A new sm-mail-plugin | Opt-in plugin repo | |
| Inside postcard | postcard would depend on cabana | |
| Option | Description | Selected |
|--------|-------------|----------|
| Settings → Mail section | Winter-like, through pact.HasSettings | ✓ |
| Settings → System section | Next to Administrators/Roles | |
| Top-level nav item | | |
| Option | Description | Selected |
|--------|-------------|----------|
| One code | system.manage_mail_templates | |
| Two codes | templates + layouts | ✓ |
| Option | Description | Selected |
|--------|-------------|----------|
| system.manage_mail_templates + system.manage_mail_layouts | Winter-compatible | ✓ |
| mail.manage_templates + mail.manage_layouts | New namespace | |
## Editing model
| Option | Description | Selected |
|--------|-------------|----------|
| Subject + Markdown body + layout | Same as the file format | ✓ |
| Also a hand-written plain-text part | | |
| HTML body (rich editor) | | |
**Layout editing:** the options were a codeeditor field, a plain textarea, or structured fields. **User's choice (free text):** "I wonder if we could have both 3 and 1. WinterCMS kind of has it - it has 'Branding' section with structured fields for colors etc and codeeditor-based layouts." This became a Branding page plus codeeditor layouts.
| Option | Description | Selected |
|--------|-------------|----------|
| Defer partials | | |
| Include partials, file + DB | | ✓ |
| Question | Options | Selected |
|----------|---------|----------|
| Branding contents | Winter colours + logo / colours only / + free CSS | Winter colours + logo |
| Branding vs config | Branding replaces brandCss once saved / config wins / concatenate | Branding replaces once saved |
| Partials shape | Same pattern as templates / built-in only | Same pattern as templates |
| Branding & partials perms | Under manage_mail_layouts / own branding code | Under manage_mail_layouts |
| Plugin file layouts | Same override model / imported to DB at boot | Same override model |
| Drift after file change | Override wins + notice / silently | Override wins + notice |
| Locale variants | Own rows + locale column / grouped tabs | Own rows + locale column |
| Validation | On save + fallback at send / save only, strict at send | On save + fallback at send |
## Preview & test send
| Question | Options | Selected |
|----------|---------|----------|
| Preview | Live draft in a sandboxed iframe + text tab / saved only | Live draft in a sandboxed iframe |
| Sample vars | Optional file samples + placeholders / placeholders only / admin JSON | Optional file samples + placeholders |
| Test send | Own address / any address / none | Own address |
## Images
| Question | Options | Selected |
|----------|---------|----------|
| Storage | Shared mail image library / per-record attachments | Shared library |
| Delivery | Absolute public URLs / inline CID / per-image toggle | Absolute URLs |
| Placing | Insert button in the editor / copy URL | Insert button |
## Claude's Discretion
- Schema layout, partial call syntax, extra predefined layouts, the image picker permission detail, the override lookup/caching mechanism (must be multi-instance safe), the SPA code-editor library (needs a decision note), the plan split.
## Deferred Ideas
- Plain-text template parts, a WYSIWYG body, CID images, test send to any address, a mail driver settings screen.

View File

@@ -0,0 +1,282 @@
# Phase 35: Mail templates and layouts editor - Pattern Map
**Mapped:** 2026-11-06
**Files analyzed:** 27 (new + modified, from 35-RESEARCH.md "Recommended Project Structure" and Wave 0 gaps)
**Analogs found:** 24 / 27
Line numbers are from master at `9232dc1`. Phase 33 is editing cabana at the same time, so re-check `form_schema.go`, `http.go` and `crud.go` line numbers before executing.
## File Classification
| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
|---|---|---|---|---|
| `modules/postcard/store.go` (new: Migrations, tables, OverrideSource, index sync) | migration + service | CRUD / batch sync | `modules/lagoon/attach/migrations.go` + `modules/lagoon/ondatabase.go` | exact (migrations), role-match (sync) |
| `modules/postcard/mailer.go` (mod: Activate wires DB source, Send lookup + fallback) | service | request-response | itself, lines 92-109 | exact |
| `modules/postcard/templates.go` (mod: partials, samples, hashes, alias fallback) | service | transform | itself | exact |
| `modules/postcard/partials.go` (new) | utility | transform | `modules/postcard/templates.go` (execHTML + goldmark, lines ~343-372) | role-match |
| `modules/postcard/samples.go` (new) | utility | transform | `modules/postcard/templates.go` parseINI / parseTemplateFile | role-match |
| `modules/postcard/brand.go` (new) | utility | transform | `modules/postcard/templates.go` layout data (lines 358-372) | partial |
| `modules/postcard/editor.go` (new: exported read + Validate/Preview/SendDraft) | service | request-response | `modules/postcard/mailer.go` Send | role-match |
| `modules/postcard/assets/{system,minimal}.htm, partials/*.htm, brand.css.tmpl, sample.htm` | config/asset | file-I/O | `modules/postcard/assets/default.htm` | exact |
| `modules/pact/capabilities.go` (mod: HasMailPartials, RowStateCustomized/Outdated) | config (interface) | n/a | itself, lines 1055-1062 and ~1271 | exact |
| `modules/lagoon/migrations.go` (mod: add postcard set) | migration registry | batch | itself, lines 225-230 | exact |
| `modules/cabana/backend_screens.go` (mod: mail controllers, permissions, settings items) | provider (pseudo-plugin) | n/a | itself, lines 76-117 | exact |
| `modules/cabana/mail_admin.go` (new: models, controllers, hooks, record actions) | controller | CRUD | `modules/cabana/backend_users_admin.go` | exact |
| `modules/cabana/mail_routes.go` (new: preview, test send, image library) | controller (route) | request-response | `modules/cabana/field_markdown.go` (markdownPreview) + `http.go:342` | exact |
| `modules/cabana/field_codeeditor.go` etc. (codeeditor, colorpicker, mailimage, mailpreview) | config (field registry) | n/a | `modules/cabana/form_schema.go:24-51` | exact |
| Branding settings model (in mail_admin.go or settings registration) | model | CRUD singleton | `modules/cabana/settings.go` (lines 96-102, 186, 236-277) | exact |
| Image library host (AdminSingleton) | controller | CRUD singleton | `modules/cabana/singleton.go:41-80` | exact |
| `modules/cabana/backendscreens/controllers/mail{templates,layouts,partials,images}/config_{form,list,filter}.yaml` + `_*.htm` | config | n/a | `modules/cabana/backendscreens/controllers/users/*` | exact |
| `modules/cabana/backendscreens/models/mail*/{fields,columns}.yaml` | config | n/a | `modules/cabana/backendscreens/models/user/*` | exact |
| `admin/src/components/form/fields/CodeEditorField.vue` | component | event-driven | `admin/src/components/form/fields/RichEditorField.vue` (lazy editor) + `MarkdownField.vue` | role-match |
| `admin/src/components/form/fields/MailPreviewField.vue` | component | request-response | `admin/src/components/form/fields/MarkdownField.vue` | exact |
| `admin/src/components/form/fields/ColorPickerField.vue` | component | event-driven | `admin/src/components/form/fields/TextField.vue` | role-match |
| `admin/src/components/form/fields/MailImageField.vue`, `admin/src/components/mail/MailImagePicker.vue` | component | request-response | `admin/src/components/form/fields/FileuploadField.vue` | role-match |
| `admin/src/components/form/registry.ts` (mod) | config | n/a | itself, lines 36-90 | exact |
| `admin/src/components/form/codeeditor/editor.ts` | utility | event-driven | none (CodeMirror is new) | no analog |
| `admin/src/components/mail/insertImage.ts` | utility | transform | none | no analog |
| Go tests (`modules/postcard/*_test.go`, `modules/cabana/mail_*_test.go`) | test | n/a | `modules/cabana/administrators_harness_test.go:154`, `lagoon/postgres_test.go` | exact |
| `admin/tests/form/{codeeditor,mailpreview,insertImage}*.test.ts`, `admin/tests/browser/codeeditor.test.ts` | test | n/a | existing `admin/tests/form/*` markdown tests | role-match |
## Pattern Assignments
### `modules/postcard/store.go` (migration + DB-backed source)
**Analog:** `modules/lagoon/attach/migrations.go` (lines 1-40). Raw SQL statements inside a gormigrate migration, ID prefixed with a date stamp:
```go
var Migrations = []*gormigrate.Migration{
{
ID: "202609180001_create_system_files",
Migrate: func(tx *gorm.DB) error {
stmts := []string{
`CREATE TABLE system_files (
id SERIAL PRIMARY KEY,
...
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
)`,
`CREATE INDEX system_files_field_index ON system_files (field)`,
}
for _, stmt := range stmts {
if err := tx.Exec(stmt).Error; err != nil {
return err
```
Use the schema in 35-RESEARCH.md "Recommended schema" (Winter-style table names). Wire the index sync through `lagoon.OnDatabase` (`modules/lagoon/ondatabase.go:19-25`):
```go
func OnDatabase(app *backpack.App, fn func(sqlDB *sql.DB, gdb *gorm.DB) error) error
```
It runs immediately if the DB is already published, otherwise when Publish runs. Because lagoon imports postcard (for the migration set), postcard must not import lagoon. Look the `*gorm.DB` up through `backpack` (`app.Lookup`) at send time, or take the source through an interface that postcard defines (D-01).
### `modules/lagoon/migrations.go` (modified)
**Analog:** itself, `migrationSets` (lines 220-230):
```go
sets := []migrationSet{
{"summercms.attach", "system_files", attach.Migrations},
{"summercms.cabana", "backend admin", BackendAdminMigrations},
{DeferredHistoryID, "deferred bindings", DeferredBindingMigrations},
{QueueHistoryID, "queue", QueueMigrations(sqlDB)},
}
```
Add `{"summercms.postcard", "mail", postcard.Migrations},` and update the set list in `modules/lagoon/pending_test.go`.
### `modules/postcard/mailer.go` (modified)
**Analog:** itself, `Activate` lines 92-109:
```go
func Activate[P interface{ ID() string }](app *backpack.App, _ []P) error {
...
m := &mailer{catalog: NewCatalog(), driver: driver, opts: opts}
if err := app.Publish[Mailer](m); err != nil {
return fmt.Errorf("postcard: %w", err)
}
return nil
}
```
Do not change the `Mailer` interface: `../sm-paymentgateway-plugin/mail_smoke_test.go:56` implements it. Add the override lookup inside `(*mailer).Send`. Treat any lookup error as "no overrides" and log a rate-limited warning (Pitfall 7).
### `modules/pact/capabilities.go` (modified)
**Analog:** itself. Row states at lines 1055-1062:
```go
const (
RowStateDeleted RowState = "deleted"
RowStateNegative RowState = "negative"
RowStateDisabled RowState = "disabled"
)
```
Append `RowStateCustomized` and `RowStateOutdated` in the same style, and update `TestRowStateValues` and cabana's `rowStateOrder`. `HasMailTemplates` (lines ~1270-1275) stays as it is. Put `HasMailPartials` next to it, in the same three-method `fs.FS` + names shape.
### `modules/cabana/backend_screens.go` (modified)
**Analog:** itself, lines 76-117. Add exported permission and controller ID constants next to `PermissionManageUsers`/`AdministratorsControllerID` (lines 14-28). Extend:
```go
func (s *backendScreens) AdminControllers() []pact.AdminController {
return []pact.AdminController{usersAdmin{screens: s}, rolesAdmin{screens: s}}
}
func (*backendScreens) Permissions() []pact.Permission {
return []pact.Permission{
{Code: PermissionManageUsers, Tab: "backend::lang.permissions.tab_system", Label: "backend::lang.permissions.manage_users"},
```
Settings items follow the `pact.SettingsItem{Code, Label, Description, Category: "backend::lang.settings.category_system", Icon, Order, Permissions, Controller}` shape (lines 96-115). No role grants in code (D-03 / 19.6.1 D-04). The YAML is embedded through `//go:embed all:backendscreens` (line 38), so the new `controllers/mail*/` and `models/mail*/` directories are picked up with no extra wiring.
### `modules/cabana/mail_admin.go` (controller, CRUD)
**Analog:** `modules/cabana/backend_users_admin.go`.
**Struct + interface assertions** (lines 24-53):
```go
type usersAdmin struct {
screens *backendScreens
}
var (
_ pact.AdminController = usersAdmin{}
_ pact.AdminPermissioned = usersAdmin{}
_ pact.ListRowStates = usersAdmin{}
_ pact.FormBeforeUpdate = usersAdmin{}
_ pact.FormBeforeDelete = usersAdmin{}
_ pact.HasAdminRecordActions = usersAdmin{}
_ pact.AdminPartialData = usersAdmin{}
...
)
```
**Identity methods** (lines 55-63): `ID()`, `ModelName()`, `ConfigDir() "controllers/users"`, `RequiredPermissions()`, `NewRecord()`.
**Helpers to copy:** `db()` (109), `requestDB(ctx)` (122), `translator()` (130), `asBackendUser` type assertion (140).
**Row states** (178-193): Customized when `is_custom`, Outdated when `is_custom && base_hash != file_hash`.
```go
func (usersAdmin) ListRowStates(_ context.Context, _ *gorm.DB, records []any) ([][]pact.RowState, error) {
out := make([][]pact.RowState, len(records))
for i, record := range records {
user, err := asBackendUser(record)
if err != nil { return nil, err }
if user.DeletedAt.Valid { out[i] = append(out[i], pact.RowStateDeleted) }
...
```
**Hooks:** FormBeforeDelete (199) is the model for refusing deletion of an in-use layout (use `ForbiddenError`, Pitfall 9). FormRules (475) handles save validation. Record actions (325) cover Reset to default and Test send. PartialData (422) feeds the server-rendered `_info.htm` / drift partials. Parameterized messages are built with `backendMessageParams(ctx, tr, key, fallback, params)` (`account_tokens.go:206,227`), not with `localizeDetails`.
### `modules/cabana/mail_routes.go` (route, request-response)
**Analog:** `modules/cabana/field_markdown.go` lines 55-80 plus mounting at `modules/cabana/http.go:342`:
```go
g.Post("/markdown/preview", requireAjax(s.markdownPreview))
```
```go
type AdminMarkdownPreviewRequest struct { Markdown string `json:"markdown"` }
type AdminMarkdownPreviewResult struct { HTML string `json:"html"` }
func (s *service) markdownPreview(w http.ResponseWriter, r *http.Request) {
principal, ok := bouncer.User(r.Context())
if !ok || principal == nil || !principal.Backend {
WriteError(w, http.StatusUnauthorized, "unauthenticated", msgUnauthenticated)
return
}
if !tokenRouteGate(principal, w) { return }
var body AdminMarkdownPreviewRequest
```
Add an exported `AdminMail*Request/Result` pair per route, swag annotations, and a per-`mode` permission check. The 422 responses use fixed message constants (`msgMarkdownPreviewRefused` style) and never echo the renderer's error. Rate-limit test send with `cooler.Attempter` (`modules/cooler/cooler.go:68-73`). Afterwards run `scripts/check-admin-openapi.sh`.
### New field types (`form_schema.go` + `field_codeeditor.go`)
**Analog:** `modules/cabana/form_schema.go` lines 24-51:
```go
formFieldTypes = map[string]struct{}{
"text": {}, ... "richeditor": {}, "repeater": {}, "money": {}, "taglist": {},
}
formFieldKeys = map[string]struct{}{ ... "mode": {}, ... "separator": {}, "customTags": {}, }
```
Add `codeeditor`, `colorpicker`, `mailimage`, `mailpreview` to the types, and `language` and `mailImages` to the keys. If the Branding settings form uses colorpicker, add it to the settings refusal check at `settings.go:102` only for types that need to be refused.
### Branding settings model
**Analog:** `modules/cabana/settings.go`. Fields are decoded with `decodeFields(raw, types.refusing())` (line 96). The refused built-ins are `widget/partial/fileupload/permissioneditor` (line 102), so a Branding logo upload cannot use `fileupload` there and needs a `mailimage` URL field instead. The singleton row sits at PK 1 (line 186), and the first Put creates it (lines 236-277). Example registration: `modules/cabana/example_settings_test.go`.
### Image library host
**Analog:** `modules/cabana/singleton.go` lines 41-80. Implement `pact.AdminSingleton.SingletonRecord(ctx, db) (any, error)` with first-or-create. cabana already retries on a unique-index race (`uniqueViolation(err)` → `singletonRace{}`). Absolute URLs come from `attach.PublicURL` (`lagoon/attach/thumb.go:80-96`) and are prefixed with `app.url` when no `public_url` is set.
### YAML controllers and models
**Analog:** `modules/cabana/backendscreens/controllers/users/config_form.yaml`:
```yaml
name: backend::lang.user.name
form: ~/plugins/summercms/cabana/models/user/fields.yaml
modelClass: Backend\Models\User
defaultRedirect: summercms/cabana/users
create:
redirect: summercms/cabana/users/preview/:id
redirectClose: summercms/cabana/users
update:
redirect: summercms/cabana/users/update/:id
redirectClose: summercms/cabana/users/preview/:id
preview:
headerPartial: hint
recordActions: [activate, deactivate, restore]
messages: { create: ..., update: ..., saved: ..., deleteConfirm: ..., deleted: ..., edit: ..., preview: ... }
```
The siblings `config_list.yaml`, `config_filter.yaml` and `_hint.htm` cover lists, the Customized/Outdated filters and server partials. The partial allowlist is in `partial_render.go:105-118`.
### `admin/src/components/form/registry.ts` (modified)
**Analog:** itself. Add an import block (lines 38-62) and an entry in the `renderers` map (lines 79-90+):
```ts
const renderers = new Map<string, Component>([
['text', TextField],
...
['fileupload', FileuploadField],
['datepicker', DatepickerField],
```
Add `mailpreview` to `valueless` (`new Set<string>([RELATION_MANAGER, 'widget', 'partial', 'fileupload'])`) and the group-labelled types to `groupLabelledTypes`. Extend the phase-history header comment (lines 1-35) with a Phase 35 paragraph.
### `MailPreviewField.vue` / `CodeEditorField.vue`
**Analog:** `admin/src/components/form/fields/MarkdownField.vue` lines 1-70:
```ts
import { computed, onBeforeUnmount, ref, watch } from 'vue'
import { api } from '../../../api/client'
import { controlAttributes, controlClass, type FieldControlProps } from '../control'
const props = defineProps<FieldControlProps>()
const emit = defineEmits<{ 'update:modelValue': [value: string] }>()
const PREVIEW_DEBOUNCE_MS = 300
let sequence = 0 // drops stale answers: if (current !== sequence) return
...
const { data, error } = await api.POST('/markdown/preview', { body: { markdown: text.value } })
if (data) { sanitizedHtml.value = data.data.html } else { previewError.value = refusal(error) }
```
For the preview, copy the debounce, the sequence guard and the `refusal()` details extraction. Render into a `sandbox` iframe `srcdoc`, which the CSP comment allows. Never `v-html` the mail. For CodeEditorField, copy the lazy-import pattern of `RichEditorField.vue` (TipTap loaded on demand) to load `codeeditor/editor.ts`. Field components import only from `../control`, never from `registry.ts` (registry.ts lines 64-67, to avoid an import cycle). Keep Mod+Enter reaching the form (Pitfall 5).
### Go tests
**Analog:** `modules/cabana/administrators_harness_test.go:154` `newScreensEnv(t, extra ...party.Plugin)`. It builds compass config with the admin secret, `lagoon.Publish(app, adminSQL, gdb)`, phrasebook and `surf.Assemble`. Reuse it for `TestMailPermissions`, routes and lifecycle. For postcard Postgres tests, copy the TestMain from `modules/lagoon/postgres_test.go`, which uses `flag.Parse()` and `testing.Short()` per CLAUDE.md. Smoke-test naming follows `backend_screens_smoke_test.go`.
## Shared Patterns
### Backend auth gate on custom routes
**Source:** `modules/cabana/field_markdown.go:72-79` (`bouncer.User` + `principal.Backend` + `tokenRouteGate`). Mount with `requireAjax` for POSTs (`http.go:342`).
**Apply to:** all mail_routes.go handlers, plus a per-permission check against `PermissionManageMail*`.
### Error responses
**Source:** `WriteError(w, status, code, msgConst)` with fixed `msg*` constants (`field_markdown.go:53,74`). Use `ForbiddenError` for refusals and translated params via `backendMessageParams`.
**Apply to:** routes and hooks.
### HTML safety gate
**Source:** `modules/postcard/templates.go:25-26` and `modules/cabana/field_markdown.go:16-18,37-48` (identical regexes). Reuse them unchanged for draft validation, but report their false positives to the user (Pitfall 8).
### Embedded pseudo-plugin assets
**Source:** `backend_screens.go:35-74` (`//go:embed all:backendscreens`, `fs.Sub`).
### Docs/README and generated artifacts
Update READMEs for postcard and cabana in the same commit. Then run `scripts/check-admin-openapi.sh`, `scripts/check-admin-dist.sh` and `summer docs:build --check`.
## No Analog Found
| File | Role | Data Flow | Reason |
|---|---|---|---|
| `admin/src/components/form/codeeditor/editor.ts` | utility | event-driven | CodeMirror 6 is new. Use 35-RESEARCH.md "CodeMirror setup" (verified export names). Needs a STACK.md row and a decision note before install. |
| `admin/src/components/mail/insertImage.ts` | utility | transform | No Markdown-insertion helper exists. Use the RESEARCH Pitfall 4 rules (absolute URL, percent-encoding). |
| `modules/postcard/samples.go` placeholder walker | utility | transform | No `text/template/parse` walker exists in the repo. Use the RESEARCH "Placeholder walker" prototype. |
## Metadata
**Analog search scope:** modules/postcard, modules/cabana (+ backendscreens), modules/lagoon (+ attach), modules/pact, admin/src/components/form
**Files scanned:** ~20
**Pattern extraction date:** 2026-11-06

View File

@@ -0,0 +1,705 @@
# Phase 35: Mail templates and layouts editor - Research
**Researched:** 2026-11-06
**Domain:** postcard mail rendering with a database override layer, cabana YAML admin screens, a CodeMirror 6 field in the Vue admin SPA
**Confidence:** HIGH for the codebase facts and integration points, MEDIUM for the recommended designs (they rest on verified facts but are proposals)
<user_constraints>
## User Constraints (from CONTEXT.md)
### Locked Decisions
#### Placement and permissions
- **D-01:** The screens live **inside cabana**, as an internal pseudo-plugin. This is the same pattern as Administrators/Roles in 19.6.1 (`modules/cabana/backend_screens.go`, `modules/cabana/backendscreens/`). Every app gets them with no setup. postcard stays free of admin and cabana code; cabana (or a thin glue layer) supplies postcard with the DB-backed layer through an interface postcard defines.
- **D-02:** **Navigation: a "Mail" section in Settings**, with entries for Mail templates, Mail layouts, Mail partials, Mail branding and Mail images. Links use `pact.HasSettings`, as in 19.6.1 D-02. There is no top-level nav item.
- **D-03:** **Two permission codes**, registered by the cabana pseudo-plugin:
- `system.manage_mail_templates` covers the templates list/form, template preview and test send.
- `system.manage_mail_layouts` covers layouts, partials, Branding and the image library, because these change every mail.
Neither code is granted to any role by default (as in 19.6.1 D-04). Only superusers reach the screens until someone grants a code. The image library and its insert picker must also be usable from the template form by holders of `system.manage_mail_templates`, either read/pick only or with upload too (planner's call, stated in the plan). — **Reversibility:** costly — the codes end up stored in `backend_user_roles.permissions` / `backend_users.permissions` JSON on every install that grants them.
#### Editing model: templates
- **D-04:** **A template override stores subject + Markdown body + layout.**
- The body stays Markdown with Go `html/template` variables (`{{ .name }}`), the same format as the file.
- The plain-text part is still derived from the body; there is no hand-written text part.
- The layout is a dropdown over all layouts (file and custom).
- Description stays file-owned and read-only.
- **D-05:** **Locale variants stay separate templates.** `activate.htm` and `activate-en.htm` are their own rows. The list has a locale column, parsed from the suffix convention postcard already uses, plus a locale filter. There is no grouping and no new locale model.
- **D-06:** **Reset to the file version** deletes the override row, on templates, file layouts and file partials alike.
- **D-07:** **Drift notice.** When an override is saved, it stores a hash of the file content it was based on. If the plugin file later changes (for example after a plugin upgrade), the override keeps winning, but the list and the form flag "file changed since override". The form offers a way to view the current file version (a diff if cheap) and the reset button. — **Reversibility:** costly — the hash column is part of the override table schema (migration).
#### Editing model: layouts, Branding, partials
- **D-08:** **Layouts use the same override model as templates.**
- Every file layout is listed: postcard's built-in default plus plugin layouts such as sm-user-plugin `layouts/user.htm` and paymentgateway `layouts/paymentgateway.htm`.
- Each file layout can get a DB override with reset.
- Admins can also **create custom layouts** that exist only in the DB. Custom layouts can be deleted (not reset); deleting one still assigned to template overrides is refused, with a count of those templates.
- "Seeded predefined layouts" means a couple of framework-shipped file layouts, for example the existing default plus one or two more such as system/minimal (the planner picks the set). They are not rows copied into the DB at boot.
- **D-09:** **Layouts are edited in a new `codeeditor` form field type**, Winter-style, with syntax highlighting for HTML/CSS/text. It is added to cabana's field registry and to the admin SPA. The layout form has tabs for the HTML wrapper, the text wrapper and the CSS/header. The field type is reusable by later phases. — **Reversibility:** costly — a published field type name in `fields.yaml` that plugins may start using.
- **D-10:** **Branding page**, as in Winter's mail brand settings.
- It is a settings page (cabana settings model) with Winter's brand colour set: body/content background, text, link, the button primary/positive/negative colours, and header/footer colours.
- It also has a **logo** upload, exposed to layouts as `{{ .logoUrl }}`.
- The colours compile into the brand CSS slot that postcard already inlines.
- **D-11:** **Precedence: Branding replaces config brandCss.** While no Branding record has been saved, `mail.brandCss` from config is used, so existing apps are unchanged. Once Branding is saved, its compiled CSS replaces `mail.brandCss`. `mail.css` is unaffected and still applied.
- **D-12:** **Mail partials are in scope, with file + DB override like templates.**
- Files live at `views/mail/partials/<name>.htm` and are named `<plugin>::mail.partials.<name>`.
- Plugins declare them through a **new additive optional pact capability**. `pact.HasMailTemplates` is not changed: core plugins must not break.
- Partials are used from template bodies and layouts through a Go template call (the planner picks the exact syntax or helper).
- A few built-in partials ship with postcard (button, panel, table).
- Admins override and reset partials; editing them needs `system.manage_mail_layouts`.
— **Reversibility:** costly — a published pact capability and naming convention that plugins implement.
#### Validation and send-time safety
- **D-13:** **Saves are validated.** Saving a template, layout or partial override parses it, test-renders it with the sample vars (D-15) and runs postcard's existing safety checks (script/iframe/object/embed, inline handlers, `javascript:`/`vbscript:`/`data:` URLs, CR/LF in the subject). Failures are field validation errors.
- **D-14:** **Fallback at send.** If an override still fails to render at send time (for example a variable missing at runtime), postcard logs the failure and sends the file version, so mail delivery doesn't stop. A template with no file (impossible for templates; custom layouts only) falls back to the default layout.
#### Preview and test send
- **D-15:** **Sample variables**: plugins may add optional sample values to a template file. One option is a sample section in the INI header; another is an additive capability (planner's call). Variables without a sample render as a visible placeholder such as `[name]`. Existing template files work unchanged.
- **D-16:** **Live preview of the unsaved draft.** The template, layout and partial forms render the current draft through postcard with sample vars. The HTML part is shown in a **sandboxed iframe**, and a tab shows the plain-text part. Rendering happens on the server through postcard, so preview matches real sends.
- **D-17:** **Test send to my own address only.** A button sends the current draft (with sample vars) to the signed-in admin's email through the configured driver. It needs the same permission as editing that record and is rate-limited per admin. There is no free-text recipient field.
#### Images
- **D-18:** **A shared mail image library.** A "Mail images" list stores images through `lagoon/attach` on the public disk. Any template, layout or partial can use them, and the Branding logo also uses this storage.
- **D-19:** **Delivery via absolute public URLs.** `<img src>` uses the attachment's absolute public URL, built from `storage.uploads.public_url` / `app.url`. No CID inline parts; postcard's `RenderedMessage` and drivers are unchanged.
- **D-20:** **An insert button in the editors.** A picker next to the markdown editor (template bodies) and the codeeditor (layouts/partials) inserts `![alt](url)` or `<img src="url" alt="">` for a chosen library image.
#### Quality gates
- **D-21:** Unit tests are the last plan (project rule). They cover:
- override precedence and reset;
- drift detection;
- fallback at send;
- save validation;
- Branding precedence over config;
- the partial capability (boot errors, namespace rule);
- the permission split;
- the test-send recipient restriction and rate limit.
The postcard and cabana READMEs and the affected `docs/` pages are updated in the same commits as API/config/permission changes. The `admin/` changes regenerate `admin/openapi/admin.json` + `schema.d.ts` (`scripts/check-admin-openapi.sh`) and rebuild the committed `modules/boardwalk/dist` (`scripts/check-admin-dist.sh`).
### Claude's Discretion
- Table names and schema (one overrides table per kind, or a shared one), as long as it is Postgres/GORM with gormigrate migrations owned by the cabana pseudo-plugin, or by postcard if the planner justifies it.
- Exact partial call syntax and the built-in partial set beyond button/panel/table.
- Which extra predefined file layouts ship (D-08).
- Whether the image picker on the template form needs `manage_mail_layouts` for uploads (D-03 note).
- How postcard learns about overrides: a lookup interface checked per send, or a cache invalidated on save. It must be correct with several app instances, so per-send lookup or explicit invalidation, never a stale boot-time snapshot.
- How the SPA codeeditor is built (the library choice needs a STACK.md/decision note per the dependency rule).
- The plan split (lean planning: present the count before writing PLAN.md files).
### Deferred Ideas (OUT OF SCOPE)
- Hand-written plain-text template parts (Winter's `content_text`), not needed now.
- A WYSIWYG/rich-editor mail body.
- CID-embedded inline images (only absolute URLs in v1).
- Test send to an arbitrary address.
- Mail driver/SMTP configuration screen in the admin.
#### Reviewed Todos (not folded)
- **Port MailBlocker and the block-mail checkbox** (`.planning/todos/pending/mailblocker-with-mailing.md`): kept separate. It is a send-path feature owned by sm-user-plugin (MailBlocker table, check before send, `block_mail` checkbox) and stays a todo for later mail work.
</user_constraints>
<phase_requirements>
## Phase Requirements
No REQUIREMENTS.md IDs are mapped to this phase (ROADMAP: "Requirements: TBD"). The related shipped requirement is **I18N-03** ("Plugins register mail templates and layouts by dotted name with the per-locale suffix convention, rendered with html/template and sent through a driver interface (SMTP via go-mail)"), which this phase must keep satisfied. The table maps the locked decisions to the research findings that enable them.
| ID | Decision | Research Support |
|----|----------|------------------|
| D-01 | Screens inside cabana; postcard defines the interface | Pattern 1 (store split), Pattern 2 (index rows); cabana pseudo-plugin facts |
| D-02 | Settings → Mail entries | `pact.SettingsItem.Controller` link entries; UI-SPEC C14 |
| D-03 | Two permission codes, no default grants | `pact.Permission` with empty `Roles`; `cabana.Allows` any-of semantics for the picker |
| D-04 | Override = subject + body + layout | Schema; FormBeforeUpdate/FormAfterUpdate ordering (Pitfall 6) |
| D-05 | Locale column/filter | Locale parsing rule (Pattern 2) |
| D-06 | Reset | Record action `reset` that clears the override columns (Open Question 1) |
| D-07 | Drift hash | `file_hash` vs `base_hash`; stdlib LCS diff (Don't Hand-Roll note) |
| D-08 | File layouts + custom layouts + predefined layouts | Index rows; built-in alias fallback; FK RESTRICT for in-use refusal |
| D-09 | `codeeditor` field type | Built-in type list changes; CodeMirror 6 packages, keymap pitfall |
| D-10/D-11 | Branding page and precedence | Settings model facts; brand CSS compiled by postcard; per-send brand lookup |
| D-12 | Partials capability | `pact.HasMailPartials` design; placeholder substitution (verified goldmark behaviour) |
| D-13 | Save validation | postcard draft-validation API; parameterized messages (Pitfall 9) |
| D-14 | Fallback at send | Per-send lookup + render retry without overrides |
| D-15 | Sample vars | INI `sample.*` keys (backward compatible) + verified placeholder walker |
| D-16 | Live preview | Preview route; srcdoc sandbox is allowed by the admin CSP |
| D-17 | Test send to self, rate-limited | Principal has no email; limiter reachability (Pattern 7) |
| D-18/D-19/D-20 | Image library, absolute URLs, insert button | attach URL facts; worker-process URL pitfall (Pitfall 4) |
| D-21 | Tests and gates | Validation Architecture |
</phase_requirements>
## Project Constraints (from CLAUDE.md)
- Standard library first. A new dependency needs a research doc or a phase/decision note naming it (`.planning/research/STACK.md`). The CodeMirror packages need a STACK.md "Admin SPA (npm) additions" row and a decision note written **before** the plan task that installs them.
- YAML is parsed with `goccy/go-yaml`, never `gopkg.in/yaml.v3`.
- Postgres only; GORM plus per-plugin gormigrate migrations. AutoMigrate is not the schema source.
- No runtime plugin loading.
- A change to a module's exported API, config keys, CLI commands or dependencies updates that module's `README.md` and the affected `docs/` pages **in the same commit**. Every identifier in a README or docs page must exist in the package (docs checker). Config keys are reviewed by hand.
- Framework code never names a consuming application (READMEs, docs and examples use neutral names such as `blog` or `acme`).
- A new module needs a beach name, a README in the standard structure and a root README row. (This phase should not need a new module; see Pattern 1.)
- Before tagging a release that changes `admin/`: rebuild, commit `modules/boardwalk/dist`, pass `scripts/check-admin-dist.sh`.
- `TestMain` functions that start containers call `flag.Parse()` and check `testing.Short()`.
- Keep `go vet ./...` and `go test ./...` green at every commit.
- Lean planning: few large plans; present the plan count with a one-line scope each and wait for confirmation. **Unit tests are the last plan.**
- Update STATE.md only through `msd_run query state.*` handlers. g15office sync on phase advance.
- No co-author tags. One logical change per commit; planning docs and code in separate commits. Stage files by path; several sessions work in this repo (Phase 33 is executing and recently touched cabana: `4cd35c9 feat(cabana): per-request options for plugin field types`).
- No push, tag or deploy without the user's go-ahead.
- Core plugins (user, blog, pages, payment) must not get breaking changes: `pact.HasMailTemplates`, `postcard.Catalog.Register` and `postcard.Mailer` keep their exact signatures.
## Summary
postcard today is an in-memory catalog: `Catalog.Register` reads each plugin's `views/mail/*.htm` at boot, and `Mailer.Send` renders a template (Markdown body through `html/template`, then goldmark) inside a layout, puts `mail.brandCss` + `mail.css` into the layout's `<style>` block and hands the result to a driver. There is no database layer, no partial support, no exported way to read the catalog or render a draft, and the published `Mailer` is an unexported `*mailer`. The phase adds all of these.
Three verified facts drive the design. First, the admin is GORM-row-based: list search/sort/filter are SQL over model columns (`query.go`), record IDs are numeric (`pathID` → `uint`), and dropdown/relation options come from rows. File templates therefore need **index rows** (Winter's `MailTemplate::syncAll()` approach) to be listed and opened at all. Second, `cabana.Activate` only runs when `serve` assembles the router, while mail is also sent from `queue:work` (a separate process when `queue.work_in_serve` is false). An override reader supplied by cabana would be absent there, so **postcard should own the read path and the schema**, wired in `postcard.Activate`, with the migrations declared in `lagoon.migrationSets` exactly like `attach.Migrations`. cabana writes the same tables through its admin models. Third, goldmark (default config, as postcard uses it) replaces raw HTML with `<!-- raw HTML omitted -->`, so a partial that emits HTML into a Markdown body would disappear. Partials in bodies need **placeholder substitution after Markdown conversion**.
The rest is mostly wiring through existing seams: Settings link entries and permissions as in 19.6.1, record actions for reset, `ForbiddenError` for the in-use delete refusal, settings model for Branding, `AdminSingleton` + `fileupload` for the image library, and new built-in field types. The UI-SPEC already fixes the SPA contract. On the SPA side the main risk is CodeMirror's `defaultKeymap` binding `Mod-Enter`, which conflicts with the form's save hotkey.
**Primary recommendation:** postcard owns the mail tables (lagoon-declared migration set `summercms.postcard`), a per-send `OverrideSource` lookup with full-file fallback, the partial capability with post-Markdown placeholder substitution, INI `sample.*` keys plus a parse-tree placeholder walker, brand CSS compilation, and an exported editor API (catalog read, draft validate/render/send). cabana adds the screens over those tables, syncing index rows from the catalog at serve start. The SPA adds CodeMirror 6 (six exact-pinned packages plus `@lezer/highlight`), lazily loaded.
## Architectural Responsibility Map
The tiers here are: the postcard module (mail domain), lagoon (migration registry), the cabana module (admin API), the Vue admin SPA (browser), and Postgres.
| Capability | Primary Tier | Secondary Tier | Rationale |
|------------|-------------|----------------|-----------|
| File catalog (templates, layouts, partials, samples, hashes) | postcard | — | Already parses files at boot; one format for files and overrides |
| Override tables and migrations | postcard (DDL), declared in lagoon `migrationSets` | Postgres | Read path must exist in every process; `attach.Migrations` precedent |
| Send-time override lookup + fallback (D-11, D-14) | postcard | Postgres | Runs in serve, `queue:work` and console commands; cabana is absent from the latter two |
| Brand CSS compilation | postcard (pure function) | cabana (calls it for preview) | Send path and preview must compile identically |
| Draft validation / preview render / test send | postcard (exported editor API) | cabana (HTTP routes, permission, rate limit) | Preview must match real sends (D-16) |
| Index row sync (file → rows) | postcard (function) | cabana (calls it at serve start) | Only the admin needs rows; the catalog is immutable after boot |
| Mail screens, permissions, settings entries, record actions | cabana pseudo-plugin | — | D-01, 19.6.1 pattern |
| Image library storage and absolute URLs | lagoon/attach | cabana (library endpoints), postcard (logo URL) | Public disk; worker processes have no bucket open (Pitfall 4) |
| Code editor, colour picker, preview pane, picker | Admin SPA | cabana (schema + routes) | UI-SPEC C1-C15 |
| Partial capability contract | pact | postcard (`BootPlugin`) | Additive interface; `HasMailTemplates` unchanged |
## Standard Stack
### Core (all already in the module graph; no new Go dependency)
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| `html/template`, `text/template`, `text/template/parse` | Go 1.27.2 stdlib | Rendering; parse-tree walk for sample placeholders | Already postcard's renderer [VERIFIED: modules/postcard/templates.go:7,12] |
| `crypto/sha256` | stdlib | D-07 file hash | Stdlib first |
| `github.com/yuin/goldmark` | v1.8.6 | Markdown body → HTML | Already pinned [VERIFIED: go.mod `github.com/yuin/goldmark v1.8.6`] |
| `gorm.io/gorm`, `github.com/go-gormigrate/gormigrate/v2` | as pinned | Override store, migrations | Already imported by `pact` [VERIFIED: `go list` imports of modules/pact] |
| `lagoon/attach` | in-repo | Image library on the public disk | D-18; imports only backpack/compass/diary, so postcard can import it without a cycle [VERIFIED: `go list` of modules/lagoon/attach] |
| `cooler` | in-repo | Shared fixed-window counter type (`cooler.Attempter`) for the test-send limit | Same semantics as surf's limiter, Redis-backed when configured [VERIFIED: modules/cooler/cooler.go:68-73] |
### Admin SPA (new npm runtime dependencies)
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| `@codemirror/state` | 6.7.6 (2026-09-22) | Editor state | `codeeditor` field |
| `@codemirror/view` | 6.43.15 (2026-10-19) | EditorView, keymap, lineNumbers, MatchDecorator, ViewPlugin | `codeeditor` field |
| `@codemirror/language` | 6.13.1 (2026-10-07) | bracketMatching, HighlightStyle, syntaxHighlighting | `codeeditor` field |
| `@codemirror/commands` | 6.11.1 (2026-09-15) | history, historyKeymap, defaultKeymap | `codeeditor` field |
| `@codemirror/lang-html` | 6.4.12 (2026-08-04) | `html()` grammar | `language: html` |
| `@codemirror/lang-css` | 6.3.1 (2024-11-26) | `css()` grammar | `language: css` |
| `@lezer/highlight` | 1.2.5 | `tags` for `HighlightStyle.define` | Imported directly by the theme, so pin it as a direct dependency (UI-SPEC lists it only as transitive) |
Versions, licenses and dates: [VERIFIED: npm registry, `npm view <pkg> version license repository.url` and `npm view <pkg> time`, 2026-11-06]. Exports `MatchDecorator`, `ViewPlugin`, `lineNumbers`, `lineWrapping`, `contentAttributes`, `keymap` (view); `bracketMatching`, `HighlightStyle`, `syntaxHighlighting` (language); `defaultKeymap`, `historyKeymap`, `history`, `indentWithTab`, `standardKeymap` (commands); `html` / `css`; `tags` (@lezer/highlight). [VERIFIED: `npm pack` of each pinned version, grep of `package/dist/index.d.ts`]
### Alternatives Considered
| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| CodeMirror 6 modular packages | `codemirror` meta package (`basicSetup`) | Pulls search, lint and autocomplete UI; UI-SPEC forbids it |
| CodeMirror 6 | Monaco / Ace / textarea overlay | Rejected in UI-SPEC (size and workers / accessibility / caret sync) |
| Stdlib LCS line diff (D-07) | `github.com/aymanbagabas/go-udiff` v0.4.1 | Only a test-time transitive dependency today (via charm `x/exp/golden`) [VERIFIED: `go mod why -m`]; using it directly is a new dependency needing a note. Inputs are small, so a bounded stdlib LCS is enough |
| postcard-owned read path | cabana-supplied `OverrideSource` | Missing in `queue:work` processes (Pattern 1) |
**Installation (SPA, after the decision note and STACK.md row are committed):**
```bash
npm --prefix admin install --save-exact @codemirror/state@6.7.6 @codemirror/view@6.43.15 @codemirror/language@6.13.1 @codemirror/commands@6.11.1 @codemirror/lang-html@6.4.12 @codemirror/lang-css@6.3.1 @lezer/highlight@1.2.5
```
## Package Legitimacy Audit
Run with `msd_run query package-legitimacy check --ecosystem npm …` on 2026-11-06. The package names come from the official CodeMirror documentation (codemirror.net examples import `@codemirror/view`, `@codemirror/commands`, `@codemirror/lang-*`) and the registry metadata. No package has a `postinstall` script (`npm view <pkg>@<ver> scripts.postinstall` empty for all).
| Package | Registry | Age | Downloads | Source Repo | Verdict | Disposition |
|---------|----------|-----|-----------|-------------|---------|-------------|
| @codemirror/state 6.7.6 | npm | 45 days | 22.6M/wk | code.haverbeke.berlin/codemirror/state | [OK] | Approved |
| @codemirror/view 6.43.15 | npm | 18 days | 23.1M/wk | code.haverbeke.berlin/codemirror/view | [SUS] (reason: `too-new`) | Flagged: planner adds a checkpoint |
| @codemirror/language 6.13.1 | npm | 30 days | 22.2M/wk | code.haverbeke.berlin/codemirror/language | [OK] | Approved |
| @codemirror/commands 6.11.1 | npm | 52 days | 21.2M/wk | code.haverbeke.berlin/codemirror/commands | [OK] | Approved |
| @codemirror/lang-html 6.4.12 | npm | 94 days | 12.0M/wk | code.haverbeke.berlin/codemirror/lang-html | [OK] | Approved |
| @codemirror/lang-css 6.3.1 | npm | ~2 yrs | 12.0M/wk | github.com/codemirror/lang-css | [OK] | Approved |
| @lezer/highlight 1.2.5 | npm | — | — | (maintainer marijn) | [OK] | Approved |
| @marijn/find-cluster-break (transitive of state) | npm | 77 days | 20.9M/wk | code.haverbeke.berlin/marijn/find-cluster-break | [OK] | Transitive only; not listed in the UI-SPEC's transitive list, so add it to the decision note |
Maintainer of every package: `marijn <marijn@haverbeke.berlin>` (lang-css also `adrianheine`). [VERIFIED: `npm view … maintainers`]
**Packages removed due to [SLOP] verdict:** none
**Packages flagged as suspicious [SUS]:** `@codemirror/view` 6.43.15, flagged only as "too-new" by the seam's threshold. It is past the project's 7-day cooldown (published 2026-10-19). The planner inserts `checkpoint:human-verify` before the install task: confirm the version (or pin 6.43.14 or older), and record the lockfile `dist.integrity` values in the decision note as the DOMPurify note did.
## Architecture Patterns
### System Architecture Diagram
```
┌──────────────── every process (serve, queue:work, console) ───────────────┐
plugin files ──boot──▶ postcard.Catalog (templates, layouts, partials, samples, sha256 per file) │
views/mail/**.htm │ │ │
+ postcard built-ins │ ▼ │
│ Mailer.Send(msg) ──▶ OverrideSource.MailOverrides(ctx, code) ──▶ Postgres │
│ │ (per send; DB from app.Lookup[*gorm.DB]) system_mail_*
│ ▼ │
│ render(file ⊕ overrides, brand) ──ok──▶ validate ──▶ Driver.Send │
│ │ error │
│ └──▶ log + render(file only, brand) ──▶ Driver.Send (D-14) │
└────────────────────────────────────────────────────────────────────────────┘
serve only:
serve start ──▶ lagoon.OnDatabase ──▶ postcard sync(catalog → index rows, ON CONFLICT upsert)
Admin SPA ──HTTP──▶ cabana generic CRUD (lists, forms, settings, singleton, record actions)
│ │ hooks: FormBeforeUpdate (stamp) / FormAfterUpdate (validate via postcard)
│ ▼
│ system_mail_templates / _layouts / _partials / _brand_settings / image library
├──POST /mail/preview ─────▶ cabana (permission per mode) ──▶ postcard editor: render draft ⊕ DB
├──POST /mail/test-send ───▶ cabana (permission, rate limit, admin email from backend_users)
│ └──▶ postcard editor: render draft ──▶ Driver.Send(to = self)
└──GET/POST /mail/images ──▶ cabana (either permission to list; layouts permission to upload)
└──▶ attach.Store (public) ──▶ absolute URL
```
### Recommended Project Structure
```
modules/postcard/
├── templates.go # existing: catalog, parser (+ partials, samples, hashes, built-in alias fallback)
├── mailer.go # existing: Send gains the override lookup and fallback; Activate wires the DB source
├── partials.go # new: partial func, placeholder substitution
├── samples.go # new: sample.* keys + parse-tree placeholder walker
├── brand.go # new: Brand struct, colour validation, CompileBrandCSS
├── store.go # new: Migrations, table constants, DB-backed OverrideSource, index sync
├── editor.go # new: exported catalog read + draft Validate/Preview/SendDraft
└── assets/ # default.htm (unchanged) + system.htm, minimal.htm, partials/{button,panel,table,subcopy}.htm, brand.css.tmpl, sample.htm
modules/pact/capabilities.go # + HasMailPartials, + RowStateCustomized/RowStateOutdated
modules/lagoon/migrations.go # + {"summercms.postcard", "mail", postcard.Migrations}
modules/cabana/
├── backend_screens.go # + mail controllers, permissions, settings items
├── mail_admin.go # new: models over postcard tables, controllers, hooks, record actions
├── mail_routes.go # new: preview, test send, image library endpoints (swag-annotated)
├── field_codeeditor.go … # new built-in types: codeeditor, colorpicker, mailimage, mailpreview
└── backendscreens/controllers/mail{templates,layouts,partials,images}/, models/mail*/
admin/src/components/form/fields/{CodeEditor,ColorPicker,MailImage,MailPreview}Field.vue
admin/src/components/form/codeeditor/editor.ts, admin/src/components/mail/{MailImagePicker.vue,insertImage.ts}
```
### Pattern 1: postcard owns the schema and the read path; cabana owns the screens
**What:** postcard defines `OverrideSource` (D-01's "interface postcard defines") **and** ships the default DB-backed implementation, installed by `postcard.Activate`. It reads `*gorm.DB` lazily per send through `app.Lookup[*gorm.DB]()`. The migrations are `postcard.Migrations`, appended to lagoon's framework sets. cabana defines its own GORM admin models over the same tables (by exported table-name constants), so postcard carries no admin code (no Fillable/Rules/YAML).
**Why this deviates from "cabana supplies the layer":** the evidence says a cabana-supplied source would not exist in every process that sends mail.
- `cabana.Activate` is called only from surf's router assembly: `admin, err := cabana.Activate(app, plugins)` [VERIFIED: modules/surf/router.go:680]. The pseudo-plugin is appended there, not in `party.Activate`: `plugins, screens := withBackendScreens(app, plugins)` [VERIFIED: modules/cabana/http.go:91].
- `queue:work` opens and publishes the DB itself (`sqlDB, gdb, err := lagoon.OpenFromApp(ctx, app)` … `if err := lagoon.Publish(app, sqlDB, gdb); err != nil {`) [VERIFIED: modules/conga/commands.go:402-412], and serve runs that worker in-process "unless queue.work_in_serve is false" [VERIFIED: modules/conga/commands.go:47-48]. Plugins send mail from River jobs.
- `postcard.Activate` runs in every process from `party.Activate`: `if err := postcard.Activate(app, ordered); err != nil {` [VERIFIED: modules/party/registry.go:132].
- The 19.6.1 pseudo-plugin "declares no migrations" and the backend tables live in lagoon: `{"summercms.cabana", "backend admin", BackendAdminMigrations},` [VERIFIED: modules/cabana/backend_screens.go:30-33; modules/lagoon/migrations.go:227].
- Module-owned framework set precedent: `{"summercms.attach", "system_files", attach.Migrations},` [VERIFIED: modules/lagoon/migrations.go:226]. lagoon importing postcard is cycle-free (postcard imports backpack, compass, diary, pact; lagoon already reaches postcard through party) [VERIFIED: `go list` imports].
**Rejected alternative:** register a cabana source from `cabana.RuntimeCommands(app)` (the only cabana call the generated `main.go` makes in every process) or from a package `init()` registry. Both rely on side effects of an unrelated call or of an import.
### Pattern 2: index rows synced from the catalog (Winter's `syncAll`)
**What:** every catalog entry has one row (`code` UNIQUE). For a non-customized row, the override columns mirror the file so that the generic list (search/sort), form (shows the file version) and relation dropdown work unchanged. postcard's send path reads only rows flagged customized; the "File version" tab and drift compare against the in-memory catalog, never the mirror.
**Why rows are needed:** the generic list query is `q := db.WithContext(ctx).Model(model)` with SQL search over model columns [VERIFIED: modules/cabana/query.go:112, 459-499], and record IDs must be integers (`n, err := strconv.ParseUint(raw, 10, 64)` … `"The id field must be an integer."`) [VERIFIED: modules/cabana/crud.go:1278-1284]. Winter does the same: `MailTemplates::index()` calls `MailTemplate::syncAll();` and non-custom rows are filled from the file in `afterFetch` (`if (!$this->is_custom) { $this->fillFromView($this->code); }`) [VERIFIED: examples/golem15-wintercms-starter/modules/system/controllers/MailTemplates.php:54; modules/system/models/MailTemplate.php:130-135].
**When to sync:** the catalog is immutable after boot, so once per serve start is enough. Register it through `lagoon.OnDatabase` from `cabana.Activate` ("runs fn … as soon as the database is available") [VERIFIED: modules/lagoon/ondatabase.go:19-25]. Use `INSERT … ON CONFLICT (code) DO UPDATE … WHERE NOT is_custom` for the mirror columns, and always refresh `file_hash`, `source` and `description`. If the tables are missing (migrations pending), log a warning and retry on the first list request. Never delete rows (a rolling deploy would churn IDs); hide entries absent from this process's catalog with `ListExtendQuery` (`code IN ?` OR database-only layouts).
**Locale column:** parse the last dotted segment's `-<suffix>`, and count it as a locale only when the suffix is one of the app's enabled locales (`activate-en` → `en`; `two_factor_code-en` → `en`; `canceledNotActive` → default). This avoids reading arbitrary dashed names as locales.
### Pattern 3: per-send override lookup with a full-file fallback (D-11, D-14)
**What:** `Send` asks the source once per message for everything the render needs, then renders. On any render or validation error with overrides applied, it logs (component `postcard`) and renders the pure file version, still applying Branding. If the DB is unavailable or a table is missing, it logs a warning (rate-limited) and renders the files. This is correct across instances by construction: there is no cache to invalidate. Mail volume is low, and the cost is three or four indexed reads in one read-only transaction.
```go
// Recommended shape (design, not existing code).
type OverrideSource interface {
// MailOverrides returns what one send of template needs: the template's
// override, its effective layout's override or database-only content,
// every partial override, and the saved Branding. A nil field means the
// file (or, for Brand, config mail.brandCss) wins.
MailOverrides(ctx context.Context, template string) (Overrides, error)
}
type Overrides struct {
Template *TemplateOverride // Subject, Body, Layout (full name or database-only code)
Layout *LayoutOverride // HTML, Text, CSS; set for a customized file layout or a database-only layout
Partials map[string]PartialOverride // full name -> HTML, Text
Brand *Brand // nil until the Branding page has been saved (D-11)
}
```
Keep `postcard.Mailer` unchanged, because outside code implements it: `func (r *mailRecorder) Send(ctx context.Context, msg postcard.Message) error` [VERIFIED: ../sm-paymentgateway-plugin/mail_smoke_test.go:56], `Send(ctx context.Context, msg postcard.Message) error` in an interface [VERIFIED: ../sm-paymentgateway-plugin/events/mailers.go:116], plus fakes in sm-user-plugin and fonoteka tests. Expose the new capability through additive API instead: an `Options.Overrides OverrideSource` field for `NewMailer` (tests), and a separately published editor service from `Activate`. `BootPlugin` already type-asserts the unexported mailer (`m, ok := got.(*mailer)`) [VERIFIED: modules/postcard/mailer.go:180]; the editor service can be reached the same way or published as its own concrete type. `backpack` refuses a second provider for the same type ("Publishing the same T twice is an error.") [VERIFIED: modules/backpack/services.go:20-21,35-36].
Caller subject precedence stays as it is: `if strings.TrimSpace(msg.Subject) != "" { subjectSrc = msg.Subject }` [VERIFIED: modules/postcard/templates.go:332-335]. No production caller sets `Message.Subject` [VERIFIED: grep of sm-*-plugin and fonoteka.go `postcard.Message{` literals], so an admin's subject override is effective everywhere today. Document the precedence in the README.
### Pattern 4: partials (D-12)
**Capability (additive):**
```go
// HasMailPartials is implemented by plugins that ship mail partials under
// views/mail/partials/<name>.htm, named <plugin>::mail.partials.<name>.
type HasMailPartials interface {
MailPartialsFS() fs.FS
MailPartials() []string
}
```
`BootPlugin` checks it next to `pact.HasMailTemplates`, whose definition stays byte-identical:
```go
type HasMailTemplates interface {
MailTemplatesFS() fs.FS
MailTemplates() []string
MailLayouts() map[string]string
}
```
[VERIFIED: modules/pact/capabilities.go:1271-1275]. The existing name→path mapping already gives the right file: `return assetRoot + strings.ReplaceAll(after, ".", "/") + ".htm", nil` with `assetRoot = "views/mail/"` [VERIFIED: modules/postcard/templates.go:21,216], so `x::mail.partials.button` → `views/mail/partials/button.htm`. Reuse `assertOwner` and the duplicate/missing errors for the same boot failures. The partial file format is the layout format (header `name =`, `==`, text section, `==`, HTML section), which is also Winter's (`partial-button.php`: `name = "Button"` / `==` / text / `==` / HTML) [VERIFIED: examples/golem15-wintercms-starter/modules/system/views/mail/partial-button.php].
**Call syntax (recommended):** `{{ partial "button" "url" .Link "body" "Activate" "type" "positive" }}`, a func `partial(name string, kv ...any)` taking key/value pairs. A bare name resolves to postcard's built-ins (`postcard::mail.partials.button`); plugin partials use the full name. Unknown name or odd kv count is a render error (D-13 maps it to `mail.invalid_partial`).
**Why placeholders:** postcard renders bodies as `execHTML` then `markdown.Convert` with `markdown = goldmark.New()` [VERIFIED: modules/postcard/templates.go:29,343-347]. Under goldmark v1.8.6 defaults, raw HTML is dropped: `"Hi\n\n<table>…</table>\n\nBye"` → `"<p>Hi</p>\n<!-- raw HTML omitted -->\n<p>Bye</p>\n"`, and a `template.HTML` returned by a template func inside a body comes out as `<!-- raw HTML omitted -->button<!-- raw HTML omitted -->` [VERIFIED: scratch program against goldmark v1.8.6 from the module cache, 2026-11-06]. Turning on `html.WithUnsafe` would change how every existing body renders, so don't.
**Flow:** in the body pass, `partial` renders the partial's text and HTML sections (html/template for HTML, text/template for text, with the kv map as data) and returns a token `MAILPARTIAL<nonce><n>`, using only `[A-Z0-9]` so neither html/template escaping nor goldmark emphasis touches it. Alphanumeric tokens survive goldmark (`"<p>SUMMERPARTIAL0X9F</p>"`) [VERIFIED: same scratch run]. After conversion, replace `<p>TOKEN</p>` and then bare `TOKEN` with the partial HTML in the HTML part, and the token with the partial text in the text part (the text part is the pre-Markdown body). Use a fresh random nonce per render so variable values cannot forge tokens. In layouts (pure html/template, no Markdown) `partial` returns `template.HTML` directly in the HTML wrapper and text in the text wrapper.
**Built-in set (recommended):** `button` (url, body, type primary/positive/negative), `panel` (body), `table` (body, a Markdown table rendered with goldmark plus `extension.Table` inside the partial helper only), `subcopy` (body). These are the colours the Branding table covers (`button_*`, `panel_bg`, `table_border_color`).
**Predefined layouts (D-08, recommended):** keep `default.htm` byte-identical and add `system` (Winter's "System layout" with its "automatic message" footer) and `minimal`. Make them reachable from plugin templates by a built-in alias fallback in `resolveLayoutLocked`: plugin aliases first, then built-in aliases. This only turns today's `unknown layout` boot errors into successes.
### Pattern 5: sample variables (D-15)
**Recommended mechanism: dotted INI keys in the existing header**, for example `sample.Name = "Ada"` and `sample.order.code = "ZAM-1"`. Old framework versions ignore them. Today's `parseINI` accepts any `key = value` line and `parseTemplateFile` reads only `subject`, `description` and `layout` [VERIFIED: modules/postcard/templates.go:228-235, 291-315]. A `[sample]` INI section would instead fail in every released postcard (`return nil, fmt.Errorf("invalid header line %q", line)`) [VERIFIED: templates.go:298-300].
**Case:** `parseINI` lower-cases keys (`key = strings.ToLower(strings.TrimSpace(key))`) [VERIFIED: templates.go:302], but template variables are case-sensitive (`{{ .Name }}`, `.bankDetailsLines` in consumer files). Keep the original case after the `sample.` prefix.
**Placeholders:** `missingkey=zero` renders a missing top-level key as empty (`[{{ .missing }}]` → `"[]"`), and a missing nested key fails: `executing "d" at <.order.code>: nil pointer evaluating interface {}.code` [VERIFIED: scratch run, Go 1.27.2]. Consumer templates use nested fields, `if .employee.first_name`, `range .order.items` with element fields and `range .banking_details.bankDetailsLines` printing `{{ . }}` [VERIFIED: grep of ../sm-paymentgateway-plugin/views/mail]. So preview and save validation need a parse-tree walker over `html/template`'s `Tree`. It turns every root field chain into nested maps with `"[a.b]"` leaves (or the sample), and every `range` target into a one-element slice built from the fields used inside the range body (a string placeholder when the body prints `{{ . }}`). The prototype in Code Examples renders the real paymentgateway shapes without error.
### Pattern 6: Branding (D-10, D-11)
- Settings forms are per-model singleton tables at primary key 1 (`Where(clause.Eq{… Value: 1}).Take(model)`), and the first Put creates the row (`if !exists { … tx.Create(model) }`) [VERIFIED: modules/cabana/settings.go:186, 236-277]. D-11's "saved" therefore means "row 1 exists". The image-library host must not be this row, or opening Mail images would silently switch apps off `mail.brandCss`.
- Settings forms refuse plugin field types (`decodeFields(raw, types.refusing())`) and these built-ins: `if field.Type == "widget" || field.Type == "partial" || field.Type == "fileupload" || field.Type == permissionFieldType {` [VERIFIED: modules/cabana/settings.go:96,102]. `colorpicker`, `mailimage` and `mailpreview` must be **built-in** cabana types, and `colorpicker`/`mailimage` must be added to `scalarFormField` so they bind to columns. That list is currently `"text", "textarea", "number", "checkbox", "switch", "dropdown", "datepicker", "markdown", "mltext", "mltextarea", "mlmarkdown", "richeditor", moneyType` [VERIFIED: modules/cabana/crud.go:1518-1525].
- The brand CSS is compiled by postcard from a CSS text/template (a port of Winter's `custom.less`, 304 lines [VERIFIED: wc of mailbrandsetting/custom.less]) after strict `^#[0-9a-f]{6}$` validation of each colour. Postcard puts CSS in the layout's `<style>` block (`<style type="text/css">{{ .brandCss }}{{ .css }}</style>`), it does not inline it into attributes [VERIFIED: modules/postcard/assets/default.htm:9]. The sm-user-plugin and paymentgateway layouts only carry `.layout-user` / `.layout-paymentgateway` wrappers [VERIFIED: their `views/mail/layouts/*.htm`]. So the compiled CSS must style generic elements (`body`, `a`, `h1`–`h3`, `p`, `table`) plus the built-in partial classes, otherwise Branding seems to do nothing in plugin layouts.
- Layout data today is exactly `"Content"`, `"Subject"`, `"css"`, `"brandCss"` [VERIFIED: modules/postcard/templates.go:358-372]. Add `"logoUrl"` (string; html/template sanitizes it in `src` attributes).
### Pattern 7: preview, test send, permissions, rate limit (D-16, D-17, D-03)
- Mount the routes like `/markdown/preview` (`g.Post("/markdown/preview", requireAjax(s.markdownPreview))`) [VERIFIED: modules/cabana/http.go:342], with swag annotations. Check permission per `mode`: template → `system.manage_mail_templates`; layout/partial/branding → `system.manage_mail_layouts`. Use `cabana.Allows`, which is any-of with a superuser bypass (`if principal.IsSuperuser || len(required) == 0 { return true }`) [VERIFIED: modules/cabana/contracts.go:327-343]. The image-library list calls `Allows(p, []string{templates, layouts})`; upload calls `Allows(p, []string{layouts})` (UI-SPEC recommendation: `canUpload` only for the layouts code).
- **Test-send recipient:** `bouncer.Principal` has `ID`, `IsSuperuser`, `PermissionGrants`, `Scope` but no email [VERIFIED: modules/bouncer/context.go:26-35]. Load `BackendUser.Email` by `principal.ID` [VERIFIED: modules/cabana/contracts.go:60-65] and never accept a recipient in the body. Restrict to interactive sessions (an `interactiveOnly` wrapper exists for account routes [VERIFIED: modules/cabana/http.go:333]).
- **Rate limit:** cabana cannot import surf, because surf imports cabana [VERIFIED: `go list` imports of modules/surf]. surf publishes its Redis-backed limiter only as `app.Publish[Store](…)` [VERIFIED: modules/surf/serve.go:237]. `cooler.Attempter` has "exactly the method set of surf.Store" [VERIFIED: modules/cooler/cooler.go:68-73]. Recommended: surf also publishes the resolved store as `cooler.Attempter` (one line where it publishes `Store`), and cabana looks it up with a small in-process fixed-window fallback (tests, memory store). Key `mail_test:<adminID>`; answer 429 with `Retry-After` as surf does.
- **Preview iframe:** the admin CSP is `"frame-ancestors 'none'; base-uri 'none'; object-src 'none'; script-src 'self'; form-action 'self'; frame-src 'none'"`, and its comment states that "a sandboxed srcdoc preview is not fetched, so it still renders" [VERIFIED: modules/boardwalk/boardwalk.go:61-66]. No CSP change is needed.
### Pattern 8: image library and absolute URLs (D-18-D-20)
- `attach.PublicURL` returns `strings.TrimRight(base, "/") + "/" + key` when `storage.uploads.public_url` is set, otherwise a root-relative path from `PublicPathPrefix()` [VERIFIED: modules/lagoon/attach/thumb.go:80-96]. Mail needs absolute URLs, so prefix `app.url` when the result starts with `/`. When neither is configured, refuse the upload/listing with a clear message.
- `PublicURLBase()` is a process global set by `OpenBucket` [VERIFIED: modules/lagoon/attach/bucket.go:42-55, 154-157]. `OpenBucket` is called only from `surf/serve.go:213` and `lagoon/commands.go:479` [VERIFIED: grep], not from `queue:work`. Any URL computed at send time in a separate worker would come out relative. Recommendation: the picker inserts the absolute URL into the content at edit time (D-20, which is text), and the logo URL is resolved by a config-based helper (add a pure `attach` function that takes `*compass.Config` instead of the globals) or stored absolute on save.
- Library host: an `AdminSingleton` controller (`SingletonRecord(ctx, db) (any, error)`, first-or-create with a unique-index race retry) [VERIFIED: modules/pact/capabilities.go:1041-1043; modules/cabana/singleton.go:41-80] on a one-row host table; `fileupload` attachMany `images`, public, `useCaption: true`. The picker's immediate upload goes through `attach.Store(ctx, db, bucket, attach.Upload{FileName, Body, Public: true}, attach.Limits{…})` [VERIFIED: modules/lagoon/attach/store.go:72-76,123] attached to the host row. That bypasses deferred binding on purpose (UI-SPEC C4).
### Pattern 9: admin wiring facts the plans touch
- **Built-in field types:** add `codeeditor`, `colorpicker`, `mailimage`, `mailpreview` to `formFieldTypes` (currently `"text" … "taglist"`) [VERIFIED: modules/cabana/form_schema.go:24-31]. Add `language` and `mailImages` to `formFieldKeys` (`mode` and `size` already exist) [VERIFIED: form_schema.go:35-51]. In the SPA, register the renderers in `registry.ts`, add `mailpreview` to `valueless` (`new Set<string>([RELATION_MANAGER, 'widget', 'partial', 'fileupload'])`) and the group-labelled types to `groupLabelledTypes` [VERIFIED: admin/src/components/form/registry.ts].
- **Row states:** pact's set is fixed: `RowStateDeleted RowState = "deleted"`, `RowStateNegative RowState = "negative"`, `RowStateDisabled RowState = "disabled"` [VERIFIED: modules/pact/capabilities.go:1055-1062]. cabana's order is `var rowStateOrder = []pact.RowState{pact.RowStateDeleted, pact.RowStateNegative, pact.RowStateDisabled}` [VERIFIED: modules/cabana/query.go:182]; messages are in `cabana/messages.go:42,61,163`; the SPA has `const ORDER = ['deleted', 'negative', 'disabled']` (RowStateBadges.vue:19) and `const ROW_STATES = ['deleted', 'negative', 'disabled']` (DataTable.vue:160); `TestRowStateValues` pins `len(set) != 3` [VERIFIED: modules/pact/capabilities_test.go:414-415]. All of these change for `customized`/`outdated`, and the OpenAPI message schema gains two keys.
- **Save hooks ordering:** the update path runs Fill → rules → `formBeforeUpdate` → relation checks → `assignBelongsTo` → `tx.Unscoped().Save(target)` → `formAfterUpdate`, with no dirty-check skip [VERIFIED: modules/cabana/crud.go:876-952]. Stamp `is_custom`, `base_hash` and `customized_at` in `FormBeforeUpdate`; run postcard validation in `FormAfterUpdate`, where a belongsTo `layout_id` is already assigned. A `*ValidationError` or `*ForbiddenError` passes through `lifecycleFailure` [VERIFIED: crud.go:1090-1106] and rolls the transaction back.
- **Partials (server-rendered `_info.htm`, `_file_version.htm`):** the allowlist has `div, span, p, strong, … code, pre` and global attributes `class, title, lang, dir, role` [VERIFIED: modules/cabana/partial_render.go:105-118]. That is enough for the drift callout and `.summer-diff`. Data comes from `AdminPartialData.PartialData` as a curated view model, never a GORM model [VERIFIED: modules/pact/capabilities.go:655-663].
- **Consumer layouts to keep rendering byte-identically:** `golem15.user::mail.layouts.user` (text wrapper `-- {{ .Content }} --`) and `golem15.paymentgateway::mail.layouts.paymentgateway` [VERIFIED: ../sm-user-plugin/plugin.go:309-313, views/mail/layouts/user.htm; ../sm-paymentgateway-plugin/mail.go:83-86].
### Recommended schema (design; table names follow the framework's Winter-name convention: `system_files`, `backend_users`)
```sql
CREATE TABLE system_mail_layouts (
id SERIAL PRIMARY KEY,
code TEXT NOT NULL UNIQUE, -- file: full name (contains '::'); database-only: ^[a-z0-9-]+$
source TEXT, -- owning plugin ID; NULL = database-only (deletable, never reset)
name TEXT NOT NULL,
content_html TEXT NOT NULL DEFAULT '', content_text TEXT NOT NULL DEFAULT '', content_css TEXT NOT NULL DEFAULT '',
is_custom BOOLEAN NOT NULL DEFAULT FALSE, -- file row: override active; database-only row: TRUE
file_hash TEXT, base_hash TEXT, -- D-07: current file hash (sync) / hash the override was based on (save)
customized_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE TABLE system_mail_templates (
id SERIAL PRIMARY KEY, code TEXT NOT NULL UNIQUE, source TEXT NOT NULL, locale TEXT, description TEXT,
subject TEXT NOT NULL DEFAULT '', body TEXT NOT NULL DEFAULT '',
layout_id INTEGER REFERENCES system_mail_layouts(id) ON DELETE RESTRICT, -- D-08 in-use refusal backstop
is_custom BOOLEAN NOT NULL DEFAULT FALSE, file_hash TEXT, base_hash TEXT, customized_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE TABLE system_mail_partials ( /* code, source, name, content_html, content_text, is_custom, file_hash, base_hash, customized_at, timestamps */ );
CREATE TABLE system_mail_brand_settings ( id INTEGER PRIMARY KEY, logo_file_id INTEGER, /* 14 colour TEXT columns */ created_at …, updated_at … );
CREATE TABLE system_mail_image_library ( id SERIAL PRIMARY KEY, created_at …, updated_at … ); -- attachMany host only
```
"Outdated" = `is_custom AND source IS NOT NULL AND base_hash IS DISTINCT FROM file_hash`, which the list filter can express in SQL. The hash is sha256 over the raw file bytes with CRLF normalized (postcard already normalizes in `splitEQ`, `strings.ReplaceAll(src, "\r\n", "\n")`) [VERIFIED: modules/postcard/templates.go:273].
### Anti-Patterns to Avoid
- **Boot-time snapshot of overrides in the mailer.** It is stale across instances (CONTEXT forbids it).
- **Adding methods to `postcard.Mailer` or changing `Catalog.Register`/`HasMailTemplates`.** Outside code implements or calls them directly (sm-user-plugin `mail_test.go:81`, paymentgateway `mail_smoke_test.go:49`).
- **`html.WithUnsafe` on the body renderer to "make partials work".** It changes every existing mail.
- **Deleting index rows on sync.** IDs churn during rolling deploys; filter by catalog membership instead.
- **Building image URLs in the SPA.** The server returns absolute URLs (UI-SPEC C4).
- **Sharing the Branding row as the image-library host.** It flips D-11 precedence.
## Don't Hand-Roll
| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Code editor | textarea + highlight overlay | CodeMirror 6 modular packages | Caret/scroll sync, a11y, bracket matching |
| Upload, storage, thumbnails, image guard | custom file handling | `attach.Store` + existing `fileupload` field | MIME/image guard, partitioned keys, public URL logic |
| Rate limiting across instances | per-process map | `cooler.Attempter` (Redis when configured) | Shared counters; same semantics as `throttle` |
| Template parsing / variable discovery | regex over `{{ }}` | `html/template` `Tree` + `text/template/parse` walk | Handles `if`/`range`/`with`/pipelines correctly |
| Markdown | own converter | goldmark (existing pin) | Same output as real sends |
| Settings singleton, record actions, confirm/danger, 409/403 handling | custom endpoints | cabana SettingsService, `pact.AdminRecordAction`, `ForbiddenError` | 19.6.1 already proved these paths |
**Key insight:** the one place a small hand-written piece is justified is the D-07 line diff. Inputs are a few hundred lines, the stdlib-first rule applies, and the UI-SPEC allows omitting the diff. A bounded LCS (cap of about 2,000 lines, beyond which only the file content is shown) is less risk than a new dependency.
## Common Pitfalls
### Pitfall 1: overrides ignored in a separate job worker
**What goes wrong:** mail sent from River jobs uses file versions while serve uses overrides.
**Why:** cabana only activates in serve (Pattern 1).
**How to avoid:** postcard's own DB source, wired in `Activate`, reading `app.Lookup[*gorm.DB]()` per send.
**Warning signs:** a test that sends through a mailer from `party.Activate` with a published DB and no `cabana.Activate` ignores an override.
### Pitfall 2: partial HTML silently vanishes from bodies
**What goes wrong:** `<!-- raw HTML omitted -->` appears where the button should be (verified behaviour).
**How to avoid:** placeholder substitution after goldmark (Pattern 4), a per-render nonce, and `[A-Z0-9]` tokens.
### Pitfall 3: save validation rejects working templates
**What goes wrong:** with an empty sample map, `{{ .order.code }}` fails with "nil pointer evaluating interface {}.code", so every paymentgateway template override would be refused under D-13.
**How to avoid:** validate and preview with the walker-built placeholder map (Pattern 5). Test against all 55 paymentgateway files and the 8 user files.
### Pitfall 4: relative image/logo URLs in mail
**What goes wrong:** `/storage/app/uploads/public/…` in a mail client, or a different URL from a worker process.
**How to avoid:** absolute URLs inserted at edit time, a config-based logo URL helper, and refusal when neither `storage.uploads.public_url` nor `app.url` is set. Note that a URL with a space breaks Markdown image syntax (`![Logo](https://cdn.example.com/a b.png)` stays literal text) [VERIFIED: scratch run]. Percent-encode in `insertImage.ts`; attach disk names are generated, so this mostly matters for `public_url` paths.
### Pitfall 5: CodeMirror swallows the form's Mod+Enter
**What goes wrong:** `defaultKeymap` contains `{ key: "Mod-Enter", run: insertBlankLine }` (and `Escape: simplifySelection`) [VERIFIED: @codemirror/commands 6.11.1 dist/index.js:1796-1816], so Mod+Enter inserts a line instead of saving (UI-SPEC C1).
**How to avoid:** `keymap.of([...historyKeymap, ...defaultKeymap.filter(b => b.key !== 'Mod-Enter')])`. Do not add `indentWithTab`; CodeMirror leaves Tab unbound by default to avoid a keyboard trap [CITED: codemirror.net/examples/tab]. Cover it in the browser test.
### Pitfall 6: validating a template against the old layout
**What goes wrong:** `FormBeforeUpdate` runs before `assignBelongsTo`, so a changed `layout_id` is not on the model yet [VERIFIED: crud.go:895-928].
**How to avoid:** validate in `FormAfterUpdate` (same transaction; a `ValidationError` rolls back).
### Pitfall 7: tables missing after a binary upgrade
**What goes wrong:** the new binary starts before `migrate` runs. Sync fails and per-send lookups hit `undefined_table`.
**How to avoid:** sends treat any lookup error as "no overrides" with a rate-limited warning; sync retries on the first list request. `serve` already reports pending migrations at startup [VERIFIED: modules/surf/serve.go:111]. Update `lagoon/pending_test.go:349` (`wantSets := []string{"summercms.attach", "summercms.cabana", DeferredHistoryID, QueueHistoryID, "demo.alpha", "demo.beta"}`) [VERIFIED].
### Pitfall 8: safety-regex false positives
**What goes wrong:** the existing checks `(?i)(?:javascript|vbscript|data):` and `(?i)\son[a-z]+\s*=` [VERIFIED: modules/postcard/templates.go:25-26] match ordinary text such as "metadata:" or " online = ", and now show up as save errors.
**How to avoid:** keep the behaviour (it matches sends) but pass the matched snippet in `:message` so admins can see why.
### Pitfall 9: parameterized validation lines come out raw
**What goes wrong:** `localizeDetails` localizes plain phrase keys only [VERIFIED: modules/cabana/crud.go:104-150], so `mail.invalid_render` with `:message`, or `mail.layout.delete_in_use` with `:name`/`:count`, shows unsubstituted.
**How to avoid:** build the final text in the hook with the translator, as `backendMessageParams(ctx, tr, key, fallback, params)` does [VERIFIED: modules/cabana/account_tokens.go:206,227]. Use a `ForbiddenError` (not a `ValidationError`) for the delete refusal (UI-SPEC C15 note).
### Pitfall 10: the templates list can be empty
**What goes wrong:** the UI-SPEC says the unfiltered list is "never empty, because postcard registers built-in mail". postcard registers **no** templates today, only the default layout [VERIFIED: modules/postcard/templates.go:62-74]. An app without mail-sending plugins shows an empty list.
**How to avoid:** accept it (the empty copy exists) or ship one built-in template. Decide in the plan.
## Code Examples
### Placeholder walker (prototype, renders the real paymentgateway shapes)
```go
// Source: scratch prototype run 2026-11-06 against Go 1.27.2 html/template.
// Output for the paymentgateway "paid" body: "Cześć [user.first_name], … **ZAM-1** …
// - [order.items.description] × [order.items.count]: … [banking_details.bankDetailsLines]"
func fill(root map[string]any, n parse.Node, prefix []string, samples map[string]string) {
switch x := n.(type) {
case *parse.ListNode:
if x == nil { return }
for _, c := range x.Nodes { fill(root, c, prefix, samples) }
case *parse.ActionNode:
fill(root, x.Pipe, prefix, samples)
case *parse.PipeNode:
if x == nil { return }
for _, c := range x.Cmds { fill(root, c, prefix, samples) }
case *parse.CommandNode:
for _, a := range x.Args { fill(root, a, prefix, samples) }
case *parse.FieldNode:
set(root, x.Ident, prefix, samples) // nested maps, "[a.b]" or the sample
case *parse.IfNode:
fill(root, x.Pipe, prefix, samples); fill(root, x.List, prefix, samples); fill(root, x.ElseList, prefix, samples)
case *parse.WithNode:
fill(root, x.Pipe, prefix, samples); fill(root, x.List, prefix, samples); fill(root, x.ElseList, prefix, samples)
case *parse.RangeNode:
// one-element slice: a map of the fields used in the body, or a string when the body prints {{ . }}
}
}
// t := template.Must(template.New("t").Option("missingkey=zero").Parse(src)); fill(vars, t.Tree.Root, nil, samples)
```
The production version must also handle `ChainNode`/`VariableNode` and `with` re-rooting (a `with` body's fields are relative to the pipeline value), and must apply the `partial` func map before parsing.
### CodeMirror setup (verified export names; `editor.ts` lazy target)
```ts
// Sources: codemirror.net/examples/tab, /examples/decoration; exports verified in the pinned dist .d.ts files.
import { EditorState } from '@codemirror/state'
import { EditorView, keymap, lineNumbers, Decoration, MatchDecorator, ViewPlugin } from '@codemirror/view'
import { defaultKeymap, history, historyKeymap } from '@codemirror/commands'
import { bracketMatching, HighlightStyle, syntaxHighlighting } from '@codemirror/language'
import { html } from '@codemirror/lang-html'
import { css } from '@codemirror/lang-css'
import { tags } from '@lezer/highlight'
const actionMatcher = new MatchDecorator({
regexp: /\{\{[\s\S]*?\}\}/g,
decoration: () => Decoration.mark({ class: 'cm-summer-action' }),
})
const goActions = ViewPlugin.fromClass(class {
decorations
constructor(view: EditorView) { this.decorations = actionMatcher.createDeco(view) }
update(u: import('@codemirror/view').ViewUpdate) { this.decorations = actionMatcher.updateDeco(u, this.decorations) }
}, { decorations: (v) => v.decorations })
const keys = keymap.of([...historyKeymap, ...defaultKeymap.filter((b) => b.key !== 'Mod-Enter')]) // Pitfall 5
// No indentWithTab: Tab moves focus (WCAG 2.1.2). Line wrapping only for language: text (EditorView.lineWrapping).
```
### Lagoon framework set (where the migration goes)
```go
// modules/lagoon/migrations.go, today [VERIFIED: lines 224-230]:
sets := []migrationSet{
{"summercms.attach", "system_files", attach.Migrations},
{"summercms.cabana", "backend admin", BackendAdminMigrations},
{DeferredHistoryID, "deferred bindings", DeferredBindingMigrations},
{QueueHistoryID, "queue", QueueMigrations(sqlDB)},
}
// recommended addition (after attach, because brand logo_file_id may reference system_files):
// {"summercms.postcard", "mail", postcard.Migrations},
```
## State of the Art
| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| Winter: Twig mail + DB rows synced on list open, CSS inlined by CssToInlineStyles | postcard: Go templates, `<style>` block (no inliner) | this project | Branding CSS must work as a `<style>` block; an inliner would be a separate dependency decision (not in scope) |
| CodeMirror 5 / Ace (Winter) | CodeMirror 6 modular, Tab unbound by default | CM6 | Lazy chunk, a11y-safe default |
**Deprecated/outdated:** the `codemirror` meta package with `basicSetup` (heavier than needed; UI-SPEC excludes it).
## Assumptions Log
| # | Claim | Section | Risk if Wrong |
|---|-------|---------|---------------|
| A1 | D-01's intent is met when postcard defines the interface **and** ships the DB implementation, with cabana owning only the screens | Pattern 1 | User may insist on cabana-owned storage; then the worker-process gap needs another wiring (CONTEXT allows "by postcard if the planner justifies it") |
| A2 | D-06 "reset deletes the override row" is satisfied by clearing the override columns of the index row (re-mirroring the file), because rows must exist for the generic admin | Pattern 2 / Open Q1 | If the user wants a literal separate override table, the generic form/list need joins (much more cabana work) |
| A3 | D-08 "not rows copied into the DB at boot" refers to predefined layouts not becoming custom records; index rows with a file mirror (synced at serve start) are acceptable | Pattern 2 | Conflicts with a literal reading; confirm |
| A4 | Winter table names (`system_mail_*`) are fine because ported apps run on a fresh Postgres (PHP side is MySQL; Winter data arrives through explicit import commands) | Schema | If an app's Postgres ever holds Winter's `system_mail_*` tables, `CREATE TABLE` collides; Winter's Twig content would then be read as Go templates |
| A5 | INI `sample.*` dotted keys are the better D-15 mechanism (vs a capability) | Pattern 5 | Planner's call per D-15; low risk |
| A6 | surf publishing its store as `cooler.Attempter` is acceptable as a small surf change | Pattern 7 | Alternative: per-instance limit only |
| A7 | Test-send limit of about 5 per 10 minutes per admin | Pattern 7 | Tuning only |
| A8 | Built-in partial set button/panel/table/subcopy and layouts default/system/minimal | Pattern 4 | Planner's discretion |
| A9 | `@lezer/highlight` 1.2.5 should be a direct pinned dependency because the theme imports `tags` | Standard Stack | If the theme avoids `tags`, it is not needed |
## Open Questions
1. **Reset semantics vs D-06 wording ("deletes the override row").**
- What we know: the generic admin needs a row per template (numeric IDs, SQL search).
- What's unclear: whether the user accepts "reset clears the override in the index row".
- Recommendation: state it in the plan's opening summary for confirmation. Behaviourally identical: the file wins, the customized state is gone.
2. **Logo URL: resolve at render (needs a config-based attach helper) or store absolute at save?**
- Recommendation: add a pure `attach` URL function taking `*compass.Config` (additive, documented in the attach README) and resolve at render. A removed library image then yields an empty `logoUrl` instead of a broken link.
3. **Picker upload permission (D-03 note).** Recommendation (as UI-SPEC): `canUpload` only for `system.manage_mail_layouts`; template editors pick only.
4. **Built-in template so the list is never empty (Pitfall 10).** Recommendation: none; keep the filtered/empty copy.
5. **`layout` field type on the template form:** `relation` (belongsTo, `nameFrom: name`, renders as a select) is the natural fit with `layout_id`. Confirm that a relation dropdown can omit the empty option, or use a required rule.
## Environment Availability
| Dependency | Required By | Available | Version | Fallback |
|------------|------------|-----------|---------|----------|
| Go toolchain | all Go work | ✓ | go1.27.2 | — |
| Node / npm | admin SPA build/tests | ✓ | v24.22.0 / 12.2.1 (`engines.node >=22.6`) | — |
| admin/node_modules | `npm test`, gates | ✓ | present | `npm --prefix admin ci` |
| Docker | testcontainers Postgres/Mailpit tests | ✓ (socket access ok) | client 29.9.1 | `-short` skips; `sudo -u golem` per CLAUDE.md if denied |
| Playwright Chromium | `test:browser` (codeeditor keyboard test) | ✓ | chromium-1169, -1194 in ~/.cache/ms-playwright | — |
| swag | `check-admin-openapi.sh` | ✓ (script runs `go run …swag@v1.16.6`) | v1.16.6 | — |
| `summer` CLI | `summer docs:build --check` | ✓ | installed in GOPATH/bin | `go test ./cmd/summer -run TestDocsTree` |
| Context7 MCP | research only | ✗ | — | WebFetch of codemirror.net + `npm pack` d.ts inspection |
**Missing dependencies with no fallback:** none.
## Validation Architecture
### Test Framework
| Property | Value |
|----------|-------|
| Framework | Go `testing` (+ testcontainers-go for Postgres/Mailpit); Vitest 3.2.7 (happy-dom) and Vitest browser mode with Playwright 1.60.0 |
| Config file | `admin/vitest.config.*`, `admin/vitest.browser.config.ts`; Go: none |
| Quick run command | `go test -short ./modules/postcard/... ./modules/pact/... ./modules/cabana/... ./modules/lagoon/...` |
| Full suite command | `go vet ./... && go test ./... && npm --prefix admin run test && npm --prefix admin run test:browser && npm --prefix admin run typecheck && scripts/check-admin-openapi.sh --check && scripts/check-admin-dist.sh && summer docs:build --check` |
### Phase Decisions → Test Map
| Decision | Behavior | Test Type | Automated Command | File Exists? |
|--------|----------|-----------|-------------------|-------------|
| D-11/D-14, Pattern 3 | Override wins; file wins without one; render failure falls back to file; DB error falls back; caller subject still wins | unit (fake `OverrideSource`, MemoryDriver) | `go test -short ./modules/postcard -run 'TestOverride\|TestFallback'` | ❌ Wave 0 |
| Pattern 1 | DB source reads real tables; works with no cabana activation | integration (Postgres) | `go test ./modules/postcard -run TestStore` | ❌ |
| D-12 | `HasMailPartials` boot errors (missing file, duplicate, foreign namespace); body partial survives Markdown; nonce forgery fails; layout partial; text part | unit | `go test -short ./modules/postcard -run TestPartial` | ❌ |
| D-15 | `sample.*` keys parsed case-preserving; old keys ignored; walker fills nested/range/dot | unit | `go test -short ./modules/postcard -run TestSample` | ❌ |
| D-13 | Draft validation errors (parse, render, unsafe, subject CR/LF, unknown layout/partial, missing `{{ .Content }}`) mapped to fields | unit + Postgres | `go test -short ./modules/postcard -run TestValidateDraft`; `go test ./modules/cabana -run TestMailSave` | ❌ |
| D-07 | Drift: `base_hash` ≠ `file_hash` → outdated state and filter; re-save clears | Postgres | `go test ./modules/cabana -run TestMailDrift` | ❌ |
| D-06/D-08 | Reset clears override; custom layout delete refused with count (403); file layout never deletable | Postgres | `go test ./modules/cabana -run 'TestMailReset\|TestMailLayoutDelete'` | ❌ |
| D-10/D-11 | No brand row → `mail.brandCss`; saved → compiled CSS replaces it; `mail.css` still applied; bad colour 422 | unit + Postgres | `go test -short ./modules/postcard -run TestBrand`; `go test ./modules/cabana -run TestMailBrand` | ❌ |
| D-03 | Permission split per controller, preview mode, picker list vs upload; no default role grants | Postgres (19.6.1 `newScreensEnv` harness) | `go test ./modules/cabana -run TestMailPermissions` | ❌ (harness exists: `administrators_harness_test.go`) |
| D-17 | Recipient is always the admin's own email; body recipient refused; 429 + Retry-After after N | Postgres | `go test ./modules/cabana -run TestMailTestSend` | ❌ |
| D-05 | Locale parsing only for enabled locales; locale filter | unit | `go test -short ./modules/cabana -run TestMailLocale` | ❌ |
| Pattern 2 | Sync idempotent; concurrent sync safe; custom rows untouched; missing tables tolerated | Postgres | `go test ./modules/postcard -run TestSync` | ❌ |
| Consumers | user + paymentgateway mail renders unchanged | unit (their repos, `replace ../summercms.go`) | `(cd ../sm-user-plugin && go test -run 'TestMail\|TestPolishMailSubjects' ./...)`; `(cd ../sm-paymentgateway-plugin && go test -run 'TestMailCatalog\|TestMailTracer\|TestMailersMatrixSmoke' ./...)` | ✅ |
| Byte-identity | Existing postcard tests still pass; default layout output unchanged | unit | `go test -short ./modules/postcard/...` | ✅ |
| UI C1/C4/C8/C10 | codeeditor keys (Tab leaves, Mod+S/Mod+Enter save, Esc ≠ Cancel); insertImage escaping; footer record actions, `meta.deletable`; preview sandbox/sequence guard | SPA unit + browser | `npm --prefix admin run test -- mail codeeditor`; `npm --prefix admin run test:browser -- codeeditor` | ❌ |
| Gates | OpenAPI/schema in sync; dist matches; docs identifiers exist | scripts | `scripts/check-admin-openapi.sh --check`; `scripts/check-admin-dist.sh`; `go test ./cmd/summer -run TestDocsTree` | ✅ |
### Sampling Rate
- **Per task commit:** the quick run command plus `go vet ./...` (and `npm --prefix admin run test` for SPA tasks).
- **Per wave merge:** the full suite command.
- **Phase gate:** full suite green plus a new `scripts/check-phase35.sh` (mirroring `check-phase34.sh`) that also runs the two consumer repos' mail tests, before `/msd-verify-work`.
### Wave 0 Gaps
- [ ] `modules/postcard/override_test.go`, `partials_test.go`, `samples_test.go`, `brand_test.go`, `store_postgres_test.go` (TestMain with `flag.Parse()` + `testing.Short()` per CLAUDE.md)
- [ ] `modules/cabana/mail_*_postgres_test.go` reusing the 19.6.1 harness
- [ ] `admin/tests/form/codeeditor*.test.ts`, `admin/tests/browser/codeeditor.test.ts`, `admin/tests/form/mailpreview.test.ts`, `admin/tests/form/insertImage.test.ts`
- [ ] Update `modules/pact/capabilities_test.go` `TestRowStateValues` and `modules/lagoon/pending_test.go` set list
- [ ] `scripts/check-phase35.sh`
## Security Domain
### Applicable ASVS Categories
| ASVS Category | Applies | Standard Control |
|---------------|---------|-----------------|
| V2 Authentication | no (reuses admin JWT/cookie) | bouncer composite guard |
| V3 Session Management | yes (test send) | interactive-only route wrapper; no API-token use of test send |
| V4 Access Control | yes | `RequiredPermissions` per controller; `cabana.Allows` per preview mode/picker action; no default role grants |
| V5 Input Validation | yes | postcard draft validation (D-13), hex colour regex, layout code `^[a-z0-9-]+$`, attach image guard/limits |
| V6 Cryptography | minimal | sha256 for drift (integrity hint only); `crypto/rand` nonce for partial tokens |
| V12 Files | yes | `attach.Store` with image limits and public flag; `accept=` is a hint only |
| V14 Config | yes | CSP unchanged; srcdoc `sandbox=""` |
### Known Threat Patterns for this stack
| Pattern | STRIDE | Standard Mitigation |
|---------|--------|---------------------|
| Stored XSS in admin preview via a mail draft | Tampering / Elevation | `sandbox=""` srcdoc iframe (no scripts, no same-origin); server-rendered HTML already passes `validateHTML`; the SPA never builds the HTML |
| Script/handler injection into sent mail | Tampering | `validateHTML` on body, layout and final HTML at save **and** send; partial outputs included |
| CSS injection through brand colours (`</style>`) | Tampering | strict `#rrggbb` validation before compiling; `validateHTML` backstop |
| Header injection via subject override | Tampering | existing CR/LF refusal, also at save |
| Spam/abuse through test send | Abuse | recipient fixed to the admin's own address; per-admin rate limit; permission per record kind |
| Placeholder forgery (user value contains the partial token) | Tampering | per-render random nonce in the token |
| Over-privileged picker upload | Elevation | upload requires `system.manage_mail_layouts`; list allowed for either code |
| Privilege via permission codes | Elevation | codes declared with no `Roles`; superuser-only until granted (19.6.1 pattern) |
| Information disclosure in preview errors | Info disclosure | `:message` limited to parser/safety text, never DB errors or paths beyond the file name |
## Sources
### Primary (HIGH confidence)
- Codebase, read this session: `modules/postcard/{templates.go,mailer.go,drivers.go,README.md,assets/default.htm}`, `modules/pact/capabilities.go`, `modules/party/registry.go`, `modules/backpack/services.go`, `modules/cabana/{backend_screens.go,http.go,settings.go,singleton.go,crud.go,query.go,form_schema.go,field_markdown.go,contracts.go,partial_render.go,messages.go}`, `modules/lagoon/{migrations.go,backend_admin_migrations.go,ondatabase.go,connection.go}`, `modules/lagoon/attach/{bucket.go,thumb.go,store.go,migrations.go}`, `modules/conga/commands.go`, `modules/surf/{serve.go,limiter.go,router.go}`, `modules/cooler/{cooler.go,README.md}`, `modules/boardwalk/boardwalk.go`, `admin/package.json`, `admin/src/components/form/registry.ts`
- Consumers: `../sm-user-plugin/{plugin.go,views/mail/**}`, `../sm-paymentgateway-plugin/{mail.go,views/mail/**,events/mailers.go,mail_smoke_test.go}`
- Winter reference: `examples/golem15-wintercms-starter/modules/system/{controllers/MailTemplates.php,models/MailTemplate.php,models/MailLayout.php,views/mail/*.php,models/mailbrandsetting/*}`
- npm registry (`npm view`, `npm pack`) for all seven SPA packages; MSD package-legitimacy seam
- Scratch programs (goldmark v1.8.6 from the module cache; html/template walker), 2026-11-06
### Secondary (MEDIUM confidence)
- codemirror.net/examples/tab (Tab handling, `indentWithTab`, `toggleTabFocusMode`)
- codemirror.net/examples/decoration (`MatchDecorator`, `ViewPlugin`, `createDeco`/`updateDeco`)
### Tertiary (LOW confidence)
- none
## Metadata
**Confidence breakdown:**
- Standard stack: HIGH. Go dependencies are already in the graph; npm versions, maintainers and exports were verified against the registry and the pinned tarballs.
- Architecture: MEDIUM-HIGH. Every integration fact was read in the code. The store split, index rows and placeholder design are recommendations, flagged in the Assumptions Log where they reinterpret CONTEXT wording.
- Pitfalls: HIGH. The goldmark, missing-key, keymap, hook-order, worker-URL and limiter-reachability pitfalls were each confirmed by execution or by reading the source.
**Research date:** 2026-11-06
**Valid until:** 2026-12-06 (codebase facts may move with concurrent Phase 33 work in cabana; re-check `cabana/http.go`, `form_schema.go` and `crud.go` line references before planning if Phase 33 lands first)

View File

@@ -0,0 +1,73 @@
---
phase: 35
review: 35-REVIEW.md
titles: json
findings:
- id: CR-01
severity: critical
disposition: fixed
title: "A site name that `UnsafeText` accepts still stops every default/system-layout send (CR-01 residual)"
- id: CR-02
severity: critical
disposition: fixed
title: "Scheme and handler checks are skipped inside raw-text elements: `<noscript>`, and `<title>`/`<textarea>`/`<style>` in SVG/MathML"
- id: WR-01
severity: warning
disposition: fixed
title: "List-valued, `meta` content, `style` and comment checks do not strip whitespace, so `java&#9;script:` passes"
- id: WR-02
severity: warning
disposition: fixed
title: "Ordinary text still blocks a send through the whole-document `eventHandler` regex"
- id: WR-03
severity: warning
disposition: fixed
title: "The new `UnsafeText` rule refuses ordinary names that the docs promise are accepted"
- id: IN-01
severity: info
disposition: open
title: "The footer partial's Markdown `body` branch is never previewed or validated in the partial editor"
- id: IN-02
severity: info
disposition: open
title: "`settings.go` now localizes every settings model's `BeforeValidate` error"
- id: IN-03
severity: info
disposition: open
title: "CSS escape sequences bypass the CSS `data:`/`javascript:` checks (accepted residual, undocumented to users)"
- id: WR-04
severity: warning
disposition: open
title: "Fallback-locale rule silently resolves typos, yet rejects real locales the admin offers"
- id: WR-05
severity: warning
disposition: open
title: "Safety check runs on undecoded markup; the new opt-out ships what the inlined path would reject"
- id: IN-04
severity: info
disposition: open
title: "Case handling differs between `EnsureLocaleRows` and send resolution; doc comment reflow"
open: 6
total: 11
recorded: 2026-11-14T16:46:28.031Z
---
# Phase 35: Code Review Disposition
| Finding | Severity | Disposition | Source |
|---------|----------|-------------|--------|
| CR-01 | critical | fixed | 35-REVIEW-FIX.md (2dbee305; needs human verification) |
| CR-02 | critical | fixed | 35-REVIEW-FIX.md (1d481bb0; needs human verification) |
| WR-01 | warning | fixed | 35-REVIEW-FIX.md (baba524c) |
| WR-02 | warning | fixed | 35-REVIEW-FIX.md |
| WR-03 | warning | fixed | 35-REVIEW-FIX.md |
| IN-01 | info | open | - |
| IN-02 | info | open | - |
| IN-03 | info | open | - |
| WR-04 | warning | open | - (not in the current review) |
| WR-05 | warning | open | - (not in the current review) |
| IN-04 | info | open | - (not in the current review) |
Dispositions: `open` (recorded, not yet triaged), `fixed`, `skipped`, `deferred`.
Set `deferred` by hand and put the reason in the Source cell; both are preserved. A `|` in the reason is kept as prose and escaped on the next run.
Re-running the gate keeps every row it can. A row the current review no longer reports is kept and its Source cell flagged, so a finding does not leave this record silently. ONE exception: when a finding id is REUSED by a different finding, the earlier decision cannot keep a row — the id is taken — and it is dropped. A RECORDED decision (anything but `open`) is named on the console when that happens; a row still at `open` is replaced silently, because `open` records no decision to lose.

View File

@@ -0,0 +1,109 @@
---
phase: 35-mail-templates-and-layouts-editor
fixed_at: 2026-11-14T16:45:00Z
review_path: .planning/phases/35-mail-templates-and-layouts-editor/35-REVIEW.md
iteration: 1
findings_in_scope: 5
fixed: 5
skipped: 0
status: all_fixed
---
# Phase 35: Code Review Fix Report
**Fixed at:** 2026-11-14T16:45:00Z
**Source review:** .planning/phases/35-mail-templates-and-layouts-editor/35-REVIEW.md
**Iteration:** 1
**Summary:**
- Findings in scope: 5 (CR-01, CR-02, WR-01, WR-02, WR-03; fix_scope critical_warning, IN-01..IN-03 not attempted)
- Fixed: 5
- Skipped: 0
`workflow.use_worktrees` is `false`, so the fixes were edited and committed in the main checkout on `master` (no worktree, no temp branch, no recovery sentinel). All verification below ran in the main checkout and can be reproduced from it.
Order of commits: CR-01, CR-02, WR-01, WR-02, WR-03, then the decision note amendment (planning doc, separate commit). WR-02 depends on CR-02: the whole-document handler regex could only be dropped once the tokenizer walk reads raw-text element and comment content.
## Fixed Issues
### CR-01: A site name that `UnsafeText` accepts still stops every default/system-layout send
**Files modified:** `modules/postcard/safety.go`, `modules/postcard/sitename_test.go`, `modules/cabana/mail_site_name_postgres_test.go`, `modules/postcard/README.md`, `docs/services/mail.md`
**Commit:** 2dbee305
**Applied fix:** `UnsafeText` now checks the escaped name in the places the built-in layouts print it (`printContext`: after `© 2000 ` in a footer paragraph, in the header span and in the logo's `alt`), not on its own. With that commit alone, `Online=Shop` and `onboarding=team` were dropped at render (with the rate-limited warning) and refused on the Branding form, so sends on default and system layouts succeeded on every path. WR-02 (31de2ff9) then removed the cause: such names are now shown and saved. Regression tests (final state, after WR-02): `TestSiteNameSend` sends `Online=Shop`/`onboarding=team` from the Branding and from a `mail.from` display name on the default and system layouts over the file-version, override and override-failure paths and checks the name in the header and footer. `TestUnsafeText` pins them as safe. `TestUnsafeSiteNameDropped/editor` checks that a template or layout save under a stored `Online=Shop` is not refused. `TestMailSiteNameSafety` (Postgres) has `handler_shaped_name_sends`, which saves `Online=Shop` on the Branding form and sends on both layouts. The verifier probe (`zz_verifier_probe_test.go` via overlay) now reports `err=<nil>` for all 8 Branding/mail.from sends and for `Editor.Validate` under Branding `Online=Shop`.
**Status:** fixed: requires human verification. This is a logic change to the safety rule.
### CR-02: Scheme and handler checks are skipped inside raw-text elements
**Files modified:** `modules/postcard/safety.go`, `modules/postcard/safety_test.go`, `modules/postcard/README.md`, `docs/services/mail.md`
**Commit:** 1d481bb0
**Applied fix:** `unsafeMarkup` now checks again, as markup:
- the raw source of the content of every raw-text element (`rawTextElements`: iframe, noembed, noframes, noscript, plaintext, script, style, textarea, title, xmp). This also covers content after a self-closing start tag such as `<style/>`, which the tokenizer reads as raw text too.
- the data of every comment, which covers Outlook conditional comments.
I used recursion instead of `z.NextIsNotRawText()`, so the HTML reading (raw text, for example CSS in `<style>`) and the foreign/scripting-off reading (markup) are both checked. The raw source is what gets re-read, so `&lt;a href=...&gt;` inside a `title` stays text. Nesting deeper than 8 levels (`maxMarkupDepth`) is refused with "rendered HTML nests raw-text elements or comments too deeply", which bounds the cost on hostile input.
Tests added to `TestURLSchemeCheck`:
- `refuses`: the six review/verifier payloads (`noscript` href, `noscript` `/onerror`, `svg title`, `svg textarea`, `svg style` with an entity, `xmp`), plus `<style/>`, a conditional-comment handler and nesting that is too deep.
- `accepts`: escaped markup in `textarea`/`title`, a safe `noscript` link, and an Outlook VML conditional comment.
- sends through a layout override with the `noscript` and `xmp` payloads, with inlining on and off. Both fall back to the file version.
- the editor refuses both payloads on `content_html`.
Note: the probe still reports `containsJS=true` for `<svg><title><a href="javascript:...">`, both in a body and in a layout. html/template escapes literal `title`/`textarea` text itself (`&lt;a href=&#34;javascript:alert(1)&#34;&gt;`), so the probe's substring match finds harmless escaped text, not an element. That is also why the svg/title payload is tested at the `validateHTML` level and not as a send.
**Status:** fixed: requires human verification. The safety-rule logic changed.
### WR-01: List-valued, `meta` content, `style` and comment checks do not strip whitespace
**Files modified:** `modules/postcard/safety.go`, `modules/postcard/safety_test.go`, `modules/postcard/README.md`, `docs/services/mail.md`
**Commit:** baba524c
**Applied fix:** I factored the stripping loop out of `hasDangerousScheme` into `stripURLSpace`, and added `containsDangerousScheme` (`dangerousScheme` on the stripped value). The list-valued attribute, `style` attribute, meta `content`, style-element text and comment checks all use it now. Regression cases in `refuses`: `values="java&#9;script:..."`, meta refresh `url=java&#9;script:...`, `srcset` split by a newline, a `style` attribute split by a tab, and a style element split by a tab. Without the fix, all five fail.
### WR-02: Ordinary text still blocks a send through the whole-document `eventHandler` regex
**Files modified:** `modules/postcard/templates.go`, `modules/postcard/safety.go`, `modules/postcard/sitename_test.go`, `modules/postcard/safety_test.go`, `modules/postcard/safety_smoke_test.go`, `modules/postcard/override_smoke_test.go`, `modules/cabana/mail_site_name_postgres_test.go`, `modules/phrasebook/backend/lang/en/lang.yaml`, `modules/phrasebook/backend/lang/pl/lang.yaml`, `modules/postcard/README.md`, `docs/services/mail.md`
**Commit:** 31de2ff9
**Applied fix:**
- Deleted the `eventHandler` regex and its check from `validateHTML`. Since CR-02, the tokenizer walk refuses every `on*` attribute, including inside raw-text elements and comments.
- Fixtures that pinned text as unsafe were moved to the safe side: `Shop onclick=x` and `x onload = 1` in `TestUnsafeText`/`TestMailSafetySmoke`, and the handler names in `TestUnsafeSiteNameDropped`.
- The `TestMailOverrideSmoke/fallback` "unsafe" body is now a Markdown `data:` image, which goldmark keeps and the scheme check refuses.
- The Branding refusal copy (en/pl) drops "text such as onclick=".
- README and docs/services/mail.md now say that text shaped like a handler is sent.
New tests:
- `TestSiteNameSend/*/handler_shaped_variable`: `Name: "Ada, buy one = get one free online = yes"` sends on the default and system layouts.
- `accepts` cases for prose, the footer `© 2026 Online=Shop` and an escaped handler in `svg title`.
- a `refuses` case for an attribute handler with a preceding space.
**Status:** fixed: requires human verification. This changes behaviour that was documented as an accepted residual in the decision note; the note is amended.
### WR-03: The new `UnsafeText` rule refuses ordinary names that the docs promise are accepted
**Files modified:** `modules/postcard/safety.go`, `modules/postcard/sitename_test.go`, `modules/postcard/safety_smoke_test.go`, `modules/cabana/mail_site_name_postgres_test.go`, `modules/postcard/README.md`, `docs/services/mail.md`
**Commit:** 8deb56ff
**Applied fix:** In `scriptURLText`, the `data:` alternative now needs a data-URL shape: `data:` at a scheme boundary, an optional MIME type, then `;` or `,`.
- Now safe: `Data:Lab`, `Big Data:Summit`, `data:Science`, `Shop data:x`. `TestUnsafeText` and `TestMailSafetySmoke` pin them, and the cabana save test stores them.
- Still unsafe: `data:text/html,x`, `data:,x`, `data:;base64,...`, `data: text/html,x`.
**Partial deviation from the review:** I kept `javascript:`/`vbscript:` matching when whitespace follows the colon. `javascript: alert(1)` is a working script URL, and the decision note lists `javascript: Acme` as unsafe on purpose. So `JavaScript: The Good Parts Club` is still refused. Relaxing that is a product decision for the user.
## Planning docs
- `.planning/notes/2026-11-14-mail-url-scheme-check.md` amended in commit 1d2e7e87 (separate docs commit). It covers whitespace stripping, the raw-text/comment re-check and its depth limit, event handlers as attributes only (handler regex dropped), `UnsafeText` print context and the data-URL rule, the new copy, the updated residual risks, and an "Amendment" section.
- Not changed: `35-UI-SPEC.md:427` and `35-08-PLAN.md:130` still quote the 35-08 copy with "text such as onclick=". The note says so. Update UI-SPEC if it is treated as a living copy contract.
## Verification
All gates ran in the **main checkout** (no worktree):
- `go vet ./...` clean, and `go test -short ./...` all ok, after every fix commit.
- `go test ./cmd/summer -run TestDocsTree` (docs checker) passed after every doc change.
- `go test -count=1 ./modules/postcard ./modules/cabana` (Docker-backed, ran directly, no `sudo -u golem` needed): ok (postcard 10.2s, cabana 90.6s). `TestMailSiteNameSafety` (7 subtests) and `TestMailOverrideSmoke/fallback` were confirmed to run, not skip.
- Each regression test was confirmed to fail with the fix reverted (CR-01, CR-02, WR-01).
- Verifier probe (`go test -overlay .../scratchpad/probe/overlay.json`): CR-01 sends all `err=<nil>`; the eight CR-02/WR-01 payloads are all refused; the `noscript` layout override falls back to the file version with inlining on and off; `Editor.Validate` refuses the `noscript` layout.
- `scripts/check-phase35.sh --self-test --go --docker --docs --marker --additive --consumers`: exit 0, every stage PASS. That includes the Docker stage (`go test ./...`), the additive check of 8 packages against v0.6.3 (new unexported helpers only, no exported API change), and the consumers. sm-user-plugin and sm-paymentgateway-plugin stayed clean before and after. The `--admin` stage was not run, because no `admin/` file changed.
- go.mod/go.sum unchanged; no new dependency; nothing pushed or tagged. Other sessions' uncommitted edits (`.planning/state.json`, `.planning/G15OFFICE.md`, `deferred-items.md`, `examples/hello/plugins.gen.go`) were left alone, and every commit staged explicit paths.
---
_Fixed: 2026-11-14T16:45:00Z_
_Fixer: Claude (msd-code-fixer)_
_Iteration: 1_

View File

@@ -0,0 +1,176 @@
---
phase: 35-mail-templates-and-layouts-editor
reviewed: 2026-11-14T15:16:46Z
depth: standard
scope: re-review of gap closure 35-08 / 35-09 (diff 75669b34..HEAD), fixes for CR-01, WR-01, WR-05 of the previous report
files_reviewed: 25
files_reviewed_list:
- docs/services/mail.md
- modules/cabana/README.md
- modules/cabana/mail_admin.go
- modules/cabana/mail_brand_layout_postgres_test.go
- modules/cabana/mail_screens_smoke_test.go
- modules/cabana/mail_site_name_postgres_test.go
- modules/cabana/settings.go
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- modules/postcard/README.md
- modules/postcard/assets/default.htm
- modules/postcard/assets/partials/footer.htm
- modules/postcard/assets/system.htm
- modules/postcard/editor.go
- modules/postcard/editor_smoke_test.go
- modules/postcard/mailer.go
- modules/postcard/override_smoke_test.go
- modules/postcard/override_test.go
- modules/postcard/partials_smoke_test.go
- modules/postcard/safety.go
- modules/postcard/safety_smoke_test.go
- modules/postcard/safety_test.go
- modules/postcard/sitename_test.go
- modules/postcard/templates.go
- scripts/check-phase35.sh
findings:
critical: 2
warning: 3
info: 3
total: 8
status: issues_found
---
# Phase 35: Code Review Report (re-review of gap closure 35-08 / 35-09)
**Reviewed:** 2026-11-14T15:16:46Z
**Depth:** standard
**Files Reviewed:** 25
**Status:** issues_found
This report replaces the 2026-11-13 report (still in git history at `75669b34:.planning/phases/35-mail-templates-and-layouts-editor/35-REVIEW.md`). It re-reviews the gap-closure diff `75669b34..HEAD`:
- the tokenizer-based URL-scheme check (`modules/postcard/safety.go`),
- `postcard.UnsafeText` and the drop of unsafe site names at render time,
- the Branding save rule,
- the literal footer `text` argument,
- the inliner fallback,
- the 35-09 tests and `check-phase35.sh` gate entries.
Findings from the previous report for code outside this diff (WR-02, WR-03, WR-04, IN-01, IN-02, IN-04) were not part of the gap closure and are not repeated here. Spot checks show they are still open (for example `scopeTemplates` at `modules/cabana/mail_admin.go:520`, and `mailLocales` still calling `w.EnabledLocales(ctx, db)` on the request transaction at line 188).
Every claim below was confirmed by probe tests run through `go test -overlay` (scratch test files mapped into `modules/postcard`). No source file was changed. `go test -short ./modules/postcard ./modules/cabana` passes.
## Summary
**CR-01 is only partly resolved.** The colon case is fixed: `Big Data: Summit` and `Metadata: Weekly` now render and send. Unsafe names are dropped at render, and the Branding form refuses them. But `UnsafeText` checks the name on its own, while the footer prints it after `© <year> `. A name starting with `on<letters>=`, such as `Online=Shop` or `onboarding=team`, passes `UnsafeText` and is saved. In the footer it then matches the whitespace-prefixed `eventHandler` regex, and every send on the default and system layouts fails, as in the original CR-01. This happens for a Branding name and for a `mail.from` display name alike (CR-01 below).
**The URL-scheme check can still be bypassed, without any encoding.** `x/net/html`'s tokenizer, used on its own, reads `noscript`, `title`, `textarea`, `xmp`, `noembed`, `noframes`, `plaintext` (and `style`) contents as raw text. `unsafeMarkup` only inspects raw text inside `style`. A mail client renders with scripting off, so it parses `<noscript>` content as markup. `<svg><title>` and `<svg><textarea>` are foreign elements whose children are markup. As a result:
- `<noscript><a href="javascript:alert(1)">`, `<noscript><img src="x"/onerror=alert(1)>` and `<svg><title><a href="javascript:alert(1)">` pass `validateHTML` and are sent, with inlining on and off.
- `values="java&#9;script:..."` and `meta content="0;url=java&#9;script:..."` pass, because the list, meta and CSS checks use the unstripped `dangerousScheme` (CR-02, WR-01).
**Ordinary text still blocks a send.** The raw `\son[a-z]+\s*=` regex still runs over the whole document. A template variable such as `Ada, buy one = get one free` fails `Send` with "rendered HTML contains event handlers". The decision note accepts this as a residual risk. The docs, however, say only event-handler attributes are refused, and the same regex is what makes CR-01 reachable (WR-02).
The rest of the gap closure is sound:
- The footer `text` argument prints the name literally (WR-01 of the previous report is resolved).
- The inliner no longer stops mail (the WR-05 contradiction is resolved).
- The Branding refusal is localized through `localizeControllerError`.
- The `check-phase35.sh` self-test now compares the planted consumer's `go.mod` with `cmp` (previous IN-03 resolved).
- Every newly gated test name exists.
## Narrative Findings (AI reviewer)
## Critical Issues
### CR-01: A site name that `UnsafeText` accepts still stops every default/system-layout send (CR-01 residual)
**File:** `modules/postcard/safety.go:25-27`, `modules/postcard/assets/default.htm:5,34`, `modules/postcard/assets/system.htm:9,39`, `modules/postcard/assets/partials/footer.htm:11`, `modules/postcard/templates.go:49,830-832`, `modules/cabana/mail_admin.go:1810`
**Issue:** `UnsafeText(s)` runs `validateHTML(html.EscapeString(s))` on the name by itself. The only check that can fire on escaped plain text is the raw `eventHandler` regex `(?i)\son[a-z]+\s*=`, which needs whitespace before `on`. The name is trimmed (`siteNameFrom`, `BeforeValidate`), so a name that begins with `on<letters>=` has no whitespace before it and passes. The built-in layouts, however, print it as `© <year> <name>`, which adds the missing space, so the rendered footer `<p>© 2026 Online=Shop</p>` matches the regex. Probe results:
- `UnsafeText("Online=Shop") == false`, and the same for `"onboarding=team"`. `MailBrandSetting.BeforeValidate` therefore saves the name.
- Branding `SiteName: "Online=Shop"`: `Send` of `acme.blog::mail.welcome` (default layout) and of `acme.blog::mail.auto` (system layout) fails with `error calling partial: postcard: rendered HTML contains event handlers`. Nothing is sent.
- No Branding, `mail.from = "\"Online=Shop\" <x@example.com>"` (a valid address): the same failure on both layouts.
`layoutSiteName` returns the name unchanged because `UnsafeText` accepted it. The file version and the override-failure fallback carry the same name, so the fallback fails too. All password-reset and system mail stops. The trigger can be configuration alone, with no admin action, which is exactly what CR-01 was about. The documented guarantee ("never stops a send", README Branding section; docs/services/mail.md) is false for this class of names. No test covers a name whose risk depends on where it is printed. `TestUnsafeText` only checks `"Shop onclick=x"` and `"x onload = 1"`, which already contain the space.
**Fix:** Check the name in the context the layouts print it in, not on its own:
```go
func UnsafeText(s string) bool {
esc := html.EscapeString(s)
// The footer prints "© <year> <name>"; the header prints it in a span and an alt attribute.
return validateHTML("<p>x "+esc+"</p><img alt=\""+esc+"\">") != nil || scriptURLText.MatchString(s)
}
```
A better fix is to remove the cause (see WR-02). The tokenizer walk already refuses every attribute whose name starts with `on`, so the raw regex is redundant once raw-text elements are re-tokenized (CR-02). Dropping it makes text never match. Add `"Online=Shop"` and `"onboarding=team"` cases to `TestSiteNameSend` and `TestUnsafeSiteNameDropped`, through both a Branding name and a `mail.from` display name.
### CR-02: Scheme and handler checks are skipped inside raw-text elements: `<noscript>`, and `<title>`/`<textarea>`/`<style>` in SVG/MathML
**File:** `modules/postcard/safety.go:98-145` (only `inStyle` text is inspected, lines 128-138), `modules/postcard/templates.go:826-833`
**Issue:** `unsafeMarkup` uses `xhtml.NewTokenizer` on its own, without the parser. The tokenizer switches to raw-text or RCDATA mode after any `iframe`, `noembed`, `noframes`, `noscript`, `plaintext`, `script`, `style`, `textarea`, `title` or `xmp` start tag (`readStartTag`). The parser would undo this for foreign content and for `noscript` with scripting off by calling `NextIsNotRawText`, but nothing calls it here. Everything inside those elements becomes one `TextToken`. Apart from `style`, that text is not checked at all, and even `style` text is checked only with the undecoded `dangerousScheme`. Mail clients parse differently:
- They render with scripting disabled, so `<noscript>` content is parsed as ordinary markup.
- In `<svg>`/`<math>`, `title`, `textarea`, `style`, `xmp` and similar are foreign elements, and their children are markup.
Probe results (each one returns `validateHTML(...) == nil`):
- `<noscript><a href="javascript:alert(1)">x</a></noscript>` (no encoding at all)
- `<noscript><img src="x"/onerror=alert(1)></noscript>` (the handler is not whitespace-prefixed, so the raw regex misses it, and the tokenizer never sees the attribute)
- `<svg><title><a href="javascript:alert(1)">x</a></title></svg>`
- `<svg><textarea><a href="javascript:alert(1)">x</a></textarea></svg>`
- `<svg><style><a href="javascript&#58;alert(1)">x</a></style></svg>` (the entity is not decoded in raw text)
A layout override whose HTML contains the `noscript` or `svg title` payload is **sent** with `javascript:alert` intact, both with `DisableAutoInlineCSS` and with inlining on. go-premailer re-serializes the raw text as is, and the post-inline check has the same blind spot. This is the WR-05 bypass again, in a simpler form, and it contradicts decision D-13 as restated in the 35-08 note ("`javascript:`, `vbscript:` and `data:` URLs are still refused at save and at send").
**Fix:** Do not let the tokenizer hide markup:
```go
case xhtml.StartTagToken:
switch t.Data {
case "style":
inStyle = true
case "noscript", "title", "textarea", "xmp", "noembed", "noframes", "plaintext":
// A mail client may parse this content as markup (scripting off, foreign content).
z.NextIsNotRawText()
}
```
`style` can be the same: call `NextIsNotRawText()` and check its CSS as text. Or re-run `unsafeMarkup` recursively on the raw text of any such element, which also covers `<svg><style>`. Alternatively, refuse `noscript`, `plaintext` and `xmp` outright in `rawUnsafeTag`, since none of them belongs in mail. Add the five payloads above to `TestURLSchemeCheck`'s `refuses` list.
## Warnings
### WR-01: List-valued, `meta` content, `style` and comment checks do not strip whitespace, so `java&#9;script:` passes
**File:** `modules/postcard/safety.go:122-124,136,140`
**Issue:** Single-URL attributes go through `hasDangerousScheme`, which removes ASCII whitespace and control characters the way the URL parser does. The other URL-bearing places use `dangerousScheme.MatchString(a.Val)` on the decoded value, which does not. Probe results:
- `<svg><a><animate attributeName="href" values="java&#9;script:alert(1)"/>...` passes. SVG animation `values` that sets `href` is a known script-URL vector, and that is exactly why `values` is in `urlListAttributes`. A URL parser strips the tab.
- `<meta http-equiv="refresh" content="0;url=java&#9;script:alert(1)">` passes, although the meta case is listed as covered.
The `from`/`to`/`by` attributes of the same animation elements are stripped and are refused, so `values` is the inconsistent one.
**Fix:** For the list, meta and CSS cases, run `dangerousScheme` on a whitespace- and control-stripped copy of the decoded value. Factor the stripping loop out of `hasDangerousScheme` as `stripURLSpace(val string) string`, and use `dangerousScheme.MatchString(stripURLSpace(a.Val))`. This over-matches prose only in places where prose does not belong (CSS, lists, meta). Add the two payloads to the `refuses` table.
### WR-02: Ordinary text still blocks a send through the whole-document `eventHandler` regex
**File:** `modules/postcard/templates.go:49,830-832`; docs `modules/postcard/README.md` (Features, "Safety checks"), `docs/services/mail.md` (security paragraph)
**Issue:** `validateHTML` still runs `(?i)\son[a-z]+\s*=` over the raw document, text content included. Probe: `Send` of `acme.blog::mail.welcome` with `Name: "Ada, buy one = get one free"` returns `postcard: rendered HTML contains event handlers`, and nothing is sent. The same happens for `<p>Status: online = yes</p>`. html/template does not escape `=` in text, so any variable (order lines, user-entered names, contact-form text, code snippets with `online=1`) can stop its own message. A user who registers with such a display name never receives a password reset. The decision note lists this as an accepted residual ("out of the user's scope"). The shipped docs say something else: the README now defines handlers as "any attribute whose name starts with `on`", and docs/services/mail.md says "Text is not a URL: a body ... is sent". Neither mentions that text can be refused. This regex is also what makes CR-01 reachable.
**Fix:** The tokenizer walk already refuses every `on*` attribute (`safety.go:119`), including the forms the regex was meant to catch. Once CR-02 is fixed and raw-text elements are tokenized, delete the raw `eventHandler` check from `validateHTML`. `editor.go` does not use it separately. If the regex must stay for now, document in both pages that text containing ` on<word>=` is refused, and add a test that pins that behaviour.
### WR-03: The new `UnsafeText` rule refuses ordinary names that the docs promise are accepted
**File:** `modules/postcard/safety.go:16`, `docs/services/mail.md` (Branding paragraph), `modules/phrasebook/backend/lang/en/lang.yaml:706`
**Issue:** `scriptURLText` treats `data:` followed by any non-space character, at a scheme boundary, as a data URL. Probe: `UnsafeText("Data:Lab")`, `UnsafeText("Big Data:Summit")` and `UnsafeText("data:Science")` are all `true`. `"JavaScript: The Good Parts Club"` is `true` as well, although a following space means it cannot be a URL (`javascript:` is matched without the `\S` requirement). The Branding save rejects these names, and an existing `mail.from` display name of this shape is silently dropped from every mail. The docs say "Ordinary text with a colon, such as `Big Data: Summit`, is accepted", and the refusal text tells the admin to "remove addresses", which these names are not. This is not a security issue: the scheme check no longer reads text, so such a name is harmless in the header and footer.
**Fix:** Since the layouts only print the name as escaped text, which is never a URL, `scriptURLText` only guards against a name that looks like a script link to a human reader. Either drop it, or require URL shape: `data:` followed by a MIME-type-like token (`data:[a-z]+/[a-z0-9.+-]+[;,]`), and `javascript:`/`vbscript:` not followed by whitespace. Pin `"Data:Lab"` as safe in `TestUnsafeText`.
## Info
### IN-01: The footer partial's Markdown `body` branch is never previewed or validated in the partial editor
**File:** `modules/postcard/assets/partials/footer.htm:4,11`, `modules/postcard/editor.go:293-305`
**Issue:** `renderPartial` gives every argument the draft reads (`text` and `body`) a non-empty placeholder. With the new `{{ if .text }}...{{ else }}{{ markdown .body }}{{ end }}`, the preview and `Editor.Validate` only ever exercise the `text` branch. A broken or unsafe `markdown .body` branch in a footer override passes the save and fails only at send, for plugin layouts that still call `partial "footer" "body" ...`. Also, a footer override written against the previous contract (`{{ markdown .body }}` only) now shows an empty copyright line on the built-in layouts. That is unreleased behaviour (not in v0.6.4) and probably acceptable, but it is not called out in the README.
**Fix:** Render the partial preview twice in the editor, once with `text` empty, or validate both branches. Mention in the README partial table that the built-in layouts pass `text`.
### IN-02: `settings.go` now localizes every settings model's `BeforeValidate` error
**File:** `modules/cabana/settings.go:265-270`
**Issue:** The change is right for the Branding refusal, but it changes the error of every plugin settings model. Any `ValidationError` or `ForbiddenError` detail that happens to be a phrase key is now translated, and the response is rebuilt as a new error. Behaviour for plain strings is unchanged, but the change is not mentioned in the cabana README. Core plugins (user, blog, pages, payment) depend on settings saves.
**Fix:** Add a line to the cabana README settings section ("`BeforeValidate` refusals are localized as on a controller save") and a test with a non-mail settings model.
### IN-03: CSS escape sequences bypass the CSS `data:`/`javascript:` checks (accepted residual, undocumented to users)
**File:** `modules/postcard/safety.go:123,136`
**Issue:** `<div style="background:url(d\61ta:image/png;base64,AA)">` passes. The decision note accepts this ("mail clients do not run script URLs from CSS"), but the README and docs state flatly that `data:` URLs in `style` attributes and style elements are refused.
**Fix:** Either decode CSS escapes (`\[0-9a-f]{1,6}\s?` and `\.`) before matching, or qualify the docs sentence.
---
_Reviewed: 2026-11-14T15:16:46Z_
_Reviewer: Claude (msd-code-reviewer)_
_Depth: standard_

View File

@@ -0,0 +1,193 @@
---
status: complete
phase: 35-mail-templates-and-layouts-editor
source: [35-VERIFICATION.md]
started: 2026-11-13T13:46:04.193Z
updated: 2026-11-16T09:10:00.000Z
---
## Current Test
<!-- OVERWRITE each test - shows where we are -->
[testing complete]
## Tests
### 1. Template list
expected: Settings → Mail → Mail templates lists the templates from user, mfa, paymentgateway and quizzes.
result: pass
retest_reason: "Framework part of G-35-9 fixed by quick 261115-cha (cross-plugin layout by full code); the list itself was correct. sm-mfa-plugin layout key deferred to after the framework tag; previous result: issue"
reported: "only paymentgateway and user emails, both correct. mfa e-mail uses Default template and no \"mfa\" template is provided. if it depends on User plugin (i think it is) it can use User template"
severity: minor
note: "quizzes registers no templates (MailTemplates returns nil); listing it in the expectation was a test-writing error, not a defect. Previous G-35-1 (one row per locale) confirmed fixed."
### 2. Customize and save a template
expected: Open the user plugin's activate template (the row without a locale suffix), change the subject to "UAT subject", Save. Reopen it: the subject is "UAT subject" and the row shows as customized.
result: pass
previous_result: pass
retest_reason: "the save-time safety check changed after the UAT pass (2026-11-13T21:09:53Z): modules/postcard/safety.go (35-08 tokenizer check, CR-02 raw-text/comment re-check, WR-01 whitespace stripping, then the quote-aware tag reading of quick 261114-p5m, d6ac0aeb) and modules/postcard/templates.go (WR-02 removed the handler regex)"
### 3. Reset to file version
expected: On the same template click "Reset to file version" and confirm. The subject is back to the file's subject and the row no longer shows as customized.
result: pass
### 4. Drift notice
expected: Customize activate again and save. Edit ../sm-demo-app/plugins/golem15/user/views/mail/activate.htm (change any text), restart with scripts/dev.sh down && scripts/dev.sh up. Opening the template shows a callout that the file changed since it was customized; your saved version is still what's used.
result: pass
### 5. Layout editor
expected: Settings → Mail → Mail layouts, open "user". HTML, plain text and CSS tabs each show a code editor with syntax highlighting; typing works and Save persists after reload.
result: pass
previous_result: pass
retest_reason: "layout validation in modules/postcard/safety.go and templates.go changed after the UAT pass (2026-11-13T21:09:53Z), including the 'nests raw-text elements or comments too deeply' refusal and the second, quote-aware tag reading (d6ac0aeb)"
### 6. Insert image into layout
expected: In the layout HTML tab, use the insert-image button, pick or upload an image. The inserted <img src> is a full URL starting with http://127.0.0.1:8097/.
result: pass
previous_result: pass
retest_reason: "the src/href check that validates the inserted img was rewritten after the UAT pass (2026-11-13T21:09:53Z): tokenizer check in 35-08, stripURLSpace refactor in WR-01, shared unsafeAttrs and a second tag reading in d6ac0aeb"
### 7. Branding
expected: Mail branding: change a colour and set a logo, Save, reload. Values persist; the preview of any template uses the new colour/logo.
result: pass
previous_result: pass
retest_reason: "modules/cabana/mail_admin.go BeforeValidate now calls postcard.UnsafeText (35-08), whose rule changed again in CR-01 (printContext), WR-03 (data-URL shape) and d6ac0aeb (validateHTML gained the tag reading); modules/cabana/settings.go error localization and modules/postcard/editor.go brand preview changed after the UAT pass (2026-11-13T21:09:53Z)"
### 8. Preview
expected: On a template, the HTML preview renders the mail with its layout; the plain-text tab shows the text version.
result: pass
retest_reason: "G-35-8 fixed by 35-06/35-07 (built-in layouts) and quick 261114-p5n (plugin layouts); previous result: issue"
reported: "logo doesn't appear, only kind of proper layout is System layout (logo doesn't show, Aktywuj konto on activate email doesn't seem to be a button, totally unstyled), other layouts sucks, I expect beautiful and working out of box layouts after this phase."
severity: major
### 9. Send test to me
expected: Click "Send test to me". ../sm-demo-app/logs/go.log gets a mail entry addressed to the signed-in admin's email (no other recipient can be entered).
result: pass
note: "go.log entry to=[admin@example.test], subject Ustaw nowe hasło (restore). Text part still shows the user layout text wrapper (-- ... --) and raw Markdown: the known plugin follow-up after the framework tag (fix user.htm text wrapper)."
previous_result: pass
retest_reason: "modules/postcard/mailer.go (site name selection), templates.go and safety.go (send-time validateHTML, handler regex removed, tag reading added) and the default/system layouts and footer partial changed after the UAT pass (2026-11-13T21:09:53Z)"
### 10. Confirm judgment-tier prohibition: postcard imports modules/lagoon/attach for AbsolutePublicURL.
expected: Accept as intentional (D-24 / 35-01 SUMMARY threat_flag dependency-surface) or request a follow-up to move AbsolutePublicURL out of lagoon.
result: pass
note: "User accepted the lagoon/attach import as intentional."
### 11. Branding refusal on the demo instance
expected: On the demo app: Site name 'javascript:alert(1)' and 'data:text/html,x' are refused with the translated message under Site name (en and pl, copy without 'text such as onclick='); 'Online=Shop', 'Data:Lab' and 'Big Data: Summit' save and appear in the preview header and footer
result: pass
### 12. Review the CR-01, CR-02 and WR-02 safety-rule changes, including the CR-02 residual fix
expected: Accept or reject the rule changes that 35-REVIEW-FIX.md marks 'requires human verification': (CR-01) UnsafeText checks the name where the layouts print it; (CR-02) raw-text element and comment content is re-checked as markup with an 8-level depth limit; (CR-02 residual, quick 261114-p5m) every tag is read a second time with attribute quoting alone deciding where it ends, which can over-refuse after an unbalanced quote in a comment or style element; (WR-02) text shaped like an event handler is sent, and only attributes count as handlers. The decision note .planning/notes/2026-11-14-mail-url-scheme-check.md was amended twice to match
result: pass
### 13. Inlined mail in a real inbox
expected: Test-send a template in the default layout to a real webmail/Outlook inbox; the button and card keep their colours with the style block stripped
result: pass
note: "2026-11-16: sent over SMTP from the demo to Gmail web. A template switched to the default layout with the button partial: the button kept its colour, the header and footer bands and link colour survived with the style block stripped. The logo is broken only because app.url is 127.0.0.1, unreachable for Gmail's image proxy."
### 14. Confirm judgment-tier prohibitions of 35-05..35-09, the review fix round and quick 261114-p5m
expected: Accept: no sibling repository changed by this phase (sm-user-plugin and sm-paymentgateway-plugin clean before and after the verifier's --consumers run; the concurrent restyle there is quick 261114-p5n, not this phase); nothing pushed or tagged (master is 113 commits ahead of origin/master, newest tag v0.6.4 predates the gap closures); framework code, docs and tests name no consuming application (--marker passed)
result: pass
## Summary
total: 14
passed: 12
issues: 1
pending: 0
skipped: 1
blocked: 0
## Gaps
- gap_id: G-35-9
truth: "The mfa plugin's two-factor code mail renders in the user plugin's layout (mfa requires golem15.user), not the bare Default layout."
status: resolved
resolved_by: quick 261115-cha
resolved_at: 2026-11-16
reason: "User reported: mfa e-mail uses Default template and no \"mfa\" template is provided. if it depends on User plugin (i think it is) it can use User template"
severity: minor
test: 1
root_cause: "sm-mfa-plugin views/mail/two_factor_code{,-en}.htm set no layout key and MailLayouts() returns nil, so postcard falls back to the default alias. postcard cannot reference another plugin's layout: Catalog.resolveLayoutLocked looks a layout up only in the registering plugin's own aliases (c.aliases[pluginID]) and the built-in aliases, so layout = \"user\" in mfa is an unknown layout at boot."
artifacts:
- path: "modules/postcard/templates.go"
issue: "resolveLayoutLocked resolves only own-plugin aliases and built-ins; no full-code (vendor.plugin::mail.layouts.x) reference to a layout another plugin registered"
- path: "../sm-mfa-plugin/views/mail/two_factor_code.htm, two_factor_code-en.htm"
issue: "no layout key"
- path: "../sm-mfa-plugin/mail.go"
issue: "MailLayouts returns nil"
missing:
- "postcard: accept a full layout code in a template's layout key when that layout is already registered (plugin Requires ordering guarantees golem15.user registers first); README/docs updated"
- "sm-mfa-plugin: layout = \"golem15.user::mail.layouts.user\" in both templates, after the framework requirement that supports it (or, to stay on v0.6.0, ship its own copy of the user layout)"
debug_session: ""
closure_note: "Framework part closed by quick 261115-cha (1fb42542, b8487b02): a template layout key accepts a full layout code another registered plugin owns; tests TestCrossPluginLayout, TestCrossPluginLayoutOverride, TestCrossPluginLayoutSync. Plugin part deferred to the follow-up after the framework tag: sm-mfa-plugin sets layout = \"golem15.user::mail.layouts.user\" in both two_factor_code templates."
- gap_id: G-35-1
truth: "Locale variants of one mail template are managed as a single backend entry (per-locale tabs/switcher), so a site with many locales does not get one list row per locale."
status: resolved
resolved_by: 35-07-PLAN.md
resolved_at: 2026-11-14
reason: "User reported: fact that each locale is a separate entry in backend is absolute disaster, why was it planned like that? imagine site with 50 locales."
severity: major
test: 1
root_cause: "Design decision D-05 (35-CONTEXT.md): locale variants stay separate templates. postcard.SyncIndex writes one summer_mail_templates row per file (activate.htm, activate-en.htm), with TemplateLocale parsed from the name suffix; cabana's MailTemplate list shows each row with a locale column and filter. There is no grouping key (base code) and no per-locale editing inside one record, so N locales produce N list rows per template."
artifacts:
- path: "modules/postcard/store.go"
issue: "SyncIndex/templates table keyed by full code incl. locale suffix; no base-code column to group variants"
- path: "modules/postcard/templates.go"
issue: "TemplateLocale only derives a label; variants are not linked to their base template"
- path: "modules/cabana/mail_admin.go"
issue: "MailTemplate list/filter/locale column expose one row per variant; form edits a single variant"
- path: "admin/src (mail template form)"
issue: "No locale switcher/tabs within a template record"
missing:
- "Supersede D-05 with a decision note: one entry per template (base code), locale variants edited via a locale switcher/tabs inside it"
- "Store a base code (or group by stripped suffix) so the list shows one row per template, with a count/indicator of customized locales"
- "Template form: locale switcher listing app locales; a locale without a file or override falls back to the default-locale content and can be customized per locale"
- "Reset/drift/customized status per locale within the one record"
- "Sending keeps resolving code-<locale> overrides first, so no change for plugins (non-breaking for user/paymentgateway)"
debug_session: ""
- gap_id: G-35-8
truth: "Mail preview renders the template inside a polished, working layout out of the box: branding logo shows, call-to-action links (e.g. 'Aktywuj konto' in activate) render as styled buttons, and every shipped layout (system and plugin layouts such as user, paymentgateway) looks finished."
status: resolved
resolved_by: 35-07-PLAN.md
resolved_at: 2026-11-14
reason: "User reported: logo doesn't appear, only kind of proper layout is System layout (logo doesn't show, Aktywuj konto on activate email doesn't seem to be a button, totally unstyled), other layouts sucks, I expect beautiful and working out of box layouts after this phase."
severity: major
test: 8
root_cause: "Phase 35 features work (logo URL built and passed as logoUrl, brand CSS applied, button partial renders) but nothing shipped uses them: (1) no layout (postcard default/system/minimal, plugin user/paymentgateway) prints logoUrl and there is no header partial; (2) sm-user-plugin and sm-paymentgateway-plugin templates use Markdown links instead of the button partial, and both plugins require framework v0.6.0 which has no partial func; (3) default.htm and the plugin layouts are bare stubs (no wrapper, card, header, footer; .layout-user/.layout-paymentgateway/.content-body unstyled), system.htm lacks header/footer and side padding; (4) CSS is only in a <style> block, never inlined, so real mail clients will still render unstyled (UI-SPEC and D-10 wrongly claim inlining)."
artifacts:
- path: "modules/postcard/assets/default.htm"
issue: "bare content-body, no logo/header/card/footer (35-01 gate kept it unchanged)"
- path: "modules/postcard/assets/system.htm"
issue: "no header/logo/footer, content cell has zero side padding"
- path: "modules/postcard/assets/minimal.htm"
issue: "no logo"
- path: "modules/postcard/templates.go"
issue: "built-in partials lack header/footer; layouts get no display name"
- path: "modules/postcard/assets/brand.css.tmpl"
issue: "no logo rule; content-body/layout-user/layout-paymentgateway unstyled"
- path: "modules/postcard/mailer.go"
issue: "CSS not inlined onto elements"
- path: "../sm-user-plugin/views/mail/layouts/user.htm"
issue: "stub layout; odd text wrapper"
- path: "../sm-user-plugin/views/mail/{activate,restore,invite}{,-en}.htm"
issue: "Markdown-link CTA instead of button partial"
- path: "../sm-paymentgateway-plugin/views/mail/layouts/paymentgateway.htm"
issue: "stub layout"
- path: "../sm-paymentgateway-plugin/views/mail/order/*.htm"
issue: "Markdown-link CTA plus duplicated URL"
- path: "../sm-user-plugin/go.mod, ../sm-paymentgateway-plugin/go.mod"
issue: "require framework v0.6.0 without partial func"
missing:
- "Port WinterCMS default layout (wrapper, header with logo or name fallback, white card, footer) to default.htm and text wrapper; header/logo/footer and padding in system.htm; logo in minimal.htm"
- "Built-in header and footer partials; display-name variable for header/footer (Branding field or layout var; app.name is a slug)"
- "brand.css.tmpl: logo rule, footer/padding checks, drop unstyled content-body"
- "Inline CSS at render with per-layout opt-out (dependency decision or in-house inliner)"
- "Render tests: logo img in default/system, button partial output; README, docs/services/mail.md, UI-SPEC inlining text updated; decision note superseding 35-01 'default.htm untouched'"
- "Plugins after framework tag: bump framework requirement; user templates use button partial; paymentgateway order templates use button partial, drop duplicate URL; replace user/paymentgateway layout contents keeping their names; fix user.htm text wrapper"
- "Demo: reset UAT overrides of golem15.user::mail.layouts.user and golem15.user::mail.activate before re-checking"
debug_session: ".planning/debug/mail-layouts-unstyled.md"
closure_note: "Framework part closed by 35-05..35-07: built-in default/system/minimal layouts with the logo or site-name header and the footer, Branding site name with the mail.from fallback, header/footer partials and button partial support in every built-in layout, CSS inlined at render with a per-layout opt-out (35-07 tests: TestBuiltinLayoutsLogo, TestHeaderFooterPartials, TestButtonPartial, TestSiteName, TestInlineCSS, TestInlineCSSOptOut, TestInlineFailure, TestMailBrandSiteName, TestMailLayoutInlineOptOut). Plugin part deferred to the follow-up after the framework tag: sm-user-plugin and sm-paymentgateway-plugin framework bump, their CTAs through the button partial, finished user/paymentgateway layouts."
rerun_scope: "Re-run test 8 on sm-demo-app scoped to the built-in layouts: reset the UAT overrides of golem15.user::mail.activate and golem15.user::mail.layouts.user, save Branding with a logo and a Site name, preview a template switched to the default layout and to the system layout with a body override that calls the button partial; expect the logo header (or the name), the white card, the styled button and the footer. Deferred follow-up check after the plugin follow-up: the activate CTA renders as a button and the user/paymentgateway layouts look finished."

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,114 @@
---
phase: "35"
slug: "mail-templates-and-layouts-editor"
# status lifecycle: draft (seeded by plan-phase) → validated (set by validate-phase §6)
status: draft
nyquist_compliant: true
wave_0_complete: true
created: "2026-11-06"
---
# Phase 35 — Validation Strategy
> Per-phase validation contract for feedback sampling during execution. Derived from `35-RESEARCH.md` § Validation Architecture.
---
## Test Infrastructure
| Property | Value |
|----------|-------|
| **Framework** | Go `testing` (+ testcontainers-go for Postgres/Mailpit); Vitest (happy-dom) and Vitest browser mode with Playwright for the admin SPA |
| **Config file** | `admin/vitest.config.*`, `admin/vitest.browser.config.ts`; Go: none |
| **Quick run command** | `go test -short ./modules/postcard/... ./modules/pact/... ./modules/cabana/... ./modules/lagoon/...` |
| **Full suite command** | `go vet ./... && go test ./... && npm --prefix admin run test && npm --prefix admin run test:browser && npm --prefix admin run typecheck && scripts/check-admin-openapi.sh --check && scripts/check-admin-dist.sh && summer docs:build --check` |
| **Estimated runtime** | ~60 seconds quick, ~10 minutes full |
---
## Sampling Rate
- **After every task commit:** quick run command plus `go vet ./...` (and `npm --prefix admin run test` for SPA tasks)
- **After every plan wave:** full suite command
- **Before `/msd-verify-work`:** full suite plus `scripts/check-phase35.sh` (also runs the sm-user-plugin and sm-paymentgateway-plugin mail tests) must be green
- **Max feedback latency:** 120 seconds
---
## Per-Decision Verification Map
| Decision | Behavior | Test Type | Automated Command | File Exists | Status |
|----------|----------|-----------|-------------------|-------------|--------|
| D-11/D-14 | Override wins; file wins without one; render failure and DB error fall back to file; caller subject still wins | unit | `go test -short ./modules/postcard -run 'TestOverride\|TestFallback'` | ✅ 35-04 | ✅ green |
| store | DB source reads real tables; works with no cabana activation | Postgres | `go test ./modules/postcard -run TestStore` | ✅ 35-04 | ✅ green |
| D-12 | `HasMailPartials` boot errors; body partial survives Markdown; nonce forgery fails; layout partial; text part | unit | `go test -short ./modules/postcard -run TestPartial` | ✅ 35-04 | ✅ green |
| D-15 | `sample.*` keys parsed; old keys ignored; placeholder walker fills nested/range/dot | unit | `go test -short ./modules/postcard -run TestSample` | ✅ 35-04 | ✅ green |
| D-13 | Draft validation errors mapped to fields | unit + Postgres | `go test -short ./modules/postcard -run TestValidateDraft`; `go test ./modules/cabana -run TestMailSave` | ✅ 35-04 | ✅ green |
| D-07 | Drift flagged and filterable; re-save clears | Postgres | `go test ./modules/cabana -run TestMailDrift` | ✅ 35-04 | ✅ green |
| D-06/D-08 | Reset clears override; in-use custom layout delete refused with count; file layout never deletable | Postgres | `go test ./modules/cabana -run 'TestMailReset\|TestMailLayoutDelete'` | ✅ 35-04 | ✅ green |
| D-10/D-11 | No brand row → `mail.brandCss`; saved → compiled CSS replaces it; `mail.css` still applied; bad colour 422 | unit + Postgres | `go test -short ./modules/postcard -run TestBrand`; `go test ./modules/cabana -run TestMailBrand` | ✅ 35-04 | ✅ green |
| D-03 | Permission split per controller, preview, picker list vs upload; no default role grants | Postgres | `go test ./modules/cabana -run TestMailPermissions` | ✅ 35-04 | ✅ green |
| D-17 | Recipient always the admin's own email; 429 + Retry-After after the limit | Postgres | `go test ./modules/cabana -run TestMailTestSend` | ✅ 35-04 | ✅ green |
| D-05 | Locale parsed for enabled locales; locale filter | unit | `go test -short ./modules/cabana -run TestMailLocale` | ✅ 35-04 | ⚪ superseded by `.planning/notes/2026-11-13-mail-template-locale-groups.md` (35-05): one record per template, no locale filter; see the G-35-1 row |
| sync | Index sync idempotent, concurrency-safe, custom rows untouched | Postgres | `go test ./modules/postcard -run TestSync` | ✅ 35-04 | ✅ green |
| consumers | user + paymentgateway mail renders unchanged | unit (sibling repos) | `bash scripts/check-phase35.sh --consumers` | ✅ | ✅ green |
| byte-identity | Existing postcard tests pass; default layout output unchanged | unit | `go test -short ./modules/postcard/...` | ✅ | ⚪ superseded by `.planning/notes/2026-11-13-mail-layouts-css-inlining.md` (35-06): default.htm is WinterCMS's default layout and output is CSS-inlined; existing postcard tests stay green, see the G-35-8 row |
| G-35-1 | Locale grouping: `TemplateBase` / `Catalog.TemplateFor` rules; send order `<template>-<locale>` customization → default customization → default file, file-backed names unchanged; `EnsureLocaleRows` (non-default locales without files, idempotent, customized content kept, file_hash follows the base); base_code from SyncIndex; reset of a fallback code; migrations roll back | postcard unit + Postgres | `go test -short ./modules/postcard -run '^(TestTemplateBase\|TestTemplateFor\|TestSendLocaleFallback)$'`; `go test ./modules/postcard -run '^TestEnsureLocaleRows$'` | ✅ 35-07 | ✅ green |
| G-35-1 | Admin side: one list row per template, customized locales, grouped badges and status filter, `localeVariants` order/labels/states/current, default version on a not-customized fallback row, save then send, reset, drift through the base file, file version against the base file, out-of-group ids 404, permission split on fallback rows, a locale enabled at run time | cabana Postgres | `go test ./modules/cabana -run '^TestMailLocaleGroups$'` | ✅ 35-07 | ✅ green |
| G-35-1 | Locale switcher: options, current, navigation (query kept), restored selection on refusal or a throwing guard; FormView shows it only with two or more variants and asks the unsaved-changes confirm | SPA unit | `npm --prefix admin run test -- tests/form/LocaleVariantSwitcher.test.ts tests/form/FormViewMail.test.ts` | ✅ 35-07 | ✅ green |
| G-35-8 | Built-in layouts: logo img (alt = site name) in the header of default and system, above the message in minimal; site name or nothing without a logo; header/footer partials (logo, name, url; © year and name); button partial (class, href, type) in every built-in layout; site name precedence with the mail.from fallback | postcard unit | `go test -short ./modules/postcard -run '^(TestBuiltinLayoutsLogo\|TestHeaderFooterPartials\|TestButtonPartial\|TestSiteName)$'` | ✅ 35-07 | ✅ green |
| G-35-8 | CSS inlining: brand colour on the button, DOCTYPE kept, media query left in a style block, text part unchanged, safety check on the inlined output (an unsafe raw layout override falls back to the file), per-layout opt-out (file header key, override column, layout draft), inliner failure sends the un-inlined HTML with one warning per layout per minute | postcard unit | `go test -short ./modules/postcard -run '^(TestInlineCSS\|TestInlineCSSOptOut\|TestInlineFailure)$'` | ✅ 35-07 | ✅ green |
| G-35-8 | Admin side: Branding site name (trimmed, max 255, preview and send header, no header row without name or logo); layout form inlining switch (file layout, reset to the file value, custom layout with the switch off) | cabana Postgres | `go test ./modules/cabana -run '^(TestMailBrandSiteName\|TestMailLayoutInlineOptOut)$'` | ✅ 35-07 | ✅ green |
| G-35-8 | Core plugins still send their mail against this checkout with the go-premailer requirement, read-only: scratch `-modfile` copies (GOWORK=off, GOPROXY=off), framework resolves to this checkout, sibling trees clean before and after | unit (sibling repos) | `bash scripts/check-phase35.sh --consumers` (self-test plants the dirty-tree and modfile cases) | ✅ 35-07 | ✅ green |
| CR-01 | Site names on the send path: mail.from "Metadata: Weekly" and Branding "Big Data: Summit" show in the header, footer and text part of the default and system layouts on the file-version, override and override-failure fallback paths; an unsafe name (`javascript:alert(1)`, `Shop onclick=x`) is left out of every path with one value-free warning per source per minute and the send succeeds; editor saves and previews under a stored unsafe name are not refused; `postcard.UnsafeText` safe/unsafe texts | postcard unit | `go test -short ./modules/postcard -run '^(TestSiteNameSend\|TestUnsafeSiteNameDropped\|TestUnsafeText\|TestMailSafetySmoke)$'` | ✅ 35-09 | ✅ green |
| CR-01 | Anchored, decoded scheme check: prose ("metadata:", "Big Data: Summit", titles, scheme words in a query) passes; every URL-bearing attribute, srcset, style attribute and element, meta refresh and the `&#58;`, `&#x3A;`, `&colon;`, `&#106;`, tab- and newline-split spellings are refused; an inlined result that fails the check sends the style-block version | postcard unit | `go test -short ./modules/postcard -run '^(TestURLSchemeCheck\|TestInlineUnsafeOutput)$'` | ✅ 35-09 | ✅ green |
| CR-01 | Admin side: a Branding save of an unsafe site name is a 422 on site_name in en and pl and stores nothing; prose names save; the Branding preview drops an unsafe draft name; a name stored before the check never refuses a template or layout save or stops a send; a mail.from display name with a colon shows on the default and system layouts | cabana Postgres | `go test ./modules/cabana -run '^(TestMailSiteNameSafety\|TestMailBrandSiteName)$'` | ✅ 35-09 | ✅ green |
| WR-01 | The footer of the default and system layouts prints the site name literally and escaped (`*Acme*`, `Acme <Studio>`, `[x](url)`): no emphasis, no HTML comment, no link; the header shows the same text and the text part's footer line the name verbatim; the footer partial's body argument stays Markdown | postcard unit | `go test -short ./modules/postcard -run '^TestFooterSiteNameLiteral$'` | ✅ 35-09 | ✅ green |
| WR-05 | The scheme check reads decoded attribute values: a layout override with `href="javascript&#58;alert(1)"` falls back to the file version with inlining on and off, and the editor refuses it on content_html (CSS URLs on content_css); a failing inlined result is sent un-inlined with one warning per layout | postcard unit | `go test -short ./modules/postcard -run '^(TestURLSchemeCheck\|TestInlineUnsafeOutput)$'` | ✅ 35-09 | ✅ green |
| UI | codeeditor keys, insertImage escaping, footer record actions, preview sandbox | SPA unit + browser | `npm --prefix admin run test -- MailPreview CodeEditor insertImage FormViewMail`; `npm --prefix admin run test:browser -- codeeditor` | ✅ 35-04 | ✅ green |
| gates | OpenAPI/schema in sync; dist matches; docs identifiers exist | scripts | `scripts/check-admin-openapi.sh --check`; `scripts/check-admin-dist.sh`; `go test ./cmd/summer -run TestDocsTree` | ✅ | ✅ green |
*Status key (historical): pending · green · red · flaky · superseded — every map row above is green or superseded.*
---
## Wave 0 Requirements
- [x] `modules/postcard/override_test.go`, `partials_test.go`, `samples_test.go`, `brand_test.go`, `store_postgres_test.go` (TestMain with `flag.Parse()` + `testing.Short()`) — 35-04 Task 2
- [x] `modules/cabana/mail_*_postgres_test.go` reusing the 19.6.1 screens harness — 35-04 Task 3
- [x] `admin/tests/form/CodeEditorField.test.ts`, `admin/tests/browser/codeeditor.test.ts`, `admin/tests/form/MailPreviewField.test.ts`, `admin/tests/form/insertImage.test.ts` — 35-04 Task 4
- [x] Update `modules/pact/capabilities_test.go` `TestRowStateValues` and attach absolute URL coverage — 35-04 Task 2
- [x] `scripts/check-phase35.sh` — 35-04 Task 1
- [x] Gap closure (G-35-1, G-35-8): `modules/postcard/{locale,locale_postgres,layouts,inline}_test.go`, `modules/cabana/mail_{locale,brand_layout}_postgres_test.go`, extended `admin/tests/form/{LocaleVariantSwitcher,FormViewMail}.test.ts`; `check-phase35.sh` requires every new name and runs the consumers through scratch modfiles — 35-07
- [x] Gap closure (CR-01): `modules/postcard/sitename_test.go`, `modules/postcard/safety_test.go`, `modules/cabana/mail_site_name_postgres_test.go`; `check-phase35.sh` requires every new name and its self-test compares the planted consumer's go.mod (IN-03) — 35-09
---
## Manual-Only Verifications
| Behavior | Decision | Why Manual | Test Instructions |
|----------|----------|------------|-------------------|
| Test-send mail looks right in a real inbox | D-17 | Visual rendering in mail clients | Send a draft from the template form to Mailpit and check HTML and text parts |
| Code editor feel (highlighting, focus, theme) | D-09 | Visual | Open a layout form in the dev SPA, edit each tab |
| One admin entry per template with a locale switcher (UAT test 1 re-run) | G-35-1 | Placement and readability of the switcher and the Customized locales column in the embedded admin | On sm-demo-app rebuilt on this framework commit: open Mail templates, check one row per template with Customized locales, open a template, switch to a locale without a file, save it, switch back; re-run UAT test 1 in full |
| Built-in layouts look finished (UAT test 8 re-run, scoped) | G-35-8 | Visual rendering of the layouts and the preview | On sm-demo-app: first reset the UAT overrides of `golem15.user::mail.activate` and `golem15.user::mail.layouts.user`; save Branding with a logo and a Site name; preview a template switched to the default layout, then to the system layout, with a body override that calls the button partial (`{{ partial "button" "url" "https://example.com" "body" "Go" }}`). Expect the logo header (or the name without a logo), the white card, the styled button and the footer (© year and name) |
| Inlined mail in a real inbox | G-35-8 | Mail clients (webmail, Outlook) differ in what they keep of a style block | Test-send a template in the default layout to a real inbox; the button and card keep their colours with the style block stripped |
| Branding site name refusal | CR-01 | The field line under Site name in the embedded admin is visual | On sm-demo-app: type `javascript: Acme` as the Branding Site name and save; the refusal line shows under the field and nothing is saved. Type `Big Data: Summit` and save; it saves and shows in the preview header and footer |
| Deferred follow-up check: plugin mail | G-35-8 (plugin part) | Deferred to the plugin follow-up after the framework tag (sm-user-plugin, sm-paymentgateway-plugin: framework bump, button partial in their templates, finished user/paymentgateway layouts keeping their names) | After the plugin follow-up ships: the activate CTA renders as a button and the user and paymentgateway layouts look finished |
**G-35-8 status:** framework part closed by 35-05..35-07 (built-in layouts, logo, site name, button partial support, CSS inlining, consumers gate). Plugin part deferred: the plugin templates' CTA through the button partial, the replaced user/paymentgateway layouts and the plugins' framework bump wait for the plugin follow-up after the framework tag (deferred follow-up check above).
**CR-01 status:** closed by 35-08 and 35-09. Site names are checked with `postcard.UnsafeText`: refused at Branding save (422 on site_name), left out at render with a warning, so no saved value can stop mail on the built-in layouts; the URL-scheme check reads decoded URL-bearing attributes only. Decision note `.planning/notes/2026-11-14-mail-url-scheme-check.md`.
---
## Validation Sign-Off
- [x] All tasks have `<automated>` verify or Wave 0 dependencies
- [x] Sampling continuity: no 3 consecutive tasks without automated verify
- [x] Wave 0 covers all MISSING references
- [x] No watch-mode flags
- [x] Feedback latency < 120s
- [x] `nyquist_compliant: true` set in frontmatter
**Approval:** pending (gate green after 35-04, after 35-07 and after 35-09 with the gap-closure tests; formal validate-phase may follow)

View File

@@ -0,0 +1,450 @@
---
phase: 35-mail-templates-and-layouts-editor
verified: 2026-11-16T07:16:15Z
status: passed
score: 23/23 must-haves verified
covered_files:
- .planning/phases/35-mail-templates-and-layouts-editor/35-01-PLAN.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-01-SUMMARY.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-02-PLAN.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-02-SUMMARY.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-03-PLAN.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-03-SUMMARY.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-04-PLAN.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-04-SUMMARY.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-05-PLAN.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-05-SUMMARY.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-06-PLAN.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-06-SUMMARY.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-07-PLAN.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-07-SUMMARY.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-08-PLAN.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-08-SUMMARY.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-09-PLAN.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-09-SUMMARY.md
- .planning/quick/261114-p5m-fix-cr-02-residual-quoted-end-tags-in-ra/261114-p5m-PLAN.md
- .planning/quick/261114-p5m-fix-cr-02-residual-quoted-end-tags-in-ra/261114-p5m-SUMMARY.md
- .planning/quick/261115-cha-let-a-mail-template-use-another-plugin-s/261115-cha-PLAN.md
- .planning/quick/261115-cha-let-a-mail-template-use-another-plugin-s/261115-cha-SUMMARY.md
- admin/openapi/admin.json
- admin/package-lock.json
- admin/package.json
- admin/src/api/schema.d.ts
- admin/src/api/types.ts
- admin/src/components/form/LocaleVariantSwitcher.vue
- admin/src/components/form/codeeditor/editor.ts
- admin/src/components/form/fields/CodeEditorField.vue
- admin/src/components/form/fields/ColorPickerField.vue
- admin/src/components/form/fields/MailImageField.vue
- admin/src/components/form/fields/MailPreviewField.vue
- admin/src/components/form/fields/MarkdownField.vue
- admin/src/components/form/fields/PartialField.vue
- admin/src/components/form/registry.ts
- admin/src/components/list/DataTable.vue
- admin/src/components/list/RowStateBadges.vue
- admin/src/components/mail/MailImagePicker.vue
- admin/src/components/mail/insertImage.ts
- admin/src/styles/main.css
- admin/src/views/FormView.vue
- admin/src/views/ListView.vue
- admin/src/views/SettingsFormView.vue
- admin/tests/browser/codeeditor-smoke.test.ts
- admin/tests/browser/codeeditor.test.ts
- admin/tests/form/CodeEditorField.test.ts
- admin/tests/form/ColorPickerField.test.ts
- admin/tests/form/FormViewMail.test.ts
- admin/tests/form/LocaleVariantSwitcher.test.ts
- admin/tests/form/MailImageField.test.ts
- admin/tests/form/MailImagePicker.test.ts
- admin/tests/form/MailPreviewField.test.ts
- admin/tests/form/insertImage.test.ts
- admin/tests/form/mail-smoke.test.ts
- admin/tests/list/RowStateBadges.test.ts
- admin/tests/views/SettingsFormView.test.ts
- docs/backend/admin-spa.md
- docs/backend/forms.md
- docs/backend/lists-and-filters.md
- docs/backend/settings.md
- docs/backend/users-and-permissions.md
- docs/database/migrations.md
- docs/plugins/registration.md
- docs/services/mail.md
- docs/services/rate-limiting.md
- docs/services/storage.md
- go.mod
- go.sum
- modules/boardwalk/dist/assets/dm-mono-latin-400-normal--0xN8mdc.woff
- modules/boardwalk/dist/assets/dm-mono-latin-400-normal-4GdczIuU.woff2
- modules/boardwalk/dist/assets/dm-mono-latin-500-normal-CN8Miw6E.woff
- modules/boardwalk/dist/assets/dm-mono-latin-500-normal-DRMDZjhP.woff2
- modules/boardwalk/dist/assets/dm-mono-latin-ext-400-normal-1aZr6b2b.woff
- modules/boardwalk/dist/assets/dm-mono-latin-ext-400-normal-C2zvOubV.woff2
- modules/boardwalk/dist/assets/dm-mono-latin-ext-500-normal-BtRyHRi6.woff2
- modules/boardwalk/dist/assets/dm-mono-latin-ext-500-normal-Dw3M13d8.woff
- modules/boardwalk/dist/assets/dm-sans-latin-400-normal-BwCSEQnW.woff
- modules/boardwalk/dist/assets/dm-sans-latin-400-normal-CW0RaeGs.woff2
- modules/boardwalk/dist/assets/dm-sans-latin-500-normal-B9HHJjqV.woff2
- modules/boardwalk/dist/assets/dm-sans-latin-500-normal-Dr3UlScf.woff
- modules/boardwalk/dist/assets/dm-sans-latin-600-normal-Aqo67rzb.woff2
- modules/boardwalk/dist/assets/dm-sans-latin-600-normal-BmdmIIQ2.woff
- modules/boardwalk/dist/assets/dm-sans-latin-700-normal-CUSSCpQX.woff
- modules/boardwalk/dist/assets/dm-sans-latin-700-normal-DvUfVpUG.woff2
- modules/boardwalk/dist/assets/dm-sans-latin-ext-400-normal-BjWJ59Pq.woff
- modules/boardwalk/dist/assets/dm-sans-latin-ext-400-normal-BtiwyxMk.woff2
- modules/boardwalk/dist/assets/dm-sans-latin-ext-500-normal-BJfUCQsA.woff2
- modules/boardwalk/dist/assets/dm-sans-latin-ext-500-normal-DR84L5F-.woff
- modules/boardwalk/dist/assets/dm-sans-latin-ext-600-normal-4vooXBpG.woff2
- modules/boardwalk/dist/assets/dm-sans-latin-ext-600-normal-DRtaDpgU.woff
- modules/boardwalk/dist/assets/dm-sans-latin-ext-700-normal-BLI3TTWz.woff
- modules/boardwalk/dist/assets/dm-sans-latin-ext-700-normal-CJIcxD6K.woff2
- modules/boardwalk/dist/assets/editor-DL0km8ky.js
- modules/boardwalk/dist/assets/editor-uDgt9VKj.js
- modules/boardwalk/dist/assets/index-Bvfii4cZ.css
- modules/boardwalk/dist/assets/index-DKWSpBPg.js
- modules/boardwalk/dist/assets/index-Vcq4gwWv.js
- modules/boardwalk/dist/assets/load-7hoJXD7k.js
- modules/boardwalk/dist/favicon.ico
- modules/boardwalk/dist/index.html
- modules/cabana/README.md
- modules/cabana/admin_openapi.go
- modules/cabana/backend_screens.go
- modules/cabana/backendscreens/controllers/mailimages/config_form.yaml
- modules/cabana/backendscreens/controllers/maillayouts/_file_version.htm
- modules/cabana/backendscreens/controllers/maillayouts/_info.htm
- modules/cabana/backendscreens/controllers/maillayouts/config_filter.yaml
- modules/cabana/backendscreens/controllers/maillayouts/config_form.yaml
- modules/cabana/backendscreens/controllers/maillayouts/config_list.yaml
- modules/cabana/backendscreens/controllers/mailpartials/_file_version.htm
- modules/cabana/backendscreens/controllers/mailpartials/_info.htm
- modules/cabana/backendscreens/controllers/mailpartials/config_filter.yaml
- modules/cabana/backendscreens/controllers/mailpartials/config_form.yaml
- modules/cabana/backendscreens/controllers/mailpartials/config_list.yaml
- modules/cabana/backendscreens/controllers/mailtemplates/_file_version.htm
- modules/cabana/backendscreens/controllers/mailtemplates/_info.htm
- modules/cabana/backendscreens/controllers/mailtemplates/config_filter.yaml
- modules/cabana/backendscreens/controllers/mailtemplates/config_form.yaml
- modules/cabana/backendscreens/controllers/mailtemplates/config_list.yaml
- modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml
- modules/cabana/backendscreens/models/mailimagelibrary/fields.yaml
- modules/cabana/backendscreens/models/maillayout/columns.yaml
- modules/cabana/backendscreens/models/maillayout/fields.yaml
- modules/cabana/backendscreens/models/mailpartial/columns.yaml
- modules/cabana/backendscreens/models/mailpartial/fields.yaml
- modules/cabana/backendscreens/models/mailtemplate/columns.yaml
- modules/cabana/backendscreens/models/mailtemplate/fields.yaml
- modules/cabana/crud.go
- modules/cabana/field_mail.go
- modules/cabana/field_mail_test.go
- modules/cabana/form_schema.go
- modules/cabana/http.go
- modules/cabana/mail_admin.go
- modules/cabana/mail_brand_layout_postgres_test.go
- modules/cabana/mail_diff.go
- modules/cabana/mail_lifecycle_postgres_test.go
- modules/cabana/mail_locale_postgres_test.go
- modules/cabana/mail_permissions_postgres_test.go
- modules/cabana/mail_routes.go
- modules/cabana/mail_screens_smoke_test.go
- modules/cabana/mail_site_name_postgres_test.go
- modules/cabana/mail_test_send_postgres_test.go
- modules/cabana/mail_unit_test.go
- modules/cabana/messages.go
- modules/cabana/openapi_conformance_test.go
- modules/cabana/phase10_coverage_test.go
- modules/cabana/query.go
- modules/cabana/relation_field.go
- modules/cabana/security_coverage_test.go
- modules/cabana/settings.go
- modules/cabana/token_routes_test.go
- modules/lagoon/README.md
- modules/lagoon/attach/absolute.go
- modules/lagoon/attach/absolute_test.go
- modules/lagoon/migrations.go
- modules/lagoon/pending_test.go
- modules/pact/README.md
- modules/pact/capabilities.go
- modules/pact/capabilities_test.go
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- modules/postcard/README.md
- modules/postcard/assets/brand.css.tmpl
- modules/postcard/assets/default.htm
- modules/postcard/assets/minimal.htm
- modules/postcard/assets/partials/button.htm
- modules/postcard/assets/partials/footer.htm
- modules/postcard/assets/partials/header.htm
- modules/postcard/assets/partials/panel.htm
- modules/postcard/assets/partials/subcopy.htm
- modules/postcard/assets/partials/table.htm
- modules/postcard/assets/sample.htm
- modules/postcard/assets/system.htm
- modules/postcard/brand.go
- modules/postcard/brand_smoke_test.go
- modules/postcard/brand_test.go
- modules/postcard/editor.go
- modules/postcard/editor_smoke_test.go
- modules/postcard/editor_test.go
- modules/postcard/inline.go
- modules/postcard/inline_test.go
- modules/postcard/layout_ref_test.go
- modules/postcard/layouts_test.go
- modules/postcard/locale_postgres_test.go
- modules/postcard/locale_test.go
- modules/postcard/mailer.go
- modules/postcard/mailer_test.go
- modules/postcard/override_smoke_test.go
- modules/postcard/override_test.go
- modules/postcard/partials.go
- modules/postcard/partials_smoke_test.go
- modules/postcard/partials_test.go
- modules/postcard/safety.go
- modules/postcard/safety_smoke_test.go
- modules/postcard/safety_test.go
- modules/postcard/samples.go
- modules/postcard/samples_test.go
- modules/postcard/sitename_test.go
- modules/postcard/store.go
- modules/postcard/store_postgres_test.go
- modules/postcard/templates.go
- modules/surf/README.md
- modules/surf/serve.go
- modules/surf/store_lookup_test.go
- scripts/check-phase35.sh
covered_digest: "v2:sha256:b413e9cd2855f94de7e18bdd280605c598352dbcbe3c3d75eaa4160791f5a57d"
behavior_unverified: 0
overrides_applied: 0
re_verification:
previous_status: human_needed
previous_score: 22/22
stale_reason: "covered_changed: quick 261115-cha (1fb42542, b8487b02) changed modules/postcard/templates.go, mailer.go (comment), README.md, docs/services/mail.md and added layout_ref_test.go"
gaps_closed:
- "G-35-9 framework part: a template's layout key may name a layout another registered plugin owns by its full code (truth 23)"
gaps_remaining: []
regressions: []
deferred:
- truth: "The mfa plugin's two-factor code mail renders in the user plugin's layout (G-35-9 plugin part; UAT row 1 issue)"
addressed_in: "sm-mfa-plugin follow-up after the next framework tag (separate repository; out of scope for this framework phase by the caller's instruction)"
evidence: "35-UAT.md G-35-9 closure_note: 'Plugin part deferred to the follow-up after the framework tag: sm-mfa-plugin sets layout = \"golem15.user::mail.layouts.user\" in both two_factor_code templates.' The framework mechanism it needs is verified here (truth 23)"
- truth: "G-35-8 plugin part: user and paymentgateway plugin CTAs through the button partial, framework bump"
addressed_in: "Plugin follow-up after the framework tag (separate repositories)"
evidence: "35-UAT.md G-35-8 closure_note; UAT row 8 passed on the re-test"
advisory:
- finding: "WR-03 partial deviation: 'JavaScript: The Good Parts Club' is still refused as a site name (javascript: followed by whitespace)"
category: other
reason: "Deliberate, per .planning/notes/2026-11-14-mail-url-scheme-check.md; a product decision. A refused name is dropped, and mail still sends"
evidence_status: "35-REVIEW-FIX.md; code inspection"
- finding: "35-UI-SPEC.md:427 still quotes the old Branding refusal copy with 'text such as onclick='"
category: other
reason: "Phrasebook en/pl changed in 31de2ff9 and UAT row 11 confirmed the new copy in the admin; update UI-SPEC if it is a living copy contract"
evidence_status: "grep, 2026-11-16"
- finding: "IN-01..IN-03 (35-REVIEW) and WR-04, WR-05, IN-04 (earlier review) remain open in 35-REVIEW-DISPOSITION.md"
category: other
reason: "Info-level or outside the fix round; none stops a send"
evidence_status: "35-REVIEW-DISPOSITION.md"
- finding: "A template naming the default layout by full code (postcard::mail.layouts.default) now resolves to the full name instead of the default alias"
category: other
reason: "Before 261115-cha that value failed at boot, so no shipped configuration changes. layoutByCode finds the full name and builtin_full_code covers the minimal case; the default case is untested"
evidence_status: "code inspection of resolveLayoutLocked"
human_verified:
- test: "Customize and save a template"
uat_row: 2
recorded_at: "2026-11-15T08:11:21.000Z"
- test: "Reset to file version"
uat_row: 3
recorded_at: "2026-11-15T08:11:21.000Z"
- test: "Drift notice"
uat_row: 4
recorded_at: "2026-11-15T08:11:21.000Z"
- test: "Layout editor"
uat_row: 5
recorded_at: "2026-11-15T08:11:21.000Z"
- test: "Insert image into layout"
uat_row: 6
recorded_at: "2026-11-15T08:11:21.000Z"
- test: "Branding"
uat_row: 7
recorded_at: "2026-11-15T08:11:21.000Z"
- test: "Preview"
uat_row: 8
recorded_at: "2026-11-15T08:11:21.000Z"
- test: "Send test to me"
uat_row: 9
recorded_at: "2026-11-15T08:11:21.000Z"
- test: "Confirm judgment-tier prohibition: postcard imports modules/lagoon/attach for AbsolutePublicURL."
uat_row: 10
recorded_at: "2026-11-15T08:11:21.000Z"
- test: "Branding refusal on the demo instance"
uat_row: 11
recorded_at: "2026-11-15T08:11:21.000Z"
- test: "Review the CR-01, CR-02 and WR-02 safety-rule changes, including the CR-02 residual fix"
uat_row: 12
recorded_at: "2026-11-15T08:11:21.000Z"
- test: "Confirm judgment-tier prohibitions of 35-05..35-09, the review fix round and quick 261114-p5m"
uat_row: 14
recorded_at: "2026-11-15T08:11:21.000Z"
human_verification:
- test: "Inlined mail in a real inbox"
expected: "Test-send a template in the default layout to a real webmail/Outlook inbox; the button and card keep their colours with the style block stripped"
why_human: "Mail clients differ in what they keep of a style block; unit tests (TestInlineCSS) prove the style attributes are written, not how a client renders them. UAT row 13 was skipped: the demo uses the log mail driver"
---
# Phase 35: Mail templates and layouts editor Verification Report
**Phase Goal:** Administrators edit every mail the application sends from the admin panel, as in WinterCMS's Mail templates screen. System mail and the templates plugins register through `pact.HasMailTemplates` appear in a list. Each template can get a database override of its subject and body, and the override can be reset to the file version. Layouts become admin-editable records assigned to templates, with a few predefined layouts seeded. Images can be uploaded and placed in layouts and templates. postcard renders the override when one exists, otherwise the plugin's file, so mail that already works keeps working.
**Verified:** 2026-11-16T07:16:15Z
**Status:** human_needed
**Re-verification:** Yes. The previous report (2026-11-14, human_needed, 22/22) went stale when quick 261115-cha changed covered files. This round fully checked the new code, regression-checked every earlier truth, and applied the completed UAT (35-UAT.md, 12 passed, 1 issue, 1 skipped). No repository source was modified.
## Goal Achievement
ROADMAP gives no Success Criteria for Phase 35 (`Requirements: TBD`), so the must-haves are the goal's clauses (Option C), merged with the PLAN truths of 35-01..35-09 (rows 1-22, unchanged from the previous report) and the must-haves of quick 261115-cha (row 23).
### Observable Truths
| # | Truth | Status | Evidence |
| --- | --- | --- | --- |
| 1 | Administrators edit mail from Settings → Mail (templates, layouts, partials, branding, images) | ✓ VERIFIED (human UAT, rows 2, 5, 6, 7) | cabana Docker suite PASS (90.9 s, 0 skips); screens unchanged since the UAT |
| 2 | Templates appear one row per template (G-35-1) | ✓ VERIFIED | `TestMailLocaleGroups` PASS (Docker). The UAT row 1 note says "Previous G-35-1 (one row per locale) confirmed fixed"; the row's remaining issue is G-35-9's plugin part (deferred) |
| 3 | Locale switcher; per-locale customize, reset, drift | ✓ VERIFIED (human UAT, rows 3, 4) | `TestMailLocaleGroups` PASS |
| 4 | DB override of subject/body; Reset restores the file | ✓ VERIFIED (human UAT, rows 2, 3) | `TestOverride`, `TestFallback`, `TestMailOverrideSmoke/override` PASS |
| 5 | Layouts are editable records; default/system/minimal seeded | ✓ VERIFIED (human UAT, row 5) | `TestMailOverrideSmoke/layouts_and_partials` PASS |
| 6 | Built-in layouts finished (header, card, footer, button) | ✓ VERIFIED (human UAT, row 8) | `TestBuiltinLayoutsLogo`, `TestHeaderFooterPartials`, `TestButtonPartial` PASS |
| 7 | Branding Site name, else mail.from display name | ✓ VERIFIED (human UAT, rows 7, 11) | `TestSiteName`, `TestMailBrandSiteName` PASS |
| 8 | CSS inlined with per-layout opt-out; inliner failure never stops mail | ✓ VERIFIED | `TestInlineCSS`, `TestInlineFailure`, `TestMailLayoutInlineOptOut` PASS. How a real client renders it stays a human item (UAT row 13 skipped) |
| 9 | Images uploaded and placed in layouts and templates | ✓ VERIFIED (human UAT, row 6) | routes and picker unchanged |
| 10 | Override when present, else file; `<template>-<locale>` fallback | ✓ VERIFIED | `TestSendLocaleFallback`, `TestTemplateFor`, `TestMailOverrideSmoke/locale_fallback`, `/file`, `/fallback` PASS |
| 11 | Mail that already works keeps working | ✓ VERIFIED | Full short suite exit 0 (47 packages); `TestSiteNameSend` PASS; `--consumers` PASS against this checkout after the plugin restyle (261114-p5n) landed |
| 12 | `check-phase35.sh` gate | ✓ VERIFIED | `--self-test`, `--docs`, `--marker`, `--additive` (8 packages vs v0.6.3), `--consumers`: all exit 0 |
| 13 | Decision notes recorded | ✓ VERIFIED | unchanged; `.planning/notes/2026-11-14-mail-url-scheme-check.md` accepted in UAT row 12 |
| 14 | Permission split, own-address test send, sandboxed preview | ✓ VERIFIED (human UAT, row 9) | cabana Docker suite PASS |
| 15 | Sends with `"Metadata: Weekly"` / `Big Data: Summit`; name in header and footer | ✓ VERIFIED (human UAT, row 11) | `TestSiteNameSend` PASS |
| 16 | Unsafe site name left out at render; send succeeds | ✓ VERIFIED | `TestUnsafeSiteNameDropped` PASS |
| 17 | Branding save of an unsafe name is a 422 on site_name (en/pl) | ✓ VERIFIED (human UAT, row 11) | `TestMailSiteNameSafety` PASS (Docker) |
| 18 | URL-scheme check anchored, decoded; `javascript:` refused at save and send | ✓ VERIFIED (human UAT, row 12 accepted the rule changes) | `TestURLSchemeCheck` PASS |
| 19 | An inlined result that fails the check is sent as its style-block version | ✓ VERIFIED | `TestInlineUnsafeOutput` PASS |
| 20 | Footer prints the site name literally | ✓ VERIFIED | `TestFooterSiteNameLiteral` PASS |
| 21 | sm-user-plugin and sm-paymentgateway-plugin mail tests pass read-only | ✓ VERIFIED | `--consumers` PASS; both trees clean before and after (empty `git status --porcelain`) |
| 22 | 35-07 pin subtest gone; gate requires new names; IN-03 self-test uses `cmp` | ✓ VERIFIED | `--self-test` PASS |
| 23 | A template's `layout` may name a layout another registered plugin owns by full code; an unregistered full code fails at boot with a require-the-owner hint; another plugin's short alias is still refused with the byte-identical error; existing resolution unchanged; editor, overrides and the index work with it (G-35-9 framework part) | ✓ VERIFIED | Diff read: the new branch in `resolveLayoutLocked` (templates.go:246-252) runs only after the own-alias and built-in lookups miss and the value holds `::`, and it checks `c.layouts`. party boots plugins in `Requires()` order (registry.go:141-147), so the owner's layouts are in the catalog first. `TestCrossPluginLayout` (6 subtests: send renders the lender's HTML and text wrappers, `owner_registers_later` error prefix and hint, `unknown_full_code`, `other_plugin_alias_refused` exact text, `precedence_unchanged`, `builtin_full_code`), `TestCrossPluginLayoutOverride` (3: override layout, customized owner layout, Editor Validate/Preview) PASS; `TestCrossPluginLayoutSync` PASS under Docker (borrower rows join the lender layout row; layout_id stable on a second sync) |
**Score:** 23/23 truths verified (0 present, behavior-unverified).
### Deferred Items
| # | Item | Addressed In | Evidence |
|---|------|-------------|----------|
| 1 | G-35-9 plugin part: sm-mfa-plugin's two_factor_code templates set `layout = "golem15.user::mail.layouts.user"` (UAT row 1 issue) | sm-mfa-plugin follow-up after the next framework tag (separate repo; out of scope by instruction) | 35-UAT.md G-35-9 closure_note; framework support verified as truth 23 |
| 2 | G-35-8 plugin part: plugin CTAs through the button partial, framework bump | Plugin follow-up after the framework tag | 35-UAT.md G-35-8 closure_note |
### Advisory (New Scope, Unevidenced)
| # | Finding | Category | Why Advisory |
|---|---------|----------|--------------|
| 1 | WR-03 deviation: `JavaScript: The Good Parts Club` still refused | other | Deliberate per the note; product decision |
| 2 | 35-UI-SPEC.md:427 quotes the old refusal copy | other | Copy contract drift; the admin shows the new copy (UAT row 11) |
| 3 | IN-01..IN-03, WR-04, WR-05, IN-04 open | other | Info-level or outside the fix round |
| 4 | `layout = "postcard::mail.layouts.default"` now resolves to the full name instead of the alias, and no test covers it | other | That value failed at boot before, so no existing configuration changes |
Closed since the previous report:
- The over-refusal advisory: the human accepted the tag-reading risk in UAT row 12, and `--consumers` passes after 261114-p5n.
- The "rows 1 and 8 still read issue" advisory: row 8 passed on the re-test, and row 1's remaining issue is G-35-9's plugin part.
### Required Artifacts
| Artifact | Expected | Status | Details |
| -------- | -------- | ------ | ------- |
| `modules/postcard/templates.go` | full-code branch in `resolveLayoutLocked`, new error, comments | ✓ VERIFIED | 17-line change. The short-alias error is untouched (`postcard: unknown layout %s`) |
| `modules/postcard/mailer.go` | BootPlugin doc comment | ✓ VERIFIED | comment-only change |
| `modules/postcard/layout_ref_test.go` | TestCrossPluginLayout, TestCrossPluginLayoutOverride, TestCrossPluginLayoutSync | ✓ VERIFIED | 309 lines with real assertions on HTML/text wrappers, error text and DB joins; all PASS |
| `modules/postcard/README.md`, `docs/services/mail.md` | full-code form, resolution order, require-the-owner rule, `acme.blog::mail.layouts.blog` example | ✓ VERIFIED | Present; `--docs` (TestDocsTree, TestCommandsDocumented, docs:build --check) PASS; no consumer app named (`--marker`) |
| Earlier artifacts (admin/, boardwalk/dist, cabana, lagoon, pact, surf, go.mod/go.sum) | | ✓ VERIFIED | `git diff --name-only 3541c9bd HEAD` lists only the five files above under modules/ and docs/; no uncommitted changes there |
### Key Link Verification
| From | To | Via | Status | Details |
| ---- | --- | --- | ------ | ------- |
| `party/registry.go` boot loop | `postcard.BootPlugin` → `Catalog.Register` → `resolveLayoutLocked` | `ordered` (Requires topological order) | ✓ WIRED | registry.go:141-147 |
| `parsedTemplate.layout` (full code) | render (`layoutFor`/`layoutByCode`), `SyncIndex` layout_id | catalog lookup by code, no plugin scoping | ✓ WIRED | `file_layout_by_full_code` send and `TestCrossPluginLayoutSync` |
| cabana layout picker / save | `Editor.Validate` | `scopeLayouts` lists every catalog layout code (mail_admin.go:321) | ✓ WIRED | `editor_validate_and_preview` PASS; cabana unchanged |
| `postcard/templates.go`, `mailer.go`, `editor.go` | `validateHTML` (safety) | unchanged since the previous report | ✓ WIRED | `TestURLSchemeCheck` PASS |
### Data-Flow Trace (Level 4)
| Artifact | Data Variable | Source | Produces Real Data | Status |
| -------- | ------------- | ------ | ------------------ | ------ |
| Borrower template HTML/text | layout wrapper | lender's file layout in `c.layouts`, or its override in `Overrides.Layouts` | Yes | ✓ FLOWING |
| Template row `layout_id` | lender layout row | `SyncIndex` subquery by code | Yes | ✓ FLOWING |
| Earlier flows (site name, overrides, layouts) | | | Yes | ✓ FLOWING |
### Behavioral Spot-Checks
| Behavior | Command | Result | Status |
| -------- | ------- | ------ | ------ |
| vet | `go vet ./...` | clean | ✓ PASS |
| Full short suite (once) | `go test -short -count=1 ./...` | exit 0, 47 packages ok | ✓ PASS |
| postcard + cabana short | `go test -short -count=1 ./modules/postcard/... ./modules/cabana/...` | ok, ok | ✓ PASS |
| postcard + cabana with Docker | `go test -count=1 ./modules/postcard/... ./modules/cabana/...` | exit 0, 0 skips (postcard 10.7 s, cabana 90.9 s) | ✓ PASS |
| Cross-plugin layout | `go test -short ./modules/postcard -run '^(TestCrossPluginLayout\|TestCrossPluginLayoutOverride\|TestCrossPluginLayoutSync)$' -v` | 9 subtests PASS (Sync skipped under -short) | ✓ PASS |
| Cross-plugin sync (Docker) | `go test ./modules/postcard -run '^(TestCrossPluginLayoutSync\|TestMailOverrideSmoke)$' -v` | PASS; smoke 11 subtests PASS | ✓ PASS |
| Named regressions | 15 postcard tests (URL check, site name, inlining, overrides, locale fallback, layouts) and 4 cabana Postgres tests | all PASS | ✓ PASS |
| Gate stages | `check-phase35.sh --self-test`, `--docs`, `--marker`, `--additive`, `--consumers` | all exit 0; siblings clean before and after | ✓ PASS |
### Probe Execution
No `scripts/*/tests/probe-*.sh` is declared or present for this phase, so this step is N/A. The phase gate stages were run directly.
### Requirements Coverage
REQUIREMENTS.md has no row naming Phase 35. Plan `requirements:` values are review and decision IDs; the quick task declares `QUICK-261115-cha`.
| Requirement | Source Plan | Description | Status | Evidence |
| ----------- | ---------- | ----------- | ------ | -------- |
| CR-01, WR-01, WR-05, D-13, D-10, D-14, D-21 | 35-08, 35-09 | safety rules, site name, gate | ✓ SATISFIED | rows 11, 16-20; UAT rows 11, 12 |
| D-01..D-25, G-35-1, G-35-8 (framework) | 35-01..07 | editor, overrides, layouts, images, locale grouping, finished layouts | ✓ SATISFIED | rows 1-10; UAT rows 2-9 |
| QUICK-261115-cha / G-35-9 (framework) | quick 261115-cha | cross-plugin layout by full code | ✓ SATISFIED | row 23 |
| Orphaned | none | none | none | no REQUIREMENTS.md row maps to Phase 35 |
### Anti-Patterns Found
| File | Line | Pattern | Severity | Impact |
| ---- | ---- | ------- | -------- | ------ |
| modules/, docs/, scripts/, admin/ lines added in 3541c9bd..HEAD | none | TBD/FIXME/XXX/TODO/HACK | none found | none |
### Prohibitions
| Statement (plan) | Tier | Verdict | Flag |
| --------- | ---- | ------- | ---- |
| pact/postcard/cabana API changes additive only | automated | Holds: `--additive` passes against v0.6.3 | none |
| No new dependency, go.mod/go.sum unchanged | automated | Holds: empty diff since the previous report | none |
| Tests and gate never write a sibling repository | automated | Holds: both trees clean before and after `--consumers` | none |
| No sibling repo changed, nothing pushed or tagged, no consuming app named | judgment | Accepted in UAT row 14. Still holds after 261115-cha: 121 commits ahead of origin/master, newest tag v0.6.4 (2026-11-08), `--marker` passed. The quick plan declares no prohibitions of its own | resolved: UAT row 14 |
| postcard imports lagoon/attach (35-01 deviation) | judgment | Accepted | resolved: UAT row 10 |
### Human Verification Required
UAT evidence (Step 8b). `verification.uat-evidence` reports `changed_since_uat: []`, with `recorded_at` 2026-11-15T08:11:21Z. That is the time of the G-35-9 closure note. The human ran the tests before commit 42ab223e (07:57:50Z), though, and the quick commits 1fb42542 and b8487b02 (08:08Z, 08:09Z) changed `templates.go` after that. The verifier therefore checked whether the change bears on any passed row:
- The new branch only runs where `Register` would have returned `postcard: unknown layout` before. A configuration that booted during the UAT never reaches it.
- `mailer.go` changed only in a comment.
- The README and docs changes do not touch runtime code.
No row's code path changed, so rows 2-12 and 14 stand as human evidence (`human_verified`). Row 1's remaining issue is G-35-9's plugin part, which is deferred above.
One item remains:
1. **Inlined mail in a real inbox** (UAT row 13, skipped). Test-send a template in the default layout to a real webmail/Outlook inbox. The button and card should keep their colours with the style block stripped. This needs an instance with working SMTP; the demo uses the log driver. If the developer judges `TestInlineCSS` sufficient, they can record an override for this item instead.
### Gaps Summary
No gaps. Quick 261115-cha delivers the framework half of G-35-9 correctly and in a small change:
- A template's `layout` key can now name a layout another plugin owns by its full code.
- The change only turns a former boot error into a resolution when the named layout is already registered. Every resolution that worked before is untouched, and the short-alias error text is byte-identical.
- party's `Requires()` boot order makes the require-the-owner rule hold in practice.
- Tests cover the send, the boot errors, the precedence, overrides, the editor and the Postgres index.
- Every earlier truth passes its regression check: vet, the full short suite, the postcard and cabana Docker suites, and all five gate stages including the read-only consumer run.
The completed UAT settles every earlier human item except row 13, the real-inbox check, which was skipped for lack of SMTP. Status is `human_needed` for that one item. The mfa plugin's own layout key lives in a separate repository and is deferred by instruction.
---
_Verified: 2026-11-16T07:16:15Z_
_Verifier: Claude (msd-verifier)_

View File

@@ -0,0 +1 @@
No external API integration: a database override layer, a postcard editor API and cabana admin routes for the framework's own admin; mail uses the unchanged drivers; CodeMirror calls no service.

View File

@@ -0,0 +1,10 @@
# Phase 35: deferred items
Out-of-scope discoveries made while executing Phase 35 plans. Not fixed here.
## Deferred Items
- `modules/pier` `TestStatelessFanOut` failed once under the full `go test -short ./...` run during 35-01
status: open
**What:** subtest "a stateless-only instance applies a revocation from the other instance" reported "B never evicted its stateless server: the revocation did not reach it" after its 10 s wait. It passed when the package was run alone and in every later full run (five more). It looks timing-sensitive under parallel package load.
**Why deferred:** pier is unrelated to the mail work; 35-01 changed nothing it uses at run time.

View File

@@ -0,0 +1,189 @@
{
"schema_version": 1,
"batch_id": "261105-oc4",
"created_at": "2026-11-05T16:31:21.798Z",
"options": {},
"base_revision": "5aa846c5e85368b534e03a1d19f441bb34de193c",
"items": [
{
"quick_id": "261105-oc5",
"client_id": null,
"description": "2FA hardening (todos 2026-10-26-activate-by-code-second-factor.md and 2026-10-26-mfa-factor-changes-need-reauth.md): sm-user-plugin ActivateByCode runs CheckLoginGates after VerifyActivationCode (finding F-1); sm-mfa-plugin requires password confirmation on factor-changing routes (WR-05) and vue-demo-app security.vue asks for the password",
"status": "complete",
"depends_on": [],
"planned_files": [
"../sm-user-plugin/controllers/api_controller.go",
"../sm-user-plugin/controllers/login_gates.go",
"../sm-user-plugin/classes/login_gate.go",
"../sm-user-plugin/login_gate_test.go",
"../sm-user-plugin/README.md",
"../sm-mfa-plugin/go.work",
"../sm-mfa-plugin/go.work.sum",
"../sm-mfa-plugin/classes/config.go",
"../sm-mfa-plugin/config/config.yaml",
"../sm-mfa-plugin/controllers/management.go",
"../sm-mfa-plugin/controllers/webauthn.go",
"../sm-mfa-plugin/factor_password_test.go",
"../sm-mfa-plugin/login_paths_test.go",
"../sm-mfa-plugin/settings_test.go",
"../sm-mfa-plugin/tracer_smoke_test.go",
"../sm-mfa-plugin/webauthn_smoke_test.go",
"../sm-mfa-plugin/webauthn_test.go",
"../sm-mfa-plugin/php_bodies_test.go",
"../sm-mfa-plugin/challenge_smoke_test.go",
"../sm-mfa-plugin/recovery_test.go",
"../sm-mfa-plugin/email_test.go",
"../sm-mfa-plugin/gate_test.go",
"../sm-mfa-plugin/trusted_test.go",
"../sm-mfa-plugin/passwordless_smoke_test.go",
"../sm-mfa-plugin/README.md",
"../sm-demo-app/vue-demo-app/app/lib/twoFactor.ts",
"../sm-demo-app/vue-demo-app/app/lib/twoFactor.test.ts",
"../sm-demo-app/vue-demo-app/app/composables/useTwoFactor.ts",
"../sm-demo-app/vue-demo-app/app/pages/account/security.vue",
"../sm-demo-app/vue-demo-app/i18n/locales/en.json",
"../sm-demo-app/vue-demo-app/i18n/locales/pl.json",
"../sm-demo-app/vue-demo-app"
],
"directory": null,
"worktree": null,
"dispatched_worktree": null,
"dispatched_branch": null,
"dispatched_base": null,
"wave": 0,
"commit": "b179e6b",
"failure_reason": null
},
{
"quick_id": "261105-oc6",
"client_id": null,
"description": "Chatchannels pin policy (todo chatchannels-pin-policy.md): sm-chatchannels-plugin PinMessage/UnpinMessage require CanManageContext or an optional contracts.PinPolicy, and verify the message belongs to the channel conversation; sm-demo-app answers the policy from its moderator group",
"status": "complete",
"depends_on": [],
"planned_files": [
"../sm-chatchannels-plugin/contracts/pin_policy.go",
"../sm-chatchannels-plugin/contracts/access_resolver.go",
"../sm-chatchannels-plugin/classes/channel_service.go",
"../sm-chatchannels-plugin/api/pins.go",
"../sm-chatchannels-plugin/pins_test.go",
"../sm-chatchannels-plugin/testdata/PHP_METHOD_MAP.md",
"../sm-chatchannels-plugin/README.md",
"../sm-demo-app/plugins/demo/classes/chat_context.go",
"../sm-demo-app/plugins/demo/classes/chat_context_test.go",
"../sm-demo-app/plugins/demo/chat.go",
"../sm-demo-app/reset_test.go",
"../sm-demo-app/README.md",
"../sm-demo-app/plugins/golem15/chatchannels",
"../sm-demo-app/chat_test.go"
],
"directory": null,
"worktree": null,
"dispatched_worktree": null,
"dispatched_branch": null,
"dispatched_base": null,
"wave": 0,
"commit": "a042536",
"failure_reason": null
},
{
"quick_id": "261105-oc7",
"client_id": null,
"description": "Chatvideo hardening (todos chatvideo-live-membership.md, chatvideo-dm-only-host-hook.md, chatvideo-incoming-handle-leak.md): sm-chatvideo-plugin honours LiveMembership and removes banned participants from the LiveKit room, adds an optional CanStartCall host hook for a DM-only rule; vue-chatvideo-layer useIncomingCalls closes stale session handles",
"status": "complete",
"depends_on": [],
"planned_files": [
"../sm-chatvideo-plugin/classes/video_service.go",
"../sm-chatvideo-plugin/classes/authorizer.go",
"../sm-chatvideo-plugin/classes/livekit.go",
"../sm-chatvideo-plugin/classes/revoked_access.go",
"../sm-chatvideo-plugin/boot.go",
"../sm-chatvideo-plugin/live_membership_test.go",
"../sm-chatvideo-plugin/contracts/call_policy.go",
"../sm-chatvideo-plugin/contracts/call_policy_test.go",
"../sm-chatvideo-plugin/api/errors.go",
"../sm-chatvideo-plugin/lang/en/lang.yaml",
"../sm-chatvideo-plugin/lang/pl/lang.yaml",
"../sm-chatvideo-plugin/call_policy_test.go",
"../sm-chatvideo-plugin/README.md",
"../sm-chatvideo-plugin/plugin.yaml",
"../sm-demo-app/plugins/golem15/chatvideo",
"../sm-demo-app/plugins/demo/video.go",
"../sm-demo-app/plugins/demo/plugin.go",
"../sm-demo-app/video_test.go",
"../sm-demo-app/config/golem15.chatvideo.yaml",
"../sm-demo-app/README.md",
"../vue-chatvideo-layer/app/composables/useIncomingCalls.ts",
"../vue-chatvideo-layer/vitest.config.ts",
"../vue-chatvideo-layer/tests/useIncomingCalls.test.ts",
"../vue-chatvideo-layer/README.md"
],
"directory": null,
"worktree": null,
"dispatched_worktree": null,
"dispatched_branch": null,
"dispatched_base": null,
"wave": 1,
"commit": "f996156",
"failure_reason": null
},
{
"quick_id": "261105-oc8",
"client_id": null,
"description": "lagoon/attach StaticHandler and StaticHandlerPublic send the stored Content-Disposition and X-Content-Type-Options nosniff (todo 2026-10-28-attach-static-handler-disposition.md)",
"status": "complete",
"depends_on": [],
"planned_files": [
"modules/lagoon/attach/static.go",
"modules/lagoon/attach/static_test.go",
"modules/lagoon/attach/lifecycle_test.go",
"modules/lagoon/README.md",
"docs/services/storage.md",
"docs/database/attachments.md",
"modules/surf/uploads.go"
],
"directory": null,
"worktree": null,
"dispatched_worktree": null,
"dispatched_branch": null,
"dispatched_base": null,
"wave": 0,
"commit": "27c98bf",
"failure_reason": null
},
{
"quick_id": "261105-oc9",
"client_id": null,
"description": "sm-demo-app hardening (todos check-local-jwt-out-of-argv.md, demo-chat-members-read-only.md, demo-nginx-livekit-rtc-only.md, demo-seed-moderation-lists-once.md, demo-vapid-runbook-pipefail.md)",
"status": "complete",
"depends_on": [],
"planned_files": [
"../sm-demo-app/plugins/demo/chat_api.go",
"../sm-demo-app/plugins/demo/classes/members.go",
"../sm-demo-app/plugins/demo/console/seed.go",
"../sm-demo-app/plugins/demo/console/seed_chat.go",
"../sm-demo-app/plugins/demo/console/seed_friends.go",
"../sm-demo-app/plugins/demo/plugin.go",
"../sm-demo-app/plugins/demo/updates/updates.go",
"../sm-demo-app/go.mod",
"../sm-demo-app/chat_test.go",
"../sm-demo-app/chat_smoke_test.go",
"../sm-demo-app/seed_chat_test.go",
"../sm-demo-app/README.md",
"../sm-demo-app/scripts/check-moderation.sh",
"../sm-demo-app/scripts/check-local.sh",
"../sm-demo-app/deploy/nginx/demo.summercms.io.conf",
"../sm-demo-app/scripts/check-deploy.sh",
"../sm-demo-app/scripts/check-live.sh",
"../sm-demo-app/DEPLOY.md"
],
"directory": null,
"worktree": null,
"dispatched_worktree": null,
"dispatched_branch": null,
"dispatched_base": null,
"wave": 2,
"commit": "9595606",
"failure_reason": null
}
]
}

View File

@@ -0,0 +1,224 @@
---
phase: quick-261105-din
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/classes/mcp_backend_binding.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/classes/mcp_store.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/controllers/mcp_consent_api.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/mcp_consent_race_test.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/mcp_consent_smoke_test.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/README.md
- /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-REVIEW-DISPOSITION.md
- /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-SECURITY.md
autonomous: true
requirements:
- quick-261105-din
- CR-01
estimate:
tokens: 70000
raw_tokens: 70000
tasks: 3
confidence: low
must_haves:
truths:
- "A revoke (DELETE /oauth/authorizations/{client_id}) that lands while an MCP allow is in flight is never undone. The allow's code issue (MarkIssued + MarkConsented inside srv.IssueCode) and its consent write (TouchConsent or replaceMCPConsent) run in ONE transaction that first takes the user's exclusive grants lock (classes.LockUserGrants), the same lock revoke takes. A revoke therefore either precedes both writes, and the allow reads the post-revoke state, or follows both and deletes the issued code and the consent."
- "While another transaction holds the user's grants lock, POST /oauth/mcp/requests/{request} with decision allow does not answer and writes nothing. The pending row keeps its request_id with a NULL code_hash, and the consent row's updated_at is unchanged."
- "The silent re-grant path (a consent row already covers the request: consent_required false, TouchConsent) runs inside the same locked transaction. After allow then revoke, the pair has no consent row and no MCP code, the code from the allow does not exchange, and a fresh authorize shows consent_required true."
- "A consent write that fails rolls the code issue back. The answer is 500 server_error, the request stays pending (request_id set, code_hash NULL), the client's consented_at stays NULL, and once the failure is gone the same request id can be allowed and its code exchanged."
- "No change in summercms.go (framework). No exported plugin signature changes. The plugin only adds classes.WithinUserGrantsLock. The OIDC flow, revoke, cascade, code exchange and refresh code paths are untouched."
- "Both new tests failed on the code before the fix, for the reason CR-01 describes. go vet ./... and the full non-short plugin suite are green at the commit."
artifacts:
- path: /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/classes/mcp_backend_binding.go
provides: "exported WithinUserGrantsLock(ctx, db, userIDs, fn); unexported grantsTxKey and grantsTxFrom(ctx)"
- path: /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/classes/mcp_store.go
provides: "MCPStore.WithinTx runs fn on the grants-lock transaction carried in ctx instead of opening its own"
- path: /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/controllers/mcp_consent_api.go
provides: "MCPConsentDecide allow path: IssueCode + recordMCPConsent inside WithinUserGrantsLock; response written after commit"
- path: /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/mcp_consent_race_test.go
provides: "TestMCPConsentAllowSerializesWithRevoke, TestMCPConsentFailureRollsBackCode (testcontainers Postgres, skip under -short)"
key_links:
- from: "controllers/mcp_consent_api.go MCPConsentDecide"
to: "classes.WithinUserGrantsLock"
via: "allow path wraps srv.IssueCode(txCtx, ...) and recordMCPConsent(txCtx, tx, ...)"
pattern: "WithinUserGrantsLock"
- from: "wristband.Server.IssueCode (framework, unchanged)"
to: "classes.MCPStore.WithinTx"
via: "s.backend.WithinTx(ctx, ...) with the ctx WithinUserGrantsLock handed to fn (LazyMCPStore delegates to NewMCPStore(db).WithinTx)"
pattern: "grantsTxFrom"
---
<objective>
Fix 32.1 review finding CR-01 in sm-oauthserver-plugin: an in-flight MCP allow can recreate a consent the user just revoked.
Root cause (verified against current code): `MCPConsentDecide` (controllers/mcp_consent_api.go:227-241) calls `srv.IssueCode`, which commits `MarkIssued` + `MarkConsented` in its own `s.backend.WithinTx` transaction. Only after that does it write the consent through `recordMCPConsent` / `replaceMCPConsent` on the pool `db`, and neither step takes `classes.LockUserGrants`. Revoke (controllers/authorizations.go:138-165) takes that exclusive advisory lock, then deletes the consent and the pair's AuthCode, AccessToken, RefreshToken and MCPCode rows. A revoke that commits between IssueCode and the consent write is undone: `Take` finds no row, so `replaceMCPConsent` inserts one. The next authorize then answers `consent_required:false` and /connect auto-allows.
Chosen design (smallest correct; no framework change). wristband's `IssueCode` does all its DB work through `s.backend.WithinTx(ctx, fn)` with the caller's ctx, and on the MCP server that backend is the plugin's `classes.LazyMCPStore`, which delegates to `classes.MCPStore.WithinTx`. So the plugin can make IssueCode's writes join a caller-owned transaction through a plugin-private context key:
1. A new `classes.WithinUserGrantsLock(ctx, db, userIDs, fn)` opens a transaction. Its first statement takes `lockUserGrants` (exclusive, ascending ids). It then calls `fn(txCtx, tx)`, where txCtx carries tx under an unexported key.
2. `MCPStore.WithinTx` checks that key. When present, it runs fn on the carried tx without BEGIN or SAVEPOINT, and the owner commits or rolls back.
3. The allow path runs `srv.IssueCode(txCtx, ...)` and `recordMCPConsent(txCtx, tx, ...)` inside that function and writes the response only after the commit.
Rejected alternative: "consent + lock first in its own transaction, IssueCode after". A revoke landing between the two commits deletes the consent but cannot see the not-yet-issued code. That leaves a live code without a consent, which is worse.
Purpose: revoke is final again. The silent re-grant (`TouchConsent`) path and the ban/password/link cascade (`revokeUserGrants`, which takes the same exclusive lock) also stop racing the allow, because the whole allow unit now holds the lock.
Output: plugin code fix + two deterministic regression tests + plugin README, in one plugin commit; 32.1 disposition and security docs updated (the orchestrator commits the docs).
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/CLAUDE.md
@/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/STATE.md
@/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-REVIEW.md
Repository facts the executor must respect:
- The plugin repo is /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin (own git repo, branch master, HEAD d600e2c, latest tag v0.1.6). Its `go.work` has an UNRELATED uncommitted change (sm-user-plugin replace pointing at ../sm-demo-app/plugins/golem15/user). Do not stage, edit, revert or stash it. Tests run with it as it is. Never use `git stash` or `git add -A` / `git add .` in that repo.
- Framework code used (read-only, do not change): /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/wristband/consent.go `IssueCode` (:78-105) calls `lookupOwnedPending` (its own `s.backend.WithinTx`, :134-) and then one `s.backend.WithinTx` holding `MarkIssued` + `MarkConsented`, always passing the caller's ctx. No other DB access.
- Interfaces in play: `wristband.Backend.WithinTx(ctx, fn func(wristband.Tx) error) error`; plugin `classes.MCPStore{db *gorm.DB}`, `mcpTx{db *gorm.DB; backendUserID uint}`; `classes.LazyMCPStore.WithinTx` → `NewMCPStore(db).WithinTx(ctx, fn)` (classes/lazy.go:62-71); `classes.LockUserGrants(ctx, db, userIDs []uint)` / unexported `lockUserGrants` (classes/mcp_backend_binding.go:89-111); `classes.ErrDatabaseUnavailable` (classes/lazy.go:15); `classes.NewStore(db).WithinOIDCTx` + `oidcTx.TouchConsent` (classes/oidc_store.go:48-55, :364-367, an UPDATE by id).
- Lock takers today: revoke (exclusive), cascade `revokeUserGrants` (exclusive, classes/cascade.go:108), code exchange `ByCodeHashForUpdate` and refresh `ByTokenHashForUpdate` (shared, classes/mcp_store.go:195, :336). Each takes the advisory lock before any row lock it holds.
- Model fields: `models.MCPCode.RequestID *string`, `CodeHash *string`, table `golem15_oauthserver_mcp_codes`; `models.Consent` table `golem15_oauthserver_consents` (UNIQUE user_id, client_id; FK users ON DELETE CASCADE); `models.Client.ConsentedAt *time.Time`.
- Test harness (package oauthserver_test): `bootOAuth(t, envs...)` boots a fresh per-test database (testmain_test.go CREATE DATABASE per boot) and skips under -short; `env.gdb` is the app's own *gorm.DB (no pool cap); helpers `registerMCPClient`, `user`, `sessionToken`, `mcpPending` (mcp_consent_smoke_test.go:62), `mcpPendingPKCE` + `exchangeMCPCode` (mcp_backend_binding_test.go:22, :46), `consentShow` / `consentDecide` (mcp_consent_smoke_test.go:86, :99), `jsonCall` (pages_smoke_test.go:240), `browser()` (harness_test.go:212), `consentScopes` / `issuedCode` (mcp_consent_test.go:216, :226), `sha256Hex` (import_cutover_smoke_test.go:26). These helpers call t.Fatal, so never call them from a goroutine. MCP env for every MCP test: SUMMER_GOLEM15__OAUTHSERVER__MCP__ENABLED=true and SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE=+mcpVerifierResource (copy from TestMCPConsent).
- Docker: the tests need Docker. If the socket is denied, run the same command through `sudo -u golem bash -c '...'` (CLAUDE.md). A skipped test is not a pass: every verify below greps for the explicit `--- PASS:` lines.
</context>
<tasks>
<task type="tracer" tdd="true">
<name>Task 1: Failing regression tests, then serialize the MCP allow with revoke under the user's grants lock</name>
<files>/media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/mcp_consent_race_test.go, /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/mcp_consent_smoke_test.go, /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/classes/mcp_backend_binding.go, /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/classes/mcp_store.go, /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/controllers/mcp_consent_api.go</files>
<read_first>
- sm-oauthserver-plugin/controllers/mcp_consent_api.go (whole file; allow path :185-242, recordMCPConsent :348-364, replaceMCPConsent :366-390)
- sm-oauthserver-plugin/controllers/authorizations.go :136-165 (revoke: lock, SELECT consent FOR UPDATE, deletes)
- sm-oauthserver-plugin/classes/mcp_backend_binding.go :71-111 and classes/mcp_store.go :34-65 (WithinTx, mcpTx)
- sm-oauthserver-plugin/mcp_consent_test.go (style, helpers) and mcp_consent_smoke_test.go :25-107 (mcpConsentView, helpers)
- summercms.go/modules/wristband/consent.go :78-160 (IssueCode, lookupOwnedPending)
</read_first>
<precondition>In /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin, `git status --short` shows only ` M go.work` and HEAD is d600e2c or a descendant that leaves controllers/mcp_consent_api.go and classes/mcp_store.go unchanged. `docker info` succeeds (else use sudo -u golem).</precondition>
<behavior>
- TestMCPConsentAllowSerializesWithRevoke. The user already holds a consent [read write], and the second request "read" (via mcpPendingPKCE) shows consent_required false, so this is the silent TouchConsent path. A separate transaction holds classes.LockUserGrants for the user. In that state the async allow does not answer, and pg_locks shows exactly one ungranted advisory waiter on the holder's lock. The pending row still has request_id = the id and a NULL code_hash, and the consent row's updated_at is unchanged. A real async DELETE /oauth/authorizations/{client} queues as the second waiter. After the holder rolls back, the allow answers 200 with a redirect_uri carrying a code, and the revoke answers 200 {"revoked":true}. Afterwards: no consent row for (user, client); zero MCP code rows with user_id = user and client_id = client; exchangeMCPCode of the allow's code is not 200 and carries an error; a fresh mcpPending(client, "read") shows consent_required true.
- TestMCPConsentFailureRollsBackCode. A fresh MCP client with no consent row, so the allow takes the replace path. A test-installed BEFORE INSERT OR UPDATE trigger on golem15_oauthserver_consents raises an exception. The allow of a "read" request (mcpPendingPKCE) answers 500 {"error":"server_error"}. The MCP code row for that request id still has request_id set and code_hash NULL, the client's consented_at is NULL, and no consent row exists. After the trigger is dropped, the same request id allows with 200, the consent row is [read], and exchangeMCPCode returns 200 with an access_token.
- On the pre-fix code, test 1 fails: the allow answers while the lock is held. Test 2 also fails: code_hash is set and the retry answers 404 request_not_found.
</behavior>
<action>
RED first: write the tests, run them, confirm both fail on the current code, and keep the failure output for the SUMMARY. Do not commit the red state, because CLAUDE.md requires `go test ./...` green at every commit.
Tests (new file mcp_consent_race_test.go, package oauthserver_test, imports the plugin's classes and models packages):
- In mcp_consent_smoke_test.go add the field ConsentRequired bool with json tag consent_required to mcpConsentView. The change is additive; no existing assertion changes.
- Add goroutine-safe helpers in the new file that never touch t. First, an async JSON call that builds the request like jsonCall (Accept and Content-Type application/json, Bearer token, env.issuer + path), sends it with env.browser(), and delivers status, body and error on a buffered channel. Second, a waiter counter that runs, on env.gdb (a different pool connection), a COUNT over pg_locks w where w.locktype is advisory and w.granted is false, and a granted advisory row h exists with the same classid, objid and objsubid and h.pid equal to the holder's backend pid. Third, a wait helper that polls the counter every 10 ms until it reaches n, with a 15 s deadline. While polling it selects on the in-flight result channels: a result arriving first fails with "allow answered <status> <body> while the user's grants lock was held", and the deadline fails with the current count.
- Holder: begin a transaction on env.gdb with t.Context(), call classes.LockUserGrants(ctx, holder, []uint{user.ID}), and read SELECT pg_backend_pid() inside it. Register a t.Cleanup that rolls it back and ignores the error when it is already rolled back.
- TestMCPConsentAllowSerializesWithRevoke follows the first behavior bullet in order. First allow: mcpPending(client, "read write") with scopes [read, write]; assert consentScopes is [read write]. Second request: mcpPendingPKCE(client, "read"). Assert consentShow is 200 with ConsentRequired false, which proves the silent path. Take the consent row's updated_at. Start the holder, start the async allow (decision allow, scopes [read]), and wait for 1 waiter. Assert the MCPCode row with request_id = id2 has a nil CodeHash and the consent updated_at is unchanged. Start the async DELETE /oauth/authorizations/{client} and wait for 2 waiters. Roll back the holder, then collect both results with a 30 s timeout per channel. Then run the final assertions. Postgres grants queued conflicting advisory requests in queue order, so the allow, which waited first, runs before the revoke. That makes the "revoke follows both" outcome deterministic.
- TestMCPConsentFailureRollsBackCode follows the second behavior bullet. Install the trigger with plain Exec on env.gdb: a plpgsql function that RAISEs EXCEPTION, and a BEFORE INSERT OR UPDATE FOR EACH ROW trigger on models.Consent{}.TableName(). The database is per test, so no WHEN clause or client-id interpolation is needed. A t.Cleanup drops the trigger and the function IF EXISTS. Drop them explicitly before the retry.
- Never log a code or token (32.1 rule: tests read code rows by sha256Hex, as issuedCode does).
GREEN: the fix, per the chosen design in the objective.
- classes/mcp_backend_binding.go: add an unexported context key type grantsTxKey and an unexported grantsTxFrom(ctx) returning (*gorm.DB, bool); it is nil-safe on ctx and returns false for a nil tx. Add the exported WithinUserGrantsLock(ctx context.Context, db *gorm.DB, userIDs []uint, fn func(ctx context.Context, tx *gorm.DB) error) error. A nil db returns ErrDatabaseUnavailable. Otherwise it runs db.WithContext(ctx).Transaction, the same style as revoke. Inside, the first statement is lockUserGrants(ctx, tx, userIDs), which is exclusive and in ascending id order. Then it calls fn with context.WithValue(ctx, grantsTxKey{}, tx) and tx. The doc comment must say all of the following. The lock is the exclusive one revoke and the cascade take. The ctx handed to fn makes MCPStore.WithinTx, and therefore wristband.Server.IssueCode on the MCP server, run on tx instead of opening its own transaction, so code issue and any other write in fn commit or roll back together. ctx and tx are valid only until fn returns. Everything in fn must use tx: a query on a second pool connection that takes the same user's grants lock would wait on this transaction for good. Exclusive rather than shared is deliberate. It matches the review's fix, also serializes two allows of the same pair, and costs only a few milliseconds of that one user's exchanges and refreshes. Record this choice in the SUMMARY.
- classes/mcp_store.go MCPStore.WithinTx: keep the nil-store check. Then, when grantsTxFrom(ctx) reports a transaction, return fn of a new mcpTx bound to that tx directly, with no nested Transaction call and no savepoint. An error from fn propagates, and the owner rolls the whole unit back. Otherwise keep today's own-transaction path. Update the doc comment to name WithinUserGrantsLock. Do not change mcpTx methods, lock takers, exchange or refresh.
- controllers/mcp_consent_api.go MCPConsentDecide: keep everything up to and including the computation of issueScopes, the offline flag and the WithGrantedOfflineAccess / WithConsentedBackend ctx values. Compute stored (issueScopes plus offline_access when granted) before the transaction. Replace the separate IssueCode call and recordMCPConsent call with one classes.WithinUserGrantsLock(ctx, db, []uint{userID}, ...) whose function does three things in order. It calls srv.IssueCode with the function's ctx, which already carries the backend and offline values because it derives from ctx, and returns its error unchanged. It then calls recordMCPConsent with the function's ctx and tx, returning its error. Finally it assigns the redirect target to a variable declared outside. After the transaction returns, call writeDecision(w, target, err). That keeps today's mapping: ErrPendingNotFound 404, ErrNoGrantableScopes 422, any other error 500 server_error, and nil 200 {redirect_uri}. The answer is written only after the commit. Leave the pre-lock reads (PendingRequest, mcpPendingClientID, linkedBackend and the 409 check) where they are, because IssueCode re-validates the pending request inside the lock through lookupOwnedPending.
- recordMCPConsent keeps its signature. Its db parameter now receives the locked tx. Rename the parameter to tx and update its doc to say it runs inside the caller's grants-lock transaction. TouchConsent decision: the touch branch needs no lock of its own, because an UPDATE by id cannot recreate a deleted row. Its covers-check read and the replace both must see the post-revoke state, and they now do because they run in the locked tx. Keep the classes.NewStore(tx).WithinOIDCTx call, which nests as a GORM savepoint on tx. replaceMCPConsent is unchanged apart from receiving tx. Update the MCPConsentDecide doc comment: the allow issues the code and records the consent in one transaction under the user's grants lock, so a revoke precedes or follows both, and a failed consent write leaves the request pending.
- Do not touch summercms.go, the OIDC decide path (controllers/consent_api.go / wristband oidc_consent.go), revoke, cascade or any exported signature. The only API addition is WithinUserGrantsLock.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin && go vet ./... && go test -count=1 -v -run 'TestMCPConsentAllowSerializesWithRevoke|TestMCPConsentFailureRollsBackCode|TestMCPConsent$|TestMCPConsentReplace|TestMCPConsentSmoke|TestMCPOfflineAccessUntick|TestMCPRevokeDeletesCode|TestMCPBackendBinding' . 2>&1 | grep -E -- '^(--- (PASS|FAIL|SKIP)|ok|FAIL|panic)'</automated>
</verify>
<done>The RED run, recorded in the SUMMARY, shows TestMCPConsentAllowSerializesWithRevoke failing with "allow answered ... while the user's grants lock was held". It shows TestMCPConsentFailureRollsBackCode failing on a non-NULL code_hash or on the 404 retry. After the fix, the verify output lists `--- PASS:` for both new tests and for TestMCPConsent, TestMCPConsentReplace, TestMCPConsentSmoke, TestMCPOfflineAccessUntick, TestMCPRevokeDeletesCode and TestMCPBackendBinding, with no FAIL or SKIP line, and `go vet ./...` is clean. Nothing is committed yet; Task 2 commits the unit together with the README.</done>
</task>
<task type="auto">
<name>Task 2: Plugin README, full suite, one plugin commit</name>
<files>/media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/README.md</files>
<read_first>
- sm-oauthserver-plugin/README.md lines 30, 33, 78 and the Testing paragraph at line 205 (grep for "After the code is issued", "LockUserGrants(ctx, db, userIDs)" and "TestMCPBackendBinding pins")
</read_first>
<action>
README (the plugin README is the module README; CLAUDE.md requires an exported API change and its README in the same commit):
- Line 33, MCP consent passage: replace the sentence beginning "After the code is issued, a consent row that already covers the request is only touched" so it says the following. The allow runs in one transaction that first takes the user's grants lock (classes.WithinUserGrantsLock, the exclusive lock revoke and the grant cascade take). In it the code is issued (IssueCode, whose MCP store joins that transaction) and a consent row that already covers the request is only touched (TouchConsent); otherwise the stored scopes become the granted set. Keep the existing offline_access, replace-not-union and SaveConsent wording. Add one sentence: a revoke therefore lands before or after both writes, so it is never undone by an allow in flight, and a failed consent write leaves the request pending with no code.
- Line 30, authorized-apps passage: after the LockUserGrants sentence, add that an MCP allow takes the same lock, so a revoke and an allow of the same user never interleave.
- Line 78, classes API list: after LockUserGrants(ctx, db, userIDs), add WithinUserGrantsLock(ctx, db, userIDs, fn). Every identifier written must exist in the package.
- Testing paragraph: append one sentence naming TestMCPConsentAllowSerializesWithRevoke (with another transaction holding the user's grants lock, the allow waits and writes nothing, and a revoke queued behind it removes the code and the consent it then wrote) and TestMCPConsentFailureRollsBackCode (a failing consent write rolls the code back and leaves the request decidable).
Gates, in this order, in the plugin dir: `go vet ./...`, then `go test -short ./...`, then the full non-short `go test -count=1 ./...` (use sudo -u golem bash -c '...' if the Docker socket is denied). Fix any failure your change caused. A failure that also reproduces at HEAD without your change is not yours to fix: record it in the SUMMARY and stop for the orchestrator.
Commit in the plugin repo with explicit paths only, never go.work. Stage classes/mcp_backend_binding.go, classes/mcp_store.go, controllers/mcp_consent_api.go, mcp_consent_race_test.go, mcp_consent_smoke_test.go and README.md. Commit as one logical change with the message "fix(mcp): serialize the consent allow with revoke under the user grants lock". The body should say: CR-01 of the 32.1 review; IssueCode and the consent write now commit in one transaction holding LockUserGrants, so a revoke can no longer be undone by an allow in flight, and a failed consent write rolls the code back. No co-author or attribution trailer (user CLAUDE.md overrides). Do not push or tag. Afterwards `git status --short` must show only ` M go.work`. Record the short hash (git rev-parse --short HEAD) for Task 3.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin && go vet ./... && go test -short ./... && go test -count=1 ./... 2>&1 | tail -5 && git status --short && git log -1 --format='%h %s' && git show --stat --format= HEAD</automated>
</verify>
<done>go vet is clean, and both the -short and the full non-short suites print ok with no FAIL. HEAD in sm-oauthserver-plugin is the new fix commit touching exactly the six listed files, with no attribution trailer, unpushed and untagged. `git status --short` shows only ` M go.work`. The README names WithinUserGrantsLock and both new tests.</done>
</task>
<task type="auto">
<name>Task 3: Mark CR-01 fixed in the 32.1 disposition and security docs (edit only; the orchestrator commits)</name>
<files>/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-REVIEW-DISPOSITION.md, /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-SECURITY.md</files>
<read_first>
- 32.1-REVIEW-DISPOSITION.md (whole file, 48 lines)
- 32.1-SECURITY.md lines 38-48 (register rows T-32.1-06, T-32.1-07) and 66-100 (Residual Risk, Sign-Off)
</read_first>
<action>
Use the plugin short hash from Task 2, called HASH below. Use Edit with scoped replacements, not Write.
32.1-REVIEW-DISPOSITION.md:
- Frontmatter: in the CR-01 finding entry, change disposition from open to fixed. Change the top-level open count from 7 to 6. Leave total, recorded and the other findings unchanged.
- Table: the CR-01 row becomes critical, fixed, with the Source cell "sm-oauthserver-plugin HASH (unreleased; ships with the next plugin tag)".
32.1-SECURITY.md:
- Residual Risk table, CR-01 row: keep the Finding, Severity and Touches cells. Replace the Gap cell with: "Fixed in sm-oauthserver-plugin HASH (2026-11-05, unreleased): `MCPConsentDecide` issues the code and writes the consent in one transaction under `classes.WithinUserGrantsLock` (exclusive `LockUserGrants`, the lock revoke takes); a failed consent write rolls the code back. Tests `TestMCPConsentAllowSerializesWithRevoke`, `TestMCPConsentFailureRollsBackCode`."
- The intro sentence under the Residual Risk heading: append "CR-01 has since been fixed (sm-oauthserver-plugin HASH)."
- Register: in T-32.1-06's evidence cell, change "Residual: CR-01, WR-03, WR-04" to "Residual: WR-03, WR-04 (CR-01 fixed in HASH)". In T-32.1-07's cell, change "Closed at L1 only — see CR-01" to "CR-01 fixed in HASH: the MCP allow takes the same lock". Keep both statuses as closed.
- Sign-Off: tick the checkbox and make it read "[x] CR-01 given a disposition in 32.1-REVIEW-DISPOSITION.md (fixed: sm-oauthserver-plugin HASH)". Change the Approval line to "verified 2026-11-05 (ASVS L1; CR-01 fixed in sm-oauthserver-plugin HASH, unreleased)".
- Do not change frontmatter status, threats_open or the audit trail table.
Do not commit and do not stage. The orchestrator makes the docs commit in summercms.go. Leave the other sessions' uncommitted files (.planning/STATE.md, state.json, G15OFFICE.md and the untracked phase dirs) untouched.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con && H=$(git -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin rev-parse --short HEAD) && grep -n "^open: 6$" 32.1-REVIEW-DISPOSITION.md && grep -n "| CR-01 | critical | fixed | sm-oauthserver-plugin $H" 32.1-REVIEW-DISPOSITION.md && grep -c "$H" 32.1-SECURITY.md && grep -n "\[x\] CR-01 given a disposition" 32.1-SECURITY.md && git -C /media/nvme/dev/golem15/summercms.io/summercms/summercms.go status --short -- .planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con</automated>
</verify>
<done>The disposition file shows CR-01 fixed with the plugin hash in both frontmatter and table, and open: 6. SECURITY.md carries the hash in the residual row, the intro, both register cells, the ticked sign-off box and the approval line (grep -c reports at least 6). Both files show as modified and unstaged in summercms.go, with no other file there touched by this task.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| browser (signed-in user) → POST /oauth/mcp/requests/{request} | the allow decision; the consent page may auto-post it when consent_required is false |
| browser (signed-in user) → DELETE /oauth/authorizations/{client_id} | the revoke that must be final |
| plugin context key → wristband.Server.IssueCode (framework) | IssueCode passes the caller's ctx to the plugin store; the store joins the carried transaction |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-261105-01 | Elevation of privilege | MCPConsentDecide allow path vs revoke (CR-01) | critical | mitigate | IssueCode (MarkIssued, MarkConsented) and recordMCPConsent run in one transaction opened by classes.WithinUserGrantsLock, whose first statement takes the exclusive per-user advisory lock revoke takes; MCPStore.WithinTx joins it via the unexported ctx key; proven by TestMCPConsentAllowSerializesWithRevoke |
| T-261105-02 | Tampering | partial allow (code issued, consent write fails) | high | mitigate | the consent error is returned from fn so the whole transaction, including MarkIssued and MarkConsented, rolls back; the answer is written only after the commit; proven by TestMCPConsentFailureRollsBackCode |
| T-261105-03 | Denial of service | grants lock contention / self-wait | medium | mitigate | lock is per user and held only for two UPDATEs and one upsert; IssueCode's store calls run on the joined tx (no second connection); WithinUserGrantsLock doc forbids pool access inside fn. No new lock cycle: every taker (revoke, cascade, exchange, refresh, allow) takes the advisory lock before any row lock it holds. The cascade's user-event transaction may hold a NO KEY UPDATE lock on the users row, and that is compatible with the KEY SHARE lock the consent insert's foreign key check takes |
| T-261105-04 | Information disclosure | transaction handle leaking through ctx | low | mitigate | key type unexported, set only by WithinUserGrantsLock, documented valid only inside fn; the handler answers with the outer ctx after the transaction returns |
| T-261105-SC | Tampering | npm/pip/cargo installs | low | accept | this task installs no packages and adds no dependency |
</threat_model>
<verification>
- Task 1 verify output: `--- PASS:` for TestMCPConsentAllowSerializesWithRevoke and TestMCPConsentFailureRollsBackCode plus the existing MCP consent, revoke and backend-binding tests; no SKIP (a skip means Docker did not run; rerun via sudo -u golem).
- The RED evidence for both new tests is recorded in the SUMMARY (output from the pre-fix run).
- Task 2: full non-short plugin suite green; one plugin commit with six explicit files; go.work still unstaged and modified; nothing pushed or tagged.
- No file under /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules changed (`git -C .../summercms.go status --short -- modules` is empty).
- Task 3: the disposition and security docs show CR-01 fixed with the plugin hash, uncommitted.
</verification>
<success_criteria>
- A revoke can no longer be undone by an MCP allow in flight: allow code issue + consent write are atomic and serialized with revoke (and with the grant cascade) under the user's exclusive grants lock.
- A failed consent write leaves no live code.
- Deterministic regression tests (lock holder + pg_locks waiter checks, DB trigger) that fail on the old code and pass on the new.
- No framework change and no breaking plugin API change; one plugin commit; 32.1 docs updated for the orchestrator's docs commit.
</success_criteria>
<output>
Create /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/quick/261105-din-fix-32-1-cr-01-serialize-mcp-consent-all/261105-din-SUMMARY.md when done. Include the plugin commit hash, the RED and GREEN test output lines, the exclusive-vs-shared lock choice, and a note for the orchestrator: wristband's OIDC decide path (oidc_consent.go:66-120, SaveConsent and mintCode in one WithinOIDCTx) is atomic but does not take LockUserGrants, so it may have a related revoke race. That is unverified, outside CR-01 and not changed here; it is a candidate follow-up.
</output>

View File

@@ -0,0 +1,114 @@
---
phase: quick-261105-din
plan: 01
subsystem: sm-oauthserver-plugin (MCP consent)
status: complete
tags: [security, oauth, mcp, concurrency, CR-01]
requires: [32.1 MCP consent JSON, classes.LockUserGrants]
provides: [classes.WithinUserGrantsLock, atomic MCP allow serialized with revoke]
affects: [controllers.MCPConsentDecide, classes.MCPStore.WithinTx]
tech-stack:
added: []
patterns: [caller-owned transaction joined via an unexported context key]
key-files:
created:
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/mcp_consent_race_test.go
modified:
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/classes/mcp_backend_binding.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/classes/mcp_store.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/controllers/mcp_consent_api.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/mcp_consent_smoke_test.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/README.md
- .planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-REVIEW-DISPOSITION.md
- .planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-SECURITY.md
decisions:
- "The MCP allow takes the user's grants lock exclusively (not shared), which matches the review's fix, also serializes two allows of the same pair, and costs only a few ms of that user's exchanges and refreshes"
- "IssueCode joins the caller's transaction through an unexported ctx key read by MCPStore.WithinTx, so there is no framework change"
metrics:
completed: 2026-11-05
actuals:
tokens: 11961
tasks: 3
commits: 1
plugin_commit: 21f5985
plan_head_before: d600e2c
plan_head_after: 21f5985
---
# Quick 261105-din: Fix 32.1 CR-01, serialize the MCP consent allow with revoke
**What changed:** the MCP consent allow now issues the code and writes the consent in a single Postgres transaction. Its first statement takes the user's exclusive grants advisory lock, which is the same lock revoke takes. A revoke therefore lands before both writes or after both, and can no longer be undone by an allow in flight. If the consent write fails, the code issue rolls back with it.
**Plugin commit:** `21f5985` in sm-oauthserver-plugin, on master: "fix(mcp): serialize the consent allow with revoke under the user grants lock". It has no co-author trailer and is not pushed or tagged. After the commit, `git status --short` shows only ` M go.work`, the unrelated change that was already there.
## What was built
- `classes.WithinUserGrantsLock(ctx, db, userIDs, fn)` is new in `classes/mcp_backend_binding.go`. It opens a transaction, takes `lockUserGrants` first (exclusive, in ascending id order), then calls `fn(txCtx, tx)`. `txCtx` carries `tx` under the unexported `grantsTxKey`. `grantsTxFrom(ctx)` is nil-safe. A nil db returns `ErrDatabaseUnavailable`.
- `MCPStore.WithinTx`: when ctx carries a grants-lock transaction, `fn` runs on it directly, with no nested transaction and no savepoint. Every other case keeps the store's own transaction. `LazyMCPStore` delegates here, so `wristband.Server.IssueCode` (`lookupOwnedPending`, `MarkIssued`, `MarkConsented`) joins the caller's transaction with no framework change.
- `MCPConsentDecide` allow path: one `WithinUserGrantsLock` runs `srv.IssueCode(txCtx, ...)` and then `recordMCPConsent(txCtx, tx, ...)`. The handler calls `writeDecision` only after the commit, so the status mapping is unchanged (404, 422, 500, 200). The reads before the lock stay where they were, because IssueCode checks the pending request again inside the lock.
- `recordMCPConsent` keeps its signature; its parameter was renamed to `tx`. Its covers-check, `TouchConsent` (nested `WithinOIDCTx`, which becomes a GORM savepoint) and `replaceMCPConsent` all run inside the locked transaction.
- README: the MCP consent passage, the authorized-apps passage, the `classes` API list (`WithinUserGrantsLock(ctx, db, userIDs, fn)`) and the Testing paragraph, which now names both new tests.
- 32.1 docs, edited but not committed: in `32.1-REVIEW-DISPOSITION.md`, CR-01 is `fixed` (`open: 6`) and its table row cites `21f5985`. In `32.1-SECURITY.md`, the residual row, intro, T-32.1-06 and T-32.1-07 cells, sign-off checkbox and approval line now cite `21f5985`.
## Lock choice: exclusive vs shared
The allow takes the exclusive lock, the one revoke and the cascade (`revokeUserGrants`) take. A shared lock would also have serialized the allow against revoke. Exclusive was chosen deliberately for three reasons:
- It matches the review's proposed fix.
- It serializes two allows of the same pair as well.
- It costs only a few milliseconds of that one user's code exchanges and refresh rotations, which take the lock shared while the allow holds it.
The lock order has no new cycle: every lock taker takes the advisory lock before any row lock.
## TDD evidence
**RED, pre-fix code (tests written first; nothing committed in the red state):**
```
mcp_consent_race_test.go:189: allow answered 200 (redirect withheld: it carries a code) while the user's grants lock was held (err <nil>)
--- FAIL: TestMCPConsentAllowSerializesWithRevoke (0.56s)
mcp_consent_race_test.go:301: after the failed consent write: code issued true, request id kept false
--- FAIL: TestMCPConsentFailureRollsBackCode (0.43s)
FAIL
```
Test 1 failed for the CR-01 reason: the allow answered while another transaction held the lock. Test 2 failed because the code was issued (`code_hash` set, `request_id` cleared by `MarkIssued`) even though the consent write failed. The test stops at that assertion, before reaching the 404 retry.
**GREEN, after the fix (Task 1 verify, Docker-backed and not skipped):**
```
--- PASS: TestMCPBackendBinding (1.15s)
--- PASS: TestMCPConsentAllowSerializesWithRevoke (0.67s)
--- PASS: TestMCPConsentFailureRollsBackCode (0.45s)
--- PASS: TestMCPConsentSmoke (0.78s)
--- PASS: TestMCPConsent (0.65s)
--- PASS: TestMCPConsentReplace (0.56s)
--- PASS: TestMCPOfflineAccessUntick (0.73s)
--- PASS: TestMCPRevokeDeletesCode (0.60s)
ok git.golem15.com/golem15/sm-oauthserver-plugin 10.351s
```
I also ran the two new tests with `-count=10`; all ten runs passed (ok, 15.97s), so they are stable.
**Plugin gates before the commit:** `go vet ./...` is clean. `go test -short ./...` passes (ok, 1.45s). The full non-short `go test -count=1 ./...` passes (ok, 96.35s). Docker was available directly, so `sudo -u golem` was not needed.
## Deviations from Plan
1. **[Rule 2 - Security] The early-answer failure message withholds the body on a 200.** The first RED run printed the allow's redirect body, which contains an authorization code. That breaks the 32.1 rule that tests never log a code. `waitForGrantsWaiters` now prints `(redirect withheld: it carries a code)` in place of a 200 body; any other status still prints its body. The plan's message shape, "allow answered <status> ... while the user's grants lock was held", is unchanged. The recorded RED output above comes from the redacted rerun. The leaked code belonged to a throwaway per-test database and was only ever printed to the local terminal.
2. **Test 2 reads the code row by client id, not by request id.** `MarkIssued` sets `request_id` to NULL, so on the pre-fix code a lookup by request id finds nothing. The test reads the client's single MCP code row and asserts `request_id == id` and `code_hash IS NULL`. It checks the same thing and gives a clearer RED message.
3. **The plugin commit is on the plugin repo's `master`.** The orchestrator's constraints and the plan say to commit there, and that is the project's normal workflow for sibling plugin repos. The executor's protected-branch halt does not apply.
## Follow-up flag for the orchestrator
wristband's OIDC decide path (`modules/wristband/oidc_consent.go:66-120`) runs `SaveConsent` and `mintCode` in one `WithinOIDCTx`, so it is atomic. It does not take `LockUserGrants`, though, so a revoke landing during an OIDC allow may race in a similar way. This is unverified and outside CR-01; nothing was changed there. It is a candidate follow-up.
## Known Stubs
None.
## Threat Flags
None. No new endpoint or trust boundary was added. The transaction handle in ctx is unexported, is set only by `WithinUserGrantsLock`, and is valid only inside `fn` (T-261105-04).
## Self-Check: PASSED
- FOUND: sm-oauthserver-plugin/mcp_consent_race_test.go
- FOUND: commit 21f5985 in sm-oauthserver-plugin (6 files, no attribution trailer)
- FOUND: 32.1-REVIEW-DISPOSITION.md with `open: 6` and the CR-01 row fixed at 21f5985; 32.1-SECURITY.md has 6 references to 21f5985 and the ticked sign-off box
- `git -C summercms.go status --short -- modules` is empty (no framework change)

View File

@@ -0,0 +1,280 @@
---
phase: quick-261105-eab
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/oidc_grants_race_test.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/mcp_consent_race_test.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/classes/oidc_store.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/classes/mcp_backend_binding.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/README.md
- /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-SECURITY.md
autonomous: true
requirements:
- quick-261105-eab
estimate:
tokens: 90000
raw_tokens: 90000
tasks: 3
confidence: low
must_haves:
truths:
- "Silent resume vs revoke: if a revoke lands while GET /oauth/authorize/resume/{request} is in flight for the same user and client (the consent covers the request), then once both have answered there is no consent row and no unconsumed auth code for that user and client, and the code the resume issued does not exchange (400)."
- "Refresh vs revoke: if a revoke lands while an OIDC refresh rotation of the same pair is in flight, then once both have answered (refresh 200, revoke 200) the pair has zero access-token and zero refresh-token rows. The new refresh token answers invalid_grant and the new access token gets 401 at /oauth/userinfo."
- "Code exchange vs revoke: if a revoke lands while an OIDC code exchange of the same pair is in flight, both answer 200 with no deadlock and no 500, and afterwards the pair has no tokens."
- "Consent decision vs revoke (pinning): if a revoke lands while an OIDC allow is blocked just before it issues its code, the allow answers 302 with a code and the revoke answers 200. Afterwards there is no consent row, no live code and no token for the pair. This test already passes on the code before the fix, which is the evidence that the decide path was consistent."
- "The plugin's OIDC store (classes/oidc_store.go oidcTx) takes the user's grants lock in shared mode before it takes the first row lock or foreign-key lock on that user's grant rows. SubjectFor, ConsentFor and SaveConsent take it on entry. ConsumeCode and RefreshTokenByHashForUpdate take it after they read the row's user_id by hash. Revoke and the grant cascade take this lock exclusively."
- "summercms.go does not change (nothing under modules/), so no framework tag is needed. No exported plugin identifier is added or changed, and the MCP code paths are untouched. go vet ./... and the full non-short plugin suite are green at the commit. Nothing blocks the plugin's v0.1.7 tag: go.mod still requires summercms v0.6.0."
artifacts:
- path: /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/oidc_grants_race_test.go
provides: "TestOIDCResumeSerializesWithRevoke, TestOIDCRefreshSerializesWithRevoke, TestOIDCExchangeSerializesWithRevoke (red before the fix), TestOIDCConsentAllowThenRevoke (pinning); goroutine-safe asyncDo, lock-waiter polling, gate trigger and pair-count helpers"
- path: /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/classes/oidc_store.go
provides: "oidcTx.SubjectFor, ConsentFor, SaveConsent, ConsumeCode, RefreshTokenByHashForUpdate take lockUserGrantsShared first; Store doc states the invariant"
key_links:
- from: "wristband.Server.Resume / decideConsent / redeemCode / rotateOIDCRefresh / UserInfo (framework, unchanged)"
to: "classes.oidcTx (plugin) via classes.LazyStore -> Store.WithinOIDCTx"
via: "SetOIDCBackend(&classes.LazyStore{...}) in servers.go:154-155"
pattern: "lockUserGrantsShared"
- from: "controllers/authorizations.go revoke (exclusive LockUserGrants)"
to: "classes/oidc_store.go oidcTx (shared lockUserGrantsShared)"
via: "the same pg_advisory key hashtext('golem15_oauthserver_user_grants:<id>')"
pattern: "userGrantsLockKey"
---
<objective>
Investigate the OIDC sibling of CR-01 in sm-oauthserver-plugin and fix it in the plugin only. The investigation is done (findings below). Task 1 turns the findings into deterministic tests that fail on the current code before Task 2 changes anything.
Findings (from reading the current code; the plugin is at HEAD 21f5985, the framework at summercms.go master):
Wiring. The plugin's servers.go:154-155 gives wristband's OIDC server a `classes.LazyStore`, which runs `classes.Store.WithinOIDCTx`: one GORM transaction per call, over `classes.oidcTx`. OIDC codes are stored in `golem15_oauthserver_auth_codes`, consents in `_consents`, and tokens in `_access_tokens` and `_refresh_tokens`. Revoke (controllers/authorizations.go:137-165) deletes rows from exactly these tables after it takes the exclusive grants lock. No oidcTx method takes the grants lock. Only the MCP store's `ByCodeHashForUpdate` and `ByTokenHashForUpdate` take it (shared; classes/mcp_store.go:201, :342). The plugin's JSON consent endpoints (controllers/consent_api.go) call `srv.ConsentRequest` and `srv.DecideConsent`, so they go through the same store.
1. Decide (`wristband.decideConsent`, oidc_consent.go:60-129, used by the HTML POST and by ConsentDecide) is CONSISTENT. `SaveConsent` (oidc_store.go:328-362) and `mintCode` run in one transaction. Two orderings are possible:
- The revoke has already deleted the consent but not committed. The INSERT ... ON CONFLICT DO NOTHING conflict check uses a dirty snapshot, so it waits for the revoke, then inserts a fresh row. That is the order revoke, then allow, and it ends with a consent and a code.
- SaveConsent locks the existing row FOR UPDATE before the revoke's SELECT FOR UPDATE. The revoke then waits for the commit, and its later DELETEs (READ COMMITTED takes a new snapshot per statement) see the issued code. That is the order allow, then revoke, and it ends with nothing.
The only defect: if a revoke commits between the DO NOTHING and the FOR UPDATE, Take returns ErrRecordNotFound, the transaction rolls back and the allow answers 500. That fails closed and leaves nothing behind. Test D pins the consistent outcome.
2. Silent resume (`wristband.Server.Resume`, oidc_authorize.go:223-256) is a RACE. `ConsentFor` is a plain read. If a revoke commits (or holds the deleted row) before `TouchConsent`, the UPDATE by id hits 0 rows without an error, and `mintCode` inserts a code after the revoke's DELETE snapshot. The result is a live code with no consent. The exchange does not require a consent (oidc_token.go:273-280 touches it only when present), so the client gets tokens that the authorized-apps list cannot show, and `DELETE /oauth/authorizations/{client}` answers 404 for them.
3. Refresh (`rotateOIDCRefresh`, oidc_token.go:352-430) is a RACE. `RefreshTokenByHashForUpdate` locks R1. The revoke's DELETE on access_tokens and refresh_tokens uses statement snapshots that do not see the successor A2 and R2. Its DELETE on refresh_tokens waits on R1 and deletes R1 after the rotation commits, so A2 and R2 survive the revoke. access_tokens has no foreign keys, so nothing cascades. The OIDC half of the grant cascade has the same hole, although the comment on revokeUserGrants claims otherwise.
4. Code exchange (`redeemCode`, oidc_token.go:197-301) can DEADLOCK. `ConsumeCode` row-locks the code. The revoke deletes the consent and then waits on the code row. The exchange's `TouchConsent` then waits on the deleted consent row. Postgres detects a deadlock (40P01) and one side answers 500.
Chosen design (plugin only, no framework change, no new exported identifier): make the OIDC store follow the rule the MCP store already follows. Every oidcTx entry point that touches a user's grant rows first calls `lockUserGrantsShared(ctx, t.db, userID)`, before any row lock or foreign-key lock on them:
- `SubjectFor`, `ConsentFor` and `SaveConsent` take the lock on entry.
- `ConsumeCode` and `RefreshTokenByHashForUpdate` first read the row's user_id by hash, take the lock, and only then run their guarded UPDATE or SELECT FOR UPDATE. This is the same pattern as MCP's ByCodeHashForUpdate.
The lock is shared because shared already serializes these flows with revoke and the cascade, which take it exclusively. OIDC flows of the same user do not need to exclude each other: the upsert and the guarded UPDATEs already handle that.
SubjectFor needs the lock because it is the first user-keyed statement in Resume, ConsentRequest and userinfo. Its INSERT takes a KEY SHARE lock on the users row through the foreign key. A user delete takes the exclusive grants lock in the cascade and then runs DELETE on users, so taking the lock after SubjectFor would let a delete and a resume deadlock. In userinfo, SubjectFor also comes before TouchAccessToken's row lock.
Alternatives considered and rejected:
- Wrapping wristband's handlers in WithinUserGrantsLock, as din did for MCPConsentDecide. The plugin mounts wristband's Resume, authorize and token handlers directly, and the token endpoint does not know the user until it reads the code or the token.
- Any framework hook. Not needed, because the framework passes every grant access through the plugin's oidcTx.
Framework change: none. The v0.1.7 plugin tag is not blocked, because go.mod keeps requiring summercms v0.6.0. Tagging stays with the orchestrator.
Purpose: a revoke of an OIDC client is final, and the "ban / password change ends every grant" cascade also catches a rotation that is in flight.
Output: one plugin commit with the four tests, the store fix and the README. A residual-risk row in 32.1-SECURITY.md, which the orchestrator commits.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/CLAUDE.md
@/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/STATE.md
@/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/quick/261105-din-fix-32-1-cr-01-serialize-mcp-consent-all/261105-din-SUMMARY.md
Repository facts the executor must respect:
- The plugin repo is /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin: its own git repo, branch master, HEAD 21f5985 (the CR-01 fix, unpushed), latest tag v0.1.6. `go.work` has an UNRELATED uncommitted change. Never stage, edit, revert or stash it. Never use `git stash`, `git add -A` or `git add .` in that repo.
- Framework code, read-only. Do not change anything in summercms.go/modules:
- summercms.go/modules/wristband/oidc_authorize.go: Resume :188-269, mintCode :413-436.
- oidc_consent.go: decideConsent :60-129.
- oidc_token.go: redeemCode :197-301, rotateOIDCRefresh :349-430.
- oidc_userinfo.go :33-63. Its order is AccessTokenByHash, client, IdentityClaims, subjectFor, TouchAccessToken.
- oidc_subject.go:62-68: subjectFor calls tx.SubjectFor.
- Plugin store: classes/oidc_store.go. Store.WithinOIDCTx is at :46-55. The methods to change are ConsumeCode :200-219, ConsentFor :316-326, SaveConsent :328-362, SubjectFor :371-389 and RefreshTokenByHashForUpdate :426-449. The lock helper `lockUserGrantsShared(ctx, db, userID)` is in classes/mcp_backend_binding.go:77-87: it is a no-op for userID 0 and uses pg_advisory_xact_lock_shared(hashtext(key)). The pattern to copy is MCP `ByCodeHashForUpdate` in classes/mcp_store.go:191-215: it reads user_id by hash with Model/Select/Where/Limit(1)/Scan, takes the lock, then locks the row. Model user_id types: AuthCode.UserID and RefreshToken.UserID are `uint`.
- Schema (updates/202610190001): auth_codes, consents, subjects and refresh_tokens have `user_id REFERENCES users ON DELETE CASCADE`. access_tokens has no foreign key at all.
- Test harness (package oauthserver_test, every Postgres test skips under -short):
- `bootOAuth(t, envs...)` boots a fresh database per test. `env.gdb` is the app's *gorm.DB, and `env.issuer` is the base URL.
- Identity: `env.user(t)`, `env.sessionToken(t, user)`, `env.oidcClient(t, name, mutate...)` (returns clientID and secret, allowed openid profile email at `testRedirect`).
- Flow helpers: `pkce(t)`, `authorizeQuery(clientID, challenge, scope, state, nonce)`, `env.consentRedirect(t, token, clientID, challenge, scope, state, nonce)` (drives authorize, resume and allow, and returns the redirect URL; it handles the silent 302), `hiddenFields(page)`, `env.do(t, method, path, cookieToken, form, header)` (fatal only on a transport error), `env.exchangeCode` (fatal unless 200), `env.signIn(t, token, clientID, secret)`, `env.userInfo(t, accessToken)` (authorize_test.go:148), `env.browser()`.
- From mcp_consent_race_test.go: `asyncResult{status, body, err}`, `env.asyncJSON` (sends a Bearer token, so use it for the revoke DELETE), `receive(t, what, ch)` (30 s).
- A refresh-enabled boot needs the env value SUMMER_GOLEM15__OAUTHSERVER__REFRESH__ENABLED=true (discovery_test.go:196) and a client mutated to OfflineAccess=true with scopes openid, profile, email, offline_access.
- The token endpoint uses client_secret_basic. Copy the Basic header that exchangeCode builds (oidc_flow_smoke_test.go:32-38).
- Never call a t-using helper from a goroutine. Never log a code or a token: on a 200 or 302, withhold the body or Location in failure messages, as din's waitForGrantsWaiters does.
- Docker: if the Docker socket is denied, run the same command through `sudo -u golem bash -c '...'`. A skipped test is not a pass, so every verify greps for explicit `--- PASS:` or `--- FAIL:` lines.
</context>
<tasks>
<task type="tracer" tdd="true">
<name>Task 1: Reproduce first, with deterministic OIDC-vs-revoke race tests (RED on the current code, D pins the decide path)</name>
<files>/media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/oidc_grants_race_test.go, /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/mcp_consent_race_test.go</files>
<read_first>
- sm-oauthserver-plugin/mcp_consent_race_test.go (whole file: helper style, how failure messages withhold the body)
- sm-oauthserver-plugin/harness_test.go :150-345 (user, sessionToken, oidcClient, do, consentRedirect)
- sm-oauthserver-plugin/oidc_flow_smoke_test.go :22-54 (tokenResponse, exchangeCode Basic header)
- sm-oauthserver-plugin/controllers/authorizations.go :137-165 (revoke statement order)
- summercms.go/modules/wristband/oidc_authorize.go :223-256 and oidc_token.go :197-301, :352-430 (the blocking points the tests rely on)
</read_first>
<precondition>In /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin, `git status --short` shows only ` M go.work`, and classes/oidc_store.go is unchanged since 21f5985. `docker info` succeeds; if it does not, use sudo -u golem.</precondition>
<behavior>
- TestOIDCResumeSerializesWithRevoke (A, RED today). The user signs in once, so a consent [openid profile email] exists. A second authorize with the same scopes parks request R. A holder transaction locks R's auth_requests row FOR UPDATE. An async GET of the resume path blocks on that row after it has read the consent; the test waits until 1 backend waits on a lock. An async revoke follows. The test waits until either the revoke answers or 2 backends wait on a lock, then rolls the holder back and collects both answers. Expected: resume 302 with a code, revoke 200. Afterwards: 0 consent rows and 0 unconsumed auth codes for the pair, and exchanging the resume's code does not return 200. Today the revoke completes while the resume is parked, and the resume then issues a code after the revoke: 1 live code, 0 consents.
- TestOIDCRefreshSerializesWithRevoke (B, RED today). Boot with refresh enabled and an OfflineAccess client. Sign in with "openid offline_access" and parse refresh_token R1 from the exchange body. Install the gate trigger (BEFORE INSERT on access_tokens) and hold the gate key. An async refresh with R1 blocks in the trigger, after it has locked R1 (1 waiter). An async revoke then blocks (2 waiters): today on R1's row, after the fix on the grants lock. Release the gate. Expected: refresh 200 with a new access token and refresh token, revoke 200. Afterwards: 0 access-token and 0 refresh-token rows for the pair, the new refresh token answers 400 at /oauth/token, and the new access token gets 401 at /oauth/userinfo. Today the new access and refresh tokens survive (counts 1 and 1).
- TestOIDCExchangeSerializesWithRevoke (C, RED today). Sign in once, then get a second code C2 through the silent consentRedirect. Install the gate trigger on access_tokens and hold the gate key. An async exchange of C2 blocks in the trigger after ConsumeCode (1 waiter). An async revoke blocks (2 waiters). Release the gate. Expected: exchange 200 and revoke 200, then 0 tokens and 0 unconsumed codes for the pair, and the exchanged access token gets 401 at /oauth/userinfo. Today the exchange's TouchConsent and the revoke's code DELETE deadlock, and one side answers 500 after about 1 s.
- TestOIDCConsentAllowThenRevoke (D, PINNING; passes today and after the fix). Sign in with "openid profile". A second authorize with "openid profile email" shows the incremental consent page; take request_id and consent_token from hiddenFields. Install the gate trigger (BEFORE INSERT on auth_codes) and hold the gate key. An async POST /oauth/authorize allow blocks in the trigger after SaveConsent (1 waiter). An async revoke blocks (2 waiters): today on the consent row, after the fix on the grants lock. Release the gate. Expected: allow 302 with a code, revoke 200. Afterwards: 0 consents, 0 unconsumed codes and 0 tokens for the pair, and the allow's code does not exchange.
</behavior>
<action>
Write the tests only. Do not change production code in this task, and do not commit: CLAUDE.md requires `go test ./...` to be green at every commit, so Task 2 commits the tests together with the fix.
In mcp_consent_race_test.go, add one field to asyncResult: `location string`. This is additive; asyncJSON leaves it empty.
New file oidc_grants_race_test.go (package oauthserver_test; imports the plugin's models package). Every helper below must be goroutine-safe or run only on the test goroutine, as noted for each.
- `env.asyncDo(ctx, method, path, cookieToken string, form url.Values, header http.Header) <-chan asyncResult`. It mirrors env.do without t. It sends from a goroutine with env.browser(), adds the token cookie (name "token") when cookieToken is set, and sets the form Content-Type when a form is given. It delivers status, body, the Location header and the error on a buffered channel of size 1.
- `env.lockWaiters(ctx) (int64, error)`. On env.gdb it counts pg_stat_activity rows where datname = current_database(), wait_event_type = 'Lock' and pid <> pg_backend_pid(). This one counter covers waits on advisory locks, transaction ids and tuples, so the same test works on the old and the new code.
- `env.waitForLockWaiters(t, n, what string, inflight ...<-chan asyncResult)`. Test goroutine only. Poll every 10 ms with a 15 s deadline. Return once the count reaches n. If an inflight channel delivers first, fail with "<what> answered <status> before <n> backends waited on a lock"; for a 200 or 302, print "(withheld: it carries a code or token)" in place of the body. On the deadline, fail with the current count.
- `env.waitForAnswerOrLockWaiters(t, ch, n) (asyncResult, bool)`. Test goroutine only. It is the same poll, but a delivery on ch is a valid outcome: it returns (result, true). Reaching n waiters returns (zero, false). The deadline fails the test.
- `env.holdGate(t) *gorm.DB`. Begin a transaction on env.gdb with t.Context() and run SELECT pg_advisory_xact_lock(861105, 1). The two-int form is used because it can never collide with the grants lock's single-bigint hashtext key. Register a Cleanup that rolls the transaction back and ignores the error.
- `env.installGateTrigger(t, table string)`. Use plain Exec on env.gdb. Create a plpgsql function oas_test_gate() RETURNS trigger whose body does PERFORM pg_advisory_xact_lock(861105, 1) and RETURN NEW. Create a trigger oas_test_gate BEFORE INSERT ON <table> FOR EACH ROW EXECUTE FUNCTION oas_test_gate(). Register a Cleanup that drops the trigger (IF EXISTS ... ON table) and the function (IF EXISTS). The database is per test, so fixed names are safe. Take table names from models.AccessToken{}.TableName() and models.AuthCode{}.TableName().
- `env.holdRequestRow(t, requestID) *gorm.DB`. Begin a transaction and run SELECT id FROM models.AuthRequest{}.TableName() WHERE request_id = ? FOR UPDATE. Assert that it found the row. Register a rollback Cleanup.
- `env.pairRows(t, userID uint, clientID string) map[string]int64`. Count the consents rows, the auth_codes rows with consumed_at IS NULL, the access_tokens rows and the refresh_tokens rows where user_id and client_id match.
- `env.tokenCall(t, clientID, secret string, form url.Values) (int, string)`. A non-fatal POST /oauth/token through env.do, with the Basic header built exactly as exchangeCode builds it. Also add `env.asyncTokenCall(ctx, clientID, secret, form) <-chan asyncResult`, built on asyncDo with the same header.
- The revoke runs on env.asyncJSON(ctx, DELETE, "/oauth/authorizations/"+clientID, sessionToken, nil), the Bearer path din already uses.
Tests. Follow the behavior bullets exactly. Each test starts with bootOAuth (B adds the refresh env value), env.user, env.sessionToken and env.oidcClient. Wait details:
- A: after starting the async resume, call waitForLockWaiters(1, "resume", resumeCh). After starting the revoke, call waitForAnswerOrLockWaiters(revokeCh, 2): today the revoke answers here, after the fix 2 waiters appear. Then roll back the holder and receive whatever has not been delivered yet.
- B, C, D: waitForLockWaiters(1, ...) with the flow's channel, then waitForLockWaiters(2, ...) with both channels, then roll back the gate holder and receive both answers.
Extract codes with url.Parse(location).Query().Get("code"). Assert that each one is non-empty without printing it. Final assertions use pairRows, tokenCall and env.userInfo; failure messages print only statuses and counts. Doc comment of each test: what it races, what today's code does (A, B, C) or that it pins a consistent ordering (D), and "Skips under -short".
RED run, on the unchanged production code:
cd /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin && go test -count=1 -v -run 'TestOIDC(Resume|Refresh|Exchange)SerializesWithRevoke|TestOIDCConsentAllowThenRevoke' .
Keep the --- FAIL and --- PASS lines and the failure messages for the SUMMARY.
Gate. These decisions control Task 2:
- Expected result: A, B and C fail for the reasons in the behavior bullets, and D passes. Continue to Task 2.
- If one of A, B or C passes: rerun it with -count=5. If it still passes, the race on that path does not reproduce as analysed; record that in the SUMMARY. If all three pass, the outcome of this task is "not reproducible": Task 2 commits the tests as pinning tests with no change to classes/oidc_store.go, and Task 3 uses the not-reproducible wording. If at least one fails, apply the whole Task 2 fix anyway: it is one uniform invariant.
- If D fails today: record that the decide path is racy after all, with the failure message. Task 2's SaveConsent lock covers it; continue.
- If a test fails for a reason other than the one predicted (a helper bug, a timeout before the expected waiter count), fix the test until the failure is the predicted one. Do not weaken the assertions.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin && go vet ./... && go test -count=1 -v -run 'TestOIDC(Resume|Refresh|Exchange)SerializesWithRevoke|TestOIDCConsentAllowThenRevoke' . 2>&1 | grep -E -- '^(--- (PASS|FAIL|SKIP)|ok|FAIL|panic)|oidc_grants_race_test.go:[0-9]+:'</automated>
</verify>
<done>go vet passes. The output shows `--- FAIL:` for TestOIDCResumeSerializesWithRevoke (a live code with no consent), TestOIDCRefreshSerializesWithRevoke (successor tokens survive) and TestOIDCExchangeSerializesWithRevoke (a 500 from the deadlock), `--- PASS:` for TestOIDCConsentAllowThenRevoke, and no SKIP. The failure lines show no code or token. Nothing is committed, and production code is untouched. Any deviation from the gate's expected result is recorded with its evidence.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: Take the user's grants lock (shared) in the plugin's OIDC store, update the README, run the full suite, make one plugin commit</name>
<files>/media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/classes/oidc_store.go, /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/classes/mcp_backend_binding.go, /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/README.md, /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/oidc_grants_race_test.go, /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/mcp_consent_race_test.go</files>
<read_first>
- sm-oauthserver-plugin/classes/oidc_store.go (whole file)
- sm-oauthserver-plugin/classes/mcp_store.go :187-215 (the ByCodeHashForUpdate pattern to copy)
- sm-oauthserver-plugin/classes/mcp_backend_binding.go :71-87 (userGrantsLockKey, lockUserGrantsShared doc)
- sm-oauthserver-plugin/README.md lines 23, 30, 32 and the Testing paragraph at 205 (grep for "**Stores.**", "An MCP allow takes the same lock", "which the MCP code exchange and refresh rotation take too", "TestMCPConsentFailureRollsBackCode")
</read_first>
<behavior>
- After the fix, all four tests from Task 1 pass. Existing OIDC, consent, token, authorized-apps, cascade and MCP tests stay green.
</behavior>
<action>
Skip the production-code part if Task 1's gate concluded "not reproducible" on all three paths. In that case, commit only the tests and the README Testing sentence, with the commit message "test(oidc): pin OIDC grant flows against a concurrent revoke".
Fix in classes/oidc_store.go, per the design in the objective:
- `SubjectFor`: the first statement is lockUserGrantsShared(ctx, t.db, userID); return its error. It runs before the INSERT ... ON CONFLICT, because that insert's foreign key takes KEY SHARE on the users row. Taking the advisory lock after it would let a user delete deadlock with a resume, since the cascade holds the exclusive lock and then runs DELETE on users.
- `ConsentFor` and `SaveConsent`: take the same lock as the first statement. In Resume and the code exchange the lock is already held by then; taking it again is a cheap re-entry. SaveConsent is the first grant-row access of the consent decision. Before it, the decision holds only its auth_requests row, which no exclusive lock holder touches.
- `ConsumeCode`: keep the empty-hash early return. Next, read user_id from models.AuthCode by code_hash, without a row lock (Model, Select("user_id"), Where, Limit(1), Scan into a struct with a uint field). When the user id is non-zero, call lockUserGrantsShared. Then run the existing guarded UPDATE unchanged. Because the read does not filter on consumed_at, the replay branch of redeemCode (CodeByHash followed by RevokeAccessTokensForCode) also runs under the lock.
- `RefreshTokenByHashForUpdate`: same pattern on models.RefreshToken by token_hash, before the existing SELECT ... FOR UPDATE.
- Do not add the lock to any other method. TouchConsent, CreateCode, CreateAccessToken, CreateRefreshToken, MarkRefreshRotated, RevokeRefreshLineage and TouchAccessToken always run after one of the five methods above in the same transaction (userinfo calls SubjectFor before TouchAccessToken). AccessTokenByHash stays a plain read.
- Doc comments. On `Store`, add a paragraph stating the invariant: every OIDC transaction that touches a user's grant rows takes that user's grants lock in shared mode before its first row or foreign-key lock on them, so revoke and the grant cascade (exclusive) either wait for a resume, consent decision, code exchange, refresh rotation or userinfo call in flight and then see what it wrote, or run first and leave it the post-revoke state. Each of the five methods gets one sentence saying it takes the lock and why. Extend the lockUserGrantsShared doc in classes/mcp_backend_binding.go: the MCP code exchange and refresh rotation take it, and so do the OIDC store's SubjectFor, ConsentFor, SaveConsent, ConsumeCode and RefreshTokenByHashForUpdate.
- Shared, not exclusive, is deliberate. It is enough to serialize with revoke and the cascade, OIDC flows of one user do not need to exclude each other, and it matches the MCP exchange and refresh. Record this choice in the SUMMARY.
- Do not touch: summercms.go, controllers/*, cascade.go, mcp_store.go, any exported identifier. Do not touch go.work.
Run the four Task 1 tests (GREEN), then run them with -count=10 for stability. A flaky test is a test bug: fix the wait condition, not the assertions.
README (the plugin's module README; behaviour and tests change in the same commit):
- Line 23, **Stores.** bullet: append one sentence. Every OIDC transaction that touches a user's grant rows first takes that user's grants lock (shared). SubjectFor, ConsentFor and SaveConsent take it on entry; ConsumeCode and RefreshTokenByHashForUpdate take it after reading the row's user. A revoke or the grant cascade therefore either waits for a resume, consent decision, code exchange, refresh rotation or userinfo call in flight and then deletes what it issued, or runs first.
- Line 30, after "An MCP allow takes the same lock, so a revoke and an allow of the same user never interleave.": add "The OIDC store takes it too (shared), so a revoke never leaves behind a code or a successor token that a silent resume, a code exchange or a refresh rotation in flight issued."
- Line 32: change "which the MCP code exchange and refresh rotation take too (shared, before they lock their row)" to "which the MCP and OIDC code exchanges and refresh rotations take too (shared, before they lock their row)".
- Testing paragraph: after the TestMCPConsentFailureRollsBackCode sentence, add one sentence. It names TestOIDCResumeSerializesWithRevoke, TestOIDCRefreshSerializesWithRevoke and TestOIDCExchangeSerializesWithRevoke: a revoke that lands while a silent resume, a refresh rotation or a code exchange is parked mid-transaction leaves no code or token for the pair, and the exchange does not deadlock. It also names TestOIDCConsentAllowThenRevoke: a revoke queued behind a consent decision removes the consent and the code that decision issued.
- Every identifier you write must exist. SubjectFor and the other method names are wristband.OIDCTx methods that oidcTx implements.
Gates, run in the plugin directory in this order: go vet ./..., then go test -short ./..., then the full non-short go test -count=1 ./... (use sudo -u golem bash -c '...' if the Docker socket is denied). Fix any failure your change caused. If a failure also reproduces at 21f5985 without your change, it is not yours: record it and stop for the orchestrator.
Commit in the plugin repo, staging explicit paths only and never go.work: classes/oidc_store.go, classes/mcp_backend_binding.go, oidc_grants_race_test.go, mcp_consent_race_test.go, README.md. Commit message "fix(oidc): serialize OIDC grant flows with revoke under the user grants lock". The body says three things. First, this is the OIDC sibling of 32.1 CR-01. Second, a silent resume could issue a code after a revoke, a refresh rotation's successor tokens survived a revoke, and a code exchange could deadlock with one. Third, the OIDC store now takes the user's grants lock (shared) before its first grant row, as the MCP store does, and the decide path was already consistent (pinned). No co-author or attribution trailer: the user's CLAUDE.md overrides that. Do not push or tag. Afterwards `git status --short` must show only ` M go.work`. Record the short hash for Task 3.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin && go vet ./... && go test -count=1 -v -run 'TestOIDC(Resume|Refresh|Exchange)SerializesWithRevoke|TestOIDCConsentAllowThenRevoke|TestOIDCFlowSmoke|TestConsentOnce|TestIncrementalConsent|TestTokenEndpoint|TestRevokeAuthorization|TestAuthorizationsSmoke|TestUserCascadeSmoke|TestMCPConsentAllowSerializesWithRevoke|TestMCPBackendBinding|TestMCPGrantRevocation' . 2>&1 | grep -E -- '^(--- (PASS|FAIL|SKIP)|ok|FAIL|panic)' && go test -short ./... && go test -count=1 ./... 2>&1 | tail -3 && git status --short && git log -1 --format='%h %s' && git show --stat --format= HEAD</automated>
</verify>
<done>Every test named in the verify run prints `--- PASS:`, with no FAIL or SKIP; this includes the four new tests, and the -count=10 run also passed. go vet is clean, and both the -short and the full non-short suites print ok. HEAD in sm-oauthserver-plugin is one new commit touching exactly the five listed files (or, in the not-reproducible branch, the tests and the README only). It has no attribution trailer and is unpushed and untagged. `git status --short` shows only ` M go.work`. `git -C /media/nvme/dev/golem15/summercms.io/summercms/summercms.go status --short -- modules` is empty.</done>
</task>
<task type="auto">
<name>Task 3: Add a one-line note on the OIDC sibling to 32.1-SECURITY.md (edit only; the orchestrator commits)</name>
<files>/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-SECURITY.md</files>
<read_first>
- 32.1-SECURITY.md lines 69-82 (Residual Risk intro and table)
</read_first>
<action>
HASH below is the plugin short hash from Task 2. Use Edit with a scoped replacement, never Write.
In the Residual Risk table, insert one row directly after the CR-01 row. Pick the variant that matches Task 1's outcome.
- Fixed variant: | CR-01 sibling (OIDC) | high | T-32.1-07 | Fixed in sm-oauthserver-plugin HASH (2026-11-05, unreleased): the OIDC decide was already consistent (consent upsert and code in one transaction, ordered against revoke by the consent row lock; pinned by `TestOIDCConsentAllowThenRevoke`), but a silent resume could issue a code after a revoke, a refresh rotation's successor tokens survived a revoke and a code exchange could deadlock with one. The OIDC store now takes the user's grants lock (shared) before its first grant row. Tests `TestOIDCResumeSerializesWithRevoke`, `TestOIDCRefreshSerializesWithRevoke`, `TestOIDCExchangeSerializesWithRevoke`. |
- Not-reproducible variant: | CR-01 sibling (OIDC) | n/a | T-32.1-07 | Not reproducible: the OIDC decide, silent resume, code exchange and refresh paths stay consistent under a concurrent revoke; pinned by tests in sm-oauthserver-plugin HASH. |
- For a partial outcome, name only the paths that reproduced, and say the uniform fix covers all of them.
Change nothing else: not the frontmatter, the register, the sign-off or the audit trail. Do not stage or commit. Leave the files of other sessions untouched (.planning/STATE.md, state.json, G15OFFICE.md and the untracked phase dirs).
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/summercms.go && H=$(git -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin rev-parse --short HEAD) && grep -n "| CR-01 sibling (OIDC) |.*$H" .planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-SECURITY.md && git status --short -- .planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con && git diff --stat -- .planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-SECURITY.md</automated>
</verify>
<done>32.1-SECURITY.md has exactly one new Residual Risk row for the OIDC sibling, and it carries the plugin hash. The file shows as modified and unstaged with a one-line insertion. This task touched no other file.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| browser (signed-in user) → GET /oauth/authorize/resume/{request}, POST /oauth/authorize, POST/GET /oauth/authorize/requests/{request} | resume (silent re-grant) and consent decision for an OIDC client |
| relying party → POST /oauth/token | code exchange and refresh rotation, authenticated with the client secret |
| browser (signed-in user) → DELETE /oauth/authorizations/{client_id} | the revoke that must be final |
| wristband (framework) → classes.oidcTx (plugin) | every OIDC grant read and write goes through the plugin's store, which takes the lock |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-261105-eab-01 | Elevation of privilege | OIDC silent resume vs revoke | high | mitigate | oidcTx.SubjectFor and ConsentFor take lockUserGrantsShared before the consent read, so a revoke cannot commit between the read and TouchConsent plus mintCode; proven by TestOIDCResumeSerializesWithRevoke |
| T-261105-eab-02 | Elevation of privilege | OIDC refresh rotation vs revoke and grant cascade | high | mitigate | RefreshTokenByHashForUpdate reads the token's user, then takes the shared lock before the row lock, so revoke and the cascade wait and their fresh statement snapshots see the successor tokens; proven by TestOIDCRefreshSerializesWithRevoke |
| T-261105-eab-03 | Denial of service | OIDC code exchange vs revoke deadlock | medium | mitigate | ConsumeCode takes the shared lock before the code's row lock, which removes the code-row / consent-row cycle; proven by TestOIDCExchangeSerializesWithRevoke |
| T-261105-eab-04 | Denial of service | new lock waits and cycles | medium | mitigate | the lock is shared only and is taken before any row or foreign-key lock on grant rows in every OIDC transaction. SubjectFor precedes the subject insert's KEY SHARE on users (user delete) and TouchAccessToken (userinfo). The decide holds only its auth_requests row, which no exclusive holder touches, before SaveConsent. No new cross-connection access inside a lock |
| T-261105-eab-05 | Tampering | OIDC consent decision vs revoke | low | accept | already consistent (one transaction, ordered by the consent row lock); pinned by TestOIDCConsentAllowThenRevoke. The fail-closed 500 window (revoke between DO NOTHING and FOR UPDATE) closes with SaveConsent's lock |
| T-261105-eab-SC | Tampering | npm/pip/cargo installs | low | accept | no packages installed, no dependency added |
</threat_model>
<verification>
- Task 1 RED evidence: A, B and C show `--- FAIL:` with the predicted reasons and D shows `--- PASS:` on 21f5985. Recorded in the SUMMARY.
- Task 2 GREEN: all four new tests and the regression set print `--- PASS:` with no SKIP, the -count=10 run is stable, the full non-short suite is green, and there is one plugin commit with explicit paths. go.work stays modified and unstaged. Nothing is pushed or tagged.
- No change under summercms.go/modules, so no framework release is needed. The plugin's go.mod is unchanged (summercms v0.6.0), so the orchestrator's v0.1.7 tag is not blocked.
- Task 3: one Residual Risk row in 32.1-SECURITY.md with the hash, left uncommitted.
</verification>
<success_criteria>
- A revoke of an OIDC client can no longer be outlived by a code from a silent resume, or by tokens from a refresh rotation, that was in flight. A code exchange no longer deadlocks with a revoke.
- The finding for the decide path is pinned by a deterministic test.
- The fix is plugin only: no framework change, no exported API change, MCP paths untouched.
- Deterministic tests: a parked transaction (row lock or gate trigger) plus a pg_stat_activity waiter count. They fail on the old code and pass on the new.
</success_criteria>
<output>
Create /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/quick/261105-eab-fix-oidc-consent-decide-race-with-revoke/261105-eab-SUMMARY.md when done. Include:
- the plugin commit hash, the RED and GREEN test lines, and the gate outcome;
- the shared-vs-exclusive choice;
- the finding per path (decide consistent; resume, refresh and exchange fixed);
- a note for the orchestrator: no framework change, v0.1.7 not blocked;
- an out-of-scope observation, not changed here: the grant cascade still filters tokens by created_at < Before, so a token a concurrent rotation issued just after Before is not revoked. MCP has the same behaviour.
</output>

View File

@@ -0,0 +1,133 @@
---
phase: quick-261105-eab
plan: 01
subsystem: sm-oauthserver-plugin (OIDC store)
status: complete
tags: [oidc, oauth, revoke, concurrency, advisory-lock, security, cr-01]
requires:
- quick-261105-din (CR-01 MCP fix, plugin 21f5985)
provides:
- OIDC store takes the user's grants lock (shared) before its first grant row
- deterministic OIDC-vs-revoke race tests (resume, refresh, exchange, decide)
affects:
- 32.1-SECURITY.md residual risk (CR-01 sibling row, uncommitted)
tech-stack:
added: []
patterns:
- "read row owner by hash, take pg_advisory_xact_lock_shared, then row-lock (copied from MCP ByCodeHashForUpdate)"
- "race tests: parked transaction (row lock or BEFORE INSERT gate trigger on a two-int advisory lock) plus pg_stat_activity lock-waiter count"
key-files:
created:
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/oidc_grants_race_test.go
modified:
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/classes/oidc_store.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/classes/mcp_backend_binding.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/mcp_consent_race_test.go
- /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/README.md
- /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-SECURITY.md (uncommitted)
decisions:
- "OIDC store takes the user grants lock in SHARED mode (not exclusive): shared already serializes with revoke and the grant cascade (exclusive); OIDC flows of one user need not exclude each other (upsert and guarded UPDATEs handle that); matches the MCP exchange and refresh."
- "Lock points: SubjectFor, ConsentFor, SaveConsent on entry; ConsumeCode and RefreshTokenByHashForUpdate after reading the row's user_id by hash. No other method locks."
- "Plugin-only fix: no framework (summercms.go/modules) change, no exported identifier added or changed, MCP paths untouched."
metrics:
duration: ~15min
completed: 2026-11-05
tasks: 3
actuals:
tokens: 13000
tasks: 3
commits: 1
plan_head_before: 21f59850d4f96789a363c52eeb02449c2d6498c1
plan_head_after: 7b9899f36f45a13daccf3ec6f7d5c729ebfcc5f1
---
# Quick 261105-eab: OIDC sibling of CR-01 (OIDC grant flows vs revoke) Summary
The plugin's OIDC store now takes the user's grants advisory lock (shared) before its first grant-row or foreign-key lock, so a revoke or the grant cascade can no longer be outlived by a code from a silent resume or by successor tokens from a refresh rotation in flight, and a code exchange no longer deadlocks with a revoke.
The repo of record for code is sm-oauthserver-plugin; `commits`, `plan_head_before` and `plan_head_after` above are measured there (`git rev-list --count 21f5985..HEAD` = 1).
## Plugin commit
- `7b9899f` fix(oidc): serialize OIDC grant flows with revoke under the user grants lock (sm-oauthserver-plugin, master, unpushed, untagged). Files: classes/oidc_store.go, classes/mcp_backend_binding.go, oidc_grants_race_test.go, mcp_consent_race_test.go, README.md. No attribution trailer. `git status --short` afterwards: only ` M go.work` (untouched).
## Gate outcome (Task 1)
Expected result, as predicted: A, B and C failed on 21f5985 for the analysed reasons, D passed. Task 2's full fix applied.
## RED evidence (21f5985, production code unchanged)
```
oidc_grants_race_test.go:322: after resume and revoke (revoke answered while the resume was parked: true): 0 consent rows, 1 live codes, want 0 and 0
oidc_grants_race_test.go:326: the resume's code exchanged (200) after the revoke
--- FAIL: TestOIDCResumeSerializesWithRevoke (0.75s)
oidc_grants_race_test.go:386: after refresh and revoke: 1 access tokens, 1 refresh tokens, want 0 and 0
oidc_grants_race_test.go:395: successor refresh token after the revoke = 200, error "", want 400 invalid_grant
oidc_grants_race_test.go:398: userinfo with the successor access token after the revoke = 200, want 401
--- FAIL: TestOIDCRefreshSerializesWithRevoke (0.63s)
oidc_grants_race_test.go:437: exchange = 200 (withheld: it carries a code or token), revoke = 500 {"error":"server_error"}, want 200 and 200
--- FAIL: TestOIDCExchangeSerializesWithRevoke (1.67s)
--- PASS: TestOIDCConsentAllowThenRevoke (0.81s)
FAIL
```
No code or token appears in any failure line (200/302 bodies are withheld). The 1.67 s on C is Postgres's deadlock_timeout (1 s) firing; the revoke was the victim in this run.
## GREEN evidence (after the fix)
```
--- PASS: TestOIDCResumeSerializesWithRevoke (0.89s)
--- PASS: TestOIDCRefreshSerializesWithRevoke (0.62s)
--- PASS: TestOIDCExchangeSerializesWithRevoke (0.62s)
--- PASS: TestOIDCConsentAllowThenRevoke (0.65s)
ok git.golem15.com/golem15/sm-oauthserver-plugin 7.594s
```
- `-count=10` stability run: 40/40 `--- PASS:`, no FAIL, `ok` (32.0 s).
- Regression set (verify command): `--- PASS:` for TestAuthorizationsSmoke, TestUserCascadeSmoke, TestRevokeAuthorization, TestConsentOnce, TestIncrementalConsent, TestMCPBackendBinding, TestMCPConsentAllowSerializesWithRevoke, TestMCPGrantRevocation, TestOIDCFlowSmoke, TestTokenEndpoint and the four new tests; no FAIL, no SKIP.
- `go vet ./...` clean; `go test -short ./...` ok; full non-short `go test -count=1 ./...` ok (101.3 s). A verbose full run printed 71 top-level `--- PASS:` lines, no `--- FAIL:`, and one pre-existing `--- SKIP: TestIDTokenShapeParity`: it skips without the PHP parity recordings (`requireParityRecordings`, parity_test.go), unrelated to this change. Docker was reachable directly (no sudo -u golem needed).
## Finding per path
| Path | Before | After |
|------|--------|-------|
| Consent decide (`decideConsent`: SaveConsent + mintCode) | Consistent (one tx; ordered against revoke by the consent row lock). Only defect: a fail-closed 500 if a revoke committed between ON CONFLICT DO NOTHING and FOR UPDATE. Pinned by D. | Same outcome, now ordered by the grants lock; the 500 window is closed by SaveConsent's lock. |
| Silent resume (`Server.Resume`) | RACE: revoke committed while resume was parked; resume then issued a live code with no consent (A). | Fixed: SubjectFor/ConsentFor hold the shared lock; the revoke waits and deletes the issued code. |
| Refresh rotation (`rotateOIDCRefresh`) | RACE: successor access and refresh tokens survived the revoke (B). | Fixed: RefreshTokenByHashForUpdate takes the lock before the row lock; the revoke's fresh statement snapshots see the successors. |
| Code exchange (`redeemCode`) | DEADLOCK: code row (exchange) vs consent row (revoke); one side 500 (C). | Fixed: ConsumeCode takes the lock before the code's row lock; both answer 200, no tokens left. |
## Shared vs exclusive
Shared, deliberately. Revoke and the grant cascade take the lock exclusively, so a shared holder already serializes every OIDC flow with them. OIDC flows of the same user do not need to exclude each other (the consent upsert and the guarded UPDATEs handle concurrent flows), and shared matches what the MCP code exchange and refresh rotation already take.
## Deviations from Plan
None in code or tests; the plan executed as written.
- Process note: the plugin commit landed on the plugin repo's `master`, as the plan and orchestrator constraints direct (that repo's convention, as for 21f5985). The executor's generic protected-branch pre-commit assertion was not applied to the sibling plugin repo.
- The orchestrator's constraint (and the user's CLAUDE.md) overrode the session's default co-author trailer: none was added.
## Notes for the orchestrator
- No framework change: `git -C summercms.go status --short -- modules` is empty. No framework tag needed.
- The plugin's go.mod is unchanged (still requires summercms v0.6.0), so nothing blocks the plugin's v0.1.7 tag. Tagging and pushing are left to the orchestrator.
- 32.1-SECURITY.md has one new Residual Risk row "CR-01 sibling (OIDC)" carrying hash 7b9899f; it is modified and unstaged (1 insertion), not committed.
- Not committed per instructions: this SUMMARY, STATE.md, the PLAN and the 32.1 docs. ROADMAP.md untouched.
## Out of scope (observed, not changed)
The grant cascade (`Cascade.OnAccessRevoked`) still filters tokens by `created_at < Before`. A token that a concurrent rotation issues just after `Before` is therefore not revoked by the cascade, even though the rotation now waits for the cascade's lock. MCP has the same behaviour. This is the cascade's cutoff semantics, not a lock-ordering gap, and was left as is.
## Threat surface
No new endpoints, auth paths or schema changes. The new test-only trigger and function (`oas_test_gate`) live only in the per-test database and are dropped in Cleanup.
## Known Stubs
None.
## Self-Check: PASSED
- FOUND: sm-oauthserver-plugin/oidc_grants_race_test.go
- FOUND: commit 7b9899f in sm-oauthserver-plugin
- FOUND: "| CR-01 sibling (OIDC) |" row with 7b9899f in 32.1-SECURITY.md

View File

@@ -0,0 +1,288 @@
---
phase: quick-261105-oc5
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- ../sm-user-plugin/controllers/api_controller.go
- ../sm-user-plugin/controllers/login_gates.go
- ../sm-user-plugin/classes/login_gate.go
- ../sm-user-plugin/login_gate_test.go
- ../sm-user-plugin/README.md
- ../sm-mfa-plugin/go.work
- ../sm-mfa-plugin/go.work.sum
- ../sm-mfa-plugin/classes/config.go
- ../sm-mfa-plugin/config/config.yaml
- ../sm-mfa-plugin/controllers/management.go
- ../sm-mfa-plugin/controllers/webauthn.go
- ../sm-mfa-plugin/factor_password_test.go
- ../sm-mfa-plugin/login_paths_test.go
- ../sm-mfa-plugin/settings_test.go
- ../sm-mfa-plugin/tracer_smoke_test.go
- ../sm-mfa-plugin/webauthn_smoke_test.go
- ../sm-mfa-plugin/webauthn_test.go
- ../sm-mfa-plugin/php_bodies_test.go
- ../sm-mfa-plugin/challenge_smoke_test.go
- ../sm-mfa-plugin/recovery_test.go
- ../sm-mfa-plugin/email_test.go
- ../sm-mfa-plugin/gate_test.go
- ../sm-mfa-plugin/trusted_test.go
- ../sm-mfa-plugin/passwordless_smoke_test.go
- ../sm-mfa-plugin/README.md
- ../sm-demo-app/vue-demo-app/app/lib/twoFactor.ts
- ../sm-demo-app/vue-demo-app/app/lib/twoFactor.test.ts
- ../sm-demo-app/vue-demo-app/app/composables/useTwoFactor.ts
- ../sm-demo-app/vue-demo-app/app/pages/account/security.vue
- ../sm-demo-app/vue-demo-app/i18n/locales/en.json
- ../sm-demo-app/vue-demo-app/i18n/locales/pl.json
- ../sm-demo-app/vue-demo-app
autonomous: true
requirements:
- quick-261105-oc5
must_haves:
truths:
- "With a login gate that challenges, POST /_user/api/v1/activate-by-code with a valid code answers the gate's status and body (for golem15.mfa: 200 {two_factor_required, challenge_token, available_methods, expires_at}) and no token or session cookie; the account is activated either way (F-1, per D-01)"
- "Without a gate, or when every gate allows, activate-by-code answers exactly as before ({message: Account activated, user, token} or the HttpOnly cookie with golem15.user.jwt.token_cookie); a gate error answers the opaque 500 with no token and the account stays activated (D-01)"
- "In sm-mfa-plugin, DELETE /2fa/totp, DELETE /2fa/email, DELETE /2fa/webauthn/{id}, POST /2fa/webauthn/register, and POST /2fa/totp/confirm for a user who already has an enabled second factor answer 403 {\"error\":\"Password confirmation required.\"} without the right password and change nothing (WR-05, per D-02, D-03)"
- "A wrong password on those routes is a failed login attempt in golem15.user's throttle, and a suspended or banned account is refused even the right password, exactly as on the recovery-code routes (D-04)"
- "The first totp/confirm of a user with no enabled factor, email/enable, totp/setup, webauthn/register/options and the trusted-device routes keep their current contract (no password); validation 422 bodies keep PHP's shape and order (D-03)"
- "golem15.mfa.factor_changes_require_password (default true) set to false restores PHP's password-free contract on all five routes (D-05)"
- "Two concurrent password-free totp/confirm calls of a user with no factor end with exactly one 200; the other answers 403 and the first secret stays stored (D-03)"
- "The demo site's /account/security asks for the password before turning the authenticator app off, sends it in the JSON body of DELETE /2fa/totp (never in the query string), shows a localized wrong-password message on the 403, and asks for it in the setup form when another factor is already on (D-06)"
artifacts:
- path: ../sm-user-plugin/controllers/api_controller.go
provides: "ActivateByCode consults CheckLoginGates after VerifyActivationCode and before mintFor"
- path: ../sm-user-plugin/login_gate_test.go
provides: "TestActivateByCodeGates (Postgres)"
- path: ../sm-mfa-plugin/controllers/management.go
provides: "password helper split (passwordFrom, checkPassword) reused by confirmPassword and the five factor-changing handlers"
- path: ../sm-mfa-plugin/classes/config.go
provides: "Config.FactorChangesRequirePassword (factor_changes_require_password, default true)"
- path: ../sm-mfa-plugin/factor_password_test.go
provides: "TestFactorChangesNeedPassword (Postgres)"
- path: ../sm-mfa-plugin/login_paths_test.go
provides: "activation_by_code_is_challenged subtest and the updated tokenMints reason"
- path: ../sm-demo-app/vue-demo-app/app/pages/account/security.vue
provides: "password step for turning TOTP off and for confirming TOTP beside another factor"
key_links:
- from: "sm-user-plugin controllers.ActivateByCode"
to: "controllers.CheckLoginGates with classes.LoginSourcePassword"
via: "the gate answer replaces the token response; sm-mfa-plugin's existing Gate challenges source password"
- from: "sm-mfa-plugin TOTPDisable/EmailDisable/WebAuthnRemove/WebAuthnRegister/TOTPConfirm"
to: "userclasses.CheckAndRecordLogin and userclasses.ThrottleStates"
via: "the shared checkPassword helper (the body of today's confirmPassword)"
- from: "vue-demo-app useTwoFactor.disableTotp(password)"
to: "DELETE /_user/api/v1/2fa/totp JSON body {password}"
via: "$fetch body"
---
<objective>
Close the two deferred 2FA hardening items: finding F-1 (sm-user-plugin's activate-by-code mints a session without asking the login gates, so with `require_activation: false` the mailed activation code stands in for an enabled second factor) and review finding WR-05 (sm-mfa-plugin lets a bare session JWT remove, replace or add second factors). Then the demo frontend asks for the password where the plugin now requires it.
Purpose: a stolen session or a mailbox alone must not get past or rewrite a user's second factor. Both plugins are shared core plugins (sm-demo-app and sm-bm-app mount golem15.mfa; fonoteka.go, sm-demo-app and sm-bm-app mount golem15.user), so the fix is additive where it can be, and the one contract change (WR-05) is explicit in the todo and comes with a config knob. The only frontend that calls the changed routes is sm-demo-app's vue-demo-app (checked at planning: sm-bm-app's frontend and fonoteka call none of them).
Output: one commit in sm-user-plugin, two in sm-mfa-plugin (workspace repoint, then the fix), one in vue-demo-app, one vue-demo-app pointer bump in sm-demo-app. No tag, push, deploy, go.mod version or plugin submodule bump.
Source todos (read them first): `.planning/todos/pending/2026-10-26-activate-by-code-second-factor.md` (g15office yfadd1mb) and `.planning/todos/pending/2026-10-26-mfa-factor-changes-need-reauth.md` (g15office krt3vrts). Background: `.planning/phases/19.6-two-factor-auth-and-device-flow-in-sm-user-plugin/19.6-SECURITY-REVIEW.md` "F-1" (option (a) is the one implemented here) and `19.6-REVIEW.md` "WR-05".
Decisions for this item (from the item description, the todos and the coordinator notes), cited below as D-01..D-07:
- D-01 (F-1): `ActivateByCode` calls `CheckLoginGates` after `VerifyActivationCode` succeeds, with `Source: classes.LoginSourcePassword` (the mailed code is the first factor here), and answers the gate's status and body instead of the token. The account stays activated. No new login source: sm-mfa-plugin's existing gate (every released version) already challenges source password, so the user-plugin patch alone closes F-1 in every app, and no cross-plugin compile dependency appears (19.6-SECURITY-REVIEW F-1 option (a)).
- D-02 (WR-05): password confirmation on `DELETE /2fa/totp`, `DELETE /2fa/email`, `DELETE /2fa/webauthn/{id}`, `POST /2fa/webauthn/register` (every registration, passkey or not) and `POST /2fa/totp/confirm` when it would replace or add beside an enabled factor. The refusal is the existing 403 `{"error":"Password confirmation required."}`.
- D-03: contract edges. Validation (422) and "method not available" (403) answers come before the password check, so PHP's bodies for malformed requests stay the same. Routes not named in D-02 are unchanged. Claude's discretion: `totp/confirm` asks for the password when the user has ANY enabled second factor (not only TOTP). The todo says "when TOTP is already on"; this is a superset of it. Adding a TOTP secret beside an enabled email or WebAuthn factor gives a session thief who also phished the password a factor they control, which is the same risk as replacing one. A user with no factor still enables the first one password-free, as before (their account is protected only by the password anyway). The decision and the factor write run in one transaction under a per-user row lock, so a race cannot slip a second secret past the check.
- D-04: the check is today's `confirmPassword` path: every non-empty password is recorded through `userclasses.CheckAndRecordLogin` for the client address, a banned or suspended account is refused even the right password, and a missing password is refused without recording (WR-06 behaviour, 0a08070).
- D-05 (config knob, Claude's discretion following the coordinator's "keep default behaviour where a config knob makes sense"): new config-only key `golem15.mfa.factor_changes_require_password`, default `true` (the todo asks for the requirement), env `SUMMER_GOLEM15__MFA__FACTOR_CHANGES_REQUIRE_PASSWORD`. `false` restores PHP's password-free contract for an application whose ported PHP frontend cannot send the password yet. The README states that this re-opens WR-05. It is not on the admin settings row (no migration), like `failure_cap.*`.
- D-06 (frontend): vue-demo-app is the submodule checkout `../sm-demo-app/vue-demo-app` (remote golem15/vue-demo-app, HEAD fe5d38d at planning). The sibling `../vue-demo-app` is a stale older checkout: do not edit it. The page asks for the password in the page, not through window.confirm, sends it only in the JSON body, and clears it after every attempt. Sending a password to today's released sm-mfa-plugin v0.1.3 is harmless (it ignores the field), so the frontend change is safe to ship ahead of the plugin release.
- D-07 (release discipline): each repo commits on its own, with explicit paths and no co-author trailer. Commit messages carry no planning IDs (they feed the changelog). No tag, push or deploy. sm-demo-app's README requires `go.mod` to pin tags and each plugin submodule to sit on its pinned tag (`scripts/check-pins.sh`), so the plugin submodule and go.mod bumps in sm-demo-app, sm-bm-app and fonoteka.go wait until the user tags the plugins. They are listed as follow-ups in the SUMMARY. Only the vue-demo-app gitlink is bumped here.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/CLAUDE.md
@/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/todos/pending/2026-10-26-activate-by-code-second-factor.md
@/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/todos/pending/2026-10-26-mfa-factor-changes-need-reauth.md
Repos (absolute; paths in files_modified are relative to summercms.go):
- U = /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin (master, HEAD 97f83cc at planning, clean)
- M = /media/nvme/dev/golem15/summercms.io/summercms/sm-mfa-plugin (master, HEAD 544017c at planning, clean)
- F = /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app/vue-demo-app (master, HEAD fe5d38d, clean)
- D = /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app (clean; vue-demo-app is its submodule)
Several sessions work in these repos at once (batch items oc6 and oc9 also touch sm-demo-app). Run `git status --short` in a repo before editing it and again before staging, and stage only the paths this plan changes.
Facts gathered during planning (do not re-derive):
- U `controllers/api_controller.go` `ActivateByCode` (~line 594): sessionDeps, sessionCookie, readFields, validate code, splitCode, IsAlreadyActivated, `VerifyActivationCode(codeContext(...), gdb, id, code)` returns `(*models.User, bool)`, then `mintFor`, `apiArray`, `writeSession(w, app, cc, token, {"message":"Account activated","user":…})`. `Login` (~lines 133-160) shows the gate-call pattern to copy: `CheckLoginGates(ctx, app, classes.LoginAttempt{User, Source, Fields, Request})`; on error `pluginLog.Error("golem15.user: login gate", "user_id", …, "err", err)` and `writeOpaque500`; on a result, status 0 means 200 and `writeJSON(w, status, gate.Body)`.
- U `controllers/login_gates.go` `CheckLoginGates` doc says "Password Login calls it; a social-login plugin calls it". U `classes/login_gate.go` documents `LoginSourcePassword` as "POST /_user/api/v1/login" and `LoginAttempt.Fields` as "it holds the password on a password login".
- U test harness: `login_gate_test.go` has `countingGate` (records attempts, answers its result) and `gatedEnv(t, result) (*adminEnv, *countingGate)`; `login_gate_smoke_test.go` has `gateFunc` (a func implementing LoginGate, for an error gate). `adminEnv` (admin_harness_test.go) has `gdb`, `seedUser(t, label, mutate)` (password "correct-horse"), `call(t, method, path, token, body)`. `account_test.go TestActivateByCode` packs the code as `strconv.FormatUint(uint64(user.ID), 10) + "!" + code` from `classes.IssueActivationCode(ctx, db, user)`. `token_cookie_test.go TestTokenCookie` covers activate-by-code with the cookie.
- U baseline (planning run): `go vet ./...` clean; `go test -short -count=1 ./...` fails only `TestRegisterCORSPath` ("config/http.yaml not found"; it needs an application checkout, known). Docker works on this host; `-short` still runs some Postgres tests.
- M `go.work` replaces sm-user-plugin with `../fonoteka.go/plugins/golem15/user`, a stale checkout (a1b78b8). M's tests (`TestEveryLoginPathIsGated` compiles the user plugin and scans its source through `go list -m`) therefore never see a U change. At planning, M built, vetted and passed its full suite (`go test -count=1 ./...`, about 55 s with Docker) against U's current checkout through a temporary GOWORK file that replaced sm-user-plugin with ../sm-user-plugin.
- M `controllers/management.go`: `confirmPassword(w, r, app, db, user)` reads `password` from the query, else from `readFields(r)["password"].(string)` (raw, never trimmed), refuses an empty one with 403, refuses banned/suspended (`userclasses.ThrottleStates`), checks `bouncer.CheckPassword`, records through `userclasses.CheckAndRecordLogin(ctx, db, user, classes.ClientIP(app, r), ok)` with `ctx := userclasses.ContextWithThrottle(r.Context(), app)`. `readFields` consumes the body, so a handler that already read its fields must not call it again. `field()` trims, so never use it for the password. `disableHandler` serves TOTPDisable and EmailDisable. `TOTPConfirm` runs signedIn, readFields, validate(totpConfirmRules), MethodAvailable, VerifyTOTP, then a transaction with `classes.EnableMethod` (an upsert that overwrites an enabled secret), `EnsureRecoveryCodes`, `Fire(EnabledEvent)`.
- M `controllers/webauthn.go`: `WebAuthnRegister` (~line 125) runs signedIn, readFields, validate(webAuthnRegisterRules), MethodAvailable, jsonField attestation, cache, a transaction with FinishRegistration, EnableMethod, EnsureRecoveryCodes, Fire. `WebAuthnRemove` (~line 202) parses `{id}` (404 on bad id) then a transaction.
- M `classes/methods.go`: `EnabledMethods(ctx, db, userID) ([]string, error)`, `MethodEnabled(ctx, db, userID, method)`. M `classes/config.go`: `Config` struct plus `LoadConfig(app)`. Booleans are read with `c.Bool`, which gives false for a missing key, so a default-true key needs `c.Has` first. `Effective` embeds `Config`; `overlay` lays the settings row over it and must not touch the new field.
- M tests that call the five routes today (all must pass after the change): `tracer_smoke_test.go` (`enableTOTP` helper ~line 73, a direct confirm ~line 129), `webauthn_smoke_test.go` (`registerKey` helper ~line 173 and direct register/delete calls ~220-328), `webauthn_test.go` (~296-341, ~454), `php_bodies_test.go` (~116-154), `challenge_smoke_test.go:315`, `recovery_test.go` (~90-113: a second confirm and a confirm after email), `email_test.go:162`, `gate_test.go:171`, `trusted_test.go` (~388-426), `passwordless_smoke_test.go:143`. Harness users all have password `testPassword` (harness_test.go:38). `settings_test.go TestSettings` covers LoadConfig through `configApp(t, map)`.
- M `login_paths_test.go`: `tokenMints` has the entry `"controllers/api_controller.go ActivateByCode mintFor": "accepted debt of plan 01; see 19.6-SECURITY-REVIEW.md finding F-1"`; `TestEveryLoginPathIsGated` has subtests mint_sites, password_is_challenged, social_sign_in, other_sources_carry_their_own_proof, passkey_only_with_its_assertion, device_poll_only_after_an_authorize, registration_mints_without_a_gate. Helpers: `e.user(t)`, `e.enableTOTP(t, user)`, `e.call`, `e.verify(t, challenge, "totp", nextCode(t, secret))`, `freshIP()`, `mustStatus`.
- M README: Routes table rows ~60-70, Passkeys ~line 87 and Security notes ~line 164 say the management routes need only the session token (PHP's contract), Configuration table ~89-108 ("The settings screen overrides all of them but `issuer` and `failure_cap.*`"), Testing ~181-189.
- F: `app/composables/useTwoFactor.ts` (`confirmTotp(secret, code)`, `disableTotp()` with DELETE and no body), `app/lib/twoFactor.ts` (pure helpers, tests in `app/lib/twoFactor.test.ts`, 14 passing), `app/pages/account/security.vue` (turnOff uses `window.confirm(t('security.turnOffConfirm'))`; the setup form shows only while TOTP is off; errors go through `authErrors(e, t, fallback)` from `app/composables/useDemoAuth.ts`, which surfaces `data.error` verbatim, so the English 403 text would show on /pl), `i18n/locales/en.json` and `pl.json` "security" blocks (~line 174). `pnpm test` = vitest in Node (pure libs only); `pnpm build` = nuxt build.
- D README: "Push vue-demo-app before the pointer bump in this repository"; a pointer bump commit looks like `6686216 chore: bump vue-demo-app (SEO layers, Polish under /pl/)`.
</context>
<tasks>
<task type="tracer" tdd="true">
<name>Task 1: sm-user-plugin: activate-by-code asks the login gates after the code verifies (F-1)</name>
<files>../sm-user-plugin/controllers/api_controller.go, ../sm-user-plugin/controllers/login_gates.go, ../sm-user-plugin/classes/login_gate.go, ../sm-user-plugin/login_gate_test.go, ../sm-user-plugin/README.md</files>
<read_first>U controllers/api_controller.go (Login ~40-185 and ActivateByCode ~590-645), controllers/login_gates.go, classes/login_gate.go, login_gate_test.go (countingGate, gatedEnv, TestLoginGateOrder), login_gate_smoke_test.go (gateFunc), account_test.go TestActivateByCode (~95-137), README.md bullets "Registration and activation" (line 19), "Login gates" (line 21), the classes/controllers API reference lines on CheckLoginGates and the LoginSource constants (~236, ~256) and the Testing paragraph on the login-gate seam (~360)</read_first>
<behavior>
- TestActivateByCodeGates (Postgres, skipped under -short like TestLoginGateOrder), each case with its own not-activated user (seedUser with IsActivated false) and a fresh activation code:
- challenge gate (gatedEnv with a {two_factor_required…} result): POST /_user/api/v1/activate-by-code answers 200 with exactly the gate body, no "token" key and no Set-Cookie; the gate ran once and saw Source == classes.LoginSourcePassword, the right User.ID, Fields["code"] == the packed code, a non-nil Request; the users row is_activated is true afterwards.
- gate with Status 401 and its own body: the answer carries that status and body, and the account is still activated.
- allowing gate (nil result): the answer is 200 {message: "Account activated", user, token} as before and the gate ran once.
- erroring gate (gateFunc returning an error): opaque 500, no token, account still activated, and a second activate-by-code with the same code answers the Winter error page because the account is already activated (unchanged IsAlreadyActivated behaviour).
- invalid or expired code: the gate never runs (count 0) and the 422 body is unchanged.
- existing TestActivateByCode, TestTokenCookie and TestLoginGateOrder stay green unchanged.
</behavior>
<action>
Write TestActivateByCodeGates in login_gate_test.go first, run it red, then implement (D-01).
In ActivateByCode, after `VerifyActivationCode` returns a verified user and before `mintFor`, call `CheckLoginGates(r.Context(), app, classes.LoginAttempt{User: user, Source: classes.LoginSourcePassword, Fields: fields, Request: r})` (the fields the handler already read; do not read the body again). On an error, log it with `pluginLog.Error("golem15.user: login gate", "user_id", user.ID, "err", err)` and answer `writeOpaque500`. On a non-nil result, answer `writeJSON(w, status, gate.Body)` with status 0 mapped to 200, the same as Login. On both paths, mint nothing and write no session cookie. The activation `VerifyActivationCode` already committed stays as it is (the account is activated whatever the gate answers). With no result, the handler continues exactly as today. Update ActivateByCode's doc comment: it activates, consults the login gates (as password Login does, with source password, because the mailed code is the first factor here), then mints; a gate answer replaces the token response.
Doc comments: in classes/login_gate.go, `LoginSourcePassword` covers POST /_user/api/v1/login and POST /_user/api/v1/activate-by-code (the mailed activation code), and `LoginAttempt.Fields` holds the password on a password login and the activation code on an activation. In controllers/login_gates.go, `CheckLoginGates` is called by password Login, activate-by-code and a social-login plugin.
README.md (same commit, per CLAUDE.md documentation rules): in "Registration and activation", `POST /activate-by-code` answers with a token unless a login gate holds the sign-in back (for example a second-factor challenge, which the user completes through the gate's plugin), and the account is activated either way. In "Login gates", list activate-by-code as a caller (after the code verifies, source password), and add the reason: with `require_activation: false` an account can enable a second factor before it activates, so the mailed code must not stand in for that factor. Update the CheckLoginGates API reference line and the Testing paragraph to name TestActivateByCodeGates.
Commit in U (D-07): `git -C U status --short` first, then stage the five paths explicitly and commit with a message like "fix: activate-by-code asks the login gates before it signs in". No planning IDs, no trailer.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin && go build ./... && go vet ./... && go test -count=1 -run 'TestActivateByCodeGates|TestActivateByCode$|TestTokenCookie|TestLoginGates$|TestLoginGateOrder|TestLoginGateSmoke|TestLoginGatesSmoke' . && N=$(go test -short -count=1 ./... 2>&1 | grep -E '^--- FAIL' | grep -vc 'TestRegisterCORSPath'); test "$N" -eq 0</automated>
</verify>
<done>TestActivateByCodeGates passes with Docker and covers the challenge, refusal, allow, error and bad-code cases. The existing activate-by-code, token-cookie and gate tests pass unchanged. `go test -short ./...` has no failure other than the known TestRegisterCORSPath. One commit in sm-user-plugin with code, doc comments and README.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: sm-mfa-plugin: factor changes ask for the password (WR-05) and activate-by-code is pinned as gated (F-1)</name>
<files>../sm-mfa-plugin/go.work, ../sm-mfa-plugin/go.work.sum, ../sm-mfa-plugin/classes/config.go, ../sm-mfa-plugin/config/config.yaml, ../sm-mfa-plugin/controllers/management.go, ../sm-mfa-plugin/controllers/webauthn.go, ../sm-mfa-plugin/factor_password_test.go, ../sm-mfa-plugin/login_paths_test.go, ../sm-mfa-plugin/settings_test.go, ../sm-mfa-plugin/tracer_smoke_test.go, ../sm-mfa-plugin/webauthn_smoke_test.go, ../sm-mfa-plugin/webauthn_test.go, ../sm-mfa-plugin/php_bodies_test.go, ../sm-mfa-plugin/challenge_smoke_test.go, ../sm-mfa-plugin/recovery_test.go, ../sm-mfa-plugin/email_test.go, ../sm-mfa-plugin/gate_test.go, ../sm-mfa-plugin/trusted_test.go, ../sm-mfa-plugin/passwordless_smoke_test.go, ../sm-mfa-plugin/README.md</files>
<read_first>M go.work, controllers/management.go (whole file), controllers/webauthn.go (WebAuthnRegister, WebAuthnRemove), controllers/helpers.go (readFields, field, signedIn, writeError), classes/config.go (Config, LoadConfig, Effective, overlay), classes/methods.go (EnabledMethods, EnableMethod), config/config.yaml, login_paths_test.go, settings_test.go TestSettings, harness_test.go (bootMFA, user, sessionToken, call), the confirm-password throttle test (grep TestPasswordConfirmationThrottle) for how a recorded failed attempt is asserted, README.md sections Routes, Passkeys, Configuration, Security notes, Testing</read_first>
<behavior>
- Workspace: after the repoint, `go list -m -f '{{.Dir}}' git.golem15.com/golem15/sm-user-plugin` in M prints the sm-user-plugin checkout, and the whole suite passes before any WR-05 change (baseline).
- TestSettings additions (no Docker): LoadConfig without the key gives FactorChangesRequirePassword true; key false gives false; env SUMMER_GOLEM15__MFA__FACTOR_CHANGES_REQUIRE_PASSWORD=false gives false; a settings row never changes it.
- TestFactorChangesNeedPassword (Postgres), one user per case, enabled through the existing helpers:
- DELETE /2fa/totp, DELETE /2fa/email and DELETE /2fa/webauthn/{id} without a password: 403 {"error":"Password confirmation required."}, and the method or credential is still there. With a wrong JSON-body password: the same 403, a failed attempt recorded for the user (assert as TestPasswordConfirmationThrottle does), and nothing changed. With the right password: the PHP 200 body ({message, status}) and the factor gone.
- POST /2fa/webauthn/register without a password: 403 and no new credential, also when the user has no factor at all and also with passwordless true. With the right password: 200 {credential, message, status}.
- POST /2fa/totp/confirm: a user with no factor enables TOTP without a password (200 with recovery_codes, unchanged). With TOTP on, a new secret without a password gives 403 and the stored secret is unchanged (decrypt or compare the ciphertext before and after); with the password gives 200. A user with only email on adding TOTP without a password gives 403, with the password 200.
- Ordering: a malformed totp/confirm or webauthn/register body without a password still answers the PHP 422 body. A method that is not available still answers its 403 "… is not available." body.
- Suspended account: after attempt_limit wrong passwords, the right password on DELETE /2fa/totp answers 403 and TOTP stays on.
- Race: two parallel password-free totp/confirm calls (different secrets, each with a valid code) for a user with no factor end with exactly one 200 and one 403, and the stored secret is the winner's.
- Knob: with golem15.mfa.factor_changes_require_password false (boot env or Config.Set), every route above works without a password (PHP contract).
- TestEveryLoginPathIsGated gains activation_by_code_is_challenged: a user with TOTP is set is_activated false and gets a code from userclasses.IssueActivationCode. POST /_user/api/v1/activate-by-code with "{id}!{code}" answers 200 two_factor_required true with no "token". The users row is activated. Completing the challenge with e.verify and nextCode mints a token. The tokenMints reason for ActivateByCode no longer says accepted debt.
</behavior>
<action>
Step A, workspace (own commit): `git -C M status --short`. In M go.work, change the sm-user-plugin replacement from ../fonoteka.go/plugins/golem15/user to ../sm-user-plugin, the plugin's own repository, which now holds Task 1. The fonoteka checkout is stale and would hide Task 1 from M's tests. Run `go build ./... && go vet ./... && go test -count=1 ./...` in M (the baseline must be green at this point, as it was at planning). Commit go.work (and go.work.sum only if Go changed it) as "chore: develop against the sm-user-plugin checkout".
Step B, tests first: add the TestSettings rows, write factor_password_test.go (TestFactorChangesNeedPassword) and the login_paths_test.go subtest and reason, and run them red.
Step C, implementation (D-02..D-05):
- classes/config.go: add `FactorChangesRequirePassword bool` to Config with a doc comment naming the key, its default and what false re-opens. LoadConfig defaults it to true and reads `c.Bool` only when `c.Has(ConfigPrefix + "factor_changes_require_password")`. Do not touch overlay (config-only key). config/config.yaml: add the key, default true, with a comment in the file's style ("(new)"; the env var name; false restores PHP's password-free factor changes for a frontend that cannot send the password, and re-opens the stolen-session exposure the README describes).
- controllers/management.go: split confirmPassword without changing its behaviour for the recovery-code routes. `passwordFrom(r, fields)` returns the query password, else the raw `fields["password"]` string (never trimmed). `checkPassword(w, r, app, db, user, password) bool` holds today's body: refuse empty, refuse banned or suspended, CheckPassword, CheckAndRecordLogin, refuse 403. confirmPassword becomes `checkPassword(w, r, app, db, user, passwordFrom(r, readFields(r)))`, keeping today's laziness: read the body only when the query has no password. Add a small helper `requiresPassword(eff)` that reports `eff.FactorChangesRequirePassword`.
- disableHandler (TOTP, email): after signedIn, if required, `confirmPassword`; then the existing transaction.
- TOTPConfirm: after validate and the availability check, and before VerifyTOTP: if required, load `classes.EnabledMethods(ctx, db, user.ID)`. When any is enabled, run checkPassword with passwordFrom(r, fields) (the fields already read) and remember confirmed. Inside the existing transaction, before EnableMethod, when required and not confirmed: lock the user's row (`SELECT id FROM users WHERE id = ? FOR UPDATE` on tx, the pattern the user plugin already uses) and re-read `EnabledMethods` on tx. If any method is now enabled, return a package-level sentinel error (for example errPasswordNeeded), roll back, and answer the 403 "Password confirmation required." (not a 500). When confirmed, take the same lock first too, so that factor writes of one user serialize.
- controllers/webauthn.go WebAuthnRegister: after validate and the availability check, and before attestation and FinishRegistration: if required, checkPassword with passwordFrom(r, fields). WebAuthnRemove: if required, confirmPassword right after signedIn, before the id parse.
- Update the handlers' doc comments: each names the password requirement and the knob.
- Existing tests: send `"password": testPassword` wherever a call now needs it. That is the `enableTOTP` and `registerKey` helpers and the direct calls listed in the context section, with the body field, never the query. `enableTOTP` may always send it, because a password the route does not need is ignored. Keep every PHP-shape assertion as it is. Only add the password field, and for the 422 cases leave it out so they still prove validation comes first.
- login_paths_test.go: set the ActivateByCode tokenMints reason to "activation code as first factor: consults the login gates first (F-1)" and add the activation_by_code_is_challenged subtest described in behavior.
README.md (same commit): Routes rows for the five routes gain `password` (JSON body; the query also works, as on the recovery-code routes) and the 403. Add a Configuration row for factor_changes_require_password and note it among the keys the settings screen does not override. Rewrite the Passkeys and Security notes paragraphs that say the management routes need only the session token: the five routes need the password (totp/confirm only when the user already has a second factor), the confirmations go through golem15.user's failed-login throttle, the knob restores PHP's contract and re-opens the exposure, and the remaining password-free paths are the first factor of an account with none, email/enable (codes go to the account's own address) and register/options (stores nothing). Add TestFactorChangesNeedPassword and the new subtest to Testing.
Commit (D-07): `git -C M status --short`, stage exactly the changed paths of this step, message like "fix: changing a second factor asks for the password". No planning IDs, no trailer. This is the contract change of the todo. The SUMMARY flags it for the release note and suggests a minor version (v0.2.0) when the user tags.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-mfa-plugin && test "$(go list -m -f '{{.Dir}}' git.golem15.com/golem15/sm-user-plugin)" = /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin && go build ./... && go vet ./... && go test -short -count=1 ./... && go test -count=1 ./...</automated>
</verify>
<done>M builds against ../sm-user-plugin. The full suite passes with Docker: TestFactorChangesNeedPassword, TestEveryLoginPathIsGated/activation_by_code_is_challenged, the TestSettings rows and every existing test (the PHP body tests unchanged except for the added password fields). Two commits in sm-mfa-plugin: the workspace repoint, then the fix with README.</done>
</task>
<task type="auto" tdd="true">
<name>Task 3: vue-demo-app: the security page asks for the password; bump the pointer in sm-demo-app</name>
<files>../sm-demo-app/vue-demo-app/app/lib/twoFactor.ts, ../sm-demo-app/vue-demo-app/app/lib/twoFactor.test.ts, ../sm-demo-app/vue-demo-app/app/composables/useTwoFactor.ts, ../sm-demo-app/vue-demo-app/app/pages/account/security.vue, ../sm-demo-app/vue-demo-app/i18n/locales/en.json, ../sm-demo-app/vue-demo-app/i18n/locales/pl.json, ../sm-demo-app/vue-demo-app</files>
<read_first>F app/pages/account/security.vue, app/composables/useTwoFactor.ts, app/lib/twoFactor.ts, app/lib/twoFactor.test.ts, app/composables/useDemoAuth.ts (formErrors, authErrors), i18n/locales/en.json and pl.json "security" blocks, README.md "Test and build"; D README.md "Remotes" bullet</read_first>
<behavior>
- twoFactor.test.ts: a new pure helper `isPasswordRefusal(e)` is true for a fetch-error-like object with statusCode (or status) 403 and data.error "Password confirmation required." It is false for a 403 with another error (for example "TOTP is not available."), for a 401 or 422, for null, a string or an object without data.
- Existing 14 tests stay green.
</behavior>
<action>
Write the helper tests first, then implement (D-06). `git -C F status --short` before editing. Edit only F, never the stale sibling ../vue-demo-app.
app/lib/twoFactor.ts: export the constant PASSWORD_CONFIRMATION_REQUIRED (the plugin's exact 403 error text) and `isPasswordRefusal(e: unknown): boolean` as described in behavior. Read `statusCode ?? status ?? response?.status` and `data?.error` defensively, as ofetch's FetchError carries them.
app/composables/useTwoFactor.ts: `disableTotp(password: string)` sends DELETE with `body: { password }` (JSON body, never the query string). `confirmTotp(secret, code, password?: string)` adds `password` to the body only when it is given. Update the comments: golem15.mfa asks for the password to turn a factor off, and to confirm TOTP when another factor is already on.
app/pages/account/security.vue:
- Turning off: replace the browser confirm dialog in turnOff with an in-page step (no browser dialog at all). "Turn off" opens a small form showing the existing turnOffConfirm text, a password input (type password, autocomplete current-password, required), a submit button (turnOff) and a cancel link-button. Submit calls disableTotp(password).
- Setup: when `state.methods.length > 0` (another factor is on; the server asks for the password then), the setup form shows the same password input and passes it to confirmTotp.
- Errors: `isPasswordRefusal(e)` shows t('security.passwordWrong'); other errors keep authErrors.
- Password handling: clear the password ref after every attempt, success or failure, and on cancel. Never log it, never put it in the URL, never store it beyond the ref. Keep `busy` handling and the existing markup classes (form, button, link-button, muted, form__error).
- Update the header comment to mention the password step.
i18n: add to the security block of en.json and pl.json, with the same keys in both: `passwordLabel` ("Your password" / "Twoje hasło"), `passwordWrong` ("Wrong password. Several wrong attempts block the account for a while." / "Nieprawidłowe hasło. Kilka błędnych prób blokuje konto na jakiś czas."), `passwordForSetup` ("Your account already has a second factor: confirm the change with your password." / "Konto ma już drugi składnik: potwierdź zmianę hasłem."). Keep turnOffConfirm as the prompt text. Valid JSON, no other key changes.
Commit in F (D-07): stage the six paths, message like "feat: the security page asks for the password to change a second factor". Then, in D: `git -C D status --short`. Stage only the gitlink `vue-demo-app` (if D shows other sessions' changes, leave them alone) and commit "chore: bump vue-demo-app (password for second-factor changes)". Do not touch D's plugin submodules, go.mod, go.work or plugins.gen.go (D-07: they wait for the plugin tags).
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app/vue-demo-app && pnpm test && node -e "const en=require('./i18n/locales/en.json').security, pl=require('./i18n/locales/pl.json').security; for (const k of ['passwordLabel','passwordWrong','passwordForSetup']) { if (!en[k]||!pl[k]) { console.error('missing', k); process.exit(1) } } if (JSON.stringify(Object.keys(en).sort())!==JSON.stringify(Object.keys(pl).sort())) process.exit(1)" && grep -q "isPasswordRefusal" app/pages/account/security.vue && ! grep -q "window.confirm" app/pages/account/security.vue && grep -q "body: { password }" app/composables/useTwoFactor.ts</automated>
</verify>
<done>vitest passes, including the new isPasswordRefusal cases. en/pl security keys match. security.vue opens no browser dialog and sends the password in the body. `pnpm build` completes. One commit in vue-demo-app and one gitlink-only bump commit in sm-demo-app.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| mailbox → activate-by-code | A mailed activation code is a public-route credential (untrusted holder) |
| session bearer → 2fa management routes | A JWT may be stolen (XSS, leaked token); it must not suffice to change factors |
| browser → password field | The password crosses the page into a JSON body |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-oc5-01 | Elevation of privilege | U ActivateByCode | medium | mitigate | CheckLoginGates after VerifyActivationCode with source password; a gate answer replaces the token (Task 1, TestActivateByCodeGates, M activation_by_code_is_challenged) |
| T-oc5-02 | Tampering | M TOTPDisable, EmailDisable, WebAuthnRemove, WebAuthnRegister, TOTPConfirm | high | mitigate | checkPassword on the five routes per D-02, factors unchanged on refusal (TestFactorChangesNeedPassword) |
| T-oc5-03 | Information disclosure | M checkPassword as a password oracle | high | mitigate | Every non-empty password is recorded through userclasses.CheckAndRecordLogin, and banned or suspended accounts are refused (D-04; suspended case in the test) |
| T-oc5-04 | Tampering | M TOTPConfirm race | medium | mitigate | Users-row FOR UPDATE and an EnabledMethods re-check inside the write transaction; sentinel answers 403 (parallel test) |
| T-oc5-05 | Information disclosure | password in query strings and access logs | low | mitigate | The frontend sends it only in the JSON body. The server's query fallback stays for parity with the existing recovery-code route and is documented |
| T-oc5-06 | Tampering | factor_changes_require_password false | medium | accept | Opt-out for ported PHP frontends only. Default true, and the README says it re-opens WR-05 |
| T-oc5-07 | Information disclosure | F password ref | low | mitigate | Cleared after every attempt and on cancel, autocomplete current-password, never logged or put in a URL |
| T-oc5-SC | Tampering | npm/pip/cargo installs | high | accept | No package is added or installed by this plan (no package.json, go.mod require or lockfile change) |
</threat_model>
<verification>
- U: `go vet ./...`; `go test -count=1 -run 'TestActivateByCodeGates|TestActivateByCode$|TestTokenCookie|TestLoginGate' .`; `go test -short -count=1 ./...` has only the known TestRegisterCORSPath failure.
- M: `go vet ./...`; `go test -count=1 ./...` (Docker) green against ../sm-user-plugin.
- F: `pnpm test`; `pnpm build` completes.
- Each repo's `git log -1 --format=%B` has no Co-Authored-By and no planning ID; `git status --short` shows nothing this plan left unstaged.
- SUMMARY records the commit hashes per repo, the tests that ran (and which needed Docker), and the follow-ups that need the user (D-07):
1. Push and tag sm-user-plugin (next patch, v0.1.20 if free) and sm-mfa-plugin (v0.2.0 suggested: contract change).
2. Push vue-demo-app before sm-demo-app's pointer bump.
3. Bump in D-17 order, separate commits each: sm-demo-app (go.mod plus the user and mfa submodules, check-pins), sm-bm-app (user and mfa), fonoteka.go (user only).
4. Changelog posts for the plugin tags.
5. Move both todos to done and update g15office yfadd1mb and krt3vrts.
6. Note F-1 and WR-05 as resolved in 19.6-SECURITY-REVIEW.md if the user wants that record.
</verification>
<success_criteria>
- With a challenging gate, activate-by-code no longer mints a token. The account is still activated, and every gate-free answer is unchanged.
- No second factor can be removed, replaced, added beside an existing one, or registered as a passkey with a session alone, unless the application opts out through factor_changes_require_password.
- Wrong confirmations count toward the login throttle, and malformed requests keep PHP's 422 bodies.
- The demo security page works against both the current v0.1.3 and the new sm-mfa-plugin.
- All suites named above are green, and every repo has only its own explicit-path commits.
</success_criteria>
<output>
Create `/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/quick/261105-oc5-2fa-hardening/261105-oc5-SUMMARY.md` when done
</output>

View File

@@ -0,0 +1,156 @@
---
phase: quick-261105-oc5
plan: 01
subsystem: auth (sm-user-plugin, sm-mfa-plugin, vue-demo-app)
tags: [security, 2fa, mfa, activation, login-gates, webauthn, totp]
status: complete
requires:
- sm-user-plugin login gate registry (CheckLoginGates)
- sm-mfa-plugin Gate (challenges source password)
provides:
- activate-by-code consults the login gates before it mints (F-1 closed)
- password confirmation on the five factor-changing mfa routes (WR-05 closed)
- golem15.mfa.factor_changes_require_password config key (default true)
- vue-demo-app /account/security password step
affects:
- sm-demo-app, sm-bm-app, fonoteka.go (plugin bumps pending tags)
tech-stack:
added: []
patterns:
- "users-row FOR UPDATE + EnabledMethods re-check inside the factor write (race-safe first factor)"
- "password helper split: passwordFrom / checkPassword / confirmPassword"
key-files:
created:
- ../sm-mfa-plugin/factor_password_test.go
modified:
- ../sm-user-plugin/controllers/api_controller.go
- ../sm-user-plugin/controllers/login_gates.go
- ../sm-user-plugin/classes/login_gate.go
- ../sm-user-plugin/login_gate_test.go
- ../sm-user-plugin/README.md
- ../sm-mfa-plugin/go.work
- ../sm-mfa-plugin/classes/config.go
- ../sm-mfa-plugin/config/config.yaml
- ../sm-mfa-plugin/controllers/management.go
- ../sm-mfa-plugin/controllers/webauthn.go
- ../sm-mfa-plugin/login_paths_test.go
- ../sm-mfa-plugin/settings_test.go
- ../sm-mfa-plugin/README.md
- ../sm-mfa-plugin/{tracer_smoke,webauthn_smoke,webauthn,php_bodies,challenge_smoke,email,gate,trusted,passwordless_smoke}_test.go
- ../sm-demo-app/vue-demo-app/app/lib/twoFactor.ts
- ../sm-demo-app/vue-demo-app/app/lib/twoFactor.test.ts
- ../sm-demo-app/vue-demo-app/app/composables/useTwoFactor.ts
- ../sm-demo-app/vue-demo-app/app/pages/account/security.vue
- ../sm-demo-app/vue-demo-app/i18n/locales/en.json
- ../sm-demo-app/vue-demo-app/i18n/locales/pl.json
- ../sm-demo-app (vue-demo-app gitlink)
decisions:
- "F-1: ActivateByCode calls CheckLoginGates with LoginSourcePassword after VerifyActivationCode; a gate answer or error replaces the token, the activation stays committed"
- "WR-05: password on DELETE totp/email/webauthn/{id}, every webauthn/register, and totp/confirm when ANY factor is enabled; validation 422 and availability 403 come first"
- "golem15.mfa.factor_changes_require_password (default true, config-only, not on the settings row); false restores the PHP password-free contract"
- "sm-mfa-plugin go.work now replaces sm-user-plugin with ../sm-user-plugin instead of the stale fonoteka checkout"
metrics:
duration: ~40 min
completed: 2026-11-05
actuals:
tokens: 26000
tasks: 3
commits: 5
commits_by_repo:
sm-user-plugin: [b179e6b]
sm-mfa-plugin: [357e85d, 3aa52c6]
vue-demo-app: [848ee1e]
sm-demo-app: [7b75d2c]
plan_head_before: "n/a (no commits in summercms.go; sibling repos: sm-user-plugin 97f83cc, sm-mfa-plugin 544017c, vue-demo-app fe5d38d, sm-demo-app da03c06)"
plan_head_after: "sm-user-plugin b179e6b, sm-mfa-plugin 3aa52c6, vue-demo-app 848ee1e, sm-demo-app 7b75d2c"
---
# Quick 261105-oc5: 2FA hardening Summary
activate-by-code now goes through the login gates, so a mailed code no longer gets a user past an enabled second factor (F-1). golem15.mfa's five factor-changing routes now need the user's password and record wrong guesses in the throttle, with a config opt-out (WR-05). The demo security page asks for the password where the plugin now needs it.
## Commits
| Repo | Hash | Message |
|------|------|---------|
| sm-user-plugin | b179e6b | fix: activate-by-code asks the login gates before it signs in |
| sm-mfa-plugin | 357e85d | chore: develop against the sm-user-plugin checkout |
| sm-mfa-plugin | 3aa52c6 | fix: changing a second factor asks for the password |
| vue-demo-app (sm-demo-app/vue-demo-app) | 848ee1e | feat: the security page asks for the password to change a second factor |
| sm-demo-app | 7b75d2c | chore: bump vue-demo-app (password for second-factor changes) |
None of the commits has a co-author trailer or a planning ID. Nothing was pushed or tagged. None of the five repos has uncommitted changes from this plan. summercms.go has no commits; the orchestrator commits this SUMMARY.
## What changed
**Task 1, sm-user-plugin (F-1).** After `VerifyActivationCode`, `ActivateByCode` calls `CheckLoginGates` with `LoginSourcePassword`, the fields it already read and the request. If a gate answers, its status and body go back to the client (status 0 means 200), with no token and no session cookie. If a gate fails, the client gets the opaque 500. Either way the account stays activated. With no gate, or when every gate allows, the answer is the same as before. The doc comments on `LoginSourcePassword`, `LoginAttempt.Fields`, `LoginGates` and `CheckLoginGates` now cover activate-by-code. The README sections "Registration and activation", "Login gates", the API reference and Testing are updated.
**Task 2, sm-mfa-plugin (WR-05).**
- `go.work` now points sm-user-plugin at `../sm-user-plugin`, the plugin's own repo, instead of the stale fonoteka checkout. The full suite passed against it before any WR-05 change.
- `management.go` splits the password check into `passwordFrom`, `checkPassword` and `confirmPassword`, and adds `requiresPassword(eff)`. The recovery-code routes behave exactly as before.
- `disableHandler` (TOTP and email) and `WebAuthnRemove` call `confirmPassword` right after `signedIn`. In `WebAuthnRemove` that is before the id is parsed.
- `WebAuthnRegister` checks the password after validation and the availability check, and before it reads the attestation. This applies to every registration.
- `TOTPConfirm` loads `EnabledMethods` after validation and the availability check. If any factor is enabled, it checks the password before `VerifyTOTP`. Inside the write transaction it locks the user's row (`SELECT id FROM users WHERE id = ? FOR UPDATE`). On the path that skipped the password, it re-reads the enabled methods; if one exists now, `errPasswordNeeded` rolls back and the client gets the 403.
- New `Config.FactorChangesRequirePassword`, from `golem15.mfa.factor_changes_require_password`: default true, env `SUMMER_GOLEM15__MFA__FACTOR_CHANGES_REQUIRE_PASSWORD`, config-only (`overlay` is unchanged). It is documented in `config/config.yaml`.
- README: Features, the Routes table (password and 403 on the five routes, plus the order of answers), Passkeys, the Configuration row and the note that the settings screen does not override it, Security notes (contract, password-free paths, the knob re-opening WR-05, the activate-by-code challenge), and Testing.
**Task 3, vue-demo-app (D-06).**
- New `PASSWORD_CONFIRMATION_REQUIRED` constant and `isPasswordRefusal(e)` helper, with 5 new vitest cases.
- `disableTotp(password)` sends `DELETE` with the JSON body `{ password }`. `confirmTotp(secret, code, password?)` adds the password only when one is given.
- `security.vue`: "Turn off" opens a form on the page (the `turnOffConfirm` text, a password field with `current-password`, submit and cancel). `window.confirm` is gone. The setup form shows the password field when `state.methods.length > 0`. A password refusal shows the localized `passwordWrong` message. The password is cleared after every attempt and on cancel.
- New `security.passwordLabel`, `passwordWrong` and `passwordForSetup` strings in both en and pl.
## Verification run
- **sm-user-plugin:** `go vet ./...` is clean. `TestActivateByCodeGates` (new, Postgres), `TestActivateByCode`, `TestTokenCookie`, `TestLoginGates`, `TestLoginGateOrder`, `TestLoginGateSmoke` and `TestLoginGatesSmoke` pass. `go test -short -count=1 ./...` and the full `go test -count=1 ./...` (Docker) fail only the known `TestRegisterCORSPath` (it needs `config/http.yaml` from an application checkout).
- **sm-mfa-plugin:** `go list -m` reports `../sm-user-plugin`. `gofmt`, `go build` and `go vet` are clean. `go test -short -count=1 ./...` and the full `go test -count=1 ./...` (Docker, about 39 s) pass. `TestFactorChangesNeedPassword` also passed under `-race`, and its race subtest passed 3 more runs.
- New tests: `TestFactorChangesNeedPassword` (disable routes, register, totp_confirm, validation and availability first, suspended account, first-factor race, knob off), the `TestSettings` cases for the knob (default, config, env, and the settings row never changing it), and `TestEveryLoginPathIsGated/activation_by_code_is_challenged`.
- The new tests were red before the handler changes, apart from the activation subtest, which already passed because Task 1 was committed first.
- **vue-demo-app:** `pnpm test` passes 230 tests, including the 5 new ones. The plan's i18n/grep check passes. `pnpm build` completes.
- Docker worked directly; `sudo -u golem` was not needed.
## Deviations from Plan
**1. [Rule 1, test fixes beyond the files the plan listed] More existing calls needed the password.** In `php_bodies_test.go` (management_group), `webauthn_test.go` (registration and delete_scoped_to_the_owner) and `webauthn_smoke_test.go`, some calls now hit the password check before the answer they assert:
- `totp/confirm 422 code` (wrong code)
- `webauthn/register 422 failed` (unknown challenge)
- `DELETE webauthn/999999 404`, and the 404 for another user's key
- registrations whose attestation fails verification
These calls now send `"password": testPassword`. Every PHP body assertion is unchanged, and the pure validation 422 cases still send no password. All the files were already in the plan's list; only these extra call sites were new.
**2. [Discretion] Order of answers in the Routes table.** For `webauthn/register` and `webauthn/{id}`, the 403 for a missing password comes before the 422 "Registration failed: …" and before the 404 for an unknown id. That follows from D-03 (the password check runs after validation and availability, before the attestation or the id is read), and the README Routes table says so.
**3. [Discretion] mfa README states the user plugin version activate-by-code depends on.** The Security note says the challenge needs "sm-user-plugin after v0.1.19". go.mod still requires sm-user-plugin v0.1.12, because no code depends on the new behaviour; only the new `activation_by_code_is_challenged` test needs it (see follow-up 3).
Nothing else deviated. The plan ran as written.
## Contract change (for the release note)
sm-mfa-plugin's management API changes: DELETE `2fa/totp`, DELETE `2fa/email`, DELETE `2fa/webauthn/{id}`, every POST `2fa/webauthn/register`, and POST `2fa/totp/confirm` when the user already has a second factor now need `password` and answer 403 `{"error":"Password confirmation required."}` without it. To restore the old contract, set `golem15.mfa.factor_changes_require_password: false`. A **minor** version, **v0.2.0**, is suggested. sm-user-plugin's change is additive (the answer changes only when a gate challenges), so a patch, **v0.1.20**, fits.
## Follow-ups for the user (not done here: no push, tag, deploy or bumps)
1. Push and tag **sm-user-plugin** (next patch, `v0.1.20` if free) and **sm-mfa-plugin** (`v0.2.0` suggested, because of the contract change). Then post on https://summercms.io/changelog/plugins for both tags (`scripts/changelog-post.py publish … --repo ../sm-<name>-plugin`).
2. Push **vue-demo-app** (`848ee1e`) before pushing sm-demo-app's pointer bump (`7b75d2c`), as sm-demo-app's README requires.
3. After the tags, bump in this order, one commit each:
- **sm-demo-app:** go.mod plus the `user` and `mfa` plugin submodules, then `scripts/check-pins.sh`.
- **sm-bm-app:** user and mfa.
- **fonoteka.go:** user only.
- Optionally raise sm-mfa-plugin's own `go.mod` require of sm-user-plugin to the new tag (and its `plugin.yaml` `requires`), so `GOWORK=off` builds see the activate-by-code gate the new login-paths subtest pins.
4. Any application that mounts golem15.mfa with a frontend other than vue-demo-app must send `password` on these routes, or set `factor_changes_require_password: false` until it can. At planning, sm-bm-app's frontend and fonoteka called none of these routes.
5. Move both todos to done (`2026-10-26-activate-by-code-second-factor.md`, `2026-10-26-mfa-factor-changes-need-reauth.md`) and update g15office yfadd1mb and krt3vrts. The orchestrator owns these.
6. Optionally mark F-1 and WR-05 as resolved in `19.6-SECURITY-REVIEW.md` and `19.6-REVIEW.md`.
## Known Stubs
None.
## Threat Flags
None. No new endpoints were added. The changes tighten existing routes as the plan's threat register describes (T-oc5-01..07 mitigated as planned; T-oc5-06 accepted, documented in the README and config.yaml).
## Self-Check: PASSED
- Files exist: `../sm-mfa-plugin/factor_password_test.go`, and every modified path listed above.
- Commits found: sm-user-plugin b179e6b; sm-mfa-plugin 357e85d, 3aa52c6; vue-demo-app 848ee1e; sm-demo-app 7b75d2c.

View File

@@ -0,0 +1,297 @@
---
phase: quick-261105-oc6
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- ../sm-chatchannels-plugin/contracts/pin_policy.go
- ../sm-chatchannels-plugin/contracts/access_resolver.go
- ../sm-chatchannels-plugin/classes/channel_service.go
- ../sm-chatchannels-plugin/api/pins.go
- ../sm-chatchannels-plugin/pins_test.go
- ../sm-chatchannels-plugin/testdata/PHP_METHOD_MAP.md
- ../sm-chatchannels-plugin/README.md
- ../sm-demo-app/plugins/demo/classes/chat_context.go
- ../sm-demo-app/plugins/demo/classes/chat_context_test.go
- ../sm-demo-app/plugins/demo/chat.go
- ../sm-demo-app/reset_test.go
- ../sm-demo-app/README.md
- ../sm-demo-app/plugins/golem15/chatchannels
- ../sm-demo-app/chat_test.go
autonomous: true
requirements:
- quick-261105-oc6
- WR-02
must_haves:
truths:
- "In sm-chatchannels-plugin, a user whose installed resolver grants channel access but answers CanManageContext false (and either does not implement contracts.PinPolicy or answers CanPin false) gets 404 from POST /_chatchannels/api/v1/contexts/{type}/{id}/channels/{channelId}/pins and from DELETE .../pins/{messageId}. No pin row is written or removed. GET .../pins still answers 200 for them."
- "A user with CanManageContext, or whose resolver also implements contracts.PinPolicy and answers CanPin true, pins and unpins. A second pin of the same message is a no-op that keeps the first pinner, and an allowed user unpins a pin someone else made. A user without channel access is refused (ErrForbiddenAccess) even when CanPin would answer true, and CanPin is not consulted for them."
- "PinMessage refuses with ErrNotFound (HTTP 404, no row) a message id that is unknown, soft-deleted, or in another conversation (another channel or a DM), and refuses any message for a channel with no conversation_id."
- "Hosts that do not implement PinPolicy compile unchanged: contracts.AccessResolver and every existing exported signature in the plugin stay the same, go.mod and go.sum are unchanged, and the plugin's go vet, go test -short and Docker-backed go test pass."
- "In sm-demo-app, with the chatchannels submodule at the new plugin commit, a member of the demo-moderators group pins and unpins in #general, including a seeded welcome pin. A plain member gets 404 for both and the seeded pin survives. The moderator cannot pin an #announcements message or a DM message through #general's path. Nobody can create a channel (CanManageContext stays false)."
- "Commits: one on sm-chatchannels-plugin main, and three on sm-demo-app master in this order: host policy, then the pointer bump alone, then the end-to-end test. None has an attribution trailer. Nothing is pushed or tagged, and go.mod/go.sum are unchanged in both repos."
artifacts:
- path: "../sm-chatchannels-plugin/contracts/pin_policy.go"
provides: "contracts.PinPolicy, the optional host hook CanPin(ctx, userID, contextType, contextID, channelID) bool"
- path: "../sm-chatchannels-plugin/classes/channel_service.go"
provides: "CanPinInChannel, the pin gate used by PinMessage/UnpinMessage, and the message-in-channel check"
- path: "../sm-chatchannels-plugin/pins_test.go"
provides: "TestPinPolicy (Docker) and TestDenyAllHasNoPinPolicy (-short)"
- path: "../sm-demo-app/plugins/demo/classes/chat_context.go"
provides: "ChatAccess.CanPin answering from the moderator group"
- path: "../sm-demo-app/chat_test.go"
provides: "TestDemoPinPolicy end to end over HTTP"
key_links:
- from: "../sm-chatchannels-plugin/classes/channel_service.go PinMessage/UnpinMessage"
to: "contracts.PinPolicy"
via: "type assertion on s.Resolver() after requireChannelAccess and a false CanManageContext"
- from: "../sm-demo-app/plugins/demo/chat.go registerChat"
to: "../sm-demo-app/plugins/demo/classes/chat_context.go NewChatAccess"
via: "svc.SetAccessResolver(classes.NewChatAccess(p.db, p.chatModeratorGroup, nil))"
- from: "../sm-demo-app go.work use ./plugins/golem15/chatchannels"
to: "../sm-chatchannels-plugin main (Task 1 commit)"
via: "submodule gitlink bumped in its own commit"
---
<objective>
Pinning in chat channels becomes a manage action (todo `chatchannels-pin-policy.md`, phase 20 review WR-02). Today any visitor of the demo can unpin the seeded welcome pins or flood the pins panel, because sm-chatchannels-plugin gates PinMessage and UnpinMessage on channel access only, and the demo grants that access to every member. PinMessage also never checks that the message belongs to the channel's conversation.
Purpose: the server enforces who may pin, through an additive and optional host contract, so shared-plugin hosts keep compiling. The demo answers that contract from its existing moderator group (`golem15.demo.chat.moderator_group`, default `demo-moderators`).
Output:
- One commit on sm-chatchannels-plugin main: `contracts.PinPolicy`, the pin gate, the message-in-channel check, tests and README.
- Three commits on sm-demo-app master: the host policy, the submodule pointer bump on its own, and the end-to-end pin test.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/STATE.md
@CLAUDE.md
@.planning/todos/pending/chatchannels-pin-policy.md
Repos and their state at planning time (2026-11-05). Use absolute paths in commands; the shell cwd resets between calls.
- Plugin: /media/nvme/dev/golem15/summercms.io/summercms/sm-chatchannels-plugin, branch `main` at 017843a (= origin/main = tag v0.1.0), clean. Leave the `backup/manifest-pre-rebase` branch alone. Its go.work resolves summercms to ../summercms.go, sm-chat-plugin to ../sm-chat-plugin and sm-user-plugin to ../fonoteka.go/plugins/golem15/user. If main has moved past 017843a, build on top of it and record `git log --oneline 017843a..main` in the SUMMARY. If the tree is dirty, stop: another session is working there.
- Demo: /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app, branch `master` at da03c06, clean (sibling batch items oc5/oc9 may have committed there before you; build on top). The submodule plugins/golem15/chatchannels is detached at 017843a (v0.1.0), and go.mod requires sm-chatchannels-plugin v0.1.0. go.work `use`s the submodule checkout, so development and tests compile the submodule. `go list ./...` at the demo root covers only the app's own 7 packages.
- Baselines measured during planning, all green: the plugin's `go vet ./...`, `go test -short ./...` and Docker-backed `go test -count=1 .` (~36 s); the demo's `go vet ./plugins/demo/...`, `go test -short ./plugins/demo/...` and Docker-backed `TestDemoModeratorDelete` + `TestResetKeepsPlans` (~35 s). Docker is reachable for this user. If the socket is denied, run the tests through `sudo -u golem` (summercms.go CLAUDE.md).
Plugin code facts (sm-chatchannels-plugin):
- contracts/access_resolver.go: the package doc says the package holds the ChannelAccessResolver seam. `AccessResolver` has `CanAccessContext` and `CanManageContext(ctx context.Context, userID uint, contextType string, contextID uint) bool`.
- classes/channel_service.go: the sentinels at :26-35 (`ErrForbidden` = "not allowed to manage this channel context", `ErrForbiddenAccess`, `ErrNotFound`). `Resolver()` at :101 never returns nil. `requireManage` at :293 and `requireAccessContext` at :303. `CanAccessChannel` at :463 checks resolver access plus membership for private channels. `requireChannelAccess` at :481. `PinMessage` at :1332 calls requireChannelAccess, then FirstOrCreate on (channel_id, message_id) with Attrs ConversationID/PinnedBy. `UnpinMessage` at :1348 calls requireChannelAccess, then deletes. `PinsFor` at :1356 orders by created_at DESC, id DESC. The file already imports `chatmodels "git.golem15.com/golem15/sm-chat-plugin/models"`.
- sm-chat-plugin models/message.go: `chatmodels.Message` (table golem15_chat_messages) has `ConversationID uint`, `SenderID`, `Type` (`chatmodels.TypeText` = "text"), `Content *string` and `DeletedAt gorm.DeletedAt`. A GORM query through `Model(&chatmodels.Message{})` therefore excludes soft-deleted rows.
- api/pins.go: `ListPins`, `PinMessage` and `UnpinMessage` call `channelActor` (api/auth.go:74). It looks the service up per request and returns 404 for an unknown, foreign or invisible channel. Errors go through `writeChannelError` (api/errors.go), which maps ErrForbidden, ErrForbiddenAccess and ErrNotFound to 404 `{"error":"Not found"}`. No mapping change is needed.
- Tests (package chatchannels_test): harness_test.go has `bootChannels(t, nil)` returning `*channelEnv` with fields app, gdb, plugins, svc and rt, plus `env.user(t)` and `env.count(t, table, where, args...)`. fixture_plugin_test.go:188 has `env.team(t, name, members...)`, which inserts acme_teams_* rows, and `teamsAlias` = "teams". http_tracer_test.go has `bootWeb(t)` returning `*webEnv` (a surf handler), `env.frontendToken(t, user)`, `env.call(t, method, path, token, body)` (path relative to chatchannels.APIPrefix), `decodeObject`, and `teamAccessResolver`, whose CanManageContext equals CanAccessContext. `channelActor` looks the service up per request, so `env.svc.SetAccessResolver(...)` after bootWeb applies to HTTP calls. TestMain (testmain_test.go) skips the container under -short.
- testdata/PHP_METHOD_MAP.md rows 37-42 map the six PHP pin tests to TestChannelHTTPTracer/TestAccessResolverDefault. TestPHPMethodMap requires status `ported` and an existing Go test name.
- The PHP original (wavepath ChannelService.php pinMessage/unpinMessage, D-57-02) let any member pin and unpin. This change deliberately tightens that per the todo (WR-02).
Demo code facts (sm-demo-app):
- plugins/demo/classes/chat_context.go: the interface assertions var block is at :18-26. `IsModerator(ctx, db, userID, group)` at :90 returns false without querying when the user is 0, the group is "" or db is nil, and otherwise calls userclasses.HasGroupCode. `ChatAccess` at :239-275 has the fields `db func() *gorm.DB` and `isMember MemberFunc`, plus `NewChatAccess(db, isMember)`, `CanAccessContext` (demo/1 + member) and `CanManageContext`, which is always false (D-07: channels come from demo:seed only, and TestDemoChannelsSeededOnly relies on it).
- plugins/demo/classes/forum_access.go is the pattern to mirror: `NewForumAccess(db func() *gorm.DB, moderatorGroup func() string, isMember MemberFunc)`, a `member` helper and a `moderator` helper.
- plugins/demo/chat.go:68: `svc.SetAccessResolver(classes.NewChatAccess(p.db, nil))`. `p.chatModeratorGroup` (:93) is a `func() string` method value.
- plugins/demo/classes/chat_context_test.go: TestDemoChatAccess (~:177) calls `NewChatAccess(someDB, m.fn)` four times. `someDB()` is an empty `&gorm.DB{}`: any real query on it panics, so unit tests must never reach IsModerator with a non-empty group for a community member.
- reset_test.go `addChatActivity` (:155-210) has the plain walker POST a pin in #general (:187, `ok("pin", ...)` fails on status >= 300). Under the new rule the walker must be a moderator for that step. `makeModerator(t, a *apiDemo, userID)` lives in chat_test.go:19 (same package main), and `a := &apiDemo{Demo: d, h: h}` already exists inside addChatActivity. demo:reset empties users_groups entirely (plugins/demo/console/reset.go:31), so the extra membership does not disturb the reset assertions.
- Root test helpers (package main): `bootAPI(t, nil, nil)` boots and seeds (the demo-moderators group exists). Also `a.member(t, email)` returning (id, token), `a.openChannel(t, token, slug)` returning the conversation id, `a.bootstrapChat(t, token).Channels` ({ID, Slug, ConversationID}), `a.postMessage(t, token, convID, content)` returning (status, id), `a.openDM(t, token, userID)` returning (status, convID), `a.call(t, method, path, token, body)` and `scalar[T](t, a.Demo, query, args...)`. The seed inserts one pin each in #general, #announcements and #ogólny by SQL (seed_chat.go:279). TestSeedChatSmoke counts 3 pinned channels, which is unaffected.
- README.md "Moderation." paragraph (~:186-188) lists what demo-moderators may do.
- scripts/check-pins.sh (run by build.sh and check-all.sh) requires each plugin submodule HEAD to equal the commit of the tag go.mod requires. After the untagged pointer bump it will report chatchannels until the user tags the plugin and bumps go.mod. That is expected; do not run it as a gate and do not change go.mod.
- Frontend: vue-chat-layer's useChat `togglePin` already hides the pin action for the session after a 4xx refusal (`pinAllowed`). No frontend change is in scope.
</context>
<tasks>
<task type="tracer">
<name>Task 1: sm-chatchannels-plugin: pin and unpin need CanManageContext or a host PinPolicy, and the pinned message must be in the channel</name>
<files>../sm-chatchannels-plugin/contracts/pin_policy.go, ../sm-chatchannels-plugin/contracts/access_resolver.go, ../sm-chatchannels-plugin/classes/channel_service.go, ../sm-chatchannels-plugin/api/pins.go, ../sm-chatchannels-plugin/pins_test.go, ../sm-chatchannels-plugin/testdata/PHP_METHOD_MAP.md, ../sm-chatchannels-plugin/README.md</files>
<precondition>/media/nvme/dev/golem15/summercms.io/summercms/sm-chatchannels-plugin is on branch main with a clean working tree, and `docker info` succeeds (or the tests run through sudo -u golem).</precondition>
<behavior>
- A member with channel access, but neither manage nor PinPolicy permission, gets ErrForbidden from PinMessage and UnpinMessage (HTTP 404). No pin row is written and an existing row survives. PinsFor still works for them (HTTP GET 200).
- A manager (CanManageContext true) pins: the row has pinned_by = manager, and a second pin of the same message keeps one row and the first pinner. A manager unpins, which removes the row.
- With a resolver that also implements contracts.PinPolicy and answers CanPin true for a non-manager, that user pins and unpins, including a pin another user made. CanPin receives the channel's context type, context id and channel id.
- A user without channel access gets ErrForbiddenAccess even though CanPin would answer true for them, and CanPin is not called for them.
- PinMessage returns ErrNotFound and writes no row for an unknown message id, a soft-deleted message, a message of another channel's conversation, and a channel copy whose ConversationID is nil. Over HTTP the foreign message is 404.
- PinsFor lists pins newest first and PinCountFor counts them (so the PHP map rows can point at this test).
- Under -short: classes.DenyAll does not implement contracts.PinPolicy, and CanPinInChannel on a nil service or a nil channel is false.
</behavior>
<action>
Work in /media/nvme/dev/golem15/summercms.io/summercms/sm-chatchannels-plugin. All changes are additive (a shared plugin used by several apps). No existing exported signature changes, contracts.AccessResolver stays as it is, and no dependency is added.
1. Create contracts/pin_policy.go with the optional interface `PinPolicy`. It has one method: `CanPin(ctx context.Context, userID uint, contextType string, contextID, channelID uint) bool`. Write the doc comment in the style of sm-chat-plugin's contracts.MessageModerator:
- It is an optional interface the host's AccessResolver may also implement.
- golem15.chatchannels consults it only for PinMessage and UnpinMessage, after the channel access check passed and only when CanManageContext answered false. True lets userID pin and unpin messages in channel channelID of that host context.
- It never grants access to the channel.
- A host that does not implement it lets only CanManageContext pin.
- Any member could pin before this rule (v0.1.0). A host that wants that behaviour back implements CanPin by answering its own CanAccessContext.
In contracts/access_resolver.go, update only the package doc comment so it names both seams: the required AccessResolver and the optional PinPolicy.
2. In classes/channel_service.go, next to the pin methods:
- Add an unexported helper `pinAllowed(ctx, actorID, ch) bool`. It is true when `s.Resolver().CanManageContext(ctx, actorID, ch.ContextType, ch.ContextID)` is true. Otherwise, when `s.Resolver()` also satisfies `contracts.PinPolicy` (type assertion), it returns `CanPin(ctx, actorID, ch.ContextType, ch.ContextID, ch.ID)`. Otherwise it is false.
- Add an exported `CanPinInChannel(ctx context.Context, actorID uint, ch *models.Channel) bool`. It is nil-safe: a nil service or channel is false, matching CanAccessChannel. It returns CanAccessChannel && pinAllowed. Hosts and bootstraps can use it to show or hide the pin action.
- Add an unexported `requirePin(ctx, actorID, ch) error`. It runs requireChannelAccess first and returns that error unchanged (ErrNotFound or ErrForbiddenAccess). It then returns ErrForbidden when pinAllowed is false.
- Add an unexported `requireMessageInChannel(ctx, ch, messageID) error`. It returns ErrNotFound when ch.ConversationID is nil or zero. Otherwise it counts `Model(&chatmodels.Message{})` rows where id = messageID and conversation_id = *ch.ConversationID, which excludes soft-deleted rows. Zero is ErrNotFound and a query error is returned as is.
- PinMessage: requirePin, then requireMessageInChannel, then the existing FirstOrCreate, unchanged.
- UnpinMessage: requirePin, then the existing delete, unchanged. Do not add a message check to unpin: a stale pin of a deleted message must stay removable.
- Update both doc comments to say "PHP successor, tightened by WR-02" and state the rule. PinsFor, IsPinned, PinCountFor and RemovePinsForMessage stay unchanged.
3. In api/pins.go, update only the doc comments of the PinMessage and UnpinMessage handlers. They now say: 404 also when the caller may not pin (CanManageContext or contracts.PinPolicy) and, for POST, when message_id is not a live message of this channel's conversation. Do not change the status mapping in api/errors.go. Forbidden and not-found both stay 404, the plugin's existing anti-enumeration rule.
4. Create pins_test.go (package chatchannels_test):
- A resolver type `pinAccess` with access for team members, using the acme_teams_members count in the same way as teamAccessResolver, and CanManageContext only for user ids in a managers set.
- A pointer type `pinAccessWithPolicy`. It embeds pinAccess, adds a pinners set, and records the arguments of each CanPin call plus a call count. Its CanPin deliberately ignores access, which proves the service checks access first.
- Compile-time assertions that both satisfy contracts.AccessResolver and that *pinAccessWithPolicy satisfies contracts.PinPolicy.
- `TestPinPolicy` (Docker; the harness skips it under -short):
- Use bootWeb(t). Create users manager, member, pinner and stranger. The team holds manager, member and pinner.
- Install pinAccess with managers = {manager}.
- CreateChannel "general" and "random" as manager with member and pinner as participants.
- Insert messages with env.gdb.Create(&chatmodels.Message{ConversationID, SenderID, Type: chatmodels.TypeText, Content}): two in general, one in random, and one in general that you then soft-delete with env.gdb.Delete.
- Cover every behavior bullet at the service level, checking errors with errors.Is and row counts with env.count on golem15_chatchannels_channel_pins.
- Cover over HTTP with env.call on /contexts/teams/{teamID}/channels/{channelID}/pins: member POST is 404, manager POST is 200 with message_id and channel_id, manager POST of the random message on general's path is 404, member GET is 200, member DELETE is 404, and manager DELETE is 200.
- Then install pinAccessWithPolicy with pinners = {pinner, stranger}. Cover: pinner pins and unpins (including the manager's pin); the recorded CanPin args are (teams, teamID, general.ID); member is still refused; stranger gets ErrForbiddenAccess and the CanPin call count does not change.
- Also cover newest-first PinsFor and PinCountFor with two pins.
- `TestDenyAllHasNoPinPolicy` (runs under -short): DenyAll does not satisfy contracts.PinPolicy, and `(*classes.ChannelService)(nil).CanPinInChannel(ctx, 1, nil)` is false.
5. In testdata/PHP_METHOD_MAP.md, re-point the six pin rows to TestPinPolicy: test_pin_message_creates_row_keyed_on_channel_and_message, test_second_pin_of_same_message_is_idempotent_noop_first_pinner_wins, test_any_member_can_unpin_regardless_of_who_pinned, test_pins_for_returns_newest_first, test_pin_unpin_list_throw_channel_forbidden_when_resolver_denies and test_pin_count_for_counts_distinct_pinned_messages. Keep status `ported`, and leave the row count and PHP names unchanged.
6. README.md: same commit, per the summercms.go documentation rules.
- Add a Features bullet "**Pin policy.**" stating the rule. Pin and unpin need channel access plus CanManageContext, or a contracts.PinPolicy the installed resolver also implements. A pinned message must be a live message of the channel's conversation (otherwise ErrNotFound, 404). Listing pins needs channel access only.
- Add a sentence in the same bullet that this tightens the v0.1.0 rule (any member pinned), and that a host that wants it back answers CanPin with its access check.
- In Usage, add a short Go example of a resolver that also implements CanPin.
- In the API reference, add a `contracts.PinPolicy` row and add `CanPinInChannel` to the ChannelService method list.
- In Testing, add the TestPinPolicy Docker line and TestDenyAllHasNoPinPolicy to the -short line.
7. Run gofmt, go vet, go test -short and the full Docker-backed go test. Then commit on main, staging the seven paths explicitly (never `git add -A`). Suggested subject: "fix: pinning needs CanManageContext or a host PinPolicy, and the message must be in the channel". The body has two short paragraphs, WR-02 and the additive contract. Add no attribution trailer of any kind: the user's global CLAUDE.md overrides any harness attribution reminder. Do not push or tag. Record the commit SHA for Task 3.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-chatchannels-plugin && test -z "$(gofmt -l .)" && go vet ./... && go test -short -count=1 ./... && go test -count=1 ./... && go test -count=1 -run '^TestPinPolicy$' -v . 2>&1 | grep -qF -- '--- PASS: TestPinPolicy' && go test -short -count=1 -run '^TestDenyAllHasNoPinPolicy$|^TestPHPMethodMap$' -v . 2>&1 | grep -qF -- '--- PASS: TestDenyAllHasNoPinPolicy' && grep -qF 'contracts.PinPolicy' README.md && grep -qF 'CanPinInChannel' README.md && awk -F'|' '$3 ~ /TestPinPolicy/ && $4 ~ /ported/ {n++} END {exit (n < 6)}' testdata/PHP_METHOD_MAP.md && S=$(git status --short) && test -z "$S" && test "$(git rev-parse --abbrev-ref HEAD)" = main && git diff --quiet 017843a main -- go.mod go.sum && M=$(git log -1 --format=%B main) && ! grep -qi 'co-authored-by' <<<"$M" && T=$(git tag --points-at main) && test -z "$T" && R=$(git branch -r --contains main) && test -z "$R"</automated>
</verify>
<done>sm-chatchannels-plugin main has one new commit with the contract, the gate, the message check, the handler docs, pins_test.go, the PHP map re-pointing and the README. TestPinPolicy passes against Postgres (not skipped) and TestDenyAllHasNoPinPolicy passes under -short. go vet, go test -short and the full go test are green. go.mod and go.sum are unchanged. The commit has no trailer, no tag and no remote branch. The SHA is recorded.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: sm-demo-app: demo moderators answer the pin policy (compatible with the current v0.1.0 pointer)</name>
<files>../sm-demo-app/plugins/demo/classes/chat_context.go, ../sm-demo-app/plugins/demo/classes/chat_context_test.go, ../sm-demo-app/plugins/demo/chat.go, ../sm-demo-app/reset_test.go, ../sm-demo-app/README.md</files>
<precondition>The sm-demo-app submodule plugins/golem15/chatchannels is still at 017843a (v0.1.0), and sm-demo-app has no uncommitted edits in the five files above.</precondition>
<behavior>
- NewChatAccess(db, moderatorGroup, isMember) keeps CanAccessContext as before (demo/1 members only), and CanManageContext stays false for everyone, moderators included.
- CanPin is false for: user 0, a non-member, any context other than demo/1, a nil db func, a nil database, a membership error, a nil moderatorGroup func, and an empty group code. The unit test never lets a community member reach IsModerator with a non-empty group, because someDB() is an empty handle.
- The walker in addChatActivity is made a moderator before the pin step, so TestResetKeepsPlans passes both before and after the pointer bump.
</behavior>
<action>
Work in /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app. Keep this commit compiling against the current submodule (v0.1.0, which has no contracts.PinPolicy). Therefore do NOT reference chancontracts.PinPolicy in this task. ChatAccess satisfies it structurally, and Task 3 adds the compile-time assertion after the bump.
1. plugins/demo/classes/chat_context.go:
- Give ChatAccess a `moderatorGroup func() string` field. Change the constructor to `NewChatAccess(db func() *gorm.DB, moderatorGroup func() string, isMember MemberFunc)`, mirroring NewForumAccess. db and moderatorGroup are resolved per check, so a config change needs no re-install.
- Factor the existing demo/1 membership check into a `member` helper like ForumAccess.member, and keep CanAccessContext's behaviour identical.
- Add `CanPin(ctx context.Context, userID uint, contextType string, contextID, channelID uint) bool`. It is true only for a community member (via the member helper) when moderatorGroup is non-nil and `IsModerator(ctx, db, userID, moderatorGroup())` returns true with no error. channelID is unused, because every demo channel lives in demo/1 and chatchannels has already resolved the channel in that context. Say so in the doc comment.
- CanManageContext stays always false, with its comment unchanged in meaning (D-07: channels come from demo:seed only).
- Update the ChatAccess type comment: members access demo/1; nobody manages it; members of the moderator group pin and unpin channel messages (golem15.chatchannels' optional PinPolicy, review WR-02).
2. plugins/demo/chat.go:68: install `classes.NewChatAccess(p.db, p.chatModeratorGroup, nil)`. Extend the chatModeratorGroup doc comment ("moderate the channels and the forum") to mention pins.
3. plugins/demo/classes/chat_context_test.go: update the four NewChatAccess calls in TestDemoChatAccess to the new signature, passing a group func returning "" for the table cases. Extend the test to assert CanPin is false in each case listed in the behavior block. Use groups "" and "g" only where the membership func denies, errors or is never reached (wrong context, user 0, nil db). Also cover a nil moderatorGroup func with a member (must be false without a query). Update the test's doc comment to mention pins. The positive moderator case needs a real database and lives in Task 3's TestDemoPinPolicy.
4. reset_test.go addChatActivity: right before the "pin" step, call makeModerator(t, a, userID). Add a one-line comment that pinning in the demo channels is a moderator action (chatchannels PinPolicy). Leave every other step as it is.
5. README.md "Moderation." paragraph: the moderator group now also pins and unpins channel messages; other members only read the pins. Keep the paragraph's style. No new config key is added.
6. Run gofmt, go vet ./..., go test -short ./..., and the Docker-backed TestResetKeepsPlans, TestDemoModeratorDelete and TestDemoChannelsSeededOnly. They pass on v0.1.0, where any member may still pin. Commit only these five paths, staged explicitly. Suggested subject: "feat: demo moderators answer chatchannels' pin policy". No trailer, no push.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app && test "$(git -C plugins/golem15/chatchannels rev-parse HEAD)" = 017843a6d8191d743a910ea20b4899f894aad837 && test -z "$(gofmt -l plugins/demo reset_test.go)" && go vet ./... && go test -short -count=1 ./... && go test -short -count=1 -run '^TestDemoChatAccess$' -v ./plugins/demo/classes 2>&1 | grep -qF -- '--- PASS: TestDemoChatAccess' && go test -count=1 -run '^TestResetKeepsPlans$|^TestDemoModeratorDelete$|^TestDemoChannelsSeededOnly$' . && git diff --quiet HEAD -- plugins/demo reset_test.go README.md && C=$(git rev-parse HEAD) && N=$(git diff --name-only "$C^" "$C") && test "$(sort <<<"$N" | tr '\n' ' ')" = "README.md plugins/demo/chat.go plugins/demo/classes/chat_context.go plugins/demo/classes/chat_context_test.go reset_test.go " && M=$(git log -1 --format=%B) && ! grep -qi 'co-authored-by' <<<"$M" && grep -qF 'NewChatAccess(p.db, p.chatModeratorGroup, nil)' plugins/demo/chat.go</automated>
</verify>
<done>sm-demo-app master has one new commit touching exactly the five files. ChatAccess.CanPin answers from the moderator group, CanManageContext is still false, and NewChatAccess takes the moderator group func. The walker is a moderator before pinning in the reset test. go vet, go test -short and the three Docker tests pass against the unchanged v0.1.0 submodule. No trailer, not pushed.</done>
</task>
<task type="auto" tdd="true">
<name>Task 3: sm-demo-app: bump the chatchannels submodule (own commit), then prove the moderator-only pin rule end to end</name>
<files>../sm-demo-app/plugins/golem15/chatchannels, ../sm-demo-app/plugins/demo/classes/chat_context.go, ../sm-demo-app/chat_test.go</files>
<precondition>Task 1's commit is on /media/nvme/dev/golem15/summercms.io/summercms/sm-chatchannels-plugin main (contracts/pin_policy.go exists there), and Task 2's commit is on sm-demo-app master.</precondition>
<behavior>
- With the submodule at the Task 1 commit, TestResetKeepsPlans, TestDemoModeratorDelete, TestDemoChannelsSeededOnly, TestDemoChatTracer and TestSeedChatSmoke stay green.
- TestDemoPinPolicy (Docker): a plain member's POST pin in #general is 404 and writes no row. A plain member's DELETE of the seeded #general pin is 404 and the row survives. A plain member's GET pins is 200.
- A demo-moderators member's POST pin of a #general message is 200 with pinned_by = moderator. Their POST of an #announcements message or of a DM message through #general's pins path is 404 with no row. Their DELETE of their own pin and of the seeded welcome pin is 200 and both rows are gone.
</behavior>
<action>
Work in /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app.
1. Pointer bump, as its own commit:
- Fetch the plugin commit from the local sibling clone, not from origin, since nothing is pushed: `git -C plugins/golem15/chatchannels fetch /media/nvme/dev/golem15/summercms.io/summercms/sm-chatchannels-plugin main`, then `git -C plugins/golem15/chatchannels checkout -q --detach FETCH_HEAD`.
- Check that the submodule HEAD equals `git -C /media/nvme/dev/golem15/summercms.io/summercms/sm-chatchannels-plugin rev-parse main`.
- Leave go.mod (still v0.1.0) and go.sum unchanged; tagging v0.1.1 and requiring it is the user's release step.
- Run go vet ./..., go test -short ./..., and the Docker-backed TestResetKeepsPlans, TestDemoModeratorDelete, TestDemoChannelsSeededOnly, TestDemoChatTracer and TestSeedChatSmoke. Task 2 makes these pass with the stricter plugin.
- Stage only the gitlink (`git add plugins/golem15/chatchannels`) and commit. Suggested subject: "chore: bump chatchannels to <short sha> (pin policy, untagged)". The body notes that check-pins.sh reports chatchannels until sm-chatchannels-plugin is tagged and go.mod requires the tag. No trailer.
2. End-to-end proof, as a second commit:
- In plugins/demo/classes/chat_context.go, add `_ chancontracts.PinPolicy = (*ChatAccess)(nil)` to the interface assertions var block. This guards against signature drift: a mismatched CanPin would otherwise silently fail closed.
- In chat_test.go, add `TestDemoPinPolicy` next to TestDemoModeratorDelete, with a doc comment naming WR-02.
- Setup: bootAPI(t, nil, nil); a plain member and a moderator via a.member, with makeModerator for the moderator. Both open #general with a.openChannel. The moderator opens #announcements. Take the channel ids from a.bootstrapChat(...).Channels by slug.
- Messages: the plain member posts a #general message. The moderator posts an #announcements message. The plain member opens a DM with the moderator and posts in it.
- Read the seeded #general pin's message_id with scalar from golem15_chatchannels_channel_pins.
- Assert every behavior bullet through a.call on /_chatchannels/api/v1/contexts/demo/1/channels/{generalID}/pins and .../pins/{messageID}, checking rows with scalar counts.
- Run gofmt, go vet ./..., go test -short ./..., TestDemoPinPolicy -v (must PASS, not SKIP) and the five Docker tests above. Commit chat_test.go and chat_context.go only. Suggested subject: "test: pinning in the demo channels is a moderator action". No trailer.
3. Do not run scripts/build.sh or scripts/check-pins.sh as gates: check-pins.sh is expected to flag the untagged chatchannels pointer. Do not push, tag or deploy.
4. Record these follow-ups in the SUMMARY for the user (do not act on them):
- Release: tag sm-chatchannels-plugin (v0.1.1) on main and push it, then bump sm-demo-app go.mod to that tag; check-pins then passes again. The release also needs a changelog post at /changelog/plugins.
- sm-bm-app vendors chatchannels too, and its ChatAccess.CanManageContext is false. When it bumps past this commit its members stop pinning unless it implements CanPin.
- vue-chat-layer could hide the pin action up front from the bootstrap's `moderator` flag; today it hides the action after the first refusal.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app && P=$(git -C /media/nvme/dev/golem15/summercms.io/summercms/sm-chatchannels-plugin rev-parse main) && test "$(git -C plugins/golem15/chatchannels rev-parse HEAD)" = "$P" && L=$(git ls-tree HEAD plugins/golem15/chatchannels) && test "$(awk '{print $3}' <<<"$L")" = "$P" && test -z "$(gofmt -l chat_test.go plugins/demo)" && go vet ./... && go test -short -count=1 ./... && go test -count=1 -run '^TestDemoPinPolicy$' -v . 2>&1 | grep -qF -- '--- PASS: TestDemoPinPolicy' && go test -count=1 -run '^TestResetKeepsPlans$|^TestDemoModeratorDelete$|^TestDemoChannelsSeededOnly$|^TestDemoChatTracer$|^TestSeedChatSmoke$' . && grep -qF 'chancontracts.PinPolicy' plugins/demo/classes/chat_context.go && git diff --quiet HEAD -- go.mod go.sum chat_test.go plugins/demo plugins/golem15/chatchannels && B=$(git log -1 --format=%H -- plugins/golem15/chatchannels) && test "$(git diff --name-only "$B^" "$B")" = "plugins/golem15/chatchannels" && git diff --quiet "$B^" HEAD -- go.mod go.sum && N=$(git diff --name-only HEAD^ HEAD) && test "$(sort <<<"$N" | tr '\n' ' ')" = "chat_test.go plugins/demo/classes/chat_context.go " && M=$(git log -2 --format=%B) && ! grep -qi 'co-authored-by' <<<"$M"</automated>
</verify>
<done>The sm-demo-app gitlink for plugins/golem15/chatchannels points at the Task 1 commit, in a commit that changes nothing else. A following commit adds the PinPolicy compile-time assertion and TestDemoPinPolicy, which passes against Postgres. The reset, moderator-delete, seeded-only, chat-tracer and seed-smoke tests stay green, and go.mod/go.sum are unchanged. No trailers, nothing pushed or tagged. The SUMMARY lists the three follow-ups (tag plus go.mod bump plus changelog, sm-bm-app impact, optional up-front hiding in the frontend).</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| browser -> /_chatchannels/api/v1 pins routes | An authenticated (jwt.auth) frontend user sends an untrusted channelId, messageId and body message_id |
| chatchannels -> host resolver (AccessResolver / PinPolicy) | The plugin trusts the host's answers; the host decides who manages and who pins |
| demo -> user groups (users_groups / user_groups) | The moderator role is read from the configured group code on every check |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-oc6-01 | Elevation of privilege | ChannelService.PinMessage / UnpinMessage (WR-02) | high | mitigate | requirePin: channel access, then CanManageContext or PinPolicy.CanPin, else ErrForbidden (404). TestPinPolicy and TestDemoPinPolicy prove a plain member can neither pin nor unpin a seeded pin |
| T-oc6-02 | Tampering | PinMessage message_id (cross-conversation pin) | medium | mitigate | requireMessageInChannel counts live golem15_chat_messages rows with conversation_id = channel.conversation_id. Foreign (other channel, DM), unknown and soft-deleted ids are ErrNotFound with no row (tests in both repos) |
| T-oc6-03 | Information disclosure | pins routes error responses | low | mitigate | Forbidden, not-found and foreign-message all answer the same 404 `{"error":"Not found"}` through the unchanged writeChannelError, so the routes are no oracle for message ids in other conversations |
| T-oc6-04 | Elevation of privilege | PinPolicy granting a non-member (host bug) | medium | mitigate | requireChannelAccess runs before PinPolicy and its error is returned unchanged. TestPinPolicy asserts the stranger gets ErrForbiddenAccess and CanPin is never called for them |
| T-oc6-05 | Denial of service | pins panel flooding | low | mitigate | Only managers or policy-approved users pin (T-oc6-01). The existing chatchannels-api bucket (120/min) still applies |
| T-oc6-06 | Elevation of privilege | demo ChatAccess.CanPin / CanManageContext | medium | mitigate | CanPin requires community membership plus the moderator group, and fails closed on an empty group, nil func, nil db or any error. CanManageContext stays false, so moderators still cannot create channels (TestDemoChannelsSeededOnly) |
| T-oc6-07 | Spoofing / Repudiation | pin attribution | low | accept | pinned_by keeps the first pinner (idempotent FirstOrCreate, PHP D-57-02). An unpin is not attributed, the same as before; only moderators can unpin now |
| T-oc6-SC | Tampering | Go module installs | low | accept | No dependency is added. go.mod and go.sum are unchanged in both repos (Task 1 and Task 3 verify). The submodule moves to a local commit fetched from the sibling clone, not from a remote |
</threat_model>
<verification>
- Plugin: gofmt clean; go vet ./...; go test -short ./...; full go test ./... with Docker; TestPinPolicy PASS (not SKIP); TestPHPMethodMap green with the six pin rows on TestPinPolicy.
- Demo: go vet ./...; go test -short ./...; Docker tests TestDemoPinPolicy, TestResetKeepsPlans, TestDemoModeratorDelete, TestDemoChannelsSeededOnly, TestDemoChatTracer and TestSeedChatSmoke green with the submodule at the plugin commit.
- Git: one plugin commit on main; three demo commits in the order host policy, then pointer bump alone, then e2e test; no trailers, no tags, no pushes; go.mod/go.sum untouched in both repos.
</verification>
<success_criteria>
- A channel member who is neither a manager nor approved by the host's PinPolicy cannot pin or unpin. The server enforces it and answers 404.
- A pin always references a live message of the channel's own conversation.
- Existing chatchannels hosts compile without change. The new rule is documented in the plugin README together with the way to restore the old behaviour.
- In the demo, only members of the configured moderator group pin and unpin. Every other member still reads the pins, and channel creation stays closed.
</success_criteria>
<output>
Create `.planning/quick/261105-oc6-chatchannels-pin-policy/261105-oc6-SUMMARY.md` in summercms.go when done. Include:
- the plugin commit SHA and base;
- the three demo commit SHAs;
- the test results, including that TestPinPolicy and TestDemoPinPolicy ran against Postgres;
- confirmation that nothing was pushed or tagged and that go.mod/go.sum are unchanged;
- the three follow-ups from Task 3 step 4.
Do not stage or commit anything in summercms.go; the batch coordinator commits the planning docs (SUMMARY, todo move, STATE).
</output>

View File

@@ -0,0 +1,126 @@
---
phase: quick-261105-oc6
plan: 01
subsystem: sm-chatchannels-plugin, sm-demo-app
tags: [chatchannels, pins, security, WR-02, demo]
status: complete
requires: []
provides:
- contracts.PinPolicy (optional CanPin host hook) in sm-chatchannels-plugin
- ChannelService.CanPinInChannel
- demo ChatAccess.CanPin answering from the moderator group
affects: [sm-bm-app (when it bumps chatchannels), vue-chat-layer (optional up-front pin hiding)]
tech-stack:
added: []
patterns: [optional host interface discovered by type assertion, like sm-chat-plugin contracts.MessageModerator]
key-files:
created:
- ../sm-chatchannels-plugin/contracts/pin_policy.go
- ../sm-chatchannels-plugin/pins_test.go
modified:
- ../sm-chatchannels-plugin/contracts/access_resolver.go
- ../sm-chatchannels-plugin/classes/channel_service.go
- ../sm-chatchannels-plugin/api/pins.go
- ../sm-chatchannels-plugin/testdata/PHP_METHOD_MAP.md
- ../sm-chatchannels-plugin/README.md
- ../sm-demo-app/plugins/demo/classes/chat_context.go
- ../sm-demo-app/plugins/demo/classes/chat_context_test.go
- ../sm-demo-app/plugins/demo/chat.go
- ../sm-demo-app/reset_test.go
- ../sm-demo-app/README.md
- ../sm-demo-app/plugins/golem15/chatchannels (gitlink)
- ../sm-demo-app/chat_test.go
decisions:
- Pinning in chatchannels is manage-only unless the host resolver also implements contracts.PinPolicy (user-confirmed; sm-bm-app behaviour change accepted as a follow-up).
- The sm-demo-app pointer bump is committed untagged; check-pins.sh flags it until the plugin is tagged.
completed: 2026-11-05
actuals:
tasks: 3
commits: 4
tokens: 9000
---
# Quick 261105-oc6: chatchannels pin policy Summary
Pinning and unpinning in chatchannels now need `CanManageContext` or an optional host `contracts.PinPolicy`, and a pinned message must be a live message of the channel's conversation. In the demo, only `demo-moderators` members pin and unpin. Every other member can still read the pins.
## Commits
Commits are in sibling repos, so the summercms.go ledger (`commits:` measured against summercms.go HEAD) does not apply. The hashes below are measured in each repo.
**sm-chatchannels-plugin** (`main`, base `017843a` = v0.1.0; main had not moved past it)
- `a042536` fix: pinning needs CanManageContext or a host PinPolicy, and the message must be in the channel
**sm-demo-app** (`master`, base `7b75d2c`, in this order)
- `ce800f2` feat: demo moderators answer chatchannels' pin policy (5 files)
- `7e4b9d3` chore: bump chatchannels to a042536 (pin policy, untagged) (gitlink only)
- `11d3afc` test: pinning in the demo channels is a moderator action (chat_test.go and chat_context.go)
No commit has an attribution trailer. Nothing was pushed or tagged: `git branch -r --contains` and `git tag --points-at` are empty in both repos. go.mod and go.sum are unchanged in both repos (`017843a..main` in the plugin, `7b75d2c..HEAD` in the demo).
## What changed
- **Plugin**
- `contracts.PinPolicy` adds `CanPin(ctx, userID, contextType, contextID, channelID)`. It is optional and found by type assertion on the installed resolver.
- `ChannelService.requirePin` checks channel access first and returns its error unchanged, so `CanPin` is never asked for a user without access. It then requires `CanManageContext` or `CanPin`, else `ErrForbidden` (404).
- `requireMessageInChannel` counts live `golem15_chat_messages` rows in the channel's conversation (soft-deleted rows excluded). An unknown, deleted or foreign message, or a channel with no conversation, gets `ErrNotFound`.
- Unpinning does not check the message, so a stale pin stays removable.
- New exported nil-safe `CanPinInChannel`. The `AccessResolver` interface and every existing signature are unchanged.
- Handler docs updated, the PHP map's six pin rows now point at `TestPinPolicy`, and the README has the rule, a Usage example, API reference rows and Testing lines.
- **Demo**
- `NewChatAccess(db, moderatorGroup, isMember)` mirrors `NewForumAccess`, with a shared `member` helper.
- `CanPin` is true only for a community member in the moderator group, and fails closed on any error, empty group, nil func or nil db. `CanManageContext` stays false (D-07).
- `chat.go` installs the resolver with `p.chatModeratorGroup`.
- The reset test's walker is made a moderator before it pins.
- The README "Moderation." paragraph is updated.
- After the pointer bump, a compile-time `chancontracts.PinPolicy` assertion was added.
## Test results
- **Plugin**
- `go vet ./...` passes.
- `go test -short -count=1 ./...` passes.
- The full Docker-backed `go test -count=1 ./...` passes (~19 s).
- `TestPinPolicy` passed against Postgres, not skipped (1.45 s). `TestDenyAllHasNoPinPolicy` and `TestPHPMethodMap` pass.
- Mutation check: with the message-in-channel check disabled, `TestPinPolicy` fails ("pin unknown message: <nil>, want ErrNotFound"). The code was restored before committing.
- **Demo, Task 2** (submodule still at v0.1.0)
- `go vet ./...` and `go test -short ./...` pass, and `TestDemoChatAccess` passes.
- Docker tests `TestResetKeepsPlans`, `TestDemoModeratorDelete` and `TestDemoChannelsSeededOnly` pass.
- **Demo, Task 3** (submodule at a042536)
- `go vet ./...` and `go test -short ./...` pass.
- `TestDemoPinPolicy` passed against Postgres (2.74 s).
- `TestResetKeepsPlans`, `TestDemoModeratorDelete`, `TestDemoChannelsSeededOnly`, `TestDemoChatTracer` and `TestSeedChatSmoke` pass.
- The full Docker-backed `go test -count=1 ./...` passes (~57 s).
## Deviations from Plan
**1. [Scope note] The plan's Task 1 verify gate `test -z "$(gofmt -l .)"` fails in the plugin because of a formatting issue that was already there.**
- `fixture_plugin_test.go` (lines 86-89) has mis-aligned one-line method bodies at base `017843a`. This plan did not touch the file.
- The changed and new files are all gofmt-clean. I left the existing issue alone because it is out of scope, and the plan stages exactly seven paths.
- Fixing it is a one-line `gofmt -w fixture_plugin_test.go` in a later plugin commit.
**2. [Test design] TestPinPolicy proves "first pinner wins" by briefly making `pinner` a manager for the second pin.**
- The first pinner is the manager. Then the base resolver is restored.
- The plan text did not fix who makes the second pin. Every other behaviour bullet is covered as written.
Otherwise the plan was executed as written.
## Follow-ups for the user (not acted on)
1. **Release:**
- Tag sm-chatchannels-plugin `v0.1.1` on `main` (a042536) and push it.
- Bump sm-demo-app `go.mod` to require that tag. `scripts/check-pins.sh` reports chatchannels until then.
- Publish a changelog post at /changelog/plugins (`scripts/changelog-post.py publish v0.1.1 notes.md --excerpt "…" --repo ../sm-chatchannels-plugin`).
- Push the three sm-demo-app commits after that.
2. **sm-bm-app** also vendors chatchannels, and its `ChatAccess.CanManageContext` is false. When it bumps past a042536, its members stop pinning unless it implements `CanPin`. To keep the old behaviour, answer `CanPin` with its own `CanAccessContext`.
3. **vue-chat-layer** could hide the pin action up front from the bootstrap's `moderator` flag. Today `togglePin` hides it only after the first 4xx refusal.
## Threat Flags
None: the change narrows existing surface and adds no endpoint.
## Self-Check: PASSED
- Files exist: `sm-chatchannels-plugin/contracts/pin_policy.go`, `sm-chatchannels-plugin/pins_test.go`, `sm-demo-app/chat_test.go` (TestDemoPinPolicy).
- Commits exist: plugin `a042536`; demo `ce800f2`, `7e4b9d3`, `11d3afc`.
- The demo gitlink at HEAD equals the plugin `main` (a0425366487b1c8e8a9566a74fe6b35613f529da).

View File

@@ -0,0 +1,440 @@
---
phase: quick-261105-oc7
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- ../sm-chatvideo-plugin/classes/video_service.go
- ../sm-chatvideo-plugin/classes/authorizer.go
- ../sm-chatvideo-plugin/classes/livekit.go
- ../sm-chatvideo-plugin/classes/revoked_access.go
- ../sm-chatvideo-plugin/boot.go
- ../sm-chatvideo-plugin/live_membership_test.go
- ../sm-chatvideo-plugin/contracts/call_policy.go
- ../sm-chatvideo-plugin/contracts/call_policy_test.go
- ../sm-chatvideo-plugin/api/errors.go
- ../sm-chatvideo-plugin/lang/en/lang.yaml
- ../sm-chatvideo-plugin/lang/pl/lang.yaml
- ../sm-chatvideo-plugin/call_policy_test.go
- ../sm-chatvideo-plugin/README.md
- ../sm-chatvideo-plugin/plugin.yaml
- ../sm-demo-app/plugins/golem15/chatvideo
- ../sm-demo-app/plugins/demo/video.go
- ../sm-demo-app/plugins/demo/plugin.go
- ../sm-demo-app/video_test.go
- ../sm-demo-app/config/golem15.chatvideo.yaml
- ../sm-demo-app/README.md
- ../vue-chatvideo-layer/app/composables/useIncomingCalls.ts
- ../vue-chatvideo-layer/vitest.config.ts
- ../vue-chatvideo-layer/tests/useIncomingCalls.test.ts
- ../vue-chatvideo-layer/README.md
autonomous: true
requirements:
- todo:chatvideo-live-membership
- todo:chatvideo-dm-only-host-hook
- todo:chatvideo-incoming-handle-leak
must_haves:
truths:
- "With a host chat context that implements golem15.chat's contracts.LiveMembership (RequireLiveMembership true), a conversation participant whose HasMember answers false gets 404 from POST /_chatvideo/api/v1/conversations/{id}/video/join, /leave, /end, GET /video/status and GET /call-links/{code}, and the registered video authorizer denies them video:session:{id}. When HasMember answers true again, access comes back. Start neither invites nor rings such a member: no participant row, and they are not in the Incoming recipient list"
- "A context that does not implement LiveMembership (or answers false) and a conversation with no context keep the participant-row behaviour unchanged. The existing tests (TestHTTPTracer, TestVideoAuthorizer, TestReconcileEmptyRoom, TestUserDeletionReassignsSession, TestGoldenEvents) pass without edits to their assertions"
- "A ban (golem15.user AccessRevokedEvent with Reason userclasses.AccessRevokedBan) or a deactivation (DeactivatingEvent) marks the user's joined participant rows of live sessions left, with left_at set, inside the event's transaction. Only after the commit does it remove the user's LiveKit identity from every live room where they were joined or had left, and publish participant-left for the rows that were joined. The call goes on for everyone else. A rolled-back ban changes nothing. AccessRevokedEvent with any other reason (password reset or change) leaves calls alone"
- "VideoService.SetCallPolicy installs an optional contracts.CallPolicy. With no policy installed, every member may start a call, as before. With contracts.DMOnly installed, POST .../video/start in a group conversation answers 403 {\"error\":\"Video calls are not available in this conversation\"}, and it creates no session, room or participant row and rings nobody. A DM start is unchanged. A policy error answers 500 and creates nothing. Joining a call that is already running (POST .../video/join) is never checked against the policy. A non-participant still gets 404, and the policy is not consulted for them"
- "sm-demo-app installs contracts.DMOnly at boot. TestDemoVideoStart asserts that a channel start is refused with 403 whether or not the channel fits max_participants: the rule no longer depends on seed data. DM calls behave as before, and the config comment and README say the server enforces the rule"
- "useIncomingCalls never keeps more than one session handle. A subscribe that resolves after a newer ring, a dismiss, accept, decline or the ring timeout has its handle closed at once. Only the latest ring's handle is kept, and clear() closes it. The new test fails on the code before the fix"
- "Additive: no exported sm-chatvideo-plugin identifier is removed or changes its signature (AuthorizeVideo, AuthorizeVideoCheck, AuthorizeVideoLookup, NewVideoService, VideoOptions, VideoService methods). No go.mod changes in any repo. No framework (summercms.go) code changes. Nothing is pushed or tagged. No commit has a co-author trailer"
artifacts:
- path: ../sm-chatvideo-plugin/classes/video_service.go
provides: "MembershipCheck type, VideoOptions.Membership and VideoOptions.CallPolicy, SetMembership, SetCallPolicy, ErrCallNotAllowed; requireParticipant goes through the membership check; Start filters invitees and applies the policy"
- path: ../sm-chatvideo-plugin/classes/authorizer.go
provides: "AuthorizeVideoMembership(getDB, member); AuthorizeVideoLookup delegates with a nil check"
- path: ../sm-chatvideo-plugin/classes/revoked_access.go
provides: "VideoService.RemoveFromCalls(ctx, tx, userIDs) with after-commit LiveKit removal"
- path: ../sm-chatvideo-plugin/contracts/call_policy.go
provides: "contracts.CallPolicy, contracts.CallPolicyFunc, contracts.DMOnly"
- path: ../sm-demo-app/plugins/demo/video.go
provides: "registerVideo installs contracts.DMOnly on the published *classes.VideoService"
- path: ../vue-chatvideo-layer/app/composables/useIncomingCalls.ts
provides: "a sequence number per watchSession, bumped by clear(); stale handles are closed"
key_links:
- from: "../sm-chatvideo-plugin/boot.go chatMembership(app)"
to: "golem15.chat classes.Service.IsParticipant (participant row + contracts.LiveMembership)"
via: "classes.MembershipCheck, used by bootService (VideoOptions.Membership) and bootRealtime (AuthorizeVideoMembership)"
- from: "../sm-chatvideo-plugin/boot.go bootListeners"
to: "classes.VideoService.RemoveFromCalls -> lagoon.AfterCommit -> RoomAPI.RemoveParticipant"
via: "app.Events.Listen for *userclasses.AccessRevokedEvent (reason ban) and *userclasses.DeactivatingEvent"
- from: "../sm-demo-app/plugins/demo/video.go"
to: "classes.VideoService.SetCallPolicy(contracts.DMOnly)"
via: "lagoon.OnDatabase after chatvideo publishes its service"
- from: "../sm-chatvideo-plugin/api/errors.go ErrCallNotAllowed -> 403"
to: "vue-chatvideo-layer callMachine failureReason(403) = 'forbidden'"
via: "existing frontend mapping; no layer change needed for the refusal"
---
<objective>
Close the three chatvideo todos from the phase 20 code review in three sibling repos, with additive changes only: IN-02 (`chatvideo-live-membership`), IN-01 (`chatvideo-dm-only-host-hook`) and IN-07 (`chatvideo-incoming-handle-leak`).
1. **Live membership and bans (sm-chatvideo-plugin).** chatvideo checks participant rows only. Change `requireParticipant` and the video authorizer to go through golem15.chat's `Service.IsParticipant`, which also asks the host context about current membership when the context implements `contracts.LiveMembership`. When a user is banned (or deactivated), chatvideo removes them from every live LiveKit room after the transaction commits.
2. **DM-only host hook (sm-chatvideo-plugin, then sm-demo-app).** Add an optional `contracts.CallPolicy` with `CanStartCall`, a ready-made `contracts.DMOnly` policy and `VideoService.SetCallPolicy`. The demo installs `DMOnly`, so the server refuses channel calls whatever the seeded participant count is.
3. **Stale handles (vue-chatvideo-layer).** `useIncomingCalls` keeps a sequence number per `watchSession` and closes every handle that is not the latest.
Live reads at planning time (all four repos clean; sm-chatvideo-plugin on `main` at 0f08c35 = v0.1.1, vue-chatvideo-layer on `main` at 2313a4e = v0.1.1, sm-demo-app on `master` at da03c06):
- `classes/video_service.go`: `requireParticipant` (lines 425-443) loads the conversation (missing: ErrNotFound) and then counts `golem15_chat_participants` rows (none: ErrNotParticipant). Start, Status, CallLink and `sessionForActor` (and through it Join, Leave and End) all call it. `Start` (84-168) plucks every participant's user_id into memberIDs, refuses with ErrTooMany when `len(memberIDs) > max_participants`, and passes memberIDs to `invite` and to `notify.Incoming`. `Leave` (207-228) shows the left pattern: Updates status `models.ParticipantLeft` and `left_at`, then calls `rooms.RemoveParticipant(ctx, room, strconvUint(actorID))`, then `notify.ParticipantLeft`.
- `classes/authorizer.go`: `AuthorizeVideoLookup(getDB)` (54-79) loads the session and counts participant rows of `session.ConversationID`. `bootRealtime` registers it under the namespace "video".
- `classes/user_deletion.go` is the pattern for work that has to wait for the commit: `q()` builds sessions on tx with `Session(&gorm.Session{NewDB: true})`; then `lagoon.AfterCommit(ctx, q(), fn)`, `context.WithoutCancel`, `roomCallTimeout` (10 s), and a `pluginLog.Warn` unless the error is ErrNotConfigured. A nil tx falls back to the service DB.
- golem15.chat: `(*classes.Service).IsParticipant(ctx, conversationID, userID) (bool, error)` exists in the required v0.1.3 and in the workspace checkout (`../sm-chat-plugin`, v0.1.5). It answers whether a participant row exists and, if the conversation's context implements `contracts.LiveMembership` and `RequireLiveMembership()` is true, whether `HasMember` holds. Chat publishes `*classes.Service` from its own `lagoon.OnDatabase` hook. Chat boots first (chatvideo `Requires()` golem15.chat), and OnDatabase hooks run in FIFO order.
- golem15.user: `AccessRevokedEvent{UserIDs []uint, Before time.Time, Reason string, Tx *gorm.DB}`, the `AccessRevokedBan` reason constant and `DeactivatingEvent{User *models.User, Tx *gorm.DB}` exist in the required v0.1.13 and in the workspace user plugin (fonoteka.go/plugins/golem15/user, v0.1.14). The admin ban action fires AccessRevokedEvent (reason "ban") inside its transaction (users_admin_controller.go:678). sm-mfa-plugin and sm-oauthserver-plugin already listen to it. No go.mod change is needed anywhere.
- lighthouse has no server-side unsubscribe or disconnect API. A Centrifugo subscription token expires (realtime.centrifugo.token_ttl, default 3600 s). Refreshing it needs the user's JWT (revoked by a ban) and runs the authorizer again.
- The production `sdkRooms.RemoveParticipant` already swallows a missing room or participant (`isMissingRoom`). `FakeRooms` has no way to put a named identity in a room: `SetCount` creates identities "0".."n-1".
- The HTTP error mapping (`api/errors.go` writeVideoError) has no 403 today. vue-chatvideo-layer `failureReason` maps 403 to the reason key 'forbidden' ("You can't join this call.") and 422 to 'tooMany'. A policy refusal must therefore be a 403 to read correctly in the existing UI.
- `TestFixtureAbsentFromProduction` fails when a production file (.go, .yaml or .md, including README.md) contains `acme.teams`, `teamsPlugin`, or any of the words queststream, family, parent, child, wavepath or fonoteka. Do not use those words in production comments or the README.
- sm-demo-app: `plugins/golem15/chatvideo` is a submodule detached at v0.1.1 (0f08c35), and `go.mod` requires sm-chatvideo-plugin v0.1.1. `go.work` uses the submodule checkout, so dev builds and `go test` compile the submodule. `scripts/check-pins.sh` and the release build (`scripts/build.sh`, GOWORK=off) use the go.mod version. `TestDemoVideoStart` (video_test.go:97) pins "no type rule on the server": a channel start is refused with 422 only because of `max_participants: 4`, and is accepted (201) after the channel is trimmed to 2 participants. The demo plugin installs other plugins' host policies from `lagoon.OnDatabase` hooks (chat.go registerChat/registerForum); Boot runs a list of steps in plugin.go.
- vue-chatvideo-layer `useIncomingCalls.ts` (88 lines): `IncomingRuntime {registered, channel, timer}` sits on `nuxtApp._chatvideoIncoming`. `watchSession` closes `rt.channel`, awaits `subscribe(videoSessionChannel(id), {onPublication})`, and keeps the handle when `pending.value?.sessionId === call.sessionId`. Two rings for the same session both pass that check, so the earlier handle leaks. Registration is guarded by `import.meta.client`, which is undefined under vitest. A scratchpad check confirmed that vitest 3.2.7 replaces it with `define: { 'import.meta.client': 'true' }`. The layer has no vitest config. Baseline: `pnpm test` gives 127 tests green; chatvideo `go vet` and `go test -short ./...` are green.
Commits (four, in this order, each staged by explicit path, with no co-author trailer and nothing pushed or tagged):
1. sm-chatvideo-plugin: `fix: honour chat live membership and remove banned users from live calls` (Task 1)
2. sm-chatvideo-plugin: `feat: optional CallPolicy host hook and a DM-only policy` (Task 2, first part)
3. sm-demo-app: `feat: video calls in DMs only, enforced on the server by chatvideo's CallPolicy` (Task 2, second part: submodule pointer bump and wiring in one commit, so the demo compiles at every commit)
4. vue-chatvideo-layer: `fix: the incoming-call runtime closes stale session handles` (Task 3)
Release state after this plan (put this in the SUMMARY): the demo's `plugins/golem15/chatvideo` pointer is ahead of its go.mod pin (still v0.1.1). Dev builds and tests compile through go.work, but `scripts/check-pins.sh` reports the mismatch and the GOWORK=off release build does not compile until the user tags sm-chatvideo-plugin (next v0.1.x), pushes it before the demo, and commits `chore: require sm-chatvideo-plugin vX` (go.mod and go.sum). The same goes for a vue-chatvideo-layer tag and a vue-demo-app bump. The executor does none of these.
Not in scope (the orchestrator records them as follow-ups):
- Ending an already open `video:session` Centrifugo subscription on a ban. lighthouse has no unsubscribe API (a framework change). The subscription's refresh needs the revoked JWT and re-runs the now live-aware authorizer.
- Revoking an already minted LiveKit join token. LiveKit has no revocation. A removed user could reconnect with the token until token_ttl (900 s) runs out. Hosts may lower `golem15.chatvideo.token_ttl`.
- Removing a user from live rooms when they leave a host context without a ban. There is no generic event for that. Live checks still refuse every new join, status, call link and subscribe.
- Ending a call whose last joined participant was banned. The reconciler already ends empty rooms within 5 minutes.
- The logout half of IN-07 (fixed in phase 20 plan 08).
- Tags, pushes, go.mod bumps, the vue-demo-app layer bump, moving the three todos to completed, and the g15office comment. The orchestrator's closing docs commit handles the todos and g15office.
Purpose: a ban ends call access at once, as it already ends chat access. The demo's DM-only promise holds on the server, not only in the seed data and the UI. The incoming-call prompt no longer leaks realtime subscriptions.
Output: four commits in three repos and 261105-oc7-SUMMARY.md.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/STATE.md
@./CLAUDE.md
@.planning/todos/pending/chatvideo-live-membership.md
@.planning/todos/pending/chatvideo-dm-only-host-hook.md
@.planning/todos/pending/chatvideo-incoming-handle-leak.md
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-REVIEW.md
<interfaces>
Existing code, verified at planning time. Paths are relative to /media/nvme/dev/golem15/summercms.io/summercms.
sm-chatvideo-plugin (package classes)
- Errors: ErrNotConfigured, ErrNotFound, ErrNotParticipant, ErrAlreadyEnded, ErrTooMany (video_service.go:20-31).
- type VideoOptions struct { DB *gorm.DB; Rooms RoomAPI; Cfg *compass.Config; Now func() time.Time }
- type VideoService struct { db, rooms, cfg, now, notify } ; func NewVideoService(opt VideoOptions) *VideoService ; SetRooms(RoomAPI) ; SetNotifier(callNotify)
- func (s *VideoService) Start(ctx, actorID, conversationID uint) (*StartResult, error) ; Join / Leave / End / Status / CallLink / Reconcile / OnUserDeleting(ctx, tx *gorm.DB, userID uint) error
- func (s *VideoService) requireParticipant(ctx, conversationID, userID uint) error (unexported)
- func (s *VideoService) invite(ctx, sessionID, starter uint, memberIDs []uint, now time.Time) error (unexported)
- callNotify interface: Incoming(ctx, *models.Session, callerID uint, recipientIDs []uint), Accepted, Declined, Ended(ctx, session, endedBy), ParticipantJoined(ctx, session, userID), ParticipantLeft(ctx, session, userID)
- authorizer.go: type ConversationCheck func(ctx, userID, sessionID uint) bool ; AuthorizeVideo(db *gorm.DB) ; AuthorizeVideoCheck(check ConversationCheck) ; AuthorizeVideoLookup(getDB func() *gorm.DB) ; allowVideo(userID, sessionID) ; parseVideoSessionChannel(channel) (uint, bool)
- livekit.go: RoomAPI { CreateRoom(ctx, name) error; DeleteRoom(ctx, name) error; RemoveParticipant(ctx, room, identity string) error; ParticipantCount(ctx, name) (int, error); ActiveRoomNames(ctx) ([]string, error) } ; FakeRooms { mu sync.Mutex; rooms map[string]map[string]struct{}; created []string } with CreateRoom, DeleteRoom, RemoveParticipant, ParticipantCount, ActiveRoomNames, CreatedNames, SetCount(name, n, create), Drop(name)
- user_deletion.go: const roomCallTimeout = 10 * time.Second ; the AfterCommit pattern described in the objective.
- logger.go: var pluginLog = diary.For("chatvideo")
- models: StatusPending/StatusActive/StatusEnded ; ParticipantInvited/ParticipantJoined/ParticipantDeclined/ParticipantLeft ; Session{ID, ConversationID, ActiveConversationID *uint, LivekitRoomName, Status, StartedBy, StartedAt, ...} ; participant columns video_session_id, user_id, status, joined_at, left_at.
- strconvUint(n uint) string (video_service.go:564), the LiveKit identity of a user.
sm-chatvideo-plugin (package chatvideo, root)
- boot.go: init registers boot steps env, realtime, service, listeners. bootRealtime registers classes.AuthorizeVideoLookup(func() *gorm.DB { app.Lookup[*gorm.DB]() }) under "video". bootService (inside lagoon.OnDatabase) builds classes.NewVideoService(VideoOptions{DB, Rooms, Cfg}), SetNotifier, then publishes p and svc. bootListeners does app.Events.Listen[*userclasses.DeletingEvent](PluginID, p.onUserDeleting). Imports userclasses "git.golem15.com/golem15/sm-user-plugin/classes".
- api/errors.go: string constants errNotFound ... errTooMany ; writeVideoError(w, what, err) switch: NotFound/NotParticipant → 404, NotConfigured → 503, AlreadyEnded/TooMany → 422, default → 500.
- lang/en/lang.yaml and lang/pl/lang.yaml: errors.{auth_required, not_found, not_configured, not_participant, session_not_found, already_ended, too_many}.
- Tests (package chatvideo_test): ensurePostgres(t) ; bootVideo(t, ids []string, extraEnv ...string) *videoEnv{app, gdb, plugins, svc, rooms *classes.FakeRooms, rt *lighthouse.Service} ; (e) user(t) *usermodels.User (activated) ; (e) conversation(t, createdBy, participants ...uint) *chatmodels.Conversation (Type group, no context) ; (e) count(t, table, where, args...) int64 ; (e) session(t, id) models.Session ; const participantsTable ; bootWeb(t) *webEnv{*videoEnv, h} ; (e *webEnv) frontendToken(t, user) string ; (e *webEnv) call(t, method, path, token, body) *httptest.ResponseRecorder (path below chatvideo.APIPrefix) ; decodeObject(t, rec) map[string]any ; deleteUserLikeAdmin shows the lagoon.Transaction + app.Events.Fire pattern ; const fixturePluginID = "acme.teams".
golem15.chat (sm-chat-plugin)
- classes.Service: IsParticipant(ctx, conversationID, userID uint) (bool, error).
- contracts.Context: ID() uint ; Type() string ; Members(ctx) ([]uint, error) ; HasMember(ctx, userID) (bool, error) ; CanOverseeChats(ctx, userID) (bool, error) ; ChatEnabled() bool ; GroupName() string ; CanActFor(ctx, actorID, memberID) bool ; BroadcastChannel() string (two or three colon-separated segments).
- contracts.LiveMembership: RequireLiveMembership() bool.
- contracts.Registry (published as *contracts.Registry): Add(pluginID string, reg Registration) error ; Registration{Alias string; Loader Loader; LegacyPHPClass string} ; type Loader func(ctx, db *gorm.DB, id uint) (Context, error).
- models.Conversation{Type string; ContextType *string; ContextID *uint; ...} with columns context_type and context_id ; models.TypeDM = "dm", models.TypeGroup = "group".
golem15.user (sm-user-plugin classes)
- AccessRevokedEvent{UserIDs []uint; Before time.Time; Reason string; Tx *gorm.DB} ; const AccessRevokedBan = "ban", AccessRevokedPasswordChanged = "password_changed" (plus password_reset, password_set_by_admin).
- DeactivatingEvent{User *models.User; Tx *gorm.DB}.
lighthouse (framework, unchanged)
- (*lighthouse.Service).Registry() *Registry ; (*Registry).Get(namespace) (Authorizer, bool) ; Authorizer.Authorize(ctx, userID uint, channel string) Result ; Result.Allowed bool, Result.Reason() string ; lighthouse.Allowed(info) / lighthouse.Denied(reason).
sm-demo-app
- plugins/demo/plugin.go: Boot runs p.wireRealtime then the steps p.registerChat, p.registerForum, p.registerCommands, p.registerModeration. Requires() already lists golem15.chatvideo.
- plugins/demo/chat.go registerForum is the template: app.HasPlugin guard, lagoon.OnDatabase, app.Lookup of the service, error "golem15.demo: golem15.forum must be listed before golem15.demo in summer.yaml", then Set...(policy).
- video_test.go TestDemoVideoStart: bootAPI(t, env, set) ; a.member(t, email) (id, token) ; a.openDM(t, token, otherID) ; a.openChannel(t, token, "general") ; a.call(t, method, path, token, body) ; scalar[T](t, a.Demo, sql, args) ; exec(t, a.DB, sql, args) ; fakeRoomService.called("CreateRoom").
- config/golem15.chatvideo.yaml lines 1-15: a comment block ending "The server does not restrict calls by conversation type; the site offers them in DMs only." README.md lines 199-201: the "**Calls.**" paragraph says the same.
vue-chatvideo-layer
- app/composables/useIncomingCalls.ts: export const RING_MS = 45_000 ; interface IncomingRuntime { registered: boolean; channel: ChannelHandle | null; timer: ReturnType<typeof setTimeout> | null } ; export function useIncomingCalls() returning { pending, accept(), decline(), dismiss }. It imports onUserEvent, subscribe and ChannelHandle from 'vue-chat-layer/app/lib/realtime', parseIncomingCall, videoEvent and videoSessionChannel from '../lib/videoClient', and useVideoClient from './useCall' (which returns nuxtApp._chatvideoClient when set).
- ChannelHandle { close(): void; resubscribe(): void }. onUserEvent(handler) returns an unsubscribe function. parseIncomingCall reads {event: 'video:call:incoming', payload: {session_id, conversation_id, caller_name}}.
- tests/useCall.test.ts shows the stubbing style: vi.mock('vue-chat-layer/app/lib/realtime', ...), vi.stubGlobal('useNuxtApp', () => ({ _chatvideoClient: client })), vi.unstubAllGlobals() in afterEach.
- package.json: "test": "vitest run" ; devDependencies vitest 3.2.7, vue 3.5.35.
</interfaces>
</context>
<tasks>
<task type="tracer" tdd="true">
<name>Task 1: chatvideo honours live membership end to end and removes banned users from live rooms</name>
<files>../sm-chatvideo-plugin/classes/video_service.go, ../sm-chatvideo-plugin/classes/authorizer.go, ../sm-chatvideo-plugin/classes/livekit.go, ../sm-chatvideo-plugin/classes/revoked_access.go, ../sm-chatvideo-plugin/boot.go, ../sm-chatvideo-plugin/live_membership_test.go, ../sm-chatvideo-plugin/README.md</files>
<read_first>
- ../sm-chatvideo-plugin/classes/video_service.go (whole file; requireParticipant, Start, Leave)
- ../sm-chatvideo-plugin/classes/authorizer.go
- ../sm-chatvideo-plugin/classes/user_deletion.go (the AfterCommit pattern to copy)
- ../sm-chatvideo-plugin/boot.go
- ../sm-chatvideo-plugin/harness_test.go, http_tracer_test.go (lines 1-80), user_deletion_test.go (lines 1-75)
- ../sm-chat-plugin/classes/service.go lines 480-560 (IsParticipant, liveHost, stillMember)
- ../sm-user-plugin/classes/access_revoked.go and classes/events.go lines 70-120
</read_first>
<behavior>
- Live context (RequireLiveMembership true, members {A, B}), conversation with participants A, B and C: A's HTTP start answers 201. A's row is joined, B's is invited, and C has no row (not invited, not rung).
- After B leaves the member set: B's POST join answers 404 and B's GET status answers 404. The registered "video" authorizer denies B on video:session:{id} and allows A. After B is added back: B's join answers 200 and the authorizer allows B.
- A context with RequireLiveMembership false: a participant outside the member set still starts, joins and is authorized (participant-row behaviour).
- A ban: A starts and B joins, and the fake room holds identities A and B. An AccessRevokedEvent{Reason: ban, UserIDs: [B]} fired inside a lagoon.Transaction leaves B in the room until the commit. After the commit B is gone from the room, A is still in it, B's row is left with left_at set, and the session is still active.
- AccessRevokedEvent with Reason password_changed for A: A stays in the room and A's row stays joined.
- A ban for A in a transaction that then returns an error (rolled back): A stays in the room and A's row stays joined.
- DeactivatingEvent{User: A} committed: A is removed from the room and A's row is left.
</behavior>
<action>
Work in /media/nvme/dev/golem15/summercms.io/summercms/sm-chatvideo-plugin. First run `git status --short`. If any file this task touches has uncommitted edits from another session, stop and report instead of editing.
RED first. Add two methods to `FakeRooms` in classes/livekit.go. `AddParticipant(room, identity string)` puts identity into an existing fake room (a missing room stays missing, as SetCount without create). `HasParticipant(room, identity string) bool`. Both take the mutex. Then write live_membership_test.go (package chatvideo_test, Docker-backed: call ensurePostgres(t) first so it skips under -short) with the cases in `<behavior>`, in three test functions:
- **TestVideoLiveMembership** (bootWeb). Add a test-only type implementing chat's contracts.Context and contracts.LiveMembership. It holds a mutex-guarded member set and a `live` flag; HasMember reads the set, RequireLiveMembership returns the flag, ChatEnabled is true, BroadcastChannel is "acme:team:1", CanActFor uses chatcontracts.DefaultCanActFor, CanOverseeChats is false. Look up `*chatcontracts.Registry` from env.app and Add(fixturePluginID, Registration{Alias "acme_team", Loader returning that context for id 1, nil otherwise}). Point the test conversation at it with an Updates of context_type "acme_team" and context_id 1. Check rows with env.count on participantsTable. Get the authorizer with `env.rt.Registry().Get("video")`.
- **TestVideoMembershipWithoutLiveCheck**: same setup with live false.
- **TestVideoBanRemovesFromCall** (bootVideo). Fire the events through env.app.Events.Fire inside lagoon.Transaction, as deleteUserLikeAdmin does. Seed the fake room with AddParticipant using the users' decimal ids as identities.
Run the tests against the unchanged service and record that they fail for the membership, ban and deactivation assertions, not only for compile errors.
GREEN, in classes/video_service.go:
- Add the exported type `MembershipCheck`: a func of (ctx context.Context, conversationID, userID uint) returning (bool, error). Its doc comment says golem15.chat's Service.IsParticipant has this shape.
- Add `Membership MembershipCheck` to VideoOptions and a `membership` field to VideoService, copied by NewVideoService. Add `SetMembership(m MembershipCheck)`, nil-receiver safe like SetNotifier, where nil restores the participant-row check.
- requireParticipant: keep the conversation load and its ErrNotFound. Then, when s.membership is set, call it. An error is returned as is, and false is ErrNotParticipant. When it is not set, keep today's participant-row count exactly. Status, CallLink, Join, Leave and End inherit this through requireParticipant and sessionForActor; do not change their signatures.
- Start: keep the ErrTooMany check on the raw memberIDs, unchanged and still before any per-member work. Then, when s.membership is set, build the recipient list from memberIDs in order. Keep actorID unconditionally (it already passed requireParticipant) and drop every other id for which the check answers false; a check error aborts Start with that error. Pass this list to invite and to notify.Incoming instead of memberIDs. With no membership set, the list is memberIDs.
In classes/authorizer.go, add the exported `AuthorizeVideoMembership(getDB func() *gorm.DB, member MembershipCheck) lighthouse.AuthorizerFunc`. It is AuthorizeVideoLookup's body, except that after loading the session it calls member(ctx, session.ConversationID, userID) when member is non-nil. An error or false is Denied("not a conversation participant"). With a nil member it keeps the participant-row count. AuthorizeVideoLookup becomes a one-line delegation with a nil member. AuthorizeVideo and AuthorizeVideoCheck stay as they are.
Create classes/revoked_access.go with the exported `(s *VideoService) RemoveFromCalls(ctx context.Context, tx *gorm.DB, userIDs []uint) error`. Its doc comment says it removes the users from every live call, for a ban or a deactivation. It mirrors OnUserDeleting's structure: nil and empty guards; a nil tx falls back to s.db and a nil ctx to Background; the q() helper on tx. Steps:
1. Load the live sessions (status pending or active, active_conversation_id NOT NULL) in which any of the users has a participant row with status joined or left.
2. Inside tx, update the users' rows with status joined in those sessions to status left with left_at now (s.now().UTC()).
3. Register one lagoon.AfterCommit callback on q(). It removes each (room, strconvUint(userID)) pair whose row was joined or left through s.rooms.RemoveParticipant, using roomCallTimeout per call and a Warn log with op remove_participant unless the error is ErrNotConfigured. It then calls s.notify.ParticipantLeft(base, session, userID) for the rows that were joined.
4. Return nil without registering a callback when there is nothing to do.
It never ends a session and never deletes rows.
In boot.go:
- Add an unexported `chatMembership(app *backpack.App) classes.MembershipCheck`. On each call it looks up `*chatclasses.Service` (import "git.golem15.com/golem15/sm-chat-plugin/classes" as chatclasses) and returns its IsParticipant answer. A missing or nil service returns false with an unexported error naming golem15.chat: fail closed, never fall back to the participant row.
- bootRealtime registers classes.AuthorizeVideoMembership with the existing getDB closure and chatMembership(app).
- bootService sets Membership: chatMembership(app) in VideoOptions.
- bootListeners adds two listeners next to the DeletingEvent one. `app.Events.Listen[*userclasses.AccessRevokedEvent](PluginID, p.onAccessRevoked)` calls p.service.RemoveFromCalls(ctx, ev.Tx, ev.UserIDs) only when ev.Reason == userclasses.AccessRevokedBan (other reasons return nil). `app.Events.Listen[*userclasses.DeactivatingEvent](PluginID, p.onUserDeactivating)` calls it with the single user id. Both return nil on a nil plugin, event, user or service, as onUserDeleting does.
Update README.md in the same commit:
- Overview: production registers AuthorizeVideoMembership with chat's Service.IsParticipant, so a host context implementing chat's contracts.LiveMembership ends call access as soon as the user leaves it.
- Features: a "Live membership." bullet (requireParticipant, the authorizer, invitees filtered at start) and a "Bans." bullet (AccessRevokedEvent with reason ban and DeactivatingEvent; rows left in the transaction; LiveKit removal and participant-left after the commit; the residual window up to token_ttl because LiveKit tokens cannot be revoked).
- API reference rows: classes.MembershipCheck, classes.VideoService.SetMembership, classes.VideoService.RemoveFromCalls, classes.AuthorizeVideoMembership, classes.FakeRooms.AddParticipant, classes.FakeRooms.HasParticipant.
- Dependencies: chat for Service.IsParticipant; the user plugin for AccessRevokedEvent and DeactivatingEvent (both in v0.1.13).
- Testing: the three new test names in the `go test -run` line.
Keep the forbidden fixture words out of every production file and the README (see objective). Run gofmt.
Commit in sm-chatvideo-plugin, staging these seven paths explicitly: `fix: honour chat live membership and remove banned users from live calls`. Add a short body naming IN-02. No co-author trailer.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-chatvideo-plugin && test -z "$(gofmt -l .)" && go vet ./... && go test -short ./... && go test -count=1 -run '^(TestVideoLiveMembership|TestVideoMembershipWithoutLiveCheck|TestVideoBanRemovesFromCall|TestHTTPTracer|TestUserDeletionReassignsSession|TestReconcileEmptyRoom|TestGoldenEvents|TestFixtureAbsentFromProduction)$' .</automated>
</verify>
<acceptance_criteria>
- The three new tests run (not skipped) and pass. They failed before the implementation for the membership, ban and deactivation assertions.
- `gofmt -l .` prints nothing. `go vet ./...` and `go test -short ./...` are green. The full `go test -count=1 ./...` (Docker; if the socket is denied, run it through `sudo -u golem` as CLAUDE.md says) is green.
- `git -C ../sm-chatvideo-plugin diff HEAD~1 --stat` lists exactly the seven task files. go.mod and go.sum are unchanged.
- `git -C ../sm-chatvideo-plugin log -1 --format=%B | grep -ci 'co-authored'` prints 0.
</acceptance_criteria>
<done>chatvideo consults chat's live membership for every participant check, the authorizer and the start invitees. A ban or deactivation removes the user from live rooms after the commit. Existing behaviour is unchanged for hosts without LiveMembership. One commit in sm-chatvideo-plugin.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: optional CallPolicy host hook with a DM-only policy, installed by the demo</name>
<files>../sm-chatvideo-plugin/contracts/call_policy.go, ../sm-chatvideo-plugin/contracts/call_policy_test.go, ../sm-chatvideo-plugin/classes/video_service.go, ../sm-chatvideo-plugin/api/errors.go, ../sm-chatvideo-plugin/lang/en/lang.yaml, ../sm-chatvideo-plugin/lang/pl/lang.yaml, ../sm-chatvideo-plugin/call_policy_test.go, ../sm-chatvideo-plugin/README.md, ../sm-chatvideo-plugin/plugin.yaml, ../sm-demo-app/plugins/golem15/chatvideo, ../sm-demo-app/plugins/demo/video.go, ../sm-demo-app/plugins/demo/plugin.go, ../sm-demo-app/video_test.go, ../sm-demo-app/config/golem15.chatvideo.yaml, ../sm-demo-app/README.md</files>
<read_first>
- ../sm-chatvideo-plugin/classes/video_service.go (after Task 1)
- ../sm-chatvideo-plugin/api/errors.go, lang/en/lang.yaml, lang/pl/lang.yaml
- ../sm-chatchannels-plugin/contracts/access_resolver.go (package doc and comment style of a host seam)
- ../sm-chat-plugin/contracts/moderator.go (comment style of an optional hook)
- ../sm-demo-app/plugins/demo/chat.go lines 73-89 (registerForum template) and plugins/demo/plugin.go lines 80-100
- ../sm-demo-app/video_test.go lines 88-200
</read_first>
<behavior>
- contracts (-short): DMOnly answers true for "dm" and false for "group" and "". CallPolicyFunc passes userID, conversationID and conversationType through unchanged.
- No policy installed: a group-conversation start answers 201 (unchanged).
- SetCallPolicy(contracts.DMOnly): a group start answers 403 with error "Video calls are not available in this conversation". The conversation has zero sessions and zero chatvideo participant rows, and env.rooms.CreatedNames() did not grow. A DM start (conversation Type "dm") answers 201.
- A recording CallPolicyFunc sees the actor id, the conversation id and "group".
- A policy that returns an error: start answers 500 and creates no session.
- A non-participant's start answers 404 and the recording policy is not called.
- A group session started before the policy was installed: with DMOnly installed, start answers 403 and another member's POST join answers 200.
- SetCallPolicy(nil): a group start answers 201 again.
- Demo: with the demo's boot, a start in #general answers 403 both with 5 participants and after trimming the channel to 2. No session exists for #general and CreateRoom was called once (for the DM only). DM starts and the stranger 404 are unchanged.
</behavior>
<action>
**Part A, sm-chatvideo-plugin** (/media/nvme/dev/golem15/summercms.io/summercms/sm-chatvideo-plugin; check `git status --short` first, as in Task 1).
RED: write contracts/call_policy_test.go (package contracts, -short) and call_policy_test.go (package chatvideo_test, Docker; ensurePostgres first; bootWeb) with the plugin cases in `<behavior>`. Create the DM conversation in the test with gdb.Create of a chatmodels.Conversation with Type chatmodels.TypeDM plus two chatmodels.Participant rows, the same way the harness's conversation helper does it. Install policies through env.svc.SetCallPolicy. Run them and record the failure: compile errors are expected until the identifiers exist, so add the contracts types first and then see the 403 assertions fail.
GREEN:
- Create contracts/call_policy.go: package contracts, with a package doc comment saying it holds golem15.chatvideo's host seams. Declare:
- The interface `CallPolicy` with the single method `CanStartCall(ctx context.Context, userID, conversationID uint, conversationType string) (bool, error)`. Its doc comment: consulted when a conversation participant starts a call, after the participant check; false refuses the start; never consulted for joining a running call.
- `CallPolicyFunc`, a func type with that signature implementing CallPolicy.
- The exported var `DMOnly CallPolicy`, a CallPolicyFunc answering conversationType == chatmodels.TypeDM (import the chat models package).
- classes/video_service.go:
- Add `ErrCallNotAllowed` (text "video calls are not allowed in this conversation"), `CallPolicy contracts.CallPolicy` in VideoOptions, a `policy` field copied by NewVideoService, and `SetCallPolicy(p contracts.CallPolicy)`, nil-receiver safe, where nil allows every start (today's behaviour).
- Change requireParticipant to return the conversation it loaded, `(*chatmodels.Conversation, error)`. Other callers discard it.
- In Start, right after requireParticipant and before activeSession, when a policy is set: call CanStartCall(ctx, actorID, conversationID, conv.Type). An error is returned as is; false returns ErrCallNotAllowed. Join, Leave, End, Status and CallLink do not consult the policy.
- api/errors.go: add the constant errCallNotAllowed = "Video calls are not available in this conversation" and a writeVideoError case mapping classes.ErrCallNotAllowed to 403. A 422 would show the frontend's "too many people" text.
- lang en and pl: add errors.not_allowed with "Video calls are not available in this conversation." and "Połączenia wideo nie są dostępne w tej rozmowie."
- README.md:
- Features: a "Call policy." bullet (optional, default allows all, DMOnly, 403 answer, join unaffected).
- Usage: a short paragraph saying a host installs a policy from a lagoon.OnDatabase hook by looking up *classes.VideoService and calling SetCallPolicy(contracts.DMOnly). Keep it in prose plus the existing code-block style.
- API reference rows: contracts.CallPolicy, contracts.CallPolicyFunc, contracts.DMOnly, classes.VideoService.SetCallPolicy, classes.ErrCallNotAllowed.
- Overview or Features: the start route's possible 403.
- Testing: add TestVideoCallPolicy to the run line.
- Run `go test -short -run TestPluginManifest .`. Only if it reports a mismatch, regenerate plugin.yaml with `go run git.golem15.com/golem15/summercms/cmd/summer plugin:manifest` (or the installed `summer plugin:manifest`) and include it. Otherwise leave plugin.yaml untouched.
Commit in sm-chatvideo-plugin, staging the changed plugin paths explicitly: `feat: optional CallPolicy host hook and a DM-only policy`. Add a body naming IN-01. No co-author trailer.
**Part B, sm-demo-app** (/media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app; check `git status --short` first; other batch items also commit here, so stage only these paths).
- Move the submodule to the new plugin HEAD with `git -C plugins/golem15/chatvideo fetch /media/nvme/dev/golem15/summercms.io/summercms/sm-chatvideo-plugin main`, then `git -C plugins/golem15/chatvideo checkout --detach FETCH_HEAD`. Confirm `git -C plugins/golem15/chatvideo rev-parse HEAD` equals `git -C ../sm-chatvideo-plugin rev-parse HEAD`.
- Create plugins/demo/video.go with `(p *Plugin) registerVideo(app *backpack.App) error`, modelled on registerForum:
- It returns nil without golem15.chatvideo.
- Inside lagoon.OnDatabase it looks up *chatvideoclasses.VideoService (import "git.golem15.com/golem15/sm-chatvideo-plugin/classes" and ".../contracts").
- A missing service returns the error "golem15.demo: golem15.chatvideo must be listed before golem15.demo in summer.yaml".
- Otherwise it calls SetCallPolicy(chatvideocontracts.DMOnly).
- Its doc comment cites D-23 (calls in DMs only), now enforced on the server.
- plugins/demo/plugin.go: append p.registerVideo to the Boot step list and mention the video call policy in Boot's doc comment.
- video_test.go: rewrite TestDemoVideoStart's doc comment ("the server refuses a call outside a DM through chatvideo's DM-only CallPolicy") and its channel section:
- The #general start answers 403 with the error text above, while participants is still 5.
- After the existing trim to 2 participants it still answers 403. Replace the old 201 assertion and its "no type rule" message.
- #general has 0 sessions, and fake.called("CreateRoom") has length 1.
- The DM part and the stranger 404 stay as they are.
- config/golem15.chatvideo.yaml: replace the last comment sentence with one saying golem15.demo installs chatvideo's DM-only CallPolicy, so the server refuses calls outside DMs (403) whatever max_participants allows. Leave the values unchanged.
- README.md "**Calls.**" paragraph: the same correction.
Run the demo gates in `<verify>`. Then commit, staging exactly plugins/golem15/chatvideo, plugins/demo/video.go, plugins/demo/plugin.go, video_test.go, config/golem15.chatvideo.yaml and README.md: `feat: video calls in DMs only, enforced on the server by chatvideo's CallPolicy`. The body names IN-01 and states that the chatvideo pointer is ahead of the go.mod pin (v0.1.1) until the plugin is tagged. No co-author trailer, no go.mod change.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-chatvideo-plugin && go vet ./... && go test -short ./... && go test -count=1 -run '^(TestVideoCallPolicy|TestVideoLiveMembership|TestHTTPTracer)$' . && cd ../sm-demo-app && go vet ./... && go test -short ./... && go test -count=1 -run '^(TestDemoVideoStart|TestBootAllPlugins|TestDemoDMs|TestDemoChatContextMembership|TestRealtimeMemberToken|TestGoModRequiresTags)$' .</automated>
</verify>
<acceptance_criteria>
- TestVideoCallPolicy and the contracts unit test pass. They failed on the 403 assertions before the Start change.
- The full `go test -count=1 ./...` in sm-chatvideo-plugin is green (Docker; `sudo -u golem` if the socket is denied).
- The demo's targeted Docker tests above pass, with TestDemoVideoStart asserting 403 for both channel starts. `go test ./...` in sm-demo-app is green (Docker); if a test unrelated to video fails, check against the base commit and report it rather than editing it.
- `git -C ../sm-demo-app show --stat HEAD` lists exactly the six demo paths. `git -C ../sm-demo-app diff HEAD~1 -- go.mod go.sum` is empty.
- Neither of the two new commits has a co-author trailer.
</acceptance_criteria>
<done>Hosts can install contracts.CallPolicy, and DMOnly ships with the plugin. The demo enforces calls in DMs only on the server, and its test proves it no longer depends on max_participants or seed data. Two commits: plugin, then demo (pointer bump and wiring).</done>
</task>
<task type="auto" tdd="true">
<name>Task 3: useIncomingCalls closes stale session handles</name>
<files>../vue-chatvideo-layer/app/composables/useIncomingCalls.ts, ../vue-chatvideo-layer/vitest.config.ts, ../vue-chatvideo-layer/tests/useIncomingCalls.test.ts, ../vue-chatvideo-layer/README.md</files>
<read_first>
- ../vue-chatvideo-layer/app/composables/useIncomingCalls.ts
- ../vue-chatvideo-layer/tests/useCall.test.ts lines 1-140 (mock and stub style)
- ../vue-chatvideo-layer/app/lib/videoClient.ts lines 195-220 (parseIncomingCall)
- ../vue-chat-layer/vitest.config.ts (the sibling layer's config shape)
- ../vue-chatvideo-layer/README.md "Composables" and "Testing" sections
</read_first>
<behavior>
- Two video:call:incoming events for session 5 while both subscribes are pending. When the first resolves before the second, the first handle is closed and the second is kept (not closed). When the second resolves first, the first, resolving later, is closed and the second is kept.
- Rings for session 5 and then session 6 while both subscribes are pending: the session 5 handle is closed whatever the order; the session 6 handle is kept and pending is session 6.
- A subscribe still pending when dismiss() runs: its handle is closed when it resolves, and pending stays null.
- The kept handle is closed by dismiss(), by accept() (which returns the conversation id) and by decline() (which calls client.leave with the conversation id).
- A video:call:ended publication on the kept handle clears pending and closes it.
- With fake timers, after RING_MS the prompt clears and the kept handle is closed.
</behavior>
<action>
Work in /media/nvme/dev/golem15/summercms.io/summercms/vue-chatvideo-layer; check `git status --short` first.
RED:
- Add vitest.config.ts using defineConfig from 'vitest/config': `define` maps 'import.meta.client' to 'true'; test.environment is 'node'; test.include is ['tests/**/*.test.ts']. Add a short header comment saying the define lets the client-only registration in useIncomingCalls run under vitest. Confirm the existing 127 tests still pass with it.
- Write tests/useIncomingCalls.test.ts with the cases in `<behavior>`:
- vi.mock 'vue-chat-layer/app/lib/realtime'. onUserEvent records the handler and returns a no-op unsubscribe. subscribe returns a promise the test resolves by hand and records the channel, the hooks and a handle with vi.fn close and resubscribe.
- In beforeEach, stub the globals: useState backed by a Map of vue refs keyed by the state key, and useNuxtApp returning one fresh object per test that carries _chatvideoClient with a vi.fn leave. A fresh object per test means each test registers its own handler.
- Import the composable dynamically after the mocks, as useCall.test.ts does. Deliver rings by calling the recorded handler with {event: 'video:call:incoming', payload: {session_id, conversation_id, caller_name}}. Flush microtasks after resolving a subscribe.
- vi.unstubAllGlobals and vi.useRealTimers in afterEach.
- Run `pnpm test` and record that the same-session cases fail on the current code (a stale handle is never closed).
GREEN, in app/composables/useIncomingCalls.ts:
- Add `seq: number` to IncomingRuntime, initialised to 0 in the nuxtApp default object.
- clear() increments rt.seq, alongside its current work, so a subscribe in flight at that moment is invalidated.
- watchSession takes `const seq = ++rt.seq` after closing the current channel. After the await it keeps the handle only when seq still equals rt.seq and pending.value?.sessionId === call.sessionId; otherwise it calls handle.close() immediately.
- The onUserEvent handler keeps its order (clear, set pending, start the timer, watchSession). The ring timer and the ended-publication check stay as they are.
- Update the file's header comment: at most one session handle is open, and a handle that resolves after a newer ring or a dismiss is closed.
README.md:
- The useIncomingCalls() bullet: one clause saying a newer ring or a dismiss closes a session subscription that is still opening.
- Testing: add a `tests/useIncomingCalls.test.ts` bullet listing what it covers, and mention vitest.config.ts (the import.meta.client define) and the updated `pnpm test` comment.
Do not bump package.json.
Commit in vue-chatvideo-layer, staging the four paths explicitly: `fix: the incoming-call runtime closes stale session handles`. Add a body naming IN-07. No co-author trailer.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/vue-chatvideo-layer && pnpm test</automated>
</verify>
<acceptance_criteria>
- `pnpm test` is green: the 127 previous tests plus the new file. The new same-session tests failed on the unchanged composable.
- `git -C ../vue-chatvideo-layer show --stat HEAD` lists exactly the four paths. package.json is unchanged.
- The commit has no co-author trailer.
</acceptance_criteria>
<done>The incoming-call runtime keeps only the latest ring's session handle and closes every stale one. Covered by a dedicated vitest file. One commit in vue-chatvideo-layer.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| browser → chatvideo JSON API | A JWT-authenticated member asks to start, join, leave or end calls and reads status and call links. The actor id comes from the token |
| browser → lighthouse subscribe (video:session:{id}) | Subscription authorization runs the plugin's "video" authorizer |
| LiveKit join token holder → LiveKit SFU | A minted HS256 token (token_ttl 900 s) admits its holder to the room until it expires. The server can only remove a connected identity |
| host application → chatvideo | Host contexts (chat's contracts.Context, LiveMembership) and the new CallPolicy decide who takes part and where calls may start |
| user plugin admin actions → chatvideo | Ban and deactivation events are fired inside the admin transaction |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-q261105oc7-01 | Elevation of privilege | requireParticipant and the video authorizer accepted a stale participant row after the user left the host context | medium | mitigate | Task 1: both go through chat's Service.IsParticipant (LiveMembership). TestVideoLiveMembership covers join, status and authorizer denial and re-admission |
| T-q261105oc7-02 | Elevation of privilege | A banned or deactivated user keeps a live LiveKit connection | medium | mitigate | Task 1: RemoveFromCalls on AccessRevokedEvent (ban) and DeactivatingEvent removes the identity after the commit and marks rows left. TestVideoBanRemovesFromCall, including the rollback and password-reason cases |
| T-q261105oc7-03 | Elevation of privilege | A removed user reconnects with the still-valid LiveKit token | medium | accept | LiveKit has no token revocation. The window is bounded by golem15.chatvideo.token_ttl (900 s), which hosts can lower. The JWT is revoked, so no new token can be minted. Documented in the README Bans bullet and the SUMMARY follow-ups |
| T-q261105oc7-04 | Information disclosure | An open video:session subscription survives a ban until its token refresh | low | accept | lighthouse has no server-side unsubscribe (a framework follow-up). The refresh needs the revoked JWT and re-runs the live-aware authorizer. The channel carries call events and user ids only |
| T-q261105oc7-05 | Elevation of privilege | A member rings everyone in a channel once max_participants allows it (IN-01) | medium | mitigate | Task 2: contracts.CallPolicy with DMOnly; the demo installs it. TestVideoCallPolicy and TestDemoVideoStart assert 403 for both channel cases and no session or room |
| T-q261105oc7-06 | Elevation of privilege | A fail-open path when the chat service or the policy errors | medium | mitigate | chatMembership returns false with an error when chat's service is missing: the authorizer denies and the API answers 500, never a participant-row fallback. A policy error aborts Start with nothing created (asserted) |
| T-q261105oc7-07 | Spoofing | Ringing (video:call:incoming on user:{id}) of users who are no longer members | low | mitigate | Task 1: Start filters invitees through the membership check before invite and notify.Incoming; asserted by the missing participant row |
| T-q261105oc7-08 | Denial of service | Per-invitee membership queries at start | low | accept | The ErrTooMany check runs first on the raw list, so at most max_participants (default 8) checks run, and only when a membership check is installed |
| T-q261105oc7-09 | Denial of service | Leaked realtime subscriptions in the browser (IN-07) | low | mitigate | Task 3: a sequence number per watchSession; stale handles are closed; tests/useIncomingCalls.test.ts |
| T-q261105oc7-SC | Tampering | npm/pip/cargo installs | low | accept | No install and no new dependency in any repo. vitest/config comes from the existing vitest 3.2.7 devDependency; the Go imports are already required modules (chat v0.1.3, user v0.1.13) |
</threat_model>
<verification>
- sm-chatvideo-plugin: gofmt clean; `go vet ./...`, `go test -short ./...` and the full `go test -count=1 ./...` (Docker) green after each of its two commits.
- sm-demo-app: `go vet ./...`, `go test -short ./...` and `go test -count=1 ./...` (Docker) green, TestDemoVideoStart asserting 403 for channel starts. The submodule pointer equals the plugin HEAD. go.mod and go.sum are unchanged.
- vue-chatvideo-layer: `pnpm test` green with the new file.
- Four commits total (two plugin, one demo, one layer), each staging only its listed paths, none with a co-author trailer. Nothing pushed or tagged; no summercms.go code changed.
</verification>
<success_criteria>
- A ban ends call access at once: no join, status, call link or subscribe for a member who left a live-membership context; banned or deactivated users are removed from live LiveKit rooms after the commit.
- Hosts can restrict where calls start through an optional CallPolicy (default unchanged). The demo enforces calls in DMs only on the server, independent of seed data.
- The incoming-call runtime never leaks a session handle.
- The SUMMARY lists the release steps (tag and push sm-chatvideo-plugin before the demo, require the tag in the demo's go.mod so check-pins passes, tag vue-chatvideo-layer and bump vue-demo-app) and the Not-in-scope follow-ups.
</success_criteria>
<output>
Create `.planning/quick/261105-oc7-chatvideo-hardening/261105-oc7-SUMMARY.md` when done. Include the four commit hashes, the release state of the demo pointer against its go.mod pin, and the follow-ups from the objective's "Not in scope" list so the orchestrator can file them.
</output>

View File

@@ -0,0 +1,149 @@
---
phase: quick-261105-oc7
plan: 01
subsystem: chatvideo (sm-chatvideo-plugin, sm-demo-app, vue-chatvideo-layer)
tags: [chatvideo, security, live-membership, bans, call-policy, realtime]
status: complete
requirements:
- todo:chatvideo-live-membership
- todo:chatvideo-dm-only-host-hook
- todo:chatvideo-incoming-handle-leak
requires:
- golem15.chat Service.IsParticipant + contracts.LiveMembership (v0.1.3)
- golem15.user AccessRevokedEvent / DeactivatingEvent (v0.1.13)
provides:
- classes.MembershipCheck, VideoOptions.Membership, VideoService.SetMembership
- classes.AuthorizeVideoMembership
- classes.VideoService.RemoveFromCalls (ban / deactivation)
- contracts.CallPolicy, contracts.CallPolicyFunc, contracts.DMOnly, VideoService.SetCallPolicy, classes.ErrCallNotAllowed (403)
- demo registerVideo installing DMOnly
- useIncomingCalls sequence-numbered session handles
affects: [sm-demo-app go.mod pin of sm-chatvideo-plugin, vue-demo-app layer pin]
tech-stack:
added: []
patterns: [lagoon.AfterCommit for LiveKit side effects, optional host hook with nil default, fail-closed membership lookup]
key-files:
created:
- ../sm-chatvideo-plugin/classes/revoked_access.go
- ../sm-chatvideo-plugin/live_membership_test.go
- ../sm-chatvideo-plugin/contracts/call_policy.go
- ../sm-chatvideo-plugin/contracts/call_policy_test.go
- ../sm-chatvideo-plugin/call_policy_test.go
- ../sm-demo-app/plugins/demo/video.go
- ../vue-chatvideo-layer/vitest.config.ts
- ../vue-chatvideo-layer/tests/useIncomingCalls.test.ts
modified:
- ../sm-chatvideo-plugin/classes/video_service.go
- ../sm-chatvideo-plugin/classes/authorizer.go
- ../sm-chatvideo-plugin/classes/livekit.go
- ../sm-chatvideo-plugin/boot.go
- ../sm-chatvideo-plugin/api/errors.go
- ../sm-chatvideo-plugin/lang/en/lang.yaml
- ../sm-chatvideo-plugin/lang/pl/lang.yaml
- ../sm-chatvideo-plugin/README.md
- ../sm-demo-app/plugins/golem15/chatvideo (submodule pointer)
- ../sm-demo-app/plugins/demo/plugin.go
- ../sm-demo-app/video_test.go
- ../sm-demo-app/config/golem15.chatvideo.yaml
- ../sm-demo-app/README.md
- ../vue-chatvideo-layer/app/composables/useIncomingCalls.ts
- ../vue-chatvideo-layer/README.md
decisions:
- "chatvideo's membership check is golem15.chat's Service.IsParticipant, looked up per call; a missing chat service fails closed (false + error), never a participant-row fallback"
- "The CallPolicy runs right after the participant check and before the active-session lookup and max_participants, so a refused start creates nothing and a running group call cannot be re-started under DMOnly (joining it still works)"
- "A policy refusal is 403 so vue-chatvideo-layer's existing failureReason(403) = 'forbidden' reads correctly; 422 would show 'too many people'"
metrics:
duration: ~50 min
completed: 2026-11-05
actuals:
tasks: 3
commits: 4
---
# Quick 261105-oc7: chatvideo hardening Summary
chatvideo now checks every participant, the `video:session` authorizer and start invitees through chat's live-membership-aware `Service.IsParticipant`. Bans and deactivations drop the user from live LiveKit rooms after the commit. An optional `contracts.CallPolicy` with a ready-made `DMOnly` lets the demo enforce DM-only calls on the server. `useIncomingCalls` closes every stale session handle.
## Commits
| # | Repo | Hash | Message |
|---|------|------|---------|
| 1 | sm-chatvideo-plugin (`main`) | `f996156` | fix: honour chat live membership and remove banned users from live calls |
| 2 | sm-chatvideo-plugin (`main`) | `11a9607` | feat: optional CallPolicy host hook and a DM-only policy |
| 3 | sm-demo-app (`master`) | `fbfdcf6` | feat: video calls in DMs only, enforced on the server by chatvideo's CallPolicy |
| 4 | vue-chatvideo-layer (`main`) | `6d5784d` | fix: the incoming-call runtime closes stale session handles |
None has a co-author trailer. Nothing was pushed or tagged. No go.mod or go.sum changed in any repo, and no summercms.go code changed. Each commit staged only its listed paths. plugin.yaml was left alone because `TestPluginManifest` passed without regenerating it.
## What was built
**Task 1 (IN-02), live membership and bans.**
- `classes.MembershipCheck`, `VideoOptions.Membership` and `VideoService.SetMembership` were added.
- `requireParticipant` uses the membership check when one is set. With none set, the participant-row count is unchanged.
- `Start` keeps the raw `ErrTooMany` check. It then drops the participants who fail the check from the invite list and from `notify.Incoming`. The actor is always kept.
- `AuthorizeVideoMembership(getDB, member)` was added, and `AuthorizeVideoLookup` now delegates to it with a nil member.
- Boot installs `chatMembership(app)` in the service and the authorizer. It looks up `*chatclasses.Service` on each call and fails closed.
- Boot also listens for `AccessRevokedEvent`, but only acts on the reason `ban`, and for `DeactivatingEvent`. Both call `RemoveFromCalls`, which:
- marks the user's joined rows of live sessions left, with `left_at`, inside the transaction
- after the commit, removes the user's LiveKit identity from rooms where they were joined or had left, and publishes participant-left for the rows that were joined
- never ends a session or deletes a row
- `FakeRooms.AddParticipant` and `FakeRooms.HasParticipant` were added for tests.
**Task 2 (IN-01), CallPolicy.**
- New `contracts` package with `CallPolicy`, `CallPolicyFunc` and `DMOnly`.
- `VideoOptions.CallPolicy`, `VideoService.SetCallPolicy` and `ErrCallNotAllowed` were added. A refusal maps to 403 `"Video calls are not available in this conversation"`, with lang `errors.not_allowed` in en and pl.
- `requireParticipant` now also returns the conversation it loaded. It is unexported.
- The demo's `registerVideo` installs `DMOnly` from a `lagoon.OnDatabase` hook (D-23).
- `TestDemoVideoStart` now expects 403 for #general with 5 participants and again after trimming to 2. It also checks there are 0 sessions for #general and exactly 1 CreateRoom call (the DM's).
- The config comment and the README "Calls." paragraph now say the server enforces the rule.
**Task 3 (IN-07), stale handles.**
- `IncomingRuntime.seq` was added. `clear()` increments it, and `watchSession` takes `const seq = ++rt.seq`. When the subscribe resolves, the handle is kept only if `seq` still matches and the session is still the pending one. Otherwise it is closed.
- New `vitest.config.ts` (defines `import.meta.client`) and `tests/useIncomingCalls.test.ts` (10 tests).
## TDD evidence
- **Task 1.** On the unchanged service, `TestVideoLiveMembership` failed on "C (not a member) has 1 participant rows". `TestVideoBanRemovesFromCall` failed on "banned B still in the room after the commit" and "deactivated A still in the room after the commit". The first ban RED run was not valid, because the helper passed the event as `any` and the generic `festival.Fire[T]` matched no listener. After fixing the helper, I confirmed the ban and deactivation failures again with the new listeners commented out.
- **Task 2.** With the contracts types and SetCallPolicy in place but not used by `Start`, `TestVideoCallPolicy` failed four subtests. Group start under DMOnly gave 201. The recording policy was never called. A policy error gave 201. A start of a running call gave 200. `TestDemoVideoStart` with `registerVideo` taken out failed with 422, then 201, 1 session and 2 CreateRoom calls.
- **Task 3.** On the unchanged composable, both same-session tests failed with "expected spy to be called 1 times, but got 0 times". The other 8 already passed and now guard against regressions.
## Verification
- **sm-chatvideo-plugin:** `go vet ./...`, `GOWORK=off go vet ./...` (against the pinned chat v0.1.3 and user v0.1.13), `go test -short ./...` and the full `go test -count=1 ./...` (Docker) all pass after each commit. `TestFixtureAbsentFromProduction` and `TestPluginManifest` pass.
- **sm-demo-app:** `go vet ./...`, `go test -short ./...`, the targeted Docker tests from the plan and the full `go test -count=1 ./...` all pass. The submodule pointer equals the plugin HEAD (`11a9607`).
- **vue-chatvideo-layer:** `pnpm test` passes 137 tests (the 127 existing plus 10 new). package.json is unchanged.
## Deviations from Plan
1. **[Rule 1 - test bug] Event firing in the ban test.** `festival.Bus.Fire` is generic (`Fire[T]`), so firing through an `any`-typed helper reached no listener. `fireInTx` now takes a fire closure that calls `env.app.Events.Fire` with the concrete event type. The fix is in the test only.
2. **Skipping under -short.** The plan says to call `ensurePostgres(t)` "so it skips under -short". In this harness `ensurePostgres` starts a container even under `-short`, so the new Docker tests call `t.Skip` under `testing.Short()` first and then `ensurePostgres`.
3. **gofmt gate.** `gofmt -l .` in sm-chatvideo-plugin already listed `harness_test.go` and `http_tracer_test.go` before this plan (import order and map alignment). Those files are outside this task and were not changed, so the plan's `test -z "$(gofmt -l .)"` gate fails on the baseline. Every file this plan touched is gofmt-clean.
## Release state (for the orchestrator / user)
- sm-demo-app `plugins/golem15/chatvideo` is at `11a9607`, ahead of its go.mod pin (`sm-chatvideo-plugin v0.1.1` = `0f08c35`). `scripts/check-pins.sh` reports exactly this. It also reports the earlier chatchannels pointer from a sibling item.
- Dev builds and tests compile through go.work. The GOWORK=off release build (`scripts/build.sh`) does not compile until these steps are done in order:
1. Tag sm-chatvideo-plugin (the next v0.1.x, at `11a9607` or later on `main`).
2. Push that tag before the demo.
3. Commit `chore: require sm-chatvideo-plugin vX` in sm-demo-app (go.mod and go.sum).
- vue-chatvideo-layer also needs a tag at `6d5784d` or later, followed by a vue-demo-app layer bump.
- I did none of these.
## Follow-ups (not in scope)
- **Open subscriptions after a ban.** A ban does not end an already open `video:session` Centrifugo subscription, because lighthouse has no server-side unsubscribe (that is a framework change). Refreshing the subscription needs the revoked JWT and re-runs the now live-aware authorizer, so access lasts until `realtime.centrifugo.token_ttl` (3600 s by default).
- **Join tokens after a ban.** An already minted LiveKit join token cannot be revoked, so a removed user could reconnect until `golem15.chatvideo.token_ttl` (900 s) runs out. Hosts may lower it. This is documented in the README "Bans." bullet.
- **Leaving a host context without a ban.** The user is not removed from live rooms, because there is no generic event for it. The live checks still refuse every new join, status read, call link and subscribe.
- **Banned last participant.** A call whose last joined participant was banned is not ended at once. The reconciler ends empty rooms within 5 minutes.
- The logout half of IN-07 was already fixed in phase 20 plan 08.
- **Pre-existing gofmt drift.** `sm-chatvideo-plugin/harness_test.go` and `http_tracer_test.go` need gofmt.
- **Orchestrator tasks.** Tags, pushes, the go.mod bump, the vue-demo-app layer bump, moving the three todos to completed and the g15office comment.
## Threat Flags
None. The only new surface is the ban/deactivation listeners and the 403 path, both in the plan's threat model (T-q261105oc7-02, -05, -06).
## Self-Check: PASSED
- Files: every created file listed above exists on disk.
- Commits: `f996156` and `11a9607` (sm-chatvideo-plugin), `fbfdcf6` (sm-demo-app) and `6d5784d` (vue-chatvideo-layer) are in their repos' logs.

View File

@@ -0,0 +1,294 @@
---
phase: quick-261105-oc8
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- modules/lagoon/attach/static.go
- modules/lagoon/attach/static_test.go
- modules/lagoon/attach/lifecycle_test.go
- modules/lagoon/README.md
- docs/services/storage.md
- docs/database/attachments.md
- modules/surf/uploads.go
autonomous: true
requirements:
- todo:2026-10-28-attach-static-handler-disposition
must_haves:
truths:
- "attach.StaticHandler and attach.StaticHandlerPublic send X-Content-Type-Options: nosniff on every response, GET and HEAD, 200 and 404 alike"
- "A served blob whose stored Content-Disposition is non-empty and parses with mime.ParseMediaType gets that value verbatim (trimmed) as the response's Content-Disposition, on GET and on HEAD. A blob attach.Store wrote for text/html (stored disposition attachment) is therefore served with Content-Disposition: attachment by both handlers"
- "A stored disposition that mime.ParseMediaType rejects (for example a value carrying CR/LF or a broken parameter) is sent as the bare value attachment: the handler fails closed and never forwards malformed metadata"
- "Additive: a blob with no stored disposition (raster images, thumbnails, blobs written before quick-261028-rqe or outside attach.Store) is served exactly as before, with its stored Content-Type and no Content-Disposition. The handlers do not derive a disposition from the type and add no Content-Security-Policy; the surf uploads route keeps doing both"
- "Ordering and 404s are unchanged: the is_public gate still runs before any bucket access, a missing blob, an invalid path and a denied row still answer 404, and a 404 never carries a Content-Disposition"
- "Non-breaking: no exported identifier is added, removed or changes its signature in modules/lagoon or modules/surf. The existing static, lifecycle and surf uploads tests (TestStaticHandler, TestStaticHandlerServesThumbURL, TestStaticHandlerPublicGate, TestUploadsMount, TestUploadsResponseHeaders) pass without edits to their existing assertions"
- "The lagoon README, docs/services/storage.md and docs/database/attachments.md describe the new headers and what the handlers still do not do; the surf uploads.go doc comment no longer says StaticHandlerPublic sends only the stored type. go vet ./..., go test -short ./..., go test ./cmd/summer -run TestDocsTree and go run ./cmd/summer docs:build --check are green at the commit, and the Docker-backed TestStaticHandlerPublicLooksUpIsPublic passes"
artifacts:
- path: modules/lagoon/attach/static.go
provides: "servePublicBlobs reads the blob's Attributes after the gate, sets nosniff, the stored Content-Type and the validated stored Content-Disposition; unexported storedDisposition helper; updated StaticHandler and StaticHandlerPublic doc comments"
contains: "X-Content-Type-Options"
- path: modules/lagoon/attach/static_test.go
provides: "TestStoredDisposition (table) and TestStaticHandlerSendsStoredDisposition (memblob and fileblob sidecar, writeBlob round trip, GET and HEAD, ungated and gated), Docker-free"
contains: "TestStaticHandlerSendsStoredDisposition"
- path: modules/lagoon/attach/lifecycle_test.go
provides: "TestStaticHandlerPublicLooksUpIsPublic also asserts the headers through the real is_public gate on Postgres"
contains: "Content-Disposition"
- path: modules/lagoon/README.md
provides: "Features bullet and the attach.StaticHandler table row name the stored disposition and nosniff"
- path: docs/services/storage.md
provides: "Serving files (mounting the handler yourself) and the deploy note describe what the handlers send and what they do not"
- path: docs/database/attachments.md
provides: "The StaticHandler paragraph and the Store disposition paragraph name the handlers"
- path: modules/surf/uploads.go
provides: "mountUploads doc comment corrected; no code change"
key_links:
- from: modules/lagoon/attach/static.go servePublicBlobs
to: gocloud.dev/blob (*Bucket).Attributes
via: "bucket.Attributes(r.Context(), key) after the allow gate and before NewReader; its ContentDisposition goes through storedDisposition"
pattern: "bucket\\.Attributes\\("
- from: modules/lagoon/attach/static.go storedDisposition
to: modules/lagoon/attach/inline.go attachmentDisposition
via: "the fail-closed value for an unparsable stored disposition is the existing attachmentDisposition constant, the same bare value attach.Store stores"
pattern: "attachmentDisposition"
- from: modules/lagoon/attach/store.go writeBlob
to: modules/lagoon/attach/static.go servePublicBlobs
via: "TestStaticHandlerSendsStoredDisposition writes through writeBlob (Store's real writer) and reads the headers back through StaticHandler"
pattern: "writeBlob\\("
---
<objective>
Close the todo `2026-10-28-attach-static-handler-disposition` in the framework (summercms.go only). Quick 261028-rqe (ba8432c, 4957e5c) made `attach.Store` store `Content-Disposition: attachment` with every blob whose type `attach.IsInlineContentType` rejects, and the surf uploads route sends a disposition. `attach.StaticHandler` and `attach.StaticHandlerPublic` still send only the stored Content-Type, so an application that mounts either handler directly serves a stored HTML body inline. The fix, from the todo's Solution: both handlers send the stored disposition and `X-Content-Type-Options: nosniff`, additively.
Live reads at planning time:
- `modules/lagoon/attach/static.go` `servePublicBlobs` (lines 38-80): method check, nil bucket, prefix strip, `parsePublicBlobPath`, the optional `allow` gate, then `bucket.NewReader(r.Context(), key, nil)`. It sets Content-Type from `reader.ContentType()` (falling back to `defaultStaticContentType`), returns for HEAD, else `io.Copy`. Both exported handlers are thin wrappers over it.
- gocloud.dev v0.46.0: `*blob.Reader` exposes only `ContentType`, `ModTime`, `Size`, `As`; it does not expose the disposition. `(*blob.Bucket).Attributes(ctx, key)` returns `*blob.Attributes` with `ContentDisposition` and `ContentType`. memblob keeps the disposition, fileblob keeps it in its `.attrs` sidecar (the default behind `file://`), s3blob reads it with a HEAD. Reading it costs one `Attributes` call per request; the rqe plan named that cost and deferred it here.
- `modules/lagoon/attach/inline.go` already has the unexported constant `attachmentDisposition` (the bare value attachment) and the exported `IsInlineContentType`. inline.go is not edited.
- `net/http.Error` (Go 1.27) sets `X-Content-Type-Options: nosniff` and does not touch Content-Disposition, so every `http.NotFound` and 405 from the handler already carries nosniff; a disposition set before an error path would leak into the 404.
- `mime.ParseMediaType` accepts `attachment`, `inline`, `attachment; filename="a.png"` and RFC 5987 `filename*=` values; it rejects `attachment;;`, `attachment; filename` and a value containing CR/LF (verified in the scratchpad).
- `modules/surf/uploads.go` wraps `attach.StaticHandlerPublic`. `serveUploads` sets nosniff and the CSP before calling it, and `uploadsDispositionWriter.decide` sets `Content-Disposition: attachment` at WriteHeader/Write time for a non-inline 2xx, i.e. after the handler has set its headers, so the route's output for non-inline types is unchanged and its tests write blobs without a stored disposition. Only its doc comment (lines 36-40, "attach.StaticHandlerPublic sends only the stored type") becomes stale.
- `TestStaticHandlerPublicLooksUpIsPublic` (lifecycle_test.go:190, package attach_test, skips under -short) is the only test of `StaticHandlerPublic` with a real `is_public` lookup.
- No other caller of the handlers exists in the repo (examples/ included). None of the seven files has uncommitted edits from another session at planning time.
Decomposition: two tasks, one commit, run in order.
- Task 1 is the tracer: the header change in servePublicBlobs plus Docker-free tests that write through `writeBlob` (Store's real writer) and read the headers back through both handlers on memblob and fileblob.
- Task 2 adds the Postgres-backed gated assertion, updates the lagoon README, the two docs pages and the surf doc comment, and commits Tasks 1 and 2 together (CLAUDE.md: a change to a module's exported behaviour updates its README and the affected docs pages in the same commit).
Not in scope (the orchestrator records these as follow-ups; do not edit sibling repos or consumer apps):
- Blob writers that bypass `attach.Store` adopting `attach.IsInlineContentType`: fonoteka.go `storeUpload` and `StorePublicFile` (see todo `2026-10-28-fonoteka-uploads-use-disk-extension.md`), the sm-user-plugin avatar writer, the sm-feedback-plugin screenshot writer.
- Adding the disposition to objects already in a bucket: an operator task, already documented in `docs/services/storage.md#deploy-note`.
- A type-derived disposition or a CSP in the handlers. The todo asks for the stored disposition only; deciding from the type would change how existing blobs without a disposition are served (a PDF opened inline would start downloading), which is not additive. The surf uploads route keeps that role.
- Moving the todo to completed and the g15office comment (`knuu7fil`): the orchestrator's closing docs commit handles both.
Purpose: an application that mounts `attach.StaticHandler` or `attach.StaticHandlerPublic` directly gets the same protection a public bucket gives since rqe: an HTML, SVG, PDF or text upload stored by `attach.Store` downloads instead of rendering, and nothing is content-sniffed.
Output: one commit in summercms.go and 261105-oc8-SUMMARY.md.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/STATE.md
@./CLAUDE.md
@.planning/todos/pending/2026-10-28-attach-static-handler-disposition.md
<interfaces>
Existing code, verified at planning time.
modules/lagoon/attach/static.go
- const defaultStaticContentType = "application/octet-stream"
- func StaticHandler(bucket *blob.Bucket, prefix string) http.Handler — signature stays.
- func StaticHandlerPublic(bucket *blob.Bucket, prefix string, db *gorm.DB) http.Handler — signature stays.
- func servePublicBlobs(bucket *blob.Bucket, prefix string, allow func(context.Context, string) (bool, error)) http.Handler — signature stays (TestStaticHandlerPublicGate calls it directly).
- Imports today: context, io, net/http, path, strings, gocloud.dev/blob, gorm.io/gorm. The change adds mime.
modules/lagoon/attach/inline.go (not edited)
- const attachmentDisposition = "attachment" (unexported, bare value, no filename parameter).
- func IsInlineContentType(contentType string) bool.
- func uploadWriterOptions(contentType string) *blob.WriterOptions — ContentType plus ContentDisposition attachment for non-inline types.
modules/lagoon/attach/store.go (not edited)
- func writeBlob(ctx context.Context, bucket *blob.Bucket, key string, r io.Reader, contentType string, limit int64) (int64, error) — writes through uploadWriterOptions. inline_test.go's TestWriteBlobDisposition already calls it with limit 0.
- func BlobKey(diskName string) string and func PartitionDirectory(diskName string) string: the partition is the first nine characters in three groups ("abc123xyz.jpg" -> "abc/123/xyz/").
modules/lagoon/attach/static_test.go (package attach): TestStaticHandler, TestStaticHandlerServesThumbURL, TestStaticHandlerPublicGate; imports context, io, net/http, net/http/httptest, testing, gocloud.dev/blob, gocloud.dev/blob/memblob. inline_test.go already imports gocloud.dev/blob/fileblob, so a test import adds no dependency.
modules/lagoon/attach/lifecycle_test.go (package attach_test): TestStaticHandlerPublicLooksUpIsPublic at line 190 creates a public jpeg row abc123xyz.jpg and a private one def456uvw.jpg via gdb.Create, writes their blobs and thumbs with bucket.WriteAll, builds h := attach.StaticHandlerPublic(bucket, "/storage/uploads", gdb) and checks status codes through a local get(path) int helper.
modules/surf/uploads.go: mountUploads doc comment lines 29-45; lines 36-40 read "attach.Store also stores the attachment disposition with the blob, but the route still decides from the type on every response: attach.StaticHandlerPublic sends only the stored type, and blobs written earlier or outside attach.Store carry no disposition." Code is not edited.
gocloud.dev v0.46.0 (go.mod)
- (*blob.Bucket).Attributes(ctx context.Context, key string) (*blob.Attributes, error); Attributes.ContentDisposition string.
- fileblob.OpenBucket(dir string, opts *fileblob.Options); nil opts writes the .attrs sidecar.
</interfaces>
</context>
<tasks>
<task type="tracer" tdd="true">
<name>Task 1: StaticHandler and StaticHandlerPublic send nosniff and the stored Content-Disposition (tracer: Store's writer to the handler's response)</name>
<files>modules/lagoon/attach/static.go, modules/lagoon/attach/static_test.go</files>
<read_first>
- modules/lagoon/attach/static.go (whole file, 129 lines)
- modules/lagoon/attach/static_test.go (whole file, 174 lines)
- modules/lagoon/attach/inline.go (whole file, 44 lines: attachmentDisposition, uploadWriterOptions)
- modules/lagoon/attach/inline_test.go lines 40-120 (how TestWriteBlobDisposition builds memblob and fileblob buckets and calls writeBlob)
</read_first>
<behavior>
- storedDisposition("") and storedDisposition(" ") return "".
- storedDisposition returns its trimmed input for "attachment", "inline", `attachment; filename="a.png"` and " attachment ".
- storedDisposition returns "attachment" for "attachment;;", "attachment; filename" and "attachment\r\nX-Evil: 1".
- On memblob and on fileblob with sidecar metadata: a blob written with writeBlob(ctx, bucket, key, body, "text/html", 0) and fetched with GET through StaticHandler answers 200 with Content-Type text/html, Content-Disposition attachment, X-Content-Type-Options nosniff and the unchanged body.
- The same blob fetched with HEAD answers 200 with the same three headers and an empty body.
- A blob written with writeBlob(..., "image/png", 0) is served with Content-Type image/png, nosniff and no Content-Disposition header at all.
- On memblob, a blob written with bucket.WriteAll and ContentDisposition `attachment; filename="a.png"` (ContentType image/png) is served with that exact disposition; one written with ContentDisposition "attachment;;" (ContentType text/html) is served with Content-Disposition attachment.
- Through servePublicBlobs with an allow func that returns true, the text/html blob gets the same headers as through StaticHandler (the gated path shares the change).
- A missing blob answers 404 with nosniff and no Content-Disposition.
</behavior>
<action>
This task implements the todo's Solution, first bullet: both handlers send the stored disposition and X-Content-Type-Options nosniff, additively. Write the tests from the behavior block first and watch them fail to compile or fail, then implement.
1. In modules/lagoon/attach/static.go, add an unexported helper storedDisposition(raw string) string. It trims surrounding whitespace; an empty result returns "". If mime.ParseMediaType rejects the trimmed value, it returns attachmentDisposition (the existing constant in inline.go: fail closed, so malformed or injected metadata never reaches a response header). Otherwise it returns the trimmed value verbatim, parameters included, so the handler behaves like a public bucket that sends the stored header. Doc comment: the value of the stored Content-Disposition a handler sends; empty for none; attachment for a value mime.ParseMediaType rejects.
2. In servePublicBlobs, keep the method check, nil-bucket check, prefix strip, parsePublicBlobPath and the allow gate exactly where they are; the gate must still run before any bucket access (TestStaticHandlerPublicGate relies on it). Then:
- Right after the method check passes, set X-Content-Type-Options to nosniff on w.Header(), so every response the handler writes carries it (http.Error sets it on the error paths too; setting it up front keeps the success path explicit).
- After the gate and before NewReader, call bucket.Attributes(r.Context(), key). On error answer http.NotFound and return, the same as a NewReader error today.
- Keep the NewReader call, its 404 on error, the deferred Close and the Content-Type logic (reader.ContentType() with the defaultStaticContentType fallback) unchanged.
- Only after both Attributes and NewReader have succeeded, set Content-Disposition to storedDisposition(attrs.ContentDisposition) when that is non-empty, next to the Content-Type header and before the HEAD return, so GET and HEAD both carry it and no 404 ever does (http.Error does not remove a Content-Disposition set earlier).
- Leave stripStaticPrefix and parsePublicBlobPath untouched.
3. Update the doc comments. StaticHandler: after the existing description, say that every response carries X-Content-Type-Options: nosniff, and a served file gets its stored Content-Type and, when the blob has one, its stored Content-Disposition (attach.Store stores attachment for every type IsInlineContentType rejects; a stored value mime.ParseMediaType rejects is sent as attachment). Say that the handler derives no disposition from the type and sends no Content-Security-Policy, so a blob stored without a disposition is served inline with its type, and that reading the disposition costs one Attributes call per request. Keep the existing warning not to mount the ungated handler on the app origin. StaticHandlerPublic: add that it sends the same headers as StaticHandler. Signatures of StaticHandler, StaticHandlerPublic and servePublicBlobs do not change; no exported identifier is added.
4. In modules/lagoon/attach/static_test.go (package attach, Docker-free, must not skip under -short):
- TestStoredDisposition: a table over the storedDisposition cases in the behavior block, failure message naming the input (use %q).
- TestStaticHandlerSendsStoredDisposition: build memblob.OpenBucket(nil) and fileblob.OpenBucket(t.TempDir(), nil), each closed through t.Cleanup, and run the same subtests on both (t.Run per bucket name). Use disk names whose partition matches PartitionDirectory, for example "abc123xyz.html" and "def456uvw.png", keyed with BlobKey, and write them with writeBlob and the types text/html and image/png, limit 0, body such as <html><script>alert(1)</script></html> and a few bytes for the png. Serve through StaticHandler(bucket, "/storage/uploads") with httptest.NewRecorder for GET and HEAD, and through servePublicBlobs(bucket, "/storage/uploads", func that returns true, nil) for GET of the html blob. Assert the headers and bodies from the behavior block. For the png assert that w.Result().Header has no Content-Disposition key at all (Values returns an empty slice), not merely an empty string.
- On the memblob bucket only, write two more blobs with bucket.WriteAll and explicit blob.WriterOptions: an image/png with ContentDisposition `attachment; filename="a.png"` and a text/html with ContentDisposition "attachment;;", each under its own valid partition key, and assert the verbatim and the fail-closed value.
- A GET for a valid-shaped key that was never written (for example "/storage/uploads/mis/sin/g12/missing123.html" — check that its partition matches PartitionDirectory of its file name, or derive the path from BlobKey) answers 404 with nosniff and no Content-Disposition.
- Add the fileblob import; no new module dependency (inline_test.go already imports it).
Do not commit at the end of this task; Task 2 commits code, tests and docs together.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/summercms.go && go vet ./modules/lagoon/... ./modules/surf/... && go test -short -count=1 -v -run 'TestStoredDisposition|TestStaticHandler' ./modules/lagoon/attach && go test -short -count=1 ./modules/lagoon/... ./modules/surf/...</automated>
</verify>
<acceptance_criteria>
- `grep -c 'func storedDisposition(raw string) string' modules/lagoon/attach/static.go` prints 1.
- `grep -c 'bucket.Attributes(' modules/lagoon/attach/static.go` prints 1.
- `grep -c '"X-Content-Type-Options", "nosniff"' modules/lagoon/attach/static.go` prints 1.
- `git diff --quiet -- modules/lagoon/attach/inline.go modules/lagoon/attach/store.go modules/surf/uploads_test.go` exits 0: the writer side and the surf tests are untouched.
- `git diff -U0 -- modules/lagoon/attach/static.go > "$SCRATCH/oc8-static.diff"` exits 0 ($SCRATCH is the session scratchpad), and `grep -E '^[-+]func ' "$SCRATCH/oc8-static.diff"` prints only the added storedDisposition line.
- The -v run reports PASS (not SKIP) for TestStoredDisposition, TestStaticHandlerSendsStoredDisposition with both bucket subtests, TestStaticHandler, TestStaticHandlerServesThumbURL and TestStaticHandlerPublicGate.
- `go test -short ./modules/surf/...` passes with no surf edit, so TestUploadsMount and TestUploadsResponseHeaders still hold.
</acceptance_criteria>
<done>Both handlers send nosniff on every response and the validated stored disposition on GET and HEAD of a served blob; blobs without one are served as before. Store's writer and the handler are proven end to end on memblob and fileblob under -short. Nothing is committed yet.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: Gated Postgres assertion, lagoon README, storage and attachments docs, surf doc comment; commit Tasks 1 and 2</name>
<files>modules/lagoon/attach/lifecycle_test.go, modules/lagoon/README.md, docs/services/storage.md, docs/database/attachments.md, modules/surf/uploads.go</files>
<precondition>The Docker daemon is reachable for testcontainers (docker info succeeds). If the socket is denied although the user is in the docker group, run the Docker-backed test through sudo -u golem, as CLAUDE.md says.</precondition>
<read_first>
- modules/lagoon/attach/lifecycle_test.go lines 1-30 (imports) and 190-245 (TestStaticHandlerPublicLooksUpIsPublic)
- modules/lagoon/README.md line 44 (Features, attach bullet; the clause "static serving with an optional `is_public` gate (`attach.StaticHandlerPublic`)") and lines 207-208 (the two handler rows)
- docs/services/storage.md lines 98-165 (Serving files and Deploy note)
- docs/database/attachments.md lines 84-92 and 136-141
- modules/surf/uploads.go lines 29-45 (mountUploads doc comment)
</read_first>
<behavior>
- Through attach.StaticHandlerPublic with a real Postgres is_public lookup, a public row whose blob was written with ContentType text/html and ContentDisposition attachment answers GET 200 with Content-Disposition attachment and X-Content-Type-Options nosniff.
- Through the same handler, the existing public jpeg original answers 200 with nosniff and no Content-Disposition, and the private original still answers 404.
</behavior>
<action>
This task covers the gated half of the todo with a real database and the documentation rule from CLAUDE.md.
1. In modules/lagoon/attach/lifecycle_test.go, TestStaticHandlerPublicLooksUpIsPublic: keep every existing assertion. Add a third public row, for example DiskName "fed654cba.txt", FileName "note.txt", ContentType "text/html", IsPublic &pub, created with gdb.Create, and write its blob at attach.BlobKey of that disk name with bucket.WriteAll and blob.WriterOptions{ContentType: "text/html", ContentDisposition: "attachment"} (what attach.Store writes for an HTML body uploaded as note.txt). Serve GET for its URL and for the existing public jpeg original through h with httptest.NewRecorder and assert the headers from the behavior block (a small local helper returning the recorder is fine; leave the existing get helper's signature as it is). Add a one-line comment that the stored disposition and nosniff go through the is_public gate.
2. modules/lagoon/README.md:
- (a) Features, attach bullet: extend the clause about static serving so it says the handlers send each file's stored Content-Type and Content-Disposition with X-Content-Type-Options: nosniff, for example: static serving (`attach.StaticHandler`, with an optional `is_public` gate in `attach.StaticHandlerPublic`) that sends each file's stored Content-Type and Content-Disposition with `X-Content-Type-Options: nosniff`.
- (b) API table, `attach.StaticHandler` row: Serves stored files and thumbnails under a URL prefix with their stored Content-Type and Content-Disposition and `X-Content-Type-Options: nosniff`. The `attach.StaticHandlerPublic` row stays as it is (it already says "attach.StaticHandler plus").
3. docs/services/storage.md:
- Serving files, the paragraph that starts "Without the key, the application decides where files are served": after "mount `attach.StaticHandlerPublic` itself", add that it sends the stored Content-Type, the stored Content-Disposition (so a file `attach.Store` stored as an attachment downloads) and `X-Content-Type-Options: nosniff`, but not the route's sandboxing Content-Security-Policy, and it adds no disposition to a file stored without one (see the deploy note). Keep the separate-origin advice.
- Deploy note, the paragraph that starts "Objects written before this change": add that `attach.StaticHandler` and `attach.StaticHandlerPublic` send the stored disposition too, so the same caveat applies to them, while the built-in route also decides from the type.
- Deploy note, the file:// sentence at the end of the section: add that `attach.StaticHandler`, `attach.StaticHandlerPublic` and the built-in route read the sidecar, so the static-server case applies only to a web server reading the directory.
- Keep the `#deploy-note` heading and anchor, the nginx example and every existing fact.
4. docs/database/attachments.md:
- Line 87, after "`attach.StaticHandler` serves originals and thumbnails under that prefix; `attach.StaticHandlerPublic` does the same and answers 404 for a row whose `is_public` flag is false.": add that both send `X-Content-Type-Options: nosniff` and each file's stored Content-Type and Content-Disposition, and send no Content-Security-Policy, which is why the warning below still applies.
- Line 140 (the paragraph about attach.Store writing Content-Disposition: attachment): extend "downloads it instead of rendering it" to cover a browser that opens it from a public bucket or through `attach.StaticHandler` and `attach.StaticHandlerPublic`.
5. modules/surf/uploads.go, mountUploads doc comment only (no code change): replace the clause saying attach.StaticHandlerPublic sends only the stored type. The new wording: attach.Store also stores the attachment disposition with the blob and attach.StaticHandlerPublic sends it, but the route still decides from the type on every response, because blobs written earlier or outside attach.Store carry no disposition.
6. Run the docs checkers and fix any identifier, link or anchor they report. Use only identifiers that exist: attach.StaticHandler, attach.StaticHandlerPublic, attach.Store, attach.IsInlineContentType. Config keys are not checked automatically; keep storage.uploads.serve and storage.uploads.public_url spelled exactly as the pages already have them.
7. Commit Tasks 1 and 2 as one commit, staging exactly these paths by name:
- modules/lagoon/attach/static.go
- modules/lagoon/attach/static_test.go
- modules/lagoon/attach/lifecycle_test.go
- modules/lagoon/README.md
- docs/services/storage.md
- docs/database/attachments.md
- modules/surf/uploads.go
Message subject: fix(lagoon/attach): StaticHandler sends the stored Content-Disposition and nosniff (quick-261105-oc8). Body: a short bullet list (both handlers set X-Content-Type-Options nosniff; the stored disposition is read with one Attributes call after the is_public gate and sent on GET and HEAD, an unparsable value as attachment; blobs without one are served as before; README, storage and attachments pages, surf comment). Never stage everything at once. Leave other sessions' STATE.md, state.json, G15OFFICE.md and the untracked .gitkeep, .msd and quick-batches files alone. Add no co-author tag (user and project CLAUDE.md override the harness attribution reminder). Do not push or tag.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/summercms.go && go vet ./... && go test -short ./... && go test ./cmd/summer -run TestDocsTree && go run ./cmd/summer docs:build --check && go test -count=1 -v -run 'TestStaticHandlerPublicLooksUpIsPublic$' ./modules/lagoon/attach && go test -count=1 -run 'TestUploads' ./modules/surf</automated>
</verify>
<acceptance_criteria>
- `grep -c 'nosniff' modules/lagoon/README.md` prints at least 2 (Features bullet and the StaticHandler row).
- `grep -c 'attach.StaticHandler' docs/services/storage.md` prints at least 2, and `grep -c 'nosniff' docs/database/attachments.md` prints at least 2.
- `grep -c '^### Deploy note' docs/services/storage.md` prints 1 (the anchor survives).
- The Docker-backed -v run reports PASS, not SKIP, for TestStaticHandlerPublicLooksUpIsPublic. If the socket is denied, rerun through `sudo -u golem`.
- After committing, `SHA1=$(git log -1 --format=%H)` and `git show --name-only --format= "$SHA1"` list exactly the 7 paths above.
- `git show "$SHA1" -- modules/surf/uploads.go > "$SCRATCH/oc8-surf.diff"` exits 0, and every changed line in it (lines starting with a single + or -, excluding the +++/--- headers) starts with `//` after the sign: the surf change is comment-only.
- `git show "$SHA1" -- modules/lagoon/ modules/surf/ > "$SCRATCH/oc8-api.diff"` exits 0, and `grep -e '^[+-]func [A-Z]' -e '^[+-]type [A-Z]' -e '^[+-]var [A-Z]' -e '^[+-]const [A-Z]' "$SCRATCH/oc8-api.diff"` prints nothing: no exported identifier is added, removed or changed.
- `git log -1 --format=%B "$SHA1" > "$SCRATCH/oc8-msg.txt"` exits 0, and `grep -ci 'co-authored-by' "$SCRATCH/oc8-msg.txt"` prints 0.
</acceptance_criteria>
<done>One commit. Both handlers send nosniff and the stored disposition, proven Docker-free on memblob and fileblob and through the real is_public gate on Postgres. The lagoon README, both docs pages and the surf comment describe the behaviour and its limits. go vet, go test -short ./..., the docs checkers, the Docker-backed handler test and the surf uploads tests are green.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| bucket attributes → response headers | Blob metadata is written by attach.Store, but any process with bucket write access (or an S3 console user) can set an arbitrary Content-Disposition. The handler forwards it into a response header |
| attach.StaticHandler(Public) → browser | An application mounting a handler directly gets no CSP and no type-derived disposition. A rendering type served inline on a trusted origin is stored XSS |
| surf uploads route → attach.StaticHandlerPublic | The route wraps the handler and sets its own nosniff, CSP and type-derived disposition after the handler's headers |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-q261105oc8-01 | Elevation of privilege | An HTML, SVG or text upload stored by attach.Store and served inline by a directly mounted StaticHandler or StaticHandlerPublic | medium | mitigate | Task 1: servePublicBlobs sends the stored Content-Disposition (attachment for every non-inline type Store wrote). TestStaticHandlerSendsStoredDisposition writes through writeBlob and asserts the header on GET and HEAD; Task 2 asserts it through the real is_public gate |
| T-q261105oc8-02 | Tampering | Header injection or malformed values through a stored Content-Disposition | low | mitigate | storedDisposition sends a value only when mime.ParseMediaType accepts it and otherwise the bare attachment constant; a CR/LF value is a TestStoredDisposition case. Go's header writer also replaces CR/LF |
| T-q261105oc8-03 | Information disclosure | Content sniffing of a served blob turning a non-HTML type into a rendered document | low | mitigate | Task 1 sets X-Content-Type-Options: nosniff on every response of both handlers; asserted on 200 GET, 200 HEAD and 404 |
| T-q261105oc8-04 | Elevation of privilege | Blobs written before quick-261028-rqe or by writers that bypass attach.Store carry no disposition and are still served inline by the handlers | medium | transfer | Task 2's docs say the handlers send only the stored disposition, keep the separate-origin warning and the deploy-note backfill advice; the surf route keeps its type-derived disposition. Direct writers (fonoteka.go, sm-user-plugin avatar, sm-feedback-plugin screenshot) are recorded as follow-ups |
| T-q261105oc8-05 | Information disclosure | Probing private files through a new bucket call before the gate | low | mitigate | The Attributes call runs after the allow gate, so a denied or missing row still 404s without touching the bucket; TestStaticHandlerPublicGate (seen-before-NewReader) stays unmodified |
| T-q261105oc8-06 | Denial of service | One extra Attributes call per request (an S3 HEAD) on the handlers and the built-in route | low | accept | The reader does not expose the disposition in gocloud.dev v0.46.0; the cost is documented in the StaticHandler doc comment. Production deployments are advised to serve uploads from a separate origin or CDN |
| T-q261105oc8-SC | Tampering | npm/pip/cargo installs | low | accept | No new dependency. mime is stdlib; gocloud.dev/blob/fileblob is already a module dependency and already imported by tests in the package |
</threat_model>
<verification>
- go vet ./... and go test -short ./... are green at the commit.
- go test ./cmd/summer -run TestDocsTree and go run ./cmd/summer docs:build --check are green.
- Docker-backed: TestStaticHandlerPublicLooksUpIsPublic passes (not skipped), and go test -run 'TestUploads' ./modules/surf passes without -short.
- One commit containing exactly the 7 files_modified paths, no co-author tag, nothing pushed or tagged.
</verification>
<success_criteria>
- A blob attach.Store wrote for a non-inline type is served by attach.StaticHandler and attach.StaticHandlerPublic with Content-Disposition: attachment, on GET and HEAD.
- Every handler response carries X-Content-Type-Options: nosniff.
- A blob without a stored disposition is served exactly as before; no exported identifier changes; the surf route's observable headers are unchanged.
- The lagoon README, docs/services/storage.md, docs/database/attachments.md and the surf doc comment match the new behaviour.
</success_criteria>
<output>
Create `.planning/quick/261105-oc8-lagoon-attach-statichandler-and-statichandlerpublic-send-the/261105-oc8-SUMMARY.md` when done. List the follow-ups from the objective's "Not in scope" block in it so the orchestrator can file them.
</output>

View File

@@ -0,0 +1,75 @@
---
phase: quick-261105-oc8
plan: 01
subsystem: lagoon/attach
status: complete
tags: [security, uploads, headers, content-disposition, nosniff]
requires: [quick-261028-rqe]
provides:
- attach.StaticHandler and attach.StaticHandlerPublic send X-Content-Type-Options nosniff and the validated stored Content-Disposition
affects: [modules/surf uploads route (doc comment only)]
tech-stack:
added: []
patterns: ["fail-closed header forwarding: stored metadata validated with mime.ParseMediaType, else the bare attachment constant"]
key-files:
created: []
modified:
- modules/lagoon/attach/static.go
- modules/lagoon/attach/static_test.go
- modules/lagoon/attach/lifecycle_test.go
- modules/lagoon/README.md
- docs/services/storage.md
- docs/database/attachments.md
- modules/surf/uploads.go
decisions:
- "Handlers forward only the stored disposition; no type-derived disposition and no CSP (additive, the surf route keeps that role)"
- "Attributes call placed after the is_public gate and before NewReader; disposition set only after both succeed so a 404 never carries it"
requirements: [todo:2026-10-28-attach-static-handler-disposition]
duration: ~15min
completed: 2026-11-05
commits: 1
plan_head_before: 5aa846c5e85368b534e03a1d19f441bb34de193c
plan_head_after: 27c98bf22aa61add1b90904456dc37fec4310ca8
actuals:
tokens: 9000
tasks: 2
commits: 1
---
# Quick 261105-oc8: attach.StaticHandler sends stored Content-Disposition and nosniff Summary
Both `attach.StaticHandler` and `attach.StaticHandlerPublic` now set `X-Content-Type-Options: nosniff` on every response and forward the blob's stored Content-Disposition (read with one `bucket.Attributes` call after the `is_public` gate, validated by `mime.ParseMediaType`, fail-closed to `attachment`) on GET and HEAD, so an HTML/SVG/PDF/text upload stored by `attach.Store` downloads instead of rendering when an app mounts the handlers directly.
## Commit
- `27c98bf` fix(lagoon/attach): StaticHandler sends the stored Content-Disposition and nosniff (quick-261105-oc8) — exactly the 7 planned paths, no co-author tag, not pushed or tagged.
## Tasks
1. **Task 1 (tracer, TDD):** RED: `TestStoredDisposition` and `TestStaticHandlerSendsStoredDisposition` failed to compile (`undefined: storedDisposition`). GREEN: unexported `storedDisposition` helper, nosniff after the method check, `Attributes` after the gate, disposition set next to Content-Type before the HEAD return. Tests run on memblob and fileblob (sidecar) through `writeBlob`, GET and HEAD, ungated and gated (`servePublicBlobs` with an allow-all func), verbatim `attachment; filename="a.png"`, fail-closed `attachment;;`, png without any Content-Disposition key, 404 with nosniff and no disposition. Tracer gate re-run passed.
2. **Task 2:** `TestStaticHandlerPublicLooksUpIsPublic` adds a public `text/html` row (`fed654cba.txt`) with stored `attachment` and asserts disposition + nosniff through the real Postgres `is_public` gate; the public jpeg gets nosniff and no disposition; existing assertions untouched. Lagoon README (Features bullet, `attach.StaticHandler` row), `docs/services/storage.md` (Serving files paragraph, deploy-note caveat, `file://` sidecar sentence), `docs/database/attachments.md` (handler paragraph, Store disposition paragraph), surf `mountUploads` doc comment (comment-only diff).
## Verification
- `go vet ./...`, `go test -short ./...`: green.
- `go test ./cmd/summer -run TestDocsTree`, `go run ./cmd/summer docs:build --check`: green ("no problems found").
- Docker-backed `TestStaticHandlerPublicLooksUpIsPublic`: PASS (not skipped). `go test -run TestUploads ./modules/surf` (no -short): PASS with no surf test edit.
- `inline.go`, `store.go`, `uploads_test.go` untouched; static.go diff adds only `func storedDisposition`; surf diff is comment-only; no exported identifier added/removed/changed in modules/lagoon or modules/surf (the only `func [A-Z]` lines in the diff are the two new `Test*` functions in `static_test.go`).
## Deviations from Plan
None - plan executed exactly as written. (The missing-blob test uses `BlobKey("mis123sin.html")` so its partition matches.)
## Threat Flags
None beyond the plan's threat model. Note for the surf route: a blob stored with a disposition on an inline raster type (which `attach.Store` never writes) would now have that stored disposition forwarded through the route too; the route's own type-derived `attachment` for non-inline types is unchanged.
## Follow-ups (not in scope; for the orchestrator to file)
- Blob writers that bypass `attach.Store` should adopt `attach.IsInlineContentType` / store the disposition: fonoteka.go `storeUpload` and `StorePublicFile` (see todo `2026-10-28-fonoteka-uploads-use-disk-extension.md`), the sm-user-plugin avatar writer, the sm-feedback-plugin screenshot writer.
- Backfilling the disposition on objects already in a bucket is an operator task (documented in `docs/services/storage.md#deploy-note`).
- Move todo `2026-10-28-attach-static-handler-disposition` to completed and post the g15office comment (`knuu7fil`).
## Self-Check: PASSED
- All 7 modified files exist; commit `27c98bf` present in `git log`.

View File

@@ -0,0 +1,249 @@
---
phase: quick-261105-oc9
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- ../sm-demo-app/plugins/demo/chat_api.go
- ../sm-demo-app/plugins/demo/classes/members.go
- ../sm-demo-app/plugins/demo/console/seed.go
- ../sm-demo-app/plugins/demo/console/seed_chat.go
- ../sm-demo-app/plugins/demo/console/seed_friends.go
- ../sm-demo-app/plugins/demo/plugin.go
- ../sm-demo-app/plugins/demo/updates/updates.go
- ../sm-demo-app/go.mod
- ../sm-demo-app/chat_test.go
- ../sm-demo-app/chat_smoke_test.go
- ../sm-demo-app/seed_chat_test.go
- ../sm-demo-app/README.md
- ../sm-demo-app/scripts/check-moderation.sh
- ../sm-demo-app/scripts/check-local.sh
- ../sm-demo-app/deploy/nginx/demo.summercms.io.conf
- ../sm-demo-app/scripts/check-deploy.sh
- ../sm-demo-app/scripts/check-live.sh
- ../sm-demo-app/DEPLOY.md
autonomous: true
requirements:
- quick-261105-oc9
must_haves:
truths:
- "GET /_demo/api/v1/chat/members writes nothing: a member without a handle is listed with handle \"\" and its users.handle is still NULL after the call (no handle assignment in a GET, so two concurrent first loads cannot race on the same rows)."
- "GET /_demo/api/v1/chat/members answers 200 for a community of more than 65535 members: the query filters users with the community's membership condition as a subquery (WHERE id <> caller AND <memberWhere>), never an id list bound as parameters."
- "demo:seed has a step \"member handles\" right after \"chat personas\" that gives every user without a handle one (the visitor, rows created outside registration): \"updated\" when it assigned any, \"exists\" otherwise."
- "The default moderation lists are written once, by golem15.demo's own migration, which runs right after golem15.moderation's migration creates the settings row and fills the lists only while both are empty. demo:seed no longer touches golem15_moderation_settings, so an admin who empties both lists keeps them empty across demo:seed and demo:reset."
- "scripts/check-local.sh passes every member JWT to curl through a config on stdin (curl -K -) from request(); no curl argv carries a bearer token. The visitor's login body goes to curl from a file in the 0700 temp directory, not argv."
- "deploy/nginx/demo.summercms.io.conf proxies only /livekit/rtc (and the paths below it, /rtc/validate and /rtc/v1 included) to LiveKit's /rtc on 127.0.0.1:7890; every other /livekit/ path answers 404 from nginx, so LiveKit's Twirp RoomService is reachable on loopback only. check-deploy.sh enforces the shape, check-live.sh probes it. The vhost is committed only, not installed on rome."
- "DEPLOY.md's VAPID step runs with set -eo pipefail, generates the pair into a variable, refuses to write unless both keys are non-empty, and appends all three lines with one tee; no key is ever printed."
- "go vet ./... and go test -short ./... in sm-demo-app are green at every commit; the Docker-backed tests named in each task pass; nothing is pushed, tagged or deployed; commits carry no co-author tag."
artifacts:
- path: ../sm-demo-app/plugins/demo/classes/members.go
provides: "OtherMembers(ctx, db, exceptID): the community's members except one user, ordered by id, read-only, membership as a subquery"
- path: ../sm-demo-app/plugins/demo/chat_api.go
provides: "chatMembers reads through classes.OtherMembers; no MemberIDs id list, no handle writes"
- path: ../sm-demo-app/plugins/demo/updates/updates.go
provides: "All(): the golem15.demo migration that fills golem15.moderation's default lists once"
- path: ../sm-demo-app/plugins/demo/plugin.go
provides: "Plugin implements pact.HasMigrations (Migrations returns updates.All())"
- path: ../sm-demo-app/deploy/nginx/demo.summercms.io.conf
provides: "location ^~ /livekit/rtc to http://127.0.0.1:7890/rtc; location ^~ /livekit/ answers 404"
key_links:
- from: "GET /_demo/api/v1/chat/members (plugins/demo/chat_api.go chatMembers)"
to: "plugins/demo/classes/members.go OtherMembers"
via: "the unexported memberWhere condition of the classes package (chat_context.go, not edited)"
pattern: "OtherMembers"
- from: "lagoon.Migrate / summer migrate (party activation order: golem15.demo Requires golem15.moderation)"
to: "plugins/demo/updates All() via Plugin.Migrations()"
via: "history table summer_migrations_golem15_demo"
pattern: "HasMigrations"
- from: "scripts/check-local.sh request()"
to: "curl -K - (config on stdin)"
via: "printf of the header line piped into curl"
pattern: "--jwt"
---
<objective>
Close the five sm-demo-app todos from the phase 20 code review in the sibling repo /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app, inside that repo only:
1. demo-chat-members-read-only.md (IN-09): GET /_demo/api/v1/chat/members becomes read-only and selects members with the membership subquery instead of an id list; missing handles are assigned in demo:seed.
2. demo-seed-moderation-lists-once.md (IN-05): the default moderation lists are seeded once, by a golem15.demo migration, not on every demo:seed.
3. check-local-jwt-out-of-argv.md (IN-03): check-local.sh passes member JWTs to curl through a config on stdin.
4. demo-nginx-livekit-rtc-only.md (IN-06): nginx proxies only LiveKit's /rtc paths; check-deploy and check-live follow.
5. demo-vapid-runbook-pipefail.md (IN-08): the VAPID runbook step uses pipefail, generates into a variable, checks both keys and appends with one tee.
Purpose: remove a write-in-GET race and a 500 past Postgres' 65535 bind parameters on a growing demo, stop deploys from undoing an admin's moderation choice, keep tokens out of /proc/*/cmdline, shrink LiveKit's public surface and make the VAPID rebuild step fail safe.
Output: five sm-demo-app commits (one per todo), no framework change, no shared-plugin change, no frontend change (the members response shape is unchanged).
Claude's discretion choices (no CONTEXT.md exists for a quick item):
- "Seed only once" is implemented as a golem15.demo data migration (the todo's first option, "insert the lists when the settings row is created"): gormigrate records it in summer_migrations_golem15_demo, demo:reset keeps settings and migrations, and no flag table is needed. This is the demo plugin's first migration; the plugin doc comment and README change accordingly.
- The members helper goes into a NEW file plugins/demo/classes/members.go (same package as the unexported memberWhere), so this item does not edit plugins/demo/classes/chat_context.go, which item 261105-oc6 edits for its pin policy.
- The "member handles" seed step covers every user without a handle (as user:backfill-handles does), not only members.
- check-local.sh's visitor login body (it carries the local visitor password) also leaves argv, through a file in the script's 0700 temp directory: same leak class, same fix, two lines.
Closing the five todos (moving them to .planning/todos/done/ with a "## Closed" note and syncing g15office) is the orchestrator's closing docs step, not part of the executor's sm-demo-app commits.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/STATE.md
@CLAUDE.md
@.planning/todos/pending/demo-chat-members-read-only.md
@.planning/todos/pending/demo-seed-moderation-lists-once.md
@.planning/todos/pending/check-local-jwt-out-of-argv.md
@.planning/todos/pending/demo-nginx-livekit-rtc-only.md
@.planning/todos/pending/demo-vapid-runbook-pipefail.md
@../sm-demo-app/README.md
@../sm-demo-app/plugins/demo/chat_api.go
@../sm-demo-app/plugins/demo/classes/chat_context.go
@../sm-demo-app/plugins/demo/console/seed.go
@../sm-demo-app/plugins/demo/console/seed_friends.go
Facts established while planning (sm-demo-app at da03c06, working tree clean):
- chat_api.go chatMembers (lines 319-367) calls classes.MemberIDs, binds every id into "id IN ? AND id <> ?", then calls the user plugin's handle assignment for each member lacking a handle. memberWhere (classes/chat_context.go) is an unexported const: activated, not deleted, no user_throttle row with is_banned. classes.MemberIDs stays (community.Members uses it).
- Registration already assigns handles (sm-user-plugin controllers/registration.go, used by social login too) and so does the admin create. Rows without a handle come from direct inserts: demo:seed's visitor (seed.go visitor.seed), legacy rows, and test helpers (demo_api_test.go apiDemo.member uses a.DB.Create without a handle).
- seed_chat.go seedPersonas already assigns persona handles at creation.
- golem15.moderation's migration 202610280001 creates golem15_moderation_settings and inserts row id 1 with NULL lists. lagoon runs each plugin's set in party activation order with history table summer_migrations_<id with dots as underscores>; golem15.demo Requires golem15.moderation. internal/demotest migrates a template database with every plugin (lagoon.Migrate), so test databases already carry the demo migration's effect.
- pact.HasMigrations is Migrations() []*gormigrate.Migration. gormigrate v2.1.7 is in sm-demo-app go.mod as indirect only.
- Tests that pin the current lists behaviour: seed_chat_test.go TestSeedChat (lines 181-219), chat_smoke_test.go chatSeedSteps (line 226-230, includes "moderation lists") and TestSeedChatSmoke (line 301). TestDemoChatMembers (chat_test.go 320-372) asserts every listed member has a handle, which members created by apiDemo.member only had because the GET wrote one.
- check-local.sh runs under set -euo pipefail; request() is at lines 124-130; 15 calls pass a bearer header literally and 12 more through local auth variables (check_quizzes, check_forum, check_call); visitor_jwt (lines 325-336) puts the login JSON in -d. check-moderation.sh request() (lines 80-93) is the pattern to copy.
- nginx: location ^~ /livekit/ at conf lines 355-375 proxies the whole LiveKit HTTP surface. check-deploy.sh lines 26-31 (header) and 329-341 (python block) pin that location; check-live.sh lines 40-42 (header) and 292-298 probe /livekit/rtc/validate. DEPLOY.md mentions /livekit/ at lines 19, 364, 370, 510, 839, 916; README lines 280 and 282 describe check-deploy and check-live.
- DEPLOY.md VAPID step: lines 533-547; other remote snippets in DEPLOY.md already use set -euo pipefail.
- Baseline: go vet ./... and go test -short ./... green; scripts/check-deploy.sh prints "check-deploy: ok"; shellcheck -S error is clean on check-local.sh, check-live.sh, check-deploy.sh; Docker is reachable for the testcontainers tests (if the socket is denied, run them through sudo -u golem, per the framework CLAUDE.md).
</context>
<tasks>
<task type="tracer" tdd="true">
<name>Task 1: GET /_demo/api/v1/chat/members reads only, through the membership subquery; demo:seed assigns missing handles (IN-09)</name>
<files>../sm-demo-app/plugins/demo/classes/members.go, ../sm-demo-app/plugins/demo/chat_api.go, ../sm-demo-app/plugins/demo/console/seed.go, ../sm-demo-app/plugins/demo/console/seed_chat.go, ../sm-demo-app/chat_test.go, ../sm-demo-app/seed_chat_test.go, ../sm-demo-app/README.md</files>
<behavior>
- TestDemoChatMembers (rewritten): the four personas are listed with their handles (ada, ben, ola, tomek); the other member created by apiDemo.member (no handle) is listed with handle "" and, after the GET, SELECT handle FROM users for that id is still NULL; the caller and the banned user are not listed; a banned caller gets 403; after mustSeed runs again, the same GET lists the other member with a non-empty handle. Red on the current code: the GET writes the handle.
- TestDemoChatMembersManyMembers (new): after bootAPI, one INSERT ... SELECT FROM generate_series(1, 66000) adds 66000 activated users (email 'bulk-' || g || '@example.com', password 'x', is_activated true, created_at and updated_at now()); a member's GET answers 200 and lists at least 66000 members. Red on the current code: 500 from the bind-parameter limit.
- TestSeedChat: with the visitor configured, the first demo:seed reports "member handles" as updated and the visitor's users.handle is non-empty; the second run reports exists. TestSeedChatWithoutVisitor: "member handles" reports exists (personas get handles at creation).
</behavior>
<action>
Work in /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app. RED first: change the tests in the behavior block (TestDemoChatMembers and the new TestDemoChatMembersManyMembers in chat_test.go, the step assertions in seed_chat_test.go; do not change apiDemo.member in demo_api_test.go, its handle-less rows are what the test needs), run them and note the failures for the SUMMARY. Do not commit red tests: the repo keeps go test green at every commit.
GREEN:
1. New file plugins/demo/classes/members.go (package classes; do not edit chat_context.go, item 261105-oc6 edits it). Add OtherMembers(ctx context.Context, db *gorm.DB, exceptID uint) ([]usermodels.User, error): nil db gives an empty slice; otherwise query the user plugin's User model with Select of id, name, surname and handle, Where "users.id <> ?" exceptID, Where(memberWhere), Order "users.id", Find. It never writes. Doc comment: the community's members except one user, ordered by id, read-only; the membership condition stays in SQL, so no id list is bound however large the community grows.
2. plugins/demo/chat_api.go chatMembers: keep the caller resolution and the IsMember 403; replace the MemberIDs call, the id-list query and the per-member handle assignment with one OtherMembers call (500 on error); build chatMemberJSON from each row with deref as now (an absent handle is ""). Drop the imports that become unused. Rewrite its doc comment: every member but the caller, ordered by id, read-only; the handle is the user plugin's, assigned at registration or by demo:seed, empty for a row that has none yet; is_bot always false.
3. plugins/demo/console/seed_chat.go: add seedMemberHandles(ctx) returning func(*gorm.DB) (string, error). It finds every user whose handle IS NULL or trims to '' (the GORM User model, ordered by id) and calls the user plugin's handle assignment on each inside the step's transaction, exactly as seedPersonas does for a new persona; it returns "updated" when it assigned at least one handle, "exists" otherwise.
4. plugins/demo/console/seed.go: in runSeed's steps insert {"member handles", seedMemberHandles(ctx)} directly after the "chat personas" step. Add "member handles" to SeedCommand's Description (after "the chat personas").
5. README.md: the GET /_demo/api/v1/chat/members row (line 173) says the call reads only and a member without a handle shows an empty one until demo:seed assigns it; the Seed list (around line 123) mentions the handles for users without one; the Testing paragraph (lines 342-353) lists TestDemoChatMembersManyMembers next to TestDemoChatMembers.
Run gofmt on the touched Go files, go vet ./..., go test -short ./..., then the Docker tests below. Commit in sm-demo-app, staging these paths explicitly, message "fix: GET /_demo/api/v1/chat/members reads only and selects members with a subquery", body naming IN-09 and the new demo:seed step "member handles". No co-author tag.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app && test -z "$(gofmt -l plugins/demo *.go)" && go vet ./... && go test -short ./... && go test -count=1 -run 'TestDemoChatMembers|TestSeedChat|TestDemoDMs|TestDemoChatBootstrap|TestDemoChatTracer' . 2>&1 | tail -5 && git log -1 --format='%h %s' && git show --stat --format= HEAD</automated>
</verify>
<done>GET /_demo/api/v1/chat/members answers from one read-only query with the membership subquery: a handle-less member stays NULL in the database and shows "" in the answer, 66000 members answer 200; demo:seed's "member handles" step assigns the missing handles (updated, then exists); README updated; vet, short tests and the named Docker tests pass; one sm-demo-app commit.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: the default moderation lists are seeded once, by a golem15.demo migration (IN-05)</name>
<files>../sm-demo-app/plugins/demo/updates/updates.go, ../sm-demo-app/plugins/demo/plugin.go, ../sm-demo-app/plugins/demo/console/seed_friends.go, ../sm-demo-app/plugins/demo/console/seed.go, ../sm-demo-app/go.mod, ../sm-demo-app/seed_chat_test.go, ../sm-demo-app/chat_smoke_test.go, ../sm-demo-app/scripts/check-moderation.sh, ../sm-demo-app/README.md</files>
<behavior>
- TestSeedChat: before the first demo:seed, golem15_moderation_settings row 1 already holds the defaults (buy followers, viagra, bit.ly) and summer_migrations_golem15_demo has the migration's id; demo:seed's output has no "moderation lists" line.
- TestSeedChat: after an admin sets both lists to '' (and again with both NULL), two demo:seed runs leave both lists empty. Red on the current code: the seed refills them. The existing "an admin's own list survives a later seed" check stays.
- chatSeedSteps no longer lists "moderation lists"; TestSeedChatSmoke's "default moderation lists were filled" assertion still holds (the migration filled them) and its settings fingerprint across demo:reset still matches.
</behavior>
<action>
Work in /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app. RED first: change seed_chat_test.go and chatSeedSteps in chat_smoke_test.go as in the behavior block, run TestSeedChat and note the failure; do not commit red tests.
GREEN:
1. New package plugins/demo/updates, file updates.go. Move defaultBannedWords and defaultBannedLinks (same values, same comment about mild defaults) here from console/seed_friends.go. Define one gormigrate migration with ID "202611050001_seed_golem15_moderation_lists" whose Migrate runs the exact UPDATE statement seedModerationLists runs today (moderation settings row id 1, only while both lists trim to empty), moved here unchanged; its Rollback returns nil (from then on the lists belong to the admin). Export All() []*gormigrate.Migration returning it. Doc comment: golem15.demo's migrations; this one gives golem15.moderation's settings row the default lists once, right after golem15.moderation's own migration creates it (golem15.demo requires golem15.moderation, so its set runs later), and only while both lists are empty, so on an existing database whose lists were already seeded it changes nothing and is just recorded.
2. plugins/demo/plugin.go: add pact.HasMigrations to the interface assertion block and func (p *Plugin) Migrations() []*gormigrate.Migration returning updates.All(). Replace "It adds no admin screens or migrations of its own." in the package doc with: no admin screens; one migration, which fills golem15.moderation's default word and link lists once.
3. plugins/demo/console/seed_friends.go: delete seedModerationLists and the two constants. plugins/demo/console/seed.go: delete the {"moderation lists", ...} step and drop "the moderation lists" from SeedCommand's Description.
4. go.mod: gormigrate is now imported directly. Hand-move the github.com/go-gormigrate/gormigrate/v2 v2.1.7 line from the indirect block into the first require block without the indirect marker (keep the version; do not run go mod tidy, the workspace replaces would make it reach for the network). go.sum does not change.
5. scripts/check-moderation.sh header (line 10): the lists the controls guard against are those that differ from the demo migration's defaults, no longer demo:seed's. Comment only.
6. README.md: the Seed list (line 124) drops "the default moderation lists"; the Moderation paragraph (around line 192) says golem15.demo's migration fills a short default list once, when the settings row is new, and an admin who empties both lists keeps them empty; the Reset paragraph's "(the moderation lists included)" stays true.
Run gofmt, go vet ./..., go test -short ./..., then the Docker tests below. Commit in sm-demo-app, staging these paths explicitly, message "fix: seed the default moderation lists once, in a golem15.demo migration", body naming IN-05 and that an admin's emptied lists now survive deploys. No co-author tag.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app && test -z "$(gofmt -l plugins/demo *.go)" && go vet ./... && go test -short ./... && go test -count=1 -run 'TestSeedChat|TestDemoModeration|TestResetKeepsPlans|TestBootAllPlugins|TestGoModRequiresTags' . 2>&1 | tail -5 && test "$(grep -hv '^[[:space:]]*//' plugins/demo/console/*.go | grep -c 'golem15_moderation_settings')" = 0 && grep -q 'func (p \*Plugin) Migrations()' plugins/demo/plugin.go && git log -1 --format='%h %s' && git show --stat --format= HEAD</automated>
</verify>
<done>golem15.demo carries one migration that fills the default lists once; demo:seed and the console package no longer touch golem15_moderation_settings; lists an admin emptied stay empty after demo:seed; tests, check-moderation comment and README updated; vet, short tests and the named Docker tests pass; one sm-demo-app commit.</done>
</task>
<task type="auto">
<name>Task 3: check-local JWTs through a curl config (IN-03), nginx proxies only LiveKit's /rtc (IN-06), VAPID runbook with pipefail (IN-08)</name>
<files>../sm-demo-app/scripts/check-local.sh, ../sm-demo-app/deploy/nginx/demo.summercms.io.conf, ../sm-demo-app/scripts/check-deploy.sh, ../sm-demo-app/scripts/check-live.sh, ../sm-demo-app/DEPLOY.md, ../sm-demo-app/README.md</files>
<action>
Work in /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app. Three commits, in this order, each staging only its own paths. No co-author tags. Nothing is pushed and nothing is installed on rome.
Commit A, scripts/check-local.sh (IN-03):
- request() takes an optional leading pair --jwt JWT before METHOD URL. With a non-empty JWT it pipes one config line, header = "Authorization: Bearer JWT" written with printf (a builtin, so the token never reaches an argv), into curl with -K - and otherwise the same curl flags, output files and the same fallback to 000 as now (the script runs under pipefail, so a curl failure still prints 000). Without --jwt, or with an empty JWT, it runs exactly as now. Copy the shape of check-moderation.sh's request() (lines 80-93). Update the comment above it to "request [--jwt JWT] METHOD URL [curl args...]" and say the token goes through a curl config on stdin, never argv.
- Every call that today passes a bearer header as a -H argument, literally or through the auth locals of check_quizzes, check_forum and check_call (27 calls: realtime, decks, quizzes, forum, friends, call, herald), passes --jwt with the matching variable ($jwt, $a_jwt, $b_jwt) instead. Remove the auth locals and their declarations.
- visitor_jwt: write the login JSON (the python3 one-liner's output, unchanged) to "$TMP/login.json" and pass -d @"$TMP/login.json", so the local visitor password leaves argv too ($TMP is the script's mktemp -d directory, mode 0700).
- If the local stack happens to be up (scripts/dev.sh up), also run scripts/check-local.sh realtime decks quizzes forum friends call herald and record the result; it is not required.
- Commit "test: check-local passes member JWTs to curl through a config on stdin" (body: IN-03).
Commit B, LiveKit signalling only (IN-06):
- deploy/nginx/demo.summercms.io.conf: replace the location ^~ /livekit/ block (lines 355-375) with two blocks. First location ^~ /livekit/rtc with proxy_pass http://127.0.0.1:7890/rtc; and every directive the old block had (proxy_http_version 1.1, Upgrade and Connection upgrade, Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto, proxy_read_timeout 7d, proxy_send_timeout 7d, proxy_buffering off). Then location ^~ /livekit/ with only return 404;. Keep tab indentation and the closing brace on its own tab-indented line (check-deploy's regexes rely on it). Rewrite the comment: livekit-client appends /rtc (and /rtc/validate, /rtc/v1) to livekit_url wss://demo.summercms.io/livekit, so only that prefix reaches LiveKit's /rtc; the rest of LiveKit's HTTP surface, the Twirp RoomService included, stays on loopback for the Go binary (livekit_admin_url), and nginx answers 404 for any other /livekit/ path. Keep the media and timeout sentences.
- scripts/check-deploy.sh: in the python block (lines 329-341) require the location ^~ /livekit/rtc block to contain proxy_pass http://127.0.0.1:{lk_port}/rtc; and each WebSocket directive, require the location ^~ /livekit/ block to contain return 404; and no proxy_pass, and require exactly one proxy_pass to the LiveKit port in the whole file; every mismatch is its own problems line as now. Update the header comment (lines 28-30) to describe the two locations. The production livekit_url check stays wss://demo.summercms.io/livekit.
- scripts/check-live.sh: keep the /livekit/rtc/validate probe; add a probe that POSTs {} as JSON to /livekit/twirp/livekit.RoomService/ListRooms through the get helper (extra curl args go before the URL) and requires 404 (LiveKit itself would answer 401), with its own bad line. Update the header comment (lines 40-42). Until the new vhost is installed on rome this probe fails there; that is expected and documented below.
- DEPLOY.md: the Overview tree (line 19) shows /livekit/rtc to 127.0.0.1:7890 and the rest of /livekit/ as 404; the port table row for 7890 (line 364) says browsers reach only the signal server through nginx /livekit/rtc and the RoomService is reachable by the Go binary on loopback only; lines 510 and 839 name /livekit/rtc; the check-live description (around line 916) adds the 404 for the rest of /livekit/. Add a short pending note in the "When deploy/nginx/demo.summercms.io.conf changed" procedure (or next to the "Applied on rome" record): the /livekit/rtc-only vhost is committed but not applied on rome; installing it needs its own go-ahead; until then check-live.sh reports the RoomService probe. Keep "Disallow: /livekit" in robots.
- README.md lines 280 and 282: check-deploy covers "the LiveKit /rtc-only location", check-live covers "/livekit/rtc/validate from LiveKit, the rest of /livekit/ 404".
- Run scripts/check-deploy.sh (must print check-deploy: ok), bash -n and shellcheck -S error on check-deploy.sh and check-live.sh. Commit "fix(deploy): nginx proxies only LiveKit's /rtc paths" (body: IN-06; the vhost is not installed on rome).
Commit C, DEPLOY.md VAPID step (IN-08), lines 533-547:
- Keep the build-machine part (source the secrets file, printf the address into $RSH $ROME) and the remote script's single-quoted form. The remote script starts with set -eo pipefail (if rome's login shell lacked pipefail it would stop before writing anything, which is still safe), reads the address, keeps the empty-address guard and the "already in .env" guard, then assigns the output of the herald:vapid-generate --json -q run (same sudo -u summercms-demo SUMMER_ENV=production ./bin/demo.new) to a variable, extracts .public_key and .private_key with jq -r and a // empty fallback into two variables, exits with "herald:vapid-generate returned no key pair" unless both are non-empty, and only then appends all three lines (PUBLIC_KEY, PRIVATE_KEY, SUBJECT=mailto:address) with one printf piped into one sudo tee -a .en[v] >/dev/null. No echo, no set -x, nothing prints a key; the final grep -c check (expects 3) stays. One sentence under the block: a failed generation now writes nothing, so a re-run needs no hand edit.
- Dry-run it in the scratchpad before committing: copy the remote script text into a file, run it with bash against a temp directory holding an .env and a stub bin/demo.new, with a sudo shim on PATH that drops -u USER and runs the rest through env. Check: the stub printing a JSON pair appends exactly three lines; a failing stub, and a stub printing JSON without private_key, both exit non-zero and leave .env byte-identical; a second run stops at "already in .env". Record the outcome in the SUMMARY.
- Commit "docs: the VAPID step runs with pipefail and appends the keys only when both exist" (body: IN-08).
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app && bash -n scripts/check-local.sh && bash -n scripts/check-live.sh && bash -n scripts/check-deploy.sh && shellcheck -S error scripts/check-local.sh scripts/check-live.sh scripts/check-deploy.sh && test "$(grep -v '^[[:space:]]*#' scripts/check-local.sh | grep -c 'Authorization')" = 1 && test "$(grep -c -- '--jwt' scripts/check-local.sh)" -ge 27 && grep -q 'curl .*-K -' scripts/check-local.sh && grep -q 'location \^~ /livekit/rtc {' deploy/nginx/demo.summercms.io.conf && grep -q 'proxy_pass http://127.0.0.1:7890/rtc;' deploy/nginx/demo.summercms.io.conf && scripts/check-deploy.sh 2>&1 | tail -1 | grep -qx 'check-deploy: ok' && grep -q 'livekit.RoomService/ListRooms' scripts/check-live.sh && awk '/^The VAPID keys, after/,/^After the release, `GET \/_herald/' DEPLOY.md | grep -q 'set -eo pipefail' && test "$(awk '/^The VAPID keys, after/,/^After the release, `GET \/_herald/' DEPLOY.md | grep -c 'tee -a')" = 1 && go vet ./... && go test -short ./... && git log -3 --format='%h %s' && git status --short</automated>
</verify>
<done>check-local.sh carries no bearer token in any curl argv (one Authorization line, inside request()'s printf) and the visitor login body comes from a file; nginx proxies only /livekit/rtc to LiveKit and answers 404 for the rest of /livekit/, check-deploy enforces it and passes, check-live probes the RoomService 404; the VAPID step uses pipefail, a variable, a both-keys check and one tee, dry-run evidence recorded; DEPLOY.md and README describe the new shape and the pending vhost go-ahead; three sm-demo-app commits; working tree clean apart from other sessions' files.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| internet -> nginx (demo.summercms.io) | anonymous traffic reaches every proxied path, /livekit/* included |
| member JWT -> Go (/_demo/api/v1/chat/members) | any authenticated member triggers the query; the community grows without a reset |
| admin settings -> deploy (demo:seed) | release automation runs against admin-owned settings rows |
| local user -> /proc/*/cmdline | other local users read process arguments of check-local's curl calls |
| build machine -> rome over SSH | the VAPID step writes secrets into /srv/summercms-demo/.env |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-oc9-01 | D | chat_api.go chatMembers | medium | mitigate | membership as a SQL subquery (OtherMembers), no bound id list; 66000-member test answers 200 (Task 1) |
| T-oc9-02 | T | chat_api.go chatMembers | low | mitigate | the GET writes nothing; handles are assigned at registration and in demo:seed's "member handles" step; test proves the row stays NULL after a GET (Task 1) |
| T-oc9-03 | T | console/seed.go, updates/updates.go | medium | mitigate | lists seeded once by a recorded migration; demo:seed no longer writes golem15_moderation_settings; test proves emptied lists survive demo:seed (Task 2) |
| T-oc9-04 | I | scripts/check-local.sh | low | mitigate | JWTs to curl through a config on stdin (printf builtin), visitor login body from a 0700 temp file; gate: one non-comment Authorization line (Task 3) |
| T-oc9-05 | E | nginx /livekit/ (LiveKit Twirp RoomService) | medium | mitigate | only ^~ /livekit/rtc is proxied; the rest of /livekit/ answers 404; check-deploy enforces, check-live probes ListRooms for 404 (Task 3) |
| T-oc9-06 | I | DEPLOY.md VAPID step | medium | mitigate | keys only in shell variables and one printf piped to sudo tee; no echo or set -x; pipefail plus both-keys check means a failed generation writes nothing (Task 3) |
| T-oc9-07 | T | rome vhost | low | accept | the nginx change is committed, not installed; installation is a separate go-ahead, documented in DEPLOY.md |
| T-oc9-SC | T | package installs | low | accept | no install: gormigrate v2.1.7 is already in go.mod and go.sum, only its indirect marker moves |
</threat_model>
<verification>
- In /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app: go vet ./... and go test -short ./... green after each of the five commits; the Docker tests TestDemoChatMembers, TestDemoChatMembersManyMembers, TestSeedChat, TestSeedChatWithoutVisitor, TestSeedChatSmoke, TestDemoModeration, TestResetKeepsPlans pass.
- scripts/check-deploy.sh prints check-deploy: ok; shellcheck -S error clean on the three scripts.
- git log shows five new commits (Task 1, Task 2, Task 3 A/B/C), none with a co-author tag; git status shows no leftover sm-demo-app change from this item; nothing pushed or tagged; nothing applied on rome.
- No file outside sm-demo-app changed by the executor (the plan and SUMMARY under summercms.go/.planning/quick are the orchestrator's).
</verification>
<success_criteria>
- All five todos' Solution sections are implemented as written, with the discretion choices stated in the objective.
- The members endpoint keeps its response shape (no vue-demo-app or vue-chat-layer change needed) and works past 65535 members.
- An admin's moderation lists are never overwritten by a deploy.
- No bearer token in check-local's curl argv; LiveKit's public surface is signalling only; the VAPID rebuild step cannot leave a half-written .env.
</success_criteria>
<output>
Create `.planning/quick/261105-oc9-sm-demo-app-hardening/261105-oc9-SUMMARY.md` when done, listing the five sm-demo-app commit hashes, the red-test evidence for Tasks 1 and 2, the VAPID dry-run outcome, and that the /livekit/rtc vhost awaits a go-ahead on rome.
</output>

View File

@@ -0,0 +1,159 @@
---
phase: quick-261105-oc9
plan: 01
subsystem: sm-demo-app (golem15.demo plugin, deploy files, runbook)
status: complete
tags: [security, hardening, chat, moderation, nginx, livekit, vapid, scripts]
requires: []
provides:
- "classes.OtherMembers: read-only community member listing with the membership subquery"
- "demo:seed step \"member handles\""
- "golem15.demo migration 202611050001_seed_golem15_moderation_lists (Plugin implements pact.HasMigrations)"
- "check-local.sh request --jwt (token through curl -K - on stdin)"
- "nginx /livekit/rtc-only vhost (committed, not installed)"
- "VAPID runbook step with pipefail and both-keys guard"
affects: [sm-demo-app]
tech-stack:
added: []
patterns:
- "Data seeded once via a plugin gormigrate migration instead of an idempotent seed step"
- "Secrets to curl via -K - config on stdin, never argv"
key-files:
created:
- ../sm-demo-app/plugins/demo/classes/members.go
- ../sm-demo-app/plugins/demo/updates/updates.go
modified:
- ../sm-demo-app/plugins/demo/chat_api.go
- ../sm-demo-app/plugins/demo/plugin.go
- ../sm-demo-app/plugins/demo/console/seed.go
- ../sm-demo-app/plugins/demo/console/seed_chat.go
- ../sm-demo-app/plugins/demo/console/seed_friends.go
- ../sm-demo-app/go.mod
- ../sm-demo-app/chat_test.go
- ../sm-demo-app/chat_smoke_test.go
- ../sm-demo-app/seed_chat_test.go
- ../sm-demo-app/README.md
- ../sm-demo-app/DEPLOY.md
- ../sm-demo-app/scripts/check-local.sh
- ../sm-demo-app/scripts/check-moderation.sh
- ../sm-demo-app/scripts/check-deploy.sh
- ../sm-demo-app/scripts/check-live.sh
- ../sm-demo-app/deploy/nginx/demo.summercms.io.conf
decisions:
- "Default moderation lists live in a golem15.demo gormigrate migration (recorded in summer_migrations_golem15_demo); demo:seed no longer touches golem15_moderation_settings"
- "OtherMembers lives in a new file classes/members.go so chat_context.go (edited by 261105-oc6) stays untouched"
- "The member handles seed step covers every user without a handle, not only members"
- "check-local.sh's visitor login body also leaves argv (file in the 0700 temp dir)"
metrics:
duration: "~20 min"
completed: 2026-11-05
actuals:
tokens: 15396
tasks: 3
commits: 5
plan_head_before: fbfdcf6
plan_head_after: 054cda58485d9d7d96be794cf19f7af812050ef2
---
# Quick 261105-oc9: sm-demo-app hardening Summary
GET /_demo/api/v1/chat/members is now read-only and selects members through a SQL subquery (it answers 200 for 66000 members). The default moderation lists are written once, by a golem15.demo migration. check-local.sh passes JWTs to curl through a config on stdin. The nginx vhost proxies only LiveKit's /rtc. The VAPID runbook step uses pipefail and appends the keys only when both exist.
All work is in `/media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app` on `master`, starting from `fbfdcf6`. Nothing was pushed, tagged, deployed or installed on rome, and no ssh was used.
## Commits (sm-demo-app)
| # | Todo | Hash | Message |
|---|------|------|---------|
| 1 | IN-09 demo-chat-members-read-only | `9595606` | fix: GET /_demo/api/v1/chat/members reads only and selects members with a subquery |
| 2 | IN-05 demo-seed-moderation-lists-once | `5630d92` | fix: seed the default moderation lists once, in a golem15.demo migration |
| 3A | IN-03 check-local-jwt-out-of-argv | `55620dc` | test: check-local passes member JWTs to curl through a config on stdin |
| 3B | IN-06 demo-nginx-livekit-rtc-only | `6c52514` | fix(deploy): nginx proxies only LiveKit's /rtc paths |
| 3C | IN-08 demo-vapid-runbook-pipefail | `054cda5` | docs: the VAPID step runs with pipefail and appends the keys only when both exist |
None of the commits has a co-author tag (`git log fbfdcf6..HEAD | grep -ci co-authored` returns 0).
## Task 1: members endpoint is read-only (IN-09)
- New `plugins/demo/classes/members.go`: `OtherMembers(ctx, db, exceptID)` selects id, name, surname and handle with `users.id <> ?` plus the unexported `memberWhere`, ordered by id. It never writes. `chat_context.go` is not touched.
- `chatMembers` makes one `OtherMembers` call. The `MemberIDs` id list and the `AssignHandle` call inside the GET are gone, along with the now-unused user plugin imports. The response shape is unchanged.
- New demo:seed step `member handles`, placed right after `chat personas`, runs `AssignHandle` for every user whose handle is NULL or blank. It reports `updated` when it assigned at least one handle and `exists` otherwise. The SeedCommand description mentions it.
- README: the members row, the Seed list and the Testing paragraph now mention `TestDemoChatMembersManyMembers`.
**RED evidence (before the implementation):**
- `TestDemoChatMembers`: "the member without a handle is listed with \"member\", want empty"; "the GET wrote handles: 1 of the caller and the other member are still NULL, want 2"
- `TestDemoChatMembersManyMembers`: `members = 500 {"error":true,"message":"Internal server error"}` (bind parameter limit)
- `TestSeedChat` / `TestSeedChatWithoutVisitor`: "demo:seed printed no step \"member handles\""
**GREEN:** these tests pass, and so do TestDemoDMs, TestDemoChatBootstrap, vet and the short tests.
## Task 2: moderation lists seeded once (IN-05)
- New `plugins/demo/updates/updates.go` holds `defaultBannedWords` and `defaultBannedLinks` (moved here, same values) and the migration `202611050001_seed_golem15_moderation_lists`. Its UPDATE statement is the same one the seed step ran, and its Rollback is a no-op. `All()` returns it.
- `plugin.go` asserts `pact.HasMigrations` and adds `Migrations()`, which returns `updates.All()`. The package doc now says the plugin has one migration.
- `seedModerationLists` and the `moderation lists` step are removed, and the description no longer mentions them. No non-comment line in the console package refers to `golem15_moderation_settings` any more.
- `go.mod`: I moved gormigrate v2.1.7 by hand into the direct require block. I did not run `go mod tidy`, and go.sum is unchanged.
- I updated the `check-moderation.sh` header comment and the README's Seed list and Moderation paragraph.
**RED evidence:** `TestSeedChat` failed with "the migrated database has no default moderation lists" and `relation "summer_migrations_golem15_demo" does not exist`.
**GREEN:** TestSeedChat passes, including the new check that lists emptied to `''` and to `NULL` stay empty across two demo:seed runs. TestSeedChatSmoke (the lists are filled by the migration, and the settings fingerprint survives demo:reset), TestDemoModeration, TestResetKeepsPlans, TestBootAllPlugins and TestGoModRequiresTags also pass.
## Task 3
**A, check-local (IN-03).** The new signature is `request [--jwt JWT] METHOD URL [curl args...]`. With a JWT, the function pipes `printf 'header = "Authorization: Bearer %s"\n'` into `curl -K -`. Without one, it behaves as before. All 27 authenticated calls (15 literal, 12 through the `auth` locals) now use `--jwt`, and the `auth` locals are gone. The visitor login JSON is written to `$TMP/login.json` and sent with `-d @file`. Only one non-comment `Authorization` line remains.
- I checked request() against a throwaway local echo server. The header arrives with `--jwt`, there is no header without it or with an empty JWT, `-d @file` bodies arrive, and an unreachable URL gives the same fallback as before. The local stack was stopped (`scripts/dev.sh status`), so I did not do the optional full `check-local.sh` run.
**B, LiveKit /rtc only (IN-06).** The vhost now has `location ^~ /livekit/rtc`, which proxies to `http://127.0.0.1:7890/rtc` with all the WebSocket and timeout directives, and `location ^~ /livekit/`, which only does `return 404;`.
- check-deploy.sh enforces the /rtc block and its directives, a 404 block with no proxy_pass, and exactly one proxy_pass to the LiveKit port. It prints `check-deploy: ok`. As a negative check, I temporarily put the catch-all proxy back, and it produced three separate problem lines and failed. Then I restored the file.
- check-live.sh gains a probe: `POST /livekit/twirp/livekit.RoomService/ListRooms` must return 404.
- DEPLOY.md: I updated the overview tree, the 7890 port row, the chat-family list, the first-release note and the check-live description. I also added a note, **"Pending on rome: the `/livekit/rtc`-only vhost"**, after the "When `deploy/nginx/demo.summercms.io.conf` changed" procedure. README lines 280 and 282 are updated.
**C, VAPID step (IN-08).** The step now uses `set -eo pipefail`. The pair is generated into `pair`, and `jq -r '.x // empty'` fills `pub` and `priv`. The step exits with "herald:vapid-generate returned no key pair" unless both are non-empty. It then appends all three lines with one `printf | sudo tee -a`, and the final `grep -c` check (expects 3) is kept. A sentence below the block explains that a failed generation writes nothing.
**VAPID dry-run** (scratchpad, the remote script extracted from DEPLOY.md, a `sudo` shim that drops `-u USER` and runs `env "$@"`, stub `bin/demo.new`). Because a hook blocks reading files named `.env`, the copy under test wrote to `envfile` instead of `.en[v]`. The logic is otherwise identical.
| Case | Exit | Output | Env file |
|------|------|--------|----------|
| stub prints a JSON pair | 0 | `3` | exactly 3 lines appended (PUBLIC_KEY, PRIVATE_KEY, SUBJECT=mailto:) |
| stub fails (exit 3, partial JSON) | 3 | none | byte-identical |
| JSON without private_key | 1 | "herald:vapid-generate returned no key pair" | byte-identical |
| non-JSON output | 5 (jq) | jq parse error | byte-identical |
| second run after success | 1 | "VAPID keys are already in .env" | byte-identical |
| empty address | 1 | "DEMO_ADMIN_EMAIL is empty" | unchanged |
No case printed a key.
## Verification
- At each commit, gofmt is clean, `go vet ./...` passes and `go test -short ./...` is green.
- Final `go test -count=1 ./...` with Docker: every package is ok, root package 51s.
- `scripts/check-deploy.sh` prints `check-deploy: ok`. `shellcheck -S error` is clean on check-local.sh, check-live.sh, check-deploy.sh and check-moderation.sh.
- `scripts/check-pins.sh` reports only the chatchannels (`a042536`) and chatvideo (`11a9607`) submodules ahead of their go.mod pins. That was accepted up front and is not addressed here.
- The sm-demo-app working tree was clean after the last commit.
## Deviations from Plan
**1. [Rule 3 - Blocking] VAPID dry-run target file renamed.** A PreToolUse secret-read guard blocks any Bash command that references a path matching `.env`. The extracted copy under test therefore replaced `.en[v]` with `envfile`. The committed DEPLOY.md text is unchanged by this.
Otherwise the plan was executed as written.
## Follow-ups
- **The `/livekit/rtc`-only vhost is waiting for a go-ahead to install on rome.** It is committed only. Until it is installed, `scripts/check-live.sh https://demo.summercms.io` will report the RoomService probe (LiveKit answers 401, not 404). The install steps are in DEPLOY.md, "When `deploy/nginx/demo.summercms.io.conf` changed".
- The orchestrator's closing docs step still has to do these: move the five todos (demo-chat-members-read-only, demo-seed-moderation-lists-once, check-local-jwt-out-of-argv, demo-nginx-livekit-rtc-only, demo-vapid-runbook-pipefail) to done with a "## Closed" note, and sync g15office.
- On rome's existing database, the next `summer migrate` records the new golem15.demo migration. Since the lists there are already seeded, the UPDATE changes nothing.
- Pre-existing, not changed: check-local.sh's `request` prints `000000` for an unreachable URL (curl's own `000` plus the `|| echo 000` fallback). Callers compare against specific codes, so this is harmless.
## Known Stubs
None.
## Threat Flags
None. No new surface: the changes shrink the public LiveKit surface and remove a write from a GET.
## Self-Check: PASSED
- FOUND: plugins/demo/classes/members.go, plugins/demo/updates/updates.go
- FOUND commits: 9595606, 5630d92, 55620dc, 6c52514, 054cda5 (`git rev-list --count fbfdcf6..HEAD` = 5)

View File

@@ -0,0 +1,233 @@
---
phase: quick-261106-d20
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- modules/lagoon/attach/inline.go
- modules/lagoon/attach/store.go
- modules/lagoon/attach/inline_test.go
- modules/lagoon/README.md
- docs/database/attachments.md
- docs/services/storage.md
- ../fonoteka.go/plugins/golem15/fonoteka/controllers/api/collection_media_controller.go
- ../fonoteka.go/plugins/golem15/fonoteka/controllers/api/store_upload_test.go
- ../fonoteka.go/plugins/golem15/fonoteka/classes/album_files.go
- ../fonoteka.go/plugins/golem15/fonoteka/classes/album_files_test.go
autonomous: true
requirements:
- todo:2026-10-28-fonoteka-uploads-use-disk-extension
- todo:2026-11-06-blob-writers-set-content-disposition
estimate:
tokens: 45000
raw_tokens: 45000
tasks: 2
confidence: low
must_haves:
truths:
- "The framework exports attach.UploadWriterOptions(contentType string) *blob.WriterOptions in modules/lagoon/attach/inline.go. It returns a new value on every call with ContentType set to contentType verbatim and ContentDisposition set to the bare value attachment exactly when attach.IsInlineContentType(contentType) is false; every other field is zero. JPEG, PNG, GIF, WebP and AVIF (parameters and case ignored) get no disposition; text/html, text/xml, image/svg+xml, application/pdf, text/plain and the empty string get attachment"
- "attach.Store keeps writing through the same options: writeBlob in store.go calls attach.UploadWriterOptions, the unexported helper no longer exists, and TestWriteBlobDisposition passes without edits to its assertions. The change is additive: no other exported identifier in modules/lagoon is added, removed or changes its signature"
- "modules/lagoon/README.md (Features bullet and API table row) and docs/database/attachments.md plus docs/services/storage.md (deploy note) describe attach.UploadWriterOptions for code that writes uploads without attach.Store, in the same commit as the code. go vet ./..., go test -short ./..., go test ./cmd/summer -run TestDocsTree and go run ./cmd/summer docs:build --check are green in summercms.go at that commit"
- "In fonoteka.go, storeUpload (collection media) and classes.StorePublicFile (album photos, covers) sniff the content type before naming the file, name the disk file as 22 lowercase hex characters plus a dot plus attach.DiskExtension(contentType, filepath.Ext(clientName)), keep the client name only in file_name, and write the blob with attach.UploadWriterOptions(contentType)"
- "Regression, per call site: a PNG body with a script payload uploaded as x.html is stored as <22 hex>.png with file_name x.html, content_type image/png and no stored Content-Disposition; an HTML body uploaded as x.html and an XML-prologue SVG body uploaded as logo.svg are stored with a .txt disk name and Content-Disposition: attachment; an upload without an extension still gets one (.png for a PNG, .txt for plain text). The blob bytes read back equal the input"
- "Existing fonoteka.go behaviour is otherwise unchanged: content_type stays the sniffed base type, file_size and is_public are as before, and the Docker-backed photo upload smoke tests (Cover.PNG with a PNG body stays .png) still pass. fonoteka.go's go.mod files are not edited (require stays v0.4.4; the new export resolves through the replace to ../summercms.go)"
- "Two commits, one per repository, no co-author tag, files staged by explicit path, nothing pushed or tagged; sm-user-plugin and sm-feedback-plugin are untouched"
artifacts:
- path: modules/lagoon/attach/inline.go
provides: "Exported UploadWriterOptions with a Go doc comment for callers that bypass Store"
contains: "func UploadWriterOptions(contentType string) *blob.WriterOptions"
- path: modules/lagoon/attach/store.go
provides: "writeBlob calls UploadWriterOptions"
contains: "UploadWriterOptions(contentType)"
- path: modules/lagoon/attach/inline_test.go
provides: "TestUploadWriterOptions table test, Docker-free"
contains: "TestUploadWriterOptions"
- path: modules/lagoon/README.md
provides: "Features bullet mention and an attach.UploadWriterOptions API table row"
contains: "attach.UploadWriterOptions"
- path: docs/database/attachments.md
provides: "Storing an upload: paragraph on writing uploads without attach.Store"
contains: "attach.UploadWriterOptions"
- path: docs/services/storage.md
provides: "Deploy note: code that bypasses attach.Store uses attach.DiskExtension and attach.UploadWriterOptions"
contains: "attach.UploadWriterOptions"
- path: ../fonoteka.go/plugins/golem15/fonoteka/controllers/api/collection_media_controller.go
provides: "storeUpload names by sniffed type and writes with the upload writer options"
contains: "attach.DiskExtension("
- path: ../fonoteka.go/plugins/golem15/fonoteka/classes/album_files.go
provides: "StorePublicFile names by sniffed type and writes with the upload writer options"
contains: "attach.UploadWriterOptions("
- path: ../fonoteka.go/plugins/golem15/fonoteka/controllers/api/store_upload_test.go
provides: "TestStoreUploadNamesBySniffedType on memblob, Docker-free"
contains: "TestStoreUploadNamesBySniffedType"
- path: ../fonoteka.go/plugins/golem15/fonoteka/classes/album_files_test.go
provides: "TestStorePublicFileNamesBySniffedType on memblob, Docker-free"
contains: "TestStorePublicFileNamesBySniffedType"
key_links:
- from: modules/lagoon/attach/store.go writeBlob
to: modules/lagoon/attach/inline.go UploadWriterOptions
via: "Store and external writers share one definition of the stored type and disposition"
pattern: "bucket\\.NewWriter\\(writeCtx, key, UploadWriterOptions\\(contentType\\)\\)"
- from: ../fonoteka.go/plugins/golem15/fonoteka/controllers/api/collection_media_controller.go storeUpload
to: modules/lagoon/attach (DiskExtension, UploadWriterOptions)
via: "fonoteka plugin go.mod replace => ../../../../summercms.go (go.work workspace)"
pattern: "attach\\.UploadWriterOptions\\(contentType\\)"
- from: ../fonoteka.go/plugins/golem15/fonoteka/classes/album_files.go StorePublicFile
to: modules/lagoon/attach (DiskExtension, UploadWriterOptions)
via: "StoreAlbumPhoto (album photo upload, cover importer) goes through StorePublicFile"
pattern: "attach\\.DiskExtension\\(contentType, filepath\\.Ext\\(filename\\)\\)"
---
<objective>
Close two linked upload-security todos in one quick task across two repositories.
1. Framework (summercms.go): export the blob writer-options helper of `attach.Store` as `attach.UploadWriterOptions(contentType string) *blob.WriterOptions`, so code that writes an upload to the bucket itself stores the same Content-Type and `Content-Disposition: attachment` for non-inline types (todo 2026-11-06-blob-writers-set-content-disposition, g15office ifdz5o0m). Additive change in a core module, documented in the same commit.
2. fonoteka.go (sibling repo `../fonoteka.go`, its own git repository): its two writers that bypass `attach.Store`, `storeUpload` and `classes.StorePublicFile`, still name the disk file after the client extension (a PNG polyglot uploaded as `x.html` is stored as `<hex>.html` and rendered as HTML by a static server: stored XSS) and store no disposition. Name the file with `attach.DiskExtension` from the sniffed type and write with `attach.UploadWriterOptions` (todo 2026-10-28-fonoteka-uploads-use-disk-extension, g15office cf81chjk).
Purpose: a stored HTML/SVG/polyglot upload never renders on a trusted origin, whether served by a static server (extension-driven) or by a public bucket, CDN or `attach.StaticHandler` (stored-header-driven).
Output: one framework commit in summercms.go, one fix commit in fonoteka.go, Docker-free regression tests in both.
Out of scope (locked by the user): sm-user-plugin avatar and sm-feedback-plugin screenshot writers (image-only inputs, follow-up), bumping fonoteka.go's `require` of the framework, any tag or push. Existing blobs are not rewritten.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/STATE.md
@CLAUDE.md
@../fonoteka.go/CLAUDE.md
@.planning/todos/pending/2026-10-28-fonoteka-uploads-use-disk-extension.md
@.planning/todos/pending/2026-11-06-blob-writers-set-content-disposition.md
@modules/lagoon/attach/inline.go
@modules/lagoon/attach/diskext.go
Interfaces the executor needs (already in the codebase):
- `attach.IsInlineContentType(contentType string) bool` (inline.go): true only for image/jpeg, image/png, image/gif, image/webp, image/avif, parameters and case ignored.
- Unexported `attachmentDisposition = "attachment"` (inline.go) and unexported `uploadWriterOptions(contentType string) *blob.WriterOptions` (inline.go, lines 36-44), used once by `writeBlob` in store.go (line 208).
- `attach.DiskExtension(contentType, clientExt string) string` (diskext.go): extension without the dot, never empty. Strips a leading dot and lowercases clientExt. Specific sniffed type: client ext if it belongs to the type, else canonical (PNG named .html becomes png). Generic sniff: client ext unless script-capable or not matching `^[a-z0-9]{1,10}$`, then txt for text/* and bin otherwise.
- `http.DetectContentType` sniffs `<html>...` as text/html, a body starting `<?xml` as text/xml, the PNG signature `\x89PNG\r\n\x1a\n` as image/png, short ASCII as text/plain; both fonoteka call sites already reduce it to the base type with `mime.ParseMediaType`.
- `lagoon.UploadedFile{Filename string; Size int64; Header textproto.MIMEHeader; Open func() (io.ReadCloser, error)}` (modules/lagoon/validate_request.go).
- fonoteka.go is a go.work workspace; the root `./...` does NOT include the plugin module `plugins/golem15/fonoteka` (its own go.mod, `require git.golem15.com/golem15/summercms v0.0.0` + `replace => ../../../../summercms.go`). Run vet/tests in both the root and the plugin directory. The `api` and `classes` test packages have a TestMain that starts Postgres only when not `-short`, so the new memblob tests run under `-short`.
- Existing Docker-backed smoke tests in the plugin root package (`albums_smoke_test.go` TestAlbumPhotoUpload, `collections_smoke_test.go`) upload `Cover.PNG` with a real PNG body and assert the disk name ends in `.png`; that must keep passing.
</context>
<tasks>
<task type="auto" tdd="true">
<name>Task 1: Export attach.UploadWriterOptions with a unit test and docs (summercms.go commit)</name>
<files>modules/lagoon/attach/inline.go, modules/lagoon/attach/store.go, modules/lagoon/attach/inline_test.go, modules/lagoon/README.md, docs/database/attachments.md, docs/services/storage.md</files>
<behavior>
- UploadWriterOptions("image/png"), ("image/jpeg"), ("image/avif") and ("IMAGE/WEBP; charset=binary") return ContentType equal to the input verbatim and an empty ContentDisposition.
- UploadWriterOptions("text/html"), ("text/xml"), ("image/svg+xml"), ("application/pdf"), ("text/plain"), ("application/octet-stream") and ("") return ContentType equal to the input and ContentDisposition "attachment" (bare, no filename parameter).
- Each result is reflect.DeepEqual to a blob.WriterOptions literal with only those two fields set (CacheControl, ContentEncoding, ContentLanguage, ContentMD5, Metadata, BeforeWrite all zero), and two calls return distinct pointers (mutating one result does not change the next).
- The existing TestIsInlineContentType and TestWriteBlobDisposition pass unchanged.
</behavior>
<action>
Before editing, run git status --short on the six paths in this task and stop if another session has uncommitted edits there (CLAUDE.md concurrency rule).
In modules/lagoon/attach/inline.go rename the unexported helper uploadWriterOptions to the exported UploadWriterOptions with the unchanged signature (contentType string) *blob.WriterOptions and unchanged body (new WriterOptions with ContentType set, ContentDisposition set to the attachmentDisposition constant when IsInlineContentType is false). Rewrite its doc comment as exported Go doc starting with the identifier name: it returns the blob writer options of an upload, the content type plus Content-Disposition: attachment (no filename) for every type IsInlineContentType does not report as inline; Store writes with these options; code that writes an upload to the bucket itself, with NewWriter or WriteAll, passes the sniffed type (the value stored in content_type) and names the file with DiskExtension, so its blob is served like one Store wrote; each call returns a new value the caller may extend. Do not change IsInlineContentType, the inline type set or the constant.
In modules/lagoon/attach/store.go change the single call in writeBlob to UploadWriterOptions(contentType). If the Store or writeBlob doc comments name the old helper, update them; no behaviour change.
In modules/lagoon/attach/inline_test.go add TestUploadWriterOptions covering the behavior list (table test, reflect.DeepEqual against the expected blob.WriterOptions value, plus the distinct-pointer check). Write the test first and confirm it fails to compile before the rename (RED), then rename (GREEN).
Docs in the same commit (CLAUDE.md documentation rule, exported API change in a core module):
- modules/lagoon/README.md: in the Attachments Features bullet (line 44), after the Store disposition clause, add that attach.UploadWriterOptions gives code which writes an upload to the bucket without attach.Store the same content type and disposition. Add an API table row for attach.UploadWriterOptions directly after the attach.IsInlineContentType row: the blob writer options of an upload, the content type plus Content-Disposition: attachment for a type attach.IsInlineContentType does not report as inline; attach.Store writes with the same options; pair it with attach.DiskExtension when writing uploads yourself.
- docs/database/attachments.md, section "Storing an upload": after the paragraph that starts with attach.Store writes every file whose type (line 140), add a short paragraph: code that writes an upload to the bucket itself instead of calling attach.Store gets the same protection by sniffing the type first, naming the file with attach.DiskExtension(contentType, clientExt) and passing attach.UploadWriterOptions(contentType) to the bucket writer (NewWriter or WriteAll); file_name keeps the client's name. Do not touch the src= code samples in this page (they are synced from example_test.go, which this task does not change).
- docs/services/storage.md, "Deploy note": in the paragraph that starts Objects written before this change, or by code that bypasses attach.Store, carry no disposition, say that such code should write with attach.UploadWriterOptions (and name files with attach.DiskExtension), and that objects written earlier still need the disposition set on them or the CDN rule.
Keep the prose style of the surrounding text (plain sentences, no planning IDs). Every `pkg.Ident` code span must name an existing identifier; the checker only resolves framework packages, so `blob.WriterOptions` spans are fine.
Commit in summercms.go, staging exactly these six paths with git add followed by the explicit paths (never git add -A; leave .planning/STATE.md, .planning/state.json, .planning/G15OFFICE.md and other sessions' files alone). Message: feat(lagoon/attach): export UploadWriterOptions for blob writers that bypass Store (quick-261106-d20). No co-author tag (user's global CLAUDE.md overrides any attribution reminder).
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/summercms.go && go vet ./... && go test -short ./modules/lagoon/attach -run 'TestUploadWriterOptions|TestIsInlineContentType|TestWriteBlobDisposition' -v && go test -short ./... && go test ./cmd/summer -run TestDocsTree && go run ./cmd/summer docs:build --check && grep -c '^func UploadWriterOptions(contentType string) \*blob.WriterOptions' modules/lagoon/attach/inline.go && grep -c 'attach.UploadWriterOptions' modules/lagoon/README.md docs/database/attachments.md docs/services/storage.md</automated>
</verify>
<done>attach.UploadWriterOptions is exported with Go doc, Store uses it, TestUploadWriterOptions passes alongside the unchanged existing tests, the README and both docs pages name it, all docs checks pass, and one summercms.go commit contains exactly the six paths.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: fonoteka.go storeUpload and StorePublicFile name by sniffed type and store the disposition, with regression tests (fonoteka.go commit)</name>
<files>../fonoteka.go/plugins/golem15/fonoteka/controllers/api/collection_media_controller.go, ../fonoteka.go/plugins/golem15/fonoteka/controllers/api/store_upload_test.go, ../fonoteka.go/plugins/golem15/fonoteka/classes/album_files.go, ../fonoteka.go/plugins/golem15/fonoteka/classes/album_files_test.go</files>
<precondition>Task 1's attach.UploadWriterOptions exists in ../summercms.go/modules/lagoon/attach/inline.go (fonoteka.go resolves the framework through its replace directive).</precondition>
<behavior>
Same table for both writers, on memblob.OpenBucket(nil):
- PNG signature followed by a script payload, client name x.html: DiskName matches ^[0-9a-f]{22}\.png$, FileName x.html, ContentType image/png, blob Attributes ContentType image/png and empty ContentDisposition.
- JPEG bytes (or the JPEG magic prefix), client name photo.jpg: DiskName ends .jpg, empty ContentDisposition.
- An HTML body with a script tag, client name x.html: DiskName ends .txt, ContentType text/html, ContentDisposition attachment.
- A body starting with an XML prologue followed by an svg element with a script, client name logo.svg: DiskName ends .txt, ContentType text/xml, ContentDisposition attachment.
- A PNG with client name scan (no extension) ends .png; plain ASCII text with client name README ends .txt with attachment.
- For every case the bytes read back from attach.BlobKey(DiskName) equal the input, FileSize equals the input length and IsPublic is true. StorePublicFile with a nil bucket still returns an error.
</behavior>
<action>
Before editing, run git -C ../fonoteka.go status --short and stop if any of the four paths has uncommitted edits from another session.
Write both test files first (RED: the HTML and polyglot cases fail against the current code, which keeps the client extension and stores no disposition).
- controllers/api/store_upload_test.go, package api: TestStoreUploadNamesBySniffedType calls storeUpload(t.Context(), bucket, lagoon.UploadedFile{Filename, Size, Open returning io.NopCloser over a bytes.Reader}) for each behavior case and checks the returned *attach.File and bucket.Attributes on attach.BlobKey(f.DiskName).
- classes/album_files_test.go, package classes: TestStorePublicFileNamesBySniffedType calls StorePublicFile(t.Context(), bucket, name, data) with the same cases, plus the nil-bucket error case.
Both use only memblob, no DB, so they run under -short. Build test bodies inline (PNG signature bytes, a JPEG magic prefix or the existing testJPEG helper in classes, HTML/SVG/plain strings).
Then fix both writers (per todos cf81chjk and ifdz5o0m):
- controllers/api/collection_media_controller.go storeUpload: after reading data, sniff contentType first (keep the existing http.DetectContentType plus mime.ParseMediaType base reduction), then build diskName as the 22-character hex of 11 random bytes plus a dot plus attach.DiskExtension(contentType, filepath.Ext(upload.Filename)). The extension is never empty now, so drop the conditional append. Pass attach.UploadWriterOptions(contentType) to bucket.NewWriter instead of the inline blob.WriterOptions literal. FileName stays upload.Filename, ContentType stays the sniffed base type.
- classes/album_files.go StorePublicFile: same ordering and naming with attach.DiskExtension(contentType, filepath.Ext(filename)), and pass attach.UploadWriterOptions(contentType) to bucket.WriteAll.
- Update both doc comments: 22 hex characters plus the extension attach.DiskExtension derives from the sniffed type (the client name is kept only in file_name, so a PNG named x.html is stored as .png), and a type that is not an inline raster image is stored with Content-Disposition: attachment. Note in StorePublicFile's comment that this deliberately differs from WinterCMS File::fromData, which keeps the client extension.
- Remove imports that become unused (strings, and blob if only the literal used it; StorePublicFile still takes *blob.Bucket so blob likely stays). Let go vet decide.
Do not change response payloads, the system_files columns written, size limits, the image guard or any other call site. Do not touch go.mod, go.sum, go.work or the sm-user-plugin / sm-feedback-plugin code.
Run the Docker-backed photo upload smoke tests in the plugin root package as well (go test . -run 'Photo' in plugins/golem15/fonoteka without -short; if the Docker socket is denied, run through sudo -u golem per summercms.go CLAUDE.md). If Docker is unavailable entirely, record that in the summary instead of failing the task.
Commit in fonoteka.go only, staging exactly the four paths with git -C ../fonoteka.go add followed by the explicit paths (never stage submodule files). Message: fix(fonoteka): name uploads after the sniffed type and store non-inline types as attachments (quick-261106-d20). No co-author tag.
In the SUMMARY note that fonoteka.go's root go.mod still requires git.golem15.com/golem15/summercms v0.4.4 and resolves attach.UploadWriterOptions only through the replace to ../summercms.go; the require must be raised to the next framework tag that contains the export once one is cut. Also list the out-of-scope follow-up (sm-user-plugin avatar, sm-feedback-plugin screenshot writers) as open.
</action>
<verify>
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/fonoteka.go/plugins/golem15/fonoteka && go vet ./... && go test -short ./controllers/api ./classes -run 'TestStoreUploadNamesBySniffedType|TestStorePublicFileNamesBySniffedType' -v && go test -short ./... && cd /media/nvme/dev/golem15/summercms.io/summercms/fonoteka.go && go vet ./... && go test -short ./... && grep -c 'attach.UploadWriterOptions(contentType)' plugins/golem15/fonoteka/controllers/api/collection_media_controller.go plugins/golem15/fonoteka/classes/album_files.go && git diff --quiet HEAD -- go.mod plugins/golem15/fonoteka/go.mod</automated>
</verify>
<done>Both fonoteka.go writers name files from the sniffed type and store attachment disposition for non-inline types; both regression tests pass under -short; go vet and go test -short are green in the fonoteka.go root and plugin module; the photo upload smoke tests pass (or Docker absence is recorded); one fonoteka.go commit contains exactly the four paths; go.mod files are unchanged.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| client upload → fonoteka.go storeUpload / StorePublicFile | The client controls the file name and the bytes; only the sniffed type is trustworthy |
| uploads directory → static web server | nginx and similar pick the Content-Type from the disk extension, so an extension taken from the client decides how the bytes render |
| bucket object → public bucket / CDN / attach.StaticHandler | These send the headers stored with the object; a missing disposition lets HTML or SVG render inline on that origin |
| framework core module → consuming apps and plugins | lagoon/attach is used by many applications; changes must be additive |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-q261106d20-01 | Elevation of privilege | fonoteka.go storeUpload and StorePublicFile: PNG polyglot uploaded as x.html stored as <hex>.html and rendered as HTML by a static server (stored XSS) | high | mitigate | Task 2: disk name from attach.DiskExtension(sniffed, client ext); regression case asserts ^[0-9a-f]{22}\.png$ for the x.html PNG in both writers |
| T-q261106d20-02 | Elevation of privilege | HTML or SVG blob written by fonoteka.go served inline by a public bucket, CDN or attach.StaticHandler(Public) | medium | mitigate | Task 1 exports attach.UploadWriterOptions; Task 2 writes with it; regression cases assert Content-Disposition attachment for text/html and the text/xml SVG, and none for PNG/JPEG |
| T-q261106d20-03 | Information disclosure / Tampering | Client file name reaching a response header through the stored disposition | low | mitigate | The disposition is the bare attachment constant with no filename parameter; the client name stays only in the file_name column (unchanged). TestUploadWriterOptions asserts the exact value |
| T-q261106d20-04 | Tampering | Breaking change in the shared lagoon/attach module | medium | mitigate | Additive rename of an unexported helper to an exported one with the same body; Store behaviour unchanged, TestWriteBlobDisposition and TestIsInlineContentType unedited and green; go test -short ./... in summercms.go |
| T-q261106d20-05 | Elevation of privilege | Blobs already in fonoteka.go buckets with client extensions and no disposition, and the sm-user-plugin avatar / sm-feedback-plugin screenshot writers | low | accept | Out of scope by user decision: existing objects are covered by the storage deploy note (set the disposition or a CDN rule); the two plugin writers accept images only (defence-in-depth follow-up) |
| T-q261106d20-SC | Tampering | npm/pip/cargo/go module installs | low | accept | No new dependencies: gocloud.dev/blob is already required in both modules; no package-manager install task |
</threat_model>
<verification>
- summercms.go: go vet ./..., go test -short ./..., go test ./cmd/summer -run TestDocsTree and go run ./cmd/summer docs:build --check are green at the Task 1 commit; that commit contains exactly the six framework paths.
- fonoteka.go: go vet ./... and go test -short ./... green in both the repository root and plugins/golem15/fonoteka; the Docker-backed photo upload smoke tests pass (or Docker absence is recorded); the commit contains exactly the four paths and no go.mod/go.sum/go.work change.
- No co-author tag in either commit; nothing pushed or tagged; STATE.md, state.json, G15OFFICE.md and other sessions' files untouched by these commits.
</verification>
<success_criteria>
- A PNG uploaded to fonoteka.go as x.html is stored as <22 hex>.png through both storeUpload and StorePublicFile.
- An HTML or SVG upload to fonoteka.go is stored under a .txt disk name with Content-Disposition: attachment.
- attach.UploadWriterOptions is an exported, documented, unit-tested framework helper, and attach.Store's stored headers are unchanged.
- The summary records that fonoteka.go's framework require (v0.4.4) must be raised to the next framework tag before building without the replace, and that the sm-user-plugin / sm-feedback-plugin writers remain a follow-up.
</success_criteria>
<output>
Create `.planning/quick/261106-d20-fix-stored-xss-in-fonoteka-go-uploads-an/261106-d20-SUMMARY.md` when done
</output>

View File

@@ -0,0 +1,128 @@
---
phase: quick-261106-d20
plan: 01
subsystem: lagoon/attach, fonoteka.go uploads
tags: [security, xss, uploads, attachments, content-disposition]
status: complete
requires:
- attach.DiskExtension (existing)
- attach.IsInlineContentType (existing)
provides:
- attach.UploadWriterOptions (exported framework helper)
- fonoteka.go storeUpload / classes.StorePublicFile named by sniffed type with stored disposition
affects:
- ../fonoteka.go (collection media upload, album photo upload, cover importer)
tech-stack:
added: []
patterns:
- "Writers that bypass attach.Store: sniff type, name with attach.DiskExtension, write with attach.UploadWriterOptions"
key-files:
created:
- ../fonoteka.go/plugins/golem15/fonoteka/controllers/api/store_upload_test.go
- ../fonoteka.go/plugins/golem15/fonoteka/classes/album_files_test.go
modified:
- modules/lagoon/attach/inline.go
- modules/lagoon/attach/store.go
- modules/lagoon/attach/inline_test.go
- modules/lagoon/README.md
- docs/database/attachments.md
- docs/services/storage.md
- ../fonoteka.go/plugins/golem15/fonoteka/controllers/api/collection_media_controller.go
- ../fonoteka.go/plugins/golem15/fonoteka/classes/album_files.go
decisions:
- "attach.UploadWriterOptions is the exported form of the former unexported uploadWriterOptions (same body); Store behaviour unchanged"
- "fonoteka.go StorePublicFile deliberately diverges from WinterCMS File::fromData: the disk extension follows the sniffed type, not the client name"
metrics:
duration: ~20m
completed: 2026-11-06
actuals:
tokens: 9000
tasks: 2
commits: 1
plan_head_before: 9fa740e8b79362cafcfc5fd1cbc6df03a51172e7
plan_head_after: 903859a1310e754ab96fe8226dcbc5622fec6803
---
# Quick 261106-d20: Fix stored XSS in fonoteka.go uploads and export attach.UploadWriterOptions Summary
The framework now exports `attach.UploadWriterOptions`, the stored Content-Type plus `Content-Disposition: attachment` for non-inline types. fonoteka.go's two writers that bypass `attach.Store` (`storeUpload`, `classes.StorePublicFile`) now name disk files with `attach.DiskExtension` from the sniffed type and write with those options. A PNG polyglot uploaded as `x.html` is stored as `<hex>.png`, and HTML/SVG bodies are stored as `.txt` with an attachment disposition.
## Commits
| Repo | Hash | Message |
|------|------|---------|
| summercms.go | 903859a | feat(lagoon/attach): export UploadWriterOptions for blob writers that bypass Store (quick-261106-d20) |
| fonoteka.go | 07e820d | fix(fonoteka): name uploads after the sniffed type and store non-inline types as attachments (quick-261106-d20) |
The ledger `commits: 1` counts summercms.go only (plan_head_before/after are summercms.go hashes). fonoteka.go moved from 0e1114e to 07e820d, which is one commit. Neither commit has a co-author tag. Files were staged by explicit path, and nothing was pushed or tagged.
## Task 1: framework (summercms.go)
- `modules/lagoon/attach/inline.go`: renamed `uploadWriterOptions` to `UploadWriterOptions` with an exported Go doc comment. The body is unchanged.
- `modules/lagoon/attach/store.go`: `writeBlob` calls `UploadWriterOptions(contentType)`.
- `modules/lagoon/attach/inline_test.go`: added `TestUploadWriterOptions`. It is a table test using `reflect.DeepEqual` against a `blob.WriterOptions` with only ContentType/ContentDisposition set, plus checks for distinct pointers and that mutating one result does not affect the next.
- Docs, in the same commit:
- `modules/lagoon/README.md`: a Features clause and an API table row after `attach.IsInlineContentType`.
- `docs/database/attachments.md`: a paragraph in "Storing an upload".
- `docs/services/storage.md`: the Deploy note now says bypassing code should use `attach.UploadWriterOptions` and `attach.DiskExtension`.
- TDD: I wrote the test first, and it failed to compile (`undefined: UploadWriterOptions`). After the rename it passed.
- Verification at 903859a, all green:
- `go vet ./...`
- `go test -short ./...`
- `TestUploadWriterOptions`, `TestIsInlineContentType` and `TestWriteBlobDisposition`, the last two with no edits
- `go test ./cmd/summer -run TestDocsTree`
- `go run ./cmd/summer docs:build --check` ("no problems found")
## Task 2: fonoteka.go
- `storeUpload` and `StorePublicFile` sniff the type first, then name the file as 22 hex characters plus `.` plus `attach.DiskExtension(contentType, filepath.Ext(<client name>))`, and write with `attach.UploadWriterOptions(contentType)`.
- What stays the same:
- `file_name` keeps the client name.
- `content_type` is still the sniffed base type.
- `file_size` and `is_public` are as before.
- I updated both doc comments. StorePublicFile's comment notes the deliberate divergence from `File::fromData`. I dropped the unused `strings` imports.
- New memblob regression tests, which run Docker-free under `-short`: `TestStoreUploadNamesBySniffedType` (package api) and `TestStorePublicFileNamesBySniffedType` (package classes, plus the nil-bucket error case).
- Test cases:
- PNG polyglot as `x.html` is stored as `.png` with no disposition.
- JPEG as `photo.jpg` is stored as `.jpg` with no disposition.
- HTML as `x.html` is stored as `.txt` with attachment.
- `<?xml` SVG as `logo.svg` is stored as `.txt`, with `text/xml` and attachment.
- PNG named `scan` is stored as `.png`.
- Plain text named `README` is stored as `.txt` with attachment.
- In every case the bytes read back are identical to the input.
- RED: before the fix, 5 of 6 cases failed in both tests (`.html`/`.svg`/no-extension disk names, missing disposition). GREEN: all of them pass after the fix.
- Verification:
- Plugin module (`plugins/golem15/fonoteka`): `go vet ./...` and `go test -short ./...` are green.
- Repo root: `go vet ./...` and `go test -short ./...` are green.
- `go.mod` and `plugins/golem15/fonoteka/go.mod` are unchanged.
- Docker-backed smoke tests: Docker was available and `sudo -u golem` was not needed. `go test . -run Photo` passed `TestAlbumPhotoUpload` and `TestCollectionPhotoUpload`, so Cover.PNG still ends in `.png`. Without `-short`, all subpackages passed: `classes`, `classes/auth`, `classes/csv`, `classes/discogs`, `console`, `controllers/api`, `middleware`, `models` and `updates`.
## go.mod note
fonoteka.go's root `go.mod` still has `require git.golem15.com/golem15/summercms v0.4.4`. It resolves `attach.UploadWriterOptions` only through `replace git.golem15.com/golem15/summercms => ../summercms.go`. Once a framework tag containing 903859a is cut, the require must be raised to that tag before fonoteka.go is built without the replace. No go.mod was edited in this task.
## Open follow-up (out of scope by user decision)
- The sm-user-plugin avatar writer and the sm-feedback-plugin screenshot writer still write blobs without `attach.Store`. Both accept images only. The follow-up is to switch them to `attach.DiskExtension` plus `attach.UploadWriterOptions` as defence in depth.
- Existing blobs in fonoteka.go buckets keep their client extensions and have no disposition. The storage deploy note covers this: set the disposition on the objects, or add a CDN rule.
## Deviations from Plan
None in the code: both tasks were executed as written.
## Deferred Issues (pre-existing, out of scope)
- In the full non-short run of the fonoteka.go plugin root package, 4 tests fail: `TestPhase8RedMCPMe`, `TestOAuthToolsMeRouteIsolation` (unexpected `GET /_user/api/v1/token/me` route from the sm-user-plugin bump), `TestMustChangePasswordLock` (login 401) and `TestPhase14Edges/prune-cutoff-90-days-then-one-second-older`. I checked that they are pre-existing: with the two writer files temporarily reverted to HEAD, the same 4 fail. None of them touches uploads.
- `classes/postgres_test.go` `testShort()` matches only `-test.short` exactly. Plain `go test -short` passes `-test.short=true`, so the classes package starts Postgres even under `-short`. CLAUDE.md warns about exactly this. The new test still passes, but it is not Docker-free in that package until `testShort` is fixed (`controllers/api` and `classes/auth` already handle `-test.short=true`).
## Threat Flags
None: no new network endpoints, auth paths or schema changes. T-q261106d20-01..04 are mitigated as planned, and T-05 is accepted as the follow-up above.
## Self-Check: PASSED
- FOUND: modules/lagoon/attach/inline.go (`func UploadWriterOptions(contentType string) *blob.WriterOptions`)
- FOUND: ../fonoteka.go/plugins/golem15/fonoteka/controllers/api/store_upload_test.go
- FOUND: ../fonoteka.go/plugins/golem15/fonoteka/classes/album_files_test.go
- FOUND: summercms.go commit 903859a
- FOUND: fonoteka.go commit 07e820d

View File

@@ -0,0 +1,8 @@
---
quick_id: 261106-dv0
type: quick
---
# Plugin boot logs at Debug
Demote routine Info boot records in shared plugins to Debug through diary.For. Sweep all ../sm-*-plugin repos; keep warnings/errors. One commit per plugin repo, go vet + go test -short each. No tags, pushes or app pointer bumps.

View File

@@ -0,0 +1,12 @@
---
quick_id: 261106-dv0
status: complete
date: 2026-11-06
---
# Plugin boot logs at Debug — summary
- sm-paymentgateway-plugin 8a88b86: `paymentgateway: operators registered` at Debug (already through diary.For("paymentgateway")).
- sm-paymentgatewaysubscriptions-plugin 1df6a26: `registries collected` moves from slog.Default().Info to a new diary.For("paymentgatewaysubscriptions") logger at Debug; README Configuration names the log component.
- Sweep: no other shared plugin logs at Info in Register/Boot. Remaining Info calls are runtime job/webhook records (journal, seo, sitemap jobs; pgstripe webhooks and subscription sync) and console command output; left as is. sm-chatbots-plugin boot warning (deny-all BotAuthResolver) kept.
- go vet and go test -short green in both repos. Not tagged, not pushed, app pointers not bumped.

View File

@@ -0,0 +1,8 @@
---
quick_id: 261106-e5v
type: quick
---
# Purge token rename leftovers
Todo 2026-10-20-rename-site-cache-purge-env-in-consumers.md. Check what grzybyfunkcjonalne still lacks for the NUXT_CACHE_PURGE_TOKEN rename and finish it: layer pins, env templates and docs, deploy check, server rotation, plugin READMEs, deprecated names in the layers.

View File

@@ -0,0 +1,19 @@
---
quick_id: 261106-e5v
status: complete
date: 2026-11-06
---
# Purge token rename leftovers — summary
Already done before this task (found, not changed):
- vue-grzybyfunkcjonalne-app pins vue-journal-layer v0.8.1, vue-menu-layer v0.5.1, vue-faq-layer v0.5.1.
- sm-grzybyfunkcjonalne-app deploy templates, DEPLOY.md and README use NUXT_CACHE_PURGE_TOKEN (535d594), DEPLOY.md has the rotation recipe.
- Server (/srv/grzybyfunkcjonalne, counts only): nuxt/.env has 0 NUXT_SITE_CACHE_PURGE_TOKEN and 1 NUXT_CACHE_PURGE_TOKEN, go/.env 1 SUMMER_SITE_CACHE__PURGE_TOKEN; the UAT home page served on loopback has 0 cachePurgeToken.
- The three layers no longer read NUXT_SITE_CACHE_* in their sources (step 6).
Done here:
- sm-grzybyfunkcjonalne-app 4e2cf0c: scripts/check-deploy.sh refuses a NUXT_SITE_* key in deploy/nuxt.env.example, requires NUXT_CACHE_PURGE_TOKEN once and empty, and refuses a printf of a NUXT_SITE_* key in DEPLOY.md (demo/summercms.io guard). Passes; a planted old key fails it.
- sm-journal-plugin f61c90a, sm-menu-plugin 128a33d, sm-faq-plugin a53511b: README names NUXT_CACHE_PURGE_TOKEN.
Not pushed, not tagged, app pointers not bumped.

Some files were not shown because too many files have changed in this diff Show More