fastapi-multiauth 0.4.0__tar.gz → 0.5.0__tar.gz

{fastapi_multiauth-0.4.0 → fastapi_multiauth-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-multiauth
-Version: 0.4.0
+Version: 0.5.0
 Summary: Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes, correct OpenAPI by construction
 Keywords: fastapi,authentication,security,oauth,api-key,bearer,cookie
 Author: d3vyce
@@ -25,7 +25,7 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Dist: anyio>=3.7
 Requires-Dist: async-lru>=2.0
-Requires-Dist: fastapi>=0.100.0
+Requires-Dist: fastapi>=0.108.0
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: itsdangerous>=2.1
 Requires-Dist: pyjwt[crypto]>=2.13.0 ; extra == 'jwt'
@@ -122,6 +122,7 @@ async def me(user=Security(auth)):
     - **`APIKeyCookieAuth`**: cookie sessions with optional HMAC-SHA256 signing (via [itsdangerous](https://itsdangerous.palletsprojects.com/)), embedded expiry, key rotation, and optional per-session ids so your app can list and revoke sessions individually.
     - **`APIKeyHeaderAuth`**: `X-API-Key`-style schemes, with **`APIKeyQueryAuth`** for legacy clients that can only pass a query parameter.
     - **`HTTPBasicAuth`**: `validator(username, password)` with `WWW-Authenticate` realm support.
+    - **`OAuth2AuthorizationCodeBearerAuth`**, **`OAuth2PasswordBearerAuth`**, **`OpenIdConnectAuth`**: validate tokens an OAuth 2.0 / OIDC provider issued, and publish the scope catalogue so `/docs` offers a real Authorize dialog.
 - **Token hashing helpers**: `hash_token`/`verify_token_hash` package the "store the hash, never the token" pattern with constant-time comparison.
 - **JWT validation** (`fastapi-multiauth[jwt]` extra): `JWTValidator` for `HTTPBearerAuth`: HS256 or provider JWKS (Keycloak/Auth0/Entra/Authentik) with TTL caching and rotation-aware `kid` refresh, `aud`/`iss`/`exp` checks, configurable scope claims, and a `claims_to_identity` hook.
 - **Security scopes**: `Security(auth, scopes=[...])` forwards the declared scopes to validators that accept a `scopes` parameter.

{fastapi_multiauth-0.4.0 → fastapi_multiauth-0.5.0}/README.md

@@ -81,6 +81,7 @@ async def me(user=Security(auth)):
     - **`APIKeyCookieAuth`**: cookie sessions with optional HMAC-SHA256 signing (via [itsdangerous](https://itsdangerous.palletsprojects.com/)), embedded expiry, key rotation, and optional per-session ids so your app can list and revoke sessions individually.
     - **`APIKeyHeaderAuth`**: `X-API-Key`-style schemes, with **`APIKeyQueryAuth`** for legacy clients that can only pass a query parameter.
     - **`HTTPBasicAuth`**: `validator(username, password)` with `WWW-Authenticate` realm support.
+    - **`OAuth2AuthorizationCodeBearerAuth`**, **`OAuth2PasswordBearerAuth`**, **`OpenIdConnectAuth`**: validate tokens an OAuth 2.0 / OIDC provider issued, and publish the scope catalogue so `/docs` offers a real Authorize dialog.
 - **Token hashing helpers**: `hash_token`/`verify_token_hash` package the "store the hash, never the token" pattern with constant-time comparison.
 - **JWT validation** (`fastapi-multiauth[jwt]` extra): `JWTValidator` for `HTTPBearerAuth`: HS256 or provider JWKS (Keycloak/Auth0/Entra/Authentik) with TTL caching and rotation-aware `kid` refresh, `aud`/`iss`/`exp` checks, configurable scope claims, and a `claims_to_identity` hook.
 - **Security scopes**: `Security(auth, scopes=[...])` forwards the declared scopes to validators that accept a `scopes` parameter.

{fastapi_multiauth-0.4.0 → fastapi_multiauth-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-multiauth"
-version = "0.4.0"
+version = "0.5.0"
 description = "Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes, correct OpenAPI by construction"
 readme = "README.md"
 license = "MIT"
@@ -36,7 +36,7 @@ classifiers = [
 dependencies = [
     "anyio>=3.7",
     "async-lru>=2.0",
-    "fastapi>=0.100.0",
+    "fastapi>=0.108.0",
     "httpx>=0.25.0",
     "itsdangerous>=2.1",
 ]

{fastapi_multiauth-0.4.0 → fastapi_multiauth-0.5.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-multiauth"
-version = "0.4.0"
+version = "0.5.0"
 description = "Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes, correct OpenAPI by construction"
 readme = "README.md"
 license = "MIT"
@@ -31,7 +31,7 @@ classifiers = [
 dependencies = [
     "anyio>=3.7",
     "async-lru>=2.0",
-    "fastapi>=0.100.0",
+    "fastapi>=0.108.0",
     "httpx>=0.25.0",
     "itsdangerous>=2.1",
 ]

{fastapi_multiauth-0.4.0 → fastapi_multiauth-0.5.0}/src/fastapi_multiauth/__init__.py

@@ -20,10 +20,13 @@ from .sources import (
     HTTPBasicAuth,
     HTTPBearerAuth,
     MultiAuth,
+    OAuth2AuthorizationCodeBearerAuth,
+    OAuth2PasswordBearerAuth,
+    OpenIdConnectAuth,
 )
 from .utils import hash_token, verify_token_hash
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 __all__ = [
     "APIKeyCookieAuth",
@@ -35,6 +38,9 @@ __all__ = [
     "HTTPBearerAuth",
     "JWTValidator",
     "MultiAuth",
+    "OAuth2AuthorizationCodeBearerAuth",
+    "OAuth2PasswordBearerAuth",
+    "OpenIdConnectAuth",
     "UnauthorizedError",
     "hash_token",
     "oauth",

{fastapi_multiauth-0.4.0 → fastapi_multiauth-0.5.0}/src/fastapi_multiauth/abc.py

@@ -4,9 +4,9 @@ import copy
 import inspect
 from abc import ABC, abstractmethod
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Annotated, Any
+from typing import TYPE_CHECKING, Any
 
-from fastapi import Depends, HTTPException, Request
+from fastapi import HTTPException, Request
 from fastapi.security import SecurityScopes
 from fastapi.security.base import SecurityBase
 
@@ -46,14 +46,45 @@ def _accepts_kwarg(fn: Callable[..., Any], name: str) -> bool:
     )
 
 
-def _unenforceable_scopes_error(owner: object, scopes: list[str]) -> RuntimeError:
-    """Error for scopes declared on a route that this source cannot check."""
+def _unenforceable_scopes_error(
+    owner: object, scopes: list[str], reason: str | None = None
+) -> RuntimeError:
+    """Error for scopes declared on a route that this source cannot check.
+
+    Args:
+        owner: The source (or combination) refusing the route.
+        scopes: The scopes the route declared.
+        reason: Why they cannot be checked, when it is not simply that this
+            source's own validator does not accept them.
+    """
+    why = reason or "its validator does not declare a 'scopes' parameter"
     return RuntimeError(
         f"{type(owner).__name__} cannot enforce the security scopes "
-        f"{scopes!r} declared on this route: its validator does not "
-        "declare a 'scopes' parameter. Add one to the validator (or "
-        "override authenticate_scoped()), or remove scopes=... from "
-        "Security()."
+        f"{scopes!r} declared on this route: {why}. "
+        "Add one to the validator (or override authenticate_scoped()), "
+        "or remove scopes=... from Security()."
+    )
+
+
+def _anonymous_scopes_error(owner: object, scopes: list[str]) -> RuntimeError:
+    """Error for scopes declared on a route that also allows anonymous callers."""
+    return RuntimeError(
+        f"{type(owner).__name__} is optional() but this route declares the "
+        f"security scopes {scopes!r}: an anonymous caller can never satisfy "
+        "them, so the route would be gated or not depending on whether a "
+        "credential was sent. Drop optional() or drop scopes=... from Security()."
+    )
+
+
+def _undeclared_scopes_error(
+    owner: object, unknown: list[str], catalogue: dict[str, str]
+) -> RuntimeError:
+    """Error for route scopes missing from the source's published catalogue."""
+    known = ", ".join(sorted(catalogue)) or "nothing"
+    return RuntimeError(
+        f"{type(owner).__name__} does not publish the security scopes "
+        f"{unknown!r} declared on this route: its catalogue lists {known}. "
+        "Add them to scopes={...} on the source, or correct the route."
     )
 
 
@@ -72,6 +103,24 @@ class _DocOnlyScheme(SecurityBase):
         return None
 
 
+_SCHEME_CLASSES: dict[type, type] = {}
+
+
+def _carry_scheme(dependency: Any, scheme: SecurityBase) -> None:
+    """Make *dependency* itself the security scheme FastAPI puts in OpenAPI."""
+    cls = type(dependency)
+    promoted = _SCHEME_CLASSES.get(cls)
+    if promoted is None:
+        promoted = _SCHEME_CLASSES[cls] = type(
+            cls.__name__,
+            (cls, SecurityBase),
+            {"__module__": cls.__module__, "__doc__": cls.__doc__},
+        )
+    dependency.__class__ = promoted
+    dependency.model = scheme.model
+    dependency.scheme_name = scheme.scheme_name
+
+
 class AuthSource(ABC):
     """Abstract base class for authentication sources.
 
@@ -81,6 +130,9 @@ class AuthSource(ABC):
     """
 
     scheme: SecurityBase | None
+    _optional: bool = False
+    _scope_catalogue: dict[str, str] | None = None
+    """The scopes this source publishes to OpenAPI, ``None`` when it has none."""
 
     def __init__(self, scheme: Any = None) -> None:
         """Set up the FastAPI dependency signature.
@@ -90,6 +142,8 @@ class AuthSource(ABC):
                 metadata is used, extraction always goes through :meth:`extract`.
         """
         self.scheme = _DocOnlyScheme(scheme) if scheme is not None else None
+        if self.scheme is not None:
+            _carry_scheme(self, self.scheme)
 
         parameters = [
             inspect.Parameter(
@@ -103,17 +157,6 @@ class AuthSource(ABC):
                 annotation=SecurityScopes,
             ),
         ]
-        if self.scheme is not None:
-            # Declared only so the scheme is registered in OpenAPI; the
-            # extracted value is ignored in favor of extract().
-            parameters.append(
-                inspect.Parameter(
-                    "credentials",
-                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
-                    annotation=Annotated[Any, Depends(self.scheme)],
-                    default=None,
-                )
-            )
         self.__signature__ = inspect.Signature(parameters, return_annotation=Any)
 
     @abstractmethod
@@ -141,6 +184,10 @@ class AuthSource(ABC):
             raise _unenforceable_scopes_error(self, scopes)
         return await self.authenticate(credential)
 
+    def _enforces_scopes(self) -> bool:
+        """Whether route-declared scopes reach an actual check in this source."""
+        return type(self).authenticate_scoped is not AuthSource.authenticate_scoped
+
     async def _authenticate_with_challenge(
         self, credential: str, scopes: list[str]
     ) -> Any:
@@ -151,15 +198,40 @@ class AuthSource(ABC):
             add_challenge(exc, self.www_authenticate())
             raise
 
+    def optional(self) -> "Self":
+        """Return a copy that yields ``None`` instead of 401 when no credential is sent."""
+        clone = copy.copy(self)
+        clone._optional = True
+        return clone
+
+    def _reject_undeclared_scopes(self, scopes: list[str]) -> None:
+        """Refuse a route declaring scopes this source never published."""
+        catalogue = self._scope_catalogue
+        if not catalogue:
+            return
+        unknown = [scope for scope in scopes if scope not in catalogue]
+        if unknown:
+            raise _undeclared_scopes_error(self, unknown, catalogue)
+
     async def dispatch(self, request: Request, scopes: list[str]) -> Any:
         """Extract the credential, then authenticate it with the route scopes.
 
+        Returns ``None`` for an absent credential when :meth:`optional` was used.
+
         Raises:
             UnauthorizedError: When no credential is present. This source's
                 ``WWW-Authenticate`` challenge is attached to any 401 raised.
+            RuntimeError: When an :meth:`optional` copy meets a route that
+                declares scopes, which an anonymous caller could never satisfy.
         """
+        if scopes:
+            if self._optional:
+                raise _anonymous_scopes_error(self, scopes)
+            self._reject_undeclared_scopes(scopes)
         credential = await self.extract(request)
         if credential is None:
+            if self._optional:
+                return None
             raise UnauthorizedError(headers=challenge_headers(self.www_authenticate()))
         return await self._authenticate_with_challenge(credential, scopes)
 
@@ -215,6 +287,10 @@ class ValidatedAuthSource(AuthSource):
         """Validate a credential, forwarding route-declared scopes to the validator."""
         return await self._call_validator(credential, scopes=scopes)
 
+    def _enforces_scopes(self) -> bool:
+        """The validator is the authority: every source funnels into it."""
+        return self._accepts_scopes
+
     def require(self, **kwargs: Any) -> "Self":
         """Return a copy of this source with additional (or overriding) validator kwargs.
 

{fastapi_multiauth-0.4.0 → fastapi_multiauth-0.5.0}/src/fastapi_multiauth/jwt.py

@@ -256,5 +256,10 @@ class JWTValidator:
                 # provider's JWKS must not take down every login.
                 continue
             keys[entry.get("kid") or ""] = key
+        if not keys:
+            raise _JWKSFetchError(
+                f"JWKS document has no usable signing key "
+                f"({len(document['keys'])} entries)"
+            )
         self._keys = keys
         self._fetched_at = time.monotonic()

{fastapi_multiauth-0.4.0 → fastapi_multiauth-0.5.0}/src/fastapi_multiauth/oauth/client.py

@@ -3,6 +3,7 @@
 import contextlib
 import functools
 from typing import Any, Literal, NamedTuple
+from urllib.parse import urlsplit
 
 import httpx
 from async_lru import alru_cache
@@ -41,13 +42,25 @@ class OIDCEndpoints(NamedTuple):
 
 def _validate_issuer(discovery_url: str, issuer: Any) -> None:
     """Check the discovery document claims the issuer it was fetched from."""
-    if not discovery_url.endswith(_DISCOVERY_SUFFIX):
-        return
-    expected = discovery_url.removesuffix(_DISCOVERY_SUFFIX).rstrip("/")
-    if not isinstance(issuer, str) or issuer.rstrip("/") != expected:
+    if not isinstance(issuer, str) or not issuer:
         raise OAuthDiscoveryError(
-            f"discovery document issuer {issuer!r} does not match the "
-            f"expected issuer {expected!r} derived from the discovery URL"
+            f"discovery document has no usable 'issuer' (got {issuer!r})"
+        )
+    claimed = issuer.rstrip("/")
+    parts = urlsplit(discovery_url)
+    origin = f"{parts.scheme}://{parts.netloc}"
+    path = parts.path.rstrip("/")
+    if path.endswith(_DISCOVERY_SUFFIX):
+        expected = (origin + path.removesuffix(_DISCOVERY_SUFFIX)).rstrip("/")
+        if claimed != expected:
+            raise OAuthDiscoveryError(
+                f"discovery document issuer {issuer!r} does not match the "
+                f"expected issuer {expected!r} derived from the discovery URL"
+            )
+    elif claimed != origin and not claimed.startswith(f"{origin}/"):
+        raise OAuthDiscoveryError(
+            f"discovery document issuer {issuer!r} is not served by "
+            f"{origin!r}, the origin the document was fetched from"
         )
 
 

{fastapi_multiauth-0.4.0 → fastapi_multiauth-0.5.0}/src/fastapi_multiauth/sources/__init__.py

@@ -5,6 +5,11 @@ from .bearer import HTTPBearerAuth
 from .cookie import APIKeyCookieAuth
 from .header import APIKeyHeaderAuth
 from .multi import MultiAuth
+from .oauth2 import (
+    OAuth2AuthorizationCodeBearerAuth,
+    OAuth2PasswordBearerAuth,
+    OpenIdConnectAuth,
+)
 from .query import APIKeyQueryAuth
 
 __all__ = [
@@ -14,4 +19,7 @@ __all__ = [
     "HTTPBasicAuth",
     "HTTPBearerAuth",
     "MultiAuth",
+    "OAuth2AuthorizationCodeBearerAuth",
+    "OAuth2PasswordBearerAuth",
+    "OpenIdConnectAuth",
 ]

{fastapi_multiauth-0.4.0 → fastapi_multiauth-0.5.0}/src/fastapi_multiauth/sources/basic.py

@@ -13,6 +13,20 @@ from ..abc import ValidatedAuthSource
 from ..utils import authorization_credential
 
 
+def _basic_challenge(realm: str | None) -> str:
+    """Build the ``WWW-Authenticate`` challenge, escaping *realm* (RFC 7230 §3.2.6)."""
+    if realm is None:
+        return "Basic"
+    if not (realm.isascii() and realm.isprintable()):
+        raise ValueError(
+            f"realm must be printable US-ASCII (RFC 7617 §2.1), got {realm!r}: "
+            "control characters have no escaped form in a quoted-string, and "
+            "non-ASCII cannot be carried in a header value"
+        )
+    escaped = realm.replace("\\", "\\\\").replace('"', '\\"')
+    return f'Basic realm="{escaped}"'
+
+
 class HTTPBasicAuth(ValidatedAuthSource):
     """HTTP Basic authentication source (wraps ``HTTPBasic`` for OpenAPI, RFC 7617).
 
@@ -23,8 +37,9 @@ class HTTPBasicAuth(ValidatedAuthSource):
         validator: Sync or async callable receiving ``(username, password)`` and
             returning the identity; raises
             :class:`~fastapi_multiauth.exceptions.UnauthorizedError` on failure.
-        realm: Optional protection-space name for the ``WWW-Authenticate`` challenge.
+        realm: Optional protection-space name for the ``WWW-Authenticate``.
         scheme_name: OpenAPI security scheme name (default ``HTTPBasic``).
+        description: Optional prose for the OpenAPI security scheme object.
         **kwargs: Extra keyword arguments forwarded to the validator on every call.
     """
 
@@ -34,20 +49,23 @@ class HTTPBasicAuth(ValidatedAuthSource):
         *,
         realm: str | None = None,
         scheme_name: str | None = None,
+        description: str | None = None,
         **kwargs: Any,
     ) -> None:
-        self._realm = realm
+        self._challenge = _basic_challenge(realm)
         super().__init__(
             validator,
-            HTTPBasic(auto_error=False, scheme_name=scheme_name),
+            HTTPBasic(
+                auto_error=False,
+                scheme_name=scheme_name,
+                description=description,
+            ),
             **kwargs,
         )
 
     def www_authenticate(self) -> str:
         """``Basic`` challenge, with the realm when configured (RFC 7617 §2)."""
-        if self._realm is not None:
-            return f'Basic realm="{self._realm}"'
-        return "Basic"
+        return self._challenge
 
     async def extract(self, request: Request) -> str | None:
         """Return the base64 credentials blob, or ``None`` when absent or empty.

{fastapi_multiauth-0.4.0 → fastapi_multiauth-0.5.0}/src/fastapi_multiauth/sources/bearer.py

@@ -1,4 +1,4 @@
-"""Bearer token authentication source."""
+"""Bearer token authentication sources."""
 
 import secrets
 from collections.abc import Callable
@@ -13,7 +13,36 @@ from ..abc import ValidatedAuthSource
 from ..utils import authorization_credential
 
 
-class HTTPBearerAuth(ValidatedAuthSource):
+class _BearerSource(ValidatedAuthSource):
+    """Extraction shared by every source carrying an ``Authorization: Bearer`` token."""
+
+    _prefix: str | None = None
+
+    def www_authenticate(self) -> str:
+        """``Bearer`` challenge per RFC 6750 §3."""
+        return "Bearer"
+
+    async def extract(self, request: Request) -> str | None:
+        """Return the bearer token, or ``None`` when absent, empty, or mismatched.
+
+        The ``Bearer`` scheme is matched case-insensitively; the prefix, when
+        configured, is kept in the returned value.
+        """
+        token = authorization_credential(request, "bearer")
+        if token is None:
+            return None
+        if self._prefix is not None and not token.startswith(self._prefix):
+            return None
+        return token
+
+    async def authenticate_scoped(self, credential: str, scopes: list[str]) -> Any:
+        """Validate the credential, re-checking the prefix and forwarding scopes."""
+        if self._prefix is not None and not credential.startswith(self._prefix):
+            raise UnauthorizedError()
+        return await self._call_validator(credential, scopes=scopes)
+
+
+class HTTPBearerAuth(_BearerSource):
     """Bearer token authentication source (wraps ``HTTPBearer`` for OpenAPI).
 
     The validator is called as ``await validator(credential, **kwargs)``.
@@ -25,6 +54,9 @@ class HTTPBearerAuth(ValidatedAuthSource):
             prefix are matched, and the prefix is kept in the validated value.
         scheme_name: OpenAPI security scheme name (default ``HTTPBearer``); give
             each source a distinct name when several appear in the same app.
+        description: Optional prose for the OpenAPI security scheme object.
+        bearer_format: Optional hint at the token format (e.g. ``"JWT"``), for
+            documentation only.
         **kwargs: Extra keyword arguments forwarded to the validator on every call.
     """
 
@@ -34,38 +66,22 @@ class HTTPBearerAuth(ValidatedAuthSource):
         *,
         prefix: str | None = None,
         scheme_name: str | None = None,
+        description: str | None = None,
+        bearer_format: str | None = None,
         **kwargs: Any,
     ) -> None:
         self._prefix = prefix
         super().__init__(
             validator,
-            HTTPBearer(auto_error=False, scheme_name=scheme_name),
+            HTTPBearer(
+                auto_error=False,
+                scheme_name=scheme_name,
+                description=description,
+                bearerFormat=bearer_format,
+            ),
             **kwargs,
         )
 
-    def www_authenticate(self) -> str:
-        """``Bearer`` challenge per RFC 6750 §3."""
-        return "Bearer"
-
-    async def extract(self, request: Request) -> str | None:
-        """Return the bearer token, or ``None`` when absent, empty, or mismatched.
-
-        The ``Bearer`` scheme is matched case-insensitively; the prefix, when
-        configured, is kept in the returned value.
-        """
-        token = authorization_credential(request, "bearer")
-        if token is None:
-            return None
-        if self._prefix is not None and not token.startswith(self._prefix):
-            return None
-        return token
-
-    async def authenticate_scoped(self, credential: str, scopes: list[str]) -> Any:
-        """Validate the credential, re-checking the prefix and forwarding scopes."""
-        if self._prefix is not None and not credential.startswith(self._prefix):
-            raise UnauthorizedError()
-        return await self._call_validator(credential, scopes=scopes)
-
     def generate_token(self, nbytes: int = 32) -> str:
         """Generate a secure URL-safe random token, prefixed when configured.
 

{fastapi_multiauth-0.4.0 → fastapi_multiauth-0.5.0}/src/fastapi_multiauth/sources/cookie.py

@@ -36,6 +36,16 @@ def _normalize_secret_keys(secret_key: str | Sequence[str] | None) -> list[str]:
     return keys
 
 
+def _precomputed_signer(keys: list[str], salt: str) -> TimestampSigner:
+    """A ``TimestampSigner`` deriving its keys once here instead of per ``unsign``."""
+    probe = TimestampSigner(keys, salt=salt, digest_method=hashlib.sha256)
+    return TimestampSigner(
+        [probe.derive_key(key) for key in keys],
+        digest_method=hashlib.sha256,
+        key_derivation="none",
+    )
+
+
 class APIKeyCookieAuth(ValidatedAuthSource):
     """Cookie-based authentication source (wraps ``APIKeyCookie`` for OpenAPI).
 
@@ -60,6 +70,7 @@ class APIKeyCookieAuth(ValidatedAuthSource):
         domain: Optional ``Domain`` cookie attribute.
         path: ``Path`` cookie attribute (default ``"/"``).
         scheme_name: OpenAPI security scheme name (default ``APIKeyCookie_{name}``).
+        description: Optional prose for the OpenAPI security scheme object.
         **kwargs: Extra keyword arguments forwarded to the validator on every call.
     """
 
@@ -76,6 +87,7 @@ class APIKeyCookieAuth(ValidatedAuthSource):
         domain: str | None = None,
         path: str = "/",
         scheme_name: str | None = None,
+        description: str | None = None,
         **kwargs: Any,
     ) -> None:
         if ttl <= 0:
@@ -98,10 +110,9 @@ class APIKeyCookieAuth(ValidatedAuthSource):
         # the last one — reverse so the first configured key is the signer.
         # The salt also separates the two payload layouts.
         self._signer = (
-            TimestampSigner(
+            _precomputed_signer(
                 list(reversed(self._secret_keys)),
-                salt=f"{_SALT_PREFIX}{name}{'.sid' if session_id else ''}",
-                digest_method=hashlib.sha256,
+                f"{_SALT_PREFIX}{name}{'.sid' if session_id else ''}",
             )
             if self._secret_keys
             else None
@@ -117,6 +128,7 @@ class APIKeyCookieAuth(ValidatedAuthSource):
                 name=name,
                 auto_error=False,
                 scheme_name=scheme_name or f"APIKeyCookie_{name}",
+                description=description,
             ),
             **kwargs,
         )

{fastapi_multiauth-0.4.0 → fastapi_multiauth-0.5.0}/src/fastapi_multiauth/sources/header.py

@@ -19,6 +19,7 @@ class APIKeyHeaderAuth(ValidatedAuthSource):
         validator: Sync or async callable returning the identity; raises
             :class:`~fastapi_multiauth.exceptions.UnauthorizedError` on failure.
         scheme_name: OpenAPI security scheme name (default ``APIKeyHeader_{name}``).
+        description: Optional prose for the OpenAPI security scheme object.
         **kwargs: Extra keyword arguments forwarded to the validator on every call.
     """
 
@@ -28,6 +29,7 @@ class APIKeyHeaderAuth(ValidatedAuthSource):
         validator: Callable[..., Any],
         *,
         scheme_name: str | None = None,
+        description: str | None = None,
         **kwargs: Any,
     ) -> None:
         self._name = name
@@ -37,6 +39,7 @@ class APIKeyHeaderAuth(ValidatedAuthSource):
                 name=name,
                 auto_error=False,
                 scheme_name=scheme_name or f"APIKeyHeader_{name}",
+                description=description,
             ),
             **kwargs,
         )

{fastapi_multiauth-0.4.0 → fastapi_multiauth-0.5.0}/src/fastapi_multiauth/sources/multi.py

@@ -1,14 +1,20 @@
 """MultiAuth: combine multiple authentication sources into a single callable."""
 
+import copy
 import inspect
-from typing import Any, cast
+from typing import Annotated, Any, cast
 
-from fastapi import Request
+from fastapi import Depends, Request
 from fastapi.security import SecurityScopes
 
 from fastapi_multiauth.exceptions import UnauthorizedError
 
-from ..abc import AuthSource
+from ..abc import (
+    AuthSource,
+    _anonymous_scopes_error,
+    _carry_scheme,
+    _unenforceable_scopes_error,
+)
 from ..utils import challenge_headers
 
 
@@ -25,6 +31,8 @@ class MultiAuth:
         TypeError: If a source is not an :class:`AuthSource` instance.
     """
 
+    _optional: bool = False
+
     def __init__(self, *sources: AuthSource) -> None:
         for source in sources:
             if not isinstance(source, AuthSource):
@@ -39,10 +47,6 @@ class MultiAuth:
                 )
         self._sources = sources
 
-        # Build a merged signature that includes the security-scheme Depends()
-        # parameters from every source so FastAPI registers them in OpenAPI
-        # docs. Parameters are renamed `_s{i}_{name}` — unique per source
-        # index — so two sources of the same type both keep their scheme.
         merged: list[inspect.Parameter] = [
             inspect.Parameter(
                 "request",
@@ -55,11 +59,20 @@ class MultiAuth:
                 annotation=SecurityScopes,
             ),
         ]
+        carried = sources[0].scheme if sources else None
+        if carried is not None:
+            _carry_scheme(self, carried)
         for i, source in enumerate(sources):
-            for name, param in inspect.signature(source).parameters.items():
-                if name in ("request", "security_scopes"):
-                    continue
-                merged.append(param.replace(name=f"_s{i}_{name}"))
+            if source.scheme is None or (i == 0 and carried is not None):
+                continue
+            merged.append(
+                inspect.Parameter(
+                    f"_s{i}_credentials",
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=Annotated[Any, Depends(cast(Any, source.scheme))],
+                    default=None,
+                )
+            )
         self.__signature__ = inspect.Signature(merged, return_annotation=Any)
 
         # The combined challenge is fixed once the sources are known; build it
@@ -71,16 +84,44 @@ class MultiAuth:
                 challenges.append(challenge)
         self._www_authenticate = ", ".join(challenges) or None
 
+        self._unenforceable = tuple(
+            type(source).__name__ for source in sources if not source._enforces_scopes()
+        )
+        self._catalogued = tuple(
+            source for source in sources if source._scope_catalogue
+        )
+
     def www_authenticate(self) -> str | None:
         """Combined challenge of all sources (RFC 9110 §11.6.1), or ``None``."""
         return self._www_authenticate
 
+    def optional(self) -> "MultiAuth":
+        """Return a copy that yields ``None`` when no source has a credential."""
+        clone = copy.copy(self)
+        clone._optional = True
+        return clone
+
     async def dispatch(self, request: Request, scopes: list[str]) -> Any:
         """Authenticate with the first source whose credential is present."""
+        if scopes:
+            if self._optional:
+                raise _anonymous_scopes_error(self, scopes)
+            for source in self._catalogued:
+                source._reject_undeclared_scopes(scopes)
+            if self._unenforceable:
+                raise _unenforceable_scopes_error(
+                    self,
+                    scopes,
+                    f"{', '.join(self._unenforceable)} cannot check them, so "
+                    "enforcement would depend on which credential the client "
+                    "presents",
+                )
         for source in self._sources:
             credential = await source.extract(request)
             if credential is not None:
                 return await source._authenticate_with_challenge(credential, scopes)
+        if self._optional:
+            return None
         raise UnauthorizedError(headers=challenge_headers(self.www_authenticate()))
 
     async def __call__(self, **kwargs: Any) -> Any:
@@ -94,4 +135,6 @@ class MultiAuth:
             else source
             for source in self._sources
         )
-        return MultiAuth(*new_sources)
+        clone = MultiAuth(*new_sources)
+        clone._optional = self._optional
+        return clone

fastapi_multiauth-0.5.0/src/fastapi_multiauth/sources/oauth2.py

@@ -0,0 +1,129 @@
+"""OAuth 2.0 and OpenID Connect authentication sources.
+
+These validate the bearer token an OAuth 2.0 or OIDC provider already issued.
+They declare no flow of their own: the URLs and scope catalogue they carry are
+OpenAPI metadata, which is what lets ``/docs`` offer a real Authorize dialog
+with per-scope checkboxes. The login flow that mints those tokens lives in
+:mod:`fastapi_multiauth.oauth`.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi.security import (
+    OAuth2AuthorizationCodeBearer,
+    OAuth2PasswordBearer,
+    OpenIdConnect,
+)
+
+from .bearer import _BearerSource
+
+
+class OAuth2PasswordBearerAuth(_BearerSource):
+    """Bearer tokens issued by a password-grant token endpoint.
+
+    Args:
+        validator: Sync or async callable returning the identity.
+        token_url: URL of the token endpoint, as advertised to OpenAPI.
+        scopes: Catalogue of scope names mapped to their descriptions.
+        scheme_name: OpenAPI security scheme name.
+        description: Optional prose for the OpenAPI security scheme object.
+        **kwargs: Extra keyword arguments forwarded to the validator.
+    """
+
+    def __init__(
+        self,
+        validator: Callable[..., Any],
+        *,
+        token_url: str,
+        scopes: dict[str, str] | None = None,
+        scheme_name: str | None = None,
+        description: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._scope_catalogue = scopes
+        super().__init__(
+            validator,
+            OAuth2PasswordBearer(
+                tokenUrl=token_url,
+                scopes=scopes,
+                scheme_name=scheme_name,
+                description=description,
+                auto_error=False,
+            ),
+            **kwargs,
+        )
+
+
+class OAuth2AuthorizationCodeBearerAuth(_BearerSource):
+    """Bearer tokens issued by an authorization-code flow.
+
+    Args:
+        validator: Sync or async callable returning the identity.
+        authorization_url: URL the Authorize dialog sends the user to.
+        token_url: URL that exchanges the code for a token.
+        refresh_url: Optional refresh endpoint.
+        scopes: Catalogue of scope names mapped to their descriptions.
+        scheme_name: OpenAPI security scheme name.
+        description: Optional prose for the OpenAPI security scheme object.
+        **kwargs: Extra keyword arguments forwarded to the validator.
+    """
+
+    def __init__(
+        self,
+        validator: Callable[..., Any],
+        *,
+        authorization_url: str,
+        token_url: str,
+        refresh_url: str | None = None,
+        scopes: dict[str, str] | None = None,
+        scheme_name: str | None = None,
+        description: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._scope_catalogue = scopes
+        super().__init__(
+            validator,
+            OAuth2AuthorizationCodeBearer(
+                authorizationUrl=authorization_url,
+                tokenUrl=token_url,
+                refreshUrl=refresh_url,
+                scopes=scopes,
+                scheme_name=scheme_name,
+                description=description,
+                auto_error=False,
+            ),
+            **kwargs,
+        )
+
+
+class OpenIdConnectAuth(_BearerSource):
+    """Bearer tokens issued by an OpenID Connect provider.
+
+    Args:
+        validator: Sync or async callable returning the identity.
+        openid_connect_url: The provider's ``.well-known`` discovery URL.
+        scheme_name: OpenAPI security scheme name.
+        description: Optional prose for the OpenAPI security scheme object.
+        **kwargs: Extra keyword arguments forwarded to the validator.
+    """
+
+    def __init__(
+        self,
+        validator: Callable[..., Any],
+        *,
+        openid_connect_url: str,
+        scheme_name: str | None = None,
+        description: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            validator,
+            OpenIdConnect(
+                openIdConnectUrl=openid_connect_url,
+                scheme_name=scheme_name,
+                description=description,
+                auto_error=False,
+            ),
+            **kwargs,
+        )

{fastapi_multiauth-0.4.0 → fastapi_multiauth-0.5.0}/src/fastapi_multiauth/sources/query.py

@@ -24,6 +24,7 @@ class APIKeyQueryAuth(ValidatedAuthSource):
         validator: Sync or async callable returning the identity; raises
             :class:`~fastapi_multiauth.exceptions.UnauthorizedError` on failure.
         scheme_name: OpenAPI security scheme name (default ``APIKeyQuery_{name}``).
+        description: Optional prose for the OpenAPI security scheme object.
         **kwargs: Extra keyword arguments forwarded to the validator on every call.
     """
 
@@ -33,6 +34,7 @@ class APIKeyQueryAuth(ValidatedAuthSource):
         validator: Callable[..., Any],
         *,
         scheme_name: str | None = None,
+        description: str | None = None,
         **kwargs: Any,
     ) -> None:
         self._name = name
@@ -42,6 +44,7 @@ class APIKeyQueryAuth(ValidatedAuthSource):
                 name=name,
                 auto_error=False,
                 scheme_name=scheme_name or f"APIKeyQuery_{name}",
+                description=description,
             ),
             **kwargs,
         )