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

xtr_security_http/entry_point/authentication_entry_point_interface.py

@@ -0,0 +1,33 @@
+"""What starts authentication when a request reaches a protected resource unauthenticated."""
+
+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__ = ["AuthenticationEntryPointInterface"]
+
+
+@runtime_checkable
+class AuthenticationEntryPointInterface(Protocol):
+    """Answers an unauthenticated request with what it takes to authenticate.
+
+    When a request reaches a protected resource without proving who is calling,
+    the firewall's entry point turns that into a response: a ``401`` carrying
+    the challenge a bearer scheme expects, a redirect to a login form. The
+    error that led here, when there is one, shapes the challenge.
+    """
+
+    async def start(self, request: Request, error: AuthenticationError | None = None) -> Response:
+        """Return the response that asks ``request`` to authenticate.
+
+        Args:
+            request: The request that reached a protected resource.
+            error: The authentication error that led here, when one did, so the
+                challenge can name why — a bad token, insufficient scope.
+        """
+        ...

xtr_security_http/event/__init__.py

@@ -0,0 +1,20 @@
+"""The events raised at the HTTP edge, around a request's authentication.
+
+The passport check, the token created, and the login having succeeded or
+failed. Each derives the event contract's :class:`~xtr_event_dispatcher_contracts.Event`;
+:mod:`xtr_security_http.security_events` names them for a subscriber.
+"""
+
+from __future__ import annotations
+
+from .authentication_token_created_event import AuthenticationTokenCreatedEvent
+from .check_passport_event import CheckPassportEvent
+from .login_failure_event import LoginFailureEvent
+from .login_success_event import LoginSuccessEvent
+
+__all__ = [
+    "AuthenticationTokenCreatedEvent",
+    "CheckPassportEvent",
+    "LoginFailureEvent",
+    "LoginSuccessEvent",
+]

xtr_security_http/event/authentication_token_created_event.py

@@ -0,0 +1,48 @@
+"""The event that lets a listener replace the freshly created token."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from xtr_event_dispatcher_contracts import Event
+
+if TYPE_CHECKING:
+    from xtr_security_core.authentication.token.token_interface import TokenInterface
+
+    from xtr_security_http.authenticator.passport.passport import Passport
+
+__all__ = ["AuthenticationTokenCreatedEvent"]
+
+
+@final
+class AuthenticationTokenCreatedEvent(Event):
+    """Announces that a token was created for a passport, before it is put to use.
+
+    Dispatched right after an authenticator turned a resolved passport into a
+    token. A listener may read the passport's badges and attributes and
+    :meth:`set_authenticated_token` a token of its own — a richer one carrying
+    extra claims, say — which then becomes the token authentication settles on.
+
+    Not a frozen dataclass: replacing the token is the whole point, so the
+    token it carries is mutable state.
+
+    Attributes:
+        passport: The passport the token was created from.
+    """
+
+    def __init__(self, token: TokenInterface, passport: Passport) -> None:
+        """Record the created token and the passport it was made from."""
+        self._token = token
+        self._passport = passport
+
+    def get_authenticated_token(self) -> TokenInterface:
+        """Return the token as it currently stands, replacements included."""
+        return self._token
+
+    def set_authenticated_token(self, token: TokenInterface) -> None:
+        """Replace the token authentication will settle on with ``token``."""
+        self._token = token
+
+    def get_passport(self) -> Passport:
+        """Return the passport the token was created from."""
+        return self._passport

xtr_security_http/event/check_passport_event.py

@@ -0,0 +1,48 @@
+"""The event that lets listeners resolve and check a passport's badges."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from xtr_event_dispatcher_contracts import Event
+
+if TYPE_CHECKING:
+    from xtr_security_http.authenticator.authenticator_interface import AuthenticatorInterface
+    from xtr_security_http.authenticator.passport.passport import Passport
+
+__all__ = ["CheckPassportEvent"]
+
+
+@dataclass(frozen=True)
+class CheckPassportEvent(Event):
+    """Announces that a passport is ready for its badges to be resolved and checked.
+
+    Dispatched once an authenticator has produced a passport, before a token is
+    made from it. Listeners resolve the badges the authenticator left for them
+    — a user provider sets a
+    :class:`~xtr_security_http.authenticator.passport.badge.user_badge.UserBadge`'s
+    loader, a credentials listener verifies a password — each marking the badge
+    it handled resolved. Every badge must be resolved by the time the listeners
+    are done, or authentication fails.
+
+    The event is mutable in spirit: a listener reaches into the passport it
+    carries and changes the badges' state. The dataclass itself is frozen — the
+    authenticator and passport it names do not change — but stopping it skips
+    the listeners that have not run, exactly as any event.
+
+    Attributes:
+        authenticator: The authenticator that produced the passport.
+        passport: The passport whose badges are to be resolved and checked.
+    """
+
+    authenticator: AuthenticatorInterface
+    passport: Passport
+
+    def get_authenticator(self) -> AuthenticatorInterface:
+        """Return the authenticator that produced the passport."""
+        return self.authenticator
+
+    def get_passport(self) -> Passport:
+        """Return the passport whose badges are to be resolved and checked."""
+        return self.passport

xtr_security_http/event/login_failure_event.py

@@ -0,0 +1,79 @@
+"""The event announcing a failed authentication."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from xtr_event_dispatcher_contracts import Event
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+    from starlette.responses import Response
+    from xtr_security_core.exception import AuthenticationError
+
+    from xtr_security_http.authenticator.authenticator_interface import AuthenticatorInterface
+    from xtr_security_http.authenticator.passport.passport import Passport
+
+__all__ = ["LoginFailureEvent"]
+
+
+@final
+class LoginFailureEvent(Event):
+    """Announces that authentication failed, and lets a listener answer it.
+
+    Dispatched when an authenticator raised — after the error was masked, if
+    the firewall hides sensitive failures — before the authenticator's failure
+    handler runs. A listener reads the error and the passport that got as far
+    as it did, and may :meth:`set_response` to answer the failure itself,
+    short-circuiting the failure handler.
+
+    Not a frozen dataclass: setting the response mutates it.
+
+    Attributes:
+        firewall_name: The firewall the authentication ran under.
+    """
+
+    def __init__(  # noqa: PLR0913, PLR0917 -- an event carrying the failure's full context
+        self,
+        exception: AuthenticationError,
+        authenticator: AuthenticatorInterface,
+        request: Request,
+        passport: Passport | None,
+        firewall_name: str,
+        response: Response | None = None,
+    ) -> None:
+        """Record the error, authenticator, request, passport, firewall and response."""
+        self._exception = exception
+        self._authenticator = authenticator
+        self._request = request
+        self._passport = passport
+        self._firewall_name = firewall_name
+        self._response = response
+
+    def get_exception(self) -> AuthenticationError:
+        """Return the error authentication failed with."""
+        return self._exception
+
+    def get_authenticator(self) -> AuthenticatorInterface:
+        """Return the authenticator that failed to authenticate the request."""
+        return self._authenticator
+
+    def get_request(self) -> Request:
+        """Return the request that failed to authenticate."""
+        return self._request
+
+    def get_passport(self) -> Passport | None:
+        """Return the passport, if one was produced before the failure."""
+        return self._passport
+
+    def get_firewall_name(self) -> str:
+        """Return the firewall the authentication ran under."""
+        return self._firewall_name
+
+    def get_response(self) -> Response | None:
+        """Return the response a listener set to answer the failure, if any."""
+        return self._response
+
+    def set_response(self, response: Response | None) -> None:
+        """Answer the failure with ``response`` instead of the failure handler."""
+        self._response = response

xtr_security_http/event/login_success_event.py

@@ -0,0 +1,79 @@
+"""The event announcing a completed, stored authentication."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from xtr_event_dispatcher_contracts import Event
+
+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_http.authenticator.authenticator_interface import AuthenticatorInterface
+    from xtr_security_http.authenticator.passport.passport import Passport
+
+__all__ = ["LoginSuccessEvent"]
+
+
+@final
+class LoginSuccessEvent(Event):
+    """Announces that authentication succeeded, was stored, and produced a response.
+
+    Dispatched after the token has been set on the storage and the
+    authenticator's success handler has run. A listener reads the passport —
+    to migrate an outdated password hash, to write an audit line — and may
+    replace the response the success handler produced with one of its own.
+
+    Not a frozen dataclass: a listener replacing the response mutates it.
+
+    Attributes:
+        authenticator: The authenticator that authenticated the request.
+        firewall_name: The firewall the authentication ran under.
+    """
+
+    def __init__(  # noqa: PLR0913, PLR0917 -- an event carrying the login's full context
+        self,
+        authenticator: AuthenticatorInterface,
+        passport: Passport,
+        token: TokenInterface,
+        request: Request,
+        response: Response | None,
+        firewall_name: str,
+    ) -> None:
+        """Record the authenticator, passport, token, request, response and firewall."""
+        self._authenticator = authenticator
+        self._passport = passport
+        self._token = token
+        self._request = request
+        self._response = response
+        self._firewall_name = firewall_name
+
+    def get_authenticator(self) -> AuthenticatorInterface:
+        """Return the authenticator that authenticated the request."""
+        return self._authenticator
+
+    def get_passport(self) -> Passport:
+        """Return the passport authentication settled on."""
+        return self._passport
+
+    def get_authenticated_token(self) -> TokenInterface:
+        """Return the token authentication settled on."""
+        return self._token
+
+    def get_request(self) -> Request:
+        """Return the request that authenticated."""
+        return self._request
+
+    def get_response(self) -> Response | None:
+        """Return the response the success handler produced, if any."""
+        return self._response
+
+    def set_response(self, response: Response | None) -> None:
+        """Replace the response the login produced with ``response``."""
+        self._response = response
+
+    def get_firewall_name(self) -> str:
+        """Return the firewall the authentication ran under."""
+        return self._firewall_name

xtr_security_http/event_listener/__init__.py

@@ -0,0 +1,21 @@
+"""The listeners that resolve a passport, check an account, and migrate a hash.
+
+Each is a plain :class:`~xtr_event_dispatcher.EventSubscriberInterface`: the
+bundle registers one with ``dispatcher.add_subscriber(listener)`` on a
+firewall's own dispatcher, and its declared methods run at the priorities the
+authentication sequence needs.
+"""
+
+from __future__ import annotations
+
+from .check_credentials_listener import CheckCredentialsListener
+from .password_migrating_listener import PasswordMigratingListener
+from .user_checker_listener import UserCheckerListener
+from .user_provider_listener import UserProviderListener
+
+__all__ = [
+    "CheckCredentialsListener",
+    "PasswordMigratingListener",
+    "UserCheckerListener",
+    "UserProviderListener",
+]

xtr_security_http/event_listener/check_credentials_listener.py

@@ -0,0 +1,162 @@
+"""The listener that verifies a passport's credentials."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+import anyio.to_thread
+from typing_extensions import override
+from xtr_event_dispatcher import EventSubscriberInterface
+from xtr_password_hasher import PasswordAuthenticatedUserInterface
+from xtr_security_core.exception import BadCredentialsError, UserNotFoundError
+
+from xtr_security_http.authenticator.passport.badge.password_upgrade_badge import (
+    PasswordUpgradeBadge,
+)
+from xtr_security_http.authenticator.passport.credentials.custom_credentials import (
+    CustomCredentials,
+)
+from xtr_security_http.authenticator.passport.credentials.password_credentials import (
+    PasswordCredentials,
+)
+from xtr_security_http.event.check_passport_event import CheckPassportEvent
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from xtr_event_dispatcher import SubscribedEvents
+    from xtr_password_hasher import PasswordHasherInterface, UserPasswordHasherInterface
+
+__all__ = ["CheckCredentialsListener"]
+
+#: The priority the credentials check runs at — after the account pre-check.
+PRIORITY = 128
+
+#: The priority the unknown-user resolve runs at — before the account pre-check.
+#: Above :data:`~xtr_security_http.event_listener.user_checker_listener.PRE_PRIORITY`
+#: (256) and below
+#: :data:`~xtr_security_http.event_listener.user_provider_listener.PRIORITY` (2048),
+#: so the badge already has its loader and the dummy is burned here, where the user
+#: is first resolved, rather than letting a ``UserNotFoundError`` escape the account
+#: pre-check uncharged.
+RESOLVE_PRIORITY = 512
+
+#: The throwaway plaintext hashed once, so a burn is a constant-time verify.
+_DUMMY_PLAINTEXT = "dummy-password-for-timing"
+
+#: One dummy hash per hasher instance, computed eagerly and kept, so neither the
+#: first unknown-user call nor a per-request listener pays the hash cost twice.
+_DUMMY_HASHES: dict[int, str] = {}
+
+
+def _dummy_hash_for(hasher: PasswordHasherInterface) -> str:
+    """Return the dummy hash for ``hasher``, computing and caching it once."""
+    key = id(hasher)
+    cached = _DUMMY_HASHES.get(key)
+    if cached is None:
+        cached = hasher.hash(_DUMMY_PLAINTEXT)
+        _DUMMY_HASHES[key] = cached
+    return cached
+
+
+@final
+class CheckCredentialsListener(EventSubscriberInterface):
+    """Verifies the credentials a passport carries, on the passport check.
+
+    A ``PasswordCredentials`` is verified against the user's stored hash through
+    the user password hasher, run in a worker thread so the argon2 cost never
+    blocks the event loop; a match that used an outdated hash adds a
+    ``PasswordUpgradeBadge`` for the migrating listener. When the user is
+    unknown, a dummy hash is still verified — the timing of a bad username and a
+    bad password stays the same, so neither reveals which was wrong.
+
+    A ``CustomCredentials`` is verified by running its own check against the
+    resolved user.
+    """
+
+    __slots__ = ("_dummy_hash", "_dummy_hasher", "_hasher")
+
+    def __init__(
+        self,
+        hasher: UserPasswordHasherInterface,
+        dummy_hasher: PasswordHasherInterface | None = None,
+    ) -> None:
+        """Record the user password hasher and, for the timing guard, a dummy hasher."""
+        self._hasher = hasher
+        self._dummy_hasher = dummy_hasher
+        self._dummy_hash = _dummy_hash_for(dummy_hasher) if dummy_hasher is not None else None
+
+    @classmethod
+    @override
+    def get_subscribed_events(cls) -> Mapping[str | type, SubscribedEvents]:
+        """Burn for an unknown user before the pre-check, verify after it."""
+        return {
+            CheckPassportEvent: [
+                ("resolve_user", RESOLVE_PRIORITY),
+                ("check_passport", PRIORITY),
+            ],
+        }
+
+    async def resolve_user(self, event: CheckPassportEvent) -> None:
+        """Resolve the user a password passport names, burning a dummy on no user.
+
+        Runs before the account pre-check, which loads the user too and would
+        otherwise let a ``UserNotFoundError`` escape before the credentials
+        check could charge the dummy. Only a passport carrying an unresolved
+        password is touched; a known user is loaded (and cached) with no burn,
+        leaving the pre-check and the verify to run as before.
+
+        Raises:
+            BadCredentialsError: When no user answers the identifier, after a
+                dummy has been burned so the timing matches a wrong password.
+        """
+        passport = event.get_passport()
+        password_credentials = passport.get_badge(PasswordCredentials)
+        if password_credentials is None or password_credentials.is_resolved():
+            return
+        try:
+            _ = await passport.get_user()
+        except UserNotFoundError as error:
+            await self._burn_dummy(password_credentials.get_password())
+            raise BadCredentialsError("The presented credentials are invalid.") from error
+
+    async def check_passport(self, event: CheckPassportEvent) -> None:
+        """Verify the password and any custom credentials the passport carries."""
+        passport = event.get_passport()
+        password_credentials = passport.get_badge(PasswordCredentials)
+        if password_credentials is not None and not password_credentials.is_resolved():
+            await self._check_password(event, password_credentials)
+        custom_credentials = passport.get_badge(CustomCredentials)
+        if custom_credentials is not None and not custom_credentials.is_resolved():
+            user = await passport.get_user()
+            if not await custom_credentials.verify(user):
+                raise BadCredentialsError("The presented credentials are invalid.")
+
+    async def _check_password(
+        self,
+        event: CheckPassportEvent,
+        credentials: PasswordCredentials,
+    ) -> None:
+        """Verify the plaintext against the user's hash, burning a dummy on no user."""
+        passport = event.get_passport()
+        plaintext = credentials.get_password()
+        try:
+            user = await passport.get_user()
+        except UserNotFoundError as error:
+            await self._burn_dummy(plaintext)
+            raise BadCredentialsError("The presented credentials are invalid.") from error
+        if not isinstance(user, PasswordAuthenticatedUserInterface):
+            await self._burn_dummy(plaintext)
+            raise BadCredentialsError("The user carries no password to verify against.")
+        valid = await anyio.to_thread.run_sync(self._hasher.is_password_valid, user, plaintext)
+        if not valid:
+            raise BadCredentialsError("The presented credentials are invalid.")
+        credentials.mark_resolved()
+        if await anyio.to_thread.run_sync(self._hasher.needs_rehash, user):
+            _ = passport.add_badge(PasswordUpgradeBadge(plaintext))
+
+    async def _burn_dummy(self, plaintext: str) -> None:
+        """Verify a throwaway hash, so an unknown user costs the same as a wrong password."""
+        if self._dummy_hasher is None or self._dummy_hash is None:
+            return
+        _ = await anyio.to_thread.run_sync(self._dummy_hasher.verify, self._dummy_hash, plaintext)

xtr_security_http/event_listener/password_migrating_listener.py

@@ -0,0 +1,79 @@
+"""The listener that re-stores a verified password under the current hash."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+import anyio.to_thread
+from typing_extensions import override
+from xtr_event_dispatcher import EventSubscriberInterface
+from xtr_password_hasher import PasswordAuthenticatedUserInterface
+
+from xtr_security_http.authenticator.passport.badge.password_upgrade_badge import (
+    PasswordUpgradeBadge,
+)
+from xtr_security_http.event.login_success_event import LoginSuccessEvent
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from xtr_event_dispatcher import SubscribedEvents
+    from xtr_logging_contracts import LoggerInterface
+    from xtr_password_hasher import UserPasswordHasherInterface
+    from xtr_security_core.user.password_upgrader_interface import PasswordUpgraderInterface
+
+__all__ = ["PasswordMigratingListener"]
+
+
+@final
+class PasswordMigratingListener(EventSubscriberInterface):
+    """Rehashes and re-stores a password whose old hash the login flagged as outdated.
+
+    A successful login that verified against an outdated hash left a
+    :class:`~xtr_security_http.authenticator.passport.badge.password_upgrade_badge.PasswordUpgradeBadge`
+    on the passport. This listener rehashes the plaintext with the current
+    algorithm in a worker thread and hands the new hash to an upgrader to
+    store. The upgrade is best-effort — it runs after the caller is already
+    authenticated — so a failure is swallowed, and the hash is upgraded on the
+    next login instead.
+    """
+
+    __slots__ = ("_hasher", "_logger", "_password_upgrader")
+
+    def __init__(
+        self,
+        hasher: UserPasswordHasherInterface,
+        password_upgrader: PasswordUpgraderInterface | None = None,
+        logger: LoggerInterface | None = None,
+    ) -> None:
+        """Record the hasher, the upgrader used when a badge carries none, and a logger."""
+        self._hasher = hasher
+        self._password_upgrader = password_upgrader
+        self._logger = logger
+
+    @classmethod
+    @override
+    def get_subscribed_events(cls) -> Mapping[str | type, SubscribedEvents]:
+        """Listen to a successful, stored login."""
+        return {LoginSuccessEvent: "on_login_success"}
+
+    async def on_login_success(self, event: LoginSuccessEvent) -> None:
+        """Rehash the flagged password and store it through an upgrader."""
+        badge = event.get_passport().get_badge(PasswordUpgradeBadge)
+        if badge is None:
+            return
+        plaintext = badge.get_and_erase_plaintext_password()
+        if not plaintext:
+            return
+        upgrader = badge.get_password_upgrader() or self._password_upgrader
+        if upgrader is None:
+            return
+        user = event.get_authenticated_token().get_user()
+        if not isinstance(user, PasswordAuthenticatedUserInterface):
+            return
+        try:
+            new_hash = await anyio.to_thread.run_sync(self._hasher.hash_password, user, plaintext)
+            await upgrader.upgrade_password(user, new_hash)
+        except Exception:  # noqa: BLE001 -- an opportunistic upgrade must never fail the login
+            if self._logger is not None:
+                self._logger.warning("Could not upgrade the password hash after a login.", {})

xtr_security_http/event_listener/user_checker_listener.py

@@ -0,0 +1,60 @@
+"""The listener that runs the account checks around authentication."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+from xtr_event_dispatcher import EventSubscriberInterface
+from xtr_security_core.event.authentication_success_event import AuthenticationSuccessEvent
+
+from xtr_security_http.event.check_passport_event import CheckPassportEvent
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from xtr_event_dispatcher import SubscribedEvents
+    from xtr_security_core.user.user_checker_interface import UserCheckerInterface
+
+__all__ = ["UserCheckerListener"]
+
+#: The priority the pre-authentication check runs at on the passport check.
+PRE_PRIORITY = 256
+
+
+@final
+class UserCheckerListener(EventSubscriberInterface):
+    """Gates a user's own state, before credentials are checked and again after.
+
+    Before the credentials check, on the passport check, it loads the user and
+    runs the pre-authentication check — the account must not be disabled or
+    locked to go on. After a token is settled, on the success event, it runs
+    the post-authentication check against the user the token carries.
+    """
+
+    __slots__ = ("_user_checker",)
+
+    def __init__(self, user_checker: UserCheckerInterface) -> None:
+        """Record the checker the account state is gated by."""
+        self._user_checker = user_checker
+
+    @classmethod
+    @override
+    def get_subscribed_events(cls) -> Mapping[str | type, SubscribedEvents]:
+        """Check pre-auth on the passport check, post-auth on the success event."""
+        return {
+            CheckPassportEvent: ("pre_check_credentials", PRE_PRIORITY),
+            AuthenticationSuccessEvent: "post_check_credentials",
+        }
+
+    async def pre_check_credentials(self, event: CheckPassportEvent) -> None:
+        """Load the user and run the pre-authentication account check."""
+        user = await event.get_passport().get_user()
+        await self._user_checker.check_pre_auth(user)
+
+    async def post_check_credentials(self, event: AuthenticationSuccessEvent) -> None:
+        """Run the post-authentication account check against the token's user."""
+        token = event.get_authentication_token()
+        user = token.get_user()
+        if user is not None:
+            await self._user_checker.check_post_auth(user, token)