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

xtr_security_http/firewall_map_interface.py

@@ -0,0 +1,48 @@
+"""What resolves a request's firewall: by name, or by matching the request.
+
+The firewall runner asks this for the firewall to run — the one bound by name,
+or the first whose matcher claims the request — and the OpenAPI scheme registry
+and ``debug:firewall`` read the firewalls it holds. The concrete map that pairs
+each firewall with its matcher is built by the bundle; the runtime here depends
+only on this shape, so a firewall runs without knowing how the map was built.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+    from xtr_security_http.firewall_context_interface import FirewallContextInterface
+
+__all__ = ["FirewallMapInterface"]
+
+
+@runtime_checkable
+class FirewallMapInterface(Protocol):
+    """Holds an application's firewalls, found by name or by matching a request.
+
+    A firewall bound by name is looked up directly; an unbound one is matched to
+    the first firewall whose matcher claims the request, in registration order.
+    """
+
+    def has(self, name: str) -> bool:
+        """Tell whether a firewall is registered under ``name``."""
+        ...
+
+    def get(self, name: str) -> FirewallContextInterface:
+        """Return the firewall named ``name``.
+
+        Raises:
+            UnknownFirewallError: When no firewall carries that name.
+        """
+        ...
+
+    def match(self, request: Request) -> FirewallContextInterface | None:
+        """Return the first firewall whose matcher claims ``request``, or ``None``."""
+        ...
+
+    def names(self) -> tuple[str, ...]:
+        """Return the names of every firewall registered."""
+        ...

xtr_security_http/firewall_scheme.py

@@ -0,0 +1,114 @@
+"""The FastAPI security object a firewall is."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from fastapi.security import HTTPBearer, SecurityScopes
+from fastapi.security.base import SecurityBase
+
+# The framework reads the dependency's __call__ signature at runtime to inject
+# these, so they — and the service types the container fills — cannot live
+# behind TYPE_CHECKING.
+from starlette.requests import Request  # noqa: TC002
+from xtr_dependency_injection import Injected  # noqa: TC002
+from xtr_security_core.authentication.token.storage.token_storage_interface import (  # noqa: TC002
+    TokenStorageInterface,
+)
+from xtr_security_core.authorization.access_decision_manager_interface import (  # noqa: TC002
+    AccessDecisionManagerInterface,
+)
+
+from ._runner import run_firewall
+from .exception.firewall_not_booted_error import FirewallNotBootedError
+from .firewall_map_interface import FirewallMapInterface  # noqa: TC001 -- filled into __call__
+from .firewall_scheme_registry import active_firewall_scheme_registry
+
+if TYPE_CHECKING:
+    from fastapi.openapi.models import SecurityBase as SecurityBaseModel
+
+__all__ = ["FirewallScheme"]
+
+_GENERIC_SCHEME_NAME = "firewall"
+
+
+@final
+class FirewallScheme(SecurityBase):
+    """A firewall, seen by FastAPI as both a dependency and a security scheme.
+
+    As a dependency, calling it runs the firewall for the request — authenticate
+    once, then decide access and any accumulated scopes. As a
+    :class:`~fastapi.security.base.SecurityBase`, its ``model`` and
+    ``scheme_name`` — read only when the schema is generated — describe the
+    firewall in OpenAPI: a bound firewall's from the registry the kernel filled
+    at boot, an unbound one's a generic bearer scheme.
+    """
+
+    def __init__(self, name: str | None) -> None:
+        """Build the scheme for the firewall ``name``, or an unbound one for ``None``."""
+        self._name = name
+        self._generic = HTTPBearer(auto_error=False, bearerFormat="JWT", scheme_name="firewall")
+
+    async def __call__(
+        self,
+        request: Request,
+        security_scopes: SecurityScopes,
+        firewall_map: Injected[FirewallMapInterface],
+        token_storage: Injected[TokenStorageInterface],
+        access_decision_manager: Injected[AccessDecisionManagerInterface],
+    ) -> None:
+        """Run the firewall for ``request``, enforcing the accumulated scopes."""
+        await run_firewall(
+            self._name,
+            request,
+            tuple(security_scopes.scopes),
+            firewall_map=firewall_map,
+            token_storage=token_storage,
+            access_decision_manager=access_decision_manager,
+        )
+
+    # These read the OpenAPI model dynamically at schema-generation time, so they
+    # are properties over the plain attributes the base declares — the override is
+    # deliberate and the type checker cannot see it is compatible.
+    @property
+    def model(  # pyright: ignore[reportIncompatibleVariableOverride, reportImplicitOverride]
+        self,
+    ) -> SecurityBaseModel:
+        """Return the firewall's OpenAPI model, resolved when the schema is built.
+
+        Raises:
+            FirewallNotBootedError: When a bound firewall's scheme is read
+                before the kernel filled the registry, or outside a request.
+        """
+        if self._name is None:
+            return self._generic.model
+        registry = active_firewall_scheme_registry()
+        entry = registry.get(self._name) if registry is not None else None
+        if entry is None:
+            raise FirewallNotBootedError(self._not_booted_message())
+        return entry.model
+
+    @property
+    def scheme_name(  # pyright: ignore[reportIncompatibleVariableOverride, reportImplicitOverride]
+        self,
+    ) -> str:
+        """Return the firewall's OpenAPI scheme name, an unbound one's generic.
+
+        Raises:
+            FirewallNotBootedError: When a bound firewall's scheme is read
+                before the kernel filled the registry, or outside a request.
+        """
+        if self._name is None:
+            return _GENERIC_SCHEME_NAME
+        registry = active_firewall_scheme_registry()
+        entry = registry.get(self._name) if registry is not None else None
+        if entry is None:
+            raise FirewallNotBootedError(self._not_booted_message())
+        return entry.scheme_name
+
+    def _not_booted_message(self) -> str:
+        """Name the firewall whose scheme was read before the kernel registered it."""
+        return (
+            f'The OpenAPI scheme of the firewall "{self._name}" was read before the '
+            f"kernel registered it, or outside a request."
+        )

xtr_security_http/firewall_scheme_registry.py

@@ -0,0 +1,87 @@
+"""The OpenAPI scheme each firewall contributes, and the holder a scheme reads it through."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, final
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from fastapi.openapi.models import SecurityBase as SecurityBaseModel
+
+__all__ = [
+    "FirewallSchemeRegistry",
+    "active_firewall_scheme_registry",
+    "active_firewall_schemes",
+]
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class _SchemeEntry:
+    """The OpenAPI model and name one firewall contributes."""
+
+    model: SecurityBaseModel
+    scheme_name: str
+
+
+@final
+class FirewallSchemeRegistry:
+    """The OpenAPI scheme each firewall contributes, filled once when the kernel boots.
+
+    The generated schema is built synchronously, inside the request serving
+    ``/openapi.json``, where an ``await`` on the container is not possible. So
+    each firewall's model and name are resolved once at boot and kept here for
+    that synchronous read. The bundle fills one of these per kernel and makes
+    it the active registry for the requests that kernel serves; a test fills
+    one and activates it with :func:`active_firewall_schemes`.
+    """
+
+    __slots__ = ("_schemes",)
+
+    def __init__(self) -> None:
+        """Start with no firewall schemes registered."""
+        self._schemes: dict[str, _SchemeEntry] = {}
+
+    def register(self, name: str, model: SecurityBaseModel, scheme_name: str | None = None) -> None:
+        """Record the OpenAPI ``model`` and name the firewall ``name`` shows."""
+        self._schemes[name] = _SchemeEntry(model, scheme_name or name)
+
+    def get(self, name: str) -> _SchemeEntry | None:
+        """Return the scheme registered for ``name``, or ``None`` when there is none."""
+        return self._schemes.get(name)
+
+    def names(self) -> tuple[str, ...]:
+        """Return the names of every firewall with a registered scheme."""
+        return tuple(self._schemes)
+
+
+# The OpenAPI scheme is read synchronously while the schema is generated, from
+# a context the reader does not share with whoever activated the registry (a
+# fixture, an async generator). A plain module-level holder — restored on exit
+# — is read the same from any context; the Phase 5 bundle keys it per kernel so
+# concurrent kernels stay isolated.
+_ACTIVE: list[FirewallSchemeRegistry | None] = [None]
+
+
+@contextmanager
+def active_firewall_schemes(registry: FirewallSchemeRegistry) -> Generator[None, None, None]:
+    """Make ``registry`` the one a firewall scheme reads while the block is entered.
+
+    The bundle activates a kernel's registry for the span its requests are
+    served; a test activates one around the block it serves an application in.
+    The previous registry is restored on exit.
+    """
+    previous = _ACTIVE[0]
+    _ACTIVE[0] = registry
+    try:
+        yield
+    finally:
+        _ACTIVE[0] = previous
+
+
+def active_firewall_scheme_registry() -> FirewallSchemeRegistry | None:
+    """Return the registry a firewall scheme reads now, or ``None`` when none is active."""
+    return _ACTIVE[0]

xtr_security_http/oidc/__init__.py

@@ -0,0 +1,7 @@
+"""OIDC discovery: finding and caching a third-party issuer's verifying keys."""
+
+from __future__ import annotations
+
+from .oidc_discovery import DiscoveryOidcKeySetProvider
+
+__all__ = ["DiscoveryOidcKeySetProvider"]

xtr_security_http/oidc/oidc_discovery.py

@@ -0,0 +1,238 @@
+"""A key set provider that fetches and caches an issuer's JWKS."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, cast, final
+
+import anyio
+from joserfc.errors import JoseError
+from joserfc.jwk import KeySet
+from typing_extensions import override
+from xtr_security_core.exception import InvalidArgumentError
+
+from xtr_security_http.access_token.oidc.exception.oidc_key_set_error import (
+    OidcKeySetError,
+)
+from xtr_security_http.authenticator.oidc.oidc_jwks import OidcKeySetProviderInterface
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import httpx
+    from joserfc._keys import KeySetSerialization
+
+__all__ = ["DiscoveryOidcKeySetProvider"]
+
+_DISCOVERY_PATH = "/.well-known/openid-configuration"
+
+
+@final
+class DiscoveryOidcKeySetProvider(OidcKeySetProviderInterface):
+    """Fetches an issuer's JWKS, caches it, and refetches when a key is unknown.
+
+    Given an issuer's ``base_uri`` it reads the OpenID discovery document to
+    find the ``jwks_uri``; given a ``jwks_uri`` outright it fetches that. The
+    set is cached for ``ttl`` seconds. A ``force_refresh`` fetches again — the
+    handler asks for one when a token names a ``kid`` the cached set lacks, a
+    rotated key — but no more than once every ``refresh_cooldown`` seconds, so a
+    burst of tokens with an unknown ``kid`` triggers a single fetch. A lock
+    serialises fetches, so concurrent callers that all find the set stale share
+    the one fetch rather than each making their own.
+
+    Every endpoint must be ``https`` unless ``allow_insecure_http`` is set, a
+    door left only for a development or test issuer served over plain HTTP.
+    """
+
+    __slots__ = (
+        "_allow_insecure_http",
+        "_base_uri",
+        "_cooldown",
+        "_http_client_factory",
+        "_jwks_uri",
+        "_key_set",
+        "_last_error",
+        "_last_fetch",
+        "_lock",
+        "_monotonic",
+        "_resolved_jwks_uri",
+        "_ttl",
+    )
+
+    def __init__(  # noqa: PLR0913 -- a wiring constructor; every knob has a default
+        self,
+        *,
+        base_uri: str | None = None,
+        jwks_uri: str | None = None,
+        http_client_factory: Callable[[], httpx.AsyncClient],
+        ttl: float = 600,
+        refresh_cooldown: float = 60,
+        allow_insecure_http: bool = False,
+        monotonic: Callable[[], float] = time.monotonic,
+    ) -> None:
+        """Record the endpoints, the client factory and the cache timings.
+
+        Raises:
+            InvalidArgumentError: When neither or both of ``base_uri`` and
+                ``jwks_uri`` are given, or a given endpoint is not ``https`` and
+                insecure HTTP is not allowed.
+        """
+        if (base_uri is None) == (jwks_uri is None):
+            raise InvalidArgumentError(
+                "A discovery key set provider needs exactly one of base_uri or jwks_uri.",
+            )
+        self._allow_insecure_http = allow_insecure_http
+        if base_uri is not None:
+            self._require_secure(base_uri)
+        if jwks_uri is not None:
+            self._require_secure(jwks_uri)
+        self._base_uri = base_uri
+        self._jwks_uri = jwks_uri
+        self._http_client_factory = http_client_factory
+        self._ttl = ttl
+        self._cooldown = refresh_cooldown
+        self._monotonic = monotonic
+        self._lock = anyio.Lock()
+        self._key_set: KeySet | None = None
+        self._resolved_jwks_uri: str | None = jwks_uri
+        self._last_fetch = 0.0
+        self._last_error: OidcKeySetError | None = None
+
+    @override
+    async def get_key_set(self, *, force_refresh: bool = False) -> KeySet:
+        """Return the cached key set, fetching a fresh one when stale or forced.
+
+        Raises:
+            OidcKeySetError: When the key set cannot be fetched, discovered or
+                read.
+        """
+        async with self._lock:
+            now = self._monotonic()
+            cached = self._fresh_cached(now, force_refresh=force_refresh)
+            if cached is not None:
+                return cached
+            held = self._held_failure(now)
+            if held is not None:
+                raise held
+            return await self._refresh(now)
+
+    async def _refresh(self, now: float) -> KeySet:
+        """Fetch a fresh key set, recording the attempt even when it fails.
+
+        The attempt time is recorded whether the fetch succeeds or fails, so the
+        cooldown applies to failures too and a burst of forced refreshes during
+        an outage makes one fetch, not one per call. When a fetch fails but a set
+        was cached before, that cached set keeps being served rather than the
+        request failing outright; when none was ever cached, the failure is
+        remembered so a burst during a cold-start outage re-raises it within the
+        cooldown rather than fetching again — see :meth:`_held_failure`.
+
+        Raises:
+            OidcKeySetError: When the fetch fails and no set was ever cached.
+        """
+        try:
+            key_set = await self._fetch()
+        except OidcKeySetError as error:
+            self._last_fetch = now
+            if self._key_set is not None:
+                return self._key_set
+            self._last_error = error
+            raise
+        self._key_set = key_set
+        self._last_fetch = now
+        self._last_error = None
+        return key_set
+
+    def _held_failure(self, now: float) -> OidcKeySetError | None:
+        """Return the remembered cold-start failure while its cooldown holds.
+
+        Only a provider that has never cached a set remembers one; within the
+        cooldown of that failure it is re-raised without a fetch, so a burst of
+        requests during a cold-start outage costs one fetch, not one each.
+        """
+        if self._key_set is not None or self._last_error is None:
+            return None
+        if now - self._last_fetch < self._cooldown:
+            return self._last_error
+        return None
+
+    def _fresh_cached(self, now: float, *, force_refresh: bool) -> KeySet | None:
+        """Return the cached set when it still answers this call, else ``None``."""
+        if self._key_set is None:
+            return None
+        window = self._cooldown if force_refresh else self._ttl
+        if now - self._last_fetch < window:
+            return self._key_set
+        return None
+
+    async def _fetch(self) -> KeySet:
+        """Discover the ``jwks_uri`` when needed, then fetch and read the set.
+
+        Raises:
+            OidcKeySetError: When discovery is needed but no base URI was given —
+                an impossible state the constructor forbids, guarded explicitly
+                in place of a bare assertion.
+        """
+        jwks_uri = self._resolved_jwks_uri
+        if jwks_uri is None:
+            base_uri = self._base_uri
+            if base_uri is None:  # pragma: no cover -- the constructor enforces one of the two
+                raise OidcKeySetError("A discovery key set provider has no base URI to discover.")
+            jwks_uri = await self._discover(base_uri)
+            self._require_secure(jwks_uri)
+            self._resolved_jwks_uri = jwks_uri
+        document = await self._get_json(jwks_uri)
+        try:
+            serialization = cast("KeySetSerialization", cast("object", document))
+            return KeySet.import_key_set(serialization)
+        except (JoseError, ValueError) as error:
+            raise OidcKeySetError(
+                f"The JWKS document at {jwks_uri} could not be read: {error}",
+            ) from error
+
+    async def _discover(self, base_uri: str) -> str:
+        """Read the discovery document at ``base_uri`` and return the ``jwks_uri`` it names.
+
+        Raises:
+            OidcKeySetError: When the document cannot be read or names no
+                usable ``jwks_uri``.
+        """
+        document = await self._get_json(base_uri.rstrip("/") + _DISCOVERY_PATH)
+        jwks_uri = document.get("jwks_uri")
+        if not isinstance(jwks_uri, str) or not jwks_uri:
+            raise OidcKeySetError(
+                f"The discovery document at {base_uri} names no jwks_uri.",
+            )
+        return jwks_uri
+
+    async def _get_json(self, uri: str) -> dict[str, object]:
+        """Fetch ``uri`` and return its JSON body as a mapping.
+
+        Raises:
+            OidcKeySetError: When the request fails or the body is not a JSON
+                object.
+        """
+        import httpx  # noqa: PLC0415 -- guarded behind the oidc extra
+
+        try:
+            async with self._http_client_factory() as client:
+                response = await client.get(uri)
+                _ = response.raise_for_status()
+                body = cast("object", response.json())
+        except (httpx.HTTPError, ValueError) as error:
+            raise OidcKeySetError(f"The request to {uri} failed: {error}") from error
+        if not isinstance(body, dict):
+            raise OidcKeySetError(f"The answer from {uri} is not a JSON object.")
+        return cast("dict[str, object]", body)
+
+    def _require_secure(self, uri: str) -> None:
+        """Refuse a non-``https`` endpoint unless insecure HTTP is allowed.
+
+        Raises:
+            InvalidArgumentError: When ``uri`` is not ``https`` and insecure
+                HTTP is not allowed.
+        """
+        if not self._allow_insecure_http and not uri.lower().startswith("https://"):
+            raise InvalidArgumentError(
+                f"The endpoint {uri} must be https; set allow_insecure_http for a dev issuer.",
+            )

xtr_security_http/request_matcher/__init__.py

@@ -0,0 +1,28 @@
+"""Request matchers: which requests a firewall's access rule claims.
+
+A rule pairs one of these with an attribute in an
+:class:`~xtr_security_http.access_map.AccessMap`; the first matcher that claims
+a request decides it. The matchers compose — a
+:class:`~xtr_security_http.request_matcher.chain_request_matcher.ChainRequestMatcher`
+holds a path, host, method and address matcher when a rule constrains all four.
+"""
+
+from __future__ import annotations
+
+from .callable_request_matcher import CallableRequestMatcher
+from .chain_request_matcher import ChainRequestMatcher
+from .host_request_matcher import HostRequestMatcher
+from .ip_request_matcher import IpRequestMatcher
+from .method_request_matcher import MethodRequestMatcher
+from .path_request_matcher import PathRequestMatcher
+from .request_matcher_interface import RequestMatcherInterface
+
+__all__ = [
+    "CallableRequestMatcher",
+    "ChainRequestMatcher",
+    "HostRequestMatcher",
+    "IpRequestMatcher",
+    "MethodRequestMatcher",
+    "PathRequestMatcher",
+    "RequestMatcherInterface",
+]

xtr_security_http/request_matcher/_pattern.py

@@ -0,0 +1,27 @@
+"""Compile a request matcher's regular expression, naming a bad one where written."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from xtr_security_core.exception import InvalidArgumentError
+
+if TYPE_CHECKING:
+    from re import Pattern
+
+__all__ = ["compile_pattern"]
+
+
+def compile_pattern(pattern: str, field_name: str) -> Pattern[str]:
+    """Compile ``pattern``, naming ``field_name`` when it will not compile.
+
+    Raises:
+        InvalidArgumentError: When ``pattern`` is not a valid regular expression.
+    """
+    try:
+        return re.compile(pattern)
+    except re.error as error:
+        raise InvalidArgumentError(
+            f'A request matcher\'s "{field_name}" is not a valid pattern: {error}.',
+        ) from error

xtr_security_http/request_matcher/callable_request_matcher.py

@@ -0,0 +1,37 @@
+"""A request matcher that defers the decision to a callable."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+
+from .request_matcher_interface import RequestMatcherInterface
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from starlette.requests import Request
+
+__all__ = ["CallableRequestMatcher"]
+
+
+@final
+class CallableRequestMatcher(RequestMatcherInterface):
+    """Claims a request when a callable says so.
+
+    The escape hatch a firewall uses when path, host and method do not express
+    its claim — the callable reads the request on its own and may reach into the
+    route template through ``request.scope["route"]``.
+    """
+
+    __slots__ = ("_decide",)
+
+    def __init__(self, decide: Callable[[Request], bool]) -> None:
+        """Record the callable that decides the claim."""
+        self._decide = decide
+
+    @override
+    def matches(self, request: Request) -> bool:
+        """Tell whether the callable claims ``request``."""
+        return self._decide(request)

xtr_security_http/request_matcher/chain_request_matcher.py

@@ -0,0 +1,37 @@
+"""A request matcher that claims a request only when every part does."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+
+from .request_matcher_interface import RequestMatcherInterface
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from starlette.requests import Request
+
+__all__ = ["ChainRequestMatcher"]
+
+
+@final
+class ChainRequestMatcher(RequestMatcherInterface):
+    """Claims a request only when every matcher it chains claims it.
+
+    An empty chain claims every request — nothing constrains it — the way a
+    rule with only a path becomes a chain of one, and a rule with no
+    constraints at all matches anything.
+    """
+
+    __slots__ = ("_matchers",)
+
+    def __init__(self, matchers: Sequence[RequestMatcherInterface]) -> None:
+        """Record the matchers that must all claim a request."""
+        self._matchers = tuple(matchers)
+
+    @override
+    def matches(self, request: Request) -> bool:
+        """Tell whether every chained matcher claims ``request``."""
+        return all(matcher.matches(request) for matcher in self._matchers)

xtr_security_http/request_matcher/host_request_matcher.py

@@ -0,0 +1,43 @@
+"""A request matcher that claims a request by its host."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+
+from ._pattern import compile_pattern
+from .request_matcher_interface import RequestMatcherInterface
+
+if TYPE_CHECKING:
+    from re import Pattern
+
+    from starlette.requests import Request
+
+__all__ = ["HostRequestMatcher"]
+
+
+@final
+class HostRequestMatcher(RequestMatcherInterface):
+    """Claims a request whose host matches a regular expression.
+
+    A request that carries no host is claimed all the same — the host
+    constraint is enforced only when there is a host to read, so a rule stays
+    applicable to requests a transport leaves hostless.
+    """
+
+    __slots__ = ("_pattern",)
+
+    def __init__(self, pattern: str) -> None:
+        """Compile ``pattern`` as the host expression to match.
+
+        Raises:
+            InvalidArgumentError: When ``pattern`` will not compile.
+        """
+        self._pattern: Pattern[str] = compile_pattern(pattern, "host")
+
+    @override
+    def matches(self, request: Request) -> bool:
+        """Tell whether the request host matches the pattern, or is absent."""
+        host = request.url.hostname
+        return host is None or self._pattern.search(host) is not None