xlock-py 0.1.0__tar.gz

xlock_py-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+node_modules/
+*.pyc
+__pycache__/
+.env
+.env.local
+*.db
+dist/
+bun.lock
+xlock-server
+server/xlock-server
+server/server
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# WASM build tooling (cloned repos, venvs)
+compiler/wasm/wasmixer/
+compiler/wasm/.venv/
+
+# WASM intermediate build artifacts (keep .wasm outputs)
+compiler/wasm/build/*.wat
+compiler/wasm/build/*.d.ts
+compiler/wasm/build/*.js
+.claude/worktrees/
+capture.html
+mouse_capture.js
+seo-outreach-training.html
+test_cloakbrowser.ts

xlock_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 x-lock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xlock_py-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+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

xlock_py-0.1.0/README.md

@@ -0,0 +1,83 @@
+# 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

xlock_py-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "xlock-py"
+version = "0.1.0"
+description = "x-lock bot protection middleware for Python — invisible alternative to reCAPTCHA"
+requires-python = ">=3.8"
+license = "MIT"
+readme = "README.md"
+authors = [{ name = "x-lock", email = "dev@x-lock.dev" }]
+keywords = [
+    "xlock",
+    "bot-protection",
+    "captcha",
+    "middleware",
+    "fastapi",
+    "django",
+    "flask",
+    "recaptcha-alternative",
+    "proof-of-work",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: Django",
+    "Framework :: FastAPI",
+    "Framework :: Flask",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Security",
+]
+
+[project.optional-dependencies]
+fastapi = ["httpx>=0.24.0", "starlette>=0.20.0"]
+flask = ["httpx>=0.24.0", "flask>=2.0.0"]
+django = []
+all = ["httpx>=0.24.0", "starlette>=0.20.0", "flask>=2.0.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["xlock"]
+
+[project.urls]
+Homepage = "https://x-lock.dev"
+Repository = "https://github.com/x-lock-dev/xlock-python"
+Issues = "https://github.com/x-lock-dev/xlock-python/issues"

xlock_py-0.1.0/xlock/__init__.py

@@ -0,0 +1,38 @@
+"""
+xlock — invisible bot protection middleware for Python
+
+Supports FastAPI/Starlette, Django, and Flask.
+
+FastAPI:
+    from xlock import XLockMiddleware
+    app.add_middleware(XLockMiddleware, site_key="sk_...", protected_paths=["/api/auth"])
+
+Django (settings.py):
+    MIDDLEWARE = ["xlock.XLockDjangoMiddleware", ...]
+    XLOCK_SITE_KEY = "sk_..."
+    XLOCK_PROTECTED_PATHS = ["/api/auth/"]
+
+Flask:
+    from xlock import XLockFlask
+    xlock = XLockFlask(app, site_key="sk_...", protected_paths=["/api/auth"])
+"""
+
+from xlock.middleware import XLockDjangoMiddleware, XLockFlask
+from xlock.verify import verify, verify_async
+
+__all__ = [
+    "XLockMiddleware",
+    "XLockDjangoMiddleware",
+    "XLockFlask",
+    "verify",
+    "verify_async",
+]
+__version__ = "0.1.0"
+
+
+def __getattr__(name: str):
+    if name == "XLockMiddleware":
+        from xlock.middleware import XLockMiddleware
+
+        return XLockMiddleware
+    raise AttributeError(f"module 'xlock' has no attribute {name!r}")

xlock_py-0.1.0/xlock/middleware.py

@@ -0,0 +1,282 @@
+"""
+x-lock middleware implementations for FastAPI/Starlette, Django, and Flask.
+"""
+
+import json
+import logging
+import os
+import urllib.request
+import urllib.error
+
+logger = logging.getLogger("x-lock")
+
+DEFAULT_API_URL = "https://api.x-lock.dev"
+
+
+# ─── FastAPI / Starlette ───
+
+try:
+    from starlette.middleware.base import BaseHTTPMiddleware
+    from starlette.requests import Request
+    from starlette.responses import JSONResponse
+    import httpx
+
+    class XLockMiddleware(BaseHTTPMiddleware):
+        """
+        x-lock middleware for FastAPI / Starlette.
+
+        Usage:
+            from xlock import XLockMiddleware
+            app.add_middleware(
+                XLockMiddleware,
+                site_key="sk_...",
+                protected_paths=["/api/auth", "/api/checkout"],
+            )
+        """
+
+        def __init__(self, app, **kwargs):
+            super().__init__(app)
+            self.api_url = kwargs.get("api_url", DEFAULT_API_URL)
+            self.site_key = kwargs.get("site_key") or os.environ.get("XLOCK_SITE_KEY")
+            self.fail_open = kwargs.get("fail_open", True)
+            self.protected_paths: list = kwargs.get("protected_paths", [])
+
+            if not self.site_key:
+                logger.warning("No site key configured — skipping enforcement")
+
+        def _matches(self, path: str) -> bool:
+            return any(path.startswith(p) for p in self.protected_paths)
+
+        async def dispatch(self, request: Request, call_next):
+            if not self.site_key:
+                return await call_next(request)
+            if request.method != "POST":
+                return await call_next(request)
+            if self.protected_paths and not self._matches(request.url.path):
+                return await call_next(request)
+
+            token = request.headers.get("x-lock")
+
+            if not token:
+                return JSONResponse(
+                    {"error": "Blocked by x-lock: missing token"}, status_code=403
+                )
+
+            try:
+                if token.startswith("v3."):
+                    session_id = token.split(".")[1]
+                    enforce_url = f"{self.api_url}/v3/session/enforce"
+                    enforce_body = {"sessionId": session_id, "siteKey": self.site_key, "path": str(request.url.path)}
+                else:
+                    enforce_url = f"{self.api_url}/v1/enforce"
+                    enforce_body = {"token": token, "siteKey": self.site_key, "path": str(request.url.path)}
+
+                async with httpx.AsyncClient(timeout=5) as client:
+                    res = await client.post(
+                        enforce_url,
+                        json=enforce_body,
+                    )
+
+                if res.status_code == 403:
+                    data = res.json()
+                    return JSONResponse(
+                        {"error": "Blocked by x-lock", "reason": data.get("reason")},
+                        status_code=403,
+                    )
+
+                if not res.is_success and not self.fail_open:
+                    return JSONResponse(
+                        {"error": "x-lock verification failed"}, status_code=403
+                    )
+
+            except Exception as e:
+                logger.error(f"Enforcement error: {e}")
+                if not self.fail_open:
+                    return JSONResponse(
+                        {"error": "x-lock verification failed"}, status_code=403
+                    )
+
+            return await call_next(request)
+
+except ImportError:
+    # Starlette/httpx not installed — provide a stub
+    class XLockMiddleware:  # type: ignore[no-redef]
+        """Stub — install starlette and httpx for FastAPI support."""
+
+        def __init__(self, *args, **kwargs):
+            raise ImportError(
+                "Install starlette and httpx for FastAPI/Starlette support: "
+                "pip install xlock[fastapi]"
+            )
+
+
+# ─── Django ───
+
+class XLockDjangoMiddleware:
+    """
+    x-lock middleware for Django.
+
+    Usage (settings.py):
+        MIDDLEWARE = ["xlock.XLockDjangoMiddleware", ...]
+        XLOCK_SITE_KEY = "sk_..."
+        XLOCK_PROTECTED_PATHS = ["/api/auth/", "/api/checkout/"]
+        XLOCK_API_URL = "https://api.x-lock.dev"  # optional
+        XLOCK_FAIL_OPEN = True  # optional
+    """
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+        try:
+            from django.conf import settings as django_settings
+
+            self.api_url = getattr(django_settings, "XLOCK_API_URL", DEFAULT_API_URL)
+            self.site_key = getattr(django_settings, "XLOCK_SITE_KEY", None) or os.environ.get("XLOCK_SITE_KEY")
+            self.fail_open = getattr(django_settings, "XLOCK_FAIL_OPEN", True)
+            self.protected_paths = getattr(django_settings, "XLOCK_PROTECTED_PATHS", [])
+        except Exception:
+            self.api_url = os.environ.get("XLOCK_API_URL", DEFAULT_API_URL)
+            self.site_key = os.environ.get("XLOCK_SITE_KEY")
+            self.fail_open = True
+            self.protected_paths = []
+
+        if not self.site_key:
+            logger.warning("No site key configured — skipping enforcement")
+
+    def __call__(self, request):
+        if self.site_key and request.method == "POST":
+            if not self.protected_paths or self._matches(request.path):
+                result = self._enforce(request)
+                if result is not None:
+                    return result
+
+        return self.get_response(request)
+
+    def _matches(self, path: str) -> bool:
+        return any(path.startswith(p) for p in self.protected_paths)
+
+    def _enforce(self, request):
+        try:
+            from django.http import JsonResponse
+        except ImportError:
+            return None
+
+        token = request.META.get("HTTP_X_LOCK")
+
+        if not token:
+            return JsonResponse({"error": "Blocked by x-lock: missing token"}, status=403)
+
+        try:
+            if token.startswith("v3."):
+                session_id = token.split(".")[1]
+                enforce_url = f"{self.api_url}/v3/session/enforce"
+                payload = json.dumps({"sessionId": session_id, "siteKey": self.site_key, "path": request.path}).encode()
+            else:
+                enforce_url = f"{self.api_url}/v1/enforce"
+                payload = json.dumps({"token": token, "siteKey": self.site_key, "path": request.path}).encode()
+
+            req = urllib.request.Request(
+                enforce_url,
+                data=payload,
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+
+            with urllib.request.urlopen(req, timeout=5) as res:
+                pass  # 200 = allowed
+
+        except urllib.error.HTTPError as e:
+            if e.code == 403:
+                data = json.loads(e.read().decode())
+                return JsonResponse(
+                    {"error": "Blocked by x-lock", "reason": data.get("reason")},
+                    status=403,
+                )
+            if not self.fail_open:
+                return JsonResponse({"error": "x-lock verification failed"}, status=403)
+
+        except Exception as e:
+            logger.error(f"Enforcement error: {e}")
+            if not self.fail_open:
+                return JsonResponse({"error": "x-lock verification failed"}, status=403)
+
+        return None
+
+
+# ─── Flask ───
+
+class XLockFlask:
+    """
+    x-lock middleware for Flask.
+
+    Usage:
+        from xlock import XLockFlask
+        app = Flask(__name__)
+        xlock = XLockFlask(app, site_key="sk_...", protected_paths=["/api/auth"])
+    """
+
+    def __init__(self, app=None, **kwargs):
+        self.api_url = kwargs.get("api_url", DEFAULT_API_URL)
+        self.site_key = kwargs.get("site_key") or os.environ.get("XLOCK_SITE_KEY")
+        self.fail_open = kwargs.get("fail_open", True)
+        self.protected_paths: list = kwargs.get("protected_paths", [])
+
+        if app:
+            self.init_app(app)
+
+    def init_app(self, app):
+        if not self.site_key:
+            app.logger.warning("[x-lock] No site key configured — skipping enforcement")
+            return
+
+        app.before_request(self._enforce)
+
+    def _matches(self, path: str) -> bool:
+        return any(path.startswith(p) for p in self.protected_paths)
+
+    def _enforce(self):
+        try:
+            from flask import request, jsonify
+        except ImportError:
+            return None
+
+        if request.method != "POST":
+            return None
+        if self.protected_paths and not self._matches(request.path):
+            return None
+
+        token = request.headers.get("x-lock")
+
+        if not token:
+            return jsonify(error="Blocked by x-lock: missing token"), 403
+
+        try:
+            import httpx
+
+            if token.startswith("v3."):
+                session_id = token.split(".")[1]
+                enforce_url = f"{self.api_url}/v3/session/enforce"
+                enforce_body = {"sessionId": session_id, "siteKey": self.site_key, "path": request.path}
+            else:
+                enforce_url = f"{self.api_url}/v1/enforce"
+                enforce_body = {"token": token, "siteKey": self.site_key, "path": request.path}
+
+            with httpx.Client(timeout=5) as client:
+                res = client.post(
+                    enforce_url,
+                    json=enforce_body,
+                )
+
+            if res.status_code == 403:
+                data = res.json()
+                return jsonify(error="Blocked by x-lock", reason=data.get("reason")), 403
+
+            if not res.ok and not self.fail_open:
+                return jsonify(error="x-lock verification failed"), 403
+
+        except Exception as e:
+            logger.error(f"Enforcement error: {e}")
+            if not self.fail_open:
+                return jsonify(error="x-lock verification failed"), 403
+
+        return None

xlock_py-0.1.0/xlock/verify.py

@@ -0,0 +1,90 @@
+"""
+Core x-lock verification — usable standalone without any framework.
+"""
+
+import json
+import urllib.request
+import urllib.error
+from typing import Optional
+
+DEFAULT_API_URL = "https://api.x-lock.dev"
+
+
+class VerifyResult:
+    __slots__ = ("blocked", "reason", "error")
+
+    def __init__(self, blocked: bool = False, reason: Optional[str] = None, error: bool = False):
+        self.blocked = blocked
+        self.reason = reason
+        self.error = error
+
+
+def verify(
+    token: str,
+    site_key: str,
+    path: Optional[str] = None,
+    api_url: str = DEFAULT_API_URL,
+) -> VerifyResult:
+    """Synchronously verify an x-lock token. Works with stdlib only."""
+    if token.startswith("v3."):
+        session_id = token.split(".")[1]
+        enforce_url = f"{api_url}/v3/session/enforce"
+        body = {"sessionId": session_id, "siteKey": site_key}
+    else:
+        enforce_url = f"{api_url}/v1/enforce"
+        body = {"token": token, "siteKey": site_key}
+
+    if path:
+        body["path"] = path
+
+    payload = json.dumps(body).encode()
+    req = urllib.request.Request(
+        enforce_url,
+        data=payload,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=5):
+            return VerifyResult(blocked=False)
+    except urllib.error.HTTPError as e:
+        if e.code == 403:
+            data = json.loads(e.read().decode())
+            return VerifyResult(blocked=True, reason=data.get("reason"))
+        return VerifyResult(blocked=False, error=True)
+    except Exception:
+        return VerifyResult(blocked=False, error=True)
+
+
+async def verify_async(
+    token: str,
+    site_key: str,
+    path: Optional[str] = None,
+    api_url: str = DEFAULT_API_URL,
+) -> VerifyResult:
+    """Async verify using httpx. Requires: pip install xlock[fastapi]"""
+    import httpx
+
+    if token.startswith("v3."):
+        session_id = token.split(".")[1]
+        enforce_url = f"{api_url}/v3/session/enforce"
+        body = {"sessionId": session_id, "siteKey": site_key}
+    else:
+        enforce_url = f"{api_url}/v1/enforce"
+        body = {"token": token, "siteKey": site_key}
+
+    if path:
+        body["path"] = path
+
+    async with httpx.AsyncClient(timeout=5) as client:
+        res = await client.post(enforce_url, json=body)
+
+    if res.status_code == 403:
+        data = res.json()
+        return VerifyResult(blocked=True, reason=data.get("reason"))
+
+    if not res.is_success:
+        return VerifyResult(blocked=False, error=True)
+
+    return VerifyResult(blocked=False)