npm package: @isatispooya/faracaptcha
Description: A modern captcha package for React apps
Author: Isatispooya CO
Latest version: 0.1.5



# **مستندات پکیج کپچا چندنوعی (faracaptcha)**


این پکیج یک مجموعه کامل از کپچاهای خلاقانه و امن را ارائه می‌دهد که می‌تواند در پروژه‌های React و Django استفاده شود. هدف اصلی:

* جلوگیری از ربات‌ها و فعالیت‌های غیرانسانی
* فراهم کردن تجربه کاربری جذاب و تعاملی
* آماده انتشار در **NPM** و فروش به صورت پکیج

پکیج شامل چند نوع کپچا است: ایموجی، متنی، صوتی، اسلایدی/پازل و پیدا کردن اشیاء در تصویر.

---

## 2. معماری کلی

### Frontend

* **React** (Client-side)
* وظایف:

  * نمایش کپچا به کاربر
  * جمع‌آوری رفتار کاربر (mouse path، زمان کلیک، drag، draw)
  * ارسال جواب به سرور

### Backend

* **Django** (Server-side)
* وظایف:

  * تولید چالش‌ها (challenge)
  * امضا و ارسال token امن به فرانت
  * بررسی جواب کاربر با توجه به secret سرور
  * ذخیره‌سازی پاسخ‌ها برای بررسی یکبار مصرف بودن
  * جمع‌آوری سیگنال‌ها و امتیازدهی برای تشخیص انسان/ربات

### امنیت

* تمام جواب‌ها و challengeها **در سرور نگهداری می‌شوند**
* استفاده از **token امن (HMAC/JWT)** برای جلوگیری از جعل پاسخ
* یکبار مصرف بودن چالش‌ها و expiration
* جمع‌آوری سیگنال‌های رفتاری و IP و Session برای تشخیص ربات

---

## 3. نوع کپچاها و جزئیات پیاده‌سازی

### 3.1 کپچا ایموجی (Emoji CAPTCHA)

**هدف:** انتخاب ایموجی صحیح بر اساس تصویر

* **فرانت:**

  * تصویر + چند ایموجی نمایش داده می‌شود
  * کاربر روی ایموجی صحیح کلیک می‌کند
  * مسیر کلیک و زمان انجام فعالیت جمع‌آوری می‌شود

* **بک‌اند:**

  * بررسی جواب با توجه به `expected emoji`
  * استفاده از token برای جلوگیری از جعل
  * ذخیره اطلاعات challenge و markUsed برای replay protection

* **جواب:**

  * ایموجی انتخاب شده توسط کاربر
  * مسیر حرکت ماوس و زمان کلیک (Behavioral signals)

* **ویژگی‌ها:**

  * تعداد ایموجی‌ها رندوم
  * تصاویر متنوع و قابل گسترش
  * امن در برابر replay و دستکاری پاسخ

---

### 3.2 کپچا متنی (Text CAPTCHA)

**هدف:** نمایش متن به صورت SVG برای جلوگیری از OCR ساده

* **فرانت:**

  * متن SVG دریافت و نمایش داده می‌شود
  * کاربر متن را در input وارد می‌کند

* **بک‌اند:**

  * متن صحیح (expected text) را با جواب کاربر مقایسه می‌کند
  * token و expiration برای جلوگیری از جعل
  * replay protection

* **ویژگی‌ها:**

  * فونت‌ها و distortion قابل تغییر
  * طول متن و سختی قابل تنظیم
  * امن در برابر کپچر خوان‌ها

---

### 3.3 کپچا صوتی (Audio CAPTCHA)

**هدف:** حل کپچا با شنیدن صدا (دسترس‌پذیری برای کاربرانی که مشکل بینایی دارند)

* **فرانت:**

  * فایل صوتی (MP3/WAV) پخش می‌شود
  * کاربر جواب را وارد می‌کند
  * می‌تواند مسیر یا زمان پاسخ ضبط شود (اختیاری)

* **بک‌اند:**

  * تولید صدا با متن تصادفی
  * رمزگذاری متن صحیح در سرور
  * بررسی جواب با token امن و expiration
  * یکبار مصرف بودن challenge

* **ویژگی‌ها:**

  * قابل تنظیم: طول صدا، نوع افکت‌ها، نویز پس‌زمینه
  * امن در برابر ربات‌های ساده

---

### 3.4 کپچا اسلایدی با پازل (Slider Puzzle CAPTCHA)

**هدف:** تکمیل تصویر با قرار دادن قطعه پازل در جای صحیح

* **فرانت:**

  * تصویر اصلی + قطعه پازل نمایش داده می‌شود
  * کاربر باید قطعه را روی موقعیت درست drag کند
  * مسیر drag و زمان انجام ذخیره می‌شود

* **بک‌اند:**

  * پاسخ صحیح: موقعیت x,y قطعه
  * بررسی دقیق موقعیت با tolerance (مثلاً ±5 پیکسل)
  * replay protection و token امن

* **ویژگی‌ها:**

  * تصاویر قابل رندوم‌سازی
  * سختی با اندازه قطعه و جابجایی قابل تنظیم
  * رفتار انسان/ربات تحلیل می‌شود

---

### 3.5 کپچا پیدا کردن شیء در عکس (Object Recognition CAPTCHA)

**هدف:** پیدا کردن شیء مشخص در تصویر

* **فرانت:**

  * تصویر نمایش داده می‌شود
  * کاربر روی نقطه‌ای که شیء قرار دارد کلیک می‌کند
  * مختصات کلیک و زمان ثبت می‌شود

* **بک‌اند:**

  * پاسخ صحیح: مختصات یا bounding box شیء
  * بررسی با tolerance ±X پیکسل
  * token امن و replay protection

* **ویژگی‌ها:**

  * تصاویر متنوع و قابل رندوم
  * امن در برابر اسکریپت‌های تحلیل تصویر ساده
  * مناسب برای تعامل انسانی واقعی

---

## 4. ویژگی‌های عمومی پکیج

* **چند نوع کپچا در یک پکیج:** Emoji, Text, Audio, Slider/Puzzle, Object
* **امنیت بالا:** token امن، یکبار مصرف، replay protection، behavioral signals
* **پشتیبانی از فرانت React و بک‌اند Django**
* **قابل انتشار در NPM**
* **امکان فروش و استفاده در SaaS یا پروژه‌های بزرگ**
* **تجربه کاربری جذاب و تعاملی**

---

## 5. مسیر توسعه

1. طراحی و آماده‌سازی APIهای backend در Django برای:

   * issueChallenge (ایجاد challenge + token)
   * verifyChallenge (بررسی جواب + behavioral signals)

2. طراحی کامپوننت‌های React برای هر نوع کپچا:

   * دریافت challenge و token از سرور
   * نمایش کپچا و تعامل کاربر
   * جمع‌آوری behavioral signals
   * ارسال جواب برای بررسی

3. تست امنیتی و رفتار ربات‌ها:

   * بررسی جعل token
   * بررسی replay
   * بررسی رفتار غیرانسانی

4. طراحی واسط کاربری:

   * ساده و جذاب
   * Responsive و Mobile-friendly

5. آماده‌سازی برای انتشار:

   * بسته‌بندی NPM
   * مستندسازی APIها و کامپوننت‌ها
   * مثال‌های استفاده و Readme کامل

---

## 6. پیشنهادات تکمیلی

* **Fallback challenge:** اگر سیگنال‌ها مشکوک بودند، کپچا سخت‌تر نمایش داده شود.
* **تجزیه و تحلیل behavioral signals** برای امتیازدهی به کاربر (human score).
* **سیستم رندوم‌سازی:** تصاویر، متن‌ها، پازل‌ها → جلوگیری از الگوریتم‌های ربات.
* **قابلیت توسعه:** افزودن انواع کپچاهای جدید (Math, Pattern, Game)