fastapi-microservices-platform-sdk 0.1.1__py3-none-any.whl

webhook_platform_sdk/producer.py

@@ -0,0 +1,391 @@
+"""Synchronous producer and management clients with safe failures."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Literal
+
+import httpx
+
+EnvelopeMode = Literal["native", "cloudevents"]
+QueryValue = str | int | float | bool | None
+
+# Sentinel distinguishing "argument not passed" from an explicit None,
+# which the PATCH endpoint treats as "clear this field".
+_UNSET: Any = object()
+
+
+class WebhookPlatformError(Exception):
+    """Base class that never embeds credentials or response bodies."""
+
+
+class TransportError(WebhookPlatformError):
+    """The service could not be reached within the configured timeout."""
+
+    def __init__(self) -> None:
+        super().__init__("Webhook Platform request failed before a response")
+
+
+class ApiError(WebhookPlatformError):
+    """A bounded HTTP failure without raw response content."""
+
+    def __init__(
+        self,
+        status_code: int,
+        code: str = "HTTP_ERROR",
+        retry_after: int | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.code = code
+        self.retry_after = retry_after
+        super().__init__(
+            f"Webhook Platform request failed "
+            f"(status={status_code}, code={code})"
+        )
+
+
+def _safe_error(response: httpx.Response) -> ApiError:
+    code = "HTTP_ERROR"
+    try:
+        document = response.json()
+        candidate = document.get("error", {}).get("code")
+        if isinstance(candidate, str) and candidate.isascii():
+            if 1 <= len(candidate) <= 64:
+                code = candidate
+    except (ValueError, AttributeError):
+        pass
+    retry_after: int | None = None
+    raw_retry_after = response.headers.get("Retry-After")
+    if raw_retry_after and raw_retry_after.isdigit():
+        retry_after = min(int(raw_retry_after), 86_400)
+    return ApiError(response.status_code, code, retry_after)
+
+
+class _JsonClient:
+    def __init__(
+        self,
+        base_url: str,
+        headers: Mapping[str, str],
+        *,
+        timeout: httpx.Timeout | float | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self._owns_client = client is None
+        self._headers = dict(headers)
+        self._client = client or httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout
+            or httpx.Timeout(10.0, connect=5.0, write=10.0, pool=5.0),
+            follow_redirects=False,
+        )
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: object | None = None,
+        data: Mapping[str, str] | None = None,
+        headers: Mapping[str, str] | None = None,
+        params: Mapping[str, QueryValue] | None = None,
+    ) -> Any:
+        try:
+            request_headers = self._headers | dict(headers or {})
+            response = self._client.request(
+                method,
+                path,
+                json=json,
+                data=data,
+                headers=request_headers,
+                params=params,
+            )
+        except httpx.HTTPError as exc:
+            raise TransportError() from exc
+        if response.status_code not in {200, 201, 202, 204}:
+            raise _safe_error(response)
+        if response.status_code == 204:
+            return None
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise ApiError(response.status_code, "INVALID_RESPONSE") from exc
+
+
+class AuthClient(_JsonClient):
+    """Register users and exchange passwords without retaining credentials."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        timeout: httpx.Timeout | float | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(
+            base_url,
+            {"User-Agent": "webhook-platform-python/0.1"},
+            timeout=timeout,
+            client=client,
+        )
+
+    def register(
+        self, email: str, name: str, password: str
+    ) -> dict[str, Any]:
+        result = self._request(
+            "POST",
+            "/users/",
+            json={"email": email, "name": name, "password": password},
+        )
+        if not isinstance(result, dict):
+            raise ApiError(201, "INVALID_RESPONSE")
+        return result
+
+    def login(self, email: str, password: str) -> str:
+        result = self._request(
+            "POST",
+            "/auth/login",
+            data={"username": email, "password": password},
+        )
+        token = result.get("access_token") if isinstance(result, dict) else None
+        if not isinstance(token, str) or not token:
+            raise ApiError(200, "INVALID_RESPONSE")
+        return token
+
+
+class Producer(_JsonClient):
+    """Send events without implicit retries.
+
+    A caller may retry only with the same idempotency key. The client never
+    retries automatically, so an ambiguous transport failure cannot create a
+    second logical event under a different key.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        timeout: httpx.Timeout | float | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        super().__init__(
+            base_url,
+            {
+                "X-API-Key": api_key,
+                "User-Agent": "webhook-platform-python/0.1",
+            },
+            timeout=timeout,
+            client=client,
+        )
+
+    def send_event(
+        self,
+        event_type: str,
+        payload: object,
+        idempotency_key: str,
+        *,
+        envelope_mode: EnvelopeMode = "native",
+    ) -> dict[str, Any]:
+        if not event_type or not idempotency_key:
+            raise ValueError("event_type and idempotency_key are required")
+        result = self._request(
+            "POST",
+            "/v1/events",
+            json={
+                "type": event_type,
+                "payload": payload,
+                "envelope_mode": envelope_mode,
+            },
+            headers={"Idempotency-Key": idempotency_key},
+        )
+        if not isinstance(result, dict):
+            raise ApiError(202, "INVALID_RESPONSE")
+        return result
+
+
+class ManagementClient(_JsonClient):
+    """Bearer-authenticated control-plane operations used by the CLI."""
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        timeout: httpx.Timeout | float | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        if not token:
+            raise ValueError("token is required")
+        super().__init__(
+            base_url,
+            {
+                "Authorization": f"Bearer {token}",
+                "User-Agent": "webhook-platform-python/0.1",
+            },
+            timeout=timeout,
+            client=client,
+        )
+
+    def list_organizations(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/v1/organizations")
+
+    def create_organization(self, name: str) -> dict[str, Any]:
+        return self._request("POST", "/v1/organizations", json={"name": name})
+
+    def list_projects(self, organization_id: str) -> list[dict[str, Any]]:
+        return self._request(
+            "GET", f"/v1/organizations/{organization_id}/projects"
+        )
+
+    def create_project(
+        self, organization_id: str, name: str
+    ) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            f"/v1/organizations/{organization_id}/projects",
+            json={"name": name},
+        )
+
+    def list_api_keys(self, project_id: str) -> list[dict[str, Any]]:
+        return self._request("GET", f"/v1/projects/{project_id}/api-keys")
+
+    def create_api_key(
+        self,
+        project_id: str,
+        name: str,
+        *,
+        expires_in_days: int | None = None,
+    ) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            f"/v1/projects/{project_id}/api-keys",
+            json={
+                "name": name,
+                "scopes": ["events:write"],
+                "expires_in_days": expires_in_days,
+            },
+        )
+
+    def revoke_api_key(
+        self, project_id: str, api_key_id: str
+    ) -> dict[str, Any]:
+        return self._request(
+            "DELETE", f"/v1/projects/{project_id}/api-keys/{api_key_id}"
+        )
+
+    def list_endpoints(self, project_id: str) -> list[dict[str, Any]]:
+        return self._request("GET", f"/v1/projects/{project_id}/endpoints")
+
+    def create_endpoint(
+        self,
+        project_id: str,
+        url: str,
+        description: str | None = None,
+        *,
+        event_types: list[str] | None = None,
+        signature_scheme: str | None = None,
+    ) -> dict[str, Any]:
+        """Create an endpoint, optionally subscribed to specific types.
+
+        ``event_types`` accepts exact event types and trailing ``prefix.*``
+        wildcards. ``signature_scheme`` selects ``legacy`` or ``standard``
+        wire signatures (ADR 0002). Optional fields are left off the
+        request when unset so the call also works against servers that
+        predate them.
+        """
+        body: dict[str, Any] = {"url": url, "description": description}
+        if event_types is not None:
+            body["event_types"] = list(event_types)
+        if signature_scheme is not None:
+            body["signature_scheme"] = signature_scheme
+        return self._request(
+            "POST",
+            f"/v1/projects/{project_id}/endpoints",
+            json=body,
+        )
+
+    def update_endpoint(
+        self,
+        project_id: str,
+        endpoint_id: str,
+        *,
+        url: str = _UNSET,
+        description: str | None = _UNSET,
+        is_active: bool = _UNSET,
+        event_types: list[str] | None = _UNSET,
+        signature_scheme: str = _UNSET,
+    ) -> dict[str, Any]:
+        """Partially update an endpoint.
+
+        Only keyword arguments that are passed are sent, matching the API's
+        PATCH semantics. Pass ``event_types=None`` explicitly to clear a
+        subscription filter. Changing ``signature_scheme`` to ``standard``
+        returns a one-time ``signing_secret`` usable with any Standard
+        Webhooks library; capture it directly into a secret manager.
+        """
+        changes: dict[str, Any] = {}
+        for field, value in (
+            ("url", url),
+            ("description", description),
+            ("is_active", is_active),
+            ("event_types", event_types),
+            ("signature_scheme", signature_scheme),
+        ):
+            if value is not _UNSET:
+                changes[field] = value
+        if not changes:
+            raise ValueError("update_endpoint requires at least one change")
+        return self._request(
+            "PATCH",
+            f"/v1/projects/{project_id}/endpoints/{endpoint_id}",
+            json=changes,
+        )
+
+    def list_deliveries(
+        self, project_id: str, *, offset: int = 0, limit: int = 50
+    ) -> list[dict[str, Any]]:
+        return self._request(
+            "GET",
+            f"/v1/projects/{project_id}/deliveries",
+            params={"offset": offset, "limit": limit},
+        )
+
+    def get_delivery(
+        self, project_id: str, delivery_id: str
+    ) -> dict[str, Any]:
+        return self._request(
+            "GET", f"/v1/projects/{project_id}/deliveries/{delivery_id}"
+        )
+
+    def replay_delivery(
+        self, project_id: str, delivery_id: str
+    ) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            f"/v1/projects/{project_id}/deliveries/{delivery_id}/replay",
+        )
+
+    def replay_deliveries(
+        self,
+        project_id: str,
+        delivery_ids: list[str],
+        idempotency_key: str,
+    ) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            f"/v1/projects/{project_id}/replays",
+            json={"delivery_ids": delivery_ids},
+            headers={"Idempotency-Key": idempotency_key},
+        )

webhook_platform_sdk/receiver.py

@@ -0,0 +1,281 @@
+"""Raw-byte receiver verification and durable deduplication helpers."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import json
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+class ReceiverVerificationError(ValueError):
+    """Base class for bounded receiver verification failures."""
+
+
+class InvalidSignature(ReceiverVerificationError):
+    def __init__(self) -> None:
+        super().__init__("Webhook signature is invalid")
+
+
+class SignatureExpired(ReceiverVerificationError):
+    def __init__(self) -> None:
+        super().__init__("Webhook timestamp is outside the allowed tolerance")
+
+
+class DuplicateEvent(ReceiverVerificationError):
+    def __init__(self, event_id: str) -> None:
+        self.event_id = event_id
+        super().__init__("Webhook event was already accepted")
+
+
+class DurableDeduplicator(Protocol):
+    """Atomically reserve an event ID in durable receiver storage."""
+
+    def claim(self, event_id: str) -> bool:
+        """Return true only for the first durable reservation."""
+
+
+@dataclass(frozen=True)
+class ReceiverEvent:
+    event_id: str
+    event_type: str
+    timestamp: int
+    body: dict[str, Any]
+    raw_body: bytes
+
+
+def _signature_parts(header: str) -> tuple[int, list[str]]:
+    """Parse the legacy ``t=<seconds>,v1=<hex>`` header format.
+
+    Only tokens in the legacy shape participate; unrecognized
+    space-delimited tokens (for example Standard Webhooks ``v1,<base64>``
+    entries) are ignored rather than treated as malformed, so a receiver on
+    this SDK survives header formats it does not use.
+    """
+    timestamp: int | None = None
+    signatures: list[str] = []
+    for token in header.split():
+        if "=" not in token.partition(",")[0]:
+            continue
+        for item in token.split(","):
+            name, separator, value = item.strip().partition("=")
+            if not separator or not value:
+                raise InvalidSignature()
+            if name == "t":
+                if timestamp is not None or not value.isdigit():
+                    raise InvalidSignature()
+                timestamp = int(value)
+            elif name == "v1":
+                if len(value) == 64:
+                    try:
+                        bytes.fromhex(value)
+                    except ValueError as exc:
+                        raise InvalidSignature() from exc
+                    signatures.append(value.lower())
+    if timestamp is None or not signatures:
+        raise InvalidSignature()
+    return timestamp, signatures
+
+
+def _standard_signatures(header: str) -> list[str]:
+    """Collect Standard Webhooks ``v1,<base64>`` tokens, ignoring others.
+
+    Non-ASCII values are dropped here so a malformed or malicious header
+    fails verification (``InvalidSignature``) instead of raising
+    ``TypeError`` from the constant-time comparison.
+    """
+    signatures: list[str] = []
+    for token in header.split():
+        version, separator, value = token.partition(",")
+        if separator and version == "v1" and value and value.isascii():
+            signatures.append(value)
+    return signatures
+
+
+def _secret_key_bytes(secret: str) -> bytes | None:
+    """Decode either secret serialization to the raw digest bytes.
+
+    Accepts ``whsec_`` + padded standard base64 (the standard form) and
+    ``whsec_`` + unpadded base64url (the legacy form). Returns ``None``
+    when the secret does not decode, in which case only legacy
+    verification (which keys on the ASCII string itself) is possible.
+
+    ``validate=True`` is load-bearing: without it ``b64decode`` silently
+    drops characters outside its alphabet, so a legacy-form (base64url)
+    secret containing ``-``/``_`` would "decode" through the standard
+    decoder into wrong key bytes instead of falling through to the
+    urlsafe decoder.
+    """
+    if not secret.startswith("whsec_"):
+        return None
+    encoded = secret.removeprefix("whsec_")
+    padded = encoded + "=" * (-len(encoded) % 4)
+    # urlsafe_b64decode has no validate parameter and would also silently
+    # accept the wrong alphabet, so translate explicitly and validate both.
+    candidates = (padded, padded.replace("-", "+").replace("_", "/"))
+    for candidate in candidates:
+        try:
+            return base64.b64decode(candidate, validate=True)
+        except (ValueError, binascii.Error):
+            continue
+    return None
+
+
+def _header_has_legacy_token(header: str) -> bool:
+    return any(
+        "=" in token.partition(",")[0] for token in header.split()
+    )
+
+
+def verify_signature(
+    raw_body: bytes,
+    signature_header: str,
+    secret: str,
+    *,
+    tolerance_seconds: int = 300,
+    now: int | None = None,
+) -> int:
+    """Verify a legacy HMAC over timestamp + period + exact body bytes."""
+    if tolerance_seconds < 0:
+        raise ValueError("tolerance_seconds must be non-negative")
+    timestamp, signatures = _signature_parts(signature_header)
+    current_time = int(time.time()) if now is None else now
+    if abs(current_time - timestamp) > tolerance_seconds:
+        raise SignatureExpired()
+    signed = str(timestamp).encode("ascii") + b"." + raw_body
+    expected = hmac.new(
+        secret.encode("utf-8"), signed, hashlib.sha256
+    ).hexdigest()
+    if not any(hmac.compare_digest(expected, item) for item in signatures):
+        raise InvalidSignature()
+    return timestamp
+
+
+def verify_signature_standard(
+    raw_body: bytes,
+    event_id: str,
+    timestamp_header: str | None,
+    signature_header: str,
+    secret: str,
+    *,
+    tolerance_seconds: int = 300,
+    now: int | None = None,
+) -> int:
+    """Verify a Standard Webhooks signature (``v1,<base64>``).
+
+    Signed content is ``event_id.timestamp.body``; the key is the decoded
+    secret digest. Either secret serialization is accepted.
+    """
+    if tolerance_seconds < 0:
+        raise ValueError("tolerance_seconds must be non-negative")
+    if not timestamp_header or not timestamp_header.isdigit():
+        raise InvalidSignature()
+    timestamp = int(timestamp_header)
+    current_time = int(time.time()) if now is None else now
+    if abs(current_time - timestamp) > tolerance_seconds:
+        raise SignatureExpired()
+    signatures = _standard_signatures(signature_header)
+    key = _secret_key_bytes(secret)
+    if not signatures or key is None:
+        raise InvalidSignature()
+    signed = f"{event_id}.{timestamp}.".encode("ascii") + raw_body
+    expected = base64.b64encode(
+        hmac.new(key, signed, hashlib.sha256).digest()
+    ).decode()
+    if not any(hmac.compare_digest(expected, item) for item in signatures):
+        raise InvalidSignature()
+    return timestamp
+
+
+def verify_request(
+    raw_body: bytes,
+    headers: Mapping[str, str],
+    secret: str,
+    *,
+    tolerance_seconds: int = 300,
+    now: int | None = None,
+) -> ReceiverEvent:
+    """Verify headers and raw bytes before parsing the JSON envelope.
+
+    Scheme auto-detection (ADR 0002): a header containing a legacy
+    ``t=…,v1=…`` token verifies as legacy; otherwise ``v1,<base64>``
+    tokens verify as Standard Webhooks. Either secret serialization is
+    accepted, so a receiver can upgrade this SDK before its endpoint
+    switches schemes.
+    """
+    normalized = {name.lower(): value for name, value in headers.items()}
+    signature = normalized.get("webhook-signature")
+    event_id = normalized.get("webhook-id")
+    event_type = normalized.get("webhook-event")
+    if not signature or not event_id or not event_type:
+        raise InvalidSignature()
+    timestamp_header = normalized.get("webhook-timestamp")
+    if _header_has_legacy_token(signature):
+        timestamp = verify_signature(
+            raw_body,
+            signature,
+            secret,
+            tolerance_seconds=tolerance_seconds,
+            now=now,
+        )
+        if timestamp_header != str(timestamp):
+            raise InvalidSignature()
+    else:
+        timestamp = verify_signature_standard(
+            raw_body,
+            event_id,
+            timestamp_header,
+            signature,
+            secret,
+            tolerance_seconds=tolerance_seconds,
+            now=now,
+        )
+    try:
+        document = json.loads(raw_body)
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ReceiverVerificationError("Webhook body is not valid JSON") from exc
+    if not isinstance(document, dict):
+        raise ReceiverVerificationError("Webhook body must be a JSON object")
+    if document.get("id") != event_id or document.get("type") != event_type:
+        raise ReceiverVerificationError(
+            "Webhook headers do not match the signed body"
+        )
+    return ReceiverEvent(
+        event_id=event_id,
+        event_type=event_type,
+        timestamp=timestamp,
+        body=document,
+        raw_body=raw_body,
+    )
+
+
+def verify_and_claim(
+    raw_body: bytes,
+    headers: Mapping[str, str],
+    secret: str,
+    deduplicator: DurableDeduplicator,
+    *,
+    tolerance_seconds: int = 300,
+    now: int | None = None,
+) -> ReceiverEvent:
+    """Verify then atomically reserve the signed event ID.
+
+    The deduplicator should reserve the ID in the same durable transaction as
+    receiver acceptance or application state changes. Return a successful 2xx
+    for DuplicateEvent so platform retries stop.
+    """
+    event = verify_request(
+        raw_body,
+        headers,
+        secret,
+        tolerance_seconds=tolerance_seconds,
+        now=now,
+    )
+    if not deduplicator.claim(event.event_id):
+        raise DuplicateEvent(event.event_id)
+    return event