SKILL.md · 24000
eset(widgetId)` after the request completes before allowing a retry. Each protected surface must retain and reset its own widget ID. The framework references show the appropriate lifecycle hook.
Migrating from another CAPTCHA
During the Step 6 codebase scan, also look for existing reCAPTCHA or hCaptcha. If found, switch Step 7 to a migration plan.
Detection signals:
- reCAPTCHA:
https://www.google.com/recaptcha/api.js,class="g-recaptcha",data-sitekey="6L...", backend POST to/recaptcha/api/siteverify - hCaptcha:
https://js.hcaptcha.com/1/api.js,class="h-captcha", backend POST tohttps://hcaptcha.com/siteverify
Substitution:
- Replace script tags with
https://challenges.cloudflare.com/turnstile/v0/api.js(async defer). - Replace
class="g-recaptcha"/class="h-captcha"divs withclass="cf-turnstile", updatedata-sitekeyto the new Turnstile sitekey, and set a meaningfuldata-actionfor the protected surface. - Token field changes from
g-recaptcha-responsetocf-turnstile-response. - Backend siteverify URL points at
https://challenges.cloudflare.com/turnstile/v0/siteverify. DropRECAPTCHA_SECRET/HCAPTCHA_SECRETenv vars; addTURNSTILE_SECRET.
Edge cases to surface to the user:
- reCAPTCHA v3 score thresholds. Turnstile has no score. Tell the user explicitly that migrated code will reject on
success === false. - reCAPTCHA Enterprise. Don't auto-migrate. Point at developers.cloudflare.com/turnstile/migration/recaptcha/.
- Custom
action=values. Preserve any valid custom action the user passed togrecaptcha.executeasdata-actionon the widget. Otherwise, use the stable action assigned in Step 7. In both cases, validate the returned action in the backend.
Edge cases
| Situation | Action |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Account enumeration is unavailable | Ask the user for the account ID and export CLOUDFLARE_ACCOUNT_ID, or obtain approval for canonical absolute WRANGLER_BIN and exact WRANGLER_VERSION. Do not install or run a project-local Wrangler. |
| Multiple Cloudflare accounts | scripts/auth-probe.sh returns all accounts; ask the user to choose, export CLOUDFLARE_ACCOUNT_ID |
| Cloudflare Pages project | Wire siteverify inside a Pages Function (or the equivalent for your framework). The Pages Plugin at developers.cloudflare.com/pages/functions/plugins/turnstile is a shortcut. |
| Cloudflare Workers backend | Use the canonical fetch idiom from Step 9 inside the Worker's request handler. fetch to challenges.cloudflare.com works the same way it does in Node. |
| EXPECTED_HOSTNAME mismatch | Update widget domains via PUT, not PATCH (PATCH returns 10405 Method not allowed): curl -X PUT .../widgets/$SITEKEY -d '{"name":"...","mode":"managed","domains":[...]}' |
| Token expired mid-flow | Stop, re-run scripts/auth-probe.sh, prompt for fresh credentials |
| Validation returns invalid-input-secret | The secret didn't reach the backend. Re-check TURNSTILE_SECRET in the customer's env / secret manager. If it's a Workers backend, run wrangler secret list to confirm the secret is bound to the right script. |
| Validation returns invalid-input-response | Expected for a dummy probe token; that means the secret IS valid. validate.sh treats this as success. |
Skill feedback
If the user reports that this skill gave incorrect or outdated guidance, or is missing information, read references/skill-feedback.md.