xtr-webhook 4.0.2__py3-none-any.whl

xtr_webhook/client/abstract_request_parser.py

@@ -0,0 +1,248 @@
+"""Everything a parser of incoming webhooks does the same way as every other."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, TypeVar
+
+import msgspec
+from typing_extensions import override
+from xtr_http_message_contracts import ResponseInterface
+
+from xtr_webhook.exception import RejectWebhookError
+
+from .request_parser_interface import RequestParserInterface
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from xtr_http_foundation import RequestMatcherInterface
+    from xtr_http_message_contracts import ServerRequestInterface
+    from xtr_remote_event import RemoteEvent
+
+__all__ = ["AbstractRequestParser"]
+
+R = TypeVar("R", bound=ResponseInterface)
+
+_MALFORMED = "Request body is malformed."
+_PLAIN_TEXT = "text/plain; charset=utf-8"
+_UNACCEPTABLE = 406
+_ACCEPTED = 202
+
+
+class AbstractRequestParser(RequestParserInterface, ABC):
+    """A parser with everything but the two things that differ per sender filled in.
+
+    What is left to a subclass is which requests are its sender's
+    (:meth:`get_request_matcher`) and how to check and read one
+    (:meth:`do_parse`). Everything around those is the same for every sender,
+    and wrong in the same way when each parser writes it again: the matcher has
+    to run before anything is read out of the request, an unreadable body has to
+    come out as a refusal rather than as a 500, and both answers have to be the
+    ones the sender's side is waiting for.
+
+    The matchers a parser says that with come from
+    [xtr-http-foundation](https://pypi.org/project/xtr-http-foundation/):
+
+    ```python
+    class AcmeRequestParser(AbstractRequestParser):
+        def get_request_matcher(self) -> RequestMatcherInterface:
+            return ChainRequestMatcher([MethodRequestMatcher("POST"), IsJsonRequestMatcher()])
+
+        async def do_parse(self, request, secret):
+            payload = await self.read_json(request)
+            return RemoteEvent("acme", str(payload["id"]), payload)
+    ```
+    """
+
+    @override
+    async def parse(
+        self,
+        request: ServerRequestInterface,
+        secret: str,
+    ) -> RemoteEvent | Sequence[RemoteEvent] | None:
+        """Check the shape of the request, then hand it to :meth:`do_parse`.
+
+        A body that will not decode is the sender's doing, not this
+        application's, so it comes back as a refusal the endpoint can answer
+        with rather than as an error the endpoint would report as its own
+        fault.
+
+        Args:
+            request: The request that arrived.
+            secret: What the sender's signature is checked against.
+
+        Returns:
+            Whatever :meth:`do_parse` read out of the request.
+
+        Raises:
+            RejectWebhookError: When the request is not one this parser
+                claims, when its body will not decode, or when
+                :meth:`do_parse` refuses it.
+        """
+        await self.validate(request)
+
+        try:
+            return await self.do_parse(request, secret)
+        except (msgspec.DecodeError, UnicodeDecodeError) as unreadable:
+            raise RejectWebhookError(_UNACCEPTABLE, _MALFORMED) from unreadable
+
+    @override
+    async def create_successful_response(self, request: ServerRequestInterface, response: R) -> R:
+        """Answer a webhook that was read with 202 and nothing else.
+
+        The sender is told the webhook was taken, not what became of it: the
+        events it carried are handled after the answer has gone, so there is
+        nothing yet to report and nothing the sender could do with it.
+
+        Args:
+            request: The request the endpoint received. Unused here; a parser
+                whose sender wants something echoed back overrides this.
+            response: The response the endpoint built.
+
+        Returns:
+            ``response`` with the status set, its body left empty.
+        """
+        del request
+
+        return response.with_status(_ACCEPTED)
+
+    @override
+    async def create_rejected_response(
+        self,
+        reason: str,
+        request: ServerRequestInterface,
+        response: R,
+    ) -> R:
+        """Answer a refused webhook with 406 and the reason as plain text.
+
+        406 says the request was understood and still not acceptable, which is
+        what a wrong signature, a stale timestamp and an unreadable payload all
+        amount to from the sender's side. The reason goes in the body as text
+        because that is the one thing a sender's log is likely to keep.
+
+        Args:
+            reason: What to tell the sender.
+            request: The request the endpoint received. Unused here.
+            response: The response the endpoint built.
+
+        Returns:
+            ``response`` with the status, the content type and the reason on
+            it.
+        """
+        del request
+
+        refused = response.with_status(_UNACCEPTABLE).with_header("Content-Type", _PLAIN_TEXT)
+        _ = await refused.get_body().write(reason.encode())
+
+        return refused
+
+    @abstractmethod
+    def get_request_matcher(self) -> RequestMatcherInterface:
+        """Return what decides whether a request is this parser's sender's.
+
+        Returns:
+            The matcher every request is put through before it is read.
+        """
+
+    @abstractmethod
+    async def do_parse(
+        self,
+        request: ServerRequestInterface,
+        secret: str,
+    ) -> RemoteEvent | Sequence[RemoteEvent] | None:
+        """Check that the request is genuine and read the events out of it.
+
+        The request has already been through :meth:`get_request_matcher`, so
+        its shape is not in question here. Whatever the sender's protocol asks
+        for is: comparing a signature over the raw body against a header, in
+        constant time, and refusing a timestamp outside the window it allows.
+
+        Args:
+            request: The request that arrived.
+            secret: What the sender's signature is checked against.
+
+        Returns:
+            The event the request carried, every event when it carried
+            several, or ``None`` when it is one to accept and ignore.
+
+        Raises:
+            RejectWebhookError: On any failure to verify the request.
+        """
+
+    async def validate(self, request: ServerRequestInterface) -> None:
+        """Refuse a request this parser's matcher does not claim.
+
+        Awaited because a matcher may be about the body — whether it reads as
+        JSON, above all — which arrives as it is read.
+
+        Args:
+            request: The request that arrived.
+
+        Raises:
+            RejectWebhookError: When the matcher does not claim the request.
+        """
+        if not await self.get_request_matcher().matches(request):
+            raise RejectWebhookError(_UNACCEPTABLE, "Request does not match.")
+
+    async def read_body(self, request: ServerRequestInterface) -> bytes:
+        """Return the body of the request, whole, from its first byte.
+
+        A signature is made over exactly the bytes that arrived, and whatever
+        read the body before this — a framework logging it, a matcher looking
+        at it — left the cursor wherever it stopped. Reading the whole of a
+        stream rewinds it first, where it can be rewound, so that is all this
+        has to ask for.
+
+        Args:
+            request: The request that arrived.
+
+        Returns:
+            Every byte of the body.
+        """
+        return await request.get_body().get_contents()
+
+    async def read_json(self, request: ServerRequestInterface) -> dict[str, object]:
+        """Return the body of the request read as a JSON object.
+
+        Args:
+            request: The request that arrived.
+
+        Returns:
+            The object the body decoded to, its values left as they came.
+
+        Raises:
+            RejectWebhookError: When the body is valid JSON but not an object
+                — an array or a bare value is not a webhook payload.
+            msgspec.DecodeError: When the body is not JSON at all. Raised
+                rather than refused here, so that :meth:`parse` turns it into
+                the same refusal wherever in a subclass it came from.
+        """
+        return self._decode_json(await self.read_body(request))
+
+    def _decode_json(self, body: bytes) -> dict[str, object]:
+        """Return bytes already read from the body, as a JSON object.
+
+        What :meth:`read_json` does once the body is in hand, separately, for a
+        parser that needs those bytes before it is willing to decode them: a
+        signature covers the body, so it has to be read whole and verified
+        first, and reading the stream a second time to decode it would be
+        decoding something nothing checked.
+
+        Args:
+            body: The bytes of the body, whole.
+
+        Returns:
+            The object they decoded to, their values left as they came.
+
+        Raises:
+            RejectWebhookError: When they are valid JSON but not an object
+                — an array or a bare value is not a webhook payload.
+            msgspec.DecodeError: When they are not JSON at all. Raised rather
+                than refused here, so that :meth:`parse` turns it into the same
+                refusal wherever in a subclass it came from.
+        """
+        try:
+            return msgspec.json.decode(body, type=dict[str, object])
+        except msgspec.ValidationError as not_an_object:
+            raise RejectWebhookError(_UNACCEPTABLE, _MALFORMED) from not_an_object

xtr_webhook/client/request_parser.py

@@ -0,0 +1,272 @@
+"""The parser for webhooks this library's own sender signs, in any of its three formats."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import re
+from typing import TYPE_CHECKING, Final, final
+
+from typing_extensions import override
+from xtr_clock import Clock
+from xtr_http_foundation import ChainRequestMatcher, IsJsonRequestMatcher, MethodRequestMatcher
+from xtr_remote_event import RemoteEvent
+
+from xtr_webhook._standard_webhooks_signature import sign
+from xtr_webhook.exception import InvalidArgumentError, RejectWebhookError
+from xtr_webhook.server.signature_format import SignatureFormat
+
+from .abstract_request_parser import AbstractRequestParser
+
+if TYPE_CHECKING:
+    from xtr_clock import ClockInterface
+    from xtr_http_foundation import RequestMatcherInterface
+    from xtr_http_message_contracts import ServerRequestInterface
+
+__all__ = ["RequestParser"]
+
+_UNACCEPTABLE: Final = 406
+
+_NUMERIC: Final = re.compile(r"^-?\d{1,19}$")
+"""What a timestamp this parser can bound looks like: an integer, nothing else.
+
+Bounded in length as well as in shape, because this runtime refuses to read a
+long enough digit string as an int at all — and a sender that sent one is owed
+the same refusal as any other unacceptable timestamp, not a server error.
+Nineteen digits reach far past any time the window can accept.
+"""
+
+
+@final
+class RequestParser(AbstractRequestParser):
+    """Reads webhooks signed the way this library's own sender signs them.
+
+    The mirror of the sender's configurators: the same two signature schemes,
+    under the same default header names, chosen by the same
+    :class:`SignatureFormat <xtr_webhook.server.SignatureFormat>`. Under the
+    transitional format either scheme authenticates a request, which is what
+    lets the two ends migrate on different days.
+
+    The signature header may carry several whitespace-separated entries — one
+    per secret during a rotation — and any one that verifies is enough. When a
+    Standard Webhooks entry verifies, the timestamp it covers is then held to a
+    window around now, so a delivery captured once cannot be fed back later.
+    """
+
+    def __init__(  # noqa: PLR0913, PLR0917 — every name and bound has a default both ends share.
+        self,
+        algorithm: str = "sha256",
+        signature_header_name: str = "Webhook-Signature",
+        event_header_name: str = "Webhook-Event",
+        id_header_name: str = "Webhook-Id",
+        timestamp_header_name: str = "Webhook-Timestamp",
+        signature_format: SignatureFormat | str = SignatureFormat.LEGACY,
+        timestamp_tolerance: int = 300,
+        clock: ClockInterface | None = None,
+    ) -> None:
+        """Configure what to verify against, under which names and bounds.
+
+        Args:
+            algorithm: The digest the legacy signature is recomputed with. The
+                Standard Webhooks signature is always SHA-256; the scheme fixes it.
+            signature_header_name: The header the signature entries arrive in.
+            event_header_name: The header the event's name arrives in, where the
+                format sends one.
+            id_header_name: The header the event's id arrives in.
+            timestamp_header_name: The header the signed timestamp arrives in.
+            signature_format: Which scheme a request must carry. The string a
+                configuration carries is accepted.
+            timestamp_tolerance: How many seconds either side of now a signed
+                timestamp may be. Zero or less turns the bound off — for a
+                replayed capture to matter less than clocks that cannot be kept
+                close enough.
+            clock: What now is measured by. ``None`` reads whichever clock is in
+                force when a request arrives, so a test can freeze it without
+                rebuilding the parser.
+
+        Raises:
+            InvalidArgumentError: When this runtime cannot make ``algorithm``, or
+                when ``signature_format`` names no format. Both are caught here
+                rather than at the first webhook: a receiver that cannot
+                recompute a signature is misconfigured, and finding out when one
+                arrives means refusing a sender for this side's mistake.
+        """
+        if algorithm not in hashlib.algorithms_available:
+            raise InvalidArgumentError(f'The signing algorithm "{algorithm}" is not available.')
+
+        self._algorithm = algorithm
+        self._signature_header_name = signature_header_name
+        self._event_header_name = event_header_name
+        self._id_header_name = id_header_name
+        self._timestamp_header_name = timestamp_header_name
+        self._signature_format = SignatureFormat.parse(signature_format)
+        self._timestamp_tolerance = timestamp_tolerance
+        self._clock = clock
+
+    @override
+    def get_request_matcher(self) -> RequestMatcherInterface:
+        """Claim only a ``POST`` whose body reads as JSON, as the sender's side emits.
+
+        The body itself decides, not the ``Content-Type`` header: a sender that
+        announces nothing still sent JSON, and one that announces JSON and sent
+        something else did not.
+        """
+        return ChainRequestMatcher([MethodRequestMatcher("POST"), IsJsonRequestMatcher()])
+
+    @override
+    async def do_parse(self, request: ServerRequestInterface, secret: str) -> RemoteEvent:
+        """Check that the request is genuine and read the one event it carries.
+
+        In that order, and over one read of the body: nothing decodes it until a
+        signature over those exact bytes has verified, so a request that is not
+        the sender's is answered on its signature rather than on whatever its
+        body turned out to be — which is both what the sender needs told and the
+        answer that says least about what this side does with a payload.
+
+        Args:
+            request: The request that arrived, already claimed by the matcher.
+            secret: What the signature entries are checked against.
+
+        Returns:
+            The event, named by the payload's ``type`` key when the Standard
+            Webhooks entry authenticated the request — that scheme signs no
+            header, so a name sent as one cannot be trusted — and by the event
+            header otherwise, which the legacy scheme does sign.
+
+        Raises:
+            InvalidArgumentError: When ``secret`` is empty. That is this side's
+                configuration, not the sender's doing, so it surfaces as a
+                server error rather than as a refusal.
+            RejectWebhookError: When a required header is missing, no signature
+                entry verifies, the signed timestamp is outside the window, the
+                body is not a JSON object, or the payload names no event.
+        """
+        if not secret:
+            raise InvalidArgumentError("A non-empty secret is required.")
+
+        body = await self.read_body(request)
+
+        required = [self._signature_header_name, self._id_header_name]
+        if self._signature_format is SignatureFormat.LEGACY:
+            required.append(self._event_header_name)
+        elif self._signature_format is SignatureFormat.STANDARD:
+            required.append(self._timestamp_header_name)
+
+        for name in required:
+            if not request.has_header(name):
+                raise RejectWebhookError(
+                    _UNACCEPTABLE, f'Missing "{name}" HTTP request signature header.'
+                )
+
+        verified = self._verify_signature(request, body, secret)
+        payload = self._decode_json(body)
+
+        return RemoteEvent(
+            self._event_name(payload)
+            if verified is SignatureFormat.STANDARD
+            else request.get_header_line(self._event_header_name),
+            request.get_header_line(self._id_header_name),
+            payload,
+        )
+
+    def _verify_signature(
+        self, request: ServerRequestInterface, body: bytes, secret: str
+    ) -> SignatureFormat:
+        """Return the scheme of the entry that authenticated the request.
+
+        The header may carry several whitespace-separated entries, one per
+        secret during a rotation. Each expectation is computed once, before its
+        loop, so the number of entries a request carries does not drive the CPU
+        cost of rejecting it; every comparison is :func:`hmac.compare_digest`,
+        so the time one takes says nothing about how much of it was right.
+
+        Args:
+            request: The request that arrived.
+            body: Its body, whole — the exact bytes the sender signed.
+            secret: What the entries are checked against.
+
+        Raises:
+            RejectWebhookError: When no entry verifies, or when the one that did
+                covers a timestamp outside the window.
+        """
+        candidates = request.get_header_line(self._signature_header_name).split()
+        message_id = request.get_header_line(self._id_header_name)
+
+        # The Standard Webhooks entry is tried first, so that a request carrying
+        # both schemes is replay-bounded whatever order its entries arrive in.
+        if self._signature_format is not SignatureFormat.LEGACY and request.has_header(
+            self._timestamp_header_name
+        ):
+            timestamp = request.get_header_line(self._timestamp_header_name)
+            expected = sign(message_id, timestamp, body, secret).encode()
+
+            for candidate in candidates:
+                if hmac.compare_digest(expected, candidate.encode()):
+                    self._check_timestamp(timestamp)
+
+                    return SignatureFormat.STANDARD
+
+        if self._signature_format is not SignatureFormat.STANDARD and request.has_header(
+            self._event_header_name
+        ):
+            event = request.get_header_line(self._event_header_name)
+            digest = hmac.new(
+                secret.encode(), event.encode() + message_id.encode() + body, self._algorithm
+            )
+            expected = f"{self._algorithm}={digest.hexdigest()}".encode()
+
+            for candidate in candidates:
+                if hmac.compare_digest(expected, candidate.encode()):
+                    return SignatureFormat.LEGACY
+
+        raise RejectWebhookError(_UNACCEPTABLE, "Signature is wrong.")
+
+    def _check_timestamp(self, timestamp: str) -> None:
+        """Refuse a signed timestamp outside the window around now.
+
+        Run only after a Standard Webhooks entry verified, because only then is
+        the timestamp known to be the sender's rather than an attacker's.
+
+        Args:
+            timestamp: What the timestamp header carried, already signed.
+
+        Raises:
+            RejectWebhookError: When the timestamp does not read as an integer
+                this runtime will convert — a value that cannot be bounded is
+                not accepted on faith, and one too long to read is refused as
+                such rather than raised over — or lies further than the
+                tolerance from now.
+        """
+        if self._timestamp_tolerance <= 0:
+            return
+
+        now = int((self._clock or Clock.get()).now().timestamp())
+
+        if (
+            _NUMERIC.match(timestamp) is None
+            or abs(now - int(timestamp)) > self._timestamp_tolerance
+        ):
+            raise RejectWebhookError(
+                _UNACCEPTABLE,
+                f'The "{self._timestamp_header_name}" HTTP request header is outside the '
+                "accepted window.",
+            )
+
+    def _event_name(self, payload: dict[str, object]) -> str:
+        """Return the event's name from the payload's ``type`` key.
+
+        Args:
+            payload: The body, already decoded.
+
+        Raises:
+            RejectWebhookError: When the key is missing or not a string — the
+                scheme that signed this request puts the name there, so a
+                payload without one names no event.
+        """
+        name = payload.get("type")
+        if not isinstance(name, str):
+            raise RejectWebhookError(
+                _UNACCEPTABLE, 'The payload is missing the "type" key holding the event name.'
+            )
+
+        return name

xtr_webhook/client/request_parser_interface.py

@@ -0,0 +1,90 @@
+"""What reads an incoming webhook into events, and answers its sender."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, TypeVar, runtime_checkable
+
+from xtr_http_message_contracts import ResponseInterface
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from xtr_http_message_contracts import ServerRequestInterface
+    from xtr_remote_event import RemoteEvent
+
+__all__ = ["RequestParserInterface"]
+
+R = TypeVar("R", bound=ResponseInterface)
+
+
+@runtime_checkable
+class RequestParserInterface(Protocol):
+    """Reads an incoming webhook into events, and refuses the ones that are not genuine.
+
+    One parser speaks for one sender: it knows which requests are that sender's,
+    how that sender signs them, and what its payload means. Everything a sender
+    can get wrong — a signature that does not match, a timestamp outside the
+    window, a body that is not readable — is one refusal, so the endpoint in
+    front of it has a single thing to answer with.
+
+    The endpoint owns the response: an HTTP message is immutable, so a parser
+    cannot build one out of nothing and still be sure it carries what the
+    application puts on every response. It is handed one and gives back the one
+    it changed.
+    """
+
+    async def parse(
+        self,
+        request: ServerRequestInterface,
+        secret: str,
+    ) -> RemoteEvent | Sequence[RemoteEvent] | None:
+        """Read a request into the events it carries.
+
+        Args:
+            request: The request that arrived.
+            secret: What the sender's signature is checked against.
+
+        Returns:
+            The event the request carried, every event when it carried
+            several, or ``None`` when it is one to accept and ignore — a
+            sender's keep-alive, an event kind this parser does not speak for.
+
+        Raises:
+            RejectWebhookError: When the request is refused, whatever the
+                reason: a signature that does not match, a replayed timestamp,
+                an unreadable payload.
+        """
+        ...
+
+    async def create_successful_response(self, request: ServerRequestInterface, response: R) -> R:
+        """Fill in the answer to a webhook that was read.
+
+        Args:
+            request: The request the endpoint received, for a parser whose
+                sender wants something of its own echoed back.
+            response: The response the endpoint built, to change and give back.
+
+        Returns:
+            The response to send, which is ``response`` with the answer on it.
+        """
+        ...
+
+    async def create_rejected_response(
+        self,
+        reason: str,
+        request: ServerRequestInterface,
+        response: R,
+    ) -> R:
+        """Fill in the answer to a webhook that was refused.
+
+        Args:
+            reason: What to tell the sender. A sender is not debugged by the
+                receiver, so this is the refusal itself, never what gave it
+                away.
+            request: The request the endpoint received.
+            response: The response the endpoint built, to change and give back.
+
+        Returns:
+            The response to send, which is ``response`` with the refusal on it.
+        """
+        ...

xtr_webhook/controller/__init__.py

@@ -0,0 +1,12 @@
+"""The endpoint every incoming webhook arrives at.
+
+One endpoint for every subscriber: the type in the URL picks the parser that reads
+the webhook and the secret it is checked against, so the events it carried reach a
+worker and the sender is answered straight away.
+"""
+
+from __future__ import annotations
+
+from .webhook_controller import WebhookController
+
+__all__ = ["WebhookController"]

xtr_webhook/controller/_built_parsers.py

@@ -0,0 +1,65 @@
+"""Parsers already built, handed over by the type of webhook each reads."""
+
+from __future__ import annotations
+
+from types import MappingProxyType
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+from xtr_service_contracts import ServiceProviderInterface
+
+from xtr_webhook.exception import LogicError
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable, Mapping
+
+    from xtr_webhook.client import RequestParserInterface
+
+__all__ = ["BuiltParsers"]
+
+
+@final
+class BuiltParsers(ServiceProviderInterface["RequestParserInterface"]):
+    """Hands over parsers from a mapping — what stands in where there is no container.
+
+    The controller asks for a parser by type and does not care where it came
+    from: a container's locator, which builds each parser with its own
+    dependencies the first time a webhook for it arrives, or a mapping of
+    parsers built by hand. This is the second of those, so the controller has
+    one thing to ask rather than two.
+    """
+
+    __slots__ = ("_parsers",)
+
+    def __init__(self, parsers: Mapping[str, RequestParserInterface]) -> None:
+        """Hand over ``parsers``, by the type of webhook each reads.
+
+        The mapping is copied: which parser speaks for a type is fixed once
+        the endpoint is built, so a caller still writing to its own dict
+        cannot change who reads a subscriber's webhooks halfway through a
+        deploy's life.
+        """
+        self._parsers = dict(parsers)
+
+    @override
+    async def get(self, name: Hashable, /) -> RequestParserInterface:
+        """Return the parser reading webhooks of the type ``name``.
+
+        Raises:
+            LogicError: If there is none. The endpoint asks :meth:`has` first
+                and answers 404 itself, so reaching this means the two were
+                asked different questions — a mistake in the code, not a
+                webhook naming a type nobody subscribed to.
+        """
+        parser = self._parsers.get(str(name))
+        if parser is None:
+            raise LogicError(f'Unable to find a parser for the webhook type "{name}".')
+        return parser
+
+    @override
+    def has(self, name: Hashable, /) -> bool:
+        return str(name) in self._parsers
+
+    @override
+    def provided_services(self) -> Mapping[Hashable, type[object]]:
+        return MappingProxyType({name: type(parser) for name, parser in self._parsers.items()})