docs(35): add code review fix report
This commit is contained in:
@@ -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 `<a href=...>` 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 (`<a href="javascript:alert(1)">`), 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	script:..."`, meta refresh `url=java	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_
|
||||
Reference in New Issue
Block a user