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,56 @@
# Requirements clarification: contact-form-cms
Questions were asked interactively in chat (project agreement); answers recorded here afterwards. Open follow-up questions are routed through the session "SLP Software - SLS - Main" (Bryan's instruction, 2026-11-10).
## Question 1: Security Baseline extension
- A) Yes, enforce
- B) No
[Answer]: A
## Question 2: Property-based testing extension
- A) Full
- B) Partial (pure functions and round-trips)
- C) No
[Answer]: B
## Question 3: Operations phase
- A) Yes, include now
- B) Decide later
- C) No
[Answer]: A
## Question 4: Relation between the cms-client package and the existing ASF form
- A) Package replaces state and validation; the existing ContactForm UI stays and uses useContactForm
- B) Package only for sending
[Answer]: A
## Question 5: Subject
- A) Select value (id) is the subject
- B) Free text
- X) Other
[Answer]: X - The human-readable label ("Newborn shoot", "Overig") is sent as `subject`; the id stays local for the ?pakket= preselect. (Decision by Bryan, relayed by SLP Software - SLS - Main)
## Question 6: Robot check
- A) None now
- B) Friendly Captcha now
- X) Other
[Answer]: B - Build Friendly Captcha now (Bryan via SLP Software - SLS - Main). Package gets a captcha slot (SLS-Main), server verifier by SLS Software - CMS, widget + CSP + privacy text by this feature.
## Question 7: Form unavailable
- A) Mailto block instead of "Binnenkort"
- B) Keep the dimmed "Binnenkort" view
- X) Other
[Answer]: B - Keep the existing dimmed "Binnenkort" gate (Bryan).
## Question 8: Testing against the server
- A) Mocks in CI + manual check against the temporary environment
- B) Mocks only
[Answer]: A
@@ -0,0 +1,44 @@
# Requirements: contact-form-cms
## Intent analysis
- **User request**: Build the own contact form for Andrea Slop Fotografie on the CMS contact module, using the headless `cms-client` package from the SlpSoftware repo (read only, copied here).
- **Request type**: New feature on existing code (brownfield). Replaces the "no back-end yet" stub from `contact-page`.
- **Scope**: Web repo only (components, content, CSP, dev proxy, tests, docs). Server work is requested from other sessions, not built here.
- **Complexity**: Moderate to complex: public endpoint with personal data, captcha, prerender/hydration constraints, cross-session contract.
- **Depth**: Standard, security-relevant. User Stories skipped (one persona: the visitor).
## Decisions (see requirement-verification-questions.md)
Security Baseline: enforced. PBT: partial (PBT-02, 03, 07, 08, 09). Operations: included. Package replaces the form's own state and validation. Subject is the readable label. Friendly Captcha built now. Gate stays the dimmed "Binnenkort" view. Tests: mocks in CI plus manual against the temporary environment.
## Functional requirements
- **FR-CF-01 Package**: Copy `src/cms-client/` (http/, contact/, README, boundary test) into `web/src/cms-client/`. It stays headless and imports nothing from the app (boundary test plus ESLint rule). The copy is kept in sync with the SlpSoftware original; no local forks of its logic.
- **FR-CF-02 Logic**: `useContactForm` drives the existing Chakra skin (fields, select, PrivacyNote, success state with `replyTime`). The old `contactFormReducer`, own validation and the `submitContactForm` stub are removed or reduced to a thin mapping.
- **FR-CF-03 Field mapping**: naam to name (max 100), email to email (254), shoot to subject (the readable label, 1-100, e.g. "Newborn shoot", "Overig"), bericht to message (2000). The package id stays local for the `?pakket=` preselect. Messages are the package's NL messages.
- **FR-CF-04 Availability (progressive enhancement)**: The prerendered/initial render is the gate ("Binnenkort"). After hydration and when the form scrolls into view (IntersectionObserver) the client calls `GET /api/v1/contact-messages/token`; only on `200` (and a captcha provider this site supports) does the form become active. Any other result (404 form closed, 429, 5xx, network, unsupported captcha) keeps the gate. `siteContent.contactForm.enabled` stays as an extra static kill switch (default false until Bryan's go). When it is `false`, the client makes NO token request at all (no network traffic, no server cost). The token is fetched lazily when the form comes into view (IntersectionObserver); first focus is only the fallback where IntersectionObserver is missing.
- **FR-CF-05 Layout stability**: No layout shift on upgrade; the existing placeholder heights stay valid. No token, widget or e-mail address in the prerendered HTML.
- **FR-CF-06 Submit**: `POST /api/v1/contact-messages` with `Idempotency-Key`, honeypot `hpCheck` (client side only the honeypot; the 3 s browser time check is dropped, the server enforces `minSeconds` through the token), one automatic token refresh on `errors.token = expired`, `202` means success. Server field errors map to the fields; focus moves after render (inputs are disabled while sending). Error messages are not placed inside `<label>`.
- **FR-CF-07 Failure**: 429, 5xx, 503 or network errors give a generic failure message with the mailto fallback; visitors never see technical text. The 429 message comes from the package (Retry-After in minutes), no own text. The mailto fallback after a failed send keeps the address out of the HTML (the `useEmailAddress` approach stays).
- **FR-CF-08 Preselect**: A package chosen via a "Boek..." link before the form has mounted is not lost: `ContactPanel` remembers the last preselect and passes it as initial value.
- **FR-CF-09 Captcha (Friendly Captcha)**: When the token endpoint returns `captcha = {provider, siteKey}`, the widget is shown client-only after hydration in a reserved height, its token goes to `captchaToken`, and it resets on expiry. The package provides the slot (SLP Software - SLS - Main), the server verifies (SLS Software - CMS); this feature builds the widget, loads it only when needed, and adds the CSP entries for the exact provider and version. Fail-open on a provider outage is a server decision already taken.
- **FR-CF-10 Privacy**: The privacy statement names the captcha provider and what the form stores. No personal data in logs, Sentry or Umami; only the events `contact-sent` and `contact-failed`.
- **FR-CF-11 Dev proxy**: Vite dev proxy for `/api` to the temporary environment (`http://192.168.1.2:5290`). Production is same-origin through the host/IIS proxy; no CORS.
- **FR-CF-12 Accessibility**: Labelled fields, focus handling for errors, live region for success/failure, honeypot hidden from assistive tech, keyboard operable, widget with reserved height.
## Non-functional requirements
- **NFR-CF-01 Security** (Security Baseline enforced): CSP `connect-src 'self'` plus captcha origins only (script/frame entries per provider and version, nothing wider); no secrets in the client (the siteKey is public); no personal data, tokens or idempotency keys logged; input limits identical to the server; honeypot and idempotency handled; dependency audit stays clean.
- **NFR-CF-02 Performance**: No new JS on pages without a form in view; the captcha script loads only when the form is active; Lighthouse budgets of `lighthouserc.cjs` stay green.
- **NFR-CF-03 Testing**: Unit and component tests for mapping, gate states, preselect and submit paths with a mocked API; fast-check on mapping/validation round-trips (PBT-02/03/07/08/09); e2e with a mocked `/api` route; manual verification against the temporary environment (CMS 192.168.1.2:5175, API :5290, smtp4dev :5301) with evidence in the construction docs. Tests of the old reducer are replaced. Extra cases: an unknown or missing captcha provider keeps the gate; an expired captcha token is never sent; every subject label is 1-100 characters and a label containing & ' " < > does not break the payload (mail encoding is server-side, the payload is tested here).
- **NFR-CF-04 Compatibility**: Works with hydration of the prerendered site (PR #14); no hydration mismatch; with JS off the gate and the mail button show.
- **NFR-CF-05 Operations**: CSP and dev-proxy changes deploy through the existing pipeline; production stays off (`enabled: false`) until Bryan's explicit go; rollback is switching `enabled` off; checklist in the Operations phase.
## Out of scope / asked of others
- Server module, captcha verifier, openapi (SLS Software - CMS); package captcha slot (SLP Software - SLS - Main).
- Per-site server config for ASF: `Contact__RecipientEmail` (env only), sender in `Email:AllowedFromAddresses`, `ForwardedHeaders:KnownProxies`/`ClientPartitionKey` on IIS, `Contact:Enabled`, `MinSeconds`, retention, CMS switch (session `AndreaSlopFotografie`, routed by SLP Software - SLS - Main).
- ASF production hosting (IIS) and the production go-live.
## Resolved with SLP Software - SLS - Main (approved on behalf of Bryan, 2026-11-10)
1. Lazy token fetch via IntersectionObserver (first focus only as fallback).
2. Friendly Captcha: provisionally v2 (bundled SDK, script-src 'self'; API origin https://global.frcapi.com in connect-src and possibly frame-src; possibly worker-src blob: and 'wasm-unsafe-eval'). Final directives per version come from CMS-U9 and a test in a real browser; no wildcards.
3. Labels come from the existing shoot options in content; the label of "Overig" is fixed per site.
4. Package captcha slot: the token response carries `captcha {provider, siteKey}` or null; the hook offers `setCaptchaToken(token|null)` and `captchaRequired`; an expired token means `setCaptchaToken(null)` and a widget reset. The final package is copied only after SLS-Main reports the branch and commit.
5. Server side for ASF is done by SLS Software - CMS (module, captcha) with AndreaSlopFotografie (host); an ASF test host with the endpoint exists only after the CMS branch is merged and deployed (not requested yet).