صفحهٔ اصلی کپچی

مستندات کپچی

کپتچی را به سرور، وردپرس یا اپلیکیشن وصل کنید. هر پاسخ را در سرور خودتان با Siteverify تأیید کنید.

شروع راه‌اندازی

آماده‌سازی در پنل

  1. در پنل مشتریان یک سایت بسازید و نام میزبان فرم را ثبت کنید.
  2. برای فرم یک اقدام فعال مثل contact_form تعریف کنید. همان نام را در مرورگر و سرور به‌کار ببرید.
  3. کلید سایت را در تنظیمات ویجت بگذارید و کلید محرمانه را فقط در محیط سرور، مثلاً در CAPTCHI_SECRET_KEY، نگه دارید.

نصب SDK در مرورگر

پوشهٔ خروجی SDK را روی وب‌سایت خود میزبانی کنید و ساختار captchi.js، captchi.css و chunks/ را حفظ کنید. در نسخهٔ خودمیزبان کپچی، مسیر خروجی این فایل‌ها از ریشهٔ پروژه apps/com_captchi_core/theme/default/assets/captchi/ است. اگر پوشهٔ خروجی در کپی سورس وجود ندارد، در ریشهٔ پروژه دستورهای زیر را اجرا کنید.

npm --prefix apps/com_captchi_core/sdk ci
npm --prefix apps/com_captchi_core/sdk run build

مسیر فایل‌ها، آدرس فرم و کلید سایت را در نمونه جایگزین کنید. ویجت توکن یک‌بارمصرف ct_resp_… را همراه فرم به سرور خودتان می‌فرستد.

<link rel="stylesheet" href="/vendor/captchi/captchi.css">
<form id="contact" action="/contact" method="post">
  <!-- Keep your existing fields and CSRF input here. -->
  <input type="hidden" name="response">
  <div id="captchi-widget"></div>
  <button type="submit">ارسال فرم</button>
  <p id="captchi-message" role="status"></p>
</form>
<script type="module">
  import { Captchi } from '/vendor/captchi/captchi.js';

  const form = document.querySelector('#contact');
  const button = form.querySelector('button');
  const message = document.querySelector('#captchi-message');
  const widget = Captchi.render('#captchi-widget', {
    siteKey: 'REPLACE_WITH_SITE_KEY',
    action: 'contact_form',
    apiBaseUrl: 'https://api.captchi.ir',
  });

  form.addEventListener('submit', async event => {
    event.preventDefault();
    button.disabled = true;
    message.textContent = '';

    try {
      form.elements.namedItem('response').value = await widget.execute();
      HTMLFormElement.prototype.submit.call(form);
    } catch {
      widget.reset();
      message.textContent = 'بررسی انجام نشد. دوباره تلاش کنید.';
      button.disabled = false;
    }
  });
</script>

تأیید در سرور با Siteverify

در مسیر پردازش فرم، توکن را با POST /api/v1/siteverify بررسی کنید. نام اقدام، نام میزبان و کلید سایت را از تنظیمات مورد اعتماد سرور بردارید. نمونهٔ PHP به افزونهٔ cURL نیاز دارد.

<?php
// Call this from your POST handler before processing the form.
function verifyCaptchi(string $response): bool
{
    $secret = getenv('CAPTCHI_SECRET_KEY');
    if ($secret === false || $secret === '' || $response === '') {
        return false;
    }

    $request = curl_init('https://api.captchi.ir/api/v1/siteverify');
    curl_setopt_array($request, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 3,
        CURLOPT_TIMEOUT => 8,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Accept: application/json'],
        CURLOPT_POSTFIELDS => json_encode([
            'secret' => $secret,
            'response' => $response,
            'site_key' => 'REPLACE_WITH_SITE_KEY',
            'action' => 'contact_form',
            'hostname' => 'example.com',
        ], JSON_THROW_ON_ERROR),
    ]);

    $body = curl_exec($request);
    $status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
    curl_close($request);

    if (!is_string($body) || $status !== 200) {
        return false;
    }

    $result = json_decode($body, true);
    return ($result['success'] ?? false) === true
        && ($result['data']['success'] ?? false) === true;
}

فرم را فقط وقتی پردازش کنید که هر دو مقدار success و data.success برابر true باشند. بررسی CSRF و اعتبارسنجی فیلدهای فرم همچنان در مسیر سرور انجام می‌شود.

افزونهٔ وردپرس کپتچی

افزونهٔ رسمی وردپرس SDK را بارگذاری می‌کند، توکن را هنگام ارسال فرم می‌گیرد و Siteverify را سمت سرور اجرا می‌کند. دانلود افزونهٔ WordPress

  1. فایل ZIP را از پیشخوان WordPress در بخش «افزونه‌ها ← افزودن ← بارگذاری افزونه» نصب و فعال کنید. افزونه به WordPress 6.0 و PHP 7.4 یا جدیدتر نیاز دارد.
  2. در تنظیمات ← Captchi، کلید عمومی و کلید محرمانه را وارد کنید. کلید محرمانه هنگام نمایش فرم پنهان می‌ماند و فقط از backend فرستاده می‌شود.
  3. hostname و action فرم را در پنل کپچی ثبت کنید؛ hostname باید همان دامنه‌ای باشد که WordPress از آن سرویس می‌دهد.
  4. در Contact Form 7 از form-tag کپچی استفاده کنید؛ افزونه اعتبارسنجی سروری را خودکار به ارسال CF7 وصل می‌کند.
  5. برای سایر فرم‌سازها، shortcode را داخل فرم بگذارید و helper تأیید را در hook پردازش همان فرم اجرا کنید.
[captchi captchi_response action:contact_form]

در Contact Form 7 نام فیلد باید captchi_response باشد. action را با مقدار فعال در پنل جایگزین کنید؛ افزونه از hook wpcf7_validate_captchi برای Siteverify سمت سرور استفاده می‌کند و در خطای شبکه یا رد پاسخ، ارسال فرم را متوقف می‌سازد.

[captchi action="contact_form" language="fa" theme="auto"]

ویژگی‌های shortcode: action شناسهٔ فعال پنل، language یکی از fa/en و theme یکی از auto/light/dark است. ویجت باید داخل فرم قرار بگیرد.

// Call this inside your existing form handler after checking its WordPress nonce.
if (!captchi_verify_submission('contact_form')) {
    wp_die('بررسی امنیتی انجام نشد. فرم را دوباره ارسال کنید.');
}

helper به‌صورت پیش‌فرض توکن را از POST می‌خواند، hostname را از home_url() می‌گیرد و در خطای شبکه یا رد Siteverify مقدار false می‌دهد. nonce وردپرس و اعتبارسنجی فیلدهای فرم را همچنان اجرا کنید. اتصال خودکار این نسخه برای Contact Form 7 است؛ برای سایر فرم‌سازها تابع را در hook اعتبارسنجی سمت سرور همان فرم صدا بزنید.

برای سیاست score_only به‌جای تابع boolean، Captchi_WordPress::verify_submission('checkout') را فراخوانی کنید؛ در پاسخ موفق، آرایهٔ risk_score را در اختیار backend قرار می‌دهد.

اپلیکیشن‌ها و برنامه‌های تک‌صفحه‌ای

SDK فعلی کپتچی برای مرورگر است. در React، Vue یا برنامهٔ وب تک‌صفحه‌ای آن را در کامپوننت کلاینت راه‌اندازی و هنگام unmount با widget.remove() پاک کنید. نتیجهٔ widget.execute() را به API خودتان بفرستید؛ اپلیکیشن موبایل نباید Siteverify را مستقیم فراخوانی کند.

import { Captchi } from '/vendor/captchi/captchi.js';

const widget = Captchi.render('#captchi-widget', {
  siteKey: 'REPLACE_WITH_SITE_KEY',
  action: 'sign_in',
  apiBaseUrl: 'https://api.captchi.ir',
  language: 'fa',
  theme: 'auto',
});

// On submit, await widget.execute() and send the returned response
// to your authenticated application server for Siteverify.

برای iOS و Android از صفحهٔ وب امن داخل WebView استفاده کنید که hostname آن در پنل ثبت شده است، یا flow تأیید را در وب‌سرور خودتان میزبانی کنید. SDK بومی Swift، Kotlin و React Native در مخزن موجود نیست. کلید محرمانه و منطق پذیرش باید روی backend برنامه باقی بمانند.

در SPA هنگام unmount کردن کامپوننت، widget.remove() را صدا بزنید. پس از خطای ارسال، widget.reset() را فراخوانی کنید تا برای تلاش بعدی توکن تازه گرفته شود.

تنظیمات سایت و حالت‌های تأیید

تنظیمات هر سایت

  • Hostname دامنه‌ای که ویجت در آن اجرا می‌شود. مقدار را از ورودی کاربر دریافت نکنید و هنگام Siteverify hostname مورد انتظار خود را بفرستید.
  • Action شناسهٔ کاری کوتاه مانند sign_in، checkout یا contact_form. حروف کوچک، عدد، خط تیره و زیرخط مجازند و شناسه باید با حرف آغاز شود.
  • Site Key کلید عمومی برای SDK مرورگر.
  • Secret Key برای Siteverify سمت سرور. در پنل فقط هنگام ایجاد یا چرخش کلید نمایش داده می‌شود؛ آن را به‌صورت secret در سرور نگه دارید.
  • Verification mode سیاست تصمیم‌گیری برای سایت. تغییرش از تنظیمات همان سایت در پنل انجام می‌شود.

حالت‌های تأیید

auto
تصمیم سرور بر پایهٔ تنظیمات و ارزیابی ریسک، عبور یا نمایش چالش را تعیین می‌کند.
invisible
درخواست واجد شرایط می‌تواند بدون تعامل چالش عبور کند؛ تصمیم همچنان در سرور است.
managed
سرور بر پایهٔ سیاست ریسک خودش تعیین می‌کند چه زمانی چالش لازم است.
always
برای درخواست‌های پذیرفته‌شده چالش تعاملی درخواست می‌شود.
score_only
ارزیابی ریسک در پاسخ Siteverify سمت سرور ارائه می‌شود. امتیاز را فقط در backend و همراه با قاعدهٔ تصمیم خودتان مصرف کنید.

تنظیمات نصب خودمیزبان

این متغیرها برای اپلیکیشن سرور کپتچی هستند، نه برای نصب‌کننده‌های SDK. نمونهٔ کامل و مقادیر پیش‌فرض در .env.example مخزن است. مقادیر حساس را با secret manager محیط خود جایگزین کنید.

# Provider and short-lived runtime state
CAPTCHI_CHALLENGE_PROVIDER=altcha
CAPTCHI_RUNTIME_STATE_DRIVER=auto

# Generate unique, private values for this deployment
CAPTCHI_ALTCHA_HMAC_SECRET=REPLACE_WITH_RANDOM_SECRET
CAPTCHI_SECRET_KEY_PEPPER=REPLACE_WITH_RANDOM_SECRET
CAPTCHI_RESPONSE_TOKEN_PEPPER=REPLACE_WITH_RANDOM_SECRET
CAPTCHI_PRIVACY_PEPPER=REPLACE_WITH_RANDOM_SECRET

# Set the environment explicitly
CAPTCHI_ENV=production
  • CAPTCHI_CHALLENGE_PROVIDER از altcha یا first-party پشتیبانی می‌کند.
  • CAPTCHI_RUNTIME_STATE_DRIVER یکی از auto، redis یا mysql است. حالت auto Redis را در صورت دسترسی انتخاب می‌کند و به MySQL بازمی‌گردد.
  • اتصال MySQL منبع پایدار تنظیمات و داده است. Redis فقط وضعیت موقت را نگه می‌دارد و اختیاری است.
  • کلیدهای CAPTCHI_*_PEPPER و HMAC باید منحصربه‌فرد، با entropy مناسب و خارج از مخزن باشند. چرخاندن آن‌ها نیازمند برنامهٔ عملیاتی جداگانه است.
  • کلیدهای نمونهٔ ct_test_* فقط برای محیط local و testing هستند و در production یا staging پذیرفته نمی‌شوند.

متغیرهای تکمیلی سرور

برای نصب خودمیزبان، APP_ENV و CAPTCHI_ENV را متناسب با محیط تنظیم کنید. محیط production یا staging، کلیدهای تست را غیرفعال می‌کند. CAPTCHI_PUBLIC_BASE_URL نشانی عمومی پنل برای لینک‌های ایمیل است. محدودیت‌های نرخ و نگهداری رویدادها در .env.example مستند شده‌اند؛ مقدار آن‌ها را با ظرفیت و ترافیک واقعی تنظیم کنید.

شناسهٔ Site و Action، hostnameهای مجاز، verification mode، دامنه‌ها و چرخش کلیدها از پنل همان سایت مدیریت می‌شوند، نه از تنظیمات JavaScript. secretهای سرور مانند pepperها فقط در محیط سرور قرار می‌گیرند.

مرجع متغیرهای سرور Captchi

این متغیرها را فقط در محیط سرور یا تنظیمات امن Pinoox قرار دهید. مقادیر زیر پیش‌فرض کد هستند؛ متغیرهای بدون پیش‌فرض باید صریح تنظیم شوند. پس از تغییر تنظیمات، سرویس PHP را طبق روش استقرار خود reload کنید.

محیط، دامنه‌ها و ارائه‌دهنده
APP_ENV و CAPTCHI_ENV
نام محیط؛ برای سرور زنده production بگذارید. اگر CAPTCHI_ENV خالی باشد، سیاست کلید تست از APP_ENV پیروی می‌کند؛ کلیدهای آزمایشی فقط در local، test و testing مجازند.
CAPTCHI_API_DOMAIN، CAPTCHI_PANEL_DOMAIN
نام میزبان API و پنل؛ پیش‌فرض به‌ترتیب api.captchi.ir و panel.captchi.ir است. فقط وقتی دامنهٔ سفارشی دارید تغییرشان دهید.
CAPTCHI_ADMIN_DOMAIN
نام میزبان اختیاری کنسول اپراتور؛ در حالت خالی، کنسول روی hostname جداگانه route نمی‌شود. DNS و TLS آن باید پیش از فعال‌سازی آماده باشد.
CAPTCHI_CHALLENGE_PROVIDER
نوع ارائه‌دهنده: altcha (پیش‌فرض) یا first-party. گزینهٔ دوم چالش‌های تعاملی کپچی را فعال می‌کند.
CAPTCHI_RUNTIME_STATE_DRIVER
محل وضعیت موقت: auto (پیش‌فرض؛ Redis در دسترس و در غیر این صورت MySQL)، redis یا mysql.
CAPTCHI_ADMIN_JWT_SECRET
کلید امضای نشست کنسول اپراتور؛ مقدار تصادفی یکتا با حداقل ۳۲ بایت بسازید و مستقل از PINOOX_JWT_SECRET نگه دارید. برای دسترسی کنسول لازم است.
کلیدهای محرمانهٔ سرویس
CAPTCHI_SECRET_KEY_PEPPER
pepper برای هش کلیدهای محرمانهٔ سایت.
CAPTCHI_RESPONSE_TOKEN_PEPPER
pepper برای پاسخ‌های یک‌بارمصرف Captchi.
CAPTCHI_PRIVACY_PEPPER
pepper برای داده‌های حریم خصوصی و شناسه‌های رویداد.
CAPTCHI_ALTCHA_HMAC_SECRET
کلید HMAC ارائه‌دهندهٔ ALTCHA؛ در صورت انتخاب altcha لازم است.
CAPTCHI_IDENTITY_MAIL_ENCRYPTION_KEY
کلید رمزنگاری outbox ایمیل هویت؛ باید Base64URL بدون padding با ۶۴ نویسه باشد.

برای ساخت امن secretهای گمشده اجرا کنید: php pinoox captchi:configure --generate-missing. مقدار کلیدها در خروجی چاپ نمی‌شود و در تنظیمات سمت‌سرور Pinoox ذخیره می‌شود. مقدارهای replace-locally نمونه‌اند و در سرور قابل استفاده نیستند؛ secret موجود را با تغییر اتفاقی عوض نکنید.

محدودیت درخواست و نگهداری داده
CAPTCHI_UNKNOWN_TARGET_GLOBAL_LIMIT_PER_MINUTE
حد درخواست برای site key ناشناخته؛ پیش‌فرض ۳۶۰۰ در دقیقه، بازهٔ پذیرفته‌شده ۱۰۰ تا ۱۰۰۰۰۰.
CAPTCHI_RUNTIME_TARGET_LOOKUP_IP_LIMIT_PER_MINUTE
حد جست‌وجوی target برای هر IP؛ پیش‌فرض ۳۶۰۰ در دقیقه، بازهٔ ۱۰۰ تا ۱۰۰۰۰۰.
CAPTCHI_SITE_CHALLENGE_CREATE_LIMIT_PER_MINUTE
حد ساخت چالش برای هر سایت؛ پیش‌فرض ۱۲۰ در دقیقه، بازهٔ ۱۰۰ تا ۱۰۰۰۰۰.
CAPTCHI_SITEVERIFY_PREAUTH_IP_LIMIT_PER_MINUTE
سقف پیش‌بررسی Siteverify برای هر IP؛ پیش‌فرض ۳۶۰۰ در دقیقه، بازهٔ ۱۰۰ تا ۱۰۰۰۰۰.
CAPTCHI_SITEVERIFY_UNKNOWN_CREDENTIAL_LIMIT_PER_MINUTE
حد اعتبارنامهٔ ناشناخته؛ پیش‌فرض ۳۶۰۰ در دقیقه، بازهٔ ۱۰۰ تا ۱۰۰۰۰۰.
CAPTCHI_SITEVERIFY_SITE_LIMIT_PER_MINUTE
حد کلی Siteverify برای هر سایت؛ پیش‌فرض ۳۶۰۰ در دقیقه، بازهٔ ۱۰۰ تا ۱۰۰۰۰۰. حد Siteverify برای هر IP در کد ثابت و برابر ۶۰ در دقیقه است.
CAPTCHI_VERIFICATION_EVENT_RETENTION_DAYS
مدت نگهداری رویدادهای تأیید؛ پیش‌فرض ۷ روز، بازهٔ ۱ تا ۹۰ روز.
CAPTCHI_HEALTH_SNAPSHOT_RETENTION_DAYS و CAPTCHI_HEALTH_RESOLVED_ALERT_RETENTION_DAYS
مدت نگهداری snapshot سلامت و هشدارهای رفع‌شده؛ پیش‌فرض به‌ترتیب ۳۰ و ۹۰ روز، بازهٔ هرکدام ۱ تا ۳۶۵ روز.
ایمیل، هشدار و دموی سرور
CAPTCHI_MAILER_DSN
آدرس حمل‌ونقل SMTP یا SMTPS برای ایمیل‌های پنل؛ نمونهٔ توسعه smtp://mailpit:1025 است. برای production از SMTPS و اعتبارنامهٔ مدیریت‌شده استفاده کنید.
CAPTCHI_MAIL_FROM
نشانی فرستندهٔ ایمیل پنل، به قالب mailbox معتبر.
CAPTCHI_PUBLIC_BASE_URL
نشانی HTTPS عمومی پنل با مسیر /panel؛ لینک ایمیل‌ها از آن ساخته می‌شود. HTTP فقط برای loopback در محیط local/testing مجاز است.
CAPTCHI_HEALTH_ALERT_MAIL_ENABLED
ارسال هشدار ایمیلی خاموش است (0)؛ برای روشن‌کردن مقدار 1 بگذارید.
CAPTCHI_HEALTH_ALERT_MAIL_DSN، CAPTCHI_HEALTH_ALERT_MAIL_RECIPIENT، CAPTCHI_HEALTH_ALERT_MAIL_SENDER
تنظیمات SMTP و mailbox گیرنده/فرستندهٔ هشدار. مقادیر Mailpit و example.test فقط برای local/test هستند؛ production به SMTPS روی پورت ۴۶۵ و دو mailbox واقعی مدیریت‌شده نیاز دارد.
CAPTCHI_DEMO_ENABLED
دموی زنده به‌طور پیش‌فرض خاموش است (0)؛ فقط با مقدار 1 فعال می‌شود.
CAPTCHI_DEMO_HOSTNAME، CAPTCHI_DEMO_SITE_KEY، CAPTCHI_DEMO_SECRET_KEY
hostname و کلیدهای اختصاصی سایت آزمایشی. کلید محرمانه فقط در backend بماند و از کلیدهای سایت واقعی استفاده نکنید.
CAPTCHI_DEMO_TRUSTED_REMOTE_ADDRESS
آدرس peer اختیاری برای proxy محلی؛ فقط وقتی ingress به loopback محدود است تنظیم شود.
CAPTCHI_LOCAL_SAMPLE_ADMIN، CAPTCHI_LOCAL_SAMPLE_SITE و CAPTCHI_LOCAL_BASE_URL
تنظیمات seed برای حساب/سایت نمونهٔ محلی؛ فقط در توسعه و تست استفاده شوند، نه production. CAPTCHI_LOCAL_BASE_URL آدرس نصب محلی را مشخص می‌کند و پیش‌فرض آن http://127.0.0.1:8099 است.

ظاهر SDK

گزینهٔ language به‌طور پیش‌فرض fa و گزینهٔ theme یکی از auto، light یا dark است. این گزینه‌ها ظاهر ویجت را تغییر می‌دهند، نه سیاست امنیتی سایت.

تست اتصال

API عمومی روی https://api.captchi.ir/api/v1 قرار دارد. SDK برای دریافت تصمیم از GET /runtime-config و برای چالش از POST /challenges و POST /challenges/complete استفاده می‌کند. Siteverify فقط از سرور برنامه فراخوانی می‌شود.

پاسخ موفق چالش یک توکن ct_resp_… با عمر ۱۲۰ ثانیه می‌دهد. توکن یک‌بارمصرف است و باید در همان hostname و action تأیید شود. هنگام پاسخ ناموفق یا timeout، دادهٔ فرم را نپذیرید و برای تلاش تازه ویجت را reset کنید.

  1. روی محیط توسعه، فرم را با کلید و دامنهٔ همان محیط ارسال کنید و پذیرش فرم پس از تأیید سرور را بررسی کنید. از کلیدهای fixture فقط در local یا testing استفاده کنید.
  2. در تست سمت سرور، درخواست بدون توکن را بررسی کنید. پردازش فرم باید متوقف شود.
  3. قطع ارتباط با API را در محیط توسعه شبیه‌سازی کنید. فرم باید پیام تلاش دوباره بدهد و دادهٔ آن پردازش نشود.
  4. برای هر تلاش تازه توکن جدید بگیرید. در فرم تک‌صفحه‌ای پس از پایان تلاش، widget.reset() را فراخوانی کنید.

نمونه‌های آموزشی روش‌های کپچا را در صفحهٔ پیش‌نمایش ببینید.

رفع خطا

invalid_secret
کلید محرمانهٔ فعال و تعلق آن به سایت را در تنظیمات سرور بررسی کنید.
hostname_mismatch / action_mismatch
نام میزبان و نام اقدام را با تنظیمات پنل و مقدار مورد انتظار سرور تطبیق دهید.
invalid_token / token_replay
بررسی را دوباره آغاز کنید تا توکن تازه صادر شود.
service_unavailable / rate_limited
پردازش فرم را متوقف کنید و امکان تلاش دوباره را پس از مدتی فراهم کنید.

کد خطا در data.error_code یا error.code قرار می‌گیرد. برای پیگیری، request_id را همراه کد خطا ثبت کنید و توکن یا کلید محرمانه را در گزارش نیاورید.