supaapps-platform93-webhooks 0.1.0a2__tar.gz

supaapps_platform93_webhooks-0.1.0a2/.gitignore

@@ -0,0 +1,38 @@
+# Local configuration and secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+
+# Local Compose credentials
+deploy/compose/secrets/
+
+# Editors and operating systems
+.DS_Store
+.idea/
+.vscode/
+
+# Dependencies
+node_modules/
+**/node_modules/
+vendor/
+
+# Build and test output
+dist/
+build/
+coverage/
+tmp/
+**/.next/
+**/out/
+**/test-results/
+**/playwright-report/
+*.log
+*.test
+*.prof
+*.tsbuildinfo
+/platform93
+__pycache__/
+*.py[cod]

supaapps_platform93_webhooks-0.1.0a2/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: supaapps-platform93-webhooks
+Version: 0.1.0a2
+Summary: Platform93 webhook signature verification
+Project-URL: Homepage, https://github.com/supaapps/platform93
+Project-URL: Repository, https://github.com/supaapps/platform93
+Project-URL: Issues, https://github.com/supaapps/platform93/issues
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# supaapps-platform93-webhooks
+
+Verification helpers for timestamped Platform93 webhook signatures over the exact raw
+request body.
+
+```bash
+pip install supaapps-platform93-webhooks
+```
+
+See the [Platform93 repository](https://github.com/supaapps/platform93) for event
+contracts and integration documentation.

supaapps_platform93_webhooks-0.1.0a2/README.md

@@ -0,0 +1,11 @@
+# supaapps-platform93-webhooks
+
+Verification helpers for timestamped Platform93 webhook signatures over the exact raw
+request body.
+
+```bash
+pip install supaapps-platform93-webhooks
+```
+
+See the [Platform93 repository](https://github.com/supaapps/platform93) for event
+contracts and integration documentation.

supaapps_platform93_webhooks-0.1.0a2/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "supaapps-platform93-webhooks"
+version = "0.1.0-alpha.2"
+description = "Platform93 webhook signature verification"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+
+[project.urls]
+Homepage = "https://github.com/supaapps/platform93"
+Repository = "https://github.com/supaapps/platform93"
+Issues = "https://github.com/supaapps/platform93/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/platform93_webhooks"]

supaapps_platform93_webhooks-0.1.0a2/src/platform93_webhooks/__init__.py

@@ -0,0 +1,17 @@
+from .verifier import (
+    PLATFORM_EVENT_VERSIONS,
+    Platform93Event,
+    assert_supported_platform_event,
+    is_custom_event,
+    is_platform_event,
+    verify_webhook,
+)
+
+__all__ = [
+    "PLATFORM_EVENT_VERSIONS",
+    "Platform93Event",
+    "assert_supported_platform_event",
+    "is_custom_event",
+    "is_platform_event",
+    "verify_webhook",
+]

supaapps_platform93_webhooks-0.1.0a2/src/platform93_webhooks/verifier.py

@@ -0,0 +1,87 @@
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Literal, TypedDict
+
+
+class Platform93Event(TypedDict):
+    specversion: Literal["1.0"]
+    id: str
+    source: str
+    type: str
+    contract_source: Literal["platform93", "application"]
+    time: str
+    application_id: str
+    schema_version: str
+    subject: str | None
+    actor: dict[str, Any] | None
+    correlation_id: str | None
+    causation_id: str | None
+    data: dict[str, Any]
+
+
+PLATFORM_EVENT_VERSIONS = dict.fromkeys((
+    "organization.created", "organization.retired", "organization.restored",
+    "application.created", "application.retired", "application.restored",
+    "delegation.created", "delegation.exchanged", "delegation.revoked",
+    "entitlement.granted", "local_entitlement_request.created", "local_entitlement_request.approved",
+    "oauth.consent_revoked", "platform93.webhook.test", "user.created",
+    "storage.object.upload_requested", "storage.object.ready", "storage.object.deleted",
+    "storage.provider.verified", "storage.provider.disabled",
+    "user.email_verified", "user.email_unverified", "user.organization_verified",
+    "user.organization_unverified", "user.email_changed", "user.password_reset",
+    "user.pending_deletion", "user.anonymized", "user.deleted", "user.suspended", "user.restored",
+    "workspace.invitation_created", "workspace.invitation_accepted", "workspace.owner_transferred",
+), "1.0")
+
+
+def verify_webhook(
+    raw_body: bytes,
+    header: str,
+    secret: str,
+    tolerance_seconds: int = 300,
+    now: float | None = None,
+) -> Platform93Event:
+    values: dict[str, list[str]] = {}
+    for part in header.split(","):
+        if "=" in part:
+            key, value = part.split("=", 1)
+            values.setdefault(key, []).append(value)
+    timestamp = int(values.get("t", ["0"])[0])
+    current = time.time() if now is None else now
+    if not timestamp or abs(current - timestamp) > tolerance_seconds:
+        raise ValueError("Platform93 webhook timestamp rejected")
+    expected = hmac.new(
+        secret.encode(), str(timestamp).encode() + b"." + raw_body, hashlib.sha256
+    ).hexdigest()
+    if not any(
+        hmac.compare_digest(expected, signature) for signature in values.get("v1", [])
+    ):
+        raise ValueError("Platform93 webhook signature rejected")
+    event = json.loads(raw_body)
+    if (
+        event.get("specversion") != "1.0"
+        or not isinstance(event.get("type"), str)
+        or event.get("contract_source") not in ("platform93", "application")
+        or not isinstance(event.get("schema_version"), str)
+        or not isinstance(event.get("data"), dict)
+    ):
+        raise ValueError("Platform93 webhook envelope rejected")
+    return event
+
+
+def is_platform_event(event: Platform93Event) -> bool:
+    return event["contract_source"] == "platform93" and event["type"] in PLATFORM_EVENT_VERSIONS
+
+
+def is_custom_event(event: Platform93Event) -> bool:
+    return event["contract_source"] == "application"
+
+
+def assert_supported_platform_event(event: Platform93Event) -> None:
+    if not is_platform_event(event):
+        raise ValueError("Unknown Platform93 event contract")
+    supported = PLATFORM_EVENT_VERSIONS[event["type"]]
+    if event["schema_version"].split(".", 1)[0] != supported.split(".", 1)[0]:
+        raise ValueError("Unsupported Platform93 event schema version")

supaapps_platform93_webhooks-0.1.0a2/tests/conformance.py

@@ -0,0 +1,18 @@
+import json
+from pathlib import Path
+
+from platform93_webhooks import assert_supported_platform_event, is_platform_event, verify_webhook
+
+
+fixture = json.loads(
+    (Path(__file__).parents[4] / "conformance" / "webhook.json").read_text()
+)
+event = verify_webhook(
+    fixture["raw_body"].encode(),
+    fixture["signature"],
+    fixture["secret"],
+    now=fixture["timestamp"],
+)
+assert event["id"] == "01900000-0000-7000-8000-000000000001"
+assert is_platform_event(event)
+assert_supported_platform_event(event)