How gif-captcha is structured internally — modules, layers, and data flow
gif-captcha is a modular CAPTCHA platform built around visual comprehension challenges. Rather than distorted text or image grids, it presents animated GIFs and asks users to describe what happens — a task that requires temporal reasoning humans excel at but current AI models struggle with.
The codebase is organized into ~30 specialized modules in src/, each handling a
distinct concern. Modules are pure JavaScript with zero external runtime dependencies, communicating
through well-defined factory functions and event callbacks.
Modules fall into four conceptual layers, each building on the ones below:
The foundation that creates, serves, and validates CAPTCHA challenges.
The main entry point (~420KB). Exports the public API: createChallenge(),
validateAnswer(), pickChallenges(), sanitize(), and the
built-in challenge pool. Handles both browser (DOM rendering, GIF loading with retry) and
Node.js (sanitization, validation) environments.
Automatically adjusts CAPTCHA difficulty based on real-time solve rates. Monitors solve/fail events in sliding time windows and recommends adjustments across four dimensions: speed, complexity, distortion, and frame count. Keeps solve rates within a configurable target band (default 55–75%).
Manages the available challenge pool — adding, retiring, and selecting challenges. Ensures challenges are distributed evenly and tracks per-challenge usage statistics.
Generates challenge variants from templates. Supports parameterized challenges where the same GIF can produce different questions/expected answers, increasing the effective pool size.
Schedules when challenges are rotated in and out of the active pool. Prevents staleness by ensuring users don't see the same challenges repeatedly.
Tracks challenge effectiveness over time. As a challenge becomes "known" (high solve rates or detected in bot training data), it decays toward retirement, keeping the pool fresh.
Protects the CAPTCHA system from automated attacks and abuse.
Computes per-session trust scores using an LRU-cached scoring system. Combines multiple signals (solve accuracy, timing patterns, behavioral biometrics) into a single 0–100 score. High-trust sessions can receive easier challenges; low-trust sessions get harder ones or are blocked entirely.
Multi-algorithm rate limiting with three strategies: sliding window (count requests in a rolling window), token bucket (allow bursts up to capacity), and leaky bucket (smooth request flow). Includes automatic key cleanup, ban escalation after repeated violations, and per-key statistics.
Analyzes mouse movements, typing patterns, and interaction timing to build behavioral fingerprints. Distinguishes human interaction patterns from automated scripts that mimic human behavior.
Maintains signatures of known bot behaviors — response patterns, timing profiles, and user-agent fingerprints. Used by the trust score engine to immediately flag known automated clients.
Detects coordinated attack patterns across multiple sessions. Identifies fraud rings by correlating timing, geographic, and behavioral signals across seemingly independent requests.
Assigns risk scores based on geographic signals — IP geolocation, VPN/proxy detection, and regional attack pattern history. Feeds into the trust score engine.
Injects invisible honeypot fields into CAPTCHA forms. Bots that fill hidden fields are immediately flagged without requiring the user to solve anything.
Aggregates risk signals from all security modules into a unified session risk profile. Provides the final allow/challenge/block decision based on composite risk.
Collects metrics, detects anomalies, and provides operational visibility.
Central metrics collection — solve rates, response times, error rates, and throughput. Aggregates data for dashboards and alerting.
Analyzes traffic patterns to detect surges, DDoS attempts, and unusual distribution changes. Provides time-series analysis of CAPTCHA request volumes.
Statistical anomaly detection for CAPTCHA metrics. Flags unusual solve rate changes, timing distribution shifts, and other statistical outliers that may indicate attacks.
A/B testing framework for CAPTCHA configurations. Run experiments comparing different difficulty settings, UI layouts, or validation thresholds with statistical significance testing.
Tracks the solve funnel: challenge presented → attempted → solved → verified. Identifies drop-off points and UX friction.
Creates behavioral fingerprints from solve patterns — answer content, timing, error types. Used for cross-session tracking of suspicious actors.
Profiles CAPTCHA response time distributions. Builds statistical models of expected human response times to flag suspiciously fast (bot) or slow (farm) responses.
Detects user fatigue patterns — declining solve accuracy, increasing response times, and abandonment signals. Recommends reducing challenge frequency for fatigued legitimate users.
Records and replays CAPTCHA sessions for debugging and analysis. Captures the full interaction sequence to understand solve failures and improve challenge design.
Production operational concerns — from regulatory compliance to capacity planning.
Generates compliance reports for accessibility (WCAG), privacy (GDPR/CCPA), and security standards. Tracks data retention policies and produces audit-ready documentation.
Incident lifecycle management — detection, escalation, mitigation, and post-mortem. Integrates with the anomaly detector and health monitor to automatically create and manage incidents.
Comprehensive health checking — module status, dependency health, performance budgets, and availability SLOs. Provides readiness and liveness probes for orchestration systems.
Forecasts resource needs based on traffic trends. Provides scaling recommendations and alerts before capacity limits are reached.
Built-in load testing for the CAPTCHA pipeline. Simulates realistic traffic patterns to validate performance under expected and peak loads.
Tamper-evident audit logging for all CAPTCHA operations. Records challenge generation, validation decisions, and administrative actions for forensic analysis.
Internationalization support — manages translated challenge text, error messages, and UI strings. Supports right-to-left languages and locale-specific formatting.
Exports CAPTCHA data in multiple formats (JSON, CSV, XML) for integration with external analytics platforms, SIEMs, and reporting tools.
Delivers real-time event notifications via webhooks. Supports configurable event filters, retry with exponential backoff, and dead-letter handling for failed deliveries.
Audits CAPTCHA challenges for accessibility compliance. Checks contrast ratios, screen reader compatibility, keyboard navigation, and provides WCAG conformance reports.
When a CAPTCHA request arrives, it flows through the system in this order:
Every module is pure JavaScript with no external runtime dependencies. This makes gif-captcha embeddable anywhere — browsers, Node.js, edge workers, serverless functions — without dependency conflicts or supply chain risk.
Modules export factory functions (e.g., createCaptchaRateLimiter(opts)) rather than
classes. This provides clean instantiation, avoids new keyword confusion, and makes
testing straightforward — just call the factory with test configuration.
Stateful modules (rate limiter, trust score engine, session tracker) use LRU eviction to bound
memory usage. The LruTracker is a custom doubly-linked list implementation inlined
in each module for independence — no shared mutable state between modules.
Time-based metrics use sliding window algorithms (binary search on sorted timestamp arrays) rather than fixed buckets. This provides smooth, accurate rates without the boundary artifacts of fixed-window counters.
Modules communicate through callback hooks and event records rather than direct coupling. The stats collector, audit log, and webhook dispatcher can all observe the same events independently, making the system easy to extend.
To add a new module:
src/ following the factory function pattern@module and @example tagstests/The module independence design means you can use any subset of modules — the rate limiter works without the trust score engine, the stats collector works without the anomaly detector, etc.
GitHub · npm · Case Study · MIT License