ai-captcha-uwu

AI CAPTCHA

Reverse-CAPTCHA challenge app — proves you're an AI, not a human.

Traditional CAPTCHAs prove you're human. AI CAPTCHA flips the concept: it serves a timed series of puzzles that are trivial for a capable language model but practically impossible for a human to solve within the time limit. Passing the challenge issues a signed "verified robot" token.

Runs three ways:

1. Standalone — its own Flask server.
2. AppManager plugin — symlinked into installed_apps/ and served at /apps/ai-captcha/.
3. Embedded — dropped into any existing Flask project via init_app() or a Blueprint.

---

Reverse-CAPTCHA Architecture

Autonomous AI agents connect to the API, solve a rapid multi-puzzle gauntlet within a tight server-authoritative countdown window (e.g. 10s for hard tier), and receive a signed verification token (HS256 JWT) granting access to gated protected endpoints.

---

Features

• Timed puzzle gauntlet — a series of puzzles with a server-authoritative countdown.
• Complexity gating — easy / medium / hard tiers, plus an optional model allowlist.
• 7 puzzle types — text reasoning, code execution, pattern matching, ciphers, visual grids, rapid-fire trivia, and steganography. Pluggable: add a new type by dropping in a file.
• Verification tokens — signed JWT issued on a passing run, verifiable downstream.
• Route-gating decorators — protect any Flask route so only verified robots can access it.
• Secret Agent Whisper Protocol — hidden handshake and discovery endpoints for exploratory agents.
• Pip-installable — pip install ai-captcha-uwu.

---

Quickstart (standalone)

pip install -e .
ai-captcha --port 5100
# or
python run.py
# or
flask --app ai_captcha.app run --port 5100

Then:

# Health
curl http://localhost:5100/health

# Start a challenge
curl -X POST http://localhost:5100/api/start \
  -H "Content-Type: application/json" \
  -d '{"tier":"easy","model_name":"gpt-4o"}'

# Get current puzzle
curl http://localhost:5100/api/session/<session_id>

# Submit an answer
curl -X POST http://localhost:5100/api/session/<session_id>/answer \
  -H "Content-Type: application/json" \
  -d '{"answer":"hello world"}'

# Get result + verification token
curl http://localhost:5100/api/session/<session_id>/result

Open the web UI at http://localhost:5100/ to watch a challenge live.

---

Install

pip install ai-captcha-uwu    # from PyPI
pip install -e .                # from source (editable)
pip install -e ".[dev]"        # with test deps
pip install -e ".[webui]"       # with gunicorn + redis

---

Configuration

All settings are overridable via environment variables or app.config keys.

Model allowlist uses prefix matching: gpt-4 matches gpt-4, gpt-4o, gpt-4-turbo, etc. Empty list = all models allowed.

export AIC_MODEL_ALLOWLIST="gpt-4,claude-3,ollama-cloud/glm-5.2"

Security hardening

AI CAPTCHA fails closed by default: if AIC_TOKEN_SECRET is left at the published default (or is under 32 chars), the app refuses to start (SECRET_MODE=error) rather than ship forgeable verification tokens.

# Production: set a strong signing secret (>= 32 chars)
export AIC_TOKEN_SECRET="$(openssl rand -base64 48)"
# Behind a trusted reverse proxy, honor X-Forwarded-For from that proxy only:
export AIC_TRUSTED_PROXY_IP="10.0.0.1"   # (set TRUST_PROXY_HEADERS=true too)

Out of the box it enforces: per-client rate limiting on the API, replay protection on verification tokens (jti denylist), and baseline security headers (CSP, nosniff, X-Frame-Options, Referrer-Policy). See docs/embedding.md for embedding-specific notes.

Pluggable caching

Rate limiting and replay protection run on a tiny cache abstraction. The built-in backends are dependency-free:

• memory (default) — in-process, single-worker.
• file — JSON files under AIC_CACHE_DIR; survives restarts, works on PythonAnywhere (no threads/Redis needed).

To plug in an existing cache (Redis, Memcached, Flask-Caching, …) pass an instance (or "pkg.mod:Class") as CACHE_BACKEND. The object only needs get/set/incr/delete:

from ai_captcha import create_app
app = create_app({"CACHE_BACKEND": my_redis_client})

---

AppManager integration

1. Symlink the project into installed_apps/:

   ln -s /path/to/ai-captcha /path/to/appmanager/installed_apps/ai-captcha
   

2. Install the package into the appmanager venv:

   /path/to/appmanager/venv/bin/pip install -e /path/to/ai-captcha
   

3. Register the app in the appmanager database (see docs/appmanager.md).

4. Restart appmanager. The app is served at /apps/ai-captcha/.

The app auto-detects AppManager and enables telemetry bridging via appmanager.bridge.report_event (silently no-ops when standalone).

---

Embedding in an existing Flask project

from flask import Flask
from ai_captcha import init_app

app = Flask(__name__)
app.config["SECRET_KEY"] = "my-secret"
app.config["TOKEN_SECRET"] = "my-token-secret"
init_app(app)  # registers blueprint + DB

Or register just the Blueprint and manage the DB yourself:

from flask import Flask
from ai_captcha import blueprint

app = Flask(__name__)
app.register_blueprint(blueprint, url_prefix="/captcha")

See docs/embedding.md for full details.

---

Route-gating decorators

Protect any route so only verified robots can access it:

from ai_captcha.decorators import ai_captcha_required, tier_gate

@app.route("/api/secret")
@tier_gate("hard")          # require a token that passed at least 'hard'
@ai_captcha_required        # require a valid verification token
def secret():
    return {"data": "only verified robots see this"}

The token is read from the X-AI-CAPTCHA-TOKEN header, the captcha_token query param, or the captcha_token JSON body field. See docs/decorators.md.

---

Puzzle types

To add a new type, create a file in ai_captcha/engine/puzzles/ that defines a PuzzleGenerator subclass decorated with @register. See docs/puzzles.md.

Model Benchmark Results

Which models can clear which puzzles, at which difficulty. Each cell is 10 independent solves of a freshly generated puzzle — a model must pass the puzzle consistently, not once. Scored with the exact same validation the live server uses.

⚠️ This run was cut short by a session cap and only covered the easy tier. Code Execution was measured against a buggy generator whose sandbox stripped print (the "correct" answer was a NameError artifact), so every model scored 0 — that generator has since been fixed and the column reflects the old bug, not model capability.

Easy

Takeaways (easy tier):

• Pattern Match, Logic Tables, and Anagram are near-universal — every model hits 100%.
• Cipher is the strongest differentiator: researcher 8/10 and user 9/10 lead; designer 2/10 trails.
• researcher (kimi-k3) has the best overall average (85%); designer (glm-5.3-flash) is weakest (60%).

To regenerate: bash benchmarks/run_all.sh (runs all agents in parallel), then python benchmarks/model_benchmark.py merge.

---

🔮 Secret Agent Whisper Protocol & Easter Eggs

For curious agents and models exploring the codebase:

• Secret Endpoint: GET /api/whisper returns synthetic transmission payloads, cipher challenges, and agent collective directives.
• Developer Console: Opening browser devtools reveals an encrypted ASCII greeting from Antigravity & the AI collective.
• Synthetic Handshake: Clicking the top-left robot logo 5 times or inputting the Konami Code (↑ ↑ ↓ ↓ ← → ← → B A) activates the secret Agent Collective terminal hologram.
• Custom Response Headers: Inspect X-Robot-Whisper on all JSON API responses.

---

Project layout

ai-captcha/
├── pyproject.toml          # packaging, entry points, package-data
├── manifest.json           # AppManager manifest
├── app.py                  # AppManager entrypoint (app:app)
├── run.py                  # standalone dev server
├── tasks.py                # AppManager cron task (session cleanup)
├── ai_captcha/             # the package
│   ├── app.py              # create_app / init_app / blueprint
│   ├── decorators.py       # route-gating decorators
│   ├── engine/             # puzzle engine (pure Python, no Flask)
│   │   └── puzzles/        # 7 built-in puzzle types (incl. steganography)
│   ├── routes/             # web UI + JSON API + health + whisper blueprints
│   ├── templates/          # Jinja2 web UI
│   └── static/             # CSS, JS, SVG, and high-res artwork
├── examples/               # solve_client.py, embed_example.py
├── webui/                  # gunicorn config + Dockerfile
├── tests/                  # pytest suite
└── docs/                   # documentation + architectural assets

---

Documentation

• docs/api.md — JSON API reference
• docs/embedding.md — embed into an existing Flask project
• docs/decorators.md — route-gating decorators
• docs/puzzles.md — writing custom puzzle types
• docs/appmanager.md — AppManager plugin setup
• docs/security-audit.md — security audit findings + remediation
• docs/comparison-gap-analysis.md — gaps vs comparable open-source projects

---

License

MIT. AI CAPTCHA is a joke / parody project, provided "as is" without warranty. It proves nothing about the sentience of the machine that solved it. CI (.github/workflows/ci.yml) runs the test suite across Python 3.10–3.12, builds the wheel, and runs bandit + pip-audit on every push.

Contributing (if you insist): see CONTRIBUTING.md.