meterbase 0.1.0__py3-none-any.whl

meterbase/webhooks.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import json
+import math
+import time
+from collections.abc import Iterable, Sequence
+from typing import Any, Protocol, cast
+
+from ._json import is_object
+from .errors import MeterbaseError, WebhookVerificationError
+from .types import EntitlementReachedEvent, ThresholdCrossedEvent, WebhookEvent
+
+__all__ = ["WebhookHeaders", "verify_webhook"]
+
+SECRET_PREFIX = "whsec_"
+DEFAULT_TOLERANCE_SECONDS = 5 * 60
+
+_EVENTS: dict[str, type[WebhookEvent]] = {
+    "threshold.crossed": ThresholdCrossedEvent,
+    "entitlement.reached": EntitlementReachedEvent,
+}
+
+
+class WebhookHeaders(Protocol):
+    """
+    A request's headers, as a web framework hands them over: Django's
+    `request.headers`, Flask's, Starlette's, or a plain `dict`. Names are
+    matched without regard to case.
+    """
+
+    def get(self, key: str, /) -> Any: ...
+
+    def items(self) -> Iterable[tuple[Any, Any]]: ...
+
+
+def verify_webhook(
+    *,
+    payload: str | bytes,
+    headers: WebhookHeaders,
+    secret: str | Sequence[str],
+    tolerance_seconds: float = DEFAULT_TOLERANCE_SECONDS,
+) -> WebhookEvent:
+    """
+    Checks a delivery's signature and timestamp the Standard Webhooks way, then
+    returns the event. Raises `WebhookVerificationError` when it is not one
+    Meterbase signed recently.
+
+    `payload` is the body exactly as received: re-serialized JSON will not
+    verify. `secret` is the endpoint's `whsec_…` secret; pass both while
+    rotating. `tolerance_seconds` is how far `webhook-timestamp` may be from
+    now.
+
+    The event is a `ThresholdCrossedEvent` or an `EntitlementReachedEvent`, so
+    `isinstance` tells them apart. A type this release does not know reads as
+    a plain `WebhookEvent`: new types can be added, so ignore any you do not
+    handle.
+    """
+    msg_id = _header(headers, "webhook-id")
+    timestamp = _header(headers, "webhook-timestamp")
+    signatures = _header(headers, "webhook-signature")
+    if not msg_id or not timestamp or not signatures:
+        raise WebhookVerificationError(
+            "Missing a webhook-id, webhook-timestamp or webhook-signature header."
+        )
+
+    sent_at = _whole_number(timestamp)
+    if sent_at is None or abs(time.time() - sent_at) > tolerance_seconds:
+        raise WebhookVerificationError(
+            "The webhook-timestamp is too far from now; this may be a replay."
+        )
+
+    body = payload.encode("utf-8") if isinstance(payload, str) else bytes(payload)
+    signed = f"{msg_id}.{timestamp}.".encode() + body
+    candidates = [
+        _from_base64(entry[len("v1,") :])
+        for entry in signatures.split(" ")
+        if entry.startswith("v1,")
+    ]
+
+    for each in [secret] if isinstance(secret, str) else secret:
+        key = (
+            _from_base64(each[len(SECRET_PREFIX) :])
+            if each.startswith(SECRET_PREFIX)
+            else None
+        )
+        if not key:
+            raise WebhookVerificationError(
+                "The secret should be whsec_ and base64: copy it from the "
+                "endpoint's settings."
+            )
+
+        expected = hmac.new(key, signed, hashlib.sha256).digest()
+        for candidate in candidates:
+            # `compare_digest` compares in constant time.
+            if candidate is not None and hmac.compare_digest(candidate, expected):
+                return _event(body)
+
+    raise WebhookVerificationError(
+        "No signature matches: the body changed, or this is the wrong secret."
+    )
+
+
+def _header(headers: WebhookHeaders, name: str) -> str | None:
+    value: object = headers.get(name)
+    if value is None:
+        # A plain dict matches case exactly, and some frameworks title-case.
+        value = next(
+            (v for k, v in headers.items() if isinstance(k, str) and k.lower() == name),
+            None,
+        )
+    if isinstance(value, (list, tuple)):
+        values = cast("Sequence[object]", value)
+        value = values[0] if values else None
+    if isinstance(value, bytes):
+        value = value.decode("latin-1")
+    return value if isinstance(value, str) else None
+
+
+def _whole_number(text: str) -> float | None:
+    try:
+        value = float(text)
+    except ValueError:
+        return None
+    return value if math.isfinite(value) and value.is_integer() else None
+
+
+def _from_base64(text: str) -> bytes | None:
+    try:
+        # Padding restored first, as a browser's `atob` would.
+        return base64.b64decode(text + "=" * (-len(text) % 4), validate=True)
+    except (binascii.Error, ValueError):
+        return None
+
+
+def _event(body: bytes) -> WebhookEvent:
+    try:
+        data = json.loads(body)
+    except ValueError as error:
+        raise MeterbaseError(
+            "The webhook is signed, but its body is not JSON."
+        ) from error
+
+    if not is_object(data):
+        raise MeterbaseError(
+            "The webhook is signed, but its body is not a JSON object."
+        )
+
+    kind = data.get("type")
+    event = _EVENTS.get(kind, WebhookEvent) if isinstance(kind, str) else WebhookEvent
+    return event(data)