Metadata-Version: 2.4
Name: powchallenge_server
Version: 1.0.3
Summary: Server validation library for the POW Captcha ecosystem.
Project-URL: Homepage, https://github.com/Simon-Bertrand/POWChallenge
Project-URL: Repository, https://github.com/Simon-Bertrand/POWChallenge
Author: Simon Bertrand
License: MIT
Keywords: argon2id,bot-protection,captcha,pow,security
Requires-Python: >=3.10
Requires-Dist: argon2-cffi
Requires-Dist: orjson
Requires-Dist: pydantic
Requires-Dist: pydantic-settings
Requires-Dist: uuid7
Provides-Extra: test
Requires-Dist: aiofiles; extra == 'test'
Requires-Dist: fastapi; extra == 'test'
Requires-Dist: httpx; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: uvicorn[standard]; extra == 'test'
Description-Content-Type: text/markdown

# powchallenge_server (Python)

A fully typed, robust Proof-of-Work (PoW) CAPTCHA server library for Python. This package provides the backend validation and challenge generation for the POW Captcha ecosystem. It prevents botnets, DDoS attacks, and credential stuffing by leveraging memory-hard cryptographic puzzles.

## Features
* **Argon2id Powered**: Defeats GPU and ASIC parallelism effectively.
* **Async IO Support**: Designed for high performance and fast concurrency.
* **Storage Backends**: Out-of-the-box support for internal Memory storage and Redis.
* **Framework Agnostic**: Integrates beautifully with FastAPI, Starlette, Flask, or raw ASGI/WSGI applications.

## Installation

Install using `pip`, `poetry`, or `uv`:

```bash
pip install powchallenge_server
```

## How to Use

Here is a simple example integrating with **FastAPI**:

```python
from fastapi import FastAPI, Request
from powchallenge_server import POWCaptchaServer
from powchallenge_server.interfaces import CaptchaValidatedPOW
from ipaddress import IPv4Address

app = FastAPI()

# Initialize server: Difficulty 10, 300 seconds validity, False for Memory Storage
captcha = POWCaptchaServer(10, 300, False)

@app.get("/challenge")
async def get_challenge(request: Request):
    ip = IPv4Address(request.client.host)
    challenge = await captcha.get_challenge(ip)
    return challenge

@app.post("/verify")
async def verify(payload: CaptchaValidatedPOW, request: Request):
    ip = IPv4Address(request.client.host)
    try:
        await captcha.verify_pow(payload, ip)
        return {"message": "Access Granted"}
    except Exception as e:
        return {"error": str(e)}
```

For advanced configuration, error handling, and Redis integration, please check the main documentation.
