csrd-auth 0.1.0__tar.gz

csrd_auth-0.1.0/.gitignore

@@ -0,0 +1,217 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+/env/
+/venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+*.db
+
+
+# Import linter cache
+.import_linter_cache/
+
+# IDE
+.idea/
+.idea/*

csrd_auth-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,81 @@
+# csrd-auth
+
+Pluggable JWT authentication for FastAPI — authenticators, key providers, and dependency factories.
+
+**Tier 1.5** — depends on `csrd-models` and `csrd-context` only.
+
+## Installation
+
+```bash
+pip install "csrd-auth @ git+https://github.com/your-org/fastapi-common.git#subdirectory=packages/auth"
+```
+
+## Usage
+
+```python
+from csrd.auth import (
+    JWTAuthenticator,
+    StaticKeyProvider,
+    create_bearer_dependency,
+    create_jwt_bearer,
+)
+```
+
+### Quick start — JWT bearer dependency
+
+```python
+# Standalone (provide your own token_finder)
+from csrd.auth import create_jwt_bearer
+
+auth_dep = create_jwt_bearer(
+    key="your-secret",
+    token_finder=lambda: extract_token_from_request(),
+)
+```
+
+When used via `csrd.versioning`, `find_token` is injected automatically:
+
+```python
+# Via versioning (token_finder = find_token by default)
+from csrd.versioning.auth import create_jwt_bearer
+
+auth_dep = create_jwt_bearer(key="your-secret")
+```
+
+## Authenticators
+
+| Class | Strategy |
+|-------|----------|
+| `JWTAuthenticator` | Decode & verify JWT locally via PyJWT |
+| `StaticAuthenticator` | Accept a fixed token (dev/testing) |
+| `RemoteAuthenticator` | Validate via upstream HTTP endpoint |
+| `CallbackAuthenticator` | Delegate to any sync/async callable |
+| `ChainedAuthenticator` | Try multiple authenticators in order |
+
+## Key Providers
+
+| Class | Strategy |
+|-------|----------|
+| `StaticKeyProvider` | Fixed string, bytes, or `SecretStr` |
+| `EnvKeyProvider` | Read from `app.state` or settings loader |
+| `JWKSKeyProvider` | Fetch from JWKS endpoint (cached with TTL) |
+| `MultiKeyProvider` | Route by `kid` header or try all |
+| `CallbackKeyProvider` | Delegate to any callable |
+
+## Protocols
+
+- `Authenticator` — `(Request, str) -> UserClaims`
+- `KeyProvider` — `(token_headers, app) -> key`
+
+Both are `@runtime_checkable` protocols.
+
+## Dependency Tier
+
+```
+Tier 1    csrd.models · csrd.lifespan · csrd.context
+Tier 1.5  csrd.auth · csrd.logging
+Tier 2    csrd.delegate · csrd.repository · csrd.service
+Tier 3    csrd.versioning
+```
+
+`csrd.auth` depends only on `csrd.models` (for `UserClaims`) and `csrd.context` (for `user_info_context`). It has **no dependency** on `csrd.versioning`.

csrd_auth-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "csrd-auth"
+version = "0.1.0"
+description = "Pluggable JWT authentication — authenticators, key providers, and FastAPI dependency factories"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115,<1",
+    "pydantic>=2,<3",
+    "PyJWT>=2,<3",
+    "csrd-context",
+    "csrd-models",
+]
+
+[tool.uv.sources]
+csrd-context = { workspace = true }
+csrd-models = { workspace = true }
+
+[project.urls]
+Repository = "https://github.com/csrd-api/fastapi-common"
+Documentation = "https://github.com/csrd-api/fastapi-common/tree/main/packages/auth"
+Changelog = "https://github.com/csrd-api/fastapi-common/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/csrd"]

csrd_auth-0.1.0/src/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-0.1.0/src/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",
+        )