fastapi-multiauth 0.6.0__tar.gz → 0.7.0__tar.gz

{fastapi_multiauth-0.6.0 → fastapi_multiauth-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-multiauth
-Version: 0.6.0
+Version: 0.7.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
@@ -13,11 +13,11 @@ Classifier: Framework :: FastAPI
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Internet :: WWW/HTTP :: Session
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -25,12 +25,12 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Dist: anyio>=3.7
 Requires-Dist: async-lru>=2.0
-Requires-Dist: fastapi>=0.123.0
+Requires-Dist: fastapi>=0.123.0,!=0.137.0,!=0.137.1
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: itsdangerous>=2.1
 Requires-Dist: pyjwt[crypto]>=2.13.0 ; extra == 'jwt'
 Requires-Dist: httpx-oauth>=0.16 ; extra == 'oauth'
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Project-URL: Homepage, https://github.com/d3vyce/fastapi-multiauth
 Project-URL: Documentation, https://fastapi-multiauth.d3vyce.fr/
 Project-URL: Repository, https://github.com/d3vyce/fastapi-multiauth
@@ -49,7 +49,7 @@ Composable authentication sources for FastAPI: bring your own validator, combine
 [![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
 [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
-[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
@@ -126,6 +126,8 @@ async def me(user=Security(auth)):
 - **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.
+- **WebSocket routes**: every source and `MultiAuth` guard `@app.websocket` routes too, refusing the handshake with the same 401/403.
+- **Freshness / step-up auth**: `source.fresh(max_age=...)` refuses a credential proven too long ago on the endpoints that can take over an account, with the [RFC 9470](https://datatracker.ietf.org/doc/html/rfc9470) challenge that tells a client to re-authenticate. Signed cookies date themselves; anything else reads the instant off your identity.
 - **Correct HTTP semantics**: 401 with `WWW-Authenticate` challenges ([RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)) and 403 via `ForbiddenError`.
 - **OAuth 2.0 / OIDC helpers** (`fastapi-multiauth[oauth]` extra): async discovery with TTL caching, HTTPS enforcement, CSRF-protected `state` encoding, PKCE (S256), and code exchange delegated to [httpx-oauth](https://github.com/frankie567/httpx-oauth).
 

{fastapi_multiauth-0.6.0 → fastapi_multiauth-0.7.0}/README.md

@@ -8,7 +8,7 @@ Composable authentication sources for FastAPI: bring your own validator, combine
 [![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
 [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
-[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
@@ -85,6 +85,8 @@ async def me(user=Security(auth)):
 - **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.
+- **WebSocket routes**: every source and `MultiAuth` guard `@app.websocket` routes too, refusing the handshake with the same 401/403.
+- **Freshness / step-up auth**: `source.fresh(max_age=...)` refuses a credential proven too long ago on the endpoints that can take over an account, with the [RFC 9470](https://datatracker.ietf.org/doc/html/rfc9470) challenge that tells a client to re-authenticate. Signed cookies date themselves; anything else reads the instant off your identity.
 - **Correct HTTP semantics**: 401 with `WWW-Authenticate` challenges ([RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)) and 403 via `ForbiddenError`.
 - **OAuth 2.0 / OIDC helpers** (`fastapi-multiauth[oauth]` extra): async discovery with TTL caching, HTTPS enforcement, CSRF-protected `state` encoding, PKCE (S256), and code exchange delegated to [httpx-oauth](https://github.com/frankie567/httpx-oauth).
 

{fastapi_multiauth-0.6.0 → fastapi_multiauth-0.7.0}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "fastapi-multiauth"
-version = "0.6.0"
+version = "0.7.0"
 description = "Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes, correct OpenAPI by construction"
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 keywords = [
     "fastapi",
     "authentication",
@@ -22,11 +22,11 @@ classifiers = [
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Topic :: Internet :: WWW/HTTP :: Session",
     "Topic :: Security",
     "Topic :: Software Development :: Libraries :: Python Modules",
@@ -36,7 +36,7 @@ classifiers = [
 dependencies = [
     "anyio>=3.7",
     "async-lru>=2.0",
-    "fastapi>=0.123.0",
+    "fastapi>=0.123.0,!=0.137.0,!=0.137.1",
     "httpx>=0.25.0",
     "itsdangerous>=2.1",
 ]
@@ -78,11 +78,14 @@ docs = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.11.21,<0.13.0"]
+requires = ["uv_build>=0.11.21,<0.14.0"]
 build-backend = "uv_build"
 
 [tool.ruff.lint]
-extend-select = ["S"]
+extend-select = [
+    "S",
+    "UP",
+]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = [

{fastapi_multiauth-0.6.0 → fastapi_multiauth-0.7.0}/pyproject.toml.orig

@@ -1,11 +1,11 @@
 [project]
 name = "fastapi-multiauth"
-version = "0.6.0"
+version = "0.7.0"
 description = "Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes, correct OpenAPI by construction"
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 authors = [
     { name = "d3vyce", email = "contact@d3vyce.fr" }
 ]
@@ -17,11 +17,11 @@ classifiers = [
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Topic :: Internet :: WWW/HTTP :: Session",
     "Topic :: Security",
     "Topic :: Software Development :: Libraries :: Python Modules",
@@ -31,7 +31,7 @@ classifiers = [
 dependencies = [
     "anyio>=3.7",
     "async-lru>=2.0",
-    "fastapi>=0.123.0",
+    "fastapi>=0.123.0,!=0.137.0,!=0.137.1",
     "httpx>=0.25.0",
     "itsdangerous>=2.1",
 ]
@@ -73,12 +73,12 @@ docs = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.11.21,<0.13.0"]
+requires = ["uv_build>=0.11.21,<0.14.0"]
 build-backend = "uv_build"
 
 [tool.ruff.lint]
 # "S" = flake8-bandit security rules, scoped to the library source.
-extend-select = ["S"]
+extend-select = ["S", "UP"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = ["S", "B008"]

{fastapi_multiauth-0.6.0 → fastapi_multiauth-0.7.0}/src/fastapi_multiauth/__init__.py

@@ -11,7 +11,7 @@ exported here, and require the ``oauth`` extra. Import them explicitly::
 
 from . import oauth
 from .abc import AuthSource
-from .exceptions import ForbiddenError, UnauthorizedError
+from .exceptions import ForbiddenError, StaleCredentialError, UnauthorizedError
 from .jwt import JWTValidator
 from .sources import (
     APIKeyCookieAuth,
@@ -27,7 +27,7 @@ from .sources import (
 from .surface import RouteAuth, SchemeRequirement, auth_surface
 from .utils import hash_token, verify_token_hash
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 
 __all__ = [
     "APIKeyCookieAuth",
@@ -44,6 +44,7 @@ __all__ = [
     "OpenIdConnectAuth",
     "RouteAuth",
     "SchemeRequirement",
+    "StaleCredentialError",
     "UnauthorizedError",
     "auth_surface",
     "hash_token",

{fastapi_multiauth-0.6.0 → fastapi_multiauth-0.7.0}/src/fastapi_multiauth/abc.py

@@ -2,20 +2,25 @@
 
 import copy
 import inspect
+import math
 from abc import ABC, abstractmethod
-from collections.abc import Callable, Mapping
-from typing import TYPE_CHECKING, Any
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, Self
 
-from fastapi import HTTPException, Request
+from fastapi import HTTPException
+from fastapi.requests import HTTPConnection
 from fastapi.security import SecurityScopes
 from fastapi.security.base import SecurityBase
 
-from fastapi_multiauth.exceptions import UnauthorizedError
-from fastapi_multiauth.utils import add_challenge, challenge_headers, ensure_async
-
-if TYPE_CHECKING:
-    from typing_extensions import Self
-
+from fastapi_multiauth.exceptions import StaleCredentialError, UnauthorizedError
+from fastapi_multiauth.utils import (
+    add_challenge,
+    challenge_headers,
+    credential_age,
+    ensure_async,
+    step_up_challenge,
+)
 
 _RESERVED_KWARGS = {
     "scopes": "injected from the route by Security(..., scopes=[...])",
@@ -101,6 +106,14 @@ def _anonymous_scopes_error(owner: object, scopes: list[str]) -> RuntimeError:
     )
 
 
+def _fresh_optional_error(owner: object) -> ValueError:
+    """Error for a dependency asking for both anonymous callers and freshness."""
+    return ValueError(
+        f"{type(owner).__name__} cannot be both optional() and fresh(): an "
+        "anonymous caller can never be fresh"
+    )
+
+
 def _undeclared_scopes_error(
     owner: object, unknown: list[str], catalogue: dict[str, str]
 ) -> RuntimeError:
@@ -124,7 +137,7 @@ class _DocOnlyScheme(SecurityBase):
         self.model = scheme.model
         self.scheme_name = scheme.scheme_name
 
-    async def __call__(self, request: Request) -> None:
+    async def __call__(self, request: HTTPConnection) -> None:
         return None
 
 
@@ -146,18 +159,30 @@ def _carry_scheme(dependency: Any, scheme: SecurityBase) -> None:
     dependency.scheme_name = scheme.scheme_name
 
 
+@dataclass(frozen=True, slots=True)
+class _Freshness:
+    """The window set by :meth:`AuthSource.fresh`."""
+
+    max_age: float
+    leeway: float
+    read: Callable[[Any], Awaitable[Any]] | None
+    """Caller-supplied reader of the instant, ``None`` to use the source's own."""
+
+
 class AuthSource(ABC):
     """Abstract base class for authentication sources.
 
     Subclasses implement :meth:`extract` and :meth:`authenticate`; both
     ``Security(source)`` and ``MultiAuth`` route through that pair via
-    :meth:`dispatch`.
+    :meth:`dispatch`. Optional hooks: :meth:`www_authenticate` for the 401
+    challenge, :meth:`authenticated_at` for :meth:`fresh`.
     """
 
     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."""
+    _freshness: _Freshness | None = None
 
     def __init__(self, scheme: Any = None) -> None:
         """Set up the FastAPI dependency signature.
@@ -177,7 +202,7 @@ class AuthSource(ABC):
             inspect.Parameter(
                 "request",
                 inspect.Parameter.POSITIONAL_OR_KEYWORD,
-                annotation=Request,
+                annotation=HTTPConnection,
             ),
             inspect.Parameter(
                 "security_scopes",
@@ -188,7 +213,7 @@ class AuthSource(ABC):
         self.__signature__ = inspect.Signature(parameters, return_annotation=Any)
 
     @abstractmethod
-    async def extract(self, request: Request) -> str | None:
+    async def extract(self, request: HTTPConnection) -> str | None:
         """Extract the raw credential from the request without validating.
 
         Must return ``None`` — never an empty string — when the credential is
@@ -207,7 +232,11 @@ class AuthSource(ABC):
         return None
 
     async def authenticate_scoped(
-        self, credential: str, scopes: list[str], *, request: Request | None = None
+        self,
+        credential: str,
+        scopes: list[str],
+        *,
+        request: HTTPConnection | None = None,
     ) -> Any:
         """Validate a credential, enforcing the scopes declared on the route.
 
@@ -226,7 +255,7 @@ class AuthSource(ABC):
         return type(self).authenticate_scoped is not AuthSource.authenticate_scoped
 
     async def _call_scoped(
-        self, credential: str, scopes: list[str], *, request: Request | None
+        self, credential: str, scopes: list[str], *, request: HTTPConnection | None
     ) -> Any:
         """Call :meth:`authenticate_scoped`, honouring overrides predating ``request``."""
         if self._scoped_takes_request:
@@ -234,21 +263,116 @@ class AuthSource(ABC):
         return await self.authenticate_scoped(credential, scopes)
 
     async def _authenticate_with_challenge(
-        self, credential: str, scopes: list[str], *, request: Request | None = None
+        self,
+        credential: str,
+        scopes: list[str],
+        *,
+        request: HTTPConnection | None = None,
     ) -> Any:
-        """Authenticate, attaching this source's challenge to any 401 raised."""
+        """Authenticate, attaching this source's challenge to any 401 raised.
+
+        Freshness is checked after the credential: an invalid one is refused as
+        invalid, not as stale.
+        """
         try:
-            return await self._call_scoped(credential, scopes, request=request)
+            identity = await self._call_scoped(credential, scopes, request=request)
         except HTTPException as exc:
             add_challenge(exc, self.www_authenticate())
             raise
+        await self._enforce_freshness(credential, identity)
+        return identity
 
-    def optional(self) -> "Self":
-        """Return a copy that yields ``None`` instead of 401 when no credential is sent."""
+    def optional(self) -> Self:
+        """Return a copy that yields ``None`` instead of 401 when no credential is sent.
+
+        Raises:
+            ValueError: On a :meth:`fresh` copy: anonymous is never fresh.
+        """
+        if self._freshness is not None:
+            raise _fresh_optional_error(self)
         clone = copy.copy(self)
         clone._optional = True
         return clone
 
+    def authenticated_at(self, credential: str) -> Any:
+        """When the factor behind *credential* was proven, for :meth:`fresh`.
+
+        Epoch seconds, a ``datetime``, or ``None`` when this source cannot date
+        the credential. Sources that can override this (a signed cookie carries
+        its mint time); the others pass ``authenticated_at=`` to :meth:`fresh`.
+        """
+        return None
+
+    def _dates_credentials(self) -> bool:
+        """Whether this source can date a credential without a caller's help."""
+        return type(self).authenticated_at is not AuthSource.authenticated_at
+
+    def fresh(
+        self,
+        max_age: float,
+        *,
+        authenticated_at: Callable[..., Any] | None = None,
+        leeway: float = 0.0,
+    ) -> Self:
+        """Return a copy that refuses a credential proven more than *max_age* ago.
+
+        Args:
+            max_age: Freshness window in seconds.
+            authenticated_at: Sync or async callable taking the identity and
+                returning the instant the caller proved a factor, as epoch
+                seconds or a ``datetime`` (naive read as UTC). Required when the
+                source cannot date its own credentials, and overrides
+                :meth:`authenticated_at`. ``None`` refuses the request.
+            leeway: Clock-skew tolerance in seconds, either way: an instant
+                further than *leeway* in the future is refused too.
+
+        Raises:
+            ValueError: Non-positive or non-finite *max_age*, negative or
+                non-finite *leeway*, an :meth:`optional` copy, a copy that
+                already has a window, or no way to date the credential.
+        """
+        if not math.isfinite(max_age) or max_age <= 0:
+            raise ValueError("max_age must be a positive, finite number of seconds")
+        if not math.isfinite(leeway) or leeway < 0:
+            raise ValueError("leeway must be a finite, non-negative number of seconds")
+        if self._optional:
+            raise _fresh_optional_error(self)
+        if self._freshness is not None:
+            raise ValueError(
+                f"{type(self).__name__} already has a freshness window: call "
+                "fresh() once, on the source or on the MultiAuth"
+            )
+        if authenticated_at is None and not self._dates_credentials():
+            raise ValueError(
+                f"{type(self).__name__} cannot date a credential: "
+                "fresh() needs authenticated_at=..."
+            )
+        clone = copy.copy(self)
+        clone._freshness = _Freshness(
+            max_age=max_age,
+            leeway=leeway,
+            read=ensure_async(authenticated_at) if authenticated_at else None,
+        )
+        return clone
+
+    async def _enforce_freshness(self, credential: str, identity: Any) -> None:
+        """Refuse an identity whose credential was proven outside the window."""
+        freshness = self._freshness
+        if freshness is None:
+            return
+        if freshness.read is not None:
+            instant = await freshness.read(identity)
+        else:
+            instant = self.authenticated_at(credential)
+        age = credential_age(instant)
+        if age is None or not (
+            -freshness.leeway <= age <= freshness.max_age + freshness.leeway
+        ):
+            raise StaleCredentialError(
+                headers=step_up_challenge(self.www_authenticate(), freshness.max_age),
+                max_age=freshness.max_age,
+            )
+
     def _reject_undeclared_scopes(self, scopes: list[str]) -> None:
         """Refuse a route declaring scopes this source never published."""
         catalogue = self._scope_catalogue
@@ -258,7 +382,7 @@ class AuthSource(ABC):
         if unknown:
             raise _undeclared_scopes_error(self, unknown, catalogue)
 
-    async def dispatch(self, request: Request, scopes: list[str]) -> Any:
+    async def dispatch(self, request: HTTPConnection, scopes: list[str]) -> Any:
         """Extract the credential, then authenticate it with the route scopes.
 
         Raises:
@@ -319,7 +443,7 @@ class ValidatedAuthSource(AuthSource):
         self,
         *args: Any,
         scopes: list[str],
-        request: Request | None = None,
+        request: HTTPConnection | None = None,
         **injected: Any,
     ) -> Any:
         """Invoke the validator with scope, request and configured kwargs forwarding."""
@@ -332,13 +456,17 @@ class ValidatedAuthSource(AuthSource):
         return await self._validator(*args, **self._kwargs, **injected)
 
     async def authenticate(
-        self, credential: str, *, request: Request | None = None
+        self, credential: str, *, request: HTTPConnection | None = None
     ) -> Any:
         """Validate a credential and return the identity (no route scopes)."""
         return await self._call_scoped(credential, [], request=request)
 
     async def authenticate_scoped(
-        self, credential: str, scopes: list[str], *, request: Request | None = None
+        self,
+        credential: str,
+        scopes: list[str],
+        *,
+        request: HTTPConnection | None = None,
     ) -> Any:
         """Validate a credential, forwarding route scopes and request to the validator."""
         return await self._call_validator(credential, scopes=scopes, request=request)
@@ -347,7 +475,7 @@ class ValidatedAuthSource(AuthSource):
         """The validator is the authority: every source funnels into it."""
         return self._accepts_scopes
 
-    def require(self, **kwargs: Any) -> "Self":
+    def require(self, **kwargs: Any) -> Self:
         """Return a copy of this source with additional (or overriding) validator kwargs.
 
         Reserved names (``scopes``, ``session_id``, ``request``) are rejected here too.

{fastapi_multiauth-0.6.0 → fastapi_multiauth-0.7.0}/src/fastapi_multiauth/exceptions.py

@@ -25,6 +25,37 @@ class UnauthorizedError(HTTPException):
         )
 
 
+class StaleCredentialError(UnauthorizedError):
+    """HTTP 401 — the credential is valid but was proven too long ago.
+
+    Raised by a route guarded with :meth:`~fastapi_multiauth.AuthSource.fresh`.
+    ``detail`` is the stable string ``"Insufficient user authentication"``, and
+    sources with an HTTP auth scheme carry the
+    `RFC 9470 <https://datatracker.ietf.org/doc/html/rfc9470>`_ step-up
+    challenge. A handler rendering its own body reads :attr:`max_age`.
+    """
+
+    max_age: float | None
+    """The freshness window the credential missed, in seconds."""
+
+    def __init__(
+        self,
+        detail: str = "Insufficient user authentication",
+        headers: dict[str, str] | None = None,
+        *,
+        max_age: float | None = None,
+    ) -> None:
+        """Initialize the exception.
+
+        Args:
+            detail: Human-readable message returned in the response body.
+            headers: Extra response headers (e.g. the step-up challenge).
+            max_age: The freshness window that was missed, in seconds.
+        """
+        self.max_age = max_age
+        super().__init__(detail=detail, headers=headers)
+
+
 class ForbiddenError(HTTPException):
     """HTTP 403 — the identity is authenticated but lacks permission.
 

{fastapi_multiauth-0.6.0 → fastapi_multiauth-0.7.0}/src/fastapi_multiauth/sources/basic.py

@@ -4,7 +4,7 @@ import base64
 from collections.abc import Callable
 from typing import Any
 
-from fastapi import Request
+from fastapi.requests import HTTPConnection
 from fastapi.security import HTTPBasic
 
 from fastapi_multiauth.exceptions import UnauthorizedError
@@ -67,7 +67,7 @@ class HTTPBasicAuth(ValidatedAuthSource):
         """``Basic`` challenge, with the realm when configured (RFC 7617 §2)."""
         return self._challenge
 
-    async def extract(self, request: Request) -> str | None:
+    async def extract(self, request: HTTPConnection) -> str | None:
         """Return the base64 credentials blob, or ``None`` when absent or empty.
 
         The ``Basic`` scheme is matched case-insensitively; decoding and the
@@ -76,7 +76,11 @@ class HTTPBasicAuth(ValidatedAuthSource):
         return authorization_credential(request, "basic")
 
     async def authenticate_scoped(
-        self, credential: str, scopes: list[str], *, request: Request | None = None
+        self,
+        credential: str,
+        scopes: list[str],
+        *,
+        request: HTTPConnection | None = None,
     ) -> Any:
         """Decode the blob, forwarding route-declared scopes to the validator."""
         try:

{fastapi_multiauth-0.6.0 → fastapi_multiauth-0.7.0}/src/fastapi_multiauth/sources/bearer.py

@@ -4,7 +4,7 @@ import secrets
 from collections.abc import Callable
 from typing import Any
 
-from fastapi import Request
+from fastapi.requests import HTTPConnection
 from fastapi.security import HTTPBearer
 
 from fastapi_multiauth.exceptions import UnauthorizedError
@@ -22,7 +22,7 @@ class _BearerSource(ValidatedAuthSource):
         """``Bearer`` challenge per RFC 6750 §3."""
         return "Bearer"
 
-    async def extract(self, request: Request) -> str | None:
+    async def extract(self, request: HTTPConnection) -> str | None:
         """Return the bearer token, or ``None`` when absent, empty, or mismatched.
 
         The ``Bearer`` scheme is matched case-insensitively; the prefix, when
@@ -36,7 +36,11 @@ class _BearerSource(ValidatedAuthSource):
         return token
 
     async def authenticate_scoped(
-        self, credential: str, scopes: list[str], *, request: Request | None = None
+        self,
+        credential: str,
+        scopes: list[str],
+        *,
+        request: HTTPConnection | None = None,
     ) -> Any:
         """Validate the credential, re-checking the prefix and forwarding scopes."""
         if self._prefix is not None and not credential.startswith(self._prefix):

{fastapi_multiauth-0.6.0 → fastapi_multiauth-0.7.0}/src/fastapi_multiauth/sources/cookie.py

@@ -5,7 +5,8 @@ import secrets
 from collections.abc import Callable, Sequence
 from typing import Any, Literal
 
-from fastapi import Request, Response
+from fastapi import Response
+from fastapi.requests import HTTPConnection
 from fastapi.security import APIKeyCookie
 from itsdangerous import BadSignature, TimestampSigner
 
@@ -149,6 +150,22 @@ class APIKeyCookieAuth(ValidatedAuthSource):
         except BadSignature:
             raise UnauthorizedError() from None
 
+    def authenticated_at(self, credential: str) -> float | None:
+        """When the signed cookie was minted, ``None`` when it does not verify."""
+        if self._signer is None:
+            return None
+        try:
+            _, signed_at = self._signer.unsign(
+                credential.encode(), max_age=self._ttl, return_timestamp=True
+            )
+        except BadSignature:
+            return None
+        return signed_at.timestamp()
+
+    def _dates_credentials(self) -> bool:
+        """Only a signed cookie carries the timestamp :meth:`fresh` needs."""
+        return self._signer is not None
+
     @property
     def name(self) -> str:
         """Cookie name. Read-only: the signing salt is derived from it."""
@@ -159,11 +176,11 @@ class APIKeyCookieAuth(ValidatedAuthSource):
         """Cookie lifetime in seconds: use it to derive your session's expiry."""
         return self._ttl
 
-    async def extract(self, request: Request) -> str | None:
+    async def extract(self, request: HTTPConnection) -> str | None:
         """Return the raw cookie value, or ``None`` when absent or empty."""
         return request.cookies.get(self._name) or None
 
-    def session_id_of(self, request: Request) -> str | None:
+    def session_id_of(self, request: HTTPConnection) -> str | None:
         """Return *request*'s session id without running the validator.
 
         ``None`` when ``session_id`` is off, or the cookie is absent, expired
@@ -180,7 +197,11 @@ class APIKeyCookieAuth(ValidatedAuthSource):
             return None
 
     async def authenticate_scoped(
-        self, credential: str, scopes: list[str], *, request: Request | None = None
+        self,
+        credential: str,
+        scopes: list[str],
+        *,
+        request: HTTPConnection | None = None,
     ) -> Any:
         """Verify the cookie, forwarding route-declared scopes to the validator."""
         plain = self._verify(credential)
@@ -214,7 +235,7 @@ class APIKeyCookieAuth(ValidatedAuthSource):
         return sid
 
     def delete_cookie(
-        self, response: Response, request: Request | None = None
+        self, response: Response, request: HTTPConnection | None = None
     ) -> str | None:
         """Clear the session cookie (logout) from this client only.
 

{fastapi_multiauth-0.6.0 → fastapi_multiauth-0.7.0}/src/fastapi_multiauth/sources/header.py

@@ -3,7 +3,7 @@
 from collections.abc import Callable
 from typing import Any
 
-from fastapi import Request
+from fastapi.requests import HTTPConnection
 from fastapi.security import APIKeyHeader
 
 from ..abc import ValidatedAuthSource
@@ -44,6 +44,6 @@ class APIKeyHeaderAuth(ValidatedAuthSource):
             **kwargs,
         )
 
-    async def extract(self, request: Request) -> str | None:
+    async def extract(self, request: HTTPConnection) -> str | None:
         """Return the API key from the configured header, or ``None`` when absent or empty."""
         return request.headers.get(self._name) or None

{fastapi_multiauth-0.6.0 → fastapi_multiauth-0.7.0}/src/fastapi_multiauth/sources/multi.py

@@ -2,9 +2,11 @@
 
 import copy
 import inspect
-from typing import Annotated, Any, cast
+from collections.abc import Callable, Iterable
+from typing import Annotated, Any, Self, cast
 
-from fastapi import Depends, Request
+from fastapi import Depends
+from fastapi.requests import HTTPConnection
 from fastapi.security import SecurityScopes
 
 from fastapi_multiauth.exceptions import UnauthorizedError
@@ -13,6 +15,7 @@ from ..abc import (
     AuthSource,
     _anonymous_scopes_error,
     _carry_scheme,
+    _fresh_optional_error,
     _unenforceable_scopes_error,
 )
 from ..utils import challenge_headers
@@ -51,7 +54,7 @@ class MultiAuth:
             inspect.Parameter(
                 "request",
                 inspect.Parameter.POSITIONAL_OR_KEYWORD,
-                annotation=Request,
+                annotation=HTTPConnection,
             ),
             inspect.Parameter(
                 "security_scopes",
@@ -95,13 +98,48 @@ class MultiAuth:
         """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."""
+    def optional(self) -> Self:
+        """Return a copy that yields ``None`` when no source has a credential.
+
+        Raises:
+            ValueError: On a :meth:`fresh` copy: anonymous is never fresh.
+        """
+        if any(source._freshness for source in self._sources):
+            raise _fresh_optional_error(self)
         clone = copy.copy(self)
         clone._optional = True
         return clone
 
-    async def dispatch(self, request: Request, scopes: list[str]) -> Any:
+    def fresh(
+        self,
+        max_age: float,
+        *,
+        authenticated_at: Callable[..., Any] | None = None,
+        leeway: float = 0.0,
+    ) -> "MultiAuth":
+        """Return a copy whose sources all require a recently proven credential.
+
+        Applies :meth:`AuthSource.fresh` to every source, so one that cannot be
+        dated refuses here instead of becoming the way around the window.
+
+        Raises:
+            ValueError: As :meth:`AuthSource.fresh`, naming the source that
+                cannot be dated or already has a window of its own.
+        """
+        if self._optional:
+            raise _fresh_optional_error(self)
+        return self._with_sources(
+            source.fresh(max_age, authenticated_at=authenticated_at, leeway=leeway)
+            for source in self._sources
+        )
+
+    def _with_sources(self, sources: Iterable[AuthSource]) -> "MultiAuth":
+        """A new :class:`MultiAuth` over *sources*, carrying this one's flags."""
+        clone = MultiAuth(*sources)
+        clone._optional = self._optional
+        return clone
+
+    async def dispatch(self, request: HTTPConnection, scopes: list[str]) -> Any:
         """Authenticate with the first source whose credential is present."""
         if scopes:
             if self._optional:
@@ -131,12 +169,9 @@ class MultiAuth:
 
     def require(self, **kwargs: Any) -> "MultiAuth":
         """Return a new :class:`MultiAuth` with kwargs forwarded to each source."""
-        new_sources = tuple(
+        return self._with_sources(
             cast(Any, source).require(**kwargs)
             if hasattr(source, "require")
             else source
             for source in self._sources
         )
-        clone = MultiAuth(*new_sources)
-        clone._optional = self._optional
-        return clone

{fastapi_multiauth-0.6.0 → fastapi_multiauth-0.7.0}/src/fastapi_multiauth/sources/query.py

@@ -3,7 +3,7 @@
 from collections.abc import Callable
 from typing import Any
 
-from fastapi import Request
+from fastapi.requests import HTTPConnection
 from fastapi.security import APIKeyQuery
 
 from ..abc import ValidatedAuthSource
@@ -49,6 +49,6 @@ class APIKeyQueryAuth(ValidatedAuthSource):
             **kwargs,
         )
 
-    async def extract(self, request: Request) -> str | None:
+    async def extract(self, request: HTTPConnection) -> str | None:
         """Return the API key from the configured query parameter, or ``None`` when absent or empty."""
         return request.query_params.get(self._name) or None

{fastapi_multiauth-0.6.0 → fastapi_multiauth-0.7.0}/src/fastapi_multiauth/surface.py

@@ -163,10 +163,22 @@ def _auth_units(dependant: Dependant) -> list[tuple[SchemeRequirement, ...]]:
     return list(dict.fromkeys(requirements))
 
 
+def _effective_route(context: Any) -> Any:
+    """Return *context*, or the merged route 0.137.2 to 0.143.0 leave off it."""
+    if getattr(context, "dependant", None) is not None:
+        return context
+    effective = getattr(
+        getattr(context, "_route_context", None), "starlette_route", None
+    )
+    return context if effective is None else effective
+
+
 def _routes_of(app: FastAPI) -> Iterable[Any]:
-    """Yield the app's routes, expanding the lazily included routers of 0.141+."""
+    """Yield the app's routes, expanding the lazily included routers of 0.137.2+."""
     expand = getattr(routing, "iter_route_contexts", None)
-    return expand(app.routes) if expand else app.routes
+    if expand is None:
+        return app.routes
+    return (_effective_route(context) for context in expand(app.routes))
 
 
 def auth_surface(app: FastAPI) -> list[RouteAuth]:

{fastapi_multiauth-0.6.0 → fastapi_multiauth-0.7.0}/src/fastapi_multiauth/utils.py

@@ -4,11 +4,15 @@ import functools
 import hashlib
 import hmac
 import inspect
+import math
+import time
 from collections.abc import Callable
+from datetime import UTC, datetime
 from typing import Any
 
 import anyio.to_thread
-from fastapi import HTTPException, Request
+from fastapi import HTTPException
+from fastapi.requests import HTTPConnection
 
 
 def hash_token(token: str) -> str:
@@ -70,7 +74,38 @@ def add_challenge(exc: HTTPException, challenge: str | None) -> None:
         exc.headers = headers
 
 
-def authorization_credential(request: Request, scheme: str) -> str | None:
+def credential_age(instant: Any) -> float | None:
+    """Seconds since *instant*, or ``None`` when it is not a point in time.
+
+    Epoch seconds or a ``datetime`` (naive read as UTC). Anything else,
+    a missing or non-finite instant included, fails closed.
+    """
+    if isinstance(instant, datetime):
+        if instant.tzinfo is None:
+            instant = instant.replace(tzinfo=UTC)
+        instant = instant.timestamp()
+    elif isinstance(instant, bool) or not isinstance(instant, (int, float)):
+        return None
+    try:
+        age = time.time() - instant
+    except OverflowError:
+        return None
+    return age if math.isfinite(age) else None
+
+
+def step_up_challenge(challenge: str | None, max_age: float) -> dict[str, str] | None:
+    """The RFC 9470 step-up ``WWW-Authenticate`` header, ``None`` without a challenge."""
+    if not challenge:
+        return None
+    separator = ", " if " " in challenge else " "
+    return challenge_headers(
+        f'{challenge}{separator}error="insufficient_user_authentication", '
+        'error_description="More recent authentication is required", '
+        f'max_age="{max(1, int(max_age))}"'
+    )
+
+
+def authorization_credential(request: HTTPConnection, scheme: str) -> str | None:
     """Extract the value of an ``Authorization: <scheme> <value>`` header.
 
     The scheme is matched case-insensitively (RFC 7235 §2.1). Returns ``None``