cm-email-webhook-verification 1.0.0__py3-none-any.whl

cm_email_webhook_verification/__init__.py

@@ -0,0 +1,23 @@
+from typing import Any
+
+from cm_email_webhook_verification.exceptions import (
+    InvalidSignatureError,
+    MissingHeaderError,
+    TimestampExpiredError,
+    WebhookVerificationError,
+)
+from cm_email_webhook_verification.validator import WebhookValidator
+
+__version__ = "1.0.0"
+__all__ = [
+    "verify",
+    "WebhookValidator",
+    "WebhookVerificationError",
+    "InvalidSignatureError",
+    "TimestampExpiredError",
+    "MissingHeaderError",
+]
+
+
+def verify(secret_key: str, payload: str, headers: dict[str, str]) -> Any:
+    return WebhookValidator(secret_key).verify(payload, headers)

cm_email_webhook_verification/exceptions.py

@@ -0,0 +1,14 @@
+class WebhookVerificationError(Exception):
+    pass
+
+
+class InvalidSignatureError(WebhookVerificationError):
+    pass
+
+
+class TimestampExpiredError(WebhookVerificationError):
+    pass
+
+
+class MissingHeaderError(WebhookVerificationError):
+    pass

cm_email_webhook_verification/signer.py

@@ -0,0 +1,11 @@
+import base64
+import hashlib
+import hmac
+
+
+def generate_signature(secret: str, payload: str) -> str:
+    key_bytes = secret.encode("utf-8")
+    payload_bytes = payload.encode("utf-8")
+
+    signature = hmac.new(key_bytes, payload_bytes, hashlib.sha512)
+    return base64.b64encode(signature.digest()).decode("utf-8")

cm_email_webhook_verification/validator.py

@@ -0,0 +1,69 @@
+import hmac
+import json
+import time
+from typing import Any
+
+from cm_email_webhook_verification.exceptions import (
+    InvalidSignatureError,
+    MissingHeaderError,
+    TimestampExpiredError,
+)
+from cm_email_webhook_verification.signer import generate_signature
+
+
+class WebhookValidator:
+    HEADER_ID = "svix-id"
+    HEADER_TIMESTAMP = "svix-timestamp"
+    HEADER_SIGNATURE = "svix-signature"
+
+    def __init__(self, secret_key: str, tolerance_in_seconds: int = 300) -> None:
+        if not secret_key or not secret_key.strip():
+            raise ValueError("secret_key cannot be empty")
+
+        self._secret_key = secret_key
+        self._tolerance_ms = tolerance_in_seconds * 1000
+
+    def verify(self, payload: str, headers: dict[str, str]) -> Any:
+        if not payload or not payload.strip():
+            raise ValueError("payload cannot be empty")
+
+        if headers is None:
+            raise ValueError("headers cannot be None")
+
+        message_id = headers.get(self.HEADER_ID)
+        timestamp_str = headers.get(self.HEADER_TIMESTAMP)
+        signature = headers.get(self.HEADER_SIGNATURE)
+
+        if not message_id or not timestamp_str or not signature:
+            missing = []
+            if not message_id:
+                missing.append(self.HEADER_ID)
+            if not timestamp_str:
+                missing.append(self.HEADER_TIMESTAMP)
+            if not signature:
+                missing.append(self.HEADER_SIGNATURE)
+            raise MissingHeaderError(f"Missing required headers: {', '.join(missing)}")
+
+        try:
+            timestamp_ms = int(timestamp_str)
+        except ValueError as e:
+            raise ValueError("Invalid timestamp format") from e
+
+        self._validate_timestamp(timestamp_ms)
+
+        signature_payload = f"{message_id}.{timestamp_ms}.{payload}"
+        expected_signature = generate_signature(self._secret_key, signature_payload)
+
+        if not hmac.compare_digest(signature, expected_signature):
+            raise InvalidSignatureError("Invalid signature")
+
+        return json.loads(payload)
+
+    def _validate_timestamp(self, timestamp_ms: int) -> None:
+        current_time_ms = int(time.time() * 1000)
+        difference = abs(current_time_ms - timestamp_ms)
+
+        if difference > self._tolerance_ms:
+            raise TimestampExpiredError(
+                "Webhook timestamp is outside the allowed tolerance window"
+            )

cm_email_webhook_verification-1.0.0.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: cm-email-webhook-verification
+Version: 1.0.0
+Summary: SDK for verifying CM Email webhook signatures
+Author: email-team
+License: MIT
+Project-URL: Documentation, https://github.com/cmdotcom/email-webhook-verification-sdks#readme
+Project-URL: Repository, https://github.com/cmdotcom/email-webhook-verification-sdks
+Keywords: webhook,verification,hmac,signature,cm,email
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# CM Email Webhook Verification SDK (Python)
+
+SDK for verifying the authenticity of webhooks sent by CM Email services.
+
+## Installation
+
+```bash
+pip install cm-email-webhook-verification
+```
+
+## Usage
+
+```python
+from cm_email_webhook_verification import WebhookValidator, WebhookVerificationError
+
+# Initialize with your webhook secret key
+validator = WebhookValidator("your-secret-key")
+
+# Extract headers and payload from incoming request
+headers = {
+    "svix-id": request.headers["svix-id"],
+    "svix-timestamp": request.headers["svix-timestamp"],
+    "svix-signature": request.headers["svix-signature"],
+}
+payload = request.body.decode("utf-8")
+
+try:
+    data = validator.verify(payload, headers)
+    # Process verified webhook data
+    print(f"Received event: {data}")
+except WebhookVerificationError as e:
+    # Handle verification failure
+    print(f"Webhook verification failed: {e}")
+```
+
+## Flask Example
+
+```python
+from flask import Flask, request, jsonify
+from cm_email_webhook_verification import WebhookValidator, WebhookVerificationError
+
+app = Flask(__name__)
+validator = WebhookValidator("your-secret-key")
+
+@app.route("/webhook", methods=["POST"])
+def webhook():
+    headers = {
+        "svix-id": request.headers.get("svix-id"),
+        "svix-timestamp": request.headers.get("svix-timestamp"),
+        "svix-signature": request.headers.get("svix-signature"),
+    }
+    payload = request.get_data(as_text=True)
+
+    try:
+        data = validator.verify(payload, headers)
+        return jsonify({"status": "ok"}), 200
+    except WebhookVerificationError:
+        return jsonify({"error": "Invalid webhook"}), 401
+```
+
+## FastAPI Example
+
+```python
+from fastapi import FastAPI, Request, HTTPException
+from cm_email_webhook_verification import WebhookValidator, WebhookVerificationError
+
+app = FastAPI()
+validator = WebhookValidator("your-secret-key")
+
+@app.post("/webhook")
+async def webhook(request: Request):
+    headers = {
+        "svix-id": request.headers.get("svix-id"),
+        "svix-timestamp": request.headers.get("svix-timestamp"),
+        "svix-signature": request.headers.get("svix-signature"),
+    }
+    payload = (await request.body()).decode("utf-8")
+
+    try:
+        data = validator.verify(payload, headers)
+        return {"status": "ok"}
+    except WebhookVerificationError:
+        raise HTTPException(status_code=401, detail="Invalid webhook")
+```
+
+## Custom Tolerance
+
+By default, webhooks are valid for 5 minutes. You can customize this:
+
+```python
+# Accept webhooks up to 10 minutes old
+validator = WebhookValidator("your-secret-key", tolerance_in_seconds=600)
+```
+
+## Exceptions
+
+| Exception | Description |
+|-----------|-------------|
+| `WebhookVerificationError` | Base exception for all verification errors |
+| `InvalidSignatureError` | Signature does not match |
+| `TimestampExpiredError` | Timestamp outside tolerance window |
+| `MissingHeaderError` | Required headers missing |
+
+## Security
+
+This SDK uses:
+- **HMAC-SHA512** for signature generation
+- **Constant-time comparison** to prevent timing attacks
+- **Timestamp validation** to prevent replay attacks
+

cm_email_webhook_verification-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+cm_email_webhook_verification/__init__.py,sha256=W0gSf2AufxRoBnXl4sIA7l448IsqEueQa4BGW5DTb44,591
+cm_email_webhook_verification/exceptions.py,sha256=nExmfRR__P9ODzgTbVFA90v7tmmPDFK70ZOwVlGF1MQ,247
+cm_email_webhook_verification/signer.py,sha256=6MhOEk23zkK2bN3cUF_w8vrqhVJbqT_BzcKTHwgCcxU,316
+cm_email_webhook_verification/validator.py,sha256=70uB8xRr0Zwl_Ge-AEYKrckmooZnmv5jXldGIOS-7-I,2405
+cm_email_webhook_verification-1.0.0.dist-info/licenses/LICENSE,sha256=pTszkBQD8rzyUTf4JC1iC3p7yKrc1xDPdCnIONbeuyM,1063
+cm_email_webhook_verification-1.0.0.dist-info/METADATA,sha256=9hVg6_W38Fh1c38sgDpTglR1RIAcXXTMO6u5fXwX_xA,4337
+cm_email_webhook_verification-1.0.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+cm_email_webhook_verification-1.0.0.dist-info/top_level.txt,sha256=BxP-GPplUBGRu3S7Gkf0yNCATNbnGL_uut8eYfXmQWo,30
+cm_email_webhook_verification-1.0.0.dist-info/RECORD,,

cm_email_webhook_verification-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cm_email_webhook_verification-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CM.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cm_email_webhook_verification-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cm_email_webhook_verification