xlock-py 0.1.1

x-lock bot protection middleware for Python — invisible alternative to reCAPTCHA

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

# 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

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

# 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

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

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