"""CSWH1 reference receiver. Run behind HTTPS; persist verified events before ACK. Requires the cloudsign/ directory from the Python SDK source archive. Configuration and integration steps: /index/api_docs?guide=webhook-receiver """ from dataclasses import dataclass, field from contextlib import contextmanager import hashlib from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer import json import os from pathlib import Path import re import sqlite3 import time from cloudsign.webhook import acknowledge_webhook, verify_webhook EVENTS = frozenset(( "signing.succeeded", "signing.failed", "signing.cancelled", "signing.superseded", "upload.completed", "upload.failed", "upload.cancelled", "version.ready", "distribution.published", "order.paid", "refund.completed", "capacity.purchased", )) SOURCE_EVENTS = {"api": EVENTS, "website": frozenset(("distribution.published",)), "website_upload": frozenset(("version.ready", "distribution.published"))} SIGNED_HEADERS = ("X-Cloudsign-Webhook-Id", "X-Cloudsign-Event-Id", "X-Cloudsign-Timestamp", "X-Cloudsign-Signature") class Rejected(Exception): def __init__(self, status, code): super().__init__(code) self.status, self.code = status, code @dataclass(frozen=True) class Config: webhook_id: str secret: str = field(repr=False) app_id: str source: str events: frozenset database: Path def __post_init__(self): if (not re.fullmatch(r"WHK[a-f0-9]{40}", self.webhook_id) or not re.fullmatch(r"CSW_[A-Za-z0-9_-]{43}", self.secret) or not re.fullmatch(r"A[a-f0-9]{32}", self.app_id) or self.source not in SOURCE_EVENTS or not self.events or not self.events <= SOURCE_EVENTS[self.source] or not self.database.is_absolute()): raise ValueError("Invalid receiver configuration") @contextmanager def connect(database): db = sqlite3.connect(database, timeout=2) try: with db: yield db finally: db.close() def prepare_database(database): """Use a dedicated private directory, outside any public web root.""" parent = database.parent if database.is_symlink() or parent.is_symlink(): raise ValueError("Database paths must not be symbolic links") parent.mkdir(mode=0o700, exist_ok=True) if os.name == "posix": for path in (parent, database): if not path.exists(): continue info = path.stat() if info.st_uid != os.getuid() or info.st_mode & 0o077: raise ValueError("Database directory and files must be private") with connect(database) as db: db.execute("PRAGMA journal_mode=WAL") db.execute("""CREATE TABLE IF NOT EXISTS webhook_inbox ( webhook_id TEXT NOT NULL, event_id TEXT NOT NULL, app_id TEXT NOT NULL, source TEXT NOT NULL, event_type TEXT NOT NULL, payload_sha256 TEXT NOT NULL, payload TEXT NOT NULL, received_at INTEGER NOT NULL, PRIMARY KEY (webhook_id, event_id) )""") if os.name == "posix": os.chmod(database, 0o600) def receive(config, headers, body, *, now=None): """headers is a sequence of pairs, preserving duplicate HTTP headers.""" pairs = [(key.lower(), value) for key, value in headers] values = {} for name in SIGNED_HEADERS: found = [value for key, value in pairs if key == name.lower()] if len(found) != 1: raise Rejected(400, "InvalidHeaders") values[name] = found[0] if values[SIGNED_HEADERS[0]] != config.webhook_id: raise Rejected(403, "SubscriptionMismatch") try: event = verify_webhook(config.secret, config.webhook_id, values[SIGNED_HEADERS[1]], values[SIGNED_HEADERS[2]], body, values[SIGNED_HEADERS[3]], now=now) except (ValueError, TypeError, RecursionError): raise Rejected(400, "InvalidNotification") from None if event["type"] == "endpoint.challenge": return acknowledge_webhook(config.secret, event) if event["data"]["app_id"] != config.app_id or event["type"] not in config.events: raise Rejected(403, "EventNotAllowed") # Canonicalize only AFTER authenticating the exact bytes that arrived. payload = json.dumps(event, sort_keys=True, separators=(",", ":"), ensure_ascii=False) digest = hashlib.sha256(payload.encode("utf8")).hexdigest() try: with connect(config.database) as db: db.execute("BEGIN IMMEDIATE") prior = db.execute("""SELECT payload_sha256, app_id, source FROM webhook_inbox WHERE webhook_id=? AND event_id=?""", (config.webhook_id, event["id"])).fetchone() if prior and prior != (digest, config.app_id, config.source): raise Rejected(409, "EventConflict") if not prior: db.execute("INSERT INTO webhook_inbox VALUES (?, ?, ?, ?, ?, ?, ?, ?)", (config.webhook_id, event["id"], config.app_id, config.source, event["type"], digest, payload, int(time.time()))) # The context manager commits (or rolls back) before generating the ACK. except sqlite3.Error: raise Rejected(503, "InboxUnavailable") from None return acknowledge_webhook(config.secret, event) def make_handler(config): class Handler(BaseHTTPRequestHandler): protocol_version = "HTTP/1.1" def setup(self): super().setup() self.connection.settimeout(5) def log_message(self, *_): pass # Do not log signatures, credentials, payloads or incoming paths. def reply(self, status, value): body = json.dumps(value, separators=(",", ":")).encode("utf8") self.send_response(status) self.send_header("Content-Type", "application/json; charset=utf-8") self.send_header("Content-Length", str(len(body))) self.send_header("Cache-Control", "no-store") self.send_header("Connection", "close") self.end_headers() self.close_connection = True self.wfile.write(body) def do_POST(self): try: if self.path != "/cloudsign/events": raise Rejected(404, "NotFound") lengths = self.headers.get_all("Content-Length", []) types = self.headers.get_all("Content-Type", []) if (self.headers.get_all("Transfer-Encoding") or self.headers.get_all("Content-Encoding") or len(lengths) != 1 or not re.fullmatch(r"[0-9]{1,5}", lengths[0]) or len(types) != 1 or not re.fullmatch( r"application/json(?:\s*;\s*charset=utf-8)?", types[0], re.IGNORECASE)): raise Rejected(400, "InvalidRequest") length = int(lengths[0]) if not 1 <= length <= 8192: raise Rejected(413, "RequestTooLarge") body = self.rfile.read(length) if len(body) != length: raise Rejected(400, "IncompleteBody") ack = receive(config, list(self.headers.items()), body) except Rejected as error: self.reply(error.status, {"error": error.code}) except (TimeoutError, OSError): self.reply(503, {"error": "ReceiverUnavailable"}) else: self.reply(202, ack) def do_GET(self): self.reply(405, {"error": "MethodNotAllowed"}) return Handler def main(): try: config = Config( os.environ["CLOUDSIGN_WEBHOOK_ID"], os.environ["CLOUDSIGN_WEBHOOK_SECRET"], os.environ["CLOUDSIGN_WEBHOOK_APP_ID"], os.environ["CLOUDSIGN_WEBHOOK_SOURCE"], frozenset(os.environ["CLOUDSIGN_WEBHOOK_EVENTS"].split(",")), Path(os.environ["CLOUDSIGN_WEBHOOK_DB"]), ) port = int(os.environ.get("CLOUDSIGN_WEBHOOK_PORT", "8900")) if not 1 <= port <= 65535: raise ValueError("Invalid port") os.umask(0o077) prepare_database(config.database) server = ThreadingHTTPServer(("127.0.0.1", port), make_handler(config)) except (KeyError, ValueError, OSError, sqlite3.Error): raise SystemExit("Receiver configuration or private database is unavailable") from None print(f"Listening on http://127.0.0.1:{port}/cloudsign/events", flush=True) try: server.serve_forever() except KeyboardInterrupt: pass finally: server.server_close() if __name__ == "__main__": main()