Turnstile را کامل نصب کنید؛ ویجت بدون Siteverify محافظت نمی‌کند

برای محافظت از فرم با Turnstile، ویجت را بسازید و در صفحه قرار دهید، اما پردازش درخواست را تا دریافت پاسخ معتبر از Siteverify در سرور متوقف کنید. راهنمای شروع Cloudflare جاسازی ویجت و اعتبارسنجی سمت سرور را دو بخش ضروری نصب معرفی می‌کند؛ سایت نیز لازم نیست ترافیکش را از شبکهٔ Cloudflare عبور دهد.

نمایش ویجت یا دریافت رشته‌ای به نام توکن، به‌تنهایی دلیل پذیرش فرم نیست؛ فرستنده می‌تواند مستقیماً به مسیر ارسال فرم درخواست بزند. مستندات Siteverify اعتبارسنجی سمت سرور را الزامی می‌داند: توکن ۳۰۰ ثانیه اعتبار دارد، فقط یک‌بار قابل اعتبارسنجی است و توکن مصرف‌شده یا منقضی باید با توکن تازه جایگزین شود.

ویجت و کلیدها را برای فرم آماده کنید

در حساب Cloudflare به بخش Turnstile بروید، ویجتی بسازید و دامنه‌هایی را که مجاز به نمایش آن هستند مشخص کنید. برای هر ویجت یک sitekey عمومی و یک secret key محرمانه دریافت می‌کنید. sitekey در صفحه قرار می‌گیرد؛ secret key را در تنظیمات خصوصی سرور، مانند متغیر محیطی، نگه دارید. اگر کلید محرمانه را در HTML، کد مرورگر یا پاسخ عمومی API بگذارید، بازدیدکننده هم به آن دسترسی خواهد داشت.

برای فرمی که هنگام بارگذاری صفحه وجود دارد، فایل JavaScript رسمی را از https://challenges.cloudflare.com/turnstile/v0/api.js بارگذاری کنید و عنصر ویجت را داخل همان فرم بگذارید؛ نمونهٔ کوتاه آن <div class="cf-turnstile" data-sitekey="YOUR_SITEKEY"></div> است. فایل را از همان نشانی بارگذاری کنید و نسخه‌ای ذخیره‌شده از آن را جایگزین نکنید. اگر فرم پس از بارگذاری صفحه ساخته می‌شود، مانند برخی برنامه‌های تک‌صفحه‌ای، می‌توانید زمان ساخت ویجت را با turnstile.render کنترل کنید.

قرارگرفتن ویجت داخل فرم HTML باعث می‌شود فیلد پنهان cf-turnstile-response توکن را همراه داده‌های فرم بفرستد. در ارسال فرم با JavaScript نیز باید همین مقدار را به درخواست خود اضافه کنید. در مسیر دریافت فرم، نام فیلد را دقیق بخوانید و نبودن یا خالی‌بودن آن را شکست اعتبارسنجی بدانید؛ فعال‌شدن دکمهٔ ارسال یا اجرای موفق کد مرورگر، تصمیم سرور را تعیین نمی‌کند.

درخواست فرم را تا پاسخ Siteverify نگه دارید

رفت‌وبرگشت توکن این ترتیب را دارد: مرورگر توکن را همراه فرم به برنامهٔ شما می‌فرستد؛ برنامه توکن و secret key را به Siteverify می‌دهد؛ Siteverify نتیجه را به برنامه برمی‌گرداند؛ برنامه تنها پس از نتیجهٔ موفق، داده‌های فرم را پردازش می‌کند. نشانی اعتبارسنجی https://challenges.cloudflare.com/turnstile/v0/siteverify است و درخواست باید با POST ارسال شود. دو پارامتر ضروری secret و response هستند؛ فرستادن remoteip اختیاری است.

نمونهٔ کوچک JavaScript را در مسیر سمت سروری در نظر بگیرید که متغیر token را از cf-turnstile-response خوانده و SITEVERIFY_URL را برابر نشانی بالا گذاشته است: const r = await fetch(SITEVERIFY_URL, {method:"POST", headers:{"Content-Type":"application/json"}, body:JSON.stringify({secret:process.env.TURNSTILE_SECRET_KEY,response:token})}); const allowed = r.ok && (await r.json()).success === true;. عملیات اصلی فرم را فقط وقتی allowed درست است اجرا کنید. درخواست بدون توکن را پیش از این فراخوانی رد کنید و خطای شبکه یا پاسخ JSON ناخوانا را نیز در مسیر فراخوانی به نتیجهٔ ناموفق تبدیل کنید.

نمونهٔ معادل در Python، پس از import کردن os و requests و تعریف همان SITEVERIFY_URL، چنین است: result = requests.post(SITEVERIFY_URL, data={"secret": os.environ["TURNSTILE_SECRET_KEY"], "response": token}, timeout=10); allowed = result.ok and result.json().get("success") is True. این دو نمونه عمداً فقط بخش اعتبارسنجی را نشان می‌دهند؛ دریافت ورودی، رسیدگی به استثنا و پاسخ HTTP به کاربر به چارچوب برنامهٔ شما بستگی دارد. اگر اتصال قطع شد یا مهلت درخواست پایان یافت، عملیات فرم را اجرا نکنید و امکان تلاش دوباره با توکن تازه را فراهم کنید.

پاسخ Siteverify علاوه بر success می‌تواند hostname و action را برگرداند. اگر برای چند فرم action جداگانه تعیین کرده‌اید، مقدار برگشتی را با فرم مورد انتظار مقایسه کنید؛ hostname را نیز می‌توان با دامنهٔ مورد انتظار سنجید. این کنترل‌ها پس از پاسخ موفق انجام می‌شوند و برای محدودکردن دامنهٔ پذیرش توکن به کار می‌روند. مقدار توکن را از مرورگر بگیرید، اما نتیجهٔ success را فقط از پاسخ مستقیم Siteverify به سرور خودتان بپذیرید.

انقضا، بازپخش و خطاها را مدیریت کنید

اگر کاربر فرم را دیر بفرستد یا توکن قبلی دوباره برای اعتبارسنجی ارسال شود، Siteverify ممکن است timeout-or-duplicate برگرداند. این کد به‌تنهایی مشخص نمی‌کند کدام‌یک رخ داده است؛ در هر دو حالت باید توکن تازه گرفت. پس از نمایش پیام مناسب، ویجت را با turnstile.reset بازنشانی کنید تا کاربر بتواند درخواست را دوباره بفرستد. فرستادن دوبارهٔ همان توکن راه‌حل قابل اتکایی نیست، زیرا ممکن است فراخوانی قبلی Siteverify آن را مصرف کرده باشد.

کدهای رایج پاسخ را در مسیر دریافت فرم به اقدام مشخص وصل کنید:

• missing-input-response: پارامتر توکن ارسال نشده است؛ دریافت cf-turnstile-response و روش ارسال فرم را بررسی کنید.
• invalid-input-response: توکن نامعتبر، بدشکل یا منقضی است؛ درخواست را رد کنید و امکان دریافت توکن تازه بدهید.
• timeout-or-duplicate: توکن منقضی یا پیش‌تر مصرف شده است؛ ویجت را بازنشانی کنید و همان توکن را دوباره نفرستید.
• missing-input-secret یا invalid-input-secret: کلید محرمانه ارسال نشده یا معتبر نیست؛ تنظیمات سرور و کلید محیط مربوط را بررسی کنید.
• bad-request یا internal-error: در حالت نخست ساختار درخواست اعتبارسنجی را اصلاح کنید؛ در حالت دوم خطای سرویس را مدیریت کنید و تا دریافت نتیجهٔ موفق، فرم را نپذیرید.

جزئیات خطا برای عیب‌یابی در گزارش سمت سرور مفید است، ولی secret key و بدنهٔ درخواست Siteverify نباید در پیام عمومی کاربر نمایش داده شوند. پیام کاربر می‌تواند میان نیاز به تلاش دوباره و اختلال موقت تفاوت بگذارد؛ خطای تنظیمات کلیدها معمولاً به اصلاح سمت سرور نیاز دارد. اگر برای تلاش دوبارهٔ خود درخواست اعتبارسنجی سازوکاری لازم دارید، Siteverify پارامتر اختیاری idempotency_key را برای این کار می‌پذیرد؛ این پارامتر جای توکن تازه پس از انقضا یا مصرف‌شدن توکن را نمی‌گیرد.

محیط آزمایش و تولید را جدا نگه دارید

برای توسعه و آزمون خودکار از کلیدهای آزمایشی استفاده کنید. راهنمای آزمون Turnstile جفت sitekey آزمایشی 1x00000000000000000000AA و secret key آزمایشی 1x0000000000000000000000000000000AA را برای مسیر موفق معرفی می‌کند؛ کلید محرمانهٔ تولید، توکن ساختگی این جفت را نمی‌پذیرد. کلید آزمایشیِ مسیر ناموفق و کلیدی که خطای توکن مصرف‌شده می‌دهد نیز برای آزمودن رفتار فرم در شکست اعتبارسنجی در دسترس‌اند.

پیش از انتشار، پیکربندی را در چند نقطه کنترل کنید:

• sitekey صفحه و secret key سرور به ویجت و محیط یکسان تعلق داشته باشند؛ برای توسعه، آزمون و تولید پیکربندی جدا نگه دارید.
• دامنه‌های مجاز ویجت تولید همان دامنه‌های موردنظر باشند و کلید محرمانه در فایل عمومی یا مخزن کد قرار نگیرد.
• مسیر دریافت فرم، درخواست بدون توکن، پاسخ ناموفق Siteverify و خطای ارتباطی را بدون اجرای عملیات اصلی رد کند.
• پس از انقضا یا مصرف‌شدن توکن، کاربر بتواند توکن تازه بگیرد و فرم را دوباره ارسال کند.

آزمون را از همان مسیر واقعی ارسال فرم انجام دهید: یک درخواست با توکن معتبر و درخواست‌هایی بدون توکن یا با توکن نامعتبر بفرستید و ببینید کدام‌یک به پردازش داده می‌رسند. برای آزمون تکرار، از کلید آزمایشی مخصوص خطای توکن مصرف‌شده استفاده کنید؛ جفت آزمایشیِ «همیشه موفق» برای سنجش بازپخش مناسب نیست. معیار پذیرش فرم در تولید، پاسخ موفق Siteverify برای توکن همان درخواست است.

بیشتر بخوانید:

• Cloudflare R2 یا Amazon S3؛ خروج داده می‌تواند صورت‌حساب را عوض کند
• Clef تصمیم می‌گیرد، متن نمی‌نویسد؛ ادعای سرعت Cloudflare زیر سؤال رفت
• Cloudflare Workers یا Vercel؛ پهنای باند می‌تواند هزینه را ۳۲ برابر کند