Metadata-Version: 2.4
Name: xlock-py
Version: 0.1.0
Summary: x-lock bot protection middleware for Python — invisible alternative to reCAPTCHA
Project-URL: Homepage, https://x-lock.dev
Project-URL: Repository, https://github.com/x-lock-dev/xlock-python
Project-URL: Issues, https://github.com/x-lock-dev/xlock-python/issues
Author-email: x-lock <dev@x-lock.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: bot-protection,captcha,django,fastapi,flask,middleware,proof-of-work,recaptcha-alternative,xlock
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: FastAPI
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Security
Requires-Python: >=3.8
Provides-Extra: all
Requires-Dist: flask>=2.0.0; extra == 'all'
Requires-Dist: httpx>=0.24.0; extra == 'all'
Requires-Dist: starlette>=0.20.0; extra == 'all'
Provides-Extra: django
Provides-Extra: fastapi
Requires-Dist: httpx>=0.24.0; extra == 'fastapi'
Requires-Dist: starlette>=0.20.0; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=2.0.0; extra == 'flask'
Requires-Dist: httpx>=0.24.0; extra == 'flask'
Description-Content-Type: text/markdown

# xlock-py

Invisible bot protection middleware for Python. Drop-in replacement for reCAPTCHA, Turnstile, and hCaptcha — no visual challenges, no user friction.

Supports **FastAPI**, **Django**, and **Flask**.

## Install

```bash
# Core (Django — no extra deps)
pip install xlock-py

# FastAPI / Starlette
pip install xlock-py[fastapi]

# Flask
pip install xlock-py[flask]

# Everything
pip install xlock-py[all]
```

## Quick Start

### FastAPI / Starlette

```python
from fastapi import FastAPI
from xlock import XLockMiddleware

app = FastAPI()
app.add_middleware(
    XLockMiddleware,
    site_key="sk_...",
    protected_paths=["/api/auth", "/api/checkout"],
)
```

### Django

```python
# settings.py
MIDDLEWARE = [
    "xlock.XLockDjangoMiddleware",
    # ... other middleware
]

XLOCK_SITE_KEY = "sk_..."
XLOCK_PROTECTED_PATHS = ["/api/auth/", "/api/checkout/"]
```

### Flask

```python
from flask import Flask
from xlock import XLockFlask

app = Flask(__name__)
xlock = XLockFlask(app, site_key="sk_...", protected_paths=["/api/auth"])
```

### Direct Verification

```python
from xlock import verify

result = verify(token="v3.abc123...", site_key="sk_...", path="/api/login")
if result.blocked:
    print(f"Blocked: {result.reason}")
```

## Configuration

| Option | Env Var | Default | Description |
|--------|---------|---------|-------------|
| `site_key` | `XLOCK_SITE_KEY` | — | Your x-lock site key |
| `api_url` | `XLOCK_API_URL` | `https://api.x-lock.dev` | API endpoint |
| `fail_open` | `XLOCK_FAIL_OPEN` | `True` | Allow requests on API errors |
| `protected_paths` | `XLOCK_PROTECTED_PATHS` | `[]` | Path prefixes to protect |

## License

MIT
