xtr-security-http 3.0.0__py3-none-any.whl

xtr_security_http/access_token/header_access_token_extractor.py

@@ -0,0 +1,80 @@
+"""An extractor that reads a bearer token from the Authorization header."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from fastapi.security import APIKeyHeader, HTTPBearer
+from typing_extensions import override
+
+from .access_token_extractor_interface import AccessTokenExtractorInterface
+
+if TYPE_CHECKING:
+    from fastapi.security.base import SecurityBase
+    from starlette.requests import Request
+
+__all__ = ["HeaderAccessTokenExtractor"]
+
+
+@final
+class HeaderAccessTokenExtractor(AccessTokenExtractorInterface):
+    """Reads a token from a request header, ``Authorization: Bearer <token>`` by default.
+
+    Built on FastAPI's own :class:`~fastapi.security.HTTPBearer` with
+    ``auto_error=False``, so a missing or malformed header reads as ``None``
+    and the firewall's entry point — not FastAPI — answers the challenge. A
+    different header name or token type folds the extraction onto an
+    :class:`~fastapi.security.APIKeyHeader` instead, for a scheme that is not
+    the standard bearer one.
+
+    Attributes:
+        header_name: The header the token is read from.
+        token_type: The scheme word before the token (``"Bearer"`` by default).
+    """
+
+    __slots__ = ("_api_key", "_bearer", "_header_name", "_token_type")
+
+    def __init__(
+        self,
+        header_name: str = "Authorization",
+        token_type: str = "Bearer",  # noqa: S107 -- a scheme word, not a secret
+    ) -> None:
+        """Build the extractor for ``header_name`` carrying a ``token_type`` token."""
+        self._header_name = header_name
+        self._token_type = token_type
+        standard = header_name.lower() == "authorization" and token_type.lower() == "bearer"
+        self._bearer = (
+            HTTPBearer(auto_error=False, bearerFormat="JWT", scheme_name="Bearer")
+            if standard
+            else None
+        )
+        self._api_key = (
+            None
+            if standard
+            else APIKeyHeader(name=header_name, auto_error=False, scheme_name=header_name)
+        )
+
+    @override
+    async def extract_access_token(self, request: Request) -> str | None:
+        """Return the token in the header, or ``None`` when it is absent or malformed."""
+        if self._bearer is not None:
+            credentials = await self._bearer(request)
+            return credentials.credentials if credentials is not None else None
+        assert self._api_key is not None  # noqa: S101 -- one of the two is always set
+        value = await self._api_key(request)
+        if value is None:
+            return None
+        prefix = f"{self._token_type} "
+        if self._token_type and value.startswith(prefix):
+            return value[len(prefix) :]
+        return value if not self._token_type else None
+
+    @override
+    def scheme(self) -> SecurityBase:
+        """Return the bearer or API-key scheme this extractor reads and documents by."""
+        return self._bearer if self._bearer is not None else self._require_api_key()
+
+    def _require_api_key(self) -> APIKeyHeader:
+        """Return the API-key scheme, asserting it was built."""
+        assert self._api_key is not None  # noqa: S101 -- built whenever the bearer is not
+        return self._api_key

xtr_security_http/access_token/oidc/__init__.py

@@ -0,0 +1,41 @@
+"""Verifying bearer tokens from third-party OIDC issuers (needs the ``oidc`` extra).
+
+Importing this subpackage requires joserfc and httpx, brought by the ``oidc``
+extra of xtr-security-http. Importing :mod:`xtr_security_http` itself pulls in
+neither; only reaching in here does, so an application that never verifies OIDC
+tokens carries no JOSE or HTTP-client dependency.
+
+The key material lives with the authenticator and discovery it serves —
+:mod:`xtr_security_http.authenticator.oidc` and :mod:`xtr_security_http.oidc` —
+and is re-exported here so the whole OIDC surface is reachable from one place.
+"""
+
+from __future__ import annotations
+
+try:
+    import httpx as _httpx
+    import joserfc as _joserfc
+except ImportError as _error:  # pragma: no cover -- exercised in a subprocess without the extra
+    raise ImportError(
+        "The OIDC access-token handler needs joserfc and httpx; install the 'oidc' extra: "
+        'uv add "xtr-security-http[oidc]".',
+    ) from _error
+else:
+    del _httpx, _joserfc
+
+from xtr_security_http.authenticator.oidc.oidc_jwks import (
+    OidcKeySetProviderInterface,
+    StaticOidcKeySetProvider,
+)
+from xtr_security_http.oidc.oidc_discovery import DiscoveryOidcKeySetProvider
+
+from .exception.oidc_key_set_error import OidcKeySetError
+from .oidc_token_handler import OidcTokenHandler
+
+__all__ = [
+    "DiscoveryOidcKeySetProvider",
+    "OidcKeySetError",
+    "OidcKeySetProviderInterface",
+    "OidcTokenHandler",
+    "StaticOidcKeySetProvider",
+]

xtr_security_http/access_token/oidc/exception/__init__.py

@@ -0,0 +1,7 @@
+"""OIDC access-token errors: the keys to verify a token could not be obtained."""
+
+from __future__ import annotations
+
+from .oidc_key_set_error import OidcKeySetError
+
+__all__ = ["OidcKeySetError"]

xtr_security_http/access_token/oidc/exception/oidc_key_set_error.py

@@ -0,0 +1,18 @@
+"""The keys that verify an OIDC token could not be obtained."""
+
+from __future__ import annotations
+
+from xtr_security_core.exception import SecurityError
+
+__all__ = ["OidcKeySetError"]
+
+
+class OidcKeySetError(SecurityError):
+    """The verifying key set could not be fetched, discovered or read.
+
+    Raised when a discovery document or a JWKS endpoint cannot be reached, an
+    answer is not the JSON a key set is read from, or a discovered endpoint is
+    not the ``https`` a key set is trusted to come over. The token handler turns
+    it into an :class:`~xtr_security_http.exception.InvalidAccessTokenError`,
+    since a token that cannot be verified cannot be trusted.
+    """

xtr_security_http/access_token/oidc/oidc_token_handler.py

@@ -0,0 +1,246 @@
+"""Verifies a bearer token from a third-party OIDC issuer into a user badge."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast, final
+
+from joserfc import jwt
+from joserfc.errors import InvalidKeyIdError, JoseError
+from joserfc.jwt import JWTClaimsRegistry
+from xtr_security_core.exception import InvalidArgumentError
+from xtr_security_core.user.attributes_based_user_provider_interface import (
+    AttributesBasedUserProviderInterface,
+)
+from xtr_security_core.user.oidc_user import OidcUser
+
+from xtr_security_http.authenticator.passport.badge.user_badge import UserBadge
+from xtr_security_http.exception.invalid_access_token_error import InvalidAccessTokenError
+
+from .exception.oidc_key_set_error import OidcKeySetError
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Mapping, Sequence
+
+    from joserfc.jwt import ClaimsOption, Token
+    from xtr_security_core.user.user_interface import UserInterface
+    from xtr_security_core.user.user_provider_interface import UserProviderInterface
+
+    from xtr_security_http.authenticator.oidc.oidc_jwks import OidcKeySetProviderInterface
+
+    UserLoader = Callable[[str], UserInterface | Awaitable[UserInterface]]
+
+__all__ = ["OidcTokenHandler"]
+
+_AT_JWT_TYPES = frozenset({"at+jwt", "application/at+jwt"})
+
+
+@final
+class OidcTokenHandler:
+    """Turns a third-party OIDC access token into the badge naming its user.
+
+    Verifies a token issued by an OIDC provider — not one this application
+    signs: its signature against the provider's keys, its ``iss`` among the
+    trusted issuers, its ``aud`` against the expected audience, and its
+    ``exp`` / ``nbf`` / ``iat`` against the clock with a leeway. An ``exp`` is
+    required — a token that never expires is refused. The algorithms
+    are an explicit allow-list refusing ``none`` and any symmetric ``HS*`` (a
+    third-party token is signed with the issuer's private key, verified with its
+    public one). When ``enforce_at_jwt_type`` is set the header's ``typ`` must be
+    ``at+jwt`` (RFC 9068).
+
+    The identifier is read from ``claim`` (``sub`` by default). With no provider
+    the claims are the user — an
+    :class:`~xtr_security_core.user.oidc_user.OidcUser`; with one, its
+    identifier loads the user, the claims handed alongside to a provider that
+    reads them. The badge carries the granted ``scope`` (from the ``scope``
+    string or the ``scp`` list), the ``client_id``, the ``jti`` and every claim.
+    Every failure becomes an
+    :class:`~xtr_security_http.exception.InvalidAccessTokenError`.
+    """
+
+    __slots__ = (
+        "_algorithms",
+        "_audience",
+        "_claim",
+        "_clock",
+        "_enforce_at_jwt_type",
+        "_issuers",
+        "_key_set_provider",
+        "_leeway",
+        "_user_provider",
+    )
+
+    def __init__(  # noqa: PLR0913 -- a wiring constructor; the verification knobs default
+        self,
+        key_set_provider: OidcKeySetProviderInterface,
+        *,
+        issuers: Sequence[str],
+        audience: str,
+        algorithms: Sequence[str] = ("RS256",),
+        claim: str = "sub",
+        leeway: int = 0,
+        enforce_at_jwt_type: bool = False,
+        clock: Callable[[], int],
+        user_provider: UserProviderInterface | None = None,
+    ) -> None:
+        """Record the provider, the trusted issuers, the audience and the knobs.
+
+        Raises:
+            InvalidArgumentError: When no issuer is given, or the algorithm
+                allow-list is empty or holds ``none`` or a symmetric ``HS*``.
+        """
+        algorithm_list = tuple(algorithms)
+        _check_algorithms(algorithm_list)
+        if not issuers:
+            raise InvalidArgumentError("An OIDC token handler needs at least one trusted issuer.")
+        self._key_set_provider = key_set_provider
+        self._issuers = tuple(issuers)
+        self._audience = audience
+        self._algorithms = algorithm_list
+        self._claim = claim
+        self._leeway = leeway
+        self._enforce_at_jwt_type = enforce_at_jwt_type
+        self._clock = clock
+        self._user_provider = user_provider
+
+    async def get_user_badge_from(self, access_token: str) -> UserBadge:
+        """Verify ``access_token`` and return the badge naming its user.
+
+        Raises:
+            InvalidAccessTokenError: When the token is malformed, wrongly
+                signed, from an untrusted issuer, for another audience, expired,
+                not yet valid, of the wrong ``typ``, or missing its identifier.
+        """
+        decoded = await self._decode(access_token)
+        claims = cast("Mapping[str, object]", decoded.claims)
+        self._validate(decoded, claims)
+        return self._badge_for(claims)
+
+    async def _decode(self, access_token: str) -> Token:
+        """Verify the signature, refetching the key set once on an unknown ``kid``.
+
+        Raises:
+            InvalidAccessTokenError: When the token cannot be verified.
+        """
+        try:
+            key_set = await self._key_set_provider.get_key_set()
+            return jwt.decode(access_token, key_set, algorithms=list(self._algorithms))
+        except InvalidKeyIdError as error:
+            return await self._decode_after_refresh(access_token, error)
+        except (JoseError, OidcKeySetError, ValueError) as error:
+            raise InvalidAccessTokenError(f"The token could not be verified: {error}") from error
+
+    async def _decode_after_refresh(self, access_token: str, cause: InvalidKeyIdError) -> Token:
+        """Refetch the key set once for a rotated key, then verify again.
+
+        Raises:
+            InvalidAccessTokenError: When the token still cannot be verified.
+        """
+        try:
+            key_set = await self._key_set_provider.get_key_set(force_refresh=True)
+            return jwt.decode(access_token, key_set, algorithms=list(self._algorithms))
+        except (JoseError, OidcKeySetError, ValueError) as error:
+            raise InvalidAccessTokenError(
+                f"The token names an unknown key: {cause}",
+            ) from error
+
+    def _validate(self, decoded: Token, claims: Mapping[str, object]) -> None:
+        """Check the ``typ`` header and the registered claims.
+
+        Raises:
+            InvalidAccessTokenError: When the type or a claim does not hold.
+        """
+        if self._enforce_at_jwt_type:
+            typ = decoded.header.get("typ")
+            if not isinstance(typ, str) or typ.lower() not in _AT_JWT_TYPES:
+                raise InvalidAccessTokenError("The token is not an at+jwt access token.")
+        options: dict[str, ClaimsOption] = {
+            "iss": {"essential": True, "values": list(self._issuers)},
+            "aud": {"essential": True, "value": self._audience},
+            "exp": {"essential": True},
+            self._claim: {"essential": True},
+        }
+        registry = JWTClaimsRegistry(now=self._clock(), leeway=self._leeway, **options)
+        try:
+            registry.validate(dict(claims))
+        except (JoseError, ValueError) as error:
+            raise InvalidAccessTokenError(f"The token's claims are not valid: {error}") from error
+
+    def _badge_for(self, claims: Mapping[str, object]) -> UserBadge:
+        """Build the badge for a verified token's claims.
+
+        Raises:
+            InvalidAccessTokenError: When the identifier claim is missing.
+        """
+        identifier = claims.get(self._claim)
+        if not isinstance(identifier, str) or not identifier:
+            raise InvalidAccessTokenError(
+                f'The token carries no usable "{self._claim}" claim.',
+            )
+        attributes: dict[str, object] = {
+            "scope": _scopes(claims),
+            "client_id": claims.get("client_id"),
+            "jti": claims.get("jti"),
+            "claims": dict(claims),
+        }
+        return UserBadge(identifier, user_loader=self._loader(claims), attributes=attributes)
+
+    def _loader(self, claims: Mapping[str, object]) -> UserLoader:
+        """Return the loader that turns the identifier into a user.
+
+        With no provider the claims are the user; with an attributes-based one
+        the claims travel to it; with a plain one only the identifier does.
+        """
+        provider = self._user_provider
+        claim = self._claim
+        if provider is None:
+
+            def load_from_claims(identifier: str) -> UserInterface:
+                del identifier
+                return OidcUser(claims, identifier_claim=claim)
+
+            return load_from_claims
+        if AttributesBasedUserProviderInterface in type(provider).__mro__:
+            attributed = cast("AttributesBasedUserProviderInterface", provider)
+
+            async def load_with_attributes(identifier: str) -> UserInterface:
+                return await attributed.load_user_by_identifier(identifier, claims)
+
+            return load_with_attributes
+
+        plain = provider
+
+        async def load_by_identifier(identifier: str) -> UserInterface:
+            return await plain.load_user_by_identifier(identifier)
+
+        return load_by_identifier
+
+
+def _check_algorithms(algorithms: tuple[str, ...]) -> None:
+    """Refuse an empty allow-list, ``none`` or a symmetric ``HS*``.
+
+    Raises:
+        InvalidArgumentError: When the allow-list is empty or holds a refused
+            algorithm.
+    """
+    if not algorithms:
+        raise InvalidArgumentError("An OIDC token handler needs at least one allowed algorithm.")
+    for algorithm in algorithms:
+        lowered = algorithm.lower()
+        if lowered == "none":
+            raise InvalidArgumentError('The algorithm "none" is never allowed.')
+        if lowered.startswith("hs"):
+            raise InvalidArgumentError(
+                f"The symmetric algorithm {algorithm!r} is not allowed for third-party tokens.",
+            )
+
+
+def _scopes(claims: Mapping[str, object]) -> list[str]:
+    """Read the granted scopes from the ``scope`` string or the ``scp`` list."""
+    scope = claims.get("scope")
+    if isinstance(scope, str):
+        return scope.split()
+    scp = claims.get("scp")
+    if isinstance(scp, (list, tuple)):
+        return [str(one) for one in cast("Sequence[object]", scp)]
+    return []

xtr_security_http/access_token/query_access_token_extractor.py

@@ -0,0 +1,51 @@
+"""An extractor that reads a bearer token from a query parameter."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from fastapi.security import APIKeyQuery
+from typing_extensions import override
+
+from .access_token_extractor_interface import AccessTokenExtractorInterface
+
+if TYPE_CHECKING:
+    from fastapi.security.base import SecurityBase
+    from starlette.requests import Request
+
+__all__ = ["QueryAccessTokenExtractor"]
+
+
+@final
+class QueryAccessTokenExtractor(AccessTokenExtractorInterface):
+    """Reads a token from a query parameter, ``access_token`` by default.
+
+    Built on FastAPI's :class:`~fastapi.security.APIKeyQuery` with
+    ``auto_error=False``, so a request without the parameter reads as ``None``.
+    Passing a bearer token in the URL is discouraged by RFC 6750, but some
+    clients can send it no other way; the extractor exists for them.
+
+    Attributes:
+        parameter_name: The query parameter the token is read from.
+    """
+
+    __slots__ = ("_parameter_name", "_query")
+
+    def __init__(self, parameter_name: str = "access_token") -> None:
+        """Build the extractor for the ``parameter_name`` query parameter."""
+        self._parameter_name = parameter_name
+        self._query = APIKeyQuery(
+            name=parameter_name,
+            auto_error=False,
+            scheme_name=parameter_name,
+        )
+
+    @override
+    async def extract_access_token(self, request: Request) -> str | None:
+        """Return the token in the query parameter, or ``None`` when it is absent."""
+        return await self._query(request)
+
+    @override
+    def scheme(self) -> SecurityBase:
+        """Return the query-parameter scheme this extractor reads and documents by."""
+        return self._query

xtr_security_http/authentication/__init__.py

@@ -0,0 +1,24 @@
+"""Running a firewall's authenticators, and the handlers around a login.
+
+Also the security-level policy that decides which authentication failures are
+hidden from the client, and the helpers that apply it.
+"""
+
+from __future__ import annotations
+
+from ._sensitive import is_sensitive, mask
+from .authentication_failure_handler_interface import AuthenticationFailureHandlerInterface
+from .authentication_success_handler_interface import AuthenticationSuccessHandlerInterface
+from .authenticator_manager import AuthenticatorManager
+from .authenticator_manager_interface import AuthenticatorManagerInterface
+from .expose_security_level import ExposeSecurityLevel
+
+__all__ = [
+    "AuthenticationFailureHandlerInterface",
+    "AuthenticationSuccessHandlerInterface",
+    "AuthenticatorManager",
+    "AuthenticatorManagerInterface",
+    "ExposeSecurityLevel",
+    "is_sensitive",
+    "mask",
+]

xtr_security_http/authentication/_sensitive.py

@@ -0,0 +1,60 @@
+"""Deciding which authentication failures to hide, and hiding them.
+
+Some failures name a fact worth hiding: that a user exists, or that an account
+is only disabled. Whether such a failure reaches the client as itself or as a
+plain rejection is set by an :class:`ExposeSecurityLevel`. These two helpers
+are the whole of that rule — one reads it, the other applies it — and they are
+private to the package: callers reach them through the re-exports on
+:mod:`xtr_security_http.authentication`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from xtr_security_core.exception import (
+    AccountStatusError,
+    BadCredentialsError,
+    CustomUserMessageAccountStatusError,
+    UserNotFoundError,
+)
+
+from .expose_security_level import ExposeSecurityLevel
+
+if TYPE_CHECKING:
+    from xtr_security_core.exception import AuthenticationError
+
+__all__ = ["is_sensitive", "mask"]
+
+
+def is_sensitive(error: AuthenticationError, level: ExposeSecurityLevel) -> bool:
+    """Tell whether ``error`` should be hidden from the client at ``level``.
+
+    An account-status failure that carries its own client-facing message is
+    never sensitive: it was raised to be shown. Otherwise, at ``ALL`` nothing
+    is hidden; at ``ACCOUNT_STATUS`` a disabled or locked account is revealed
+    but an unknown user is not; at ``NONE`` both are hidden.
+    """
+    if isinstance(error, CustomUserMessageAccountStatusError):
+        return False
+    if level is ExposeSecurityLevel.ALL:
+        return False
+    if isinstance(error, AccountStatusError):
+        return level is ExposeSecurityLevel.NONE
+    return isinstance(error, UserNotFoundError)
+
+
+def mask(error: AuthenticationError, level: ExposeSecurityLevel) -> AuthenticationError:
+    """Return ``error``, or a bad-credentials error hiding it, at ``level``.
+
+    A hidden failure becomes a
+    :class:`~xtr_security_core.exception.BadCredentialsError` chained to the real
+    one, so the client learns only that its credentials failed while the cause
+    survives on ``__cause__`` for the log.
+    """
+    if not is_sensitive(error, level):
+        return error
+    masked = BadCredentialsError()
+    masked.__cause__ = error
+    masked.__suppress_context__ = True
+    return masked

xtr_security_http/authentication/authentication_failure_handler_interface.py

@@ -0,0 +1,31 @@
+"""What answers a request once its authentication fails."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+    from starlette.responses import Response
+    from xtr_security_core.exception import AuthenticationError
+
+__all__ = ["AuthenticationFailureHandlerInterface"]
+
+
+@runtime_checkable
+class AuthenticationFailureHandlerInterface(Protocol):
+    """Turns a failed authentication into a response, or leaves it to the entry point.
+
+    An authenticator delegates its failure reaction here: a handler may answer
+    the request itself — a challenge, a redirect back to a form — or return
+    ``None`` to let the failure carry on and be turned into a response by the
+    firewall's entry point.
+    """
+
+    async def on_authentication_failure(
+        self,
+        request: Request,
+        error: AuthenticationError,
+    ) -> Response | None:
+        """Answer ``request`` for the failure ``error``, or return ``None``."""
+        ...

xtr_security_http/authentication/authentication_success_handler_interface.py

@@ -0,0 +1,31 @@
+"""What answers a request once its authentication succeeds."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+    from starlette.responses import Response
+    from xtr_security_core.authentication.token.token_interface import TokenInterface
+
+__all__ = ["AuthenticationSuccessHandlerInterface"]
+
+
+@runtime_checkable
+class AuthenticationSuccessHandlerInterface(Protocol):
+    """Turns a successful authentication into a response, or lets the request go on.
+
+    An authenticator delegates its success reaction here: a handler may answer
+    the request itself — a redirect after a form login — or return ``None`` to
+    let the request reach its endpoint with the token now set.
+    """
+
+    async def on_authentication_success(
+        self,
+        request: Request,
+        token: TokenInterface,
+        firewall_name: str,
+    ) -> Response | None:
+        """Answer ``request`` for the authenticated ``token``, or return ``None``."""
+        ...