[houko]

What & why

Was: Survey spam protection worked only with Google reCAPTCHA; Turnstile keys protected sign-up and nothing else.

Now: When TURNSTILE_SITE_KEY and TURNSTILE_SECRET_KEY are set, Turnstile is the spam protection of public surveys (link pages and the web SDK widget); an instance with only reCAPTCHA keys keeps reCAPTCHA.

• The runtime renders an interaction-only Turnstile widget once per survey, in the survey's language, and sends its token as the new optional turnstileToken on the first response create. Updates need no token.
• Each create attempt takes a token of its own: the response queue asks the widget for a token on every create, including a retry after a 500/503 and a stored create sent after a reload, and the widget hands each token out once and resets for the next. A token the server may already have spent is never sent again.
• A Turnstile error that Cloudflare retries on its own (300xxx, 600xxx, challenge timeouts) keeps the submit waiting up to 20 s for the retry; configuration errors (110xxx) and unsupported browsers fail at once.
• The server verifies it with the shared verifier (now internal/platform/turnstile), passing the trusted client IP and the expected action (submit_response for responses, sign_up for sign-up, which the sign-up widget now names), so a token minted by one form is refused by the other. A token without an action (Cloudflare's test keys, a page rendered before this change) is still taken. A refused or missing token is a 400 with the existing recaptcha_verification_failed code; Cloudflare not answering is a 503 spam_protection_unavailable, never an accept.
• While both key pairs are configured, a create that carries no turnstileToken but a recaptchaToken is checked by reCAPTCHA against the survey's threshold, so pages and SDK state cached from before the switch keep working.
• The surveys runtime advertises supportsTurnstile on window.formaSurveys (additive). js-core does not show a Turnstile-protected survey through a runtime without it (a stale edge-cached /js/surveys.umd.js), instead of showing it and refusing the first answer.
• The editor's switch names the provider in use; reCAPTCHA's score threshold shows only for reCAPTCHA. Survey page CSP allows challenges.cloudflare.com for the Turnstile provider; sign-up already did, and the e2e confirms it loads.

Where to look

• checkSpamProtection — provider choice, 400 vs 503
• Verifier.Verify — which siteverify answers count as "no verdict"
• TurnstileChallenge — token wait, expiry, failure

Breaking changes

• This PR contains breaking changes

Change	Before	After	Who's affected	Action required
Spam protection provider when both Turnstile and reCAPTCHA keys are set	reCAPTCHA	Turnstile; the environment state sends turnstileSiteKey instead of recaptchaSiteKey. reCAPTCHA tokens are still accepted while the reCAPTCHA keys stay set	Self-hosters with both key pairs and surveys with spam protection on	Add the sites that embed SDK surveys to the Turnstile widget's hostnames, or remove the Turnstile keys to stay on reCAPTCHA
SDK bundles /js/forma.umd.js and /js/surveys.umd.js		Unversioned and served with s-maxage=2592000: an edge copy from before this release does not know Turnstile	App surveys with spam protection on, once Turnstile keys are set	Purge both URLs from the Cloudflare edge cache when rolling this release out, and again when the Turnstile keys are first set. A stale forma.umd.js would show protected surveys without a token (the server refuses the first answer); a stale surveys.umd.js behind a fresh forma.umd.js is now caught by js-core, which skips the survey

Migrations & env

• No migration. TURNSTILE_SITE_KEY / TURNSTILE_SECRET_KEY now also turn on survey spam protection (.env.example, compose comments updated).
• forma.yldm.ai has neither key pair today, so this changes nothing there until the keys are added. When adding them: purge https://forma.yldm.ai/js/forma.umd.js and https://forma.yldm.ai/js/surveys.umd.js from the Cloudflare cache (purge by URL).

How this was tested

Rerun: cd apps/server && go test ./internal/platform/turnstile ./internal/clientapi ./internal/linksurvey ./internal/auth ./internal/platform/config and E2E_TURNSTILE=pass|fail vp exec playwright test turnstile.spec.ts (e2e.yml restarts the stack with Cloudflare's test keys)

Coverage

Behaviour	How	Outcome
Verify: valid, invalid, spent, missing, Cloudflare down, timeout, bad secret, another widget's action, no action	unit (guard) TestVerify*	Only success for the expected action (or none) accepts; outages return ErrUnavailable
A retried or later create never reuses a token; stored creates after a reload get one; no token keeps a stored answer	unit (red before the fix) turnstile.test.ts, response.queue.test.ts, survey.test.tsx	Each attempt sends a fresh token
A retryable Turnstile error waits for Turnstile's retry, bounded at 20 s	unit (red before the fix) turnstile.test.ts	Submit succeeds after the retry, fails after 20 s
Stale runtime without Turnstile support is not used for a protected survey	unit (red before the fix) widget.test.ts	Survey skipped, isSurveyRunning released
reCAPTCHA token during the switch; sign-up token on a response	unit TestCreateResponseTurnstile	200 via reCAPTCHA while its keys are set, else 400; sign-up token 400
Response create with Turnstile: missing/invalid 400, down 503, valid 200, update without token 200	unit TestCreateResponseTurnstile + 7 new contract exchanges	As listed; nothing written without an accepted token
Survey page CSP and page state name Turnstile only for its provider	unit (red on main) TestSurveyPagePolicyWithTurnstile, TestSurveyPageTurnstileSiteKey	Fail on main, pass here
Sign-up page loads Turnstile under its CSP; link survey on a phone sends the token	e2e turnstile.spec.ts (pass keys)	Token XXXX.DUMMY.TOKEN.XXXX sent, response stored, no CSP violations
SDK widget on a customer page renders Turnstile and sends the token	e2e turnstile.spec.ts (pass keys)	Response created with the token
Always-fail secret refuses the response and the respondent sees the spam error	e2e turnstile.spec.ts (fail secret)	400 recaptcha_verification_failed, error card shown

Open gaps

• Turnstile validates hostnames: SDK surveys on customer domains not in the widget's hostname list cannot be submitted (the editor note says so). reCAPTCHA had the same limit.
• Native mobile SDKs are not covered, as with reCAPTCHA.

Risks

• Every create attempt runs a fresh (usually invisible) Turnstile challenge after the first; a respondent may see an interactive challenge again on a retry.
• Turnstile keys set for sign-up only now also switch survey spam protection away from reCAPTCHA.

[github-actions]

🚨 PR Size Warning

This PR has approximately 1163 lines of changes (951 additions, 212 deletions across 48 files).

Large PRs (>800 lines) are significantly harder to review and increase the chance of merge conflicts. Consider splitting this into smaller, self-contained PRs.

💡 Suggestions:

• Split by feature or module - Break down into logical, independent pieces
• Create a sequence of PRs - Each building on the previous one
• Branch off PR branches - Don't wait for reviews to continue dependent work

📊 What was counted:

• ✅ Source files, stylesheets, configuration files
• ❌ Excluded 32 files (tests, locales, locks, generated files)

📚 Guidelines:

• Ideal: 300-500 lines per PR
• Warning: 500-800 lines
• Critical: 800+ lines ⚠️

If this large PR is unavoidable (e.g., migration, dependency update, major refactor), please explain in the PR description why it couldn't be split.