diff --git a/aidlc-docs/features/contact-forms-module/construction/plans/cms-u9-friendly-captcha-and-asf-host-code-generation-plan.md b/aidlc-docs/features/contact-forms-module/construction/plans/cms-u9-friendly-captcha-and-asf-host-code-generation-plan.md new file mode 100644 index 0000000..b3fcb5c --- /dev/null +++ b/aidlc-docs/features/contact-forms-module/construction/plans/cms-u9-friendly-captcha-and-asf-host-code-generation-plan.md @@ -0,0 +1,46 @@ +# Code Generation Plan — CMS-U9 friendly-captcha-and-asf-host + +Status: PLAN, waiting for approval by SLP Software - SLS - Main. Nothing built. No push, no deploy. + +## Starting point (already in the code) +- `ICaptchaVerifier` seam with `NullCaptchaVerifier` (always true); `ContactSubmissionService` calls it only when `Contact:Captcha:Enabled`; a `false` answer is classified as spam: **202 + status spam**, identical to today. +- Token response already has `captcha: null | { provider, siteKey }` (from `Contact:Captcha:Provider|SiteKey`); request already has optional `captchaToken`. So the wire contract needs **no change**; only the rule "captchaToken is required when captcha is on" gets a defined meaning (a missing/empty token counts as a failed check = spam, never a 400, so a bot learns nothing). +- Public routes carry `[PublicSiteEndpoint]` (gate exempt, also when the CMS/master is "not available"). + +## Decisions to confirm +1. **Friendly Captcha version: v2 (recommended).** Server verify: `POST https://global.frcapi.com/api/v2/captcha/siteverify` (EU-only alternative host `eu.frcapi.com`), JSON `{ "response": , "sitekey": }`, header `X-API-Key: `; result `success: true|false`. Endpoint host is configurable (`Contact:Captcha:VerifyUrl`, default global v2). v1 (`api.friendlycaptcha.com/api/v1/siteverify`, form `solution` + `secret`, EU host `eu-api.friendlycaptcha.eu`) is the old API and is **not** built. I will re-check these URLs/field names against the provider's current documentation at build time and report any difference before coding on them. +2. Client-side (for the website session): the v2 widget (`@friendlycaptcha/sdk`) needs the **site key** (from the token response) and renders into the form; on solve it yields a response string that is sent as `captchaToken`. The widget loads its worker/script from the app bundle (or a script URL) and talks to the provider API at runtime. +3. **Fail-open** (decided): provider timeout (verify timeout default 3 s, configurable), network error or 5xx => treated as passed + a warning log with the failure kind only (never token, address or message text). A definite negative answer (`success:false`, or 4xx for a bad/expired token) => spam. A 4xx caused by our own config (bad secret/sitekey: 401/403) => fail-open too, but logged as **error** `captcha_misconfigured` so it is noticed; the token response never leaks it. +4. Config per site, secret only via environment: `Contact:Captcha:Enabled|Provider (friendlycaptcha)|SiteKey|VerifyUrl|TimeoutSeconds`, secret `Contact__Captcha__Secret` (env only, never in committed config; startup refuses `Enabled=true` + `Provider=friendlycaptcha` with an empty secret or sitekey, logging names only). Unknown provider => startup validation failure. +5. Privacy note (docs): Friendly Captcha does not use cookies or personal tracking; the visitor's IP address is processed for the challenge request by the provider (EU-hosted option exists; verify call from our server sends the response + sitekey only, **not** the visitor IP unless we choose to). Documented per provider/version in the contract doc; exact wording to be checked against the provider's own privacy statement at build time, and ASF's privacy page owner (Andrea) needs to mention it. + +## Build steps +- [ ] **Step 1 — Verifier**: `FriendlyCaptchaVerifier : ICaptchaVerifier` using `IHttpClientFactory` (named client, timeout from options), returns true/false per the rules above; `CaptchaProviderOptionsValidator`; provider selection in `ContactModule` (`NullCaptchaVerifier` stays for provider-less/disabled). +- [ ] **Step 2 — Submission rule**: when enabled, an empty `captchaToken` = failed check (spam), without calling the provider. +- [ ] **Step 3 — Token response**: unchanged shape; only returns `captcha` when enabled **and** provider/sitekey valid; test that no secret/verify URL ever appears in any response. +- [ ] **Step 4 — Tests (no real network)**: fake `HttpMessageHandler`: success true/false, timeout, 5xx, 401/403 (misconfigured), malformed JSON, cancellation; empty token; request body/headers exact (`X-API-Key`, JSON fields); logs carry no token/secret/PII; pipeline test on the real host with the fake handler registered: spam => 202 + stored as spam, identical response body to genuine; fail-open => genuine stored; token response `captcha` shape; startup validation (missing secret/sitekey, unknown provider). +- [ ] **Step 5 — Subject label check (decision a)**: tests with labels containing `& ' " < > ` and line-break/control characters through validator, mail (subject stays fixed; HTML body encodes the label; text part indents it), Reply-To, admin list/detail JSON (React escapes on display; verified by a frontend test with `x & "q"`). +- [ ] **Step 6 — CSP proposal (not applied to ASF by me)**: add a catalogue option so a site can allow the captcha provider: for `StrictSite`: `connect-src 'self' https://global.frcapi.com` (and `https://eu.frcapi.com` when the EU host is used), `frame-src` is not needed for the v2 default widget (it runs in-page); if the widget is configured in iframe mode add `frame-src https://global.frcapi.com`; `script-src` additions only if the SDK is loaded from a CDN instead of the site bundle (avoid: bundle it). Delivered as: `SecurityHeaders:AllowedSiteConnectOrigins` entries (already supported by the catalogue) plus documented values; **no catalogue code change is needed for connect-src**, and I add a `frame-src` extension only if you want iframe mode. Documented in the contract doc. +- [ ] **Step 7 — ASF host** (coordinate with session `AndreaSlopFotografie`; the host project is theirs, I only add): + - `ProjectReference` to `Modules.Contact` + module registration in `Api.AndreaSlopFotografie`; per-site `Contact:SiteId` (e.g. `andreaslop`), own database/connection as already used there. + - Host tests (new, in `Api.AndreaSlopFotografie.Tests`, real pipeline on MariaDB): (a) contact routes answer only when `Contact:Enabled` + CMS switch; (b) `[PublicSiteEndpoint]`: token/submit routes stay reachable (200/202/404-closed, never the gate's 503) while the availability gate is "not available"; admin routes remain gated; (c) rate limits are per client: with `ForwardedHeaders:KnownProxies` set, two client addresses get separate buckets; without it, one shared bucket (test documents the consequence). + - Docs: release conditions for ASF: `ForwardedHeaders__KnownProxies__0=` before `Contact__Enabled=true`; `Contact__RecipientEmail` env only; From: `Email:FromAddress` is the site address; contact mail uses `GetEffectiveSenderAsync`, so it follows `Email:AllowedFromAddresses`/the site settings (to be set for ASF to a real ASF address via env, not in repo); captcha secret via env. +- [ ] **Step 8 — Docs**: contract doc (captcha shape, `captchaToken` rule, spam behaviour, fail-open, CSP values, privacy note), handoff section 8 (keys + env var names), OpenAPI regenerated (description of `captchaToken`/`captcha`), summary, state/audit. +- [ ] **Step 9 — Verification**: all test projects incl. pipeline on a temporary MariaDB; one commit; no push; container removed. + +## Answers to the ASF-host facts (short) +1. ASF csproj/registration: **to build in U9** (step 7). +2. KnownProxies empty ⇒ one shared bucket behind IIS: **to build in U9**: host test + documented release condition (`ForwardedHeaders__KnownProxies__0`); `ClientPartitionKey` already used by the contact limiter (**present**). +3. From / AllowedFromAddresses: **present in code** (contact mail uses the site's effective sender); ASF value is an env/config decision for their host (**U9 doc**, no repo address). +4. CSP: **U9 proposal** (step 6; connect-src only via the existing `AllowedSiteConnectOrigins`, nothing applied to ASF by me). +5. Gate: `[PublicSiteEndpoint]` on `GET /contact-messages/token` and `POST /contact-messages` is **present** and tested on the SlpSoftware host (pipeline tests with the gate off); a test on the **ASF host configuration** is **to build in U9** (step 7b). Management routes stay gated. +6. Mail renderer/branding reuse: **present**. The contact mail uses the core `MailTemplateRenderer` (logo, brand colour, dark mode, nl/en) and the site's effective sender. + +## Not touched +Admin app (except possibly one test for escaped labels), auth/refresh, users, theme assets, `src/cms-client` (SLP Software - SLS - Main changes it), ASF host files other than the ProjectReference/registration agreed with the ASF session. + +## Questions +1. Friendly Captcha **v2** (recommended) — OK? +2. Missing `captchaToken` while captcha is on = spam (202), not 400 — OK? +3. Misconfigured provider (401/403 from verify) = fail-open + error log — OK, or fail-closed (everything becomes spam) instead? +4. Widget mode: in-page SDK (no `frame-src`) — OK?