Next.js CAPTCHA: Route Handler में हल करें (Node.js SDK)

Server code से Next.js CAPTCHA हल करने के लिए, CapSkip को Node.js runtime पर चलने वाले App Router Route Handler के अंदर call करें, फिर token लौटाएँ या उसी request में इस्तेमाल करें। यह गाइड उस डेवलपर के लिए है जिसके Next.js server को ऐसे पेज का CAPTCHA पार करना है जो उसका अपना नहीं है, अपनी साइट पर CAPTCHA जोड़ने के लिए नहीं। Handler capskip 1.7.0 पैकेज से Cloudflare Turnstile token माँगता है, अपने secrets server पर ही रखता है और function की सीमा के हिसाब से timeout तय करता है। हर task CapSkip Turnstile सॉल्वर के पास जाता है, जो आपके अपने Windows PC पर चलता है और हर solve का कुछ नहीं लेता।
आपको क्या चाहिए
- CapSkip चलाने वाला Windows PC। Local mode डिफ़ॉल्ट रूप से 127.0.0.1, port 8080 पर सुनता है। इंस्टॉल के चरण यहाँ हैं: सेटअप गाइड.
- Node.js 20.9 या बाद का, जो Next.js 16.4.6 के engines फ़ील्ड में न्यूनतम वर्शन है। capskip पैकेज खुद Node.js 18 घोषित करता है। मैंने npm 11.19.1 के साथ 20.11.1 और 24.22.0 चलाए।
- एक Turnstile widget वाला पेज जिसे ऑटोमेट करने की आपको अनुमति है, उसका URL, और widget के data-sitekey attribute से मिला sitekey।
- CapSkip के लिए एक address जिस तक आपका Next.js server पहुँच सके: अपने PC पर 127.0.0.1, hosted platform पर Server mode।
यहाँ सब कुछ मेरे लिखे दो mocks के सामने चला: एक CapSkip के in.php और res.php endpoints की नकल करता है, दूसरा एक sign-up पेज की, जो Turnstile token जाँचता है। असली CapSkip app को कोई task नहीं भेजा गया, इसलिए नीचे का कोई भी solve समय असली नहीं है, और किसी hosting platform पर कुछ deploy नहीं किया गया। Turnstile उदाहरण इसलिए है कि उसकी call को सिर्फ़ sitekey और पेज URL चाहिए; पैकेज जो भी दूसरा टाइप हल करता है, वह इसी helper में बैठ जाता है।
स्टेप 1: प्रोजेक्ट बनाएँ और secrets को server की तरफ़ रखें
इसे किसी खाली फ़ोल्डर में Windows PowerShell में चलाएँ। type फ़ील्ड मिटाने वाली लाइन ज़रूरी है: npm 11.19.1 type की जगह commonjs लिख देता है, और तब Next.js 16.4.6 ने 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
उसी फ़ोल्डर में .env.local नाम की फ़ाइल बनाएँ। Next.js उसे next dev और next start के लिए लोड करता है। कोई नाम NEXT_PUBLIC_ से शुरू नहीं होता, और यह मायने रखता है: Next.js ब्राउज़र कोड में ऐसे variable के हर reference को build के समय उसके मान से बदल देता है। मैंने एक ऐसा variable Client Component में reference करके build किया और उसका मान .next/static के नीचे एक फ़ाइल में दिखा। जिस prefix वाले variable को किसी ने reference नहीं किया, और जिस variable पर prefix नहीं था, वे वहाँ किसी फ़ाइल में नहीं दिखे।
# .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 बंद होने पर CapSkip कोई भी key मान स्वीकार कर लेता है, इसलिए key वाली लाइन तभी मायने रखती है जब आप validation चालू करें। SOLVE_SECRET आपके अपने route का पासवर्ड है (स्टेप 3)। Next.js को एक root layout भी चाहिए:
// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>{children}</body>
</html>
);
}स्टेप 2: एक helper जो CapSkip से बात करता है
SDK को एक ऐसी फ़ाइल में रखें जिसे सिर्फ़ server import कर सके। उसकी पहली लाइन, server-only import, गलती को build की विफलता बना देती है। जब किसी Client Component ने यह फ़ाइल import की, तो next build एक error के साथ रुक गया, जिसमें लिखा था कि server-only को Client Component module से import नहीं किया जा सकता।
// 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 };
}पैकेज अपनी type definitions खुद लाता है, इसलिए किसी @types पैकेज की ज़रूरत नहीं, और strict flag चालू रखने पर tsc ने इस गाइड की फ़ाइलों में कोई error नहीं बताया (TypeScript 7.0.2; Next.js जो tsconfig.json बनाता है उसमें strict बंद रहता है)। code फ़ील्ड का टाइप string या object है, क्योंकि कुछ टाइप object लौटाते हैं, इसलिए helper उसे String() में लपेटता है। वैकल्पिक userAgent फ़ील्ड, पैकेज के अनुसार, token submit करते समय इस्तेमाल होने वाला User-Agent है।
स्टेप 3: आपके Next.js CAPTCHA solve के लिए Route Handler
SDK, CapSkip से Node.js के http module के ज़रिए बात करता है, इसलिए route को Node.js runtime पर चलना होगा। Next.js docs nodejs को डिफ़ॉल्ट बताते हैं और edge को deprecated चिह्नित करते हैं, फिर भी handler में nodejs लिखा है। Cache Components चालू होने पर docs कहते हैं कि runtime export हटा दें, क्योंकि तब Node.js ही अकेला runtime है; मैंने इसे टेस्ट नहीं किया। मैंने देखने के लिए उसे edge कर दिया: build deprecation चेतावनी के साथ पास हुआ, और पहली request का जवाब 502 आया, जिसके संदेश में लिखा था कि Edge runtime Node.js के url module को सपोर्ट नहीं करता। SDK इस विफलता को अपने network exception में लपेट देता है, इसलिए यह ऐसा दिखता है जैसे CapSkip तक पहुँचा ही नहीं जा रहा।
यह route एक public URL है जो आपका solver खर्च करता है, इसलिए वह सिर्फ़ allow list के पेज हल करता है, और सिर्फ़ उस caller के लिए जो आपका secret भेजे। SOLVE_SECRET सेट न हो तो वह मना कर देता है, क्योंकि Bearer undefined वाले header से तुलना करने पर वह header भेजने वाला कोई भी अंदर आ जाता: मेरे run में उस header को 401 मिला। Object.hasOwn constructor या toString जैसे नामों को target बनकर निकलने से रोकता है; ऐसे पाँच नामों और null वाली JSON body, सबको 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 में CapSkip का अपना जवाब होता है, जैसे ERROR_CAPTCHA_UNSOLVABLE, और वहाँ नया request मदद कर सकता है, जैसा कि ERROR_CAPTCHA_UNSOLVABLE गाइड में समझाया गया है। इसे चलाने से पहले, TARGETS में YOUR_SITEKEY और URL को उस साइट के sitekey और पेज से बदलें जिसे आप ऑटोमेट करते हैं, और नीचे app/actions.ts में PAGE_URL और sitekey के साथ भी यही करें। dev server को एक terminal में शुरू करें:
# first terminal, in the project folder npx next dev
फिर दूसरे terminal से route को call करें, .env.local वाले अपने secret के साथ:
# 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"}'जवाब में token और userAgent होते हैं। token को पेज के form फ़ील्ड में रखें, यहाँ cf-turnstile-response, और वही User-Agent form के साथ भेजें। मेरी mock साइट ने token को एक बार स्वीकार किया और दूसरी बार 403 दिया, जो mock का नियम है, Cloudflare का नहीं। मैंने यह flow next dev में और next build के बाद next start में, दोनों Node.js वर्शन पर चलाया। पहला run एक tsconfig.json भी लिख देता है, और next dev एक AGENTS.md फ़ाइल जोड़ता है; दोनों Next.js से आती हैं।
स्टेप 4: या server action में solve और submit करें
जब ब्राउज़र को token की कभी ज़रूरत न हो, तो server पर ही solve और submit करें और सिर्फ़ नतीजा वापस भेजें। एक server action यह कर सकता है, और token ब्राउज़र से दूर रहता है। वह वही helper import करता है और Referer जोड़ता है, क्योंकि fetch कोई Referer नहीं भेजता और कुछ frameworks HTTPS form submission पर उसे जाँचते हैं। वह पहले एक cookie भी जाँचता है, जिसकी वजह पेज फ़ाइल के बाद बताई गई है।
// 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)}`;
}एक छोटा Client Component action चलाता है, और पेज maxDuration को उसी कारण से export करता है जिस कारण 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 एक public POST endpoint है। जो भी यह पेज लोड कर सकता है, वह उसे चला सकता है। पेज को अपने sign-in के पीछे रखें, या signUp() की शुरुआत में session या secret जाँचें, जैसा cookie टेस्ट करता है। आज़माने के लिए, ब्राउज़र के developer tools में solve-key नाम की एक cookie जोड़ें जिसमें आपका secret हो। जाँच के बिना, पेज के hidden form फ़ील्ड बिना किसी credentials के दोहराने वाली एक script को सफलता का टेक्स्ट मिल गया और उसने mock पर एक task शुरू कर दिया।
Cookie सेट होने पर, बटन पर क्लिक करने से mock साइट का स्वागत टेक्स्ट दिखा, और token कभी ब्राउज़र तक नहीं पहुँचा। मैं यह नहीं जाँच सका कि कोई hosting platform किसी action पर maxDuration कैसे लागू करता है, इसलिए इसे अपने platform पर टेस्ट करें।
SDK timeout के मुकाबले maxDuration
Next.js route segment docs बताते हैं कि maxDuration का डिफ़ॉल्ट deployment platform तय करता है, और self-hosting उसे लागू नहीं करता: maxDuration 2 पर और 5 सेकंड लेने वाले mock के साथ, next start ने 7.8 सेकंड बाद 200 दिया (Node.js 24.22.0)। solve को काटने वाली सीमा आपके host की होती है। Vercel duration docs बताते हैं कि Fluid compute चालू होने पर हर plan पर डिफ़ॉल्ट 300 सेकंड है, और अधिकतम Hobby पर 300 तथा Pro और Enterprise पर 800 है, और इससे लंबा run समाप्त कर दिया जाता है। अपना चुना हुआ मान export करें और अपने platform की संख्याएँ जाँचें; वह जिस 30 मिनट के बढ़े हुए अधिकतम को beta बताता है, उसे यहाँ शामिल नहीं किया गया है।
SDK एक schedule पर poll करता है: mock के सामने उसने नतीजा करीब 0, 0.25, 0.77, 1.78, 3.8, 7.8 और 12.8 सेकंड पर माँगा, फिर हर 5 सेकंड पर। वह अपनी deadline तभी जाँचता है जब अगला poll बनता है। कभी जवाब न देने वाले mock के साथ, timeout 5 की call 7.80 सेकंड बाद खत्म हुई, timeout 10 की 12.83 बाद, और route का timeout 40 की 42.88 सेकंड बाद, जब handler ने अपना 504 लौटाया (Node.js 24.22.0 और 20.11.1 में 0.1 सेकंड के भीतर एक जैसा नतीजा)। तो एक call अपने timeout से 5 सेकंड तक ज़्यादा चल सकती है। timeout को maxDuration से कम से कम 10 सेकंड कम रखें, जैसे यहाँ 40, 60 से कम है।
पैकेज की type comments कहती हैं कि Turnstile 300 सेकंड इंतज़ार करता है, लेकिन 1.7.0 source में turnstile() कोई timeout पास नहीं करता, और option के बिना की गई call 122.98 सेकंड पर खत्म हुई, यानी 120 सेकंड का डिफ़ॉल्ट लागू हुआ। अपना मान खुद पास करें और यह असहमति बेमानी हो जाती है।
जो client हार मान लेता है, वह task को नहीं रोकता। SDK किसी call को cancel नहीं कर सकता: जब मेरे client ने 1 सेकंड बाद request छोड़ दी, तब भी handler अपने आख़िरी poll तक, 37.9 सेकंड पर, poll करता रहा। इसलिए timeout छोटा रखें।
Hosted platforms: Server mode से CapSkip तक पहुँचें
Hosted platform पर 127.0.0.1 function की अपनी मशीन है, आपका PC नहीं। मैंने handler को ऐसे port पर भेजा जहाँ कुछ नहीं सुन रहा था और 0.06 सेकंड में 502 मिला, संदेश था connect ECONNREFUSED 127.0.0.1 और port। आपके PC पर चल रहे CapSkip के लिए deploy किए गए function में भी यही संदेश दिखना चाहिए; मैंने जाँचने के लिए कुछ deploy नहीं किया।
इसका हल Server mode है: connection settings में CapSkip आपके network के दूसरे devices से, या VPS पर इंटरनेट से भी, कनेक्शन स्वीकार कर सकता है। इसके लिए CapSkip को administrator के रूप में चलना होता है, और गाइड कहती है कि सबसे स्थिर remote access static public IP से मिलता है। फिर अपने host के environment variables में CAPSKIP_HOST को उस address पर और CAPSKIP_PORT को port पर सेट करें। ये सेटिंग्स आपको सेटअप गाइड की कनेक्शन सेटिंग्समें मिलेंगी। जो mock सभी addresses पर सुन रहा था, उसके सामने handler मेरे PC के network address से उस तक पहुँच गया। इससे ये settings जाँची जाती हैं, असली Server mode नहीं।
Server mode शुरू होते ही CapSkip अपना port हर address के लिए खोल देता है, इसलिए उसे सिर्फ़ अपेक्षित मशीनों तक रखने के लिए बाकी सबके लिए Windows Firewall का block rule जोड़ें। Hosted platform के egress addresses की सूची आम तौर पर नहीं बन सकती, इसलिए वहाँ असली सुरक्षा API Key Validation है, जिसमें सिर्फ़ आपकी किसी key वाली requests ही प्रोसेस होती हैं, साथ में एक छोटा timeout। SDK सादा http address बनाता है, इसलिए key बिना encryption के जाती है। अगर आपका platform तय egress addresses देता है (मैंने किसी की जाँच नहीं की), तो सिर्फ़ उन्हें अनुमति दें और बाकी सबके लिए block rule रखें। Validation चालू होने और मेल खाती key न होने पर मेरे route ने 502 लौटाया।
आम errors
| आप जो देखते हैं | कारण | फिक्स |
|---|---|---|
| Build रुकता है: module format CommonJs does not match | npm init ने type की जगह commonjs लिखा | स्टेप 1 की npm pkg delete type वाली लाइन चलाएँ |
| Build रुकता है: server-only cannot be imported from a Client Component | use client वाली एक फ़ाइल helper को import करती है | इसके बजाय client से route या server action को call करें |
| 401 unauthorized | Authorization header गायब या गलत है, या SOLVE_SECRET सेट नहीं है | Bearer और अपना secret भेजें |
| 400 unknown target | Body में allow list की कोई key नहीं है | Target का नाम भेजें, उदाहरण के लिए signup |
| 500, और server log में CAPSKIP_HOST is not set | Server जहाँ चलता है वहाँ variable खाली या सेट नहीं है | उसे सेट करें, फिर restart या redeploy करें |
| ECONNREFUSED के साथ 502 | उस host और port पर कुछ नहीं सुन रहा, या आप hosted platform पर 127.0.0.1 इस्तेमाल कर रहे हैं | CapSkip शुरू करें, या Server mode इस्तेमाल करें |
| 502, संदेश कि Edge runtime Node.js module को सपोर्ट नहीं करता | Route Edge runtime पर चल रहा है | runtime को nodejs के रूप में export करें |
| ERROR_KEY_DOES_NOT_EXIST के साथ 502 | API Key Validation चालू है और key CapSkip की सूची में नहीं है | CapSkip में key जोड़ें और CAPSKIP_API_KEY सेट करें |
| ERROR_CAPTCHA_UNSOLVABLE के साथ 502 | CapSkip ने कोशिश की और challenge पास नहीं हुआ | फिर से माँगें, स्टेप 3 में दी गई गाइड देखें |
| 504 solve timed out | timeout के भीतर कोई token नहीं मिला | जाँचें कि CapSkip चल रहा है, फिर retry करें |
| पेज दूसरी बार token को ठुकरा देता है | Token एक बार इस्तेमाल का होता है (मेरी mock साइट का नियम) | हर submission के लिए एक token |
ERROR_CAPTCHA_UNSOLVABLE को छोड़कर हर पंक्ति मेरे runs से है; वह वाली CapSkip docs पर आधारित है।
FAQ
क्या Vercel पर चलता Next.js app मेरे PC पर चल रहे CapSkip का इस्तेमाल कर सकता है?
हाँ, Server mode के ज़रिए। CapSkip आपके network या public IP पर सुनता है, function वही HTTP API इस्तेमाल करता है जो लोकल में करता है, और सिर्फ़ CAPSKIP_HOST बदलता है। उन मशीनों के लिए Windows Firewall का block rule जोड़ें जिनकी आप उम्मीद नहीं करते, और API Key Validation चालू करें।
क्या route को token ब्राउज़र को लौटाना चाहिए?
सिर्फ़ तब जब ब्राउज़र को उसकी ज़रूरत हो। Token के लिए server action ज़्यादा सुरक्षित है, क्योंकि तब वह ब्राउज़र तक पहुँचता ही नहीं, लेकिन endpoint के लिए नहीं: वह भी public है, इसलिए उसकी भी सुरक्षा करें। जो भी चुनें, हर call आपके PC पर एक task शुरू करती है।
क्या Next.js route के call करने पर CapSkip हर solve का बिल बनाता है?
नहीं। request जहाँ से भी आए, solver आपकी अपनी Windows मशीन ही है, उस पर प्रति-solve कोई मीटर नहीं। आपका host उस समय का मीटर रख सकता है जो function नतीजे के इंतज़ार में बिताता है।
Next.js CAPTCHA solve चार settings पर टिका है: Node.js runtime, timeout से ऊपर का maxDuration, बिना NEXT_PUBLIC_ नाम वाले secrets, और CapSkip का ऐसा address जिस तक server पहुँच सके। क्योंकि solve आपके अपने PC पर चल रहे कैप्चा सॉल्वर में होता है, इसलिए retry का कोई अतिरिक्त ख़र्च नहीं। दूसरे CAPTCHA टाइप के लिए देखें Node.js कैप्चा सॉल्वर पेज। Netlify जैसे अपनी सीमाओं वाले host की जानकारी यहाँ है: Netlify Functions गाइड.
