hub02-sdk 0.1.0__tar.gz

hub02_sdk-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Node
+node_modules/
+dist/
+*.tsbuildinfo
+npm-debug.log*
+.eslintcache
+
+# Python
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+*.whl
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Env / secrets
+.env
+.env.*

hub02_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: hub02-sdk
+Version: 0.1.0
+Summary: Hub02 tool-identity SDK — verify Hub02 identity tokens (Ed25519) on your Python backend.
+Project-URL: Homepage, https://github.com/Irshai02/hub02-sdk
+Project-URL: Repository, https://github.com/Irshai02/hub02-sdk
+Author: Hub02
+License: MIT
+Keywords: auth,ed25519,hub02,identity,jwt,sso
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Security
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: pyjwt[crypto]>=2.8.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: flask>=2.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: starlette>=0.37; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# `hub02-sdk` (Python)
+
+Verify Hub02 tool-identity tokens (Ed25519) on your Python backend, and read
+the signed-in user — no second login.
+
+> Token algorithm is **EdDSA / Ed25519**, `iss="hub02"`, `aud="tool-identity"`.
+> JWKS: `https://ddeubhasvmeqwtzgkunt.supabase.co/functions/v1/jwks`.
+
+## Install
+
+```bash
+pip install hub02-sdk            # not yet published — install from the repo for now
+# pip install "git+https://github.com/Irshai02/hub02-sdk.git#subdirectory=python"
+```
+
+## Server — verify on your backend
+
+The Hub02 proxy injects the identity JWT as the `X-Hub02-Auth` header (also
+accepts `Authorization: Bearer <jwt>`). Always trust `user.id` from the
+verified token, never a client-supplied field.
+
+### Framework-agnostic
+
+```python
+from hub02_sdk.server import authenticate_hub02, Hub02AuthError
+
+try:
+    user = authenticate_hub02(request)   # request: FastAPI/Starlette, Flask, Django, or header dict
+    plan = get_plan(user.id)             # key your data on user.id (durable UUID)
+except Hub02AuthError:
+    ...                                   # 401
+```
+
+### FastAPI
+
+```python
+from fastapi import FastAPI, Depends
+from hub02_sdk.server import fastapi_dependency, Hub02User
+
+require_user = fastapi_dependency()       # optionally fastapi_dependency(tool_id="my-tool")
+app = FastAPI()
+
+@app.get("/my-plan")
+def my_plan(user: Hub02User = Depends(require_user)):
+    return get_plan(user.id)
+```
+
+### Flask
+
+```python
+from flask import Flask, jsonify
+from hub02_sdk.server import flask_authenticate_hub02, Hub02AuthError
+
+app = Flask(__name__)
+
+@app.get("/my-plan")
+def my_plan():
+    try:
+        user = flask_authenticate_hub02()
+    except Hub02AuthError as e:
+        return jsonify(authenticated=False, error=str(e)), 401
+    return jsonify(get_plan(user.id))
+```
+
+## Public API
+
+| Name | Signature | Purpose |
+|---|---|---|
+| `verify_hub02_token` | `(token, *, tool_id=None, jwks_url=…, leeway=5) -> Hub02Claims` | Verify Ed25519 token vs JWKS; checks `iss`/`aud`/`exp`/optional `tool_id`. Raises `Hub02AuthError`. |
+| `authenticate_hub02` | `(request, *, tool_id=None, …) -> Hub02User` | Extract + verify token from a request; raises `Hub02AuthError` (status 401). |
+| `extract_token` | `(request) -> str | None` | Pull token from `X-Hub02-Auth` / `Authorization: Bearer`. |
+| `fastapi_dependency` | `(*, tool_id=None, …) -> Depends-able` | FastAPI dependency returning `Hub02User`; raises `HTTPException(401)`. |
+| `flask_authenticate_hub02` | `(*, tool_id=None, …) -> Hub02User` | Flask helper using `flask.request`. |
+| `Hub02User` | dataclass `{ id, hub_id, tool_id, email, name }` | Trusted identity. Key data on `id`. |
+| `Hub02Claims` | dict subclass | Raw verified claims. |
+| `Hub02AuthError` | exception (`status = 401`) | Raised on any verification failure. |
+
+Client helpers (SSR / forwarded identity, in `hub02_sdk`):
+`user_from_window_identity(data)`, `user_from_me_response(data)`.
+
+## Develop / test (offline, no secrets)
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Tests generate a local Ed25519 keypair and a mock JWKS — no network, no Hub02
+secrets.
+
+## License
+
+MIT.

hub02_sdk-0.1.0/README.md

@@ -0,0 +1,94 @@
+# `hub02-sdk` (Python)
+
+Verify Hub02 tool-identity tokens (Ed25519) on your Python backend, and read
+the signed-in user — no second login.
+
+> Token algorithm is **EdDSA / Ed25519**, `iss="hub02"`, `aud="tool-identity"`.
+> JWKS: `https://ddeubhasvmeqwtzgkunt.supabase.co/functions/v1/jwks`.
+
+## Install
+
+```bash
+pip install hub02-sdk            # not yet published — install from the repo for now
+# pip install "git+https://github.com/Irshai02/hub02-sdk.git#subdirectory=python"
+```
+
+## Server — verify on your backend
+
+The Hub02 proxy injects the identity JWT as the `X-Hub02-Auth` header (also
+accepts `Authorization: Bearer <jwt>`). Always trust `user.id` from the
+verified token, never a client-supplied field.
+
+### Framework-agnostic
+
+```python
+from hub02_sdk.server import authenticate_hub02, Hub02AuthError
+
+try:
+    user = authenticate_hub02(request)   # request: FastAPI/Starlette, Flask, Django, or header dict
+    plan = get_plan(user.id)             # key your data on user.id (durable UUID)
+except Hub02AuthError:
+    ...                                   # 401
+```
+
+### FastAPI
+
+```python
+from fastapi import FastAPI, Depends
+from hub02_sdk.server import fastapi_dependency, Hub02User
+
+require_user = fastapi_dependency()       # optionally fastapi_dependency(tool_id="my-tool")
+app = FastAPI()
+
+@app.get("/my-plan")
+def my_plan(user: Hub02User = Depends(require_user)):
+    return get_plan(user.id)
+```
+
+### Flask
+
+```python
+from flask import Flask, jsonify
+from hub02_sdk.server import flask_authenticate_hub02, Hub02AuthError
+
+app = Flask(__name__)
+
+@app.get("/my-plan")
+def my_plan():
+    try:
+        user = flask_authenticate_hub02()
+    except Hub02AuthError as e:
+        return jsonify(authenticated=False, error=str(e)), 401
+    return jsonify(get_plan(user.id))
+```
+
+## Public API
+
+| Name | Signature | Purpose |
+|---|---|---|
+| `verify_hub02_token` | `(token, *, tool_id=None, jwks_url=…, leeway=5) -> Hub02Claims` | Verify Ed25519 token vs JWKS; checks `iss`/`aud`/`exp`/optional `tool_id`. Raises `Hub02AuthError`. |
+| `authenticate_hub02` | `(request, *, tool_id=None, …) -> Hub02User` | Extract + verify token from a request; raises `Hub02AuthError` (status 401). |
+| `extract_token` | `(request) -> str | None` | Pull token from `X-Hub02-Auth` / `Authorization: Bearer`. |
+| `fastapi_dependency` | `(*, tool_id=None, …) -> Depends-able` | FastAPI dependency returning `Hub02User`; raises `HTTPException(401)`. |
+| `flask_authenticate_hub02` | `(*, tool_id=None, …) -> Hub02User` | Flask helper using `flask.request`. |
+| `Hub02User` | dataclass `{ id, hub_id, tool_id, email, name }` | Trusted identity. Key data on `id`. |
+| `Hub02Claims` | dict subclass | Raw verified claims. |
+| `Hub02AuthError` | exception (`status = 401`) | Raised on any verification failure. |
+
+Client helpers (SSR / forwarded identity, in `hub02_sdk`):
+`user_from_window_identity(data)`, `user_from_me_response(data)`.
+
+## Develop / test (offline, no secrets)
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Tests generate a local Ed25519 keypair and a mock JWKS — no network, no Hub02
+secrets.
+
+## License
+
+MIT.

hub02_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hub02-sdk"
+version = "0.1.0"
+description = "Hub02 tool-identity SDK — verify Hub02 identity tokens (Ed25519) on your Python backend."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Hub02" }]
+keywords = ["hub02", "sso", "identity", "jwt", "ed25519", "auth"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Intended Audience :: Developers",
+  "Topic :: Security",
+]
+dependencies = [
+  "PyJWT[crypto]>=2.8.0",
+  "cryptography>=42.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Irshai02/hub02-sdk"
+Repository = "https://github.com/Irshai02/hub02-sdk"
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100"]
+flask = ["flask>=2.0"]
+dev = [
+  "pytest>=8.0",
+  "ruff>=0.6",
+  "build>=1.2",
+  "fastapi>=0.100",
+  "flask>=2.0",
+  "starlette>=0.37",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hub02_sdk"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/hub02_sdk", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "."]
+addopts = "--import-mode=importlib"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+ignore = ["E501"]

hub02_sdk-0.1.0/src/hub02_sdk/__init__.py

@@ -0,0 +1,36 @@
+"""Hub02 SDK — read the signed-in Hub02 user and verify identity tokens.
+
+Public surface::
+
+    from hub02_sdk import Hub02User
+    from hub02_sdk.server import verify_hub02_token, authenticate_hub02
+
+Token algorithm is EdDSA / Ed25519, ``iss="hub02"``, ``aud="tool-identity"``.
+"""
+
+from ._shared import (
+    HUB02_ALG,
+    HUB02_AUD,
+    HUB02_ISS,
+    HUB02_JWKS_URL,
+    HUB02_ME_PATH,
+    Hub02AuthError,
+    Hub02Claims,
+    Hub02User,
+)
+from .client import user_from_me_response, user_from_window_identity
+
+__all__ = [
+    "Hub02User",
+    "Hub02Claims",
+    "Hub02AuthError",
+    "HUB02_JWKS_URL",
+    "HUB02_ISS",
+    "HUB02_AUD",
+    "HUB02_ALG",
+    "HUB02_ME_PATH",
+    "user_from_window_identity",
+    "user_from_me_response",
+]
+
+__version__ = "0.1.0"

hub02_sdk-0.1.0/src/hub02_sdk/_shared.py

@@ -0,0 +1,77 @@
+"""Shared constants and types for the Hub02 SDK.
+
+These pin the contract so client and server halves cannot drift:
+  - JWKS endpoint (public Ed25519 keys)
+  - token issuer (``iss``)
+  - token audience (``aud``)
+
+Token algorithm is EdDSA / Ed25519 (NOT ES256).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+#: Public JWKS endpoint exposing Hub02's Ed25519 verification keys.
+HUB02_JWKS_URL = "https://ddeubhasvmeqwtzgkunt.supabase.co/functions/v1/jwks"
+
+#: Expected ``iss`` claim on a Hub02 identity token.
+HUB02_ISS = "hub02"
+
+#: Expected ``aud`` claim on a Hub02 identity token.
+HUB02_AUD = "tool-identity"
+
+#: Signing / verification algorithm. EdDSA over the Ed25519 curve.
+HUB02_ALG = "EdDSA"
+
+#: Same-origin pull endpoint the proxy exposes for client identity.
+HUB02_ME_PATH = "/__hub02/me"
+
+
+@dataclass
+class Hub02User:
+    """Identity returned to application code.
+
+    ``id`` is the durable Hub02 user UUID (the ``sub`` claim) — builders MUST
+    key their data on this. ``email`` / ``name`` are display-only and may
+    change.
+    """
+
+    id: str
+    hub_id: Optional[str] = None
+    tool_id: Optional[str] = None
+    email: Optional[str] = None
+    name: Optional[str] = None
+
+
+class Hub02Claims(dict):
+    """Raw verified claims from a Hub02 identity JWT (a plain dict).
+
+    Common keys: ``sub``, ``iss``, ``aud``, ``hub_id``, ``tool_id``,
+    ``email``, ``name``, ``iat``, ``exp``.
+    """
+
+    @property
+    def sub(self) -> str:
+        return self["sub"]
+
+
+class Hub02AuthError(Exception):
+    """Raised when token verification or authorization fails.
+
+    Carries ``status = 401`` so framework handlers can map it directly.
+    """
+
+    status = 401
+
+
+def claims_to_user(claims: dict[str, Any]) -> Hub02User:
+    """Map verified claims to the public :class:`Hub02User`."""
+    return Hub02User(
+        id=claims["sub"],
+        hub_id=claims.get("hub_id"),
+        tool_id=claims.get("tool_id"),
+        email=claims.get("email"),
+        name=claims.get("name"),
+    )

hub02_sdk-0.1.0/src/hub02_sdk/client.py

@@ -0,0 +1,69 @@
+"""Hub02 SDK — client-side helpers (Python).
+
+Client-side Python is minimal — most Python use is server-side. This module
+provides a helper to read an already-established Hub02 identity from a
+forwarded header (e.g. SSR frameworks where the proxy injected
+``X-Hub02-*`` / ``window.__HUB02__`` upstream), plus the ``Hub02User`` type.
+
+For real authorization, verify the token on the server with
+:func:`hub02_sdk.server.authenticate_hub02` — never trust a forwarded
+identity field without verifying the signed token.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from ._shared import Hub02User
+
+__all__ = ["Hub02User", "user_from_window_identity", "user_from_me_response"]
+
+
+def user_from_window_identity(data: Any) -> Optional[Hub02User]:
+    """Build a :class:`Hub02User` from a ``window.__HUB02__`` JSON blob.
+
+    Accepts a dict or a JSON string. Returns ``None`` if no ``user_id``.
+    Display-only: do not use as an authorization decision on its own.
+    """
+    if isinstance(data, str):
+        try:
+            data = json.loads(data)
+        except (ValueError, TypeError):
+            return None
+    if not isinstance(data, dict):
+        return None
+    user_id = data.get("user_id") or data.get("id")
+    if not user_id:
+        return None
+    return Hub02User(
+        id=user_id,
+        hub_id=data.get("hub_id"),
+        tool_id=data.get("tool_id"),
+        email=data.get("email"),
+        name=data.get("name"),
+    )
+
+
+def user_from_me_response(data: Any) -> Optional[Hub02User]:
+    """Build a :class:`Hub02User` from a ``GET /__hub02/me`` JSON body.
+
+    Returns ``None`` when ``authenticated`` is false or no ``user_id``.
+    """
+    if isinstance(data, str):
+        try:
+            data = json.loads(data)
+        except (ValueError, TypeError):
+            return None
+    if not isinstance(data, dict) or not data.get("authenticated"):
+        return None
+    user_id = data.get("user_id")
+    if not user_id:
+        return None
+    return Hub02User(
+        id=user_id,
+        hub_id=data.get("hub_id"),
+        tool_id=data.get("tool_id"),
+        email=data.get("email"),
+        name=data.get("name"),
+    )

hub02_sdk-0.1.0/src/hub02_sdk/server.py

@@ -0,0 +1,275 @@
+"""Hub02 SDK — server (framework-agnostic + FastAPI + Flask helpers).
+
+Verifies Hub02 identity JWTs against the public JWKS using Ed25519, and turns
+a request into a trusted :class:`Hub02User`.
+
+SECURITY: always read ``user.id`` from the verified token — never from a
+client-supplied field.
+
+Usage::
+
+    from hub02_sdk.server import authenticate_hub02
+    user = authenticate_hub02(request)   # raises Hub02AuthError on invalid
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Optional
+
+import jwt
+from jwt import PyJWK, PyJWKClient
+
+from ._shared import (
+    HUB02_ALG,
+    HUB02_AUD,
+    HUB02_ISS,
+    HUB02_JWKS_URL,
+    Hub02AuthError,
+    Hub02Claims,
+    Hub02User,
+    claims_to_user,
+)
+
+__all__ = [
+    "verify_hub02_token",
+    "authenticate_hub02",
+    "extract_token",
+    "fastapi_dependency",
+    "flask_authenticate_hub02",
+    "Hub02User",
+    "Hub02Claims",
+    "Hub02AuthError",
+]
+
+
+# --------------------------------------------------------------------------
+# JWKS cache (by kid, TTL ~10m, refetch on unknown kid).
+# --------------------------------------------------------------------------
+
+_JWKS_TTL_SEC = 10 * 60
+
+
+class _JwksCache:
+    """Thread-safe JWKS resolver with a TTL and unknown-kid refetch."""
+
+    def __init__(self, url: str) -> None:
+        self._url = url
+        self._client: Optional[PyJWKClient] = None
+        self._fetched_at = 0.0
+        self._lock = threading.Lock()
+
+    def _client_fresh(self) -> PyJWKClient:
+        now = time.time()
+        with self._lock:
+            if self._client is None or (now - self._fetched_at) > _JWKS_TTL_SEC:
+                self._client = PyJWKClient(self._url, lifespan=_JWKS_TTL_SEC)
+                self._fetched_at = now
+            return self._client
+
+    def get_key(self, token: str) -> PyJWK:
+        client = self._client_fresh()
+        try:
+            return client.get_signing_key_from_jwt(token)
+        except Exception:
+            # Unknown kid → force a refetch once.
+            with self._lock:
+                self._client = PyJWKClient(self._url, lifespan=_JWKS_TTL_SEC)
+                self._fetched_at = time.time()
+                client = self._client
+            return client.get_signing_key_from_jwt(token)
+
+
+_caches: dict[str, _JwksCache] = {}
+_caches_lock = threading.Lock()
+
+
+def _resolve_key(token: str, jwks_url: str, jwks_client: Any) -> Any:
+    if jwks_client is not None:
+        # Caller-provided resolver (tests). Either a PyJWKClient-like with
+        # get_signing_key_from_jwt, or a mapping kid->key.
+        if hasattr(jwks_client, "get_signing_key_from_jwt"):
+            return jwks_client.get_signing_key_from_jwt(token).key
+        # mapping by kid
+        header = jwt.get_unverified_header(token)
+        kid = header.get("kid")
+        key = jwks_client.get(kid) if hasattr(jwks_client, "get") else None
+        if key is None:
+            raise Hub02AuthError(f"No key for kid {kid}")
+        return key
+    with _caches_lock:
+        cache = _caches.get(jwks_url)
+        if cache is None:
+            cache = _JwksCache(jwks_url)
+            _caches[jwks_url] = cache
+    return cache.get_key(token).key
+
+
+def verify_hub02_token(
+    token: str,
+    *,
+    tool_id: Optional[str] = None,
+    jwks_url: str = HUB02_JWKS_URL,
+    jwks_client: Any = None,
+    leeway: int = 5,
+) -> Hub02Claims:
+    """Verify a Hub02 identity JWT.
+
+    Checks: Ed25519 signature vs JWKS, ``iss == "hub02"``,
+    ``aud == "tool-identity"``, ``exp`` not passed (small leeway), and — if
+    ``tool_id`` is supplied — that the ``tool_id`` claim matches.
+
+    Raises :class:`Hub02AuthError` on any failure.
+    """
+    if not token or not isinstance(token, str):
+        raise Hub02AuthError("Missing token")
+
+    try:
+        signing_key = _resolve_key(token, jwks_url, jwks_client)
+    except Hub02AuthError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise Hub02AuthError(f"Could not resolve signing key: {exc}") from exc
+
+    try:
+        payload = jwt.decode(
+            token,
+            signing_key,
+            algorithms=[HUB02_ALG],
+            issuer=HUB02_ISS,
+            audience=HUB02_AUD,
+            leeway=leeway,
+            options={"require": ["exp", "sub"]},
+        )
+    except Exception as exc:  # noqa: BLE001  (PyJWT raises many subclasses)
+        raise Hub02AuthError(f"Token verification failed: {exc}") from exc
+
+    if not payload.get("sub"):
+        raise Hub02AuthError("Token missing sub claim")
+
+    if tool_id is not None and payload.get("tool_id") != tool_id:
+        raise Hub02AuthError(f"Token tool_id mismatch (expected {tool_id})")
+
+    return Hub02Claims(payload)
+
+
+# --------------------------------------------------------------------------
+# Request helpers
+# --------------------------------------------------------------------------
+
+
+def _get_header(request: Any, name: str) -> Optional[str]:
+    """Read a header from common request objects (Starlette/FastAPI, Flask,
+    Django, or a plain dict)."""
+    lname = name.lower()
+    headers = getattr(request, "headers", None)
+    if headers is not None:
+        # Starlette/Werkzeug headers are case-insensitive mappings.
+        try:
+            val = headers.get(name) or headers.get(lname)
+            if val:
+                return val
+        except Exception:  # noqa: BLE001
+            pass
+    # Django style: request.META["HTTP_X_HUB02_AUTH"]
+    meta = getattr(request, "META", None)
+    if isinstance(meta, dict):
+        key = "HTTP_" + name.upper().replace("-", "_")
+        if meta.get(key):
+            return meta[key]
+    # Plain dict of headers.
+    if isinstance(request, dict):
+        return request.get(name) or request.get(lname)
+    return None
+
+
+def extract_token(request: Any) -> Optional[str]:
+    """Extract the identity token: ``X-Hub02-Auth`` then ``Authorization:
+    Bearer``."""
+    direct = _get_header(request, "X-Hub02-Auth")
+    if direct:
+        return direct[7:].strip() if direct.lower().startswith("bearer ") else direct.strip()
+    auth = _get_header(request, "Authorization")
+    if auth and auth.lower().startswith("bearer "):
+        return auth[7:].strip()
+    return None
+
+
+def authenticate_hub02(
+    request: Any,
+    *,
+    tool_id: Optional[str] = None,
+    jwks_url: str = HUB02_JWKS_URL,
+    jwks_client: Any = None,
+    leeway: int = 5,
+) -> Hub02User:
+    """Verify the request's identity token and return the trusted user.
+
+    Framework-agnostic: accepts Starlette/FastAPI, Flask, Django, or a plain
+    header dict. Raises :class:`Hub02AuthError` (status 401) when no valid
+    token is present.
+    """
+    token = extract_token(request)
+    if not token:
+        raise Hub02AuthError("No Hub02 identity token on request")
+    claims = verify_hub02_token(
+        token,
+        tool_id=tool_id,
+        jwks_url=jwks_url,
+        jwks_client=jwks_client,
+        leeway=leeway,
+    )
+    return claims_to_user(claims)
+
+
+# --------------------------------------------------------------------------
+# FastAPI dependency
+# --------------------------------------------------------------------------
+
+
+def fastapi_dependency(*, tool_id: Optional[str] = None, **kwargs: Any):
+    """Build a FastAPI dependency that returns a :class:`Hub02User`.
+
+    Usage::
+
+        from fastapi import Depends
+        from hub02_sdk.server import fastapi_dependency
+        require_user = fastapi_dependency()
+
+        @app.get("/my-plan")
+        def my_plan(user = Depends(require_user)):
+            return get_plan(user.id)
+    """
+
+    def _dep(request: Any) -> Hub02User:
+        try:
+            return authenticate_hub02(request, tool_id=tool_id, **kwargs)
+        except Hub02AuthError as exc:
+            try:
+                from fastapi import HTTPException
+            except ImportError as ie:  # pragma: no cover
+                raise exc from ie
+            raise HTTPException(
+                status_code=401,
+                detail={"authenticated": False, "error": str(exc)},
+            ) from exc
+
+    return _dep
+
+
+# --------------------------------------------------------------------------
+# Flask helper
+# --------------------------------------------------------------------------
+
+
+def flask_authenticate_hub02(*, tool_id: Optional[str] = None, **kwargs: Any) -> Hub02User:
+    """Flask helper: read the current request and return a trusted user.
+
+    Call inside a view (uses ``flask.request``). Raises
+    :class:`Hub02AuthError` (status 401) on failure — register an error
+    handler, or wrap in try/except and return a 401 JSON body.
+    """
+    from flask import request as flask_request
+
+    return authenticate_hub02(flask_request, tool_id=tool_id, **kwargs)