zubbl-fastapi 0.1.0__py3-none-any.whl

zubbl_fastapi/__init__.py

@@ -0,0 +1,37 @@
+from .integration import (
+    BlockResponseHandler,
+    DEFAULT_EXCLUDED_PATHS,
+    IdentityResolver,
+    MissingIdentityMode,
+    Zubbl,
+    ZubblFastAPIError,
+)
+from .endpoints import (
+    RouteCatalogue,
+    RouteCatalogueDiff,
+    RouteDescriptor,
+)
+from .identity import (
+    IdentityResolutionError,
+    identify_from_state,
+)
+from .middleware import ZubblMiddleware
+from .observation import RuntimeResponseObservation
+
+__all__ = [
+    "BlockResponseHandler",
+    "IdentityResolutionError",
+    "identify_from_state",
+    "DEFAULT_EXCLUDED_PATHS",
+    "IdentityResolver",
+    "MissingIdentityMode",
+    "RouteDescriptor",
+    "RouteCatalogueDiff",
+    "RouteCatalogue",
+    "RuntimeResponseObservation",
+    "Zubbl",
+    "ZubblFastAPIError",
+    "ZubblMiddleware",
+]
+
+__version__ = "0.1.0"

zubbl_fastapi/endpoints.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.routing import APIRoute
+
+
+def _normalise_path(value: str) -> str:
+    cleaned = value.strip()
+
+    if not cleaned:
+        raise ValueError("endpoint path must be a non-empty string")
+
+    if not cleaned.startswith("/"):
+        cleaned = f"/{cleaned}"
+
+    if len(cleaned) > 1:
+        cleaned = cleaned.rstrip("/")
+
+    return cleaned or "/"
+
+
+def _clean_optional_string(value: Any) -> str | None:
+    if not isinstance(value, str):
+        return None
+
+    cleaned = value.strip()
+    return cleaned or None
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class RouteDescriptor:
+    """
+    One stable application endpoint.
+
+    A FastAPI route supporting several methods becomes one descriptor per
+    method, giving every endpoint a deterministic path/method identity.
+    """
+
+    path: str
+    method: str
+    name: str
+    operation_id: str | None = None
+    tags: tuple[str, ...] = ()
+    include_in_schema: bool = True
+
+    def __post_init__(self) -> None:
+        path = _normalise_path(self.path)
+        method = self.method.strip().upper()
+        name = self.name.strip()
+
+        if not method:
+            raise ValueError("endpoint method must be a non-empty string")
+
+        if not name:
+            raise ValueError("endpoint name must be a non-empty string")
+
+        tags = tuple(
+            dict.fromkeys(
+                str(tag).strip()
+                for tag in self.tags
+                if str(tag).strip()
+            )
+        )
+
+        object.__setattr__(self, "path", path)
+        object.__setattr__(self, "method", method)
+        object.__setattr__(self, "name", name)
+        object.__setattr__(
+            self,
+            "operation_id",
+            _clean_optional_string(self.operation_id),
+        )
+        object.__setattr__(self, "tags", tags)
+
+    @property
+    def key(self) -> tuple[str, str]:
+        return self.path, self.method
+
+    @property
+    def identifier(self) -> str:
+        return f"{self.method} {self.path}"
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "path": self.path,
+            "method": self.method,
+            "name": self.name,
+            "operation_id": self.operation_id,
+            "tags": list(self.tags),
+            "include_in_schema": self.include_in_schema,
+        }
+
+    @property
+    def fingerprint(self) -> str:
+        payload = json.dumps(
+            self.as_dict(),
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+        ).encode("utf-8")
+
+        return hashlib.sha256(payload).hexdigest()
+
+
+@dataclass(frozen=True, slots=True)
+class RouteCatalogueDiff:
+    added: tuple[RouteDescriptor, ...]
+    removed: tuple[RouteDescriptor, ...]
+    changed: tuple[
+        tuple[RouteDescriptor, RouteDescriptor],
+        ...,
+    ]
+
+    @property
+    def has_changes(self) -> bool:
+        return bool(self.added or self.removed or self.changed)
+
+
+@dataclass(frozen=True, slots=True)
+class RouteCatalogue:
+    routes: tuple[RouteDescriptor, ...]
+
+    def __post_init__(self) -> None:
+        ordered = tuple(
+            sorted(
+                self.routes,
+                key=lambda route: (
+                    route.path,
+                    route.method,
+                    route.name,
+                ),
+            )
+        )
+
+        keys = [route.key for route in ordered]
+
+        if len(keys) != len(set(keys)):
+            raise ValueError(
+                "route catalogue contains duplicate path/method entries"
+            )
+
+        object.__setattr__(self, "routes", ordered)
+
+    @classmethod
+    def empty(cls) -> RouteCatalogue:
+        return cls(routes=())
+
+    @classmethod
+    def from_app(
+        cls,
+        app: FastAPI,
+        *,
+        include_hidden: bool = False,
+    ) -> RouteCatalogue:
+        descriptors: list[RouteDescriptor] = []
+
+        for route in app.routes:
+            if not isinstance(route, APIRoute):
+                continue
+
+            if not include_hidden and not route.include_in_schema:
+                continue
+
+            methods = sorted(route.methods or ())
+
+            for method in methods:
+                if method in {"HEAD", "OPTIONS"}:
+                    continue
+
+                operation_id = (
+                    route.operation_id
+                    or getattr(route, "unique_id", None)
+                )
+
+                descriptors.append(
+                    RouteDescriptor(
+                        path=route.path,
+                        method=method,
+                        name=route.name,
+                        operation_id=operation_id,
+                        tags=tuple(route.tags or ()),
+                        include_in_schema=route.include_in_schema,
+                    )
+                )
+
+        return cls(routes=tuple(descriptors))
+
+    def __len__(self) -> int:
+        return len(self.routes)
+
+    def __iter__(self):
+        return iter(self.routes)
+
+    def lookup(
+        self,
+        path: str,
+        method: str,
+    ) -> RouteDescriptor | None:
+        key = (
+            _normalise_path(path),
+            method.strip().upper(),
+        )
+
+        for route in self.routes:
+            if route.key == key:
+                return route
+
+        return None
+
+    def lookup_by_name(
+        self,
+        name: str,
+    ) -> tuple[RouteDescriptor, ...]:
+        cleaned = name.strip()
+
+        return tuple(
+            route
+            for route in self.routes
+            if route.name == cleaned
+        )
+
+    def lookup_by_operation_id(
+        self,
+        operation_id: str,
+    ) -> tuple[RouteDescriptor, ...]:
+        cleaned = operation_id.strip()
+
+        return tuple(
+            route
+            for route in self.routes
+            if route.operation_id == cleaned
+        )
+
+    def as_list(self) -> list[dict[str, Any]]:
+        return [route.as_dict() for route in self.routes]
+
+    @property
+    def fingerprint(self) -> str:
+        payload = json.dumps(
+            self.as_list(),
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+        ).encode("utf-8")
+
+        return hashlib.sha256(payload).hexdigest()
+
+    def diff(
+        self,
+        previous: RouteCatalogue,
+    ) -> RouteCatalogueDiff:
+        current_by_key = {
+            route.key: route
+            for route in self.routes
+        }
+        previous_by_key = {
+            route.key: route
+            for route in previous.routes
+        }
+
+        added = tuple(
+            current_by_key[key]
+            for key in sorted(
+                current_by_key.keys() - previous_by_key.keys()
+            )
+        )
+        removed = tuple(
+            previous_by_key[key]
+            for key in sorted(
+                previous_by_key.keys() - current_by_key.keys()
+            )
+        )
+
+        changed: list[
+            tuple[RouteDescriptor, RouteDescriptor]
+        ] = []
+
+        for key in sorted(
+            current_by_key.keys() & previous_by_key.keys()
+        ):
+            old = previous_by_key[key]
+            new = current_by_key[key]
+
+            if old != new:
+                changed.append((old, new))
+
+        return RouteCatalogueDiff(
+            added=added,
+            removed=removed,
+            changed=tuple(changed),
+        )

zubbl_fastapi/identity.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from starlette.requests import Request
+
+
+class IdentityResolutionError(ValueError):
+    """Raised when an identity helper is configured incorrectly."""
+
+
+def _resolve_attribute_path(
+    value: Any,
+    attribute_path: str,
+) -> Any:
+    current = value
+
+    for segment in attribute_path.split("."):
+        cleaned = segment.strip()
+
+        if not cleaned:
+            raise IdentityResolutionError(
+                "attribute_path contains an empty segment"
+            )
+
+        if current is None:
+            return None
+
+        if isinstance(current, dict):
+            current = current.get(cleaned)
+        else:
+            current = getattr(current, cleaned, None)
+
+    return current
+
+
+def identify_from_state(
+    attribute_path: str,
+) -> Callable[[Request], Any]:
+    """
+    Build an identity resolver from request.state.
+
+    Examples:
+        identify_from_state("user.id")
+        identify_from_state("external_user_id")
+    """
+    if not isinstance(attribute_path, str) or not attribute_path.strip():
+        raise IdentityResolutionError(
+            "attribute_path must be a non-empty string"
+        )
+
+    cleaned_path = attribute_path.strip()
+
+    def resolver(request: Request) -> Any:
+        return _resolve_attribute_path(
+            request.state,
+            cleaned_path,
+        )
+
+    return resolver

zubbl_fastapi/integration.py

@@ -0,0 +1,368 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+from contextlib import asynccontextmanager
+from collections.abc import Awaitable, Callable, Iterable
+from typing import AsyncIterator, Literal, TypeAlias
+
+from fastapi import FastAPI
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.routing import Match
+from starlette.types import Scope
+
+from zubbl_runtime import RuntimeClient, route_matches
+
+from .endpoints import RouteCatalogue, RouteCatalogueDiff
+
+
+IdentityValue: TypeAlias = str | int | None
+IdentityResult: TypeAlias = IdentityValue | Awaitable[IdentityValue]
+IdentityResolver: TypeAlias = Callable[[Request], IdentityResult]
+BlockResponseResult: TypeAlias = Response | Awaitable[Response]
+BlockResponseHandler: TypeAlias = Callable[
+    [Request, object],
+    BlockResponseResult,
+]
+MissingIdentityMode: TypeAlias = Literal["skip", "block"]
+
+
+DEFAULT_EXCLUDED_PATHS = frozenset(
+    {
+        "/health",
+        "/healthz",
+        "/ready",
+        "/readiness",
+        "/metrics",
+        "/docs",
+        "/redoc",
+        "/openapi.json",
+    }
+)
+
+
+class ZubblFastAPIError(RuntimeError):
+    """Raised when the FastAPI integration is misconfigured."""
+
+
+class Zubbl:
+    """
+    FastAPI integration for Zubbl Runtime Guard.
+
+    The adapter contains framework glue only. Policy retrieval, caching,
+    resilience and enforcement remain inside zubbl-runtime.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        identify: IdentityResolver,
+        base_url: str = "https://api.zubbl.com",
+        timeout_seconds: float = 8.0,
+        excluded_paths: Iterable[str] = DEFAULT_EXCLUDED_PATHS,
+        missing_identity: MissingIdentityMode = "skip",
+        trust_proxy_headers: bool = False,
+        on_block: BlockResponseHandler | None = None,
+        client: RuntimeClient | None = None,
+    ) -> None:
+        if not callable(identify):
+            raise TypeError("identify must be callable")
+
+        if missing_identity not in {"skip", "block"}:
+            raise ValueError(
+                "missing_identity must be 'skip' or 'block'"
+            )
+
+        self._identify = identify
+        self._missing_identity = missing_identity
+        self._trust_proxy_headers = trust_proxy_headers
+        self._on_block = on_block
+
+        self._excluded_paths = frozenset(
+            self._normalise_excluded_path(path)
+            for path in excluded_paths
+        )
+
+        self._client = client or RuntimeClient(
+            api_key,
+            base_url=base_url,
+            timeout_seconds=timeout_seconds,
+        )
+
+        self._initialise_lock = asyncio.Lock()
+        self._attached_app: FastAPI | None = None
+        self._endpoint_catalogue = RouteCatalogue.empty()
+        self._last_endpoint_sync = None
+        self._endpoint_sync_error: str | None = None
+
+    @staticmethod
+    def _normalise_excluded_path(path: str) -> str:
+        if not isinstance(path, str) or not path.strip():
+            raise ValueError(
+                "excluded paths must be non-empty strings"
+            )
+
+        cleaned = path.strip()
+
+        if not cleaned.startswith("/"):
+            cleaned = f"/{cleaned}"
+
+        if len(cleaned) > 1:
+            cleaned = cleaned.rstrip("/")
+
+        return cleaned
+
+    @property
+    def client(self) -> RuntimeClient:
+        return self._client
+
+    @property
+    def endpoint_catalogue(self) -> RouteCatalogue:
+        return self._endpoint_catalogue
+
+    @property
+    def last_endpoint_sync(self):
+        return self._last_endpoint_sync
+
+    @property
+    def endpoint_sync_error(self) -> str | None:
+        return self._endpoint_sync_error
+
+    def refresh_endpoint_catalogue(
+        self,
+    ) -> RouteCatalogueDiff:
+        if self._attached_app is None:
+            raise ZubblFastAPIError(
+                "Zubbl must be attached before discovering endpoints"
+            )
+
+        previous = self._endpoint_catalogue
+        current = RouteCatalogue.from_app(
+            self._attached_app,
+        )
+
+        self._endpoint_catalogue = current
+        return current.diff(previous)
+
+    @property
+    def missing_identity(self) -> MissingIdentityMode:
+        return self._missing_identity
+
+    @property
+    def trust_proxy_headers(self) -> bool:
+        return self._trust_proxy_headers
+
+    async def build_block_response(
+        self,
+        request: Request,
+        result,
+    ) -> Response | None:
+        if self._on_block is None:
+            return None
+
+        response = self._on_block(request, result)
+
+        if inspect.isawaitable(response):
+            response = await response
+
+        if not isinstance(response, Response):
+            raise ZubblFastAPIError(
+                "on_block must return a Starlette Response"
+            )
+
+        return response
+
+    def is_excluded(self, path: str) -> bool:
+        cleaned = path if path == "/" else path.rstrip("/")
+
+        return any(
+            route_matches(pattern, cleaned)
+            for pattern in self._excluded_paths
+        )
+
+    def resolve_route_template(
+        self,
+        scope: Scope,
+    ) -> str:
+        """
+        Resolve the stable FastAPI/Starlette route template for a request.
+
+        Falls back to the concrete request path when no route matches.
+        """
+        concrete_path = str(scope.get("path") or "/")
+
+        if self._attached_app is None:
+            return concrete_path
+
+        for route in self._attached_app.router.routes:
+            match, child_scope = route.matches(scope)
+
+            if match is not Match.FULL:
+                continue
+
+            matched_route = child_scope.get("route", route)
+            template = getattr(matched_route, "path", None)
+
+            if isinstance(template, str) and template.strip():
+                return template
+
+            route_path = getattr(route, "path", None)
+
+            if isinstance(route_path, str) and route_path.strip():
+                return route_path
+
+        return concrete_path
+
+    async def resolve_identity(
+        self,
+        request: Request,
+    ) -> str | None:
+        value = self._identify(request)
+
+        if inspect.isawaitable(value):
+            value = await value
+
+        if value is None:
+            return None
+
+        cleaned = str(value).strip()
+        return cleaned or None
+
+    async def ensure_initialised(self) -> RuntimeClient:
+        if self._client.initialized:
+            return self._client
+
+        if self._client.closed:
+            raise ZubblFastAPIError(
+                "The Zubbl Runtime Client has already been closed"
+            )
+
+        async with self._initialise_lock:
+            if not self._client.initialized:
+                await self._client.init()
+
+        return self._client
+
+    async def startup(self) -> None:
+        if self._attached_app is not None:
+            self.refresh_endpoint_catalogue()
+
+        client = await self.ensure_initialised()
+
+        if (
+            client.config.endpoint_discovery
+            and len(self._endpoint_catalogue) > 0
+        ):
+            try:
+                self._last_endpoint_sync = (
+                    await client.sync_endpoint_catalogue(
+                        fingerprint=(
+                            self._endpoint_catalogue.fingerprint
+                        ),
+                        routes=(
+                            self._endpoint_catalogue.as_list()
+                        ),
+                    )
+                )
+                self._endpoint_sync_error = None
+            except Exception as exc:
+                # Endpoint inventory must never prevent the host application
+                # from starting. Retain the error for diagnostics.
+                self._endpoint_sync_error = (
+                    f"{type(exc).__name__}: {exc}"
+                )
+
+    async def shutdown(self) -> None:
+        await self._client.close()
+
+    @asynccontextmanager
+    async def lifecycle(self) -> AsyncIterator[Zubbl]:
+        """
+        Explicit lifecycle context for applications that already compose
+        multiple lifespan-managed services.
+
+        Example:
+
+            @asynccontextmanager
+            async def lifespan(app):
+                async with zubbl.lifecycle():
+                    yield
+        """
+        await self.startup()
+
+        try:
+            yield self
+        finally:
+            await self.shutdown()
+
+    def lifespan(self):
+        """
+        Return a FastAPI-compatible lifespan callable.
+
+        Example:
+
+            zubbl = Zubbl(...)
+            app = FastAPI(lifespan=zubbl.lifespan())
+        """
+
+        @asynccontextmanager
+        async def zubbl_lifespan(
+            app: FastAPI,
+        ) -> AsyncIterator[None]:
+            async with self.lifecycle():
+                yield
+
+        return zubbl_lifespan
+
+    def attach(
+        self,
+        app: FastAPI,
+        *,
+        manage_lifecycle: bool = True,
+    ) -> Zubbl:
+        if self._attached_app is not None:
+            if self._attached_app is app:
+                return self
+
+            raise ZubblFastAPIError(
+                "This Zubbl instance is already attached to another app"
+            )
+
+        # Imported lazily to avoid an integration/middleware import cycle.
+        from .middleware import ZubblMiddleware
+
+        app.add_middleware(
+            ZubblMiddleware,
+            integration=self,
+        )
+
+        # FastAPI/Starlette inserts newly added middleware at the outermost
+        # position. Runtime Guard identity resolution commonly depends on
+        # authentication middleware having already populated request.state.
+        #
+        # Move Zubbl to the innermost user-middleware position so existing
+        # authentication/session middleware runs first, while Zubbl still
+        # evaluates policy before the route handler executes.
+        zubbl_middleware = app.user_middleware.pop(0)
+        app.user_middleware.append(zubbl_middleware)
+
+        if manage_lifecycle:
+            app.add_event_handler(
+                "startup",
+                self.startup,
+            )
+            app.add_event_handler(
+                "shutdown",
+                self.shutdown,
+            )
+
+        app.state.zubbl = self
+        self._attached_app = app
+
+        # Capture routes already registered before attachment. Startup refresh
+        # captures routes registered afterwards.
+        self.refresh_endpoint_catalogue()
+
+        return self

zubbl_fastapi/middleware.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+import time
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.types import (
+    ASGIApp,
+    Message,
+    Receive,
+    Scope,
+    Send,
+)
+
+from zubbl_runtime import RuntimeRequestContext
+
+from .integration import Zubbl
+from .observation import RuntimeResponseObservation
+
+
+def _truthy_header(value: str | None) -> bool:
+    return str(value or "").strip().lower() in {
+        "1",
+        "true",
+        "yes",
+        "on",
+    }
+
+
+def _trace_id(request: Request) -> str | None:
+    return (
+        request.headers.get("X-Zubbl-Trace-ID")
+        or request.headers.get("X-Trace-ID")
+        or request.headers.get("traceparent")
+    )
+
+
+class ZubblMiddleware:
+    """
+    Pure ASGI middleware for Zubbl Runtime Guard.
+
+    It does not consume the request body and does not use BaseHTTPMiddleware.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        integration: Zubbl,
+    ) -> None:
+        self._app = app
+        self._integration = integration
+
+    async def __call__(
+        self,
+        scope: Scope,
+        receive: Receive,
+        send: Send,
+    ) -> None:
+        if scope["type"] != "http":
+            await self._app(scope, receive, send)
+            return
+
+        path = str(scope.get("path") or "/")
+
+        if self._integration.is_excluded(path):
+            await self._app(scope, receive, send)
+            return
+
+        request = Request(scope, receive=receive)
+        external_user_id = (
+            await self._integration.resolve_identity(request)
+        )
+
+        if external_user_id is None:
+            if self._integration.missing_identity == "block":
+                response = JSONResponse(
+                    status_code=401,
+                    content={
+                        "detail": (
+                            "Zubbl could not resolve an application "
+                            "identity for this request"
+                        ),
+                        "action": "identity_required",
+                    },
+                    headers={
+                        "X-Zubbl-Action": "identity_required",
+                    },
+                )
+                await response(scope, receive, send)
+                return
+
+            scope.setdefault("state", {})
+            scope["state"]["zubbl"] = None
+            scope["state"]["zubbl_skipped_reason"] = (
+                "missing_identity"
+            )
+
+            await self._app(scope, receive, send)
+            return
+
+        client = await self._integration.ensure_initialised()
+        route_template = (
+            self._integration.resolve_route_template(scope)
+        )
+
+        context = self._build_context(
+            request,
+            external_user_id=external_user_id,
+            route_template=route_template,
+        )
+        result = await client.evaluate(context)
+
+        state = scope.setdefault("state", {})
+        state["zubbl"] = result
+        state["zubbl_context"] = context
+
+        if result.should_block:
+            started_at = time.perf_counter()
+
+            response = (
+                await self._integration.build_block_response(
+                    request,
+                    result,
+                )
+            )
+
+            if response is None:
+                response = JSONResponse(
+                    status_code=result.status_code,
+                    content=dict(result.body),
+                    headers=dict(result.headers),
+                )
+
+            await response(scope, receive, send)
+
+            state["zubbl_observation"] = RuntimeResponseObservation(
+                status_code=result.status_code,
+                latency_ms=max(
+                    0.0,
+                    (time.perf_counter() - started_at) * 1000,
+                ),
+                completed=True,
+                route_template=route_template,
+                request_id=context.request_id,
+                trace_id=context.trace_id,
+            )
+            return
+
+        await self._call_and_observe(
+            scope=scope,
+            receive=receive,
+            send=send,
+            context=context,
+            route_template=route_template,
+        )
+
+    async def _call_and_observe(
+        self,
+        *,
+        scope: Scope,
+        receive: Receive,
+        send: Send,
+        context: RuntimeRequestContext,
+        route_template: str,
+    ) -> None:
+        started_at = time.perf_counter()
+        status_code = 500
+        completed = False
+        exception_type: str | None = None
+
+        async def observed_send(message: Message) -> None:
+            nonlocal status_code, completed
+
+            if message["type"] == "http.response.start":
+                status_code = int(message["status"])
+
+            if (
+                message["type"] == "http.response.body"
+                and not message.get("more_body", False)
+            ):
+                completed = True
+
+            await send(message)
+
+        try:
+            await self._app(
+                scope,
+                receive,
+                observed_send,
+            )
+        except Exception as exc:
+            exception_type = type(exc).__name__
+            raise
+        finally:
+            latency_ms = max(
+                0.0,
+                (time.perf_counter() - started_at) * 1000,
+            )
+
+            scope.setdefault("state", {})[
+                "zubbl_observation"
+            ] = RuntimeResponseObservation(
+                status_code=status_code,
+                latency_ms=latency_ms,
+                completed=completed,
+                route_template=route_template,
+                request_id=context.request_id,
+                trace_id=context.trace_id,
+                exception_type=exception_type,
+            )
+
+    def _build_context(
+        self,
+        request: Request,
+        *,
+        external_user_id: str,
+        route_template: str,
+    ) -> RuntimeRequestContext:
+        country = "XX"
+        asn: str | None = None
+        vpn = False
+        hosting = False
+
+        if self._integration.trust_proxy_headers:
+            country = (
+                request.headers.get("X-Zubbl-Geo-Country")
+                or request.headers.get("CF-IPCountry")
+                or "XX"
+            )
+            asn = request.headers.get("X-Zubbl-ASN")
+            vpn = _truthy_header(
+                request.headers.get(
+                    "X-Zubbl-Privacy-VPN"
+                )
+            )
+            hosting = _truthy_header(
+                request.headers.get(
+                    "X-Zubbl-Privacy-Hosting"
+                )
+            )
+
+        return RuntimeRequestContext(
+            external_user_id=external_user_id,
+            method=request.method,
+            path=request.url.path,
+            route_template=route_template,
+            request_id=(
+                request.headers.get("X-Request-ID")
+                or request.headers.get("X-Zubbl-Request-ID")
+            ),
+            trace_id=_trace_id(request),
+            country=country,
+            asn=asn,
+            vpn=vpn,
+            hosting=hosting,
+        )

zubbl_fastapi/observation.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeResponseObservation:
+    """
+    Completed framework response facts.
+
+    This is deliberately observation only. Telemetry transport is introduced
+    later in Sprint 21.8.
+    """
+
+    status_code: int
+    latency_ms: float
+    completed: bool
+
+    route_template: str
+    request_id: str | None = None
+    trace_id: str | None = None
+    exception_type: str | None = None
+
+    def __post_init__(self) -> None:
+        if not 100 <= self.status_code <= 599:
+            raise ValueError(
+                "status_code must be a valid HTTP status"
+            )
+
+        if self.latency_ms < 0:
+            raise ValueError(
+                "latency_ms must not be negative"
+            )
+
+        if (
+            not isinstance(self.route_template, str)
+            or not self.route_template.strip()
+        ):
+            raise ValueError(
+                "route_template must be a non-empty string"
+            )

zubbl_fastapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: zubbl-fastapi
+Version: 0.1.0
+Summary: Official FastAPI integration for the Zubbl Runtime Intelligence Platform
+Author-email: Zubbl <support@zubbl.com>
+License-Expression: MIT
+Project-URL: Homepage, https://zubbl.com
+Project-URL: Documentation, https://zubbl.com
+Keywords: fastapi,security,runtime,application-security,observability,telemetry,behaviour,api-security,zubbl
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: zubbl-runtime>=0.1.0
+Provides-Extra: test
+Requires-Dist: httpx>=0.27.0; extra == "test"
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
+
+# Zubbl FastAPI
+
+The official FastAPI integration for the Zubbl Runtime Intelligence Platform.
+
+Zubbl provides real-time runtime visibility, behavioural security and adaptive protection from inside your application.
+
+## Features
+
+- 5 minute integration
+- Automatic endpoint discovery
+- Runtime request telemetry
+- Behavioural security signals
+- Runtime protection policies
+- Live Runtime Viewer integration
+- Runtime Guard heartbeat
+- Zero application code changes beyond initial setup
+
+## Requirements
+
+- Python 3.10+
+- FastAPI 0.110+
+
+## Installation
+
+```bash
+pip install zubbl-fastapi
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from zubbl_fastapi import Zubbl
+
+app = FastAPI()
+
+zubbl = Zubbl("YOUR_API_KEY")
+
+zubbl.attach(
+    app,
+    identify=lambda request: request.state.user.id
+)
+```
+
+Start your application.
+
+Your application will automatically appear inside the Zubbl Runtime Viewer.
+
+## Documentation
+
+https://zubbl.com
+
+## Runtime Intelligence
+
+Unlike traditional security tooling, Zubbl observes what happens after authentication.
+
+It continuously builds runtime evidence, behavioural intelligence and protection decisions directly from application behaviour.
+
+---
+
+Built by Zubbl.

zubbl_fastapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+zubbl_fastapi/__init__.py,sha256=uVwdZuPC_itJ57BoNL2azLYansgrP2GmDj_0mBlI00U,799
+zubbl_fastapi/endpoints.py,sha256=1kor5u1ttpNxnt2CTAobfE0l5W5sjdbh6ZMuWrZOyNE,7457
+zubbl_fastapi/identity.py,sha256=Y-zwI_fKZbxUEWOjT4La8SNHFl09Ch4vMEQZBg1NN9E,1438
+zubbl_fastapi/integration.py,sha256=nKL9dyMxWQOq6nng47WTyx0rn4l_o4LuQ3EpWDAx8AM,10496
+zubbl_fastapi/middleware.py,sha256=RCPxSAtR3rW1Ram7y12shUJD_5ldKVFSpr6YBTZjMRU,7185
+zubbl_fastapi/observation.py,sha256=TIGckGhMi0nR9SBXf-yboumjobJ07ZNgYSldmhwif5Y,1038
+zubbl_fastapi-0.1.0.dist-info/METADATA,sha256=K_2gEAIn6L-Isee-cwSIS-E33KjNv8CpGv-qio-8f2A,2380
+zubbl_fastapi-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+zubbl_fastapi-0.1.0.dist-info/top_level.txt,sha256=QX_nDBBOpnHp__qunQYruBnNCvVwvlBHECuyb6XIs-s,14
+zubbl_fastapi-0.1.0.dist-info/RECORD,,

zubbl_fastapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zubbl_fastapi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zubbl_fastapi