Compare commits

...

225 Commits

Author SHA1 Message Date
Jakub Zych
10c8a05d06 docs(32.2): record tag-and-publish release decision 2026-11-21 13:30:58 +01:00
Jakub Zych
eb721a77fc test(32.2): reorder UAT so the release precedes the live checks 2026-11-21 13:27:39 +01:00
Jakub Zych
449ff6a454 docs(32.2): re-verify phase after code review fixes 2026-11-21 13:27:23 +01:00
Jakub Zych
5a54122efa docs(32.2): shorten COVERAGE.md opt-out reason for the coverage gate 2026-11-21 13:20:10 +01:00
Jakub Zych
261ad3fd43 docs(32.2): reconcile code review disposition after fixes 2026-11-21 10:03:58 +01:00
Jakub Zych
cf96d372c7 docs(32.2): add code review fix reports 2026-11-21 10:03:43 +01:00
Jakub Zych
0ade662a04 fix(32.2): WR-06 check the consent provider's redirect against the request's redirect URI
cabana loads the pending request on both decisions and refuses (500) a Decide answer whose scheme, user info, host, path or opaque part differ from the registered redirect URI. The admin SPA also refuses blob:, file:, about: and filesystem: and a destination that does not return to the host the consent card showed. Regenerated the admin OpenAPI document and rebuilt modules/boardwalk/dist.
2026-11-21 09:32:54 +01:00
Jakub Zych
60bc6ee68f fix(32.2): WR-05 hand the deactivate revocation the plain transaction
The deactivate lifecycle fired BackendAccessRevokedEvent with actionDB's Unscoped session, so a listener's Delete through ev.Tx was a hard delete only for that reason. It now passes the save's transaction like every other site.
2026-11-21 09:21:59 +01:00
Jakub Zych
a261a8fdfe fix(32.2): WR-04 never fire BackendAccessRevokedEvent without the save's transaction
fireBackendAccessRevoked refuses a nil tx before any listener runs, and the Administrators and Roles update hooks fail closed (like the delete hook) when the save carries no transaction, instead of firing with whatever TxFromContext answered.
2026-11-21 09:17:33 +01:00
Jakub Zych
19bb3f9485 fix(32.2): WR-03 refuse an unknown MCPGrant.Subject instead of treating it as a user grant
pier now resolves only the empty subject (frontend user grant) and pact.MCPGrantSubjectBackend; any other value is ErrUnauthorized and never reaches the linked-administrator lookup.
2026-11-21 09:11:46 +01:00
Jakub Zych
1dcc2ed06d fix(32.2): WR-02 refuse a ConsentPath that is not a same-origin path
Add wristband.CheckConsentPath (additive, for hosts to call at boot) and make Authorize answer 500 before storing a pending request while the configured path fails it, so the handoff can never leave the issuer's origin.
2026-11-21 09:08:12 +01:00
Jakub Zych
fa7a84821e fix(32.2): WR-01 apply DefaultScopes to offline_access-only authorize requests
A request naming only offline_access now gets Options.DefaultScopes (when set) plus offline access instead of a pending request with zero data scopes. The read fallback is only used when the server accepts read; otherwise the request is refused with invalid_scope (RFC 6749 3.3).
2026-11-21 09:05:07 +01:00
Jakub Zych
20260e8bb4 test(32.2): persist human verification items as UAT 2026-11-21 02:52:39 +01:00
Jakub Zych
e238537fc2 docs(32.2): phase verification report 2026-11-21 02:52:38 +01:00
Jakub Zych
c16402f79b docs(32.2): record code review disposition 2026-11-21 02:41:55 +01:00
Jakub Zych
7a2b4954be docs(32.2): add code review reports 2026-11-21 02:41:41 +01:00
Jakub Zych
75f45933b8 docs(phase-32.2): update tracking after wave 4 2026-11-21 02:31:05 +01:00
Jakub Zych
7a39fda957 docs(32.2-05): record the hold release decision and complete the tests plan
- 32.2-05-release-decision.txt: hold, framework-base v0.6.6, plugin-base v0.1.7
- 32.2-05-SUMMARY.md: tests, regression exit codes, deviations, release
  pending the user's go-ahead, live SameSite connector check unverified
2026-11-21 02:30:45 +01:00
Jakub Zych
fc90a5470c docs(32.2-05): update deferred items after the plugin tests 2026-11-21 02:22:48 +01:00
Jakub Zych
b1b96d85da fix(32.2-05): run admin:reset-password in a lagoon transaction
The reset fired BackendAccessRevokedEvent inside a plain GORM
transaction, where lagoon.AfterCommit refuses to run, so a listener's
after-commit work (sm-oauthserver-plugin's revoked MCPSubjectChanged
events that end MCP sessions) never ran for this D-13 site.
TestBackendAccessRevokedEvent now asserts the after-commit callback runs
once for a committed reset and not for a vetoed one.
2026-11-21 02:14:12 +01:00
Jakub Zych
1e00ed3d3e test(32.2-05): admin SPA tests for the consent screen, login hint and My account item rows
- ConnectView.test.ts: every C1 state, the * rule, no auto-allow, Allow and
  Deny bodies through window.location.assign, forbidden schemes, switch
  account, 401/404 handling, focus and the profile fallback
- router, LoginView and AccountContributions tests extended for /connect,
  the login hint and item rows (null items unchanged, empty block, :title
  confirm, 404 item_gone, 409 action_stale)
2026-11-21 02:00:16 +01:00
Jakub Zych
7ecfa6087d test(32.2-05): unit tests for administrator MCP grants, admin consent, account items and access revocation
- wristband: TestAuthorizeConsentPath, TestAuthorizeDefaultScopes
- pier: TestBackendOnlyGrant, TestLinkedGrantNoScopeLimit (Docker)
- cabana: TestTokenScopeNames, TestMCPAdminConsent, TestAccountContributionItems,
  TestBackendAccessRevokedEvent (Docker); export_test.go exposes the event
  helper for the de-duplication case
2026-11-21 02:00:16 +01:00
Jakub Zych
d450a6819e docs(phase-32.2): update tracking after wave 3 2026-11-21 01:40:46 +01:00
Jakub Zych
308f121d1b docs(32.2-04): complete first-consumer administrator MCP OAuth plan 2026-11-21 01:40:19 +01:00
Jakub Zych
fdcab18bb8 docs(phase-32.2): update tracking after wave 2 2026-11-21 01:27:06 +01:00
Jakub Zych
7e89a9d7e4 docs(32.2-03): complete sm-oauthserver-plugin backend-subject mode plan 2026-11-21 01:26:39 +01:00
Jakub Zych
26af5f9549 docs(phase-32.2): update tracking after plan 32.2-02 2026-11-21 00:59:08 +01:00
Jakub Zych
44a39ff250 docs(32.2-02): complete admin consent screen and account items plan 2026-11-21 00:57:03 +01:00
Jakub Zych
ee754b6b5d chore(32.2-02): rebuild embedded admin dist with the connect screen and account items 2026-11-21 00:53:01 +01:00
Jakub Zych
2708982601 feat(32.2-02): My account item rows with per-row actions; connect screen docs
- AccountContributions renders a section's items as list rows (title,
  subtitle, meta joined with ' · ') with one button per item action, or
  the dashed empty block; sections without items render as before
- item actions confirm with :title filled as text, post to
  /account/contribution-items/{name}/{item}/actions/{action}, reload and
  focus the section heading; 404 toasts item_gone and reloads
- myaccount.items_empty, item_gone, item_action_named in en and pl
- docs/backend/admin-spa.md: the /connect screen and My account item rows
2026-11-21 00:52:23 +01:00
Jakub Zych
6900bd1a72 feat(32.2-02): every consent card state, account switch and login hint
- Loading skeleton (aria-busy, no buttons), Expired (404 or no request,
  no call), Load error with Try again, No grantable scope (Deny only),
  Returning with the continue link for http(s) redirects
- 422 shows scopes_required under the scopes; 5xx, network, 400 and a
  javascript:/data:/vbscript: redirect show decide_failed; ticks kept
- 401 hands over to expireSession; focus follows the state heading
- Use another account: logout() without the router, then login with the
  /connect?request= redirect
- LoginView shows mcp_connect.login_hint when the redirect is /connect
2026-11-21 00:48:02 +01:00
Jakub Zych
f46c90f7fb feat(32.2-02): admin consent card at /connect posts the decision and leaves for redirect_uri
- /connect route without shell and without public, so login round-trips back
- ConnectView ready state: client mark, fact box, catalog-order scope picker
  with the token-dialog * rule, Stay connected, Deny and Allow
- Allow/Deny POST /mcp/consent/{request}; the browser leaves through
  window.location.assign after refusing javascript:, data: and vbscript:
- MCPConsent, MCPConsentDecision and AccountItem type aliases
- backend::lang.mcp_connect copy in en and pl; connect page title
- smoke test: ticks, POST body, assign called, router never used
2026-11-21 00:42:01 +01:00
Jakub Zych
1d3e6df6ec docs(phase-32.2): update tracking after wave 1 2026-11-21 00:35:58 +01:00
Jakub Zych
9809f9bea8 docs(32.2-01): complete framework seams plan 2026-11-21 00:33:39 +01:00
Jakub Zych
fcc7bbde25 feat(32.2-01): in-transaction BackendAccessRevokedEvent at every admin access change
- cabana: BackendAccessRevokedEvent with reasons deleted, deactivated,
  password_changed, password_set, password_reset and permissions, fired
  synchronously inside the save's transaction; a listener error rolls back
- fired on admin delete, deactivate, a password set by another admin, an own
  password change, admin:reset-password, a role/permissions/superuser change
  and a role's permission change (every holder); MCPSubjectChanged unchanged
- role delete fires nothing (refused while the role has holders); no sign
  out everywhere action exists
- smoke test TestBackendAccessRevokedSmoke (Postgres)
2026-11-21 00:32:26 +01:00
Jakub Zych
3f7ce6020d feat(32.2-01): per-item rows and item actions on My account contributions
- pact: AccountContribution.Items/ItemActions/ItemsEmpty, AccountItem,
  AccountItemAction, AccountItemActionInput, ErrAccountItemNotFound
- cabana: the list sends items (null without Items), permitted item actions
  and the empty line; boot refuses item actions without Items
- cabana: POST {api}/account/contribution-items/{name}/{item}/actions/{action}
  runs only for an item the administrator's own Items listed, in a transaction
  (path outside /account/contributions/ to avoid a ServeMux overlap)
- swag views; admin.json and schema.d.ts regenerated; route inventories
2026-11-21 00:22:13 +01:00
Jakub Zych
97d7ee0586 feat(32.2-01): admin consent endpoint for administrator-only MCP grants
- pact: MCPAdminConsent provider interface, MCPAdminConsentRequest,
  MCPAdminConsentDecision, ErrMCPConsentNotFound, ErrMCPConsentNoScopes
- cabana: GET/POST {api}/mcp/consent/{request}, interactive-only, scope
  policy of personal tokens (requested, catalog, owned; * collapses)
- cabana: TokenScopeNames and TokenScopeLabels export the token-scope catalog
- swag views and annotations; admin.json and schema.d.ts regenerated so the
  contract and conformance inventories stay green
- phrasebook keys mcp_connect.request_not_found and no_grantable_scopes
2026-11-21 00:14:43 +01:00
Jakub Zych
c63bfa3ef2 feat(32.2-01): administrator-only MCP grants and a configurable consent handoff
- pact: MCPGrant.Subject with MCPGrantSubjectBackend, MCPSubject.ScopeLimited
- pier: a backend-subject grant resolves straight to a scope-limited backend
  subject bound to oauth:backend:<client>:<admin>, no link lookup, no ceiling
- pier: the backend guard scope-limits ScopeLimited subjects like g15_ tokens
- wristband: Options.ConsentPath and Options.DefaultScopes; defaults unchanged
- smoke tests TestBackendSubjectSmoke (Postgres) and TestConsentPathSmoke
2026-11-21 00:06:19 +01:00
Jakub Zych
45eb34e5c4 docs(32.2): create phase plan
Five plans in four waves: framework seams, admin SPA consent route and plugin backend mode in parallel, app wiring with a local proof, then unit tests and the release checkpoint. Research open questions marked resolved.
2026-11-20 23:52:23 +01:00
Jakub Zych
9783b3d530 docs(32.2): UI design contract 2026-11-20 23:00:29 +01:00
Jakub Zych
28a07f6b27 docs(32.2): research and validation strategy 2026-11-20 21:58:45 +01:00
Jakub Zych
6c44946dfa docs(state): insert phase 32.2 and record its context session 2026-11-20 20:39:26 +01:00
Jakub Zych
b70071060c docs(32.2): capture phase context 2026-11-20 20:39:13 +01:00
Jakub Zych
e74af3b6c3 docs: capture exploration — mcp-oauth-backend-subject 2026-11-20 19:31:35 +01:00
Jakub Zych
e4863b22fb docs(quick-261119-kj8): sm-user-plugin JWT blacklist sweep as scheduled command 2026-11-19 15:08:10 +01:00
Jakub Zych
005fb4a2cb docs(quick-261118-qsd): compile module README Go examples via src= references 2026-11-18 20:25:00 +01:00
Jakub Zych
8c03cc3621 feat(docsite): require src= on Go code blocks of module READMEs (quick-261118-qsd) 2026-11-18 20:18:38 +01:00
Jakub Zych
1e56d750ef docs(lighthouse,postcard,signpost): compile README Go examples via src= (quick-261118-qsd) 2026-11-18 20:13:14 +01:00
Jakub Zych
a2551d83d7 docs(pact,party,surf): compile README Go examples via src= (quick-261118-qsd) 2026-11-18 20:07:39 +01:00
Jakub Zych
cd55a3980d docs(pier,seaglass,sunrise,sunscreen,tide): compile README Go examples via src= (quick-261118-qsd) 2026-11-18 20:04:47 +01:00
Jakub Zych
6409837b0c docs(phrasebook,sieve,towel,wire,wristband): compile README Go examples via src= (quick-261118-qsd) 2026-11-18 20:01:05 +01:00
Jakub Zych
c517db564c docs(flare,kiosk,lagoon): compile README Go examples via src= (quick-261118-qsd)
- flare: send region run by TestDocsNotifyReply against a loopback TLS push
  service; blogSubscriptions and the publish-source region run by
  TestDocsSubscriptionSource on a Postgres container (skips under -short)
- kiosk: write, newest and client regions run by TestDocsWriteManifest (a
  copy of the literal fixture), ExampleVersionsResponse and
  TestDocsBlogReleases (httptest registry); the CheckT fence reuses
  TestPluginManifest
- lagoon: new open region run by TestDocsOpenFromApp (DocsDSN added to
  export_docs_test.go); the model, create-post, on-database, publish and
  migrations fences reuse the Database pages' targets
2026-11-18 19:53:27 +01:00
Jakub Zych
d04454c57b docs(cooler,diary,festival,fetchguard): compile README Go examples via src= (quick-261118-qsd)
- cooler: ExampleFromApp and the articlesController purge declarations;
  AllowExport run by TestDocsAllowExport on miniredis
- diary: blogLog and ExampleFor; the generated main's run function, run by
  TestDocsRun in a temp directory with diary.Reset on cleanup
- festival: PostPublished/ExampleBus_Fire and PostFormExtended/Collected/
  ExampleBus_Collect, with a TestDocsDeclarations for Collected
- fetchguard: fetch region run by TestDocsFetchImage (loopback refused as
  private_ip), client region run by TestDocsSyncItems on a stub transport
2026-11-18 19:48:01 +01:00
Jakub Zych
becb31fbef docs(cabana,compass,conga): compile README Go examples via src= (quick-261118-qsd)
- cabana: the hand-written controller fence points at Post, PostsController
  and BlogPlugin declarations; TestDocsDeclarations now calls each of them
- compass: mailSettings and ExampleOpen; the YAML block matches the
  directory ExampleOpen writes
- conga: job, dispatch and progress fences reuse the Jobs page targets; new
  reindex and worker regions run in TestDocsDispatch (Docker), and the
  schedule fence is FeedPlugin.Schedule, checked by TestDocsSchedule
2026-11-18 19:44:21 +01:00
Jakub Zych
a0f5b5e561 docs(backpack,beachcomber,boardwalk,bonfire,bouncer): compile README Go examples via src= (quick-261118-qsd)
- backpack: Greeter and ExampleApp_Publish replace the whole-file fence
- beachcomber: Post's Searchable methods plus a new SearchIndexSchema, a
  Plugin.Boot that installs the gate, and the existing gate/search regions
- boardwalk: new example_test.go; the mount region runs in ExampleHandler
- bonfire: importPostsCommand and acmeMain (the binary's main as a function
  returning the exit code), run by ExampleExecute; ExampleCatalog_Has
- bouncer: users/FindByID and ExampleNewJWTGuard; RefreshRoute run by
  TestDocsRefreshRoute on a production compass config
2026-11-18 19:39:50 +01:00
Jakub Zych
48527e4206 docs(breakwater): compile README Go examples via src= (quick-261118-qsd)
- the Usage fence becomes two src= references to ExampleRender and
  ExamplePurify, filled by summer docs:sync
- the Phase 11.1 SC4 acceptance scan now allows top-level src= fences
  in module READMEs (nested ones are still refused) and expects the
  api/<name> pages to caption them like docs/ pages
2026-11-18 19:32:11 +01:00
Jakub Zych
721830c502 feat(docsite): check, caption and sync src= blocks in module READMEs (quick-261118-qsd)
- checkSnippets compares top-level src= fences of module READMEs like
  docs/ pages; the README src= refusal is gone
- Sync also rewrites drifted src= fences in modules/<name>/README.md,
  still all-or-nothing across pages and READMEs
- fenceAnnotator captions top-level src= fences on every page
- the snippet-readme-src planted violation now plants a drifted README
  fence instead of the old refusal
- utilities.md, README.md and CLAUDE.md describe src= in module READMEs
2026-11-18 19:29:36 +01:00
Jakub Zych
830f305376 style: gofmt cabana mail routes and postcard store test 2026-11-18 18:42:59 +01:00
Jakub Zych
66ec8de315 docs(quick-261118-lbt): per-app plugin instances, closable limiter store, one router build 2026-11-18 15:50:11 +01:00
Jakub Zych
38f7f3a777 feat(surf): AssembleRouter builds the router and handler once; the router stops the MCP endpoint it mounted (quick-261118-lbt)
- surf.AssembleRouter returns the router and the compiled handler from
  one build, so an mcp.enabled app is not built twice; Assemble keeps
  its signature and is implemented on top of it
- serve uses AssembleRouter with a deferred Router.Close
- pier.Pier.Close stops the session reaper and the Redis warm-up; the
  router that mounted the endpoint owns it
- ExampleAssembleRouter, routing/testing docs and the surf/pier READMEs
2026-11-18 15:44:56 +01:00
Jakub Zych
d9e21ad019 fix(surf): close the rate-limit store a router created (quick-261118-lbt)
- MemoryStore.Close stops the sweep goroutine; Attempt keeps working
- Router.Close runs what the router owns (the fallback MemoryStore of
  BuildRouter), never a store published on the app
- BuildRouter closes the router on every error return
- serve closes its router and installCooler's fallback store on exit;
  route:list closes its router
- README and rate-limiting docs describe the ownership
2026-11-18 15:41:05 +01:00
Jakub Zych
ea1befdd6c feat(party): give every application its own plugin instances (quick-261118-lbt)
- Register keeps a pristine shallow copy of each pointer-to-struct plugin;
  every Activate hands its application a fresh copy, so a second
  application no longer rebinds the first one's plugins
- value plugins and pointers to non-struct types are used as is
- party.RegisterFactory for plugins whose init builds maps or pointers
- activate() and its tests are unchanged
- README and plugin/lifecycle docs describe the per-application rule
2026-11-18 15:37:06 +01:00
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&#9;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
506 changed files with 65042 additions and 1628 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
@@ -1639,6 +1705,36 @@ Plans:
**Wave 6** *(blocked on Wave 5 completion)*
- [x] 32-06-PLAN.md — unit tests, additive and compat proof, framework patch release, plugin tags, demo mount, changelog
### Phase 32.2: MCP OAuth with administrator subjects (INSERTED)
**Goal:** As an editor of a blog-only application whose MCP tools are backend-guarded (Journal) and which has no frontend users, I want to add the site's `/mcp` as a connector and sign in once as my administrator account over OAuth, so that agents no longer need a hand-copied `g15_` personal token. Delivered as an additive, off-by-default backend-subject mode of `sm-oauthserver-plugin`, so applications on the frontend-user flow (with its verified account link) are unchanged. Decision note: `.planning/notes/2026-11-20-mcp-oauth-backend-subject.md`.
**Mode:** mvp
**Requirements**: TBD
**Depends on:** Phase 32.1 (MCP OAuth for plugin apps), Phase 19.7 (generic MCP module)
**Repos:** `summercms.go`, `sm-oauthserver-plugin`, `sm-grzybyfunkcjonalne-app`
**Plans:** 5/5 plans executed
**Success Criteria** (what must be TRUE):
1. With the backend-subject mode on, `/oauth/mcp/authorize` recognises a signed-in administrator from the cabana cookie session, sends an anonymous browser through the admin login and back, and shows a server-rendered, branded consent page; the issued grant carries the administrator (`BackendUserID`) and no frontend user. With the mode off (the default), every existing flow and test of `sm-oauthserver-plugin` and sm-bm-app passes unchanged.
2. `pier` resolves such a grant straight to the `backend` subject, with no account-link lookup; `tools/list` and tool calls are capped by the administrator's cabana permissions and the granted scopes, the same as a scope-limited `g15_` token.
3. Revoking the grant (a new connected-apps list on cabana My account), or deleting, deactivating or re-passwording the administrator, ends the grant's tokens and its open MCP sessions (`pact.MCPSubjectChanged`).
4. sm-grzybyfunkcjonalne-app mounts `golem15.oauthserver` in backend mode, its proxy routes the OAuth discovery and `/oauth/mcp/*` paths to the Go binary, and an MCP client (Claude connector) completes discovery, registration, sign-in and a Journal tool call over OAuth on a local stack; `g15_` personal tokens keep working.
5. Module READMEs, `docs/` pages and the app's DEPLOY.md are updated; the new code has unit tests in the phase's last plan; the framework and `sm-oauthserver-plugin` get patch tags.
Plans:
**Wave 1**
- [x] 32.2-01-PLAN.md — Framework seams: pact backend grant and consent provider, wristband handoff, pier scope limit, cabana consent endpoint, revoke event, account items
**Wave 2** *(blocked on Wave 1 completion)*
- [x] 32.2-02-PLAN.md — Admin SPA consent route, switch account, account items, openapi and dist
- [x] 32.2-03-PLAN.md — sm-oauthserver-plugin backend mode: config, migration, store, verifier, consent provider, revocation, My account, connections screen
**Wave 3** *(blocked on Wave 2 completion)*
- [x] 32.2-04-PLAN.md — sm-grzybyfunkcjonalne-app wiring, local MCP OAuth proof, DEPLOY.md
**Wave 4** *(blocked on Wave 3 completion)*
- [x] 32.2-05-PLAN.md — Unit tests, regressions and release checkpoint
### Phase 32.1: MCP OAuth for plugin apps: declared scopes, MCP subject on context, per-client MCP consent (INSERTED)
**Goal:** As an application whose plugins declare their own member token scopes, I want an agent connected to `/mcp` over OAuth to get the same tools, attribution and revocation as one using a personal token, so that OAuth sign-in can be switched on in production. A consuming app's agent-access work found three gaps (its D-36, D-37 and D-38); all three are additive and ship as patch releases of the framework (0.5.x) and `sm-oauthserver-plugin`.
@@ -1692,7 +1788,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 +1821,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 +1915,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 +1940,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,19 @@
---
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 32.2 context gathered
last_updated: "2026-11-20T19:39:15.961Z"
last_activity: 2026-11-19
last_activity_desc: "Completed quick task 261119-kj8: sm-user-plugin JWT blacklist sweep as scheduled command"
state_head: b70071060c600f37c2d24cb230c21601031e53d1
progress:
total_phases: 47
total_phases: 53
completed_phases: 37
total_plans: 242
completed_plans: 238
total_plans: 304
completed_plans: 293
gsd_state_version: "1.0"
milestone_name: milestone
---
@@ -25,22 +25,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-19 — Completed quick task 261119-kj8: sm-user-plugin JWT blacklist sweep as scheduled command
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 +68,7 @@ Progress: [████████░░] 82%
| 19.4 | 4 | - | - |
| 19.5 | 5 | - | - |
| 19.6.1 | 5 | - | - |
| 35 | 9 | - | - |
**Recent Trend:**
@@ -278,6 +279,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 +362,12 @@ 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
- Phase 32.2 inserted after Phase 32: MCP OAuth with administrator subjects: backend-subject mode in sm-oauthserver-plugin so blog-only apps (grzybyfunkcjonalne) accept OAuth for backend-guarded Journal tools
### Decisions
@@ -954,41 +1005,149 @@ 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
- [2026-10-01] [docs] Benchmark Płytarium on WinterCMS vs SummerCMS and publish a measured table — [todo file](.planning/todos/pending/2026-10-01-benchmark-the-application-on-wintercms-vs-summercms.md)
- [2026-10-07] [sm-translate-plugin] Translate Messages as a Nuxt i18n JSON editor — [todo file](.planning/todos/pending/2026-10-07-translate-messages-as-nuxt-i18n-json-editor.md)
- [2026-10-10] [framework] Prompt open admin and site tabs to reload when a new version is deployed — [todo file](.planning/todos/pending/2026-10-11-reload-open-apps-when-a-new-version-is-deployed.md) — Needs TBD. Ideas:.
- [2026-10-11] [lagoon/attach, fonoteka.go uploads] Uploads keep the client file extension, so a valid image can be served as HTML (stored XSS) — [todo file](.planning/todos/pending/2026-10-11-uploads-keep-client-extension-stored-xss.md)
- [unknown] [sm-user-plugin / cabana] Verified link between a frontend user and a backend user — [todo file](.planning/todos/pending/2026-10-17-frontend-backend-account-link.md)
- [unknown] [sm-user-plugin / pact] Plugins register their frontend permission codes in Go — [todo file](.planning/todos/pending/2026-10-17-plugin-registered-frontend-permissions.md)
- [2026-10-19] [sm-oauthserver-plugin] Record PHP OIDC parity against WavePath before the OIDC cutover — [todo file](.planning/todos/pending/2026-10-19-record-php-oidc-parity-against-wavepath.md)
- [2026-10-20] [consumers] Move grzybyfunkcjonalne to NUXT_CACHE_PURGE_TOKEN and the new layers before the NUXT_SITE_CACHE_* names are dropped — [todo file](.planning/todos/pending/2026-10-20-rename-site-cache-purge-env-in-consumers.md)
- [2026-10-21] [framework] Quiet plugin boot logs on console commands like --help — [todo file](.planning/todos/pending/2026-10-21-quiet-plugin-boot-logs-on-console-commands.md) — Needs TBD. Options, possibly combined:.
- [2026-10-22] [framework] Console review info findings (IN-01..IN-13) and the delegate signal exit code — [todo file](.planning/todos/pending/2026-10-22-console-review-info-findings.md)
- [2026-10-22] [sm-user-plugin] User login ignores is_activated — [todo file](.planning/todos/pending/2026-10-22-user-login-ignores-is-activated.md)
- [2026-10-22] [sm-user-plugin] User login lockout and same-second cutoff — [todo file](.planning/todos/pending/2026-10-22-user-login-lockout-and-same-second-cutoff.md)
- [2026-10-22] [sm-user-plugin] User login opt-in session cookie — [todo file](.planning/todos/pending/2026-10-22-user-login-opt-in-session-cookie.md)
- [2026-10-22] [sm-user-plugin] User logout blacklist missing under serve — [todo file](.planning/todos/pending/2026-10-22-user-logout-blacklist-missing-under-serve.md)
- [2026-10-22] [user-plugin] User plugin logout leaves the session cookie valid for up to 60 minutes — [todo file](.planning/todos/pending/2026-10-22-user-logout-cookie-stays-valid.md)
- [2026-10-22] [sm-user-plugin] User password routes 404 switch — [todo file](.planning/todos/pending/2026-10-22-user-password-routes-404-switch.md)
- [2026-10-22] [sm-user-plugin] User session routes ignore the cookie — [todo file](.planning/todos/pending/2026-10-22-user-session-routes-ignore-cookie.md)
- [unknown] [cabana / admin] Audit-log admin action runs with the admin id (toolbar actions) — [todo file](.planning/todos/pending/admin-action-audit-log.md)
- [unknown] [sm-faq-plugin] Port the FAQ plugin as sm-faq-plugin so FAQs become editable — [todo file](.planning/todos/pending/faq-plugin-port.md)
- [unknown] [summercms.go lagoon] lagoon README registers an after-commit GORM callback that can sort after the flush — [todo file](.planning/todos/pending/lagoon-readme-after-commit-callback-order.md)
- [2026-10-28] [framework] Earlier phase gate scripts still name consuming applications — [todo file](.planning/todos/pending/2026-10-28-earlier-phase-gates-name-consuming-apps.md)
- [2026-10-29] [consumers] Stream-aware previous/next links on the summercms.io changelog — [todo file](.planning/todos/pending/2026-10-29-stream-aware-previous-next-on-summercms-io-changelog.md)
- [unknown] [vue-chat-layer app/composables/useChat.ts] Chat messages that start with "/" but name no command are posted as text — [todo file](.planning/todos/pending/chat-slash-text-escape.md)
- [unknown] [vue-forum-layer app/utils/forumClient.ts, vue-userfriends-layer app/utils/friendsClient.ts] Single-flight 401 refresh in the forum and friends clients,… — [todo file](.planning/todos/pending/forum-friends-client-401-refresh.md)
- [unknown] [sm-user-plugin mail] Port MailBlocker and the block-mail checkbox with the mailing work — [todo file](.planning/todos/pending/mailblocker-with-mailing.md)
- [unknown] [sm-menu-plugin] Port the menu plugin as sm-menu-plugin so blog menus become editable — [todo file](.planning/todos/pending/menu-plugin-port.md)
- [unknown] [sm-demo-app plugins/demo/moderation.go (with seams in user, userfriends and chat)] Moderate profile names, friend-group names and chat attachment… — [todo file](.planning/todos/pending/moderation-profile-group-and-filenames.md)
- [2026-10-21] [sm-user-plugin] Let password-less social accounts set a first password through change-password — [todo file](.planning/todos/pending/oauth-password-bootstrap-change-password.md)
- [unknown] [summercms.go/modules/*/README.md, internal/docsite] Convert module README Go code blocks to compiled src= references — [todo file](.planning/todos/pending/readme-go-fences-src.md)
- [unknown] [../fonoteka.go/README.md] Refresh fonoteka.go README — short status plus migrate/serve/login — [todo file](.planning/todos/pending/refresh-fonoteka-readme.md)
- [unknown] [cabana] Show the administrators holding a role on the Roles screen — [todo file](.planning/todos/pending/roles-screen-holders-list.md)
- [unknown] [summercms.go internal/build] make:admin-controller output does not boot and names the model after the controller — [todo file](.planning/todos/pending/scaffold-admin-controller-incomplete.md)
- [unknown] [summercms.go internal/build] Scaffolded files carry a DO NOT EDIT header, and make:command cannot reach the application — [todo file](.planning/todos/pending/scaffold-generated-header-and-command-deps.md)
- [unknown] [summercms.go internal/build] make:model and make:migration in the same second produce migrations that run out of order — [todo file](.planning/todos/pending/scaffold-same-second-migration-order.md)
- [2026-10-12] [framework] Purge the Nuxt site cache on menu and FAQ admin saves (framework-level purge service) — [todo file](.planning/todos/pending/site-cache-purge-for-menu-and-faq.md)
- [unknown] [sm-sitemap-plugin] Port the sitemap plugin 1:1 as sm-sitemap-plugin for the next blog project — [todo file](.planning/todos/pending/sitemap-plugin-port.md)
- [unknown] [sm-sitemap-plugin] Sitemap - replace the browser XSLT view before Chromium drops XSLT — [todo file](.planning/todos/pending/sitemap-xslt-browser-deprecation.md)
### Blockers/Concerns
@@ -999,13 +1158,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 +1222,39 @@ 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/) |
| 261118-lbt | Per-app plugin instances, closable limiter store, one router build | 2026-11-18 | 38f7f3a7 | [261118-lbt-per-app-plugin-instances-closable-limite](./quick/261118-lbt-per-app-plugin-instances-closable-limite/) |
| 261118-qsd | Compile module README Go examples via src= references | 2026-11-18 | 8c03cc36 | [261118-qsd-compile-module-readme-go-examples-via-sr](./quick/261118-qsd-compile-module-readme-go-examples-via-sr/) |
| 261119-kj8 | sm-user-plugin: JWT blacklist sweep as scheduled user:jwt-blacklist-sweep command (sm-user-plugin bc5f4f7) | 2026-11-19 | bc5f4f7 | [261119-kj8-sm-user-plugin-replace-the-jwt-blacklist](./quick/261119-kj8-sm-user-plugin-replace-the-jwt-blacklist/) |
## Deferred Items
@@ -1079,6 +1266,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-20T19:39:14.066Z
Stopped at: Phase 32.2 context gathered
Resume file: .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-CONTEXT.md

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,31 @@
---
title: MCP OAuth with administrator subjects (backend-subject mode of sm-oauthserver-plugin)
date: 2026-11-20
context: /msd-explore session. sm-bm-app's MCP accepts OAuth sign-in because it mounts golem15.oauthserver and its Nuxt site has a login page and the /connect consent page. sm-grzybyfunkcjonalne-app's MCP only accepts admin g15_ personal tokens; its tools are the Journal's backend-guarded blog tools, and the site has no frontend users at all.
---
# MCP OAuth with administrator subjects
## Starting point
- An MCP OAuth grant's subject is always a frontend user (`pact.MCPGrant.UserID`). Backend-guarded tools appear only when the grant carries the `backend` scope and that frontend user has a verified link to an administrator (`sm-user-plugin` `BackendLinks`, confirmed on `/link-admin` with a fresh sign-in; `pier/identity.go` `consentedBackendSubject`). That is decisions 5 and 6 of `2026-10-17-generic-mcp-module.md`, and it is built.
- sm-grzybyfunkcjonalne-app has none of what that path needs: `golem15.oauthserver` is not mounted (`config/mcp.yaml`: "no OAuth server on this site"), and the Nuxt site extends only the journal, menu, faq and seo layers. It has no login, no `/connect` and no `/link-admin` page. Its only real users are a few editors, and they are administrators.
- The cabana admin session is an HttpOnly cookie on the same origin (`admin/src/api/client.ts`). `sm-oauthserver-plugin` already renders its own consent and error pages in Go (`views/consent.html.tmpl`, `error.html.tmpl`) with branding.
## Decisions
1. **On grzyby, the OAuth sign-in authenticates an administrator.** There are no frontend users there. Giving editors frontend accounts plus a link only to reach their own admin tools would add a public login surface to a blog for no gain.
2. **It is an additive mode of `sm-oauthserver-plugin`, not a new framework module.** One authorization server keeps one implementation of code stores, PKCE, refresh rotation, replay-family revocation, the Clients and Branding screens, and pruning. The mode is off by default, so sm-bm-app, sm-demo-app and every other consumer stay unchanged (core plugin, no breaking changes).
## Shape of the change (to be settled in discuss-phase)
- **sm-oauthserver-plugin:** a config key (working name `mcp.subject: backend`, default `user`). In backend mode, `/oauth/mcp/authorize` recognises a signed-in administrator from the cabana cookie and sends an anonymous browser to the admin login with a return URL. Consent is a server-rendered Go page (reuse `consent.html.tmpl` and branding), not the Nuxt `/connect`. The grant records `BackendUserID` with no `UserID`. That needs an additive migration if `user_id` is NOT NULL, revocation when the administrator is deleted, deactivated or changes password, and a "Connected apps" list with revoke on cabana My account. The `Requires()` on `golem15.user` is a question for this mode only. grzyby mounts golem15.user anyway.
- **summercms.go `pier`:** a grant with only `BackendUserID` resolves straight to the backend subject (guard `backend`), with no link lookup. Tools are capped by the administrator's cabana permissions and the granted scopes, as for a `g15_` token with a scope limit. An administrator change or revocation fires `pact.MCPSubjectChanged`, so open sessions re-list or end.
- **sm-grzybyfunkcjonalne-app:** add `golem15.oauthserver` to `summer.yaml`. Add `config/golem15.oauthserver.yaml` with the backend mode, `mcp.enabled` and `mcp.resource`, which must equal `mcp.resource` in `config/mcp.yaml`. Add proxy rules so `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource` and `/oauth/mcp/*` reach the Go binary and not Nuxt. `allow_personal_tokens: true` stays, so existing `g15_` agents keep working. Update DEPLOY.md.
## Open questions
- Can one application run both subject modes at once (for example the demo: frontend users and admins as separate MCP subjects), or is it one mode per application?
- Does consent let the administrator narrow the scopes (read only, no write), like the 32.1 `/connect` checkboxes?
- Do the Claude and ChatGPT connectors complete dynamic client registration and discovery unchanged against the backend-mode server? Not checked in this session.
- Admin-login brute-force and the Turnstile/2FA gates: does the authorize redirect reuse the cabana login unchanged, including the device or second-factor steps?

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

@@ -0,0 +1,401 @@
---
phase: 32.2
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- modules/pact/mcp.go
- modules/pact/capabilities.go
- modules/pact/README.md
- modules/wristband/server.go
- modules/wristband/authorize.go
- modules/wristband/consent_path_smoke_test.go
- modules/wristband/README.md
- modules/pier/identity.go
- modules/pier/backend_guard.go
- modules/pier/backend_subject_smoke_test.go
- modules/pier/README.md
- modules/cabana/token_scopes_export.go
- modules/cabana/mcp_consent.go
- modules/cabana/mcp_consent_smoke_test.go
- modules/cabana/account_contributions.go
- modules/cabana/account_items_smoke_test.go
- modules/cabana/admin_events.go
- modules/cabana/backend_access_revoked_smoke_test.go
- modules/cabana/backend_users_admin.go
- modules/cabana/backend_roles_admin.go
- modules/cabana/account.go
- modules/cabana/commands.go
- modules/cabana/http.go
- modules/cabana/admin_openapi.go
- modules/cabana/README.md
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- docs/services/mcp.md
- docs/services/oauth-server.md
- docs/services/events.md
- docs/backend/users-and-permissions.md
- docs/plugins/registration.md
autonomous: true
requirements: [SC-1, SC-2, SC-3, SC-5]
estimate:
tokens: 120000
raw_tokens: 120000
tasks: 4
confidence: low
must_haves:
truths:
- "SC-1, D-04: wristband Options.ConsentPath and Options.DefaultScopes are new. Empty ConsentPath keeps the authorize handoff byte-identical to today ({issuer}/connect?request=<id>); a set path is appended to the issuer instead. Empty DefaultScopes keeps the PHP fallback read; a set list (filtered to the resolved allowed set) is what an authorize request with no data scope gets. DefaultOptions is unchanged."
- "SC-2, D-01, D-09: pact.MCPGrant has Subject (pact.MCPGrantSubjectBackend = backend) and pact.MCPSubject has ScopeLimited. pier resolves a grant with Subject backend, UserID 0 and BackendUserID set straight to a backend subject: no frontend subject, no MCPLinkedBackendResolver lookup, binding oauth:backend:<client>:<admin>, read/write ceiling off, ScopeLimited true."
- "SC-2, D-09: the backend guard applies cabana.ScopeLimitFor to a subject with ScopeLimited true exactly as to a g15_ personal-token subject; a linked user-mode grant (ScopeLimited false, ClientID set) still gets no scope limit, and a grant with Subject empty and UserID 0 is still refused."
- "SC-1, D-03, D-11: cabana serves GET and POST {admin api}/mcp/consent/{request} inside the backend-guarded admin group, interactive-only (a g15_ token gets 403 interactive_only) and X-Requested-With on POST. It delegates to a published pact.MCPAdminConsent and answers 404 request_not_found when none is published or the provider answers pact.ErrMCPConsentNotFound. Show lists only requested ∩ catalog ∩ scopes the administrator can use; Decide drops submitted scopes outside that set, collapses * like token creation, and answers 422 no_grantable_scopes when nothing is left."
- "D-09: cabana.TokenScopeNames(app) answers the token-scope catalog names in catalog order (*, admin:read, then plugin TokenScopes) before cabana.Activate, and cabana.TokenScopeLabels translates catalog names to their labels."
- "SC-3, D-12: pact.AccountContribution gains Items, ItemActions and ItemsEmpty. A section with nil Items serialises items as null and renders as today; a section with Items always sends an array. POST /account/contributions/{name}/items/{item}/actions/{action} answers 404 for an item the administrator's own Items did not list or when Run answers pact.ErrAccountItemNotFound, 403 for missing permissions, and runs Run inside a transaction."
- "SC-3, D-13: cabana.BackendAccessRevokedEvent is fired synchronously inside the save's transaction on admin delete, deactivate, password set by another admin, own password change, admin:reset-password, the administrator's role/own permissions/superuser flag change, and a role's permission change (for every holder). A listener error rolls the save back. The existing after-commit MCPSubjectChanged emissions are unchanged. Sign out everywhere is not offered by cabana; the docs say so."
- "SC-5: module READMEs (pact, wristband, pier, cabana) and docs/services/mcp.md, oauth-server.md, events.md, docs/backend/users-and-permissions.md and docs/plugins/registration.md describe every identifier this plan adds, in the commit that adds it; framework docs and code never name a consuming application; docs:build --check passes."
artifacts:
- path: modules/pact/mcp.go
provides: "MCPGrant.Subject, MCPGrantSubjectBackend, MCPSubject.ScopeLimited, MCPAdminConsent, MCPAdminConsentRequest, MCPAdminConsentDecision, ErrMCPConsentNotFound, ErrMCPConsentNoScopes"
contains: "MCPGrantSubjectBackend"
- path: modules/pact/capabilities.go
provides: "AccountContribution.Items/ItemActions/ItemsEmpty, AccountItem, AccountItemAction, AccountItemActionInput, ErrAccountItemNotFound"
contains: "AccountItemAction"
- path: modules/wristband/server.go
provides: "Options.ConsentPath, Options.DefaultScopes"
contains: "ConsentPath"
- path: modules/pier/identity.go
provides: "backend-only grant branch of resolveOAuth"
contains: "MCPGrantSubjectBackend"
- path: modules/cabana/mcp_consent.go
provides: "GET/POST {api}/mcp/consent/{request} handlers"
contains: "MCPAdminConsent"
- path: modules/cabana/token_scopes_export.go
provides: "TokenScopeNames, TokenScopeLabels"
contains: "func TokenScopeNames"
- path: modules/cabana/admin_events.go
provides: "BackendAccessRevokedEvent and reason constants, fireBackendAccessRevoked"
contains: "BackendAccessRevokedEvent"
key_links:
- from: modules/wristband/authorize.go
to: Options.ConsentPath
via: "handoff URL built from issuer + consent path (default /connect)"
pattern: "ConsentPath"
- from: modules/pier/identity.go resolveOAuth
to: modules/pier/backend_guard.go principal
via: "MCPSubject.ScopeLimited set by the backend branch, read by the scope-limit condition"
pattern: "ScopeLimited"
- from: modules/cabana/mcp_consent.go
to: pact.MCPAdminConsent
via: "app.Lookup at request time"
pattern: "Lookup\\[pact.MCPAdminConsent\\]"
- from: modules/cabana/backend_users_admin.go, account.go, commands.go, backend_roles_admin.go
to: modules/cabana/admin_events.go
via: "fireBackendAccessRevoked with the save's transaction"
pattern: "fireBackendAccessRevoked"
---
<objective>
User story (phase goal, ROADMAP 32.2): **As an** editor of a blog-only application whose MCP tools are backend-guarded (Journal) and which has no frontend users, **I want to** add the site's `/mcp` as a connector and sign in once as my administrator account over OAuth, **so that** agents no longer need a hand-copied `g15_` personal token.
Slice in this plan (the thin end-to-end path the tracer proves): an MCP client holding an administrator-only grant calls tools/list on `/mcp` and sees only the backend tools that the administrator's cabana permissions and granted scopes allow. That is the same cap a `g15_` token with those scopes gets. The tracer sends a real HTTP request through pier, the backend guard and cabana.ScopeLimitFor to a Postgres-backed backend tool (TestBackendSubjectSmoke), and proves that wristband hands authorize off to a configured consent path (TestConsentPathSmoke). The token comes from a fake verifier because issuing it is plan 03's job.
Lean-split exception (accepted; recorded for the MVP check): the phase's plans follow repository and surface boundaries (01 framework, 02 admin SPA, 03 sm-oauthserver-plugin, 04 the first consumer app, 05 tests and release), not user-visible slices. The user confirmed this 5-plan split under the project's lean-planning rule (CLAUDE.md, "few, large plans per phase"). The boundaries also match the release order, because the plugin can only require a framework version that has been tagged. Each plan still leads with a tracer through every layer it touches. The first real-token path is plan 03's tracer (authorize, cabana consent, token, verifier). The first path a person can run end to end (discovery, registration, admin sign-in, consent, Journal tool call) is plan 04's tracer. On its own, plan 01's only observable result is the tracer's tools/list response.
Framework seams for SC-1, SC-2, SC-3 and the framework half of SC-5 (D-01, D-03, D-04, D-09, D-11, D-12, D-13): the pieces of summercms.go that an administrator-subject mode of the OAuth server plugin needs, all additive and off unless a plugin uses them.
Purpose: plans 02 (admin SPA) and 03 (sm-oauthserver-plugin backend mode) build against these contracts. Every zero value means today's behaviour, so applications on the frontend-user MCP flow are unchanged.
Output: pact, wristband, pier and cabana API, the cabana consent endpoint and account-item route with swag annotations, the in-transaction revocation event at every D-13 site, smoke tests, and the READMEs and docs pages in the same commits. The broad unit-test pass is plan 05. The openapi document and the SPA types are regenerated in plan 02, not here.
⚠ spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip). SC-1..SC-5 from the ROADMAP stand in as requirements.
Discretion recorded here (CONTEXT "Claude's Discretion"):
- pier representation: pact.MCPGrant.Subject with the constant pact.MCPGrantSubjectBackend; UserID stays 0 and BackendUserID carries the administrator.
- Consent JSON lives in cabana under the admin API and delegates to a published pact.MCPAdminConsent provider, because plugin routes cannot read the admin cookie (cabana.ResolveBackend never reads it) and the SPA cannot load plugin code. cabana owns the scope policy (catalog, scopeOverlaps, validateTokenScopes); the provider only resolves and issues.
- D-13 uses a new in-transaction cabana event mirroring sm-user-plugin's AccessRevokedEvent. Sign out everywhere: cabana has no such action; documented as not offered.
- Reversibility: D-04 and the new pact types are costly (published contracts other apps will adopt), recorded on the tasks; no one-way door, so no checkpoint.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-CONTEXT.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-RESEARCH.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-PATTERNS.md
@.planning/notes/2026-11-20-mcp-oauth-backend-subject.md
@.planning/notes/oauth2-wristband-direct-port.md
@modules/pact/mcp.go
@modules/pact/capabilities.go
@modules/wristband/server.go
@modules/wristband/authorize.go
@modules/wristband/consent.go
@modules/pier/identity.go
@modules/pier/backend_guard.go
@modules/pier/events.go
@modules/cabana/token_scopes.go
@modules/cabana/token_commands.go
@modules/cabana/token_resolver.go
@modules/cabana/api_tokens.go
@modules/cabana/account_tokens.go
@modules/cabana/account_contributions.go
@modules/cabana/subject_events.go
@modules/cabana/http.go
@modules/cabana/admin_openapi.go
<interfaces>
Existing (read this session):
- pact.MCPGrant{UserID uint; ClientID string; TokenID uint; Scopes []string; ExpiresAt time.Time; BackendUserID uint}
- pact.MCPSubject{Guard string; UserID uint; Scopes []string; ClientID string; TokenID uint}
- pact.MCPSubjectChanged{Guard, UserID, Kind, TokenID, ClientID}; kinds MCPSubjectPermissions, MCPSubjectLink, MCPSubjectRevoked, MCPSubjectDeleted
- pact.AccountContribution{Name, Label, Description string; Status func(ctx, adminID uint) (string, error) `json:"-"`; Actions []AccountAction}
- pact.AccountAction{Name, Label, Confirm string; Danger bool; Permissions []string; Applies func(ctx, adminID uint) (bool, error); Run func(ctx, AccountActionInput) (AccountActionResult, error)}
- pact.AccountActionResult{Message, URL string}
- wristband: authorize.go line 187 builds the handoff as s.opts.Issuer + "/connect?request=" + rfc3986Escape(requestID); parseAuthorizeScopes falls back to []string{"read"} at line 250
- wristband: (s *Server) PendingRequest(ctx, requestID, userID) (PendingRequestView, error); IssueCode(ctx, requestID, userID, grantedScopes, collectionIDs) (string, error); DenyPending(ctx, requestID, userID) (string, error); ErrPendingNotFound, ErrNoGrantableScopes
- pier: resolveOAuth refuses grant.UserID == 0; Identity has unexported ceiling and consentedBackend; writes() = !ceiling || Scopes contains write; fingerprint() writes each subject's Guard:UserID:ClientID:sorted scopes
- pier backend_guard.go principal: scope limit only when subject.ClientID == "" && subject.TokenID != 0, through cabana.ScopeLimitFor(g.app, subject.Scopes, method), known == 0 → errScopeUnavailable
- cabana: scopeAll "*", scopeAdminRead "admin:read"; tokenCatalogForApp(app) (*Registry, error) compiles the catalog from party.Activated; scopeOverlaps(reg, owner, name) bool; validateTokenScopes(reg, owner, scopes) ([]string, map[string]any); mapCompiledScope(ctx, tr, scope) AdminAPITokenScope{Name, Label, Description, ReadOnly, Known}
- cabana: accountPrincipal(w, r) *bouncer.Principal; interactiveOnly(h); requireAjax(h); WriteData; WriteError; WriteErrorDetails; backendMessage(ctx, tr, key, fallback); TxFromContext(ctx) (*gorm.DB, bool); lagoon.AfterCommit
- cabana: fireSubjectChanged(ctx, app, kind, adminIDs...) fires MCPSubjectChanged after commit; revocationCutoff()
- cabana http.go line 335: r.GroupRaw(api, []string{"backend", "locale.from-principal"}, ...) holds /account* routes, e.g. g.Post("/account/contributions/{name}/actions/{action}", interactiveOnly(requireAjax(s.accountContributionAction)))
- cabana admin_openapi.go: AccountContributionView, AccountContributionActionView, AccountActionResultView and swag doc funcs AdminAccountContributions / AdminAccountContributionAction
- D-13 sites: backend_users_admin.go FormAfterDelete (tx from TxFromContext), the deactivate lifecycle action (Updates is_activated false + tokens_valid_after), FormBeforeUpdate (storePassword changed → cutoff), FormAfterUpdate (role/permissions/superuser change → MCPSubjectPermissions); backend_roles_admin.go FormAfterUpdate (holders); account.go accountUpdate changePassword inside its transaction closure (variable tx); commands.go admin:reset-password inside gdb.Transaction(func(tx *gorm.DB) error)
- sm-user-plugin classes/events.go AccessRevokedEvent{UserIDs []uint; Before time.Time; Reason string; Tx *gorm.DB} is the shape to mirror
</interfaces>
</context>
<tasks>
<task type="tracer">
<name>Tracer: an administrator-only grant reaches a backend tool through pier, scope-limited, and wristband hands off to a configured consent path</name>
<reversibility rating="costly">D-04 makes the handoff path a public wristband option, and MCPGrant.Subject / MCPSubject.ScopeLimited become a grant shape other plugins will produce and read.</reversibility>
<precondition>docker info exits 0 (the pier backend-guard smoke uses a testcontainers Postgres like modules/pier/backend_scope_unavailable_test.go).</precondition>
<files>modules/pact/mcp.go, modules/wristband/server.go, modules/wristband/authorize.go, modules/wristband/consent_path_smoke_test.go, modules/pier/identity.go, modules/pier/backend_guard.go, modules/pier/backend_subject_smoke_test.go, modules/pact/README.md, modules/wristband/README.md, modules/pier/README.md, docs/services/mcp.md, docs/services/oauth-server.md</files>
<read_first>
modules/pact/mcp.go (MCPSubject at line 134, MCPGrant at line 280, MCPLinkedBackendResolver)
modules/wristband/server.go (Options; ScopesSupported doc comment is the empty-means-default pattern; DefaultOptions)
modules/wristband/authorize.go (line 187 handoff, line 43 comment, parseAuthorizeScopes fallback at line 250, allowedAuthorizeScopes)
modules/wristband/mcp_scopes_smoke_test.go (smoke test shape to copy)
modules/pier/identity.go (resolveOAuth, consentedBackendSubject, writes, fingerprint)
modules/pier/backend_guard.go (principal)
modules/pier/events.go (revokedMatch and refreshBackend; read only, no change expected)
modules/pier/backend_scope_unavailable_test.go (Docker harness for cabana-backed backend tools to copy)
modules/pier/helpers_test.go (fake verifier acmeVerifier)
.planning/notes/oauth2-wristband-direct-port.md (default bytes must stay PHP-identical)
</read_first>
<action>
pact (modules/pact/mcp.go), per D-01 and D-09: add Subject string to MCPGrant, documented as the kind of subject the grant names; empty means the frontend user in UserID (today's meaning). Add exported const MCPGrantSubjectBackend = "backend": the grant's subject is the backend account in BackendUserID, UserID is 0 and no frontend user is involved. Add ScopeLimited bool to MCPSubject: when true, the guard caps the subject with the same scope limit a personal token with those scopes gets. Zero values keep every existing producer and reader unchanged. Update the MCPGrant and BackendUserID doc comments so they describe both meanings.
wristband (D-04): add Options.ConsentPath string, appended to Issuer for the MCP authorize handoff; empty means "/connect". Add Options.DefaultScopes []string: the scopes an MCP authorize request gets when it names no data scope (absent, empty or identity-only scope value); empty means the PHP default read. Leave DefaultOptions unchanged. In authorize.go build the handoff from Issuer + resolved consent path + "?request=" + rfc3986Escape(requestID), so the default bytes are identical to today. Thread the default-scope list into the empty-scope fallback of parseAuthorizeScopes (resolved per server: DefaultScopes filtered to the server's allowed set; if empty after filtering, read). Do not change client lookup, redirect matching, PKCE, resource validation or the order of checks. Update the line 43 comment and the Options doc comments. OIDC flavour is unaffected.
pier (D-01, D-09): in resolveOAuth, after MCPVerifyToken succeeds, branch when grant.Subject == pact.MCPGrantSubjectBackend: refuse with ErrUnauthorized unless grant.UserID == 0 and grant.BackendUserID != 0; otherwise build Identity with Scopes cloned, Binding "oauth:backend:" + ClientID + ":" + BackendUserID, ExpiresAt, TokenKind TokenKindOAuth, ceiling false, no Frontend subject even when a frontend guard is registered, and Backend = &pact.MCPSubject{Guard: BackendGuard, UserID: BackendUserID, Scopes, ClientID, TokenID, ScopeLimited: true}. Do not call linkedBackend or consentedBackendSubject on that path. The existing path below stays byte-for-byte the same, including the grant.UserID == 0 refusal for grants without the backend subject. In backend_guard.go principal change the scope-limit condition to apply when (subject.ClientID == "" and subject.TokenID != 0) or subject.ScopeLimited; user-mode linked grants never set ScopeLimited, so they stay unlimited (D-09 says that must not change). Add ScopeLimited to the per-subject part of fingerprint() so a change re-filters a cached server. Do not edit filter.go.
Smoke tests, same commit. modules/wristband/consent_path_smoke_test.go TestConsentPathSmoke: a server with default options redirects a valid authorize request to {issuer}/connect?request=..., a server with ConsentPath "/admin/connect" redirects to {issuer}/admin/connect?request=..., and a server with DefaultScopes ["acme"] and acme in ScopesSupported stores acme for a request with no scope (read via PendingRequest). modules/pier/backend_subject_smoke_test.go TestBackendSubjectSmoke (Docker, package pier_test, copy the backend_scope_unavailable_test.go harness): a fake verifier answers a grant with Subject backend, UserID 0, BackendUserID = a seeded administrator and Scopes [admin:read]; tools/list over /mcp lists a read-only backend tool and hides a write backend tool of the fixture controller; the same verifier answering Subject "" and UserID 0 gets 401. Skip under testing.Short(), with flag.Parse() handled the way the existing pier Docker tests do.
Docs in the same commit (D-04, D-09, SC-5): modules/pact/README.md (MCPGrant.Subject, MCPGrantSubjectBackend, MCPSubject.ScopeLimited), modules/wristband/README.md (ConsentPath, DefaultScopes, defaults unchanged), modules/pier/README.md (administrator-only grants: backend subject straight from the grant, no link lookup, distinct binding, ceiling off, scope limit like a personal token; linked grants unchanged), docs/services/mcp.md and docs/services/oauth-server.md (the same rules in prose). Prose only, no new Go code block unless it is a src= reference into compiled test code refreshed with summer docs:sync. Never name a consuming application in framework code or docs. Stage only the files of this task by path; do not git add -A; leave other sessions' uncommitted files alone.
</action>
<verify>
<automated>go test -count=1 -run 'TestBackendSubjectSmoke|TestConsentPathSmoke|TestMCPScopesSmoke|TestMCPSeam|TestDiscoveryFields|TestBackendScopeUnavailable' ./modules/pier ./modules/wristband</automated>
<fails_when>non-zero exit, or a line contains FAIL, or the output contains `[no tests to run]`, or `--- SKIP: TestBackendSubjectSmoke` appears, or TestBackendSubjectSmoke or TestConsentPathSmoke has no `--- PASS` line (run with -v if needed)</fails_when>
<automated>go vet ./modules/pact ./modules/pier ./modules/wristband && go test -short -count=1 ./modules/pact ./modules/pier ./modules/wristband && go test ./cmd/summer -run TestDocsTree -count=1 && go run ./cmd/summer docs:build --check</automated>
<fails_when>non-zero exit, or a line contains FAIL, or docs:build prints a problem line</fails_when>
</verify>
<acceptance_criteria>
- modules/pact/mcp.go contains `MCPGrantSubjectBackend = "backend"`, a `Subject string` field on MCPGrant and a `ScopeLimited bool` field on MCPSubject.
- modules/wristband/server.go contains `ConsentPath string` and `DefaultScopes []string` on Options; DefaultOptions has no ConsentPath or DefaultScopes entry.
- TestConsentPathSmoke passes, proving the default handoff is exactly {issuer}/connect?request=<id>.
- `grep -n 'subject.ScopeLimited' modules/pier/backend_guard.go` finds the scope-limit condition; `grep -n '"oauth:backend:"' modules/pier/identity.go` finds the backend binding.
- TestBackendSubjectSmoke passes (not skipped): admin:read grant lists the read-only backend tool and not the write tool; a grant with empty Subject and UserID 0 gets 401.
- modules/pier/filter.go has no diff in this commit.
- TestDocsTree and docs:build --check pass; `git grep -n -i 'grzyby' -- modules/pact modules/wristband modules/pier modules/cabana docs` prints nothing.
</acceptance_criteria>
<done>An administrator-only grant resolves to a scope-limited backend subject end to end through pier, and wristband can hand authorize off to a configured consent path with unchanged defaults. One commit with only this task's files.</done>
</task>
<task type="auto">
<name>Cabana admin consent endpoint backed by a published pact.MCPAdminConsent, with the token-scope catalog exported</name>
<reversibility rating="costly">The pact.MCPAdminConsent interface and the {api}/mcp/consent JSON contract are consumed by the admin SPA and by the OAuth server plugin; renaming them needs coordinated releases.</reversibility>
<precondition>docker info exits 0 (cabana admin smoke tests use Postgres).</precondition>
<files>modules/pact/mcp.go, modules/cabana/token_scopes_export.go, modules/cabana/mcp_consent.go, modules/cabana/mcp_consent_smoke_test.go, modules/cabana/http.go, modules/cabana/admin_openapi.go, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, modules/pact/README.md, modules/cabana/README.md, docs/services/oauth-server.md</files>
<read_first>
modules/pact/mcp.go (MCPLinkedBackendResolver + LinkedBackendUser: provider interface and plain view struct pattern)
modules/cabana/token_commands.go (tokenCatalogForApp at line 101)
modules/cabana/token_scopes.go (catalog, scopeOverlaps at line 333)
modules/cabana/api_tokens.go (validateTokenScopes at line 133: * collapse and refusal rules)
modules/cabana/account_tokens.go (accountTokenScopes and mapCompiledScope: filtering by scopeOverlaps and label mapping)
modules/cabana/account_contributions.go (handler style: accountPrincipal, WriteData, WriteError, moduleLog)
modules/cabana/account.go (accountPrincipal, backendMessage)
modules/cabana/http.go (line 335 group, interactiveOnly/requireAjax wrapping)
modules/cabana/admin_openapi.go (lines 336-395: view structs and swag annotation style)
modules/cabana/account_contributions_smoke_test.go (Docker admin harness to copy)
../sm-oauthserver-plugin/controllers/mcp_consent_api.go (user-mode body shapes the admin view mirrors: mcpConsentClient, mcpScopeDetail, mcpConsentShowBody)
modules/phrasebook/backend/lang/en/lang.yaml and pl/lang.yaml (group layout)
</read_first>
<action>
pact (D-03): add the provider interface MCPAdminConsent with MCPAdminConsentShow(ctx context.Context, adminID uint, requestID string) (MCPAdminConsentRequest, error) and MCPAdminConsentDecide(ctx context.Context, adminID uint, requestID string, decision MCPAdminConsentDecision) (string, error), the second answering the client redirect URI. Add MCPAdminConsentRequest{RequestID, ClientID, ClientName, LogoURL, RedirectURI string; Scopes []string (requested data scopes, offline_access excluded); OfflineAccess bool (requested); ConsentRequired bool; ExpiresAt time.Time} and MCPAdminConsentDecision{Allow bool; Scopes []string; OfflineAccess bool}. Add sentinels ErrMCPConsentNotFound and ErrMCPConsentNoScopes. Doc: one provider per application, published through app.Publish by the plugin that owns the MCP authorization server; the framework applies the scope policy before calling Decide.
cabana catalog export (D-09), new file modules/cabana/token_scopes_export.go: TokenScopeNames(app *backpack.App) ([]string, error) answers the catalog names in catalog order (*, admin:read, then plugin TokenScopes) built on tokenCatalogForApp, so it works at plugin Boot before cabana.Activate. TokenScopeLabels(ctx context.Context, app *backpack.App, names []string) []string answers the translated label of each catalog name, the name itself for an unknown one, in input order. Neither changes the catalog.
cabana endpoint (D-03, D-09, D-11), new file modules/cabana/mcp_consent.go, mounted in the line 335 backend group of http.go as g.Get("/mcp/consent/{request}", interactiveOnly(s.mcpConsentShow)) and g.Post("/mcp/consent/{request}", interactiveOnly(requireAjax(s.mcpConsentDecide))). Both: accountPrincipal, then app.Lookup[pact.MCPAdminConsent](); none published → 404 code request_not_found. Show: call MCPAdminConsentShow(ctx, principal.ID, request); ErrMCPConsentNotFound → 404 request_not_found; other errors → 500 logged with moduleLog.ErrorContext (never log the request id together with a code). Answer MCPConsentView{request_id, client{id, name, redirect_host, logo_url}, admin{login, name, email}, scopes []AdminAPITokenScope, offline_access, consent_required, expires_at RFC 3339}. scopes = requested names in catalog order that are in the catalog and pass scopeOverlaps for the principal (D-11 hides the rest), mapped with mapCompiledScope. redirect_host = the host of RedirectURI, or its scheme-and-origin when the host is empty. admin = the administrator's login, "first last" name and email loaded from backend_users. Decide: decode MCPConsentDecisionRequest{decision "allow"|"deny", scopes []string, offline_access bool} under a 16 KiB http.MaxBytesReader with unknown fields refused (400). decision deny → MCPAdminConsentDecide with Allow false. decision allow → load the request through MCPAdminConsentShow again, keep submitted names that are requested and grantable (others dropped, not errors), normalise with validateTokenScopes (* collapses to ["*"]), empty → 422 no_grantable_scopes; OfflineAccess = requested && body offline_access; call Decide with Allow true. ErrMCPConsentNotFound → 404, ErrMCPConsentNoScopes → 422 no_grantable_scopes. Success → 200 MCPConsentDecisionView{redirect_uri}. cabana opens no transaction; the provider owns its lock and transaction. Messages through backendMessage with new keys mcp_connect.request_not_found and mcp_connect.no_grantable_scopes added to both en and pl phrasebook files (English: "This connection request has expired or does not exist." / "Choose at least one scope you can use."; Polish equivalents).
Swag (admin_openapi.go): exported view structs MCPConsentView, MCPConsentClientView, MCPConsentAdminView, MCPConsentDecisionRequest, MCPConsentDecisionView and doc funcs AdminMCPConsentShow (GET /mcp/consent/{request}: 200, 401, 403, 404) and AdminMCPConsentDecide (POST: 200, 400, 401, 403, 404, 422) in the style of lines 368-395. Do not run scripts/check-admin-openapi.sh here; plan 02 regenerates admin/openapi/admin.json and admin/src/api/schema.d.ts.
Smoke test modules/cabana/mcp_consent_smoke_test.go TestMCPAdminConsentSmoke (Docker, copy the account contributions smoke harness): a fake provider published for the test; an administrator holding only the read permissions behind admin:read sees admin:read and not * in Show; allow with scopes [*, admin:read] from that admin yields Decide called with [admin:read]; an anonymous request gets 401; a g15_ token gets 403 with reason interactive_only; no provider → 404. Docs same commit: pact README (MCPAdminConsent and its types), cabana README API reference (TokenScopeNames, TokenScopeLabels, the endpoint and its rules), docs/services/oauth-server.md (admin consent contract). Stage by path, no git add -A.
</action>
<verify>
<automated>go test -count=1 -run 'TestMCPAdminConsentSmoke|TestAccountContributionsSmoke|TestPhase09ContractInventory|TestScopeLimitForMethods' ./modules/cabana</automated>
<fails_when>non-zero exit, or a line contains FAIL, or `[no tests to run]`, or `--- SKIP: TestMCPAdminConsentSmoke` appears</fails_when>
<automated>go vet ./modules/pact ./modules/cabana && go test -short -count=1 ./modules/pact ./modules/cabana ./modules/phrasebook && go test ./cmd/summer -run TestDocsTree -count=1 && go run ./cmd/summer docs:build --check</automated>
<fails_when>non-zero exit, or a line contains FAIL, or docs:build prints a problem line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n 'type MCPAdminConsent interface' modules/pact/mcp.go` matches; ErrMCPConsentNotFound and ErrMCPConsentNoScopes exist.
- `grep -n 'func TokenScopeNames(app \*backpack.App) (\[\]string, error)' modules/cabana/token_scopes_export.go` matches.
- http.go mounts `/mcp/consent/{request}` GET wrapped in interactiveOnly and POST wrapped in interactiveOnly(requireAjax(...)) inside the backend group.
- admin_openapi.go has `@Router /mcp/consent/{request} [get]` and `@Router /mcp/consent/{request} [post]`.
- TestMCPAdminConsentSmoke passes, not skipped, covering hidden scopes, the dropped `*`, 401, 403 interactive_only and 404 without provider.
- Both phrasebook files have mcp_connect.request_not_found and mcp_connect.no_grantable_scopes.
</acceptance_criteria>
<done>The admin SPA has a same-origin, cookie-authenticated consent API whose scope policy is the g15_ token policy, and a plugin can serve consent data by publishing one interface.</done>
</task>
<task type="auto">
<name>Per-item rows and item actions on My account contributions</name>
<reversibility rating="costly">AccountContribution.Items/ItemActions and the item action route are part of the pact plugin contract and the admin API.</reversibility>
<precondition>docker info exits 0.</precondition>
<files>modules/pact/capabilities.go, modules/cabana/account_contributions.go, modules/cabana/account_items_smoke_test.go, modules/cabana/http.go, modules/cabana/admin_openapi.go, modules/pact/README.md, modules/cabana/README.md, docs/plugins/registration.md, docs/backend/users-and-permissions.md</files>
<read_first>
modules/pact/capabilities.go (HasAccountContributions, AccountContribution, AccountAction, AccountActionInput, AccountActionResult at lines 596-650)
modules/cabana/account_contributions.go (compileAccountContributions at line 38, accountContributionsList at line 98, accountContributionAction at line 160)
modules/cabana/admin_openapi.go (AccountContributionView at line 336, AccountContributionActionView, annotations at lines 368-395)
modules/cabana/http.go (line 349-350 contribution routes)
modules/cabana/account_contributions_smoke_test.go and account_contributions_hardening_test.go (behaviour that must not change)
../sm-user-plugin/account_contributions.go (an existing contributor that must keep working unchanged)
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md section C3
</read_first>
<action>
pact (D-12): add to AccountContribution Items func(ctx context.Context, adminID uint) ([]AccountItem, error) with json:"-", ItemActions []AccountItemAction and ItemsEmpty string (phrase key or text; empty means the framework's own empty line). Add AccountItem{ID, Title, Subtitle string; Meta []string}, AccountItemAction{Name, Label, Confirm string; Danger bool; Permissions []string; Run func(ctx context.Context, in AccountItemActionInput) (AccountActionResult, error) json:"-"} and AccountItemActionInput{AdminID uint; ItemID string}. Add sentinel ErrAccountItemNotFound (Run answers it when the item is gone). Document that Confirm may contain :title, which the admin fills with the item's Title, and that Items must be a pure read scoped to the signed-in administrator. Nil Items keeps a section exactly as today.
cabana compile: in compileAccountContributions refuse at boot ItemActions without Items, an item action whose Name is not an identifier or repeats within the section, a nil Run and an empty Label, with the same error style as section actions.
cabana list: in accountContributionsList add to AccountContributionView Items []AccountItemView json:"items" (nil, serialised null, when the section has no Items func; a non-nil, possibly empty slice otherwise), ItemActions []AccountContributionActionView json:"item_actions" (only actions whose Permissions the administrator holds, via the same Allows check section actions use), and ItemsEmpty string json:"items_empty" (translated; empty when unset). A failing Items sets view.Error true, leaves items null, logs, and never hides other sections. Labels and Confirm texts are translated like section actions. New exported AccountItemView{ID, Title, Subtitle string; Meta []string}.
cabana route: g.Post("/account/contributions/{name}/items/{item}/actions/{action}", interactiveOnly(requireAjax(s.accountContributionItemAction))) next to the section action route. Handler: unknown section or action → 404; missing permissions → 403 like section actions; then call the section's Items for the signed-in administrator and answer 404 when {item} is not among the returned IDs (an administrator can never act on an item their own Items did not list); then run Run inside a transaction carried by the context exactly like accountContributionAction; ErrAccountItemNotFound from Run → 404; other errors → the existing action error mapping. 200 answers AccountActionResultView with the localized message.
Swag: AccountItemView, the new AccountContributionView fields, and doc func AdminAccountContributionItemAction for POST /account/contributions/{name}/items/{item}/actions/{action} (200, 401, 403, 404, 422).
Smoke test modules/cabana/account_items_smoke_test.go TestAccountItemsSmoke (Docker): a section without Items still answers items null; a section with Items for admin A lists two rows; the item action on a listed ID runs with AdminID and ItemID; the same ID posted by admin B (whose Items list is empty) gets 404 and Run is not called; Run answering ErrAccountItemNotFound gives 404; a boot with ItemActions and no Items fails. Docs same commit: pact README, cabana README, docs/plugins/registration.md and docs/backend/users-and-permissions.md (items, item actions, ItemsEmpty, :title). Stage by path.
</action>
<verify>
<automated>go test -count=1 -run 'TestAccountItemsSmoke|TestAccountContributionsSmoke|TestAccountContributions$|TestAccountContributionURL|TestAccountContributionsIsolation|TestAccountContributionsAppliesFailureFlagsSection' ./modules/cabana</automated>
<fails_when>non-zero exit, or a line contains FAIL, or `[no tests to run]`, or `--- SKIP: TestAccountItemsSmoke` appears</fails_when>
<automated>go vet ./modules/pact ./modules/cabana && go test -short -count=1 ./modules/pact ./modules/cabana && go test ./cmd/summer -run TestDocsTree -count=1 && go run ./cmd/summer docs:build --check</automated>
<fails_when>non-zero exit, or a line contains FAIL, or docs:build prints a problem line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n 'type AccountItemAction struct' modules/pact/capabilities.go` and `grep -n 'ErrAccountItemNotFound' modules/pact/capabilities.go` match.
- http.go has the route `/account/contributions/{name}/items/{item}/actions/{action}` wrapped in interactiveOnly(requireAjax(...)).
- TestAccountItemsSmoke passes (not skipped), including the cross-admin 404 with Run not called.
- The existing account contribution tests named in the verify command still pass unchanged.
- admin_openapi.go has `@Router /account/contributions/{name}/items/{item}/actions/{action} [post]`.
</acceptance_criteria>
<done>A plugin can contribute a My account section with a list of rows and per-row actions; existing contributors render exactly as before.</done>
</task>
<task type="auto">
<name>In-transaction BackendAccessRevokedEvent at every D-13 site</name>
<reversibility rating="costly">BackendAccessRevokedEvent and its reason values become an event contract plugins listen to; a listener error now rolls back the admin save.</reversibility>
<precondition>docker info exits 0.</precondition>
<files>modules/cabana/admin_events.go, modules/cabana/backend_users_admin.go, modules/cabana/backend_roles_admin.go, modules/cabana/account.go, modules/cabana/commands.go, modules/cabana/backend_access_revoked_smoke_test.go, modules/cabana/README.md, docs/services/events.md, docs/backend/users-and-permissions.md</files>
<read_first>
modules/cabana/subject_events.go (fireSubjectChanged, fireTokenRevoked; keep them unchanged)
modules/cabana/backend_users_admin.go (FormAfterDelete line 219, deactivate action lines 276-292, FormBeforeUpdate around line 815, FormAfterUpdate line 830-845, the prior* fields on the model)
modules/cabana/backend_roles_admin.go (FormAfterUpdate lines 178-199; check for a role delete path that changes holders' permissions)
modules/cabana/account.go (accountUpdate changePassword inside the transaction closure, lines 370-398)
modules/cabana/commands.go (admin:reset-password transaction, lines 141-165)
modules/cabana/tx_context.go (TxFromContext)
modules/cabana/subject_events_test.go (listener test style)
../sm-user-plugin/classes/events.go (AccessRevokedEvent lines 112-130: synchronous fire with Tx, listener error aborts)
</read_first>
<action>
New file modules/cabana/admin_events.go (D-13): exported BackendAccessRevokedEvent{AdminIDs []uint; Reason string; Tx *gorm.DB} with reason constants BackendAccessDeleted = "deleted", BackendAccessDeactivated = "deactivated", BackendAccessPasswordChanged = "password_changed" (own change on My account), BackendAccessPasswordSet = "password_set" (set by another administrator), BackendAccessPasswordReset = "password_reset" (admin:reset-password), BackendAccessPermissions = "permissions" (role, own permissions, superuser flag, or a role's permissions). Doc: fired synchronously through app.Events.Fire inside the transaction of the save, before commit; a listener's error is returned and rolls the save back; listeners revoke grants keyed on the administrators and must not open their own transaction when Tx is set. Unexported fireBackendAccessRevoked(ctx context.Context, app *backpack.App, tx *gorm.DB, reason string, adminIDs ...uint) error: no-op answering nil when app or bus is nil or no non-zero id remains; otherwise fires one event with the de-duplicated non-zero ids and returns the listener error.
Call sites, each next to the existing fireSubjectChanged call (which stays as is) and each returning the error so the save rolls back: usersAdmin.FormAfterDelete (deleted, its tx); the deactivate lifecycle action (deactivated, the db/tx the action updates through); usersAdmin.FormBeforeUpdate records on the model an unexported flag when storePassword changed the password and the editor is another administrator, and FormAfterUpdate fires password_set when the flag is set; usersAdmin.FormAfterUpdate fires permissions when role, own permissions or superuser flag changed (D-13: revoke, not only re-list); rolesAdmin.FormAfterUpdate fires permissions for the holders it already plucks, through the save's transaction; account.go accountUpdate fires password_changed inside the transaction closure when changePassword is set, with the closure's tx; commands.go admin:reset-password fires password_reset inside its transaction with tx. If backend_roles_admin.go allows deleting a role that still has holders, fire permissions for those holders there too; if deletion is refused while holders exist, add nothing and say so in the SUMMARY. cabana offers no sign out everywhere action: add none, and document that.
Smoke test modules/cabana/backend_access_revoked_smoke_test.go TestBackendAccessRevokedSmoke (Docker, admin harness): a listener records events; deleting an administrator, deactivating one, an administrator setting another's password, an own password change on PUT /account, a role change, and a role permission change each record one event with the matching reason, the affected id and a non-nil Tx; a listener that returns an error makes the password change answer non-2xx and leaves the stored password hash unchanged. admin:reset-password is covered in plan 05. Docs same commit: cabana README (event, reasons, rollback rule, sign out everywhere not offered), docs/services/events.md (event table), docs/backend/users-and-permissions.md (what ends an administrator's OAuth grants). Stage by path.
</action>
<verify>
<automated>go test -count=1 -run 'TestBackendAccessRevokedSmoke|TestFireSubjectChangedReachesPointerListener|TestFireSubjectChangedWaitsForCommit' ./modules/cabana</automated>
<fails_when>non-zero exit, or a line contains FAIL, or `[no tests to run]`, or `--- SKIP: TestBackendAccessRevokedSmoke` appears</fails_when>
<automated>go vet ./... && go test -short -count=1 ./... && go test ./cmd/summer -run TestDocsTree -count=1 && go run ./cmd/summer docs:build --check</automated>
<fails_when>non-zero exit, or a line contains FAIL, or docs:build prints a problem line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n 'type BackendAccessRevokedEvent struct' modules/cabana/admin_events.go` matches and the six reason constants exist.
- `grep -c 'fireBackendAccessRevoked(' modules/cabana/backend_users_admin.go` is at least 4; backend_roles_admin.go, account.go and commands.go each contain at least one call.
- The existing fireSubjectChanged calls remain at each site (`grep -c 'fireSubjectChanged(' modules/cabana/backend_users_admin.go` is still 3, as before the task).
- TestBackendAccessRevokedSmoke passes, not skipped, including the rolled-back password change.
- go vet ./... and go test -short ./... pass for the whole framework module.
</acceptance_criteria>
<done>Every administrator change D-13 names fires an in-transaction event a plugin can revoke grants on atomically; nothing changes for applications that do not listen.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| MCP client → wristband authorize | Untrusted scope, redirect and request values; this plan only changes where the browser is handed off and the empty-scope default |
| Browser (admin SPA) → cabana consent API | Cookie-authenticated, same-origin; decides which scopes an agent gets |
| MCP bearer → pier backend guard | A verified grant becomes a backend subject acting as an administrator |
| cabana admin saves → plugin listeners | In-transaction event; a listener can veto the save |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-32.2-01 | Elevation of privilege | pier resolveOAuth backend branch | high | mitigate | Branch only on Subject backend with UserID 0 and BackendUserID non-zero; every other grant takes the unchanged path, which still refuses UserID 0; ScopeLimited true so ScopeLimitFor caps the subject; no link lookup |
| T-32.2-02 | Information disclosure | pier session binding | high | mitigate | Binding oauth:backend:<client>:<admin>, never oauth:<client>:0, so two administrators of one client never share a session |
| T-32.2-03 | Elevation of privilege | pier linked user-mode grants | medium | mitigate | Scope-limit condition widened only by ScopeLimited, which only the backend branch sets; filter.go untouched; smoke proves the empty-Subject UserID-0 grant is refused |
| T-32.2-04 | Tampering (CSRF) | cabana POST /mcp/consent/{request} | high | mitigate | requireAjax (X-Requested-With), SameSite=Strict cookie, interactiveOnly; 16 KiB body cap; unknown fields refused |
| T-32.2-05 | Elevation of privilege | consent scope selection | high | mitigate | Granted = submitted ∩ requested ∩ scopeOverlaps(admin) then validateTokenScopes; never trust the provider or the SPA to filter (D-11) |
| T-32.2-06 | Spoofing | wristband handoff | medium | mitigate | ConsentPath is appended to the issuer only (same origin); client lookup, exact redirect match and PKCE run before the handoff unchanged |
| T-32.2-07 | Elevation of privilege | account item action | high | mitigate | cabana answers 404 for an item id not listed by the administrator's own Items before Run; permissions checked first; Run inside a transaction |
| T-32.2-08 | Repudiation / Elevation | D-13 revocation | high | mitigate | BackendAccessRevokedEvent fired in the save's transaction at every site; listener error rolls back; existing after-commit MCPSubjectChanged kept |
| T-32.2-SC | Tampering | npm/pip/cargo/go module installs | low | accept | No dependency is added in this plan; the Package Legitimacy Audit lists none |
</threat_model>
<verification>
Each task's verify passes on its own commit. After task 4: go vet ./... and go test -short ./... green for the framework module; the four Docker smokes pass; TestDocsTree and docs:build --check pass; `git grep -n -i 'grzyby' -- modules/pact modules/wristband modules/pier modules/cabana docs` is empty.
</verification>
<success_criteria>
- SC-1 framework half: configurable handoff and default scopes (D-04), cabana consent endpoint with the token scope policy (D-03, D-09, D-11).
- SC-2 framework half: pier backend-only grants with the personal-token scope limit (D-01, D-09); linked grants unchanged.
- SC-3 framework half: My account items (D-12) and the in-transaction revocation event at every D-13 site.
- SC-5 framework docs in the same commits.
</success_criteria>
<output>
Create `.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-01-SUMMARY.md` when done.
</output>
## Artifacts this phase produces
Plan 01 (framework seams):
- pact: MCPGrant.Subject, const MCPGrantSubjectBackend, MCPSubject.ScopeLimited
- pact: interface MCPAdminConsent (MCPAdminConsentShow, MCPAdminConsentDecide), structs MCPAdminConsentRequest, MCPAdminConsentDecision, errors ErrMCPConsentNotFound, ErrMCPConsentNoScopes
- pact: AccountContribution.Items, AccountContribution.ItemActions, AccountContribution.ItemsEmpty, structs AccountItem, AccountItemAction, AccountItemActionInput, error ErrAccountItemNotFound
- wristband: Options.ConsentPath, Options.DefaultScopes
- pier: backend-only branch in resolveOAuth (binding format oauth:backend:<client>:<admin>), ScopeLimited in the backend guard condition and in fingerprint
- cabana: TokenScopeNames, TokenScopeLabels (new file modules/cabana/token_scopes_export.go)
- cabana: routes GET/POST {api}/mcp/consent/{request} (new file modules/cabana/mcp_consent.go), POST {api}/account/contributions/{name}/items/{item}/actions/{action}
- cabana: view structs MCPConsentView, MCPConsentClientView, MCPConsentAdminView, MCPConsentDecisionRequest, MCPConsentDecisionView, AccountItemView; AccountContributionView.Items/ItemActions/ItemsEmpty; swag doc funcs AdminMCPConsentShow, AdminMCPConsentDecide, AdminAccountContributionItemAction
- cabana: BackendAccessRevokedEvent, BackendAccessDeleted, BackendAccessDeactivated, BackendAccessPasswordChanged, BackendAccessPasswordSet, BackendAccessPasswordReset, BackendAccessPermissions, fireBackendAccessRevoked (new file modules/cabana/admin_events.go)
- phrasebook keys: backend::lang.mcp_connect.request_not_found, backend::lang.mcp_connect.no_grantable_scopes
- smoke tests: TestConsentPathSmoke, TestBackendSubjectSmoke, TestMCPAdminConsentSmoke, TestAccountItemsSmoke, TestBackendAccessRevokedSmoke

View File

@@ -0,0 +1,252 @@
---
phase: 32.2-mcp-oauth-with-administrator-subjects
plan: 01
subsystem: auth
tags: [mcp, oauth, pier, wristband, cabana, pact, postgres, swag]
requires:
- phase: 32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con
provides: MCPGrant.BackendUserID, configurable MCP scopes, user-mode consent flow
provides:
- pact MCPGrant.Subject + MCPGrantSubjectBackend, MCPSubject.ScopeLimited
- pact MCPAdminConsent provider interface with MCPAdminConsentRequest/Decision and ErrMCPConsentNotFound/ErrMCPConsentNoScopes
- pact AccountContribution.Items/ItemActions/ItemsEmpty, AccountItem, AccountItemAction, AccountItemActionInput, ErrAccountItemNotFound
- wristband Options.ConsentPath and Options.DefaultScopes (defaults byte-identical to PHP)
- pier backend-only grant branch (binding oauth:backend:<client>:<admin>, ceiling off, scope-limited like g15_ tokens)
- cabana GET/POST {api}/mcp/consent/{request} with the personal-token scope policy
- cabana POST {api}/account/contribution-items/{name}/{item}/actions/{action}
- cabana TokenScopeNames, TokenScopeLabels
- cabana BackendAccessRevokedEvent fired in-transaction at every D-13 site
affects: [32.2-02 admin SPA, 32.2-03 sm-oauthserver-plugin backend mode, 32.2-04 first consumer app, 32.2-05 tests and release]
actuals:
tokens: 37974
tasks: 4
commits: 4
plan_head_before: 45eb34e5c4e86cd94ab3467be1e93ae7d688f3b2
plan_head_after: fcc7bbde25a270a6211aace6b1cc40589b2295b4
tech-stack:
added: []
patterns:
- "Zero value means today's behaviour for every new pact field and wristband option"
- "Framework owns the scope policy; a published provider (pact.MCPAdminConsent) only resolves and issues"
- "In-transaction veto event (BackendAccessRevokedEvent) next to the unchanged after-commit MCPSubjectChanged"
key-files:
created:
- modules/cabana/mcp_consent.go
- modules/cabana/token_scopes_export.go
- modules/cabana/admin_events.go
- modules/pier/backend_subject_smoke_test.go
- modules/wristband/consent_path_smoke_test.go
- modules/cabana/mcp_consent_smoke_test.go
- modules/cabana/account_items_smoke_test.go
- modules/cabana/backend_access_revoked_smoke_test.go
modified:
- modules/pact/mcp.go
- modules/pact/capabilities.go
- modules/wristband/server.go
- modules/wristband/authorize.go
- modules/pier/identity.go
- modules/pier/backend_guard.go
- modules/cabana/account_contributions.go
- modules/cabana/admin_openapi.go
- modules/cabana/http.go
- modules/cabana/backend_users_admin.go
- modules/cabana/backend_roles_admin.go
- modules/cabana/account.go
- modules/cabana/commands.go
- modules/cabana/contracts.go
- admin/openapi/admin.json
- admin/src/api/schema.d.ts
key-decisions:
- "The account item action route is POST {api}/account/contribution-items/{name}/{item}/actions/{action}, not /account/contributions/{name}/items/{item}/actions/{action}: the planned nine-segment POST overlaps the controller routes ({vendor}/{plugin}/{controller}/{id}/relations/{name}/records) and surf refuses the boot"
- "admin/openapi/admin.json and admin/src/api/schema.d.ts are regenerated in plan 01 (not 02), because the contract and conformance inventory tests fail go test ./... without them"
- "A requested * is offered on admin consent, exactly as on g15_ token creation (scopeOverlaps always offers *); D-11 hides only catalog scopes the admin cannot use and names outside the catalog"
- "Role delete fires no BackendAccessRevokedEvent: FormBeforeDelete refuses deleting a role that any administrator holds"
patterns-established:
- "Administrator-only grant: Subject backend, UserID 0, BackendUserID set; resolveOAuth branches before the UserID==0 refusal"
- "Consent JSON lives in cabana under the admin API and delegates to app.Lookup[pact.MCPAdminConsent] at request time"
requirements-completed: [SC-1, SC-2, SC-3, SC-5]
coverage:
- id: D1
description: "Administrator-only grant lists only the backend tools its scopes allow over a real /mcp request; empty-subject UserID-0 grant gets 401"
requirement: SC-2
verification:
- kind: integration
ref: "modules/pier/backend_subject_smoke_test.go#TestBackendSubjectSmoke"
status: pass
human_judgment: false
- id: D2
description: "wristband hands authorize off to {issuer}/connect by default and to Options.ConsentPath when set; DefaultScopes fill an empty-scope request"
requirement: SC-1
verification:
- kind: unit
ref: "modules/wristband/consent_path_smoke_test.go#TestConsentPathSmoke"
status: pass
human_judgment: false
- id: D3
description: "cabana admin consent endpoint: hidden scopes, dropped unrequested *, 401, 403 interactive_only, 404 without provider, 422 no_grantable_scopes, 400 bad body"
requirement: SC-1
verification:
- kind: integration
ref: "modules/cabana/mcp_consent_smoke_test.go#TestMCPAdminConsentSmoke"
status: pass
- kind: integration
ref: "modules/cabana/openapi_conformance_test.go#TestPhase10OpenAPIConformance"
status: pass
human_judgment: false
- id: D4
description: "My account items and item actions: items null without Items, cross-admin 404 without Run, ErrAccountItemNotFound 404, boot refusals"
requirement: SC-3
verification:
- kind: integration
ref: "modules/cabana/account_items_smoke_test.go#TestAccountItemsSmoke"
status: pass
human_judgment: false
- id: D5
description: "BackendAccessRevokedEvent fires in the save's transaction at delete, deactivate, password set, own password change, role change and role permission change; a listener error rolls back"
requirement: SC-3
verification:
- kind: integration
ref: "modules/cabana/backend_access_revoked_smoke_test.go#TestBackendAccessRevokedSmoke"
status: pass
human_judgment: false
- id: D6
description: "READMEs and docs describe every new identifier; docs checker passes; no consuming application named"
requirement: SC-5
verification:
- kind: other
ref: "go run ./cmd/summer docs:build --check; go test ./cmd/summer -run TestDocsTree"
status: pass
human_judgment: false
duration: 40min
completed: 2026-11-21
status: complete
---
# Phase 32.2 Plan 01: Framework seams for administrator-subject MCP OAuth Summary
**Administrator-only MCP grants that pier resolves straight to a scope-limited backend subject, a cabana admin consent API over a published pact.MCPAdminConsent, per-row My account items, and an in-transaction BackendAccessRevokedEvent at every admin access change**
## Performance
- **Duration:** about 40 min
- **Started:** 2026-11-20T22:52Z
- **Completed:** 2026-11-20T23:33Z
- **Tasks:** 4 of 4
- **Files modified:** 40 (including the regenerated admin.json and schema.d.ts)
## Accomplishments
- Tracer: a fake verifier's `Subject: backend` grant with `admin:read` lists the read-only backend tool and hides the write tool of a superuser over a real `/mcp` request through pier, the backend guard and `cabana.ScopeLimitFor` on Postgres. Removing `|| subject.ScopeLimited` makes the test fail, so it checks the scope limit. Linked user-mode grants are still not scope-limited, and `filter.go` is untouched.
- wristband `Options.ConsentPath` and `Options.DefaultScopes`. With both empty the handoff is byte-identical to the PHP server (`{issuer}/connect?request=<id>`), and `DefaultOptions` is unchanged.
- cabana `GET/POST {api}/mcp/consent/{request}` (interactive only; the POST needs X-Requested-With, is capped at 16 KiB and refuses unknown fields). Show lists the requested scopes that are in the catalog and that the administrator holds. Decide drops the rest, collapses `*`, and answers 422 when nothing is left. `TokenScopeNames` and `TokenScopeLabels` export the catalog for plugin Boot.
- My account sections can list rows with per-row actions. A row action runs only for an item the administrator's own `Items` listed, inside a transaction. Existing contributors are unchanged: a section without `Items` sends `items: null`.
- `cabana.BackendAccessRevokedEvent` (six reasons) fires synchronously inside the save's transaction at every D-13 site, and a listener error rolls the save back. The existing after-commit `MCPSubjectChanged` emissions stay as they were (3 calls in backend_users_admin.go).
## Task Commits
1. **Task 1 (tracer): administrator-only grants and configurable consent handoff** - `c63bfa3e` (feat)
2. **Task 2: cabana admin consent endpoint and exported token-scope catalog** - `97d7ee05` (feat)
3. **Task 3: per-item rows and item actions on My account** - `3f7ce602` (feat)
4. **Task 4: in-transaction BackendAccessRevokedEvent** - `fcc7bbde` (feat)
Tracer gate: auto mode is off and human_verify_mode is end-of-phase with an automated-only `<verify>`. The verify ran again end to end and passed (TestBackendSubjectSmoke PASS, not skipped), so expansion continued.
## Files Created/Modified
- `modules/pact/mcp.go`: MCPGrant.Subject, MCPGrantSubjectBackend, MCPSubject.ScopeLimited, MCPAdminConsent and its types and sentinels
- `modules/pact/capabilities.go`: AccountContribution.Items/ItemActions/ItemsEmpty, AccountItem, AccountItemAction, AccountItemActionInput, ErrAccountItemNotFound
- `modules/wristband/server.go`, `authorize.go`: ConsentPath and DefaultScopes, `consentPath()` and `defaultAuthorizeScopes()`
- `modules/pier/identity.go`: `resolveBackendGrant`, ScopeLimited in `fingerprint()`
- `modules/pier/backend_guard.go`: scope-limit condition widened by `subject.ScopeLimited`
- `modules/cabana/mcp_consent.go`: consent show and decide handlers
- `modules/cabana/token_scopes_export.go`: TokenScopeNames, TokenScopeLabels
- `modules/cabana/account_contributions.go`: item compile checks, list fields, `accountContributionItemAction`
- `modules/cabana/admin_events.go`: BackendAccessRevokedEvent, reasons, `fireBackendAccessRevoked`
- `modules/cabana/backend_users_admin.go`, `backend_roles_admin.go`, `account.go`, `commands.go`, `contracts.go`: D-13 call sites and the `passwordSetByOther` flag
- `modules/cabana/admin_openapi.go`: MCPConsent* and AccountItemView views, three swag doc funcs
- `modules/cabana/http.go`: three new routes in the backend group
- `modules/phrasebook/backend/lang/{en,pl}/lang.yaml`: `mcp_connect.request_not_found`, `mcp_connect.no_grantable_scopes`
- `admin/openapi/admin.json`, `admin/src/api/schema.d.ts`: regenerated by `scripts/check-admin-openapi.sh` (additions only; `npm --prefix admin run typecheck` passes)
- Route inventory tests updated: `security_coverage_test.go`, `phase10_coverage_test.go`, `phase10_csrf_test.go` (40 unsafe routes), `token_routes_test.go`, `openapi_conformance_test.go` (new cases and a fake consent provider)
- Docs: pact, wristband, pier and cabana READMEs; `docs/services/mcp.md`, `oauth-server.md`, `events.md` (new framework event table); `docs/backend/users-and-permissions.md`; `docs/plugins/registration.md`
## Decisions Made
- The pier backend branch runs before the `grant.UserID == 0` refusal. Every other grant goes down the unchanged path, so a grant with an empty Subject and UserID 0 still gets 401 (tested).
- `defaultAuthorizeScopes` drops identity scopes and duplicates as well as names outside the allowed set. It falls back to `read` when nothing is left.
- The consent view's `redirect_host` is `url.Host`, port included. For a URI without a host it is the URI with the query and fragment removed.
- Show loads the administrator (login, "first last", email) from backend_users. A database failure answers 500 instead of leaving `admin` out.
- Swag `enums:"allow,deny"` is set on `MCPConsentDecisionRequest.Decision`. The `items`/`item_actions` fields are not marked nullable, matching the repo's existing convention for pointer and nil fields.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 3 - Blocking] Item action route path changed**
- **Found during:** Task 3
- **Issue:** surf refused to boot with `POST /account/contributions/{name}/items/{item}/actions/{action}`. That nine-segment POST overlaps the controller routes (`{vendor}/{plugin}/{controller}/{id}/relations/{name}/records` and others). The overlap family surf then generates conflicts with the SPA catch-all `GET /backend/{path...}`.
- **Fix:** The route is now `POST {api}/account/contribution-items/{name}/{item}/actions/{action}`. It is strictly more specific than the record action route `{vendor}/{plugin}/{controller}/{id}/actions/{action}`, so no overlap is possible. The semantics are unchanged.
- **Impact for plan 02:** the SPA must call `/account/contribution-items/{name}/{item}/actions/{action}`, which the regenerated schema.d.ts already types. The UI-SPEC text naming the old path is out of date.
- **Committed in:** `3f7ce602`
**2. [Rule 3 - Blocking] admin.json and schema.d.ts regenerated in plan 01**
- **Found during:** Task 2
- **Issue:** The plan said not to run `scripts/check-admin-openapi.sh` here. But `TestPhase09ContractInventory` and `TestPhase10ConformanceInventory`/`TestPhase10OpenAPIConformance` fail `go test -short ./...` when a route is not in admin.json or has no conformance case. CLAUDE.md requires `go test ./...` to be green at every commit.
- **Fix:** Regenerated both files in tasks 2 and 3 (additions only), and added conformance cases plus a fake `pact.MCPAdminConsent` and an `Items` section to the conformance fixture. Updated the route inventories (CSRF count 38 to 40, token route classes, permission matrix). Plan 02's regeneration step will now find them up to date, and `check-admin-openapi.sh --check` passes.
- **Committed in:** `97d7ee05`, `3f7ce602`
**3. [Rule 1 - Interpretation] `*` on admin consent**
- **Found during:** Task 2
- **Issue:** The plan's smoke text says an admin with only read permissions "sees admin:read and not *". Under the g15_ token policy (D-09, `scopeOverlaps`), however, `*` is always offered.
- **Fix:** I kept the token policy. The smoke covers it through the request: the provider does not request `*`, so it is hidden and dropped from `[*, admin:read]`, and Decide gets `[admin:read]`. A second case shows that a requested `*` is offered and collapses the grant to `["*"]`. Plans 02 and 03 should expect `*` to appear when the client requests it.
- **Committed in:** `97d7ee05`
---
**Total deviations:** 3 (2 blocking fixes, 1 interpretation). **Impact:** no scope creep. The route path change is the only contract difference that plan 02 has to pick up.
## Issues Encountered
- `cabana.Activate` registers the `backend` middleware itself, so the pier fixture plugin must not declare one (the first test run failed with a duplicate middleware error).
- Plugin token scopes need a description (boot check), so the consent fixture now has one.
## Notes for later plans
- D-13 role delete: `rolesAdmin.FormBeforeDelete` refuses deleting a role that any administrator holds (deleted administrators included), so no event is added there.
- No "sign out everywhere" action exists in cabana. None was added, and the docs say so.
- `admin:reset-password` fires `password_reset` inside its transaction. Its smoke coverage is left to plan 05, as the plan says.
- The ScopeLimited mutation check (removing the condition makes TestBackendSubjectSmoke fail) was run by hand and is not committed.
## Verification
- Task verifies all passed: `TestBackendSubjectSmoke`, `TestConsentPathSmoke`, `TestMCPScopesSmoke`, `TestMCPSeam`, `TestDiscoveryFields`, `TestBackendScopeUnavailable`, `TestMCPAdminConsentSmoke`, `TestAccountContributionsSmoke`, `TestPhase09ContractInventory`, `TestScopeLimitForMethods`, `TestAccountItemsSmoke`, the existing account contribution tests, `TestBackendAccessRevokedSmoke`, `TestFireSubjectChanged*`. Each passed and none was skipped.
- `go vet ./...` and `go test -short -count=1 ./...` pass for the whole framework module. The full Docker runs of `./modules/cabana`, `./modules/pier`, `./modules/wristband` and `./modules/pact` pass.
- `go test ./cmd/summer -run TestDocsTree` and `summer docs:build --check` pass. `scripts/check-admin-openapi.sh --check` passes, and so does `npm --prefix admin run typecheck`.
- `git grep -n -i 'grzyby' -- modules/pact modules/wristband modules/pier modules/cabana docs` finds nothing.
## User Setup Required
None.
## Next Phase Readiness
- Plan 02 can build ConnectView and the item rows against the typed schema. It must use the `/account/contribution-items/...` path.
- Plan 03 implements `pact.MCPAdminConsent`, sets `wristband.Options.ConsentPath`/`DefaultScopes`, answers `Subject: backend` grants and listens for `cabana.BackendAccessRevokedEvent`.
## Self-Check: PASSED
- All 8 created files exist on disk.
- Commits c63bfa3e, 97d7ee05, 3f7ce602 and fcc7bbde are in `git log`.
---
*Phase: 32.2-mcp-oauth-with-administrator-subjects*
*Completed: 2026-11-21*

View File

@@ -0,0 +1,303 @@
---
phase: 32.2
plan: 02
type: execute
wave: 2
depends_on: [32.2-01]
files_modified:
- admin/openapi/admin.json
- admin/src/api/schema.d.ts
- admin/src/api/types.ts
- admin/src/views/ConnectView.vue
- admin/src/app/router.ts
- admin/src/app/pageTitle.ts
- admin/src/views/LoginView.vue
- admin/src/components/account/AccountContributions.vue
- admin/tests/smoke/connect.smoke.test.ts
- admin/tests/smoke/account-items.smoke.test.ts
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- modules/cabana/admin_openapi.go
- docs/backend/admin-spa.md
- modules/boardwalk/dist
autonomous: true
requirements: [SC-1, SC-3, SC-5]
estimate:
tokens: 85000
raw_tokens: 85000
tasks: 3
confidence: low
must_haves:
truths:
- "SC-1, D-03: the admin SPA has a route { path: '/connect', name: 'connect', component: ConnectView } with no meta.shell and no meta.public, so an anonymous visitor of /<admin prefix>/connect?request=<id> is sent to login with redirect=/connect?request=<id> and comes back after any 2FA or Turnstile step; safeRedirect is unchanged."
- "SC-1, D-05: ConnectView is a standalone full-screen card copied from LoginView (navy gradient, wordmark, white card, light-literal palette, no sidebar or top bar) showing the client mark, the heading with the client name, the subline, a fact box with 'Signed in as' and 'Returns to' (the redirect host, always shown), the scope checkboxes, the Stay connected row, and Deny (left) and Allow (right)."
- "D-06: 'Use another account' calls logout() without the router argument, then router.replace({ name: 'login', query: { redirect: route.fullPath } }); it is disabled while a decision is in flight; a sign-out failure shows the inline alert (decide_failed copy), keeps the card and re-enables the button."
- "D-09, D-11: the scope rows are exactly the scopes GET /mcp/consent/{request} returned, in catalog order (*, admin:read, plugin scopes); the SPA never re-adds a hidden scope. Every shown scope starts ticked except *, which starts unticked unless it is the only scope; ticking * clears and disables the others and shows the scope_all_includes note; the submitted scopes are ['*'] when * is ticked, else the ticked names in catalog order. Read-only scopes carry the Read-only pill."
- "D-10: the Stay connected checkbox is shown only when offline_access was requested, is ticked by default and posts offline_access true|false; when offline_access was not requested the row is not rendered and offline_access false is posted."
- "No auto-allow: nothing is posted on mount even when consent_required is false (the previously allowed note is shown instead); Allow and Deny POST {decision, scopes, offline_access} and, on 200, switch to the Returning state and call window.location.assign(redirect_uri), never the router and never safeRedirect; a redirect_uri whose scheme is javascript:, data: or vbscript: is treated as a submit failure with no navigation; no native form POST (admin CSP form-action 'self')."
- "UI loading — consent card: the Loading state is a skeleton card with aria-busy=true and no buttons, so nothing can be submitted before the request is known."
- "UI loading — decision in flight: a disabled fieldset wraps the checkboxes, both buttons are disabled, the clicked button shows LoaderCircle (Allow shows mcp_connect.allowing), then the Returning state stays until the browser leaves."
- "UI loading — My account items arrive with the existing GET /account/contributions; nothing renders until it answers, so there is no item-level loading UI."
- "UI empty — no grantable scope (D-11): when the API returns zero scopes, the none_grantable alert replaces the scope group, no offline row is shown, and only Deny is offered, full width."
- "UI empty — request missing: a missing or empty ?request goes straight to the Expired state without a network call."
- "UI empty — nothing ticked: Allow is disabled while the submitted scope set would be empty; Deny stays available."
- "UI empty — My account items: a section whose items array is empty renders the dashed empty block (data-account-items-empty) with ItemsEmpty, or myaccount.items_empty when ItemsEmpty is unset; the status line stays above it."
- "UI error — consent load 5xx or network: the Load error state shows load_failed in the alert block and a full-width Try again button that re-runs the load."
- "UI error — 404 on load or submit: the Expired state (Clock icon, expired_heading, expired_body, a RouterLink to / with open_admin)."
- "UI error — 401 at any point: expireSession sends the browser to login with redirect = the current /connect?request=… path; no copy on the card."
- "UI error — submit 422 shows api_tokens.scopes_required under the scopes; 5xx, network or 400 shows decide_failed above the buttons; in both the ticks are kept and both buttons are enabled again."
- "UI error — forbidden redirect scheme: treated as a submit failure (decide_failed); no navigation."
- "UI error — My account item revoke: 404 shows myaccount.item_gone as a danger toast and reloads; 409 shows myaccount.action_stale and reloads; 403 shows the server message or list.action_forbidden; other failures show extension.action_failed."
- "UI error — a section whose items func failed renders the existing section_error line in place of both the list and the empty block."
- "UI populated — consent scopes follow catalog order with the initial ticks and Read-only pill above, and the offline row is ticked when requested."
- "UI populated — My account items: one role=listitem row per item (data-account-item=<id>) with title, subtitle, meta joined with ' · ' (tabular-nums) and one Button size=sm per item action (variant danger with the Ban icon when Danger, else outline), aria-label myaccount.item_action_named with the item title."
- "UI partial — no logo shows the Bot icon in a 48px circle (a logo is shown only for a same-origin path or an https: URL); no email shows the name alone; no name shows the login; when the API omits admin the card falls back to currentUser."
- "UI zero-one-many — My account items: zero renders the empty block, one or many render the same row list with dividers (first:border-t-0), no pagination."
- "UI overflow — the consent card grows with the page and the page scrolls (min-h-screen main, not fixed height); rows wrap and nothing scrolls inside the card."
- "UI long-text — client name, admin email, redirect host, scope descriptions and item titles/subtitles/meta use [overflow-wrap:anywhere]; nothing on the consent card truncates; My account rows stack under max-sm:flex-col."
- "UI loading/error — the consent scope list never renders on its own; it inherits the card's Loading, Load error and Expired states."
- "SC-3, D-12: AccountContributions.vue renders items additively: a section JSON without items (null) renders exactly as today (status line and buttons); an item action with Confirm or Danger runs through confirm.ask({ message with :title filled from the item Title, confirmLabel, danger }, run) using the confirm AccountView passes in; while one runs every action button is disabled; after a 2xx the section reloads and focus returns to the section heading (tabindex=-1)."
- "C2: LoginView shows one Meta line mcp_connect.login_hint under its heading only when safeRedirect(route.query.redirect) resolves to pathname /connect; nothing else in LoginView changes."
- "SC-5: admin/openapi/admin.json and admin/src/api/schema.d.ts are regenerated by scripts/check-admin-openapi.sh and pass --check; modules/boardwalk/dist is rebuilt and committed and scripts/check-admin-dist.sh passes; docs/backend/admin-spa.md documents the /connect route and account items; framework copy never names a consuming application."
artifacts:
- path: admin/src/views/ConnectView.vue
provides: "Standalone consent card with every state of UI-SPEC C1"
contains: "window.location.assign"
- path: admin/src/app/router.ts
provides: "connect route without shell and without public"
contains: "name: 'connect'"
- path: admin/src/components/account/AccountContributions.vue
provides: "item rows, empty block and item actions"
contains: "data-account-item"
- path: admin/src/api/schema.d.ts
provides: "typed /mcp/consent/{request} and item action routes"
contains: "/mcp/consent/{request}"
- path: modules/boardwalk/dist
provides: "rebuilt embedded SPA"
key_links:
- from: admin/src/views/ConnectView.vue
to: "cabana GET/POST /mcp/consent/{request} (plan 01)"
via: "api client (openapi-fetch) typed by schema.d.ts"
pattern: "/mcp/consent/\\{request\\}"
- from: admin/src/views/LoginView.vue
to: admin/src/app/router.ts safeRedirect
via: "login round trip back to /connect?request="
pattern: "safeRedirect"
- from: admin/src/components/account/AccountContributions.vue
to: "cabana POST /account/contributions/{name}/items/{item}/actions/{action}"
via: "api client"
pattern: "/items/"
---
<objective>
User story (phase goal, ROADMAP 32.2): **As an** editor of a blog-only application whose MCP tools are backend-guarded (Journal) and which has no frontend users, **I want to** add the site's `/mcp` as a connector and sign in once as my administrator account over OAuth, **so that** agents no longer need a hand-copied `g15_` personal token.
Slice in this plan (the "sign in once as my administrator" step): an administrator who opens `/<admin prefix>/connect?request=…` goes through the normal admin login if needed, sees the consent card, ticks scopes and clicks Allow, and the browser leaves for the client's redirect. The tracer proves this against plan 01's JSON contract (connect.smoke.test.ts, router.test.ts). The provider behind that contract is plan 03, and the run against a live stack is plan 04.
The admin SPA half of SC-1 and SC-3 (D-03, D-05, D-06, D-09, D-10, D-11, D-12): a consent route inside the admin SPA that an anonymous browser reaches through the normal admin login, and per-item rows with actions in My account contributions. All copy, layout and states follow 32.2-UI-SPEC.md (C1, C2, C3).
Purpose: the admin cookie is Path=<admin prefix> and SameSite=Strict, so only same-origin SPA fetches carry it; the consent screen must be framework code against plan 01's JSON contract, because the SPA cannot load plugin Vue code.
Output: ConnectView, the route, the login hint, item rendering, regenerated openapi and types, the rebuilt committed boardwalk dist, and docs. Smoke tests only; ConnectView.test.ts and the extended unit tests are plan 05.
⚠ spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
Discretion recorded (UI-SPEC already decided): plain checkboxes with the token-dialog `*` rule, no presets; the scope-picker logic is copied into ConnectView rather than extracted, so ApiTokenCreateDialog.vue is not touched. UI-SPEC "UI Considerations" rows marked covered are must_haves truths here (admin-wide list rows are in plan 03); the five backstop rows are in plan 05; the dismissed login-hint overflow row needs nothing.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-CONTEXT.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-RESEARCH.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-01-SUMMARY.md
@admin/src/views/LoginView.vue
@admin/src/app/router.ts
@admin/src/components/account/AccountContributions.vue
@admin/src/components/account/ApiTokenCreateDialog.vue
@admin/src/components/account/ApiTokensPanel.vue
@admin/src/state/useAuth.ts
@admin/src/api/types.ts
@scripts/check-admin-openapi.sh
@scripts/check-admin-dist.sh
<interfaces>
From plan 01 (cabana, admin API base {prefix}/api/v1; check 32.2-01-SUMMARY.md for any rename):
- GET /mcp/consent/{request} → 200 data MCPConsentView{request_id, client{id, name, redirect_host, logo_url}, admin{login, name, email}, scopes[AdminAPITokenScope{name, label, description, read_only, known}], offline_access, consent_required, expires_at}; 401; 403 interactive_only; 404 request_not_found
- POST /mcp/consent/{request} body MCPConsentDecisionRequest{decision 'allow'|'deny', scopes[], offline_access} with X-Requested-With → 200 data MCPConsentDecisionView{redirect_uri}; 400; 404; 422 no_grantable_scopes
- GET /account/contributions → AccountContributionView gains items (AccountItemView{id, title, subtitle, meta[]} array, or null when the section has none), item_actions (AccountContributionActionView[]), items_empty (string)
- POST /account/contributions/{name}/items/{item}/actions/{action} → 200 AccountActionResultView{message, url}; 403; 404; 409; 422
Existing SPA:
- router.ts: safeRedirect(value) accepts a single-leading-slash path; beforeEach sends an anonymous visitor to { name: 'login', query: { redirect: to.fullPath } }; '/login' route has meta.public, '/account' has meta.shell
- useAuth.ts: currentUser (readonly), expireSession(router), logout(router?) — call logout() with no router argument for the switch
- types.ts: aliases like AccountContribution = Schemas['cabana.AccountContributionView']
- LoginView.vue line 34: router.replace(safeRedirect(route.query.redirect) ?? '/')
</interfaces>
</context>
<tasks>
<task type="tracer">
<name>Tracer: a signed-in administrator opens /connect?request=…, ticks scopes and Allow sends the browser to the client's redirect</name>
<reversibility rating="reversible">An SPA route and a view behind the plan 01 contract; replaceable without touching the API.</reversibility>
<precondition>32.2-01-SUMMARY.md exists and `grep -n '@Router /mcp/consent/{request} \[get\]' modules/cabana/admin_openapi.go` matches; admin/node_modules exists or `npm --prefix admin ci` succeeds.</precondition>
<files>admin/openapi/admin.json, admin/src/api/schema.d.ts, admin/src/api/types.ts, admin/src/views/ConnectView.vue, admin/src/app/router.ts, admin/src/app/pageTitle.ts, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, admin/tests/smoke/connect.smoke.test.ts, modules/cabana/admin_openapi.go</files>
<read_first>
admin/src/views/LoginView.vue (whole file: shell markup, busy/failed refs, double-submit guard, alert block classes)
admin/src/components/account/ApiTokenCreateDialog.vue (scope rows, toggleScope, scopeDisabled, starChecked at lines 64 and 149-177, skeleton rows)
admin/src/app/router.ts (routes at lines 60-80, beforeEach at line 92, safeRedirect at line 31)
admin/src/app/pageTitle.ts (login and account branches)
admin/src/api/client.ts and admin/src/api/types.ts (openapi-fetch usage and schema aliases)
admin/tests/smoke/tracer.smoke.test.ts (smoke test harness and fetch mocking to copy)
scripts/check-admin-openapi.sh
modules/phrasebook/backend/lang/en/lang.yaml (api_tokens and myaccount groups for reused keys)
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md (Copywriting Contract, C1 Layout, Ready state, Interaction)
</read_first>
<action>
First run scripts/check-admin-openapi.sh (no argument) so admin/openapi/admin.json and admin/src/api/schema.d.ts include plan 01's /mcp/consent/{request} routes, the account item action route and the new view fields. If swag refuses one of plan 01's annotations, fix only that annotation in modules/cabana/admin_openapi.go and note it in the SUMMARY. Add aliases in admin/src/api/types.ts: MCPConsent = Schemas['cabana.MCPConsentView'], MCPConsentDecision = Schemas['cabana.MCPConsentDecisionView'], AccountItem = Schemas['cabana.AccountItemView'].
Route (D-03): add { path: '/connect', name: 'connect', component: ConnectView } to router.ts next to the other fixed paths, before the /:vendor/:plugin/:controller entries, with no meta.shell and no meta.public; do not change safeRedirect or beforeEach. pageTitle.ts: a connect branch returning t('backend::lang.mcp_connect.page_title').
ConnectView.vue (D-05, D-09, D-10, D-11), new, script setup lang ts, copying LoginView's main, wordmark and card markup verbatim and using only light-literal hex classes inside the card (no Button.vue, no token utilities, no dark: variants), per UI-SPEC Color. This task builds the Ready state only: on mount and when route.query.request changes, GET /mcp/consent/{request}; render the client mark (logo only for a same-origin path or an https: URL, else the Bot icon circle), h1 mcp_connect.heading with :client, the subline, the fact box (signed_in_as with admin_with_email, returns_to with redirect_host in font-mono), the scope group (role=group labelled by api_tokens.scopes) with the copied row markup, the initial ticks and the * rule from the UI-SPEC, the offline row when offline_access was requested (ticked by default, D-10), and Deny then Allow. Allow is disabled while no scope is ticked or while busy. Allow POSTs {decision: 'allow', scopes, offline_access}; Deny POSTs {decision: 'deny'}; on 200 call window.location.assign(redirect_uri) after refusing javascript:, data: and vbscript: schemes. The redirect URI never goes through the router or the login-redirect sanitizer (it is absolute and server-issued); never use a native form submit. No auto-allow on mount, no initial focus on Allow or Deny, no Allow hotkey. All copy through t(); no literal UI strings.
Phrasebook: add the whole backend::lang.mcp_connect group of the UI-SPEC Copywriting Contract to en and pl (page_title, heading, subline, signed_in_as, admin_with_email, switch_account, returns_to, offline, offline_description, previously_allowed, allow, allowing, deny, returning, continue, login_hint, none_grantable, expired_heading, expired_body, open_admin, load_failed, retry, decide_failed), keeping plan 01's request_not_found and no_grantable_scopes. Reuse api_tokens.scopes, scope_all_includes, read_only and scopes_required; do not duplicate them.
Smoke test admin/tests/smoke/connect.smoke.test.ts: mount the router at /connect?request=req1 signed in, mock GET to answer two scopes and offline_access true; the card shows both scopes ticked and Stay connected ticked; clicking Allow POSTs scopes and offline_access true and calls a stubbed window.location.assign with the mocked redirect_uri, and the router's push and replace are not called with that URI. Commit source and test (not the dist) by path; do not git add -A.
</action>
<verify>
<automated>npm --prefix admin run typecheck && npm --prefix admin run test -- tests/smoke/connect.smoke.test.ts tests/app/router.test.ts tests/app/pageTitle.test.ts tests/app/i18n.test.ts</automated>
<fails_when>non-zero exit, or the vitest summary shows a failed test, or `No test files found`, or connect.smoke.test.ts is absent from the run output</fails_when>
<automated>scripts/check-admin-openapi.sh --check && go test -count=1 -run 'TestPhase09ContractInventory|TestPhase10OpenAPIConformance' ./modules/cabana</automated>
<fails_when>non-zero exit, or check-admin-openapi reports a differing file, or a line contains FAIL, or `[no tests to run]`</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "name: 'connect'" admin/src/app/router.ts` matches and that route object has neither `shell` nor `public` in its meta.
- `grep -n '/mcp/consent/{request}' admin/src/api/schema.d.ts` matches.
- ConnectView.vue contains `window.location.assign`; connect.smoke.test.ts asserts the router's push and replace were not called with the redirect_uri.
- Both phrasebook files contain `mcp_connect:` with page_title, heading, allow and deny.
- connect.smoke.test.ts passes and asserts window.location.assign was called with the mocked redirect_uri.
- check-admin-openapi.sh --check exits 0.
</acceptance_criteria>
<done>An administrator can finish a consent from the SPA and the browser leaves for the client redirect; the API contract is typed.</done>
</task>
<task type="auto">
<name>Every consent state, the account switch and the login hint</name>
<reversibility rating="reversible">View states and copy; no contract change.</reversibility>
<files>admin/src/views/ConnectView.vue, admin/src/views/LoginView.vue, admin/tests/smoke/connect.smoke.test.ts</files>
<read_first>
admin/src/views/ConnectView.vue (from task 1)
admin/src/views/LoginView.vue
admin/src/state/useAuth.ts (logout without router, expireSession, currentUser)
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md (C1 Other states, Interaction, C2, UI Considerations)
</read_first>
<action>
In ConnectView add the UI-SPEC C1 states: Loading (aria-busy true, sr-only h1 with page_title, the 48px skeleton circle, two skeleton bars and three skeleton scope rows, no buttons); Expired (404 on load or submit, or a missing/empty request; no network call in the missing case; Clock icon circle, expired_heading, expired_body, RouterLink to / with open_admin styled like Deny); Load error (5xx or network; page_title h1, alert block with load_failed, full-width Try again that reloads); No grantable scope (zero scopes: client mark, h1, subline and fact box, the none_grantable alert instead of the scope group, no offline row, only Deny, full width); Returning (client mark, h1 returning with :host, an inline LoaderCircle, and for http: or https: URIs a continue link with href = the URI). Inline alerts: 422 shows api_tokens.scopes_required under the scopes; 5xx, network or 400 shows decide_failed above the buttons; ticks kept and buttons re-enabled. 401 anywhere calls expireSession(router) so the browser returns to login with redirect = route.fullPath. Busy treatment: a disabled fieldset around the checkboxes, both buttons disabled, a spinner on the clicked one (Allow label becomes mcp_connect.allowing). Previously allowed note under the subline when consent_required is false (no auto-allow). After every state change past the first render, focus the state's h1 (or the alert block for inline errors). Admin value: admin.name with (email) when both present, the name alone without email, the login when the name is empty; when the API omits admin, fall back to currentUser.
Use another account (D-06): a type=button text button under the signed-in value; await logout() with no router argument, then router.replace({ name: 'login', query: { redirect: route.fullPath } }); disabled while a decision is in flight; when logout throws, show the decide_failed inline alert, keep the card and re-enable the button.
LoginView (C2): when safeRedirect(route.query.redirect) resolves to a path whose pathname is /connect, render one Meta line with mcp_connect.login_hint under the h1. Nothing else in LoginView changes; 2FA, Turnstile and redirect behaviour stay as they are (D-03).
Extend admin/tests/smoke/connect.smoke.test.ts with two smoke cases: a 404 on load renders expired_heading; Use another account calls POST /auth/logout and replaces to login with the redirect query. Commit by path.
</action>
<verify>
<automated>npm --prefix admin run typecheck && npm --prefix admin run test -- tests/smoke/connect.smoke.test.ts tests/views/LoginView.test.ts</automated>
<fails_when>non-zero exit, or the vitest summary shows a failed test, or `No test files found`</fails_when>
</verify>
<acceptance_criteria>
- ConnectView.vue contains `aria-busy`, `expired_heading`, `load_failed`, `none_grantable`, `returning` and `switch_account` keys.
- `grep -n 'logout()' admin/src/views/ConnectView.vue` matches (no router argument passed to logout).
- LoginView.vue references `mcp_connect.login_hint` and the existing LoginView.test.ts still passes.
- The extended smoke cases pass.
</acceptance_criteria>
<done>The consent card handles loading, expiry, failures, no-grantable-scope, returning and account switching as the UI-SPEC defines, and the login screen says why the administrator is signing in.</done>
</task>
<task type="auto">
<name>Account contribution items, docs and the rebuilt embedded dist</name>
<reversibility rating="reversible">Additive rendering of a field older sections never send; the dist is regenerated output.</reversibility>
<files>admin/src/components/account/AccountContributions.vue, admin/tests/smoke/account-items.smoke.test.ts, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, docs/backend/admin-spa.md, modules/boardwalk/dist</files>
<read_first>
admin/src/components/account/AccountContributions.vue (whole file: sections, actions, running guard, confirm usage)
admin/src/components/account/ApiTokensPanel.vue (list container and row classes)
admin/src/views/AccountView.vue (the confirm it passes down)
admin/tests/account/AccountContributions.test.ts (existing behaviour that must keep passing)
docs/backend/admin-spa.md
scripts/check-admin-dist.sh
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md (C3)
</read_first>
<action>
AccountContributions.vue (D-12, UI-SPEC C3), inside each section card after the status line and before the section buttons: when the section's items is null or absent render nothing new (the section looks exactly as today). When items is an array with entries, render a role=list container with the ApiTokensPanel row classes and one role=listitem row per item with data-account-item set to the item id: title, subtitle (omitted when empty), meta joined with ' · ' in tabular-nums (omitted when empty), and one Button size=sm per item_actions entry with data-account-item-action set to its name, variant danger plus the Ban icon when danger, else outline, aria-label t('backend::lang.myaccount.item_action_named', { action, title }). When items is an empty array render the dashed empty block (data-account-items-empty) with items_empty or myaccount.items_empty. A section with error true keeps the existing section_error line in place of both. Running an item action: Confirm or Danger → confirm.ask({ message: the confirm text with :title replaced by the item title as text, confirmLabel: action label, danger }, run); otherwise run directly. run POSTs /account/contributions/{name}/items/{encodeURIComponent(item)}/actions/{action}. The existing running guard disables every action button. 2xx: toast the answer message or form.action_done, then reload. 404: danger toast myaccount.item_gone, then reload. 409, 403 and other failures: exactly as section actions today. After a reload that follows an item action, focus the section heading (give it tabindex=-1).
Phrasebook en and pl: add myaccount.items_empty, myaccount.item_gone and myaccount.item_action_named with the UI-SPEC copy.
Smoke test admin/tests/smoke/account-items.smoke.test.ts: a section without items renders no list and no empty block; a section with items [] renders the empty block; a Danger item action asks the confirm with :title replaced and POSTs the item route.
docs/backend/admin-spa.md: document the /connect consent route (standalone, reached through the login redirect, framework screen over the cabana consent API) and the My account item rows and actions. Never name a consuming application.
Last: npm --prefix admin run build, then commit modules/boardwalk/dist as its own commit (stage modules/boardwalk/dist by path), after committing the component, test, phrasebook and docs changes by path. Do not git add -A.
</action>
<verify>
<automated>npm --prefix admin run typecheck && npm --prefix admin run test && npm --prefix admin run test:browser</automated>
<fails_when>non-zero exit, or the vitest summary shows a failed test, or `No test files found`</fails_when>
<automated>scripts/check-admin-dist.sh && scripts/check-admin-openapi.sh --check && go test ./cmd/summer -run TestDocsTree -count=1 && go run ./cmd/summer docs:build --check && go test -short -count=1 ./modules/boardwalk ./modules/phrasebook ./modules/cabana</automated>
<fails_when>non-zero exit, or check-admin-dist prints `modules/boardwalk/dist is stale`, or a line contains FAIL, or docs:build prints a problem line</fails_when>
</verify>
<acceptance_criteria>
- AccountContributions.vue contains `data-account-item`, `data-account-items-empty` and `data-account-item-action`.
- The whole admin vitest suite passes, including the unchanged tests/account/AccountContributions.test.ts.
- check-admin-dist.sh exits 0 after the dist commit; `git status --porcelain -- modules/boardwalk/dist` is empty.
- docs/backend/admin-spa.md mentions the /connect route; `git grep -n -i 'grzyby' -- admin/src docs/backend/admin-spa.md modules/phrasebook` prints nothing.
</acceptance_criteria>
<done>My account shows plugin-supplied rows with per-row actions, and the embedded admin the Go binary serves includes the consent route.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| Server-issued redirect_uri → browser navigation | The SPA navigates cross-origin to a URI wristband validated against the client's registered list |
| Server data → DOM | Client name, admin name/email, scope labels and item titles are untrusted text |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-32.2-09 | Spoofing (open redirect) | ConnectView navigation | high | mitigate | Navigate only to the redirect_uri of a 200 decision answer; refuse javascript:, data:, vbscript:; never accept a URI from the query string; the login round trip uses the unchanged safeRedirect |
| T-32.2-10 | Spoofing (phishing) | ConnectView fact box | medium | mitigate | Returns to (redirect host) is always shown and never truncated, as the MCP spec requires; client logo only from a same-origin path or https |
| T-32.2-11 | Tampering (XSS) | ConnectView, AccountContributions | high | mitigate | Every server string renders as text through Vue interpolation; no v-html; :title is substituted as text |
| T-32.2-12 | Elevation of privilege (click-through consent) | ConnectView | medium | mitigate | No auto-allow, no initial focus on Allow, no Allow hotkey; `*` is never pre-ticked unless it is the only scope |
| T-32.2-SC | Tampering | npm installs | low | accept | No new npm dependency; npm ci installs the committed lockfile |
</threat_model>
<verification>
Typecheck, the whole vitest suite and the browser suite pass; check-admin-openapi.sh --check and check-admin-dist.sh pass; docs:build --check passes; go test -short passes for boardwalk, phrasebook and cabana.
</verification>
<success_criteria>
- SC-1 SPA half: the consent card under the admin prefix, reached through the unchanged login (D-03, D-05, D-06, D-09, D-10, D-11).
- SC-3 SPA half: My account rows with Revoke-style item actions (D-12).
- SC-5: regenerated typed contract, rebuilt committed dist, admin-spa docs.
</success_criteria>
<output>
Create `.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-02-SUMMARY.md` when done.
</output>
## Artifacts this phase produces
Plan 02 (admin SPA):
- New file admin/src/views/ConnectView.vue (states: loading, ready, expired, load error, no grantable scope, returning)
- Route { path: '/connect', name: 'connect' } in admin/src/app/router.ts; connect branch in admin/src/app/pageTitle.ts
- Type aliases MCPConsent, MCPConsentDecision, AccountItem in admin/src/api/types.ts
- LoginView login hint (mcp_connect.login_hint)
- AccountContributions.vue item rows: data-account-item, data-account-item-action, data-account-items-empty
- Phrasebook keys: backend::lang.mcp_connect.* (page_title, heading, subline, signed_in_as, admin_with_email, switch_account, returns_to, offline, offline_description, previously_allowed, allow, allowing, deny, returning, continue, login_hint, none_grantable, expired_heading, expired_body, open_admin, load_failed, retry, decide_failed), backend::lang.myaccount.items_empty, item_gone, item_action_named
- Regenerated admin/openapi/admin.json and admin/src/api/schema.d.ts; rebuilt modules/boardwalk/dist
- Smoke tests: admin/tests/smoke/connect.smoke.test.ts, admin/tests/smoke/account-items.smoke.test.ts

View File

@@ -0,0 +1,238 @@
---
phase: 32.2-mcp-oauth-with-administrator-subjects
plan: 02
subsystem: admin-spa
tags: [mcp, oauth, consent, admin-spa, vue, boardwalk, phrasebook, my-account]
requires:
- phase: 32.2-01
provides: cabana GET/POST {api}/mcp/consent/{request}, POST {api}/account/contribution-items/{name}/{item}/actions/{action}, AccountContributionView items/item_actions/items_empty, regenerated admin.json and schema.d.ts
provides:
- admin SPA route /connect (name connect, no shell, not public) with ConnectView
- ConnectView states loading, ready, no grantable scope, expired, load error, returning, inline 422/decide failures
- LoginView login hint when the redirect is /connect
- AccountContributions item rows, empty block and item actions
- type aliases MCPConsent, MCPConsentDecision, AccountItem
- backend::lang.mcp_connect.* consent copy, myaccount.items_empty/item_gone/item_action_named (en, pl)
- rebuilt modules/boardwalk/dist
- docs/backend/admin-spa.md "Connect screen" section and My account item rows
affects: [32.2-03 sm-oauthserver-plugin backend mode (sets ConsentPath to {admin prefix}/connect, contributes the items section), 32.2-04 live run, 32.2-05 ConnectView.test.ts and extended unit tests]
actuals:
tokens: 11200
tasks: 3
commits: 4
plan_head_before: 1d3e6df6ecc1dcc2bfdd0872353261231e7874f9
plan_head_after: ee754b6b5d0669f3872ce2cd8362bb9cf775ae75
tech-stack:
added: []
patterns:
- "Server-issued cross-origin redirect leaves through window.location.assign after a scheme deny-list, never through the router or safeRedirect"
- "Consent card copies LoginView's light-literal palette (no Button.vue, no tokens, no dark: variants)"
- "Additive per-item rendering: items null keeps a section exactly as before"
key-files:
created:
- admin/src/views/ConnectView.vue
- admin/tests/smoke/connect.smoke.test.ts
- admin/tests/smoke/account-items.smoke.test.ts
modified:
- admin/src/app/router.ts
- admin/src/app/pageTitle.ts
- admin/src/api/types.ts
- admin/src/views/LoginView.vue
- admin/src/components/account/AccountContributions.vue
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- docs/backend/admin-spa.md
- modules/boardwalk/dist
key-decisions:
- "Deny posts {decision: 'deny', scopes: [], offline_access: false}: the generated MCPConsentDecisionRequest type marks all three fields required (swag --requiredByDefault), and cabana ignores scopes on deny"
- "Item ids are passed raw to openapi-fetch, which already applies encodeURIComponent to path parameters; the plan's explicit encodeURIComponent would double-encode (smoke test pins client:1 -> client%3A1)"
- "Focus follows the state heading only after the first settled render, so the initial load never moves focus; inline errors focus their alert block"
- "A 422 on Deny (not expected from cabana) shows decide_failed, not scopes_required"
- "While Use another account runs, Allow and Deny are disabled as well (locked = deciding or switching)"
patterns-established:
- "ConnectView talks only to cabana's admin API; plugins supply the consent through pact.MCPAdminConsent, never Vue code"
requirements-completed: [SC-1, SC-3, SC-5]
coverage:
- id: D1
description: "Signed-in admin at /connect?request= sees both scopes and Stay connected ticked; Allow POSTs {allow, scopes, offline_access true} with X-Requested-With and window.location.assign gets redirect_uri; router push/replace never see it; nothing posts before the click"
requirement: SC-1
verification:
- kind: unit
ref: "admin/tests/smoke/connect.smoke.test.ts#Allow posts the ticked scopes and Stay connected, then leaves for redirect_uri without the router"
status: pass
human_judgment: false
- id: D2
description: "404 on load renders the Expired state with a link to /; Use another account POSTs /auth/logout and lands on login with redirect=/connect?request=req1 and the login hint"
requirement: SC-1
verification:
- kind: unit
ref: "admin/tests/smoke/connect.smoke.test.ts#shows the Expired state when the request is unknown (404 on load)"
status: pass
- kind: unit
ref: "admin/tests/smoke/connect.smoke.test.ts#Use another account signs out and returns through login to the same request"
status: pass
human_judgment: false
- id: D3
description: "My account: section without items unchanged; items [] renders the empty block; danger item action confirms with :title filled, posts the encoded item route, reloads and focuses the section heading"
requirement: SC-3
verification:
- kind: unit
ref: "admin/tests/smoke/account-items.smoke.test.ts"
status: pass
- kind: unit
ref: "admin/tests/account/AccountContributions.test.ts (unchanged, 16 tests)"
status: pass
human_judgment: false
- id: D4
description: "Typed contract regenerated and unchanged, dist rebuilt and committed, docs checker clean, SPA phrase keys resolve in en and pl"
requirement: SC-5
verification:
- kind: other
ref: "scripts/check-admin-openapi.sh --check; scripts/check-admin-dist.sh; summer docs:build --check; go test ./cmd/summer -run TestDocsTree; modules/phrasebook TestPhase10SPAKeysResolve"
status: pass
human_judgment: false
- id: D5
description: "Cross-site cookie on the real connector flow shows the signed-in card, not login, after the cross-site redirect (UI-SPEC backstop, RESEARCH Pitfall 7)"
requirement: SC-1
verification:
- kind: manual
ref: "deferred to the live connector check (plan 04 / deploy)"
status: pending
human_judgment: true
duration: 20min
completed: 2026-11-21
status: complete
---
# Phase 32.2 Plan 02: Admin consent screen and My account item rows Summary
**A standalone `/connect` consent card in the admin SPA that an administrator reaches through the normal login, which posts Allow/Deny to cabana's consent API and sends the browser to the server-issued `redirect_uri` with `window.location.assign`. Plus per-item rows with Revoke-style actions on My account, and the rebuilt embedded dist.**
## Performance
- **Duration:** about 20 min
- **Started:** 2026-11-20T23:36Z
- **Completed:** 2026-11-20T23:56Z
- **Tasks:** 3 of 3
- **Files modified:** 12 source/doc files plus the regenerated `modules/boardwalk/dist`
## Accomplishments
- **Tracer.** At `/connect?request=req1` a signed-in administrator sees the scopes the API returned, in catalog order, together with Stay connected. Allow sends `{decision, scopes, offline_access}` through openapi-fetch (with X-Requested-With and the same-origin cookie), and the browser leaves through `window.location.assign`. The router never sees the URI. The smoke test proves this against plan 01's JSON contract.
- **Every C1 state:**
- Loading: skeleton card with `aria-busy` and no buttons.
- Expired: a 404 on load or submit, or no `request` parameter (in which case no network call is made).
- Load error: shows Try again.
- No grantable scope: only Deny, full width.
- Returning: an inline spinner, plus a continue link for http(s) URIs.
- Inline errors: a 422 shows `scopes_required` and the ticks are kept. A 5xx, a network failure, a 400, or a `javascript:`/`data:`/`vbscript:` URI shows `decide_failed`.
- 401: handled by `expireSession`.
- **Scope picker.** Uses the token-dialog `*` rule (ticking `*` clears and disables the others and shows the note). `*` starts unticked unless it is the only scope. The Read-only pill and the logo rule (a same-origin path or `https:`, else the Bot circle) are in place. There is no auto-allow, no initial focus on Allow or Deny, and no hotkey.
- **Use another account.** Calls `logout()` without a router, then `router.replace({ name: 'login', query: { redirect: route.fullPath } })`. LoginView shows `mcp_connect.login_hint` when `safeRedirect(redirect)` points to `/connect`.
- **My account items.**
- A section with `items` shows one `role=listitem` row per item (title, subtitle, and meta joined with ` · `) and one `Button size=sm` per item action. Danger actions get the Ban icon and the `item_action_named` aria-label.
- An empty `items` array shows the dashed empty block.
- A section with `items: null` renders exactly as before, and the existing 16 AccountContributions tests are unchanged and pass.
- Item actions confirm with `:title` filled in as text, post the item route, reload, and focus the section heading. A 404 shows the `item_gone` toast and reloads.
- **Docs and dist.** `docs/backend/admin-spa.md` has a new "Connect screen" section and a paragraph on My account item rows. `modules/boardwalk/dist` is rebuilt and committed, and `check-admin-dist.sh` passes.
## Task Commits
1. **Task 1 (tracer): consent card at /connect, decision POST, leave for redirect_uri** - `f46c90f7` (feat)
2. **Task 2: every consent state, account switch and login hint** - `6900bd1a` (feat)
3. **Task 3: My account item rows, docs** - `27089826` (feat); **rebuilt dist** - `ee754b6b` (chore)
Tracer gate: auto mode is off, and human_verify_mode is end-of-phase with an automated-only `<verify>`. The verify ran again (typecheck, the connect, router, pageTitle and i18n vitest files, `check-admin-openapi.sh --check`, and the contract and conformance Go tests) and passed, so expansion continued.
## Files Created/Modified
- `admin/src/views/ConnectView.vue`: the consent card with all of its states
- `admin/src/app/router.ts`: `{ path: '/connect', name: 'connect', component: ConnectView }`, without `meta.shell` or `meta.public`. `safeRedirect` and `beforeEach` are unchanged
- `admin/src/app/pageTitle.ts`: connect branch → `mcp_connect.page_title`
- `admin/src/api/types.ts`: `MCPConsent`, `MCPConsentDecision`, `AccountItem`
- `admin/src/views/LoginView.vue`: the login hint line, and nothing else
- `admin/src/components/account/AccountContributions.vue`: item rows, the empty block, item actions, and a focusable section heading
- `modules/phrasebook/backend/lang/{en,pl}/lang.yaml`: the 23 `mcp_connect` keys and 3 `myaccount` keys
- `docs/backend/admin-spa.md`: the Connect screen and My account item rows
- `admin/tests/smoke/connect.smoke.test.ts` (3 cases), `admin/tests/smoke/account-items.smoke.test.ts` (3 cases)
- `modules/boardwalk/dist`: rebuilt
## Decisions Made
- Deny sends `scopes: []` and `offline_access: false` along with `decision: 'deny'`. The generated request type requires all three fields, and cabana ignores them on a deny.
- Path parameters are not encoded by hand, because openapi-fetch's `defaultPathSerializer` already applies `encodeURIComponent`.
- Focus moves only after the first settled render, so the initial load does not move focus. Later state changes focus the state's `h1`, and inline errors focus their alert.
- `locked` covers both a decision in flight and an account switch in progress, so Allow, Deny and Use another account cannot overlap.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 1 - Bug] No double-encoding of the item id**
- **Found during:** Task 3
- **Issue:** The plan says to POST `.../{encodeURIComponent(item)}/...`. openapi-fetch already encodes path parameters, so a second `encodeURIComponent` would turn `client:1` into `client%253A1`, and the item would never be found (404).
- **Fix:** The raw `item.id` is passed in `params.path`. The smoke test checks that the request goes to `.../contribution-items/agents/client%3A1/actions/revoke`.
- **Files modified:** admin/src/components/account/AccountContributions.vue, admin/tests/smoke/account-items.smoke.test.ts
- **Commit:** 27089826
**2. [Prior-wave pickup] Item action path**
- The SPA uses plan 01's `/account/contribution-items/{name}/{item}/actions/{action}`, not the plan's `/account/contributions/{name}/items/...`. The plan's key_link pattern `/items/` therefore does not match. The route is typed in `schema.d.ts`.
**3. [Rule 3 - Interpretation] Deny body**
- The plan says "Deny POSTs {decision: 'deny'}". The typed body needs `scopes` and `offline_access`, so they are sent empty and false. The server accepts this (DisallowUnknownFields only refuses extra keys).
**Other notes:**
- `scripts/check-admin-openapi.sh` produced no diff, as expected after plan 01. `--check` passes.
- `modules/cabana/admin_openapi.go` is untouched, because swag accepted every annotation from plan 01.
**Total deviations:** 1 bug fix, 1 contract pickup, 1 interpretation. No scope creep.
## Issues Encountered
- `rm` is aliased to an interactive prompt in this shell. A throwaway scratch test (it exercised the `*` rule, no grantable scope, 422, a `javascript:` URI, a 5xx followed by retry, a missing request and the anonymous redirect, and all passed) was removed with `command rm -f`, and nothing from it was committed.
## Known Stubs
None.
## Threat Flags
None. The consent screen adds no new server surface. It uses only the plan 01 routes covered by T-32.2-09..12:
- `redirect_uri` comes only from the 200 decision answer, with the scheme deny-list applied.
- The redirect host is always shown and never truncated.
- Every server string is rendered by interpolation and `v-html` is never used. `:title` is filled in as text.
- There is no auto-allow, and `*` is never pre-ticked unless it is the only scope.
## Verification
- `npm --prefix admin run typecheck`: pass.
- `npm --prefix admin run test`: 116 files and 1685 tests pass. `npm --prefix admin run test:browser`: 4 files and 13 tests pass.
- `scripts/check-admin-openapi.sh --check`, `scripts/check-admin-dist.sh` (after the dist commit), `go test ./cmd/summer -run TestDocsTree` and `summer docs:build --check` ("no problems found"): pass.
- `go test -short` passes for `./modules/boardwalk`, `./modules/phrasebook` (including TestPhase10SPAKeysResolve, so every new key resolves in en and pl) and `./modules/cabana`. `TestPhase09ContractInventory` and `TestPhase10OpenAPIConformance` pass and were not skipped.
- `go vet ./...` and `go test -short -count=1 ./...` pass for the whole module.
- `git grep -n -i 'grzyby' -- admin/src docs/backend/admin-spa.md modules/phrasebook` finds nothing.
- `git status --porcelain -- modules/boardwalk/dist` is empty.
## User Setup Required
None.
## Next Phase Readiness
- Plan 03: set `wristband.Options.ConsentPath` to `<admin prefix>/connect` (the SPA reads `?request=`), and contribute the `mcp_connections` section with `Items`/`ItemActions` (`revoke`, `Danger: true`, a `Confirm` with `:title`).
- Plan 05: write `ConnectView.test.ts` covering the `*` rule, no auto-allow, the switch round trip and the back-compat backstops against the `data-*` hooks used here (`data-connect-state`, `data-scope`, `data-connect-offline`, `data-action="allow|deny|switch-account|retry|open-admin"`, `data-connect-error`, `data-connect-none-grantable`, `data-previously-allowed`, `data-scope-all-note`, `data-connect-continue`, `data-login-hint`).
- Human verification is still needed for the cross-site cookie on a real connector (D5).
## Self-Check: PASSED
- All 3 created files exist on disk.
- Commits f46c90f7, 6900bd1a, 27089826 and ee754b6b are in `git log`.

View File

@@ -0,0 +1,364 @@
---
phase: 32.2
plan: 03
type: execute
wave: 2
depends_on: [32.2-01]
files_modified:
- ../sm-oauthserver-plugin/config/config.yaml
- ../sm-oauthserver-plugin/servers.go
- ../sm-oauthserver-plugin/routes.go
- ../sm-oauthserver-plugin/plugin.go
- ../sm-oauthserver-plugin/updates/202611200001_add_golem15_oauthserver_backend_subjects.go
- ../sm-oauthserver-plugin/models/consent.go
- ../sm-oauthserver-plugin/models/mcp_connection.go
- ../sm-oauthserver-plugin/models/mcpconnection/columns.yaml
- ../sm-oauthserver-plugin/classes/mcp_backend_subject.go
- ../sm-oauthserver-plugin/classes/mcp_store.go
- ../sm-oauthserver-plugin/classes/mcp_verifier.go
- ../sm-oauthserver-plugin/classes/backend_cascade.go
- ../sm-oauthserver-plugin/controllers/mcp_admin_consent.go
- ../sm-oauthserver-plugin/controllers/mcp_connections.go
- ../sm-oauthserver-plugin/controllers/mcpconnections/config_list.yaml
- ../sm-oauthserver-plugin/controllers/admin_registry.go
- ../sm-oauthserver-plugin/account.go
- ../sm-oauthserver-plugin/admin.go
- ../sm-oauthserver-plugin/admin_permissions.go
- ../sm-oauthserver-plugin/admin_navigation.go
- ../sm-oauthserver-plugin/lang/en/lang.yaml
- ../sm-oauthserver-plugin/lang/pl/lang.yaml
- ../sm-oauthserver-plugin/harness_test.go
- ../sm-oauthserver-plugin/backend_mode_smoke_test.go
- ../sm-oauthserver-plugin/backend_revocation_smoke_test.go
- ../sm-oauthserver-plugin/backend_account_smoke_test.go
- ../sm-oauthserver-plugin/README.md
- ../sm-oauthserver-plugin/plugin.yaml
autonomous: true
requirements: [SC-1, SC-2, SC-3, SC-5]
estimate:
tokens: 130000
raw_tokens: 130000
tasks: 3
confidence: low
must_haves:
truths:
- "SC-1, D-02, D-07: golem15.oauthserver has a new config key mcp.subject with values user (the default) and backend; mcp.consent_path (empty: <backend.uri>/connect in backend mode, /connect in user mode) and oidc.enabled (default true) are new too. An unknown subject, backend with mcp.enabled false, and backend together with mcp_scopes fail boot with a clear message. With the defaults, every route, scope list, store write and existing test behaves exactly as before."
- "D-08: Requires() still answers [golem15.user] in both modes."
- "SC-1, D-01, D-03, D-04: in backend mode /oauth/mcp/authorize hands the browser to {issuer}<backend.uri>/connect?request=<id>; the plugin publishes pact.MCPAdminConsent, and an allow through cabana's {api}/mcp/consent/{request} issues a code under the backend grants lock whose mcp_codes, access_tokens, refresh_tokens and consents rows have user_id NULL and backend_user_id = the administrator; no frontend user is involved."
- "SC-1 (Pitfall 4, Pitfall 6): in backend mode the user-mode consent routes /oauth/mcp/requests/{request} are not mounted (404); with oidc.enabled false the OIDC discovery, JWKS, /oauth/authorize*, /oauth/token and /oauth/userinfo routes are not mounted, and the frontend authorized-apps routes are mounted only when oidc.enabled is true or the subject is user."
- "SC-2, D-09: in backend mode wristband metadata scopes_supported, the authorize allow-list and the verifier's MCPScopesSupported (so pier's protected-resource metadata) are cabana.TokenScopeNames plus offline_access, and Options.DefaultScopes is the catalog names, so a client sending no scope does not fall back to read."
- "SC-2, D-01: the verifier answers a backend row (user_id NULL, backend_user_id set) as pact.MCPGrant{UserID: 0, BackendUserID: admin, Subject: pact.MCPGrantSubjectBackend, ClientID, TokenID, Scopes, ExpiresAt}, refusing it when cabana.BackendPrincipal answers nil (deleted or deactivated) or the token was issued before the administrator's tokens_valid_after; user rows take the unchanged path."
- "D-10: offline_access granted on the admin consent yields a refresh token; refresh rotation of a backend row keeps user_id NULL and backend_user_id, and refuses a deleted, deactivated or re-passworded administrator."
- "SC-3, D-13: a listener on cabana.BackendAccessRevokedEvent (registered only in backend mode) revokes, inside the save's transaction and under the backend grants lock, every backend access and refresh token of the administrators, deletes their unused backend codes and backend consents, and after commit fires pact.MCPSubjectChanged{Guard: backend, UserID, Kind: revoked, ClientID} once per touched client. User rows and user-mode linked grants are not touched."
- "SC-3, D-12: in backend mode the plugin contributes a My account section mcp_connections (only then; user-mode apps' My account is unchanged) listing the signed-in administrator's backend consents (ID client_id, Title client name falling back to client_id, Subtitle scope labels without offline_access, Meta connected / last used or never used) ordered by last_used_at DESC NULLS LAST then created_at DESC, with one item action revoke (Danger, Confirm with :title) that revokes that one client's grant and ends its sessions."
- "SC-3, D-12: in backend mode a side-menu entry mcp_connections (icon network, after OAuth clients) opens the admin-wide list golem15.oauthserver.mcpconnections, gated by the new permission golem15.oauthserver.manage_mcp_connections (no default role; superusers pass), with columns administrator, email, client, scopes, created_at, last_used_at, no toolbar buttons, no recordUrl, recordsPerPage 20 and a bulk action revoke."
- "UI loading — the admin-wide MCP connections list uses the existing ListView skeleton rows."
- "UI empty — the admin-wide list shows mcp_connections.list_empty; an empty search uses the existing empty-search message."
- "UI error — the admin-wide list relies on the existing ListView error handling and bulk-action failure toast; nothing new."
- "UI long-text — administrator, email, client and scopes cells wrap with the existing ListView cell wrapping."
- "UI overflow — on a small screen the admin-wide list uses the existing ListView horizontal scroll container."
- "UI zero-one-many — the admin-wide list pages 20 rows with the existing pager; zero rows show mcp_connections.list_empty."
- "UI partial — the administrator column falls back to the login when the administrator has no name."
- "UI partial — a My account item whose client has no name uses the client_id as its Title."
- "SC-5: the plugin README documents backend mode (keys, routes, scopes, storage, migration and rollback, revocation, My account section, MCP connections screen and permission, exclusive per application for now) in the commits that add each piece; the migration is additive and its rollback is documented as deleting backend grants."
artifacts:
- path: ../sm-oauthserver-plugin/updates/202611200001_add_golem15_oauthserver_backend_subjects.go
provides: "nullable user_id on access/refresh/consents, consents.backend_user_id, partial unique and lookup indexes, NOT VALID subject checks"
contains: "oas_consents_backend_client_unique"
- path: ../sm-oauthserver-plugin/classes/mcp_backend_subject.go
provides: "WithBackendSubject, backend grants advisory locks, RevokeBackendGrants"
contains: "WithinBackendGrantsLock"
- path: ../sm-oauthserver-plugin/classes/mcp_verifier.go
provides: "backend branch returning MCPGrantSubjectBackend"
contains: "MCPGrantSubjectBackend"
- path: ../sm-oauthserver-plugin/controllers/mcp_admin_consent.go
provides: "pact.MCPAdminConsent implementation"
contains: "MCPAdminConsentDecide"
- path: ../sm-oauthserver-plugin/classes/backend_cascade.go
provides: "listener for cabana.BackendAccessRevokedEvent"
contains: "BackendAccessRevokedEvent"
- path: ../sm-oauthserver-plugin/account.go
provides: "HasAccountContributions mcp_connections section"
contains: "AccountContributions"
key_links:
- from: ../sm-oauthserver-plugin/servers.go
to: "cabana.TokenScopeNames / wristband Options.ConsentPath + DefaultScopes (plan 01)"
via: "backend-mode NewServers"
pattern: "TokenScopeNames"
- from: ../sm-oauthserver-plugin/plugin.go Boot
to: pact.MCPAdminConsent
via: "app.Publish in backend mode; cabana's consent endpoint looks it up"
pattern: "MCPAdminConsent"
- from: ../sm-oauthserver-plugin/classes/mcp_store.go
to: ../sm-oauthserver-plugin/classes/mcp_backend_subject.go
via: "backendSubjectFrom(ctx) on writes, backend row detection on reads"
pattern: "backendSubject"
- from: ../sm-oauthserver-plugin/classes/backend_cascade.go
to: "pier session teardown"
via: "MCPSubjectChanged revoked with ClientID after commit"
pattern: "MCPSubjectRevoked"
---
<objective>
User story (phase goal, ROADMAP 32.2): **As an** editor of a blog-only application whose MCP tools are backend-guarded (Journal) and which has no frontend users, **I want to** add the site's `/mcp` as a connector and sign in once as my administrator account over OAuth, **so that** agents no longer need a hand-copied `g15_` personal token.
Slice in this plan (the OAuth server issues the administrator's grant): in backend mode, an MCP client's authorize request is handed to the admin consent route, and an Allow through cabana's consent API issues a code. The exchanged token verifies as an administrator-only grant whose rows name the administrator and no frontend user (TestBackendModeSmoke, the first real-token path of the phase). Administrators also list and revoke their own connections on My account.
The plugin half of SC-1, SC-2 and SC-3 (D-01, D-02, D-03, D-04, D-07, D-08, D-09, D-10, D-12, D-13): an additive, off-by-default backend-subject mode of sm-oauthserver-plugin, where the MCP OAuth sign-in authenticates an administrator and the grant names that administrator.
Purpose: an application whose MCP tools are backend-guarded and which has no frontend users can accept MCP OAuth sign-in as an administrator. The plugin is shared by several applications, so every change is additive and the user mode (the default) behaves exactly as before.
Output: config keys, one additive migration, per-row subject storage in the existing tables, backend advisory locks, verifier and refresh branches, the published consent provider, the cabana-event revocation listener, the My account section, the admin-wide MCP connections screen with its permission, and README, all in ../sm-oauthserver-plugin. Smoke tests only; the broad tests are plan 05.
⚠ spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
Discretion recorded (CONTEXT "Claude's Discretion"):
- Storage: nullable user_id on access tokens, refresh tokens and consents, plus consents.backend_user_id with a partial unique index (backend_user_id, client_id) WHERE user_id IS NULL, in one additive migration. Every user-mode query filters on user_id, so NULL rows are invisible to it. Model field types stay as they are (UserID uint scans NULL as 0); Consent gains BackendUserID *uint.
- Permission: golem15.oauthserver.manage_mcp_connections, no default role.
- Admin-wide list model: a read-only models.MCPConnection whose list query is a derived table aliased to the model's table name, joining consents to backend_users and clients so administrator (full name falling back to login), email and client are real searchable columns. If cabana's list query cannot take the derived table, fall back to relation columns (relation admin select login, relation admin select email, relation client select name over references:ClientID) and record the full-name deviation in the SUMMARY.
- The backend-mode admin controller, permission, navigation entry and My account section are returned only in backend mode, so controllers.AdminControllers(nil) and every user-mode surface stay as they are. cabana compiles these at Activate, which runs after Boot, so the booted config is known; if a test shows otherwise, record it and declare them unconditionally.
- Reversibility: D-02 and D-07 make the mode and its keys a public contract (costly, recorded on the tasks); the migration is costly (its rollback drops backend grants); nothing is one-way, so no checkpoint.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-CONTEXT.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-RESEARCH.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-PATTERNS.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-01-SUMMARY.md
@../sm-oauthserver-plugin/README.md
@../sm-oauthserver-plugin/plugin.go
@../sm-oauthserver-plugin/servers.go
@../sm-oauthserver-plugin/routes.go
@../sm-oauthserver-plugin/config/config.yaml
@../sm-oauthserver-plugin/classes/mcp_store.go
@../sm-oauthserver-plugin/classes/mcp_verifier.go
@../sm-oauthserver-plugin/classes/mcp_backend_binding.go
@../sm-oauthserver-plugin/classes/cascade.go
@../sm-oauthserver-plugin/controllers/mcp_consent_api.go
@../sm-oauthserver-plugin/harness_test.go
<interfaces>
From plan 01 (summercms.go working tree; the plugin's go.mod replaces the framework with ../summercms.go; check 32.2-01-SUMMARY.md for any rename):
- pact.MCPGrant.Subject string; const pact.MCPGrantSubjectBackend = "backend"; pact.MCPSubject.ScopeLimited bool
- pact.MCPAdminConsent interface { MCPAdminConsentShow(ctx, adminID uint, requestID string) (pact.MCPAdminConsentRequest, error); MCPAdminConsentDecide(ctx, adminID uint, requestID string, d pact.MCPAdminConsentDecision) (string, error) }
- pact.MCPAdminConsentRequest{RequestID, ClientID, ClientName, LogoURL, RedirectURI string; Scopes []string; OfflineAccess, ConsentRequired bool; ExpiresAt time.Time}; pact.MCPAdminConsentDecision{Allow bool; Scopes []string; OfflineAccess bool}; pact.ErrMCPConsentNotFound, pact.ErrMCPConsentNoScopes
- pact.AccountContribution.Items func(ctx, adminID uint) ([]pact.AccountItem, error); ItemActions []pact.AccountItemAction; ItemsEmpty string; pact.AccountItem{ID, Title, Subtitle string; Meta []string}; pact.AccountItemAction{Name, Label, Confirm string; Danger bool; Permissions []string; Run func(ctx, pact.AccountItemActionInput) (pact.AccountActionResult, error)}; pact.AccountItemActionInput{AdminID uint; ItemID string}; pact.ErrAccountItemNotFound
- wristband.Options.ConsentPath string; wristband.Options.DefaultScopes []string
- cabana.TokenScopeNames(app) ([]string, error); cabana.TokenScopeLabels(ctx, app, names) []string; cabana.AdminPrefix(app) (string, error); cabana.BackendPrincipal(ctx, app, id) (*bouncer.Principal, error) — nil for deleted/deactivated, Principal.TokensValidAfter time.Time
- cabana.BackendAccessRevokedEvent{AdminIDs []uint; Reason string; Tx *gorm.DB}
Existing plugin (read this session):
- Config{..., MCPEnabled bool; MCPResource string}; LoadConfig reads golem15.oauthserver.*; NewServers builds mcpOpts from DefaultOptions with ScopesSupported = classes.AdvertisedMCPScopes(app) and the verifier with the same slice
- Boot publishes servers.KeyRing, pact.MCPTokenVerifier (when MCPEnabled) and registers Cascade listeners on userclasses events
- routes.go: OIDC groups at lines 40-68, MCP group at lines 70-82 (metadata, authorize, register, token; user consent /oauth/mcp/requests/{request} behind jwt.auth)
- classes/mcp_backend_binding.go: consentedBackendKey/WithConsentedBackend, WithGrantedOfflineAccess, backendBinding(scopes, id) (nil unless the backend scope), userGrantsLockKey "golem15_oauthserver_user_grants:<id>", lockUserGrantsShared, LockUserGrants, grantsTxKey, WithinUserGrantsLock
- classes/mcp_store.go: mcpTx methods MarkIssued (column map), ByCodeHashForUpdate, Create (refresh), ByTokenHashForUpdate, refreshUserUsable, refreshRecord, Mint, consentedBackend
- classes/mcp_verifier.go: MCPVerifyToken, stamp, issuedBeforeCutoff(createdAt *time.Time, cutoff time.Time) bool
- classes/subject_events.go: FireSubjectChanged, FireSubjectChangedAfterCommit(ctx, app, tx, guard, userID, kind)
- controllers/mcp_consent_api.go: mcpRequestedScopes, mcpPendingClientID, replaceMCPConsent, clipRunes, maxMCPClientName, mcpScopeText
- models: AccessToken.UserID uint, AccessToken.BackendUserID *uint, RefreshToken.UserID uint/BackendUserID *uint, MCPCode.UserID *uint/BackendUserID *uint, Consent{ID, UserID uint, ClientID, Scopes Strings, LastUsedAt, CreatedAt, UpdatedAt}
- controllers.AdminControllers(func() *backpack.App) answers exactly the clients and branding controllers (admin_surface_test.go pins that)
- harness_test.go: bootOAuthWith(t, extra []string, overrides ...string) with SUMMER_* overrides; env.admin(t, permissions...) answers an admin bearer; adminCall uses cabana.DefaultAdminPrefix + "/api/v1"
</interfaces>
</context>
<tasks>
<task type="tracer">
<name>Tracer: in backend mode an administrator consents through cabana and the issued token verifies as an administrator-only grant</name>
<reversibility rating="costly">D-02 and D-07 publish mcp.subject (values user and backend), mcp.consent_path and oidc.enabled as the plugin's config contract, and the migration changes three columns other code reads; its rollback deletes backend grants.</reversibility>
<precondition>docker info exits 0; `grep -n 'MCPGrantSubjectBackend' /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/pact/mcp.go` and `grep -n 'type MCPAdminConsent interface' /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/pact/mcp.go` match (plan 01 landed).</precondition>
<files>../sm-oauthserver-plugin/config/config.yaml, ../sm-oauthserver-plugin/servers.go, ../sm-oauthserver-plugin/routes.go, ../sm-oauthserver-plugin/plugin.go, ../sm-oauthserver-plugin/updates/202611200001_add_golem15_oauthserver_backend_subjects.go, ../sm-oauthserver-plugin/models/consent.go, ../sm-oauthserver-plugin/classes/mcp_backend_subject.go, ../sm-oauthserver-plugin/classes/mcp_store.go, ../sm-oauthserver-plugin/classes/mcp_verifier.go, ../sm-oauthserver-plugin/controllers/mcp_admin_consent.go, ../sm-oauthserver-plugin/harness_test.go, ../sm-oauthserver-plugin/backend_mode_smoke_test.go, ../sm-oauthserver-plugin/README.md</files>
<read_first>
../sm-oauthserver-plugin/config/config.yaml (comment style, mcp block, mcp_scopes)
../sm-oauthserver-plugin/servers.go (Config, LoadConfig, NewServers)
../sm-oauthserver-plugin/routes.go (every GroupRaw block)
../sm-oauthserver-plugin/plugin.go (Requires, Boot)
../sm-oauthserver-plugin/updates/202610230001_add_backend_user_id.go (migration file shape, run helper, Register in init)
../sm-oauthserver-plugin/updates/202610190001_create_golem15_oauthserver_tables.go (current columns and constraints)
../sm-oauthserver-plugin/classes/mcp_backend_binding.go (context keys, lock keys, WithinUserGrantsLock join-the-tx trick)
../sm-oauthserver-plugin/classes/mcp_store.go (MarkIssued, ByCodeHashForUpdate, mcpCodeRecord, Mint, Create)
../sm-oauthserver-plugin/classes/mcp_verifier.go (MCPVerifyToken, issuedBeforeCutoff)
../sm-oauthserver-plugin/controllers/mcp_consent_api.go (MCPConsentShow, MCPConsentDecide, replaceMCPConsent, IssueCode usage)
../sm-oauthserver-plugin/harness_test.go and admin_smoke_test.go (bootOAuthWith, env.admin, adminCall)
../sm-oauthserver-plugin/mcp_consent_smoke_test.go (PKCE + DCR + authorize + token test flow to copy)
/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/cabana/mcp_consent.go (the endpoint this provider serves; from plan 01)
</read_first>
<action>
Config (D-07, D-04, D-14 prerequisite): in config/config.yaml add under mcp, with the file's comment style and "(new)" markers, subject: user (user or backend; backend authenticates an administrator and needs mcp.enabled; one subject per application for now) and consent_path: "" (empty: <backend.uri>/connect in backend mode, /connect in user mode), and a new top-level oidc block with enabled: true (false mounts no OIDC provider routes). Name the env vars SUMMER_GOLEM15__OAUTHSERVER__MCP__SUBJECT, ..._MCP__CONSENT_PATH and ..._OIDC__ENABLED in the comments. In servers.go add Config.MCPSubjectMode (exported constants SubjectModeUser = "user" and SubjectModeBackend = "backend" in package classes), Config.MCPConsentPath and Config.OIDCEnabled, read in LoadConfig; empty subject is user; any other value fails boot ("%s: mcp.subject %q must be user or backend"); backend with mcp.enabled false fails boot; backend while golem15.oauthserver.mcp_scopes is set fails boot (the member-scope filter has no meaning there).
Migration (storage discretion), new updates/202611200001_add_golem15_oauthserver_backend_subjects.go with ID 202611200001_add_golem15_oauthserver_backend_subjects, raw SQL through run like 202610230001: ALTER COLUMN user_id DROP NOT NULL on golem15_oauthserver_access_tokens, _refresh_tokens and _consents; ADD COLUMN backend_user_id INTEGER NULL on _consents (no FK: backend users are only soft-deleted); CREATE UNIQUE INDEX oas_consents_backend_client_unique ON _consents (backend_user_id, client_id) WHERE user_id IS NULL; CREATE INDEX oas_tokens_backend_client_idx and oas_refresh_backend_client_idx on (backend_user_id, client_id) WHERE user_id IS NULL; ADD CONSTRAINT oas_tokens_subject_check CHECK ((user_id IS NOT NULL AND user_id > 0) OR backend_user_id IS NOT NULL) NOT VALID, oas_refresh_subject_check and oas_consents_subject_check CHECK (user_id IS NOT NULL OR backend_user_id IS NOT NULL) NOT VALID. Rollback: DELETE the user_id IS NULL rows of the three tables (comment: backend grants cannot survive a down migration), drop the constraints, indexes and column, SET NOT NULL. Do not touch auth_codes (OIDC) or mcp_codes (already nullable). Add BackendUserID *uint (column backend_user_id) to models.Consent; do not change any existing field type.
Subject and locks, new classes/mcp_backend_subject.go: WithBackendSubject(ctx) context.Context and unexported backendSubjectFrom(ctx) bool; backendGrantsLockKey(id) = "golem15_oauthserver_backend_grants:" + id (a namespace separate from users, so administrator 7 and user 7 never contend); lockBackendGrantsShared, LockBackendGrants(ctx, db, adminIDs) and WithinBackendGrantsLock(ctx, db, adminIDs, fn) reusing grantsTxKey exactly like WithinUserGrantsLock so MCPStore.WithinTx joins the locked transaction.
Store, authorization-code path (classes/mcp_store.go): MarkIssued with backendSubjectFrom(ctx) writes user_id nil and backend_user_id = the id wristband passes (regardless of the backend scope; never reuse backendBinding for it); ByCodeHashForUpdate also selects backend_user_id, and a row with user_id NULL and backend_user_id set takes lockBackendGrantsShared, fills the record's UserID from backend_user_id and marks the mcpTx as a backend-subject transaction; Mint and Create (refresh) in a backend-subject transaction write no user_id (column map or Omit, never a zero) and backend_user_id = the id. User-mode writes are unchanged.
Verifier (D-01, D-09): in MCPVerifyToken, after the existing token and client checks and before the user principal lookup, a row with UserID 0 and BackendUserID set loads cabana.BackendPrincipal; nil, an error, or issuedBeforeCutoff(token.CreatedAt, principal.TokensValidAfter) answers pact.ErrMCPTokenInvalid; otherwise stamp and answer pact.MCPGrant{UserID: 0, BackendUserID, Subject: pact.MCPGrantSubjectBackend, ClientID, TokenID, Scopes, ExpiresAt}. The user path is unchanged.
Consent provider (D-03), new controllers/mcp_admin_consent.go: exported type MCPAdminConsent{App *backpack.App; Server *wristband.Server} with NewMCPAdminConsent(app, srv) implementing pact.MCPAdminConsent. Show: srv.PendingRequest(ctx, requestID, adminID) (wristband.ErrPendingNotFound → pact.ErrMCPConsentNotFound), the client name clipped like the user-mode API, the logo URL, the pending redirect URI, requested data scopes without offline_access, OfflineAccess, ConsentRequired (false when the administrator's backend consent for the client already covers the request), ExpiresAt. Decide: deny → srv.DenyPending; allow → WithinBackendGrantsLock for the administrator, then IssueCode with ctx carrying WithBackendSubject and WithGrantedOfflineAccess(d.OfflineAccess), then replace the backend consent row (user_id NULL, backend_user_id, client_id, the granted scopes plus offline_access when granted; INSERT … ON CONFLICT on the partial unique index; never merge with older scopes); wristband.ErrNoGrantableScopes → pact.ErrMCPConsentNoScopes. Answer the redirect target IssueCode or DenyPending returns. Do not log codes or bearer tokens.
Servers and routes (D-04, D-09, Pitfalls 3, 4, 6): in NewServers, backend mode sets mcpOpts.ScopesSupported = cabana.TokenScopeNames(app) plus offline_access (same slice on the verifier, so pier's protected-resource metadata advertises it), mcpOpts.DefaultScopes = the catalog names, and mcpOpts.ConsentPath = cfg.MCPConsentPath or cabana.AdminPrefix(app) + "/connect" (an AdminPrefix error fails boot). User mode keeps classes.AdvertisedMCPScopes and leaves ConsentPath and DefaultScopes empty. In routes.go mount the OIDC groups only when OIDCEnabled; the frontend authorized-apps routes only when OIDCEnabled or the subject is user; the /oauth/mcp/requests/{request} consent routes only in user mode. Boot publishes pact.MCPAdminConsent (controllers.NewMCPAdminConsent(app, servers.MCP)) in backend mode only. Requires() stays [golem15.user] (D-08).
Harness and smoke: add bootBackendMode(t, overrides...) in harness_test.go (mcp.enabled true, mcp.subject backend, oidc.enabled false, a resource). New backend_mode_smoke_test.go TestBackendModeSmoke (Docker): register a client by DCR, authorize with PKCE and no scope → 302 to issuer + cabana.DefaultAdminPrefix + "/connect?request=…"; an administrator holding admin:read's permissions GETs {prefix}/api/v1/mcp/consent/{request} (scopes include admin:read) and POSTs allow with [admin:read] and offline_access true → redirect_uri with code; exchanging the code answers an access token and a refresh token; the published pact.MCPTokenVerifier answers Subject backend, UserID 0, BackendUserID = the administrator; the access_tokens, refresh_tokens and consents rows have user_id NULL and backend_user_id set; GET /oauth/mcp/requests/{request} and /.well-known/openid-configuration answer 404; metadata scopes_supported contains *, admin:read and offline_access; a boot with mcp.subject frontend fails. README: a "Backend-subject mode" section with the keys, routes and storage added here. Commit in ../sm-oauthserver-plugin only, staging these files by path; never stage go.work (another session's edit).
</action>
<verify>
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 600s -run 'TestBackendModeSmoke|TestMCPConsentSmoke|TestMCPStoreSmoke|TestMCPTokenVerifierSmoke|TestMCPTokenVerifier$' .</automated>
<fails_when>non-zero exit, or a line contains FAIL, or `[no tests to run]`, or `--- SKIP: TestBackendModeSmoke` appears, or TestBackendModeSmoke has no `--- PASS` line (run with -v if needed)</fails_when>
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin vet ./... && go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -short -count=1 ./...</automated>
<fails_when>non-zero exit, or a line contains FAIL</fails_when>
</verify>
<acceptance_criteria>
- config/config.yaml contains `subject: user`, `consent_path: ""` and an `oidc:` block with `enabled: true`.
- `grep -n 'oas_consents_backend_client_unique' ../sm-oauthserver-plugin/updates/202611200001_add_golem15_oauthserver_backend_subjects.go` matches and the file has a Rollback.
- `grep -n '"golem15_oauthserver_backend_grants:"' ../sm-oauthserver-plugin/classes/mcp_backend_subject.go` matches.
- `grep -n 'MCPGrantSubjectBackend' ../sm-oauthserver-plugin/classes/mcp_verifier.go` matches.
- plugin.go Requires() still returns exactly golem15.user.
- TestBackendModeSmoke passes (not skipped) with every assertion listed in the action.
- The plugin's `go test -short ./...` passes, so user-mode unit tests are unchanged.
</acceptance_criteria>
<done>In backend mode an MCP client's authorization request ends in an administrator-only grant whose rows name the administrator and no frontend user; user mode is untouched.</done>
</task>
<task type="auto">
<name>Refresh rotation and in-transaction revocation for administrator grants</name>
<reversibility rating="reversible">Internal store branches and a listener behind the plan 01 event; no new public contract.</reversibility>
<precondition>docker info exits 0; `grep -n 'type BackendAccessRevokedEvent struct' /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/cabana/admin_events.go` matches.</precondition>
<files>../sm-oauthserver-plugin/classes/mcp_store.go, ../sm-oauthserver-plugin/classes/mcp_backend_subject.go, ../sm-oauthserver-plugin/classes/backend_cascade.go, ../sm-oauthserver-plugin/plugin.go, ../sm-oauthserver-plugin/backend_revocation_smoke_test.go, ../sm-oauthserver-plugin/README.md</files>
<read_first>
../sm-oauthserver-plugin/classes/mcp_store.go (ByTokenHashForUpdate, refreshUserUsable, refreshRow, refreshRecord)
../sm-oauthserver-plugin/classes/cascade.go (Cascade, revokeUserGrants, grantRef, txOf; the revoke shape to mirror)
../sm-oauthserver-plugin/classes/subject_events.go (FireSubjectChangedAfterCommit)
../sm-oauthserver-plugin/controllers/authorizations.go (revoke: per-client revoke and its after-commit event)
../sm-oauthserver-plugin/mcp_revocation_smoke_test.go (revocation test shape)
/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/cabana/admin_events.go (event and reasons, plan 01)
</read_first>
<action>
Refresh (D-10): ByTokenHashForUpdate treats a row with user_id NULL and backend_user_id set as a backend-subject row: lockBackendGrantsShared, mark the mcpTx as backend-subject so the rotated refresh and the new access token (Create, Mint) keep user_id NULL and backend_user_id; refreshUserUsable for such a row loads cabana.BackendPrincipal and answers unusable when it is nil, errors, or the row's created_at is before principal.TokensValidAfter (issuedBeforeCutoff); refreshRecord fills UserID from BackendUserID for such a row. User rows are unchanged, ban checks included.
Revocation (D-13): in classes/mcp_backend_subject.go add exported BackendGrantRef{AdminID uint; ClientID string} and RevokeBackendGrants(ctx, tx *gorm.DB, adminIDs []uint, clientID string) ([]BackendGrantRef, error): for rows with user_id NULL and backend_user_id IN adminIDs (and client_id = clientID when non-empty) revoke the access tokens and refresh tokens the way revokeUserGrants revokes user rows, delete unused mcp_codes and the consents, and answer the distinct (admin, client) pairs touched. Add FireBackendRevokedAfterCommit(ctx, app, tx, refs) firing pact.MCPSubjectChanged{Guard: "backend", UserID: AdminID, Kind: pact.MCPSubjectRevoked, ClientID} per ref through lagoon.AfterCommit (a listener error only logs).
Listener, new classes/backend_cascade.go: BackendCascade{App *backpack.App} with OnBackendAccessRevoked(ctx, ev *cabana.BackendAccessRevokedEvent) error: nil-safe on ev and empty AdminIDs; uses ev.Tx (falls back to the app database outside a transaction, like Cascade.txOf); takes LockBackendGrants for the ids; RevokeBackendGrants with clientID ""; FireBackendRevokedAfterCommit; returns any error so the administrator save rolls back. Boot registers it with app.Events.Listen[*cabana.BackendAccessRevokedEvent](PluginID, …) only in backend mode. User rows, user-mode linked grants (rows with a user_id) and the existing userclasses listeners are not touched.
Smoke, new backend_revocation_smoke_test.go TestBackendRevocationSmoke (Docker, bootBackendMode): one administrator connects two clients with offline_access; a refresh rotation answers a new access token whose row keeps user_id NULL and backend_user_id; the administrator's own password change through PUT {prefix}/api/v1/account (current password supplied) leaves both clients' access and refresh tokens refused by the verifier and the token endpoint, deletes both backend consents, and records two MCPSubjectChanged revoked events (one per ClientID) after commit through a recording listener; deactivating a second administrator through the admin users screen revokes their grant the same way. README: refresh and revocation rules, and which administrator changes end grants (from plan 01's event). Commit by path in ../sm-oauthserver-plugin.
</action>
<verify>
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 600s -run 'TestBackendRevocationSmoke|TestBackendModeSmoke|TestMCPRevocationSmoke|TestUserDeleteCascade' .</automated>
<fails_when>non-zero exit, or a line contains FAIL, or `[no tests to run]`, or `--- SKIP: TestBackendRevocationSmoke` appears</fails_when>
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin vet ./... && go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -short -count=1 ./...</automated>
<fails_when>non-zero exit, or a line contains FAIL</fails_when>
</verify>
<acceptance_criteria>
- `grep -n 'func RevokeBackendGrants' ../sm-oauthserver-plugin/classes/mcp_backend_subject.go` and `grep -n 'OnBackendAccessRevoked' ../sm-oauthserver-plugin/classes/backend_cascade.go` match.
- plugin.go registers the BackendAccessRevokedEvent listener inside a backend-mode condition.
- TestBackendRevocationSmoke passes (not skipped), including the two per-client revoked events and the rotated backend-shaped refresh.
- Existing TestUserDeleteCascade and TestMCPRevocationSmoke still pass.
</acceptance_criteria>
<done>An administrator's agent can stay connected through refresh, and every D-13 change ends its tokens and sessions atomically with the save.</done>
</task>
<task type="auto">
<name>My account MCP connections section and the admin-wide MCP connections screen</name>
<reversibility rating="costly">The permission code golem15.oauthserver.manage_mcp_connections is stored in roles once administrators grant it; renaming it later needs a data fix.</reversibility>
<precondition>docker info exits 0; `grep -n 'type AccountItemAction struct' /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/pact/capabilities.go` matches.</precondition>
<files>../sm-oauthserver-plugin/account.go, ../sm-oauthserver-plugin/models/mcp_connection.go, ../sm-oauthserver-plugin/models/mcpconnection/columns.yaml, ../sm-oauthserver-plugin/controllers/mcp_connections.go, ../sm-oauthserver-plugin/controllers/mcpconnections/config_list.yaml, ../sm-oauthserver-plugin/controllers/admin_registry.go, ../sm-oauthserver-plugin/admin.go, ../sm-oauthserver-plugin/admin_permissions.go, ../sm-oauthserver-plugin/admin_navigation.go, ../sm-oauthserver-plugin/lang/en/lang.yaml, ../sm-oauthserver-plugin/lang/pl/lang.yaml, ../sm-oauthserver-plugin/backend_account_smoke_test.go, ../sm-oauthserver-plugin/README.md, ../sm-oauthserver-plugin/plugin.yaml</files>
<read_first>
/media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin/account_contributions.go (HasAccountContributions example: phrase prefix, Status, Danger + Confirm)
../sm-oauthserver-plugin/controllers/clients.go and controllers/clients/config_list.yaml, models/client/columns.yaml (admin controller, ListExtendQuery, YAML)
../sm-oauthserver-plugin/controllers/admin_registry.go (AdminControllers)
../sm-oauthserver-plugin/admin.go (embed list), admin_permissions.go, admin_navigation.go
../sm-oauthserver-plugin/admin_surface_test.go (must keep passing unchanged in user mode)
../sm-oauthserver-plugin/lang/en/lang.yaml and lang/pl/lang.yaml
/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/cabana/list_schema.go and query.go (relation/select columns, relationSubquery)
/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/pact/capabilities.go (AdminBulkAction, HasAdminBulkActions, ListExtendQuery)
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md (C4, C5 and the plugin copy tables)
</read_first>
<action>
My account (D-12, UI-SPEC C4), new account.go: var _ pact.HasAccountContributions = (*Plugin)(nil); AccountContributions() answers nothing in user mode and, in backend mode, one section Name mcp_connections, Label account.section, Description account.description, Status account.status with :url = the configured mcp.resource, ItemsEmpty account.empty (all golem15.oauthserver::lang.*). Items: the administrator's backend consents (user_id IS NULL AND backend_user_id = adminID) joined to clients, ordered last_used_at DESC NULLS LAST then created_at DESC; ID client_id, Title the client name or the client_id when the name is empty, Subtitle cabana.TokenScopeLabels of the granted scopes without offline_access joined with ", ", Meta [account.connected with :date YYYY-MM-DD, account.last_used with :date or account.never_used], translated with the request locale. One item action revoke: Label account.revoke, Confirm account.revoke_confirm (contains :title), Danger true; Run takes LockBackendGrants for in.AdminID on cabana.TxFromContext's transaction, RevokeBackendGrants(ctx, tx, [in.AdminID], in.ItemID), answers pact.ErrAccountItemNotFound when nothing was revoked, FireBackendRevokedAfterCommit, and answers Message account.revoked.
Admin-wide list (D-12, UI-SPEC C5): new models/mcp_connection.go, a read-only MCPConnection with TableName golem15_oauthserver_mcp_connections and fields id, backend_user_id, client_id, administrator, email, client, scopes_text, created_at, last_used_at (not added to models.Register, because it has no table of its own). New controllers/mcp_connections.go with exported MCPConnectionsControllerID = "golem15.oauthserver.mcpconnections" and PermissionManageMCPConnections = "golem15.oauthserver.manage_mcp_connections": ConfigDir controllers/mcpconnections, RequiredPermissions [PermissionManageMCPConnections], NewRecord &models.MCPConnection{}, ListExtendQuery replacing the FROM with a derived table aliased golem15_oauthserver_mcp_connections over consents with user_id IS NULL AND backend_user_id IS NOT NULL joined to backend_users (administrator = trimmed first and last name, else login; email) and LEFT JOIN clients (client = name, else client_id), scopes_text = the granted names without offline_access joined with ", ". If cabana's list cannot take the derived table, use the relation-column fallback recorded in the objective. Bulk action revoke (Label mcp_connections.revoke, Confirm mcp_connections.revoke_confirm, empty result Message so the framework's list.bulk_done shows) revokes each selected (administrator, client) pair through RevokeBackendGrants and FireBackendRevokedAfterCommit inside the action's transaction. controllers/mcpconnections/config_list.yaml per C5 (title, noRecordsMessage, recordsPerPage 20, showCheckboxes, showSetup, showSorting, defaultSort created_at desc, bulkActions [revoke], toolbar search prompt backend::lang.list.search_prompt, no toolbar buttons, no recordUrl); models/mcpconnection/columns.yaml with id (invisible), administrator, email, client (text, searchable), scopes (text), created_at and last_used_at (datetime). Add a BackendModeAdminControllers accessor in controllers and have Plugin.AdminControllers append it only in backend mode, so controllers.AdminControllers(nil) still answers exactly two controllers. Add the YAML files to admin.go's embed list.
Permission and navigation: Permissions() adds {Code: PermissionManageMCPConnections, Tab: golem15.oauthserver::lang.plugin.tab, Label: golem15.oauthserver::lang.permissions.manage_mcp_connections} in backend mode, no default role. Navigation() adds, in backend mode, a side-menu entry after clients: Code mcp_connections, Label mcp_connections.menu_label, Icon network, Permissions [PermissionManageMCPConnections], Controller MCPConnectionsControllerID. The main item keeps its label and golem15.oauthserver.* permission.
Lang en and pl: the account.* and mcp_connections.* groups and permissions.manage_mcp_connections exactly as the UI-SPEC copy tables give them. README: My account section, MCP connections screen, permission and the bulk revoke. If TestPluginManifest fails because the README summary or capabilities changed, regenerate plugin.yaml with `go -C /media/nvme/dev/golem15/summercms.io/summercms/summercms.go run ./cmd/summer plugin:manifest` run against this plugin directory (check the command's usage) and commit it.
Smoke, new backend_account_smoke_test.go TestBackendAccountSmoke (Docker, bootBackendMode): GET {prefix}/api/v1/account/contributions lists mcp_connections with one item per connected client; POST …/items/{client_id}/actions/revoke revokes only that client (the other client's token still verifies) and records one revoked event with that ClientID; a second administrator posting the first one's client_id gets 404; the mcpconnections list answers 403 without the permission and lists both administrators' connections with it, searchable by administrator; bulk revoke removes the selected rows; in user mode (bootOAuth) the contributions list has no mcp_connections section and TestAdminSurfaceHidesCredentials still passes. Commit by path.
</action>
<verify>
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 600s -run 'TestBackendAccountSmoke|TestAdminSurfaceHidesCredentials|TestClientsAdminSmoke|TestBrandingAdminSmoke|TestPluginManifest' .</automated>
<fails_when>non-zero exit, or a line contains FAIL, or `[no tests to run]`, or `--- SKIP: TestBackendAccountSmoke` appears</fails_when>
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin vet ./... && go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 900s ./...</automated>
<fails_when>non-zero exit, or a line contains FAIL</fails_when>
</verify>
<acceptance_criteria>
- `grep -n '"golem15.oauthserver.manage_mcp_connections"' ../sm-oauthserver-plugin/controllers/mcp_connections.go` matches.
- account.go declares `var _ pact.HasAccountContributions = (*Plugin)(nil)` and answers no section in user mode.
- controllers/mcpconnections/config_list.yaml has `recordsPerPage: 20` and `bulkActions`, and no `recordUrl` key.
- Both lang files contain account.section, account.revoke_confirm, mcp_connections.list_title and permissions.manage_mcp_connections.
- TestBackendAccountSmoke passes (not skipped); TestAdminSurfaceHidesCredentials passes unchanged.
- The full plugin suite (`go test ./...` with Docker) passes.
</acceptance_criteria>
<done>Administrators see and revoke their own agents on My account, and a superuser or a holder of the new permission sees and revokes everyone's; user-mode applications see no new section, screen or permission.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| cabana consent endpoint → plugin provider | The administrator id comes from cabana's authenticated principal, never from the request body |
| MCP token endpoint → store | Code and refresh lookups decide whose subject a token names |
| oas_at_ bearer → verifier | A token becomes an administrator grant |
| cabana admin saves → revocation listener | In-transaction revocation; a failure rolls the save back |
| Admin list and My account → revoke | Revoking another administrator's agent |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-32.2-13 | Elevation of privilege | store MarkIssued/Mint/Create | critical | mitigate | Backend writes leave user_id NULL (never 0 or an admin id in a users-FK column); CHECK constraints refuse a row naming no subject or user_id 0 |
| T-32.2-14 | Elevation of privilege | user consent routes in backend mode | high | mitigate | /oauth/mcp/requests/* not mounted in backend mode, so a frontend user cannot finish an administrator's pending request (Pitfall 4); smoke asserts 404 |
| T-32.2-15 | Elevation of privilege | verifier backend branch | high | mitigate | cabana.BackendPrincipal (nil for deleted/deactivated) and the tokens_valid_after cutoff on every verification and refresh; pier re-verifies every request |
| T-32.2-16 | Tampering (race) | consent allow vs revoke | medium | mitigate | Issue and revoke both run under the per-administrator backend grants advisory lock, in a namespace separate from users |
| T-32.2-17 | Repudiation / Elevation | D-13 revocation | high | mitigate | Listener revokes in the save's transaction and returns its error; MCPSubjectChanged revoked per client after commit ends sessions |
| T-32.2-18 | Elevation of privilege | My account revoke | medium | mitigate | Run scopes RevokeBackendGrants to in.AdminID; cabana already refuses unlisted items; smoke asserts the cross-admin 404 |
| T-32.2-19 | Elevation of privilege | admin-wide list and bulk revoke | medium | mitigate | RequiredPermissions manage_mcp_connections, no default role; list query restricted to backend rows |
| T-32.2-20 | Information disclosure | logs | medium | mitigate | No code, bearer, refresh token or request id in log lines; tests assert status codes and ids |
| T-32.2-21 | Denial of service | migration on existing installs | low | accept | DROP NOT NULL and NOT VALID constraints avoid table rewrites and scans; indexes are partial over backend rows, empty on user-mode installs |
| T-32.2-SC | Tampering | go module installs | low | accept | No dependency added; cabana is already a framework import of the plugin |
</threat_model>
<verification>
The three Docker smokes pass; the plugin's go vet, go test -short ./... and the full go test ./... pass; plugin.yaml matches the manifest; no go.work is staged.
</verification>
<success_criteria>
- SC-1 plugin half: backend-mode authorize → admin SPA consent → administrator-only grant; user mode unchanged (D-01, D-02, D-03, D-04, D-07, D-08).
- SC-2 plugin half: the verifier answers backend grants pier scope-limits; scopes are the cabana catalog (D-09).
- SC-3 plugin half: revocation on every D-13 change, My account revoke and the admin-wide screen (D-12, D-13).
- SC-5: plugin README.
</success_criteria>
<output>
Create `.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-03-SUMMARY.md` when done.
</output>
## Artifacts this phase produces
Plan 03 (sm-oauthserver-plugin):
- Config keys: golem15.oauthserver.mcp.subject (user|backend), golem15.oauthserver.mcp.consent_path, golem15.oauthserver.oidc.enabled; Config.MCPSubjectMode, Config.MCPConsentPath, Config.OIDCEnabled; classes.SubjectModeUser, classes.SubjectModeBackend
- Migration 202611200001_add_golem15_oauthserver_backend_subjects (new file updates/202611200001_add_golem15_oauthserver_backend_subjects.go): nullable user_id on access_tokens, refresh_tokens, consents; consents.backend_user_id; indexes oas_consents_backend_client_unique, oas_tokens_backend_client_idx, oas_refresh_backend_client_idx; constraints oas_tokens_subject_check, oas_refresh_subject_check, oas_consents_subject_check
- models.Consent.BackendUserID; new read model models.MCPConnection (models/mcp_connection.go) with models/mcpconnection/columns.yaml
- New file classes/mcp_backend_subject.go: WithBackendSubject, backendSubjectFrom, backendGrantsLockKey, lockBackendGrantsShared, LockBackendGrants, WithinBackendGrantsLock, BackendGrantRef, RevokeBackendGrants, FireBackendRevokedAfterCommit
- New file classes/backend_cascade.go: BackendCascade, OnBackendAccessRevoked
- New file controllers/mcp_admin_consent.go: MCPAdminConsent, NewMCPAdminConsent (implements pact.MCPAdminConsent)
- New file controllers/mcp_connections.go: MCPConnectionsControllerID, PermissionManageMCPConnections, BackendModeAdminControllers, bulk action revoke; controllers/mcpconnections/config_list.yaml
- New file account.go: AccountContributions (section mcp_connections, item action revoke)
- Permission golem15.oauthserver.manage_mcp_connections; navigation side-menu entry mcp_connections
- Lang keys golem15.oauthserver::lang.account.*, mcp_connections.*, permissions.manage_mcp_connections
- Test helper bootBackendMode; smoke tests TestBackendModeSmoke, TestBackendRevocationSmoke, TestBackendAccountSmoke

View File

@@ -0,0 +1,277 @@
---
phase: 32.2-mcp-oauth-with-administrator-subjects
plan: 03
subsystem: auth
tags: [mcp, oauth, wristband, cabana, sm-oauthserver-plugin, postgres, my-account, admin-list]
requires:
- phase: 32.2-01
provides: pact.MCPAdminConsent, MCPGrant.Subject backend, wristband ConsentPath/DefaultScopes, cabana TokenScopeNames/TokenScopeLabels/BackendAccessRevokedEvent, account item actions
- phase: 32.2-02
provides: admin SPA /connect screen and My account item rows
provides:
- golem15.oauthserver config keys mcp.subject (user|backend), mcp.consent_path, oidc.enabled
- migration 202611200001_add_golem15_oauthserver_backend_subjects (nullable user_id, consents.backend_user_id, partial indexes, NOT VALID subject checks)
- administrator-subject code issue, exchange, refresh rotation and verification under a separate backend grants advisory lock
- controllers.MCPAdminConsent published as pact.MCPAdminConsent in backend mode
- classes.BackendCascade on cabana.BackendAccessRevokedEvent (backend mode only), RevokeBackendGrants, FireBackendRevokedAfterCommit
- My account section mcp_connections with a revoke item action (backend mode only)
- admin-wide golem15.oauthserver.mcpconnections list, permission golem15.oauthserver.manage_mcp_connections, side-menu entry (backend mode only)
affects: [32.2-04 first consumer app wiring, 32.2-05 unit tests and release]
actuals:
tokens: 35800
tasks: 3
commits: 3
plan_head_before: 7b9899f36f45a13daccf3ec6f7d5c729ebfcc5f1
plan_head_after: 4c209c183b7806c8af2be232fb15ec475d953342
tech-stack:
added: []
patterns:
- "Per-row subject: user_id NULL plus backend_user_id marks an administrator's grant; every user-mode query already filters on user_id"
- "Backend-mode surfaces (routes, admin controller, permission, navigation, My account section, listener) are returned only when mcp.subject is backend, so user-mode apps are byte-for-byte unchanged"
- "Read-only admin list over a derived table aliased to the model's table name, so cabana's qualified search, sort and id lookups work unchanged"
key-files:
created:
- ../sm-oauthserver-plugin/updates/202611200001_add_golem15_oauthserver_backend_subjects.go
- ../sm-oauthserver-plugin/classes/mcp_backend_subject.go
- ../sm-oauthserver-plugin/classes/backend_cascade.go
- ../sm-oauthserver-plugin/controllers/mcp_admin_consent.go
- ../sm-oauthserver-plugin/controllers/mcp_connections.go
- ../sm-oauthserver-plugin/controllers/mcpconnections/config_list.yaml
- ../sm-oauthserver-plugin/models/mcp_connection.go
- ../sm-oauthserver-plugin/models/mcpconnection/columns.yaml
- ../sm-oauthserver-plugin/account.go
- ../sm-oauthserver-plugin/backend_mode_smoke_test.go
- ../sm-oauthserver-plugin/backend_revocation_smoke_test.go
- ../sm-oauthserver-plugin/backend_account_smoke_test.go
modified:
- ../sm-oauthserver-plugin/config/config.yaml
- ../sm-oauthserver-plugin/servers.go
- ../sm-oauthserver-plugin/routes.go
- ../sm-oauthserver-plugin/plugin.go
- ../sm-oauthserver-plugin/classes/mcp_store.go
- ../sm-oauthserver-plugin/classes/mcp_verifier.go
- ../sm-oauthserver-plugin/classes/lazy.go
- ../sm-oauthserver-plugin/models/consent.go
- ../sm-oauthserver-plugin/admin.go
- ../sm-oauthserver-plugin/admin_permissions.go
- ../sm-oauthserver-plugin/admin_navigation.go
- ../sm-oauthserver-plugin/lang/en/lang.yaml
- ../sm-oauthserver-plugin/lang/pl/lang.yaml
- ../sm-oauthserver-plugin/harness_test.go
- ../sm-oauthserver-plugin/admin_smoke_test.go
- ../sm-oauthserver-plugin/README.md
key-decisions:
- "The admin-wide MCP connections list uses the derived-table approach from the plan (no relation-column fallback was needed): cabana's list, count, search, sort and bulk record loading all accept it"
- "The bulk revoke is Detached: cabana's non-detached bulk path row-locks the scoped rows with FOR UPDATE, which Postgres refuses on a derived table with a LEFT JOIN and an aggregate; the action opens its own lagoon transaction and takes every selected administrator's backend grants lock first, in ascending id order"
- "A backend consent row is created with last_used_at NULL, and the verifier stamps it (at most once a minute, with the token stamp), so My account can show 'Never used' and the admin list a real last use"
- "RevokeBackendGrants takes the backend grants locks itself and counts a deleted consent as touched, so a connection whose tokens are all expired or revoked can still be revoked from My account"
- "MCPStore carries the app (set by LazyMCPStore; NewMCPStore keeps its signature) so the refresh of an administrator's grant can load cabana.BackendPrincipal; without an app such a refresh is refused"
patterns-established:
- "classes.WithBackendSubject(ctx) marks an MCP code issue as an administrator's; the store then writes user_id NULL and backend_user_id, and the exchange and every rotation keep that shape"
requirements-completed: [SC-1, SC-2, SC-3, SC-5]
coverage:
- id: D1
description: "Backend mode: an authorize request without a scope hands off to {issuer}/backend/connect?request=; an administrator sees admin:read through cabana's consent API and allows it; the code exchange answers access and refresh tokens; the verifier answers Subject backend, UserID 0, BackendUserID = the administrator; mcp_codes, access_tokens, refresh_tokens and consents rows have user_id NULL and backend_user_id set; /oauth/mcp/requests/*, OIDC discovery, JWKS, userinfo, authorize and authorized-apps routes answer 404; scopes_supported holds *, admin:read and offline_access and no read or backend; an unknown subject and backend without mcp.enabled fail boot"
requirement: SC-1
verification:
- kind: integration
ref: "../sm-oauthserver-plugin/backend_mode_smoke_test.go#TestBackendModeSmoke"
status: pass
human_judgment: false
- id: D2
description: "User mode unchanged: existing MCP consent, store, verifier, revocation, cascade, clients and branding smokes and the admin surface test pass"
requirement: SC-2
verification:
- kind: integration
ref: "../sm-oauthserver-plugin TestMCPConsentSmoke, TestMCPStoreSmoke, TestMCPTokenVerifierSmoke, TestMCPTokenVerifier, TestMCPRevocationSmoke, TestUserDeleteCascade, TestClientsAdminSmoke, TestBrandingAdminSmoke, TestAdminSurfaceHidesCredentials"
status: pass
human_judgment: false
- id: D3
description: "Refresh rotation keeps the administrator-only shape; the administrator's own password change revokes both clients' grants (verifier and token endpoint refuse them, consents deleted, one revoked event per client); deactivating another administrator on the Administrators screen revokes theirs; a frontend user's grant is untouched"
requirement: SC-3
verification:
- kind: integration
ref: "../sm-oauthserver-plugin/backend_revocation_smoke_test.go#TestBackendRevocationSmoke"
status: pass
human_judgment: false
- id: D4
description: "My account mcp_connections lists one row per connected client; revoke ends that client only (one revoked event), another administrator gets 404; the MCP connections list answers 403 without its permission, lists both administrators (name or login), searches by administrator and bulk-revokes the selected row; user mode has no section and no screen"
requirement: SC-3
verification:
- kind: integration
ref: "../sm-oauthserver-plugin/backend_account_smoke_test.go#TestBackendAccountSmoke"
status: pass
human_judgment: false
- id: D5
description: "Plugin README documents the keys, routes, scopes, storage, migration and rollback, verification, refresh, revocation, My account section, MCP connections screen and permission, and the one-subject-per-application rule; plugin.yaml still matches the manifest"
requirement: SC-5
verification:
- kind: other
ref: "../sm-oauthserver-plugin/manifest_test.go#TestPluginManifest; README review"
status: pass
human_judgment: false
duration: 22min
completed: 2026-11-21
status: complete
---
# Phase 32.2 Plan 03: sm-oauthserver-plugin backend-subject mode Summary
**An additive `mcp.subject: backend` mode of sm-oauthserver-plugin. The MCP OAuth sign-in authenticates an administrator through the admin SPA's /connect screen and cabana's consent API. The grant is stored with `user_id` NULL and `backend_user_id` set, and it verifies as an administrator-only grant. It is refreshed and revoked under its own advisory lock and revoked in the same transaction as every cabana access change. Administrators list and revoke their connections on My account, and a permission holder does the same for everyone on an admin-wide screen.**
## Performance
- **Duration:** about 22 min
- **Started:** 2026-11-21T00:03Z
- **Completed:** 2026-11-21T00:25Z
- **Tasks:** 3 of 3
- **Files modified:** 28 in ../sm-oauthserver-plugin (2205 insertions, 130 deletions)
## Accomplishments
- **Tracer (task 1).** Plain `go test` runs the whole administrator path against Postgres:
- DCR, then authorize with no scope, which hands off to `{issuer}/backend/connect?request=…`.
- cabana `GET` and `POST {api}/mcp/consent/{request}`, then the code exchange.
- `MCPVerifyToken` answers `Subject: backend`, `UserID: 0`, `BackendUserID: admin`.
- Every row has `user_id` NULL. The MCP code row was checked as well.
- **Config.**
- `mcp.subject` defaults to `user`. An unknown value fails boot. `backend` fails boot without `mcp.enabled` or together with `mcp_scopes`.
- `mcp.consent_path` defaults to `<backend.uri>/connect` in backend mode and `/connect` in user mode.
- `oidc.enabled` defaults to true. When false, discovery, JWKS, token, userinfo, authorize, resume, switch account and the redirect-mode consent JSON are not mounted, and the authorized-apps routes are mounted only in user mode.
- Backend mode never mounts `/oauth/mcp/requests/*` (Pitfall 4). `Requires()` is still `[golem15.user]`.
- **Scopes (D-09).** In backend mode, metadata, the authorize allow-list and the verifier's `MCPScopesSupported` (and through it pier's protected-resource metadata) use the same slice: `cabana.TokenScopeNames` plus `offline_access`. `DefaultScopes` is the catalog, so a client that sends no scope never falls back to `read`.
- **Storage.** One additive migration. User-mode writes are unchanged. In backend mode:
- `MarkIssued` writes `user_id` NULL and `backend_user_id` = the administrator, under `WithBackendSubject`.
- `ByCodeHashForUpdate` and `ByTokenHashForUpdate` recognise backend rows, take `golem15_oauthserver_backend_grants:<id>` shared, and report the administrator as the record's user.
- `Mint` and `Create` in such a transaction `Omit("user_id")`, so the column is never written as 0.
- **Refresh (D-10).** A rotation keeps the administrator-only shape. It is refused when `cabana.BackendPrincipal` returns nil or an error, or when the refresh token is older than `tokens_valid_after`.
- **Revocation (D-13).**
- `BackendCascade.OnBackendAccessRevoked` is registered only in backend mode. In the save's transaction it revokes the access and refresh tokens and deletes unused codes and consents.
- After the commit it fires `MCPSubjectChanged{Guard: backend, Kind: revoked, ClientID}` once per client.
- User rows and user-mode linked grants are never touched (tested with a frontend user's token on the same client).
- **My account (D-12, C4).**
- Section `mcp_connections`: the status is the connector address. Rows are ordered by `last_used_at DESC NULLS LAST`, then `created_at DESC`.
- Each row shows the client name, falling back to the client_id, the scope labels from `cabana.TokenScopeLabels` without `offline_access`, and Connected plus Last used or Never used.
- Item action `revoke`: Danger, with a Confirm naming `:title`. It runs on cabana's transaction.
- **Admin-wide screen (D-12, C5).**
- `golem15.oauthserver.mcpconnections` reads a derived table over the backend consents joined to `backend_users` and the clients.
- Columns: administrator, email, client, scopes, created_at, last_used_at. 20 per page, no toolbar buttons, no recordUrl, bulk `revoke`.
- The permission `golem15.oauthserver.manage_mcp_connections` (no default role) and the side-menu entry `mcp_connections` (icon network, after Clients) exist only in backend mode, so `controllers.AdminControllers(nil)` still returns exactly two controllers.
- **Docs and copy.** The README has a "Backend-subject mode" section plus the new config rows, routes and API reference entries. en and pl lang files have the `account.*` and `mcp_connections.*` keys and `permissions.manage_mcp_connections`, with the UI-SPEC copy.
## Task Commits
All in `../sm-oauthserver-plugin` (branch master, not pushed):
1. **Task 1 (tracer): backend-subject MCP sign-in for administrators** - `6996ffe` (feat)
2. **Task 2: refresh rotation and in-transaction revocation of administrator grants** - `9b97466` (feat)
3. **Task 3: My account MCP connections and the admin-wide MCP connections screen** - `4c209c1` (feat)
Tracer gate: auto mode is off, and human_verify_mode is end-of-phase with an automated-only `<verify>`. TestBackendModeSmoke ran again with the user-mode smokes (PASS, not skipped), so expansion continued.
## Files Created/Modified
- `config/config.yaml`, `servers.go`: the new keys, `Config.MCPSubjectMode`/`MCPConsentPath`/`OIDCEnabled`/`BackendMode()`, the backend-mode `NewServers` branch
- `routes.go`: OIDC groups gated by `oidc.enabled`, authorized apps by `oidc.enabled || user mode`, user consent JSON user mode only
- `plugin.go`: publishes `pact.MCPAdminConsent` and registers `BackendCascade` in backend mode only
- `updates/202611200001_add_golem15_oauthserver_backend_subjects.go`: the migration and its rollback (deletes backend grants first)
- `models/consent.go`: `BackendUserID *uint`. No existing field type changed.
- `classes/mcp_backend_subject.go`: `SubjectModeUser`/`SubjectModeBackend`, `WithBackendSubject`, the backend locks, `WithinBackendGrantsLock`, `BackendGrantRef`, `RevokeBackendGrants`, `FireBackendRevokedAfterCommit`
- `classes/mcp_store.go`, `classes/lazy.go`: the backend branches; `MCPStore` carries the app
- `classes/mcp_verifier.go`: `verifyBackend`, which also stamps the backend consent's last use
- `classes/backend_cascade.go`: the listener
- `controllers/mcp_admin_consent.go`: the provider
- `controllers/mcp_connections.go`, `controllers/mcpconnections/config_list.yaml`, `models/mcp_connection.go`, `models/mcpconnection/columns.yaml`: the admin-wide screen
- `account.go`, `admin.go`, `admin_permissions.go`, `admin_navigation.go`: the My account section and the backend-mode admin surface
- `lang/en/lang.yaml`, `lang/pl/lang.yaml`: copy
- `harness_test.go` (`bootBackendMode`, `adminAccount`, `adminLogin`), `admin_smoke_test.go` (`admin` now delegates to `adminAccount`), and three new smoke tests
- `README.md`
## Decisions Made
See key-decisions in the frontmatter. In addition:
- `MCPAdminConsentDecide` intersects the decision's scopes with the pending request again, as a defensive check on top of cabana's policy. It reads the pending client inside the locked transaction, before `IssueCode`.
- A verifier lookup failure (`BackendPrincipal` returns an error) answers `ErrMCPTokenInvalid`, as the plan specifies. This still fails closed.
- The admin list column is named `scopes` (the plan says `scopes_text`), so the column key in columns.yaml and the model column are the same.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 3 - Blocking] The admin-wide bulk revoke is Detached**
- **Found during:** Task 3 (design, before the first run)
- **Issue:** A non-detached cabana bulk action loads its records with `FOR UPDATE` through `ListExtendQuery`. Postgres refuses that on the derived table, because it has a LEFT JOIN and an aggregate scalar subquery.
- **Fix:** `Detached: true`. Run opens its own `lagoon.Transaction`, takes every selected administrator's backend grants lock in ascending order, revokes each pair and fires the events after commit.
- **Files modified:** `controllers/mcp_connections.go`
- **Commit:** `4c209c1`
**2. [Rule 2 - Missing functionality] Backend consent last use**
- **Found during:** Task 3
- **Issue:** Under the user-mode helper, a consent stores `last_used_at` = now at consent time, so "Never used" would never appear and the list's "Last used" would only be the consent time.
- **Fix:** Backend consents are inserted with `last_used_at` NULL. The verifier stamps it on use, inside the same once-a-minute throttle as the token stamp.
- **Files modified:** `controllers/mcp_admin_consent.go`, `classes/mcp_verifier.go`
- **Commit:** `6996ffe`
**3. [Rule 3 - Blocking] `MCPConnection` implements `Fillable` and `Rules`**
- **Found during:** Task 3
- **Issue:** cabana's `BulkAction` calls `newWritableModel`, which requires `lagoon.HasFillable` and `Rules()` on the record.
- **Fix:** Both are empty, because a connection is never edited.
- **Commit:** `4c209c1`
**4. [Test helper] `adminAccount` instead of a second copy of `admin`**
- `env.admin` now delegates to the new `adminAccount`, which also returns the id, login and password. The revocation and account smokes need them. `admin_smoke_test.go` lost two unused imports.
---
**Total deviations:** 3 auto-fixed, 1 test-helper refactor. **Impact:** no scope creep. The relation-column fallback in the objective was not needed.
## Issues Encountered
- `TestPHPMethodMap` fails in the plugin under `-short` and in the full run, before and after this plan. The PHP reference tree outside the repo gained `AuthorizeResolveUserJwtOnlyTest.php` on 2026-11-16, and its five methods are not in `php_methods.txt`. This is out of scope and logged in `deferred-items.md`. Apart from it, every plugin test passes, including the full Docker suite (`go test -count=1 ./...`).
## Known Stubs
None.
## Threat Flags
None beyond the plan's threat model. The new surfaces are:
- the admin consent provider (T-32.2-13, -14, -16)
- the verifier and refresh branches (T-32.2-15)
- the cabana listener (T-32.2-17)
- My account revoke (T-32.2-18, with the cross-admin 404 tested)
- the admin list and bulk revoke (T-32.2-19, with the 403 tested)
No code, bearer token, refresh token or request id is logged (T-32.2-20).
## Verification
- Task 1: `TestBackendModeSmoke`, `TestMCPConsentSmoke`, `TestMCPStoreSmoke`, `TestMCPTokenVerifierSmoke` and `TestMCPTokenVerifier` all PASS, none skipped.
- Task 2: `TestBackendRevocationSmoke`, `TestBackendModeSmoke`, `TestMCPRevocationSmoke` and `TestUserDeleteCascade` all PASS.
- Task 3: `TestBackendAccountSmoke`, `TestAdminSurfaceHidesCredentials` (unchanged), `TestClientsAdminSmoke`, `TestBrandingAdminSmoke` and `TestPluginManifest` all PASS. `plugin.yaml` needed no regeneration.
- Plugin `go vet ./...` is clean. Plugin `go test -short ./...` and `go test ./...` pass except the pre-existing `TestPHPMethodMap` (see Issues).
- Framework `go vet ./...` and `go test -short -count=1 ./...` pass. This plan changed nothing in the framework.
- `go.work` in the plugin (another session's edit) was never staged. Nothing was pushed or tagged.
## User Setup Required
None.
## Next Phase Readiness
- Plan 04 can mount golem15.oauthserver in the consumer app with `mcp.enabled: true`, `mcp.subject: backend`, `oidc.enabled: false` and `mcp.resource`. `mcp.consent_path` can stay empty, because it defaults to `<backend.uri>/connect`.
- Plan 05 owns the broad unit tests, the plugin release pin (the framework require is still v0.6.0 with the `replace`) and the `TestPHPMethodMap` follow-up if it wants it.
## Self-Check: PASSED
- All 12 created files exist in ../sm-oauthserver-plugin.
- Commits 6996ffe, 9b97466 and 4c209c1 are in the plugin's `git log`.

View File

@@ -0,0 +1,228 @@
---
phase: 32.2
plan: 04
type: execute
wave: 3
depends_on: [32.2-02, 32.2-03]
files_modified:
- ../sm-grzybyfunkcjonalne-app/.gitmodules
- ../sm-grzybyfunkcjonalne-app/plugins/golem15/oauthserver
- ../sm-grzybyfunkcjonalne-app/go.work
- ../sm-grzybyfunkcjonalne-app/go.mod
- ../sm-grzybyfunkcjonalne-app/go.sum
- ../sm-grzybyfunkcjonalne-app/summer.yaml
- ../sm-grzybyfunkcjonalne-app/main.go
- ../sm-grzybyfunkcjonalne-app/plugins.gen.go
- ../sm-grzybyfunkcjonalne-app/scripts/build.sh
- ../sm-grzybyfunkcjonalne-app/config/golem15.oauthserver.yaml
- ../sm-grzybyfunkcjonalne-app/config/mcp.yaml
- ../sm-grzybyfunkcjonalne-app/boot_test.go
- ../sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh
- ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-staging.conf
- ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-production.conf
- ../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh
- ../sm-grzybyfunkcjonalne-app/deploy/env.example
- ../sm-grzybyfunkcjonalne-app/DEPLOY.md
- ../sm-grzybyfunkcjonalne-app/README.md
autonomous: true
requirements: [SC-4, SC-5]
estimate:
tokens: 70000
raw_tokens: 70000
tasks: 2
confidence: low
must_haves:
truths:
- "SC-4, D-14: sm-grzybyfunkcjonalne-app mounts golem15.oauthserver (submodule plugins/golem15/oauthserver, summer.yaml, go.work use, go.mod require + replace) with config/golem15.oauthserver.yaml setting mcp.enabled true, mcp.subject backend, oidc.enabled false and a local mcp.resource equal to the /mcp resource of config/mcp.yaml; config/mcp.yaml keeps allow_personal_tokens true."
- "SC-4, D-14: on a local stack, scripts/smoke-mcp-oauth.sh completes, with no browser and no Nuxt: POST /mcp without a bearer answers 401 with resource_metadata; the protected-resource metadata lists journal and offline_access; the authorization-server metadata lists the MCP endpoints and /.well-known/openid-configuration answers 404; dynamic registration; PKCE authorize answers 302 to /gfadmin/connect?request=…; admin sign-in through POST /gfadmin/api/v1/auth/login with a cookie jar; GET and POST /gfadmin/api/v1/mcp/consent/{request}; code exchange; MCP initialize, notifications/initialized, tools/list containing journal_list_posts and tools/call journal_list_posts without isError; the same tools/list and call with a g15_ personal token; and after the administrator changes their password, the OAuth bearer answers 401."
- "SC-4, D-14: both nginx vhosts route exactly /.well-known/oauth-authorization-server (GET, HEAD) and ^~ /oauth/mcp/ (GET, POST) to the Go binary with auth_basic off and no add_header, next to the existing /mcp and protected-resource locations; scripts/check-deploy.sh requires them and the backend-mode config."
- "SC-5, D-14: DEPLOY.md's MCP section describes OAuth sign-in as an administrator (connector address, admin sign-in and consent, My account revoke, the oauthserver env keys, rollback) next to g15_ tokens, states the minimum sm-oauthserver-plugin version, and says the production deploy and the live Claude connector check happen separately on the user's go-ahead."
- "UI backstop (recorded, verified later): the SameSite=Strict admin cookie on a real cross-site connector redirect chain (D-03, RESEARCH assumption A2) cannot be proven on a localhost stack; DEPLOY.md lists the live check (add the connector in Claude, sign in, the consent card shows signed in rather than the login screen) for the deferred deploy. The phase VERIFICATION.md must list this check under human verification with status unverified (not passed, not failed), pointing at the DEPLOY.md note and the VALIDATION.md manual-only row; the local smoke passing does not close it."
artifacts:
- path: ../sm-grzybyfunkcjonalne-app/config/golem15.oauthserver.yaml
provides: "backend-mode, OIDC-off MCP authorization server config"
contains: "subject: backend"
- path: ../sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh
provides: "local end-to-end OAuth proof"
contains: "mcp/consent"
- path: ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-production.conf
provides: "OAuth locations"
contains: "location ^~ /oauth/mcp/"
key_links:
- from: ../sm-grzybyfunkcjonalne-app/config/golem15.oauthserver.yaml mcp.resource
to: ../sm-grzybyfunkcjonalne-app/config/mcp.yaml (pier resource from app.url)
via: "equal resource string; production via SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE"
pattern: "resource"
- from: ../sm-grzybyfunkcjonalne-app/go.work
to: ../sm-grzybyfunkcjonalne-app/plugins/golem15/oauthserver
via: "use ./plugins/golem15/oauthserver and go.mod replace"
pattern: "plugins/golem15/oauthserver"
---
<objective>
User story (phase goal, ROADMAP 32.2): **As an** editor of a blog-only application whose MCP tools are backend-guarded (Journal) and which has no frontend users, **I want to** add the site's `/mcp` as a connector and sign in once as my administrator account over OAuth, **so that** agents no longer need a hand-copied `g15_` personal token.
Slice in this plan (the whole story on the first consumer's local stack): a scripted MCP client runs discovery, dynamic registration, admin sign-in, consent and a Journal tool call over OAuth, and a `g15_` token keeps working (scripts/smoke-mcp-oauth.sh). The real Claude connector on a cross-site redirect is the deferred live check (see the UI backstop truth).
SC-4 and the app half of SC-5 (D-14): the first consumer, sm-grzybyfunkcjonalne-app, mounts golem15.oauthserver in backend mode with only the MCP authorization server, routes the OAuth paths to Go, proves the whole flow on a local stack and documents it.
Purpose: editors of this blog-only site sign their agent in once as their administrator instead of pasting a g15_ token; g15_ tokens keep working.
Output: submodule and module wiring, the regenerated main.go and plugins.gen.go, the oauthserver config, a local proof script, nginx locations, the extended check-deploy.sh, env example and DEPLOY.md. The production deploy and a live Claude connector run are not part of this phase (CONTEXT Deferred).
⚠ spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
Submodule rule (CLAUDE.md, memory): the app may only point at plugin commits that are pushed, and the pointer bump to the release is its own commit after the plugin push (plan 05). So this plan adds the submodule at the commit origin/master already has, commits the wiring with that gitlink, and then moves only the submodule's working tree to the local plan 03 commits (fetched from the sibling checkout) for the proof, leaving that gitlink change uncommitted for plan 05. The SC-4 "Claude connector" wording is met by a scripted MCP client locally; the connector itself is the deferred live check.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-CONTEXT.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-RESEARCH.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-03-SUMMARY.md
@../sm-grzybyfunkcjonalne-app/summer.yaml
@../sm-grzybyfunkcjonalne-app/go.work
@../sm-grzybyfunkcjonalne-app/config/mcp.yaml
@../sm-grzybyfunkcjonalne-app/config/backend.yaml
@../sm-grzybyfunkcjonalne-app/scripts/build.sh
@../sm-grzybyfunkcjonalne-app/scripts/smoke.sh
@../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh
@../sm-grzybyfunkcjonalne-app/DEPLOY.md
@../sm-bm-app/config/golem15.oauthserver.yaml
<interfaces>
- golem15.oauthserver keys from plan 03: mcp.enabled, mcp.resource, mcp.subject (user|backend), mcp.consent_path (empty: <backend.uri>/connect in backend mode), oidc.enabled (default true); env SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE etc.
- Backend-mode routes: GET /.well-known/oauth-authorization-server, GET /oauth/mcp/authorize, POST /oauth/mcp/register, POST /oauth/mcp/token; pier: /mcp, /.well-known/oauth-protected-resource[/mcp]; cabana: {/gfadmin}/api/v1/auth/login (cookie set only with X-Requested-With), {/gfadmin}/api/v1/mcp/consent/{request} GET/POST, PUT {/gfadmin}/api/v1/account (password change)
- Journal token scopes: journal, journal:read; cabana scopes *, admin:read
- grzyby today: config/backend.yaml uri /gfadmin; config/mcp.yaml enabled, path /mcp, allow_personal_tokens true; summer.yaml build.tags [summercms_mcp, nodynamic]; nginx upstream 127.0.0.1:8096; a location ~ /\. dotfile rule answers 404 for unlisted /.well-known paths; scripts/check-deploy.sh fails on any add_header inside a location
- scripts/smoke.sh: throwaway database from SMOKE_ADMIN_DSN or a postgres:15 container, run migrate and admin:create (password on stdin), SUMMER_APP__URL=http://127.0.0.1:$GO_PORT
</interfaces>
</context>
<tasks>
<task type="tracer">
<name>Tracer: mount the OAuth server in backend mode and prove discovery → registration → admin sign-in → consent → Journal tool call locally</name>
<reversibility rating="reversible">App wiring and config; turning SUMMER_GOLEM15__OAUTHSERVER__MCP__ENABLED off or removing the plugin entry restores today's g15_-only MCP.</reversibility>
<precondition>docker info exits 0 (or SMOKE_ADMIN_DSN is set); 32.2-02-SUMMARY.md and 32.2-03-SUMMARY.md exist; `git -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin log --oneline -1` is a plan 03 commit; `git -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin status -sb` shows master tracking origin/master.</precondition>
<files>../sm-grzybyfunkcjonalne-app/.gitmodules, ../sm-grzybyfunkcjonalne-app/plugins/golem15/oauthserver, ../sm-grzybyfunkcjonalne-app/go.work, ../sm-grzybyfunkcjonalne-app/go.mod, ../sm-grzybyfunkcjonalne-app/go.sum, ../sm-grzybyfunkcjonalne-app/summer.yaml, ../sm-grzybyfunkcjonalne-app/main.go, ../sm-grzybyfunkcjonalne-app/plugins.gen.go, ../sm-grzybyfunkcjonalne-app/scripts/build.sh, ../sm-grzybyfunkcjonalne-app/config/golem15.oauthserver.yaml, ../sm-grzybyfunkcjonalne-app/config/mcp.yaml, ../sm-grzybyfunkcjonalne-app/boot_test.go, ../sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh, ../sm-grzybyfunkcjonalne-app/README.md</files>
<read_first>
../sm-grzybyfunkcjonalne-app/.gitmodules (entry style: path, url git@git.golem15.com:golem15/<repo>.git, branch)
../sm-grzybyfunkcjonalne-app/go.work and go.mod (use list, require block, replace lines 192-206)
../sm-grzybyfunkcjonalne-app/summer.yaml (plugins list)
../sm-grzybyfunkcjonalne-app/scripts/build.sh (PLUGINS array; summer build drift check)
../sm-grzybyfunkcjonalne-app/scripts/smoke.sh (database setup lines 97-120 and 239-300, admin:create, serve and fail helpers)
../sm-grzybyfunkcjonalne-app/boot_test.go (TestBootUserTranslateJournal plugin lists at lines 38-66)
../sm-grzybyfunkcjonalne-app/config/mcp.yaml and config/backend.yaml
../sm-bm-app/config/golem15.oauthserver.yaml (header comment style)
../sm-oauthserver-plugin/README.md (backend-mode section from plan 03)
../sm-grzybyfunkcjonalne-app/README.md (plugin table)
</read_first>
<action>
Wiring (D-14): from ../sm-grzybyfunkcjonalne-app, git submodule add -b master git@git.golem15.com:golem15/sm-oauthserver-plugin.git plugins/golem15/oauthserver (it checks out the commit origin/master already has; do not push anything). Add ./plugins/golem15/oauthserver to go.work use; add git.golem15.com/golem15/sm-oauthserver-plugin to go.mod's require at the latest pushed tag and a replace to ./plugins/golem15/oauthserver next to the other plugin replaces; go mod tidy so go.sum is complete. Add - id: golem15.oauthserver with module git.golem15.com/golem15/sm-oauthserver-plugin to summer.yaml and the submodule path to the PLUGINS array of scripts/build.sh. Regenerate main.go and plugins.gen.go with summer build (install the CLI with GOBIN=<scratch dir> go -C /media/nvme/dev/golem15/summercms.io/summercms/summercms.go install ./cmd/summer, then run that binary's build from the app root). Add golem15.oauthserver to both plugin lists of boot_test.go. README.md: the plugin table names the oauthserver submodule and what it serves.
Config: new config/golem15.oauthserver.yaml with a header comment in the style of sm-bm-app's (what it serves, env overrides SUMMER_GOLEM15__OAUTHSERVER__<KEY>, no secret here, signing keys generated in the database), oidc.enabled false, mcp.enabled true, mcp.subject backend, consent_path left unset (defaults to /gfadmin/connect from backend.uri), and mcp.resource http://127.0.0.1:8096/mcp as the local default with a comment that production sets SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE and that it must equal the pier resource (<app.url>/mcp). config/mcp.yaml: change only its comments (OAuth sign-in as an administrator now exists next to personal tokens); keep the three lines enabled: true, path: /mcp and allow_personal_tokens: true exactly as they are (check-deploy.sh matches them).
Commit, in ../sm-grzybyfunkcjonalne-app only, staging these paths explicitly (.gitmodules, the plugins/golem15/oauthserver gitlink at the pushed commit, go.work, go.mod, go.sum, summer.yaml, main.go, plugins.gen.go, scripts/build.sh, config/golem15.oauthserver.yaml, config/mcp.yaml, boot_test.go, README.md). Then move only the submodule's working tree to the local plan 03 commits: git -C plugins/golem15/oauthserver fetch /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin master and check out FETCH_HEAD detached. Do not commit that gitlink change; plan 05 commits the release pointer after the plugin push. Leave the untracked .agents/, .gsd/, docs/ and sm-grzybyfunkcjonalne-app entries alone.
Proof script, new executable scripts/smoke-mcp-oauth.sh (bash, set -euo pipefail, curl, jq, openssl, psql; no new dependency), header comment in the style of scripts/smoke.sh: build the Go binary into a temp dir with go build -tags summercms_mcp,nodynamic (no Nuxt), create a throwaway database exactly like smoke.sh (SMOKE_ADMIN_DSN or a postgres:15 container, dropped on exit), run migrate, create a superuser administrator with a random password on stdin and a g15_ token with scope journal (the binary's admin:token:create command), serve on SMOKE_GO_PORT (default 18097) with SUMMER_APP__URL and SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE set to that port. Then, failing with a clear message at each step: 1) POST /mcp without bearer → 401 and a resource_metadata parameter; 2) GET /.well-known/oauth-protected-resource/mcp → authorization_servers and scopes_supported containing journal and offline_access; 3) GET /.well-known/oauth-authorization-server → authorization, registration and token endpoints under /oauth/mcp/, and GET /.well-known/openid-configuration → 404; 4) POST /oauth/mcp/register with redirect http://127.0.0.1:<port>/cb and token_endpoint_auth_method none; 5) PKCE verifier and S256 challenge with openssl; 6) GET /oauth/mcp/authorize with scope "journal offline_access" and resource → 302 whose Location is <app.url>/gfadmin/connect?request=<id>; 7) POST /gfadmin/api/v1/auth/login with X-Requested-With: XMLHttpRequest and a curl cookie jar; 8) GET /gfadmin/api/v1/mcp/consent/<id> (jar, X-Requested-With) shows journal; POST allow with scopes [journal] and offline_access true → redirect_uri with code and iss; 9) POST /oauth/mcp/token (code, verifier, redirect_uri, client_id, resource) → an access token and a refresh token; 10) MCP initialize, notifications/initialized, tools/list containing journal_list_posts, tools/call journal_list_posts with isError false; 11) the same tools/list and call with the g15_ token; 12) PUT /gfadmin/api/v1/account changing the administrator's password (jar, X-Requested-With) → a following tools/list with the OAuth bearer answers 401. Never echo tokens, codes or the password; print step names and status codes only. Commit the script by path.
</action>
<verify>
<automated>bash /media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh</automated>
<fails_when>non-zero exit, or the output lacks the final step-12 success line, or any step line reports an unexpected status code</fails_when>
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app vet -tags summercms_mcp,nodynamic ./... && go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app test -count=1 -tags summercms_mcp,nodynamic ./...</automated>
<fails_when>non-zero exit, or a line contains FAIL</fails_when>
</verify>
<acceptance_criteria>
- .gitmodules has a plugins/golem15/oauthserver entry with url git@git.golem15.com:golem15/sm-oauthserver-plugin.git; the committed gitlink equals a commit that `git -C ../sm-oauthserver-plugin branch -r --contains <gitlink>` lists on origin/master.
- summer.yaml lists golem15.oauthserver; go.work uses ./plugins/golem15/oauthserver; go.mod has the replace.
- config/golem15.oauthserver.yaml contains `subject: backend` and an oidc block with `enabled: false`; config/mcp.yaml still contains the exact lines `enabled: true`, `path: /mcp`, `allow_personal_tokens: true`.
- `git -C ../sm-grzybyfunkcjonalne-app status --porcelain -- main.go plugins.gen.go` is empty after summer build.
- scripts/smoke-mcp-oauth.sh exits 0 with all twelve steps passing; piping its output through `grep -E 'oas_at_[A-Za-z0-9]|g15_[A-Za-z0-9]{8,}|code=[A-Za-z0-9]'` prints nothing.
- The app's vet and tagged tests pass (boot test includes golem15.oauthserver).
</acceptance_criteria>
<done>The site's MCP endpoint accepts an OAuth agent signed in as an administrator, locally, end to end, and g15_ tokens still work.</done>
</task>
<task type="auto">
<name>Proxy the OAuth paths to Go, guard them in check-deploy.sh, and document the deploy</name>
<reversibility rating="reversible">nginx locations and docs; removing the two locations sends the paths back to the dotfile rule and Nuxt.</reversibility>
<files>../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-staging.conf, ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-production.conf, ../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh, ../sm-grzybyfunkcjonalne-app/deploy/env.example, ../sm-grzybyfunkcjonalne-app/DEPLOY.md</files>
<read_first>
../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-staging.conf (lines 82-130 server headers and /gfadmin, 170-225 /mcp and protected-resource locations, 250-260 dotfile rule)
../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-production.conf (same locations; keep in step)
../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh (header list, location checks at lines 230-320, config checks at lines 350-370)
../sm-grzybyfunkcjonalne-app/deploy/env.example
../sm-grzybyfunkcjonalne-app/DEPLOY.md (MCP section at line 411, Security headers at line 229, Release at line 249, Rollback)
../sm-bm-app/deploy/nginx/bm.jakubzych.com.conf (lines 97-110, an OAuth-enabled vhost)
</read_first>
<action>
nginx (D-14), both vhosts, next to the existing /mcp and protected-resource locations and with the same proxy headers they use: location = /.well-known/oauth-authorization-server (auth_basic off on staging, limit_except GET HEAD { deny all; }, proxy_pass http://127.0.0.1:8096) and location ^~ /oauth/mcp/ (auth_basic off on staging, limit_except GET POST { deny all; }, client_max_body_size 64k, proxy_pass http://127.0.0.1:8096). Exact and prefix locations keep the dotfile rule and Nuxt away from them. No add_header inside either (server-level security headers keep applying). Comment each with why (the connector fetches metadata, registers and exchanges tokens server-to-server; the browser leg of /oauth/mcp/authorize hands off to /gfadmin/connect, which /gfadmin already proxies). Do not add /.well-known/openid-configuration (OIDC is off; the dotfile rule answers 404).
check-deploy.sh: extend the header comment and the checks so each vhost must have both new locations with the method limits above and no add_header, config/golem15.oauthserver.yaml must contain subject: backend and the oidc enabled: false block, and summer.yaml must list golem15.oauthserver. Keep every existing check.
deploy/env.example: add SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE=https://<host>/mcp with a comment that it must equal <SUMMER_APP__URL>/mcp.
DEPLOY.md (SC-5): rewrite the MCP section's Auth paragraph: agents connect over OAuth as an administrator (connector address <site>/mcp; the browser signs in at /gfadmin with the usual login gates and shows the consent card; scopes are the g15_ token scopes; Stay connected gives a refresh token; each administrator revokes agents on My account and a superuser or a holder of golem15.oauthserver.manage_mcp_connections on the OAuth server's MCP connections screen; deleting, deactivating or re-passwording an administrator, or changing their role or permissions, ends their agents), and g15_ personal tokens keep working. Add the oauthserver env key, the nginx locations, the migration note (migrate creates the golem15_oauthserver_* tables on the first run), the minimum sm-oauthserver-plugin version (the release plan 05 tags; write it as "the plugin release that adds mcp.subject"), scripts/smoke-mcp-oauth.sh as the local check, and rollback (SUMMER_GOLEM15__OAUTHSERVER__MCP__ENABLED=false and a Go restart; g15_ tokens keep working). Add a "Live connector check (deferred)" note: after the production deploy, on the user's go-ahead, add the connector in Claude and sign in; the consent card must show the signed-in administrator, not the login screen, after the cross-site redirect (SameSite=Strict cookie; not provable on localhost). Commit these files by path in the app repo.
</action>
<verify>
<automated>bash /media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh</automated>
<fails_when>non-zero exit, or a line starting with `check-deploy:` reports a failure, or nginx -t output contains `emerg`</fails_when>
</verify>
<acceptance_criteria>
- `grep -c 'location = /.well-known/oauth-authorization-server' ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-staging.conf` and the same for the production vhost are 1; `grep -c 'location ^~ /oauth/mcp/'` is 1 in each.
- check-deploy.sh passes and names the new locations in its header comment.
- DEPLOY.md's MCP section mentions /gfadmin/connect, My account, golem15.oauthserver.manage_mcp_connections, SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE, scripts/smoke-mcp-oauth.sh and the deferred live connector check.
- deploy/env.example contains SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE.
</acceptance_criteria>
<done>The deployed site will route the OAuth paths to Go, the deploy checker guards them, and DEPLOY.md tells the operator how to run, check and roll back administrator OAuth.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| Internet → nginx → Go | New public OAuth endpoints on a site that had none |
| Local proof script → logs | Tokens, codes and a password exist during the run |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-32.2-22 | Elevation of privilege | OIDC provider surface | medium | mitigate | oidc.enabled false in config/golem15.oauthserver.yaml and no nginx location for OIDC paths; the smoke asserts /.well-known/openid-configuration is 404 |
| T-32.2-23 | Denial of service | /oauth/mcp/register and /token | medium | mitigate | Plugin throttles (BucketMCPRegister, BucketMCPToken) and the DCR client cap stay on; nginx limits methods and body size (64k) |
| T-32.2-24 | Information disclosure | smoke-mcp-oauth.sh output | medium | mitigate | Print step names and status codes only; acceptance checks the output for oas_at_, g15_ and code= values |
| T-32.2-25 | Tampering | security headers | low | mitigate | No add_header in the new locations, so server-level headers apply; check-deploy.sh enforces it |
| T-32.2-SC | Tampering | go module installs | low | accept | Only the first-party sm-oauthserver-plugin is added, as a submodule of the organisation's repository |
</threat_model>
<verification>
scripts/smoke-mcp-oauth.sh passes all twelve steps; the app's go vet and tagged go test pass; scripts/check-deploy.sh passes; summer build leaves main.go and plugins.gen.go unchanged.
Human verification, open after this phase (unverified, not a failure): the D-03 SameSite=Strict cookie on a real cross-site connector redirect chain (RESEARCH A2). The local stack is same-site, so the smoke cannot prove it. It stays open until the live connector check in DEPLOY.md runs after the deferred production deploy, and VERIFICATION.md lists it as such.
</verification>
<success_criteria>
- SC-4: local proof of discovery, registration, administrator sign-in, consent and a Journal tool call over OAuth, with g15_ tokens still working (D-14).
- SC-5: DEPLOY.md, env example and check-deploy updated; production deploy explicitly deferred.
</success_criteria>
<output>
Create `.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-04-SUMMARY.md` when done.
</output>
## Artifacts this phase produces
Plan 04 (sm-grzybyfunkcjonalne-app):
- Submodule plugins/golem15/oauthserver (.gitmodules entry, gitlink at the pushed origin/master commit; working tree at the local plan 03 commits, uncommitted)
- summer.yaml plugin entry golem15.oauthserver; go.work use ./plugins/golem15/oauthserver; go.mod require + replace git.golem15.com/golem15/sm-oauthserver-plugin => ./plugins/golem15/oauthserver; regenerated main.go and plugins.gen.go; scripts/build.sh PLUGINS entry
- New file config/golem15.oauthserver.yaml (oidc.enabled false, mcp.enabled true, mcp.subject backend, mcp.resource local default)
- New file scripts/smoke-mcp-oauth.sh (twelve-step local OAuth proof, env SMOKE_ADMIN_DSN, SMOKE_GO_PORT)
- nginx locations `= /.well-known/oauth-authorization-server` and `^~ /oauth/mcp/` in both vhosts; check-deploy.sh checks for them and for the backend-mode config
- deploy/env.example key SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE; DEPLOY.md MCP section with the deferred live connector check

View File

@@ -0,0 +1,265 @@
---
phase: 32.2-mcp-oauth-with-administrator-subjects
plan: 04
subsystem: auth
tags: [mcp, oauth, sm-oauthserver-plugin, sm-grzybyfunkcjonalne-app, nginx, deploy, smoke]
requires:
- phase: 32.2-01
provides: pact.MCPAdminConsent, cabana GET/POST {api}/mcp/consent/{request}, BackendAccessRevokedEvent on password change
- phase: 32.2-02
provides: admin SPA /connect screen and My account item rows
- phase: 32.2-03
provides: sm-oauthserver-plugin mcp.subject backend, mcp.consent_path, oidc.enabled (local commits 6996ffe, 9b97466, 4c209c1)
provides:
- sm-grzybyfunkcjonalne-app mounts golem15.oauthserver (submodule plugins/golem15/oauthserver, go.work use, go.mod require v0.1.7 + replace, summer.yaml, build.sh)
- config/golem15.oauthserver.yaml in backend mode with oidc off and a local mcp.resource
- scripts/smoke-mcp-oauth.sh, a twelve-step local proof of administrator OAuth sign-in with no browser and no Nuxt
- nginx locations = /.well-known/oauth-authorization-server and ^~ /oauth/mcp/ in both vhosts, guarded by check-deploy.sh
- DEPLOY.md MCP section for administrator OAuth, env.example key, deferred live connector check
affects: [32.2-05 plugin release and app pointer bump, phase 32.2 VERIFICATION human-verification list]
actuals:
tokens: 11079
tasks: 2
commits: 3
plan_head_before: c06a2d8cd92e49318f83ee97d6aa2d2f7ecbdde4
plan_head_after: df554d5e3df8348d92f3e50487b2c5567424209c
tech-stack:
added: []
patterns:
- "Scripted MCP OAuth client in bash (curl, jq, openssl): secrets travel in header files and @file form fields, output is step names and status codes only"
- "Committed gitlink at the pushed plugin commit, working tree on unpushed local commits for the proof; the pointer bump is a later commit"
key-files:
created:
- ../sm-grzybyfunkcjonalne-app/config/golem15.oauthserver.yaml
- ../sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh
- ../sm-grzybyfunkcjonalne-app/plugins/golem15/oauthserver (submodule)
modified:
- ../sm-grzybyfunkcjonalne-app/.gitmodules
- ../sm-grzybyfunkcjonalne-app/go.work
- ../sm-grzybyfunkcjonalne-app/go.mod
- ../sm-grzybyfunkcjonalne-app/go.sum
- ../sm-grzybyfunkcjonalne-app/summer.yaml
- ../sm-grzybyfunkcjonalne-app/plugins.gen.go
- ../sm-grzybyfunkcjonalne-app/scripts/build.sh
- ../sm-grzybyfunkcjonalne-app/config/mcp.yaml
- ../sm-grzybyfunkcjonalne-app/boot_test.go
- ../sm-grzybyfunkcjonalne-app/README.md
- ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-staging.conf
- ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-production.conf
- ../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh
- ../sm-grzybyfunkcjonalne-app/deploy/env.example
- ../sm-grzybyfunkcjonalne-app/DEPLOY.md
key-decisions:
- "Rollback of the OAuth sign-in sets both SUMMER_GOLEM15__OAUTHSERVER__MCP__ENABLED=false and SUMMER_GOLEM15__OAUTHSERVER__MCP__SUBJECT=user: the plan's single key fails boot (mcp.subject backend needs mcp.enabled), verified with route:list"
- "go.mod requires sm-oauthserver-plugin v0.1.7 (the latest pushed tag, equal to the committed gitlink); plan 05 bumps require, gitlink and plugins.gen.go to the new release together"
- "The boot test asserts the backend-mode route set (MCP OAuth routes mounted; /.well-known/openid-configuration, /oauth/jwks, /oauth/authorize, /oauth/token and /oauth/mcp/requests/* absent) and sets golem15.oauthserver.mcp.resource to <app.url>/mcp like pier's"
- "env.example carries the concrete UAT value of SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE and the production value in its production block, in the file's existing style, instead of a <host> placeholder"
patterns-established:
- "check-deploy.sh parses config/golem15.oauthserver.yaml by top-level block and refuses any OpenID Connect nginx location"
requirements-completed: [SC-4, SC-5]
coverage:
- id: D1
description: "sm-grzybyfunkcjonalne-app mounts golem15.oauthserver in backend mode with oidc off: submodule, go.work, go.mod require + replace, summer.yaml, build.sh, regenerated plugins.gen.go; config/mcp.yaml keeps enabled, path and allow_personal_tokens; the boot test activates nine plugins, checks the gitlink and the backend-mode route set"
requirement: SC-4
verification:
- kind: integration
ref: "go -C ../sm-grzybyfunkcjonalne-app test -count=1 -tags summercms_mcp,nodynamic ./... (TestBootUserTranslateJournal, TestCompanionsHost with Docker)"
status: pass
- kind: other
ref: "summer build at the committed gitlink 7b9899f leaves main.go and plugins.gen.go unchanged"
status: pass
human_judgment: false
- id: D2
description: "Local end-to-end proof: 401 with resource_metadata, protected-resource and authorization-server metadata, openid-configuration 404, dynamic registration, PKCE authorize 302 to /gfadmin/connect?request=, admin cookie sign-in, consent GET/POST, code exchange with refresh token, MCP initialize, notifications/initialized, tools/list and tools/call journal_list_posts over OAuth and with a g15_ token, and 401 for the OAuth bearer after a password change"
requirement: SC-4
verification:
- kind: e2e
ref: "bash ../sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh (ends 'smoke-mcp-oauth: ok (12 steps)'; output has no oas_at_, g15_ or code= values)"
status: pass
human_judgment: false
- id: D3
description: "Both nginx vhosts route exactly /.well-known/oauth-authorization-server (GET, HEAD) and ^~ /oauth/mcp/ (GET, POST, 64k) to Go with auth_basic off on staging and no add_header; check-deploy.sh requires them, the backend-mode config and the summer.yaml entry, and refuses an OpenID Connect location"
requirement: SC-4
verification:
- kind: automated_ui
ref: "bash ../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh (nginx -t both vhosts; 'check-deploy: ok') plus seven mutants on a scratch copy, all caught"
status: pass
human_judgment: false
- id: D4
description: "DEPLOY.md MCP section: OAuth sign-in as an administrator next to g15_ tokens (connector address, /gfadmin/connect sign-in and consent, Stay connected, My account revoke, manage_mcp_connections screen, what ends an administrator's agents), config and env key, minimum plugin release, migration, nginx, local smoke, rollback, and the deferred live connector check; env.example key"
requirement: SC-5
verification:
- kind: other
ref: "grep of DEPLOY.md for /gfadmin/connect, My account, golem15.oauthserver.manage_mcp_connections, SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE, scripts/smoke-mcp-oauth.sh, Live connector check (deferred); env.example contains the key"
status: pass
human_judgment: false
- id: D5
description: "Live connector check: on a real cross-site redirect from Claude the SameSite=Strict admin cookie still reaches /gfadmin/connect, so the consent card shows the signed-in administrator rather than the login screen (D-03, RESEARCH A2)"
requirement: SC-4
verification: []
human_judgment: true
rationale: "A localhost stack is same-site and cannot reproduce the cross-site redirect chain; it needs the deferred production deploy on the user's go-ahead (DEPLOY.md 'Live connector check (deferred)', VALIDATION.md manual-only row). Status unverified, not passed and not failed."
duration: 20min
completed: 2026-11-21
status: complete
---
# Phase 32.2 Plan 04: first consumer mounts administrator MCP OAuth Summary
**sm-grzybyfunkcjonalne-app now mounts sm-oauthserver-plugin as a backend-mode, OIDC-off MCP authorization server. A scripted MCP client proves the whole administrator sign-in locally in twelve steps: discovery, registration, PKCE, /gfadmin/connect consent, code exchange and a Journal tool call. `g15_` tokens keep working, and a password change ends the OAuth grant. Both vhosts route the two OAuth paths to Go, check-deploy guards them, and DEPLOY.md documents operation, rollback and the deferred live connector check.**
## Performance
- **Duration:** about 20 min
- **Started:** 2026-11-21T00:18Z
- **Completed:** 2026-11-21T00:39Z
- **Tasks:** 2 of 2
- **Files modified:** 18 in ../sm-grzybyfunkcjonalne-app (752 insertions, 49 deletions)
## Accomplishments
- **Wiring (task 1).**
- `git submodule add -b master` created `plugins/golem15/oauthserver`. Its committed gitlink is `7b9899f`, which is v0.1.7 and equals `origin/master` (`git branch -r --contains 7b9899f` lists `origin/master`).
- Added `use ./plugins/golem15/oauthserver` to go.work. go.mod requires `v0.1.7` and has a `replace` to the submodule. `go mod tidy` filled go.sum.
- summer.yaml lists `golem15.oauthserver` (after `golem15.faq`), and the build.sh `PLUGINS` array has the submodule.
- `summer build` regenerated plugins.gen.go. main.go is unchanged.
- **Config.**
- New `config/golem15.oauthserver.yaml` sets `oidc.enabled: false`, `mcp.enabled: true`, `mcp.subject: backend` and `mcp.resource: http://127.0.0.1:8096/mcp`. Comments cover the env override and the equality with `<app.url>/mcp`. `consent_path` is unset.
- In config/mcp.yaml only the comments changed. The three lines check-deploy matches are untouched.
- **Boot test.**
- Nine plugins, with golem15.oauthserver in both lists and a gitlink check.
- A new `assertMCPOAuthRoutes` checks that the four MCP OAuth routes are mounted and the OIDC and user-mode consent routes are not.
- The test sets the oauthserver resource to `<app.url>/mcp`, so pier's resource-mismatch warning is gone.
- **Proof (task 1).** `scripts/smoke-mcp-oauth.sh` runs as follows:
- It builds with `-tags summercms_mcp,nodynamic`, creates a throwaway database (`SMOKE_ADMIN_DSN` or a postgres:15 container, dropped on exit) and migrates it.
- It creates a superuser with a random password on stdin and a `g15_` token (scope `journal`), then serves on `SMOKE_GO_PORT` (default 18097).
- It passes all twelve steps. Access, refresh and personal tokens, the code and the passwords never reach a command line or the output.
- **Proxy (task 2).**
- Both vhosts now have `location = /.well-known/oauth-authorization-server` (`limit_except GET HEAD`) and `location ^~ /oauth/mcp/` (`limit_except GET POST`, `client_max_body_size 64k`). Each sends the same proxy headers as the `/mcp` locations, and staging adds `auth_basic off`. There is no `add_header` and no OIDC location.
- The `/mcp` comments now name OAuth access tokens next to `g15_` tokens.
- **check-deploy.sh.**
- New header bullet.
- Both new locations are required, with exact method limits, the body cap and the staging gate-off.
- Any OpenID Connect location is refused.
- The oauthserver config must have `mcp.enabled: true`, `mcp.subject: backend` and `oidc.enabled: false`, and summer.yaml must list the plugin.
- Every existing check is kept.
- **Docs.**
- `deploy/env.example` gained `SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE`, with the UAT value and the production value.
- The DEPLOY.md MCP section was rewritten. Auth now covers both ways, then come OAuth server config, plugin version and migration, nginx, Check (with the local smoke), the deferred live connector check, and the corrected rollback.
- README.md has the plugin in the overview, a layout row for the submodule, and the new script.
## Task Commits
All in `../sm-grzybyfunkcjonalne-app` (branch master, not pushed):
1. **Task 1 (tracer): mount golem15.oauthserver as the MCP authorization server for administrators** - `2953bf8` (feat)
2. **Task 1 (tracer): local end-to-end proof of administrator OAuth sign-in** - `f2dc85d` (test)
3. **Task 2: route the MCP OAuth paths to Go and document administrator sign-in** - `df554d5` (deploy)
Tracer gate: auto mode is off. human_verify_mode is end-of-phase (the default) and `<verify>` is automated-only. The smoke and the tagged app tests ran again and passed before task 2, so expansion continued.
## Files Created/Modified
- `.gitmodules`, `plugins/golem15/oauthserver`: the submodule entry (url `git@git.golem15.com:golem15/sm-oauthserver-plugin.git`, branch master) and the gitlink at 7b9899f
- `go.work`, `go.mod`, `go.sum`: the workspace use, the require and replace, and the tidied sums
- `summer.yaml`, `plugins.gen.go`, `scripts/build.sh`: the plugin entry, the generated registration, and the plugin dir for the build check
- `config/golem15.oauthserver.yaml`: the backend-mode config (new)
- `config/mcp.yaml`: comments only
- `boot_test.go`: the plugin lists, the gitlink check, `assertMCPOAuthRoutes` and the resource alignment
- `scripts/smoke-mcp-oauth.sh`: the twelve-step proof (new, executable)
- `deploy/nginx/grzybyfunkcjonalne-{staging,production}.conf`: the two locations and the `/mcp` comment
- `scripts/check-deploy.sh`: the new checks
- `deploy/env.example`, `DEPLOY.md`, `README.md`: the docs
## Decisions Made
See key-decisions in the frontmatter. In addition:
- Regenerating plugins.gen.go also refreshed two stale values: golem15.user `v0.1.19` became `v0.1.21` (the previous commit bumped the user pointer without regenerating), and `FrameworkVersion` `v0.6.1` became `v0.6.6`, the framework checkout's base tag. Without the regeneration, build.sh's drift check would fail.
- The smoke script's steps 8 and 12 send `X-Requested-With: XMLHttpRequest` with the cookie jar, the same as the SPA. The account PUT sends the email as well, because cabana requires it. Step 12 calls `tools/list` without a session id, so the 401 comes from the bearer check and not from session handling.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 1 - Bug] The documented rollback would not boot**
- **Found during:** Task 2 (DEPLOY.md rollback)
- **Issue:** The plan's rollback, `SUMMER_GOLEM15__OAUTHSERVER__MCP__ENABLED=false` alone, fails boot with `golem15.oauthserver: mcp.subject backend needs mcp.enabled`. This was checked with `route:list` on the built binary.
- **Fix:** DEPLOY.md also sets `SUMMER_GOLEM15__OAUTHSERVER__MCP__SUBJECT=user`. That boots with no MCP OAuth routes. The only plugin routes left are the user-mode `/oauth/authorizations` ones, which have no nginx location.
- **Files modified:** `DEPLOY.md`
- **Commit:** `df554d5`
**2. [Rule 2 - Missing check] Boot test asserts the backend-mode route set**
- **Found during:** Task 1
- **Issue:** The plan only added the plugin to the boot test's lists. Nothing in the Go tests would notice the plugin booting in user mode or with OIDC on.
- **Fix:** Added `assertMCPOAuthRoutes`, and aligned `golem15.oauthserver.mcp.resource` with the test's `app.url`.
- **Files modified:** `boot_test.go`
- **Commit:** `2953bf8`
**3. [Rule 3 - Blocking] Smoke token expiry**
- **Found during:** Task 1 (first smoke run)
- **Issue:** `admin:token:create --expires 1d` is refused (`api_tokens.expires_invalid`).
- **Fix:** The script uses `30d`, the value scripts/smoke.sh uses. The token dies with the throwaway database anyway.
- **Commit:** `f2dc85d`
### Notes on the plan text
- The acceptance check `grep -c 'location ^~ /oauth/mcp/'` prints 0 for any file, because GNU grep reads `^` as an anchor there. With `grep -cF` each vhost has exactly 1, and check-deploy.sh matches the location with `grep -qF`.
- The committed state is intermediate by design, following the submodule rule. On a fresh `git submodule update`, the gitlink 7b9899f (v0.1.7) predates backend mode, so `TestBootUserTranslateJournal` fails at commits 2953bf8 to df554d5 until plan 05 commits the release pointer. With the working tree on the plan 03 commits, as left now, vet and every app test pass.
---
**Total deviations:** 3 auto-fixed. **Impact:** no scope creep. The rollback fix keeps the documented rollback from failing boot.
## Issues Encountered
None beyond the deviations.
## Known Stubs
None.
## Threat Flags
None beyond the plan's threat model:
- T-32.2-22: OIDC off. The smoke asserts the 404, check-deploy refuses an OIDC location, and the boot test asserts the routes are absent.
- T-32.2-23: the plugin throttles stay on. nginx limits methods and the body size (64k).
- T-32.2-24: the output check printed nothing.
- T-32.2-25: no `add_header` in the new locations, and check-deploy enforces it.
## Verification
- `bash scripts/smoke-mcp-oauth.sh`: all twelve steps pass and the run ends `smoke-mcp-oauth: ok (12 steps)`. `grep -E 'oas_at_[A-Za-z0-9]|g15_[A-Za-z0-9]{8,}|code=[A-Za-z0-9]'` over the output prints nothing.
- `go vet -tags summercms_mcp,nodynamic ./...` and `go test -count=1 -tags summercms_mcp,nodynamic ./...` in the app: ok (Docker suite included). Untagged `go test -short ./...`: ok.
- `bash scripts/check-deploy.sh`: `check-deploy: ok` (nginx -t on both vhosts). The seven mutants were an add_header, a widened method limit, `subject: user`, `oidc` on, a missing summer.yaml entry, an added openid-configuration location, and the staging gate left on. Each one fails the check.
- `summer build` at the committed gitlink leaves `main.go` and `plugins.gen.go` unchanged. With the working tree on 4c209c1, only the oauthserver row changes (`v0.1.7-3-g4c209c1` and the newer plugin.yaml description), and plan 05 regenerates that with the release pointer. The file was restored to the committed copy.
- `go mod tidy -diff` is clean with the plan 03 plugin tree.
**Human verification, still open after this phase (unverified, not a failure):** the D-03 `SameSite=Strict` admin cookie on a real cross-site connector redirect chain (RESEARCH A2). It stays open until the "Live connector check (deferred)" in DEPLOY.md runs after the deferred production deploy. The phase VERIFICATION.md must list it under human verification with status unverified, pointing at that DEPLOY.md note and the VALIDATION.md manual-only row.
## User Setup Required
None for the local proof. The production deploy, the server's `go/.env` key (`SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE=https://grzybyfunkcjonalne.pl/mcp`), the vhost install and the live Claude connector check wait for the user's go-ahead.
## Next Phase Readiness
- **Plan 05**, after pushing and tagging sm-oauthserver-plugin, makes one app commit with these changes:
- the gitlink `plugins/golem15/oauthserver` moves to the release (it is uncommitted now; the working tree sits at local 4c209c1);
- the go.mod require goes from `v0.1.7` to the new tag;
- `summer build` regenerates plugins.gen.go (new version and description);
- then run `scripts/smoke-mcp-oauth.sh` and `scripts/check-deploy.sh` again.
- DEPLOY.md calls the minimum version "the sm-oauthserver-plugin release that adds `mcp.subject`". Plan 05 can name the tag there.
- Nothing was pushed, tagged or deployed in any repo. STATE.md and ROADMAP.md were not touched.
## Self-Check: PASSED
- Files exist: `config/golem15.oauthserver.yaml`, `scripts/smoke-mcp-oauth.sh` (executable), `plugins/golem15/oauthserver/plugin.go`.
- Commits 2953bf8, f2dc85d and df554d5 are in the app's `git log`. The gitlink 7b9899f is on the plugin's `origin/master`.

View File

@@ -0,0 +1,350 @@
---
phase: 32.2
plan: 05
type: execute
wave: 4
depends_on: [32.2-01, 32.2-02, 32.2-03, 32.2-04]
files_modified:
- modules/wristband/consent_path_test.go
- modules/pier/backend_only_grant_test.go
- modules/cabana/token_scope_names_test.go
- modules/cabana/mcp_admin_consent_test.go
- modules/cabana/account_items_test.go
- modules/cabana/backend_access_revoked_test.go
- admin/tests/views/ConnectView.test.ts
- admin/tests/app/router.test.ts
- admin/tests/views/LoginView.test.ts
- admin/tests/account/AccountContributions.test.ts
- ../sm-oauthserver-plugin/backend_tools_test.go
- ../sm-oauthserver-plugin/backend_mode_test.go
- ../sm-oauthserver-plugin/backend_consent_test.go
- ../sm-oauthserver-plugin/backend_subject_migration_test.go
- ../sm-oauthserver-plugin/backend_grant_rows_test.go
- ../sm-oauthserver-plugin/backend_revoke_test.go
- ../sm-oauthserver-plugin/go.mod
- ../sm-oauthserver-plugin/go.sum
- ../sm-oauthserver-plugin/plugin.yaml
- ../sm-grzybyfunkcjonalne-app/plugins/golem15/oauthserver
- ../sm-grzybyfunkcjonalne-app/go.mod
- ../sm-grzybyfunkcjonalne-app/go.sum
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-changelog-framework.md
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-changelog-plugin.md
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-changelog-published.txt
autonomous: false
requirements: [SC-1, SC-2, SC-3, SC-4, SC-5]
estimate:
tokens: 115000
raw_tokens: 115000
tasks: 5
confidence: low
must_haves:
truths:
- "SC-1, SC-2 (D-01, D-09): TestBackendGrantToolsMatchPersonalToken proves end to end in the plugin harness (Docker, summercms_mcp tag) that an administrator who consents over OAuth with a plugin scope's read variant lists only read-only tools, with the full scope lists write tools, and in both cases sees exactly the tool set a g15_ token with the same scopes sees, and that a tool call succeeds."
- "SC-1 (D-04): TestAuthorizeConsentPath and TestAuthorizeDefaultScopes lock the default handoff {issuer}/connect?request= and the read fallback, and the set values."
- "SC-2 (D-01, D-09): TestBackendOnlyGrant proves no frontend subject, no linked-backend lookup, distinct bindings for two administrators of one client, ceiling off, ScopeLimited true, refusal of malformed backend grants and a fingerprint change on ScopeLimited; TestLinkedGrantNoScopeLimit proves a user-mode linked grant still gets no scope limit."
- "SC-1 (D-03, D-09, D-11): TestMCPAdminConsent covers 401, 403 interactive_only, missing X-Requested-With, 404 without provider and for ErrMCPConsentNotFound, hidden scopes, dropped unknown and ungrantable scopes, the * collapse, 422 no_grantable_scopes, deny, offline_access only when requested, unknown body fields and the body cap; TestTokenScopeNames locks catalog order and labels."
- "SC-3 (D-12, D-13): TestAccountContributionItems covers null versus empty items, permission-filtered item actions, the items error flag, 403, both 404 paths and compile refusals; TestBackendAccessRevokedEvent covers all seven D-13 sites including admin:reset-password and role permission changes for holders, de-duplicated ids, rollback on listener error, no event for unrelated edits, and the unchanged after-commit MCPSubjectChanged."
- "SC-1, SC-3 (D-02, D-07, D-08, D-10, D-12, D-13): the plugin tests TestBackendMode, TestBackendConsent, TestBackendSubjectMigration, TestBackendGrantRows, TestBackendRevokeFromAccount and TestBackendCascade pass in Docker; the full plugin suite, the framework suite, the admin suites, the grzyby smoke and check-deploy, and sm-bm-app's tests against the new plugin through a scratch go.work all pass with user mode unchanged."
- "SC-5: tags, pushes and changelog posts happen only after the blocking release checkpoint records tag-and-publish: the framework gets the next free v0.6 patch on master containing every earlier tag, the plugin gets v0.1.8 after its go.mod requires that framework tag, the plugin is pushed before the app's pointer bump, which is its own commit, and each tag gets its changelog post the same day; no deploy."
- { statement: "UI backstop — the consent * rule: ticking * disables and clears the other scopes and shows the scope_all_includes note, the POST body is ['*'], and unticking re-enables them (ConnectView.test.ts)", verification: backstop }
- { statement: "UI backstop — no auto-allow and the decision navigation: with consent_required false nothing is POSTed on mount; Allow and Deny POST the documented bodies and call window.location.assign with the server URI, never the router (ConnectView.test.ts)", verification: backstop }
- { statement: "UI backstop — the switch account round trip: Use another account calls POST /auth/logout then replaces to login with redirect = the current /connect?request=…; the router test covers anonymous /connect → login → back (ConnectView.test.ts, router.test.ts)", verification: backstop }
- { statement: "UI backstop — account contribution items back-compat: a section without items renders exactly as before, items [] renders the empty block, and an item action runs the confirm with :title filled (AccountContributions.test.ts)", verification: backstop }
- { statement: "UI backstop — the D-03 SameSite=Strict cookie on a real cross-site connector redirect chain (RESEARCH A2) is not provable on localhost; it is routed to the live connector check DEPLOY.md lists for the deferred production deploy. VERIFICATION.md lists it under human verification with status unverified (not passed), and no test in this plan claims to cover it", verification: backstop }
artifacts:
- path: ../sm-oauthserver-plugin/backend_tools_test.go
provides: "OAuth administrator grant tools equal a g15_ token's tools"
contains: "TestBackendGrantToolsMatchPersonalToken"
- path: modules/pier/backend_only_grant_test.go
provides: "pier backend-only grant and linked-grant regression"
contains: "TestBackendOnlyGrant"
- path: modules/cabana/backend_access_revoked_test.go
provides: "all D-13 sites"
contains: "TestBackendAccessRevokedEvent"
- path: admin/tests/views/ConnectView.test.ts
provides: "consent screen unit tests and UI backstops"
contains: "window.location.assign"
- path: .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt
provides: "checkpoint record read by the release verify"
key_links:
- from: ../sm-oauthserver-plugin/backend_tools_test.go
to: "pier tools/list through the published verifier"
via: "real authorize, admin consent, token exchange and /mcp calls"
pattern: "tools/list"
- from: release task
to: 32.2-05-release-decision.txt
via: "first line hold or tag-and-publish, then base tags"
pattern: "tag-and-publish"
---
<objective>
User story (phase goal, ROADMAP 32.2): **As an** editor of a blog-only application whose MCP tools are backend-guarded (Journal) and which has no frontend users, **I want to** add the site's `/mcp` as a connector and sign in once as my administrator account over OAuth, **so that** agents no longer need a hand-copied `g15_` personal token.
Slice in this plan (the "so that" part of the story): an OAuth agent and a `g15_` token with equal scopes see and call the same tools (TestBackendGrantToolsMatchPersonalToken). The rest of the plan is the unit tests, the regression runs that show user mode is unchanged, and the gated release.
Last plan of the phase (project rule: unit tests are the last plan): the Validation Architecture tests for SC-1 to SC-4 across summercms.go, the admin SPA and sm-oauthserver-plugin, regression runs proving user mode is unchanged (framework, plugin, grzyby, sm-bm-app through a scratch go.work), then a blocking human checkpoint before any tag, push or changelog post (SC-5).
Purpose: plans 01 to 04 carry smoke tests only; this plan proves every behaviour, including the five UI backstops, and keeps releasing behind the user's go-ahead.
Output: test files in three repos, recorded regression runs, and, only if the checkpoint says so, the framework patch tag, sm-oauthserver-plugin v0.1.8, the grzyby pointer bump commit and the two changelog posts.
⚠ spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
Do not deploy anything. Do not hardcode the framework version: compute it from tags at release time (memory: next free patch, never a minor bump without the user's word; tags only on master; each tag contains all earlier tags).
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-CONTEXT.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-VALIDATION.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-01-SUMMARY.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-02-SUMMARY.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-03-SUMMARY.md
@.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-04-SUMMARY.md
@modules/pier/backend_subject_smoke_test.go
@modules/cabana/mcp_consent_smoke_test.go
@modules/cabana/account_items_smoke_test.go
@modules/cabana/backend_access_revoked_smoke_test.go
@admin/tests/smoke/connect.smoke.test.ts
@../sm-oauthserver-plugin/harness_test.go
@../sm-oauthserver-plugin/backend_mode_smoke_test.go
@../sm-oauthserver-plugin/testmain_test.go
</context>
<tasks>
<task type="tracer">
<name>Tracer: an OAuth administrator grant and a g15_ token with equal scopes see and call the same tools</name>
<reversibility rating="reversible">Tests only.</reversibility>
<precondition>docker info exits 0; plans 01-04 SUMMARY files exist.</precondition>
<files>../sm-oauthserver-plugin/backend_tools_test.go</files>
<read_first>
../sm-oauthserver-plugin/harness_test.go (bootBackendMode, env.admin, adminCall)
../sm-oauthserver-plugin/backend_mode_smoke_test.go (authorize → admin consent → token flow)
../sm-oauthserver-plugin/testmain_test.go (Docker skip under testing.Short with flag.Parse)
/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/pier/backend_subject_smoke_test.go (MCP initialize/tools/list helpers)
/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/modules/surf/pier_on.go (pier is linked only with -tags summercms_mcp)
</read_first>
<action>
New ../sm-oauthserver-plugin/backend_tools_test.go with build constraint //go:build summercms_mcp, TestBackendGrantToolsMatchPersonalToken (Docker; skip under testing.Short()). Boot backend mode with pier enabled (mcp.enabled, allow_personal_tokens true) and a test fixture plugin declaring TokenScopes acme and acme:read and backend-guarded admin routes exposed as MCP tools: one read-only, one write (copy the fixture style of the framework's pier Docker tests; do not depend on any app plugin). For an administrator holding the fixture permissions: connect over OAuth (DCR, PKCE authorize, cabana consent with [acme:read], token exchange) and list tools: only the read-only tool; call it: success. Connect a second client with [acme]: both tools listed, the write call succeeds. Create g15_ tokens with [acme:read] and [acme] through cabana and assert their tools/list results equal the OAuth ones name for name (D-09: an OAuth agent and a g15_ token with equal scopes see the same tools). Revoke one OAuth client from My account and assert its next call answers 401 while the other client still works. Never print tokens or codes. Commit in the plugin repo by path.
</action>
<verify>
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 600s -tags summercms_mcp -run 'TestBackendGrantToolsMatchPersonalToken' -v .</automated>
<fails_when>non-zero exit, or a line contains FAIL, or `[no tests to run]`, or `--- SKIP: TestBackendGrantToolsMatchPersonalToken`, or no `--- PASS: TestBackendGrantToolsMatchPersonalToken` line</fails_when>
</verify>
<acceptance_criteria>
- backend_tools_test.go starts with `//go:build summercms_mcp`.
- TestBackendGrantToolsMatchPersonalToken has a PASS line and asserts OAuth and g15_ tool lists are equal for both scope sets.
- No production file is in this commit.
</acceptance_criteria>
<done>SC-1 and SC-2 are proven end to end through the real authorization server, the admin consent API and pier.</done>
</task>
<task type="auto">
<name>Framework and admin SPA unit tests</name>
<reversibility rating="reversible">Tests only.</reversibility>
<precondition>docker info exits 0; admin/node_modules exists.</precondition>
<files>modules/wristband/consent_path_test.go, modules/pier/backend_only_grant_test.go, modules/cabana/token_scope_names_test.go, modules/cabana/mcp_admin_consent_test.go, modules/cabana/account_items_test.go, modules/cabana/backend_access_revoked_test.go, admin/tests/views/ConnectView.test.ts, admin/tests/app/router.test.ts, admin/tests/views/LoginView.test.ts, admin/tests/account/AccountContributions.test.ts</files>
<read_first>
modules/wristband/consent_path_smoke_test.go, modules/pier/backend_subject_smoke_test.go, modules/pier/export_test.go, modules/pier/helpers_test.go
modules/cabana/mcp_consent_smoke_test.go, account_items_smoke_test.go, backend_access_revoked_smoke_test.go, scope_limit_for_test.go
admin/tests/smoke/connect.smoke.test.ts, admin/tests/smoke/account-items.smoke.test.ts, admin/tests/app/router.test.ts, admin/tests/views/LoginView.test.ts, admin/tests/account/AccountContributions.test.ts
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-UI-SPEC.md (C1-C3, UI Considerations backstop rows)
</read_first>
<action>
Go (summercms.go), extending the plan 01 smokes, never weakening them:
modules/wristband/consent_path_test.go: TestAuthorizeConsentPath (empty path byte-identical {issuer}/connect?request=<escaped id>; a set path; an issuer with a path segment) and TestAuthorizeDefaultScopes (absent, empty and identity-only scope values fall back to DefaultScopes; DefaultScopes entries outside the allowed set are dropped; empty DefaultScopes keeps read; an explicit scope is not replaced).
modules/pier/backend_only_grant_test.go (package pier for the unexported fields): TestBackendOnlyGrant (frontend guard registered but Frontend nil; a fake MCPLinkedBackendResolver records zero calls; bindings oauth:backend:c1:7 and oauth:backend:c1:8 differ; writes() true; ScopeLimited true; Subject backend with UserID non-zero, and with BackendUserID 0, answer ErrUnauthorized; fingerprint differs when only ScopeLimited differs) and TestLinkedGrantNoScopeLimit (Docker: a user-mode grant with the backend scope and a matching consented link reaches the backend guard with principal.Scope nil, as before).
modules/cabana/token_scope_names_test.go: TestTokenScopeNames (order *, admin:read, plugin scopes in plugin order; works before Activate; TokenScopeLabels translates and passes unknown names through).
modules/cabana/mcp_admin_consent_test.go: TestMCPAdminConsent (Docker) with the cases of the SC-1 truth above, a 16 KiB+ body refused and a fake provider asserting the exact Decide arguments.
modules/cabana/account_items_test.go: TestAccountContributionItems (Docker) with the cases of the SC-3 truth above; Run sees a transaction through TxFromContext.
modules/cabana/backend_access_revoked_test.go: TestBackendAccessRevokedEvent (Docker): each of the seven sites (delete, deactivate, password set by another admin, own password change, admin:reset-password through the command, role/own permissions/superuser change, a role's permission change firing once with every holder) records the right reason and ids with a non-nil Tx; a listener error rolls back the delete and the role save; a name-only edit fires nothing; the after-commit MCPSubjectChanged emissions still happen.
Admin vitest: admin/tests/views/ConnectView.test.ts covering every C1 state, the * rule, no auto-allow, Allow and Deny bodies, window.location.assign with the server URI and never the router, forbidden schemes as submit failures, Use another account (logout then login with redirect), 401 → expireSession, 404 on submit → Expired, focus moving to the state heading, and the currentUser fallback; extend router.test.ts (anonymous /connect?request=x → login with redirect=/connect?request=x; safeRedirect accepts it), LoginView.test.ts (the hint only for a /connect redirect) and AccountContributions.test.ts (null items unchanged, [] empty block, item rows and action buttons, confirm with :title, 404 item_gone toast plus reload, 409 action_stale). Commit Go tests and admin tests by path in the framework repo; no production file changes unless a test exposes a bug, in which case fix it in its own commit and say so in the SUMMARY.
</action>
<verify>
<automated>go test -count=1 -run 'TestAuthorizeConsentPath|TestAuthorizeDefaultScopes|TestBackendOnlyGrant|TestLinkedGrantNoScopeLimit|TestTokenScopeNames|TestMCPAdminConsent$|TestAccountContributionItems|TestBackendAccessRevokedEvent' -v ./modules/wristband ./modules/pier ./modules/cabana</automated>
<fails_when>non-zero exit, or any `--- FAIL` or `--- SKIP` line, or `[no tests to run]`, or fewer than eight distinct top-level `--- PASS: Test` lines for the eight names</fails_when>
<automated>npm --prefix admin run typecheck && npm --prefix admin run test -- tests/views/ConnectView.test.ts tests/app/router.test.ts tests/views/LoginView.test.ts tests/account/AccountContributions.test.ts</automated>
<fails_when>non-zero exit, or the vitest summary shows a failed test, or `No test files found`, or ConnectView.test.ts is absent from the run output</fails_when>
</verify>
<acceptance_criteria>
- All eight Go test names have a PASS line and none is skipped.
- ConnectView.test.ts exists and contains tests for the * rule, no auto-allow, the switch round trip and forbidden schemes (the four ConnectView/router backstops).
- AccountContributions.test.ts contains the back-compat case (null items render exactly as before) and the :title confirm case.
- The four admin test files pass under vitest.
</acceptance_criteria>
<done>SC-1, SC-2 and SC-3 framework and SPA behaviour is locked by unit tests, including the UI backstops.</done>
</task>
<task type="auto">
<name>Plugin unit tests and the cross-repo regression runs</name>
<reversibility rating="reversible">Tests and read-only regression runs; the scratch go.work lives in a temp dir.</reversibility>
<precondition>docker info exits 0; /media/nvme/dev/golem15/summercms.io/summercms/sm-bm-app/go.work exists.</precondition>
<files>../sm-oauthserver-plugin/backend_mode_test.go, ../sm-oauthserver-plugin/backend_consent_test.go, ../sm-oauthserver-plugin/backend_subject_migration_test.go, ../sm-oauthserver-plugin/backend_grant_rows_test.go, ../sm-oauthserver-plugin/backend_revoke_test.go</files>
<read_first>
../sm-oauthserver-plugin/backend_mode_smoke_test.go, backend_revocation_smoke_test.go, backend_account_smoke_test.go (plan 03 smokes)
../sm-oauthserver-plugin/mcp_backfill_test.go (migration test pattern: migrate twice, rollback)
../sm-oauthserver-plugin/mcp_revocation_test.go and cascade_test.go (revocation assertions)
/media/nvme/dev/golem15/summercms.io/summercms/sm-bm-app/go.work (use list for the scratch copy)
</read_first>
<action>
Plugin tests (Docker, not -short), in ../sm-oauthserver-plugin: backend_mode_test.go TestBackendMode (boot refusals: unknown mcp.subject, backend with mcp.enabled false, backend with mcp_scopes; backend mode: /oauth/mcp/requests/{request} 404, OIDC routes 404 with oidc.enabled false and present with oidc.enabled true, the authorized-apps rule, mcp.consent_path override, metadata scopes_supported = catalog plus offline_access, a no-scope request yields the catalog names; user mode: handoff still {issuer}/connect and scopes unchanged). backend_consent_test.go TestBackendConsent (allow and deny through cabana's endpoint; the consent row is replaced, never merged; consent_required false once covered; another administrator's issued request answers 404; a frontend user's JWT cannot reach the admin consent). backend_subject_migration_test.go TestBackendSubjectMigration (columns nullable and the partial unique index exist after migrate; the CHECK refuses an access token row with user_id 0 and no backend_user_id; rollback deletes backend rows and restores NOT NULL; migrate again succeeds). backend_grant_rows_test.go TestBackendGrantRows (code, access, refresh and consent rows have user_id NULL and backend_user_id; refresh rotation keeps the shape; replaying a rotated backend refresh token revokes the family; a user-mode grant in a user-mode boot is byte-for-byte as before). backend_revoke_test.go TestBackendRevokeFromAccount (only the chosen client revoked, one revoked event with that ClientID, cross-admin 404) and TestBackendCascade (each D-13 trigger revokes and fires one event per client; with the listener disabled the verifier still refuses a token issued before tokens_valid_after, sleeping past the two-second cutoff window of RESEARCH Pitfall 8; user rows and user-mode linked grants untouched). Commit by path in the plugin repo.
Regression runs, recorded in the SUMMARY with pass counts: the framework suite and MCP-tagged pier/surf; the full plugin suite with and without -tags summercms_mcp; admin typecheck, test and test:browser plus check-admin-openapi.sh --check and check-admin-dist.sh; docs; in ../sm-grzybyfunkcjonalne-app scripts/smoke-mcp-oauth.sh, scripts/check-deploy.sh and the tagged go test; sm-bm-app against the new plugin through a scratch go.work: copy sm-bm-app/go.work to a mktemp -d directory with every use path made absolute under /media/nvme/dev/golem15/summercms.io/summercms/sm-bm-app except plugins/golem15/oauthserver, which points at /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin, and an absolute summercms replace; run with GOWORK set to it. Do not edit sm-bm-app or sm-demo-app.
</action>
<verify>
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 900s -run 'TestBackendMode$|TestBackendConsent|TestBackendSubjectMigration|TestBackendGrantRows|TestBackendRevokeFromAccount|TestBackendCascade' -v .</automated>
<fails_when>non-zero exit, or any `--- FAIL` or `--- SKIP` line, or `[no tests to run]`, or fewer than six top-level `--- PASS: TestBackend` lines</fails_when>
<automated>go vet ./... && go test -count=1 ./... && go test -count=1 -tags summercms_mcp ./modules/pier ./modules/surf && go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 900s ./... && go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 900s -tags summercms_mcp ./...</automated>
<fails_when>non-zero exit, or a line contains FAIL</fails_when>
<automated>npm --prefix admin run typecheck && npm --prefix admin run test && npm --prefix admin run test:browser && scripts/check-admin-openapi.sh --check && scripts/check-admin-dist.sh && go test ./cmd/summer -run TestDocsTree -count=1 && go run ./cmd/summer docs:build --check</automated>
<fails_when>non-zero exit, or a vitest summary shows a failed test, or check-admin-dist prints `stale`, or docs:build prints a problem line</fails_when>
<automated>bash /media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh && bash /media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh && go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app test -count=1 -tags summercms_mcp,nodynamic ./...</automated>
<fails_when>non-zero exit, or a line contains FAIL, or the smoke output lacks its final step line</fails_when>
<automated>W="$(mktemp -d)" && B=/media/nvme/dev/golem15/summercms.io/summercms/sm-bm-app && sed -e "s#^\t\.\$#\t$B#" -e "s#^\t\./plugins/golem15/oauthserver\$#\t/media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin#" -e "s#^\t\./#\t$B/#" -e "s#=> \.\./summercms.go#=> /media/nvme/dev/golem15/summercms.io/summercms/summercms.go#" "$B/go.work" > "$W/go.work" && grep -q sm-oauthserver-plugin "$W/go.work" && GOWORK="$W/go.work" go -C "$B" vet -tags summercms_mcp ./... && GOWORK="$W/go.work" go -C "$B" test -count=1 -tags summercms_mcp ./...</automated>
<fails_when>non-zero exit, or a line contains FAIL, or the grep finds no sm-oauthserver-plugin line in the scratch go.work</fails_when>
</verify>
<acceptance_criteria>
- The six plugin test names have PASS lines, none skipped.
- Framework, plugin (both tag settings), admin, docs, grzyby and sm-bm-app runs all exit 0; the SUMMARY records each command and its result.
- No file in sm-bm-app or sm-demo-app changed (`git -C ../sm-bm-app status --porcelain` shows nothing new from this task).
</acceptance_criteria>
<done>Backend mode is proven in the plugin, and every existing consumer path (user mode, sm-bm-app, g15_ tokens) is shown unchanged.</done>
</task>
<task type="checkpoint:decision" gate="blocking">
<name>Whether to tag, push and post the changelog</name>
<reversibility rating="costly">A pushed framework tag and plugin v0.1.8 are what other applications will require; a mistake is fixed by a further patch, never a rewritten tag.</reversibility>
<decision>Tag the framework's next free v0.6 patch and sm-oauthserver-plugin v0.1.8, push both, commit and push the grzyby pointer bump, and publish both changelog posts now?</decision>
<context>SC-5 asks for patch tags. Memory rules: tag only at phase completion after full verification and validation; default to the next patch (never a minor bump without the user's word); tags only on master; each tag must contain every earlier tag. If the user wants /msd-verify-work first, choose hold and run the release later. No deploy of any application happens either way (CONTEXT Deferred: production deploy of the first consumer and the live Claude connector check). There is no auto-select: an unattended run must stop here. On resume, before any later task changes a ref, write .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt with three lines: the accepted option id (hold or tag-and-publish), `framework-base <highest v0.6.* tag in summercms.go now>`, `plugin-base <highest v0.1.* tag in sm-oauthserver-plugin now>`, read with git tag --list --sort=-v:refname. Create no tag, push nothing and publish nothing in this task.</context>
<options>
<option id="tag-and-publish">
<name>Tag, push and post the changelog</name>
<pros>The first consumer can require released versions; SC-5 is met the same day with its changelog posts.</pros>
<cons>The tags are public before /msd-verify-work has run.</cons>
</option>
<option id="hold">
<name>Do not tag or push yet</name>
<pros>Verification and validation can run first, as the release memory recommends.</pros>
<cons>SC-5's tags and the grzyby pointer bump wait for a later go-ahead.</cons>
</option>
</options>
<resume-signal>Select tag-and-publish or hold</resume-signal>
<read_first>
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-RESEARCH.md (Release mechanics)
CLAUDE.md (Commits and concurrency: changelog posts, plugin push before pointer bump)
</read_first>
<acceptance_criteria>
- No git tag, git push or changelog publish runs before this checkpoint returns.
- 32.2-05-release-decision.txt exists before the next task changes any ref, and its first line is the accepted option id.
</acceptance_criteria>
</task>
<task type="auto">
<name>Release only if the checkpoint accepted it</name>
<reversibility rating="costly">Pushed tags, the pointer bump and the changelog posts are the release; hold does none of it.</reversibility>
<files>../sm-oauthserver-plugin/go.mod, ../sm-oauthserver-plugin/go.sum, ../sm-oauthserver-plugin/plugin.yaml, ../sm-grzybyfunkcjonalne-app/plugins/golem15/oauthserver, ../sm-grzybyfunkcjonalne-app/go.mod, ../sm-grzybyfunkcjonalne-app/go.sum, .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt, .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-changelog-framework.md, .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-changelog-plugin.md, .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-changelog-published.txt</files>
<read_first>
.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt
../sm-oauthserver-plugin/go.mod (require summercms, replace line) and plugin.yaml (generated by summer plugin:manifest)
../sm-grzybyfunkcjonalne-app/go.mod (require lines for summercms and sm-oauthserver-plugin)
../sm-summercmsio-app/DEPLOY.md section "Posting to the changelog"
CLAUDE.md changelog rules
</read_first>
<action>
Read the decision record; never rewrite it after a ref changes (if resuming without it, write it as the checkpoint describes before changing anything). If the first line is hold: create no tag, push nothing, run no changelog script, say so in the SUMMARY and stop.
tag-and-publish, in this order. 1) Framework: on master with a clean index for the files of this phase, the new tag is framework-base's patch plus one (next free v0.6 patch; if that tag already exists locally or on origin, stop and ask). Check that HEAD contains every existing v0.* tag (git merge-base --is-ancestor for each), create an annotated tag whose message summarises the phase in user terms, push master, then push the tag. 2) Plugin: set the summercms require in ../sm-oauthserver-plugin/go.mod to the new framework tag (keep the replace line), refresh go.sum, regenerate plugin.yaml with the framework's summer plugin:manifest so TestPluginManifest passes, run the plugin's go test -short ./..., commit go.mod, go.sum and plugin.yaml by path (never go.work), tag v0.1.8 (stop and ask if it exists or if plugin-base is not v0.1.7), push master, then push the tag. 3) App pointer bump, its own commit, only after step 2's push: in ../sm-grzybyfunkcjonalne-app check out v0.1.8 in plugins/golem15/oauthserver, set the go.mod requires of sm-oauthserver-plugin to v0.1.8 and of summercms to the new framework tag, go mod tidy, run scripts/smoke-mcp-oauth.sh and the tagged go test, commit the gitlink, go.mod and go.sum by path, push master. No deploy. 4) Changelog, from ../sm-summercmsio-app: scripts/changelog-post.py source <framework tag> and write .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-changelog-framework.md (user-facing markdown with ## Highlights, ## Added, ## Changed, ## Fixed; no H1, no planning IDs, no quick codes), then publish it with an --excerpt; write 32.2-05-changelog-plugin.md the same way for v0.1.8 and publish it with --repo ../sm-oauthserver-plugin. Append each published post URL the script prints to 32.2-05-changelog-published.txt, one per line. The script reads the g15_ token from ~/.config/summercms/journal-token: never print, copy or mint it; if the file is missing or the token is refused, stop and ask. Never force-push. Do not git add -A anywhere.
</action>
<verify>
<automated>python3 -I -c 'import pathlib,subprocess,sys
d=pathlib.Path("/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/phases/32.2-mcp-oauth-with-administrator-subjects")
fw=pathlib.Path("/media/nvme/dev/golem15/summercms.io/summercms/summercms.go"); pl=pathlib.Path("/media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin"); app=pathlib.Path("/media/nvme/dev/golem15/summercms.io/summercms/sm-grzybyfunkcjonalne-app")
rec=d/"32.2-05-release-decision.txt"
rec.is_file() or sys.exit("decision record absent")
L=[x.strip() for x in rec.read_text().splitlines() if x.strip()]
len(L)>=3 or sys.exit("decision record incomplete")
opt=L[0]; fb=L[1].split()[-1]; pb=L[2].split()[-1]
opt in ("hold","tag-and-publish") or sys.exit("bad option")
def g(r,*a):
p=subprocess.run(["git","-C",str(r),*a],capture_output=True,text=True)
p.returncode==0 or sys.exit("git failed in "+r.name)
return p.stdout
def tags(r,pat): return [t for t in g(r,"tag","--list",pat).split() if t]
nxt="v0.6."+str(int(fb.split(".")[2])+1)
if opt=="hold":
nxt not in tags(fw,"v0.6.*") or sys.exit("hold but framework tagged")
"v0.1.8" not in tags(pl,"v0.1.*") or sys.exit("hold but plugin tagged")
sys.exit(0)
nxt in tags(fw,"v0.6.*") or sys.exit("framework tag missing")
"refs/tags/"+nxt in g(fw,"ls-remote","--tags","origin") or sys.exit("framework tag not pushed")
"refs/tags/v0.1.8" in g(pl,"ls-remote","--tags","origin") or sys.exit("plugin tag not pushed")
"summercms "+nxt in (pl/"go.mod").read_text() or sys.exit("plugin go.mod not on framework tag")
c=g(pl,"rev-list","-n","1","v0.1.8").strip()
c in g(app,"ls-tree","HEAD","plugins/golem15/oauthserver") or sys.exit("app pointer not at v0.1.8")
"sm-oauthserver-plugin v0.1.8" in (app/"go.mod").read_text() or sys.exit("app go.mod not on v0.1.8")
for n in ("32.2-05-changelog-framework.md","32.2-05-changelog-plugin.md"):
t=(d/n).read_text() if (d/n).is_file() else sys.exit(n+" missing")
(not t.lstrip().startswith("# ")) or sys.exit(n+" starts with an H1")
all(h in t for h in ("## Highlights","## Added","## Changed","## Fixed")) or sys.exit(n+" missing heading")
pub=d/"32.2-05-changelog-published.txt"
urls=[x for x in pub.read_text().split() if x.startswith("https://summercms.io/changelog")] if pub.is_file() else []
len(urls)>=2 or sys.exit("changelog posts not recorded")'</automated>
<fails_when>non-zero exit, including decision record absent, decision record incomplete, bad option, git failed, hold but framework tagged, hold but plugin tagged, framework tag missing, framework tag not pushed, plugin tag not pushed, plugin go.mod not on framework tag, app pointer not at v0.1.8, app go.mod not on v0.1.8, a changelog file missing or starting with an H1 or missing a heading, or changelog posts not recorded</fails_when>
</verify>
<acceptance_criteria>
- hold: no new v0.6 tag in summercms.go, no v0.1.8 in sm-oauthserver-plugin, no changelog script run.
- tag-and-publish: the framework tag is the next v0.6 patch on master and on origin; sm-oauthserver-plugin v0.1.8 is on origin and its go.mod requires that framework tag; the grzyby commit moving plugins/golem15/oauthserver to v0.1.8 comes after the plugin push and is its own commit; two changelog posts are recorded; nothing was deployed.
</acceptance_criteria>
<done>SC-5's patch releases either shipped with their changelog posts and the app pointer bump, or stayed local because the checkpoint said hold.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| Test output and changelog notes | Tokens, codes and the journal token must not reach logs or the public post |
| git push of release tags | What other repositories will require |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-32.2-26 | Information disclosure | tests, smoke output, changelog-post.py | medium | mitigate | Tests assert status codes and ids, never print bearer tokens or codes; the journal token is read by the script only, never printed, copied or minted; stop if it is missing |
| T-32.2-27 | Tampering | release tags | medium | mitigate | Blocking checkpoint; tag only on master containing every earlier tag; next patch computed from tags; no force-push; plugin pushed before the app pointer bump |
| T-32.2-28 | Spoofing | sm-bm-app regression scratch workspace | low | accept | The scratch go.work lives in a temp dir and only redirects the plugin to the sibling checkout; sm-bm-app files are not changed |
| T-32.2-SC | Tampering | go/npm installs | low | accept | No dependency added; npm ci uses the committed lockfile |
</threat_model>
<verification>
All named tests pass (none skipped); every regression run in task 3 exits 0; the checkpoint record exists and the release verify agrees with it.
Carried as unverified human verification (not a failure, and not closed by any test here): the D-03 cross-site SameSite=Strict cookie check (RESEARCH A2, VALIDATION.md manual-only row, DEPLOY.md "Live connector check (deferred)"). VERIFICATION.md must list it as open.
</verification>
<success_criteria>
- SC-1 to SC-4 have automated proofs beyond the plan 01-04 smokes, including the five UI backstops (four in vitest, one routed to the deferred live check).
- SC-5: tags, pushes, pointer bump and changelog posts happen only through the checkpoint.
</success_criteria>
<output>
Create `.planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-SUMMARY.md` when done.
</output>
## Artifacts this phase produces
Plan 05 (tests and release):
- Framework tests: TestAuthorizeConsentPath, TestAuthorizeDefaultScopes (modules/wristband/consent_path_test.go); TestBackendOnlyGrant, TestLinkedGrantNoScopeLimit (modules/pier/backend_only_grant_test.go); TestTokenScopeNames, TestMCPAdminConsent, TestAccountContributionItems, TestBackendAccessRevokedEvent (modules/cabana/*_test.go)
- Admin tests: admin/tests/views/ConnectView.test.ts (new); extended router.test.ts, LoginView.test.ts, AccountContributions.test.ts
- Plugin tests: TestBackendGrantToolsMatchPersonalToken (build tag summercms_mcp), TestBackendMode, TestBackendConsent, TestBackendSubjectMigration, TestBackendGrantRows, TestBackendRevokeFromAccount, TestBackendCascade
- Release records: 32.2-05-release-decision.txt, 32.2-05-changelog-framework.md, 32.2-05-changelog-plugin.md, 32.2-05-changelog-published.txt
- Only after tag-and-publish: next framework v0.6 patch tag, sm-oauthserver-plugin v0.1.8 (go.mod on that framework tag, regenerated plugin.yaml), the grzyby pointer bump commit to v0.1.8, two changelog posts

View File

@@ -0,0 +1,302 @@
---
phase: 32.2-mcp-oauth-with-administrator-subjects
plan: 05
subsystem: testing
tags: [mcp, oauth, wristband, pier, cabana, admin-spa, sm-oauthserver-plugin, regression, release-gate]
requires:
- phase: 32.2-01
provides: wristband consent_path and DefaultScopes, pier backend-only grants, cabana MCP admin consent, account items, BackendAccessRevokedEvent
- phase: 32.2-02
provides: admin SPA /connect screen, login hint, My account item rows
- phase: 32.2-03
provides: sm-oauthserver-plugin mcp.subject backend (local commits 6996ffe, 9b97466, 4c209c1)
- phase: 32.2-04
provides: sm-grzybyfunkcjonalne-app mounts the plugin in backend mode, smoke-mcp-oauth.sh, check-deploy.sh guards
provides:
- TestBackendGrantToolsMatchPersonalToken - an OAuth administrator grant and a g15_ token with equal scopes list and call the same tools
- framework unit tests for SC-1 to SC-3 in wristband, pier and cabana
- admin SPA tests for the consent screen, the login hint and the My account item rows (four of the five UI backstops)
- plugin unit tests for backend-subject mode, consent, migration, grant rows, revocation and the D-13 cascade
- recorded regression runs across framework, admin, plugin, grzyby and sm-bm-app (all exit 0)
- admin:reset-password now runs in a lagoon transaction, so BackendAccessRevokedEvent listeners' after-commit work fires
- 32.2-05-release-decision.txt recording hold (framework-base v0.6.6, plugin-base v0.1.7)
affects: [32.2 VERIFICATION, the release of the next v0.6 patch and sm-oauthserver-plugin v0.1.8, grzyby pointer bump]
actuals:
tokens: 46063
tasks: 5
commits: 4
plan_head_before: d450a6819e9b6d6da8879e9bb6933a365394d156
plan_head_after: fc90a5470ce87acbbe199c4d0d0e64059315acee
tech-stack:
added: []
patterns:
- "Throttle-aware Docker tests: a cascade test rotates fresh OAuth clients instead of relaxing the plugin's register/token throttles"
- "Test-only hooks through export_test.go (cabana.FireBackendAccessRevokedForTest), never exported from the package"
key-files:
created:
- modules/wristband/consent_path_test.go
- modules/pier/backend_only_grant_test.go
- modules/cabana/token_scope_names_test.go
- modules/cabana/mcp_admin_consent_test.go
- modules/cabana/account_items_test.go
- modules/cabana/backend_access_revoked_test.go
- admin/tests/views/ConnectView.test.ts
- ../sm-oauthserver-plugin/backend_tools_test.go
- ../sm-oauthserver-plugin/backend_mode_test.go
- ../sm-oauthserver-plugin/backend_consent_test.go
- ../sm-oauthserver-plugin/backend_subject_migration_test.go
- ../sm-oauthserver-plugin/backend_grant_rows_test.go
- ../sm-oauthserver-plugin/backend_revoke_test.go
- ../sm-oauthserver-plugin/jwt_only_test.go
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt
modified:
- modules/cabana/commands.go
- modules/cabana/export_test.go
- admin/tests/app/router.test.ts
- admin/tests/views/LoginView.test.ts
- admin/tests/account/AccountContributions.test.ts
- ../sm-oauthserver-plugin/testdata/php_methods.txt
- ../sm-oauthserver-plugin/testdata/PHP_METHOD_MAP.md
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/deferred-items.md
key-decisions:
- "Release checkpoint answered hold: no tag, no push, no changelog post; the release (next v0.6 patch above v0.6.6, sm-oauthserver-plugin v0.1.8, grzyby pointer bump, two changelog posts) is pending the user's go-ahead after /msd-verify-work"
- "admin:reset-password runs in lagoon.Transaction instead of a plain GORM transaction, so lagoon.AfterCommit callbacks registered by BackendAccessRevokedEvent listeners run (Rule 1)"
- "TestPHPMethodMap: the five AuthorizeResolveUserJwtOnlyTest methods are mapped, three ported as adapted subtests and two marked not applicable (the Go plugin resolves users from the session JWT only)"
- "offline_access-only authorize requests storing no data scope is pre-existing (user mode behaves the same) and was logged to deferred-items.md, not changed"
patterns-established:
- "Plugin v0.1.8 must require a framework tag that contains b1b96d85"
requirements-completed: [SC-1, SC-2, SC-3, SC-4]
coverage:
- id: D1
description: "An administrator who consents over OAuth with acme:read lists and calls only the read-only tool, with acme lists and calls the write tool, and both tool lists equal a g15_ token's tools/list with the same scopes; revoking one connection from My account answers 401 for it and leaves the other working"
requirement: SC-2
verification:
- kind: integration
ref: "go -C ../sm-oauthserver-plugin test -count=1 -tags summercms_mcp -run TestBackendGrantToolsMatchPersonalToken . (backend_tools_test.go, Docker)"
status: pass
human_judgment: false
- id: D2
description: "Framework unit tests: consent handoff path and default scopes (wristband), backend-only grants and the user-mode linked-grant regression (pier), token scope names, MCP admin consent API, account contribution items and BackendAccessRevokedEvent at all seven D-13 sites (cabana)"
requirement: SC-1
verification:
- kind: unit
ref: "go test -count=1 -run 'TestAuthorizeConsentPath|TestAuthorizeDefaultScopes|TestBackendOnlyGrant|TestLinkedGrantNoScopeLimit|TestTokenScopeNames|TestMCPAdminConsent$|TestAccountContributionItems|TestBackendAccessRevokedEvent' ./modules/wristband ./modules/pier ./modules/cabana"
status: pass
human_judgment: false
- id: D3
description: "Admin SPA tests and four UI backstops: the * consent rule, no auto-allow with Allow/Deny through window.location.assign, the switch-account round trip, and account item rows back-compat"
requirement: SC-1
verification:
- kind: automated_ui
ref: "npm --prefix admin run test -- tests/views/ConnectView.test.ts tests/app/router.test.ts tests/views/LoginView.test.ts tests/account/AccountContributions.test.ts"
status: pass
human_judgment: false
- id: D4
description: "Plugin backend-mode unit tests: TestBackendMode, TestBackendConsent, TestBackendSubjectMigration, TestBackendGrantRows, TestBackendRevokeFromAccount, TestBackendCascade"
requirement: SC-3
verification:
- kind: integration
ref: "go -C ../sm-oauthserver-plugin test -count=1 -run 'TestBackendMode$|TestBackendConsent|TestBackendSubjectMigration|TestBackendGrantRows|TestBackendRevokeFromAccount|TestBackendCascade' . (Docker)"
status: pass
human_judgment: false
- id: D5
description: "User mode unchanged: full regression runs in framework, admin, plugin (both tag sets), grzyby (smoke, check-deploy, tagged tests) and sm-bm-app through a scratch go.work"
requirement: SC-4
verification:
- kind: integration
ref: "task 3 regression commands (see Verification below), every exit code 0"
status: pass
human_judgment: false
- id: D6
description: "Live connector check: on a real cross-site redirect from Claude the SameSite=Strict admin cookie still reaches the admin /connect screen, so the consent card shows the signed-in administrator rather than the login screen (D-03, RESEARCH A2, fifth UI backstop)"
requirement: SC-1
verification: []
human_judgment: true
rationale: "A localhost stack is same-site and cannot reproduce the cross-site redirect chain. It is routed to sm-grzybyfunkcjonalne-app DEPLOY.md 'Live connector check (deferred)', which runs after the deferred production deploy on the user's go-ahead. Status UNVERIFIED, not passed and not failed; no test in this plan claims to cover it."
- id: D7
description: "SC-5 release: next v0.6 patch tag, sm-oauthserver-plugin v0.1.8, grzyby pointer bump, two changelog posts"
requirement: SC-5
verification:
- kind: other
ref: "task 5 automated verify on the hold branch (no v0.6.7 in summercms.go, no v0.1.8 in sm-oauthserver-plugin): exit 0"
status: pass
human_judgment: true
rationale: "The checkpoint answer was hold. The release is pending the user's go-ahead after verification; SC-5 is not met yet."
duration: 48min
completed: 2026-11-21
status: complete
---
# Phase 32.2 Plan 05: tests, regression runs and release gate Summary
**An OAuth administrator grant and a `g15_` token with equal scopes now provably see and call the same MCP tools. Unit tests cover SC-1 to SC-3 in wristband, pier, cabana, the admin SPA and sm-oauthserver-plugin. Regression runs in five repos show user mode is unchanged. One real bug came out of the tests: `admin:reset-password` never ran its listeners' after-commit work, and it is now fixed. The release checkpoint answered hold, so nothing was tagged, pushed or posted.**
## Performance
- **Duration:** about 48 min
- **Started:** 2026-11-21T00:41:38Z
- **Completed:** 2026-11-21T01:29Z
- **Tasks:** 5 of 5 (task 4 was the checkpoint, task 5 ran its hold branch)
- **Files modified:** 13 in summercms.go (tests, commands.go, deferred items, decision record), 8 in ../sm-oauthserver-plugin
## Accomplishments
- **Tracer (task 1), sm-oauthserver-plugin `bae8222`.** `TestBackendGrantToolsMatchPersonalToken` (`summercms_mcp`, Docker) runs the real flow: authorize, admin consent, token exchange and `/mcp` calls.
- `acme:read` lists and calls only the read-only backend tool.
- `acme` lists and calls the write tool.
- In both cases the tool list matches a `g15_` token with the same scopes, name for name.
- Revoking one connection from My account makes that bearer get 401, and the other client keeps working.
- **Framework unit tests (task 2), `7ecfa608`.**
- wristband: `TestAuthorizeConsentPath`, `TestAuthorizeDefaultScopes`.
- pier (Docker): `TestBackendOnlyGrant`, `TestLinkedGrantNoScopeLimit`.
- cabana: `TestTokenScopeNames`, `TestMCPAdminConsent`, `TestAccountContributionItems`, `TestBackendAccessRevokedEvent` (Docker, all seven D-13 sites).
- **Admin SPA tests (task 2), `1e00ed3d`.**
- New `ConnectView.test.ts` covers every C1 state, the `*` rule, no auto-allow, the Allow and Deny bodies through `window.location.assign`, forbidden schemes, switch account, 401/404 handling, focus and the profile fallback.
- router, LoginView and AccountContributions tests are extended: anonymous `/connect` goes to login and back, the login hint, `items` null versus `[]`, the `:title` confirm, 404 `item_gone` and 409 `action_stale`.
- **Plugin backend-mode tests (task 3), sm-oauthserver-plugin `793eadd`.** `TestBackendMode`, `TestBackendConsent`, `TestBackendSubjectMigration`, `TestBackendGrantRows`, `TestBackendRevokeFromAccount`, `TestBackendCascade`.
- **Regression runs (task 3).** Every command in task 3's verify exits 0 (see Verification).
- **Release gate (tasks 4 and 5).** The user answered **hold**.
- `32.2-05-release-decision.txt` records `hold`, `framework-base v0.6.6` and `plugin-base v0.1.7`.
- Task 5's automated verify passes on the hold branch (exit 0).
- No tag was created and nothing was pushed in any repo. No changelog script ran and nothing was deployed.
## Task Commits
| Task | Name | Repo | Commit |
|---|---|---|---|
| 1 | Tracer: OAuth administrator grant tools equal a `g15_` token's tools | sm-oauthserver-plugin | `bae8222` (test) |
| 2 | Framework unit tests (wristband, pier, cabana) | summercms.go | `7ecfa608` (test) |
| 2 | Admin SPA tests | summercms.go | `1e00ed3d` (test) |
| 3 | Plugin backend-mode unit tests | sm-oauthserver-plugin | `793eadd` (test) |
| 3 | Rule 1 fix: admin:reset-password in a lagoon transaction | summercms.go | `b1b96d85` (fix) |
| 3 | TestPHPMethodMap: map AuthorizeResolveUserJwtOnlyTest | sm-oauthserver-plugin | `1124fd1` (test) |
| 3 | Deferred items after the plugin tests | summercms.go | `fc90a547` (docs) |
| 4 | Checkpoint: whether to tag, push and post the changelog | - | answered hold |
| 5 | Release only if the checkpoint accepted it | summercms.go | decision record, in the plan metadata commit |
`commits: 4` in the frontmatter is measured with the framework ledger (`d450a681..fc90a547`). The three plugin commits are local to `../sm-oauthserver-plugin`, which is now 6 commits ahead of `origin/master` (plans 03 and 05). Nothing was pushed.
Tracer gate: auto mode is off, human_verify_mode is end-of-phase and task 1's `<verify>` is automated-only. The verify ran again and passed, so the plan continued to task 2.
## Files Created/Modified
- `modules/wristband/consent_path_test.go`: consent handoff path and default scopes
- `modules/pier/backend_only_grant_test.go`: backend-only grants and the linked-grant regression
- `modules/cabana/{token_scope_names,mcp_admin_consent,account_items,backend_access_revoked}_test.go`: the SC-1 and SC-3 cabana tests
- `modules/cabana/export_test.go`: `FireBackendAccessRevokedForTest`, used by the de-duplication case
- `modules/cabana/commands.go`: `admin:reset-password` in `lagoon.Transaction`
- `admin/tests/views/ConnectView.test.ts` (new), `admin/tests/app/router.test.ts`, `admin/tests/views/LoginView.test.ts`, `admin/tests/account/AccountContributions.test.ts`
- `../sm-oauthserver-plugin/backend_{tools,mode,consent,subject_migration,grant_rows,revoke}_test.go`, `jwt_only_test.go`, `testdata/php_methods.txt`, `testdata/PHP_METHOD_MAP.md`
- `.planning/phases/32.2-mcp-oauth-with-administrator-subjects/deferred-items.md`, `32.2-05-release-decision.txt`
## Decisions Made
See key-decisions in the frontmatter.
**Release decision: hold. The release is pending the user's go-ahead after verification.** When the user says go, task 5's tag-and-publish branch runs in this order:
1. Tag the framework's next free v0.6 patch (v0.6.7 if still free) on master. It must contain every earlier tag and `b1b96d85`.
2. Point sm-oauthserver-plugin's go.mod at that framework tag, regenerate plugin.yaml, then tag v0.1.8 and push it.
3. Commit the grzyby pointer and go.mod bump to v0.1.8 as a separate commit, after the plugin push.
4. Publish the two changelog posts the same day.
The decision record is not rewritten if the bases move. Recompute the bases at release time.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 1 - Bug] admin:reset-password skipped its listeners' after-commit work**
- **Found during:** Task 3 (regression runs, D-13 site coverage)
- **Issue:** The reset fired `BackendAccessRevokedEvent` inside a plain GORM transaction, and `lagoon.AfterCommit` refuses to run there. As a result the plugin's revoked `MCPSubjectChanged` events, which end MCP sessions, never ran for this D-13 site.
- **Fix:** The command now runs in `lagoon.Transaction`. `TestBackendAccessRevokedEvent` asserts that the after-commit callback runs once for a committed reset and does not run for a vetoed one.
- **Files modified:** `modules/cabana/commands.go`, `modules/cabana/backend_access_revoked_test.go`
- **Committed in:** `b1b96d85`
**2. [Rule 3 - Blocking] TestPHPMethodMap failure (pre-existing, logged by plan 03)**
- **Found during:** Task 3 (full plugin suite)
- **Issue:** The PHP reference tree gained `AuthorizeResolveUserJwtOnlyTest`, and its five methods were unmapped, so the plugin's full `go test ./...` could not pass.
- **Fix:** Three methods are ported as adapted subtests of `TestAuthorizeResolveUserJwtOnly`. Two are marked not applicable, because the Go plugin resolves users from the session JWT only.
- **Committed in:** sm-oauthserver-plugin `1124fd1`; deferred-items.md updated in `fc90a547`
**3. [Rule 3 - Blocking] TestBackendCascade hit the plugin's register and token throttles**
- **Found during:** Task 3
- **Fix:** The test rotates six fresh OAuth clients instead of reusing one. The throttles are not relaxed.
- **Committed in:** sm-oauthserver-plugin `793eadd`
**4. [Rule 3 - Blocking] De-duplication case needed an internal hook**
- **Fix:** `cabana.FireBackendAccessRevokedForTest` lives in `export_test.go`, so the package's exported API is unchanged.
- **Committed in:** `7ecfa608`
---
**Total deviations:** 4 (1 Rule 1, 3 Rule 3). **Impact:** the Rule 1 fix closes a real gap in session termination after a password reset. The other three are test plumbing only, with no scope creep.
## Issues Encountered
- The first `npm --prefix admin run test:browser` run hit a Vite dynamic-import flake under load in the code editor test files. The rerun passed (4 files, 13 tests) with no code change.
- A pre-existing behaviour was logged to deferred-items.md and not changed: an authorize request whose only scope is `offline_access` stores no data scope. User mode behaves the same way.
## Verification
Regression exit codes (task 3; logs in the session scratchpad, `r1-*.log` to `r5-bm.log`):
| Run | Exit |
|---|---|
| framework `go vet ./...` | 0 |
| framework `go test -count=1 ./...` (47 packages, Docker) | 0 |
| framework `go test -count=1 -tags summercms_mcp ./modules/pier ./modules/surf` | 0 |
| plugin `go vet` (both tag sets) | 0 |
| plugin `go test -count=1 ./...` | 0 |
| plugin `go test -count=1 -tags summercms_mcp ./...` | 0 |
| admin `typecheck` | 0 |
| admin `test` (117 files, 1729 tests) | 0 |
| admin `test:browser` (rerun, 4 files, 13 tests) | 0 |
| `scripts/check-admin-openapi.sh --check` | 0 |
| `scripts/check-admin-dist.sh` | 0 |
| `go test ./cmd/summer -run TestDocsTree` | 0 |
| `go run ./cmd/summer docs:build --check` | 0 |
| grzyby `scripts/smoke-mcp-oauth.sh` (`ok (12 steps)`) | 0 |
| grzyby `scripts/check-deploy.sh` | 0 |
| grzyby `go test -count=1 -tags summercms_mcp,nodynamic ./...` | 0 |
| sm-bm-app via scratch go.work: `vet -tags summercms_mcp` / `test -tags summercms_mcp` | 0 / 0 |
| task 5 verify (hold branch) | 0 |
The grzyby runs used the plugin working tree at local `4c209c1` and later. The grzyby gitlink is still uncommitted (` M plugins/golem15/oauthserver`) until the release.
**Human verification, open (UNVERIFIED, not a failure):** the D-03 `SameSite=Strict` admin cookie on a real cross-site connector redirect chain (RESEARCH A2, the fifth UI backstop, the VALIDATION.md manual-only row). It is routed to `../sm-grzybyfunkcjonalne-app/DEPLOY.md`, "Live connector check (deferred)", and runs after the deferred production deploy on the user's go-ahead. The phase VERIFICATION.md must list it under human verification with status unverified. No test in this plan claims to cover it.
## Known Stubs
None.
## Threat Flags
None beyond the plan's threat model:
- T-32.2-26: the tests assert status codes and ids, and the smoke output carries no tokens or codes. No changelog script ran, so the journal token was never read.
- T-32.2-27: the blocking checkpoint held. No tag and no push.
## User Setup Required
None.
## Next Phase Readiness
- Phase 32.2 is ready for `/msd-verify-work`.
- The release waits for the user's go-ahead, following the task 5 order above.
- Still not done: the plugin's 6 local commits are unpushed, the grzyby gitlink is uncommitted, and the DEPLOY.md minimum-version wording can name v0.1.8 once it exists.
- STATE.md and ROADMAP.md were not touched by this plan, as the orchestrator instructed.
## Self-Check: PASSED
- Files exist: the wristband, pier and cabana test files, `admin/tests/views/ConnectView.test.ts`, `../sm-oauthserver-plugin/backend_tools_test.go`, `../sm-oauthserver-plugin/backend_revoke_test.go` and `32.2-05-release-decision.txt`.
- Framework commits `7ecfa608`, `1e00ed3d`, `b1b96d85` and `fc90a547` exist, as do plugin commits `bae8222`, `793eadd` and `1124fd1`.
- There is no `v0.6.7` tag in summercms.go and no `v0.1.8` tag in sm-oauthserver-plugin.

View File

@@ -0,0 +1,3 @@
tag-and-publish
framework-base v0.6.6
plugin-base v0.1.7

View File

@@ -0,0 +1,124 @@
# Phase 32.2: MCP OAuth with administrator subjects - Context
**Gathered:** 2026-11-20
**Status:** Ready for planning
<domain>
## Phase Boundary
An application whose MCP tools are backend-guarded and which has no frontend users (first consumer: sm-grzybyfunkcjonalne-app, Journal tools only) can accept MCP OAuth sign-in as an **administrator**. The work is an additive, off-by-default backend-subject mode of `sm-oauthserver-plugin`, the `summercms.go` pieces it needs (pier resolution of administrator-only grants, a configurable consent handoff in wristband, an admin SPA consent route), and the grzyby wiring. The existing frontend-user MCP OAuth flow (sm-bm-app, sm-demo-app: Nuxt `/connect`, verified account link for backend tools) behaves exactly as before.
Ends at a local-stack proof, patch tags, an app pointer bump and DEPLOY.md. The production deploy of grzybyfunkcjonalne.pl happens separately, on the user's go-ahead.
</domain>
<decisions>
## Implementation Decisions
### Framing (from the /msd-explore session, `.planning/notes/2026-11-20-mcp-oauth-backend-subject.md`)
- **D-01:** On a backend-mode application, the OAuth sign-in authenticates an administrator (`backend_users`). No frontend user and no account link is involved; the grant subject is the administrator.
- **D-02:** It is a mode of `sm-oauthserver-plugin`, not a new framework module. Code stores, PKCE, refresh rotation, replay-family revocation, the Clients and Branding screens and pruning are reused. Every change to the plugin is additive. `sm-oauthserver-plugin`, `sm-user-plugin`, `sm-journal-plugin` and the framework are shared by many apps, so no breaking changes. — **Reversibility:** costly — the mode becomes a public config key and a grant shape other apps may adopt.
### Consent surface
- **D-03:** Consent lives in the **admin SPA** (boardwalk, `admin/`) as a route under the admin prefix (working shape `/<admin prefix>/connect?request=…`), not as a Go-rendered page and not in Nuxt. Reason: the admin cookie `summer_admin` is `Path=<admin prefix>`, `SameSite=Strict` (`modules/cabana/auth.go` `sessionCookie`). It never reaches `/oauth/mcp/authorize` at the root, and it isn't sent on the cross-site navigation from the MCP client. A route inside the SPA gets it on its same-origin API fetches, and the SPA router already sends an anonymous visitor to login with `?redirect=` and back (`admin/src/app/router.ts` `safeRedirect`). Login gates (2FA, Turnstile) therefore apply unchanged.
- **D-04:** wristband's MCP authorize handoff, currently hard-wired to `{issuer}/connect?request=` (`modules/wristband/authorize.go`), becomes configurable so backend mode can point it at the admin SPA route. The default stays `/connect`. — **Reversibility:** costly — wristband option and oauthserver config key are public API.
- **D-05:** The consent screen is a **standalone full-screen card** like `LoginView` (no sidebar or top bar). It shows the client name, the redirect host, the scope checkboxes and the refresh choice, with Allow and Deny.
- **D-06:** The consent screen shows the signed-in administrator ("Signed in as <name> (<email>)") with a **"use another account"** action. That action signs out and goes back to login with the same redirect, like the 19.4 OIDC switch-account flow.
### Mode per application
- **D-07:** The mode is **exclusive per application for now**: a config key on `golem15.oauthserver` (working name `mcp.subject`, values `user` (default) and `backend`). One issuer, one `/mcp` resource, one consent surface per app. Pick a config shape that doesn't block coexisting modes later (see Deferred). — **Reversibility:** costly — config key name and values become part of the plugin's contract.
- **D-08:** `sm-oauthserver-plugin` keeps `Requires() = ["golem15.user"]` in backend mode. grzyby mounts golem15.user anyway, and the core plugin's dependency graph stays untouched.
### Consent choices
- **D-09:** The scopes on consent are the **cabana token-scope catalog**, the same as `g15_` personal-token creation (`modules/cabana/token_scopes.go`: `*`, `admin:read` and the plugin-declared `TokenScopes()` such as the Journal's). A backend-mode grant gets the same `bouncer.ScopeLimit` a personal token with those scopes would (`cabana.ScopeLimitFor`). An OAuth agent and a `g15_` token with equal scopes therefore see and can call the same tools. This differs from today's linked-admin grants, which carry no scope limit (`modules/pier/backend_guard.go` `principal` applies the limit only when `ClientID == ""`). That existing behaviour must not change for user-mode grants. In backend mode the advertised `scopes_supported` (wristband metadata and pier's protected-resource metadata) come from this catalog.
- **D-10:** `offline_access` appears as a **"Stay connected" checkbox, ticked by default**, as in 32.1's `/connect`. Unticked, the agent gets no refresh token and re-consents when the access token expires.
- **D-11:** Scopes the administrator can't use (they lack the scope's permissions) are **hidden** from the consent screen. A request that asked for them gets only what is ticked and granted.
### Revocation and visibility
- **D-12:** Each administrator lists and revokes their own MCP connections in a **My account section** (`pact.HasAccountContributions`). A superuser, or an administrator holding a new oauthserver permission, can see and revoke any administrator's connections on the existing oauthserver admin screens.
- **D-13:** An administrator's MCP grants (access and refresh tokens) are revoked, and their open MCP sessions ended (`pact.MCPSubjectChanged`), on: **delete, deactivate, password change, role or permission change** (including the role's own permissions changing) and **"sign out everywhere"** where cabana offers it. Role and permission changes revoke the grants rather than only re-listing tools.
### Rollout
- **D-14:** sm-grzybyfunkcjonalne-app mounts `golem15.oauthserver` in backend mode with only the MCP authorization server enabled (no OIDC provider surface), keeps `allow_personal_tokens: true`, routes `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource` and `/oauth/mcp/*` to the Go binary, and documents it in DEPLOY.md. Proof: on a local stack, an MCP client completes discovery, dynamic registration, admin sign-in, consent and a Journal tool call. The production deploy is not part of this phase.
### Claude's Discretion
- How backend-mode grants are stored. The current tables have `user_id INTEGER NOT NULL REFERENCES users(id)` on access tokens, auth codes and consents (`updates/202610190001_create_golem15_oauthserver_tables.go`). Options: nullable `user_id` via an additive migration with the readers that assume it hardened, or companion rows keyed on `backend_user_id`. Constraints: additive only, user-mode rows and queries unchanged, and the per-user advisory lock and revocation cascade keep working.
- How pier represents an administrator-only grant (for example `pact.MCPGrant` with `UserID` 0 and `BackendUserID` set, resolved straight to the `backend` subject, with no `MCPLinkedBackendResolver` lookup). Additive to `pact`.
- Where the consent JSON API lives (oauthserver routes under the admin API, authenticated by the cabana guard) and how the framework SPA route renders a consent screen whose data a plugin serves. The admin SPA can't load plugin Vue code, so the screen is framework code against a JSON contract.
- The name of the new "manage any administrator's MCP connections" permission and its default role (none, like `golem15.users.manage_backend_links`).
- Whether `*` and `admin:read` are shown as plain scope checkboxes or as "full access" / "read only" presets above the plugin scopes.
</decisions>
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Decisions behind this phase
- `.planning/notes/2026-11-20-mcp-oauth-backend-subject.md`: why administrator subjects, why an oauthserver mode, first change list and open questions. D-03 refines its "server-rendered Go consent page": consent moves to the admin SPA because of the cookie scope.
- `.planning/notes/2026-10-17-generic-mcp-module.md`: the original MCP shape (one connector per person, verified account link, Journal stays on `backend_users`). Backend mode is the second path next to it, not a replacement.
- `.planning/notes/oauth2-wristband-direct-port.md`: wristband's design constraints (RFC behaviours that must stay byte-exact).
- `.planning/ROADMAP.md` Phase 32.2: goal and success criteria. Phases 32.1, 19.7 and 19.4 for the prior MCP OAuth, MCP module and OIDC decisions.
### Prior phase context
- `.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/`: declared scopes, MCP consent records, per-client revoke, the `/connect` checkboxes.
- `.planning/phases/19.4-*/`: wristband OIDC flavour, switch-account flow, consent store, sm-oauthserver-plugin creation.
### Module and plugin docs
- `modules/wristband/README.md`, `modules/pier/README.md`, `modules/cabana/README.md`, `modules/boardwalk/README.md`
- `../sm-oauthserver-plugin/README.md`
- `../sm-user-plugin/README.md` §"Frontend account link for administrators" and §"MCP guard": how user-mode backend grants work today (must stay unchanged).
- `../sm-journal-plugin/mcp.go`: the backend-guarded tools grzyby exposes.
- `../sm-grzybyfunkcjonalne-app/config/mcp.yaml`, `summer.yaml`, `DEPLOY.md`; `../sm-bm-app/config/golem15.oauthserver.yaml` (a user-mode configuration example).
</canonical_refs>
<code_context>
## Existing Code Insights
### Reusable Assets
- `wristband.Server.Authorize` / MCP code, token, register handlers: the whole OAuth protocol side; only the handoff URL and subject binding change.
- `sm-oauthserver-plugin/classes/mcp_backend_binding.go` (`WithConsentedBackend`, `backendBinding`): already carries `BackendUserID` from consent onto codes and tokens; backend mode sets it without the `backend` scope or a user.
- `sm-oauthserver-plugin/controllers/mcp_consent_api.go` (`MCPConsentShow`, `MCPConsentDecide`): the consent JSON the Nuxt `/connect` uses; the admin-side counterpart mirrors it under the cabana guard.
- `cabana.ScopeLimitFor`, the token-scope catalog and `cabana.BackendPrincipal`: scope limits and principal loading for D-09.
- `admin/src/views/LoginView.vue`, `admin/src/app/router.ts` (`safeRedirect`, login redirect): standalone screen pattern and sign-in round trip for D-03, D-05, D-06.
- `pact.HasAccountContributions` / `modules/cabana/account_contributions.go`: My account section for D-12 (sm-user-plugin's `frontend_account` section is the example).
### Established Patterns
- `pier/identity.go`: `identityResolver` builds the backend subject; `consentedBackendSubject` is the user-mode path that must stay as is. `LinkCacheTTL` and the `MCPSubjectChanged` events show how changes propagate.
- `pier/backend_guard.go`: the scope limit applies only to personal-token subjects today. Backend-mode OAuth subjects need it too (D-09) without changing user-mode linked grants.
- Off-by-default modes keep every existing test green (32.1 and 19.4 releases: patch tags for the framework and the plugin).
### Integration Points
- `golem15.oauthserver` config: new subject mode key, consent handoff path.
- cabana events for D-13 (delete, deactivate, password change, role and permission saves, sign out everywhere). Some may need new additive hooks in cabana.
- grzyby proxy (nginx/Caddy in `deploy/`) for the OAuth paths. Today Nuxt answers everything except the Go API prefixes.
</code_context>
<specifics>
## Specific Ideas
- The consent screen should look like an authorization step, not an admin page: same card style as the admin login.
- OAuth agents and `g15_` tokens with equal scopes must behave identically. That's the mental model for administrators.
- Revocation is strict: any role or permission change ends the grants instead of quietly re-listing tools.
</specifics>
<deferred>
## Deferred Ideas
- **Both subject modes on one application** (for example the demo offering member and administrator connectors, through two resources or a choice at authorize). Exclusive per app for now (D-07); the config shape should leave room for it.
- **Production deploy of grzybyfunkcjonalne.pl with OAuth on** and a live check with the Claude connector: after the phase, on the user's go-ahead.
- **Backend mode without golem15.user** for apps that mount no user plugin (D-08 keeps the dependency).
### Reviewed Todos (not folded)
- "Benchmark Płytarium on WinterCMS vs SummerCMS", "Record PHP OIDC parity against WavePath" (belongs to Phase 31-08), "Earlier phase gate scripts still name consuming applications", "Translate Messages as a Nuxt i18n JSON editor": keyword matches only, unrelated to this phase.
</deferred>
---
*Phase: 32.2-mcp-oauth-with-administrator-subjects*
*Context gathered: 2026-11-20*

View File

@@ -0,0 +1,95 @@
# Phase 32.2: MCP OAuth with administrator subjects - 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-20
**Phase:** 32.2-mcp-oauth-with-administrator-subjects
**Areas discussed:** Consent surface, Mode per app, Consent choices, Revocation & visibility, Rollout
Scout finding presented first: `summer_admin` is `Path=<admin prefix>`, `SameSite=Strict`, so a root-level authorize or a cross-site navigation never sees it. That ruled out the exploration note's "authorize reads the cookie, Go renders consent".
---
## Consent surface
| Option | Description | Selected |
|--------|-------------|----------|
| Admin SPA route | /smbackend/connect in boardwalk; reuses login redirect and same-origin cookie fetch; wristband handoff configurable | ✓ |
| Go page under prefix | Server-rendered at /smbackend/oauth/connect, JS same-origin fetch to learn the admin | |
| You decide | Planner picks | |
| Option | Description | Selected |
|--------|-------------|----------|
| Standalone screen | Full-screen card like LoginView | ✓ |
| Inside admin chrome | Normal admin page | |
| Option | Description | Selected |
|--------|-------------|----------|
| Show + switch | Signed-in admin plus "use another account" | ✓ |
| Show only | Account shown, no switch | |
## Mode per app
| Option | Description | Selected |
|--------|-------------|----------|
| Exclusive per app | mcp.subject user / backend | |
| Both coexist | One app accepts both | |
| Exclusive now, coexist later | Ship exclusive, defer coexistence, keep config shape open | ✓ |
| Option | Description | Selected |
|--------|-------------|----------|
| Keep requiring golem15.user | No Requires() change | ✓ |
| Make it optional | Backend mode without the user plugin | |
## Consent choices
| Option | Description | Selected |
|--------|-------------|----------|
| Cabana token scopes | Same catalog and ScopeLimit as g15_ tokens | ✓ |
| All-or-nothing | Full admin permissions | |
| Read vs read+write | admin:read vs * | |
| Option | Description | Selected |
|--------|-------------|----------|
| Checkbox, on by default | "Stay connected" offline_access | ✓ |
| Always | Always refreshable | |
| Never | Re-authorize on expiry | |
| Option | Description | Selected |
|--------|-------------|----------|
| Show disabled + explain | Greyed out with reason | |
| Hide them | Only usable scopes listed | ✓ |
| You decide | Planner chooses | |
## Revocation & visibility
| Option | Description | Selected |
|--------|-------------|----------|
| My account + superuser screen | Own list on My account; superuser/permission sees all | ✓ |
| My account only | No global view | |
| Admin screens only | Behind a permission | |
Kill triggers (multi-select): Delete / deactivate ✓, Password change ✓, Role / permission change ✓, Sign out everywhere ✓.
## Rollout
| Option | Description | Selected |
|--------|-------------|----------|
| Local proof, deploy separately | Tags, pointer bump, DEPLOY.md; deploy on go-ahead | ✓ |
| Include prod deploy | Deploy checkpoint and live connector check | |
| Explore more gray areas | Keep discussing | |
## Claude's Discretion
- Storage of administrator-only grants (nullable user_id vs companion rows), additive only.
- pact/pier representation of an administrator-only grant.
- Location of the consent JSON API and the SPA ↔ plugin contract.
- Name and default role of the "manage any administrator's MCP connections" permission.
- Presentation of `*` / `admin:read` (plain checkboxes or presets).
## Deferred Ideas
- Both subject modes on one application.
- Production deploy of grzybyfunkcjonalne.pl with OAuth.
- Backend mode without golem15.user.

View File

@@ -0,0 +1,239 @@
# Phase 32.2: MCP OAuth with administrator subjects - Pattern Map
**Mapped:** 2026-11-20
**Files analyzed:** 30 (file list from 32.2-RESEARCH.md "Recommended file layout")
**Analogs found:** 28 / 30
Repos: `F` = summercms.go, `P` = ../sm-oauthserver-plugin, `U` = ../sm-user-plugin, `G` = ../sm-grzybyfunkcjonalne-app, `B` = ../sm-bm-app. All analog paths are git-tracked source (no `.msd/` mirrors).
## File Classification
| New/Modified File | Role | Data Flow | Closest Analog | Match |
|---|---|---|---|---|
| F `modules/pact/mcp.go` (MCPGrant.Subject, MCPSubject.ScopeLimited, MCPAdminConsent) | model/contract | request-response | same file: `MCPGrant` (l.280-292), `MCPLinkedBackendResolver` (l.314-323) | exact |
| F `modules/pact/capabilities.go` (AccountContribution.Items/ItemActions) | contract | CRUD | same file `AccountContribution`/`AccountAction` (l.614-640) | exact |
| F `modules/wristband/server.go` (Options.ConsentPath, DefaultScopes) | config | - | same file `Options` (l.26-60), `ScopesSupported` empty→default doc (l.36-40) | exact |
| F `modules/wristband/authorize.go` | controller | request-response | same file l.187 handoff | exact |
| F `modules/pier/identity.go` | service | request-response | same file `resolveOAuth` (l.204-238), `consentedBackendSubject` (l.240) | exact |
| F `modules/pier/backend_guard.go` | middleware/guard | request-response | same file `principal` (l.105-122) | exact |
| F `modules/cabana/mcp_consent.go` (new) | controller | request-response | `modules/cabana/account_contributions.go` (l.98-233) + P `controllers/mcp_consent_api.go` (body shapes) | role-match |
| F `modules/cabana/token_scopes_export.go` (new) | utility | transform | `modules/cabana/token_scopes.go` (`ownerHas` l.237, `scopeOverlaps` l.333, `methodFilterScopes` l.365) | exact |
| F `modules/cabana/admin_events.go` (new BackendAccessRevokedEvent) | event | event-driven | U `classes/events.go` `AccessRevokedEvent` (l.112-130); F `modules/cabana/subject_events.go` (l.25-60) | exact |
| F `modules/cabana/account_contributions.go` | controller | CRUD | same file | exact |
| F `modules/cabana/admin_openapi.go` | config (docs) | - | same file l.370-395 (account contributions annotations) | exact |
| F `admin/src/views/ConnectView.vue` (new) | component | request-response | `admin/src/views/LoginView.vue` (101 lines) | exact (standalone card) |
| F `admin/src/app/router.ts` | route | - | same file l.62 (`/login`), l.74 (`/account`), guard l.90-101 | exact |
| F `admin/src/components/account/AccountContributions.vue` | component | CRUD | same file (160 lines); `ApiTokensPanel.vue` for per-row revoke list | exact |
| F `admin/openapi/admin.json`, `admin/src/api/schema.d.ts` | generated | - | `scripts/check-admin-openapi.sh` | generated |
| F `modules/boardwalk/dist` | generated | - | `scripts/check-admin-dist.sh` | generated |
| P `updates/2026112xxxxx_add_golem15_oauthserver_backend_subjects.go` | migration | batch | P `updates/202610230001_add_backend_user_id.go` | exact |
| P `classes/mcp_store.go` | store | CRUD | same file `MarkIssued` (l.262-287), `ByCodeHashForUpdate` (l.192), `Create` (l.300), `ByTokenHashForUpdate`/`refreshUserUsable` (l.334-377) | exact |
| P `classes/mcp_backend_subject.go` (new) | utility | request-response | P `classes/mcp_backend_binding.go` (ctx keys l.11-62, locks l.73-110) | exact |
| P `classes/mcp_verifier.go` | service | request-response | same file `MCPVerifyToken` (l.83-145) | exact |
| P `classes/backend_cascade.go` (new) | listener | event-driven | P `classes/cascade.go` (l.1-80) + `classes/subject_events.go` (`FireSubjectChangedAfterCommit` l.25) | exact |
| P `controllers/mcp_admin_consent.go` (new) | controller/provider | request-response | P `controllers/mcp_consent_api.go` | exact |
| P `controllers/mcp_connections.go` (new admin list screen) | controller | CRUD | P `controllers/clients.go` + `controllers/clients/` YAML; U `backend_links_admin.go` | role-match |
| P `account.go` (new HasAccountContributions) | provider | CRUD | U `account_contributions.go` (l.1-80) | exact |
| P `admin_permissions.go` / `admin_navigation.go` | config | - | same files (`Permissions()` l.10-23) | exact |
| P `servers.go` / `routes.go` / `config/config.yaml` | config/route | - | same files; `routes.go` `GroupRaw` blocks (l.32-85); `config.yaml` comment style (l.1-36) | exact |
| G `summer.yaml`, `.gitmodules`, `go.mod`, `go.work` | config | - | G `summer.yaml` plugins (l.8-24) ; B for oauthserver entry | exact |
| G `config/golem15.oauthserver.yaml` | config | - | B `config/golem15.oauthserver.yaml` | exact |
| G `deploy/nginx/*.conf` | config | - | B `deploy/nginx/bm.jakubzych.com.conf` (l.1-10, 97-110) | exact |
| G `scripts/smoke-mcp-oauth.sh`, `DEPLOY.md` | test/docs | - | none tracked for full OAuth dance (see No Analog) | partial |
## Pattern Assignments
### F `modules/pact/mcp.go`
**Analog:** same file, `MCPGrant` l.280-292. Add fields additively with doc comments in the same voice; zero value must mean today's behaviour.
```go
type MCPGrant struct {
UserID uint
ClientID string
TokenID uint
Scopes []string
ExpiresAt time.Time
// BackendUserID is the backend account the consent page showed ...
BackendUserID uint
}
```
`MCPSubject` (l.134-140) is `{Guard, UserID, Scopes, ClientID, TokenID}`; add `ScopeLimited bool` there. A new provider interface (`MCPAdminConsent`) follows `MCPLinkedBackendResolver` (l.314-323): single-method-ish interface published through `app.Lookup[...]`, plus a plain view struct like `LinkedBackendUser`. Subject-changed kinds: reuse `MCPSubjectRevoked`/`MCPSubjectDeleted`/`MCPSubjectPermissions` (l.347-353), do not add kinds unless needed.
### F `modules/pact/capabilities.go`
**Analog:** `AccountContribution` l.614-620 and `AccountAction` l.629-640:
```go
type AccountContribution struct {
Name string
Label string
Description string
Status func(ctx context.Context, adminID uint) (string, error) `json:"-"`
Actions []AccountAction
}
```
Add `Items func(ctx, adminID uint) ([]AccountItem, error) \`json:"-"\`` and `ItemActions []AccountAction` (or a sibling item-action type with `Run(ctx, adminID, itemID)`). Nil keeps existing plugins (U) unchanged.
### F `modules/wristband/server.go` + `authorize.go`
**Analog:** `Options.ScopesSupported` doc (l.36-40): "empty or nil resolves to PHP default". Use the same rule for `ConsentPath` (empty → `/connect`). Change only l.187:
```go
spa := s.opts.Issuer + "/connect?request=" + rfc3986Escape(requestID)
```
→ `s.opts.Issuer + consentPath + "?request=" + ...`. Default bytes must stay identical (PHP parity, `.planning/notes/oauth2-wristband-direct-port.md`); also update l.43 comment.
### F `modules/pier/identity.go`
**Analog:** `resolveOAuth` l.204-238 builds `Identity` and calls `consentedBackendSubject(ctx, grant.UserID, grant.ClientID, grant.TokenID, scopes, grant.BackendUserID)` (l.231). Add an early branch: when `grant.Subject == pact.MCPGrantSubjectBackend` (or `UserID==0 && BackendUserID!=0`), set only `id.Backend = &pact.MCPSubject{Guard: backend, UserID: grant.BackendUserID, Scopes, ClientID, TokenID, ScopeLimited: true}`; no frontend subject, no `linkedBackend` (l.309-325) lookup.
### F `modules/pier/backend_guard.go`
**Analog:** `principal` l.105-122:
```go
if subject.ClientID == "" && subject.TokenID != 0 {
limit, known, _ := cabana.ScopeLimitFor(g.app, subject.Scopes, method)
if known == 0 {
return nil, errScopeUnavailable
}
if limit == nil {
limit = &bouncer.ScopeLimit{}
}
principal.Scope = limit
}
```
Extend the condition to `(subject.ClientID == "" && subject.TokenID != 0) || subject.ScopeLimited`; user-mode linked grants (ScopeLimited false) unchanged (D-09).
### F `modules/cabana/mcp_consent.go` (new)
**Analog:** `modules/cabana/account_contributions.go` handlers l.98-233.
- Auth: `principal := accountPrincipal(w, r); if principal == nil { return }`
- Lookup provider: `app.Lookup[pact.MCPAdminConsent]()`; absent → `WriteError(w, http.StatusNotFound, "not_found", msgNotFound)`.
- Response: `WriteData(w, http.StatusOK, view, map[string]any{})`; errors via `WriteError(w, status, code, msg)`; log with `moduleLog.ErrorContext(ctx, "cabana: ...", ...)`.
- Translation: `translateKey(ctx, s.translator(), key)`.
- Transaction for the decision POST: same as `accountContributionAction` (Run inside a tx carried by context, `TxFromContext`).
- Route path `r.PathValue("request")`. Body shapes for client/scope lists copy P `controllers/mcp_consent_api.go` `mcpConsentClient`, `mcpScopeDetail`, `mcpConsentShowBody` (l.35-60) so the SPA mirrors 32.1's `/connect` shape.
### F `modules/cabana/token_scopes_export.go` (new)
**Analog:** `modules/cabana/token_scopes.go`: catalog `tokenScopeCatalog` (l.32), `ownerHas(p, code)` (l.237), `scopeOverlaps(reg, owner, name)` (l.333). Export `TokenScopeNames(app)` and a grantable-for-principal view; D-11 hide = filter with `scopeOverlaps`. Exported funcs taking `*backpack.App` follow `ScopeLimitFor(app, scopes, method)` (tested in `scope_limit_for_test.go`). Docs checker: add to cabana README API reference.
### F `modules/cabana/admin_events.go` (new)
**Analog:** U `classes/events.go` l.112-117:
```go
type AccessRevokedEvent struct {
UserIDs []uint
Before time.Time
Reason string
Tx *gorm.DB
}
```
Model `BackendAccessRevokedEvent{AdminIDs []uint; Reason string; Tx *gorm.DB}` with Reason constants (deleted, deactivated, password, permissions, sign_out_everywhere). Fire synchronously inside the save tx (listener failure rolls back, like U); the `MCPSubjectChanged` after-commit fan-out copies `fireSubjectChanged` (`subject_events.go` l.25-48: `lagoon.AfterCommit(ctx, tx, func(...){ app.Events.Fire(ctx, &pact.MCPSubjectChanged{Guard: backendSubjectGuard, ...}) })`). Call sites: the places that already call `fireSubjectChanged` (grep `fireSubjectChanged(` in cabana: backend users admin, account, commands).
### F `modules/cabana/account_contributions.go`
**Analog:** same file. Items list goes in the per-section loop of `accountContributionsList` (l.105-150), same error policy: a failing `Items` sets `view.Error = true` and logs, never hides other sections. Item action route copies `accountContributionAction` (l.160-233): 404 unknown, 403 `!Allows(principal, action.Permissions)`, 409 no longer applies, run in tx. Compile-time validation in `compileAccountContributions` (l.38).
### F `modules/cabana/admin_openapi.go`
**Analog:** l.370-395 (`@Summary List My account contributions` / `@Router /account/contributions [get]`). Add annotations for `/mcp/consent/{request} [get]`, `[post]`, item action route; then `scripts/check-admin-openapi.sh`.
### F `admin/src/views/ConnectView.vue` (new)
**Analog:** `admin/src/views/LoginView.vue` (whole file, 101 lines): `<script setup lang="ts">`, imports `t` from `../app/i18n`, `safeRedirect` from `../app/router`, `useAuth` state, lucide icons, `busy`/`failed` refs, guard against double submit:
```ts
async function submit(): Promise<void> {
if (busy.value) { return }
busy.value = true
failed.value = false
try { ... } finally { busy.value = false }
}
```
Template: same standalone card markup as LoginView (no shell). "Use another account" = logout from `state/useAuth` then `router.replace({ name: 'login', query: { redirect: route.fullPath } })`. Final Allow/Deny answer is a `window.location.assign(redirect_url)` (cross-origin client redirect). Follow 32.2-UI-SPEC.md for copy and states.
### F `admin/src/app/router.ts`
**Analog:** l.62 and guard l.90-101:
```ts
{ path: '/login', name: 'login', component: LoginView, meta: { public: true } },
...
return { name: 'login', query: { redirect: to.fullPath } }
```
New: `{ path: '/connect', name: 'connect', component: ConnectView }` — no `meta.shell`, no `meta.public` (anonymous → login with redirect via existing guard). Verify `safeRedirect` (l.28-50) accepts `/connect?request=...`.
### F `admin/src/components/account/AccountContributions.vue`
**Analog:** same file (sections + actions + confirm dialog); per-item row list with revoke button copies `ApiTokensPanel.vue` (312 lines) list/revoke layout.
### P migration `updates/2026112xxxxx_add_golem15_oauthserver_backend_subjects.go`
**Analog:** `updates/202610230001_add_backend_user_id.go` (whole file):
```go
var addBackendUserID = []*gormigrate.Migration{
{
ID: "202610230001_add_golem15_oauthserver_backend_user_id",
Migrate: func(tx *gorm.DB) error {
return run(tx, []string{ `ALTER TABLE ... ADD COLUMN backend_user_id INTEGER NULL`, ... })
},
Rollback: func(tx *gorm.DB) error { return run(tx, []string{ ... }) },
},
}
func init() { Register(addBackendUserID...) }
```
SQL body: RESEARCH.md Pattern 1 (l.212-227). Doc comment explains rollback deletes backend rows.
### P `classes/mcp_backend_subject.go` (new)
**Analog:** `classes/mcp_backend_binding.go`: context key pattern l.11-62
```go
type consentedBackendKey struct{}
func WithConsentedBackend(ctx context.Context, backendUserID uint) context.Context {
return context.WithValue(ctx, consentedBackendKey{}, backendUserID)
}
func consentedBackendFrom(ctx context.Context) uint {
id, _ := ctx.Value(consentedBackendKey{}).(uint)
...
```
→ `WithBackendSubject(ctx)` / `backendSubjectFrom(ctx)`. Advisory locks copy `userGrantsLockKey`, `lockUserGrantsShared`, `LockUserGrants` (l.73-110) with a distinct key namespace for admins.
### P `classes/mcp_store.go`
**Analog:** `MarkIssued` l.262-287 column map:
```go
cols := map[string]any{
"request_id": nil, "code_hash": codeHash, "user_id": userID, ...
"backend_user_id": backendBinding(scopes, consentedBackendFrom(ctx)),
}
```
Backend ctx: `"user_id": nil, "backend_user_id": userID`. Same branching for `Create` (l.300), `ByCodeHashForUpdate` (l.192), `refreshUserUsable` (l.363), `refreshRecord`. Reader table: RESEARCH.md l.229-240.
### P `classes/mcp_verifier.go`
**Analog:** `MCPVerifyToken` l.83-145. Keep token/client checks (l.92-115); branch before `userclasses.PrincipalByID(ctx, db, token.UserID)` (l.117): when `token.UserID == nil/0 && token.BackendUserID != nil` → `cabana.BackendPrincipal(ctx, app, id)`, `issuedBeforeCutoff(token.CreatedAt, principal.TokensValidAfter)`, skip `ThrottleStates`, return grant with `Subject: backend, BackendUserID: id`. Note `models.AccessToken.UserID` must become a pointer/nullable (check model file).
### P `classes/backend_cascade.go` (new)
**Analog:** `classes/cascade.go`: `Cascade{App *backpack.App}`, handler signature `func (c Cascade) OnUserDeleting(ctx context.Context, ev *userclasses.DeletingEvent) error` with nil guards and `tx == nil → lookupDB(c.App)` fallback (l.31-60). Fire sessions-ended with `FireSubjectChangedAfterCommit(ctx, app, tx, guard, id, kind)` (`classes/subject_events.go` l.25). Register listener where `Cascade` is registered in `plugin.go`.
### P `controllers/mcp_admin_consent.go` (new)
**Analog:** `controllers/mcp_consent_api.go` (imports l.3-21, constants `mcpBackendScope`, `mcpOfflineAccessScope`, `maxMCPClientName`, view structs l.35-60, IssueCode with `classes.WithGrantedOfflineAccess`). Implements `pact.MCPAdminConsent`; issues with `classes.WithBackendSubject(ctx)` and the admin ID.
### P `controllers/mcp_connections.go` (new admin screen)
**Analog:** `controllers/clients.go` + `controllers/clients/` YAML (columns.yaml/config_list.yaml) and `controllers/admin_registry.go`; permission gating as in `admin_permissions.go`. Revoke action copies the per-client revoke from 32.1 (`controllers/authorizations.go`).
### P `account.go` (new)
**Analog:** U `account_contributions.go` l.15-55: `var _ pact.HasAccountContributions = (*Plugin)(nil)`, phrase-key prefix const, one contribution with `Status`, `Actions` gated by `Applies`; Danger+Confirm on revoke. Only offered when `mcp.subject == backend`.
### P `admin_permissions.go` / `admin_navigation.go`
**Analog:** `admin_permissions.go` l.10-23 — append `{Code: controllers.PermissionManageMCPConnections, Tab: "golem15.oauthserver::lang.plugin.tab", Label: "golem15.oauthserver::lang.permissions.manage_mcp_connections"}`; no default role.
### P `config/config.yaml`, `servers.go`, `routes.go`
**Analog:** config.yaml comment style l.1-36 (each key documented, PHP name or "(new)"). New keys `mcp.subject: user`, `mcp.consent_path: ""`, `oidc.enabled: true`. `routes.go` `GroupRaw` blocks l.32-85: gate OIDC groups behind `oidc.enabled`.
### G app wiring
- `summer.yaml` plugins list l.8-24: add `- id: golem15.oauthserver\n module: git.golem15.com/golem15/sm-oauthserver-plugin`.
- `config/golem15.oauthserver.yaml`: copy B's file header and `mcp.enabled/resource` block; add `mcp.subject: backend`, `mcp.consent_path: /<admin prefix>/connect`, `oidc.enabled: false`.
- nginx: G confs already proxy; copy B `bm.jakubzych.com.conf` l.97-110 comment and `location = /mcp`, and ensure `/oauth/` and `/.well-known/oauth-*` reach the Go binary.
- `.gitmodules`/`go.mod replace`/`go.work use`: copy existing `plugins/golem15/*` entries in G.
## Shared Patterns
- **Admin API auth/response (cabana):** `accountPrincipal(w, r)`, `Allows(principal, perms)`, `WriteData`, `WriteError`, `moduleLog.*Context` — `modules/cabana/account_contributions.go` l.98-233.
- **After-commit MCP session end:** cabana `fireSubjectChanged` (`subject_events.go` l.25-48); plugin `FireSubjectChangedAfterCommit` (P `classes/subject_events.go` l.25).
- **Event in transaction, listener failure rolls back:** U `classes/events.go` `AccessRevokedEvent` + P `classes/cascade.go`.
- **Context-carried flags into wristband store:** P `classes/mcp_backend_binding.go` l.11-62.
- **Migrations:** raw SQL slice through `run(tx, ...)` + `Register(...)` in `init()` (P `updates/`).
- **Additivity:** zero values = current behaviour in every new pact field / wristband option / config key (core plugins are shared).
## No Analog Found
| File | Role | Reason |
|---|---|---|
| G `scripts/smoke-mcp-oauth.sh` | test | No tracked script drives discovery + DCR + login + consent + tool call end to end; use RESEARCH.md flow and P `mcp_consent_smoke_test.go` harness for Go-side pieces |
| Admin-scoped scope-limited OAuth grant in pier | service | New concept; RESEARCH.md Code Examples define it |
## Metadata
**Analog search scope:** summercms.go `modules/{pact,wristband,pier,cabana}`, `admin/src`; sm-oauthserver-plugin (root, classes, controllers, updates, config); sm-user-plugin (classes/events.go, account_contributions.go); sm-grzybyfunkcjonalne-app and sm-bm-app (summer.yaml, config, deploy/nginx).
**Files scanned:** ~35

View File

@@ -0,0 +1,669 @@
# Phase 32.2: MCP OAuth with administrator subjects - Research
**Researched:** 2026-11-20
**Domain:** OAuth 2.1 authorization server (wristband + sm-oauthserver-plugin), MCP resource (pier), cabana admin API / admin SPA, nginx wiring of a consumer app
**Confidence:** HIGH for the code seams (read this session); MEDIUM for SPA/cookie behaviour on a real cross-site connector; LOW for exact Claude-connector behaviour (not probed)
<user_constraints>
## User Constraints (from CONTEXT.md)
### Locked Decisions
- **D-01:** On a backend-mode application, the OAuth sign-in authenticates an administrator (`backend_users`). No frontend user and no account link is involved; the grant subject is the administrator.
- **D-02:** It is a mode of `sm-oauthserver-plugin`, not a new framework module. Code stores, PKCE, refresh rotation, replay-family revocation, the Clients and Branding screens and pruning are reused. Every change to the plugin is additive. `sm-oauthserver-plugin`, `sm-user-plugin`, `sm-journal-plugin` and the framework are shared by many apps, so no breaking changes. — **Reversibility:** costly — the mode becomes a public config key and a grant shape other apps may adopt.
- **D-03:** Consent lives in the **admin SPA** (boardwalk, `admin/`) as a route under the admin prefix (working shape `/<admin prefix>/connect?request=…`), not as a Go-rendered page and not in Nuxt. Reason: the admin cookie `summer_admin` is `Path=<admin prefix>`, `SameSite=Strict` (`modules/cabana/auth.go` `sessionCookie`). It never reaches `/oauth/mcp/authorize` at the root, and it isn't sent on the cross-site navigation from the MCP client. A route inside the SPA gets it on its same-origin API fetches, and the SPA router already sends an anonymous visitor to login with `?redirect=` and back (`admin/src/app/router.ts` `safeRedirect`). Login gates (2FA, Turnstile) therefore apply unchanged.
- **D-04:** wristband's MCP authorize handoff, currently hard-wired to `{issuer}/connect?request=` (`modules/wristband/authorize.go`), becomes configurable so backend mode can point it at the admin SPA route. The default stays `/connect`. — **Reversibility:** costly — wristband option and oauthserver config key are public API.
- **D-05:** The consent screen is a **standalone full-screen card** like `LoginView` (no sidebar or top bar). It shows the client name, the redirect host, the scope checkboxes and the refresh choice, with Allow and Deny.
- **D-06:** The consent screen shows the signed-in administrator ("Signed in as <name> (<email>)") with a **"use another account"** action. That action signs out and goes back to login with the same redirect, like the 19.4 OIDC switch-account flow.
- **D-07:** The mode is **exclusive per application for now**: a config key on `golem15.oauthserver` (working name `mcp.subject`, values `user` (default) and `backend`). One issuer, one `/mcp` resource, one consent surface per app. Pick a config shape that doesn't block coexisting modes later (see Deferred). — **Reversibility:** costly — config key name and values become part of the plugin's contract.
- **D-08:** `sm-oauthserver-plugin` keeps `Requires() = ["golem15.user"]` in backend mode. grzyby mounts golem15.user anyway, and the core plugin's dependency graph stays untouched.
- **D-09:** The scopes on consent are the **cabana token-scope catalog**, the same as `g15_` personal-token creation (`modules/cabana/token_scopes.go`: `*`, `admin:read` and the plugin-declared `TokenScopes()` such as the Journal's). A backend-mode grant gets the same `bouncer.ScopeLimit` a personal token with those scopes would (`cabana.ScopeLimitFor`). An OAuth agent and a `g15_` token with equal scopes therefore see and can call the same tools. This differs from today's linked-admin grants, which carry no scope limit (`modules/pier/backend_guard.go` `principal` applies the limit only when `ClientID == ""`). That existing behaviour must not change for user-mode grants. In backend mode the advertised `scopes_supported` (wristband metadata and pier's protected-resource metadata) come from this catalog.
- **D-10:** `offline_access` appears as a **"Stay connected" checkbox, ticked by default**, as in 32.1's `/connect`. Unticked, the agent gets no refresh token and re-consents when the access token expires.
- **D-11:** Scopes the administrator can't use (they lack the scope's permissions) are **hidden** from the consent screen. A request that asked for them gets only what is ticked and granted.
- **D-12:** Each administrator lists and revokes their own MCP connections in a **My account section** (`pact.HasAccountContributions`). A superuser, or an administrator holding a new oauthserver permission, can see and revoke any administrator's connections on the existing oauthserver admin screens.
- **D-13:** An administrator's MCP grants (access and refresh tokens) are revoked, and their open MCP sessions ended (`pact.MCPSubjectChanged`), on: **delete, deactivate, password change, role or permission change** (including the role's own permissions changing) and **"sign out everywhere"** where cabana offers it. Role and permission changes revoke the grants rather than only re-listing tools.
- **D-14:** sm-grzybyfunkcjonalne-app mounts `golem15.oauthserver` in backend mode with only the MCP authorization server enabled (no OIDC provider surface), keeps `allow_personal_tokens: true`, routes `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource` and `/oauth/mcp/*` to the Go binary, and documents it in DEPLOY.md. Proof: on a local stack, an MCP client completes discovery, dynamic registration, admin sign-in, consent and a Journal tool call. The production deploy is not part of this phase.
### Claude's Discretion
- How backend-mode grants are stored. The current tables have `user_id INTEGER NOT NULL REFERENCES users(id)` on access tokens, auth codes and consents (`updates/202610190001_create_golem15_oauthserver_tables.go`). Options: nullable `user_id` via an additive migration with the readers that assume it hardened, or companion rows keyed on `backend_user_id`. Constraints: additive only, user-mode rows and queries unchanged, and the per-user advisory lock and revocation cascade keep working.
- How pier represents an administrator-only grant (for example `pact.MCPGrant` with `UserID` 0 and `BackendUserID` set, resolved straight to the `backend` subject, with no `MCPLinkedBackendResolver` lookup). Additive to `pact`.
- Where the consent JSON API lives (oauthserver routes under the admin API, authenticated by the cabana guard) and how the framework SPA route renders a consent screen whose data a plugin serves. The admin SPA can't load plugin Vue code, so the screen is framework code against a JSON contract.
- The name of the new "manage any administrator's MCP connections" permission and its default role (none, like `golem15.users.manage_backend_links`).
- Whether `*` and `admin:read` are shown as plain scope checkboxes or as "full access" / "read only" presets above the plugin scopes.
### Deferred Ideas (OUT OF SCOPE)
- **Both subject modes on one application** (for example the demo offering member and administrator connectors, through two resources or a choice at authorize). Exclusive per app for now (D-07); the config shape should leave room for it.
- **Production deploy of grzybyfunkcjonalne.pl with OAuth on** and a live check with the Claude connector: after the phase, on the user's go-ahead.
- **Backend mode without golem15.user** for apps that mount no user plugin (D-08 keeps the dependency).
- Reviewed todos not folded: "Benchmark Płytarium on WinterCMS vs SummerCMS", "Record PHP OIDC parity against WavePath", "Earlier phase gate scripts still name consuming applications", "Translate Messages as a Nuxt i18n JSON editor".
</user_constraints>
<phase_requirements>
## Phase Requirements
No REQ-IDs are assigned (ROADMAP: "Requirements: TBD"). The five ROADMAP success criteria act as requirements; this research labels them SC-1..SC-5.
| ID | Description | Research Support |
|----|-------------|------------------|
| SC-1 | Backend mode: authorize → admin login → SPA consent; grant carries `BackendUserID`, no frontend user; mode off = all existing flows/tests unchanged | §Storage recommendation, §wristband seams, §Admin SPA consent, §Pitfalls 1-6 |
| SC-2 | pier resolves the grant straight to the `backend` subject, capped by cabana permissions and granted scopes like a scope-limited `g15_` token | §pier seams, §Code Examples (identity, backend guard) |
| SC-3 | Revoke (My account list), delete/deactivate/password change ends tokens and sessions | §D-13 revocation map, §My account |
| SC-4 | grzyby mounts oauthserver in backend mode, proxy routes OAuth paths, local MCP client proof; `g15_` still works | §grzyby wiring, §Local proof |
| SC-5 | READMEs, docs/, DEPLOY.md; unit tests last plan; patch tags | §Release mechanics, §Validation Architecture |
</phase_requirements>
## Summary
The MCP OAuth flow is already subject-agnostic at the protocol layer: wristband carries the "user id" as an opaque `uint` through `IssueCode` → `MarkIssued` → code exchange → `Mint` / refresh `Create`, and refuses only a code with a nil user (`modules/wristband/token.go:248`). Everything that interprets that id as a frontend user lives in `sm-oauthserver-plugin` (store, verifier, cascade, consent controllers) and in pier (`resolveOAuth` rejects `grant.UserID == 0`, `modules/pier/identity.go:210`). Backend mode can therefore be built by (1) letting the plugin pass the administrator id as wristband's opaque subject id and persist it as `user_id NULL, backend_user_id = <admin>` per row, (2) a backend branch in the verifier and refresh check that loads the admin through `cabana.BackendPrincipal` and applies its `tokens_valid_after` cutoff, and (3) a pier branch that turns a backend-only grant into a `backend` subject with the cabana scope limit and no read/write ceiling.
The recommended storage is **nullable `user_id` on access tokens, refresh tokens and consents, plus `backend_user_id` on consents with a partial unique index** (one additive migration). Every user-mode query filters on `user_id = ?` / `IN ?`, so `NULL` rows are invisible to them; the only readers that see all rows (verifier by hash, refresh by hash, prune, the client authorizations partial) are few and listed below. Companion tables would duplicate the wristband store, the verifier lookup, lineage revocation and pruning for no safety gain.
Three framework seams are missing today and must be added additively: a wristband consent-handoff path and default-scope option, a cabana-owned admin consent endpoint backed by a new pact provider interface (the SPA cannot load plugin code and plugin routes cannot read the `summer_admin` cookie: `cabana.ResolveBackend` is "never the admin cookie"), and a per-row "items" extension of `pact.AccountContribution` (today a section is only a status line and fixed buttons, so per-connection revoke does not fit). D-13 needs one new in-transaction cabana event: password changes fire no MCP event today, and role/permission changes only re-list tools.
**Primary recommendation:** Nullable `user_id` + per-row backend subject in the existing tables; a cabana `{api}/mcp/consent/{request}` endpoint that delegates to a published `pact.MCPAdminConsent` provider; pier keys a backend-only grant on a new `pact.MCPGrant` subject marker and applies `cabana.ScopeLimitFor` through a new `pact.MCPSubject` flag; revocation through a new in-transaction `cabana` "admin access revoked" event mirroring sm-user-plugin's `AccessRevokedEvent`.
## Architectural Responsibility Map
| Capability | Primary Tier | Secondary Tier | Rationale |
|------------|-------------|----------------|-----------|
| RFC 8414 metadata, DCR, authorize, token, PKCE, refresh rotation | API (wristband, mounted by oauthserver) | — | Unchanged protocol code; only handoff URL and default scopes become options |
| Subject binding of codes/tokens (admin vs user) | Database / Storage (oauthserver `MCPStore`) | API | wristband's id is opaque; the store decides per row |
| Admin sign-in, 2FA/Turnstile | API (cabana auth) + Browser (admin SPA LoginView) | — | Reused unchanged (D-03) |
| Consent screen | Browser (admin SPA `ConnectView`) | API (cabana consent endpoint → oauthserver provider) | Cookie is `Path=<prefix>`, `SameSite=Strict`; only same-origin SPA fetches carry it |
| Scope catalog, "hide what you can't use", scope validation | API (cabana) | — | cabana owns the token-scope catalog and `scopeOverlaps`; unexported today |
| Token verification at `/mcp` | API (oauthserver `MCPTokenVerifier`) | API (pier) | Verifier answers `pact.MCPGrant`; pier builds the identity |
| Tool listing/calls capped by admin permissions + scopes | API (pier backend guard + cabana) | — | Same path as `g15_` tokens |
| Revocation on admin changes | API (cabana fires, oauthserver listens) | Database | cabana owns admin lifecycle; oauthserver owns grant rows |
| Session teardown | API (pier `handleEvent`) | Store (memory/redis fan-out) | Existing `pact.MCPSubjectChanged` path |
| My account connections list | Browser (AccountView) + API (cabana contributions) | oauthserver (items provider) | Framework renders, plugin supplies data |
| Proxy routing of OAuth paths | CDN/edge (nginx in grzyby `deploy/nginx`) | — | Nuxt answers everything else |
## Standard Stack
No new dependencies. Everything is standard library, existing modules, or packages already in `.planning/research/STACK.md` / the plugin's go.mod.
### Core (existing, versions from go.mod files read this session)
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| `git.golem15.com/golem15/summercms` | v0.6.6 tagged; HEAD = `v0.6.6-4-g6c44946d` [VERIFIED: git describe] | pact, pier, wristband, cabana, boardwalk | The framework |
| `sm-oauthserver-plugin` | v0.1.7, HEAD = v0.1.7 (go.work has an uncommitted change by another session; leave it) [VERIFIED: git describe/status] | MCP + OIDC authorization server | D-02 |
| `sm-user-plugin` | v0.1.21 latest tag; oauthserver go.mod requires v0.1.17 [VERIFIED: git tag, go.mod] | `Requires()` dependency (D-08) | unchanged |
| `gorm.io/gorm` | v1.31.2 [VERIFIED: sm-oauthserver-plugin/go.mod] | Store | existing |
| `go-gormigrate/gormigrate/v2` | v2.1.7 | Additive migration | existing |
| `github.com/modelcontextprotocol/go-sdk` | v1.8.0 (indirect) | pier transport | existing |
| Admin SPA: vue 3.5.35, vitest 3.2.7, openapi-fetch, playwright 1.60.0 | [VERIFIED: admin/package.json] | Consent route + tests | existing |
| swag v1.16.6 via `go run` in `scripts/check-admin-openapi.sh` | [VERIFIED: script line 31] | Typed admin API contract | existing pipeline |
### Alternatives Considered
| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| Nullable `user_id` | Companion tables keyed on `backend_user_id` | Needs a second `wristband.Backend`, a two-table verifier lookup, duplicated lineage revoke/prune; rejected |
| Cabana-owned consent endpoint | Plugin route under the admin prefix with the `backend` middleware | Plugin routes mount before `cabana.Activate` (`modules/surf/router.go:753`), `interactiveOnly`/`requireAjax` are unexported, the plugin would hard-code the API base; rejected |
| New in-tx cabana event for D-13 | oauthserver listening to `*pact.MCPSubjectChanged` (after commit) | Covers delete/deactivate/permissions but not password change, not atomic, listener errors only logged; use as defense in depth only |
**Installation:** none.
## Package Legitimacy Audit
No external packages are installed by this phase. **Packages removed due to [SLOP] verdict:** none. **Packages flagged [SUS]:** none.
## Architecture Patterns
### System Architecture Diagram
```
MCP client (Claude connector / script)
│ 1. POST /mcp (no bearer) ──► pier ─► 401 WWW-Authenticate resource_metadata=…
│ 2. GET /.well-known/oauth-protected-resource[/mcp] ──► pier PRM
│ scopes_supported ◄── verifier.MCPScopesSupported() ◄── cabana catalog (backend mode)
│ 3. GET /.well-known/oauth-authorization-server ──► wristband Metadata (same scope slice)
│ 4. POST /oauth/mcp/register ──► wristband Register (DCR, kind=mcp client)
│ 5. Browser: GET /oauth/mcp/authorize?…PKCE…&resource=…
│ └─► wristband Authorize: validate client/redirect/PKCE/scopes/resource
│ → CreatePending (mcp_codes, user_id NULL)
│ → 302 {issuer}{ConsentPath}?request=<id> (backend mode: /<admin prefix>/connect)
▼
Admin SPA (boardwalk, /<prefix>/connect)
├─ not signed in? router → /<prefix>/login?redirect=/connect?request=… (2FA/Turnstile unchanged) → back
├─ GET {prefix}/api/v1/mcp/consent/{request} (cookie summer_admin, X-Requested-With)
│ cabana: guard → principal → provider.Show(adminID, request)
│ → requested ∩ catalog ∩ scopeOverlaps(admin) (D-11) + labels
├─ "use another account": POST /auth/logout → login?redirect=same (D-06)
└─ POST {prefix}/api/v1/mcp/consent/{request} {decision, scopes, offline_access}
cabana: validate scopes (validateTokenScopes) → provider.Decide(adminID, …)
oauthserver: WithinBackendGrantsLock(admin) {
wristband.IssueCode(ctx+backendSubject, request, adminID, scopes)
→ MarkIssued: user_id NULL, backend_user_id = admin
record consent row (user_id NULL, backend_user_id, client_id) }
→ {redirect_uri: <client redirect>?code=…&iss=…&state=…}
SPA: window.location.assign(redirect_uri) (NOT safeRedirect)
▼
MCP client: POST /oauth/mcp/token (code + verifier + resource)
wristband Token → ByCodeHashForUpdate (backend lock shared) → Mint/Create (user_id NULL, backend_user_id)
▼
POST /mcp Authorization: Bearer oas_at_…
pier.resolveOAuth → verifier.MCPVerifyToken
backend row: cabana.BackendPrincipal(admin) nil? → invalid; created_at < tokens_valid_after? → invalid
→ MCPGrant{UserID:0, BackendUserID:admin, Subject:"backend", Scopes}
→ Identity{Frontend:nil, Backend:{Guard:"backend", UserID:admin, ClientID, TokenID, ScopeLimited:true},
ceiling:false, Binding:"oauth:backend:<client>:<admin>"}
→ backendGuard.principal: BackendPrincipal + ScopeLimitFor(scopes, method) (D-09)
→ tools/list, tools/call (Journal tools, guard "backend")
Revocation: cabana admin delete/deactivate/password/role/permission save
→ in-tx event (new) → oauthserver revokes backend rows in same tx
→ after commit: MCPSubjectChanged{Guard:"backend", UserID:admin, Kind:revoked, ClientID} per client
→ pier.handleEvent ends matching sessions
```
### Recommended file layout (new/changed)
```
summercms.go/
├── modules/pact/mcp.go # MCPGrant.Subject (+const), MCPSubject.ScopeLimited, MCPAdminConsent provider + view/decision types + errors
├── modules/pact/capabilities.go # AccountContribution.Items / ItemActions (additive)
├── modules/wristband/server.go # Options.ConsentPath, Options.DefaultScopes
├── modules/wristband/authorize.go # use them (defaults keep PHP bytes)
├── modules/pier/identity.go # backend-only grant branch
├── modules/pier/backend_guard.go # scope limit when subject.ScopeLimited
├── modules/cabana/mcp_consent.go # GET/POST {api}/mcp/consent/{request} (new)
├── modules/cabana/token_scopes_export.go # TokenScopeNames(app), grantable view for consent (new exports)
├── modules/cabana/admin_events.go # BackendAccessRevokedEvent (new), fired from users admin/account/commands
├── modules/cabana/account_contributions.go # items list + item action route
├── modules/cabana/admin_openapi.go # swag annotations for the new endpoints
├── admin/src/views/ConnectView.vue # standalone card (new)
├── admin/src/app/router.ts # { path: '/connect', name: 'connect', component: ConnectView } (no shell, not public)
├── admin/src/components/account/AccountContributions.vue # render items + per-item actions
├── admin/openapi/admin.json, admin/src/api/schema.d.ts # regenerated
└── modules/boardwalk/dist # rebuilt and committed
sm-oauthserver-plugin/
├── updates/2026112xxxxx_add_golem15_oauthserver_backend_subjects.go
├── classes/mcp_store.go # per-row backend subject
├── classes/mcp_backend_subject.go # WithBackendSubject ctx, backend grants lock, revokeBackendGrants (new)
├── classes/mcp_verifier.go # backend branch
├── classes/backend_cascade.go # listener for the cabana event (new)
├── controllers/mcp_admin_consent.go # implements pact.MCPAdminConsent (new)
├── controllers/mcp_connections.go # admin list screen of backend connections (new)
├── account.go # HasAccountContributions (new)
├── admin_permissions.go / admin_navigation.go # new permission + side menu
├── servers.go / routes.go / config/config.yaml # mcp.subject, mcp.consent_path, oidc.enabled
sm-grzybyfunkcjonalne-app/
├── summer.yaml, .gitmodules, go.mod, go.work # add golem15.oauthserver
├── plugins/golem15/oauthserver (submodule)
├── config/golem15.oauthserver.yaml, config/mcp.yaml
├── deploy/nginx/*.conf # OAuth locations
├── scripts/smoke-mcp-oauth.sh (or Go test) # local proof
└── DEPLOY.md
```
### Pattern 1: Per-row backend subject in the existing store (storage recommendation)
**What:** wristband keeps passing one opaque `uint`. In backend mode the consent provider calls `IssueCode(ctx, request, adminID, …)` with `ctx = classes.WithBackendSubject(ctx)`. The store writes `user_id = NULL, backend_user_id = adminID`. On the code exchange and refresh lookup the store reads the row; `user_id IS NULL AND backend_user_id IS NOT NULL` marks a backend row, the record's `UserID` is filled with `backend_user_id`, and `Mint`/`Create` in that transaction write the same shape.
**Why this works with wristband** [VERIFIED: modules/wristband/token.go:248,262,276,351,365]: the exchange requires only `rec.UserID != nil` and forwards `*rec.UserID` to `tx.Mint` and into the refresh record; refresh forwards `rec.UserID`. wristband never loads a user.
**Current schema** [VERIFIED: sm-oauthserver-plugin/updates/202610190001_create_golem15_oauthserver_tables.go:74,92,106,112,128; 202610190003…:23; 202610230001…:20-22]:
- auth_codes (OIDC): `user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,` (line 74) — not touched.
- access_tokens: `user_id INTEGER NOT NULL,` (line 92) — no FK.
- consents: `user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,` (line 106), `CONSTRAINT oas_consents_user_client_unique UNIQUE (user_id, client_id)` (line 112).
- refresh_tokens: `user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,` (line 128).
- mcp_codes: `user_id INTEGER NULL REFERENCES users(id) ON DELETE CASCADE,` (line 23 of 202610190003) — already nullable.
- `ALTER TABLE golem15_oauthserver_mcp_codes ADD COLUMN backend_user_id INTEGER NULL`, same for access_tokens and refresh_tokens (202610230001 lines 20-22). Consents have no `backend_user_id`.
**Migration (one file, raw SQL like the others):**
```sql
ALTER TABLE golem15_oauthserver_access_tokens ALTER COLUMN user_id DROP NOT NULL;
ALTER TABLE golem15_oauthserver_refresh_tokens ALTER COLUMN user_id DROP NOT NULL;
ALTER TABLE golem15_oauthserver_consents ALTER COLUMN user_id DROP NOT NULL;
ALTER TABLE golem15_oauthserver_consents ADD COLUMN backend_user_id INTEGER NULL;
CREATE UNIQUE INDEX oas_consents_backend_client_unique
ON golem15_oauthserver_consents (backend_user_id, client_id) WHERE user_id IS NULL;
CREATE INDEX oas_tokens_backend_client_idx ON golem15_oauthserver_access_tokens (backend_user_id, client_id) WHERE user_id IS NULL;
CREATE INDEX oas_refresh_backend_client_idx ON golem15_oauthserver_refresh_tokens (backend_user_id, client_id) WHERE user_id IS NULL;
-- every row names a subject; a uint zero written by mistake is refused
ALTER TABLE golem15_oauthserver_access_tokens ADD CONSTRAINT oas_tokens_subject_check CHECK ((user_id IS NOT NULL AND user_id > 0) OR backend_user_id IS NOT NULL) NOT VALID;
ALTER TABLE golem15_oauthserver_refresh_tokens ADD CONSTRAINT oas_refresh_subject_check CHECK (user_id IS NOT NULL OR backend_user_id IS NOT NULL) NOT VALID;
ALTER TABLE golem15_oauthserver_consents ADD CONSTRAINT oas_consents_subject_check CHECK (user_id IS NOT NULL OR backend_user_id IS NOT NULL) NOT VALID;
```
Rollback: `DELETE … WHERE user_id IS NULL` on the three tables (backend grants cannot survive a down migration; say so in the comment), drop constraints/indexes/column, `SET NOT NULL`. `NOT VALID` keeps the migration from scanning or failing on historic rows. `backend_user_id` gets no FK, matching 202610230001 and because backend users are only soft-deleted (`modules/cabana/backend_users_admin.go` FormAfterDelete comment: "a backend user is never hard-deleted").
**Reader inventory (sm-oauthserver-plugin, non-test) and what each needs:**
| Reader | Filter | Sees backend rows? | Action |
|--------|--------|--------------------|--------|
| `classes/mcp_store.go` `MarkIssued` | writes `"user_id": userID` | writes them | backend ctx → `user_id: nil`, `backend_user_id: id` |
| `mcp_store.go` `ByCodeHashForUpdate` | owner `Select("user_id")` into `*uint`; locks user | yes | also select `backend_user_id`; backend row → backend lock (shared); fill record `UserID` from `backend_user_id`; remember subject kind on `mcpTx` |
| `mcp_store.go` `Create` (refresh), `Mint` | `UserID: rec.UserID` | writes | backend tx → omit `user_id` (`Omit("user_id")` or column map), set `backend_user_id` regardless of the `backend` scope (today `backendBinding` requires that scope) |
| `mcp_store.go` `ByTokenHashForUpdate` + `refreshUserUsable` | `PrincipalByID(user)` | yes | backend row → `cabana.BackendPrincipal` + `issuedBeforeCutoff(created_at, principal.TokensValidAfter)`; no ban check (admins have none) |
| `mcp_store.go` `refreshRecord` | `UserID: m.UserID` | yes | backend row → `UserID = *m.BackendUserID` |
| `classes/mcp_verifier.go` `MCPVerifyToken` | `PrincipalByID(token.UserID)` | yes | backend branch (see Code Examples) |
| `classes/cascade.go` `purge`, `revokeUserGrants` | `user_id = ?` / `IN ?` | no | unchanged |
| `controllers/authorizations.go` (frontend authorized apps) | `s.user_id = ?` | no | unchanged |
| `controllers/mcp_consent_api.go` | jwt.auth frontend | — | do not mount in backend mode (Pitfall 4) |
| `controllers/clients.go` `authorizations` partial | `client_id = ?` | yes (UserID 0 → user not found → skipped) | OIDC clients only (`ListExtendQuery` `kind = oidc`); backend consents are MCP, so no change needed |
| `console/prune.go` `PruneExpired` | expiry only | yes | correct as is |
| `classes/oidc_store.go` consents | `user_id = ? AND client_id = ?`, `ON CONFLICT (user_id, client_id)` | no | unchanged |
| `updates/…backfill_…mcp_consents.go` | scans all live MCP tokens | only on a fresh DB, before any backend row exists | unchanged; it already ran everywhere else |
| `models.*` `UserID uint` | GORM scan | NULL → 0 | keep `uint` (GORM's uint setter ignores a nil `**uint`, [VERIFIED: ~/go/pkg/mod/gorm.io/gorm@v1.31.2/schema/field.go:696-706 `case **uint: if data != nil && *data != nil { … SetUint(…) }`]); do not change exported field types |
No other repository reads the oauthserver tables (grep of sibling repos found only the plugin's own files) [VERIFIED: grep this session].
**Advisory lock:** today `userGrantsLockKey` is `"golem15_oauthserver_user_grants:" + id` and `lockUserGrantsShared` returns early for id 0 [VERIFIED: classes/mcp_backend_binding.go]. Add a parallel `backendGrantsLockKey` (`"golem15_oauthserver_backend_grants:" + id`), `lockBackendGrantsShared`, `LockBackendGrants`, `WithinBackendGrantsLock` (same join-the-tx trick through `grantsTxKey`, so `MCPStore.WithinTx` reuses the tx). Separate namespace means admin 7 and user 7 never contend and never cross-serialize.
### Pattern 2: pier backend-only grant
**What:** `pact.MCPGrant` gains `Subject string` (const `pact.MCPGrantSubjectBackend = "backend"`; empty = the frontend user, today's meaning). The verifier sets it with `UserID: 0`, `BackendUserID: admin`. `resolveOAuth` branches before the `grant.UserID == 0` refusal.
Current code [VERIFIED: modules/pier/identity.go:209-231]: `if err != nil || grant.UserID == 0 { return Identity{}, ErrUnauthorized }`, `Binding: "oauth:" + grant.ClientID + ":" + strconv.FormatUint(uint64(grant.UserID), 10)`, `ceiling: true`, `id.Backend = r.consentedBackendSubject(…)`.
Backend branch requirements:
- `Frontend: nil` even when a frontend guard is registered (grzyby mounts golem15.user, so `r.frontendGuard` is set). A frontend subject with UserID 0 would be wrong.
- `Binding: "oauth:backend:" + clientID + ":" + adminID` — with UserID 0 the current format would put every admin of one client on `oauth:<client>:0` (Pitfall 2).
- `ceiling: false` — like an admin personal token; writes are governed by the scope limit's methods. With `ceiling: true` every non-read-only Journal tool would be hidden because `write` is not a cabana scope (`modules/pier/identity.go:80-82` `return !id.ceiling || slices.Contains(id.Scopes, "write")`).
- `Backend: &pact.MCPSubject{Guard: BackendGuard, UserID: admin, Scopes, ClientID, TokenID, ScopeLimited: true}`.
- `consentedBackend` not used; `refreshBackend` already returns early when `Frontend == nil` (`modules/pier/events.go:288-293`), so link events never touch it.
**Scope limit:** current condition [VERIFIED: modules/pier/backend_guard.go:110] `if subject.ClientID == "" && subject.TokenID != 0 {` → becomes `if (subject.ClientID == "" && subject.TokenID != 0) || subject.ScopeLimited {`. User-mode linked grants never set `ScopeLimited`, so their behaviour is unchanged (D-09). `errScopeUnavailable` then also covers a backend grant whose scopes all disappeared.
**Sessions:** `revokedMatch` with `ClientID` already matches `id.subjectFor("backend")` with that client [VERIFIED: modules/pier/events.go:80-94], so the plugin fires `MCPSubjectChanged{Guard: "backend", UserID: admin, Kind: revoked, ClientID}` per revoked client and nothing in pier changes. Include `ScopeLimited` in `fingerprint()` for completeness.
**PRM:** no pier change. `mountPRM` copies `MCPAdvertisedScopes.MCPScopesSupported()` when non-empty [VERIFIED: modules/pier/prm.go:37-40]; the plugin's verifier returns the backend-mode slice.
### Pattern 3: wristband options (D-04, plus default scopes)
Current [VERIFIED: modules/wristband/authorize.go:187] `spa := s.opts.Issuer + "/connect?request=" + rfc3986Escape(requestID)` and [authorize.go:250] the empty-scope fallback `return []string{"read"}, ""`.
Add to `Options` (zero value keeps PHP bytes, `DefaultOptions` unchanged):
- `ConsentPath string` — appended to `Issuer`; empty means `"/connect"`. Backend mode sets `cabana.AdminPrefix(app) + "/connect"` (`/gfadmin/connect` on grzyby; `modules/cabana/prefix.go` `AdminPrefix` reads `backend.uri`, callable at Boot).
- `DefaultScopes []string` — the scopes an authorize request with no data scope gets; empty means `["read"]`. Backend mode must set it, because `read` is not a cabana scope (Pitfall 3). Recommended value: the catalog's data scopes (everything advertised except `offline_access`); the consent screen then lets the admin narrow, which matches the MCP spec's "request all scopes_supported, let the user decide at consent" strategy [CITED: modelcontextprotocol.io/specification/2025-11-25/basic/authorization "Scope Selection Strategy"].
Scopes themselves need no wristband change: `NewServers` already sets `mcpOpts.ScopesSupported = scopes` and the verifier gets the same slice [VERIFIED: sm-oauthserver-plugin/servers.go NewServers]. Backend mode swaps the slice for `cabana catalog names + "offline_access"`. cabana names such as `*`, `admin:read`, `journal`, `journal:read` are valid RFC 6749 scope tokens (`%x21 / %x23-5B / %x5D-7E`) [ASSUMED from RFC 6749 §3.3 grammar].
**Catalog timing:** oauthserver builds its servers in `Boot`; `cabana.Activate` (which compiles the registry used by `ScopeLimitFor`) runs later at route assembly (`modules/surf/router.go:753`). But `party.Activated` is published before any `Register`/`Boot` (`modules/party/registry.go` activate: `app.Publish(Activated(ordered))` precedes the Register loop), and cabana already compiles a standalone catalog from it for CLI commands (`modules/cabana/token_commands.go` `tokenCatalogForApp` → `compileTokenCatalog(plugins)`). Export `cabana.TokenScopeNames(app *backpack.App) ([]string, error)` on top of `tokenCatalogForApp` (catalog order: `*`, `admin:read`, then plugin scopes). Constants [VERIFIED: modules/cabana/token_scopes.go:14-15] `scopeAll = "*"`, `scopeAdminRead = "admin:read"`.
### Pattern 4: Cabana-owned consent endpoint + pact provider (discretion item "where the consent JSON lives")
Why cabana: the SPA's API base is `{prefix}/api/v1` (`modules/cabana/prefix.go` `adminAPIVersion = "/api/v1"`); the cookie is `Path: s.adminPrefix()`, `HttpOnly`, `SameSite: http.SameSiteStrictMode` [VERIFIED: modules/cabana/auth.go sessionCookie]; plugin-side `cabana.ResolveBackend` reads "the Authorization Bearer header only (admin JWT or g15_ personal API token — never the admin cookie)" [VERIFIED: modules/cabana/token_guard.go ResolveBackend comment]. The admin group is `r.GroupRaw(api, []string{"backend", "locale.from-principal"}, …)` with `interactiveOnly(requireAjax(…))` wrappers [VERIFIED: modules/cabana/http.go:335-347]. Mounting the consent routes there gives cookie auth, CSRF header, interactive-only (no `g15_` tokens) and swag/openapi typing for free.
Contract (recommended, mirrors `controllers/mcp_consent_api.go` minus the link fields):
```
GET {api}/mcp/consent/{request}
200 {data: {request_id, client:{name, redirect_host, logo_url}, admin:{login, name, email},
scopes:[{name, label, description}], // requested ∩ catalog ∩ scopeOverlaps(admin) (D-11)
offline_access: bool, // requested
consent_required: bool, expires_at}}
404 request_not_found (missing/expired/used/foreign/no provider), 401
POST {api}/mcp/consent/{request} body {decision:"allow"|"deny", scopes:[…], offline_access: bool}
200 {data: {redirect_uri}} 422 no_grantable_scopes 404 request_not_found
```
pact interface (provider published by oauthserver in backend mode; cabana answers 404 when none is published):
```go
type MCPAdminConsent interface {
MCPAdminConsentShow(ctx context.Context, adminID uint, requestID string) (MCPAdminConsentRequest, error)
MCPAdminConsentDecide(ctx context.Context, adminID uint, requestID string, d MCPAdminConsentDecision) (redirectURI string, err error)
}
// ErrMCPConsentNotFound, ErrMCPConsentNoScopes sentinel errors
```
cabana does the scope policy (it owns the catalog): filter requested scopes with `scopeOverlaps`, and on allow run the same normalisation as token creation (`validateTokenScopes`: `*` collapses the set to `["*"]`, unknown or not-overlapping names refused) [VERIFIED: modules/cabana/api_tokens.go validateTokenScopes]. Submitted scopes outside requested ∩ grantable are dropped, not errors (D-11). The provider only resolves the pending request (wristband `PendingRequest`), issues the code under the backend grants lock and records the consent.
### Pattern 5: Admin SPA consent route
- Route: `{ path: '/connect', name: 'connect', component: ConnectView }` with no `meta.shell` (standalone card) and no `meta.public` (so `beforeEach` sends anonymous visitors to `{ name: 'login', query: { redirect: to.fullPath } }`) [VERIFIED: admin/src/app/router.ts:92-104]. `/connect` is a single segment, so it does not collide with `/:vendor/:plugin/:controller`.
- Login round trip: `LoginView` does `router.replace(safeRedirect(route.query.redirect) ?? '/')` [VERIFIED: admin/src/views/LoginView.vue:34]; `safeRedirect` accepts `/connect?request=…` (single leading slash). Any MFA/Turnstile step inside the login flow is reused as is.
- After the decision the SPA navigates to the **server-issued** `redirect_uri` with `window.location.assign`. Never route it through `safeRedirect` (it rejects absolute URLs; the URI is trusted because wristband validated it against the registered list).
- "Use another account": `POST {api}/auth/logout`, clear `currentUser`, `router.replace({ name: 'login', query: { redirect: '/connect?request=' + id } })`.
- Scope UI: reuse the `ApiTokenCreateDialog` rule that ticking `*` disables the others (`starChecked`, admin/src/components/account/ApiTokenCreateDialog.vue:64,149-177). Recommendation for the discretion item: **plain checkboxes with that rule**, labels from the catalog, so the consent mirrors `g15_` token creation exactly (the D-09 mental model). "Stay connected" checkbox ticked by default, shown when `offline_access` was requested.
- `boardwalk` serves `index.html` for client-side routes (`modules/boardwalk/boardwalk.go` header comment: "falls back to index.html for client-side routes"), so `/gfadmin/connect` loads without a cookie; the cookie rides on the SPA's same-origin API fetches.
- Release gate: rebuild `modules/boardwalk/dist` and pass `scripts/check-admin-dist.sh`; regenerate types with `scripts/check-admin-openapi.sh` and pass `--check`.
### Pattern 6: My account connections (D-12)
`pact.AccountContribution` today is `Name, Label, Description, Status func(ctx, adminID) (string, error), Actions []AccountAction` and `AccountActionInput` carries only `AdminID` [VERIFIED: modules/pact/capabilities.go:599-650]. The list endpoint returns status + fixed buttons [VERIFIED: modules/cabana/account_contributions.go:98-158]. A per-connection list with revoke does not fit. Add additively:
```go
// on AccountContribution
Items func(ctx context.Context, adminID uint) ([]AccountItem, error) `json:"-"`
ItemActions []AccountItemAction
type AccountItem struct { ID, Title, Subtitle string; Meta []string }
type AccountItemAction struct { Name, Label, Confirm string; Danger bool; Permissions []string
Run func(ctx context.Context, in AccountItemActionInput) (AccountActionResult, error) `json:"-"` }
type AccountItemActionInput struct { AdminID uint; ItemID string }
```
Route `POST /account/contributions/{name}/items/{item}/actions/{action}` in the same group, run in a transaction like section actions. `AccountContributions.vue` renders items under the section. The oauthserver item ID is the client_id; revoke deletes the admin's consent and the pair's codes/tokens under `LockBackendGrants` and fires the per-client revoked event after commit (mirror of `controllers/authorizations.go` `revoke`).
Admin-wide view: the existing Clients screen lists OIDC clients only (`ListExtendQuery` `kind = ?` oidc) [VERIFIED: controllers/clients.go:70-79]. Add a side-menu "MCP connections" list over backend consents (`backend_user_id IS NOT NULL AND user_id IS NULL`), relation columns to the admin and client (cabana list columns support `relation`/`select`, `modules/cabana/list_schema.go:68-69`), a "Revoke" record action and bulk action. Permission: **`golem15.oauthserver.manage_mcp_connections`**, no default role (superusers pass cabana checks anyway), label under the existing `golem15.oauthserver::lang.plugin.tab`. The main navigation item already requires `golem15.oauthserver.*`.
### D-13 revocation map
| Trigger | Where in cabana | Today | Needed |
|---------|-----------------|-------|--------|
| Delete admin | `usersAdmin.FormAfterDelete` sets `tokens_valid_after = revocationCutoff()` and fires `MCPSubjectDeleted` (after commit) | verifier would need the cutoff; sessions already end | new in-tx event → revoke rows; verifier cutoff as defense in depth |
| Deactivate | lifecycle action: `is_activated: false, tokens_valid_after: revocationCutoff()` + `MCPSubjectDeleted` | same | same |
| Password set by another admin | `FormBeforeUpdate`: `user.TokensValidAfter = &cutoff` when `storePassword` changed; **no event** | — | event (fire from FormAfterUpdate on a flag set in BeforeUpdate) |
| Own password change | `account.go` `accountUpdate`: `updates["tokens_valid_after"] = now.Truncate(time.Second)`; **no event** | — | event |
| `admin:reset-password` command | `commands.go`: password + `tokens_valid_after` cutoff; **no event** | — | event |
| Role / own permissions / superuser flip | `usersAdmin.FormAfterUpdate` fires `MCPSubjectPermissions` | re-list only | event with reason permissions → revoke (D-13 says revoke) |
| Role's permissions change | `rolesAdmin.FormAfterUpdate` fires `MCPSubjectPermissions` for holders | re-list only | event for holders |
| "Sign out everywhere" | not offered by cabana (no route found; `logout` is per-token) | — | none; document "not offered" |
[VERIFIED: modules/cabana/backend_users_admin.go:219-234, 284-289, 767-845; account.go:287-390; commands.go:150-165; backend_roles_admin.go:179-199; grep for everywhere/sign-out]
Recommended event, mirroring sm-user-plugin `AccessRevokedEvent{UserIDs []uint; Before time.Time; Reason string; Tx *gorm.DB}` [VERIFIED: sm-user-plugin/classes/events.go:112-117]:
```go
// modules/cabana
type BackendAccessRevokedEvent struct {
AdminIDs []uint
Before time.Time
Reason string // deleted, deactivated, password_changed, password_set, password_reset, permissions
Tx *gorm.DB
}
```
Fired synchronously inside the save's transaction (`TxFromContext`) through `app.Events.Fire`; a listener error rolls the save back, as the user-plugin pattern does. oauthserver's listener revokes the admins' backend rows (tokens revoked, consents and unused codes deleted) under `lockBackendGrants`, then `lagoon.AfterCommit` fires `MCPSubjectChanged{Guard: "backend", UserID, Kind: revoked, ClientID}` per touched client. Keep the existing cabana `MCPSubjectChanged` emissions untouched (they also serve user-mode linked grants and `g15_` sessions).
Defense in depth: the verifier and refresh check refuse a backend token with `created_at` before the admin's `tokens_valid_after` (`issuedBeforeCutoff`, already used for users), and `cabana.BackendPrincipal` answers nil for a deleted or deactivated admin [VERIFIED: modules/cabana/token_resolver.go BackendPrincipal comment]. So even a missed event cannot leave a usable token after delete, deactivate or password change; pier re-verifies the bearer on every request [VERIFIED: identity.go Identity comment "Every request resolves its own Identity from its bearer"].
### Anti-Patterns to Avoid
- **Writing `user_id = 0` for backend rows.** access_tokens has no FK, so a GORM `Create` with `UserID: 0` silently stores 0 instead of NULL. Use `Omit("user_id")`/column maps; the CHECK above catches it.
- **Reusing `backendBinding(scopes, id)` for backend rows.** It returns nil unless the scopes contain `backend` [VERIFIED: classes/mcp_backend_binding.go backendBinding]; backend-mode scopes never do.
- **Mounting the user-mode `/oauth/mcp/requests/*` routes in backend mode** (Pitfall 4).
- **Plugin Vue code or plugin routes under the admin prefix** for consent (see Pattern 4).
- **Changing `UserID uint` model fields to pointers** — an exported API change for no gain.
## Don't Hand-Roll
| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Scope → route-method limit | new limit logic | `cabana.ScopeLimitFor` | identical to `g15_` tokens by construction (D-09) |
| Scopes an admin may grant | permission matching in the plugin | cabana `scopeOverlaps` / `validateTokenScopes` (export thin wrappers or keep them behind the cabana endpoint) | the token dialog's rules, incl. `*` collapsing |
| Admin loading, deactivated/deleted check | SQL on backend_users | `cabana.BackendPrincipal` (+ `TokensValidAfter`) | same answer the guard uses |
| Session teardown | custom pier hooks | `pact.MCPSubjectChanged` with `ClientID` | `revokedMatch` already handles it |
| Commit-time side effects | goroutines | `lagoon.AfterCommit` / `userclasses.FireSubjectEventAfterCommit` | rollback-safe |
| PKCE/DCR/refresh replay | anything | wristband | byte-exact PHP contract |
| Login, 2FA, Turnstile on the consent path | a second login page | admin SPA `LoginView` + router redirect | D-03 |
**Key insight:** the only genuinely new logic is the per-row subject switch and the backend branches; everything else is wiring existing, already-tested pieces through additive seams.
## Common Pitfalls
### Pitfall 1: The pending row is owned by everyone until issued
**What goes wrong:** `lookupOwnedPending` treats `pending.UserID == nil` as owned by every caller and compares `*pending.UserID != userID` otherwise [VERIFIED: wristband/consent.go]. In backend mode the "userID" is an admin id; in user mode it is a user id. Fine while the modes are exclusive, but a backend-mode app must not also expose the frontend consent routes, or a frontend user could consent to an admin's pending request with their own id.
**How to avoid:** backend mode mounts only metadata/authorize/register/token; the consent path is the cabana endpoint only.
### Pitfall 2: Binding collision for UserID 0
**What goes wrong:** `"oauth:" + clientID + ":" + "0"` for every admin of one client → sessions shared across admins.
**How to avoid:** distinct backend binding format; test two admins on one client get distinct bindings.
### Pitfall 3: Empty-scope fallback is `read`
**What goes wrong:** a client that sends no `scope` gets `["read"]` (authorize.go:250), which no cabana scope matches; consent shows nothing and `ScopeLimitFor` answers known 0.
**How to avoid:** `Options.DefaultScopes` set in backend mode.
### Pitfall 4: Frontend consent routes in backend mode
**What goes wrong:** `MCPConsentShow/Decide` behind `jwt.auth` would let any frontend user of the app finish a pending backend-mode request as a user-subject grant.
**How to avoid:** do not mount them when `mcp.subject: backend`; a test asserts 404.
### Pitfall 5: Read/write ceiling hides write tools
**What goes wrong:** OAuth identities set `ceiling: true`; cabana scopes never include `write`, so every non-read-only tool disappears.
**How to avoid:** `ceiling: false` for backend-only grants; the scope limit's methods do the capping.
### Pitfall 6: OIDC surface still mounted
**What goes wrong:** `Routes` always mounts OIDC discovery, JWKS, `/oauth/authorize`, `/oauth/token`, `/oauth/userinfo` and the authorized-apps routes [VERIFIED: sm-oauthserver-plugin/routes.go]. D-14 wants no OIDC surface; MCP clients also probe `/.well-known/openid-configuration` as a fallback [CITED: MCP authorization spec, "Authorization Server Metadata Discovery"].
**How to avoid:** additive `oidc.enabled` (default true) key; grzyby sets false. The nginx vhost routes only the MCP paths anyway.
### Pitfall 7: SameSite=Strict on the cross-site redirect chain
**What goes wrong:** the top-level navigation from the connector's site to `/gfadmin/connect` does not carry the Strict cookie; a server-side check on that request would see "anonymous".
**How to avoid:** the SPA shell is public and the session is read by the SPA's same-origin API fetch (D-03). A localhost proof is same-site and cannot exercise this; flag the live connector check for the deploy step [ASSUMED: browser SameSite semantics for subresource fetches from a same-origin document].
### Pitfall 8: `tokens_valid_after` granularity
**What goes wrong:** cabana's `revocationCutoff()` is `now + 1s`, and `issuedBeforeCutoff` refuses `createdAt < cutoff + 1s`, so a consent completed within about two seconds after an admin-set password or deactivation/reactivation would be refused.
**How to avoid:** acceptable; tests must sleep past the window or use a clock seam.
### Pitfall 9: Revocation event fired outside the transaction
**What goes wrong:** firing the new cabana event after commit makes the oauthserver revocation non-atomic and its errors silent.
**How to avoid:** fire with the save's `Tx` (as sm-user-plugin does), and keep the verifier cutoff check.
### Pitfall 10: Docker-backed and MCP-tagged tests are skipped silently
**What goes wrong:** `go test -short` skips testcontainers tests; pier is linked only with `-tags summercms_mcp` (`modules/surf/pier_on.go:1`). A full flow test without the tag never mounts `/mcp`.
**How to avoid:** run the backend-mode end-to-end test with `-tags summercms_mcp` and without `-short`.
## Code Examples
### Verifier backend branch (sm-oauthserver-plugin)
```go
// Source: pattern of classes/mcp_verifier.go MCPVerifyToken (read this session)
if token.UserID == 0 && token.BackendUserID != nil { // user_id NULL scans as 0
admin, err := cabana.BackendPrincipal(ctx, v.App, *token.BackendUserID)
if err != nil {
return pact.MCPGrant{}, err
}
if admin == nil || issuedBeforeCutoff(token.CreatedAt, admin.TokensValidAfter) {
return pact.MCPGrant{}, pact.ErrMCPTokenInvalid
}
v.stamp(ctx, db, token.ID, now)
return pact.MCPGrant{
UserID: 0, BackendUserID: *token.BackendUserID, Subject: pact.MCPGrantSubjectBackend,
ClientID: token.ClientID, TokenID: token.ID,
Scopes: slices.Clone(stringsOf(token.Scopes)), ExpiresAt: *token.ExpiresAt,
}, nil
}
// … existing user path unchanged
```
`cabana.BackendPrincipal` errors with `ErrUnauthenticated` when cabana is not activated; that is a fail-closed 401, which is correct.
### pier identity branch
```go
// Source: modules/pier/identity.go resolveOAuth (read this session), additive branch
grant, err := verifier.MCPVerifyToken(ctx, raw)
if err != nil {
return Identity{}, ErrUnauthorized
}
if grant.Subject == pact.MCPGrantSubjectBackend {
if grant.UserID != 0 || grant.BackendUserID == 0 {
return Identity{}, ErrUnauthorized
}
scopes := append([]string(nil), grant.Scopes...)
return Identity{
Scopes: scopes,
Binding: "oauth:backend:" + grant.ClientID + ":" + strconv.FormatUint(uint64(grant.BackendUserID), 10),
ExpiresAt: grant.ExpiresAt,
TokenKind: TokenKindOAuth,
Backend: &pact.MCPSubject{Guard: BackendGuard, UserID: grant.BackendUserID, Scopes: scopes,
ClientID: grant.ClientID, TokenID: grant.TokenID, ScopeLimited: true},
}, nil
}
if grant.UserID == 0 {
return Identity{}, ErrUnauthorized
}
// … existing user path unchanged
```
### oauthserver config (backend mode, grzyby)
```yaml
# config/golem15.oauthserver.yaml
oidc:
enabled: false
mcp:
enabled: true
subject: backend # user (default) | backend
# consent_path: "" # empty: <backend.uri>/connect in backend mode, /connect in user mode
resource: http://127.0.0.1:8096/mcp # must equal mcp.resource of config/mcp.yaml; production via env
```
Existing keys read today: `golem15.oauthserver.mcp.enabled`, `golem15.oauthserver.mcp.resource` [VERIFIED: sm-oauthserver-plugin/servers.go:126-127]; `mcp_scopes` filters declared member scopes and should be ignored (or refused) in backend mode. The port 8096 is the vhost's upstream (`proxy_pass http://127.0.0.1:8096;`) [VERIFIED: deploy/nginx/grzybyfunkcjonalne-staging.conf:182].
### nginx locations to add (grzyby, both vhosts)
```nginx
location = /.well-known/oauth-authorization-server { auth_basic off; limit_except GET HEAD { deny all; } proxy_pass http://127.0.0.1:8096; … same proxy headers … }
location ^~ /oauth/mcp/ { auth_basic off; limit_except GET POST { deny all; } client_max_body_size 64k; proxy_pass http://127.0.0.1:8096; … }
```
The two PRM locations and `/mcp` exist already (staging.conf:175-224). Exact locations are needed because a `location ~ /\.` dotfile rule answers 404 for `/.well-known/*` otherwise (staging.conf:195-196 comment and :254). `/gfadmin` is already proxied (staging.conf:122). No `add_header` in the new locations (`scripts/check-deploy.sh` fails on one, DEPLOY.md:239). `auth_basic off` is required because the connector fetches metadata, register and token server-to-server.
## Local proof (SC-4)
grzyby runs as one Go binary locally (Nuxt is not needed for the OAuth paths; app.url pointing at the Go port serves `/gfadmin`, `/mcp`, `/.well-known/*`, `/oauth/mcp/*`). Recommended: `scripts/smoke-mcp-oauth.sh` (bash + curl + openssl, no new deps):
1. `POST /mcp` without bearer → 401 and `resource_metadata`.
2. `GET /.well-known/oauth-protected-resource/mcp` → `authorization_servers`, `scopes_supported` contains `journal`.
3. `GET /.well-known/oauth-authorization-server` → endpoints; `GET /.well-known/openid-configuration` → 404 (OIDC off).
4. `POST /oauth/mcp/register` (redirect `http://127.0.0.1:<port>/cb`, auth method none).
5. PKCE: `verifier=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n')`, challenge = `printf %s "$verifier" | openssl dgst -sha256 -binary | base64 | tr '+/' '-_' | tr -d '='`.
6. `GET /oauth/mcp/authorize?…&resource=…` → 302 to `/gfadmin/connect?request=<id>`.
7. Admin login: `POST /gfadmin/api/v1/auth/login` with `X-Requested-With`, cookie jar (the login handler sets the cookie when the CSRF header is present; `modules/cabana/http.go` comment "without it the response is a Bearer body and no cookie is set").
8. `GET`/`POST /gfadmin/api/v1/mcp/consent/<id>` with the jar and `X-Requested-With` → `redirect_uri` with `code`.
9. `POST /oauth/mcp/token` (code, verifier, resource) → `oas_at_…` (+ refresh when ticked).
10. MCP `initialize` → `notifications/initialized` → `tools/list` (Journal tools present) → `tools/call journal_show_post`.
11. Regression: the same with a `g15_` token.
12. Revocation: change the admin's password via `PUT /gfadmin/api/v1/account` → next `/mcp` call 401.
A Claude connector run is part of the deferred deploy check.
## Release mechanics
- Order (CLAUDE.md, memory): framework commits → plugin commits (development through `go.work` replace) → at phase completion only: framework tag = next free patch on `master` (v0.6.6 now; phase 35 may take v0.6.7 first — pick the next free one at tag time) → plugin `go.mod` `require git.golem15.com/golem15/summercms vX.Y.Z` (today v0.6.0 with `replace => ../summercms.go`) → plugin tag **v0.1.8** → grzyby: add submodule `plugins/golem15/oauthserver` (`url = git@git.golem15.com:golem15/sm-oauthserver-plugin.git`, `branch = master`), `go.work use ./plugins/golem15/oauthserver`, `go.mod require sm-oauthserver-plugin v0.1.8` + `replace … => ./plugins/golem15/oauthserver`, bump `summercms` require (today v0.6.1) — plugin pushed first, pointer bump as its own commit.
- Changelog posts the same day for the framework tag and the plugin tag (`../sm-summercmsio-app/scripts/changelog-post.py`). No push/tag without the user's go-ahead.
- sm-bm-app (oauthserver v0.1.7, summercms v0.6.4) and sm-demo-app (v0.1.6, v0.6.1) are not bumped in this phase; verify them against the new plugin with a scratch `go.work` replace.
## State of the Art
| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| MCP clients rely on DCR | Spec 2025-11-25: Client ID Metadata Documents preferred, DCR "MAY", kept for backwards compatibility | MCP spec 2025-11-25 | wristband offers DCR only; clients that support CIMD fall back to DCR when `client_id_metadata_document_supported` is absent [CITED: modelcontextprotocol.io/specification/2025-11-25/basic/authorization] |
| Client picks scopes | Use `scope` from WWW-Authenticate, else all PRM `scopes_supported` | same | consent receives the whole catalog; DefaultScopes matters only for clients that send none |
## Assumptions Log
| # | Claim | Section | Risk if Wrong |
|---|-------|---------|---------------|
| A1 | cabana scope names (`*`, `journal:read`) are acceptable to Claude/ChatGPT connectors as scope tokens | Pattern 3 | connector refuses or drops `*`; mitigate by offering `admin:read`/plugin scopes and testing at deploy |
| A2 | SameSite=Strict cookie is sent on the SPA's same-origin fetch after a cross-site redirect chain | Pitfall 7 | consent always shows login; would need a re-navigation trick; only checkable live |
| A3 | The Claude connector requests `offline_access` when advertised | Pattern 5 | "Stay connected" never shown; tokens expire hourly |
| A4 | cabana list relation columns can join consents→clients via `client_id` string references | Pattern 6 | the admin screen needs a ListExtendQuery join or a partial instead |
| A5 | Firing a new cabana event synchronously inside admin saves has no ordering conflict with existing FormAfterUpdate hooks | D-13 map | minor rework of hook placement |
| A6 | No other app relies on `Options` zero values producing `/connect` other than through `DefaultOptions` | Pattern 3 | none if empty-means-default is kept |
## Open Questions (RESOLVED)
1. **Show consent when already consented?** The user-mode contract has `consent_required`; vue-oauth-layer omits scopes when consent is stored. Recommendation: always show the card for admins (one click), keep the field for parity.
**RESOLVED** (32.2-01, 32.2-02): adopted. 32.2-01 task 2 keeps `consent_required` in the cabana `MCPConsentView`; 32.2-02 always renders the card, posts nothing on mount even when `consent_required` is false, and shows the "previously allowed" note instead (no auto-allow).
2. **Keep `oidc.enabled` as a new key or tie OIDC off to `mcp.subject: backend`?** Recommendation: separate key (default true); coupling would block the deferred coexistence.
**RESOLVED** (32.2-03): adopted. 32.2-03 task 1 adds `oidc.enabled` as its own key, default true; with it false, the OIDC discovery, JWKS, `/oauth/authorize*`, `/oauth/token` and `/oauth/userinfo` routes are not mounted. It is not derived from `mcp.subject`.
3. **`mcp_scopes` in backend mode:** ignore or fail boot? Recommendation: fail boot with a clear message when set together with `subject: backend`.
**RESOLVED** (32.2-03): adopted. 32.2-03 task 1 fails boot when `golem15.oauthserver.mcp_scopes` is set together with `mcp.subject: backend`. The same task also fails boot on an unknown subject and on backend with `mcp.enabled: false`.
4. **"Sign out everywhere":** cabana offers none today. Recommendation: document; if added later it fires the new event with its own reason.
**RESOLVED** (32.2-01): adopted. 32.2-01 task 4 adds no such action and documents that cabana does not offer one (cabana README, `docs/backend/users-and-permissions.md`). D-13 covers it "where cabana offers it", so nothing is left out. A later sign-out-everywhere action would fire `cabana.BackendAccessRevokedEvent` with its own reason.
## Environment Availability
| Dependency | Required By | Available | Version | Fallback |
|------------|------------|-----------|---------|----------|
| Go | all Go code/tests | ✓ | go1.27.2 | — |
| Node / npm | admin SPA build/tests | ✓ | v24.22.0 / 12.2.1, `admin/node_modules` present | — |
| Docker | testcontainers Postgres tests | ✓ | 29.9.1, daemon reachable | `sudo -u golem` if the group list is stale (CLAUDE.md) |
| swag | openapi script | via `go run …@v1.16.6` | — | — |
| openssl, curl | local proof script | assumed present [ASSUMED] | — | a Go test instead |
**Missing dependencies with no fallback:** none.
## Validation Architecture
### Test Framework
| Property | Value |
|----------|-------|
| Framework | Go `testing` (+ testcontainers Postgres), vitest 3.2.7 (+ browser config with playwright) |
| Config file | per-package `TestMain` (`sm-oauthserver-plugin/testmain_test.go` with `flag.Parse()` + `testing.Short()`); `admin/vitest.config*.ts` |
| Quick run command | `go test -short ./modules/pier ./modules/wristband ./modules/cabana ./modules/pact` (framework); `cd ../sm-oauthserver-plugin && go test -short ./...` |
| Full suite command | `go vet ./... && go test ./... && go test -tags summercms_mcp ./modules/pier ./modules/surf`; `cd ../sm-oauthserver-plugin && go test ./... && go test -tags summercms_mcp ./...`; `npm --prefix admin run typecheck && npm --prefix admin run test && npm --prefix admin run test:browser`; `scripts/check-admin-openapi.sh --check && scripts/check-admin-dist.sh`; `summer docs:build --check` |
### Success criteria → tests
| ID | Behavior | Type | Command | File exists? |
|----|----------|------|---------|-------------|
| SC-1 | `ConsentPath`/`DefaultScopes` defaults keep `/connect` and `read`; set values used | unit | `go test -short ./modules/wristband -run 'TestAuthorize(ConsentPath|DefaultScopes)'` | ❌ new |
| SC-1 | backend mode authorize → 302 `/<prefix>/connect`; user consent routes 404; OIDC routes 404 with `oidc.enabled: false` | integration (docker) | `cd ../sm-oauthserver-plugin && go test ./ -run TestBackendMode` | ❌ new |
| SC-1 | consent endpoint: anon 401, foreign/expired 404, hidden scopes, `*` collapse, allow → redirect with code, deny → access_denied | integration | `go test ./modules/cabana -run TestMCPAdminConsent` (fake provider) + plugin `-run TestBackendConsent` | ❌ new |
| SC-1 | rows: `user_id IS NULL`, `backend_user_id` set on code, access, refresh, consent; migration up/down | integration | plugin `go test ./ -run 'TestBackendSubjectMigration|TestBackendGrantRows'` | ❌ new |
| SC-1 | mode off: existing suites unchanged | regression | plugin `go test ./...`; sm-bm-app `go test ./...` with scratch go.work replace | ✅ |
| SC-1 | ConnectView: renders card, switch account, Allow/Deny navigation, router sends anon to login | unit (vitest) | `npm --prefix admin run test -- tests/views/ConnectView.test.ts tests/app/router.test.ts` | ❌ new (router ✅) |
| SC-2 | backend grant → backend subject, no frontend subject, distinct binding, ceiling off, ScopeLimit applied; user-mode linked grant unchanged | unit | `go test -short ./modules/pier -run 'TestBackendOnlyGrant|TestLinkedGrantNoScopeLimit'` | ❌ new |
| SC-2 | `journal:read` grant lists read tools only; `journal` lists write tools; equals `g15_` token with same scopes | integration (docker, MCP tag) | plugin `go test -tags summercms_mcp ./ -run TestBackendGrantToolsMatchPersonalToken` | ❌ new |
| SC-3 | My account items list + revoke ends one client's sessions | unit + integration | `go test ./modules/cabana -run TestAccountContributionItems`; plugin `-run TestBackendRevokeFromAccount` | ❌ new |
| SC-3 | delete/deactivate/password (own, set, CLI)/role/role-permissions → tokens revoked + MCPSubjectChanged per client; verifier refuses pre-cutoff token | integration | `go test ./modules/cabana -run TestBackendAccessRevokedEvent`; plugin `-run TestBackendCascade` | ❌ new |
| SC-4 | local stack proof | smoke (manual-run script) | `cd ../sm-grzybyfunkcjonalne-app && scripts/build.sh && scripts/smoke-mcp-oauth.sh` | ❌ new |
| SC-4 | vhost contains the OAuth locations, no add_header | static | `cd ../sm-grzybyfunkcjonalne-app && scripts/check-deploy.sh` | ✅ (extend) |
| SC-5 | docs identifiers and snippets | static | `summer docs:build --check` | ✅ |
### Sampling Rate
- **Per task commit:** the quick command of the touched repo.
- **Per wave merge:** the full suite of the touched repo.
- **Phase gate:** all full suites green, `check-admin-openapi.sh --check`, `check-admin-dist.sh`, the grzyby smoke, before `/msd-verify-work`.
### Wave 0 Gaps
- [ ] Plugin harness helper that boots with `mcp.subject: backend` and a backend user (extend `harness_test.go` `bootOAuthWith`).
- [ ] A pier test fake verifier returning a backend grant (existing helpers in `modules/pier/helpers_test.go`).
- [ ] `admin/tests/views/ConnectView.test.ts` fixtures for the new endpoint.
- [ ] `scripts/smoke-mcp-oauth.sh` in grzyby.
## Security Domain
### Applicable ASVS Categories
| ASVS Category | Applies | Standard Control |
|---------------|---------|-----------------|
| V2 Authentication | yes | cabana login (2FA/Turnstile) reused; PKCE S256 enforced by wristband |
| V3 Session Management | yes | `summer_admin` HttpOnly/Strict cookie; `tokens_valid_after` cutoff on OAuth tokens; refresh rotation + replay family revocation |
| V4 Access Control | yes | `cabana.Allows` + `ScopeLimitFor`; consent scopes ⊆ requested ∩ grantable; per-admin locks |
| V5 Input Validation | yes | wristband client/redirect/resource validation; cabana `validateTokenScopes`; capped JSON bodies |
| V6 Cryptography | yes | existing token hashing (SHA-256 of 32 random bytes); no new crypto |
### Known Threat Patterns
| Pattern | STRIDE | Standard Mitigation |
|---------|--------|---------------------|
| CSRF on consent allow | Tampering | `requireAjax` + Strict cookie + interactive-only |
| Open redirect via consent | Spoofing | wristband exact redirect match; SPA navigates only to the server-issued URI |
| Frontend user hijacking a backend pending request | Elevation | backend mode does not mount user consent routes (Pitfall 4) |
| Scope escalation (granting scopes the admin lacks) | Elevation | cabana filters with `scopeOverlaps` and re-validates on decide |
| Grant outliving a password change/deactivation | Elevation | in-tx revocation + verifier cutoff check |
| Cross-admin session reuse | Information disclosure | per-admin binding key |
| Phishing via client name | Spoofing | show redirect host (MCP spec MUST) [CITED: MCP authorization spec "Localhost Redirect URI Risks"] |
## Suggested plan split (lean, for the planner to confirm with the user)
1. **Framework seams** (summercms.go): pact additions, wristband options, pier backend-only branch + scope flag, cabana `TokenScopeNames`, consent endpoint + swag, `BackendAccessRevokedEvent` at every site, account contribution items API; module READMEs and docs/services/oauth-server.md, mcp.md, backend/admin-spa.md, users-and-permissions.md, plugins/registration.md in the same commits. Smoke tests only.
2. **Admin SPA** (summercms.go `admin/`): ConnectView + route, switch account, items rendering in AccountContributions, regenerated openapi/types, rebuilt `modules/boardwalk/dist`. Can run in parallel with 3 once 1 lands.
3. **sm-oauthserver-plugin backend mode**: config keys (`mcp.subject`, `mcp.consent_path`, `oidc.enabled`), migration, per-row store, backend locks, verifier/refresh branch, consent provider, cabana-event listener, My account section, MCP connections screen + permission, README.
4. **grzyby wiring + local proof**: submodule, summer.yaml, config, nginx, smoke script, DEPLOY.md.
5. **Unit tests + release checkpoint** (project rule: tests last): the Validation Architecture tests across the three repos, regression runs for sm-bm-app, tags (framework next patch, plugin v0.1.8), pointer bump, changelog posts — on the user's go-ahead.
## Project Constraints (from CLAUDE.md)
- One Go module; new code in existing modules; no new module needed (beach-name rule not triggered).
- Standard library first; no new dependency without a decision note (none needed).
- YAML via goccy/go-yaml only.
- Docs: exported API, config key or CLI change updates the module README and `docs/` in the same commit; every identifier in docs must exist; Go code blocks in docs/READMEs are `src=` references (`summer docs:sync`).
- Admin changes: rebuild and commit `modules/boardwalk/dist`, pass `scripts/check-admin-dist.sh`; openapi via `scripts/check-admin-openapi.sh`.
- Keep `go vet ./...` and `go test ./...` green at every commit; Docker tests skip under `-short` with `flag.Parse()` + `testing.Short()`.
- Framework code never names a consuming application.
- Core plugins shared across apps: no breaking changes (user, oauthserver, journal).
- Plugin commit first, then the app pointer bump as a separate commit; tags only at phase completion on the default branch, next patch by default; changelog post the same day; no push/tag/deploy without the user's go-ahead.
- No co-author tags; stage files by path; leave other sessions' uncommitted edits (e.g. `sm-oauthserver-plugin/go.work`, `.planning/state.json`).
- Lean planning: present plan count and scopes before writing PLAN.md; unit tests are the last plan; STATE.md via `msd_run query state.*`; g15office comment when the phase advances.
## Sources
### Primary (HIGH confidence, read this session)
- summercms.go: `modules/wristband/{authorize,server,consent,stores,token}.go`, `modules/pier/{identity,backend_guard,events,prm}.go`, `modules/pact/{mcp,capabilities}.go`, `modules/cabana/{auth,prefix,token_guard,token_resolver,token_scopes,api_tokens,account,account_contributions,account_tokens,backend_users_admin,backend_roles_admin,subject_events,record_events,commands,http,registry,token_commands}.go`, `modules/party/registry.go`, `modules/surf/router.go`, `admin/src/app/router.ts`, `admin/src/views/LoginView.vue`, `admin/package.json`, `scripts/check-admin-{dist,openapi}.sh`
- sm-oauthserver-plugin: `plugin.go`, `servers.go`, `routes.go`, `admin*.go`, `config/config.yaml`, `updates/*`, `models/*`, `classes/{mcp_store,mcp_verifier,mcp_backend_binding,cascade,subject_events,mcp_scopes}.go`, `controllers/{mcp_consent_api,authorizations,clients}.go`, `console/prune.go`, `go.mod`
- sm-grzybyfunkcjonalne-app: `summer.yaml`, `config/{mcp,backend,app}.yaml`, `.gitmodules`, `go.mod`, `go.work`, `deploy/nginx/grzybyfunkcjonalne-staging.conf`, `DEPLOY.md`
- sm-user-plugin `classes/events.go`; sm-journal-plugin `token_scopes.go`, `mcp.go`; sm-bm-app `config/golem15.oauthserver.yaml`
- gorm v1.31.2 `schema/field.go` (module cache)
### Secondary (MEDIUM)
- MCP Authorization spec 2025-11-25 (WebFetch): scope selection, discovery order, DCR/CIMD, redirect-host display
### Tertiary (LOW)
- Connector behaviour for `*` scopes and `offline_access` (A1, A3): not probed
## Metadata
**Confidence breakdown:**
- Standard stack: HIGH — no new packages; versions read from go.mod/tags.
- Architecture: HIGH for Go seams (code read); MEDIUM for SPA cookie behaviour on a real cross-site connector.
- Pitfalls: HIGH — each tied to a read line of code.
**Process note:** the research-plan/research-store seam was not used; all findings come from direct file reads and one spec fetch.
**Research date:** 2026-11-20
**Valid until:** 2026-12-20 (other sessions are changing cabana and the plugin; re-check `git log` of cabana, pier and sm-oauthserver-plugin before executing)

View File

@@ -0,0 +1,42 @@
---
phase: "32.2"
sources: [32.2-REVIEW-FIX.md, 32.2-REVIEW-FIX-plugin-app.md, 32.2-REVIEW.md (framework, prefix FW), 32.2-REVIEW-plugin-app.md (plugin+app, prefix PA)]
open: 13
total: 29
---
# Phase 32.2 code review disposition
One row per finding, defaulting to `open`. Edit the disposition (fixed / accepted / deferred / wontfix) and the source cell when a finding is triaged.
| ID | Severity | Title | Disposition | Source |
|----|----------|-------|-------------|--------|
| FW-WR-01 | warning | `DefaultScopes` never applies to an `offline_access`-only authorize request, which ends in a consent screen with nothing to grant | fixed | 32.2-REVIEW-FIX.md fa7a8482 |
| FW-WR-02 | warning | `ConsentPath` is concatenated onto `Issuer` without validation and can send the browser off-origin | fixed | 32.2-REVIEW-FIX.md 1dcc2ed0 |
| FW-WR-03 | warning | pier treats an unknown `MCPGrant.Subject` as a frontend-user grant (fail-open) | fixed | 32.2-REVIEW-FIX.md 19bb3f94 |
| FW-WR-04 | warning | The Administrators and Roles hooks fire `BackendAccessRevokedEvent` with a possibly nil `Tx`, and the listener then revokes outside the save's transaction | fixed | 32.2-REVIEW-FIX.md a261a8fd |
| FW-WR-05 | warning | The deactivate site hands listeners an `Unscoped` session as `Tx`, unlike every other site | fixed | 32.2-REVIEW-FIX.md 60bc6ee6 |
| FW-WR-06 | warning | The framework never checks the provider's redirect against the request's redirect URI, and the SPA guard is only a scheme deny-list | fixed | 32.2-REVIEW-FIX.md 0ade662a |
| FW-IN-01 | info | A requested `*` is offered to administrators who hold no permission, so the "none grantable" state never shows for them | open | — |
| FW-IN-02 | info | The session binding namespaces can collide | open | — |
| FW-IN-03 | info | Item actions can answer 409, but the OpenAPI annotation does not document it | open | — |
| FW-IN-04 | info | The new literal admin API routes shadow controller routes of a vendor named `mcp` or `account` | open | — |
| FW-IN-05 | info | Dispatched calls of administrator OAuth grants carry no credential, so `interactiveOnly` cannot tell them from a cookie session | open | — |
| PA-CR-01 | critical | App master pins oauthserver v0.1.7, which ignores `mcp.subject`/`oidc.enabled`, and check-deploy cannot tell | deferred | detection in 2190109 (app); fix is the held release pointer bump, UAT item 4 |
| PA-WR-01 | warning | Administrator refresh asks the pool for a second connection while holding the rotation transaction | fixed | 32.2-REVIEW-FIX-plugin-app.md 1f872f6 |
| PA-WR-02 | warning | A transient failure in the administrator lookup becomes a terminal `invalid_grant` or 401 | fixed | 32.2-REVIEW-FIX-plugin-app.md 7873a2a |
| PA-WR-03 | warning | The consent decision and the code exchange never re-validate the administrator under the lock | fixed | 32.2-REVIEW-FIX-plugin-app.md c99e7e5 |
| PA-WR-04 | warning | Two administrators deciding the same pending request are not serialized, and the last writer silently wins | fixed | 32.2-REVIEW-FIX-plugin-app.md b56b411 |
| PA-WR-05 | warning | The verifier accepts administrator grants whatever the configured mode | fixed | 32.2-REVIEW-FIX-plugin-app.md 7a28ec9 |
| PA-WR-06 | warning | The BackendCascade fallback without a transaction makes the revocation non-atomic and the lock a no-op | fixed | 32.2-REVIEW-FIX-plugin-app.md 12caf3f |
| PA-WR-07 | warning | The DEPLOY.md rollback leaves administrators' grants alive for a later re-enable | fixed | 32.2-REVIEW-FIX-plugin-app.md 3215b68 (app) |
| PA-WR-08 | warning | smoke-mcp-oauth.sh puts passwords, the authorization code and the PKCE verifier on process argv | fixed | 32.2-REVIEW-FIX-plugin-app.md 7934a55 (app) |
| PA-WR-09 | warning | The committed `mcp.resource` is loopback, and a missing env override fails silently | fixed | 32.2-REVIEW-FIX-plugin-app.md f9819b3 (plugin), 013d3f9 (app) |
| PA-IN-01 | info | Migration rollback keeps administrators' MCP codes | open | — |
| PA-IN-02 | info | The Clients screen's authorizations partial silently drops administrators' consents | open | — |
| PA-IN-03 | info | check-deploy's OpenID Connect location regex misses broader routes | open | — |
| PA-IN-04 | info | The advisory lock keys are 32-bit `hashtext` values shared with the user-grants namespace | open | — |
| PA-IN-05 | info | Smoke step 12 does not prove the cascade or the refresh | open | — |
| PA-IN-06 | info | The refresh-token CHECK allows `user_id = 0`, unlike the access-token CHECK | open | — |
| PA-IN-07 | info | A wall-clock sleep in a Docker test | open | — |
| PA-IN-08 | info | nginx `limit_except` refuses CORS preflight on the authorization server endpoints | open | — |

View File

@@ -0,0 +1,172 @@
---
phase: 32.2-mcp-oauth-with-administrator-subjects
fixed_at: 2026-11-21T10:30:00Z
review_path: .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-REVIEW-plugin-app.md
iteration: 1
findings_in_scope: 10
fixed: 10
skipped: 0
status: all_fixed
---
# Phase 32.2: Code Review Fix Report (sm-oauthserver-plugin and sm-grzybyfunkcjonalne-app)
**Fixed at:** 2026-11-21T10:30:00Z
**Source review:** .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-REVIEW-plugin-app.md
**Iteration:** 1
**Summary:**
- Findings in scope: 10 (CR-01, WR-01 .. WR-09; Info findings IN-01 .. IN-08 out of scope)
- Fixed: 10 (CR-01 only partly: the check is in place, the pointer bump is still held)
- Skipped: 0
- Framework-review plugin follow-ups: 3 applied (see the last section)
**Scope.** I edited and committed only `../sm-oauthserver-plugin` (master, 9 new local commits) and `../sm-grzybyfunkcjonalne-app` (master, 4 new local commits). I did not touch the framework repo. Nothing was pushed or tagged. In the app I left `go.work`, the ` M plugins/golem15/oauthserver` working-tree pointer and the untracked dirs alone. In the plugin I left its local ` M go.work` alone. `workflow.use_worktrees` is `false`, so all edits, commits and gates ran in the main checkouts of the two sibling repos. The results can be reproduced from those trees.
## Fixed Issues
### CR-01: App master pins oauthserver v0.1.7, and check-deploy cannot tell
**Repo:** sm-grzybyfunkcjonalne-app
**Files modified:** `scripts/check-deploy.sh`, `DEPLOY.md`
**Commit:** 2190109
**Applied fix:** check-deploy now refuses a tree whose oauthserver predates backend mode. It fails in each of these cases:
- `go.mod` requires `sm-oauthserver-plugin v0.1.0` .. `v0.1.7`;
- `plugins.gen.go` records such a version for `golem15.oauthserver`;
- the checked-out plugin lacks `SubjectModeBackend = "backend"`;
- the committed gitlink's tree (`git ls-tree HEAD` plus `git show <pin>:classes/mcp_backend_subject.go`) lacks it.
DEPLOY.md says to run the check before tagging or deploying. The real fix, the release pointer bump (gitlink, go.mod require, plugins.gen.go), is **held by the user (UAT item 4)** and was not made. Because of that, `scripts/check-deploy.sh` now **fails at app HEAD on purpose**: "go.mod requires sm-oauthserver-plugin v0.1.7, which predates mcp.subject backend". It will pass once the bump lands.
**Status:** fixed: requires human verification (the check fails until the held bump)
### WR-01: Administrator refresh asks the pool for a second connection while holding the rotation transaction
**Repo:** sm-oauthserver-plugin
**Files modified:** `classes/mcp_store.go`, `backend_review_fix_test.go` (new)
**Commit:** 1f872f6
**Applied fix:** `refreshUserUsable` now loads the administrator with `cabana.BackendUsers{DB: t.db}.FindByID`, through the new unexported `backendAdminTx`. That runs on the rotation's own transaction instead of `cabana.BackendPrincipal`, which took a second pooled connection. The fix needs no framework change. `TestBackendRefreshOnOneConnection` sets the pool to one connection: the old code timed out and refused the refresh, and the new code completes. I confirmed the test fails on the old code.
### WR-02: A transient failure in the administrator lookup becomes a terminal `invalid_grant` or 401
**Repo:** sm-oauthserver-plugin
**Files modified:** `classes/mcp_store.go`, `classes/mcp_verifier.go`, `backend_review_fix_test.go`, `README.md`
**Commit:** 7873a2a
**Applied fix:**
- **Refresh.** A lookup error is returned, so the request fails closed with a retryable 5xx. A nil administrator still makes the grant unusable.
- **Verifier.** `cabana.ErrUnauthenticated` (cabana not activated) still answers `ErrMCPTokenInvalid`. Every other error is returned as it is.
- **Test.** `TestBackendLookupFailureIsNotTerminal` renames `backend_users` to simulate a database blip. Both paths return an error rather than a refusal, and both accept the grant again once the table is back. It fails on the old code.
### WR-03: The consent decision and the code exchange never re-validate the administrator under the lock
**Repo:** sm-oauthserver-plugin
**Files modified:** `classes/mcp_backend_subject.go`, `classes/mcp_store.go`, `controllers/mcp_admin_consent.go`, `backend_review_fix_test.go`, `README.md`
**Commit:** c99e7e5
**Applied fix:**
- **New helper.** The exported `classes.BackendSubjectCurrent(ctx, db, adminID, at)` reads the administrator in the locked transaction and applies the verifier's cutoff rule.
- **Decision.** `MCPAdminConsentDecide` records the start of the decision. Under `WithinBackendGrantsLock` it refuses with 404 and writes nothing when the administrator no longer loads or `tokens_valid_after` moved after that start. The refusal is logged as a warning.
- **Exchange.** `ByCodeHashForUpdate` refuses an administrator's code with `invalid_grant` when the administrator no longer loads, or when the code's issue time (`updated_at`, falling back to `created_at`) is before the cutoff.
- **Test.** `TestBackendSubjectRevalidatedUnderLock` covers three cases, and all three fail on the old code:
- a decision blocked on the lock while a transaction moves `tokens_valid_after` the way cabana does (now+1s): 404, no code, no consent;
- the exchange after a direct cutoff move: 400;
- the exchange after a deactivation: 400.
**Status:** fixed: requires human verification (cutoff timing logic)
### WR-04: Two administrators deciding the same pending request are not serialized
**Repo:** sm-oauthserver-plugin
**Files modified:** `classes/mcp_store.go`, `backend_review_fix_test.go`, `README.md`
**Commit:** b56b411
**Applied fix:** `MarkIssued` now updates only a row that is still pending: `code_hash IS NULL AND request_id IS NOT NULL AND used_at IS NULL`. When the update matches no row, it returns `wristband.ErrPendingNotFound`. The consent API maps that to 404 and rolls back the second decision's consent write. Outside the race, behaviour is unchanged, in user mode too. `TestMCPMarkIssuedOnlyOnce`: a second issue on the same row returns `ErrPendingNotFound`, and the first issue's hash and administrator stay in place. It fails on the old code.
### WR-05: The verifier accepts administrator grants whatever the configured mode
**Repo:** sm-oauthserver-plugin
**Files modified:** `classes/lazy.go`, `classes/mcp_store.go`, `classes/mcp_verifier.go`, `servers.go`, `backend_review_fix_test.go`, `README.md`
**Commit:** 7a28ec9
**Applied fix:**
- **New fields.** `LazyMCPStore.BackendSubjects` and `MCPTokenVerifier.BackendSubjects` are new exported fields, so no existing API breaks. `NewServers` sets both from `cfg.BackendMode()`.
- **The zero value refuses administrator rows.** In user mode an administrator's access token is `ErrMCPTokenInvalid`, and their code and refresh token are `invalid_grant`.
- **The unused `app` field was removed.** The store's `app` field (unexported) existed only for the old refresh lookup.
- **Not mirrored in backend mode.** Frontend users' grants keep verifying in backend mode, because an existing test pins that frontend users' grants are "never touched". I enforced only the direction the review asked for.
- **Test.** `TestUserModeRefusesAdministratorGrants`: the user-mode values refuse all three grant kinds, and the backend-mode values accept them.
- **Red check.** I did not run this test against the old code: it does not compile there, because the new field is missing.
### WR-06: The BackendCascade fallback without a transaction makes the revocation non-atomic
**Repo:** sm-oauthserver-plugin
**Files modified:** `classes/backend_cascade.go`, `backend_review_fix_test.go`, `README.md`
**Commit:** 12caf3f
**Applied fix:** I followed the framework review's follow-up and refused a nil `Tx` (the fail-closed choice). I did not use the reviewer's alternative of opening the listener's own transaction. Framework WR-04 already guarantees cabana never fires the event without a transaction.
- `txOf` and the pool fallback are gone. An event with a nil `Tx` answers the new `classes.ErrBackendRevocationNoTx` and revokes nothing.
- **Test.** `TestBackendCascadeRefusesNoTx`: the nil-`Tx` event returns the error and the grant still verifies; the same event inside a transaction revokes the grant.
This commit also covers the framework follow-up "BackendCascade txOf fallback".
### WR-07: The DEPLOY.md rollback leaves administrators' grants alive
**Repo:** sm-grzybyfunkcjonalne-app
**Files modified:** `DEPLOY.md`
**Commit:** 3215b68
**Applied fix:** The OAuth rollback now ends the grants before the restart. One `psql` transaction (DSN read from `.env`, `ON_ERROR_STOP`):
- revokes the access and refresh tokens with `user_id IS NULL`;
- deletes administrators' unused MCP codes;
- deletes the consents with `user_id IS NULL`.
The section explains why: grants are not revoked while the switch is off, and they come back on a roll forward. It also warns against a partial `SUBJECT=user` rollback. I checked the column names against the plugin models. I did not run the SQL on a server.
### WR-08: smoke-mcp-oauth.sh puts passwords, the authorization code and the PKCE verifier on argv
**Repo:** sm-grzybyfunkcjonalne-app
**Files modified:** `scripts/smoke-mcp-oauth.sh`
**Commit:** 7934a55
**Applied fix:**
- jq now reads the passwords and the consent redirect from its environment (`env.L`, `env.P`, `env.U`, `env.K`, `env.E`, `env.C`) instead of `--arg`.
- curl reads the PKCE verifier from a file (`code_verifier@$TMP/verifier`), the way it already read the code.
- The script runs under `umask 077`.
- The header now states the guarantee, and the usage range was updated.
The script passes locally (12 steps).
### WR-09: The committed `mcp.resource` is loopback, and a missing env override fails silently
**Repos:** both
**Commits:** plugin f9819b3, app 013d3f9
**Applied fix:**
- **Plugin** (`servers.go`, `resource_check_test.go` new, `README.md`). With `mcp.enabled`, `LoadConfig` checks for a loopback `mcp.resource` (`localhost`, `*.localhost`, a loopback IP) on an issuer that is not loopback:
- in backend mode it fails boot, and the error names `SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE`;
- in user mode it only logs a warning, so existing user-mode applications boot as before;
- local development (loopback on both sides) is unaffected.
`TestLoopbackResourceOnPublicIssuer` is a short test and fails on the old code.
- **App** (`scripts/check-deploy.sh`, `DEPLOY.md`).
- check-deploy requires `deploy/env.example` to set the override to `<SUMMER_APP__URL>/mcp`, both for UAT and in the production comment block. I checked it against two broken templates and it caught both.
- `check-deploy.sh --live` reads Go's protected resource metadata on 127.0.0.1:8096. It fails when the resource is loopback or its origin is not `authorization_servers[0]`, and skips when MCP is off (404). The live branch was not run on a server. I tested its Python against sample metadata, one good and one mismatched.
- DEPLOY.md documents both checks and the plugin's boot refusal.
## Framework review follow-ups (sm-oauthserver-plugin)
- **wristband WR-02, `CheckConsentPath` at boot.** Commit d581799 (`servers.go`, `backend_review_fix_test.go`, `README.md`). With `mcp.enabled`, `NewServers` checks the resolved consent path in either mode and fails boot on a bad one. With MCP off the key is not read. `TestConsentPathCheckedAtBoot` fails on the old code.
- Behaviour note: a user-mode application with MCP on and an invalid `mcp.consent_path` (for example one with a `?` or no leading `/`) now fails boot. Before, it booted, and with the new framework its authorize would answer 500.
- **cabana WR-04, `BackendCascade.txOf` fallback.** Done in the WR-06 commit 12caf3f.
- **cabana WR-06, decide answers built from the pending redirect URI.** Commit 93c0b40 (`controllers/mcp_admin_consent.go` doc comment, `backend_review_fix_test.go`). The provider already built both answers through wristband. `TestAdminConsentAnswersThePendingRedirect` checks that the allow and deny answers keep the registered scheme, host and path, have no user info or fragment, and carry code or error plus state.
## Verification
All gates ran in the main checkouts of the two sibling repos (no worktree). Docker was reachable directly.
- **Plugin, every commit:** `go vet ./...` clean and `go test -short ./...` ok.
- **Plugin, per commit:** Docker runs of the touched areas, `go test -run 'TestBackend|TestMCP' .` and the like, all ok.
- **Plugin, full suite:** `go test -count=1 ./...` (about 2 minutes) ok after WR-04, after WR-05 and after the last commit (WR-09).
- **Red checks:** each new test failed against the code before its fix, by stashing that fix. The exceptions are WR-05 and WR-06, whose tests reference new symbols and do not compile on the old code.
- **App:**
- `go vet ./...` clean;
- `go test -short -tags summercms_mcp ./...` ok;
- `scripts/smoke-mcp-oauth.sh` ok (12 steps), against the submodule's plugin;
- `scripts/check-deploy.sh` fails with the CR-01 message, which is expected until the held pointer bump. Every check before it passes, including the new env.example check.
- **App against the fixed plugin.** I used a temporary `GOWORK` in the scratchpad that points the oauthserver module at `../sm-oauthserver-plugin`, without touching the app's `go.work`. With it, `go test -tags summercms_mcp -count=1 ./...` passed, and `scripts/smoke-mcp-oauth.sh` passed (12 steps). So the app boots and signs in with all plugin fixes, including the WR-09 boot check.
---
_Fixed: 2026-11-21T10:30:00Z_
_Fixer: Claude (msd-code-fixer)_
_Iteration: 1_

View File

@@ -0,0 +1,92 @@
---
phase: 32.2-mcp-oauth-with-administrator-subjects
fixed_at: 2026-11-21T09:40:00Z
review_path: .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-REVIEW.md
iteration: 1
findings_in_scope: 6
fixed: 6
skipped: 0
status: all_fixed
---
# Phase 32.2: Code Review Fix Report
**Fixed at:** 2026-11-21T09:40:00Z
**Source review:** .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-REVIEW.md
**Iteration:** 1
**Summary:**
- Findings in scope: 6 (WR-01 .. WR-06; Info findings IN-01 .. IN-05 out of scope)
- Fixed: 6
- Skipped: 0
Scope: framework repository only (summercms.go, branch master). `workflow.use_worktrees` is `false`, so all edits and commits were made in the main checkout and every verification gate below ran there; the results are reproducible from this tree. The sibling repositories were not touched; plugin follow-ups are listed at the end.
## Fixed Issues
### WR-01: `DefaultScopes` never applies to an `offline_access`-only authorize request
**Files modified:** `modules/wristband/authorize.go`, `modules/wristband/server.go`, `modules/wristband/consent_path_test.go`, `modules/wristband/README.md`, `docs/services/oauth-server.md`
**Commit:** fa7a8482
**Applied fix:** `parseAuthorizeScopes` takes a `defaultsSet` flag (true when `Options.DefaultScopes` is non-empty). With it set, a request whose only remaining token is `offline_access` gets the filtered default scopes plus `offline_access`, so the pending request carries data scopes and keeps offline access. Without `DefaultScopes` the PHP behaviour is unchanged. `defaultAuthorizeScopes` never takes `offline_access` from the list, and the `["read"]` fallback is used only when the server accepts `read`; otherwise a request naming no scope is refused with `invalid_scope` (RFC 6749 section 3.3) instead of storing a scope the server does not advertise. Tests: offline_access-only (also with `openid` and repeated) gets the defaults and the offline flag; no `DefaultScopes` keeps PHP parity; a server without `read` refuses a scopeless request.
**Status:** fixed: requires human verification (scope-fallback logic)
### WR-02: `ConsentPath` concatenated onto `Issuer` without validation
**Files modified:** `modules/wristband/authorize.go`, `modules/wristband/server.go`, `modules/wristband/consent_path_test.go`, `modules/wristband/README.md`, `docs/services/oauth-server.md`
**Commit:** 1dcc2ed0
**Applied fix:** `NewServer` returns no error and changing its signature would break the plugin, so the fix is additive: a new exported `wristband.CheckConsentPath(p string) error` (empty is valid; otherwise it must start with a single `/` and carry no `?`, `#`, `\`, `@`, whitespace or control character) that hosts can call at boot, and `Authorize` checks it before storing the pending request. While the configured path fails, it answers 500 with no `Location`, so the handoff can never leave the issuer's origin. Test: the accepted and refused paths (including `@evil.example/connect`, `backend/connect`, `//evil`, `/\evil`, `?`, `#`), plus authorize answering 500 with no Location and no stored pending row.
### WR-03: pier treats an unknown `MCPGrant.Subject` as a frontend-user grant
**Files modified:** `modules/pier/identity.go`, `modules/pier/backend_only_grant_test.go`, `modules/pier/README.md`, `modules/pact/mcp.go`, `modules/pact/README.md`, `docs/services/mcp.md`
**Commit:** 19bb3f94
**Applied fix:** `resolveOAuth` switches on `grant.Subject`: `pact.MCPGrantSubjectBackend` goes to `resolveBackendGrant`, the empty value is the legacy user grant, and any other value is `ErrUnauthorized`. Regression grants with `Subject: "member"` and `Subject: "Backend"` (both with a frontend user and a linked administrator) are refused, and the linked-backend resolver is never called for them. I confirmed the test fails against the previous code.
### WR-04: Administrators and Roles hooks fire `BackendAccessRevokedEvent` with a possibly nil `Tx`
**Files modified:** `modules/cabana/admin_events.go`, `modules/cabana/backend_users_admin.go`, `modules/cabana/backend_roles_admin.go`, `modules/cabana/backend_access_revoked_tx_test.go` (new), `modules/cabana/README.md`, `docs/services/events.md`
**Commit:** a261a8fd
**Applied fix:** `fireBackendAccessRevoked` refuses a nil `tx` with an error before any listener runs, whenever there are ids to fire for. The `usersAdmin.FormAfterUpdate` hook computes whether it will revoke, and only then requires `TxFromContext` (fail closed with "an update needs its transaction", like the delete hook), so saves that revoke nothing behave as before. `rolesAdmin.FormAfterUpdate` checks `ok` too and still passes the raw transaction, like every other site. The event doc now says `Tx` is never nil. New short test (no Docker): the helper refuses nil tx and runs no listener, both user-hook revocation paths and the role hook refuse without a transaction, and a no-op update still passes.
**Status:** fixed: requires human verification (hook state handling)
### WR-05: The deactivate site hands listeners an `Unscoped` session as `Tx`
**Files modified:** `modules/cabana/backend_users_admin.go`, `modules/cabana/backend_access_revoked_smoke_test.go`, `modules/cabana/admin_events.go`
**Commit:** 60bc6ee6
**Applied fix:** The deactivate lifecycle passes `TxFromContext(ctx)` (the save's own transaction) instead of `actionDB`'s Unscoped session. The Docker smoke test now asserts for every reason that `ev.Tx.Statement.Unscoped` is false. I confirmed it fails on the old code ("deactivated: event Tx is Unscoped").
### WR-06: The framework never checks the provider's redirect against the request's redirect URI
**Files modified:** `modules/cabana/mcp_consent.go`, `modules/cabana/mcp_admin_consent_test.go`, `modules/cabana/admin_openapi.go`, `admin/openapi/admin.json`, `admin/src/api/schema.d.ts` (regenerated), `admin/src/views/ConnectView.vue`, `admin/tests/views/ConnectView.test.ts`, `modules/boardwalk/dist/*` (rebuilt), `modules/cabana/README.md`, `modules/pact/mcp.go`, `modules/pact/README.md`, `docs/services/oauth-server.md`, `docs/backend/admin-spa.md`
**Commit:** 0ade662a
**Applied fix:**
- **Server.** `mcpConsentDecide` validates the decision word first, then loads the request through `MCPAdminConsentShow` for both allow and deny. A deny of an unknown request is now 404 from Show and no longer reaches Decide. After Decide, the new `mcpConsentSameRedirect` requires the answer to keep the registered redirect URI's scheme, user info, host with port, opaque part and escaped path; only the query and fragment may differ. A mismatch is logged and answered with 500 without echoing the URI.
- **SPA.** The scheme deny-list now also refuses `blob:`, `file:`, `about:` and `filesystem:`. The destination must also return to `consent.client.redirect_host`: hosts are compared through the browser URL parser (so case and default ports are normalised), and host-less custom-scheme URIs are compared without query and fragment.
- **Generated files and docs.** The swag description was updated and `admin/openapi/admin.json` and `schema.d.ts` regenerated. The dist was rebuilt.
- **Tests.**
- Go: foreign redirects (other host, other scheme, other path, host added, `javascript:`, relative) are refused on both decisions, and the registered redirect with its own query and fragment is accepted. A new short `TestMCPConsentSameRedirect` table was added.
- SPA: the new schemes, foreign hosts, a different port and a custom-scheme redirect against a web host all fail. A host matching case- and default-port-insensitively is accepted. The custom-scheme fixture now carries the matching `redirect_host`.
- **Note.** A refused redirect is caught after the provider has already committed its decision. The code never reaches the browser, but the pending request is used up.
**Status:** fixed: requires human verification (redirect comparison logic)
## Verification
All gates ran in the main checkout (no worktree), on master:
- Every commit: `go vet ./...` clean, `go test -short ./...` all ok, `go test ./cmd/summer -run TestDocsTree` ok.
- Docker-backed (Docker reachable directly): `go test ./modules/wristband` ok (WR-01, WR-02), `go test ./modules/pier` ok (WR-03), `go test ./modules/cabana` ok (WR-04, WR-05, WR-06), `go test ./modules/boardwalk` ok (WR-06).
- WR-06 admin: `npm --prefix admin run test` 117 files and 1738 tests passed, `npm --prefix admin run typecheck` clean, `npm --prefix admin run build` then `scripts/check-admin-dist.sh` ("dist matches a fresh build"), and `scripts/check-admin-openapi.sh --check` clean after regeneration.
## Plugin follow-ups (sm-oauthserver-plugin, not edited here)
- WR-02: call `wristband.CheckConsentPath(mcpOpts.ConsentPath)` in `NewServers` (servers.go, after the ConsentPath is resolved) and return the error, so a bad `mcp.consent_path` is refused at boot instead of producing 500s at authorize.
- WR-04: `BackendCascade.txOf` can drop its fallback to the application pool, because cabana now never fires `BackendAccessRevokedEvent` with a nil `Tx`. Refusing a nil `Tx` is the fail-closed choice and matches PA-WR-06.
- WR-06: the plugin's `MCPAdminConsentDecide` must keep answering a URI built from the pending request's `RedirectURI`, which it does today via wristband `IssueCode`/`DenyPending`. Any other answer is now a 500.
- WR-01: no change needed. In backend mode `DefaultScopes` is the catalog, which always contains `*`, so the `read` fallback is never reached there.
---
_Fixed: 2026-11-21T09:40:00Z_
_Fixer: Claude (msd-code-fixer)_
_Iteration: 1_

View File

@@ -0,0 +1,338 @@
---
phase: 32.2-mcp-oauth-with-administrator-subjects
reviewed: 2026-11-21T12:00:00Z
depth: standard
scope: sibling repos ../sm-oauthserver-plugin (7b9899f..HEAD) and ../sm-grzybyfunkcjonalne-app (c06a2d8..HEAD)
files_reviewed: 51
files_reviewed_list:
- ../sm-oauthserver-plugin/README.md
- ../sm-oauthserver-plugin/account.go
- ../sm-oauthserver-plugin/admin.go
- ../sm-oauthserver-plugin/admin_navigation.go
- ../sm-oauthserver-plugin/admin_permissions.go
- ../sm-oauthserver-plugin/admin_smoke_test.go
- ../sm-oauthserver-plugin/backend_account_smoke_test.go
- ../sm-oauthserver-plugin/backend_consent_test.go
- ../sm-oauthserver-plugin/backend_grant_rows_test.go
- ../sm-oauthserver-plugin/backend_mode_smoke_test.go
- ../sm-oauthserver-plugin/backend_mode_test.go
- ../sm-oauthserver-plugin/backend_revocation_smoke_test.go
- ../sm-oauthserver-plugin/backend_revoke_test.go
- ../sm-oauthserver-plugin/backend_subject_migration_test.go
- ../sm-oauthserver-plugin/backend_tools_test.go
- ../sm-oauthserver-plugin/classes/backend_cascade.go
- ../sm-oauthserver-plugin/classes/lazy.go
- ../sm-oauthserver-plugin/classes/mcp_backend_subject.go
- ../sm-oauthserver-plugin/classes/mcp_store.go
- ../sm-oauthserver-plugin/classes/mcp_verifier.go
- ../sm-oauthserver-plugin/config/config.yaml
- ../sm-oauthserver-plugin/controllers/mcp_admin_consent.go
- ../sm-oauthserver-plugin/controllers/mcp_connections.go
- ../sm-oauthserver-plugin/controllers/mcpconnections/config_list.yaml
- ../sm-oauthserver-plugin/harness_test.go
- ../sm-oauthserver-plugin/jwt_only_test.go
- ../sm-oauthserver-plugin/lang/en/lang.yaml
- ../sm-oauthserver-plugin/lang/pl/lang.yaml
- ../sm-oauthserver-plugin/models/consent.go
- ../sm-oauthserver-plugin/models/mcp_connection.go
- ../sm-oauthserver-plugin/models/mcpconnection/columns.yaml
- ../sm-oauthserver-plugin/plugin.go
- ../sm-oauthserver-plugin/routes.go
- ../sm-oauthserver-plugin/servers.go
- ../sm-oauthserver-plugin/updates/202611200001_add_golem15_oauthserver_backend_subjects.go
- ../sm-grzybyfunkcjonalne-app/.gitmodules
- ../sm-grzybyfunkcjonalne-app/DEPLOY.md
- ../sm-grzybyfunkcjonalne-app/README.md
- ../sm-grzybyfunkcjonalne-app/boot_test.go
- ../sm-grzybyfunkcjonalne-app/config/golem15.oauthserver.yaml
- ../sm-grzybyfunkcjonalne-app/config/mcp.yaml
- ../sm-grzybyfunkcjonalne-app/deploy/env.example
- ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-production.conf
- ../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-staging.conf
- ../sm-grzybyfunkcjonalne-app/go.mod
- ../sm-grzybyfunkcjonalne-app/go.work
- ../sm-grzybyfunkcjonalne-app/plugins/golem15/oauthserver
- ../sm-grzybyfunkcjonalne-app/scripts/build.sh
- ../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh
- ../sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh
- ../sm-grzybyfunkcjonalne-app/summer.yaml
findings:
critical: 1
warning: 9
info: 8
total: 18
status: issues_found
---
# Phase 32.2: Code Review Report (sm-oauthserver-plugin and sm-grzybyfunkcjonalne-app)
**Reviewed:** 2026-11-21T12:00:00Z
**Depth:** standard
**Files Reviewed:** 51
**Status:** issues_found
## Summary
Reviewed the backend-subject mode of sm-oauthserver-plugin (7b9899f..HEAD: 6996ffe, 9b97466, 4c209c1, bae8222, 793eadd, 1124fd1) and the first consumer wiring in sm-grzybyfunkcjonalne-app (c06a2d8..HEAD: 2953bf8, f2dc85d, df554d5). Framework code (cabana, wristband, pier) was read only where the plugin calls into it. A sibling reviewer covers the framework itself.
**User mode stays unchanged by default.** That holds for routes, scopes, admin surface, account contributions and listeners. Every new surface is gated on `cfg.BackendMode()`. Every user-mode query filters on `user_id`, so it never sees the `user_id IS NULL` rows. There are three global changes:
- the NOT VALID CHECK constraints, which every app gets;
- the verifier's new backend branch, which is not gated on mode (WR-05);
- the consents column, which needs `migrate` to run before the new binary.
**Lock design.** The design is sound:
- shared `golem15_oauthserver_backend_grants:<id>` on code exchange and refresh;
- exclusive on revocation, consent issue and bulk revoke;
- ascending id order.
The weak points are elsewhere:
- the refresh path asks for a second pool connection while it holds a transaction (WR-01);
- transient errors are turned into terminal `invalid_grant`/401 (WR-02);
- the consent decision does not re-validate the administrator inside the lock, and the exchange never validates it, so a race can mint a grant past a password-change cutoff (WR-03);
- the per-admin lock does not serialize two administrators deciding the same request (WR-04).
**App.** The committed app state is not deployable. The gitlink, go.mod and plugins.gen.go are still pinned to v0.1.7, which predates backend mode and ignores the new keys, and check-deploy.sh cannot detect it (CR-01). The nginx locations are correct: exact or prefix matches, method limits, a 64k body cap, `auth_basic off` on staging, and no `add_header`, which is enforced globally. The smoke script never prints a secret. It does put the passwords and the authorization code on jq's argv, which contradicts its stated guarantee (WR-08). The DEPLOY.md rollback boots, but it leaves administrators' grants alive for a later re-enable (WR-07).
## Critical Issues
### CR-01: App master pins oauthserver v0.1.7, which ignores `mcp.subject`/`oidc.enabled`, and check-deploy cannot tell
**File:** `../sm-grzybyfunkcjonalne-app/plugins/golem15/oauthserver` (gitlink 7b9899f), `../sm-grzybyfunkcjonalne-app/go.mod:12`, `../sm-grzybyfunkcjonalne-app/plugins.gen.go:42`, `../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh:372-395`
**Issue:**
- **The pin.** At app HEAD (df554d5) the committed gitlink is `7b9899f`, which is v0.1.7. go.mod requires `v0.1.7`, and plugins.gen.go records `Version: "v0.1.7"`.
- **What v0.1.7 does with this config.** DEPLOY.md:428 says it: "v0.1.7 and older ignore these keys and would serve a user-mode OAuth server with OpenID Connect". A fresh clone with `git submodule update --init` therefore builds a binary that:
- mounts the OIDC provider;
- runs MCP OAuth in **user** mode, with authorize handing off to Nuxt `/connect` instead of `/gfadmin/connect`;
- mounts the frontend-user consent JSON `/oauth/mcp/requests/{request}` (jwt.auth).
- **nginx exposes it.** The new `location ^~ /oauth/mcp/` in both vhosts sends that consent JSON to Go. A frontend user session could then finish MCP requests with the user-mode scopes (`read`, `write`, `backend`).
- **Nothing catches it.**
- `TestBootUserTranslateJournal` fails at these commits (32.2-04-SUMMARY, "Notes on the plan text").
- `check-deploy.sh` passes: it only greps `config/golem15.oauthserver.yaml` and summer.yaml, and never checks that the compiled plugin understands those keys.
- **Why it blocks.** This intermediate state is known and documented, and the release is on hold, but nothing stops it from shipping. A push of app master, or a deploy from it, runs the wrong security model with no error.
**Fix:** Do not push app master until the plan 05 pointer bump (gitlink, go.mod require and plugins.gen.go moved to the plugin release that contains 4c209c1). Also make check-deploy refuse a plugin without backend mode, for example:
```bash
# The compiled oauthserver must know mcp.subject backend (v0.1.8+).
grep -qF 'SubjectModeBackend = "backend"' "$ROOT/plugins/golem15/oauthserver/classes/mcp_backend_subject.go" 2>/dev/null ||
fail "plugins/golem15/oauthserver predates mcp.subject backend; bump the submodule"
grep -Eq 'golem15\.oauthserver.*Version: "v0\.1\.[0-7]"' "$ROOT/plugins.gen.go" &&
fail "plugins.gen.go pins golem15.oauthserver to a release without backend mode"
```
## Warnings
### WR-01: Administrator refresh asks the pool for a second connection while holding the rotation transaction
**File:** `../sm-oauthserver-plugin/classes/mcp_store.go:432-438`
**Issue:**
- **What happens.** `refreshUserUsable` runs inside wristband's `WithinTx`, which holds one pooled connection plus the shared advisory lock. For a backend row it calls `cabana.BackendPrincipal(ctx, t.app, …)`. That resolves to `lazyBackendUsers.FindByID`, which takes the app's `*gorm.DB` and runs `First(&user, id)` on a **different** pool connection (cabana/http.go:304-312, auth.go:44).
- **Why it hangs.** With N concurrent refresh rotations and a pool of N, every connection is held by a transaction waiting for a second connection. The pool deadlocks until the context times out. Postgres cannot detect this.
- **Inconsistency.** The user-mode branch right below it uses the transaction (`userclasses.PrincipalByID(ctx, t.db…)`).
**Fix:** Load the administrator through the transaction. Either query `backend_users` with `t.db`, or add a cabana helper that takes a `*gorm.DB`:
```go
if backendRefreshRow(m) {
principal, err := cabana.BackendPrincipalTx(ctx, t.app, t.db, *m.BackendUserID) // reads with t.db
...
}
```
Alternatively, resolve the principal before `WithinTx`. That is harder here, because the row is only known after the lookup.
### WR-02: A transient failure in the administrator lookup becomes a terminal `invalid_grant` or 401
**File:** `../sm-oauthserver-plugin/classes/mcp_store.go:434-437`, `../sm-oauthserver-plugin/classes/mcp_verifier.go:165-168`
**Issue:**
- **Refresh.** `err != nil || principal == nil` → `return false, nil`, and wristband answers `invalid_grant`.
- **Verifier.** The same condition answers `pact.ErrMCPTokenInvalid`, a 401.
- **Effect of a DB blip.** The access token gets a 401, so the client refreshes. The refresh gets `invalid_grant`, so the client (Claude, for example) drops the connection and the administrator has to sign in and consent again. A transient DB error, a context cancel or a pool timeout is enough.
- **User mode is different.** It returns `err` on lookup errors (mcp_store.go:445-447, mcp_verifier.go:124-127), which fails closed with a retryable 5xx.
- **Not a security fix.** Failing closed does not need the error to be terminal: a 500 also denies access.
**Fix:** Keep "nil principal" as unusable, and propagate real errors:
```go
principal, err := cabana.BackendPrincipal(ctx, t.app, *m.BackendUserID)
if err != nil {
return false, err
}
if principal == nil {
return false, nil
}
```
In `verifyBackend`, map `ErrUnauthenticated` (cabana not activated) to invalid and return other errors as they are.
### WR-03: The consent decision and the code exchange never re-validate the administrator under the lock
**File:** `../sm-oauthserver-plugin/controllers/mcp_admin_consent.go:129-144`, `../sm-oauthserver-plugin/classes/mcp_store.go:208-248`
**Issue:**
- **Where the check happens.** cabana authenticates the administrator and applies its scope policy before `MCPAdminConsentDecide` runs. The provider then takes the exclusive backend grants lock, but it never re-reads the administrator.
- **The race.** A password change, a password set or a deactivation runs in cabana's save transaction. It moves `tokens_valid_after` and takes the same exclusive lock in `RevokeBackendGrants`. A decision that passed cabana's check just before that save waits on the lock. After the save commits, it issues a fresh code and writes a consent.
- **The exchange does not check either.** `ByCodeHashForUpdate` only locks, so the exchange mints tokens whose `created_at` is **after** the new cutoff:
- after a password change (for example, to evict a stolen session), the attacker's in-flight consent leaves a fully valid OAuth grant, refresh included;
- after a deactivation, the minted grant is dormant and becomes valid again when the account is re-activated.
- **Leftover rows.** A consent row for the deactivated administrator also stays behind, and the admin list shows it.
**Fix:** Inside `WithinBackendGrantsLock`, after the lock, read the administrator with `tx` and refuse when they are inactive or deleted, or when their `tokens_valid_after` is later than the start of the request (pass the session's issued-at or the request time from cabana). Do the same check in `ByCodeHashForUpdate` for backend codes, as `refreshUserUsable` already does for refresh tokens:
```go
case owner.BackendUserID != nil:
if err := lockBackendGrantsShared(ctx, t.db, *owner.BackendUserID); err != nil { return nil, err }
// after taking the row: refuse when the administrator no longer loads or
// the code was issued before tokens_valid_after
```
### WR-04: Two administrators deciding the same pending request are not serialized, and the last writer silently wins
**File:** `../sm-oauthserver-plugin/classes/mcp_store.go:193-198` (ByRequestID, no row lock), `../sm-oauthserver-plugin/classes/mcp_store.go:321-322` (MarkIssued `WHERE id = ?`), `../sm-oauthserver-plugin/controllers/mcp_admin_consent.go:129`
**Issue:**
- **No serialization.** `WithinBackendGrantsLock(… []uint{adminID} …)` serializes only one administrator's own operations. A backend pending row keeps `user_id` NULL, so every administrator "owns" it (`lookupOwnedPending`).
- **The race.** `ByRequestID` reads without `FOR UPDATE`, and `MarkIssued` updates by id without any condition. When admins A and B both POST a decision for the same request, both read the unissued row. B's `UPDATE` waits on A's row lock, then overwrites `code_hash`, `scopes` and `backend_user_id`.
- **The result.** A's redirect carries a dead code. The client ends up with **B's** grant. B's consent row is written as well.
- **Scope.** The same unconditional `MarkIssued` exists in user mode. In backend mode it lets one administrator's approval silently become another administrator's grant.
**Fix:** Make the issue conditional and check the affected rows:
```go
res := t.db.WithContext(ctx).Model(&models.MCPCode{}).
Where("id = ? AND code_hash IS NULL AND request_id IS NOT NULL AND used_at IS NULL", id).
UpdateColumns(cols)
if res.Error != nil { return res.Error }
if res.RowsAffected != 1 { return wristband.ErrPendingNotFound }
```
Alternatively, row-lock the pending row in `ByRequestID` when it is called inside the decision transaction.
### WR-05: The verifier accepts administrator grants whatever the configured mode
**File:** `../sm-oauthserver-plugin/classes/mcp_verifier.go:121-123`, `../sm-oauthserver-plugin/classes/mcp_store.go:433-438`, `../sm-oauthserver-plugin/plugin.go:119-124`
**Issue:**
- **The ungated branch.** `token.UserID == 0 && token.BackendUserID != nil` routes to `verifyBackend` in user mode too. Refresh does the same through `backendRefreshRow`.
- **What survives a switch.** If an app switches `mcp.subject` from `backend` to `user` with `mcp.enabled` still true, every administrator grant keeps verifying and refreshing. At the same time:
- `BackendCascade` is no longer registered, so role, permission and superuser changes revoke nothing;
- the My account section is gone;
- the MCP connections screen and its permission are gone.
- **Consequence.** Nobody can see or revoke those grants from the UI. Only the `tokens_valid_after` and deactivated checks remain.
- **Docs.** The README states "One subject per application", but the code does not enforce it.
**Fix:** Give the verifier and the store the configured mode. In user mode, refuse backend-subject rows (`ErrMCPTokenInvalid`, refresh unusable). Alternatively, revoke all `user_id IS NULL` grants at boot when the mode is `user`.
### WR-06: The BackendCascade fallback without a transaction makes the revocation non-atomic and the lock a no-op
**File:** `../sm-oauthserver-plugin/classes/backend_cascade.go:36-44`, `../sm-oauthserver-plugin/classes/backend_cascade.go:48-53`
**Issue:**
- **The fallback.** When `ev.Tx` is nil, `txOf` returns the pool handle and `RevokeBackendGrants` runs on it.
- **What goes wrong.** `pg_advisory_xact_lock` then runs in autocommit, so the lock is released as soon as that statement ends. The SELECT, UPDATE and DELETE statements after it are separate transactions:
- a refresh rotation can mint a successor between the SELECT and the UPDATE, and the successor stays live;
- a failure part-way leaves the grants half revoked.
- **Today.** cabana passes a transaction at every site today, so this is latent. It is still the documented contract of `OnBackendAccessRevoked`.
**Fix:**
```go
if ev.Tx == nil {
db, err := lookupDB(c.App)
if err != nil { return err }
return lagoon.Transaction(ctx, db, func(ctx context.Context, tx *gorm.DB) error {
refs, err := RevokeBackendGrants(ctx, tx, ev.AdminIDs, "")
if err != nil { return err }
FireBackendRevokedAfterCommit(ctx, c.App, tx, refs)
return nil
})
}
```
### WR-07: The DEPLOY.md rollback leaves administrators' grants alive for a later re-enable
**File:** `../sm-grzybyfunkcjonalne-app/DEPLOY.md:440`
**Issue:**
- **What the rollback does.** `MCP__ENABLED=false` plus `MCP__SUBJECT=user` unmounts the routes and the verifier. The access tokens, refresh tokens and consents stay in the database.
- **Changes during the rollback are not applied.** `BackendCascade` is registered only in backend mode, so role, own-permission and superuser changes made during the rollback window revoke nothing. Password changes and deactivations are still caught by the cutoff check.
- **Re-enabling revives them.** Rolling forward again brings back every refresh token issued before the rollback, including grants an operator would expect to be gone after "rolling back OAuth".
- **Mode switch.** Combined with WR-05, `SUBJECT=user` with `ENABLED=true` (a plausible partial rollback) would keep them verifying.
**Fix:** Add a step that ends the grants. For example, run in psql:
`UPDATE golem15_oauthserver_access_tokens SET revoked_at = now() WHERE user_id IS NULL AND revoked_at IS NULL;`
Do the same for `golem15_oauthserver_refresh_tokens`, and `DELETE FROM golem15_oauthserver_consents WHERE user_id IS NULL;`. Alternatively, state plainly that re-enabling restores existing connections.
### WR-08: smoke-mcp-oauth.sh puts passwords, the authorization code and the PKCE verifier on process argv
**File:** `../sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh:344`, `:372`, `:391`, `:420-421`
**Issue:**
- **The claim.** The script header (lines 35-36) and 32.2-04-SUMMARY ("Access, refresh and personal tokens, the code and the passwords never reach a command line") promise that no secret reaches a command line.
- **What actually reaches argv:**
- `jq -n --arg l … --arg p "$ADMIN_PASSWORD"` (344);
- `jq -n … --arg c "$ADMIN_PASSWORD" --arg p "$NEW_PASSWORD"` (420-421);
- `jq -rn --arg u "$CALLBACK"`, where the callback URL holds the authorization code (372);
- `curl --data-urlencode "code_verifier=$VERIFIER"` (391).
- **Who can read it.** Every one of these is visible to other local users through `/proc/<pid>/cmdline` or `ps`.
- **Why it matters.** The values are throwaway, but the guarantee is false (T-32.2-24), and the script is the template the next app will copy.
**Fix:** Pass the values through the environment or files instead of argv:
```bash
login="$(L="$ADMIN_LOGIN" P="$ADMIN_PASSWORD" jq -n '{login: env.L, password: env.P}')"
raw="$(U="$CALLBACK" K="$1" jq -rn 'env.U | split("?")[1] | ...')"
printf 'code_verifier=%s' "$VERIFIER" >"$TMP/verifier"; curl ... --data-urlencode "code_verifier@$TMP/verifier"
```
Note that `VAR=x cmd` puts the value in the environment, not in argv.
### WR-09: The committed `mcp.resource` is loopback, and a missing env override fails silently
**File:** `../sm-grzybyfunkcjonalne-app/config/golem15.oauthserver.yaml:26`
**Issue:**
- **The default.** `resource: http://127.0.0.1:8096/mcp` is the committed value for every environment. Production and UAT depend on `SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE` in `go/.env`.
- **When the key is missing.** pier only logs a warning (DEPLOY.md:426). The AS advertises and accepts the loopback resource, and Claude's request for `https://grzybyfunkcjonalne.pl/mcp` fails.
- **Nothing guards it.** check-deploy, the boot test and the release steps do not check it.
- **The pieces already exist.** `mcp.yaml` derives its resource from `app.url`, so the two can drift.
**Fix:** Leave `resource` empty and have the plugin default it to `<app.url>/mcp` in backend mode. Alternatively, make a mismatch between pier's resource and the verifier's resource fail boot when both are configured. At minimum, add a post-deploy check that `/.well-known/oauth-protected-resource/mcp` `.resource` equals the authorization server's `resource`.
## Info
### IN-01: Migration rollback keeps administrators' MCP codes
**File:** `../sm-oauthserver-plugin/updates/202611200001_add_golem15_oauthserver_backend_subjects.go:46-48`
**Issue:** The rollback deletes `user_id IS NULL` access tokens, refresh tokens and consents. It does not delete issued but unexchanged MCP codes that have `user_id IS NULL AND backend_user_id IS NOT NULL`. Those rows survive the down migration as orphans that the older code cannot interpret. They expire quickly, but the README's "rollback deletes every administrator's grant" is not quite true.
**Fix:** Add `DELETE FROM golem15_oauthserver_mcp_codes WHERE user_id IS NULL AND backend_user_id IS NOT NULL AND code_hash IS NOT NULL`.
### IN-02: The Clients screen's authorizations partial silently drops administrators' consents
**File:** `../sm-oauthserver-plugin/controllers/clients.go:251-290`
**Issue:** The partial loads every consent for the client and looks up `consent.UserID` among frontend users. Backend consents (UserID 0) are skipped with `continue`, so an operator who inspects an MCP client sees no administrator connections.
**Fix:** Filter with `user_id IS NOT NULL` explicitly. Optionally, show the administrators' rows, or link to the MCP connections screen.
### IN-03: check-deploy's OpenID Connect location regex misses broader routes
**File:** `../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh:336`
**Issue:** The regex only finds the literal paths. `location ^~ /oauth/`, `location /oauth` or a regex such as `~ ^/oauth/(token|jwks)` would route the OIDC paths to Go and pass the check.
**Fix:** Refuse any `location` that matches `/oauth` other than the exact `^~ /oauth/mcp/`, the same way the `/_seo` check works.
### IN-04: The advisory lock keys are 32-bit `hashtext` values shared with the user-grants namespace
**File:** `../sm-oauthserver-plugin/classes/mcp_backend_subject.go:56-58`, `:70`, `:84`
**Issue:** `hashtext("golem15_oauthserver_backend_grants:N")` and the user-grants keys share one int4 space. A collision is unlikely but possible. It would make unrelated transactions contend, and transactions that take both kinds of lock (a cabana save firing both user-link and backend events) could deadlock.
**Fix:** Use the two-key form, `pg_advisory_xact_lock(<namespace const>, id)`.
### IN-05: Smoke step 12 does not prove the cascade or the refresh
**File:** `../sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh:417-432`
**Issue:** The 401 after the password change also follows from the `tokens_valid_after` check alone. If `BackendCascade` were not registered, the step would still pass. The refresh token obtained in step 9 is never used, so neither rotation nor refusal after revocation is covered end to end.
**Fix:** After the password change, also POST `grant_type=refresh_token`, with the token passed from a file, and expect 400 `invalid_grant`.
### IN-06: The refresh-token CHECK allows `user_id = 0`, unlike the access-token CHECK
**File:** `../sm-oauthserver-plugin/updates/202611200001_add_golem15_oauthserver_backend_subjects.go:38-39`
**Issue:** The comment says the CHECK refuses the zero `user_id` a GORM create of a zero uint writes. Only the access-token CHECK has `user_id > 0`. The refresh-token and consent CHECKs accept `user_id = 0` with `backend_user_id` NULL.
**Fix:** Use the same `(user_id IS NOT NULL AND user_id > 0) OR backend_user_id IS NOT NULL` on all three tables.
### IN-07: A wall-clock sleep in a Docker test
**File:** `../sm-oauthserver-plugin/backend_revoke_test.go:298-321`
**Issue:** The test sets the cutoff to `time.Now()+1s` and then sleeps 2.1 s, relying on the verifier's one-second margin and on the app and DB clocks matching. On a loaded CI host this is a source of flakiness, and it adds 2 s to every run.
**Fix:** Write a cutoff in the past relative to a controllable clock (the verifier has `clock()`), or set `tokens_valid_after` to `now - 1s` and create the fresh grant after it.
### IN-08: nginx `limit_except` refuses CORS preflight on the authorization server endpoints
**File:** `../sm-grzybyfunkcjonalne-app/deploy/nginx/grzybyfunkcjonalne-production.conf:229-261` (same in staging)
**Issue:** `limit_except GET HEAD` and `limit_except GET POST` return 403 for `OPTIONS`. Browser-based MCP clients, such as the MCP Inspector, preflight the metadata and token endpoints, so they cannot connect. Claude's server-side connector is not affected.
**Fix:** If browser clients are in scope, allow `OPTIONS` and let the plugin answer CORS. Otherwise, document that only server-side connectors are supported.
---
_Reviewed: 2026-11-21T12:00:00Z_
_Reviewer: Claude (msd-code-reviewer)_
_Depth: standard_

View File

@@ -0,0 +1,234 @@
---
phase: 32.2-mcp-oauth-with-administrator-subjects
reviewed: 2026-11-21T12:00:00Z
depth: standard
scope: framework (summercms.go) half; sm-oauthserver-plugin and sm-grzybyfunkcjonalne-app reviewed separately
diff_base: 45eb34e5
files_reviewed: 56
files_reviewed_list:
- admin/src/api/types.ts
- admin/src/app/pageTitle.ts
- admin/src/app/router.ts
- admin/src/components/account/AccountContributions.vue
- admin/src/views/ConnectView.vue
- admin/src/views/LoginView.vue
- admin/tests/account/AccountContributions.test.ts
- admin/tests/app/router.test.ts
- admin/tests/smoke/account-items.smoke.test.ts
- admin/tests/smoke/connect.smoke.test.ts
- admin/tests/views/ConnectView.test.ts
- admin/tests/views/LoginView.test.ts
- docs/backend/admin-spa.md
- docs/backend/users-and-permissions.md
- docs/plugins/registration.md
- docs/services/events.md
- docs/services/mcp.md
- docs/services/oauth-server.md
- modules/cabana/README.md
- modules/cabana/account.go
- modules/cabana/account_contributions.go
- modules/cabana/account_items_smoke_test.go
- modules/cabana/account_items_test.go
- modules/cabana/admin_events.go
- modules/cabana/admin_openapi.go
- modules/cabana/backend_access_revoked_smoke_test.go
- modules/cabana/backend_access_revoked_test.go
- modules/cabana/backend_roles_admin.go
- modules/cabana/backend_users_admin.go
- modules/cabana/commands.go
- modules/cabana/contracts.go
- modules/cabana/export_test.go
- modules/cabana/http.go
- modules/cabana/mcp_admin_consent_test.go
- modules/cabana/mcp_consent.go
- modules/cabana/mcp_consent_smoke_test.go
- modules/cabana/openapi_conformance_test.go
- modules/cabana/phase10_coverage_test.go
- modules/cabana/phase10_csrf_test.go
- modules/cabana/security_coverage_test.go
- modules/cabana/token_routes_test.go
- modules/cabana/token_scope_names_test.go
- modules/cabana/token_scopes_export.go
- modules/pact/README.md
- modules/pact/capabilities.go
- modules/pact/mcp.go
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- modules/pier/README.md
- modules/pier/backend_guard.go
- modules/pier/backend_only_grant_test.go
- modules/pier/backend_subject_smoke_test.go
- modules/pier/identity.go
- modules/wristband/README.md
- modules/wristband/authorize.go
- modules/wristband/consent_path_smoke_test.go
- modules/wristband/consent_path_test.go
- modules/wristband/server.go
findings:
critical: 0
warning: 6
info: 5
total: 11
status: issues_found
---
# Phase 32.2: Code Review Report
**Reviewed:** 2026-11-21T12:00:00Z
**Depth:** standard
**Files Reviewed:** 56 (framework repository only; the generated `modules/boardwalk/dist`, `admin/openapi/admin.json` and `admin/src/api/schema.d.ts` were excluded)
**Status:** issues_found
## Summary
This review covers the framework half of phase 32.2: the cabana admin consent endpoints (`GET`/`POST {api}/mcp/consent/{request}`), the My account item action route, `BackendAccessRevokedEvent` at the D-13 sites, the pact contract additions, pier's administrator-only grant branch, wristband's `ConsentPath`/`DefaultScopes`, and the SPA `ConnectView`, `LoginView` hint and `AccountContributions` item rows. I traced the diff from `45eb34e5..HEAD` together with the helpers it calls: `scopeOverlaps`, `validateTokenScopes`, `accountPrincipal`, `interactiveOnly`, `requireAjax`, `lagoon.Transaction`/`AfterCommit`, `festival.Bus.Fire`, the crud save order (Fill, FormBeforeUpdate, applyPermissionValues, Save, FormAfterUpdate), `actionDB` and the boardwalk security headers.
The checks the caller asked for came out as follows:
- **CSRF on the consent POST.** It is wrapped in `interactiveOnly(requireAjax(...))`, the admin cookie is `SameSite=Strict`, and boardwalk sends `frame-ancestors 'none'` and `X-Frame-Options: DENY`. No CSRF or clickjacking path found. The GET has no side effects in cabana.
- **Scope escalation.** `grantableConsentScopes` keeps only requested catalog scopes that pass `scopeOverlaps`. The decision is filtered against that set and then runs through `validateTokenScopes`. An unrequested `*` is dropped, and a requested `*` collapses to `["*"]`. Offline access is the AND of requested and asked. The pier backend guard caps `ScopeLimited` subjects with `ScopeLimitFor` and refuses all-unknown scopes. I could not inject an unrequested or ungrantable scope.
- **Item-action authorization.** The route checks, in order: section exists, action exists, permission (403), the item ID is in the caller's own `Items` (read inside the transaction), then `Run`. No cross-admin path found.
- **In-transaction revocation event.** It fires at delete, deactivate, password set, own password change, `admin:reset-password` (now a lagoon transaction), user role/permission/superuser change and role permission change. The hook order means the `prior*` captures are correct. Problems remain in what Tx handle the listener gets (WR-04, WR-05).
- **ConnectView redirect handling.** It leaves through `window.location.assign` after a scheme deny-list. The redirect URI itself is never checked by the framework against the request it belongs to (WR-06).
No blockers were found in the framework half. The warnings are about fail-open edges and contract inconsistencies that a plugin (the sibling oauthserver plugin, or a future one) can trip over.
## Narrative Findings (AI reviewer)
## Warnings
### WR-01: `DefaultScopes` never applies to an `offline_access`-only authorize request, which ends in a consent screen with nothing to grant
**File:** `modules/wristband/authorize.go:270-283` (with `151-160`), `modules/wristband/server.go:102-107`
**Issue:** The `Options.DefaultScopes` doc says it applies when a request "names no data scope". `parseAuthorizeScopes` only falls back when `kept` is empty after dropping the identity scopes. `scope=offline_access` (or `openid offline_access`) leaves `kept = ["offline_access"]`, so the fallback is skipped. Lines 151-160 then remove `offline_access` into the boolean, and the pending request is stored with **zero data scopes**. In backend mode this request reaches cabana's consent with `scopes: []`, and the admin gets the "none grantable" dead end even though the operator configured `DefaultScopes` for exactly this case. MCP clients that ask only for a refresh token do this.
A related case: when `DefaultScopes` is empty, or nothing survives its filter, the fallback is `["read"]` without checking `allowed`. On a backend-mode server `read` is not in `scopes_supported`, so the stored request carries a scope the server does not advertise.
**Fix:** Apply the fallback on the data scopes, not on all kept scopes:
```go
data := 0
for _, p := range kept {
if p != "offline_access" {
data++
}
}
if data == 0 {
out := append([]string(nil), fallback...)
if stringSliceContains(kept, "offline_access") {
out = append(out, "offline_access")
}
return out, ""
}
```
Keep PHP parity by doing this only when `len(s.opts.DefaultScopes) > 0`, for example with a flag passed in. Add a test for `scope=offline_access` with `DefaultScopes` set.
### WR-02: `ConsentPath` is concatenated onto `Issuer` without validation and can send the browser off-origin
**File:** `modules/wristband/authorize.go:189, 198-205`, `modules/wristband/server.go:94-100`
**Issue:** `spa := s.opts.Issuer + s.consentPath() + "?request=" + ...` uses the option exactly as given. Neither wristband nor its only caller validates it (the sibling `sm-oauthserver-plugin/servers.go:149,216-229` passes the trimmed `mcp.consent_path` straight through). Some example values:
- `@evil.example/connect` produces `https://app.example@evil.example/connect`, an off-origin 302 carrying the pending request id.
- `backend/connect` (missing slash) produces `https://app.examplebackend/connect`.
- A value containing `?` gives a malformed `...?x=1?request=`.
The option is described as "elsewhere on the same origin", but nothing enforces that. This is public API (D-04, reversibility costly).
**Fix:** Validate in `wristband.New` (or the options constructor) and refuse at boot:
```go
if p := opts.ConsentPath; p != "" {
if !strings.HasPrefix(p, "/") || strings.HasPrefix(p, "//") || strings.ContainsAny(p, "?#\\@") {
return nil, fmt.Errorf("wristband: ConsentPath %q must be a same-origin absolute path", p)
}
}
```
### WR-03: pier treats an unknown `MCPGrant.Subject` as a frontend-user grant (fail-open)
**File:** `modules/pier/identity.go:218-223`
**Issue:** `resolveOAuth` branches only on `grant.Subject == pact.MCPGrantSubjectBackend`. Any other non-empty value, such as a future `"member"` kind, a typo in a verifier, or a value from a newer plugin running against an older framework, falls through to the legacy path. That path treats `UserID` as the frontend user and also runs `consentedBackendSubject` to attach a linked administrator. pact documents `Subject` as an enum whose only meanings are empty and `"backend"`, so an unrecognized value should be refused, not reinterpreted.
**Fix:**
```go
switch grant.Subject {
case pact.MCPGrantSubjectBackend:
return resolveBackendGrant(grant)
case "":
// legacy user grant, below
default:
return Identity{}, ErrUnauthorized
}
```
### WR-04: The Administrators and Roles hooks fire `BackendAccessRevokedEvent` with a possibly nil `Tx`, and the listener then revokes outside the save's transaction
**File:** `modules/cabana/backend_users_admin.go:854-863`, `modules/cabana/backend_roles_admin.go:200-203`
**Issue:** Both hooks use `tx, _ := TxFromContext(ctx)` and pass whatever they got to `fireBackendAccessRevoked`. The event's documented contract (`admin_events.go:18-24`) is "inside the transaction of the save ... with that transaction in Tx ... commit together or not at all". If either hook ever runs without a carried transaction (another crud entry point, a test harness, a future refactor), the event fires with `Tx == nil`. The only listener today (`sm-oauthserver-plugin` `BackendCascade.txOf`) then falls back to the application pool. It revokes grants on a second connection that commits on its own while the save may still roll back, and it can wait on row or advisory locks held by the open save. `FormAfterDelete` (`backend_users_admin.go:225-228`) and `actionDB` already fail closed in this situation; these two do not.
**Fix:** Fail closed, as the delete hook does:
```go
tx, ok := TxFromContext(ctx)
if !ok {
return errors.New("cabana: administrators: an update needs its transaction")
}
```
In the roles hook, `writeDB(ctx)` already requires the transaction, so reuse that handle instead of reading the context a second time. Optionally, make `fireBackendAccessRevoked` refuse a nil `tx` when listeners exist.
### WR-05: The deactivate site hands listeners an `Unscoped` session as `Tx`, unlike every other site
**File:** `modules/cabana/backend_users_admin.go:291` (compare `235`, `856-861`, `account.go:399`, `commands.go:169`)
**Issue:** In the deactivate lifecycle, `db` comes from `actionDB(ctx)`, which is `tx.Session(NewDB).WithContext(ctx).Unscoped().Session(&gorm.Session{})`. GORM keeps `Statement.Unscoped` across that last `Session`. So listeners get a handle on which `Delete` is a **hard delete** and queries include soft-deleted rows, but only when the reason is `deactivated`. The other reasons get the plain transaction. A listener that writes through `ev.Tx` with a model that has `gorm.DeletedAt` behaves differently depending on the reason. The oauthserver models currently have no `DeletedAt`, so nothing is hit today, but the event is public API meant for any plugin.
**Fix:** Pass the raw transaction at this site:
```go
tx, _ := TxFromContext(ctx) // actionDB already proved it exists
if err := fireBackendAccessRevoked(ctx, c.application(), tx, BackendAccessDeactivated, user.ID); err != nil {
```
Alternatively, document that `Tx` is a fresh session and pass `tx.Session(&gorm.Session{NewDB: true})` at every site.
### WR-06: The framework never checks the provider's redirect against the request's redirect URI, and the SPA guard is only a scheme deny-list
**File:** `modules/cabana/mcp_consent.go:218-232`, `admin/src/views/ConnectView.vue:192-203, 232-240`
**Issue:** `mcpConsentDecide` returns whatever string `MCPAdminConsentDecide` gives back as `redirect_uri`. ConnectView then navigates the top-level window to it after refusing only `javascript:`, `data:` and `vbscript:`. pact says the framework "owns the scope policy", but the open-redirect safety of the consent screen rests entirely on the provider. The framework already has the request's `RedirectURI` from the Show call on the allow path. Nothing confirms the returned URI is that redirect plus `code`/`state`/`error`. If a provider builds the URI from anything other than the registered redirect (a bug, or a future provider), the admin's browser is sent to an arbitrary scheme or host straight after consent, with an authorization code in the URL. The deny path does not even load the request.
**Fix:** In cabana, load the request on both paths, then refuse (500 and log) a redirect that does not match the registered one:
```go
want, _ := url.Parse(req.RedirectURI)
got, err := url.Parse(redirect)
if err != nil || got.Scheme != want.Scheme || got.Host != want.Host || got.Path != want.Path {
moduleLog.ErrorContext(ctx, "cabana: mcp consent provider answered a foreign redirect", "admin_id", principal.ID)
WriteError(w, http.StatusInternalServerError, "error", msgServerError)
return
}
```
In the SPA, also refuse `blob:`, `file:`, `about:` and `filesystem:`. Better, compare the destination's scheme and host with `consent.client.redirect_host` before calling `assign`.
## Info
### IN-01: A requested `*` is offered to administrators who hold no permission, so the "none grantable" state never shows for them
**File:** `modules/cabana/token_scopes.go:337-339` (used by `modules/cabana/mcp_consent.go:61-63`)
**Issue:** `scopeOverlaps` always answers true for `*`. A client that requests `* admin:read` shown to an administrator with no permissions lists `*` as grantable instead of the `none_grantable` explanation. The administrator can then allow a grant that can do nothing. This is consistent with g15_ token creation (documented in the 32.2-01 summary), but on consent it is misleading.
**Fix:** On the consent path, offer `*` only when the administrator is a superuser or holds at least one registered permission, the same test `admin:read` uses.
### IN-02: The session binding namespaces can collide
**File:** `modules/pier/identity.go:227, 262`
**Issue:** A user grant binds to `oauth:<client>:<user>` and an administrator grant to `oauth:backend:<client>:<admin>`. A user-mode client whose ID starts with `backend:` produces the same key as an administrator grant. Today this is prevented only by server-generated client IDs and the one-mode-per-app rule (D-07), which the CONTEXT plans to relax.
**Fix:** Use an unambiguous prefix such as `oauth-backend:<client>:<admin>`, or escape the `:` in client IDs.
### IN-03: Item actions can answer 409, but the OpenAPI annotation does not document it
**File:** `modules/cabana/admin_openapi.go:503-518`, `modules/cabana/account_contributions.go:349-355`
**Issue:** `writeCRUDError` maps an `actionConflict` from `Run` to 409, and `AccountContributions.vue` handles 409. `AdminAccountContributionItemAction` lists 401/403/404/422 only, and it also does not mention the `X-Requested-With` requirement that the decide annotation does mention.
**Fix:** Add `@Failure 409 {object} ErrorEnvelope` and "Needs X-Requested-With" to the description, then regenerate.
### IN-04: The new literal admin API routes shadow controller routes of a vendor named `mcp` or `account`
**File:** `modules/cabana/http.go:351-355`
**Issue:** `GET/POST /mcp/consent/{request}` is more specific than `/{vendor}/{plugin}/{controller}`, so a plugin `mcp.consent` loses its list and create routes without any boot error. The same goes for `account/contribution-items/...` against record actions of an `account.contribution-items` controller. This is unlikely, but nothing refuses it.
**Fix:** Refuse the vendor/plugin pairs `mcp/consent` and `account/contribution-items` when compiling controllers, or document them as reserved.
### IN-05: Dispatched calls of administrator OAuth grants carry no credential, so `interactiveOnly` cannot tell them from a cookie session
**File:** `modules/pier/identity.go:248-274`, `modules/pier/dispatch.go:207-216`, `modules/cabana/token_guard.go:154-171`
**Issue:** `resolveBackendGrant` sets no `credential`, so `bouncer.Dispatch.Credential` is nil for these calls. `interactiveOnly` only refuses `*BackendAPIToken` credentials and `g15_` bearers. Tools are limited to the plugin's own token-guarded routes, so this is not reachable today. But an OAuth agent is treated as "interactive" wherever a plugin route relies on that wrapper.
**Fix:** Attach a marker credential (for example an `*MCPGrantCredential{ClientID, TokenID}`) for administrator grants, and have `interactiveOnly` refuse it too.
---
_Reviewed: 2026-11-21T12:00:00Z_
_Reviewer: Claude (msd-code-reviewer)_
_Depth: standard_

View File

@@ -0,0 +1,44 @@
---
status: testing
phase: 32.2-mcp-oauth-with-administrator-subjects
source: [32.2-VERIFICATION.md]
started: 2026-11-21T01:52:38.959Z
updated: 2026-11-21T12:27:35.000Z
---
## Current Test
number: 1
name: SC-5 release go-ahead. 32.2-05-release-decision.txt records hold (framework-base v0.6.6, plugin-base v0.1.7). Decide whether to run plan 05 task 5's tag-and-publish branch: framework next free v0.6 patch (v0.6.7 if still free, must contain b1b96d85), sm-oauthserver-plugin v0.1.8 requiring that tag, push the plugin, then the grzyby pointer bump as its own commit (gitlink, go.mod require, regenerated plugins.gen.go), then the two changelog posts the same day.
expected: |
Tags v0.6.x (must contain the review fixes up to 0ade662a, since plugin d581799 calls wristband.CheckConsentPath) and v0.1.8 on origin, plugin go.mod on the framework tag, app gitlink and go.mod on v0.1.8 with check-deploy.sh passing again, two changelog URLs recorded in 32.2-05-changelog-published.txt; task 5's automated verify passes on the tag-and-publish branch.
awaiting: user response
## Tests
### 1. SC-5 release go-ahead. 32.2-05-release-decision.txt records hold (framework-base v0.6.6, plugin-base v0.1.7). Decide whether to run plan 05 task 5's tag-and-publish branch: framework next free v0.6 patch (v0.6.7 if still free, must contain b1b96d85), sm-oauthserver-plugin v0.1.8 requiring that tag, push the plugin, then the grzyby pointer bump as its own commit (gitlink, go.mod require, regenerated plugins.gen.go), then the two changelog posts the same day.
expected: Tags v0.6.x (must contain the review fixes up to 0ade662a, since plugin d581799 calls wristband.CheckConsentPath) and v0.1.8 on origin, plugin go.mod on the framework tag, app gitlink and go.mod on v0.1.8 with check-deploy.sh passing again, two changelog URLs recorded in 32.2-05-changelog-published.txt; task 5's automated verify passes on the tag-and-publish branch.
result: [pending]
### 2. Live connector check (cross-site SameSite=Strict admin cookie, D-03 / RESEARCH A2). After the production deploy, add https://grzybyfunkcjonalne.pl/mcp as a connector in Claude while signed in to /gfadmin, start the OAuth sign-in, then call a Journal tool and revoke the connection on My account. Procedure: ../sm-grzybyfunkcjonalne-app/DEPLOY.md, section 'Live connector check (deferred)'; 32.2-VALIDATION.md, Manual-Only Verifications row 1.
expected: After the cross-site redirect from Claude, the /gfadmin/connect consent card shows the signed-in administrator, not the login screen. If it shows login, signing in must return to the same consent request.
result: [pending]
### 3. Live connector scope behaviour (32.2-VALIDATION.md, Manual-Only Verifications row 2). In the same live run, note which scope value Claude sends to /oauth/mcp/authorize and whether the consent card offers the expected scopes.
expected: The consent card lists the scopes the administrator can grant (journal, journal:read and so on) with Stay connected. If Claude asks only for offline_access, the backend-mode DefaultScopes (token catalog) are now applied (FW-WR-01 fixed in fa7a8482), so a 'no grantable scope' card with only Deny is a regression.
result: [pending]
### 4. Production resource override (review PA-WR-09). During the deploy, check that SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE is set in go/.env and that GET /.well-known/oauth-protected-resource/mcp .resource equals the authorization server's resource (https://grzybyfunkcjonalne.pl/mcp).
expected: Both resources are the public https URL; the committed loopback default (http://127.0.0.1:8096/mcp) is not served. `scripts/check-deploy.sh --live` passes on the server; a missing override now fails boot in backend mode (PA-WR-09).
result: [pending]
## Summary
total: 4
passed: 0
issues: 0
pending: 4
skipped: 0
blocked: 0
## Gaps

View File

@@ -0,0 +1,370 @@
---
phase: "32.2"
slug: "mcp-oauth-with-administrator-subjects"
status: approved
reviewed_at: "2026-11-20"
shadcn_initialized: false
preset: none
created: "2026-11-20"
---
# Phase 32.2 — UI Design Contract
> Visual and interaction contract for frontend phases. Generated by msd-ui-researcher, verified by msd-ui-checker.
This phase adds three surfaces to the existing admin SPA (`admin/`, embedded by boardwalk). There is no new design system work.
1. **Consent screen** `/<admin prefix>/connect?request=…` (`ConnectView.vue`, new). A standalone full-screen card built like `LoginView.vue`, with no sidebar or top bar (D-03, D-05). It shows the client name, the redirect host, "Signed in as" with "Use another account" (D-06), scope checkboxes from the cabana token-scope catalog with the scopes the administrator lacks hidden (D-09, D-11), a "Stay connected" checkbox ticked by default (D-10), and Allow / Deny. It also has loading, expired, load-error, submit-error, no-grantable-scope and "returning" states.
2. **My account: MCP connections** (D-12). A section that `sm-oauthserver-plugin` contributes through `pact.HasAccountContributions`. It is rendered by the framework's `AccountContributions.vue` through a new, additive per-item extension: one row per connected agent, each with a Revoke button.
3. **MCP connections list** on the oauthserver admin screens (D-12). It is driven by WinterCMS-style YAML (`config_list.yaml`, `columns.yaml`) and rendered by the existing `ListView.vue`. Its contract is columns, permission, navigation and copy, with no new Vue code.
There is one small addition to `LoginView.vue`: a context line when the login redirect leads to `/connect`.
Out of scope: wristband's own authorize-time error pages (unknown client, redirect mismatch). wristband renders them before the handoff, they are unchanged, and they never reach the SPA. The Nuxt `/connect` of user mode is also out of scope (unchanged, D-02). D-13 revocation has no UI.
Sources:
- 32.2-CONTEXT.md D-03, D-05, D-06, D-09, D-10, D-11, D-12 (locked) and the Claude's Discretion items.
- 32.2-RESEARCH.md Patterns 4-6 (consent JSON contract, SPA route, account items) and Pitfall 7.
- The codebase scan: `admin/src/views/LoginView.vue`, `admin/src/components/account/{ApiTokenCreateDialog,ApiTokensPanel,AccountContributions}.vue`, `admin/src/components/ui/Button.vue`, `admin/src/app/{router,pageTitle,icons,i18n}.ts`, `admin/src/state/useAuth.ts`, `admin/src/styles/main.css`, `modules/phrasebook/backend/lang/{en,pl}/lang.yaml`, `modules/pact/capabilities.go`, `modules/cabana/{list_schema,navigation}.go`, `../sm-oauthserver-plugin/{admin*.go,controllers/clients/*.yaml,models/client/columns.yaml,lang/*/lang.yaml,models/consent.go}`, `../vue-oauth-layer/app/pages/connect.vue` (user-mode behaviour reference).
- House conventions from the approved 16.3 UI-SPEC (scope picker, token list rows, alert blocks, skeletons, copy) and the Direction C v2 design README (`.planning/phases/10-admin-vue-spa/design/README.md`).
---
## Design System
| Property | Value |
|----------|-------|
| Tool | none. There is no shadcn: this is a Vue 3 SPA with its own Direction C v2 system. The shadcn gate does not apply to a Vue codebase with an established system (same ruling as Phases 10.1, 12.1, 12.2, 16.3, 35) |
| Preset | not applicable |
| Component library | Reka UI 2.9.10 (headless primitives) plus the local components in `admin/src/components/` |
| Icon library | `@lucide/vue` 1.17.0, named imports only. Sizes: 20px in the wordmark and the 48px client circle (24px there), 18px in the login-style alert block, 16px in buttons and alert blocks, 14px in note lines. Navigation icons are registry names from `admin/src/app/icons.ts` |
| Font | DM Sans 400/600/700 (self-hosted `@fontsource/dm-sans`). DM Mono 400 (`font-mono`) for the redirect host and scope names. `tabular-nums` on every date |
**This contract adds no new tokens, colours, fonts, radii, shadows or icons to the registry.** Every value below either reuses an existing token or copies a class string from `LoginView.vue`, `ApiTokenCreateDialog.vue`, `ApiTokensPanel.vue` or `AccountContributions.vue`.
---
## Component Inventory
Enumerated by `node --input-type=module -e "import * as r from 'reka-ui'; console.log(Object.keys(r).length)"` (run in `admin/`) — 478 exports — reka-ui@2.9.10 — 2026-11-20.
Local components enumerated by `find admin/src/components -name '*.vue' | wc -l` — 69 components — summercms-admin@unversioned (private workspace package with no `version` in `admin/package.json`; pinned by repo commit 28a07f6b) — 2026-11-20.
Icon presence was verified by `node --input-type=module -e "import * as l from '@lucide/vue'; for (const n of [...]) console.log(n, n in l)"` (run in `admin/`) against @lucide/vue@1.17.0 on 2026-11-20. `Sun`, `Bot`, `CircleAlert`, `Info`, `LoaderCircle`, `Clock`, `Ban` and `Globe` are all exported. The navigation registry (`admin/src/app/icons.ts`) contains `network`, which is used for the new side-menu entry. `plug`/`bot` are **not** in the registry, so do not use them as navigation icon names.
This table is a **non-exhaustive** list of known-good components for this phase, not a closed allowlist. Checking for another Reka export or local component is the expected path.
| Component | Import path | Notes |
|-----------|-------------|-------|
| `LoginView.vue` shell markup | `admin/src/views/LoginView.vue` | The `<main>` gradient background, wordmark, card classes, alert block and primary button classes are copied verbatim into `ConnectView.vue` (D-05) |
| Scope picker markup | `admin/src/components/account/ApiTokenCreateDialog.vue` | Row markup, `toggleScope` / `scopeDisabled` / `starChecked` logic (`*` disables the rest) and the skeleton rows are copied, with the light-literal colours below. Extract a shared helper (for example `admin/src/app/scopePicker.ts`) if the planner prefers; the behaviour must stay identical |
| Token row markup | `admin/src/components/account/ApiTokensPanel.vue` | The list container and row classes, reused for My account item rows |
| `AccountContributions.vue` | `admin/src/components/account/AccountContributions.vue` | Extended to render `items` (C4). Existing sections without items render exactly as today |
| `Button` | `admin/src/components/ui/Button.vue` | My account item actions (`size="sm"`, `danger` / `outline`). **Not** used on the consent card, because its tokens flip in dark mode while the card stays light (see Color) |
| `ConfirmDialog` via `useConfirm` | `admin/src/components/ui/ConfirmDialog.vue`, `confirm.ts` | Item revoke confirmation. Reuse the `confirm` that `AccountView` passes in; do not mount a second one |
| `showToast` | `admin/src/state/useToasts.ts` | Item revoke success and failure toasts. The consent screen uses no toasts: every message is inline in the card |
| `logout`, `currentUser`, `expireSession` | `admin/src/state/useAuth.ts` | "Use another account" (call `logout()` **without** the router argument, then route to login with the redirect), the signed-in fallback, and the 401 handling |
| `safeRedirect` | `admin/src/app/router.ts` | Unchanged. Used only for the login round trip. **Never** pass the consent's `redirect_uri` through it |
| `t` | `admin/src/app/i18n.ts` | All copy. There are no literal UI strings in components |
| `api` (openapi-fetch) | `admin/src/api/client.ts` | `GET`/`POST /mcp/consent/{request}` and the account item action route, once `scripts/check-admin-openapi.sh` regenerates `schema.d.ts` |
| `ListView.vue` + cabana list YAML | `admin/src/views/ListView.vue`, `modules/cabana/list_schema.go` | The admin-wide MCP connections list. Column types are limited to `text`, `datetime`, `switch`, `date`, `time` and `money` (`listColumnTypes`) |
New files this phase creates: `admin/src/views/ConnectView.vue`, and `admin/tests/views/ConnectView.test.ts` (in the last plan). The phase also changes `admin/src/app/router.ts`, `admin/src/app/pageTitle.ts`, `admin/src/views/LoginView.vue` and `admin/src/components/account/AccountContributions.vue`. Plugin side: `controllers/mcpconnections/config_list.yaml`, `models/consent/columns.yaml` (or a dedicated view model's columns), and lang keys.
---
## Spacing Scale
Declared values for new layout in this phase (multiples of 4):
| Token | Value | Tailwind | Usage |
|-------|-------|----------|-------|
| xs | 4px | `gap-1` | Label to mono scope name in a scope row; dt to dd inside a fact row |
| sm | 8px | `gap-2` | Info-note icon gap; item meta line gap; the "returning" spinner to text |
| md | 16px | `gap-4`, `px-4` | Fact box and scope-row horizontal padding; item row column gap; My account items stack gap |
| lg | 24px | `gap-6`, `px-6` | Wordmark-to-card column gap (copied from LoginView); empty-state horizontal padding |
| xl | 32px | `p-8`, `py-8` | Consent card padding (copied from LoginView); empty-state vertical padding |
| 2xl | 48px | `size-12` | The client logo / icon circle (a size, not a gap) |
| 3xl | 64px | — | Not used |
Exceptions (inherited from Direction C and copied verbatim from existing components; the same values 16.3 locked as system-level exceptions):
- Consent card stack gap 18px (`gap-[18px]`), copied from the LoginView card.
- Scope-row vertical padding 12px (`py-3`) and minimum row height 56px (`min-h-[56px]`); checkbox-to-text gap 12px (`gap-3`); 2px checkbox nudge (`mt-0.5`). All copied from the ApiTokenCreateDialog scope picker.
- Fact box vertical padding 12px (`py-3`), the same as a scope row, so the two boxes align.
- Footer button gap 10px (`gap-2.5`), copied from ApiTokenCreateDialog and ConfirmDialog.
- Item row vertical padding 14px (`py-3.5`), copied from ApiTokensPanel rows.
- Login-style alert block padding 12×14 (`px-3.5 py-3`), copied from LoginView.
- My account section card padding 28px (`p-7`), unchanged existing markup.
Fixed component dimensions (sizes, not spacing): 44px consent buttons (`h-input`, as the login button); 38px item action buttons (`Button size="sm"`); 20px checkboxes (`size-5`); 48px client circle; 34px wordmark circle (copied); consent column max width 480px (`max-w-[480px]`, wider than the 400px login column because scope rows carry descriptions); 12px skeleton bars with `rounded-[6px]`.
---
## Typography
Exactly four sizes. All inherit DM Sans and the 14px/1.5 base from `html` in `main.css`.
| Role | Size | Weight | Line Height | Used by |
|------|------|--------|-------------|---------|
| Body | 14px | 400 | 1.5 | Consent subline, signed-in value in the fact box, alert-block text, the expired and load-error bodies |
| Label | 14px | 600 | 1.5 | Scope label, "Stay connected" label, fact-row terms (`dt`), the "Use another account" text button, Allow / Deny button text, item row title, the Read-only pill (13px/600, as in 16.3) |
| Meta | 13px | 400 | 1.5 | Scope mono name and description, offline description, the `*` info note, redirect host (DM Mono), "previously allowed" note, login hint line, item meta line (`tabular-nums`), the items empty line, the "returning" fallback link |
| Heading | 22px | 700 | 1.2 (`tracking-[-0.02em]`) | Consent card `h1` (all states). The LoginView title class `text-[22px] font-bold tracking-[-0.02em]`, copied verbatim, so sign-in and consent read as one flow |
Inherited, unchanged markup (not new text): the wordmark "Summer**CMS**" at 18px/700 (copied from LoginView) and the My account section heading at 18px/700 (existing `AccountContributions.vue`).
Weights: new content uses 400 and 600 only. **700 is the inherited heading-only weight.** It appears on the consent `h1` and on the two inherited 18px elements, all copied verbatim. This is the system-level exception the user locked on 2026-10-11 (16.3 UI-SPEC, Typography) and that later phases re-applied. It is not a defect. DM Mono appears only on the redirect host and the scope names (`journal:read`, `*`).
---
## Color
**Consent card: light-literal palette.** `LoginView` draws a white card on the fixed navy gradient with literal hex values, so the card looks the same in light and dark mode (the theme preference is applied only after `me()`). `ConnectView` sits in the same flow, so it copies that treatment. Its card uses the **light** values of the existing tokens as literals (from `:root` in `main.css`), with no `dark:` variants, and does not use `Button.vue` or token utilities (`text-muted`, `bg-subtle` and so on) inside the card. Every literal below is an existing `:root` token value; no new colour is introduced.
| Role | Value | Usage |
|------|-------|-------|
| Dominant (60%) | Gradient `radial-gradient(ellipse at 50% 35%, #2b3a5c 0%, #1d2740 60%)` (copied); card `#ffffff` (`bg-white`) | Page behind the card; the card itself; scope rows; the Deny button fill |
| Secondary (30%) | `#f3f5f8` (subtle) fact box and Read-only pill; `#e6e9ef` (border) row and box dividers; `#d2d8e2` (border-strong) Deny border and checkbox outline; `#566175` (muted) meta and description text; `#eceff4` (skel) skeleton bars; text `#141b2d` | Fact box, dividers, meta text, skeletons, body text |
| Accent (10%) | `#22304d` (primary, light value); the yellow `accent` `#fcd34d` / `accent-soft` (wordmark only, copied); focus ring `rgba(252,196,40,.55)` (base style) | See the reserved list |
| Destructive | `#c62828` (danger) / `#fdf0f0` (danger-soft) on the card; the `danger` / `danger-soft` tokens in My account | Consent alert blocks (load failure, submit failure, no grantable scopes); item Revoke buttons and their confirm button |
**My account items and the admin-wide list use tokens** (`surface`, `border`, `muted`, `danger` …) and follow dark mode, like the rest of the shell. No hex literals appear there.
Accent reserved for (exhaustive for this phase):
1. `#22304d` fill: the **Allow** button only. It is the single primary action on the consent card.
2. `#22304d` checkbox tint (`accent-[#22304d]`): checked scope checkboxes and the "Stay connected" checkbox.
3. Yellow `accent` / `accent-soft`: the wordmark sun circle and "CMS" (copied from LoginView), and nothing else.
4. Focus ring (3px): `:focus-visible` on every focusable element (base style), never removed.
Accent is never used for: the Deny button (white fill, `#d2d8e2` border, `#141b2d` text, hover `#f1f3f7`), the "Use another account" text button (`#141b2d` text, underline on hover), the redirect host, scope names, links, or the My account item buttons. **Deny is not styled as destructive.** Refusing is a safe, neutral choice and must not look alarming. Danger colour is used only for errors and for Revoke.
---
## Copywriting Contract
Polish is the design language; English values follow. Placeholders use `:name` syntax (phrasebook). Copy lives in three places:
- **Framework (consent screen, login hint, generic item strings):** `modules/phrasebook/backend/lang/{en,pl}/lang.yaml`, in a new `mcp_connect:` group (`backend::lang.mcp_connect.*`) and additions to `myaccount:`. Framework copy never names an application.
- **Plugin (My account section, admin-wide list, permission):** `../sm-oauthserver-plugin/lang/{en,pl}/lang.yaml`, in new `account:` and `mcp_connections:` groups and `permissions.manage_mcp_connections`.
- **Server-delivered:** the client name, redirect host, admin name and email, and the scope labels and descriptions (from the cabana catalog, translated server-side; `*` and `admin:read` use the existing `api_tokens.scope_all*` and `scope_admin_read*` keys). These render as text, never as HTML.
### Primary CTAs and key states (consent screen)
| Element | Copy (EN / PL) |
|---------|----------------|
| Page title (`document.title` indicator) | `mcp_connect.page_title` "Connect an agent" / "Połącz agenta" |
| Heading (ready) | `mcp_connect.heading` "Allow :client to use the admin as you?" / "Pozwolić aplikacji :client korzystać z panelu w Twoim imieniu?" (the client name always follows a declined noun in Polish, so it stays in the nominative) |
| Subline | `mcp_connect.subline` "The agent gets your permissions, limited to the scopes you tick. It never gets more access than your own account." / "Agent otrzyma Twoje uprawnienia w granicach zaznaczonych zakresów. Nigdy nie dostanie szerszego dostępu niż Twoje konto." |
| Fact row: signed in (term) | `mcp_connect.signed_in_as` "Signed in as" / "Zalogowano jako" |
| Fact row: signed in (value) | `mcp_connect.admin_with_email` ":name (:email)" / ":name (:email)". With no email, the name alone. With no name, the login |
| Switch account | `mcp_connect.switch_account` "Use another account" / "Użyj innego konta" |
| Fact row: return address (term) | `mcp_connect.returns_to` "Returns to" / "Wrócisz do" (value: the redirect host in DM Mono) |
| Scopes group label | reuse `api_tokens.scopes` "Scopes" / "Zakresy" |
| `*` ticked note | reuse `api_tokens.scope_all_includes` "Full access already includes every other scope." / "Pełny dostęp obejmuje wszystkie pozostałe zakresy." |
| Read-only pill | reuse `api_tokens.read_only` "Read-only" / "Tylko odczyt" |
| Offline checkbox label | `mcp_connect.offline` "Stay connected" / "Pozostań połączony" |
| Offline description | `mcp_connect.offline_description` "The agent can renew its access without asking you again. Untick it and the agent has to be allowed again when its access expires." / "Agent może odnawiać dostęp bez ponownego pytania. Po odznaczeniu trzeba będzie ponownie wyrazić zgodę, gdy jego dostęp wygaśnie." |
| Previously allowed note (`consent_required: false`) | `mcp_connect.previously_allowed` "You have allowed :client before." / "Aplikacja :client ma już Twoją zgodę." |
| Primary CTA | `mcp_connect.allow` "Allow" / "Zezwól"; while busy `mcp_connect.allowing` "Allowing…" / "Zezwalanie…" |
| Secondary CTA | `mcp_connect.deny` "Deny" / "Odmów"; while busy the same label with a spinner |
| Returning state | `mcp_connect.returning` "Returning you to :host…" / "Wracasz do :host…" |
| Returning fallback link (http/https only) | `mcp_connect.continue` "Continue to :host" / "Przejdź do :host" |
| Login hint (LoginView, redirect to `/connect`) | `mcp_connect.login_hint` "Sign in to finish connecting your MCP agent." / "Zaloguj się, aby dokończyć łączenie agenta MCP." |
### Empty, error and refusal states (consent screen)
| Element | Copy (EN / PL) |
|---------|----------------|
| Empty: no grantable scope (every requested scope is hidden, D-11) | Alert block: `mcp_connect.none_grantable` "Your account has none of the permissions this agent asks for. Deny the request, or ask a superuser for the permissions and connect again." / "Twoje konto nie ma żadnego z uprawnień, o które prosi ten agent. Odmów albo poproś superużytkownika o uprawnienia i połącz się ponownie." Only Deny is offered |
| Expired / unknown / used request (404, or no `request` parameter) | Heading `mcp_connect.expired_heading` "This connection request has expired" / "Ta prośba o połączenie wygasła"; body `mcp_connect.expired_body` "Connection requests are valid for a few minutes and work only once. Go back to your agent and connect again." / "Prośba o połączenie jest ważna kilka minut i działa tylko raz. Wróć do agenta i połącz się ponownie."; link `mcp_connect.open_admin` "Go to the admin panel" / "Przejdź do panelu" |
| Error: load failed (5xx or network) | Alert block: `mcp_connect.load_failed` "The connection request could not be loaded. Check your connection and try again." / "Nie udało się wczytać prośby o połączenie. Sprawdź połączenie i spróbuj ponownie."; button `mcp_connect.retry` "Try again" / "Spróbuj ponownie" |
| Error: nothing ticked (client-side, Allow disabled) | Allow stays disabled; no message |
| Error: 422 `no_grantable_scopes` on Allow | Alert block under the scopes: reuse `api_tokens.scopes_required` "Choose at least one scope." / "Wybierz co najmniej jeden zakres." The ticks are kept |
| Error: submit failed (5xx, network, 400) | Alert block above the buttons: `mcp_connect.decide_failed` "Your answer could not be sent. Try again." / "Nie udało się wysłać odpowiedzi. Spróbuj ponownie." The ticks are kept and both buttons are enabled again |
| Error: 404 on submit | Switches to the expired state above |
| Error: 401 at any point | No copy on the card: `expireSession` sends the browser to login with `redirect` = this `/connect?request=…` path, and the existing `auth.session_expired` notice applies |
### Destructive actions
| Action | Confirmation approach | Copy (EN / PL) |
|--------|----------------------|----------------|
| Deny (consent) | **No confirmation.** Deny is reversible: the agent can simply ask again | `mcp_connect.deny` "Deny" / "Odmów" |
| Use another account (consent) | **No confirmation.** It only signs out of this browser session, and the request survives the round trip until it expires | `mcp_connect.switch_account` |
| Revoke one connection (My account item) | ConfirmDialog, `danger`, with the request run as the confirm action (`confirm.ask(request, run)`), so the confirm button shows the busy spinner | Button: `golem15.oauthserver::lang.account.revoke` "Revoke" / "Unieważnij"; aria-label `backend::lang.myaccount.item_action_named` ":action: :title" / ":action: :title". Confirm: `account.revoke_confirm` "Revoke the connection “:title”? The agent loses access at once and has to be connected again." / "Unieważnić połączenie „:title”? Agent natychmiast straci dostęp i trzeba będzie połączyć go ponownie." (the framework fills `:title` with the item title; C3). Confirm button: the action label. Success toast: `account.revoked` "Connection revoked" / "Unieważniono połączenie" |
| Revoke selected connections (admin-wide list, bulk) | Existing bulk confirm dialog with the action's `Confirm` text | Menu item: `mcp_connections.revoke` "Revoke connections" / "Unieważnij połączenia". Confirm: `mcp_connections.revoke_confirm` "Revoke the selected connections? Their agents lose access at once and have to be connected again." / "Unieważnić zaznaczone połączenia? Ich agenci natychmiast stracą dostęp i trzeba będzie połączyć ich ponownie." Result: empty `Message`, so the framework's `list.bulk_done` (CLDR plural with `:count`) shows |
### My account section (plugin copy, `golem15.oauthserver::lang.account.*`)
| Element | Copy (EN / PL) |
|---------|----------------|
| Section label | `account.section` "MCP connections" / "Połączenia MCP" |
| Section description | `account.description` "Agents you allowed to use the admin as you. Revoking a connection ends its access and its open sessions at once." / "Agenci, którym udzielono zgody na korzystanie z panelu w Twoim imieniu. Unieważnienie połączenia natychmiast odbiera dostęp i kończy otwarte sesje." |
| Status line (connector address) | `account.status` "Connector address: :url" / "Adres konektora: :url" (`:url` = the configured `mcp.resource`) |
| Empty state (no items) | `account.empty` "No agents are connected. Add the connector address in your agent and sign in to connect one." / "Brak połączonych agentów. Dodaj adres konektora w agencie i zaloguj się, aby go połączyć." |
| Item title | The client name (server data) |
| Item subtitle | The granted scope labels, joined with ", " (`*` → `api_tokens.scope_all`; `offline_access` is left out) |
| Item meta | `account.connected` "Connected :date" / "Połączono :date"; `account.last_used` "Last used :date" / "Ostatnio użyto :date" or `account.never_used` "Never used" / "Nieużywane". `:date` is `YYYY-MM-DD` |
| Item gone (404 on revoke) | framework `myaccount.item_gone` "This entry no longer exists. The section has been refreshed." / "Ten wpis już nie istnieje. Sekcja została odświeżona." (danger toast, then reload) |
| Revoke failed (other) | existing `extension.action_failed` (danger toast); 403 shows the server message or `list.action_forbidden`; 409 shows `myaccount.action_stale` and reloads (as for section actions today) |
| Framework fallback when `ItemsEmpty` is unset | `myaccount.items_empty` "Nothing here yet." / "Nic tu jeszcze nie ma." |
### Admin-wide list (plugin copy, `golem15.oauthserver::lang.mcp_connections.*`)
| Element | Copy (EN / PL) |
|---------|----------------|
| Side-menu label | `mcp_connections.menu_label` "MCP connections" / "Połączenia MCP" |
| List title | `mcp_connections.list_title` "Administrators' MCP connections" / "Połączenia MCP administratorów" |
| Empty list | `mcp_connections.list_empty` "No MCP connections in this view. Clear the search, or wait for an administrator to connect an agent." / "Brak połączeń MCP w tym widoku. Wyczyść wyszukiwanie albo poczekaj, aż administrator połączy agenta." |
| Columns | `mcp_connections.administrator` "Administrator" / "Administrator"; `mcp_connections.email` "Email" / "E-mail"; `mcp_connections.client` "Agent" / "Agent"; `mcp_connections.scopes` "Scopes" / "Zakresy"; `mcp_connections.created_at` "Connected" / "Połączono"; `mcp_connections.last_used_at` "Last used" / "Ostatnio użyto" |
| Search prompt | existing `backend::lang.list.search_prompt` |
| Permission label | `permissions.manage_mcp_connections` "See and revoke administrators' MCP connections" / "Podgląd i unieważnianie połączeń MCP administratorów" (tab `plugin.tab`, no default role) |
---
## Component Contracts
### C1. Consent screen — `admin/src/views/ConnectView.vue` (D-03, D-05, D-06, D-09, D-10, D-11)
**Route.** `{ path: '/connect', name: 'connect', component: ConnectView }` in `router.ts`, with **no** `meta.shell` (standalone) and **no** `meta.public`. The existing `beforeEach` therefore sends an anonymous visitor to `{ name: 'login', query: { redirect: '/connect?request=…' } }`, and LoginView returns through `safeRedirect`. Place the route before the `/:vendor/:plugin/:controller` entries (a single segment never collides, but keep it with the other fixed paths). `pageTitle.ts` gains a `connect` branch returning `mcp_connect.page_title`.
**Layout (copied from LoginView).**
- `<main class="flex min-h-screen items-center justify-center px-4" style="background: radial-gradient(ellipse at 50% 35%, #2b3a5c 0%, #1d2740 60%)">`.
- Column `flex w-full max-w-[480px] flex-col gap-6`: the wordmark block (verbatim), then the card.
- Card: `flex flex-col gap-[18px] rounded-card bg-white p-8 text-[#141b2d] shadow-login`. In the ready state it is a `<form novalidate @submit.prevent="allow">`.
**Ready state, top to bottom.**
1. Client mark. When `client.logo_url` is a same-origin path or an `https:` URL, show a `size-12 rounded-inner object-contain` image with `alt=""` (the name is in the heading). Otherwise show a `size-12 rounded-full bg-[#f3f5f8]` circle holding `Bot` (24px, `text-[#566175]`).
2. `h1` (Heading role, `tabindex="-1"`) `mcp_connect.heading`, followed by the subline (Body, `text-[#566175]`). When `consent_required === false`, the "previously allowed" note (Meta, `Info` 14px) follows.
3. Fact box: a `<dl>` with `flex flex-col gap-3 rounded-inner bg-[#f3f5f8] px-4 py-3`, two rows, each a `flex flex-col gap-1`:
- `dt` `mcp_connect.signed_in_as` (Label). `dd` holds the admin value (Body, `[overflow-wrap:anywhere]`), then on its own line the "Use another account" text button (`type="button"`, Label, `text-[#141b2d] underline-offset-2 hover:underline`, no fill).
- `dt` `mcp_connect.returns_to` (Label). `dd` holds `client.redirect_host` in `font-mono text-[13px]` with `[overflow-wrap:anywhere]`. **Always shown** (MCP spec: show the redirect host; anti-phishing). When the host is empty, show the full redirect origin the API returns. The row is never omitted.
4. Scope group: `role="group"` labelled by the "Scopes" label. Row markup is copied from ApiTokenCreateDialog: `overflow-hidden rounded-inner border border-[#e6e9ef]`, and each row is a `label` with `flex min-h-[56px] items-start gap-3 border-t border-[#e6e9ef] px-4 py-3 first:border-t-0`, a checkbox (`mt-0.5 size-5 shrink-0 rounded-[6px] accent-[#22304d]`), the label (Label), the mono name (Meta, `font-mono text-[#566175]`), the Read-only pill when `read_only` (`h-6 rounded-pill bg-[#f3f5f8] px-2.5 text-[13px] font-semibold text-[#566175]`) and the description (Meta, `text-[#566175] [overflow-wrap:anywhere]`). Rows appear in catalog order (`*`, `admin:read`, then plugin scopes). Only the scopes the API returns are shown; the API has already removed the ones the admin cannot use (D-11), and the SPA never re-adds them.
- **Initial ticks:** every shown scope is ticked **except `*`**, which starts unticked, unless `*` is the only scope shown, in which case it starts ticked. This keeps "full access" an explicit choice even when a client requests everything (RESEARCH Pattern 3, `DefaultScopes`).
- **`*` rule (discretion item, decided):** plain checkboxes, no presets. Ticking `*` clears and disables the others (`opacity-60 cursor-not-allowed`) and shows the `scope_all_includes` note (Meta, `Info` 14px); unticking re-enables them, with their previous ticks cleared. This matches `g15_` token creation exactly (D-09 mental model). Submitted scopes are `['*']` when `*` is ticked, else the ticked names in catalog order.
5. Offline row, shown only when `offline_access` was requested: a separate bordered box with the same row markup as a scope row (not inside the scope group). Checkbox **ticked by default** (D-10), label `mcp_connect.offline` (Label) and description `mcp_connect.offline_description` (Meta). Posted as `offline_access: true|false`.
6. Inline alert slot (submit failures, `role="alert"`). LoginView alert block classes: `flex items-center gap-2.5 rounded-control bg-[#fdf0f0] px-3.5 py-3 text-[#c62828]` with `CircleAlert` 18px.
7. Buttons: `flex gap-2.5`, both `flex-1 h-input rounded-control font-semibold`, **Deny on the left, Allow on the right** (the order of ApiTokenCreateDialog's cancel and submit). Allow is `type="submit"` with `bg-[#22304d] text-white hover:opacity-90 disabled:opacity-60`, disabled while no scope is ticked or while busy. Deny is `type="button"` with `border border-[#d2d8e2] bg-white text-[#141b2d] hover:bg-[#f1f3f7] disabled:opacity-60`.
**Interaction.**
- Load on mount and when `route.query.request` changes: `GET {api}/mcp/consent/{request}`. A missing or empty `request` goes straight to the expired state without a request.
- **No auto-allow.** The card is shown even when `consent_required` is false (RESEARCH Open Question 1). Unlike the user-mode `/connect`, nothing is posted without a click.
- No initial focus on Allow or Deny, and no hotkey for Allow. Consent needs a deliberate click. After each state change past the first render, focus moves to the state's `h1` (or to the alert block for inline errors).
- Allow: `POST {api}/mcp/consent/{request}` with `{decision: 'allow', scopes, offline_access}`. While it runs, a `fieldset disabled` wraps the checkboxes, both buttons are disabled, and Allow shows `LoaderCircle` 16px `animate-spin` with `mcp_connect.allowing`.
- Deny: `POST` with `{decision: 'deny'}`, the same busy treatment on Deny (spinner, same label).
- On a `200 {redirect_uri}` for either decision, switch to the **returning** state and call `window.location.assign(redirect_uri)`. First refuse (and treat as a submit failure) a URI whose scheme is `javascript:`, `data:` or `vbscript:`. Never route the URI through `safeRedirect` or the router. Never use a native form POST: the admin CSP is `form-action 'self'`.
- "Use another account": `await logout()` (no router argument), then `router.replace({ name: 'login', query: { redirect: route.fullPath } })`. The button is disabled while a decision is in flight.
- Signed-in value: `admin.name` / `admin.email` / `admin.login` from the API. When the API omits `admin`, fall back to `currentUser` (first and last name, email, login).
**Other states.** All use the same card shell; only the card contents change.
- **Loading:** `aria-busy="true"`. A 48px `bg-[#eceff4]` circle, two skeleton bars (`h-3 w-56`, `h-3 w-40`, `rounded-[6px] bg-[#eceff4]`), then three skeleton scope rows copied from the token dialog. No buttons. The `h1` is visually hidden (`sr-only`) and reads `mcp_connect.page_title`.
- **Expired** (404 on load or submit, or no `request`): `Clock` 24px in the 48px `bg-[#f3f5f8]` circle, the `h1` `expired_heading`, the body `expired_body` (`text-[#566175]`), and a full-width outline button-styled `RouterLink` to `/` with `open_admin` (Deny classes).
- **Load error:** `h1` `mcp_connect.page_title`, the alert block with `load_failed`, and a full-width "Try again" button (Deny classes) that re-runs the load.
- **No grantable scope** (ready, but the API returned zero scopes): the client mark, `h1`, subline and fact box as in ready; the `none_grantable` alert block in place of the scope group; no offline row; only **Deny**, full width.
- **Returning:** the client mark, `h1` `mcp_connect.returning` with `:host`, and a `LoaderCircle` 16px inline. When the URI is `http:` or `https:`, a Meta link `mcp_connect.continue` with `href` = the URI (`text-[#141b2d] underline`) follows, for browsers that block the navigation. No buttons.
### C2. Login hint — `admin/src/views/LoginView.vue` (additive)
When `safeRedirect(route.query.redirect)` resolves to a path whose pathname is `/connect`, render one Meta line (`text-[13px] text-[#566175]`) directly under the login `h1` with `mcp_connect.login_hint`. Nothing else in LoginView changes. Any 2FA or Turnstile step, error and redirect behaviour stays as it is (D-03).
### C3. Account contribution items — `pact.AccountContribution` + `admin/src/components/account/AccountContributions.vue` (D-12, additive)
The UI needs the RESEARCH Pattern 6 shape plus two small additions, all additive:
- `AccountContribution.Items` (func), `ItemActions []AccountItemAction`, and **`ItemsEmpty string`** (phrase key or text; empty means the framework's `myaccount.items_empty`).
- `AccountItem { ID, Title, Subtitle string; Meta []string }`. The framework interpolates **`:title`** in an item action's `Confirm` with the item's `Title` (as text).
- The JSON of a section **without** `Items` carries no `items` (or `null`), and that section renders exactly as today: status line and buttons only. Sections with `Items` always send an array, possibly empty.
Rendering, inside the existing section card, after the status line and before the section buttons:
- **Items present:** `role="list"` container `flex flex-col overflow-hidden rounded-inner border border-border` (from ApiTokensPanel). Each `role="listitem"` row, with `data-account-item="<id>"`, uses `flex items-start justify-between gap-4 border-t border-border px-4 py-3.5 first:border-t-0 max-sm:flex-col`. Left column `flex min-w-0 flex-1 flex-col gap-1`: title (Label, `[overflow-wrap:anywhere]`), subtitle (Meta, `text-muted [overflow-wrap:anywhere]`, omitted when empty), and the meta line (Meta, `text-muted tabular-nums`, entries joined with " · ", omitted when empty). Right: one `Button size="sm"` per item action, with `variant="danger"` and the `Ban` icon when `Danger`, else `variant="outline"` and no icon. `data-account-item-action="<name>"`, aria-label `myaccount.item_action_named` with the item title, and `max-sm:self-start`.
- **Zero items:** `data-account-items-empty`, `rounded-inner border border-dashed border-border-strong px-6 py-8 text-center`, with one Meta line in `text-muted` holding `ItemsEmpty`.
- **Section error:** unchanged. The existing `section_error` line replaces both the list and the empty block.
- **Running an item action:** if the action has `Confirm` or `Danger`, `confirm.ask({ message, confirmLabel: action.label, danger }, run)`. Otherwise run directly. Run calls `POST /account/contributions/{name}/items/{item}/actions/{action}`. While it runs, every action button in every section is disabled (the existing `running` guard). On 2xx: toast with the answer message (or `form.action_done`), then reload. On 404: `item_gone` danger toast, then reload. On 409, 403 and other failures: as for section actions today.
- After a revoke reload, focus returns to the section heading (it gets `tabindex="-1"`), because the revoked row's button no longer exists.
### C4. oauthserver My account section (D-12) — `sm-oauthserver-plugin/account.go` (new)
- Contributed only when `mcp.subject: backend`. In user mode, `AccountContributions()` returns none, so other apps' My account pages are unchanged.
- `Name: "mcp_connections"`, `Label: account.section`, `Description: account.description`, `Status: account.status` with the resource URL, `ItemsEmpty: account.empty`.
- Items are the signed-in admin's backend consents (`user_id IS NULL AND backend_user_id = admin`), ordered by `last_used_at DESC NULLS LAST`, then `created_at DESC`. Item fields: `ID` = client_id, `Title` = client name, `Subtitle` = scope labels, `Meta` = [connected, last used or never used].
- One item action: `Name: "revoke"`, `Label: account.revoke`, `Confirm: account.revoke_confirm`, `Danger: true`, result `Message: account.revoked`.
- No cap or pagination: an administrator has a handful of agents. Rows stack.
### C5. Admin-wide MCP connections list (D-12) — YAML-driven, `sm-oauthserver-plugin`
- **Controller** `golem15.oauthserver.mcpconnections` over the consent rows of backend subjects (`ListExtendQuery`: `user_id IS NULL AND backend_user_id IS NOT NULL`, joined to `backend_users` and `golem15_oauthserver_clients` for the text columns). `RequiredPermissions: [golem15.oauthserver.manage_mcp_connections]`; superusers pass as always.
- **Navigation:** a side-menu entry under the existing `oauthserver` main item, after "OAuth clients", with `Code: mcp_connections`, `Icon: network`, `Label: mcp_connections.menu_label`, the new permission, and `Visible` only when `mcp.subject: backend`. The main item keeps its label and permissions, and cabana's `openableTarget` already sends an admin who only holds the new permission to this entry.
- **`config_list.yaml`:** `title: mcp_connections.list_title`; `noRecordsMessage` / `messages.empty: mcp_connections.list_empty`; `recordsPerPage: 20`; `showCheckboxes: true`; `showSetup: true`; `showSorting: true`; `defaultSort: { column: created_at, direction: desc }`; `bulkActions: [revoke]`; `toolbar.search.prompt: backend::lang.list.search_prompt`; **no `toolbar.buttons`** (there is nothing to create); **no `recordUrl`** (a connection has nothing to edit, and every fact is in the columns).
- **`columns.yaml`** (in order): `id` (invisible); `administrator` (`text`, searchable: the full name, falling back to the login); `email` (`text`, searchable); `client` (`text`, searchable: the client name); `scopes` (`text`: the granted scope names joined with ", ", e.g. `journal, journal:read`, without `offline_access`); `created_at` (`datetime`); `last_used_at` (`datetime`, null shows the existing `list.empty_value` "—"). Cabana list relations may not join on the string `client_id` (RESEARCH A4). Use `select` expressions over the `ListExtendQuery` join, or a read-only view model, whichever the planner proves. The visible contract above is fixed either way.
- **Bulk action** `revoke` (copy in the Copywriting Contract, Destructive actions): it revokes each selected (admin, client) pair exactly like the My account item action, and fires the per-client `MCPSubjectChanged` after commit. Revoked rows disappear from the list (the consent row is deleted), so no row state is needed.
---
## UI Considerations
Applicable state considerations resolved: 38 probe checks in 38 rows (32 covered, 5 backstop, 1 dismissed, 0 unresolved). The elements are the consent card (form, interactive controls, static content), its scope list (list-collection), the login hint (static content), the My account items (list-collection, interactive control) and the admin-wide list (list-collection, existing ListView). The empty and error copy lives in the Copywriting Contract.
| Category | Element(s) | Status | Resolution / Reason |
|----------|------------|--------|---------------------|
| loading | Consent card | ✅ covered | Skeleton card (C1 Loading) with `aria-busy="true"` and no buttons, so nothing can be submitted before the request is known |
| loading | Consent decision in flight | ✅ covered | Fieldset disabled, both buttons disabled, a spinner on the clicked button, then the Returning state until the browser leaves |
| loading | My account items | ✅ covered | Items arrive with the existing `GET /account/contributions`; nothing renders until it answers (existing behaviour), so no item-level loading UI |
| loading | Admin-wide list | ✅ covered | Existing ListView skeleton rows |
| empty | Consent scopes (none grantable) | ✅ covered | C1 No grantable scope: the `none_grantable` alert replaces the scope group, and only Deny is offered |
| empty | Consent request missing (`?request` absent) | ✅ covered | The Expired state, without a network call |
| empty | Consent form (nothing ticked) | ✅ covered | Allow is disabled while the submitted scope set would be empty; Deny stays available |
| empty | My account items | ✅ covered | The dashed empty block with `account.empty`; the status line with the connector address stays above it, so the next step is visible |
| empty | Admin-wide list | ✅ covered | `mcp_connections.list_empty`; an empty search uses the existing empty-search message |
| error | Consent load (5xx/network) | ✅ covered | Load error state with Try again |
| error | Consent load/submit 404 | ✅ covered | Expired state with a link to the admin |
| error | Consent 401 (session ended mid-flow) | ✅ covered | `expireSession` → login with the redirect back to the same `/connect?request=…` |
| error | Consent submit 422 / 5xx | ✅ covered | Inline alert, ticks kept, buttons enabled again |
| error | Consent `redirect_uri` with a forbidden scheme | ✅ covered | Treated as a submit failure (`decide_failed`); no navigation |
| error | My account item revoke 404 / 409 / 403 / other | ✅ covered | Toasts as in C3, with a reload on 404 and 409 |
| error | My account section items func failing | ✅ covered | The existing `section_error` line replaces the list |
| populated | Consent scopes | ✅ covered | Catalog order. Every shown scope ticked except `*` (unless `*` is alone). Read-only pill on read-only scopes. Offline row ticked when requested |
| populated | My account items | ✅ covered | One row per client: name, scope labels, "Connected · Last used" meta, Revoke |
| partial | Consent with `offline_access` not requested | ✅ covered | The offline row is not rendered; `offline_access: false` is posted |
| partial | Consent with no logo, no email or no name | ✅ covered | Bot circle; name without parentheses; login when the name is empty |
| zero-one-many | My account items | ✅ covered | Zero: the empty block. One or many: the same row list with dividers (`first:border-t-0`). No pagination (C4) |
| overflow | Consent scope list on a small screen | ✅ covered | The card grows with the page; the page scrolls (the `min-h-screen` main is not fixed height). Rows wrap; nothing scrolls inside the card |
| long-text | Client name, admin email, redirect host, scope descriptions, item titles | ✅ covered | `[overflow-wrap:anywhere]` on each. The heading wraps; nothing truncates on the consent card, because the redirect host must be read in full |
| populated | Consent `*` rule | 🧪 backstop | Vitest (`ConnectView.test.ts`): ticking `*` disables and clears the others and shows the note, the POST body is `['*']`, and unticking re-enables them |
| populated | No auto-allow and the decision navigation | 🧪 backstop | Vitest: with `consent_required: false` nothing is POSTed on mount; Allow and Deny POST the documented bodies and call `window.location.assign` with the server URI, never the router |
| populated | Switch account round trip | 🧪 backstop | Vitest: "Use another account" calls `POST /auth/logout`, then replaces to `login` with `redirect` = the current `/connect?request=…`; the router test covers anonymous `/connect` → login → back |
| populated | Account contribution items back-compat | 🧪 backstop | Vitest: a section without `items` renders exactly as before (status + buttons); a section with `items: []` renders the empty block; an item action runs the confirm with `:title` filled |
| populated | Cross-site cookie on the real connector flow (RESEARCH Pitfall 7, A2) | 🧪 backstop | Not provable on a localhost (same-site) stack: a live Claude-connector check at the deferred deploy step must show the signed-in card, not the login screen, after the cross-site redirect. Route to human verification |
| error | Admin-wide list (load, bulk revoke failure) | ✅ covered | Existing ListView error handling and bulk-action failure toast; nothing new |
| long-text | Admin-wide list cells (administrator, email, client, scopes) | ✅ covered | Existing ListView cell wrapping |
| overflow | Admin-wide list on a small screen | ✅ covered | Existing ListView horizontal scroll container |
| zero-one-many | Admin-wide list | ✅ covered | `recordsPerPage: 20` with the existing pager; zero rows show `mcp_connections.list_empty` |
| partial | Admin-wide list row (administrator without a name) | ✅ covered | The `administrator` column falls back to the login |
| error | "Use another account" sign-out failure | ✅ covered | The inline alert (`role="alert"`, `decide_failed` copy) shows and the card stays; the button is re-enabled |
| partial | My account item (client without a name) | ✅ covered | `Title` falls back to the client_id |
| overflow / long-text | My account items | ✅ covered | Titles, subtitles and meta wrap with `[overflow-wrap:anywhere]`; rows stack under `max-sm:flex-col` |
| loading / error | Consent scope list | ✅ covered | Inherited from the consent card's Loading, Load error and Expired states; the list never renders on its own |
| overflow / long-text | Login hint | ⛔ dismissed | One static, short translated line under the heading; it wraps with the heading's container and carries no user data |
Open, prose-owned considerations (domain probes):
- **Accessibility:** the scope group is `role="group"` with a label. Every checkbox is inside its `label`. Alerts use `role="alert"`. Focus moves to the state heading on state changes. The 3px focus ring is never removed. Danger is never conveyed by colour alone (a text label is always present).
- **i18n:** Polish and English keys ship together. The Polish heading avoids inflecting the client name. Dates are `YYYY-MM-DD`, and the list datetimes use the existing admin formatting.
---
## Registry Safety
| Registry | Blocks Used | Safety Gate |
|----------|-------------|-------------|
| shadcn official | none (shadcn not used) | not applicable |
| third-party registries | none | not applicable |
| npm (new admin SPA deps) | none: only existing `reka-ui`, `@lucide/vue`, `vue`, `vue-router` and `openapi-fetch` | not applicable. The release gates still apply: `scripts/check-admin-openapi.sh --check` after the swag annotations, and a rebuilt, committed `modules/boardwalk/dist` passing `scripts/check-admin-dist.sh` |
---
## Checker Sign-Off
- [x] Dimension 1 Copywriting: FLAG (non-blocking)
- [x] Dimension 2 Visuals: PASS
- [x] Dimension 3 Color: PASS
- [x] Dimension 4 Typography: FLAG (non-blocking)
- [x] Dimension 5 Spacing: FLAG (non-blocking)
- [x] Dimension 6 Registry Safety: PASS
- [x] Dimension 7 Inventory Provenance: PASS
**Approval:** approved 2026-11-20 (msd-ui-checker)

View File

@@ -0,0 +1,90 @@
---
phase: "32.2"
slug: "mcp-oauth-with-administrator-subjects"
# 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-20"
---
# Phase 32.2 — Validation Strategy
> Per-phase validation contract for feedback sampling during execution.
---
## Test Infrastructure
| Property | Value |
|----------|-------|
| **Framework** | go test (+ testcontainers Postgres), vitest (+ browser config) |
| **Config file** | per-package `TestMain` (`sm-oauthserver-plugin/testmain_test.go`); `admin/vitest.config*.ts` |
| **Quick run command** | `go test -short ./modules/pier ./modules/wristband ./modules/cabana ./modules/pact`; `go -C ../sm-oauthserver-plugin test -short ./...` |
| **Full suite command** | `go vet ./... && go test ./... && go test -tags summercms_mcp ./modules/pier ./modules/surf`; `go -C ../sm-oauthserver-plugin test ./... && go -C ../sm-oauthserver-plugin test -tags summercms_mcp ./...`; `npm --prefix admin run typecheck && npm --prefix admin run test && npm --prefix admin run test:browser`; `scripts/check-admin-openapi.sh --check && scripts/check-admin-dist.sh`; `go run ./cmd/summer docs:build --check` |
| **Estimated runtime** | ~60 s quick, ~6 min full (Docker) |
---
## Sampling Rate
- **After every task commit:** Run the quick command of the touched repo
- **After every plan wave:** Run the full suite of the touched repo
- **Before `/msd-verify-work`:** All full suites green, plus `check-admin-openapi.sh --check`, `check-admin-dist.sh` and the grzyby smoke script
- **Max feedback latency:** 60 seconds (quick loop)
---
## Per-Task Verification Map
Filled by the planner per task; source map from RESEARCH.md §Validation Architecture:
| Criterion | Behavior | Test Type | Automated Command | File Exists | Status |
|-----------|----------|-----------|-------------------|-------------|--------|
| SC-1 | wristband `ConsentPath`/`DefaultScopes` defaults unchanged, set values used | unit | `go test -short ./modules/wristband -run 'TestAuthorize(ConsentPath\|DefaultScopes)'` | ❌ W0 | ⬜ pending |
| SC-1 | backend mode authorize → admin `/connect`; user consent + OIDC routes absent | integration | `go -C ../sm-oauthserver-plugin test ./ -run TestBackendMode` | ❌ W0 | ⬜ pending |
| SC-1 | admin consent endpoint (401/404/hidden scopes/allow/deny) | integration | `go test ./modules/cabana -run TestMCPAdminConsent`; plugin `-run TestBackendConsent` | ❌ W0 | ⬜ pending |
| SC-1 | backend grant rows + migration up/down | integration | plugin `go test ./ -run 'TestBackendSubjectMigration\|TestBackendGrantRows'` | ❌ W0 | ⬜ pending |
| SC-1 | mode off: existing suites unchanged | regression | plugin `go test ./...`; sm-bm-app `go test ./...` | ✅ | ⬜ pending |
| SC-1 | ConnectView + router | unit | `npm --prefix admin run test -- tests/views/ConnectView.test.ts tests/app/router.test.ts` | ❌ W0 | ⬜ pending |
| SC-2 | pier backend-only grant, ScopeLimit; linked grant unchanged | unit | `go test -short ./modules/pier -run 'TestBackendOnlyGrant\|TestLinkedGrantNoScopeLimit'` | ❌ W0 | ⬜ pending |
| SC-2 | tools match a `g15_` token with equal scopes | integration | plugin `go test -tags summercms_mcp ./ -run TestBackendGrantToolsMatchPersonalToken` | ❌ W0 | ⬜ pending |
| SC-3 | My account items + revoke | unit + integration | `go test ./modules/cabana -run TestAccountContributionItems`; plugin `-run TestBackendRevokeFromAccount` | ❌ W0 | ⬜ pending |
| SC-3 | delete/deactivate/password/role cascade + verifier cutoff | integration | `go test ./modules/cabana -run TestBackendAccessRevokedEvent`; plugin `-run TestBackendCascade` | ❌ W0 | ⬜ pending |
| SC-4 | local stack proof | smoke | `cd ../sm-grzybyfunkcjonalne-app && scripts/smoke-mcp-oauth.sh` | ❌ W0 | ⬜ pending |
| SC-4 | vhost OAuth locations | static | `cd ../sm-grzybyfunkcjonalne-app && scripts/check-deploy.sh` | ✅ (extend) | ⬜ pending |
| SC-5 | docs identifiers and snippets | static | `go run ./cmd/summer docs:build --check` | ✅ | ⬜ pending |
*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
---
## Wave 0 Requirements
- [ ] Plugin harness helper booting with `mcp.subject: backend` and a backend user (extend `harness_test.go` `bootOAuthWith`)
- [ ] pier fake verifier returning a backend grant (`modules/pier/helpers_test.go`)
- [ ] `admin/tests/views/ConnectView.test.ts` fixtures for the new endpoint
- [ ] `scripts/smoke-mcp-oauth.sh` in sm-grzybyfunkcjonalne-app
---
## Manual-Only Verifications
| Behavior | Requirement | Why Manual | Test Instructions |
|----------|-------------|------------|-------------------|
| `SameSite=Strict` admin cookie on a real cross-site connector redirect chain | SC-1, SC-4 | Local proof is same-site | After deploy (out of phase), add the connector in Claude and sign in |
| Claude connector handling of `*` and `offline_access` | SC-4 | Needs the live connector | Same live check |
---
## 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,288 @@
---
phase: 32.2-mcp-oauth-with-administrator-subjects
verified: 2026-11-21T12:27:00Z
status: human_needed
score: 4/5 roadmap success criteria verified (SC-5 partial: docs and tests verified, patch tags held by the user)
covered_files:
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-01-PLAN.md
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-01-SUMMARY.md
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-02-PLAN.md
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-02-SUMMARY.md
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-03-PLAN.md
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-03-SUMMARY.md
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-04-PLAN.md
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-04-SUMMARY.md
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-PLAN.md
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-SUMMARY.md
- admin/openapi/admin.json
- admin/src/api/schema.d.ts
- admin/src/api/types.ts
- admin/src/app/pageTitle.ts
- admin/src/app/router.ts
- admin/src/components/account/AccountContributions.vue
- admin/src/views/ConnectView.vue
- admin/src/views/LoginView.vue
- admin/tests/account/AccountContributions.test.ts
- admin/tests/app/router.test.ts
- admin/tests/smoke/account-items.smoke.test.ts
- admin/tests/smoke/connect.smoke.test.ts
- admin/tests/views/ConnectView.test.ts
- admin/tests/views/LoginView.test.ts
- docs/backend/admin-spa.md
- docs/backend/users-and-permissions.md
- docs/plugins/registration.md
- docs/services/events.md
- docs/services/mcp.md
- docs/services/oauth-server.md
- modules/cabana/README.md
- modules/cabana/account.go
- modules/cabana/account_contributions.go
- modules/cabana/account_items_smoke_test.go
- modules/cabana/account_items_test.go
- modules/cabana/admin_events.go
- modules/cabana/admin_openapi.go
- modules/cabana/backend_access_revoked_smoke_test.go
- modules/cabana/backend_access_revoked_test.go
- modules/cabana/backend_access_revoked_tx_test.go
- modules/cabana/backend_roles_admin.go
- modules/cabana/backend_users_admin.go
- modules/cabana/commands.go
- modules/cabana/contracts.go
- modules/cabana/export_test.go
- modules/cabana/http.go
- modules/cabana/mcp_admin_consent_test.go
- modules/cabana/mcp_consent.go
- modules/cabana/mcp_consent_smoke_test.go
- modules/cabana/openapi_conformance_test.go
- modules/cabana/phase10_coverage_test.go
- modules/cabana/phase10_csrf_test.go
- modules/cabana/security_coverage_test.go
- modules/cabana/token_routes_test.go
- modules/cabana/token_scope_names_test.go
- modules/cabana/token_scopes_export.go
- modules/pact/README.md
- modules/pact/capabilities.go
- modules/pact/mcp.go
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- modules/pier/README.md
- modules/pier/backend_guard.go
- modules/pier/backend_only_grant_test.go
- modules/pier/backend_subject_smoke_test.go
- modules/pier/identity.go
- modules/wristband/README.md
- modules/wristband/authorize.go
- modules/wristband/consent_path_smoke_test.go
- modules/wristband/consent_path_test.go
- modules/wristband/server.go
covered_digest: "v2:sha256:cecde21ecf0b63d819c14d6ed77d9bc7a1d890137f0819f9e2b47497916d1159"
# The fingerprint tool refuses files outside the project root, so the sibling
# repositories cannot be fingerprinted. They were verified at these commits:
# summercms.go HEAD 5a54122e (code at 0ade662a; highest tag v0.6.6)
# ../sm-oauthserver-plugin HEAD f9819b3 (15 commits ahead of origin/master 7b9899f = v0.1.7; local ` M go.work` not touched)
# ../sm-grzybyfunkcjonalne-app HEAD 013d3f9 (8 ahead of origin/master); committed gitlink 7b9899f, submodule working tree 4c209c1 (pre-fix), go.mod v0.1.7
# App gates were run through a temporary GOWORK in the session scratchpad that
# points golem15.oauthserver at ../sm-oauthserver-plugin (f9819b3); the app's
# go.work was not edited.
behavior_unverified: 0
overrides_applied: 0
re_verification:
previous_status: human_needed
previous_score: 4/5 roadmap success criteria verified (SC-5 partial)
gaps_closed: []
gaps_remaining: []
regressions: []
note: "The previous report had no gaps: section. It was regenerated after the code-review fixes (framework fa7a8482..0ade662a, plugin 1f872f6..f9819b3, app 3215b68..013d3f9). All five truths were re-checked in full, not as a regression pass."
coincidental_reliance_items:
- truth: "SC-4: sm-grzybyfunkcjonalne-app mounts golem15.oauthserver in backend mode and the local stack completes discovery, registration, sign-in and a Journal tool call over OAuth"
reason: undeclared-precondition
harden: "The proof holds only for a build whose oauthserver module is the unpushed plugin checkout (here via a scratch GOWORK at f9819b3; with the app's own go.work the submodule working tree sits at 4c209c1, which predates every PA-WR fix). The committed app state (gitlink 7b9899f, go.mod v0.1.7) still has no backend mode. The new check-deploy guard (2190109) now makes this visible: check-deploy fails at app HEAD until the held release pointer bump lands (PA-CR-01, deferred to UAT item 4)."
human_verification:
- test: "Live connector check (cross-site SameSite=Strict admin cookie, D-03 / RESEARCH A2). After the production deploy, add https://grzybyfunkcjonalne.pl/mcp as a connector in Claude while signed in to /gfadmin, start the OAuth sign-in, then call a Journal tool and revoke the connection on My account. Procedure: ../sm-grzybyfunkcjonalne-app/DEPLOY.md, section 'Live connector check (deferred)'; 32.2-VALIDATION.md, Manual-Only Verifications row 1."
expected: "After the cross-site redirect from Claude, the /gfadmin/connect consent card shows the signed-in administrator, not the login screen. If it shows login, signing in must return to the same consent request."
why_human: "A localhost stack is same-site, so neither the smoke script nor any test can reproduce the cross-site navigation chain. Status: unverified."
- test: "Live connector scope behaviour (32.2-VALIDATION.md, Manual-Only Verifications row 2). In the same live run, note which scope value Claude sends to /oauth/mcp/authorize and whether the consent card offers the expected scopes."
expected: "The consent card lists the catalog scopes the signed-in administrator can grant (for example journal, journal:read; `*` collapses the grant to everything the administrator may use) and offers Stay connected. Since FW-WR-01 (fa7a8482) a request whose only scope is offline_access gets the backend-mode DefaultScopes (the token catalog) plus offline_access, so it must no longer end on 'no grantable scope' with Deny only. If it still does, that is a regression to report."
why_human: "Depends on the real Claude connector's authorize request; the fallback is proven in wristband unit tests with a catalog-shaped server, not against the live connector."
- test: "Production resource override (review PA-WR-09). During the deploy, check that SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE is set in go/.env and that GET /.well-known/oauth-protected-resource/mcp .resource equals the authorization server's resource (https://grzybyfunkcjonalne.pl/mcp)."
expected: "Both resources are the public https URL. Since PA-WR-09 the plugin release with backend mode refuses to boot when the key is missing (loopback resource on a public issuer), and `scripts/check-deploy.sh --live` on the server reports ok."
why_human: "Deploy-time environment; the --live branch of check-deploy was never run on a server."
- test: "SC-5 release go-ahead. 32.2-05-release-decision.txt records hold (framework-base v0.6.6, plugin-base v0.1.7). Decide whether to run plan 05 task 5's tag-and-publish branch: framework next free v0.6 patch (v0.6.7 if still free, must contain b1b96d85), sm-oauthserver-plugin v0.1.8 requiring that tag, push the plugin, then the grzyby pointer bump as its own commit (gitlink, go.mod require, regenerated plugins.gen.go), then the two changelog posts the same day."
expected: "The framework tag contains the review fixes up to 0ade662a (the plugin's d581799 calls wristband.CheckConsentPath, which exists only from 1dcc2ed0). Tags v0.6.x and v0.1.8 on origin, plugin go.mod on the framework tag, app gitlink and go.mod on v0.1.8 (also moves the submodule working tree off 4c209c1), two changelog URLs recorded in 32.2-05-changelog-published.txt; task 5's automated verify passes and `scripts/check-deploy.sh` in the app passes again."
why_human: "Releases are gated on the user's word (tag only at phase completion after verification). SC-5's tag clause is not met until this runs; it is a pending user decision, not a code gap."
---
# Phase 32.2: MCP OAuth with administrator subjects Verification Report
**Phase Goal:** As an editor of a blog-only application whose MCP tools are backend-guarded (Journal) and which has no frontend users, I want to add the site's `/mcp` as a connector and sign in once as my administrator account over OAuth, so that agents no longer need a hand-copied `g15_` personal token. Delivered as an additive, off-by-default backend-subject mode of `sm-oauthserver-plugin`, so applications on the frontend-user flow are unchanged.
**Verified:** 2026-11-21T12:27:00Z
**Status:** human_needed
**Re-verification:** Yes, regenerated after the code-review fixes (the previous report had no gaps)
**Mode:** mvp
## MVP user-story guard
As in the previous run, `user-story.validate` rejects the goal only because it reads "As **an** editor" and the canonical regex wants the literal `As a `. Role, capability and outcome slots are present. Verification proceeds; reported as a wording warning.
## User Flow Coverage
Outcome clause: "agents no longer need a hand-copied `g15_` personal token".
| # | Step | Expected | Evidence in codebase | Status |
|---|------|----------|----------------------|--------|
| 1 | Add `<site>/mcp` as a connector | 401 with `resource_metadata`; metadata points at `/oauth/mcp/*`; OIDC off | smoke steps 1-3, re-run here against plugin f9819b3 | VERIFIED (locally) |
| 2 | Client registers, authorize hands off | DCR 201; 302 to `/gfadmin/connect?request=<id>` | smoke 4-6; `servers.go` ConsentPath = admin prefix + `/connect`, now checked at boot (`wristband.CheckConsentPath`, d581799) and at authorize (1dcc2ed0) | VERIFIED |
| 3 | Sign in once as the administrator | anonymous visitor goes through admin login and back | router `/connect`; `router.test.ts`; smoke 7 | VERIFIED same-site; cross-site cookie is human item 1 |
| 4 | Consent | card with client, redirect host, grantable scopes; Allow issues a code | `ConnectView.vue` (39 tests), cabana `mcpConsentShow`/`mcpConsentDecide`, plugin provider; smoke 8 | VERIFIED |
| 5 | Token exchange | tokens whose rows name the administrator only | smoke 9; `TestBackendModeSmoke`, `TestBackendGrantRows` | VERIFIED |
| 6 | Agent calls a Journal tool | `journal_list_posts` listed and callable | smoke 10 (11 tools, isError false) | VERIFIED (locally) |
| 7 | `g15_` tokens keep working | same list and call with a personal token | smoke 11; `TestBackendGrantToolsMatchPersonalToken` | VERIFIED |
| 8 | Access ends when it should | password change, deactivate, delete, role/permission change, My account revoke | smoke 12 (401 after password change); `TestBackendCascade`, `TestBackendRevokeFromAccount`, `TestBackendAccessRevokedEvent`, `TestBackendSubjectRevalidatedUnderLock` | VERIFIED |
The outcome holds for a build from the working trees. On the committed app master it does not yet hold (pinned plugin v0.1.7 has no backend mode); check-deploy now refuses that tree, and the held release closes it.
## Goal Achievement
### Observable Truths (ROADMAP success criteria)
| # | Truth | Status | Evidence |
|---|-------|--------|----------|
| SC-1 | Backend mode: authorize recognises a signed-in administrator, anonymous browser goes through admin login and back, branded consent page; grant carries `BackendUserID` and no frontend user. Mode off: every existing flow and test of sm-oauthserver-plugin and sm-bm-app passes unchanged. | VERIFIED | Handoff `{issuer}{ConsentPath}?request=` with the new same-origin guard (`wristband/authorize.go:167` `CheckConsentPath` before storing; refusals of `//evil`, `@evil`, `?`, `#`, `\` in `TestCheckConsentPath`). Consent in the admin SPA (D-03; ROADMAP still says "server-rendered", wording note carried from the previous report). Decide now loads the request through Show first and rejects a provider redirect that leaves the registered redirect URI (`mcpConsentSameRedirect`, `TestMCPConsentSameRedirect`). Grant rows user_id NULL / backend_user_id set (`TestBackendGrantRows`, `TestBackendSubjectMigration`). Mode off re-run here: plugin full suite `go test -count=1 ./...` (Docker) and sm-bm-app `go test -short -tags summercms_mcp ./...` through a scratch GOWORK against plugin f9819b3 and framework HEAD, both exit 0. User-mode impacts of the fixes reviewed: user mode keeps `read` in `fixedMCPScopes`, so the new `invalid_scope` refusal (no `read` and no DefaultScopes) cannot fire there; administrator rows are refused in user mode (`TestUserModeRefusesAdministratorGrants`), which only narrows; a loopback `mcp.resource` only warns in user mode; an invalid `mcp.consent_path` with MCP on now fails boot in user mode too (documented behaviour note, Info). |
| SC-2 | pier resolves such a grant straight to the backend subject, no link lookup; tools capped by cabana permissions and granted scopes like a scope-limited `g15_` token. | VERIFIED | `pier/identity.go:218` now switches on `grant.Subject`: backend to `resolveBackendGrant`, empty to the user path, anything else `ErrUnauthorized` (FW-WR-03, regression grants `member` and `Backend` refused in `backend_only_grant_test.go`). `resolveBackendGrant` refuses UserID != 0 or BackendUserID == 0, binding `oauth:backend:<client>:<admin>`, `ScopeLimited: true`. Re-run here: `go test -count=1 ./modules/pier` (Docker, includes `TestBackendSubjectSmoke`) ok; plugin `TestBackendGrantToolsMatchPersonalToken` (`-tags summercms_mcp`) PASS. |
| SC-3 | Revoking the grant (My account), or deleting, deactivating or re-passwording the administrator, ends the grant's tokens and open MCP sessions. | VERIFIED | cabana fires `BackendAccessRevokedEvent` in the save's transaction and now refuses a nil `Tx` (FW-WR-04, `TestBackendAccessRevokedNeedsTransaction`); deactivate passes the plain tx, not Unscoped (FW-WR-05, smoke asserts `ev.Tx.Statement.Unscoped` false in `TestBackendAccessRevokedSmoke`). Plugin `BackendCascade` refuses a nil Tx (`ErrBackendRevocationNoTx`, `TestBackendCascadeRefusesNoTx`), so revocation is always atomic under the lock. The race closed by PA-WR-03: the decision and the code exchange re-read the administrator under the grants lock (`BackendSubjectCurrent`, `TestBackendSubjectRevalidatedUnderLock`: 404/no code, 400 after cutoff move, 400 after deactivation). Double decision serialized (`MarkIssued` conditional update, `TestMCPMarkIssuedOnlyOnce`). Re-run here: `TestBackendCascade`, `TestBackendRevokeFromAccount`, `TestBackendRevocationSmoke`, `TestBackendAccountSmoke`, `TestBackendAccessRevokedEvent`, all PASS; smoke step 12 (401 after a password change). |
| SC-4 | grzyby mounts golem15.oauthserver in backend mode, proxy routes discovery and `/oauth/mcp/*` to Go, an MCP client completes discovery, registration, sign-in and a Journal tool call over OAuth on a local stack; `g15_` tokens keep working. | VERIFIED (coincidental-reliance) | Config, nginx and wiring unchanged from the previous verification and re-checked by check-deploy (every check before the CR-01 version guard passes). `scripts/smoke-mcp-oauth.sh` re-run here with `GOWORK` pointing at plugin f9819b3 (the script's `go -C "$ROOT" build` inherits it): "ok (12 steps)", grep for token or JWT values in the output: 0. App `go vet -tags summercms_mcp ./...` and `go test -short -count=1 -tags summercms_mcp ./...` through the same GOWORK: exit 0, which includes the plugin's new WR-09 boot check (the smoke sets the resource override). Caveat: see `coincidental_reliance_items` (committed app state still pins v0.1.7; `scripts/check-deploy.sh` at app HEAD exits 1 with "go.mod requires sm-oauthserver-plugin v0.1.7, which predates mcp.subject backend", on purpose). |
| SC-5 | READMEs, `docs/` and DEPLOY.md updated; unit tests in the last plan; framework and sm-oauthserver-plugin get patch tags. | PARTIAL (tags held) | Docs: new exported identifiers of the fixes are documented: `wristband.CheckConsentPath` (wristband README:150, 208; `docs/services/oauth-server.md:109`, including the offline_access fallback), plugin README lists `BackendSubjectCurrent`, `ErrBackendRevocationNoTx`, `BackendSubjects` and the loopback refusal; DEPLOY.md covers the rollback SQL (PA-WR-07), the resource override and `check-deploy.sh --live` (PA-WR-09), and the minimum plugin version guard (CR-01). `summer docs:build --check` re-run: "no problems found". Tests: plan 05 is the tests plan; the review fixes each added a test (red-checked by the fixer except WR-05/WR-06 plugin tests, which do not compile on the old code). Tags: NOT met. Highest framework tag v0.6.6, no v0.6.7 on origin, plugin origin/master still 7b9899f (v0.1.7), app pointer not bumped, no changelog posts; `32.2-05-release-decision.txt` = hold. Routed to human item 4 (user decision; tagging follows verification by project rule). |
**Score:** 4/5 roadmap truths verified (0 present-but-behavior-unverified). SC-5 is partial and pending the user's release go-ahead.
### Plan must_haves (merged under the SCs above)
| Plan | Must-have group | Status | Notes |
|------|-----------------|--------|-------|
| 01 | wristband ConsentPath/DefaultScopes, pact grant shape, pier branch, cabana consent endpoint, TokenScopeNames/Labels, account items, BackendAccessRevokedEvent, docs | VERIFIED | Fixes FW-WR-01..06 extend these without changing the contract shape; `CheckConsentPath` is additive (no `NewServer` signature change). `parseAuthorizeScopes` gained a `defaultsSet` parameter (unexported). |
| 02 | /connect route, ConnectView states, switch account, scope rules, account item rows, regenerated openapi, rebuilt dist | VERIFIED | SPA redirect guard now also refuses `blob:`, `file:`, `about:`, `filesystem:` and requires the destination to return to `client.redirect_host` (`ConnectView.vue:192`, tests in `ConnectView.test.ts`). `check-admin-openapi.sh --check` exit 0; `check-admin-dist.sh` "matches a fresh build"; 6 SPA files, 105 tests pass. |
| 03 | config keys and boot refusals, migration, store/verifier branches, consent provider, revocation listener, My account section, connections screen | VERIFIED | Plus PA-WR-01 (refresh reads the administrator on the rotation tx, `TestBackendRefreshOnOneConnection` with a one-connection pool), PA-WR-02 (lookup errors are retryable, `TestBackendLookupFailureIsNotTerminal`), PA-WR-05 (administrator grants honoured in backend mode only), PA-WR-09 (loopback resource refused in backend mode, `TestLoopbackResourceOnPublicIssuer`), `TestConsentPathCheckedAtBoot`, `TestAdminConsentAnswersThePendingRedirect`. |
| 04 | app wiring, smoke, nginx, check-deploy, DEPLOY.md | VERIFIED (local) | Smoke no longer puts secrets on argv (jq `env.*`, curl `@file`, `umask 077`; PA-WR-08). check-deploy gained the CR-01 version guard and the env.example/--live resource checks. |
| 05 | tracer tools test, unit tests, regression runs, release checkpoint | VERIFIED except the release truth | UI backstops as in the previous report (cross-site cookie remains human item 1). Release truth is human item 4. |
### Required Artifacts
| Artifact | Expected | Status | Details |
|----------|----------|--------|---------|
| `modules/pact/mcp.go` | MCPGrant.Subject, backend constant, ScopeLimited, MCPAdminConsent | VERIFIED | unknown subject documented as refused |
| `modules/wristband/authorize.go`, `server.go` | ConsentPath, DefaultScopes, CheckConsentPath | VERIFIED | `CheckConsentPath` at authorize.go:167, 214; offline_access fallback in `parseAuthorizeScopes` |
| `modules/pier/identity.go`, `backend_guard.go` | backend-only branch, subject switch, ScopeLimited | VERIFIED | identity.go:218-227, 262-283 |
| `modules/cabana/mcp_consent.go` | GET/POST consent with redirect check | VERIFIED | `mcpConsentSameRedirect` at :91 |
| `modules/cabana/admin_events.go` | event, reasons, nil-Tx refusal | VERIFIED | `backend_access_revoked_tx_test.go` (new) |
| `admin/src/views/ConnectView.vue` | consent card, redirect guard | VERIFIED | `window.location.assign` at :274 after the deny-list and host match |
| `modules/boardwalk/dist` | rebuilt SPA | VERIFIED | check-admin-dist passes |
| `../sm-oauthserver-plugin/classes/mcp_backend_subject.go` | locks, revoke, `BackendSubjectCurrent` | VERIFIED | |
| `../sm-oauthserver-plugin/classes/mcp_store.go` | exchange re-check, conditional MarkIssued, tx-bound refresh | VERIFIED | |
| `../sm-oauthserver-plugin/classes/mcp_verifier.go` | backend branch gated by `BackendSubjects` | VERIFIED | set in `servers.go` from `cfg.BackendMode()` |
| `../sm-oauthserver-plugin/classes/backend_cascade.go` | listener, nil-Tx refusal | VERIFIED | |
| `../sm-oauthserver-plugin/controllers/mcp_admin_consent.go` | provider, re-check under lock | VERIFIED | |
| `../sm-oauthserver-plugin/servers.go` | DefaultScopes = catalog, CheckConsentPath at boot | VERIFIED | lines 240-285 |
| `../sm-grzybyfunkcjonalne-app/scripts/smoke-mcp-oauth.sh` | twelve-step proof | VERIFIED | re-run, pass |
| `../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh` | deploy guard incl. CR-01 | VERIFIED (fails on purpose until the release bump) | |
### Key Link Verification
| From | To | Via | Status |
|------|----|-----|--------|
| plugin `NewServers` (backend mode) | wristband `Options.DefaultScopes` | `slices.Clone(catalog)` | WIRED; offline_access-only requests now use it |
| plugin `NewServers` | `wristband.CheckConsentPath` | boot error when `mcp.enabled` | WIRED (`TestConsentPathCheckedAtBoot`) |
| wristband authorize | `Options.ConsentPath` | handoff URL, guarded | WIRED |
| pier `resolveOAuth` | `resolveBackendGrant` | `switch grant.Subject` | WIRED |
| pier backend subject | backend guard ScopeLimitFor | `MCPSubject.ScopeLimited` | WIRED (`TestBackendSubjectSmoke`) |
| cabana `mcpConsentDecide` | provider Show then Decide | `mcpConsentSameRedirect` on the answer | WIRED |
| cabana save sites | plugin `BackendCascade` | event with non-nil save tx | WIRED (`TestBackendAccessRevokedEvent`, `TestBackendCascade`) |
| plugin consent provider | `classes.BackendSubjectCurrent` | inside `WithinBackendGrantsLock` | WIRED (`TestBackendSubjectRevalidatedUnderLock`) |
| plugin `NewServers` | store and verifier `BackendSubjects` | `cfg.BackendMode()` | WIRED (`TestUserModeRefusesAdministratorGrants`) |
| app config `mcp.resource` | plugin loopback check / pier resource | env override | WIRED locally; production is human item 3 |
### Data-Flow Trace (Level 4)
| Artifact | Data | Source | Real data | Status |
|----------|------|--------|-----------|--------|
| ConnectView | consent request | cabana Show, plugin provider, wristband pending row | yes | FLOWING (smoke 8) |
| ConnectView fact box | admin login/name/email | `backend_users` | yes | FLOWING |
| My account `mcp_connections` | items | consents joined with clients | yes | FLOWING (`TestBackendAccountSmoke`) |
| MCP connections screen | rows | backend consents, backend_users, clients | yes | FLOWING |
### Behavioral Spot-Checks (run in this verification)
| Behavior | Command | Result | Status |
|----------|---------|--------|--------|
| Framework vet and fast suite | `go vet ./...`; `go test -short -count=1 ./...` | exit 0, exit 0 | PASS |
| Framework Docker tests, touched modules | `go test -count=1 ./modules/wristband ./modules/pier`; `go test -count=1 -run 'TestMCPAdminConsent\|TestMCPConsentSameRedirect\|TestBackendAccessRevoked\|TestAccountContributionItems\|TestTokenScopeNames\|TestMCPConsent' -v ./modules/cabana` | ok, ok; 9 top-level PASS incl. `TestBackendAccessRevokedNeedsTransaction`, `TestBackendAccessRevokedSmoke` | PASS |
| Plugin vet and fast suite | `go vet ./...`; `go test -short -count=1 ./...` (also with `-tags summercms_mcp`) | exit 0 | PASS |
| Plugin backend-mode and review-fix tests (Docker) | `go test -count=1 -tags summercms_mcp -run '<19 named tests>' -v .` | 19 PASS, 0 SKIP | PASS |
| Plugin full suite (user mode unchanged) | `go test -count=1 ./...` | ok (128 s), exit 0 | PASS |
| sm-bm-app against the fixed plugin | scratch GOWORK, `go test -short -count=1 -tags summercms_mcp ./...` | exit 0; sm-bm-app tree unchanged | PASS |
| App against the fixed plugin | scratch GOWORK, `go vet -tags summercms_mcp ./...`; `go test -short -count=1 -tags summercms_mcp ./...` | exit 0, exit 0 | PASS |
| grzyby local proof | `GOWORK=<scratch> bash scripts/smoke-mcp-oauth.sh` | "ok (12 steps)"; secret grep 0 | PASS |
| grzyby deploy guard | `bash scripts/check-deploy.sh` | exit 1: "go.mod requires sm-oauthserver-plugin v0.1.7, which predates mcp.subject backend" | EXPECTED FAIL (PA-CR-01, held release) |
| Admin SPA | `npm --prefix admin run test -- ConnectView router LoginView AccountContributions connect.smoke account-items.smoke` | 6 files, 105 tests | PASS |
| Contract, dist, docs | `check-admin-openapi.sh --check`; `check-admin-dist.sh`; `summer docs:build --check` | exit 0; matches a fresh build; no problems found | PASS |
### Probe Execution
Step 7c: the phase declares no probe scripts and no `scripts/*/tests/probe-*.sh` applies; the grzyby smoke is the phase's runnable check and was executed by the verifier.
### Requirements Coverage
No requirement IDs are registered for this phase (ROADMAP: "Requirements: TBD"). Plans use SC-1..SC-5 as stand-ins; coverage is the truths table. No orphaned requirements.
### Code review disposition (32.2-REVIEW-DISPOSITION.md)
16 of 29 findings fixed (FW-WR-01..06, PA-WR-01..09), PA-CR-01 deferred to the release (detection landed), 13 info findings open. Each fix named in the fix reports was located in the code at the stated commit and its test re-run here. None of the open info findings makes a truth false. Two observations from this verification, both Info:
- FW-WR-01 also changes wristband for hosts that set `ScopesSupported` without `read` and no `DefaultScopes`: a scopeless request is now refused with `invalid_scope` instead of storing `read`. The plugin's user mode always includes `read`, so no current consumer is affected, but the framework release notes should mention it.
- PA-WR-03 uses `tokens_valid_after`, which cabana sets one second ahead. A decision started, or a code issued, within that second after a password change is refused. This fails closed; the administrator retries.
### Anti-Patterns Found
| File | Line | Pattern | Severity | Impact |
|------|------|---------|----------|--------|
| phase diffs (framework 45eb34e5..HEAD, plugin 7b9899f..HEAD, app c06a2d8..HEAD) | - | TBD/FIXME/XXX/TODO/HACK added | none found | - |
| `admin/src/views/ConnectView.vue` | switchAccount catch | unreachable error branch (`logout()` never throws) | Info | carried from the previous report |
| `../sm-grzybyfunkcjonalne-app` working tree | - | submodule `plugins/golem15/oauthserver` checked out at 4c209c1, behind every plugin fix | Info | a build with the app's own go.work uses pre-fix plugin code; resolved by the release pointer bump |
### Human Verification Required
UAT evidence (Step 8b): `32.2-UAT.md` has four rows, all `pending`; none settles an item. The four items keep their exact row names; rows 2 and 3 have updated expected text for the fixed code.
#### 1. Live connector check (cross-site cookie)
**Test:** After the production deploy, add `https://grzybyfunkcjonalne.pl/mcp` as a connector in Claude while signed in to `/gfadmin`, sign in, call a Journal tool, then revoke on My account.
**Expected:** The consent card shows the signed-in administrator after the cross-site redirect; if it shows login, signing in returns to the same request.
**Why human:** Cross-site `SameSite=Strict` navigation cannot be reproduced on localhost.
#### 2. Connector scope behaviour
**Test:** In the same run, note the scope value Claude sends to `/oauth/mcp/authorize` and what the card offers.
**Expected:** The card lists the catalog scopes the administrator can grant and offers Stay connected. A request with only `offline_access` now gets the catalog (FW-WR-01 fixed), so "no grantable scope" with Deny only would be a regression.
**Why human:** Depends on the real connector's request.
#### 3. Production MCP resource
**Test:** Check that `SUMMER_GOLEM15__OAUTHSERVER__MCP__RESOURCE` is set, run `scripts/check-deploy.sh --live`, and compare the protected-resource `.resource` with the authorization server's resource.
**Expected:** Both `https://grzybyfunkcjonalne.pl/mcp`; `--live` ok. A missing key now fails boot instead of logging only.
**Why human:** Deploy-time environment; `--live` has not been run on a server.
#### 4. SC-5 release go-ahead (pending)
**Test:** Decide whether to run plan 05 task 5's tag-and-publish branch.
**Expected:** Framework v0.6 patch (v0.6.7 is still free) containing b1b96d85 and the review fixes through 0ade662a (the plugin now calls `wristband.CheckConsentPath`); plugin v0.1.8 on that tag, pushed; app pointer bump commit (gitlink, go.mod, plugins.gen.go), after which `scripts/check-deploy.sh` passes; two changelog posts the same day.
**Why human:** Releases need the user's word; the checkpoint answered hold.
### Gaps Summary
No code gaps block the phase goal. SC-1 to SC-4 were re-proven on the post-review code: the administrator signs in over OAuth through the admin SPA consent card, the grant names only the administrator, pier caps it like a `g15_` token with the same scopes and now refuses unknown subject kinds, every revocation path and the decision/exchange race end the grant, and the first consumer completes the flow locally while `g15_` tokens keep working. User mode is unchanged: the full plugin suite and sm-bm-app pass against the fixed plugin and framework.
What remains is release and live evidence: SC-5's tags, the plugin push, the app pointer bump (which also closes PA-CR-01 and makes check-deploy pass again) and the changelog posts wait for the user's go-ahead. The cross-site cookie, the connector's scope request and the production resource can only be checked after the deferred deploy.
---
_Verified: 2026-11-21T12:27:00Z_
_Verifier: Claude (msd-verifier)_

View File

@@ -0,0 +1 @@
No external API integration: the phase builds its own OAuth server mode and MCP resource; the Claude connector only calls these endpoints.

View File

@@ -0,0 +1,11 @@
# Phase 32.2 deferred items
## From plan 32.2-03 (sm-oauthserver-plugin)
- **TestPHPMethodMap fails, unrelated to this phase.** The test in `../sm-oauthserver-plugin/php_method_map_test.go` scans the PHP reference tree at `/media/nvme/dev/jz/wavepath.org/plugins/golem15/oauthserver/tests`. That tree gained `AuthorizeResolveUserJwtOnlyTest.php` on 2026-11-16, and its five methods are missing from the plugin's `php_methods.txt`. The failure shows under `go test -short ./...` and `go test ./...` in the plugin, before and after plan 03. Fix: map the five methods in `php_methods.txt` (or mark them as not ported), in a separate quick task.
**Resolved in plan 32.2-05:** sm-oauthserver-plugin commit `1124fd1` maps the five methods (three ported as adapted subtests of `TestAuthorizeResolveUserJwtOnly`, the flag default and the flag-off session fallback not applicable: the Go plugin resolves users from the session JWT only). `TestPHPMethodMap` passes again.
## From plan 32.2-05
- **An MCP authorize request whose only scope is `offline_access` stores no data scope.** wristband's `parseAuthorizeScopes` treats `offline_access` as an explicit scope, so the `DefaultScopes` fallback (backend mode: the token catalog) does not apply and the consent screen shows "no grantable scope" (only Deny). User mode behaves the same way (no `read` fallback either), so this is not new in this phase. Possible follow-up: treat `offline_access` like the identity scopes when deciding whether a request names a data scope. Not changed here.

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."

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