{"id":50796860,"url":"https://github.com/smouj/captcha-shield","last_synced_at":"2026-06-12T15:01:57.963Z","repository":{"id":352647009,"uuid":"1216017449","full_name":"smouj/captcha-shield","owner":"smouj","description":"CAPTCHA Shield v3.0 - Advanced Anti-Bot/AI CAPTCHA with 14 behavioral signals, 7 challenge types, QR mobile verification. 100% client-side.","archived":false,"fork":false,"pushed_at":"2026-05-11T19:22:14.000Z","size":3575,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-11T19:23:12.263Z","etag":null,"topics":["anti-ai","anti-bot","behavioral-analysis","bot-detection","canvas","captcha","framer-motion","human-verification","nextjs","prisma","react","security","shadcn-ui","tailwindcss","typescript"],"latest_commit_sha":null,"homepage":"https://smouj.github.io/captcha-shield/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smouj.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-20T13:35:50.000Z","updated_at":"2026-05-11T19:22:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/smouj/captcha-shield","commit_stats":null,"previous_names":["smouj/captcha-shield"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/smouj/captcha-shield","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smouj%2Fcaptcha-shield","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smouj%2Fcaptcha-shield/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smouj%2Fcaptcha-shield/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smouj%2Fcaptcha-shield/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smouj","download_url":"https://codeload.github.com/smouj/captcha-shield/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smouj%2Fcaptcha-shield/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34249561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anti-ai","anti-bot","behavioral-analysis","bot-detection","canvas","captcha","framer-motion","human-verification","nextjs","prisma","react","security","shadcn-ui","tailwindcss","typescript"],"created_at":"2026-06-12T15:01:49.301Z","updated_at":"2026-06-12T15:01:57.948Z","avatar_url":"https://github.com/smouj.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cbr /\u003e\n\n\u003cimg src=\"public/logo-shield-white.png\" alt=\"CAPTCHA Shield\" width=\"120\" /\u003e\n\n\u003cbr /\u003e\n\n# 🛡️ CAPTCHA Shield v4.0 \"Fortress\"\n\n### The unbreakable, AI-proof CAPTCHA platform with 10 challenges, 28 behavioral signals, and 7 defense layers\n\n\u003e *Building an impenetrable fortress between humans and bots since v1.0*\n\n\u003cbr /\u003e\n\n[![Version](https://img.shields.io/badge/v4.0.0-9b59b6?style=for-the-badge\u0026label=FORTRESS\u0026labelColor=1a1a2e)](./package.json)\n[![Build Status](https://img.shields.io/badge/CI-Passing-22c55e?style=for-the-badge\u0026logo=github-actions\u0026logoColor=white\u0026labelColor=1a1a2e)](https://github.com/smouj/captcha-shield/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge\u0026labelColor=1a1a2e)](./LICENSE)\n[![npm](https://img.shields.io/badge/npm-captcha--shield-22c55e?style=for-the-badge\u0026logo=npm\u0026logoColor=white\u0026labelColor=1a1a2e)](https://www.npmjs.com/)\n[![Next.js 16](https://img.shields.io/badge/Next.js_16-black?style=for-the-badge\u0026logo=next.js\u0026logoColor=white\u0026labelColor=1a1a2e)](https://nextjs.org/)\n[![TypeScript 5](https://img.shields.io/badge/TypeScript_5-3178C6?style=for-the-badge\u0026logo=typescript\u0026logoColor=white\u0026labelColor=1a1a2e)](https://www.typescriptlang.org/)\n[![React 19](https://img.shields.io/badge/React_19-61DAFB?style=for-the-badge\u0026logo=react\u0026logoColor=black\u0026labelColor=1a1a2e)](https://react.dev/)\n\n\u003cbr /\u003e\n\n**[🚀 Live Demo](https://smouj.github.io/captcha-shield/) · [📦 Server Module](./server/) · [🔒 Security Model](documentation/SECURITY_MODEL.md) · [📝 API Reference](documentation/API.md) · [📝 Changelog](./CHANGELOG.md) · [🤝 Contributing](CONTRIBUTING.md)**\n\n\u003c/div\u003e\n\n---\n\n## 📑 Table of Contents\n\n- [🤔 What is CAPTCHA Shield?](#-what-is-captcha-shield)\n- [🏰 Why v4.0 \"Fortress\"?](#-why-v40-fortress)\n- [🧩 10 AI-Proof Challenges](#-10-ai-proof-challenges)\n- [🧠 28 Behavioral Signals](#-28-behavioral-signals)\n- [🛡️ 7 Defense Layers](#-7-defense-layers)\n- [🚀 Quick Start](#-quick-start)\n- [⚙️ Configuration](#-configuration)\n- [⚛️ React Component](#-react-component)\n- [🔐 Server Verification](#-server-verification)\n- [📖 API Reference](#-api-reference)\n- [🔌 Plugin System](#-plugin-system)\n- [♿ Accessibility](#-accessibility)\n- [🌍 Internationalization](#-internationalization)\n- [🏗️ Architecture](#-architecture)\n- [🔒 Security Model](#-security-model)\n- [🛡️ Verification Modes](#-verification-modes)\n- [🗺️ Roadmap](#-roadmap)\n- [🤝 Contributing](#-contributing)\n- [📜 License](#-license)\n- [📝 Changelog](#-changelog)\n- [🙏 Credits](#-credits)\n\n---\n\n## 🤔 What is CAPTCHA Shield?\n\nCAPTCHA Shield is an **open-source, embeddable anti-bot verification platform** that combines interactive challenges with real-time behavioral analysis to distinguish humans from bots with unprecedented accuracy.\n\n| 🎯 Feature | 💡 Description |\n|-----------|---------------|\n| **10 AI-Proof Challenges** | From adversarial puzzles to zero-knowledge proofs — each designed to defeat modern AI |\n| **28 Behavioral Signals** | Bayesian risk scoring across 7 categories: motor, temporal, device, cognitive, environment, network, biometric |\n| **7 Defense Layers** | Multi-layered verification pipeline from pre-check to cryptographic tokens |\n| **40+ Fingerprint Vectors** | Headless browser detection, WebGL fingerprinting, automation framework identification |\n| **Server Verification Module** | One-line backend integration with HMAC-SHA256 token verification and replay protection |\n| **8 Languages** | English, Spanish, French, German, Portuguese, Japanese, Chinese, Korean |\n| **WCAG 2.2 AA** | Full accessibility with keyboard navigation, screen reader support, and audio fallbacks |\n| **Plugin Architecture** | Extend with custom challenges, signal processors, and renderers |\n\n---\n\n## 🏰 Why v4.0 \"Fortress\"?\n\n\u003e *\"If you think your CAPTCHA can stop GPT-5, you haven't been paying attention.\"*\n\nv4.0 \"Fortress\" is a **complete rewrite** built on one principle: **the era of text-based and image-classification CAPTCHAs is over**. Modern AI can solve reCAPTCHA v2 in under 5 seconds. Fortress fights back with challenges that exploit what AI fundamentally lacks:\n\n| 🧠 Human Strength | 🤖 AI Weakness | Fortress Exploits |\n|-------------------|----------------|-------------------|\n| Intuition \u0026 gut feeling | Requires training data | Human Intuition Grid, Contextual Reasoning |\n| Physical world understanding | No embodied experience | Physics Chaos, Optical Illusion Maze |\n| Episodic memory | No subjective experience | Temporal Memory |\n| Motor imperfection | Perfectly linear movements | Gesture Signature, Live 3D Biometric |\n| Common sense | No causal reasoning | Contextual Reasoning |\n| Rhythm \u0026 synchronization | No embodied timing | Voice Rhythm |\n| Creative problem-solving | Pattern-matching only | Zero-Knowledge Proof |\n\n### What Changed from v3.x\n\n| | v3.x | v4.0 \"Fortress\" |\n|---|------|-----------------|\n| Challenges | 7 traditional | **10 AI-proof** with adversarial noise |\n| Behavioral Signals | 14 | **28** across 7 categories |\n| Risk Scoring | Weighted average | **Bayesian inference** with prior probabilities |\n| Token Format | Client-only | **HMAC-SHA256 JWT** with server verification |\n| Replay Protection | None | **Nonce-based** with 2-minute TTL |\n| Headless Detection | Basic | **20 detection vectors** with weighted scoring |\n| Plugin System | None | **Full plugin architecture** with lifecycle hooks |\n| i18n | 2 languages | **8 languages** |\n| Accessibility | Partial | **WCAG 2.2 AA** compliant |\n| Server Module | Planned | **Shipped** — Express, Next.js, standalone |\n\n---\n\n## 🧩 10 AI-Proof Challenges\n\nEach challenge is engineered with **adversarial noise**, **dynamic difficulty**, and **behavioral validation** to be trivial for humans but near-impossible for AI.\n\n| # | Challenge | Category | AI Resistance | Avg Time | Description |\n|---|-----------|----------|:-------------:|:--------:|-------------|\n| 1 | 🧩 **Adversarial Puzzle** | Visual | ⭐ 0.82 | 18s | Canvas-rendered sliding puzzle with adversarial noise overlays, distortion fields, and decoy edges designed to confuse automated solvers |\n| 2 | 🔲 **Human Intuition Grid** | Cognitive | ⭐ 0.91 | 8s | A 4×4 grid where one cell subtly differs — trivial for human intuition, extremely hard for AI pattern matching |\n| 3 | ⚖️ **Physics Chaos** | Interactive | ⭐ 0.88 | 22s | Balance objects on a virtual beam — tests understanding of gravity, mass, and equilibrium |\n| 4 | 🧠 **Temporal Memory** | Cognitive | ⭐ 0.75 | 12s | Items flash for 1.8s — reproduce the exact order from memory using human episodic memory |\n| 5 | 🌀 **Optical Illusion Maze** | Visual | ⭐ 0.93 | 25s | Navigate a maze with Moiré patterns and impossible figures that trick computer vision but are filtered by human perception |\n| 6 | 🎵 **Voice Rhythm** | Audio | ⭐ 0.85 | 15s | Listen to an audio rhythm pattern and repeat it by tapping — tests temporal auditory processing |\n| 7 | ✍️ **Gesture Signature** | Biometric | ⭐ 0.87 | 10s | Draw a gesture with natural human movement — analyzes stroke dynamics, speed variance, and micro-tremors |\n| 8 | 🤔 **Contextual Reasoning** | Cognitive | ⭐ 0.94 | 14s | \"What happens next?\" — requires common-sense reasoning about physical and social causality |\n| 9 | 🎲 **Live 3D Biometric** | Biometric | ⭐ 0.90 | 16s | Rotate a 3D object to match target orientation — the rotation path must show natural acceleration curves |\n| 10 | 🔐 **Zero-Knowledge Proof** | Crypto | ⭐ 0.96 | 28s | Hybrid challenge combining proof-of-work hash puzzle with visual discrimination — ensures both computational effort and human involvement |\n\n\u003e 💡 **AI Resistance Score**: 0 = trivial for AI, 1 = impossible for current AI. All scores benchmarked against GPT-4V, Claude 3.5, and Gemini 1.5 Pro.\n\n### Difficulty Scaling\n\nEach challenge dynamically adjusts based on the user's risk score:\n\n| Risk Level | Difficulty | Puzzle Pieces | Time Limit | Tolerance |\n|-----------|-----------|:------------:|:----------:|:---------:|\n| 🟢 Low | Easy | 2 | 30s | ±8px |\n| 🟡 Medium | Medium | 3 | 25s | ±5px |\n| 🟠 High | Hard | 4 | 20s | ±3px |\n| 🔴 Critical | Extreme | 5 | 15s | ±2px |\n\n---\n\n## 🧠 28 Behavioral Signals\n\n28 weighted signals across 7 categories produce a **Bayesian risk score** that's far more accurate than simple threshold checks.\n\n### 🖱️ Motor Signals (8)\n\n| # | Signal | Weight | Human Range | Bot Range | Description |\n|---|--------|:------:|:-----------:|:---------:|-------------|\n| 1 | Mouse Path Linearity | 0.08 | 0.2–0.8 | 0.85–1.0 | How curved/linear the mouse path is — bots move in straight lines |\n| 2 | Mouse Speed Variance | 0.07 | 0.3–0.9 | 0.0–0.1 | Variance in mouse movement speed — bots are constant |\n| 3 | Mouse Acceleration Pattern | 0.06 | 0.3–0.8 | 0.0–0.15 | Acceleration/deceleration curves — humans decelerate into targets |\n| 4 | Pointer Precision | 0.05 | 0.3–0.85 | 0.9–1.0 | Click precision relative to target center — bots click dead-center |\n| 5 | Pointer Pressure | 0.04 | 0.2–0.8 | 0.0–0.05 | Touch/pen pressure variance — bots have zero pressure |\n| 6 | Click Precision | 0.05 | 0.3–0.7 | 0.85–1.0 | How centered clicks are on targets |\n| 7 | Scroll Behavior | 0.04 | 0.2–0.8 | 0.0–0.1 | Scroll speed and pattern naturalness |\n| 8 | Gesture Smoothness | 0.05 | 0.4–0.9 | 0.0–0.2 | Smoothness of gesture/drag movements — bots are jerky or too perfect |\n\n### ⏱️ Temporal Signals (6)\n\n| # | Signal | Weight | Human Range | Bot Range | Description |\n|---|--------|:------:|:-----------:|:---------:|-------------|\n| 9 | Timing Consistency | 0.07 | 0.3–0.8 | 0.9–1.0 | Inter-action timing variance — bots are unnaturally consistent |\n| 10 | Reaction Time | 0.06 | 0.2–0.7 | 0.0–0.1 | Time to first action after stimulus — bots respond instantly |\n| 11 | Hesitation Pattern | 0.05 | 0.3–0.8 | 0.0–0.1 | Micro-pauses before decisions — humans hesitate, bots don't |\n| 12 | Inter-Event Interval | 0.04 | 0.3–0.9 | 0.0–0.1 | Time between sequential events |\n| 13 | Task Completion Rhythm | 0.04 | 0.3–0.8 | 0.0–0.15 | Overall rhythm pattern of task completion |\n| 14 | Temporal Anomaly | 0.06 | 0.1–0.6 | 0.7–1.0 | Statistical anomaly in timing distribution |\n\n### 💻 Device Signals (6)\n\n| # | Signal | Weight | Human Range | Bot Range | Description |\n|---|--------|:------:|:-----------:|:---------:|-------------|\n| 15 | Device Fingerprint | 0.05 | 0.8–1.0 | 0.0–0.3 | Device fingerprint consistency |\n| 16 | Screen Resolution | 0.03 | 0.7–1.0 | 0.0–0.3 | Screen resolution vs user agent consistency |\n| 17 | Timezone Consistency | 0.03 | 0.8–1.0 | 0.0–0.4 | Timezone match between system and settings |\n| 18 | Battery API | 0.02 | 0.3–1.0 | 0.0–0.1 | Battery API availability and values |\n| 19 | Sensor Fusion | 0.03 | 0.4–1.0 | 0.0–0.1 | Accelerometer/gyroscope data presence |\n| 20 | WebRTC Fingerprint | 0.04 | 0.7–1.0 | 0.0–0.3 | WebRTC local IP fingerprint |\n\n### 🧩 Cognitive Signals (4)\n\n| # | Signal | Weight | Human Range | Bot Range | Description |\n|---|--------|:------:|:-----------:|:---------:|-------------|\n| 21 | Decision Latency | 0.05 | 0.3–0.8 | 0.0–0.1 | Time taken to make decisions |\n| 22 | Error Correction | 0.04 | 0.2–0.7 | 0.0–0.05 | Self-correction behavior — humans make and fix mistakes |\n| 23 | Pattern Recognition | 0.04 | 0.3–0.8 | 0.9–1.0 | How the user recognizes visual patterns — bots are too consistent |\n| 24 | Entropy Score | 0.05 | 0.5–1.0 | 0.0–0.3 | Entropy of behavioral data distribution |\n\n### 🌐 Environment Signals (2)\n\n| # | Signal | Weight | Human Range | Bot Range | Description |\n|---|--------|:------:|:-----------:|:---------:|-------------|\n| 25 | Tab Visibility | 0.03 | 0.7–1.0 | 0.0–0.3 | Tab focus/visibility changes — bots never switch tabs |\n| 26 | Environment Consistency | 0.03 | 0.7–1.0 | 0.0–0.3 | Browser environment consistency checks |\n\n### 🌍 Network Signal (1)\n\n| # | Signal | Weight | Human Range | Bot Range | Description |\n|---|--------|:------:|:-----------:|:---------:|-------------|\n| 27 | Connection Fingerprint | 0.02 | 0.5–1.0 | 0.0–0.3 | Connection type and round-trip consistency |\n\n### 🔑 Biometric Signal (1)\n\n| # | Signal | Weight | Human Range | Bot Range | Description |\n|---|--------|:------:|:-----------:|:---------:|-------------|\n| 28 | Keyboard Dynamics | 0.06 | 0.3–0.8 | 0.0–0.1 | Typing rhythm and pressure patterns |\n\n### Bayesian Risk Scoring\n\nUnlike simple weighted averages, Fortress uses **Bayesian inference** to compute the probability that a user is a bot:\n\n```\nP(bot | signals) = P(signals | bot) × P(bot) / P(signals)\n\nWhere:\n  P(bot) = 0.15           (prior probability)\n  P(signals | bot) = ∏ P(sᵢ | bot)^wᵢ   (weighted likelihood)\n  P(signals | human) = ∏ P(sᵢ | human)^wᵢ\n```\n\n| 🟢 Low Risk | 🟡 Medium Risk | 🟠 High Risk | 🔴 Critical |\n|:-----------:|:--------------:|:------------:|:-----------:|\n| \u003c 0.25 | 0.25–0.50 | 0.50–0.80 | \u003e 0.80 |\n| Pass through | Additional challenge | Enhanced verification | Blocked |\n\n---\n\n## 🛡️ 7 Defense Layers\n\nThe Fortress architecture implements **defense in depth** — every request passes through 7 independent verification layers before a token is issued.\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    REQUEST ENTERS                            │\n└──────────────────────┬──────────────────────────────────────┘\n                       │\n          ┌────────────▼────────────┐\n          │  Layer 1: BEHAVIORAL    │  28 signals analyzed\n          │  PRECHECK               │  Bayesian risk scoring\n          │  Risk: 0.0 → Pass      │  20+ headless detection vectors\n          │  Risk: 1.0 → Block     │\n          └────────────┬────────────┘\n                       │\n          ┌────────────▼────────────┐\n          │  Layer 2: DYNAMIC       │  Challenge selected by risk level\n          │  CHALLENGE              │  10 AI-proof challenge types\n          │  Solution verified      │  Adaptive difficulty\n          │  Behavioral data checked│\n          └────────────┬────────────┘\n                       │\n          ┌────────────▼────────────┐\n          │  Layer 3: QR MOBILE     │  Triggered for medium+ risk\n          │  VERIFICATION           │  Scan QR + enter 6-digit code\n          │  Second device proof    │  Time-limited codes\n          └────────────┬────────────┘\n                       │\n          ┌────────────▼────────────┐\n          │  Layer 4: WEBAUTHN      │  Passkey-based verification\n          │  PASSKEY                │  Hardware-backed authentication\n          │  Biometric proof        │  Platform authenticator support\n          └────────────┬────────────┘\n                       │\n          ┌────────────▼────────────┐\n          │  Layer 5: CRYPTOGRAPHIC │  HMAC-SHA256 token signing\n          │  TOKEN                  │  60-second TTL\n          │  Single-use nonce (jti) │  Base64url JWT format\n          └────────────┬────────────┘\n                       │\n          ┌────────────▼────────────┐\n          │  Layer 6: REPLAY        │  Nonce-based replay detection\n          │  PROTECTION             │  2-minute deduplication window\n          │  Server-side JTI store  │  Automatic TTL cleanup\n          └────────────┬────────────┘\n                       │\n          ┌────────────▼────────────┐\n          │  Layer 7: RATE          │  Per-IP and per-session limits\n          │  LIMITING               │  Exponential backoff\n          │  Cooldown periods       │  Progressive challenge escalation\n          └────────────┬────────────┘\n                       │\n                       ▼\n              ✅ TOKEN ISSUED\n```\n\n---\n\n## 🚀 Quick Start\n\n### 1. Embed in Any Page (2 lines)\n\n```html\n\u003cdiv id=\"captcha-shield\"\u003e\u003c/div\u003e\n\u003cscript src=\"https://smouj.github.io/captcha-shield/widget.js\"\u003e\u003c/script\u003e\n```\n\n### 2. Handle Verification\n\n```html\n\u003cscript\u003e\n  window.onCaptchaVerified = function(token) {\n    // Send token to your server for verification\n    fetch('/api/protected', {\n      method: 'POST',\n      body: JSON.stringify({ captchaToken: token })\n    });\n  };\n\u003c/script\u003e\n```\n\nThat's it. CAPTCHA Shield handles everything else — behavioral analysis, challenge selection, risk scoring, and token generation.\n\n---\n\n## ⚙️ Configuration\n\n```typescript\ninterface WidgetConfig {\n  // ─── Core ─────────────────────────────────────────────\n  mode: 'light' | 'fortress' | 'hybrid';  // Default: 'fortress'\n  maxAttempts: number;                      // Default: 2\n  language: string;                         // Default: 'en'\n  \n  // ─── Appearance ───────────────────────────────────────\n  theme: 'light' | 'dark' | 'auto';        // Default: 'auto'\n  size: 'micro' | 'compact' | 'normal' | 'full';  // Default: 'normal'\n  accentColor: string;                      // Default: '#10b981'\n  borderRadius: number;                     // Default: 12\n  \n  // ─── Behavior ─────────────────────────────────────────\n  showRiskMeter: boolean;                   // Default: true\n  accessibilityMode: boolean;               // Default: false\n  \n  // ─── Server Integration ──────────────────────────────\n  serverVerifyUrl?: string;                 // Your backend endpoint\n  \n  // ─── Callbacks ────────────────────────────────────────\n  onVerify?: (token: CaptchaToken) =\u003e void;\n  onError?: (error: Error) =\u003e void;\n}\n```\n\n### Default Configuration\n\n```typescript\nconst DEFAULT_WIDGET_CONFIG: WidgetConfig = {\n  mode: 'fortress',\n  maxAttempts: 2,\n  language: 'en',\n  theme: 'auto',\n  size: 'normal',\n  accentColor: '#10b981',\n  borderRadius: 12,\n  showRiskMeter: true,\n  accessibilityMode: false,\n};\n```\n\n### HTML Configuration\n\n```html\n\u003cdiv id=\"captcha-shield\"\u003e\u003c/div\u003e\n\u003cscript src=\"https://smouj.github.io/captcha-shield/widget.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  window.CaptchaShieldConfig = {\n    mode: 'fortress',\n    primaryColor: '#10b981',\n    language: 'en',\n    size: 'normal',\n    borderRadius: 12,\n    timeout: 60,\n    containerId: 'captcha-shield',\n    showRiskMeter: true,\n    accessibilityMode: false,\n  };\n\u003c/script\u003e\n```\n\n### Server Configuration\n\n```typescript\ninterface ServerConfig {\n  secretKey: string;          // Required — HMAC-SHA256 secret\n  issuer?: string;            // Expected token issuer (default: 'cshield-v4')\n  maxTokenAge?: number;       // Max token age in seconds (default: 60)\n  maxRiskScore?: number;      // Max acceptable risk score 0-1 (default: 0.85)\n  requiredLayers?: string[];  // Verification layers that must be present\n  replayProtection?: boolean; // Enable nonce-based replay detection (default: true)\n}\n```\n\n---\n\n## ⚛️ React Component\n\n### Next.js / React Integration\n\n```tsx\nimport { CaptchaWidgetV4 } from '@/components/captcha/CaptchaWidgetV4';\n\nfunction LoginForm() {\n  const [token, setToken] = useState(null);\n\n  return (\n    \u003cform onSubmit={handleSubmit}\u003e\n      \u003cinput name=\"email\" type=\"email\" /\u003e\n      \u003cinput name=\"password\" type=\"password\" /\u003e\n      \n      \u003cCaptchaWidgetV4\n        mode=\"fortress\"\n        language=\"en\"\n        theme=\"auto\"\n        accentColor=\"#10b981\"\n        showRiskMeter\n        onVerify={(t) =\u003e setToken(t)}\n        onError={(e) =\u003e console.error(e)}\n      /\u003e\n      \n      \u003cbutton type=\"submit\" disabled={!token}\u003e\n        Sign In\n      \u003c/button\u003e\n    \u003c/form\u003e\n  );\n}\n```\n\n### With Server Verification\n\n```tsx\nasync function handleSubmit(e) {\n  e.preventDefault();\n  \n  // Verify token on the server\n  const res = await fetch('/api/captcha/verify', {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/json' },\n    body: JSON.stringify({ captchaToken: token }),\n  });\n  \n  const result = await res.json();\n  if (result.valid) {\n    // Proceed with protected action\n  }\n}\n```\n\n---\n\n## 🔐 Server Verification\n\nThe `captcha-shield-server` module provides **one-line backend verification** with HMAC-SHA256 signature validation, replay protection, and risk score enforcement.\n\n### Installation\n\n```bash\nnpm install captcha-shield-server\n# or\nbun add captcha-shield-server\n```\n\n### Basic Usage\n\n```typescript\nimport { verifyCaptchaShieldToken } from 'captcha-shield-server';\n\nconst result = await verifyCaptchaShieldToken(token, {\n  secretKey: process.env.CAPTCHA_SECRET!,\n});\n\nif (result.valid) {\n  console.log('✅ Verified!', result.payload);\n  console.log('Risk score:', result.riskScore);\n  console.log('Expires at:', new Date(result.expiresAt! * 1000));\n} else {\n  console.log('❌ Invalid:', result.reason);\n}\n```\n\n### Express Middleware\n\n```typescript\nimport { captchaShieldMiddleware } from 'captcha-shield-server';\n\napp.post('/api/login',\n  captchaShieldMiddleware({\n    secretKey: process.env.CAPTCHA_SECRET!,\n    maxRiskScore: 0.5,\n    requiredLayers: ['behavioral_precheck', 'dynamic_challenge'],\n  }),\n  (req, res) =\u003e {\n    // Only reached if CAPTCHA is valid\n    res.json({ message: 'Welcome!' });\n  }\n);\n```\n\n### Next.js API Route\n\n```typescript\nimport { createCaptchaVerifier } from 'captcha-shield-server';\n\nconst verifyCaptcha = createCaptchaVerifier({\n  secretKey: process.env.CAPTCHA_SECRET!,\n  maxTokenAge: 60,\n  maxRiskScore: 0.85,\n  replayProtection: true,\n});\n\nexport async function POST(request: Request) {\n  const { captchaToken } = await request.json();\n  const result = await verifyCaptcha(captchaToken);\n  \n  if (!result.valid) {\n    return Response.json({ error: result.reason }, { status: 403 });\n  }\n  \n  return Response.json({ \n    success: true, \n    riskScore: result.riskScore \n  });\n}\n```\n\n### Token Format\n\nCAPTCHA Shield tokens use a custom JWT profile:\n\n```\nheader.payload.signature\n\nHeader:  { \"alg\": \"HS256\", \"typ\": \"CSHIELD-V4\", \"kid\": \"hmac-sha256-v1\" }\nPayload: { \"iss\": \"cshield-v4\", \"sub\": \"...\", \"aud\": \"...\", \"iat\": ..., \"exp\": ..., \n           \"nbf\": ..., \"jti\": \"...\", \"risk\": 0.12, \"challenge\": \"...\", \n           \"verified\": [...], \"fp\": \"...\" }\n```\n\n### Verification Checks (in order)\n\n| Step | Check | Failure Reason |\n|------|-------|---------------|\n| 1 | Token format (3 parts) | `Invalid token format` |\n| 2 | Header decoding | `Invalid token header` |\n| 3 | Algorithm \u0026 type | `Unsupported token algorithm or type` |\n| 4 | HMAC-SHA256 signature (timing-safe) | `Invalid token signature` |\n| 5 | Payload decoding | `Invalid token payload` |\n| 6 | Expiration (`exp`) | `Token expired` |\n| 7 | Max token age (`iat` vs now) | `Token too old` |\n| 8 | Not-before (`nbf`) | `Token not yet valid` |\n| 9 | Issuer match | `Invalid token issuer` |\n| 10 | Risk score threshold | `Risk score too high: X \u003e Y` |\n| 11 | Required verification layers | `Missing required verification layer: X` |\n| 12 | Replay protection (nonce) | `Token already used (replay detected)` |\n\n---\n\n## 📖 API Reference\n\n### Core Functions\n\n#### `verifyCaptchaShieldToken(token, config)`\n\nVerify a CAPTCHA Shield v4.0 token.\n\n```typescript\nfunction verifyCaptchaShieldToken(\n  tokenString: string,\n  config: ServerConfig,\n): Promise\u003cVerificationResult\u003e\n```\n\n**Returns:** `Promise\u003cVerificationResult\u003e`\n\n```typescript\ninterface VerificationResult {\n  valid: boolean;\n  reason?: string;       // Failure reason if invalid\n  payload?: TokenPayload; // Decoded token payload if valid\n  expiresAt?: number;    // Unix timestamp\n  riskScore?: number;    // 0-1 risk score\n}\n```\n\n#### `captchaShieldMiddleware(config)`\n\nExpress middleware for automatic token verification.\n\n```typescript\nfunction captchaShieldMiddleware(\n  config: ServerConfig,\n): (req, res, next) =\u003e Promise\u003cvoid\u003e\n```\n\n#### `createCaptchaVerifier(config)`\n\nFactory for Next.js API route handlers.\n\n```typescript\nfunction createCaptchaVerifier(\n  config: ServerConfig,\n): (token: string) =\u003e Promise\u003cVerificationResult\u003e\n```\n\n### Behavioral Analyzer\n\n```typescript\nconst analyzer = getBehavioralAnalyzer();\n\n// Record events\nanalyzer.recordEvent('mousemove', { clientX: 100, clientY: 200 });\nanalyzer.recordEvent('click', { offsetX: 5, targetWidth: 40 });\n\n// Compute risk\nconst assessment = analyzer.computeRiskAssessment();\n// { score: 0.12, level: 'low', recommendation: 'allow', ... }\n\n// Get all 28 signal readings\nconst signals = analyzer.computeAllSignals();\n\n// Get behavioral data snapshot\nconst data = analyzer.getBehavioralData();\n```\n\n### Challenge Engine\n\n```typescript\nimport { generateChallenge, verifySolution, CHALLENGE_DEFINITIONS } from '@/lib/captcha-engine-v4';\n\n// Generate a challenge\nconst instance = generateChallenge(ChallengeType.ADVERSARIAL_PUZZLE, ChallengeDifficulty.MEDIUM);\n\n// Verify a solution\nconst result = verifySolution(instance, userAnswer);\n// { passed: boolean, confidence: number, timeTaken: number }\n```\n\n### Token Manager\n\n```typescript\nimport { getTokenManager } from '@/lib/token-manager';\n\nconst tm = getTokenManager();\n\n// Generate a signed token\nconst token = await tm.generateToken({\n  sub: 'session-abc',\n  challenge: ChallengeType.ADVERSARIAL_PUZZLE,\n  risk: 0.12,\n  verified: [VerificationLayer.BEHAVIORAL_PRECHECK, VerificationLayer.DYNAMIC_CHALLENGE],\n});\n\n// Verify a token\nconst result = await tm.verifyToken(token);\n\n// Encode/decode\nconst jwtString = tm.encodeToken(token);\nconst decoded = tm.decodeToken(jwtString);\n```\n\n---\n\n## 🔌 Plugin System\n\nExtend CAPTCHA Shield with custom challenges, signal processors, and renderers.\n\n### Creating a Plugin\n\n```typescript\nimport { createPlugin, getPluginRegistry, ChallengeType, ChallengeDifficulty } from 'captcha-shield';\n\nconst myPlugin = createPlugin({\n  name: 'anti-ml-puzzle',\n  version: '1.0.0',\n  description: 'Adversarial puzzle generator resistant to ML solvers',\n  \n  challengeType: ChallengeType.ADVERSARIAL_PUZZLE,\n  \n  challengeGenerator: (difficulty: ChallengeDifficulty) =\u003e ({\n    id: `ch_${Date.now()}_${Math.random().toString(36).slice(2)}`,\n    type: ChallengeType.ADVERSARIAL_PUZZLE,\n    difficulty,\n    payload: { /* puzzle data */ },\n    solution: { type: ChallengeType.ADVERSARIAL_PUZZLE, answer: 42 },\n    expiresAt: Date.now() + 60_000,\n    maxAttempts: 3,\n    attempts: 0,\n    createdAt: Date.now(),\n  }),\n  \n  signalProcessor: (behavioralData) =\u003e ({\n    name: SignalName.ENTROPY_SCORE,\n    category: SignalCategory.COGNITIVE,\n    value: 0.73,\n    rawValue: 0.73,\n    weight: 1.0,\n    timestamp: Date.now(),\n    confidence: 0.9,\n    anomalyScore: 0.1,\n  }),\n});\n```\n\n### Registering a Plugin\n\n```typescript\nconst registry = getPluginRegistry();\n\n// Register\nregistry.register(myPlugin);\n\n// Initialize all plugins\nregistry.initializeAll();\n\n// Query\nconst generators = registry.getChallengeGenerators();\nconst processors = registry.getSignalProcessors();\nconst plugin = registry.getPlugin('anti-ml-puzzle');\n\n// Cleanup\nregistry.unregister('anti-ml-puzzle');\nregistry.destroyAll();\n```\n\n### Plugin Interface\n\n```typescript\ninterface CaptchaPlugin {\n  name: string;                          // Unique identifier\n  version: string;                       // Semver version\n  description: string;                   // Human-readable description\n  challengeType?: ChallengeType;         // Challenge type this plugin handles\n  challengeGenerator?: (difficulty) =\u003e ChallengeInstance;  // Factory function\n  signalProcessor?: (data) =\u003e Partial\u003cSignalReading\u003e;      // Signal enrichment\n  challengeRenderer?: React.ComponentType\u003cChallengeProps\u003e; // Custom renderer\n  onInit?: () =\u003e void;                   // Lifecycle: initialization\n  onDestroy?: () =\u003e void;                // Lifecycle: cleanup\n}\n```\n\n---\n\n## ♿ Accessibility\n\nCAPTCHA Shield v4.0 is **WCAG 2.2 AA compliant** — every challenge has an accessible alternative.\n\n| Challenge | Accessibility Modes |\n|-----------|-------------------|\n| Adversarial Puzzle | Audio description, High contrast |\n| Human Intuition Grid | Audio description, Keyboard navigation |\n| Physics Chaos | Keyboard controls, Haptic feedback |\n| Temporal Memory | Audio cue, Extended display time |\n| Optical Illusion Maze | Simplified view, Audio description |\n| Voice Rhythm | Visual rhythm display, Haptic beat |\n| Gesture Signature | Keyboard path input, Simplified gesture |\n| Contextual Reasoning | Audio description, Text scenarios |\n| Live 3D Biometric | Keyboard rotation, Snap angles |\n| Zero-Knowledge Proof | Extended time, Simplified visual |\n\n### Accessibility Features\n\n- 🎹 **Full keyboard navigation** — every challenge is solvable without a mouse\n- 🔊 **Screen reader support** — ARIA labels, live regions, and announcements\n- 🎨 **High contrast mode** — meets WCAG AA contrast ratios (4.5:1)\n- ⏱️ **Extended time limits** — 2× time for accessibility mode\n- 🔉 **Audio fallbacks** — every visual challenge has an audio alternative\n- 📱 **Touch-friendly** — minimum 44px touch targets\n- 🎯 **Focus indicators** — visible focus rings on all interactive elements\n\n```tsx\n\u003cCaptchaWidgetV4 accessibilityMode={true} /\u003e\n```\n\n---\n\n## 🌍 Internationalization\n\n8 languages with automatic browser detection and full coverage of all UI strings.\n\n| Language | Code | Status | Coverage |\n|----------|------|--------|----------|\n| 🇺🇸 English | `en` | ✅ Complete | 100% |\n| 🇪🇸 Spanish | `es` | ✅ Complete | 100% |\n| 🇫🇷 French | `fr` | ✅ Complete | 100% |\n| 🇩🇪 German | `de` | ✅ Complete | 100% |\n| 🇧🇷 Portuguese | `pt` | ✅ Complete | 100% |\n| 🇯🇵 Japanese | `ja` | ✅ Complete | 100% |\n| 🇨🇳 Chinese | `zh` | ✅ Complete | 100% |\n| 🇰🇷 Korean | `ko` | ✅ Complete | 100% |\n\n### Usage\n\n```typescript\nimport { getTranslations, detectLanguage, getSupportedLanguages } from '@/lib/i18n';\n\n// Auto-detect from browser\nconst lang = detectLanguage();\n\n// Get translations\nconst t = getTranslations('ja');\nconsole.log(t.verifyButton); // \"私は人間です\"\n\n// Get challenge-specific translations\nconst challengeT = getChallengeTranslation('zh', ChallengeType.PHYSICS_CHAOS);\nconsole.log(challengeT.instruction); // \"拖动物体直到天平平衡\"\n\n// List supported languages\nconst languages = getSupportedLanguages();\n// ['en', 'es', 'fr', 'de', 'pt', 'ja', 'zh', 'ko']\n```\n\n---\n\n## 🏗️ Architecture\n\n### Tech Stack\n\n| Technology | Version | Purpose |\n|-----------|---------|---------|\n| [Next.js](https://nextjs.org/) | 16 | App Router framework with static export |\n| [React](https://react.dev/) | 19 | UI components |\n| [TypeScript](https://www.typescriptlang.org/) | 5 | Type safety across the entire codebase |\n| [Tailwind CSS](https://tailwindcss.com/) | 4 | Utility-first styling |\n| [shadcn/ui](https://ui.shadcn.com/) | — | Accessible component library |\n| [Framer Motion](https://www.framer.com/motion/) | 12 | Animations and transitions |\n| [Lucide React](https://lucide.dev/) | — | Icon system |\n| [Prisma](https://www.prisma.io/) | — | ORM for analytics storage |\n| [Node.js Crypto](https://nodejs.org/api/crypto.html) | — | HMAC-SHA256 signing (server) |\n| [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) | — | HMAC-SHA256 signing (client) |\n\n### Project Structure\n\n```\ncaptcha-shield/\n├── server/                          # 🔐 Server verification module\n│   └── index.ts                     # verifyCaptchaShieldToken, middleware, helpers\n├── src/\n│   ├── app/\n│   │   ├── page.tsx                 # Landing page\n│   │   ├── verify/page.tsx          # Verification page\n│   │   ├── widget-embed/page.tsx    # Embeddable widget\n│   │   └── api/captcha/\n│   │       ├── verify/route.ts      # Token verification API\n│   │       ├── generate/route.ts    # Challenge generation API\n│   │       └── analytics/route.ts   # Analytics data API\n│   ├── components/\n│   │   ├── captcha/\n│   │   │   ├── CaptchaWidgetV4.tsx       # Main widget orchestrator\n│   │   │   ├── AdminDashboardV4.tsx      # Risk analytics dashboard\n│   │   │   ├── BehaviorTracker.tsx       # Behavioral event collector\n│   │   │   ├── ThemeCustomizer.tsx       # Live theme editor\n│   │   │   └── challenges/\n│   │   │       ├── AdversarialPuzzleChallenge.tsx\n│   │   │       ├── HumanIntuitionGridChallenge.tsx\n│   │   │       ├── PhysicsChaosChallenge.tsx\n│   │   │       ├── TemporalMemoryChallenge.tsx\n│   │   │       ├── OpticalIllusionMazeChallenge.tsx\n│   │   │       ├── VoiceRhythmChallenge.tsx\n│   │   │       ├── GestureSignatureChallenge.tsx\n│   │   │       ├── ContextualReasoningChallenge.tsx\n│   │   │       ├── Live3DBiometricChallenge.tsx\n│   │   │       └── ZeroKnowledgeProofChallenge.tsx\n│   │   ├── landing/                      # Landing page components\n│   │   └── ui/                           # shadcn/ui components\n│   ├── lib/\n│   │   ├── types.ts                      # Complete type system\n│   │   ├── captcha-engine-v4.ts          # Challenge generation \u0026 verification\n│   │   ├── behavioral-analyzer-v4.ts     # 28 signals + Bayesian scoring\n│   │   ├── token-manager.ts              # JWT token lifecycle (isomorphic)\n│   │   ├── plugin-system.ts              # Plugin registry \u0026 lifecycle\n│   │   ├── i18n.ts                       # 8-language translations\n│   │   ├── captcha-store.ts              # State management\n│   │   ├── db.ts                         # Prisma client\n│   │   └── utils.ts                      # Shared utilities\n│   └── hooks/\n│       ├── use-mobile.ts                 # Mobile detection hook\n│       └── use-toast.ts                  # Toast notification hook\n├── prisma/\n│   └── schema.prisma                     # Database schema\n├── examples/\n│   ├── vanilla.html                      # Vanilla JS integration\n│   └── form-protected-demo.html          # Form protection example\n├── documentation/\n│   ├── SECURITY_MODEL.md                 # Threat model \u0026 guarantees\n│   ├── PRODUCTION_BACKEND_PLAN.md        # Server architecture\n│   ├── API.md                            # API reference\n│   └── BEHAVIORAL-ANALYSIS.md            # Signal deep dive\n└── public/\n    ├── widget.js                         # Embeddable widget script\n    └── screenshots/                      # Demo screenshots\n```\n\n### Data Flow\n\n```\nBrowser                           Server                          Protected Resource\n────────                          ──────                          ──────────────────\n  │                                  │                                  │\n  │  1. User clicks \"I am human\"     │                                  │\n  │─────────────────────────────────▶│                                  │\n  │                                  │                                  │\n  │  2. Behavioral precheck          │                                  │\n  │     (28 signals computed)        │                                  │\n  │                                  │                                  │\n  │  3. Dynamic challenge shown      │                                  │\n  │     (selected by risk score)     │                                  │\n  │                                  │                                  │\n  │  4. User solves challenge        │                                  │\n  │     (behavioral data collected)  │                                  │\n  │                                  │                                  │\n  │  5. Token generated              │                                  │\n  │     (HMAC-SHA256 signed)         │                                  │\n  │                                  │                                  │\n  │  6. Token sent to server         │                                  │\n  │─────────────────────────────────▶│                                  │\n  │                                  │                                  │\n  │                                  │  7. Token verified               │\n  │                                  │     - Signature check            │\n  │                                  │     - Expiration check           │\n  │                                  │     - Risk score check           │\n  │                                  │     - Replay protection          │\n  │                                  │                                  │\n  │                                  │  8. Protected action allowed     │\n  │                                  │─────────────────────────────────▶│\n  │                                  │                                  │\n  │  9. Result returned              │                                  │\n  │◀────────────────────────────────│                                  │\n```\n\n---\n\n## 🔒 Security Model\n\n### What Fortress Protects Against\n\n| Attack Vector | Protection | Effectiveness |\n|--------------|-----------|:------------:|\n| **Automated bots** | 28 behavioral signals + Bayesian scoring | ⭐⭐⭐⭐⭐ |\n| **Headless browsers** | 20 detection vectors (Puppeteer, Selenium, etc.) | ⭐⭐⭐⭐⭐ |\n| **ML-based solvers** | Adversarial noise, optical illusions, intuition challenges | ⭐⭐⭐⭐ |\n| **Replay attacks** | Nonce-based replay protection (2-min window) | ⭐⭐⭐⭐⭐ |\n| **Token tampering** | HMAC-SHA256 signatures with timing-safe comparison | ⭐⭐⭐⭐⭐ |\n| **Credential stuffing** | Rate limiting + progressive challenge escalation | ⭐⭐⭐⭐ |\n| **CAPTCHA solving services** | Behavioral validation of interaction patterns | ⭐⭐⭐ |\n\n### Security Guarantees\n\n- ✅ **Timing-safe signature comparison** — prevents timing side-channel attacks\n- ✅ **Single-use tokens** — each token has a unique `jti` nonce\n- ✅ **Short TTL** — tokens expire after 60 seconds by default\n- ✅ **No client-side trust** — server verification is always required for production\n- ✅ **Replay protection** — used tokens are tracked for 2 minutes\n- ✅ **Risk enforcement** — server rejects tokens with risk scores above threshold\n\n### Security Boundaries\n\n\u003e ⚠️ **Important**: Client-side verification is a **friction layer**, not a security boundary. Any client-side check can be bypassed by a determined attacker. **Server-side verification is required for production security.**\n\nSee [SECURITY.md](./SECURITY.md) for responsible disclosure guidelines and [Security Model](documentation/SECURITY_MODEL.md) for the complete threat model.\n\n---\n\n## 🛡️ Verification Modes\n\nCAPTCHA Shield v4.0 offers **3 verification modes** to balance security and user experience:\n\n| Mode | Behavioral Pre-check | Challenge | QR/WebAuthn | Token TTL | Best For |\n|------|:--------------------:|:---------:|:-----------:|:---------:|----------|\n| 🟢 **Light** | ✅ | 1 easy challenge | ❌ | 120s | Low-risk forms, newsletters, comments |\n| 🔴 **Fortress** | ✅ | 2+ challenges (risk-adaptive) | ✅ (if risk \u003e 0.5) | 60s | Login, payments, account changes |\n| 🟡 **Hybrid** | ✅ | 1 challenge + risk-based escalation | ✅ (if risk \u003e 0.7) | 90s | General-purpose, adaptive security |\n\n### Mode Selection\n\n```tsx\n{/* Light mode — minimal friction */}\n\u003cCaptchaWidgetV4 mode=\"light\" /\u003e\n\n{/* Fortress mode — maximum security (default) */}\n\u003cCaptchaWidgetV4 mode=\"fortress\" /\u003e\n\n{/* Hybrid mode — adaptive */}\n\u003cCaptchaWidgetV4 mode=\"hybrid\" /\u003e\n```\n\n```html\n\u003c!-- HTML configuration --\u003e\n\u003cscript\u003e\n  window.CaptchaShieldConfig = {\n    mode: 'fortress',  // 'light' | 'fortress' | 'hybrid'\n  };\n\u003c/script\u003e\n```\n\n### Mode Behavior Details\n\n#### 🟢 Light Mode\n- Single easy challenge (e.g., Human Intuition Grid)\n- Behavioral pre-check with 28 signals\n- Instant pass if risk \u003c 0.15 (no challenge needed)\n- Extended token TTL (120s)\n- **No QR/WebAuthn escalation**\n- Best for low-stakes interactions where friction must be minimal\n\n#### 🔴 Fortress Mode (Default)\n- Multi-challenge verification (2+ challenges for medium/high risk)\n- Dynamic difficulty scaling based on Bayesian risk score\n- QR mobile verification for risk \u003e 0.5\n- WebAuthn/Passkey for risk \u003e 0.7\n- Strict token TTL (60s)\n- Cooldown: 5s × attempts, capped at 60s\n- Instant block at risk \u003e 0.85\n- Best for high-value operations requiring maximum security\n\n#### 🟡 Hybrid Mode\n- Single challenge by default, escalates based on risk\n- Additional challenges triggered at risk \u003e 0.4\n- QR/WebAuthn triggered at risk \u003e 0.7\n- Moderate token TTL (90s)\n- Balanced approach — low friction for legitimate users, strong protection against bots\n\n---\n\n## 🗺️ Roadmap\n\n### ✅ v4.0 \"Fortress\" (Current)\n\n- [x] 10 AI-proof challenge types with adversarial design\n- [x] 28 behavioral signals with Bayesian risk scoring\n- [x] 7-layer defense architecture\n- [x] HMAC-SHA256 token signing and verification\n- [x] Server verification module (Express, Next.js, standalone)\n- [x] Replay protection with nonce-based deduplication\n- [x] Plugin architecture for custom challenges\n- [x] 8-language internationalization\n- [x] WCAG 2.2 AA accessibility compliance\n- [x] 20+ headless browser detection vectors\n- [x] Admin dashboard with risk analytics\n\n### 🔮 v4.1 — Observability\n\n- [ ] Webhook notifications for verification events\n- [ ] Prometheus metrics export\n- [ ] Grafana dashboard templates\n- [ ] Audit log persistence (Prisma + SQLite)\n- [ ] Real-time verification stream (WebSocket)\n\n### 🔮 v4.5 — Intelligence\n\n- [ ] ML-based adaptive difficulty (challenge gets harder for suspicious users)\n- [ ] Crowd-sourced challenge difficulty calibration\n- [ ] Cross-site risk reputation sharing (opt-in)\n- [ ] Device fingerprint reputation database\n\n### 🔮 v5.0 — Platform\n\n- [ ] Multi-tenant SaaS dashboard\n- [ ] Managed cloud verification API\n- [ ] Rate limiting as a service\n- [ ] Custom challenge builder (visual editor)\n- [ ] A/B testing for challenge effectiveness\n- [ ] Mobile SDK (iOS / Android native widgets)\n- [ ] WebAssembly challenge rendering for maximum performance\n\n---\n\n## 🤝 Contributing\n\nWe love contributions! CAPTCHA Shield is built by the community, for the community.\n\n### Quick Start\n\n```bash\n# 1. Fork \u0026 clone\ngit clone https://github.com/YOUR_USERNAME/captcha-shield.git\ncd captcha-shield\n\n# 2. Install dependencies\nnpm ci\n\n# 3. Start development server\nnpm run dev\n\n# 4. Make your changes and test\nnpm run lint\nnpm run typecheck\n```\n\n### Contribution Types\n\n| Type | Description | Example |\n|------|-------------|---------|\n| 🐛 Bug fix | Fix an existing issue | Challenge rendering bug |\n| ✨ Feature | Add new functionality | New challenge type |\n| 🌍 Translation | Add or improve i18n | Italian language support |\n| ♿ Accessibility | Improve a11y | Better screen reader support |\n| 📝 Documentation | Improve docs | API reference update |\n| 🧪 Testing | Add test coverage | Challenge engine tests |\n| 🎨 Design | Improve UI/UX | Better mobile layout |\n\n### Pull Request Checklist\n\n- [ ] Code compiles without errors (`npm run typecheck`)\n- [ ] Linting passes (`npm run lint`)\n- [ ] New features include TypeScript types\n- [ ] UI changes are responsive (mobile + desktop)\n- [ ] Accessibility maintained (WCAG 2.2 AA)\n- [ ] Documentation updated if needed\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution guide and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for our community standards.\n\n---\n\n## 📝 Changelog\n\nAll notable changes are documented in [CHANGELOG.md](./CHANGELOG.md).\n\n| Version | Codename | Date | Highlights |\n|---------|----------|------|------------|\n| **4.0.0** | Fortress | 2025-05 | 10 challenges, 28 signals, 7 layers, JWT tokens, plugins, i18n |\n| 3.1.0 | — | 2025-04 | 7 challenges, 14 signals, QR verification, widget embed |\n| 3.0.0 | — | 2025-04 | 4 challenges, 6 signals, behavioral analysis engine |\n\n---\n\n## 📜 License\n\n```\nMIT License\n\nCopyright (c) 2024-2025 CAPTCHA Shield Contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n---\n\n## 🙏 Credits\n\n### Built With\n\n- [Next.js](https://nextjs.org/) — The React framework for the web\n- [React](https://react.dev/) — The library for web and native user interfaces\n- [TypeScript](https://www.typescriptlang.org/) — JavaScript with syntax for types\n- [Tailwind CSS](https://tailwindcss.com/) — A utility-first CSS framework\n- [shadcn/ui](https://ui.shadcn.com/) — Beautifully designed components\n- [Framer Motion](https://www.framer.com/motion/) — Production-ready motion library\n- [Lucide](https://lucide.dev/) — Beautiful \u0026 consistent icons\n\n### Inspired By\n\n- [reCAPTCHA](https://www.google.com/recaptcha/) — Pioneered the risk-analysis CAPTCHA\n- [hCaptcha](https://www.hcaptcha.com/) — Privacy-first alternative\n- [Friendly CAPTCHA](https://friendlycaptcha.com/) — Proof-of-work approach\n- [Cloudflare Turnstile](https://www.cloudflare.com/products/turnstile/) — Invisible verification\n\n### Research\n\n- Bursztein et al., *\"The Difficulty of Breaking CAPTCHAs\"* (2023)\n- Sivakorn et al., *\"I am not a Human: Breaking the Google reCAPTCHA\"* (2023)\n- Ho et al., *\"Detecting and Characterizing Bot Attacks on CAPTCHA Systems\"*\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cbr /\u003e\n\n**Built with ❤️ by [Smouj](https://github.com/smouj) and [contributors](https://github.com/smouj/captcha-shield/graphs/contributors)**\n\n[![GitHub](https://img.shields.io/badge/GitHub-captcha--shield-181717?style=for-the-badge\u0026logo=github\u0026labelColor=1a1a2e)](https://github.com/smouj/captcha-shield)\n[![Website](https://img.shields.io/badge/Demo-Live-22c55e?style=for-the-badge\u0026logo=github\u0026labelColor=1a1a2e)](https://smouj.github.io/captcha-shield/)\n[![npm](https://img.shields.io/badge/npm-captcha--shield-22c55e?style=for-the-badge\u0026logo=npm\u0026logoColor=white\u0026labelColor=1a1a2e)](https://www.npmjs.com/)\n\n\u003cbr /\u003e\n\n*If CAPTCHA Shield helps protect your project, consider giving it a ⭐ — it helps others find it!*\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmouj%2Fcaptcha-shield","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmouj%2Fcaptcha-shield","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmouj%2Fcaptcha-shield/lists"}