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:
+64
@@ -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) |
|
||||
Reference in New Issue
Block a user