gbkomi-captcha 0.1.1

# gbkomi-captcha

🔐 Advanced CAPTCHA generator with visual distortion, noise, and wave deformation.  
Designed to be **bot-proof** for web applications and Telegram bots.

## Features

- ✅ **Image-based CAPTCHA** (numbers or short text)
- ✅ **Wave distortion** + random rotation per character
- ✅ **Noise lines & dots** to defeat OCR
- ✅ **Rate limiting** and **challenge expiration**
- ✅ **One-time use** verification
- ✅ Ready-to-use **Flask**, **FastAPI**, and **Telegram** integrations
- ✅ Pluggable storage backend (Memory / Redis)

## Installation

```bash
pip install gbkomi-captcha

For Redis support:

pip install gbkomi-captcha[redis]

For web integrations:

pip install gbkomi-captcha[web]

For Telegram bots:

pip install gbkomi-captcha[telegram]

Quick Start

Generate a CAPTCHA image

from gbkomi_captcha import CaptchaGenerator
from gbkomi_captcha.middleware.challenge import create_challenge

gen = CaptchaGenerator()
image, text = gen.generate()  # e.g. "8342"

challenge_id = create_challenge(text, ttl=120)

# Send `image` to the user, keep `challenge_id`
# Later verify with:
# from gbkomi_captcha.middleware.validators import validate_answer
# is_valid = validate_answer(challenge_id, user_input)

With Flask

from flask import Flask
from gbkomi_captcha.integrations.flask import flask_blueprint

app = Flask(__name__)
app.register_blueprint(flask_blueprint, url_prefix="/api")

# GET /api/captcha/image → returns PNG with X-Captcha-Id header
# POST /api/captcha/verify → JSON { "challenge_id": "...", "answer": "1234" }

With FastAPI

from fastapi import FastAPI
from gbkomi_captcha.integrations.fastapi import fastapi_router

app = FastAPI()
app.include_router(fastapi_router, prefix="/api")

With Telegram Bot

from telegram.ext import Application
from gbkomi_captcha.integrations.telegram import TelegramCaptcha

app = Application.builder().token("TOKEN").build()
captcha = TelegramCaptcha(app.bot)

# Inside a handler:
# await captcha.send_captcha(chat_id, user_id)
# Then later:
# await captcha.verify(chat_id, user_id, challenge_id, answer)

Configuration

You can override default settings:

config = {
    "length": 6,
    "charset": "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
    "width": 200,
    "height": 80,
    "noise_level": 0.4,
    "distortion_strength": 4.0,
    "ttl_seconds": 60,
    "max_attempts": 3,
    "rate_limit": 5,
}
gen = CaptchaGenerator(config)

Storage Backends

• MemoryStorage: in-memory dict (default, for testing)
• RedisStorage: persistent with TTL (production)

from gbkomi_captcha.storage.redis import RedisStorage
from gbkomi_captcha.middleware.challenge import get_storage

storage = RedisStorage(host="localhost", port=6379, db=0)
# Replace the default storage globally
import gbkomi_captcha.middleware.challenge as challenge
challenge._storage = storage

Security Notes

• The CAPTCHA answer is never sent to the client.
• Each challenge is one-time use and expires after TTL.
• Rate limiting prevents brute-force attacks.
• Wave distortion + random noise make OCR extremely difficult.

Requirements

• Python >= 3.10
• Pillow (image processing)

License

MIT

Author

GBKOMI