commitguardian 0.1.0__py3-none-any.whl

commitguard/notifications/__init__.py

@@ -0,0 +1,2 @@
+"""Notifications: typed events emitted with domain changes, delivered in-app, by e-mail
+and to signed webhooks. See :mod:`commitguard.notifications.service`."""

commitguard/notifications/channels/__init__.py

@@ -0,0 +1 @@
+"""Notification channels: in-app (database), e-mail (SMTP) and signed webhooks."""

commitguard/notifications/channels/base.py

@@ -0,0 +1,22 @@
+"""What every external delivery channel returns and raises."""
+
+from dataclasses import dataclass
+
+
+class DeliveryError(Exception):
+    """A delivery attempt failed.
+
+    ``code`` is a short, non-sensitive label stored with the delivery record
+    (never a provider response body). ``permanent`` failures are not retried.
+    """
+
+    def __init__(self, code: str, *, permanent: bool = False) -> None:
+        super().__init__(code)
+        self.code = code[:64]
+        self.permanent = permanent
+
+
+@dataclass(frozen=True, slots=True)
+class DeliveryReceipt:
+    provider: str
+    provider_message_id: str | None

commitguard/notifications/channels/email.py

@@ -0,0 +1,110 @@
+"""E-mail channel.
+
+:class:`EmailProvider` is the interface the notification domain depends on;
+:class:`SmtpEmailProvider` is the implementation shipped in this phase (any
+SMTP relay, including those of SES, SendGrid or Resend). Provider credentials
+come from the environment or a secret file (:mod:`commitguard.notifications.settings`),
+never from repository or organization configuration.
+
+Messages are **plain text** only: repository names, rule titles and other
+repository-controlled values are never interpreted as HTML. Header values are
+set through :class:`email.message.EmailMessage`, which rejects line breaks, so
+untrusted text cannot inject headers. ``Message-ID`` is derived from the
+delivery's idempotency key, so a retried message can be recognised as the same
+message by the relay and by recipients' mail systems.
+"""
+
+import smtplib
+import ssl
+from dataclasses import dataclass
+from email.message import EmailMessage
+from email.utils import formatdate
+from typing import Literal, Protocol
+
+from commitguard.notifications.channels.base import DeliveryError, DeliveryReceipt
+from commitguard.security.secrets import Secret
+
+SMTP_TIMEOUT_SECONDS = 15.0
+
+type SmtpSecurity = Literal["starttls", "tls", "none"]
+
+
+@dataclass(frozen=True, slots=True)
+class OutgoingEmail:
+    to: str
+    subject: str
+    text: str
+
+
+def build_message(sender: str, email: OutgoingEmail, idempotency_key: str) -> EmailMessage:
+    message = EmailMessage()
+    message["From"] = sender
+    message["To"] = email.to
+    message["Subject"] = " ".join(email.subject.split())[:200]
+    message["Date"] = formatdate(usegmt=True)
+    domain = sender.rsplit("@", 1)[-1] if "@" in sender else "commitguard.invalid"
+    message["Message-ID"] = f"<{idempotency_key[:64]}@{domain}>"
+    message["Auto-Submitted"] = "auto-generated"
+    message.set_content(email.text, subtype="plain", charset="utf-8")
+    return message
+
+
+class EmailProvider(Protocol):
+    name: str
+
+    def send(self, email: OutgoingEmail, *, idempotency_key: str) -> DeliveryReceipt: ...
+
+
+class SmtpEmailProvider:
+    name = "smtp"
+
+    def __init__(
+        self,
+        *,
+        host: str,
+        port: int,
+        sender: str,
+        security: SmtpSecurity = "starttls",
+        username: str | None = None,
+        password: Secret | None = None,
+        timeout: float = SMTP_TIMEOUT_SECONDS,
+    ) -> None:
+        self._host = host
+        self._port = port
+        self._sender = sender
+        self._security = security
+        self._username = username
+        self._password = password
+        self._timeout = timeout
+
+    def send(self, email: OutgoingEmail, *, idempotency_key: str) -> DeliveryReceipt:
+        message = build_message(self._sender, email, idempotency_key)
+        context = ssl.create_default_context()
+        try:
+            client: smtplib.SMTP
+            if self._security == "tls":
+                client = smtplib.SMTP_SSL(
+                    self._host, self._port, timeout=self._timeout, context=context
+                )
+            else:
+                client = smtplib.SMTP(self._host, self._port, timeout=self._timeout)
+            with client:
+                if self._security == "starttls":
+                    client.starttls(context=context)
+                if self._username and self._password:
+                    client.login(self._username, self._password.reveal())
+                refused = client.send_message(message)
+        except smtplib.SMTPRecipientsRefused:
+            raise DeliveryError("recipient_refused", permanent=True) from None
+        except smtplib.SMTPAuthenticationError:
+            raise DeliveryError("smtp_authentication_failed") from None
+        except smtplib.SMTPResponseException as exc:
+            permanent = 500 <= exc.smtp_code < 600
+            raise DeliveryError(f"smtp_{exc.smtp_code}", permanent=permanent) from None
+        except TimeoutError:
+            raise DeliveryError("smtp_timeout") from None
+        except (smtplib.SMTPException, ssl.SSLError, OSError) as exc:
+            raise DeliveryError(f"smtp_unavailable_{type(exc).__name__}"[:64]) from None
+        if refused:
+            raise DeliveryError("recipient_refused", permanent=True)
+        return DeliveryReceipt(self.name, str(message["Message-ID"]))

commitguard/notifications/channels/in_app.py

@@ -0,0 +1,74 @@
+"""In-app channel: who receives a notification in their CommitGuard inbox.
+
+Recipients are computed when the event is dispatched, from the organization's
+current members:
+
+* the member's role must grant the type's permission (for example
+  ``github:manage`` for installation disconnects), and the owner of a personal
+  (user-account) installation is always included;
+* the type must be enabled for the member (mandatory types always are).
+
+Repository visibility on GitHub is per session (reported by GitHub at
+sign-in), so it is applied when notifications are *read*: a notification about
+a repository is only listed for a session that can see that repository, and the
+role check is applied again at read time. A member who lost their role or
+their GitHub access stops seeing notifications immediately.
+"""
+
+import sqlite3
+
+from commitguard.controlplane.access import Role
+from commitguard.notifications.models import NotificationType, TypeDefinition
+from commitguard.notifications.preferences import (
+    OrganizationSettings,
+    UserPreferences,
+    in_app_enabled,
+)
+
+
+def eligible_members(
+    db: sqlite3.Connection,
+    account_id: int,
+    definition: TypeDefinition,
+) -> set[int]:
+    users = {
+        int(row["user_id"])
+        for row in db.execute(
+            "SELECT user_id, role FROM memberships WHERE account_id = ?", (int(account_id),)
+        ).fetchall()
+        if row["role"] in {r.value for r in Role}
+        and definition.permission in Role(row["role"]).permissions
+    }
+    personal = db.execute(
+        "SELECT 1 FROM installations WHERE account_id = ? AND account_type = 'User' LIMIT 1",
+        (int(account_id),),
+    ).fetchone()
+    if personal is not None:
+        users.add(int(account_id))  # a user account's GitHub user ID is its account ID
+    return users
+
+
+def recipients(
+    db: sqlite3.Connection,
+    account_id: int,
+    definition: TypeDefinition,
+    organization: OrganizationSettings,
+) -> list[int]:
+    muted = {
+        int(row["user_id"])
+        for row in db.execute(
+            "SELECT user_id FROM notification_user_preferences WHERE account_id = ? "
+            "AND type = ? AND in_app = 0",
+            (int(account_id), definition.type.value),
+        ).fetchall()
+    }
+    result = []
+    for user_id in sorted(eligible_members(db, account_id, definition)):
+        preferences = UserPreferences(
+            user_id,
+            account_id,
+            frozenset({definition.type}) if user_id in muted else frozenset[NotificationType](),
+        )
+        if in_app_enabled(definition, organization, preferences):
+            result.append(user_id)
+    return result

commitguard/notifications/channels/sink.py

@@ -0,0 +1,58 @@
+"""Test mode: channels that record deliveries instead of sending them.
+
+With ``COMMITGUARD_NOTIFICATIONS_MODE=test`` (and always when
+``COMMITGUARD_ENV=test``) e-mail and webhook deliveries go through the full
+pipeline - outbox, preferences, delivery records, retries, audit - but the
+final hop is replaced by these in-memory sinks, so a test or staging
+environment can never reach a real mailbox or endpoint.
+"""
+
+import json
+import threading
+from dataclasses import dataclass
+
+from commitguard.notifications.channels.base import DeliveryError, DeliveryReceipt
+from commitguard.notifications.channels.email import OutgoingEmail
+from commitguard.notifications.channels.webhook import WebhookRequest
+
+MAX_RECORDED = 1000
+
+
+@dataclass(frozen=True, slots=True)
+class RecordedEmail:
+    email: OutgoingEmail
+    idempotency_key: str
+
+
+class RecordingEmailProvider:
+    name = "test-sink"
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self.sent: list[RecordedEmail] = []
+        self.failure: DeliveryError | None = None  # tests simulate an outage
+
+    def send(self, email: OutgoingEmail, *, idempotency_key: str) -> DeliveryReceipt:
+        with self._lock:
+            if self.failure is not None:
+                raise self.failure
+            self.sent.append(RecordedEmail(email, idempotency_key))
+            del self.sent[:-MAX_RECORDED]
+        return DeliveryReceipt(self.name, f"test-{idempotency_key[:24]}")
+
+
+class RecordingWebhookTransport:
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self.requests: list[WebhookRequest] = []
+        self.status = 200
+
+    def post(self, request: WebhookRequest, *, timeout: float) -> int:
+        with self._lock:
+            self.requests.append(request)
+            del self.requests[:-MAX_RECORDED]
+            return self.status
+
+    def payloads(self) -> list[dict[str, object]]:
+        with self._lock:
+            return [json.loads(r.body) for r in self.requests]

commitguard/notifications/channels/webhook.py

@@ -0,0 +1,233 @@
+"""Signed outbound webhooks.
+
+Request::
+
+    POST <endpoint URL>                       (HTTPS; redirects are not followed)
+    Content-Type: application/json
+    User-Agent: CommitGuard-Notifications
+    X-CommitGuard-Event: policy_rolled_back
+    X-CommitGuard-Delivery: <idempotency key>  (same value on every retry)
+    X-CommitGuard-Timestamp: 1767225600        (Unix seconds)
+    X-CommitGuard-Signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>
+
+Receivers verify the signature over the timestamp *and* the raw body with
+:func:`verify_signature` (or the equivalent in their language), reject
+timestamps outside a small window (default five minutes) to stop replays, and
+use ``X-CommitGuard-Delivery`` to discard a retried delivery they already
+processed.
+
+Signing secrets: each endpoint has its own secret, derived from the
+deployment's signing key (``COMMITGUARD_NOTIFICATION_SIGNING_KEY``) and the
+endpoint ID with HMAC. Nothing secret is stored in the database; the secret is
+shown once, when an administrator adds the endpoint. A tenant's secret reveals
+nothing about another tenant's.
+
+Network safety: the endpoint host is resolved at send time and the connection
+is made to the resolved address itself (TLS still verifies the certificate for
+the host name), so a DNS change between the address check and the connection
+cannot redirect the request. Loopback, private, link-local and other
+non-public addresses are refused in production.
+"""
+
+import hashlib
+import hmac
+import http.client
+import ipaddress
+import socket
+import ssl
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Protocol
+from urllib.parse import urlsplit
+
+from commitguard.notifications.channels.base import DeliveryError, DeliveryReceipt
+from commitguard.security.secrets import Secret
+
+WEBHOOK_TIMEOUT_SECONDS = 10.0
+SIGNATURE_TOLERANCE_SECONDS = 300
+MAX_URL_CHARS = 2048
+SIGNATURE_VERSION = "v1"
+SECRET_PREFIX = "whsec_"  # noqa: S105 - display prefix, not a secret
+
+
+def endpoint_secret(signing_key: Secret, endpoint_id: str) -> Secret:
+    digest = hmac.new(
+        signing_key.reveal().encode("utf-8"),
+        b"commitguard-webhook-endpoint\x1f" + endpoint_id.encode("ascii"),
+        hashlib.sha256,
+    ).hexdigest()
+    return Secret(SECRET_PREFIX + digest)
+
+
+def sign(secret: Secret, timestamp: int, body: bytes) -> str:
+    mac = hmac.new(secret.reveal().encode("utf-8"), f"{timestamp}.".encode() + body, hashlib.sha256)
+    return f"{SIGNATURE_VERSION}={mac.hexdigest()}"
+
+
+def verify_signature(
+    secret: Secret,
+    *,
+    timestamp: str | None,
+    signature: str | None,
+    body: bytes,
+    now: float,
+    tolerance: int = SIGNATURE_TOLERANCE_SECONDS,
+) -> bool:
+    """Receiver-side check: authentic body, fresh timestamp (replay window)."""
+    if not timestamp or not signature or not timestamp.isascii() or not timestamp.isdigit():
+        return False
+    sent = int(timestamp)
+    if abs(now - sent) > tolerance:
+        return False
+    expected = sign(secret, sent, body)
+    return hmac.compare_digest(expected.encode("ascii"), signature.strip().encode("ascii"))
+
+
+class WebhookUrlError(ValueError):
+    pass
+
+
+def validate_webhook_url(url: object, *, allow_insecure_local: bool) -> str:
+    """An endpoint URL administrators may register."""
+    if not isinstance(url, str) or not url or len(url) > MAX_URL_CHARS:
+        raise WebhookUrlError("the webhook URL must be an https:// URL")
+    if any(ord(c) < 0x21 or ord(c) == 0x7F for c in url):
+        raise WebhookUrlError("the webhook URL contains invalid characters")
+    parts = urlsplit(url)
+    host = parts.hostname
+    local = host in ("localhost", "127.0.0.1", "::1")
+    if parts.scheme != "https" and not (parts.scheme == "http" and local and allow_insecure_local):
+        raise WebhookUrlError("the webhook URL must use https")
+    if not host or parts.username or parts.password or parts.fragment:
+        raise WebhookUrlError("the webhook URL must not contain credentials or a fragment")
+    try:
+        _ = parts.port
+    except ValueError:
+        raise WebhookUrlError("the webhook URL has an invalid port") from None
+    if not allow_insecure_local:
+        try:
+            address = ipaddress.ip_address(host)
+        except ValueError:
+            address = None
+        if local or (address is not None and not address.is_global):
+            raise WebhookUrlError("the webhook URL must point to a public host")
+    return url
+
+
+@dataclass(frozen=True, slots=True)
+class WebhookRequest:
+    url: str
+    body: bytes
+    headers: Mapping[str, str]
+
+
+class WebhookTransport(Protocol):
+    def post(self, request: WebhookRequest, *, timeout: float) -> int:
+        """Send the request and return the HTTP status (redirects are not followed)."""
+        ...
+
+
+type Resolver = Callable[[str, int], list[str]]
+
+
+def _resolve(host: str, port: int) -> list[str]:
+    return sorted(
+        {str(info[4][0]) for info in socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)}
+    )
+
+
+class PinnedHttpsTransport:
+    """HTTPS POST to the address that passed the network check (no DNS rebinding)."""
+
+    def __init__(self, *, allow_private: bool = False, resolver: Resolver = _resolve) -> None:
+        self._allow_private = allow_private
+        self._resolver = resolver
+
+    def post(self, request: WebhookRequest, *, timeout: float) -> int:
+        parts = urlsplit(request.url)
+        host = parts.hostname or ""
+        secure = parts.scheme == "https"
+        port = parts.port or (443 if secure else 80)
+        try:
+            addresses = self._resolver(host, port)
+        except OSError:
+            raise DeliveryError("webhook_dns_failed") from None
+        allowed = [a for a in addresses if self._allow_private or ipaddress.ip_address(a).is_global]
+        if not allowed:
+            raise DeliveryError("webhook_address_refused", permanent=True)
+        address = allowed[0]
+        path = (parts.path or "/") + (f"?{parts.query}" if parts.query else "")
+        connection: http.client.HTTPConnection
+        if secure:
+            connection = _PinnedHTTPSConnection(host, port, address, timeout)
+        else:
+            connection = http.client.HTTPConnection(address, port, timeout=timeout)
+        try:
+            connection.request("POST", path, body=request.body, headers=dict(request.headers))
+            response = connection.getresponse()
+            response.read(65536)
+            return int(response.status)
+        except TimeoutError:
+            raise DeliveryError("webhook_timeout") from None
+        except (ssl.SSLError, http.client.HTTPException, OSError) as exc:
+            raise DeliveryError(f"webhook_unreachable_{type(exc).__name__}"[:64]) from None
+        finally:
+            connection.close()
+
+
+class _PinnedHTTPSConnection(http.client.HTTPSConnection):
+    def __init__(self, host: str, port: int, address: str, timeout: float) -> None:
+        super().__init__(host, port, timeout=timeout, context=ssl.create_default_context())
+        self._address = address
+
+    def connect(self) -> None:
+        sock = socket.create_connection((self._address, self.port), self.timeout)
+        context = ssl.create_default_context()
+        self.sock = context.wrap_socket(sock, server_hostname=self.host)
+
+
+class WebhookProvider:
+    name = "webhook"
+
+    def __init__(
+        self,
+        signing_key: Secret,
+        transport: WebhookTransport,
+        *,
+        timeout: float = WEBHOOK_TIMEOUT_SECONDS,
+    ) -> None:
+        self._signing_key = signing_key
+        self._transport = transport
+        self._timeout = timeout
+
+    def secret_for(self, endpoint_id: str) -> Secret:
+        return endpoint_secret(self._signing_key, endpoint_id)
+
+    def send(
+        self,
+        *,
+        url: str,
+        endpoint_id: str,
+        event_type: str,
+        body: bytes,
+        idempotency_key: str,
+        timestamp: int,
+    ) -> DeliveryReceipt:
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": "CommitGuard-Notifications",
+            "X-CommitGuard-Event": event_type,
+            "X-CommitGuard-Delivery": idempotency_key,
+            "X-CommitGuard-Timestamp": str(timestamp),
+            "X-CommitGuard-Signature": sign(self.secret_for(endpoint_id), timestamp, body),
+        }
+        status = self._transport.post(
+            WebhookRequest(url=url, body=body, headers=headers), timeout=self._timeout
+        )
+        if 200 <= status < 300:
+            return DeliveryReceipt(self.name, idempotency_key)
+        if 300 <= status < 400:
+            raise DeliveryError("webhook_redirect_refused", permanent=True)
+        if status in (408, 425, 429) or status >= 500:
+            raise DeliveryError(f"webhook_http_{status}")
+        raise DeliveryError(f"webhook_http_{status}", permanent=True)

commitguard/notifications/deduplication.py

@@ -0,0 +1,57 @@
+"""Notification deduplication.
+
+Two mechanisms keep one underlying event from producing many notifications:
+
+1. **Idempotent emission.** Every notification event has a *storage key*: its
+   domain identity (``dedup_key``) plus, for types with a coalescing window, the
+   window it falls in. The outbox has a unique constraint on
+   ``(account_id, storage key)``. Emitting the same key again - a replayed
+   webhook, a retried job, twenty commits of one pull request detected in one
+   scan - updates the existing event (``occurrences`` + 1, newest text) instead
+   of inserting another one, and it creates no new e-mail or webhook deliveries.
+2. **Idempotent delivery.** Each delivery has an idempotency key derived from
+   the event, the channel and the destination, also unique in the database, and
+   sent to the provider (``Message-ID`` for e-mail, ``X-CommitGuard-Delivery``
+   for webhooks) so a retry after an ambiguous failure can be recognised.
+
+Domain keys, per type:
+
+=============================  ==================================================
+``critical_violation``,        installation, repository, pull request / branch /
+``high_violation``             merge group, rule - one notification per rule per
+                               change within an hour, however many commits
+``policy_changed``,            organization and the new version number
+``policy_rolled_back``
+``installation_disconnected``  installation (within an hour: flapping
+``installation_reconnected``   suspend/unsuspend does not repeat the alert)
+``merge_queue_failure``        repository and merge group commit
+``check_rerun_failed``         the failed execution
+=============================  ==================================================
+"""
+
+from collections.abc import Iterable
+from datetime import datetime
+
+from commitguard.notifications.models import DEFINITIONS, NotificationType
+from commitguard.security.hashing import fingerprint
+
+
+def domain_key(notification_type: NotificationType, *parts: str | int) -> str:
+    return ":".join([notification_type.value, *(str(p) for p in parts)])
+
+
+def storage_key(notification_type: NotificationType, dedup_key: str, occurred_at: datetime) -> str:
+    """The outbox uniqueness key: the domain key, bucketed by the coalescing window."""
+    window = DEFINITIONS[notification_type].coalesce_seconds
+    if not window:
+        return dedup_key
+    bucket = int(occurred_at.timestamp() // window)
+    return f"{dedup_key}@{bucket}"
+
+
+def delivery_idempotency_key(event_id: str, channel: str, destination: str) -> str:
+    return fingerprint(["notification-delivery", event_id, channel, destination])
+
+
+def unique_sorted(values: Iterable[str]) -> list[str]:
+    return sorted(set(values))