csrd-auth 0.1.0__py3-none-any.whl

csrd/auth/__init__.py

@@ -0,0 +1,58 @@
+"""Pluggable authentication for FastAPI applications.
+
+The auth system is built around two pluggable protocols:
+
+1. :class:`Authenticator` — how to validate a token and produce claims.
+2. :class:`KeyProvider` — how to resolve the cryptographic key(s) used
+   for JWT verification.
+"""
+
+from ._authenticators import (
+    CallbackAuthenticator,
+    ChainedAuthenticator,
+    JWTAuthenticator,
+    RemoteAuthenticator,
+    StaticAuthenticator,
+    _default_claims_mapper,
+)
+from ._factory import (
+    create_bearer_dependency,
+    create_jwt_bearer,
+)
+from ._key_providers import (
+    CallbackKeyProvider,
+    EnvKeyProvider,
+    JWKSKeyProvider,
+    MultiKeyProvider,
+    StaticKeyProvider,
+    _coerce_key_provider,
+)
+from ._protocols import (
+    AuthCallback,
+    Authenticator,
+    KeyCallback,
+    KeyProvider,
+    KeySource,
+)
+
+__all__ = (
+    "AuthCallback",
+    "Authenticator",
+    "CallbackAuthenticator",
+    "CallbackKeyProvider",
+    "ChainedAuthenticator",
+    "EnvKeyProvider",
+    "JWKSKeyProvider",
+    "JWTAuthenticator",
+    "KeyCallback",
+    "KeyProvider",
+    "KeySource",
+    "MultiKeyProvider",
+    "RemoteAuthenticator",
+    "StaticAuthenticator",
+    "StaticKeyProvider",
+    "_coerce_key_provider",
+    "_default_claims_mapper",
+    "create_bearer_dependency",
+    "create_jwt_bearer",
+)

csrd/auth/_authenticators.py

@@ -0,0 +1,220 @@
+# ruff: noqa: B904
+"""Built-in authenticator implementations."""
+
+import inspect
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+import jwt as pyjwt
+from fastapi import HTTPException, Request
+from starlette.status import HTTP_401_UNAUTHORIZED
+
+from csrd.models.claims import UserClaims
+
+from ._key_providers import _coerce_key_provider
+from ._protocols import AuthCallback, Authenticator, KeySource
+
+logger = logging.getLogger(__name__)
+
+
+def _default_claims_mapper(payload: dict[str, Any]) -> UserClaims:
+    sub = payload.get("sub", "")
+    user_name = (
+        payload.get("user_name") or payload.get("preferred_username") or payload.get("email") or ""
+    )
+
+    authorities = payload.get("authorities") or payload.get("roles") or []
+    if isinstance(authorities, str):
+        authorities = authorities.split()
+
+    return UserClaims(
+        sub=sub,
+        user_name=user_name,
+        authorities=list(authorities),
+    )
+
+
+@dataclass
+class JWTAuthenticator:
+    """Decode and verify a JWT token locally using PyJWT."""
+
+    key: KeySource | None = None
+    algorithms: list[str] = field(default_factory=lambda: ["HS256"])
+    audience: str | None = None
+    issuer: str | None = None
+    options: dict[str, Any] = field(default_factory=dict)
+    claims_mapper: Callable[[dict[str, Any]], UserClaims] | None = None
+
+    def __post_init__(self) -> None:
+        self._key_provider = _coerce_key_provider(self.key)
+
+    async def __call__(self, request: Request, token: str) -> UserClaims:
+        mapper = self.claims_mapper or _default_claims_mapper
+
+        try:
+            unverified_headers = pyjwt.get_unverified_header(token)
+        except pyjwt.DecodeError:
+            raise HTTPException(status_code=HTTP_401_UNAUTHORIZED, detail="Malformed token")
+
+        resolved = self._key_provider(unverified_headers, request.app)
+        if inspect.isawaitable(resolved):
+            resolved = await resolved
+
+        decode_kwargs: dict[str, Any] = {
+            "algorithms": self.algorithms,
+            "options": dict(self.options),
+        }
+        if self.audience is not None:
+            decode_kwargs["audience"] = self.audience
+        if self.issuer is not None:
+            decode_kwargs["issuer"] = self.issuer
+
+        try:
+            payload = pyjwt.decode(token, resolved, **decode_kwargs)
+        except pyjwt.ExpiredSignatureError:
+            raise HTTPException(
+                status_code=HTTP_401_UNAUTHORIZED,
+                detail="Token has expired",
+            )
+        except pyjwt.InvalidTokenError as exc:
+            logger.debug("JWT validation failed: %s", exc)
+            raise HTTPException(
+                status_code=HTTP_401_UNAUTHORIZED,
+                detail="Invalid token",
+            )
+
+        return mapper(payload)
+
+
+@dataclass
+class StaticAuthenticator:
+    """Accept a fixed token value and return preconfigured claims."""
+
+    token: str
+    claims: UserClaims = field(default_factory=lambda: UserClaims(sub="static"))
+
+    async def __call__(self, request: Request, token: str) -> UserClaims:
+        import hmac
+
+        if not hmac.compare_digest(token, self.token):
+            raise HTTPException(
+                status_code=HTTP_401_UNAUTHORIZED,
+                detail="Invalid token",
+            )
+        return self.claims
+
+
+@dataclass
+class RemoteAuthenticator:
+    """Validate the token by calling an upstream HTTP endpoint."""
+
+    url: str
+    method: str = "GET"
+    token_header: str = "Authorization"
+    token_prefix: str = "Bearer "
+    claims_mapper: Callable[[dict[str, Any]], UserClaims] | None = None
+    httpx_client_kwargs: dict[str, Any] = field(default_factory=dict)
+    client: Any = None
+
+    async def __call__(self, request: Request, token: str) -> UserClaims:
+        import httpx
+
+        mapper = self.claims_mapper or _default_claims_mapper
+        headers = {self.token_header: f"{self.token_prefix}{token}"}
+
+        async def _do_request(c: httpx.AsyncClient) -> httpx.Response:
+            try:
+                return await c.request(self.method, self.url, headers=headers)
+            except httpx.HTTPError as exc:
+                logger.warning("Remote auth request failed: %s", exc)
+                raise HTTPException(
+                    status_code=HTTP_401_UNAUTHORIZED,
+                    detail="Authentication service unavailable",
+                )
+
+        if self.client is not None:
+            resp = await _do_request(self.client)
+        else:
+            client_kwargs = {"timeout": 10.0, **self.httpx_client_kwargs}
+            async with httpx.AsyncClient(**client_kwargs) as client:
+                resp = await _do_request(client)
+
+        if resp.status_code >= 400:
+            logger.debug(
+                "Remote auth rejected token: status=%d body=%s",
+                resp.status_code,
+                resp.text[:200],
+            )
+            raise HTTPException(
+                status_code=HTTP_401_UNAUTHORIZED,
+                detail="Token rejected by authentication service",
+            )
+
+        try:
+            payload = resp.json()
+        except Exception:
+            raise HTTPException(
+                status_code=HTTP_401_UNAUTHORIZED,
+                detail="Invalid response from authentication service",
+            )
+
+        if isinstance(payload, dict) and payload.get("active") is False:
+            raise HTTPException(
+                status_code=HTTP_401_UNAUTHORIZED,
+                detail="Token is not active",
+            )
+
+        return mapper(payload)
+
+
+@dataclass
+class CallbackAuthenticator:
+    """Delegate authentication to an arbitrary user-provided function."""
+
+    callback: AuthCallback
+
+    async def __call__(self, request: Request, token: str) -> UserClaims:
+        try:
+            result = self.callback(request, token)
+            if inspect.isawaitable(result):
+                result = await result
+        except HTTPException:
+            raise
+        except Exception as exc:
+            logger.debug("Callback authenticator failed: %s", exc)
+            raise HTTPException(
+                status_code=HTTP_401_UNAUTHORIZED,
+                detail="Authentication failed",
+            ) from exc
+
+        if not isinstance(result, UserClaims):
+            raise TypeError(
+                f"Authenticator callback must return UserClaims, got {type(result).__name__}"
+            )
+        return result
+
+
+@dataclass
+class ChainedAuthenticator:
+    """Try multiple authenticators in order; first success wins."""
+
+    authenticators: list[Authenticator | Any] = field(default_factory=list)
+
+    async def __call__(self, request: Request, token: str) -> UserClaims:
+        last_exc: HTTPException | None = None
+        for auth in self.authenticators:
+            try:
+                result = auth(request, token)
+                if inspect.isawaitable(result):
+                    result = await result
+                return result
+            except HTTPException as exc:
+                last_exc = exc
+                continue
+
+        raise last_exc or HTTPException(
+            status_code=HTTP_401_UNAUTHORIZED,
+            detail="All authenticators failed",
+        )

csrd/auth/_factory.py

@@ -0,0 +1,93 @@
+"""Dependency factory functions for FastAPI auth integration."""
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import Request
+
+from csrd.context.platform import user_info_context
+from csrd.models.claims import UserClaims
+
+from ._authenticators import (
+    CallbackAuthenticator,
+    ChainedAuthenticator,
+    JWTAuthenticator,
+    RemoteAuthenticator,
+    StaticAuthenticator,
+)
+from ._protocols import AuthCallback, Authenticator, KeySource
+
+
+def create_bearer_dependency(
+    authenticator: Authenticator | AuthCallback,
+    *,
+    token_finder: Callable[[], str] | None = None,
+) -> Callable:
+    """Build a FastAPI dependency from any :class:`Authenticator`.
+
+    Parameters
+    ----------
+    authenticator:
+        The authenticator instance or callback to use.
+    token_finder:
+        Zero-arg callable that extracts the bearer token from the
+        current request context. When *None*, the token must be
+        provided by a framework-level mechanism (e.g. the versioning
+        dispatch middleware populates the contextvar automatically).
+    """
+    if not isinstance(
+        authenticator,
+        (
+            JWTAuthenticator,
+            StaticAuthenticator,
+            RemoteAuthenticator,
+            CallbackAuthenticator,
+            ChainedAuthenticator,
+        ),
+    ) and callable(authenticator):
+        authenticator = CallbackAuthenticator(authenticator)
+
+    async def _bearer_dependency(request: Request) -> UserClaims:
+        if token_finder is None:
+            raise RuntimeError(
+                "No token_finder configured. Either pass token_finder= to "
+                "create_bearer_dependency(), or use csrd.versioning which "
+                "provides this automatically."
+            )
+        token = token_finder()
+
+        result = authenticator(request, token)
+        if inspect.isawaitable(result):
+            claims = await result
+        else:
+            claims = result
+
+        user_info_context.set(claims)
+        return claims
+
+    return _bearer_dependency
+
+
+def create_jwt_bearer(
+    *,
+    key: KeySource | None = None,
+    algorithms: list[str] | None = None,
+    audience: str | None = None,
+    issuer: str | None = None,
+    options: dict[str, Any] | None = None,
+    claims_mapper: Callable[[dict[str, Any]], UserClaims] | None = None,
+    token_finder: Callable[[], str] | None = None,
+) -> Callable:
+    """Convenience shortcut: build a JWT bearer dependency."""
+    return create_bearer_dependency(
+        JWTAuthenticator(
+            key=key,
+            algorithms=algorithms or ["HS256"],
+            audience=audience,
+            issuer=issuer,
+            options=options or {},
+            claims_mapper=claims_mapper,
+        ),
+        token_finder=token_finder,
+    )

csrd/auth/_key_providers.py

@@ -0,0 +1,219 @@
+# ruff: noqa: B904
+"""Built-in key provider implementations."""
+
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from fastapi import HTTPException
+from pydantic import SecretStr
+from starlette.status import HTTP_401_UNAUTHORIZED
+
+from ._protocols import KeyCallback, KeyProvider, KeySource
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class StaticKeyProvider:
+    """A single fixed key — HMAC secret string, PEM-encoded public key, or raw bytes."""
+
+    key: str | bytes | SecretStr
+
+    def __call__(self, token_headers: dict[str, Any], app: Any) -> str | bytes:
+        if isinstance(self.key, SecretStr):
+            return self.key.get_secret_value()
+        return self.key
+
+
+@dataclass
+class EnvKeyProvider:
+    """Read the JWT key from ``app.state`` or a fallback settings loader.
+
+    Parameters
+    ----------
+    state_key:
+        Attribute name on ``app.state`` where a settings object with a
+        ``jwt_secret`` field is stored. Defaults to ``"_versioning_settings"``.
+    settings_loader:
+        Zero-arg callable that returns a settings object with a
+        ``jwt_secret`` attribute. Called when ``app.state`` lookup fails.
+        If *None* and the state lookup also fails, a ``RuntimeError``
+        is raised.
+    """
+
+    state_key: str = "_versioning_settings"
+    settings_loader: Callable[[], Any] | None = None
+
+    def __call__(self, token_headers: dict[str, Any], app: Any) -> str:
+        settings = getattr(app.state, self.state_key, None)
+        if settings is None and self.settings_loader is not None:
+            settings = self.settings_loader()
+
+        if settings is None:
+            raise RuntimeError(
+                "No JWT secret configured. Set the JWT_SECRET env var, "
+                "pass key= to JWTAuthenticator, or use a KeyProvider."
+            )
+
+        jwt_key = getattr(settings, "jwt_secret", None)
+        if jwt_key is None:
+            raise RuntimeError(
+                "No JWT secret configured. Set the JWT_SECRET env var, "
+                "pass key= to JWTAuthenticator, or use a KeyProvider."
+            )
+        return jwt_key.get_secret_value() if isinstance(jwt_key, SecretStr) else str(jwt_key)
+
+
+@dataclass
+class JWKSKeyProvider:
+    """Fetch signing keys from a JWKS (JSON Web Key Set) endpoint."""
+
+    url: str
+    cache_ttl: float = 300.0
+    httpx_kwargs: dict[str, Any] = field(default_factory=dict)
+
+    _jwk_set: Any = field(default=None, init=False, repr=False)
+    _fetched_at: float = field(default=0.0, init=False, repr=False)
+
+    async def __call__(self, token_headers: dict[str, Any], app: Any) -> Any:
+        kid = token_headers.get("kid")
+        alg = token_headers.get("alg", "RS256")
+
+        key = self._find_key(kid, alg)
+        if key is not None:
+            return key
+
+        await self._async_refresh()
+        key = self._find_key(kid, alg)
+        if key is not None:
+            return key
+
+        detail = f"No matching key found in JWKS (kid={kid})" if kid else "No keys in JWKS"
+        raise HTTPException(status_code=HTTP_401_UNAUTHORIZED, detail=detail)
+
+    def _find_key(self, kid: str | None, alg: str) -> Any:
+        if self._jwk_set is None or (time.monotonic() - self._fetched_at > self.cache_ttl):
+            return None
+
+        try:
+            from jwt import PyJWKSet  # noqa: F401 — availability check
+        except ImportError:
+            raise RuntimeError(
+                "JWKSKeyProvider requires PyJWT[crypto]. Install with: pip install 'PyJWT[crypto]'"
+            ) from None
+
+        for jwk in self._jwk_set.keys:
+            jwk_kid = getattr(jwk, "key_id", None)
+            if kid is not None and jwk_kid != kid:
+                continue
+            return jwk.key
+        return None
+
+    async def _async_refresh(self) -> None:
+        if self._jwk_set is not None and time.monotonic() - self._fetched_at <= self.cache_ttl:
+            return
+
+        import httpx
+
+        try:
+            from jwt import PyJWKSet
+        except ImportError:
+            raise RuntimeError(
+                "JWKSKeyProvider requires PyJWT[crypto]. Install with: pip install 'PyJWT[crypto]'"
+            ) from None
+
+        kwargs = {"timeout": 10.0, **self.httpx_kwargs}
+        try:
+            async with httpx.AsyncClient(**kwargs) as client:
+                resp = await client.get(self.url)
+            resp.raise_for_status()
+            self._jwk_set = PyJWKSet.from_dict(resp.json())
+            self._fetched_at = time.monotonic()
+            logger.debug(
+                "Refreshed JWKS from %s: %d key(s)",
+                self.url,
+                len(self._jwk_set.keys),
+            )
+        except Exception as exc:
+            logger.warning("Failed to fetch JWKS from %s: %s", self.url, exc)
+            if self._jwk_set is None:
+                raise HTTPException(
+                    status_code=HTTP_401_UNAUTHORIZED,
+                    detail="Unable to fetch signing keys",
+                )
+
+
+@dataclass
+class MultiKeyProvider:
+    """Route to different keys by ``kid`` JWT header, or try all keys in order."""
+
+    providers: dict[str, KeyProvider | str | bytes] | list[KeyProvider | str | bytes]
+
+    def __call__(self, token_headers: dict[str, Any], app: Any) -> Any:
+        kid = token_headers.get("kid")
+
+        if isinstance(self.providers, dict):
+            if kid is not None and kid in self.providers:
+                return self._resolve_one(self.providers[kid], token_headers, app)
+
+            for provider in self.providers.values():
+                try:
+                    return self._resolve_one(provider, token_headers, app)
+                except Exception:
+                    continue
+
+            raise HTTPException(
+                status_code=HTTP_401_UNAUTHORIZED,
+                detail=f"No key found for kid={kid}" if kid else "No matching key",
+            )
+
+        last_exc: Exception | None = None
+        for provider in self.providers:
+            try:
+                return self._resolve_one(provider, token_headers, app)
+            except Exception as exc:
+                last_exc = exc
+                continue
+
+        raise last_exc or HTTPException(status_code=HTTP_401_UNAUTHORIZED, detail="No matching key")
+
+    @staticmethod
+    def _resolve_one(
+        provider: KeyProvider | str | bytes, token_headers: dict[str, Any], app: Any
+    ) -> Any:
+        if isinstance(provider, (str, bytes)):
+            return provider
+        if isinstance(provider, SecretStr):
+            return provider.get_secret_value()
+        return provider(token_headers, app)
+
+
+@dataclass
+class CallbackKeyProvider:
+    """Delegate key resolution to any user-supplied function."""
+
+    callback: KeyCallback
+
+    def __call__(self, token_headers: dict[str, Any], app: Any) -> Any:
+        return self.callback(token_headers, app)
+
+
+# ── Coerce raw values into KeyProvider instances ────────────────────────
+
+
+def _coerce_key_provider(key: KeySource | None) -> KeyProvider:
+    if key is None:
+        return EnvKeyProvider()
+    if isinstance(key, KeyProvider):
+        return key
+    if isinstance(key, (str, bytes, SecretStr)):
+        return StaticKeyProvider(key)
+    if callable(key):
+        return CallbackKeyProvider(key)
+    raise TypeError(
+        f"key must be a string, bytes, SecretStr, KeyProvider, or callable — "
+        f"got {type(key).__name__}"
+    )

csrd/auth/_protocols.py

@@ -0,0 +1,29 @@
+"""Protocols and type aliases for the auth system."""
+
+from collections.abc import Callable
+from typing import Any, Protocol, runtime_checkable
+
+from fastapi import Request
+from pydantic import SecretStr
+
+from csrd.models.claims import UserClaims
+
+
+@runtime_checkable
+class Authenticator(Protocol):
+    """Protocol for pluggable authentication strategies."""
+
+    def __call__(self, request: Request, token: str) -> UserClaims: ...
+
+
+@runtime_checkable
+class KeyProvider(Protocol):
+    """Protocol for pluggable JWT key resolution."""
+
+    def __call__(self, token_headers: dict[str, Any], app: Any) -> Any: ...
+
+
+AuthCallback = Callable[[Request, str], UserClaims | Any]
+KeyCallback = Callable[..., Any]
+
+KeySource = str | bytes | SecretStr | KeyProvider

csrd_auth-0.1.0.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: csrd-auth
+Version: 0.1.0
+Summary: Pluggable JWT authentication — authenticators, key providers, and FastAPI dependency factories
+Project-URL: Repository, https://github.com/csrd-api/fastapi-common
+Project-URL: Documentation, https://github.com/csrd-api/fastapi-common/tree/main/packages/auth
+Project-URL: Changelog, https://github.com/csrd-api/fastapi-common/blob/main/CHANGELOG.md
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: csrd-context
+Requires-Dist: csrd-models
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: pyjwt<3,>=2

csrd_auth-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+csrd/auth/__init__.py,sha256=2_2Ug0hx23XoQmYNs6M2g79uBUS4ck4Rg7DviD0qpfQ,1320
+csrd/auth/_authenticators.py,sha256=C3rRNlr1qoIz8AphoUamuozbB7m5HylyQR_CbpSmXXk,7254
+csrd/auth/_factory.py,sha256=J2mGoyw_JX1C8bxJpvvXULwh5Gin0hTDCv-Ula6cf6E,2801
+csrd/auth/_key_providers.py,sha256=Py7yuHK1WIQh4iO86ScfVIUa1p_5rQDu_Gts3cgOoCo,7512
+csrd/auth/_protocols.py,sha256=Mh68kIwn3EipKhsiBoxfNvZtVlHJcKdKl5hpupJrOIo,756
+csrd/auth/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+csrd_auth-0.1.0.dist-info/METADATA,sha256=S1pNBc0p6Dd0eMYrSaW_cfoZmb3U-7Pw6FgW_NXwu6I,594
+csrd_auth-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+csrd_auth-0.1.0.dist-info/RECORD,,

csrd_auth-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any