turnstile-spin: guide token reset after submit to fix V2 double-redemption

[juleslemee]

Context

The Spin V2 dashboard flow went to public production on 2026-07-14 (widget Set up with Spin button). The first 3 days of telemetry showed elevated timeout-or-duplicate failures on the canonical siteverify path:

	V2 (first 3 days)	V1 (same-elapsed baseline)
sv_ok / sv_fail	2,426 / 124	8,721 / 85
Failure rate	4.86%	0.97%
Double-redemption share of failures	99% (123/124)	Very small

Zero invalid-input-secret, one other_failure. Secret wiring is fine; the failure class is stale-token retries.

Root cause

cf-turnstile-response tokens are single-use. When siteverify returns success: false, the customer's error UI puts the form back with the same DOM-cached token; a naive retry submits it and the edge rejects the second attempt as timeout-or-duplicate.

The V1 skill flow deployed a managed Worker that owned the whole request path, including client-side widget lifecycle. When V2 pivoted to canonical siteverify inside the customer's own backend, the client-side reset guidance was dropped in the simplification. Grep for reset, single-use, timeout-or-duplicate, data-error-callback across SKILL.md + all six framework references before this PR: zero hits.

The needle-mover here shipped on the server side: siteverify release 2026.7.3 (tagged 2026-07-20) cut V2's error rate from 16.4% at Sunday's traffic peak to 2.35% today on 51K events. V1 is running at 4.5% today over the same window, so V2 is now comfortably below V1.

This PR's client-side changes remain worth landing as hygiene: without them, agent-generated customer code keeps producing the redundant-siteverify pattern that 2026.7.3 has to absorb server-side. With them, agents emit the correct client-side contract from the start.

Fix

Client-side reset guidance in three places:

1. The canonical HTML snippet in SKILL.md (The frontend-edit contract section) gets an id="cf-form" and a setTimeout(() => window.turnstile?.reset(), 0) submit listener.
2. A new Token lifecycle paragraph explains the single-use contract and points at the per-framework hooks.
3. Each of the six framework references (vanilla-html, nextjs-app, nextjs-pages, sveltekit, astro, hugo) adds the framework-idiomatic reset call — submit listener for native forms, else branch of handleSubmit for AJAX, use:enhance callback for SvelteKit form actions, useActionState useEffect for Next.js Server Actions.

The reset-on-submit pattern (as opposed to data-error-callback wiring) was chosen because it's the smallest diff, framework-agnostic, and requires no callback wiring. The trade-off is one extra Turnstile challenge on successful in-page-retry submits (which is fine — Turnstile challenges are free and typically invisible).

Helper-script hardening

skills/turnstile-spin/scripts/ also picks up a robustness pass in response to the docs-bot's first review on the docs mirror. Findings addressed: 1 critical + 15 warnings + 1 suggestion.

• widget-create.sh: build request body and success/error output via python3 json.dumps (the original curl -d "{\"name\":\"$NAME\",...}" broke on names containing quotes, backslashes, or control characters). Argument-value validation before every shift 2. Drop 2>/dev/null on the API curl so network errors reach stderr. URL-encode account_id.
• validate.sh: switch to mktemp + -o $tmp + -w %{http_code} pattern; explicit HTTP status check before parsing; structured Python error handling for JSON parse failures. URL-encode account_id and sitekey.
• auth-probe.sh: command -v wrangler guard before invocation (avoids npx install-prompt hang in non-interactive envs) with fallback to $CLOUDFLARE_ACCOUNT_ID. Replace GET-based scope probe with POST-invalid-payload probe so it tests Turnstile:Edit specifically (a GET would authorize a Read-only token and let the agent proceed to widget-create.sh before failing).
• fetch-secret.sh: argument validation, mktemp with explicit template + trap-based cleanup, Python fallbacks use .get() with structured error output, URL encoding.
• persist-skill.sh: build the scripts JSON list via python3 os.listdir + json.dumps (replaces ls | sed | paste which mishandled filenames with quotes, backslashes, or newlines).

All 5 scripts pass bash -n and end-to-end smoke tests.

Companion PRs

The three surfaces of the Spin skill must stay in lockstep (canonical SKILL.md, docs prompt.md, dashboard-inlined spinSkillContent.ts):

• [Turnstile] Spin V2 post-launch tidy-up: prompt.md hotfix + docs backlog cloudflare-docs#32147 — spin-docs-followup branch, syncs prompt.md and the 5 helper scripts
• cloudflare/fe/stratus MR !40817 — inlines the same 5 scripts into spinSkillContent.ts

Rollout

Draft opened Friday 2026-07-17. With siteverify 2026.7.3 already shipping the server-side fix on Monday and V2 running comfortably below V1 (2.35% vs 4.5% today), this PR can land at normal review speed as product-hygiene rather than a hotfix. Grafana dashboard dfscir1b3r4sgc is the launch monitor.

Follow-up

The three-surface manual sync is manual by design (see the header comment at the top of spinSkillContent.ts in stratus). NC-8619 tracks adding runtime-fetch-with-fallback in stratus so the dashboard picks up prompt.md changes without a stratus MR.

[juleslemee]

cc @marinaelmore — this is the canonical-skill half of the Spin V2 token-reset hotfix. Companion PRs where you're already auto-added as reviewer:

• Docs: [Turnstile] Spin V2 post-launch tidy-up: prompt.md hotfix + docs backlog cloudflare-docs#32147
• Dashboard: https://gitlab.cfdata.org/cloudflare/fe/stratus/-/merge_requests/40817

Ready for review; hoping to merge Monday AM.

[juleslemee]

@marinaelmore GitHub won't let me add you as a formal reviewer here (fork PR, non-codeowner restriction), but you can submit an approve directly from the Files tab without being requested. This PR is the canonical skills half of the same three-repo Turnstile Spin V2 change you're already reviewing in cloudflare/cloudflare-docs#32147.