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

xtr_security_http/event_listener/user_provider_listener.py

@@ -0,0 +1,53 @@
+"""The listener that gives a user badge its loader from the firewall's provider."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+from xtr_event_dispatcher import EventSubscriberInterface
+
+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_provider_interface import UserProviderInterface
+
+__all__ = ["UserProviderListener"]
+
+#: The priority the provider listener runs at — before every other passport check.
+PRIORITY = 2048
+
+
+@final
+class UserProviderListener(EventSubscriberInterface):
+    """Sets a user badge's loader from the firewall's provider, when it has none.
+
+    Runs first on the passport check, so the listeners after it — the account
+    check, the credentials check — can load the user. An authenticator that
+    already gave the badge a loader (a bearer handler that resolved the user
+    from a token's claims) is left alone. The provider's ``load_user_by_identifier``
+    is set as the loader directly, so a badge with attributes reaches an
+    attributes-based provider's two-argument method and a plain provider's
+    one-argument one — the badge chooses by the method's own shape.
+    """
+
+    __slots__ = ("_provider",)
+
+    def __init__(self, provider: UserProviderInterface) -> None:
+        """Record the provider a badge's loader is built from."""
+        self._provider = provider
+
+    @classmethod
+    @override
+    def get_subscribed_events(cls) -> Mapping[str | type, SubscribedEvents]:
+        """Listen to the passport check first of all, at :data:`PRIORITY`."""
+        return {CheckPassportEvent: ("check_passport", PRIORITY)}
+
+    async def check_passport(self, event: CheckPassportEvent) -> None:
+        """Give the badge the provider's loader, unless it already has one."""
+        badge = event.get_passport().get_user_badge()
+        if badge.get_user_loader() is None:
+            badge.set_user_loader(self._provider.load_user_by_identifier)

xtr_security_http/exception/__init__.py

@@ -0,0 +1,18 @@
+"""The errors the HTTP edge adds to the security core's.
+
+Each derives from a core error — :class:`~xtr_security_core.exception.SecurityError`
+or :class:`~xtr_security_core.exception.AuthenticationError` — so one
+``except SecurityError`` still catches everything the family raises.
+"""
+
+from __future__ import annotations
+
+from .firewall_not_booted_error import FirewallNotBootedError
+from .invalid_access_token_error import InvalidAccessTokenError
+from .unknown_firewall_error import UnknownFirewallError
+
+__all__ = [
+    "FirewallNotBootedError",
+    "InvalidAccessTokenError",
+    "UnknownFirewallError",
+]

xtr_security_http/exception/firewall_not_booted_error.py

@@ -0,0 +1,18 @@
+"""Something a booted kernel provides was read before boot, or outside a request."""
+
+from __future__ import annotations
+
+from xtr_security_core.exception import SecurityError
+
+__all__ = ["FirewallNotBootedError"]
+
+
+class FirewallNotBootedError(SecurityError, RuntimeError):
+    """A firewall's booted state was read too early, or outside a request.
+
+    The OpenAPI scheme a firewall contributes is resolved from the booted
+    kernel serving the current request. Read it before the kernel has booted,
+    or with no request in scope, and there is nothing to resolve — this is
+    raised rather than a wrong, silently-chosen answer. Also a
+    :class:`RuntimeError`.
+    """

xtr_security_http/exception/invalid_access_token_error.py

@@ -0,0 +1,20 @@
+"""A bearer access token was malformed, expired or wrongly signed."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from xtr_security_core.exception import AuthenticationError
+
+__all__ = ["InvalidAccessTokenError"]
+
+
+class InvalidAccessTokenError(AuthenticationError):
+    """A bearer access token could not be trusted.
+
+    The token was present but malformed, expired, signed with the wrong key,
+    or otherwise not verifiable. A protected resource answers such a token
+    with a challenge naming ``invalid_token``.
+    """
+
+    MESSAGE_KEY: ClassVar[str] = "Invalid credentials."

xtr_security_http/exception/unknown_firewall_error.py

@@ -0,0 +1,34 @@
+"""A firewall was asked for by a name that is not configured."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from xtr_security_core.exception import SecurityError
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = ["UnknownFirewallError"]
+
+
+class UnknownFirewallError(SecurityError, LookupError):
+    """No firewall is configured under the name asked for.
+
+    Also a :class:`LookupError`. Names the firewalls that are configured, so
+    the mistake — a typo, a firewall never declared — is plain from the error.
+
+    Attributes:
+        name: The name that matched no firewall.
+        configured: The names that are configured.
+    """
+
+    name: str
+    configured: tuple[str, ...]
+
+    def __init__(self, name: str, configured: Sequence[str] = ()) -> None:
+        """Record the unknown name and the names that are configured."""
+        self.name = name
+        self.configured = tuple(configured)
+        known = ", ".join(f'"{one}"' for one in self.configured) or "none"
+        super().__init__(f'The firewall "{name}" is not configured. Configured: {known}.')

xtr_security_http/firewall/__init__.py

@@ -0,0 +1,15 @@
+"""The firewall a request passes, its access listener and its exception listener.
+
+The :class:`Firewall` dependency a route attaches, the
+:class:`AccessListener` that decides a request against a firewall's rules, and
+the :class:`ExceptionListener` that turns a security error into a response, kept
+together in one folder.
+"""
+
+from __future__ import annotations
+
+from .access_listener import AccessListener
+from .exception_listener import ExceptionListener
+from .firewall import Firewall
+
+__all__ = ["AccessListener", "ExceptionListener", "Firewall"]

xtr_security_http/firewall/access_listener.py

@@ -0,0 +1,66 @@
+"""The step that decides a request against a firewall's access-control rules."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from xtr_security_core.authorization.access_decision import AccessDecision
+from xtr_security_core.authorization.voter.authenticated_voter import AuthenticatedVoter
+from xtr_security_core.exception import AccessDeniedError
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+    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.access_map_interface import AccessMapInterface
+
+__all__ = ["AccessListener"]
+
+
+@final
+class AccessListener:
+    """Requires of a request whatever its firewall's first matching rule demands.
+
+    Run after authentication, inside the firewall. It finds the first access
+    rule the request matches and decides the token against that rule's one
+    attribute. A ``PUBLIC_ACCESS`` rule short-circuits — the resource is open,
+    so no decision is made. A request matching no rule is left alone, its
+    access decided by whatever the route itself requires.
+    """
+
+    __slots__ = ("_access_decision_manager", "_access_map")
+
+    def __init__(
+        self,
+        access_map: AccessMapInterface,
+        access_decision_manager: AccessDecisionManagerInterface,
+    ) -> None:
+        """Record the rules to match and the manager that decides them."""
+        self._access_map = access_map
+        self._access_decision_manager = access_decision_manager
+
+    async def check_access(self, request: Request, token: TokenInterface) -> None:
+        """Decide ``token`` against the first rule ``request`` matches.
+
+        Raises:
+            AccessDeniedError: When a matching rule's attribute is not granted,
+                carrying the decision so a handler can explain or challenge.
+        """
+        attribute = self._access_map.get_attribute(request)
+        if attribute is None or attribute == AuthenticatedVoter.PUBLIC_ACCESS:
+            return
+        decision = AccessDecision()
+        granted = await self._access_decision_manager.decide(
+            token,
+            [attribute],
+            access_decision=decision,
+        )
+        if not granted:
+            raise AccessDeniedError(
+                "Access to the requested resource is denied.",
+                attributes=(attribute,),
+                access_decision=decision,
+            )

xtr_security_http/firewall/exception_listener.py

@@ -0,0 +1,151 @@
+"""The listener that turns a security error into a response on the lifecycle."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast, final
+
+from starlette.responses import JSONResponse
+from typing_extensions import override
+from xtr_event_dispatcher import EventSubscriberInterface
+from xtr_http_kernel import ExceptionEvent
+from xtr_security_core.authentication.authentication_trust_resolver_interface import (  # noqa: TC002
+    AuthenticationTrustResolverInterface,
+)
+from xtr_security_core.exception import (
+    AccessDeniedError,
+    AuthenticationError,
+    InsufficientAuthenticationError,
+)
+
+from xtr_security_http._state import FIREWALL_CONTEXT_KEY, TOKEN_KEY, CarriedResponse
+from xtr_security_http.authorization.oauth2_scope_voter import parse_oauth2_scope
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from starlette.requests import Request
+    from starlette.responses import Response
+    from xtr_event_dispatcher import SubscribedEvents
+    from xtr_security_core.authentication.token.token_interface import TokenInterface
+
+    from xtr_security_http.firewall_context_interface import FirewallContextInterface
+
+__all__ = ["ExceptionListener"]
+
+
+@final
+class ExceptionListener(EventSubscriberInterface):
+    """Turns a security error raised while handling a request into a response.
+
+    Sits on the lifecycle's exception event, alone deciding ``401`` versus
+    ``403``:
+
+    - a carried handler response is sent as it is;
+    - an :class:`~xtr_security_core.exception.AuthenticationError` becomes the
+      firewall's entry-point challenge, or a bare ``401`` bearer challenge when
+      the firewall has no entry point;
+    - an :class:`~xtr_security_core.exception.AccessDeniedError` from a caller who
+      is not fully authenticated becomes the entry-point challenge for
+      insufficient authentication; from a fully authenticated caller it becomes
+      a scope challenge when the denied attribute is a scope, the firewall's
+      access-denied handler when it has one, or a plain ``403`` otherwise.
+
+    Any other exception is left untouched, to whatever else handles it.
+
+    The firewall the request ran under, and the token it authenticated, are read
+    from ``request.state`` — stashed there by the firewall — so this singleton
+    listener answers a request without reaching into the request scope. The
+    trust resolver is a singleton it is built with.
+    """
+
+    __slots__ = ("_trust_resolver",)
+
+    def __init__(self, trust_resolver: AuthenticationTrustResolverInterface) -> None:
+        """Build the listener over the application's trust resolver."""
+        self._trust_resolver = trust_resolver
+
+    @classmethod
+    @override
+    def get_subscribed_events(cls) -> Mapping[str | type, SubscribedEvents]:
+        """Listen to the lifecycle's exception event."""
+        return {ExceptionEvent: "on_exception"}
+
+    async def on_exception(self, event: ExceptionEvent) -> None:
+        """Answer the request when the exception is one this listener owns."""
+        error = event.exception
+        if isinstance(error, CarriedResponse):
+            event.set_response(error.response)
+            return
+        if not isinstance(error, (AuthenticationError, AccessDeniedError)):
+            return
+        context = _context_of(event.request)
+        if isinstance(error, AuthenticationError):
+            event.set_response(await self._on_authentication_error(context, event.request, error))
+            return
+        event.set_response(await self._on_access_denied(context, event.request, error))
+
+    async def _on_authentication_error(
+        self,
+        context: FirewallContextInterface | None,
+        request: Request,
+        error: AuthenticationError,
+    ) -> Response:
+        """Answer an authentication error with the entry-point challenge, or a bare 401."""
+        if context is not None and context.entry_point is not None:
+            return await context.entry_point.start(request, error)
+        return _bare_challenge()
+
+    async def _on_access_denied(
+        self,
+        context: FirewallContextInterface | None,
+        request: Request,
+        error: AccessDeniedError,
+    ) -> Response:
+        """Answer a denial: a challenge when not fully authenticated, else a refusal."""
+        if not self._is_full_fledged(request):
+            if context is not None and context.entry_point is not None:
+                return await context.entry_point.start(request, InsufficientAuthenticationError())
+            return _bare_challenge()
+        if (
+            _is_scope_denial(error)
+            and context is not None
+            and context.scope_denied_handler is not None
+        ):
+            answered = await context.scope_denied_handler.handle(request, error)
+            if answered is not None:
+                return answered
+        if context is not None and context.access_denied_handler is not None:
+            answered = await context.access_denied_handler.handle(request, error)
+            if answered is not None:
+                return answered
+        return JSONResponse({"error": "access_denied"}, status_code=403)
+
+    def _is_full_fledged(self, request: Request) -> bool:
+        """Tell whether the request's token is fully authenticated."""
+        token = _token_of(request)
+        return self._trust_resolver.is_full_fledged(token)
+
+
+def _context_of(request: Request) -> FirewallContextInterface | None:
+    """Return the firewall context the firewall stashed for ``request``, if any."""
+    context = getattr(request.state, FIREWALL_CONTEXT_KEY, None)
+    return cast("FirewallContextInterface | None", context)
+
+
+def _token_of(request: Request) -> TokenInterface | None:
+    """Return the token the firewall stashed for ``request``, if any."""
+    return cast("TokenInterface | None", getattr(request.state, TOKEN_KEY, None))
+
+
+def _bare_challenge() -> Response:
+    """Return a plain ``401`` carrying a bare bearer challenge."""
+    return JSONResponse(
+        {"error": "unauthorized"},
+        status_code=401,
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+
+
+def _is_scope_denial(error: AccessDeniedError) -> bool:
+    """Tell whether the denied attribute is an OAuth2 scope request."""
+    return any(parse_oauth2_scope(attribute) is not None for attribute in error.attributes)

xtr_security_http/firewall/firewall.py

@@ -0,0 +1,142 @@
+"""The firewall dependency: attach it to an app, a router or a route."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import TYPE_CHECKING, Final, ParamSpec, TypeVar, cast, overload
+
+from fastapi import APIRouter
+from fastapi.params import Security
+
+from xtr_security_http.firewall_scheme import FirewallScheme
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Iterable
+
+__all__ = ["Firewall"]
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+_HIDDEN_PREFIX: Final = "_xtr_firewall_"
+
+
+class Firewall(Security):
+    """A firewall a request passes before its endpoint runs.
+
+    Written wherever the framework takes a dependency, as a decorator, or on a
+    router before its routes:
+
+    ```python
+    app = FastAPI(dependencies=[Firewall()])       # chosen per request by the config
+    api = Firewall("api")                            # bound by name: exact OpenAPI scheme
+
+    router = APIRouter(prefix="/api", dependencies=[api])
+
+
+    @router.get("/books", dependencies=[api.scopes("books:read")])
+    async def books() -> list[Book]: ...
+
+
+    @router.delete("/books/{isbn}")
+    @Firewall("api")                                 # below the route decorator
+    async def delete_book(isbn: str) -> None: ...
+    ```
+
+    Bound by name, it resolves that firewall directly and shows its exact
+    scheme in OpenAPI. Unbound, it is matched per request to the first firewall
+    whose request matcher claims it. Authentication runs once per request
+    however many firewall dependencies a route carries; the accumulated
+    ``scopes`` are checked against the token with the OAuth2 scope voter.
+
+    Attributes:
+        firewall_name: The firewall bound by name, or ``None`` when matched per
+            request.
+    """
+
+    firewall_name: str | None  # pyright: ignore[reportUninitializedInstanceVariable]
+
+    def __init__(
+        self,
+        name: str | None = None,
+        *,
+        scopes: Iterable[str] = (),
+        _scheme: FirewallScheme | None = None,
+    ) -> None:
+        """Attach the firewall ``name`` (or the matched one), requiring ``scopes``.
+
+        Args:
+            name: The firewall to bind by name, or ``None`` to match per request.
+            scopes: The scopes a request must carry, added to the OpenAPI
+                operation and checked by the scope voter.
+            _scheme: The shared scheme a scoped variant reuses; not for callers.
+        """
+        scheme = _scheme if _scheme is not None else FirewallScheme(name)
+        super().__init__(dependency=scheme, scopes=list(scopes), use_cache=True)
+        object.__setattr__(self, "firewall_name", name)
+
+    def scoped(self, *scopes: str) -> Firewall:
+        """Return a variant requiring ``scopes``, sharing this firewall's scheme.
+
+        The returned firewall points at the same scheme object, so the two are
+        one security scheme in OpenAPI with the scopes added to the operation
+        that uses the variant. Named ``scoped`` — not ``scopes`` — because the
+        framework reads ``scopes`` as the accumulated list on the marker itself.
+        """
+        scheme = cast("FirewallScheme", self.dependency)
+        return Firewall(self.firewall_name, scopes=scopes, _scheme=scheme)
+
+    @overload
+    def __call__(self, target: APIRouter, /) -> APIRouter: ...
+
+    @overload
+    def __call__(self, target: Callable[_P, _R], /) -> Callable[_P, _R]: ...
+
+    def __call__(self, target: APIRouter | Callable[_P, _R], /) -> APIRouter | Callable[_P, _R]:
+        """Attach this firewall to every route of ``target``, or to the endpoint ``target``.
+
+        A router must have no route yet — the framework copies a router's
+        dependencies into each route as it is added. An endpoint must be
+        decorated below its route decorator, which reads the endpoint's
+        signature then.
+        """
+        if isinstance(target, APIRouter):
+            target.dependencies.append(self)
+            return target
+        return self._decorate(target)
+
+    def _decorate(self, endpoint: Callable[_P, _R]) -> Callable[_P, _R]:
+        """Return ``endpoint`` taking this firewall as a hidden dependency."""
+        signature = inspect.signature(endpoint)
+        taken = set(signature.parameters)
+        index = 0
+        while f"{_HIDDEN_PREFIX}{index}" in taken:
+            index += 1
+        name = f"{_HIDDEN_PREFIX}{index}"
+
+        parameters = list(signature.parameters.values())
+        keywords = [p for p in parameters if p.kind is inspect.Parameter.VAR_KEYWORD]
+        others = [p for p in parameters if p.kind is not inspect.Parameter.VAR_KEYWORD]
+        hidden = inspect.Parameter(name, inspect.Parameter.KEYWORD_ONLY, default=self)
+        extended = signature.replace(parameters=[*others, hidden, *keywords])
+
+        if inspect.iscoroutinefunction(endpoint):
+            call = cast("Callable[_P, Awaitable[object]]", endpoint)
+
+            @functools.wraps(endpoint)
+            async def asynchronous(*args: _P.args, **kwargs: _P.kwargs) -> object:
+                _ = kwargs.pop(name, None)
+                return await call(*args, **kwargs)
+
+            wrapper = cast("Callable[_P, _R]", asynchronous)
+        else:
+
+            @functools.wraps(endpoint)
+            def synchronous(*args: _P.args, **kwargs: _P.kwargs) -> _R:
+                _ = kwargs.pop(name, None)
+                return endpoint(*args, **kwargs)
+
+            wrapper = synchronous
+        wrapper.__signature__ = extended  # pyright: ignore[reportAttributeAccessIssue]  # ty: ignore[unresolved-attribute]
+        return wrapper

xtr_security_http/firewall_context_interface.py

@@ -0,0 +1,64 @@
+"""The per-firewall contract the firewall runner and exception listener read.
+
+The HTTP edge runs a firewall without knowing how its parts were built: the
+runner authenticates through the manager and decides through the access
+listener, and the exception listener answers a failure through the entry point
+and handlers. Both read those parts off this contract, so the concrete context
+that gathers them — built by the bundle — lives outside this package while the
+runtime here depends only on the shape.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from fastapi.security.base import SecurityBase
+    from xtr_event_dispatcher_contracts import EventDispatcherInterface
+
+    from xtr_security_http.authentication.authenticator_manager_interface import (
+        AuthenticatorManagerInterface,
+    )
+    from xtr_security_http.authorization.access_denied_handler_interface import (
+        AccessDeniedHandlerInterface,
+    )
+    from xtr_security_http.entry_point.authentication_entry_point_interface import (
+        AuthenticationEntryPointInterface,
+    )
+    from xtr_security_http.firewall.access_listener import AccessListener
+
+__all__ = ["FirewallContextInterface"]
+
+
+@runtime_checkable
+class FirewallContextInterface(Protocol):
+    """The runtime pieces of one firewall, resolved once and shared for its lifetime.
+
+    Groups the manager that authenticates a request, the access listener that
+    decides it, the entry point and handlers that answer it, the firewall's own
+    event dispatcher, and the OpenAPI scheme it contributes.
+
+    Attributes:
+        name: The firewall's name — the key it is looked up by, and the memo
+            key that keeps its authentication to one pass per request.
+        authenticator_manager: Runs the firewall's authenticators.
+        access_listener: Decides a request against the firewall's rules.
+        dispatcher: The firewall's own event dispatcher.
+        scheme: The FastAPI security object the firewall shows in OpenAPI.
+        security: Whether the firewall authenticates at all; ``False`` lets
+            every request through untouched.
+        entry_point: Answers an unauthenticated request with a challenge.
+        access_denied_handler: Answers a fully-authenticated caller's denial.
+        scope_denied_handler: Answers a denied OAuth2 scope with its own
+            challenge, ahead of the plain access-denied handler.
+    """
+
+    name: str
+    authenticator_manager: AuthenticatorManagerInterface
+    access_listener: AccessListener
+    dispatcher: EventDispatcherInterface
+    scheme: SecurityBase
+    security: bool
+    entry_point: AuthenticationEntryPointInterface | None
+    access_denied_handler: AccessDeniedHandlerInterface | None
+    scope_denied_handler: AccessDeniedHandlerInterface | None

xtr_security_http/firewall_map.py

@@ -0,0 +1,93 @@
+"""The firewalls of an application: found by name, or by matching a request."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+from xtr_security_core.exception import InvalidArgumentError
+
+from .exception.unknown_firewall_error import UnknownFirewallError
+from .firewall_map_interface import FirewallMapInterface
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from starlette.requests import Request
+
+    from .firewall_context_interface import FirewallContextInterface
+    from .request_matcher.request_matcher_interface import RequestMatcherInterface
+
+__all__ = ["FirewallMap"]
+
+
+@final
+class FirewallMap(FirewallMapInterface):
+    """Holds an application's firewalls, found by name or by matching a request.
+
+    A firewall bound by name — ``Firewall("api")`` — is looked up directly. An
+    unbound firewall — ``Firewall()`` — is matched to the first firewall whose
+    request matcher claims the request, in the order they were registered, so a
+    narrow firewall must be registered before a catch-all it would shadow.
+
+    Each firewall is paired with a
+    :class:`~xtr_security_http.request_matcher.request_matcher_interface.RequestMatcherInterface`
+    — a path, host, method or callable matcher, or a chain of them, from the
+    ``request_matcher`` package — so the map matches a request without a notion
+    of matching of its own. A chain of no matchers claims every request, the
+    catch-all a firewall registered last relies on.
+
+    The contexts it holds are read through
+    :class:`~xtr_security_http.firewall_context_interface.FirewallContextInterface`,
+    so the map works over whatever concrete context the bundle gathers.
+    """
+
+    __slots__ = ("_by_name", "_matchers")
+
+    def __init__(
+        self,
+        firewalls: Sequence[tuple[RequestMatcherInterface, FirewallContextInterface]] = (),
+    ) -> None:
+        """Record the firewalls, keyed by name and kept in matching order.
+
+        Raises:
+            InvalidArgumentError: When two firewalls share a name.
+        """
+        self._matchers: tuple[tuple[RequestMatcherInterface, FirewallContextInterface], ...] = (
+            tuple(firewalls)
+        )
+        self._by_name: dict[str, FirewallContextInterface] = {}
+        for _, context in self._matchers:
+            if context.name in self._by_name:
+                raise InvalidArgumentError(f'Two firewalls share the name "{context.name}".')
+            self._by_name[context.name] = context
+
+    @override
+    def has(self, name: str) -> bool:
+        """Tell whether a firewall is registered under ``name``."""
+        return name in self._by_name
+
+    @override
+    def get(self, name: str) -> FirewallContextInterface:
+        """Return the firewall named ``name``.
+
+        Raises:
+            UnknownFirewallError: When no firewall carries that name.
+        """
+        try:
+            return self._by_name[name]
+        except KeyError as error:
+            raise UnknownFirewallError(name, tuple(self._by_name)) from error
+
+    @override
+    def match(self, request: Request) -> FirewallContextInterface | None:
+        """Return the first firewall whose matcher claims ``request``, or ``None``."""
+        for matcher, context in self._matchers:
+            if matcher.matches(request):
+                return context
+        return None
+
+    @override
+    def names(self) -> tuple[str, ...]:
+        """Return the names of every firewall registered."""
+        return tuple(self._by_name)