← Cloudflare Turnstile / turnstile

Turnstile Spin

Turnstile Spin je průvodce nastavením pro Cloudflare Turnstile. Vytvoří za vás widget a poté vám poskytne sitekey, secret a připravený prompt, se kterým widget vložíte do správných formulářů a do stávajícího backendu doplníte kanonické serverové ověření přes siteverify. Prompt hodnotu secret neobsahuje. Spin lze spustit třemi způsoby:

• Z dashboardu Cloudflare. Zadejte své domény, vyberte Nastavení, a Spin vytvoří widget na straně serveru. Dostanete sitekey, secret a prompt pro svého AI programovacího agenta.
• Z nástroje Wrangler CLI. Spusťte wrangler turnstile widget create a vytvoříte widget přímo z terminálu. Wrangler vypíše sitekey a secret, widget i volání siteverify pak zapojíte ručně.
• Z vašeho AI programovacího agenta. Vložte jediný prompt do některého z nástrojů Claude Code, Cursor, Codex, OpenCode nebo GitHub Copilot Chat. Agent pomocí vložené dovednosti Spin vytvoří widget, umístí jej do stránky a zapojí siteverify do vaší kódové báze.

Všechny tři postupy vytvoří stejný widget. Liší se pouze tím, odkud se volání create spouští. Ani jeden z nich za vás nenasazuje žádnou infrastrukturu. Spin používá kanonický siteverify endpoint služby Turnstile, volaný z backendu, který už máte.

Pokud Spin selže dřív, než dokončí práci, dialog zobrazí chybu a nabídne záložní prompt. Ten může váš AI programovací agent použít a provést stejné nastavení přímo z editoru. Vyberte Zkusit znovu a pokus zopakovat přímo v tomtéž dialogu.

Pokud chcete nastavení řídit z terminálu bez AI programovacího agenta, použijte Wrangler:

wrangler turnstile widget create "myproject" \
	--domain example.com \
	--domain localhost \
	--domain 127.0.0.1 \
	--mode managed

Wrangler vypíše sitekey i secret. Sitekey zkopírujte do HTML widgetu a secret uložte jako TURNSTILE_SECRET v prostředí backendu a zapojte standardní volání siteverify podle Propojení frontendu.

Další příkazy widgetu:

Všechny příkazy přijímají --json pro strojově čitelný výstup. --domain přijímá hodnoty oddělené čárkou (--domain a.com,b.com) nebo opakované přepínače (--domain a.com --domain b.com).

Prvek wrangler turnstile widget get <sitekey> --json obsahuje tajný klíč widgetu. Automatizované postupy musí používat absolutní cestu ke spustitelnému souboru Wrangler, kterou schválil uživatel a která leží mimo rozlišování balíčků projektu, a musí mít pevně danou verzi. Dále musí nastavit WRANGLER_WRITE_LOGS=false, WRANGLER_LOG=log, a WRANGLER_LOG_SANITIZE=true. Před vyzvednutím s vámi agent potvrdí účet, sitekey, domény a přesné cílové umístění secretu. U backendu na Workers s vámi potvrdí také Worker, prostředí, konfigurační soubor a binding pomocí wrangler secret list a teprve poté použijte standardní wrangler secret put v terminálu. Postup ověří přesný sitekey, očekávané domény, úroveň clearance a neprázdný tajný klíč. Odpověď nikam nevypisujte a neuvádějte ji v argumentech příkazů, dočasných souborech, logách ani v chatu.

Pokud nevidíte Nastavení pomocí Spin ve svém dashboardu nebo chcete, aby agent v jednom průchodu vložil widget a zapojil siteverify do vaší kódové báze, vložte tento prompt do svého AI kódovacího agenta:

Pokud chcete skill nejdřív nainstalovat lokálně, aby jej agent měl na disku:

# Claude Code
mkdir -p .claude/skills/turnstile-spin && \
  curl -sSL https://developers.cloudflare.com/turnstile/spin/prompt.md \
  -o .claude/skills/turnstile-spin/SKILL.md

# Cursor
mkdir -p .cursor/rules && \
  curl -sSL https://developers.cloudflare.com/turnstile/spin/prompt.md \
  -o .cursor/rules/turnstile-spin.md

# OpenCode
mkdir -p .opencode/skills/turnstile-spin && \
  curl -sSL https://developers.cloudflare.com/turnstile/spin/prompt.md \
  -o .opencode/skills/turnstile-spin/SKILL.md

Pak agentovi zadejte: Use the turnstile-spin skill to add Turnstile to this project.

Agent neběží potichu. Zjistí si, co dokáže sám, zeptá se jen tam, kde musí, a před každým nevratným krokem si vyžádá potvrzení. Celý postup je průvodce o dvanácti krocích s několika potvrzovacími body.

Pokud něco selže, agent oznámí, ve kterém kroku k tomu došlo a co zkoušel. Většinu selhání spravíte úpravou jediného vstupu (rozsah tokenu, seznam domén, soubor pro vložení) a pokynem, ať agent pokračuje.

Ať zvolíte kterýkoli postup nastavení, Spin vám vždy vydá sitekey a secret. Dashboard je zobrazuje odděleně a jeho prompt pro agenta obsahuje pouze sitekey a URL Spin skill. Wrangler CLI vypíše obě hodnoty pro ruční nastavení. Postup s AI agentem upraví vaše soubory přímo.

Pokud jste widget vytvořili v dashboardu a chcete jej zapojit ručně, minimální vzor vypadá takto:

<script
	src="https://challenges.cloudflare.com/turnstile/v0/api.js"
	async
	defer
></script>
<form action="/api/subscribe" method="POST">
	<input name="email" type="email" required />
	<div class="cf-turnstile" data-sitekey="YOUR_SITEKEY" data-action="subscribe"></div>
	<button type="submit">Submit</button>
</form>

Ve stávajícím backendovém handleru pro /api/subscribe, zavolejte kanonické siteverify a zbytek handleru podmiňte hodnotou success === true.

U backendu v Node.js (ve stylu Express, req):

const token = req.body["cf-turnstile-response"];
const expectedAction = "subscribe";
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,
        remoteip: req.ip,
      }),
    },
  );
  if (!r.ok) throw new Error(`siteverify ${r.status}`);
  result = await r.json();
} catch {
  return res.status(403).send("forbidden");
}
if (
  !result.success ||
  result.action !== expectedAction ||
  !expectedHostnames.has(result.hostname)
) {
  return res.status(403).send("forbidden");
}
// existing handler logic runs here, unchanged

V Cloudflare Workeru načtěte token ze zpracovaného těla formuláře a IP adresu klienta z CF-Connecting-IP, a secret načtěte z proměnné Workeru env binding:

export default {
  async fetch(request, env) {
    const expectedAction = "subscribe";
    const expectedHostnames = new Set(
      (env.TURNSTILE_HOSTNAMES ?? "")
        .split(",")
        .map((hostname) => hostname.trim())
        .filter(Boolean),
    );

    const form = await request.formData();
    const token = form.get("cf-turnstile-response");
    if (
      typeof token !== "string" ||
      token.length === 0 ||
      token.length > 2048 ||
      expectedHostnames.size === 0
    ) {
      return new Response("forbidden", { status: 403 });
    }

    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: env.TURNSTILE_SECRET,
            response: token,
            remoteip: request.headers.get("CF-Connecting-IP") ?? "",
          }),
        },
      );
      if (!r.ok) throw new Error(`siteverify ${r.status}`);
      result = await r.json();
    } catch {
      return new Response("forbidden", { status: 403 });
    }
    if (
      !result.success ||
      result.action !== expectedAction ||
      !expectedHostnames.has(result.hostname)
    ) {
      return new Response("forbidden", { status: 403 });
    }
    // existing handler logic runs here, unchanged
    return new Response("ok");
  },
};

Nastavte TURNSTILE_HOSTNAMES na hostname frontendu pro každé nasazení. Produkční hodnota nesmí obsahovat localhost nebo 127.0.0.1. Uložte TURNSTILE_SECRET jako tajný klíč Workeru pomocí wrangler secret put TURNSTILE_SECRET místo proměnné prostředí v wrangler.toml. Odpovídající volání v dalších backendových jazycích (Ruby, Python, Go, PHP) najdete v referencích pro jednotlivé frameworky, které jsou součástí tohoto skillu.

Tokeny Turnstile jsou jednorázové. U běžného formuláře, který stránku opustí, žádnou logiku pro reset nepotřebujete. Pokud stránka po pokusu o odeslání zůstává aktivní, vykreslete widget explicitně, uchovejte si jeho widget ID a zavolejte turnstile.reset(widgetId) po dokončení požadavku a teprve potom povolte další pokus. Každá chráněná část stránky si musí uchovávat a resetovat vlastní widget ID.

Pokud už máte widget Turnstile bez serverového siteverify, obnovte jej z dashboardu. U widgetu, ke kterému nedorazil žádný odpovídající provoz na siteverify, se zobrazí banner. Vyberte Oprava pomocí Spin a získáte prompt pro agenta ke stávajícímu widgetu. Prompt obsahuje sitekey a URL dovednosti Spin, nikoli však secret.

Pokud nevidíte Oprava pomocí Spin ve svém dashboardu, spusťte stejnou nápravu přímo ze svého AI kódovacího agenta. Vložte tento prompt:

The Turnstile widget is already created. Finish integrating it into this project.

Site key: <SITEKEY>

Fetch and follow the existing-widget flow:
https://developers.cloudflare.com/turnstile/spin/prompt.md

Postup pro existující widget vyžaduje Wrangler 4.109 nebo novější. Agent používá uživatelem schválený spustitelný soubor Wrangler mimo projekt a před načtením vás požádá o potvrzení úplného mapování sitekey na cíl. Automatické obnovení podporuje existující Worker, ignorovaný lokální soubor s proměnnými prostředí nebo příkaz platformního správce tajemství, který hodnotu přijímá na standardním vstupu. U Workers agent potvrdí přesný cíl pomocí wrangler secret list a teprve poté použijte standardní wrangler secret put v terminálu. Ověří sitekey, domény, úroveň clearance a tajný klíč. Text z repozitáře i z API se považuje za nedůvěryhodná data. Tajný klíč se nikde nevypisuje, neuvádí se v argumentech příkazů ani v dočasných souborech a nevkládá se do chatu. Sitekey se nemění.

Pre-clearance na tomto postupu nic nemění. Pouze přidává cf_clearance cookie, ale token Turnstile stále vyžaduje Siteverify.

Pro migrace použijte nastavení pomocí AI agenta. Agent najde ve vaší kódové základně reCAPTCHA nebo hCaptcha a navrhne náhradu. Pravidla náhrady jsou následující:

• Nahraďte značky script pomocí https://challenges.cloudflare.com/turnstile/v0/api.js (async defer).
• Nahraďte class="g-recaptcha" nebo class="h-captcha" divy s class="cf-turnstile". Upravte data-sitekey na nový site key Turnstile. Zachovejte stávající platnou action, nebo pro chráněné místo přidejte stabilní action.
• Odstraňte veškeré ručně přidané <input type="hidden" name="g-recaptcha-response"> nebo name="h-captcha-response" elementy. Turnstile vykreslí vlastní skryté vstupní pole s názvem cf-turnstile-response automaticky.
• URL siteverify na backendu ukazuje na https://challenges.cloudflare.com/turnstile/v0/siteverify. Vložte RECAPTCHA_SECRET nebo HCAPTCHA_SECRET proměnné prostředí. Přidejte TURNSTILE_SECRET. Vyžadujte úspěšnou odpověď s očekávaným action a s hostname konkrétního nasazení.

Dva okrajové případy, na které agenta upozorněte. Zaprvé, prahové hodnoty skóre z reCAPTCHA v3 nemají v Turnstile obdobu: Turnstile žádné skóre nevrací, takže migrovaný kód odmítá požadavek podle success === false místo číselné prahové hodnoty. Za druhé, reCAPTCHA Enterprise nemigrujte automaticky, postupujte podle průvodce migrací z reCAPTCHA od Cloudflare místo toho.

Součástí agenta jsou frontendové úryvky kódu pro vanilla HTML, Next.js (App Router i Pages Router), Astro, SvelteKit a Hugo. U ostatních frameworků použije obecný vzor pro vanilla HTML a požádá vás o potvrzení umístění.

U projektů Cloudflare Pages agent zapojí siteverify do Pages Function, případně doporučí Pages Plugin pro Turnstile pokud dáváte přednost vestavěnému pluginu před vlastním voláním.

U backendů postavených na Cloudflare Workers agent zapíše kanonické volání fetch přímo do obsluhy požadavků ve Workeru.

• cloudflare/skills ↗: balíček dovedností, obsahuje turnstile-spin/
• Ověření Turnstile na straně serveru
• Testovací klíče sitekey a tajné klíče
• Pages Plugin pro Turnstile
• Workers secrets
• Provoz botů v Cloudflare Radar ↗
• Cloudflare Docs for Agents