AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

turnstile-spin

Set up, repair, or migrate to Cloudflare Turnstile bot verification in an existing frontend and backend, including server-side Siteverify.

Original source
cloudflare
License
Apache-2.0
Pinned revision
e44f580f9c4fa3bf268e284ae7706c7954ba31fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read cloudflare--turnstile-spin at revision e44f580f9c4fa3bf268e284ae7706c7954ba31fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 10

references/sveltekit.md

SvelteKit

For SvelteKit projects. The widget renders in the page; siteverify is called from a SvelteKit form action (or a +server.ts endpoint) server-side.

<script>
	import { enhance } from "$app/forms";
	import { onMount } from "svelte";

	let turnstileContainer;
	let signupWidgetId;

	onMount(() => {
		const render = () => {
			signupWidgetId = window.turnstile.render(turnstileContainer, {
				sitekey: "YOUR_SITEKEY",
				action: "signup",
			});
			delete window.onSignupTurnstileLoad;
		};

		if (window.turnstile) {
			render();
			return;
		}

		window.onSignupTurnstileLoad = render;
		const script = document.createElement("script");
		script.src =
			"https://challenges.cloudflare.com/turnstile/v0/api.js?onload=onSignupTurnstileLoad&render=explicit";
		script.async = true;
		document.head.appendChild(script);

		return () => {
			delete window.onSignupTurnstileLoad;
		};
	});
</script>

<form
	method="POST"
	use:enhance={() => {
		return async ({ result, update }) => {
			try {
				await update();
			} finally {
				if (result.type !== "redirect" && signupWidgetId !== undefined) {
					window.turnstile.reset(signupWidgetId);
				}
			}
		};
	}}
>
	<input name="email" type="email" required />
	<div bind:this={turnstileContainer}></div>
	<button type="submit">Sign up</button>
</form>

Form action (canonical siteverify):

import type { Actions } from "./$types";
import { fail } from "@sveltejs/kit";
import { TURNSTILE_SECRET, TURNSTILE_HOSTNAMES } from "$env/static/private";

const expectedHostnames = new Set(
	(TURNSTILE_HOSTNAMES ?? "")
		.split(",")
		.map((h) => h.trim())
		.filter(Boolean),
);

export const actions: Actions = {
	default: async ({ request, getClientAddress }) => {
		const data = await request.formData();
		const token = data.get("cf-turnstile-response");
		if (typeof token !== "string" || expectedHostnames.size === 0) {
			return fail(403, { error: "Verification failed" });
		}

		const verify = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", {
			method: "POST",
			headers: { "Content-Type": "application/x-www-form-urlencoded" },
			body: new URLSearchParams({
				secret: TURNSTILE_SECRET,
				response: token,
				remoteip: getClientAddress(),
			}),
		});
		const result = await verify.json();
		if (
			verify.ok !== true ||
			result.success !== true ||
			result.action !== "signup" ||
			!expectedHostnames.has(result.hostname)
		) {
			return fail(403, { error: "Verification failed" });
		}

		// process signup
		return { ok: true };
	},
};

signup is the stable action for this surface. Preserve an existing custom migration action and compare the returned action to the same value. Siteverify is mandatory for every widget mode, including pre-clearance. Set TURNSTILE_HOSTNAMES to the deployment-specific frontend hostnames; a production value must not include localhost or 127.0.0.1.

In .env:

TURNSTILE_SECRET=YOUR_SECRET

The $env/static/private import enforces that the secret never reaches the client bundle.

Variant: client-side fetch to an endpoint

If you need a JSON API rather than progressive-enhancement form post, use +server.ts:

import type { RequestHandler } from "./$types";
import { TURNSTILE_SECRET, TURNSTILE_HOSTNAMES } from "$env/static/private";

const expectedHostnames = new Set(
	(TURNSTILE_HOSTNAMES ?? "")
		.split(",")
		.map((h) => h.trim())
		.filter(Boolean),
);

export const POST: RequestHandler = async ({ request, getClientAddress }) => {
	const { token } = await request.json();
	if (expectedHostnames.size === 0) {
		return new Response("forbidden", { status: 403 });
	}
	const verify = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", {
		method: "POST",
		headers: { "Content-Type": "application/x-www-form-urlencoded" },
		body: new URLSearchParams({
			secret: TURNSTILE_SECRET,
			response: token,
			remoteip: getClientAddress(),
		}),
	});
	const result = await verify.json();
	if (
		verify.ok !== true ||
		result.success !== true ||
		result.action !== "signup" ||
		!expectedHostnames.has(result.hostname)
	) {
		return new Response("forbidden", { status: 403 });
	}
	// process signup
	return new Response(JSON.stringify({ ok: true }), { status: 200 });
};

The explicit renderer above retains signupWidgetId. Reset it in finally when calling this endpoint so every completion path gets a fresh token:

<script>
	async function submit(e) {
		e.preventDefault();
		try {
			const token = new FormData(e.currentTarget).get("cf-turnstile-response");
			const res = await fetch("/api/signup", {
				method: "POST",
				body: JSON.stringify({ token }),
			});
			const result = await res.json();
			if (!res.ok || result.ok !== true) throw new Error("Submission failed");
			// proceed
		} catch {
			// surface error
		} finally {
			if (signupWidgetId !== undefined) {
				window.turnstile.reset(signupWidgetId);
			}
		}
	}
</script>

Substitutions

| Placeholder | Replace with | | ------------------- | -------------------------------------------------------------------- | | YOUR_SITEKEY | The widget site key from Step 8 | | YOUR_SECRET | The secret captured in Step 8. Stays in env, never inlined. |