veridian-sdk 0.1.0__tar.gz

veridian_sdk-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.env
+.venv/
+__pycache__/
+.atl/
+.claude/worktrees/
+*.db
+*.sqlite3
+.pytest_cache/
+dist/

veridian_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Veridian authors
+
+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.

veridian_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: veridian-sdk
+Version: 0.1.0
+Summary: ASGI middleware that reports access events to Veridian and blocks sessions, IPs and users on its blocklist
+Project-URL: Homepage, https://github.com/Juanalv1/veridian
+Project-URL: Repository, https://github.com/Juanalv1/veridian
+Project-URL: Issues, https://github.com/Juanalv1/veridian/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: httpx
+Requires-Dist: starlette
+Description-Content-Type: text/markdown
+
+# veridian-sdk
+
+ASGI middleware for [Veridian](https://github.com/Juanalv1/veridian). It reports each request of your app to the Veridian engine and answers `403 {"error": "blocked"}` to any session, IP or user that is on the engine's blocklist.
+
+## Install
+
+```bash
+pip install veridian-sdk
+```
+
+Requires Python 3.12 or newer.
+
+## Usage
+
+Works with any ASGI app (FastAPI, Starlette). Wrap the app and tell the middleware who the user and the session are:
+
+```python
+import os
+
+from fastapi import FastAPI
+from veridian_sdk import VeridianMiddleware
+
+app = FastAPI()
+
+app = VeridianMiddleware(
+    app,
+    token=os.environ["VERIDIAN_TOKEN"],
+    base_url=os.environ["VERIDIAN_URL"],
+    user_id=lambda request: request.state.user_id if hasattr(request.state, "user_id") else None,
+    session_id=lambda request: request.cookies.get("sid"),
+    trusted_proxies=0,
+)
+```
+
+- `user_id` and `session_id` are callables that take a Starlette `Request` and return a string or `None`. They run before the app (to enforce the blocklist) and again after it (the app may have just logged the user in). Requests with no user are not reported.
+- Pass a hash of the session cookie as `session_id`, never the cookie itself.
+- `trusted_proxies` is the number of your own proxies in front of the app. With `0` the connection IP is used and `X-Forwarded-For` is ignored, because any client can write it.
+- `exclude_paths` (default `("/static",)`) lists path prefixes that pass straight through with no event and no blocklist check.
+
+## What is sent
+
+One event per request, sent in the background in batches: `id`, `ts`, `user_id`, `session_id`, `ip`, `user_agent` (first 200 characters), `device_id`, `method`, `route` (the route template, for example `/items/{item_id}`), `status` and `bytes`.
+
+The middleware also sets its own device cookie (`vrd_did`) in the user's browser.
+
+## What is never sent
+
+Request and response bodies, and passwords, are never read into events.
+
+## Fail-open
+
+If the engine is slow or down, your app is not delayed or broken: the middleware keeps using the last blocklist it knew.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

veridian_sdk-0.1.0/README.md

@@ -0,0 +1,56 @@
+# veridian-sdk
+
+ASGI middleware for [Veridian](https://github.com/Juanalv1/veridian). It reports each request of your app to the Veridian engine and answers `403 {"error": "blocked"}` to any session, IP or user that is on the engine's blocklist.
+
+## Install
+
+```bash
+pip install veridian-sdk
+```
+
+Requires Python 3.12 or newer.
+
+## Usage
+
+Works with any ASGI app (FastAPI, Starlette). Wrap the app and tell the middleware who the user and the session are:
+
+```python
+import os
+
+from fastapi import FastAPI
+from veridian_sdk import VeridianMiddleware
+
+app = FastAPI()
+
+app = VeridianMiddleware(
+    app,
+    token=os.environ["VERIDIAN_TOKEN"],
+    base_url=os.environ["VERIDIAN_URL"],
+    user_id=lambda request: request.state.user_id if hasattr(request.state, "user_id") else None,
+    session_id=lambda request: request.cookies.get("sid"),
+    trusted_proxies=0,
+)
+```
+
+- `user_id` and `session_id` are callables that take a Starlette `Request` and return a string or `None`. They run before the app (to enforce the blocklist) and again after it (the app may have just logged the user in). Requests with no user are not reported.
+- Pass a hash of the session cookie as `session_id`, never the cookie itself.
+- `trusted_proxies` is the number of your own proxies in front of the app. With `0` the connection IP is used and `X-Forwarded-For` is ignored, because any client can write it.
+- `exclude_paths` (default `("/static",)`) lists path prefixes that pass straight through with no event and no blocklist check.
+
+## What is sent
+
+One event per request, sent in the background in batches: `id`, `ts`, `user_id`, `session_id`, `ip`, `user_agent` (first 200 characters), `device_id`, `method`, `route` (the route template, for example `/items/{item_id}`), `status` and `bytes`.
+
+The middleware also sets its own device cookie (`vrd_did`) in the user's browser.
+
+## What is never sent
+
+Request and response bodies, and passwords, are never read into events.
+
+## Fail-open
+
+If the engine is slow or down, your app is not delayed or broken: the middleware keeps using the last blocklist it knew.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

veridian_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "veridian-sdk"
+version = "0.1.0"
+description = "ASGI middleware that reports access events to Veridian and blocks sessions, IPs and users on its blocklist"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = [
+    "httpx",
+    "starlette",
+]
+
+[project.urls]
+Homepage = "https://github.com/Juanalv1/veridian"
+Repository = "https://github.com/Juanalv1/veridian"
+Issues = "https://github.com/Juanalv1/veridian/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/veridian_sdk"]

veridian_sdk-0.1.0/src/veridian_sdk/__init__.py

@@ -0,0 +1,3 @@
+from veridian_sdk.middleware import VeridianMiddleware, resolve_client_ip
+
+__all__ = ["VeridianMiddleware", "resolve_client_ip"]

veridian_sdk-0.1.0/src/veridian_sdk/middleware.py

@@ -0,0 +1,332 @@
+"""Veridian ASGI middleware.
+
+Reports one event per request to the engine (in the background, batched) and
+refuses requests whose session, IP or user is on the engine's blocklist
+(each refusal is reported as a 403 event too). It is fail-open: the engine being slow or down never delays or breaks the app.
+Request and response bodies are never read into events.
+"""
+
+import asyncio
+import logging
+import uuid
+from collections import deque
+from datetime import datetime, timezone
+from http.cookies import SimpleCookie
+
+import httpx
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Match
+
+log = logging.getLogger("veridian")
+
+DEVICE_COOKIE = "vrd_did"
+DEVICE_COOKIE_MAX_AGE = 60 * 60 * 24 * 365
+MAX_BATCH = 200
+DEFAULT_EXCLUDE_PATHS = ("/static",)
+
+
+def resolve_client_ip(scope: dict, trusted_proxies: int = 0) -> str:
+    """Client IP that the client cannot choose.
+
+    With 0 trusted proxies the socket peer is used and X-Forwarded-For is
+    ignored (anyone can write it). With N, the Nth value from the right is
+    used: the one appended by our outermost proxy. Fewer values than N falls
+    back to the first value.
+    """
+    client = scope.get("client")
+    peer = client[0] if client else ""
+    if trusted_proxies <= 0:
+        return peer
+    raw = [v for k, v in scope.get("headers", []) if k == b"x-forwarded-for"]
+    values = [p.strip() for h in raw for p in h.decode("latin-1").split(",") if p.strip()]
+    if not values:
+        return peer
+    if len(values) < trusted_proxies:
+        return values[0]
+    return values[-trusted_proxies]
+
+
+def _cookie(scope: dict, name: str) -> str | None:
+    for k, v in scope.get("headers", []):
+        if k == b"cookie":
+            jar = SimpleCookie()
+            try:
+                jar.load(v.decode("latin-1"))
+            except Exception:
+                return None
+            if name in jar:
+                return jar[name].value
+    return None
+
+
+def _header(scope: dict, name: bytes) -> str | None:
+    for k, v in scope.get("headers", []):
+        if k == name:
+            return v.decode("latin-1")
+    return None
+
+
+def _route_template(scope: dict) -> str:
+    route = scope.get("route")
+    if route is not None:
+        template = getattr(route, "path_format", None) or getattr(route, "path", None)
+        if template:
+            return template
+    return scope.get("path", "")
+
+
+def _routes_of(app) -> list:
+    """The router's routes, found by walking the `.app` chain of wrapped apps."""
+    for _ in range(16):
+        routes = getattr(app, "routes", None)
+        if routes is not None:
+            return list(routes)
+        app = getattr(app, "app", None)
+        if app is None:
+            break
+    return []
+
+
+def _template_without_calling(scope: dict, routes: list) -> str:
+    """Route template for a request the app never saw (it was blocked).
+
+    Matches the path against the router's routes without running any endpoint.
+    Mounted sub-apps and anything unmatched fall back to the raw path: it may
+    carry IDs (e.g. /invoices/42), so the engine groups that access less well.
+    """
+    for route in routes:
+        try:
+            match, _ = route.matches(scope)
+        except Exception:
+            continue
+        template = getattr(route, "path_format", None)
+        if match == Match.FULL and template and not hasattr(route, "routes"):
+            return template
+    return scope.get("path", "")
+
+
+class VeridianMiddleware:
+    def __init__(
+        self,
+        app,
+        token: str,
+        base_url: str,
+        user_id=lambda request: None,
+        session_id=lambda request: None,
+        trusted_proxies: int = 0,
+        http_client: httpx.AsyncClient | None = None,
+        flush_interval: float = 2.0,
+        poll_interval: float = 2.0,
+        max_queue: int = 1000,
+        background: bool = True,
+        exclude_paths: tuple[str, ...] = DEFAULT_EXCLUDE_PATHS,
+    ):
+        """`user_id` and `session_id` are callables taking a Starlette Request
+        and returning a string or None. They run before the app (to enforce the
+        blocklist) and again after it (the app may have just logged the user in,
+        e.g. by setting request.state). `background=False` disables the
+        flush/poll tasks so tests can drive flush() and refresh_blocklist().
+
+        `exclude_paths` are path prefixes (whole segments) that pass straight
+        through: no event, no device cookie and no blocklist check. Static
+        assets are not user actions, and a blocked attacker only needs to be
+        stopped on the app's routes, so `/static` is excluded by default."""
+        self.app = app
+        self.token = token
+        self.base_url = base_url.rstrip("/")
+        self.user_id = user_id
+        self.session_id = session_id
+        self.trusted_proxies = trusted_proxies
+        self.exclude_paths = tuple(p.rstrip("/") for p in exclude_paths)
+        self.client = http_client or httpx.AsyncClient(timeout=2.0)
+        self.flush_interval = flush_interval
+        self.poll_interval = poll_interval
+        self.background = background
+        self.queue: deque[dict] = deque(maxlen=max_queue)  # drops oldest when full
+        self.blocklist_version: int | None = None
+        self.blocked = {"users": set(), "sessions": set(), "ips": set()}
+        self._tasks: list[asyncio.Task] = []
+
+    # --- ASGI --------------------------------------------------------------
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] == "lifespan":
+            await self.app(scope, self._watch_shutdown(receive), send)
+            return
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        self._ensure_background()
+        if self._is_excluded(scope.get("path", "")):
+            await self.app(scope, receive, send)
+            return
+        request = Request(scope)
+        ip = resolve_client_ip(scope, self.trusted_proxies)
+
+        if self._is_blocked(request, ip):
+            response = JSONResponse({"error": "blocked"}, status_code=403)
+            await response(scope, receive, send)
+            # The app is not called, so the route template is matched by hand.
+            # The device cookie is only read here, never issued to a blocked client.
+            self._record(
+                scope, request, ip, _cookie(scope, DEVICE_COOKIE), 403, len(response.body),
+                route=_template_without_calling(scope, _routes_of(scope.get("app") or self.app)),
+            )
+            return
+
+        device_id = _cookie(scope, DEVICE_COOKIE)
+        new_device = device_id is None
+        if new_device:
+            device_id = "d_" + uuid.uuid4().hex[:12]
+        status = 0
+        size = 0
+
+        async def send_wrapper(message):
+            nonlocal status, size
+            if message["type"] == "http.response.start":
+                status = message["status"]
+                if new_device:
+                    cookie = (
+                        f"{DEVICE_COOKIE}={device_id}; Path=/; HttpOnly; SameSite=Lax; "
+                        f"Max-Age={DEVICE_COOKIE_MAX_AGE}"
+                    )
+                    message = {
+                        **message,
+                        "headers": [*message.get("headers", []), (b"set-cookie", cookie.encode())],
+                    }
+            elif message["type"] == "http.response.body":
+                size += len(message.get("body", b""))
+            await send(message)
+
+        try:
+            await self.app(scope, receive, send_wrapper)
+        finally:
+            self._record(scope, request, ip, device_id, status, size)
+
+    def _is_excluded(self, path: str) -> bool:
+        return any(path == p or path.startswith(p + "/") for p in self.exclude_paths)
+
+    def _watch_shutdown(self, receive):
+        async def wrapped():
+            message = await receive()
+            if message["type"] == "lifespan.shutdown":
+                await self.aclose()
+            return message
+
+        return wrapped
+
+    # --- blocklist ---------------------------------------------------------
+
+    def _safe(self, fn, request):
+        try:
+            value = fn(request)
+            return value if value else None
+        except Exception:
+            log.exception("veridian: identity callable failed")
+            return None
+
+    def _is_blocked(self, request: Request, ip: str) -> bool:
+        b = self.blocked
+        if ip and ip in b["ips"]:
+            return True
+        session = self._safe(self.session_id, request)
+        if session and session in b["sessions"]:
+            return True
+        user = self._safe(self.user_id, request)
+        return bool(user and user in b["users"])
+
+    async def refresh_blocklist(self) -> None:
+        """Poll the engine once. Any failure keeps the last known list."""
+        try:
+            params = {"since": self.blocklist_version} if self.blocklist_version is not None else None
+            r = await self.client.get(
+                f"{self.base_url}/v1/blocklist", params=params, headers=self._auth()
+            )
+            if r.status_code == 304:
+                return
+            if r.status_code != 200:
+                return
+            data = r.json()
+            self.blocked = {
+                "users": set(map(str, data.get("users", []))),
+                "sessions": set(map(str, data.get("sessions", []))),
+                "ips": set(map(str, data.get("ips", []))),
+            }
+            self.blocklist_version = int(data["version"])
+        except Exception as exc:
+            log.warning("veridian: blocklist refresh failed: %s", exc)
+
+    # --- events ------------------------------------------------------------
+
+    def _record(self, scope, request, ip, device_id, status, size, route=None) -> None:
+        try:
+            user = self._safe(self.user_id, request)
+            if not user:
+                return
+            self.queue.append(
+                {
+                    "id": "e_" + uuid.uuid4().hex,
+                    "ts": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+                    "user_id": user,
+                    "session_id": self._safe(self.session_id, request),
+                    "ip": ip,
+                    "user_agent": (_header(scope, b"user-agent") or "")[:200],
+                    "device_id": device_id,
+                    "method": scope["method"],
+                    "route": route if route is not None else _route_template(scope),
+                    "status": status,
+                    "bytes": size,
+                }
+            )
+        except Exception:
+            log.exception("veridian: could not record event")
+
+    async def flush(self) -> None:
+        """Send queued events once. On failure they stay queued (ids make the
+        retry idempotent)."""
+        batch = list(self.queue)[:MAX_BATCH]
+        if not batch:
+            return
+        try:
+            r = await self.client.post(
+                f"{self.base_url}/v1/events", json={"events": batch}, headers=self._auth()
+            )
+            if r.status_code != 202:
+                return
+        except Exception as exc:
+            log.warning("veridian: event flush failed: %s", exc)
+            return
+        sent = {e["id"] for e in batch}
+        remaining = [e for e in self.queue if e["id"] not in sent]
+        self.queue.clear()
+        self.queue.extend(remaining)
+
+    # --- background --------------------------------------------------------
+
+    def _auth(self) -> dict:
+        return {"Authorization": f"Bearer {self.token}"}
+
+    def _ensure_background(self) -> None:
+        if not self.background or self._tasks:
+            return
+        loop = asyncio.get_running_loop()
+        self._tasks = [
+            loop.create_task(self._loop(self.flush, self.flush_interval)),
+            loop.create_task(self._loop(self.refresh_blocklist, self.poll_interval)),
+        ]
+
+    @staticmethod
+    async def _loop(fn, interval: float) -> None:
+        while True:
+            try:
+                await fn()
+            except Exception:
+                log.exception("veridian: background task error")
+            await asyncio.sleep(interval)
+
+    async def aclose(self) -> None:
+        for t in self._tasks:
+            t.cancel()
+        self._tasks = []