Contact: Friendly Captcha v2, opstartvalidatie, ASF-host met Contact-module en hosttests (CMS-U9)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -5,7 +5,7 @@
|
||||
- **Feature Slug**: contact-forms-module
|
||||
- **Project Type**: Brownfield
|
||||
- **Start Date**: 2026-11-09
|
||||
- **Current Stage**: PHASE 2 - CMS-U7, CMS-U5 and CMS-U6 built and committed; next plan CMS-U8
|
||||
- **Current Stage**: PHASE 2 - CMS-U7, U5, U6, U8 and U9 built
|
||||
- **Branch**: feature/contact-forms-module (worktree ..SlpModularCms-contact-forms, from master d9cc539; main checkout stays on feature/identity-email-notifications — never switch it)
|
||||
|
||||
## Workspace State
|
||||
|
||||
@@ -155,3 +155,16 @@
|
||||
**Context**: Phase 2, one commit.
|
||||
|
||||
---
|
||||
|
||||
|
||||
## CMS-U9 built
|
||||
|
||||
**Timestamp**: 2026-11-10
|
||||
|
||||
**User Input**: Approval of plan CMS-U9 with the owner's answers (Friendly Captcha v2; missing token = spam 202; provider 401/sitekey_invalid = fail-open + error log; in-page widget) and the instruction to postpone the frame-src catalogue change until the owner decides (via SLP Software - SLS - Main).
|
||||
|
||||
**AI Response**: Verifier, config, start-up validation, ASF host reference and tests built; docs checked against the provider's v2 documentation; found that the v2 widget needs frame-src (reported, step 6 postponed, patch parked).
|
||||
|
||||
**Context**: Phase 2, one commit, nothing pushed.
|
||||
|
||||
---
|
||||
|
||||
+8
@@ -0,0 +1,8 @@
|
||||
# CMS-U9 — Friendly Captcha v2 and the ASF host (summary)
|
||||
|
||||
- `FriendlyCaptchaVerifier` (v2 siteverify, X-API-Key, fail-open rules, no secrets/tokens in logs), `ContactCaptchaOptions` (+ VerifyUrl, TimeoutSeconds, `Problems()`), start-up validation (`ContactOptionsValidator`, ValidateOnStart: the host refuses to start with an incomplete captcha setup), module wiring (`NullCaptchaVerifier` while off), token response only announces a complete setup, missing/empty `captchaToken` while on = spam (202).
|
||||
- OpenAPI: descriptions for token and submit operations regenerated.
|
||||
- ASF host: `ProjectReference` + `Contact` config section (off), rate-limit policies, release conditions in the file and in the handoff (section 8).
|
||||
- Tests (new): verifier (request shape, EU URL, all answers, timeout, network error, cancellation, empty token, no secrets in logs), options validation, submission rule, pipeline with a fake provider (token response shape, spam vs genuine identical 202, missing token, fail-open 500/503/401, label with `& ' " < >`, start-up refusal), mail label encoding, ASF host tests (closed by default, public routes reachable while the gate is closed, per-client vs shared bucket, committed defaults), frontend label test.
|
||||
- NOT included (instruction): the `frame-src` CSP catalogue change (`AllowedSiteFrameOrigins`), parked as a patch; see handoff section 8 for the provider's CSP requirement.
|
||||
- Deviation found against the plan: the v2 widget needs `frame-src` (iframes); the "no frame-src" assumption was wrong. Also `sitekey_invalid` is HTTP 400 (not 401/403).
|
||||
@@ -112,3 +112,34 @@ Rebased onto `origin/master` `e671078` (merge of PR #11: identity-email-notifica
|
||||
- Env var `Contact__RecipientEmail` (SLP: environment only, like ASF). Optional `Contact__Mail__SweepSeconds|MaxAttempts|ClaimMinutes|BatchSize`, `Contact__Mail__BackoffMinutes__0..n`.
|
||||
- Mail itself needs the host's normal `Email:*` configuration; without it messages stay `pending` with `mailError: "disabled"`.
|
||||
- Detail: `nextMailAttemptAt`; resend: `mailError`. New migration `ContactMailClaim`.
|
||||
|
||||
|
||||
## 8. CMS-U9 additions (Friendly Captcha v2 and the ASF host)
|
||||
|
||||
### Captcha contract (no wire change)
|
||||
- `GET /contact-messages/token` -> `captcha: null` while off, otherwise `{ "provider": "friendlycaptcha", "siteKey": "<public site key>" }`. Nothing else about the captcha (API key, verify URL) is ever returned.
|
||||
- `POST /contact-messages`: `captchaToken` = the widget's response string (the widget also puts it in the form field `frc-captcha-response`). While the captcha is on, a **missing, empty or rejected** value is treated as spam: answer `202 {"status":"received"}` identical to a genuine message, stored with status `spam` (never a 400, so a bot learns nothing). While the captcha is off the field is ignored.
|
||||
- Verify (server side, Friendly Captcha **v2**): `POST https://global.frcapi.com/api/v2/captcha/siteverify` (EU-only: `https://eu.frcapi.com/api/v2/captcha/siteverify`), header `X-API-Key: <API key>`, JSON `{ "response": "...", "sitekey": "..." }`; `success:true` passes, `success:false` (HTTP 200 `response_invalid|response_timeout|response_duplicate`, or 400 `response_missing|bad_request`) = spam. Checked against developer.friendlycaptcha.com on 2026-11-10.
|
||||
- **Fail-open**: timeout (default 3 s), network error and 5xx let the visitor through (warning `captcha_unavailable`, kind only). Our own wrong API key or site key (HTTP 401, or 400 with `error_code: sitekey_invalid`) also lets the visitor through but logs an **error** `captcha_misconfigured`. The response token, the API key and the site key are never logged.
|
||||
|
||||
### Configuration (per site)
|
||||
| Key | Notes |
|
||||
|---|---|
|
||||
| `Contact:Captcha:Enabled` | default `false` |
|
||||
| `Contact:Captcha:Provider` | `friendlycaptcha` (only supported value; case-insensitive) |
|
||||
| `Contact:Captcha:SiteKey` | public; sent to the browser |
|
||||
| `Contact__Captcha__Secret` | the API key; **environment variable / secrets manager only**, never committed |
|
||||
| `Contact:Captcha:VerifyUrl` | default global v2 URL; use the EU URL above for EU-only processing; must be https |
|
||||
| `Contact:Captcha:TimeoutSeconds` | default 3 (1-30) |
|
||||
|
||||
With `Contact:Enabled=true` and `Captcha:Enabled=true` the host **refuses to start** when provider, site key or secret is missing/invalid (the message names the setting only, never a value).
|
||||
|
||||
### Widget (website session) and CSP
|
||||
- Widget: Friendly Captcha v2 SDK with `sitekey` = `siteKey` from the token response; for the EU endpoint the widget needs `apiEndpoint: "eu"` (`data-api-endpoint="eu"`). The response goes into `captchaToken`. Exact SDK package/events: to be verified by the website session against the SDK docs.
|
||||
- **CSP**: the v2 widget renders in iframes. The provider's CSP guide says you need `frame-src https://*.frcapi.com` (global and EU). `StrictSite` currently has no `frame-src` (iframes fall back to `default-src 'self'` and are blocked). The additive catalogue change `SecurityHeaders:AllowedSiteFrameOrigins` (StrictSite only, absent = header byte-identical) is **prepared but NOT included in this unit**; waiting for the owner's decision on exact origins vs wildcard and on global vs EU. No `connect-src`/`script-src` additions are documented by the provider.
|
||||
- Privacy (provider statements, v2 docs): "Friendly Captcha does not rely on user tracking or cookies for its protection service"; the dedicated EU endpoint is "hosted in Germany" and "personal information (i.e. visitor IP addresses) never leave the EU". The site's privacy page must name the captcha provider and the processing of the visitor's IP address for the challenge.
|
||||
|
||||
### ASF host (`Api.AndreaSlopFotografie`)
|
||||
- References `Modules.Contact`; section `Contact` in its `appsettings.json` (`Enabled:false`, `SiteId: andreaslop`), the three contact rate-limit policies. Capabilities now list `Contact`; the module does nothing and touches no database while `Contact:Enabled=false`.
|
||||
- Release conditions (also in the comment of that section): `ForwardedHeaders__KnownProxies__0` = reverse proxy (IIS) address first (otherwise the whole site shares one bucket); `Contact__RecipientEmail` (env only); mail via `Email__Smtp__*`, `App__PublicBaseUrl`; sender = `Email:FromAddress` or the address chosen in the site settings from `Email:AllowedFromAddresses` (set by environment for ASF); captcha settings above; then `Contact__Enabled=true` and the admin switch (Berichten).
|
||||
- Host tests (`Api.AndreaSlopFotografie.Tests/ContactHostTests.cs`, real MariaDB): closed by default; public routes stay reachable (200/202) while the availability gate is "not available" and the management routes answer 503; per-client buckets with a known proxy vs one shared bucket without.
|
||||
|
||||
+10
-10
@@ -1,6 +1,6 @@
|
||||
# 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.
|
||||
Status: BUILT except step 6 (frame-src catalogue change, postponed on instruction). 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.
|
||||
@@ -15,18 +15,18 @@ Status: PLAN, waiting for approval by SLP Software - SLS - Main. Nothing built.
|
||||
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 `<b>x</b> & "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):
|
||||
- [x] **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).
|
||||
- [x] **Step 2 — Submission rule**: when enabled, an empty `captchaToken` = failed check (spam), without calling the provider.
|
||||
- [x] **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.
|
||||
- [x] **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).
|
||||
- [x] **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 `<b>x</b> & "q"`).
|
||||
- [ ] **Step 6 (POSTPONED on instruction until the frame-src decision; patch parked, not committed) — 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.
|
||||
- [x] **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=<IIS proxy ip>` 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.
|
||||
- [x] **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.
|
||||
- [x] **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).
|
||||
|
||||
Reference in New Issue
Block a user