Package Exports
- @isatispooya/faracaptcha
- @isatispooya/faracaptcha/dist/index.cjs.js
- @isatispooya/faracaptcha/dist/index.es.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@isatispooya/faracaptcha) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
مستندات پکیج کپچا چندنوعی (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. مسیر توسعه
طراحی و آمادهسازی APIهای backend در Django برای:
- issueChallenge (ایجاد challenge + token)
- verifyChallenge (بررسی جواب + behavioral signals)
طراحی کامپوننتهای React برای هر نوع کپچا:
- دریافت challenge و token از سرور
- نمایش کپچا و تعامل کاربر
- جمعآوری behavioral signals
- ارسال جواب برای بررسی
تست امنیتی و رفتار رباتها:
- بررسی جعل token
- بررسی replay
- بررسی رفتار غیرانسانی
طراحی واسط کاربری:
- ساده و جذاب
- Responsive و Mobile-friendly
آمادهسازی برای انتشار:
- بستهبندی NPM
- مستندسازی APIها و کامپوننتها
- مثالهای استفاده و Readme کامل
6. پیشنهادات تکمیلی
- Fallback challenge: اگر سیگنالها مشکوک بودند، کپچا سختتر نمایش داده شود.
- تجزیه و تحلیل behavioral signals برای امتیازدهی به کاربر (human score).
- سیستم رندومسازی: تصاویر، متنها، پازلها → جلوگیری از الگوریتمهای ربات.
- قابلیت توسعه: افزودن انواع کپچاهای جدید (Math, Pattern, Game)