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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-multiauth
-Version: 0.7.0
+Version: 0.8.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
@@ -123,13 +123,14 @@ async def me(user=Security(auth)):
     - **`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.
+- **Token hashing helpers**: `hash_token`/`verify_token_hash` package the "store the hash, never the token" pattern with constant-time comparison, and `checksum_token_generator`/`verify_token_checksum` add a GitHub-style CRC32 suffix that refuses typos before the lookup.
 - **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.
+- **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. `source.stepped_up(acr_values=[...], acr=...)` asks for a stronger level instead, and composes with `fresh()` into one challenge; `AuthenticationMethodReference` names the [RFC 8176](https://datatracker.ietf.org/doc/html/rfc8176) `amr` values.
 - **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).
+- **Security-event logging**: every refusal is a `WARNING` under `fastapi_multiauth.*` with a reason code (`invalid_signature`, `expired`, `stale`, …) in `extra`, never the credential or the identity; silent until your app configures logging.
+- **OAuth 2.0 / OIDC helpers** (`fastapi-multiauth[oauth]` extra): async discovery with TTL caching, HTTPS enforcement, CSRF-protected `state` encoding, PKCE (S256), code exchange delegated to [httpx-oauth](https://github.com/frankie567/httpx-oauth), and OpenID Connect ID token validation with `nonce` and `at_hash` (plus the `jwt` extra).
 
 ## Comparison
 

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

@@ -82,13 +82,14 @@ async def me(user=Security(auth)):
     - **`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.
+- **Token hashing helpers**: `hash_token`/`verify_token_hash` package the "store the hash, never the token" pattern with constant-time comparison, and `checksum_token_generator`/`verify_token_checksum` add a GitHub-style CRC32 suffix that refuses typos before the lookup.
 - **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.
+- **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. `source.stepped_up(acr_values=[...], acr=...)` asks for a stronger level instead, and composes with `fresh()` into one challenge; `AuthenticationMethodReference` names the [RFC 8176](https://datatracker.ietf.org/doc/html/rfc8176) `amr` values.
 - **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).
+- **Security-event logging**: every refusal is a `WARNING` under `fastapi_multiauth.*` with a reason code (`invalid_signature`, `expired`, `stale`, …) in `extra`, never the credential or the identity; silent until your app configures logging.
+- **OAuth 2.0 / OIDC helpers** (`fastapi-multiauth[oauth]` extra): async discovery with TTL caching, HTTPS enforcement, CSRF-protected `state` encoding, PKCE (S256), code exchange delegated to [httpx-oauth](https://github.com/frankie567/httpx-oauth), and OpenID Connect ID token validation with `nonce` and `at_hash` (plus the `jwt` extra).
 
 ## Comparison
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-multiauth"
-version = "0.7.0"
+version = "0.8.0"
 description = "Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes, correct OpenAPI by construction"
 readme = "README.md"
 license = "MIT"

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

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-multiauth"
-version = "0.7.0"
+version = "0.8.0"
 description = "Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes, correct OpenAPI by construction"
 readme = "README.md"
 license = "MIT"

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

@@ -9,9 +9,17 @@ exported here, and require the ``oauth`` extra. Import them explicitly::
     redirect = oauth.oauth_build_authorization_redirect(...)
 """
 
+import logging
+
 from . import oauth
 from .abc import AuthSource
-from .exceptions import ForbiddenError, StaleCredentialError, UnauthorizedError
+from .amr import AuthenticationMethodReference
+from .exceptions import (
+    ForbiddenError,
+    InsufficientAuthenticationError,
+    StaleCredentialError,
+    UnauthorizedError,
+)
 from .jwt import JWTValidator
 from .sources import (
     APIKeyCookieAuth,
@@ -25,18 +33,27 @@ from .sources import (
     OpenIdConnectAuth,
 )
 from .surface import RouteAuth, SchemeRequirement, auth_surface
-from .utils import hash_token, verify_token_hash
+from .utils import (
+    checksum_token_generator,
+    hash_token,
+    verify_token_checksum,
+    verify_token_hash,
+)
+
+__version__ = "0.8.0"
 
-__version__ = "0.7.0"
+logging.getLogger(__name__).addHandler(logging.NullHandler())
 
 __all__ = [
     "APIKeyCookieAuth",
     "APIKeyHeaderAuth",
     "APIKeyQueryAuth",
     "AuthSource",
+    "AuthenticationMethodReference",
     "ForbiddenError",
     "HTTPBasicAuth",
     "HTTPBearerAuth",
+    "InsufficientAuthenticationError",
     "JWTValidator",
     "MultiAuth",
     "OAuth2AuthorizationCodeBearerAuth",
@@ -47,7 +64,9 @@ __all__ = [
     "StaleCredentialError",
     "UnauthorizedError",
     "auth_surface",
+    "checksum_token_generator",
     "hash_token",
     "oauth",
+    "verify_token_checksum",
     "verify_token_hash",
 ]

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

@@ -2,26 +2,36 @@
 
 import copy
 import inspect
+import logging
 import math
 from abc import ABC, abstractmethod
-from collections.abc import Awaitable, Callable, Mapping
+from collections.abc import Awaitable, Callable, Mapping, Sequence
 from dataclasses import dataclass
-from typing import Any, Self
+from typing import Any, ClassVar, Self
 
 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 StaleCredentialError, UnauthorizedError
+from fastapi_multiauth.exceptions import (
+    InsufficientAuthenticationError,
+    StaleCredentialError,
+    UnauthorizedError,
+)
 from fastapi_multiauth.utils import (
     add_challenge,
     challenge_headers,
     credential_age,
     ensure_async,
+    log_decision,
+    refusal,
+    refusal_reason,
     step_up_challenge,
 )
 
+logger = logging.getLogger(__name__)
+
 _RESERVED_KWARGS = {
     "scopes": "injected from the route by Security(..., scopes=[...])",
     "session_id": "injected by APIKeyCookieAuth(session_id=True)",
@@ -106,14 +116,46 @@ 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."""
+def _step_up_optional_error(owner: object, guard: str) -> ValueError:
+    """Error for a dependency asking for both anonymous callers and a step-up."""
     return ValueError(
-        f"{type(owner).__name__} cannot be both optional() and fresh(): an "
-        "anonymous caller can never be fresh"
+        f"{type(owner).__name__} cannot be both optional() and {guard}: an "
+        "anonymous caller has proven no factor at all"
     )
 
 
+def _step_up_optional_guard(owner: Any) -> str | None:
+    """The step-up guard that keeps *owner* from being optional, if any."""
+    if owner._freshness is not None:
+        return "fresh()"
+    if owner._assurance is not None:
+        return "stepped_up()"
+    return None
+
+
+def _validate_acr_values(acr_values: Sequence[str]) -> tuple[str, ...]:
+    """Check *acr_values* can travel in the step-up challenge's quoted string."""
+    if isinstance(acr_values, str):
+        raise TypeError("acr_values must be a sequence of strings, not a string")
+    values = tuple(acr_values)
+    if not values:
+        raise ValueError("acr_values must list at least one value")
+    for value in values:
+        if not (
+            isinstance(value, str)
+            and value
+            and value.isascii()
+            and value.isprintable()
+            and not any(char in value for char in ' "\\')
+        ):
+            raise ValueError(
+                f"each acr_values entry must be non-empty printable US-ASCII "
+                f"without spaces, quotes or backslashes (got {value!r}): the "
+                "values are space-separated inside a quoted-string (RFC 9470)"
+            )
+    return values
+
+
 def _undeclared_scopes_error(
     owner: object, unknown: list[str], catalogue: dict[str, str]
 ) -> RuntimeError:
@@ -169,6 +211,15 @@ class _Freshness:
     """Caller-supplied reader of the instant, ``None`` to use the source's own."""
 
 
+@dataclass(frozen=True, slots=True)
+class _Assurance:
+    """The levels set by :meth:`AuthSource.stepped_up`."""
+
+    acr_values: tuple[str, ...]
+    read: Callable[[Any], Awaitable[Any]]
+    """Caller-supplied reader of the identity's ``acr``."""
+
+
 class AuthSource(ABC):
     """Abstract base class for authentication sources.
 
@@ -183,6 +234,15 @@ class AuthSource(ABC):
     _scope_catalogue: dict[str, str] | None = None
     """The scopes this source publishes to OpenAPI, ``None`` when it has none."""
     _freshness: _Freshness | None = None
+    _assurance: _Assurance | None = None
+    _logger: ClassVar[logging.Logger] = logger
+    """Where this source logs its decisions: its module's logger."""
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Log a library source under its own module's logger."""
+        super().__init_subclass__(**kwargs)
+        if cls.__module__.startswith(f"{__package__}."):
+            cls._logger = logging.getLogger(cls.__module__)
 
     def __init__(self, scheme: Any = None) -> None:
         """Set up the FastAPI dependency signature.
@@ -272,24 +332,40 @@ class AuthSource(ABC):
         """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.
+        invalid, not as stale. Every outcome is logged.
         """
         try:
             identity = await self._call_scoped(credential, scopes, request=request)
+            await self._enforce_step_up(credential, identity)
         except HTTPException as exc:
             add_challenge(exc, self.www_authenticate())
+            self._log(logging.WARNING, refusal_reason(exc), exc.status_code)
             raise
-        await self._enforce_freshness(credential, identity)
+        if self._logger.isEnabledFor(logging.DEBUG):
+            self._log(logging.DEBUG, "authenticated")
         return identity
 
+    def _log(self, level: int, reason: str, status: int | None = None) -> None:
+        """Log one decision of this source."""
+        log_decision(
+            self._logger,
+            level,
+            reason,
+            source=type(self).__name__,
+            scheme=self.scheme.scheme_name if self.scheme is not None else None,
+            status=status,
+        )
+
     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.
+            ValueError: On a :meth:`fresh` or :meth:`stepped_up` copy:
+                anonymous has proven no factor.
         """
-        if self._freshness is not None:
-            raise _fresh_optional_error(self)
+        guard = _step_up_optional_guard(self)
+        if guard is not None:
+            raise _step_up_optional_error(self, guard)
         clone = copy.copy(self)
         clone._optional = True
         return clone
@@ -336,7 +412,7 @@ class AuthSource(ABC):
         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)
+            raise _step_up_optional_error(self, "fresh()")
         if self._freshness is not None:
             raise ValueError(
                 f"{type(self).__name__} already has a freshness window: call "
@@ -355,23 +431,89 @@ class AuthSource(ABC):
         )
         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
+    def stepped_up(
+        self,
+        acr_values: Sequence[str],
+        *,
+        acr: Callable[..., Any],
+    ) -> Self:
+        """Return a copy that refuses a credential not proven at one of *acr_values*.
+
+        The `RFC 9470 <https://datatracker.ietf.org/doc/html/rfc9470>`_
+        counterpart of :meth:`fresh`: "authenticate more strongly" rather than
+        "authenticate again". Both compose, in either order, into one
+        challenge carrying ``acr_values`` and ``max_age``.
+
+        Args:
+            acr_values: The authentication context class references the route
+                accepts; any one of them passes.
+            acr: Sync or async callable taking the identity and returning the
+                ``acr`` the caller authenticated with, e.g.
+                ``lambda claims: claims.get("acr")``. Anything outside
+                *acr_values*, ``None`` included, refuses the request.
+
+        Raises:
+            TypeError: If *acr_values* is a bare string.
+            ValueError: An empty *acr_values*, an entry that cannot travel in
+                the challenge (whitespace, quotes, backslashes, non-ASCII), an
+                :meth:`optional` copy, or a copy that already has levels.
+        """
+        values = _validate_acr_values(acr_values)
+        if self._optional:
+            raise _step_up_optional_error(self, "stepped_up()")
+        if self._assurance is not None:
+            raise ValueError(
+                f"{type(self).__name__} already has acr_values: call "
+                "stepped_up() once, on the source or on the MultiAuth"
+            )
+        clone = copy.copy(self)
+        clone._assurance = _Assurance(acr_values=values, read=ensure_async(acr))
+        return clone
+
+    async def _enforce_step_up(self, credential: str, identity: Any) -> None:
+        """Refuse an identity outside the :meth:`fresh` window or :meth:`stepped_up` levels."""
+        freshness, assurance = self._freshness, self._assurance
+        if freshness is not None and not await self._is_fresh(
+            freshness, credential, identity
+        ):
+            raise refusal(self._step_up_error(StaleCredentialError), "stale")
+        if assurance is not None:
+            achieved = await assurance.read(identity)
+            if achieved not in assurance.acr_values:
+                raise refusal(
+                    self._step_up_error(InsufficientAuthenticationError),
+                    "insufficient_acr",
+                )
+
+    async def _is_fresh(
+        self, freshness: _Freshness, credential: str, identity: Any
+    ) -> bool:
+        """Whether the credential was proven inside the window."""
         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 (
+        return age is not None and (
             -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 _step_up_error(
+        self, error_cls: type[InsufficientAuthenticationError]
+    ) -> InsufficientAuthenticationError:
+        """The refusal, its challenge listing every step-up requirement."""
+        max_age = self._freshness.max_age if self._freshness else None
+        acr_values = self._assurance.acr_values if self._assurance else None
+        return error_cls(
+            headers=step_up_challenge(
+                self.www_authenticate(),
+                error_cls.error_description,
+                max_age=max_age,
+                acr_values=acr_values,
+            ),
+            max_age=max_age,
+            acr_values=acr_values,
+        )
 
     def _reject_undeclared_scopes(self, scopes: list[str]) -> None:
         """Refuse a route declaring scopes this source never published."""
@@ -398,7 +540,9 @@ class AuthSource(ABC):
         credential = await self.extract(request)
         if credential is None:
             if self._optional:
+                self._log(logging.DEBUG, "anonymous")
                 return None
+            self._log(logging.INFO, "missing_credential", 401)
             raise UnauthorizedError(headers=challenge_headers(self.www_authenticate()))
         return await self._authenticate_with_challenge(
             credential, scopes, request=request

fastapi_multiauth-0.8.0/src/fastapi_multiauth/amr.py

@@ -0,0 +1,54 @@
+"""Authentication Method Reference values (RFC 8176) for ``amr`` claims."""
+
+from enum import StrEnum
+
+
+class AuthenticationMethodReference(StrEnum):
+    """The registered values of the ``amr`` claim (RFC 8176 §2, IANA registry).
+
+    A ``StrEnum``, so members compare equal to the strings a provider puts in
+    the claim: ``AuthenticationMethodReference.MULTI_FACTOR in claims["amr"]``.
+    """
+
+    FACE = "face"
+    """Biometric authentication using facial recognition."""
+    FINGERPRINT = "fpt"
+    """Biometric authentication using a fingerprint."""
+    GEOLOCATION = "geo"
+    """Use of geolocation information for authentication."""
+    HARDWARE_KEY = "hwk"
+    """Proof-of-possession of a hardware-secured key."""
+    IRIS = "iris"
+    """Biometric authentication using an iris scan."""
+    KNOWLEDGE_BASED = "kba"
+    """Knowledge-based authentication."""
+    MULTI_CHANNEL = "mca"
+    """Multiple-channel authentication."""
+    MULTI_FACTOR = "mfa"
+    """Multiple-factor authentication."""
+    ONE_TIME_PASSWORD = "otp"  # noqa: S105
+    """One-time password."""
+    PIN = "pin"
+    """Personal Identification Number or pattern used to unlock a device."""
+    PROOF_OF_POSSESSION = "pop"
+    """Proof-of-possession of a key (OpenID Connect EAP ACR Values 1.0)."""
+    PASSWORD = "pwd"  # noqa: S105
+    """Password-based authentication."""
+    RISK_BASED = "rba"
+    """Risk-based authentication."""
+    RETINA = "retina"
+    """Biometric authentication using a retina scan."""
+    SMART_CARD = "sc"
+    """Smart card."""
+    SMS = "sms"
+    """Confirmation by an SMS text message to a registered number."""
+    SOFTWARE_KEY = "swk"
+    """Proof-of-possession of a software-secured key."""
+    TELEPHONE = "tel"
+    """Confirmation by a telephone call to a registered number."""
+    USER_PRESENCE = "user"
+    """User presence test."""
+    VOICE = "vbm"
+    """Biometric authentication using a voiceprint."""
+    WINDOWS_INTEGRATED = "wia"
+    """Windows integrated authentication."""

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

@@ -1,5 +1,7 @@
 """Exceptions raised by authentication sources and OAuth helpers."""
 
+from typing import ClassVar
+
 from fastapi import HTTPException, status
 
 
@@ -25,18 +27,26 @@ class UnauthorizedError(HTTPException):
         )
 
 
-class StaleCredentialError(UnauthorizedError):
-    """HTTP 401 — the credential is valid but was proven too long ago.
+class InsufficientAuthenticationError(UnauthorizedError):
+    """HTTP 401: the credential is valid but its authentication falls short.
 
-    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`.
+    Raised by a route guarded with :meth:`~fastapi_multiauth.AuthSource.stepped_up`
+    when the credential was not proven at a requested level, and the base of
+    :class:`StaleCredentialError`. ``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 listing every requirement of the route. A handler
+    rendering its own body reads :attr:`max_age` and :attr:`acr_values`.
     """
 
+    error_description: ClassVar[str] = "A different authentication level is required"
+    """The challenge's ``error_description`` for this refusal."""
+
     max_age: float | None
-    """The freshness window the credential missed, in seconds."""
+    """The route's freshness window in seconds, ``None`` without :meth:`fresh`."""
+
+    acr_values: tuple[str, ...] | None
+    """The levels the route accepts, ``None`` without :meth:`stepped_up`."""
 
     def __init__(
         self,
@@ -44,18 +54,31 @@ class StaleCredentialError(UnauthorizedError):
         headers: dict[str, str] | None = None,
         *,
         max_age: float | None = None,
+        acr_values: tuple[str, ...] | 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.
+            max_age: The route's freshness window, in seconds.
+            acr_values: The authentication context classes the route accepts.
         """
         self.max_age = max_age
+        self.acr_values = acr_values
         super().__init__(detail=detail, headers=headers)
 
 
+class StaleCredentialError(InsufficientAuthenticationError):
+    """HTTP 401 — the credential is valid but was proven too long ago.
+
+    Raised by a route guarded with :meth:`~fastapi_multiauth.AuthSource.fresh`.
+    Everything else is as :class:`InsufficientAuthenticationError`.
+    """
+
+    error_description: ClassVar[str] = "More recent authentication is required"
+
+
 class ForbiddenError(HTTPException):
     """HTTP 403 — the identity is authenticated but lacks permission.
 
@@ -89,9 +112,26 @@ class OAuthDiscoveryError(OAuthError):
     """Raised when the OIDC discovery document cannot be fetched or is invalid."""
 
 
+class OAuthStateError(OAuthError):
+    """Raised when the OAuth ``state`` parameter fails its CSRF check.
+
+    The callback did not originate from a redirect this session started: the
+    route must not exchange the code.
+    """
+
+
 class OAuthExchangeError(OAuthError):
     """Raised when the OAuth authorization code exchange fails."""
 
 
 class OAuthUserinfoError(OAuthError):
     """Raised when the userinfo endpoint cannot be reached or returns garbage."""
+
+
+class OAuthIDTokenError(OAuthError):
+    """Raised when an OpenID Connect ID token fails validation.
+
+    Its signature, issuer, audience, lifetime, ``nonce`` or ``at_hash`` did not
+    check out, or the provider's signing keys could not be fetched: do not
+    trust any of its claims.
+    """