Metadata-Version: 2.4
Name: gbkomi-captcha
Version: 0.1.1
Summary: Bot-proof image CAPTCHA generator with Flask, FastAPI, and Telegram support
Author: gbkomi
License: MIT
Project-URL: Homepage, https://github.com/gbkomi/gbkomi-captcha
Project-URL: Repository, https://github.com/gbkomi/gbkomi-captcha
Project-URL: Issues, https://github.com/gbkomi/gbkomi-captcha/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Framework :: Flask
Classifier: Framework :: FastAPI
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: Pillow>=10.0.0
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == "redis"
Provides-Extra: web
Requires-Dist: Flask>=2.3.0; extra == "web"
Requires-Dist: FastAPI>=0.100.0; extra == "web"
Requires-Dist: uvicorn>=0.23.0; extra == "web"
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=20.0; extra == "telegram"
Provides-Extra: all
Requires-Dist: redis>=5.0.0; extra == "all"
Requires-Dist: Flask>=2.3.0; extra == "all"
Requires-Dist: FastAPI>=0.100.0; extra == "all"
Requires-Dist: uvicorn>=0.23.0; extra == "all"
Requires-Dist: python-telegram-bot>=20.0; extra == "all"

```markdown
# 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:

```bash
pip install gbkomi-captcha[redis]
```

For web integrations:

```bash
pip install gbkomi-captcha[web]
```

For Telegram bots:

```bash
pip install gbkomi-captcha[telegram]
```

## Quick Start

### Generate a CAPTCHA image

```python
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

```python
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

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

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

### With Telegram Bot

```python
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:

```python
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)

```python
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
