=== Captchi Human Verification ===
Contributors: captchi
Tags: captcha, security, forms, spam
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.2
License: MIT
License URI: https://opensource.org/license/mit/

اتصال ویجت کپچی به فرم‌های وردپرس و تأیید امن پاسخ در سمت سرور.

== نصب ==

1. فایل ZIP افزونهٔ Captchi را از صفحهٔ مستندات دریافت کنید.
2. در پیشخوان WordPress به افزونه‌ها ← افزودن افزونه ← بارگذاری افزونه بروید.
3. ZIP را بارگذاری، نصب و فعال کنید.
4. از تنظیمات ← Captchi کلید عمومی و کلید محرمانهٔ سایت را وارد کنید.
5. hostname و action مورد استفاده را در پنل کپچی ثبت و فعال کنید.

کلید محرمانه در تنظیمات به‌صورت متن نمایش داده نمی‌شود. برای نگه‌داشتن کلید قبلی، فیلد آن را خالی بگذارید. برای حذف کلید، گزینهٔ حذف را انتخاب کنید.

== قرار دادن ویجت ==

shortcode را داخل فرم قرار دهید:

    [captchi action="contact_form"]

ویجت باید داخل تگ `<form>` رندر شود. افزونه هنگام ارسال فرم، توکن را با SDK کپچی می‌گیرد، در فیلد `captchi_response` قرار می‌دهد و بعد همان فرم را ارسال می‌کند. در هر فرم یک ویجت بگذارید.

ویژگی‌های اختیاری:

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

- `action`: شناسهٔ فعال تعریف‌شده در پنل کپچی؛ حروف کوچک، عدد، خط تیره و زیرخط.
- `language`: یکی از `fa` یا `en`.
- `theme`: یکی از `auto`، `light` یا `dark`.

=== Contact Form 7 ===

اگر Contact Form 7 نصب و فعال باشد، افزونه form-tag کپچی و بررسی سروری را خودکار ثبت می‌کند. در بخش قالب فرم Contact Form 7 این تگ را قرار دهید:

    [captchi captchi_response action:contact_form]

مقدار `action` را با action فعال پنل کپچی جایگزین کنید. فیلد باید `captchi_response` نام داشته باشد. افزونه توکن را هنگام ارسال بررسی می‌کند و در صورت خطای شبکه یا رد Siteverify ارسال ایمیل را متوقف می‌کند. توکن برای ذخیره‌سازی در ماژول‌های Contact Form 7 علامت‌گذاری نمی‌شود.

=== سایر فرم‌سازها ===

برای فرم‌هایی که shortcodeهای WordPress را رندر می‌کنند از `[captchi action="contact_form"]` استفاده کنید. در handler یا hook سروری همان فرم، پیش از پردازش داده‌ها تابع `captchi_verify_submission('contact_form')` را فراخوانی کنید. اگر فرم‌ساز shortcode را فیلتر می‌کند، خروجی ویجت را از hook قالب همان فرم‌ساز قرار دهید.

== تأیید اجباری در سرور ==

وجود فیلد مخفی به‌تنهایی اعتبارسنجی نیست. پیش از ذخیرهٔ فرم، ارسال ایمیل یا انجام پرداخت، Siteverify را فراخوانی کنید. action را به‌صورت ثابت و مورد اعتماد در handler تعیین کنید و از مقدار ارسالی کاربر برای آن استفاده نکنید.

نمونهٔ handler:

    if (!isset($_POST['my_form_nonce']) || !wp_verify_nonce(sanitize_text_field(wp_unslash($_POST['my_form_nonce'])), 'my_form_submit')) {
        wp_die('درخواست معتبر نیست.');
    }

    if (!captchi_verify_submission('contact_form')) {
        wp_die('بررسی امنیتی انجام نشد. فرم را دوباره ارسال کنید.');
    }

    // Continue with normal field validation and form processing.

helper در صورت خطای شبکه، پاسخ نامعتبر، action نامعتبر یا رد Siteverify مقدار `false` می‌دهد. بررسی nonce، اعتبارسنجی فیلدهای فرم و کنترل دسترسی همچنان مسئولیت handler فرم است.

برای تصمیم‌گیری بر پایهٔ risk score در حالت `score_only`:

    $result = Captchi_WordPress::verify_submission('checkout');
    if (!is_array($result)) {
        // Reject the form.
    }
    $risk_score = $result['risk_score'] ?? null;

آستانهٔ پذیرش را در backend و بر اساس سیاست محصول خود تعریف کنید.

== امنیت و حریم خصوصی ==

- کلید محرمانه فقط در درخواست server-to-server به `https://api.captchi.ir/api/v1/siteverify` ارسال می‌شود و در HTML/JavaScript قرار نمی‌گیرد.
- پاسخ توکن یک‌بارمصرف Captchi است؛ آن را در log یا پایگاه داده ذخیره نکنید.
- درخواست Siteverify با TLS، تأیید گواهی و بدون دنبال‌کردن redirect ارسال می‌شود.
- در خطای شبکه یا Siteverify، فرم پذیرفته نمی‌شود.
- پاسخ و secret در گزارش خطا ثبت نمی‌شوند.

== پرسش‌های متداول ==

= ویجت دیده نمی‌شود =

مطمئن شوید افزونه فعال است، کلید عمومی در تنظیمات ذخیره شده، hostname سایت در پنل کپچی ثبت شده و shortcode داخل یک فرم قرار دارد.

= فرم ارسال می‌شود اما همیشه رد می‌شود =

نام action در shortcode، handler و پنل باید دقیقاً یکسان باشد. hostname ثبت‌شده باید با دامنهٔ WordPress یکی باشد. همچنین از فعال‌بودن action و ثبت کلید محرمانه اطمینان بگیرید.

= فرم Contact Form 7 نامعتبر است یا ایمیل ارسال نمی‌شود =

تگ `[captchi captchi_response action:contact_form]` و action را با نام فیلد و action فعال در پنل تطبیق دهید. hostname ثبت‌شده باید با دامنهٔ WordPress یکی باشد.

= آیا همهٔ فرم‌سازها خودکار وصل می‌شوند؟ =

اتصال خودکار نسخهٔ فعلی برای Contact Form 7 فراهم است. سایر فرم‌سازها با shortcode و helper عمومی Siteverify قابل اتصال‌اند؛ محل افزودن ویجت و hook اعتبارسنجی هرکدام فرق دارد.

== Changelog ==

= 1.0.2 =
* اتصال آمادهٔ Contact Form 7 شامل form-tag و اعتبارسنجی Siteverify.

= 1.0.1 =
* Refreshes the install package with the current SDK and WordPress compatibility metadata.

= 1.0.0 =
* افزونهٔ مستقل WordPress با صفحهٔ تنظیمات.
* shortcode ویجت و اتصال SDK ماژولار.
* helper سرور برای Siteverify با رفتار fail-closed.
