turnstile-spin

Files (14)

• README.md
• SKILL.md
• astro.md · references/
• hugo.md · references/
• nextjs-app.md · references/
• nextjs-pages.md · references/
• sveltekit.md · references/
• vanilla-html.md · references/
• auth-probe.sh · scripts/
• persist-skill.sh · scripts/
• validate.sh · scripts/
• widget-create.sh · scripts/
• test_persist_skill.py · tests/
• validation.md · tests/

SKILL.md (first lines)

# Turnstile Spin skill

Turns the prompt "set up Turnstile" into a working end-to-end integration: a widget, frontend snippets at every chosen insertion point, canonical server-side siteverify in the customer's existing backend, and a real validation pass before reporting success.

You are the agent. Run the wizard below by invoking the scripts under `scripts/` and branching on their JSON output. The scripts hold the deterministic logic (API calls, retry/error handling); your job is orchestration, codebase reading, confirmation, and the frontend + backend edits.

This file is the canonical machine-readable behavior. Product requirements come from the [Turnstile documentation](https://developers.cloudflare.com/turnstile/index.md), and the hosted prompt must mirror this behavior.

## Framework references

Read the reference for the existing frontend when wiring the integration:

| Frontend | Reference |
|---|---|
| Vanilla HTML | [vanilla-html](references/vanilla-html.md) |
| Next.js App Router | [nextjs-app](references/nextjs-app.md) |
| Next.js Pages Router | [nextjs-pages](references/nextjs-pages.md) |
| Astro | [astro](references/astro.md) |
| SvelteKit | [sveltekit](references/sveltekit.md) |
| Hugo | [hugo](references/hugo.md) |

## When to load this skill

Load when the user's prompt mentions any of:

- "Turnstile", "CAPTCHA", "bot protection"
- "siteverify", "cf-turnstile-response"
- "protect this form", "protect this endpoint", "protect this button", "stop bot signups", "spam signups", "block bots on <target>"
- A specific signup, login, contact form, download, comment, API endpoint, or other user-triggered request combined with "Cloudflare" or "bot"

Do not load for unrelated Cloudflare tasks (Workers, Pages, R2, etc.) unless Turnstile is also mentioned.

## Choose the flow before responding

Inspect the user's prompt before starting the numbered wizard. If it says the widget is already created and provides one or more sitekeys, go directly to the existing-widget flow below. Do not run, summarize, or propose the widget-creation flow. Otherwise, use the numbered creation wizard.

## Conversation flow

The user pasted the prompt. You are in a multi-step dialog. Detect what you can, ask only when you have to, confirm before every irreversible step. Each numbered moment is one agent message. Items marked **[wait for user]** require a user response.

1. **Brief acknowledge.** One sentence: "I'll run Turnstile setup end to end. That's: check auth, scan the codebase, create the widget, embed it where visitor requests need verification, wire server-side siteverify, validate. Proceed?" **[wait for user]** Do NOT present a plan yet. Auth + scan come first.

2. **CLI check.** Spin's helper scripts use `curl` against `api.cloudflare.com`. Account enumeration requires either an explicit `$CLOUDFLARE_ACCOUNT_ID` or a user-approved canonical absolute `WRANGLER_BIN` outside the project with exact `WRANGLER_VERSION`. Never use `npx`, `pnpm exec`, a package script, a project-local binary, or an unapproved executable for a credential-bearing command. Never install Wrangler automatically during the flow.

3. **Auth + scope probe (FIRST irreversible action).** Run `scripts/auth-probe.sh`. If account enumeration needs Wrangler, set `PROJECT_ROOT`, approved canonical `WRANGLER_BIN`, and exact `WRANGLER_VERSION` first. Branch on `status`:
   - `ok`: continue to Step 4. The script already picked the account (single-account token, or one matching `$CLOUDFLARE_ACCOUNT_ID`).
   - `missing_token` or `missing_scope`: ask the user to create a token at https://dash.cloudflare.com/profile/api-tokens → Custom token → permission `Account.Turnstile:Edit` → include the target account in Account Resources. **Do NOT direct them to `wrangler login`** unless wrangler's OAuth scope includes `Account.Turnstile:Edit` (varies by wrangler version). Offer two ways to provide the token without chat, cleanest first:
     1. **Export + relaunch** (token enters neither chat nor shell history): `read -rsp 'Cloudflare API token: ' token; echo; export CLOUDFLARE_API_TOKEN="$token"; unset token`, then restart the agent from that terminal.
     2. **Save to file** (token in a user-only file): `umask 077; read -rsp 'Cloudflare API token: ' token; echo; printf '%s' "$token" > ~/.cf-turnstile-token; unset token`, then load it without printing it.
     Do not ask the user to paste the API token into chat. When auth is established, re-run `auth-probe.sh` and resume from Step 4.
   - `network_failure`: the probe could not reach `api.cloudflare.com`. Show the diagnostic (VPN/proxy, TLS interception, DNS). Do not treat this as a scope problem. Ask the user to fix connectivity, then re-run `auth-probe.sh`.
   - `upstream_failure`: the API returned an unexpected response (`http_code` non-4xx). Do not assume the token is bad. Show the code, ask the user to retry after a brief wait, and re-run `auth-probe.sh`.
   - `multiple_accounts`: the token covers more than one account and `$CLOUDFLARE_ACCOUNT_ID` is unset. Present the numbered `accounts` list. **[wait for user]** Then export `CLOUDFLARE_ACCOUNT_ID=<chosen>` and re-run `auth-probe.sh`.
   - `account_mismatch`: `$CLOUDFLARE_ACCOUNT_ID` is set but isn't one of the token's accounts. Show the `accounts` list and ask the user to either `unset CLOUDFLARE_ACCOUNT_ID` or set it to one of those IDs.

4. **Account selection.** If `auth-probe.sh` returned `ok` after a `multiple_accounts` round-trip, this is already done. Otherwise the script picked the single account silently and you continue to Step 5.

5. **Domain.** Always include `localhost` and `127.0.0.1`. For production, scan `package.json` `homepage`, `wrangler.toml`, `README.md`, `AGENTS.md`, git remote. Confirm: "I'll register for `localhost`, `127.0.0.1`, and `<domain>`. OK?" **[wait for user]** If no production domain is found, ask. Registering local and production domains on one widget is safe only when each backend deployment validates the exact frontend hostname returned by siteverify. Never include `localhost` or `127.0.0.1` in a production backend's expected-hostname allowlist.

6. **Codebase scan.** Detect three things silently:
   - **Frontend framework** (Next.js, Astro, SvelteKit, Hugo, vanilla, etc.) → drives the widget embed snippet.
   - **Backend handler location** (Express route, Next.js API route, Rails controller, Workers fetch handler, Pages Function, etc.) → drives the siteverify snippet.
   - **Existing CAPTCHA** (reCAPTCHA / hCaptcha) → switches Step 7 to migration mode.

7. **Insertion plan.** Show the candidate list with `[recommended]` / `[skip by default]` markers; ask the user to confirm (numbers, "all", "recommended", or a list). Assign each chosen surface a stable action such as `signup`, `login`, or `contact`. Actions must be 1–32 characters and contain only letters, numbers, underscores, or hyphens. Show the action-to-handler mapping for confirmation. **[wait for user]** If an existing CAPTCHA was detected, present a migration plan instead (see "Migrating from another CAPTCHA").

8. **Widget creation.** Prefer the approved Wrangler executable when its `turnstile widget` subcommand is available:

   ```sh
   WRANGLER_WRITE_LOGS=false WRANGLER_LOG=log WRANGLER_LOG_SANITIZE=true \
     "$WRANGLER_BIN" turnstile widget create "<name>" \
     --domain <d1> --domain <d2> ... --mode managed --json
   ```

   In a `set +x` subshell, capture the complete stdout JSON in one shell variable. Parse `SITEKEY` and a non-empty, non-whitespace `WIDGET_SECRET` with `jq`, then unset the response variable. If the approved Wrangler executable is missing or older than the Turnstile subcommand, use the same capture pattern with `scripts/widget-create.sh --account-id <id> --name <name> --domains <list> --mode managed`. Do not fall back after an authentication or API failure. Report only the sitekey. Never print the complete response or write the secret to disk except into the user's own secret store in Step 9.

9. **Wire the integration.** State the contract: "I'll embed the widget at each chosen surface and add a canonical siteverify call inside its existing handler. The handler will require `success === true`, the expected action, and an approved frontend hostname. The existing handler logic stays the same. The secret lives in your env as `TURNSTILE_SECRET`." Ask "yes" / "show". **[wait for user]** If "show", print unified diffs and ask again. Do NOT propose alternate behavior (mail delivery, custom backends).

   Canonical server-side siteverify (Node / fetch idiom; adapt to the detected backend):

   ```js
   const expectedAction = 'signup';
   const expectedHostnames = new Set(
     (process.env.TURNSTILE_HOSTNAMES ?? '')
       .split(',')
       .map((hostname) => hostname.trim())
       .filter(Boolean),
   );

   if (typeof token !== 'string' || token.length === 0 || token.length > 2048 || expectedHostnames.size === 0) {
     return res.status(403).send('forbidden');
   }

   let result;
   try {
     const r = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
       method: 'POST',
       headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
       signal: AbortSignal.timeout(10_000),
       body: new URLSearchParams({
         secret: process.env.TURNSTILE_SECRET,
         response: token,         // cf-turnstile-response from the request
         remoteip: clientIp,      // X-Forwarded-For / req.ip / etc.
       }),
     });
     if (!r.ok) throw new Error(`siteverify ${r.status}`);
     result = await r.json();
   } catch (err) {
     // Network error, non-2xx, or non-JSON body from siteverify. Fail closed.
     return res.status(403).send('forbidden');  // adapt to your framework
   }
   if (
     !result.success ||
     result.action !== expectedAction ||
     !expectedHostnames.has(result.hostname)
   ) {
     return res.status(403).send('forbidden');
   }
   // existing handler logic runs here, unchanged

From cloudflare/skills, Apache-2.0.

More from cloudflare/skills