Turnstile

Turnstile nedir?

“Cloudflare’s smart CAPTCHA alternative.”

“Turnstile can be embedded into any website without sending traffic through Cloudflare and works without showing visitors a CAPTCHA.”

Klasik bir CAPTCHA insana soru soruyor: trafik ışıklarını seç, bozuk yazıyı oku. Turnstile tarayıcıya soru soruyor:

“First, we run a series of small non-interactive JavaScript challenges to gather signals about the visitor or browser environment.”

“These challenges include proof-of-work (computational puzzles), proof-of-space, probing for web APIs, and various other challenges for detecting browser-quirks and human behavior. As a result, we can fine-tune the difficulty of the challenge to the specific request and avoid showing a visual or interactive puzzle to a user.”

Ve veri işleme tarafında net bir sınır çiziliyor:

“Turnstile processes only the data strictly necessary to provide this security function. Turnstile does not access, store, or transmit user communications, form entries, or other page inputs.”

Nasıl çalışır?

Üç widget modu

Managed modun en kötü durumu tek bir onay kutusu — “Turnstile will only require interaction if a further check is necessary… the visitor will be prompted to select a box.” Görsel bulmaca hiç yok. reCAPTCHA veya hCaptcha’nın resim ızgaralarına kıyasla bu, erişilebilirlik açısından gerçek bir fark.

Widget hata durumları — sorun giderirken işine yarayacak:

İki anahtar ve zorunlu sunucu doğrulaması

Widget challenges.cloudflare.com üzerinden yükleniyor — CSP kullanıyorsan bu alan adına izin vermen gerekiyor.

Siteverify: POST https://challenges.cloudflare.com/turnstile/v0/siteverify

Hem application/x-www-form-urlencoded hem application/json kabul ediyor, her zaman JSON dönüyor.

Yanıt:

{
  "success": true,
  "challenge_ts": "2026-09-01T15:14:30.096Z",
  "hostname": "ornek.com.tr",
  "error-codes": [],
  "action": "giris",
  "cdata": "oturum-123456789",
  "metadata": { "ephemeral_id": "x:9f78e0ed210960d7693b167e" }
}

Hata kodları:

Idempotency: ağ hatası sonrası aynı token’ı yeniden doğrularken sahte bir timeout-or-duplicate almamak için bir UUID üretip tüm denemelerde aynısını gönderiyorsun. Cloudflare’in kendi örneği UUID’yi döngünün dışında üretiyor ve üstel geri çekilme kullanıyor. Anahtarın sunucu tarafında ne kadar saklandığı belgelenmemiş.

action ve cData:

• action — “A customer value that can be used to differentiate widgets under the same sitekey in analytics… up to 32 alphanumeric characters including _ and -.”
• cData — “A customer payload that can be attached to the challenge throughout its issuance and which is returned upon validation… up to 255 alphanumeric characters including _ and -.”

“Caution — Both action and cData fields only accept alphanumeric characters, underscores (_), and hyphens (-).”

Form entegrasyonu varsayılanları: gizli alan otomatik oluşuyor (response-field: true), adı cf-turnstile-response. Yenileme davranışı: refresh-expired varsayılan auto, retry varsayılan auto, retry-interval varsayılan 8000 ms (maks 900000).

Hostname yönetimi

“By default, every widget requires at least one hostname to be configured. You cannot create a widget without specifying at least one authorized hostname.”

“Wildcard characters (such as *) are not supported in the hostname field. However, adding a hostname automatically authorizes all of its subdomains.”

Geçersiz biçimler: şema (http://ornek.com.tr), port (ornek.com.tr:443), yol (ornek.com.tr/giris).

Pre-clearance ve WAF ilişkisi

Ücretsiz planda da var — plan tablosunda “Pre-clearance support | Yes | Yes”.

“Pre-clearance allows Turnstile to issue clearance cookies that can be used across your Cloudflare-protected domains.”

Nasıl çalışıyor:

1. Zone’undaki bir WAF kuralı normalde ziyaretçiyi tam sayfa bir Cloudflare challenge ekranıyla kesiyor.
2. Turnstile pre-clearance modunda yapılandırıldığında, sayfa içindeki widget’ı çözmek aynı zamanda o zone için cf_clearance çerezini üretiyor.
3. Sonraki isteklerde bu çerez WAF’ın challenge şartını karşılıyor — araya giren ekran hiç çıkmıyor.

Asıl kullanım senaryosu:

“Integrate Cloudflare challenges on single-page applications (SPAs) by allowing Turnstile to issue a Pre-Clearance cookie.”

Pre-clearance olmadan bir SPA’nın fetch() çağrısı WAF challenge’ına takıldığında JSON yerine HTML challenge sayfası dönüyor ve uygulama kırılıyor.

İçerik Güvenlik Politikası

“Cloudflare recommends using the nonce-based approach documented with CSP3… Turnstile works with strict-dynamic.”

Alternatif:

Content-Security-Policy:
  script-src https://challenges.cloudflare.com;
  frame-src  https://challenges.cloudflare.com;
  connect-src 'self';            /* pre-clearance kullanıyorsan */

Ve bir kısıt: “You cannot set your own CSP and/or Referer-Policy via meta tags or Transform rules in challenge pages.”

Sınırlar

Ne zaman kullanılır, ne zaman kullanılmaz

Kullanılır

• Cloudflare’de olmayan bir sitede form koruması istiyorsan. Bu, ürünün en ayırt edici yanı.
• Kayıt, giriş, iletişim ve yorum formlarında. Klasik CAPTCHA’nın yerini alıyor ve kullanıcıya bulmaca çözdürmüyor.
• Bir SPA’de WAF challenge’ı fetch() çağrılarını kırıyorsa. Pre-clearance belgelenmiş çözüm.
• Erişilebilirlik önemliyse. Managed modda en kötü durum bir onay kutusu; resim ızgarası yok.
• Bütçe sıfırsa. Challenge sayısı sınırsız ve ölçümlü faturalama yok.

Kullanılmaz

Sunucu tarafı doğrulama yazamayacaksan. Widget tek başına hiçbir şey korumuyor. siteverify çağıramıyorsan bu ürünü kurmanın anlamı yok.

Native mobil uygulamada SDK bekliyorsan. WebView zorunlu; resmî native SDK yok.

file:// veya başka bir protokolde. “Turnstile is designed to function only on pages using http:// or https://.”

Bot yönetimi bekliyorsan. Turnstile bir anı doğruluyor — o istek insan mı. Sürekli bot skorlaması, AI crawler yönetimi ve endpoint bazlı politika için Bot Management gerekiyor.

Hız sınırlama yerine. Turnstile “bu bir insan mı” sorusuna cevap veriyor, “bu istemci çok mu hızlı” sorusuna değil. İkincisi Rate Limiting.

Çözülen challenge’ı insanlık kanıtı sayacaksan. “A ‘solved’ Turnstile challenge does not automatically confirm the visitor is human… Bots might complete challenges, but Cloudflare can detect bot-like signals and mark the token as invalid.”

WCAG seviyesine sözleşmede dayanacaksan. İki resmî sayfa AA ve AAA diyor; teyit almadan bir ihaleye yazma.

20 widget’tan fazlasına ihtiyacın varsa ve Enterprise değilsen. Çok müşterili bir SaaS’ta bu sınır çabuk doluyor.

Somut örnekler

İstemci tarafı

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

<form method="POST" action="/kayit">
  <input type="email" name="eposta" required />

  <div class="cf-turnstile"
       data-sitekey="SITEKEY"
       data-action="kayit"
       data-cdata="kampanya-2026"
       data-language="tr"
       data-theme="auto"></div>

  <button type="submit">Kaydol</button>
</form>

Gizli alan otomatik oluşuyor: cf-turnstile-response.

Sunucu tarafı doğrulama (tam kontrol listesiyle)

async function turnstileDogrula(token, istemciIp, beklenenAction, beklenenHostname) {
  const govde = new URLSearchParams();
  govde.append("secret", process.env.TURNSTILE_SECRET);
  govde.append("response", token);
  if (istemciIp) govde.append("remoteip", istemciIp);
  govde.append("idempotency_key", crypto.randomUUID());

  const yanit = await fetch(
    "https://challenges.cloudflare.com/turnstile/v0/siteverify",
    { method: "POST", body: govde }
  );
  const d = await yanit.json();

  if (!d.success) return { gecerli: false, sebep: d["error-codes"] };

  // Cloudflare bunları senin adına DOĞRULAMIYOR — kendin karşılaştır
  if (beklenenAction && d.action !== beklenenAction)
    return { gecerli: false, sebep: "action_uyusmuyor" };
  if (beklenenHostname && d.hostname !== beklenenHostname)
    return { gecerli: false, sebep: "hostname_uyusmuyor" };

  return { gecerli: true, cdata: d.cdata, zaman: d.challenge_ts };
}

Yeniden deneme — idempotency anahtarı döngü DIŞINDA

async function tekrarliDogrula(token, istemciIp, maksDeneme = 3) {
  const anahtar = crypto.randomUUID();      // her denemede AYNI anahtar
  for (let deneme = 0; deneme < maksDeneme; deneme++) {
    try {
      return await siteverify(token, istemciIp, anahtar);
    } catch (e) {
      if (deneme === maksDeneme - 1) throw e;
      await new Promise((r) => setTimeout(r, Math.pow(2, deneme) * 1000));
    }
  }
}

Anahtarı döngünün içinde üretirsen ikinci deneme sahte bir timeout-or-duplicate alıyor.

Süresi dolan token’ı yenilemek

window.onloadTurnstileCallback = function () {
  turnstile.render("#turnstile-kabi", {
    sitekey: "SITEKEY",
    language: "tr",
    "expired-callback": () => turnstile.reset(),
    "timeout-callback": () => turnstile.reset(),
  });
};

Cloudflare’in test anahtarları

“Test sitekeys generate a dummy token: XXXX.DUMMY.TOKEN.XXXX” “Test keys work on any domain, including: localhost, 127.0.0.1, 0.0.0.0”

Ve bir kural: test secret’ı yalnızca dummy token kabul ediyor, üretim secret’ı yalnızca gerçek token.

Demo 1: Cloudflare’den geçmeyen bir on-prem formda uçtan uca tur

Bu demonun değeri, ürünün en ayırt edici iddiasını kanıtlaması: site Cloudflare’de olmak zorunda değil.

Adım 1 — Cloudflare’den geçmediğini kanıtla

# On-prem sunucunun doğrudan IP'siyle, hiçbir proxy olmadan
dig +short ornek-onprem.local
curl -sS -D- -o /dev/null http://192.168.1.50:8080/kayit | grep -i "server:"
# Beklenen: nginx / Apache — "server: cloudflare" DEĞİL

Yanıt başlıklarında cloudflare değil kendi web sunucusunun adı

Adım 2 — Widget’ı yerleştir

localhost test anahtarlarıyla değil, gerçek bir sitekey oluştur ve hostname’i ekle.

Panelde widget oluşturulurken mod seçimi ve hostname alanı

On-prem sayfada render olan Managed mod widget'ı

Adım 3 — Token’ı yakala

# Tarayıcı geliştirici araçlarında formu gönder ve gizli alanı oku
document.querySelector('[name="cf-turnstile-response"]').value.length

cf-turnstile-response gizli alanının değeri ve uzunluğu (2048'e kadar)

Adım 4 — siteverify’ı çağır

curl -sS -X POST "https://challenges.cloudflare.com/turnstile/v0/siteverify" \
  -d "secret=$TURNSTILE_SECRET" \
  -d "response=$TOKEN" \
  -d "remoteip=203.0.113.10" | jq

success:true, challenge_ts, hostname ve action alanlarını içeren JSON

Adım 5 — 🔴 Aynı token’ı ikinci kez gönder

curl -sS -X POST "https://challenges.cloudflare.com/turnstile/v0/siteverify" \
  -d "secret=$TURNSTILE_SECRET" -d "response=$TOKEN" | jq '.["error-codes"]'

success:false ve error-codes içinde timeout-or-duplicate

Adım 6 — Beş dakikayı bekle

TOKEN=$(...)          # yeni bir token al
sleep 310
curl -sS -X POST ".../siteverify" -d "secret=$TURNSTILE_SECRET" -d "response=$TOKEN" | jq

5 dakikadan sonra aynı hata koduyla reddedilmesi

Adım 7 — action ve hostname doğrulamasını kanıtla

İki widget oluştur (data-action="giris" ve data-action="kayit"), giriş widget’ından aldığın token’ı kayıt uç noktasına gönder.

siteverify'ın success:true döndürdüğü ama action alanının beklenenle uyuşmadığı

Adım 8 — Analytics’te sıfır kontrolü

Token Validation sayacının sıfırdan büyük olduğu — siteverify'ın gerçekten çağrıldığının kanıtı

Bu demoda ölçülenler:

Demo 2: Test anahtarlarıyla dört senaryoyu deterministik üretmek

Bu demo hiç gerçek trafiğe ihtiyaç duymuyor ve her seferinde aynı sonucu veriyor.

Adım 1 — Her zaman geçen widget

<div class="cf-turnstile" data-sitekey="1x00000000000000000000AA" data-language="tr"></div>

curl -sS -X POST ".../siteverify" \
  -d "secret=1x0000000000000000000000000000000AA" \
  -d "response=XXXX.DUMMY.TOKEN.XXXX" | jq

Widget'ın anında çözülmesi ve siteverify'ın success:true dönmesi

Adım 2 — Her zaman düşen widget

<div class="cf-turnstile" data-sitekey="2x00000000000000000000AB" data-language="tr"></div>

Widget'ın hata durumunu göstermesi

Adım 3 — Etkileşimi zorlayan widget

<div class="cf-turnstile" data-sitekey="3x00000000000000000000FF" data-language="tr"></div>

Onay kutulu widget'ın Türkçe metinle göründüğü — resim ızgarası olmadığı

Adım 4 — “Harcanmış token” secret’ı

curl -sS -X POST ".../siteverify" \
  -d "secret=3x0000000000000000000000000000000AA" \
  -d "response=XXXX.DUMMY.TOKEN.XXXX" | jq

timeout-or-duplicate hatasının deterministik olarak üretilmesi

Adım 5 — Üretim ve test anahtarlarının karışmadığını göster

# Üretim secret'ı + dummy token → reddedilmeli
curl -sS -X POST ".../siteverify" -d "secret=$GERCEK_SECRET" \
  -d "response=XXXX.DUMMY.TOKEN.XXXX" | jq '.["error-codes"]'

# Test secret'ı + gerçek token → reddedilmeli
curl -sS -X POST ".../siteverify" -d "secret=1x0000000000000000000000000000000AA" \
  -d "response=$GERCEK_TOKEN" | jq '.["error-codes"]'

İki çapraz denemenin de reddedildiği çıktı

Adım 6 — Hostname kapsamını test et

Widget’a yalnızca www.ornek.com.tr ekle, sonra widget’ı çıplak ornek.com.tr üzerinde çalıştır.

www eklenmişken çıplak alan adında widget'ın çalışmaması

Sonra ornek.com.tr ekle ve alt alan adlarının otomatik kapsandığını göster.

Kök alan adı eklendiğinde shop. ve panel. alt alan adlarında da çalıştığı

Bu demoda ölçülenler:

Fiyatlandırma

Ephemeral ID (yalnızca Enterprise): “Ephemeral IDs are dynamically generated for each Turnstile solve attempt. No cookies or local storage is required.… IDs expire within a few days and cannot be used to identify individual users.” Etkinleştirme kendi kendine yapılamıyor — hesap ekibi gerekiyor.

Lisanslama ve hukuki çerçeve

Hizmet tescillidir ve Cloudflare Hizmet Şartları’na tabidir.

KVKK açısından güçlü dayanak. Turnstile’ın veri işleme sınırı açıkça yazılı:

“Turnstile processes only the data strictly necessary to provide this security function. Turnstile does not access, store, or transmit user communications, form entries, or other page inputs.”

Yani formdaki kişisel veriler Cloudflare’e gitmiyor — yalnızca tarayıcı ortamı sinyalleri ve (gönderirsen) remoteip. Bu, bir CAPTCHA çözümü için oldukça dar bir kapsam ve aydınlatma metninde somut olarak yazılabilir.

remoteip isteğe bağlı. Ziyaretçinin IP adresini siteverify’a göndermek zorunlu değil. Veri minimizasyonu açısından göndermemeyi tercih edebilirsin; doğrulama yine çalışıyor. Gönderirsen bir kişisel veri aktarımı yapmış oluyorsun.

Ephemeral ID. Enterprise’da açılan bu özellik bile gizlilik odaklı tasarlanmış: çerez veya yerel depolama kullanmıyor, hesabına özgü ve “expire within a few days and cannot be used to identify individual users.”

Sık yapılan hatalar

siteverify’ı hiç çağırmamak. Widget tek başına hiçbir şey korumuyor. Analytics’te Token Validation sıfırsa durum budur.

action ve hostname alanlarını doğrulamamak. Cloudflare bunları döndürüyor ama zorlamıyor.

Aynı token’ı ikinci kez doğrulamak. timeout-or-duplicate.

Idempotency anahtarını yeniden deneme döngüsünün içinde üretmek. Sahte timeout-or-duplicate alıyorsun.

Beş dakikalık pencereyi hesaba katmamak. Uzun formlarda expired-callback ile turnstile.reset() çağır.

action veya cData’ya Türkçe karakter, boşluk veya nokta koymak. Yalnızca alfanümerik, _ ve -.

Hostname’e www yazıp çıplak alan adını unutmak. Alt alan adları otomatik kapsanıyor ama üst alan adı kapsanmıyor.

Hostname’e şema, port veya yol yazmak. Geçersiz.

Any Hostname’i açıp hostname doğrulamasını yazmamak. Koruma tamamen kalkıyor.

CSP’ye challenges.cloudflare.com eklemeyi unutmak. Widget hiç yüklenmiyor.

Pre-clearance kullanıp connect-src 'self' eklememek. cf_clearance çerezi sessizce kurulmuyor.

Pre-clearance’ta yanlış zone’u seçmek. Alt alan adı ayrı bir zone ise o zone’u seçmen gerekiyor.

Native mobil SDK aramak. Yok; WebView kullan.

Çözülen challenge’ı insanlık kanıtı saymak. “does not automatically confirm the visitor is human.”

Test ve üretim anahtarlarını karıştırmak. Test secret’ı yalnızca dummy token, üretim secret’ı yalnızca gerçek token kabul ediyor.