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

xtr_security_http/__init__.py

@@ -0,0 +1,143 @@
+"""The HTTP edge of xtr security: firewalls, authenticators and access tokens.
+
+The :class:`Firewall`, :class:`IsGranted` and :class:`CurrentUser` route
+surface, the authenticator and passport machinery a firewall runs, the bearer
+access-token extractors and the :class:`AccessTokenAuthenticator`, and the
+listeners and events around a login. Built on the security core; needs FastAPI
+and xtr-http-kernel.
+"""
+
+from __future__ import annotations
+
+from .access_map import AccessMap
+from .access_map_interface import AccessMapInterface
+from .access_token import (
+    AccessTokenExtractorInterface,
+    AccessTokenHandlerInterface,
+    ChainAccessTokenExtractor,
+    FormEncodedBodyExtractor,
+    HeaderAccessTokenExtractor,
+    QueryAccessTokenExtractor,
+)
+from .authentication import (
+    AuthenticationFailureHandlerInterface,
+    AuthenticationSuccessHandlerInterface,
+    AuthenticatorManager,
+    AuthenticatorManagerInterface,
+    ExposeSecurityLevel,
+    is_sensitive,
+    mask,
+)
+from .authenticator import (
+    AbstractAuthenticator,
+    AccessTokenAuthenticator,
+    AuthenticatorInterface,
+)
+from .authenticator.passport import Passport, SelfValidatingPassport
+from .authenticator.passport.badge import (
+    BadgeInterface,
+    PasswordUpgradeBadge,
+    PreAuthenticatedUserBadge,
+    UserBadge,
+)
+from .authenticator.passport.credentials import (
+    CredentialsInterface,
+    CustomCredentials,
+    PasswordCredentials,
+)
+from .authenticator.token import PostAuthenticationToken
+from .authorization import (
+    AccessDeniedHandlerInterface,
+    InsufficientScopeAccessDeniedHandler,
+    OAuth2ScopeVoter,
+    oauth2_scope,
+)
+from .decorator.current_user import CurrentUser
+from .decorator.is_granted import IsGranted
+from .decorator.is_granted_context import IsGrantedContext
+from .entry_point import AuthenticationEntryPointInterface
+from .event import (
+    AuthenticationTokenCreatedEvent,
+    CheckPassportEvent,
+    LoginFailureEvent,
+    LoginSuccessEvent,
+)
+from .event_listener import (
+    CheckCredentialsListener,
+    PasswordMigratingListener,
+    UserCheckerListener,
+    UserProviderListener,
+)
+from .exception import (
+    FirewallNotBootedError,
+    InvalidAccessTokenError,
+    UnknownFirewallError,
+)
+from .firewall import AccessListener, ExceptionListener, Firewall
+from .firewall_context_interface import FirewallContextInterface
+from .firewall_map import FirewallMap
+from .firewall_map_interface import FirewallMapInterface
+from .firewall_scheme import FirewallScheme
+from .firewall_scheme_registry import (
+    FirewallSchemeRegistry,
+    active_firewall_schemes,
+)
+
+__all__ = [
+    "AbstractAuthenticator",
+    "AccessDeniedHandlerInterface",
+    "AccessListener",
+    "AccessMap",
+    "AccessMapInterface",
+    "AccessTokenAuthenticator",
+    "AccessTokenExtractorInterface",
+    "AccessTokenHandlerInterface",
+    "AuthenticationEntryPointInterface",
+    "AuthenticationFailureHandlerInterface",
+    "AuthenticationSuccessHandlerInterface",
+    "AuthenticationTokenCreatedEvent",
+    "AuthenticatorInterface",
+    "AuthenticatorManager",
+    "AuthenticatorManagerInterface",
+    "BadgeInterface",
+    "ChainAccessTokenExtractor",
+    "CheckCredentialsListener",
+    "CheckPassportEvent",
+    "CredentialsInterface",
+    "CurrentUser",
+    "CustomCredentials",
+    "ExceptionListener",
+    "ExposeSecurityLevel",
+    "Firewall",
+    "FirewallContextInterface",
+    "FirewallMap",
+    "FirewallMapInterface",
+    "FirewallNotBootedError",
+    "FirewallScheme",
+    "FirewallSchemeRegistry",
+    "FormEncodedBodyExtractor",
+    "HeaderAccessTokenExtractor",
+    "InsufficientScopeAccessDeniedHandler",
+    "InvalidAccessTokenError",
+    "IsGranted",
+    "IsGrantedContext",
+    "LoginFailureEvent",
+    "LoginSuccessEvent",
+    "OAuth2ScopeVoter",
+    "Passport",
+    "PasswordCredentials",
+    "PasswordMigratingListener",
+    "PasswordUpgradeBadge",
+    "PostAuthenticationToken",
+    "PreAuthenticatedUserBadge",
+    "QueryAccessTokenExtractor",
+    "SelfValidatingPassport",
+    "UnknownFirewallError",
+    "UserBadge",
+    "UserCheckerListener",
+    "UserProviderListener",
+    "active_firewall_schemes",
+    "is_sensitive",
+    "mask",
+    "oauth2_scope",
+]

xtr_security_http/_runner.py

@@ -0,0 +1,134 @@
+"""The one pass a firewall makes over a request: authenticate, decide, scope.
+
+Shared by the bound and the unbound firewall dependency. Authentication runs
+once per firewall per request — memoised on ``request.state`` — while the
+access and scope decisions run on every call, since two schemes in one request
+carry different scope sets.
+
+The firewall map, the token storage and the access-decision manager are handed
+in by the caller — the firewall scheme fills them from the request scope with
+``Injected[...]`` markers — so nothing here reaches into the container.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from xtr_security_core.authentication.token.null_token import NullToken
+from xtr_security_core.authorization.access_decision import AccessDecision
+from xtr_security_core.exception import AccessDeniedError, AuthenticationError
+
+from ._state import (
+    AUTHENTICATED_FIREWALLS_KEY,
+    FIREWALL_CONTEXT_KEY,
+    TOKEN_KEY,
+    CarriedResponse,
+)
+from .authorization.oauth2_scope_voter import oauth2_scope
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from starlette.requests import Request
+    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_core.authorization.access_decision_manager_interface import (
+        AccessDecisionManagerInterface,
+    )
+
+    from xtr_security_http.firewall_context_interface import FirewallContextInterface
+    from xtr_security_http.firewall_map_interface import FirewallMapInterface
+
+__all__ = ["run_firewall"]
+
+
+async def run_firewall(  # noqa: PLR0913 -- the firewall's request, scopes and its three injected services
+    name: str | None,
+    request: Request,
+    scopes: Sequence[str],
+    *,
+    firewall_map: FirewallMapInterface,
+    token_storage: TokenStorageInterface,
+    access_decision_manager: AccessDecisionManagerInterface,
+) -> None:
+    """Run the firewall ``name`` (or the one matching ``request``) over ``request``.
+
+    Raises:
+        UnknownFirewallError: When ``name`` names no configured firewall.
+        AuthenticationError: When authentication fails and no handler answered.
+        AccessDeniedError: When an access rule or a scope is not granted.
+        CarriedResponse: When a success or failure handler produced a response.
+    """
+    context = _resolve(firewall_map, name, request)
+    if context is None or not context.security:
+        return
+
+    setattr(request.state, FIREWALL_CONTEXT_KEY, context)
+    await _authenticate_once(context, request)
+    token = token_storage.get_token() or NullToken()
+    setattr(request.state, TOKEN_KEY, token)
+    await context.access_listener.check_access(request, token)
+    if scopes:
+        await _check_scopes(access_decision_manager, request, token, scopes)
+
+
+def _resolve(
+    firewall_map: FirewallMapInterface, name: str | None, request: Request
+) -> FirewallContextInterface | None:
+    """Return the firewall to run: the one named, or the first that matches."""
+    if name is not None:
+        return firewall_map.get(name)
+    return firewall_map.match(request)
+
+
+async def _authenticate_once(context: FirewallContextInterface, request: Request) -> None:
+    """Authenticate the request under ``context`` at most once, memoised by name.
+
+    Raises:
+        AuthenticationError: When authentication fails, on this call and every
+            later one this request.
+        CarriedResponse: When a handler produced a response to send.
+    """
+    memo: dict[str, BaseException | None] = getattr(request.state, AUTHENTICATED_FIREWALLS_KEY, {})
+    if not memo:
+        setattr(request.state, AUTHENTICATED_FIREWALLS_KEY, memo)
+    if context.name in memo:
+        outcome = memo[context.name]
+        if isinstance(outcome, BaseException):
+            raise outcome
+        return
+    try:
+        response = await context.authenticator_manager.authenticate_request(request)
+    except AuthenticationError as error:
+        memo[context.name] = error
+        raise
+    memo[context.name] = None
+    if response is not None:
+        raise CarriedResponse(response)
+
+
+async def _check_scopes(
+    access_decision_manager: AccessDecisionManagerInterface,
+    request: Request,
+    token: TokenInterface,
+    scopes: Sequence[str],
+) -> None:
+    """Decide the accumulated scopes against the token, denying when short.
+
+    Raises:
+        AccessDeniedError: When the token lacks a required scope, carrying the
+            scope attribute so the exception listener answers with a scope
+            challenge.
+    """
+    del request
+    attribute = oauth2_scope(*scopes)
+    decision = AccessDecision()
+    granted = await access_decision_manager.decide(token, [attribute], access_decision=decision)
+    if not granted:
+        raise AccessDeniedError(
+            "The token does not carry the scope this resource requires.",
+            attributes=(attribute,),
+            access_decision=decision,
+        )

xtr_security_http/_state.py

@@ -0,0 +1,57 @@
+"""The keys the firewall stashes its per-request state on ``request.state`` under.
+
+Authentication runs once per request; the firewall that ran and the token it
+authenticated are stashed here for the dependencies and the exception listener
+that read them later in the same request. Every key is prefixed so it never
+collides with what an application keeps on the same object.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from starlette.responses import Response
+
+__all__ = [
+    "AUTHENTICATED_FIREWALLS_KEY",
+    "FIREWALL_CONTEXT_KEY",
+    "TOKEN_KEY",
+    "CarriedResponse",
+]
+
+_PREFIX: Final = "_xtr_security_"
+
+#: Maps a firewall name to the outcome of authenticating this request under it —
+#: the error authentication raised, or ``None`` for a plain success — so
+#: authentication stays one pass per firewall.
+AUTHENTICATED_FIREWALLS_KEY: Final = f"{_PREFIX}authenticated_firewalls"
+
+#: The firewall context in charge of the request, stashed by the firewall so the
+#: exception listener — a singleton with no access to the request scope — reads
+#: the entry point and handlers it needs without touching the container.
+FIREWALL_CONTEXT_KEY: Final = f"{_PREFIX}firewall_context"
+
+#: The token the firewall authenticated for the request, stashed alongside the
+#: context so the exception listener can weigh it without the token storage.
+TOKEN_KEY: Final = f"{_PREFIX}token"
+
+
+class CarriedResponse(Exception):  # noqa: N818 -- a control-flow carrier, not an error condition
+    """Carries a response an authentication handler produced out of the firewall.
+
+    A firewall runs as a dependency, which cannot itself answer a request; when
+    a success or failure handler produced a response, the firewall raises this
+    to carry it to the exception listener, which emits the response it holds.
+    Internal to the HTTP layer.
+
+    Attributes:
+        response: The response to send.
+    """
+
+    response: Response
+
+    def __init__(self, response: Response) -> None:
+        """Record the response to carry out to the exception listener."""
+        super().__init__("A security handler produced a response.")
+        self.response = response

xtr_security_http/access_map.py

@@ -0,0 +1,52 @@
+"""The ordered access-control rules of a firewall, matched against a request."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+
+from .access_map_interface import AccessMapInterface
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+    from .request_matcher.request_matcher_interface import RequestMatcherInterface
+
+__all__ = ["AccessMap"]
+
+
+@final
+class AccessMap(AccessMapInterface):
+    """Holds a firewall's access-control rules and finds the first a request matches.
+
+    A rule is a request matcher and the one attribute a claimed request must
+    satisfy, added with :meth:`add`. Rules are tried in the order they were
+    added; the first whose matcher claims the request decides it, so a broad
+    ``^/api`` rule must be added after the narrow ``^/api/admin`` it would
+    otherwise shadow. A request matching no rule has no attribute to satisfy —
+    the firewall lets it through, its access left to whatever the route itself
+    requires.
+    """
+
+    __slots__ = ("_rules",)
+
+    def __init__(self) -> None:
+        """Start with no rules; add each with :meth:`add`."""
+        self._rules: list[tuple[RequestMatcherInterface, str]] = []
+
+    def add(self, request_matcher: RequestMatcherInterface, attribute: str) -> None:
+        """Append a rule: ``attribute`` is required of a request ``request_matcher`` claims.
+
+        One attribute per rule is deliberate — a rule that needs two conditions
+        is two rules, or a single closure attribute.
+        """
+        self._rules.append((request_matcher, attribute))
+
+    @override
+    def get_attribute(self, request: Request) -> str | None:
+        """Return the attribute the first matching rule requires, or ``None``."""
+        for request_matcher, attribute in self._rules:
+            if request_matcher.matches(request):
+                return attribute
+        return None

xtr_security_http/access_map_interface.py

@@ -0,0 +1,24 @@
+"""What answers which attribute a request must satisfy for a firewall."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+__all__ = ["AccessMapInterface"]
+
+
+@runtime_checkable
+class AccessMapInterface(Protocol):
+    """Answers the attribute a request must hold, from a firewall's access rules.
+
+    The access listener asks this after authentication: the first rule whose
+    matcher claims the request names the one attribute the token must satisfy,
+    and a request no rule claims has none.
+    """
+
+    def get_attribute(self, request: Request) -> str | None:
+        """Return the attribute the first matching rule requires, or ``None``."""
+        ...

xtr_security_http/access_token/__init__.py

@@ -0,0 +1,19 @@
+"""Reading and validating bearer access tokens at the HTTP edge."""
+
+from __future__ import annotations
+
+from .access_token_extractor_interface import AccessTokenExtractorInterface
+from .access_token_handler_interface import AccessTokenHandlerInterface
+from .chain_access_token_extractor import ChainAccessTokenExtractor
+from .form_encoded_body_extractor import FormEncodedBodyExtractor
+from .header_access_token_extractor import HeaderAccessTokenExtractor
+from .query_access_token_extractor import QueryAccessTokenExtractor
+
+__all__ = [
+    "AccessTokenExtractorInterface",
+    "AccessTokenHandlerInterface",
+    "ChainAccessTokenExtractor",
+    "FormEncodedBodyExtractor",
+    "HeaderAccessTokenExtractor",
+    "QueryAccessTokenExtractor",
+]

xtr_security_http/access_token/access_token_extractor_interface.py

@@ -0,0 +1,31 @@
+"""What reads a bearer access token out of a request."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from fastapi.security.base import SecurityBase
+    from starlette.requests import Request
+
+__all__ = ["AccessTokenExtractorInterface"]
+
+
+@runtime_checkable
+class AccessTokenExtractorInterface(Protocol):
+    """Reads the token string from a request, and names the scheme it read it by.
+
+    An extractor knows where a token lives — an ``Authorization`` header, a
+    query parameter, a form field — and returns it as a string, or ``None``
+    when the request carries none. :meth:`scheme` returns the FastAPI security
+    object the extractor is built on, so the same object both parses the
+    request and describes the scheme in the generated OpenAPI.
+    """
+
+    async def extract_access_token(self, request: Request) -> str | None:
+        """Return the token in ``request``, or ``None`` when there is none."""
+        ...
+
+    def scheme(self) -> SecurityBase:
+        """Return the FastAPI security object this extractor parses and documents by."""
+        ...

xtr_security_http/access_token/access_token_handler_interface.py

@@ -0,0 +1,34 @@
+"""What turns a bearer access token into the badge naming its user."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from xtr_security_http.authenticator.passport.badge.user_badge import UserBadge
+
+__all__ = ["AccessTokenHandlerInterface"]
+
+
+@runtime_checkable
+class AccessTokenHandlerInterface(Protocol):
+    """Validates an access token and reports who it was issued for.
+
+    A handler is the whole of what makes a bearer token trustworthy: it
+    verifies the token — a JWT's signature and claims, an introspection
+    call — and returns a
+    :class:`~xtr_security_http.authenticator.passport.badge.user_badge.UserBadge`
+    naming the user, its attributes carrying the token's ``scope``,
+    ``client_id``, ``jti`` and remaining claims. This is the seam an OAuth2
+    resource server plugs its own token validation into.
+    """
+
+    async def get_user_badge_from(self, access_token: str) -> UserBadge:
+        """Return the user badge ``access_token`` proves.
+
+        Raises:
+            AuthenticationError: When the token cannot be trusted — most often
+                an :class:`InvalidAccessTokenError` for a malformed, expired or
+                wrongly signed token.
+        """
+        ...

xtr_security_http/access_token/chain_access_token_extractor.py

@@ -0,0 +1,58 @@
+"""An extractor that tries several extractors in order."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+from xtr_security_core.exception import InvalidArgumentError
+
+from .access_token_extractor_interface import AccessTokenExtractorInterface
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from fastapi.security.base import SecurityBase
+    from starlette.requests import Request
+
+__all__ = ["ChainAccessTokenExtractor"]
+
+
+@final
+class ChainAccessTokenExtractor(AccessTokenExtractorInterface):
+    """Returns the first token any of its extractors finds.
+
+    Tries each extractor in turn and returns the first non-``None`` token, so a
+    firewall can accept a token from a header or a query parameter without
+    caring which the client used. Its OpenAPI scheme is the first extractor's —
+    the one a client is nudged towards.
+    """
+
+    __slots__ = ("_extractors",)
+
+    def __init__(self, extractors: Sequence[AccessTokenExtractorInterface]) -> None:
+        """Record the extractors to try, in order.
+
+        Raises:
+            InvalidArgumentError: When no extractor is given, which would find
+                no token ever.
+        """
+        if not extractors:
+            raise InvalidArgumentError(
+                "A chain access-token extractor needs at least one extractor."
+            )
+        self._extractors = tuple(extractors)
+
+    @override
+    async def extract_access_token(self, request: Request) -> str | None:
+        """Return the first token any extractor finds, or ``None`` when none do."""
+        for extractor in self._extractors:
+            token = await extractor.extract_access_token(request)
+            if token is not None:
+                return token
+        return None
+
+    @override
+    def scheme(self) -> SecurityBase:
+        """Return the first extractor's scheme, the one documented for the firewall."""
+        return self._extractors[0].scheme()

xtr_security_http/access_token/form_encoded_body_extractor.py

@@ -0,0 +1,57 @@
+"""An extractor that reads a bearer token from a form-encoded body."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+from urllib.parse import parse_qs
+
+from fastapi.security import 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__ = ["FormEncodedBodyExtractor"]
+
+_FORM_CONTENT_TYPE = "application/x-www-form-urlencoded"
+
+
+@final
+class FormEncodedBodyExtractor(AccessTokenExtractorInterface):
+    """Reads a token from a form field of an ``x-www-form-urlencoded`` body.
+
+    RFC 6750 allows a bearer token in a form body; this reads the
+    ``access_token`` field of one, when the request carries that content type.
+    The body is parsed directly, so no form-parsing dependency is needed. There
+    is no dedicated OpenAPI scheme for a body-carried token, so it documents
+    itself as the standard bearer scheme.
+
+    Attributes:
+        field_name: The form field the token is read from.
+    """
+
+    __slots__ = ("_bearer", "_field_name")
+
+    def __init__(self, field_name: str = "access_token") -> None:
+        """Build the extractor for the ``field_name`` form field."""
+        self._field_name = field_name
+        self._bearer = HTTPBearer(auto_error=False, bearerFormat="JWT", scheme_name="Bearer")
+
+    @override
+    async def extract_access_token(self, request: Request) -> str | None:
+        """Return the token in the form body, or ``None`` when it is absent."""
+        content_type = request.headers.get("content-type", "")
+        if not content_type.startswith(_FORM_CONTENT_TYPE):
+            return None
+        body = await request.body()
+        fields = parse_qs(body.decode("utf-8"))
+        values = fields.get(self._field_name)
+        return values[0] if values else None
+
+    @override
+    def scheme(self) -> SecurityBase:
+        """Return the bearer scheme this extractor documents by."""
+        return self._bearer