For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /tr/docs/web/captcha.md (or send Accept: text/markdown).
Spam koruması
Genel formlarda ve auth uç noktalarında env ile açılıp kapanan Turnstile kontrolleri.
Başlangıç seviyesinde izlenecek yol
Önkoşullar: Aşağıdaki iki başlangıç kılavuzunu okuyun, Web yerel kurulumunu tamamlayın ve bu monorepo'yu düzenleyicinizde kökünden açın. Web ayarları apps/web/.env.local'ye aittir; Next.js, .env kökünü okumaz. Varsayılan sahte modda /dashboard, veritabanı olmayan bir demodur; /auth'nin taşınan bir veritabanına ihtiyacı var.
Kısa terimler: Çalışma alanı, bir ekibin ayrı kullanıcıları, verileri ve ayarlarıdır. Sunucu güvenilir arka uçtur; sağlayıcı anahtarlarını tarayıcı ve telefon kodundan uzak tutun. Geçiş, tabloları oluşturan veya güncelleyen sürümlü bir veritabanı değişikliğidir. Yapay zeka modeli yanıt veren motordur; model kataloğu, sunucunun mevcut model kimlikleri ve fiyatlarının listesidir. Sağlayıcı yapay zeka, e-posta veya faturalandırma hizmeti gibi bir dış hizmettir. Yetki, bir çalışma alanının bir özelliği kullanmasına olanak tanıyan bir yetkidir. Web kancası, bir hizmetin başka bir hizmetin URL'sine gönderdiği bir mesajdır.
1. Tam yerel/konuşlandırılmış ana bilgisayar adı için bir Turnike test widget'ı oluşturun. apps/web/.env.local'de CAPTCHA_PROVIDER=turnstile ve NEXT_PUBLIC_TURNSTILE_SITE_KEY'yi ayarlayın; TURNSTILE_SECRET_KEY'yi yalnızca sunucunun gizli deposuna koyun.
2. Test iletişim formunu yeniden başlatın ve gönderin.
3. Mücadeleyi ve başarılı bir geçerli belirteç yanıtını bekleyin. Her istek başarısız olursa ana bilgisayar adını ve anahtar çiftini karşılaştırın; asla gizli anahtarı açığa çıkarmayın.
Özel kod için, sağlanan prompts/README.md ile başlayın ve en yakın istemi kopyalayın: Bir uygulama ekranı için prompts/new-app-screen.md veya genel bir sayfa için prompts/new-landing-page.md. Sunucu, veritabanı veya sağlayıcı çalışması için kodlama temsilcinize bu kılavuzun görevini verin ve ondan AGENTS.md, .ai/PROJECT_CONTEXT.md ve eşleşen .ai/ aynalarını okumasını isteyin; burada adı geçen kaynak dosyaların tamamını inceleyin; düzenlemeden önce dosyaları ve kontrolleri listeleyin; çalışma alanı sahipliğini ve yalnızca sunucuya ait sırları koruyun; ve size farkı göstereceğim. İstediğiniz davranışı, giriş ve çıkış alanlarını, izin verilen rolleri, beklenen başarıyı ve hataları ve test hesabını, sağlayıcıyı veya cihazı ona bildirin. Örnek değerleri kullanın; asla gerçek bir sırrı yapıştırmayın.
Her iki anahtarı da etkinleştir
CAPTCHA_PROVIDER=off varsayılandır. turnstile'yi seçin, Turnstile uygulamanızda eşleşen ana bilgisayar adını yapılandırın ve her iki anahtarı da sağlayın. NEXT_PUBLIC_TURNSTILE_SITE_KEY halka açıktır; TURNSTILE_SECRET_KEY yalnızca sunucu doğrulayıcı tarafından kullanılır.
CAPTCHA_PROVIDER=turnstile
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your-site-key
# TURNSTILE_SECRET_KEY belongs in the server secret store.Korunan yüzeyleri koruyun
Kapı, iletişim/bülten formlarını ve Better Auth oturum açma, kaydolma, OTP ve parola sıfırlama kimlik bilgileri uç noktalarını kapsar. Doğrulama/hız sınırlamayı tamamlar; oturumların veya çalışma alanı yetkilendirmesinin yerine geçmez.
Reddetmeyi ve kurtarmayı doğrulayın
Geçerli bir jetonu, eksik/süresi dolmuş/geçersiz jetonu, doğrulayıcı hatasını ve istemci widget'ı sıfırlandıktan sonra yeniden denemeyi test edin. Eyleme dönüştürülebilir, insan kontrolüne sahip kopya ve klavye erişimini sürdürün; Sağlayıcıları değiştirmeden önce seçilen kimlik doğrulama motorunun kapsamını inceleyin.
Kurulum ve yapılandırma
CAPTCHA_PROVIDER doğrulayıcıyı seçer: off (varsayılan — yerel geliştirme kimlik bilgisi olmadan kalır) veya turnstile. Turnstile'ı açmak sunucuda TURNSTILE_SECRET_KEY ve istemci widget'ı için NEXT_PUBLIC_TURNSTILE_SITE_KEY gerektirir — biri eksikse config şeması başlatmayı başarısız kılar.
apps/web/src/captcha.ts, süreç genelinde tek bir doğrulayıcı kurar; token'ı on saniyelik zaman aşımıyla Cloudflare'ın siteverify uç noktasına gönderir ve kapalı şekilde başarısız olur — doğrulanamayan bir token asla insanlık kanıtı sayılmaz.
CAPTCHA_PROVIDER=turnstile
TURNSTILE_SECRET_KEY=… # server-only
NEXT_PUBLIC_TURNSTILE_SITE_KEY=…
Guarded: sign-in/up, OTP send, reset,
contact + newsletter formsUygulama iş akışı
CaptchaWidget (src/captcha-widget.tsx) widget'ı işler ve cf-turnstile-response alanını üst forma enjekte eder; auth istemci çağrıları ise token'ı x-captcha-response başlığında taşır. İletişim ve bülten eylemleri yazmadan önce doğrular — başarısız kontrol lead oluşturmak yerine status=captcha döndürür.
packages/auth, sağlayıcı açıkken better-auth'un captcha eklentisini bağlar; CAPTCHA_ENDPOINTS kimlik bilgisi girişi ve token üreten rotaları kapsar — sign-in, sign-up, OTP gönderimi, parola sıfırlama. check-verification-otp gibi tüketen uç noktalar liste dışı kalır: orada OTP ya da token'ın kendisi kanıttır.
Doğrulama ve sorun giderme
Korunan her formu eksik token ve bozuk token ile gönderin — ikisi de kapalı şekilde başarısız olmalı. Ulaşılamayan bir siteverify'ın geçirmek yerine reddettiğini, provider=off'un yerel geliştirmeyi açık bıraktığını ve sırrın istemci paketlerine ya da loglara asla ulaşmadığını doğrulayın.