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

xtr_security_http/authentication/authenticator_manager.py

@@ -0,0 +1,232 @@
+"""Drives a firewall's authenticators over one request, in the fixed order."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast, final
+
+from typing_extensions import override
+from xtr_security_core.event.authentication_success_event import AuthenticationSuccessEvent
+from xtr_security_core.exception import AuthenticationError, BadCredentialsError
+
+from xtr_security_http.authentication._sensitive import mask
+from xtr_security_http.authentication.expose_security_level import ExposeSecurityLevel
+from xtr_security_http.event.authentication_token_created_event import (
+    AuthenticationTokenCreatedEvent,
+)
+from xtr_security_http.event.check_passport_event import CheckPassportEvent
+from xtr_security_http.event.login_failure_event import LoginFailureEvent
+from xtr_security_http.event.login_success_event import LoginSuccessEvent
+
+from .authenticator_manager_interface import AuthenticatorManagerInterface
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from starlette.requests import Request
+    from starlette.responses import Response
+    from xtr_event_dispatcher_contracts import EventDispatcherInterface
+    from xtr_logging_contracts import LoggerInterface
+    from xtr_security_core.authentication.token.storage.token_storage_interface import (
+        TokenStorageInterface,
+    )
+    from xtr_security_core.authentication.token.token_interface import TokenInterface
+
+    from xtr_security_http.authenticator.authenticator_interface import AuthenticatorInterface
+    from xtr_security_http.authenticator.passport.badge.badge_interface import BadgeInterface
+    from xtr_security_http.authenticator.passport.passport import Passport
+
+__all__ = ["AuthenticatorManager"]
+
+#: Returned when a lazy authenticator did not apply — no credential was presented.
+_ABSTAINED: object = object()
+
+
+@final
+class AuthenticatorManager(AuthenticatorManagerInterface):
+    """Runs the authenticators of one firewall and dispatches the events around each step.
+
+    The order is fixed and is the whole contract of this class:
+
+    1. the first authenticator whose :meth:`supports` is not ``False`` reads
+       the request into a passport;
+    2. a :class:`~xtr_security_http.event.check_passport_event.CheckPassportEvent`
+       lets listeners resolve the badges — set the user loader, verify a
+       password;
+    3. every badge must report itself resolved, and every required badge must
+       be present, or a
+       :class:`~xtr_security_core.exception.BadCredentialsError` is raised;
+    4. the user is loaded and a token is created, then an
+       :class:`~xtr_security_http.event.authentication_token_created_event.AuthenticationTokenCreatedEvent`
+       lets a listener replace it;
+    5. an
+       :class:`~xtr_security_core.event.authentication_success_event.AuthenticationSuccessEvent`
+       runs the post-authentication account check;
+    6. the token is stored, the authenticator's success handler runs, and a
+       :class:`~xtr_security_http.event.login_success_event.LoginSuccessEvent`
+       lets a listener migrate a password or replace the response.
+
+    A failure anywhere is masked to the configured level, announced as a
+    :class:`~xtr_security_http.event.login_failure_event.LoginFailureEvent`,
+    offered to the authenticator's failure handler, and — if nobody answered —
+    re-raised for the firewall's entry point to turn into a challenge.
+    """
+
+    __slots__ = (
+        "_authenticators",
+        "_event_dispatcher",
+        "_expose_security_errors",
+        "_firewall_name",
+        "_logger",
+        "_required_badges",
+        "_token_storage",
+    )
+
+    def __init__(  # noqa: PLR0913, PLR0917 -- a wiring constructor; every dependency is required
+        self,
+        authenticators: Sequence[AuthenticatorInterface],
+        token_storage: TokenStorageInterface,
+        event_dispatcher: EventDispatcherInterface,
+        firewall_name: str,
+        logger: LoggerInterface | None = None,
+        expose_security_errors: ExposeSecurityLevel = ExposeSecurityLevel.NONE,
+        required_badges: Sequence[type[BadgeInterface]] = (),
+    ) -> None:
+        """Record the authenticators, the storage, the dispatcher and the policy."""
+        self._authenticators = tuple(authenticators)
+        self._token_storage = token_storage
+        self._event_dispatcher = event_dispatcher
+        self._firewall_name = firewall_name
+        self._logger = logger
+        self._expose_security_errors = expose_security_errors
+        self._required_badges = tuple(required_badges)
+
+    @override
+    def supports(self, request: Request) -> bool | None:
+        """Tell whether an authenticator handles ``request``: ``True``, ``None`` or ``False``."""
+        lazy = False
+        for authenticator in self._authenticators:
+            supported = authenticator.supports(request)
+            if supported is True:
+                return True
+            if supported is None:
+                lazy = True
+        return None if lazy else False
+
+    @override
+    async def authenticate_request(self, request: Request) -> Response | None:
+        """Authenticate ``request`` through the first supporting authenticator.
+
+        A lazy authenticator — one whose :meth:`supports` returned ``None`` —
+        that raises a plain
+        :class:`~xtr_security_core.exception.BadCredentialsError` is read as "no
+        credential presented": it did not apply, so the next authenticator is
+        tried and, failing that, the request stays anonymous. Any other failure
+        from it, and every failure from an eager authenticator, is a real
+        authentication failure the firewall turns into a challenge.
+        """
+        for authenticator in self._authenticators:
+            supported = authenticator.supports(request)
+            if supported is False:
+                continue
+            outcome = await self._authenticate(authenticator, request, lazy=supported is None)
+            if outcome is not _ABSTAINED:
+                return cast("Response | None", outcome)
+        return None
+
+    async def _authenticate(
+        self,
+        authenticator: AuthenticatorInterface,
+        request: Request,
+        *,
+        lazy: bool,
+    ) -> Response | object | None:
+        """Carry one authenticator through the sequence, or abstain when it does not apply."""
+        passport: Passport | None = None
+        try:
+            passport = await authenticator.authenticate(request)
+            _ = await self._event_dispatcher.dispatch(CheckPassportEvent(authenticator, passport))
+            self._ensure_resolved(passport)
+            _ = await passport.get_user()
+            token = await authenticator.create_token(passport, self._firewall_name)
+            token = await self._token_created(token, passport)
+            _ = await self._event_dispatcher.dispatch(AuthenticationSuccessEvent(token))
+        except BadCredentialsError as error:
+            if lazy and passport is None:
+                return _ABSTAINED
+            return await self._on_failure(authenticator, request, passport, error)
+        except AuthenticationError as error:
+            return await self._on_failure(authenticator, request, passport, error)
+        return await self._on_success(authenticator, request, passport, token)
+
+    def _ensure_resolved(self, passport: Passport) -> None:
+        """Raise when a badge is unresolved or a required badge is absent."""
+        passport.check_if_completely_resolved()
+        for badge in self._required_badges:
+            if not passport.has_badge(badge):
+                raise BadCredentialsError(
+                    f"The passport is missing the required badge {badge.__name__}.",
+                )
+
+    async def _token_created(self, token: TokenInterface, passport: Passport) -> TokenInterface:
+        """Announce the created token and return whichever token a listener settled on."""
+        event = AuthenticationTokenCreatedEvent(token, passport)
+        _ = await self._event_dispatcher.dispatch(event)
+        return event.get_authenticated_token()
+
+    async def _on_success(
+        self,
+        authenticator: AuthenticatorInterface,
+        request: Request,
+        passport: Passport,
+        token: TokenInterface,
+    ) -> Response | None:
+        """Store the token, run the success handler, then announce the login."""
+        self._token_storage.set_token(token)
+        if self._logger is not None:
+            self._logger.info(
+                "Authenticated the request.",
+                {"firewall": self._firewall_name, "user": token.get_user_identifier()},
+            )
+        response = await authenticator.on_authentication_success(
+            request,
+            token,
+            self._firewall_name,
+        )
+        event = LoginSuccessEvent(
+            authenticator,
+            passport,
+            token,
+            request,
+            response,
+            self._firewall_name,
+        )
+        _ = await self._event_dispatcher.dispatch(event)
+        return event.get_response()
+
+    async def _on_failure(
+        self,
+        authenticator: AuthenticatorInterface,
+        request: Request,
+        passport: Passport | None,
+        error: AuthenticationError,
+    ) -> Response | None:
+        """Mask the error, announce the failure, offer it to the handler, then re-raise.
+
+        Raises:
+            AuthenticationError: The masked error, when no listener or handler
+                answered it — the firewall turns it into a challenge.
+        """
+        masked = mask(error, self._expose_security_errors)
+        if self._logger is not None:
+            self._logger.info(
+                "Authentication failed.",
+                {"firewall": self._firewall_name, "error": type(error).__name__},
+            )
+        event = LoginFailureEvent(masked, authenticator, request, passport, self._firewall_name)
+        _ = await self._event_dispatcher.dispatch(event)
+        if event.get_response() is not None:
+            return event.get_response()
+        response = await authenticator.on_authentication_failure(request, masked)
+        if response is not None:
+            return response
+        raise masked

xtr_security_http/authentication/authenticator_manager_interface.py

@@ -0,0 +1,40 @@
+"""What drives a firewall's authenticators over one request."""
+
+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
+
+__all__ = ["AuthenticatorManagerInterface"]
+
+
+@runtime_checkable
+class AuthenticatorManagerInterface(Protocol):
+    """Runs a firewall's authenticators over a request, settling on a token or a failure.
+
+    Asks each authenticator whether it supports the request, authenticates
+    through the first that does, checks the passport, creates and stores the
+    token, and dispatches the events around each step. It answers with a
+    response only when a success or failure handler produced one; otherwise the
+    request goes on with its token set on the storage.
+    """
+
+    def supports(self, request: Request) -> bool | None:
+        """Tell whether any authenticator handles ``request``.
+
+        ``None`` means no authenticator is sure yet — a lazy one that would try
+        only if a credential were present.
+        """
+        ...
+
+    async def authenticate_request(self, request: Request) -> Response | None:
+        """Authenticate ``request``, returning a handler's response if one answered.
+
+        Raises:
+            AuthenticationError: When authentication fails and no failure
+                handler answered it — the firewall turns it into a challenge.
+        """
+        ...

xtr_security_http/authentication/expose_security_level.py

@@ -0,0 +1,27 @@
+"""How much of an authentication failure a client is allowed to learn."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+__all__ = ["ExposeSecurityLevel"]
+
+
+class ExposeSecurityLevel(Enum):
+    """How much of the real reason an authentication failure may reveal.
+
+    Telling a client precisely why authentication failed helps an attacker:
+    that a user exists, or that an account is merely disabled rather than
+    unknown, is a way to probe. This level decides how much leaks out; anything
+    hidden is reported to the client as plain bad credentials.
+
+    - ``NONE`` — reveal nothing: unknown users and account-status failures
+      alike become bad credentials. The safe default.
+    - ``ACCOUNT_STATUS`` — reveal that an account is disabled, locked or
+      expired, but still hide whether a user exists.
+    - ``ALL`` — reveal every failure as it happened. For development.
+    """
+
+    NONE = "none"
+    ACCOUNT_STATUS = "account_status"
+    ALL = "all"

xtr_security_http/authenticator/__init__.py

@@ -0,0 +1,9 @@
+"""The authenticators a firewall runs, and the passports they produce."""
+
+from __future__ import annotations
+
+from .abstract_authenticator import AbstractAuthenticator
+from .access_token_authenticator import AccessTokenAuthenticator
+from .authenticator_interface import AuthenticatorInterface
+
+__all__ = ["AbstractAuthenticator", "AccessTokenAuthenticator", "AuthenticatorInterface"]

xtr_security_http/authenticator/abstract_authenticator.py

@@ -0,0 +1,66 @@
+"""A starting point for an authenticator: the token, and no-op hooks."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from typing_extensions import override
+
+from xtr_security_http.authenticator.token.post_authentication_token import PostAuthenticationToken
+
+from .authenticator_interface import AuthenticatorInterface
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+    from starlette.responses import Response
+    from xtr_security_core.authentication.token.token_interface import TokenInterface
+    from xtr_security_core.exception import AuthenticationError
+
+    from .passport.passport import Passport
+
+__all__ = ["AbstractAuthenticator"]
+
+
+class AbstractAuthenticator(  # pyright: ignore[reportImplicitAbstractClass]  -- subclasses implement supports/authenticate
+    AuthenticatorInterface,
+):
+    """The parts of an authenticator every kind shares.
+
+    Turns a resolved passport into a
+    :class:`~xtr_security_http.authenticator.token.post_authentication_token.PostAuthenticationToken`
+    carrying the user and its roles, and answers both ``on_authentication_*``
+    hooks with ``None`` — letting the request go on. A concrete authenticator
+    overrides :meth:`supports` and :meth:`authenticate`, and either hook when
+    it wants to answer the request itself.
+    """
+
+    @override
+    async def create_token(self, passport: Passport, firewall_name: str) -> TokenInterface:
+        """Build a post-authentication token for the passport's user and roles.
+
+        The user is read from the passport's user badge, which the passport
+        check already loaded, so this call does no I/O.
+        """
+        user = passport.get_user_badge().get_loaded_user()
+        return PostAuthenticationToken(user, firewall_name, user.get_roles())
+
+    @override
+    async def on_authentication_success(
+        self,
+        request: Request,
+        token: TokenInterface,
+        firewall_name: str,
+    ) -> Response | None:
+        """Answer nothing: the request goes on to its endpoint."""
+        del request, token, firewall_name
+        return None
+
+    @override
+    async def on_authentication_failure(
+        self,
+        request: Request,
+        error: AuthenticationError,
+    ) -> Response | None:
+        """Answer nothing: the failure is turned into a challenge elsewhere."""
+        del request, error
+        return None

xtr_security_http/authenticator/access_token_authenticator.py

@@ -0,0 +1,199 @@
+"""The authenticator that proves a caller by a bearer access token."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, cast, final
+
+from starlette.responses import JSONResponse
+from typing_extensions import override
+from xtr_security_core.exception import AuthenticationError, BadCredentialsError
+
+from xtr_security_http.authenticator.passport.self_validating_passport import SelfValidatingPassport
+from xtr_security_http.authorization.oauth2_scope_voter import OAuth2ScopeVoter
+from xtr_security_http.entry_point.authentication_entry_point_interface import (
+    AuthenticationEntryPointInterface,
+)
+from xtr_security_http.exception.invalid_access_token_error import InvalidAccessTokenError
+
+from .abstract_authenticator import AbstractAuthenticator
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from starlette.requests import Request
+    from starlette.responses import Response
+    from xtr_security_core.authentication.token.token_interface import TokenInterface
+    from xtr_security_core.user.user_interface import UserInterface
+    from xtr_security_core.user.user_provider_interface import UserProviderInterface
+
+    from xtr_security_http.access_token.access_token_extractor_interface import (
+        AccessTokenExtractorInterface,
+    )
+    from xtr_security_http.access_token.access_token_handler_interface import (
+        AccessTokenHandlerInterface,
+    )
+    from xtr_security_http.authentication.authentication_failure_handler_interface import (
+        AuthenticationFailureHandlerInterface,
+    )
+    from xtr_security_http.authentication.authentication_success_handler_interface import (
+        AuthenticationSuccessHandlerInterface,
+    )
+    from xtr_security_http.authenticator.passport.passport import Passport
+
+__all__ = ["AccessTokenAuthenticator"]
+
+
+@final
+class AccessTokenAuthenticator(AbstractAuthenticator, AuthenticationEntryPointInterface):
+    """Authenticates a request by a bearer access token, and challenges when it is absent or bad.
+
+    An extractor reads the token out of the request; a handler validates it and
+    returns a user badge. The passport is self-validating — the token already
+    proved the user — so no credentials are checked. The badge's ``scope``
+    attribute (a list, or a space-separated string) becomes the token's
+    ``oauth2_scope`` attribute, the one
+    :class:`~xtr_security_http.authorization.oauth2_scope_voter.OAuth2ScopeVoter`
+    reads.
+
+    As the firewall's entry point it also answers an unauthenticated or failed
+    request with the RFC 6750 ``WWW-Authenticate: Bearer`` challenge — a bare
+    one when no token was sent, ``error="invalid_token"`` when one was rejected.
+
+    Attributes:
+        realm: The protection realm named in the challenge, when set.
+    """
+
+    #: The token attribute the copied scopes are stored under.
+    SCOPE_ATTRIBUTE: ClassVar[str] = OAuth2ScopeVoter.SCOPE_ATTRIBUTE
+
+    #: The badge attribute the handler stores the granted scopes under.
+    BADGE_SCOPE_ATTRIBUTE: ClassVar[str] = "scope"
+
+    __slots__: ClassVar[tuple[str, ...]] = (
+        "_extractor",
+        "_failure_handler",
+        "_handler",
+        "_realm",
+        "_success_handler",
+        "_user_provider",
+    )
+
+    def __init__(  # noqa: PLR0913, PLR0917 -- a wiring constructor; the handlers are optional peers
+        self,
+        handler: AccessTokenHandlerInterface,
+        extractor: AccessTokenExtractorInterface,
+        user_provider: UserProviderInterface | None = None,
+        success_handler: AuthenticationSuccessHandlerInterface | None = None,
+        failure_handler: AuthenticationFailureHandlerInterface | None = None,
+        realm: str | None = None,
+    ) -> None:
+        """Record the handler, extractor, optional provider, handlers and realm."""
+        self._handler = handler
+        self._extractor = extractor
+        self._user_provider = user_provider
+        self._success_handler = success_handler
+        self._failure_handler = failure_handler
+        self._realm = realm
+
+    @override
+    def supports(self, request: Request) -> bool | None:
+        """Handle the request only when it carries a token this extractor reads.
+
+        Returns ``None`` — not ``False`` — when no token is present, so the
+        firewall leaves the request anonymous rather than failing it; a
+        protected route then challenges through the entry point.
+        """
+        del request
+        return None
+
+    @override
+    async def authenticate(self, request: Request) -> Passport:
+        """Read and validate the token, and build a self-validating passport.
+
+        Raises:
+            AuthenticationError: When no token is present, or the handler
+                rejects the one that is.
+        """
+        token = await self._extractor.extract_access_token(request)
+        if token is None:
+            raise BadCredentialsError("No access token was found in the request.")
+        badge = await self._handler.get_user_badge_from(token)
+        if self._user_provider is not None and badge.get_user_loader() is None:
+            provider = self._user_provider
+
+            async def load(identifier: str) -> UserInterface:
+                return await provider.load_user_by_identifier(identifier)
+
+            badge.set_user_loader(load)
+        passport = SelfValidatingPassport(badge)
+        scope = badge.get_attributes().get(self.BADGE_SCOPE_ATTRIBUTE)
+        if scope is not None:
+            passport.set_attribute(self.SCOPE_ATTRIBUTE, scope)
+        return passport
+
+    @override
+    async def create_token(self, passport: Passport, firewall_name: str) -> TokenInterface:
+        """Build the token and copy the passport's scope onto it as ``oauth2_scope``."""
+        token = await super().create_token(passport, firewall_name)
+        scope = passport.get_attribute(self.SCOPE_ATTRIBUTE)
+        if scope is not None:
+            token.set_attribute(self.SCOPE_ATTRIBUTE, self._normalize_scope(scope))
+        return token
+
+    @override
+    async def on_authentication_success(
+        self,
+        request: Request,
+        token: TokenInterface,
+        firewall_name: str,
+    ) -> Response | None:
+        """Delegate to the success handler, or let the request go on."""
+        if self._success_handler is not None:
+            return await self._success_handler.on_authentication_success(
+                request,
+                token,
+                firewall_name,
+            )
+        return None
+
+    @override
+    async def on_authentication_failure(
+        self,
+        request: Request,
+        error: AuthenticationError,
+    ) -> Response | None:
+        """Delegate to the failure handler, or let the entry point challenge."""
+        if self._failure_handler is not None:
+            return await self._failure_handler.on_authentication_failure(request, error)
+        return None
+
+    @override
+    async def start(self, request: Request, error: AuthenticationError | None = None) -> Response:
+        """Answer an unauthenticated or failed request with an RFC 6750 challenge.
+
+        A rejected token — an
+        :class:`InvalidAccessTokenError` — draws the
+        ``error="invalid_token"`` challenge and a matching body; a request that
+        carried no token, or one only lacking authentication, draws a bare
+        ``Bearer`` challenge.
+        """
+        del request
+        parts = ["Bearer"]
+        if self._realm is not None:
+            parts.append(f'realm="{self._realm}"')
+        body: dict[str, str] = {}
+        if isinstance(error, InvalidAccessTokenError):
+            parts.append('error="invalid_token"')
+            parts.append(f'error_description="{error.get_message_key()}"')
+            body = {"error": "invalid_token"}
+        challenge = parts[0] + (" " + ", ".join(parts[1:]) if len(parts) > 1 else "")
+        return JSONResponse(body, status_code=401, headers={"WWW-Authenticate": challenge})
+
+    def _normalize_scope(self, scope: object) -> list[str]:
+        """Turn a scope list or space-separated string into a list of scopes."""
+        if isinstance(scope, str):
+            return scope.split()
+        if isinstance(scope, (list, tuple, set, frozenset)):
+            items: Iterable[object] = cast("Iterable[object]", scope)
+            return [str(one) for one in items]
+        return [str(scope)]

xtr_security_http/authenticator/authenticator_interface.py

@@ -0,0 +1,68 @@
+"""What an authenticator — one way of proving who is calling — answers to."""
+
+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
+    from xtr_security_core.exception import AuthenticationError
+
+    from .passport.passport import Passport
+
+__all__ = ["AuthenticatorInterface"]
+
+
+@runtime_checkable
+class AuthenticatorInterface(Protocol):
+    """One way of authenticating a request, from a bearer token to a form post.
+
+    A firewall runs its authenticators in order. Each is asked whether it
+    :meth:`supports` the request; the first that does authenticates it,
+    producing a passport the manager checks and turns into a token. The two
+    ``on_authentication_*`` hooks let an authenticator answer the request
+    itself — a redirect on success, a challenge on failure — rather than
+    letting the request go on to its endpoint.
+    """
+
+    def supports(self, request: Request) -> bool | None:
+        """Tell whether this authenticator handles ``request``.
+
+        ``True`` authenticates it and stops the others; ``False`` skips it;
+        ``None`` authenticates it but lets a later authenticator try too if
+        this one produces no token — a lazy authenticator with no credential
+        present in the request.
+        """
+        ...
+
+    async def authenticate(self, request: Request) -> Passport:
+        """Read ``request`` into a passport, before any badge is resolved.
+
+        Raises:
+            AuthenticationError: When the request cannot even be read into a
+                passport — a malformed token, a missing field.
+        """
+        ...
+
+    async def create_token(self, passport: Passport, firewall_name: str) -> TokenInterface:
+        """Turn a resolved ``passport`` into the token authentication settles on."""
+        ...
+
+    async def on_authentication_success(
+        self,
+        request: Request,
+        token: TokenInterface,
+        firewall_name: str,
+    ) -> Response | None:
+        """React to a successful authentication, optionally answering the request."""
+        ...
+
+    async def on_authentication_failure(
+        self,
+        request: Request,
+        error: AuthenticationError,
+    ) -> Response | None:
+        """React to a failed authentication, optionally answering the request."""
+        ...

xtr_security_http/authenticator/oidc/__init__.py

@@ -0,0 +1,7 @@
+"""The OIDC key material a firewall's access-token authenticator verifies with."""
+
+from __future__ import annotations
+
+from .oidc_jwks import OidcKeySetProviderInterface, StaticOidcKeySetProvider
+
+__all__ = ["OidcKeySetProviderInterface", "StaticOidcKeySetProvider"]