Starts the contact form feature: AI-DLC inception and design, dev proxy for /api

Adds the contact-form-cms feature docs (requirements, execution plan,
functional and infrastructure design, code generation plan) and an optional
Vite dev proxy for /api through API_PROXY_TARGET.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-10 23:04:16 +01:00
co-authored by Claude Sonnet 5.5
parent 7d594ffa1d
commit 4da314c0ba
10 changed files with 490 additions and 1 deletions
@@ -0,0 +1,64 @@
# Infrastructure design: contact-form (unit 1, web)
Status: DRAFT for approval by SLP Software - SLS - Main (on behalf of Bryan).
## 1. Request path
All calls are same-origin: `/api/v1/contact-messages/token` and `/api/v1/contact-messages`. The site is served by the CMS host (test now, ASF production on IIS later), which also serves `/api`; no CORS and no new origin for the API.
```mermaid
flowchart LR
B[Browser] -->|same origin /api/v1| H[ASF CMS host<br/>contact module]
H --> M[(MariaDB)]
H --> S[SMTP]
B -.captcha API.-> F[Friendly Captcha<br/>global.frcapi.com provisional]
classDef c fill:#f6e05e,stroke:#c05621,color:#000;
classDef s fill:#63b3ed,stroke:#2b6cb0,color:#000;
classDef x fill:#fbb6ce,stroke:#97266d,color:#000;
class B c;
class H,M,S s;
class F x;
```
Text alternative: the browser talks only to the ASF CMS host on the same origin, plus the captcha provider's API when a captcha is required.
## 2. Content Security Policy
Two places define the CSP and both must match:
- `web/config/securityHeaders.ts` (the prescription and the Vite dev/preview headers) - changed in this feature.
- The ASF CMS host's security header options (set by the CMS session `AndreaSlopFotografie`) - requested from them, not edited here.
Planned additions (provisional; Friendly Captcha v2 with the bundled `@friendlycaptcha/sdk`). The official CSP guide (developer.friendlycaptcha.com/docs/v2/guides/csp) says the widget uses iframes and needs at least `frame-src https://*.frcapi.com`; it names no other directive. Bryan decides exact origin versus wildcard and the host (EU recommended, `eu.frcapi.com`; the EU endpoint needs a Friendly Captcha Advanced or Enterprise plan, to be checked by Bryan). Everything marked "test" is added only if a real-browser test proves it necessary; no wildcards beyond what Bryan accepts.
| Directive | Now | Add |
|---|---|---|
| frame-src | not set (falls back to default-src) | the exact origin of the chosen host (`https://eu.frcapi.com` or `https://global.frcapi.com`), or `https://*.frcapi.com` if Bryan accepts the wildcard the docs name |
| connect-src | `'self'` + Umami + Sentry | test: the chosen host origin (the SDK fetches from its API endpoint) |
| script-src | `'self'` + Umami | nothing planned (SDK bundled, first-party chunk); test: `'wasm-unsafe-eval'` only if the SDK needs WebAssembly |
| worker-src | not set | test: `blob:` only if the SDK needs it |
Rules: add only what a real-browser test proves necessary (except the documented frame-src); each added entry gets a comment with the reason; the existing test `securityHeaders` gets assertions for the exact directives; no `unsafe-eval`, no wildcard hosts. The captcha script chunk is first-party, so `script-src 'self'` still holds.
## 3. Dev proxy
`vite.config.ts` `server.proxy`: `/api` to `http://192.168.1.2:5290` (the temporary environment) for local development, configurable through an env variable (default off in CI). Production and preview have no proxy. The dev CSP `connect-src` stays `'self' ws:` plus the above; the proxy keeps requests same-origin in the browser.
## 4. Build and delivery
- New code is in the lazy ContactForm chunk and a separate captcha chunk; pages without a form in view load no new JS (Lighthouse budgets in `lighthouserc.cjs` must stay green; a measurement is part of Build and Test).
- `web/src/cms-client/` is plain TypeScript/React inside the existing build. ESLint `no-restricted-imports` and the boundary test copy over with the package.
- `siteContent.contactForm.enabled` stays `false` in the merge; Bryan switches it on after the server is ready and he gives the explicit go.
- The CI pipeline is unchanged (unit, e2e, lint, Lighthouse); the CMS-check mode of deploy-test is unchanged.
## 5. Configuration and secrets
No secrets in the client. The captcha `siteKey` is public and arrives in the token response, so there is no new build-time variable. Server settings (`Contact__RecipientEmail`, `Contact:Enabled`, `MinSeconds`, retention, `ForwardedHeaders:KnownProxies`/`ClientPartitionKey`, `Email:AllowedFromAddresses`) belong to the CMS sessions and are requested through SLP Software - SLS - Main.
## 6. Observability
Events `contact-sent` and `contact-failed` through the existing analytics wrapper; nothing else, no field values, no tokens. Sentry captures unexpected exceptions without breadcrumbs from form fields (existing scrubbing configuration is checked in Build and Test).
## 7. Rollback and go-live
- Rollback: set `siteContent.contactForm.enabled = false` and redeploy; the gate returns and no token request is made. The server can also close the form (`Contact:Enabled` off gives 404, which keeps the gate).
- Go-live needs: server module deployed on the ASF host, recipient and sender configured, captcha configured (or off), Bryan's explicit go.
## 8. Dependencies on other sessions
| Item | Owner |
|---|---|
| Package captcha slot (branch and commit) | SLP Software - SLS - Main |
| Server contact module, captcha verifier, openapi for ASF | SLS Software - CMS |
| ASF host config (CSP options, recipient, proxies, Contact:Enabled) | AndreaSlopFotografie (via SLS-Main) |
| ASF test host with the endpoint | after Bryan merges the CMS branch (not requested yet) |