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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-multiauth
-Version: 0.5.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.108.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)
 
 ---
@@ -118,7 +118,7 @@ async def me(user=Security(auth)):
 - **BYO validator**: every source wraps a sync or async callable you provide; the library never touches your user model or database.
 - **`MultiAuth`**: try several sources in order on a single route (e.g. web session cookie + API bearer token), with all schemes documented in OpenAPI.
 - **Built-in sources**: covering the standard `fastapi.security` schemes:
-    - **`HTTPBearerAuth`**: bearer tokens with optional Stripe-style `user_`/`org_` prefixes to route different token types to different validators, plus `generate_token()` for secure token creation.
+    - **`HTTPBearerAuth`**: bearer tokens with optional Stripe-style `user_`/`org_` prefixes to route different token types to different validators, plus `generate_token()` for secure token creation (bring your own `token_generator` to pick the token format).
     - **`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.
@@ -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.5.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)
 
 ---
@@ -77,7 +77,7 @@ async def me(user=Security(auth)):
 - **BYO validator**: every source wraps a sync or async callable you provide; the library never touches your user model or database.
 - **`MultiAuth`**: try several sources in order on a single route (e.g. web session cookie + API bearer token), with all schemes documented in OpenAPI.
 - **Built-in sources**: covering the standard `fastapi.security` schemes:
-    - **`HTTPBearerAuth`**: bearer tokens with optional Stripe-style `user_`/`org_` prefixes to route different token types to different validators, plus `generate_token()` for secure token creation.
+    - **`HTTPBearerAuth`**: bearer tokens with optional Stripe-style `user_`/`org_` prefixes to route different token types to different validators, plus `generate_token()` for secure token creation (bring your own `token_generator` to pick the token format).
     - **`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.
@@ -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.5.0 → fastapi_multiauth-0.7.0}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "fastapi-multiauth"
-version = "0.5.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.108.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.5.0 → fastapi_multiauth-0.7.0}/pyproject.toml.orig

@@ -1,11 +1,11 @@
 [project]
 name = "fastapi-multiauth"
-version = "0.5.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.108.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.5.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,
@@ -24,9 +24,10 @@ from .sources import (
     OAuth2PasswordBearerAuth,
     OpenIdConnectAuth,
 )
+from .surface import RouteAuth, SchemeRequirement, auth_surface
 from .utils import hash_token, verify_token_hash
 
-__version__ = "0.5.0"
+__version__ = "0.7.0"
 
 __all__ = [
     "APIKeyCookieAuth",
@@ -41,7 +42,11 @@ __all__ = [
     "OAuth2AuthorizationCodeBearerAuth",
     "OAuth2PasswordBearerAuth",
     "OpenIdConnectAuth",
+    "RouteAuth",
+    "SchemeRequirement",
+    "StaleCredentialError",
     "UnauthorizedError",
+    "auth_surface",
     "hash_token",
     "oauth",
     "verify_token_hash",

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

@@ -2,24 +2,30 @@
 
 import copy
 import inspect
+import math
 from abc import ABC, abstractmethod
-from collections.abc import Callable
-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=[...])",
     "session_id": "injected by APIKeyCookieAuth(session_id=True)",
+    "request": "injected when the validator declares a 'request' parameter",
 }
 
 
@@ -33,11 +39,20 @@ def _reject_reserved_kwargs(kwargs: dict[str, Any]) -> None:
             )
 
 
-def _accepts_kwarg(fn: Callable[..., Any], name: str) -> bool:
-    """Return whether *fn* declares a *name* parameter."""
+def _signature_params(
+    fn: Callable[..., Any],
+) -> Mapping[str, inspect.Parameter] | None:
+    """The parameters of *fn*, ``None`` when it has no inspectable signature."""
     try:
-        parameters = inspect.signature(fn).parameters
+        return inspect.signature(fn).parameters
     except (TypeError, ValueError):
+        return None
+
+
+def _accepts_kwarg(fn: Callable[..., Any], name: str) -> bool:
+    """Return whether *fn* declares a *name* parameter, ``False`` when uninspectable."""
+    parameters = _signature_params(fn)
+    if parameters is None:
         return False
     param = parameters.get(name)
     return param is not None and param.kind in (
@@ -46,6 +61,21 @@ def _accepts_kwarg(fn: Callable[..., Any], name: str) -> bool:
     )
 
 
+def _override_accepts_request(method: Callable[..., Any]) -> bool:
+    """Whether an ``authenticate_scoped`` override can be handed the request."""
+    parameters = _signature_params(method)
+    if parameters is None:  # not introspectable: take the override at its word
+        return True
+    return any(
+        (
+            param.name == "request"
+            and param.kind is not inspect.Parameter.POSITIONAL_ONLY
+        )
+        or param.kind is inspect.Parameter.VAR_KEYWORD
+        for param in parameters.values()
+    )
+
+
 def _unenforceable_scopes_error(
     owner: object, scopes: list[str], reason: str | None = None
 ) -> RuntimeError:
@@ -76,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:
@@ -99,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
 
 
@@ -121,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.
@@ -141,6 +191,9 @@ class AuthSource(ABC):
             scheme: Optional ``fastapi.security`` scheme; only its OpenAPI
                 metadata is used, extraction always goes through :meth:`extract`.
         """
+        self._scoped_takes_request = _override_accepts_request(
+            type(self).authenticate_scoped
+        )
         self.scheme = _DocOnlyScheme(scheme) if scheme is not None else None
         if self.scheme is not None:
             _carry_scheme(self, self.scheme)
@@ -149,7 +202,7 @@ class AuthSource(ABC):
             inspect.Parameter(
                 "request",
                 inspect.Parameter.POSITIONAL_OR_KEYWORD,
-                annotation=Request,
+                annotation=HTTPConnection,
             ),
             inspect.Parameter(
                 "security_scopes",
@@ -160,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
@@ -178,8 +231,21 @@ class AuthSource(ABC):
         """
         return None
 
-    async def authenticate_scoped(self, credential: str, scopes: list[str]) -> Any:
-        """Validate a credential, enforcing the scopes declared on the route."""
+    async def authenticate_scoped(
+        self,
+        credential: str,
+        scopes: list[str],
+        *,
+        request: HTTPConnection | None = None,
+    ) -> Any:
+        """Validate a credential, enforcing the scopes declared on the route.
+
+        Args:
+            credential: The raw credential returned by :meth:`extract`.
+            scopes: The scopes the route declared, empty outside a route.
+            request: The request being authenticated, ``None`` when there is
+                none. Ignored here; override to use it.
+        """
         if scopes:  # fail closed: plain authenticate() cannot check scopes
             raise _unenforceable_scopes_error(self, scopes)
         return await self.authenticate(credential)
@@ -188,22 +254,125 @@ class AuthSource(ABC):
         """Whether route-declared scopes reach an actual check in this source."""
         return type(self).authenticate_scoped is not AuthSource.authenticate_scoped
 
+    async def _call_scoped(
+        self, credential: str, scopes: list[str], *, request: HTTPConnection | None
+    ) -> Any:
+        """Call :meth:`authenticate_scoped`, honouring overrides predating ``request``."""
+        if self._scoped_takes_request:
+            return await self.authenticate_scoped(credential, scopes, request=request)
+        return await self.authenticate_scoped(credential, scopes)
+
     async def _authenticate_with_challenge(
-        self, credential: str, scopes: list[str]
+        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.authenticate_scoped(credential, scopes)
+            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
@@ -213,11 +382,9 @@ 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.
 
-        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.
@@ -233,7 +400,9 @@ class AuthSource(ABC):
             if self._optional:
                 return None
             raise UnauthorizedError(headers=challenge_headers(self.www_authenticate()))
-        return await self._authenticate_with_challenge(credential, scopes)
+        return await self._authenticate_with_challenge(
+            credential, scopes, request=request
+        )
 
     async def __call__(self, **kwargs: Any) -> Any:
         """FastAPI dependency dispatch."""
@@ -261,40 +430,55 @@ class ValidatedAuthSource(AuthSource):
             scheme: Optional ``fastapi.security`` scheme for OpenAPI.
             **kwargs: Extra keyword arguments forwarded to the validator on
                 every call. Names the library injects itself are reserved:
-                ``scopes`` and ``session_id``.
+                ``scopes``, ``session_id`` and ``request``.
         """
         _reject_reserved_kwargs(kwargs)
         self._validator = ensure_async(validator)
         self._accepts_scopes = _accepts_kwarg(validator, "scopes")
+        self._accepts_request = _accepts_kwarg(validator, "request")
         self._kwargs = kwargs
         super().__init__(scheme)
 
     async def _call_validator(
-        self, *args: Any, scopes: list[str], **injected: Any
+        self,
+        *args: Any,
+        scopes: list[str],
+        request: HTTPConnection | None = None,
+        **injected: Any,
     ) -> Any:
-        """Invoke the validator with scope and configured kwargs forwarding."""
+        """Invoke the validator with scope, request and configured kwargs forwarding."""
         if self._accepts_scopes:
             injected["scopes"] = scopes
         elif scopes:  # fail closed: the validator cannot check them
             raise _unenforceable_scopes_error(self, scopes)
+        if self._accepts_request:
+            injected["request"] = request
         return await self._validator(*args, **self._kwargs, **injected)
 
-    async def authenticate(self, credential: str) -> Any:
+    async def authenticate(
+        self, credential: str, *, request: HTTPConnection | None = None
+    ) -> Any:
         """Validate a credential and return the identity (no route scopes)."""
-        return await self.authenticate_scoped(credential, [])
+        return await self._call_scoped(credential, [], request=request)
 
-    async def authenticate_scoped(self, credential: str, scopes: list[str]) -> Any:
-        """Validate a credential, forwarding route-declared scopes to the validator."""
-        return await self._call_validator(credential, scopes=scopes)
+    async def authenticate_scoped(
+        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)
 
     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":
+    def require(self, **kwargs: Any) -> Self:
         """Return a copy of this source with additional (or overriding) validator kwargs.
 
-        Reserved names (``scopes``, ``session_id``) are rejected here too.
+        Reserved names (``scopes``, ``session_id``, ``request``) are rejected here too.
         """
         _reject_reserved_kwargs(kwargs)
         clone = copy.copy(self)