CAPTCHA Next.js: Pecahkan di Route Handler (SDK Node.js)

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

Untuk memecahkan CAPTCHA Next.js dari kode server, panggil CapSkip di dalam Route Handler App Router yang berjalan di runtime Node.js, lalu kembalikan token atau gunakan di request yang sama. Panduan ini untuk developer yang server Next.js-nya harus melewati CAPTCHA di halaman milik pihak lain, bukan untuk memasang CAPTCHA di situs Anda sendiri. Handler meminta token Cloudflare Turnstile dari paket capskip 1.7.0, menyimpan rahasianya di server, dan menetapkan timeout yang sesuai dengan batas fungsi. Setiap task dikirim ke pemecah Turnstile CapSkip, yang berjalan di PC Windows milik Anda dan tidak mengenakan biaya per pemecahan.

Apa yang Anda butuhkan

  • PC Windows dengan CapSkip yang berjalan. Local mode mendengarkan di 127.0.0.1, port 8080 secara default. Langkah penginstalan ada di panduan penyiapan.
  • Node.js 20.9 atau lebih baru, batas minimum pada kolom engines di Next.js 16.4.6. Paket capskip sendiri menyatakan Node.js 18. Saya menjalankan 20.11.1 dan 24.22.0 dengan npm 11.19.1.
  • Halaman dengan widget Turnstile yang boleh Anda otomatisasi, URL-nya, dan sitekey dari atribut data-sitekey milik widget tersebut.
  • Alamat CapSkip yang bisa dijangkau server Next.js Anda: 127.0.0.1 di PC Anda sendiri, Server mode di platform hosting.

Semua yang ada di sini dijalankan terhadap dua mock buatan saya: satu meniru endpoint in.php dan res.php milik CapSkip, satunya meniru halaman pendaftaran yang memeriksa token Turnstile. Aplikasi CapSkip yang asli tidak dikirimi task, jadi tidak ada waktu pemecahan di bawah yang nyata, dan tidak ada yang di-deploy ke platform hosting. Turnstile dipakai sebagai contoh karena pemanggilannya hanya butuh sitekey dan URL halaman; tipe lain yang dipecahkan paket ini cocok dengan helper yang sama.

Langkah 1: buat proyek dan simpan rahasia di sisi server

Jalankan ini di folder kosong di Windows PowerShell. Baris yang menghapus field type diperlukan: npm 11.19.1 menulis type commonjs, dan Next.js 16.4.6 lalu menolak build.

# 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

Buat file bernama .env.local di folder itu. Next.js memuatnya untuk next dev dan next start. Tidak ada nama yang diawali NEXT_PUBLIC_, dan itu penting: Next.js mengganti referensi ke variabel semacam itu di kode browser dengan nilainya saat build. Saya melakukan build dengan satu variabel yang direferensikan di Client Component, dan nilainya muncul di file di bawah .next/static. Variabel berawalan yang tidak direferensikan, dan variabel tanpa awalan, tidak muncul di file mana pun di sana.

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

Saat API Key Validation nonaktif, CapSkip menerima nilai key apa pun, jadi baris key baru berarti setelah Anda mengaktifkan validasi. SOLVE_SECRET adalah kata sandi untuk route Anda sendiri (Langkah 3). Next.js juga memerlukan root layout:

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

Langkah 2: satu helper yang berbicara dengan CapSkip

Simpan SDK dalam satu file yang hanya bisa diimpor oleh server. Baris pertamanya, impor server-only, mengubah kesalahan menjadi kegagalan build. Saat sebuah Client Component mengimpor file ini, next build berhenti dengan error yang menyatakan bahwa server-only tidak bisa diimpor dari modul Client Component.

// 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 ini menyertakan definisi tipe sendiri, jadi paket @types tidak diperlukan, dan tsc tidak melaporkan error untuk file dalam panduan ini dengan flag strict aktif (TypeScript 7.0.2; tsconfig.json yang dibuat Next.js membiarkan strict nonaktif). Field code bertipe string atau objek, karena beberapa tipe mengembalikan objek, jadi helper membungkusnya dengan String(). Field userAgent yang opsional adalah, menurut paketnya, User-Agent yang dipakai saat mengirim token.

Langkah 3: Route Handler untuk pemecahan CAPTCHA Next.js Anda

SDK berbicara dengan CapSkip lewat modul http Node.js, jadi route harus berjalan di runtime Node.js. Dokumentasi Next.js menjadikan nodejs sebagai default dan menandai edge sebagai deprecated, dan handler tetap menulis nodejs. Dengan Cache Components aktif, dokumentasi menyuruh menghapus export runtime, karena Node.js menjadi satu-satunya runtime; itu tidak saya uji. Saya mengubahnya ke edge untuk melihat hasilnya: build lolos dengan peringatan deprecation, dan request pertama dijawab 502 dengan pesan bahwa Edge runtime tidak mendukung modul url Node.js. SDK membungkus kegagalan itu dalam network exception-nya, jadi tampak seperti CapSkip yang tidak terjangkau.

Route ini adalah URL publik yang memakai pemecah Anda, jadi ia hanya memecahkan halaman dalam daftar yang diizinkan, untuk pemanggil yang mengirim secret Anda. Route menolak saat SOLVE_SECRET belum diatur, karena membandingkan dengan header Bearer undefined akan meloloskan siapa pun yang mengirim header itu; header tersebut mendapat 401 pada eksekusi saya. Object.hasOwn mencegah nama seperti constructor atau toString lolos sebagai target; lima nama seperti itu dan body JSON null semuanya mendapat 400.

// 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
  }
}

ApiException membawa jawaban CapSkip sendiri, seperti ERROR_CAPTCHA_UNSOLVABLE, dan request baru bisa membantu di sini, seperti yang dijelaskan dalam panduan ERROR_CAPTCHA_UNSOLVABLE tersebut. Sebelum Anda menjalankannya, ganti YOUR_SITEKEY dan URL di TARGETS dengan sitekey dan halaman situs yang Anda otomatisasi, dan lakukan hal yang sama untuk PAGE_URL dan sitekey di app/actions.ts di bawah. Jalankan dev server di satu terminal:

# first terminal, in the project folder
npx next dev

Lalu panggil route dari terminal kedua, dengan secret Anda dari .env.local:

# 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"}'

Balasannya berisi token dan userAgent. Letakkan token di field form halaman, di sini cf-turnstile-response, dan kirim User-Agent itu bersama form. Situs mock saya menerima token sekali dan menjawab 403 pada kali kedua, itu aturan mock, bukan aturan Cloudflare. Saya menjalankan alurnya di next dev dan di next build plus next start, pada kedua versi Node.js. Eksekusi pertama juga menulis tsconfig.json, dan next dev menambahkan file AGENTS.md; keduanya berasal dari Next.js.

Langkah 4: atau pecahkan dan kirim di server action

Saat browser tidak pernah membutuhkan token, pecahkan dan kirim di server lalu kembalikan hanya hasilnya. Server action bisa melakukannya, dan token tidak sampai ke browser. Ia mengimpor helper yang sama dan menambahkan Referer, karena fetch tidak mengirimnya dan sebagian framework memeriksanya pada pengiriman form HTTPS. Ia juga memeriksa cookie terlebih dahulu, dengan alasan yang diberikan setelah file halaman.

// 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)}`;
}

Sebuah Client Component kecil menjalankan action, dan halaman mengekspor maxDuration dengan alasan yang sama seperti route.

// 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 />;
}

Server action adalah endpoint POST publik. Siapa pun yang bisa memuat halaman ini bisa memicunya. Letakkan halaman di balik sign-in Anda sendiri, atau periksa sesi atau secret di bagian atas signUp(), seperti yang dilakukan tes cookie. Untuk mencobanya, tambahkan cookie bernama solve-key berisi secret Anda di developer tools browser. Tanpa pemeriksaan, skrip yang memutar ulang field form tersembunyi halaman tanpa kredensial mendapat teks sukses dan memulai task di mock.

Dengan cookie terpasang, satu klik pada tombol menampilkan teks sambutan situs mock, dan token tidak pernah sampai ke browser. Saya tidak bisa memeriksa bagaimana platform hosting menerapkan maxDuration pada action, jadi uji itu di platform Anda.

maxDuration dibandingkan timeout SDK

Dokumentasi segmen rute Next.js memberi maxDuration nilai default yang ditetapkan oleh platform deployment, dan self-hosting tidak menegakkannya: dengan maxDuration 2 dan mock yang butuh 5 detik, next start menjawab 200 setelah 7,8 detik (Node.js 24.22.0). Batas yang memotong pemecahan adalah batas host Anda. Dokumentasi durasi Vercel mencantumkan, dengan Fluid compute aktif, default 300 detik di setiap paket dan maksimum 300 di Hobby serta 800 di Pro dan Enterprise, dan menyatakan bahwa eksekusi yang lebih lama dihentikan. Ekspor nilai yang Anda pilih dan periksa angka di platform Anda; maksimum yang diperpanjang 30 menit, yang dicantumkan sebagai beta, tidak dibahas di sini.

SDK melakukan polling sesuai jadwal: terhadap mock, ia meminta hasil pada sekitar 0, 0,25, 0,77, 1,78, 3,8, 7,8 dan 12,8 detik, lalu setiap 5 detik. Ia memeriksa batas waktunya hanya saat polling berikutnya jatuh tempo. Dengan mock yang tidak pernah menjawab, timeout 5 berakhir setelah 7,80 detik, timeout 10 setelah 12,83, dan timeout 40 milik route setelah 42,88 detik, saat handler mengembalikan 504-nya (Node.js 24.22.0 dan 20.11.1 sepakat dalam selisih 0,1 detik). Jadi sebuah panggilan bisa melewati timeout-nya hingga 5 detik. Jaga timeout setidaknya 10 detik di bawah maxDuration, seperti 40 di bawah 60 di sini.

Komentar tipe paket menyatakan Turnstile menunggu 300 detik, tetapi di source 1.7.0 turnstile() tidak meneruskan timeout, dan panggilan tanpa opsi itu berakhir pada 122,98 detik, jadi default 120 detik yang berlaku. Teruskan nilai Anda sendiri dan perbedaan itu tidak lagi penting.

Klien yang menyerah tidak menghentikan task. SDK tidak bisa membatalkan panggilan: saat klien saya menutup request setelah 1 detik, handler terus polling sampai polling terakhirnya pada 37,9 detik. Jadi jaga timeout tetap pendek.

Platform hosting: jangkau CapSkip dengan Server mode

Di platform hosting, 127.0.0.1 adalah mesin milik fungsi itu sendiri, bukan PC Anda. Saya mengarahkan handler ke port yang tidak didengarkan apa pun dan mendapat 502 dalam 0,06 detik dengan pesan connect ECONNREFUSED 127.0.0.1 dan port-nya. Fungsi yang sudah di-deploy seharusnya menampilkan pesan yang sama untuk CapSkip di PC Anda; saya tidak men-deploy apa pun untuk memeriksanya.

Solusinya adalah Server mode: di pengaturan koneksi, CapSkip juga bisa menerima koneksi dari perangkat lain di jaringan Anda, atau dari internet di sebuah VPS. Ini mengharuskan CapSkip berjalan sebagai administrator, dan panduannya menyebut IP publik statis memberi akses jarak jauh yang paling stabil. Lalu atur CAPSKIP_HOST di environment variable host Anda ke alamat itu dan CAPSKIP_PORT ke port-nya. Pengaturannya ada di pengaturan koneksi pada panduan penyiapan. Terhadap mock yang mendengarkan di semua alamat, handler menjangkaunya lewat alamat jaringan PC saya. Itu memeriksa pengaturan ini, bukan Server mode yang sebenarnya.

CapSkip membuka port-nya ke semua alamat saat Server mode dimulai, jadi untuk membatasinya hanya ke mesin yang Anda harapkan, tambahkan aturan block Windows Firewall untuk yang lain. Alamat egress platform hosting biasanya tidak bisa didaftar, jadi perlindungan yang realistis di sana adalah API Key Validation, yang hanya memproses request dengan salah satu key Anda, ditambah timeout pendek. SDK membangun alamat http biasa, jadi key dikirim tanpa enkripsi. Jika platform Anda menyediakan alamat egress tetap (saya tidak memeriksa satu pun), izinkan hanya alamat itu dan pertahankan aturan block untuk semua yang lain. Dengan validasi aktif dan tanpa key yang cocok, route saya mengembalikan 502.

Kesalahan umum

Apa yang Anda lihatPenyebabPerbaiki
Build berhenti: format modul CommonJs tidak cocoknpm init menulis type commonjsJalankan baris npm pkg delete type dari Langkah 1
Build berhenti: server-only tidak bisa diimpor dari Client ComponentFile dengan use client mengimpor helperPanggil route atau server action dari klien
401 unauthorizedHeader Authorization hilang atau salah, atau SOLVE_SECRET belum diaturKirim Bearer dan secret Anda
400 unknown targetBody tidak memuat key dari daftar yang diizinkanKirim nama target, misalnya signup
500 dan CAPSKIP_HOST is not set di log serverVariabel kosong atau belum diatur di tempat server berjalanAtur variabelnya, lalu restart atau deploy ulang
502 dengan ECONNREFUSEDTidak ada yang mendengarkan di host dan port itu, atau Anda berada di platform hosting dengan 127.0.0.1Jalankan CapSkip, atau gunakan Server mode
502 yang menyebut Edge runtime tidak mendukung modul Node.jsRoute berjalan di Edge runtimeEkspor runtime sebagai nodejs
502 dengan ERROR_KEY_DOES_NOT_EXISTAPI Key Validation aktif dan key tidak ada dalam daftar CapSkipTambahkan key di CapSkip dan atur CAPSKIP_API_KEY
502 dengan ERROR_CAPTCHA_UNSOLVABLECapSkip sudah mencoba dan tidak lolos dari tantanganCoba lagi, lihat panduan yang ditautkan di Langkah 3
504 solve timed outTidak ada token dalam batas timeoutPastikan CapSkip berjalan, lalu coba lagi
Halaman menolak token untuk kedua kalinyaToken hanya sekali pakai (aturan situs mock saya)Satu token per pengiriman

Setiap baris kecuali ERROR_CAPTCHA_UNSOLVABLE berasal dari eksekusi saya; yang itu mengikuti dokumentasi CapSkip.

FAQ

Bisakah aplikasi Next.js di Vercel memakai CapSkip di PC saya?

Ya, lewat Server mode. CapSkip mendengarkan di jaringan atau IP publik Anda, fungsi memakai HTTP API yang sama seperti secara lokal, dan hanya CAPSKIP_HOST yang berubah. Tambahkan aturan block Windows Firewall untuk mesin yang tidak Anda harapkan, dan aktifkan API Key Validation.

Haruskah route mengembalikan token ke browser?

Hanya jika browser membutuhkannya. Server action lebih aman untuk token, yang lalu tidak pernah sampai ke browser, tetapi tidak untuk endpoint-nya: ia juga publik, jadi lindungi juga. Mana pun yang Anda pilih, setiap panggilan memulai task di PC Anda.

Apakah CapSkip menagih per pemecahan saat route Next.js memanggilnya?

Tidak. Dari mana pun request datang, pemecahnya tetap mesin Windows Anda sendiri, tanpa meteran per pemecahan. Host Anda mungkin mengukur waktu yang dihabiskan fungsi untuk menunggu hasil.

Pemecahan CAPTCHA Next.js bergantung pada empat pengaturan: runtime Node.js, maxDuration di atas timeout, rahasia tanpa nama NEXT_PUBLIC_, dan alamat CapSkip yang bisa dijangkau server. Karena pemecahan dilakukan oleh pemecah captcha di PC Anda sendiri, percobaan ulang tidak memakan biaya tambahan. Untuk tipe CAPTCHA lain, lihat halaman pemecah CAPTCHA Node.js. Host dengan batasan sendiri, seperti Netlify, dibahas di panduan Netlify Functions.