Files
slp-modular-cms/aidlc-docs/features/contact-forms-module/construction/plans/cms-u9-friendly-captcha-and-asf-host-code-generation-plan.md
T

8.7 KiB

Code Generation Plan — CMS-U9 friendly-captcha-and-asf-host

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.
  • 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": <captchaToken>, "sitekey": <siteKey> }, header X-API-Key: <secret>; 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 <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.
  • 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.

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?