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:
+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