Next.js CAPTCHA: Route Handler İçinde Çözün (Node.js SDK)

next.js captcha - Next.js CAPTCHA: Solve It in a Route Handler (Node.js SDK)

Sunucu kodundan bir Next.js CAPTCHA çözmek için, CapSkip’i Node.js runtime üzerinde çalışan bir App Router Route Handler içinde çağırın, ardından token’ı döndürün ya da aynı istekte kullanın. Bu kılavuz, Next.js sunucusunun sahibi olmadığı bir sayfadaki CAPTCHA’yı geçmesi gereken geliştirici içindir; kendi sitenize CAPTCHA eklemek için değil. Handler, capskip 1.7.0 paketinden bir Cloudflare Turnstile token’ı ister, secret’larını sunucuda tutar ve function sınırına uyan bir timeout ayarlar. Her görevi üstlenen CapSkip Turnstile çözücü, sahibi olduğunuz bir Windows bilgisayarında çalışır ve çözüm başına hiçbir şey almaz.

Neye ihtiyacınız var

  • CapSkip çalışan bir Windows bilgisayarı. Local mode varsayılan olarak 127.0.0.1 adresinde, 8080 portunda dinler. Kurulum adımları için şuna bakın: kurulum kılavuzu.
  • Node.js 20.9 veya üzeri; bu, Next.js 16.4.6 sürümünün engines alanındaki alt sınırdır. capskip paketinin kendisi Node.js 18 bildirir. Ben npm 11.19.1 ile 20.11.1 ve 24.22.0 sürümlerini çalıştırdım.
  • Otomatikleştirmenize izin olan, Turnstile widget’ı bulunan bir sayfa, onun URL’si ve widget’ın data-sitekey özniteliğindeki sitekey.
  • CapSkip için Next.js sunucunuzun erişebileceği bir adres: kendi bilgisayarınızda 127.0.0.1, barındırılan bir platformda Server mode.

Buradaki her şey yazdığım iki mock’a karşı çalıştı: biri CapSkip in.php ve res.php endpoint’lerini taklit eder, diğeri bir Turnstile token’ını kontrol eden kayıt sayfasını taklit eder. Gerçek CapSkip uygulamasına hiçbir görev gönderilmedi; bu yüzden aşağıdaki çözüm sürelerinin hiçbiri gerçek değildir ve hiçbir barındırma platformuna bir şey dağıtılmadı. Örnek olarak Turnstile seçildi, çünkü çağrısı yalnızca bir sitekey ve bir sayfa URL’si ister; paketin çözdüğü diğer her tür aynı yardımcıya uyar.

1. Adım: projeyi oluşturun ve secret’ları sunucu tarafında tutun

Bunu boş bir klasörde Windows PowerShell’de çalıştırın. type alanını silen satır gereklidir: npm 11.19.1 commonjs değerinde bir type yazar ve Next.js 16.4.6 bunun üzerine derlemeyi reddetti.

# Windows PowerShell, in an empty folder
npm init -y
npm pkg delete type
npm install next react react-dom capskip server-only
npm install -D typescript @types/node @types/react
mkdir lib, app\api\turnstile

O klasörde .env.local adlı bir dosya oluşturun. Next.js onu next dev ve next start için yükler. Hiçbir ad NEXT_PUBLIC_ ile başlamaz ve bu önemlidir: Next.js, tarayıcı kodundaki böyle bir değişkene yapılan referansı derleme sırasında değeriyle değiştirir. Birini bir Client Component içinde referans vererek derledim ve değeri .next/static altındaki bir dosyada göründü. Hiçbir yerde referans verilmeyen önekli bir değişken ile öneksiz bir değişken orada hiçbir dosyada görünmedi.

# .env.local
CAPSKIP_HOST=127.0.0.1
CAPSKIP_PORT=8080
CAPSKIP_API_KEY=YOUR_API_KEY
SOLVE_SECRET=YOUR_LONG_RANDOM_STRING

API Key Validation kapalıyken CapSkip her anahtar değerini kabul eder; bu yüzden anahtar satırı ancak doğrulamayı açtığınızda önem kazanır. SOLVE_SECRET, kendi route’unuzun parolasıdır (3. Adım). Next.js ayrıca bir kök layout ister:

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

2. Adım: CapSkip ile konuşan tek bir yardımcı

SDK’yı yalnızca sunucunun içe aktarabileceği tek bir dosyada tutun. Onun ilk satırı, yani server-only import’u, bir hatayı derleme hatasına çevirir. Bir Client Component bu dosyayı içe aktardığında next build, server-only paketinin bir Client Component modülünden içe aktarılamayacağını söyleyen bir hatayla durdu.

// lib/solver.ts
import "server-only";
import { CapSkip } from "capskip";

let client: CapSkip | undefined;

function getClient(): CapSkip {
  const host = process.env.CAPSKIP_HOST;
  // Without this check the SDK would quietly use 127.0.0.1, which on a
  // hosted platform is the platform's own machine.
  if (!host) throw new Error("CAPSKIP_HOST is not set");
  client ??= new CapSkip({
    host,
    port: Number(process.env.CAPSKIP_PORT ?? 8080),
    apiKey: process.env.CAPSKIP_API_KEY, // only matters with API Key Validation on
  });
  return client;
}

// timeout is in seconds and covers this one call; see the timing section.
export async function solveTurnstile(sitekey: string, url: string) {
  const result = await getClient().turnstile(sitekey, url, { timeout: 40 });
  return { token: String(result.code), userAgent: result.userAgent };
}

Paket kendi tip tanımlarıyla gelir, bu yüzden bir @types paketine gerek yoktur ve tsc, bu kılavuzdaki dosyalar için strict bayrağı açıkken hiç hata bildirmedi (TypeScript 7.0.2; Next.js’in oluşturduğu tsconfig.json strict değerini kapalı bırakır). code alanı string ya da nesne olarak tiplenmiştir, çünkü bazı türler nesne döndürür; bu yüzden yardımcı onu String() ile sarar. İsteğe bağlı userAgent alanı, pakete göre, token gönderilirken kullanılacak User-Agent değeridir.

3. Adım: Next.js CAPTCHA çözümünüz için Route Handler

SDK, CapSkip ile Node.js http modülü üzerinden konuşur; bu yüzden route Node.js runtime üzerinde çalışmalıdır. Next.js belgeleri nodejs değerini varsayılan yapar ve edge değerini kullanımdan kalkmış olarak işaretler; yine de handler nodejs der. Cache Components etkinken belgeler, Node.js o durumda tek runtime olduğundan runtime export’unun kaldırılmasını söyler; bunu test etmedim. Ne olacağını görmek için onu edge yaptım: derleme bir kullanımdan kalkma uyarısıyla geçti ve ilk istek, Edge runtime’ın Node.js url modülünü desteklemediğini söyleyen bir mesajla 502 yanıtı verdi. SDK bu hatayı kendi ağ exception’ına sarar; bu yüzden CapSkip’e ulaşılamıyormuş gibi görünür.

Route herkese açık bir URL’dir ve çözücünüzü harcar; bu yüzden yalnızca bir izin listesindeki sayfaları, sizin secret’ınızı gönderen bir çağıran için çözer. SOLVE_SECRET ayarlı değilse reddeder, çünkü Bearer undefined başlığıyla karşılaştırmak, o başlığı gönderen herkesi içeri alırdı; o başlık benim çalıştırmamda 401 aldı. Object.hasOwn, constructor veya toString gibi adların hedef olarak geçmesini engeller; böyle beş ad ve null değerinde bir JSON gövdesi hep 400 aldı.

// app/api/turnstile/route.ts
import { timingSafeEqual } from "node:crypto";
import { NextResponse } from "next/server";
import { ApiException, NetworkException, TimeoutException } from "capskip";
import { solveTurnstile } from "../../../lib/solver";

export const runtime = "nodejs"; // the SDK uses node:http, so no Edge
export const maxDuration = 60; // seconds; read by the host platform

// Only these pages can be solved, and only for a caller with the secret.
const TARGETS: Record<string, { sitekey: string; url: string }> = {
  signup: { sitekey: "YOUR_SITEKEY", url: "https://example.com/signup" },
};

function authorized(header: string | null): boolean {
  const secret = process.env.SOLVE_SECRET;
  if (!secret || !header) return false;
  const given = Buffer.from(header);
  const wanted = Buffer.from(`Bearer ${secret}`);
  return given.length === wanted.length && timingSafeEqual(given, wanted);
}

export async function POST(request: Request) {
  if (!authorized(request.headers.get("authorization"))) {
    return NextResponse.json({ error: "unauthorized" }, { status: 401 });
  }
  const body = await request.json().catch(() => null);
  const name = typeof body?.target === "string" ? body.target : "";
  const target = Object.hasOwn(TARGETS, name) ? TARGETS[name] : undefined;
  if (!target) return NextResponse.json({ error: "unknown target" }, { status: 400 });

  try {
    const { token, userAgent } = await solveTurnstile(target.sitekey, target.url);
    return NextResponse.json({ token, userAgent });
  } catch (err) {
    if (err instanceof TimeoutException) {
      return NextResponse.json({ error: "solve timed out" }, { status: 504 });
    }
    if (err instanceof ApiException || err instanceof NetworkException) {
      return NextResponse.json({ error: err.message }, { status: 502 });
    }
    throw err; // a ValidationException is a bug in your code: let it be a 500
  }
}

Bir ApiException, ERROR_CAPTCHA_UNSOLVABLE gibi CapSkip’in kendi cevabını taşır ve orada yeni bir istek işe yarayabilir; bunu ERROR_CAPTCHA_UNSOLVABLE kılavuzu açıklar. Çalıştırmadan önce TARGETS içindeki YOUR_SITEKEY değerini ve URL’yi otomatikleştirdiğiniz sitenin sitekey ve sayfasıyla değiştirin; aşağıdaki app/actions.ts içindeki PAGE_URL ve sitekey için de aynısını yapın. Geliştirme sunucusunu bir terminalde başlatın:

# first terminal, in the project folder
npx next dev

Ardından route’u ikinci bir terminalden, .env.local içindeki secret’ınızla çağırın:

# second terminal
Invoke-RestMethod -Method Post -Uri http://localhost:3000/api/turnstile `
  -Headers @{ Authorization = "Bearer YOUR_LONG_RANDOM_STRING" } `
  -ContentType "application/json" -Body '{"target":"signup"}'

Cevap token ve userAgent içerir. Token’ı sayfanın form alanına, burada cf-turnstile-response alanına koyun ve formla birlikte o User-Agent değerini gönderin. Mock sitem bir token’ı bir kez kabul etti ve ikinci seferde 403 yanıtı verdi; bu, mock’un kuralıdır, Cloudflare’in değil. Akışı next dev içinde ve next build artı next start ile, iki Node.js sürümünde de çalıştırdım. İlk çalıştırma ayrıca bir tsconfig.json yazar ve next dev bir AGENTS.md dosyası ekler; ikisi de Next.js’ten gelir.

4. Adım: ya da bir server action içinde çözün ve gönderin

Tarayıcının token’a hiç ihtiyacı yoksa, çözümü ve gönderimi sunucuda yapın ve geriye yalnızca sonucu gönderin. Bir server action bunu yapabilir ve token tarayıcıya hiç ulaşmaz. Aynı yardımcıyı içe aktarır ve bir Referer ekler, çünkü fetch hiçbir Referer göndermez ve bazı framework’ler bunu bir HTTPS form gönderiminde kontrol eder. Ayrıca, sayfa dosyasından sonra verilen nedenle, önce bir cookie’yi kontrol eder.

// app/actions.ts
"use server";
import { cookies } from "next/headers";
import { solveTurnstile } from "../lib/solver";

const PAGE_URL = "https://example.com/signup";

// Solve and submit in one server-side step, so the token never leaves the server.
export async function signUp(_previous: string, formData: FormData): Promise<string> {
  // A server action is a public endpoint: replace this cookie test with
  // your own session check.
  const secret = process.env.SOLVE_SECRET;
  if (!secret || (await cookies()).get("solve-key")?.value !== secret) return "not allowed";

  const { token, userAgent } = await solveTurnstile("YOUR_SITEKEY", PAGE_URL);
  const reply = await fetch(PAGE_URL, {
    method: "POST",
    headers: {
      Referer: PAGE_URL, // fetch sends no Referer by itself
      ...(userAgent ? { "User-Agent": userAgent } : {}),
    },
    body: new URLSearchParams({
      email: String(formData.get("email")),
      "cf-turnstile-response": token,
    }),
  });
  return `${reply.status} ${(await reply.text()).slice(0, 60)}`;
}

Küçük bir Client Component action’ı çalıştırır ve sayfa, route ile aynı nedenle maxDuration export eder.

// app/signup-form.tsx
"use client";
import { useActionState } from "react";
import { signUp } from "./actions";

export default function SignupForm() {
  const [result, action, pending] = useActionState(signUp, "");
  return (
    <form action={action}>
      <input name="email" defaultValue="[email protected]" />
      <button disabled={pending}>{pending ? "Solving..." : "Sign up"}</button>
      <p id="result">{result}</p>
    </form>
  );
}
// app/page.tsx
import SignupForm from "./signup-form";

export const maxDuration = 60; // meant for the form's server action; unchecked on hosts

export default function Home() {
  return <SignupForm />;
}

Bir server action herkese açık bir POST endpoint’idir. Bu sayfayı yükleyebilen herkes onu tetikleyebilir. Sayfayı kendi oturum açma ekranınızın arkasına koyun ya da cookie testinde olduğu gibi signUp() işlevinin başında bir oturumu veya secret’ı kontrol edin. Denemek için tarayıcının geliştirici araçlarında, değeri secret’ınız olan solve-key adlı bir cookie ekleyin. Kontrol olmadan, sayfanın gizli form alanlarını hiçbir kimlik bilgisi olmadan yeniden oynatan bir script başarı metnini aldı ve mock üzerinde bir görev başlattı.

Cookie ayarlıyken butona tıklamak mock sitenin karşılama metnini gösterdi ve token tarayıcıya hiç ulaşmadı. Bir barındırma platformunun bir action için maxDuration değerini nasıl uyguladığını kontrol edemedim; bunu kendi platformunuzda test edin.

maxDuration ve SDK timeout karşılaştırması

Next.js route segment belgelerine göre maxDuration için varsayılanı dağıtım platformu belirler ve kendi sunucunuzda barındırma bunu zorunlu kılmaz: maxDuration 2 iken ve 5 saniye gerektiren bir mock ile next start, 7,8 saniye sonra 200 yanıtı verdi (Node.js 24.22.0). Bir çözümü kesen sınır, host’unuzun sınırıdır. Vercel süre belgelerine göre Fluid compute açıkken varsayılan süre her planda 300 saniyedir; üst sınır Hobby’de 300, Pro ve Enterprise’da 800’dür ve daha uzun bir çalışma sonlandırılır. Seçtiğiniz bir değeri export edin ve platformunuzun rakamlarını kontrol edin; beta olarak listelediği 30 dakikalık uzatılmış üst sınır burada ele alınmıyor.

SDK sonucu bir zamanlamayla tekrar tekrar sorar: mock’a karşı sonucu yaklaşık 0; 0,25; 0,77; 1,78; 3,8; 7,8 ve 12,8 saniyelerde istedi, ardından her 5 saniyede bir. Süre sınırını yalnızca bir sonraki poll zamanı geldiğinde kontrol eder. Hiç cevap vermeyen bir mock ile timeout 5, 7,80 saniye sonra bitti; timeout 10, 12,83 saniye sonra; route’un timeout 40 değeri ise handler 504 döndürdüğünde 42,88 saniye sonra bitti (Node.js 24.22.0 ve 20.11.1, 0,1 saniye içinde aynı sonucu verdi). Yani bir çağrı timeout değerini 5 saniyeye kadar aşabilir. timeout değerini maxDuration değerinin en az 10 saniye altında tutun; burada 40, 60’ın altındadır.

Paketin tip yorumları Turnstile için 300 saniye beklendiğini söyler, ancak 1.7.0 kaynağında turnstile() hiçbir timeout geçirmez ve seçeneksiz bir çağrı 122,98 saniyede bitti; yani 120 saniyelik varsayılan uygulandı. Kendi değerinizi geçin, bu çelişki önemini yitirir.

Vazgeçen bir istemci görevi durdurmaz. SDK bir çağrıyı iptal edemez: istemcim isteği 1 saniye sonra bıraktığında handler, 37,9. saniyedeki son poll’una kadar sorgulamayı sürdürdü. Bu yüzden timeout değerini kısa tutun.

Barındırılan platformlar: CapSkip’e Server mode ile ulaşın

Barındırılan bir platformda 127.0.0.1, sizin bilgisayarınız değil, function’ın kendi makinesidir. Handler’ı hiçbir şeyin dinlemediği bir porta yönelttim ve 0,06 saniyede, connect ECONNREFUSED 127.0.0.1 ve port mesajıyla bir 502 aldım. Dağıtılmış bir function, bilgisayarınızdaki CapSkip için aynı mesajı göstermelidir; kontrol etmek için hiçbir şey dağıtmadım.

Çözüm Server mode: bağlantı ayarlarında CapSkip, ağınızdaki diğer cihazlardan ya da bir VPS üzerinde internetten gelen bağlantıları da kabul edebilir. Bunun için CapSkip’in yönetici olarak çalışması gerekir ve kılavuz, en kararlı uzaktan erişimi sabit bir genel IP’nin sağladığını söyler. Ardından host’unuzun ortam değişkenlerinde CAPSKIP_HOST değerini o adrese, CAPSKIP_PORT değerini porta ayarlayın. Ayarlar şu bölümdedir: kurulum kılavuzunun bağlantı ayarları. Tüm adreslerde dinleyen bir mock’a karşı handler, ona bilgisayarımın ağ adresi üzerinden ulaştı. Bu, gerçek Server mode’u değil, bu ayarları doğrular.

CapSkip, Server mode başladığında portunu her adrese açar; bu yüzden erişimi beklediğiniz makinelerle sınırlamak için diğerlerine bir Windows Firewall engelleme kuralı ekleyin. Barındırılan bir platformun çıkış adresleri genellikle listelenemez; bu yüzden orada gerçekçi koruma, yalnızca anahtarlarınızdan birini taşıyan isteklerin işlendiği API Key Validation artı kısa bir timeout’tur. SDK düz bir http adresi oluşturur; bu yüzden anahtar şifrelenmeden gider. Platformunuz sabit çıkış adresleri sunuyorsa (hiçbirini kontrol etmedim), yalnızca onlara izin verin ve engelleme kuralını diğer her şey için koruyun. Doğrulama açıkken ve eşleşen anahtar yokken route’um 502 döndürdü.

Yaygın hatalar

GördüğünüzNedenDüzeltme
Derleme durur: module format CommonJs does not matchnpm init, commonjs değerinde bir type yazdı1. Adım’daki npm pkg delete type satırını çalıştırın
Derleme durur: server-only cannot be imported from a Client Componentuse client içeren bir dosya yardımcıyı içe aktarırBunun yerine route’u veya bir server action’ı istemciden çağırın
401 unauthorizedAuthorization başlığı eksik veya yanlış ya da SOLVE_SECRET ayarlı değilBearer ve secret’ınızı gönderin
400 unknown targetGövdede izin listesinden bir anahtar yokHedef adını gönderin, örneğin signup
500 ve sunucu günlüğünde CAPSKIP_HOST is not setDeğişken, sunucunun çalıştığı yerde boş veya ayarlı değilAyarlayın, ardından yeniden başlatın veya yeniden dağıtın
ECONNREFUSED ile 502O host ve portta hiçbir şey dinlemiyor ya da 127.0.0.1 ile barındırılan bir platformdasınızCapSkip’i başlatın ya da Server mode kullanın
Edge runtime bir Node.js modülünü desteklemiyor diyen 502Route Edge runtime üzerinde çalışıyorruntime değerini nodejs olarak export edin
ERROR_KEY_DOES_NOT_EXIST ile 502API Key Validation açık ve anahtar CapSkip’in listesinde yokAnahtarı CapSkip’e ekleyin ve CAPSKIP_API_KEY değerini ayarlayın
ERROR_CAPTCHA_UNSOLVABLE ile 502CapSkip denedi ve doğrulamayı geçemediYeniden isteyin, 3. Adım’da bağlantısı verilen kılavuza bakın
504 solve timed outTimeout içinde token gelmediCapSkip’in çalıştığını kontrol edin, sonra yeniden deneyin
Sayfa ikinci kez bir token’ı reddediyorBir token tek kullanımlıktır (mock sitemin bir kuralı)Gönderim başına bir token

ERROR_CAPTCHA_UNSOLVABLE dışındaki her satır benim çalıştırmalarımdan gelir; o satır CapSkip belgelerini izler.

FAQ

Vercel üzerindeki bir Next.js uygulaması, bilgisayarımdaki bir CapSkip’i kullanabilir mi?

Evet, Server mode ile. CapSkip ağınızda veya genel IP’nizde dinler, function yerel kullanımdakiyle aynı HTTP API’sini kullanır ve yalnızca CAPSKIP_HOST değişir. Beklemediğiniz makineler için bir Windows Firewall engelleme kuralı ekleyin ve API Key Validation özelliğini açın.

Route token’ı tarayıcıya döndürmeli mi?

Yalnızca tarayıcının buna ihtiyacı varsa. Token için bir server action daha güvenlidir, çünkü token o zaman tarayıcıya hiç ulaşmaz; ama endpoint için değil: o da herkese açıktır, bu yüzden onu da koruyun. Hangisini seçerseniz seçin, her çağrı bilgisayarınızda bir görev başlatır.

Bir Next.js route’u CapSkip’i çağırdığında CapSkip çözüm başına ücret alır mı?

Hayır. İstek nereden gelirse gelsin çözücü yine sizin kendi Windows makinenizdir ve üzerinde çözüm başına işleyen bir sayaç yoktur. Host’unuz, bir function’ın sonuç beklerken harcadığı süreyi ölçebilir.

Next.js’te bir CAPTCHA çözümü dört ayara dayanır: Node.js runtime, timeout değerinin üzerinde bir maxDuration, NEXT_PUBLIC_ adı taşımayan secret’lar ve sunucunun erişebildiği bir CapSkip adresi. Çözme işi kendi bilgisayarınızdaki bir captcha çözücü ile yapıldığı için yeniden denemenin ekstra bir maliyeti olmaz. Diğer CAPTCHA türleri için Node.js CAPTCHA çözücü sayfasına göz atın. Kendi sınırları olan bir host, örneğin Netlify, şurada ele alınır: Netlify Functions kılavuzu.