Documents build and test, operations and the approved privacy wording

Adds the build and test summary and instructions, the deployment and
monitoring plans, the production readiness checklist with the go-live
conditions, and the approved privacy draft (retention, controller).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-10 23:40:11 +01:00
co-authored by Claude Sonnet 5.5
parent a1444b7b2a
commit d8847d8c3b
12 changed files with 136 additions and 20 deletions
@@ -0,0 +1,26 @@
# Deployment plan: contact-form-cms
Scope: the web change only. The server module and host configuration are delivered by other sessions.
## Method
The existing Gitea pipeline (continuous_integration.yaml). A push to master deploys the test site and ASF test; production only by manual dispatch. Nothing is merged or deployed without Bryan (a test deploy of the feature branch is allowed on request of Bryan or SLP Software - SLS - Main).
## What changes on deploy
- Site bundle with the form (lazy chunks), cms-client package, captcha widget chunk, new `frame-src` in the generated server configs (`web/deploy/iis/web.config`, `web/deploy/nginx/*.conf`, regenerated with `pnpm server-config`).
- `siteContent.contactForm.enabled` stays `false` in the merge: the site then asks the server nothing and shows the "Binnenkort" gate.
## Server side prerequisites for turning it on (not built here)
| Item | Owner |
|---|---|
| Contact module in the ASF host, `openapi/andreaslopfotografie.v1.json` | SLS Software - CMS |
| `Contact__RecipientEmail` (env only), sender in `Email:AllowedFromAddresses`, `Contact:Enabled` + CMS switch, `MinSeconds`, retention 12 months / 30 days spam | AndreaSlopFotografie (host) |
| `ForwardedHeaders:KnownProxies` / `ClientPartitionKey` on IIS | AndreaSlopFotografie (host) |
| ASF host CSP `frame-src`: global, global0, global1 (`AllowedSiteFrameOrigins__0..2`) | AndreaSlopFotografie (host) |
| Captcha: verifier configured with the secret; free key only for tests, paid plan before commercial use | Bryan / SLS Software - CMS |
## Rollback
Set `siteContent.contactForm.enabled = false` and redeploy (the gate returns, no token request). The server can also close the form (`Contact:Enabled` off answers 404, which keeps the gate). Captcha problems are handled by the form itself (message plus mail button).
## Test deploy steps (on request)
1. Merge or deploy the feature branch to the ASF test site through the pipeline (switch on only if the test host serves the contact endpoint).
2. Run the real-browser check from the build and test instructions against the test host.
@@ -0,0 +1,7 @@
# Monitoring plan: contact-form-cms
- **Events (Umami)**: only `contact-sent` and `contact-failed`, names only. No field values, token, idempotency key or captcha response anywhere in analytics, logs or Sentry.
- **Sentry**: the existing browser setup stays; the form logs nothing itself. Check once on the test site that a failed send does not put form values into a breadcrumb or event (Build and Test of the next deploy).
- **Server side (CMS)**: the contact module's message list (status, mail status, attempts) is the operational view; failed mails and spam counts are watched there. Owner: CMS sessions.
- **Watch after go-live**: ratio `contact-failed` to `contact-sent` in Umami; messages with mail status `failed`; captcha problem message shown (not counted separately, visible through failed sends).
- **Alerts**: none new on the web side; mail failures are shown in the CMS admin.
@@ -0,0 +1,31 @@
# Production readiness checklist: contact-form-cms
Status: web side ready for a test deploy; NOT ready for production (go-live conditions open). The form stays off in production (`siteContent.contactForm.enabled = false`) until Bryan gives an explicit go.
## Done (web)
- [x] Form on the headless `cms-client` package, no forked logic; import boundary enforced
- [x] No request to the server while the switch is off; token only when the form is near the screen
- [x] No token, widget or e-mail address in the prerendered HTML (tests)
- [x] Honeypot, idempotency key, one token refresh, server-side time check, captcha slot with fail-safe message and mail button
- [x] CSP: `frame-src` with exact global, global0, global1 hosts; no wildcard; real-browser run without violations
- [x] No personal data in analytics/logs; events limited to `contact-sent`/`contact-failed`
- [x] Tests: unit, component, property, e2e, real-browser widget run; lint, format, audit clean; Lighthouse as before
- [x] Dependency: `@friendlycaptcha/sdk` 1.1.3 (MPL-2.0), audit clean
## Go-live conditions (all must be true; Bryan decides)
- [ ] **Full ASF privacy statement published** (separate feature; the form text in `privacy-statement-draft.md` is input; mail provider and widget data still to check). Not needed for testing, required before go-live.
- [ ] **Captcha decision**: off at go-live until a paid Friendly Captcha plan exists (free key is for testing only); with the EU endpoint the CSP gets eu, eu0, eu1 and the privacy text changes.
- [ ] Server: contact module deployed on the ASF host, recipient and sender configured, retention 12 months / 30 days spam, proxies/partition key set, host CSP `frame-src` set.
- [ ] A real mail from the production host checked (SPF/DKIM, "toon origineel") and the message visible in the ASF CMS.
- [ ] Test of the form on the deployed ASF test host with the real server (after the CMS branch is merged and deployed).
- [ ] ASF production hosting (IIS) in place (separate feature).
- [ ] Bryan's explicit go, then `siteContent.contactForm.enabled = true` in its own reviewed change.
## Rollback
`enabled = false` and redeploy, or `Contact:Enabled` off on the server (404 keeps the gate).
## Risks and notes
- Free captcha tier must not be used commercially.
- The global endpoint processes IP addresses possibly outside the EU; EU needs the paid plan.
- With the switch on, a closed form (404) logs one console message per page view in the browser.
- Hydration e2e tests run with the switch off; if it is on, they need the API mocked.