8.7 KiB
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)
ICaptchaVerifierseam withNullCaptchaVerifier(always true);ContactSubmissionServicecalls it only whenContact:Captcha:Enabled; afalseanswer is classified as spam: 202 + status spam, identical to today.- Token response already has
captcha: null | { provider, siteKey }(fromContact:Captcha:Provider|SiteKey); request already has optionalcaptchaToken. 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
- Friendly Captcha version: v2 (recommended). Server verify:
POST https://global.frcapi.com/api/v2/captcha/siteverify(EU-only alternative hosteu.frcapi.com), JSON{ "response": <captchaToken>, "sitekey": <siteKey> }, headerX-API-Key: <secret>; resultsuccess: true|false. Endpoint host is configurable (Contact:Captcha:VerifyUrl, default global v2). v1 (api.friendlycaptcha.com/api/v1/siteverify, formsolution+secret, EU hosteu-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. - 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 ascaptchaToken. The widget loads its worker/script from the app bundle (or a script URL) and talks to the provider API at runtime. - 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 errorcaptcha_misconfiguredso it is noticed; the token response never leaks it. - Config per site, secret only via environment:
Contact:Captcha:Enabled|Provider (friendlycaptcha)|SiteKey|VerifyUrl|TimeoutSeconds, secretContact__Captcha__Secret(env only, never in committed config; startup refusesEnabled=true+Provider=friendlycaptchawith an empty secret or sitekey, logging names only). Unknown provider => startup validation failure. - 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 : ICaptchaVerifierusingIHttpClientFactory(named client, timeout from options), returns true/false per the rules above;CaptchaProviderOptionsValidator; provider selection inContactModule(NullCaptchaVerifierstays 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
captchawhen 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 responsecaptchashape; 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(andhttps://eu.frcapi.comwhen the EU host is used),frame-srcis not needed for the v2 default widget (it runs in-page); if the widget is configured in iframe mode addframe-src https://global.frcapi.com;script-srcadditions only if the SDK is loaded from a CDN instead of the site bundle (avoid: bundle it). Delivered as:SecurityHeaders:AllowedSiteConnectOriginsentries (already supported by the catalogue) plus documented values; no catalogue code change is needed for connect-src, and I add aframe-srcextension 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):ProjectReferencetoModules.Contact+ module registration inApi.AndreaSlopFotografie; per-siteContact: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 whenContact: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: withForwardedHeaders:KnownProxiesset, 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>beforeContact__Enabled=true;Contact__RecipientEmailenv only; From:Email:FromAddressis the site address; contact mail usesGetEffectiveSenderAsync, so it followsEmail: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,
captchaTokenrule, spam behaviour, fail-open, CSP values, privacy note), handoff section 8 (keys + env var names), OpenAPI regenerated (description ofcaptchaToken/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)
- ASF csproj/registration: to build in U9 (step 7).
- KnownProxies empty ⇒ one shared bucket behind IIS: to build in U9: host test + documented release condition (
ForwardedHeaders__KnownProxies__0);ClientPartitionKeyalready used by the contact limiter (present). - 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).
- CSP: U9 proposal (step 6; connect-src only via the existing
AllowedSiteConnectOrigins, nothing applied to ASF by me). - Gate:
[PublicSiteEndpoint]onGET /contact-messages/tokenandPOST /contact-messagesis 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. - 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
- Friendly Captcha v2 (recommended) — OK?
- Missing
captchaTokenwhile captcha is on = spam (202), not 400 — OK? - Misconfigured provider (401/403 from verify) = fail-open + error log — OK, or fail-closed (everything becomes spam) instead?
- Widget mode: in-page SDK (no
frame-src) — OK?