fastapi-toolsets 3.1.1__tar.gz → 4.0.0__tar.gz

{fastapi_toolsets-3.1.1 → fastapi_toolsets-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-toolsets
-Version: 3.1.1
+Version: 4.0.0
 Summary: Production-ready utilities for FastAPI applications
 Keywords: fastapi,sqlalchemy,postgresql
 Author: d3vyce
@@ -29,12 +29,14 @@ Requires-Dist: asyncpg>=0.29.0
 Requires-Dist: fastapi>=0.100.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: sqlalchemy[asyncio]>=2.0
-Requires-Dist: fastapi-toolsets[cli,metrics,pytest] ; extra == 'all'
+Requires-Dist: fastapi-toolsets[cli,metrics,pytest,security] ; extra == 'all'
 Requires-Dist: typer>=0.9.0 ; extra == 'cli'
 Requires-Dist: prometheus-client>=0.20.0 ; extra == 'metrics'
 Requires-Dist: httpx>=0.25.0 ; extra == 'pytest'
 Requires-Dist: pytest-xdist>=3.0.0 ; extra == 'pytest'
 Requires-Dist: pytest>=8.0.0 ; extra == 'pytest'
+Requires-Dist: async-lru>=1.0 ; extra == 'security'
+Requires-Dist: httpx>=0.25.0 ; extra == 'security'
 Requires-Python: >=3.11
 Project-URL: Homepage, https://github.com/d3vyce/fastapi-toolsets
 Project-URL: Documentation, https://fastapi-toolsets.d3vyce.fr/
@@ -44,6 +46,7 @@ Provides-Extra: all
 Provides-Extra: cli
 Provides-Extra: metrics
 Provides-Extra: pytest
+Provides-Extra: security
 Description-Content-Type: text/markdown
 
 # FastAPI Toolsets
@@ -79,6 +82,7 @@ Install only the extras you need:
 ```bash
 uv add "fastapi-toolsets[cli]"
 uv add "fastapi-toolsets[metrics]"
+uv add "fastapi-toolsets[security]"
 uv add "fastapi-toolsets[pytest]"
 ```
 
@@ -104,6 +108,7 @@ uv add "fastapi-toolsets[all]"
 
 ### Optional
 
+- **Security**: Composable authentication sources (`BearerTokenAuth`, `CookieAuth`, `APIKeyHeaderAuth`, `MultiAuth`) with HMAC-signed cookies and OAuth 2.0 / OIDC helpers
 - **CLI**: Django-like command-line interface with fixture management and custom commands support
 - **Metrics**: Prometheus metrics endpoint with provider/collector registry
 - **Pytest Helpers**: Async test client, database session management, `pytest-xdist` support, and table cleanup utilities

{fastapi_toolsets-3.1.1 → fastapi_toolsets-4.0.0}/README.md

@@ -31,6 +31,7 @@ Install only the extras you need:
 ```bash
 uv add "fastapi-toolsets[cli]"
 uv add "fastapi-toolsets[metrics]"
+uv add "fastapi-toolsets[security]"
 uv add "fastapi-toolsets[pytest]"
 ```
 
@@ -56,6 +57,7 @@ uv add "fastapi-toolsets[all]"
 
 ### Optional
 
+- **Security**: Composable authentication sources (`BearerTokenAuth`, `CookieAuth`, `APIKeyHeaderAuth`, `MultiAuth`) with HMAC-signed cookies and OAuth 2.0 / OIDC helpers
 - **CLI**: Django-like command-line interface with fixture management and custom commands support
 - **Metrics**: Prometheus metrics endpoint with provider/collector registry
 - **Pytest Helpers**: Async test client, database session management, `pytest-xdist` support, and table cleanup utilities

{fastapi_toolsets-3.1.1 → fastapi_toolsets-4.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-toolsets"
-version = "3.1.1"
+version = "4.0.0"
 description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"
@@ -50,13 +50,17 @@ cli = [
 metrics = [
     "prometheus_client>=0.20.0",
 ]
+security = [
+    "async-lru>=1.0",
+    "httpx>=0.25.0",
+]
 pytest = [
     "httpx>=0.25.0",
     "pytest-xdist>=3.0.0",
     "pytest>=8.0.0",
 ]
 all = [
-    "fastapi-toolsets[cli,metrics,pytest]",
+    "fastapi-toolsets[cli,metrics,pytest,security]",
 ]
 
 [project.scripts]
@@ -66,12 +70,14 @@ manager = "fastapi_toolsets.cli.app:cli"
 dev = [
     {include-group = "tests"},
     {include-group = "docs"},
+    {include-group = "docs-src"},
     "fastapi-toolsets[all]",
     "prek>=0.3.8",
     "ruff>=0.1.0",
     "ty>=0.0.1a0",
 ]
 tests = [
+    "async-lru>=1.0",
     "coverage>=7.0.0",
     "httpx>=0.25.0",
     "pytest-anyio>=0.0.0",
@@ -84,6 +90,9 @@ docs = [
     "mkdocstrings-python>=2.0.2",
     "zensical>=0.0.30",
 ]
+docs-src = [
+    "bcrypt>=4.0.0",
+]
 
 [build-system]
 requires = ["uv_build>=0.10,<0.12.0"]

{fastapi_toolsets-3.1.1 → fastapi_toolsets-4.0.0}/src/fastapi_toolsets/__init__.py

@@ -21,4 +21,4 @@ Example usage:
         return Response(data={"user": user.username}, message="Success")
 """
 
-__version__ = "3.1.1"
+__version__ = "4.0.0"

{fastapi_toolsets-3.1.1 → fastapi_toolsets-4.0.0}/src/fastapi_toolsets/crud/factory.py

@@ -1334,7 +1334,7 @@ class AsyncCrud(Generic[ModelType]):
                 count_q = count_q.where(and_(*filters))
 
             count_result = await session.execute(count_q)
-            total_count: int | None = count_result.scalar_one()
+            total_count: int = count_result.scalar_one()
             has_more = page * items_per_page < total_count
         else:
             # Fetch one extra row to detect if a next page exists without COUNT

{fastapi_toolsets-3.1.1 → fastapi_toolsets-4.0.0}/src/fastapi_toolsets/db.py

@@ -151,52 +151,57 @@ class LockMode(str, Enum):
     ACCESS_EXCLUSIVE = "ACCESS EXCLUSIVE"
 
 
-@asynccontextmanager
-async def lock_tables(
-    session: AsyncSession,
+def lock_tables(
+    session_maker: async_sessionmaker[_SessionT],
     tables: list[type[DeclarativeBase]],
     *,
     mode: LockMode = LockMode.SHARE_UPDATE_EXCLUSIVE,
     timeout: str = "5s",
-) -> AsyncGenerator[AsyncSession, None]:
+) -> AbstractAsyncContextManager[_SessionT]:
     """Lock PostgreSQL tables for the duration of a transaction.
 
-    Acquires table-level locks that are held until the transaction ends.
-    Useful for preventing concurrent modifications during critical operations.
-
     Args:
-        session: AsyncSession instance
-        tables: List of SQLAlchemy model classes to lock
-        mode: Lock mode (default: SHARE UPDATE EXCLUSIVE)
-        timeout: Lock timeout (default: "5s")
+        session_maker: Async session factory used to create the dedicated
+            session.
+        tables: List of SQLAlchemy model classes to lock.
+        mode: Lock mode (default: SHARE UPDATE EXCLUSIVE).
+        timeout: Lock timeout (default: "5s").
 
     Yields:
-        The session with locked tables
+        The dedicated session, open within the locked transaction.
 
     Raises:
-        SQLAlchemyError: If lock cannot be acquired within timeout
+        SQLAlchemyError: If the lock cannot be acquired within *timeout*.
 
     Example:
         ```python
         from fastapi_toolsets.db import lock_tables, LockMode
 
-        async with lock_tables(session, [User, Account]):
-            # Tables are locked with SHARE UPDATE EXCLUSIVE mode
+        async with lock_tables(session_maker, [User, Account]) as session:
+            # Tables are locked; changes are committed when the context exits.
             user = await UserCrud.get(session, [User.id == 1])
             user.balance += 100
 
         # With custom lock mode
-        async with lock_tables(session, [Order], mode=LockMode.EXCLUSIVE):
-            # Exclusive lock - no other transactions can access
+        async with lock_tables(session_maker, [Order], mode=LockMode.EXCLUSIVE) as session:
             await process_order(session, order_id)
         ```
     """
     table_names = ",".join(table.__tablename__ for table in tables)
 
-    async with get_transaction(session):
-        await session.execute(text(f"SET LOCAL lock_timeout='{timeout}'"))
-        await session.execute(text(f"LOCK {table_names} IN {mode.value} MODE"))
-        yield session
+    @asynccontextmanager
+    async def _lock() -> AsyncGenerator[_SessionT, None]:
+        async with session_maker() as session:
+            try:
+                await session.execute(text(f"SET LOCAL lock_timeout='{timeout}'"))
+                await session.execute(text(f"LOCK {table_names} IN {mode.value} MODE"))
+                yield session
+                await session.commit()
+            except BaseException:
+                await session.rollback()
+                raise
+
+    return _lock()
 
 
 async def create_database(

{fastapi_toolsets-3.1.1 → fastapi_toolsets-4.0.0}/src/fastapi_toolsets/schemas.py

@@ -179,7 +179,7 @@ class PaginatedResponse(BaseResponse, Generic[DataT]):
                 ]
                 cls._discriminated_union_cache[item] = cached
             return cached  # ty:ignore[invalid-return-type]
-        return super().__class_getitem__(item)
+        return super().__class_getitem__(item)  # ty:ignore[invalid-return-type]
 
 
 class OffsetPaginatedResponse(PaginatedResponse[DataT]):

fastapi_toolsets-4.0.0/src/fastapi_toolsets/security/__init__.py

@@ -0,0 +1,26 @@
+"""Authentication helpers for FastAPI using Security()."""
+
+from .abc import AuthSource
+from .oauth import (
+    oauth_build_authorization_redirect,
+    oauth_decode_state,
+    oauth_encode_state,
+    oauth_fetch_userinfo,
+    oauth_generate_state_token,
+    oauth_resolve_provider_urls,
+)
+from .sources import APIKeyHeaderAuth, BearerTokenAuth, CookieAuth, MultiAuth
+
+__all__ = [
+    "APIKeyHeaderAuth",
+    "AuthSource",
+    "BearerTokenAuth",
+    "CookieAuth",
+    "MultiAuth",
+    "oauth_build_authorization_redirect",
+    "oauth_decode_state",
+    "oauth_encode_state",
+    "oauth_fetch_userinfo",
+    "oauth_generate_state_token",
+    "oauth_resolve_provider_urls",
+]

fastapi_toolsets-4.0.0/src/fastapi_toolsets/security/abc.py

@@ -0,0 +1,55 @@
+"""Abstract base class for authentication sources."""
+
+import functools
+import inspect
+from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+from fastapi import Request
+from fastapi.security import SecurityScopes
+
+from fastapi_toolsets.exceptions import UnauthorizedError
+
+
+def _ensure_async(fn: Callable[..., Any]) -> Callable[..., Any]:
+    """Wrap *fn* so it can always be awaited, caching the coroutine check at init time."""
+    if inspect.iscoroutinefunction(fn):
+        return fn
+
+    @functools.wraps(fn)
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        return fn(*args, **kwargs)
+
+    return wrapper
+
+
+class AuthSource(ABC):
+    """Abstract base class for authentication sources."""
+
+    def __init__(self) -> None:
+        """Set up the default FastAPI dependency signature."""
+        source = self
+
+        async def _call(
+            request: Request,
+            security_scopes: SecurityScopes,  # noqa: ARG001
+        ) -> Any:
+            credential = await source.extract(request)
+            if credential is None:
+                raise UnauthorizedError()
+            return await source.authenticate(credential)
+
+        self._call_fn: Callable[..., Any] = _call
+        self.__signature__ = inspect.signature(_call)
+
+    @abstractmethod
+    async def extract(self, request: Request) -> str | None:
+        """Extract the raw credential from the request without validating."""
+
+    @abstractmethod
+    async def authenticate(self, credential: str) -> Any:
+        """Validate a credential and return the authenticated identity."""
+
+    async def __call__(self, **kwargs: Any) -> Any:
+        """FastAPI dependency dispatch."""
+        return await self._call_fn(**kwargs)

fastapi_toolsets-4.0.0/src/fastapi_toolsets/security/oauth.py

@@ -0,0 +1,197 @@
+"""OAuth 2.0 / OIDC helper utilities."""
+
+import base64
+import binascii
+import hmac
+import json
+import secrets
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+from async_lru import alru_cache
+from fastapi.responses import RedirectResponse
+
+
+@alru_cache(maxsize=32)
+async def oauth_resolve_provider_urls(
+    discovery_url: str,
+) -> tuple[str, str, str | None]:
+    """Fetch the OIDC discovery document and return endpoint URLs.
+
+    Args:
+        discovery_url: URL of the provider's ``/.well-known/openid-configuration``.
+
+    Returns:
+        A ``(authorization_url, token_url, userinfo_url)`` tuple.
+        *userinfo_url* is ``None`` when the provider does not advertise one.
+    """
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(discovery_url)
+        resp.raise_for_status()
+    cfg = resp.json()
+    return (
+        cfg["authorization_endpoint"],
+        cfg["token_endpoint"],
+        cfg.get("userinfo_endpoint"),
+    )
+
+
+async def oauth_fetch_userinfo(
+    *,
+    token_url: str,
+    userinfo_url: str,
+    code: str,
+    client_id: str,
+    client_secret: str,
+    redirect_uri: str,
+    required_scopes: str | None = None,
+) -> dict[str, Any]:
+    """Exchange an authorization code for tokens and return the userinfo payload.
+
+    Args:
+        token_url: Provider's token endpoint.
+        userinfo_url: Provider's userinfo endpoint.
+        code: Authorization code received from the provider's callback.
+        client_id: OAuth application client ID.
+        client_secret: OAuth application client secret.
+        redirect_uri: Redirect URI that was used in the authorization request.
+        required_scopes: Space-separated scopes that must be present in the token
+            response ``scope`` field (RFC 6749 §3.3).  Raises ``ValueError`` if
+            the provider granted fewer scopes than requested.
+
+    Returns:
+        The JSON payload returned by the userinfo endpoint as a plain ``dict``.
+
+    Raises:
+        ValueError: If the provider granted a different token type than ``bearer``
+            or did not grant all ``required_scopes``.
+    """
+    async with httpx.AsyncClient() as client:
+        token_resp = await client.post(
+            token_url,
+            data={
+                "grant_type": "authorization_code",
+                "code": code,
+                "client_id": client_id,
+                "client_secret": client_secret,
+                "redirect_uri": redirect_uri,
+            },
+            headers={"Accept": "application/json"},
+        )
+        token_resp.raise_for_status()
+        token_data = token_resp.json()
+
+        if token_data.get("token_type", "bearer").lower() != "bearer":
+            raise ValueError(
+                f"unsupported token_type: {token_data.get('token_type')!r}"
+            )
+
+        if required_scopes is not None:
+            granted = set(token_data.get("scope", "").split())
+            missing = set(required_scopes.split()) - granted
+            if missing:
+                raise ValueError(f"provider did not grant required scopes: {missing}")
+
+        access_token = token_data["access_token"]
+
+        userinfo_resp = await client.get(
+            userinfo_url,
+            headers={"Authorization": f"Bearer {access_token}"},
+        )
+        userinfo_resp.raise_for_status()
+        return userinfo_resp.json()
+
+
+def oauth_generate_state_token() -> str:
+    """Generate a cryptographically random CSRF token for the OAuth ``state`` parameter."""
+    return secrets.token_urlsafe(32)
+
+
+def oauth_build_authorization_redirect(
+    authorization_url: str,
+    *,
+    client_id: str,
+    scopes: str,
+    redirect_uri: str,
+    destination: str,
+    state_token: str,
+) -> RedirectResponse:
+    """Return an OAuth 2.0 authorization ``RedirectResponse``.
+
+    Args:
+        authorization_url: Provider's authorization endpoint.
+        client_id: OAuth application client ID.
+        scopes: Space-separated list of requested scopes.
+        redirect_uri: URI the provider should redirect back to after authorization.
+        destination: URL the user should be sent to after the full OAuth flow
+            completes (embedded in ``state``).
+        state_token: CSRF token generated by :func:`oauth_generate_state_token`.
+            Must be stored server-side (session or signed cookie) and verified via
+            :func:`oauth_decode_state` on the callback endpoint (RFC 6749 §10.12).
+
+    Returns:
+        A :class:`~fastapi.responses.RedirectResponse` to the provider's
+        authorization page.
+    """
+    params = urlencode(
+        {
+            "client_id": client_id,
+            "response_type": "code",
+            "scope": scopes,
+            "redirect_uri": redirect_uri,
+            "state": oauth_encode_state(destination, state_token),
+        }
+    )
+    return RedirectResponse(f"{authorization_url}?{params}")
+
+
+def oauth_encode_state(url: str, state_token: str) -> str:
+    """Encode a destination URL and CSRF token into an OAuth ``state`` parameter.
+
+    Args:
+        url: Post-login destination URL.
+        state_token: CSRF token from :func:`oauth_generate_state_token`.
+    """
+    payload = json.dumps({"n": state_token, "d": url}, separators=(",", ":"))
+    return base64.urlsafe_b64encode(payload.encode()).decode()
+
+
+def oauth_decode_state(
+    state: str | None, *, expected_state_token: str, fallback: str
+) -> str:
+    """Decode and CSRF-verify an OAuth ``state`` parameter.
+
+    Uses a constant-time comparison for the CSRF token to prevent timing attacks.
+
+    Args:
+        state: Raw ``state`` query parameter from the provider's callback.
+        expected_state_token: The token stored before the authorization redirect.
+            If it does not match the decoded value, ``fallback`` is returned.
+        fallback: URL to return when ``state`` is absent, malformed, or fails
+            CSRF verification.
+
+    Returns:
+        The destination URL embedded in ``state``, or ``fallback``.
+
+    Important:
+        **Single-use**: delete the stored token from the session immediately
+        after calling this function — whether it matched or not — so that a
+        captured callback URL cannot be replayed.
+
+        **Open-redirect**: validate the returned URL against a known-good
+        origin or relative-path allowlist before issuing the final redirect.
+        Do not forward arbitrary URLs to ``RedirectResponse``.
+    """
+    if not state or state == "null":  # "null" guards against JS JSON.stringify(null)
+        return fallback
+    try:
+        padded = state + "=" * (-len(state) % 4)
+        payload = json.loads(base64.urlsafe_b64decode(padded).decode("utf-8"))
+        if not isinstance(payload, dict) or not hmac.compare_digest(
+            payload.get("n", "").encode(), expected_state_token.encode()
+        ):
+            return fallback
+        return str(payload["d"])
+    except (UnicodeDecodeError, ValueError, binascii.Error, KeyError):
+        return fallback

fastapi_toolsets-4.0.0/src/fastapi_toolsets/security/sources/__init__.py

@@ -0,0 +1,8 @@
+"""Built-in authentication source implementations."""
+
+from .header import APIKeyHeaderAuth
+from .bearer import BearerTokenAuth
+from .cookie import CookieAuth
+from .multi import MultiAuth
+
+__all__ = ["APIKeyHeaderAuth", "BearerTokenAuth", "CookieAuth", "MultiAuth"]

fastapi_toolsets-4.0.0/src/fastapi_toolsets/security/sources/bearer.py

@@ -0,0 +1,120 @@
+"""Bearer token authentication source."""
+
+import inspect
+import secrets
+from typing import Annotated, Any, Callable
+
+from fastapi import Depends, Request
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer, SecurityScopes
+
+from fastapi_toolsets.exceptions import UnauthorizedError
+
+from ..abc import AuthSource, _ensure_async
+
+
+class BearerTokenAuth(AuthSource):
+    """Bearer token authentication source.
+
+    Wraps :class:`fastapi.security.HTTPBearer` for OpenAPI documentation.
+    The validator is called as ``await validator(credential, **kwargs)``
+    where ``kwargs`` are the extra keyword arguments provided at instantiation.
+
+    Args:
+        validator: Sync or async callable that receives the credential and any
+            extra keyword arguments, and returns the authenticated identity
+            (e.g. a ``User`` model). Should raise
+            :class:`~fastapi_toolsets.exceptions.UnauthorizedError` on failure.
+        prefix: Optional token prefix (e.g. ``"user_"``). If set, only tokens
+            whose value starts with this prefix are matched. The prefix is
+            **kept** in the value passed to the validator — store and compare
+            tokens with their prefix included. Use :meth:`generate_token` to
+            create correctly-prefixed tokens. This enables multiple
+            ``BearerTokenAuth`` instances in the same app (e.g. ``"user_"``
+            for user tokens, ``"org_"`` for org tokens).
+        **kwargs: Extra keyword arguments forwarded to the validator on every
+            call (e.g. ``role=Role.ADMIN``).
+    """
+
+    def __init__(
+        self,
+        validator: Callable[..., Any],
+        *,
+        prefix: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._validator = _ensure_async(validator)
+        self._prefix = prefix
+        self._kwargs = kwargs
+        self._scheme = HTTPBearer(auto_error=False)
+
+        async def _call(
+            security_scopes: SecurityScopes,  # noqa: ARG001
+            credentials: Annotated[
+                HTTPAuthorizationCredentials | None, Depends(self._scheme)
+            ] = None,
+        ) -> Any:
+            if credentials is None:
+                raise UnauthorizedError()
+            return await self._validate(credentials.credentials)
+
+        self._call_fn = _call
+        self.__signature__ = inspect.signature(_call)
+
+    async def _validate(self, token: str) -> Any:
+        """Check prefix and call the validator."""
+        if self._prefix is not None and not token.startswith(self._prefix):
+            raise UnauthorizedError()
+        return await self._validator(token, **self._kwargs)
+
+    async def extract(self, request: Request) -> str | None:
+        """Extract the raw credential from the request without validating.
+
+        Returns ``None`` if no ``Authorization: Bearer`` header is present,
+        the token is empty, or the token does not match the configured prefix.
+        The prefix is included in the returned value.
+        """
+        auth = request.headers.get("Authorization", "")
+        if not auth.startswith("Bearer "):
+            return None
+        token = auth[7:]
+        if not token:
+            return None
+        if self._prefix is not None and not token.startswith(self._prefix):
+            return None
+        return token
+
+    async def authenticate(self, credential: str) -> Any:
+        """Validate a credential and return the identity.
+
+        Calls ``await validator(credential, **kwargs)`` where ``kwargs`` are
+        the extra keyword arguments provided at instantiation.
+        """
+        return await self._validate(credential)
+
+    def require(self, **kwargs: Any) -> "BearerTokenAuth":
+        """Return a new instance with additional (or overriding) validator kwargs."""
+        return BearerTokenAuth(
+            self._validator,
+            prefix=self._prefix,
+            **{**self._kwargs, **kwargs},
+        )
+
+    def generate_token(self, nbytes: int = 32) -> str:
+        """Generate a secure random token for this auth source.
+
+        Returns a URL-safe random token. If a prefix is configured it is
+        prepended — the returned value is what you store in your database
+        and return to the client as-is.
+
+        Args:
+            nbytes: Number of random bytes before base64 encoding. The
+                resulting string is ``ceil(nbytes * 4 / 3)`` characters
+                (43 chars for the default 32 bytes). Defaults to 32.
+
+        Returns:
+            A ready-to-use token string (e.g. ``"user_Xk3..."``).
+        """
+        token = secrets.token_urlsafe(nbytes)
+        if self._prefix is not None:
+            return f"{self._prefix}{token}"
+        return token

fastapi_toolsets-4.0.0/src/fastapi_toolsets/security/sources/cookie.py

@@ -0,0 +1,148 @@
+"""Cookie-based authentication source."""
+
+import base64
+import hashlib
+import hmac
+import inspect
+import json
+import time
+from typing import Annotated, Any, Callable
+
+from fastapi import Depends, Request, Response
+from fastapi.security import APIKeyCookie, SecurityScopes
+
+from fastapi_toolsets.exceptions import UnauthorizedError
+
+from ..abc import AuthSource, _ensure_async
+
+
+class CookieAuth(AuthSource):
+    """Cookie-based authentication source.
+
+    Wraps :class:`fastapi.security.APIKeyCookie` for OpenAPI documentation.
+    Optionally signs the cookie with HMAC-SHA256 to provide stateless, tamper-
+    proof sessions without any database entry.
+
+    Args:
+        name: Cookie name.
+        validator: Sync or async callable that receives the cookie value
+            (plain, after signature verification when ``secret_key`` is set)
+            and any extra keyword arguments, and returns the authenticated
+            identity.
+        secret_key: When provided, the cookie is HMAC-SHA256 signed.
+            :meth:`set_cookie` embeds an expiry and signs the payload;
+            :meth:`extract` verifies the signature and expiry before handing
+            the plain value to the validator.  When ``None`` (default), the raw
+            cookie value is passed to the validator as-is.
+        ttl: Cookie lifetime in seconds (default 24 h).  Only used when
+            ``secret_key`` is set.
+        secure: Set the ``Secure`` flag on the cookie so it is only transmitted
+            over HTTPS (default ``True``).  Set to ``False`` only in local
+            development environments where HTTPS is unavailable.
+        **kwargs: Extra keyword arguments forwarded to the validator on every
+            call (e.g. ``role=Role.ADMIN``).
+    """
+
+    def __init__(
+        self,
+        name: str,
+        validator: Callable[..., Any],
+        *,
+        secret_key: str | None = None,
+        ttl: int = 86400,
+        secure: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        self._name = name
+        self._validator = _ensure_async(validator)
+        self._secret_key = secret_key
+        self._ttl = ttl
+        self._secure = secure
+        self._kwargs = kwargs
+        self._scheme = APIKeyCookie(name=name, auto_error=False)
+
+        async def _call(
+            security_scopes: SecurityScopes,  # noqa: ARG001
+            value: Annotated[str | None, Depends(self._scheme)] = None,
+        ) -> Any:
+            if value is None:
+                raise UnauthorizedError()
+            plain = self._verify(value)
+            return await self._validator(plain, **self._kwargs)
+
+        self._call_fn = _call
+        self.__signature__ = inspect.signature(_call)
+
+    def _hmac(self, data: str) -> str:
+        if self._secret_key is None:
+            raise RuntimeError("_hmac called without secret_key configured")
+        return hmac.new(
+            self._secret_key.encode(), data.encode(), hashlib.sha256
+        ).hexdigest()
+
+    def _sign(self, value: str) -> str:
+        data = base64.urlsafe_b64encode(
+            json.dumps({"v": value, "exp": int(time.time()) + self._ttl}).encode()
+        ).decode()
+        return f"{data}.{self._hmac(data)}"
+
+    def _verify(self, cookie_value: str) -> str:
+        """Return the plain value, verifying HMAC + expiry when signed."""
+        if not self._secret_key:
+            return cookie_value
+
+        try:
+            data, sig = cookie_value.rsplit(".", 1)
+        except ValueError:
+            raise UnauthorizedError()
+
+        if not hmac.compare_digest(self._hmac(data), sig):
+            raise UnauthorizedError()
+
+        try:
+            payload = json.loads(base64.urlsafe_b64decode(data))
+            value: str = payload["v"]
+            exp: int = payload["exp"]
+        except Exception:
+            raise UnauthorizedError()
+
+        if exp < int(time.time()):
+            raise UnauthorizedError()
+
+        return value
+
+    async def extract(self, request: Request) -> str | None:
+        return request.cookies.get(self._name)
+
+    async def authenticate(self, credential: str) -> Any:
+        plain = self._verify(credential)
+        return await self._validator(plain, **self._kwargs)
+
+    def require(self, **kwargs: Any) -> "CookieAuth":
+        """Return a new instance with additional (or overriding) validator kwargs."""
+        return CookieAuth(
+            self._name,
+            self._validator,
+            secret_key=self._secret_key,
+            ttl=self._ttl,
+            secure=self._secure,
+            **{**self._kwargs, **kwargs},
+        )
+
+    def set_cookie(self, response: Response, value: str) -> None:
+        """Attach the cookie to *response*, signing it when ``secret_key`` is set."""
+        cookie_value = self._sign(value) if self._secret_key else value
+        response.set_cookie(
+            self._name,
+            cookie_value,
+            httponly=True,
+            samesite="lax",
+            secure=self._secure,
+            max_age=self._ttl,
+        )
+
+    def delete_cookie(self, response: Response) -> None:
+        """Clear the session cookie (logout)."""
+        response.delete_cookie(
+            self._name, httponly=True, samesite="lax", secure=self._secure
+        )

fastapi_toolsets-4.0.0/src/fastapi_toolsets/security/sources/header.py

@@ -0,0 +1,67 @@
+"""API key header authentication source."""
+
+import inspect
+from typing import Annotated, Any, Callable
+
+from fastapi import Depends, Request
+from fastapi.security import APIKeyHeader, SecurityScopes
+
+from fastapi_toolsets.exceptions import UnauthorizedError
+
+from ..abc import AuthSource, _ensure_async
+
+
+class APIKeyHeaderAuth(AuthSource):
+    """API key header authentication source.
+
+    Wraps :class:`fastapi.security.APIKeyHeader` for OpenAPI documentation.
+    The validator is called as ``await validator(api_key, **kwargs)``
+    where ``kwargs`` are the extra keyword arguments provided at instantiation.
+
+    Args:
+        name: HTTP header name that carries the API key (e.g. ``"X-API-Key"``).
+        validator: Sync or async callable that receives the API key and any
+            extra keyword arguments, and returns the authenticated identity.
+            Should raise :class:`~fastapi_toolsets.exceptions.UnauthorizedError`
+            on failure.
+        **kwargs: Extra keyword arguments forwarded to the validator on every
+            call (e.g. ``role=Role.ADMIN``).
+    """
+
+    def __init__(
+        self,
+        name: str,
+        validator: Callable[..., Any],
+        **kwargs: Any,
+    ) -> None:
+        self._name = name
+        self._validator = _ensure_async(validator)
+        self._kwargs = kwargs
+        self._scheme = APIKeyHeader(name=name, auto_error=False)
+
+        async def _call(
+            security_scopes: SecurityScopes,  # noqa: ARG001
+            api_key: Annotated[str | None, Depends(self._scheme)] = None,
+        ) -> Any:
+            if api_key is None:
+                raise UnauthorizedError()
+            return await self._validator(api_key, **self._kwargs)
+
+        self._call_fn = _call
+        self.__signature__ = inspect.signature(_call)
+
+    async def extract(self, request: Request) -> str | None:
+        """Extract the API key from the configured header."""
+        return request.headers.get(self._name) or None
+
+    async def authenticate(self, credential: str) -> Any:
+        """Validate a credential and return the identity."""
+        return await self._validator(credential, **self._kwargs)
+
+    def require(self, **kwargs: Any) -> "APIKeyHeaderAuth":
+        """Return a new instance with additional (or overriding) validator kwargs."""
+        return APIKeyHeaderAuth(
+            self._name,
+            self._validator,
+            **{**self._kwargs, **kwargs},
+        )

fastapi_toolsets-4.0.0/src/fastapi_toolsets/security/sources/multi.py

@@ -0,0 +1,71 @@
+"""MultiAuth: combine multiple authentication sources into a single callable."""
+
+import inspect
+from typing import Any, cast
+
+from fastapi import Request
+from fastapi.security import SecurityScopes
+
+from fastapi_toolsets.exceptions import UnauthorizedError
+
+from ..abc import AuthSource
+
+
+class MultiAuth:
+    """Combine multiple authentication sources into a single callable.
+
+    Args:
+        *sources: Auth source instances to try in order.
+    """
+
+    def __init__(self, *sources: AuthSource) -> None:
+        self._sources = sources
+
+        async def _call(
+            request: Request,
+            security_scopes: SecurityScopes,  # noqa: ARG001
+            **kwargs: Any,  # noqa: ARG001  — absorbs scheme values injected by FastAPI
+        ) -> Any:
+            for source in self._sources:
+                credential = await source.extract(request)
+                if credential is not None:
+                    return await source.authenticate(credential)
+            raise UnauthorizedError()
+
+        self._call_fn = _call
+
+        # Build a merged signature that includes the security-scheme Depends()
+        # parameters from every source so FastAPI registers them in OpenAPI docs.
+        seen: set[str] = {"request", "security_scopes"}
+        merged: list[inspect.Parameter] = [
+            inspect.Parameter(
+                "request",
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                annotation=Request,
+            ),
+            inspect.Parameter(
+                "security_scopes",
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                annotation=SecurityScopes,
+            ),
+        ]
+        for i, source in enumerate(sources):
+            for name, param in inspect.signature(source).parameters.items():
+                if name in seen:
+                    continue
+                merged.append(param.replace(name=f"_s{i}_{name}"))
+                seen.add(name)
+        self.__signature__ = inspect.Signature(merged, return_annotation=Any)
+
+    async def __call__(self, **kwargs: Any) -> Any:
+        return await self._call_fn(**kwargs)
+
+    def require(self, **kwargs: Any) -> "MultiAuth":
+        """Return a new :class:`MultiAuth` with kwargs forwarded to each source."""
+        new_sources = tuple(
+            cast(Any, source).require(**kwargs)
+            if hasattr(source, "require")
+            else source
+            for source in self._sources
+        )
+        return MultiAuth(*new_sources)