Metadata-Version: 2.4
Name: xlock-py
Version: 0.1.1
Summary: x-lock bot protection middleware for Python — invisible alternative to reCAPTCHA
Project-URL: Homepage, https://x-lock.cloud
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.cloud>
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

Flow-aware automation protection for Python. Protect auth, checkout, and API routes while keeping flow structure in code.

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"],
    flows=[
        {
            "slug": "login",
            "match": [{"method": "POST", "pathPattern": "/api/auth/login"}],
        },
        {
            "slug": "checkout",
            "match": [{"method": "POST", "pathPattern": "/api/checkout"}],
        },
    ],
)
```

### Django

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

XLOCK_SITE_KEY = "sk_..."
XLOCK_PROTECTED_PATHS = ["/api/auth/", "/api/checkout/"]
XLOCK_FLOWS = [
    {
        "slug": "login",
        "match": [{"method": "POST", "pathPattern": "/api/auth/login"}],
    }
]
```

### Flask

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

app = Flask(__name__)
xlock = XLockFlask(
    app,
    site_key="sk_...",
    protected_paths=["/api/auth"],
    flows=[
        {
            "slug": "login",
            "match": [{"method": "POST", "pathPattern": "/api/auth/login"}],
        }
    ],
)
```

### Direct Verification

```python
from xlock import verify

result = verify(
    token="v3.abc123...",
    site_key="sk_...",
    method="POST",
    path="/api/login",
    domain="app.example.com",
    flows=[
        {
            "slug": "login",
            "match": [{"method": "POST", "pathPattern": "/api/login"}],
        }
    ],
)
if result.blocked:
    print(f"Blocked: {result.reason}")
else:
    print(result.action, result.resolved_flow)
```

### Result Contract

`VerifyResult` includes:

- `action`: `allow`, `log`, `pow`, `challenge`, `deny`, `delay`
- `reason`
- `score`
- `signals`
- `flow_hint`
- `resolved_flow`
- `delay_ms`
- `challenge_mode`
- `policy_id`

## 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` | Runtime API endpoint |
| `fail_open` | `XLOCK_FAIL_OPEN` | `True` | Allow requests on API errors |
| `protected_paths` | `XLOCK_PROTECTED_PATHS` | `[]` | Path prefixes to protect |
| `flows` / `XLOCK_FLOWS` | — | `[]` | SDK-canonical flow declarations used for local `flowHint` resolution |

## License

MIT
