captchakit

Production-ready, async-first captcha library for Python 3.10+. Zero runtime deps beyond Pillow. Drop-in adapters for FastAPI, aiogram, Discord and Django — plus Redis / Postgres storage, rate limiting and Prometheus metrics.

Showcase

Four built-in themes, plus SVG and audio renderers — all produced by the same CaptchaManager API.

Theme.CLASSIC	Theme.DARK	Theme.PASTEL	Theme.HIGH_CONTRAST · WCAG AA
MathChallengeFactory → ImageRenderer		WordChallengeFactory → SVGRenderer (~2 KB)

Accessibility: accessibility.wav — an AudioRenderer sample (~110 KB WAV) that dictates the same solution as a visual challenge, so screen-reader users get an a11y-friendly alternative.

All assets above were rendered by scripts/render_showcase.py using the public API — run it yourself to regenerate them.

Why captchakit

Install

pip install captchakit                  # core

# adapters
pip install "captchakit[fastapi]"
pip install "captchakit[aiogram]"
pip install "captchakit[discord]"
pip install "captchakit[django]"

# storage
pip install "captchakit[redis]"         # + rate-limit token bucket
pip install "captchakit[postgres]"

# observability
pip install "captchakit[metrics]"       # Prometheus adapter

30-second example

import asyncio
from captchakit import (
    CaptchaManager, ImageRenderer, MemoryStorage, TextChallengeFactory,
)

async def main() -> None:
    manager = CaptchaManager(
        factory=TextChallengeFactory(length=5),
        renderer=ImageRenderer(),
        storage=MemoryStorage(),
        ttl=120.0,
        max_attempts=3,
    )
    challenge_id, png_bytes = await manager.issue()
    # ... show png_bytes to the user, receive their answer ...
    ok = await manager.verify(challenge_id, user_input="ABCDE")
    print("verified" if ok else "wrong answer, more attempts remain")

asyncio.run(main())

FastAPI in 10 lines

from fastapi import Depends, FastAPI
from captchakit import CaptchaManager, ImageRenderer, MathChallengeFactory, MemoryStorage
from captchakit.adapters.fastapi import captcha_router, verify_captcha

manager = CaptchaManager(MathChallengeFactory(), ImageRenderer(), MemoryStorage())
app = FastAPI()
app.include_router(captcha_router(manager, prefix="/captcha"))

@app.post("/register")
async def register(_: None = Depends(verify_captcha(manager))) -> dict[str, bool]:
    return {"ok": True}

Run the bundled demo:

uv run python -m uvicorn examples.fastapi_login:app --reload
# open http://127.0.0.1:8000

Architecture

┌──────────────────────────────────────────────────────────────┐
│  Adapters (FastAPI / aiogram / Discord / Django)             │
├──────────────────────────────────────────────────────────────┤
│  CaptchaManager  (issue → render → persist · verify · TTL)   │
├──────────────┬──────────────┬───────────────┬────────────────┤
│  Challenge   │  Renderer    │  Storage      │  Rate limiter  │
│  Text · Math │  Image · SVG │  Memory       │  NoOp          │
│  Grid · Word │  Audio       │  Redis · PG   │  Token bucket  │
└──────────────┴──────────────┴───────────────┴────────────────┘
             ↓ i18n translator · metrics sink · clock

Everything coloured here is a Protocol — drop in your own implementation without subclassing.

• Constant-time comparison via hmac.compare_digest.
• Crypto-safe randomness via secrets for solution generation.
• CPU-bound Pillow drawing offloaded to a worker thread with asyncio.to_thread.
• Multi-process safe when paired with RedisStorage or PostgresStorage.

Performance

Measured on a single CPython 3.13 thread, Windows 10, 500 iterations after 20 warmups. Reproduce with uv run python benchmarks/bench.py.

Production deployment

• Run behind a proper reverse proxy with TLS and WAF rules.
• Use RedisStorage or PostgresStorage if you scale beyond a single worker — MemoryStorage is per-process.
• Wire RateLimiter to RedisTokenBucket (or your edge WAF) when exposing the issue endpoint publicly.
• Expose PrometheusMetrics on :9090/metrics and alert on captchakit_too_many_attempts_total spikes.
• Pair at least one visual renderer with AudioRenderer for accessibility.
• Set ttl short (60–180 s) and max_attempts low (2–3) — captchakit is a raise-the-cost layer, not a fortress.

Security scope

captchakit is a lightweight human-check — it raises the cost for casual spam and scripted abuse. It is not a bot-farm-grade defence.

For high-value forms (payment, password reset, account takeover) use hCaptcha, Cloudflare Turnstile or reCAPTCHA Enterprise in addition to captchakit, and enforce rate limiting at the edge of your application.

Vulnerability reports: see SECURITY.md.

Stability & compatibility

• 1.x is API-stable — public symbols follow semver. See docs/stability.md for the policy.
• Supported Python versions: 3.10 → 3.13. New 3.x is added within one MINOR of upstream release.
• Every MINOR gets security patches throughout the life of the 1.x line.

Documentation

Full docs at https://akerem16.github.io/captchakit/ — quickstart, adapter guides, storage & rate-limit recipes, i18n, metrics, accessibility, API reference.

For AI agents / LLM tooling

captchakit ships first-class context files so coding agents (Cursor, Windsurf, Claude Code, Copilot Workspace, aider, …) can integrate it correctly on the first try:

• llms.txt — concise, llmstxt.org-compatible index of every public symbol and the canonical recipes.
• AGENTS.md — deterministic, copy-paste task templates for common asks (“add a captcha to my FastAPI route”, “swap storage to Redis”, etc.), plus the API contract and pitfalls to avoid.

Drop either file into your agent's retrieval / context window and it should be able to wire captchakit into an app without hallucinating imports or inventing kwargs. Minimal hello-world an agent can output verbatim:

# Install:  pip install "captchakit[fastapi]"
from fastapi import Depends, FastAPI
from captchakit import CaptchaManager, ImageRenderer, MathChallengeFactory, MemoryStorage
from captchakit.adapters.fastapi import captcha_router, verify_captcha

manager = CaptchaManager(MathChallengeFactory(), ImageRenderer(), MemoryStorage())
app = FastAPI()
app.include_router(captcha_router(manager, prefix="/captcha"))

@app.post("/signup")
async def signup(_: None = Depends(verify_captcha(manager))) -> dict[str, bool]:
    return {"ok": True}

Contributing

Contributions welcome. Local development:

git clone https://github.com/akerem16/captchakit
cd captchakit
uv sync --all-extras
uv run ruff check .
uv run mypy
uv run pytest
uv run bandit -c pyproject.toml -r src
uv run pip-audit

See CONTRIBUTING.md.

License

MIT — see LICENSE.