commitguardian 0.1.0__py3-none-any.whl

commitguard/notifications/service.py

@@ -0,0 +1,128 @@
+"""NotificationService: the notification subsystem, wired from settings.
+
+::
+
+    domain services ── emit() ──> outbox ──> NotificationDispatcher ──> inbox rows
+                                                        └──────────> delivery records
+                                                                          │
+                                                   DeliveryWorker (retries) ▼
+                                                        e-mail (SMTP) / signed webhook
+
+The GitHub App service runs :meth:`run_once` on a background thread every few
+seconds; tests call it directly. Nothing here is on the webhook request path
+or the scan path: a slow or unavailable provider delays only notifications.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from commitguard.github.storage import SqliteStateStore
+from commitguard.notifications.channels.email import EmailProvider, SmtpEmailProvider
+from commitguard.notifications.channels.sink import (
+    RecordingEmailProvider,
+    RecordingWebhookTransport,
+)
+from commitguard.notifications.channels.webhook import (
+    PinnedHttpsTransport,
+    WebhookProvider,
+    WebhookTransport,
+)
+from commitguard.notifications.dispatcher import NotificationDispatcher
+from commitguard.notifications.retry import DeliveryWorker
+from commitguard.notifications.settings import NotificationMode, NotificationSettings
+from commitguard.observability.logging import get_logger
+from commitguard.observability.metrics import Metrics
+from commitguard.services.audit import AuditService
+
+log = get_logger(__name__)
+
+RUN_INTERVAL_SECONDS = 5.0
+
+
+@dataclass(frozen=True, slots=True)
+class RunResult:
+    dispatched: int
+    attempted: int
+
+
+class NotificationService:
+    def __init__(
+        self,
+        store: SqliteStateStore,
+        audit: AuditService,
+        metrics: Metrics,
+        settings: NotificationSettings,
+        *,
+        email: EmailProvider | None = None,
+        webhook_transport: WebhookTransport | None = None,
+        now: Callable[[], datetime] = lambda: datetime.now(UTC),
+    ) -> None:
+        self.settings = settings
+        self._store = store
+        self._now = now
+        if settings.mode is NotificationMode.TEST:
+            email = email or RecordingEmailProvider()
+            webhook_transport = webhook_transport or RecordingWebhookTransport()
+        elif settings.mode is NotificationMode.DELIVER:
+            if email is None and settings.smtp is not None:
+                email = SmtpEmailProvider(
+                    host=settings.smtp.host,
+                    port=settings.smtp.port,
+                    sender=settings.smtp.sender,
+                    security=settings.smtp.security,  # type: ignore[arg-type]
+                    username=settings.smtp.username,
+                    password=settings.smtp.password,
+                )
+            if webhook_transport is None and settings.signing_key is not None:
+                webhook_transport = PinnedHttpsTransport(allow_private=not settings.production)
+        else:
+            email, webhook_transport = None, None
+        self.email = email if settings.email_available else None
+        self.webhook_transport = webhook_transport
+        self.webhook = (
+            WebhookProvider(settings.signing_key, webhook_transport)
+            if settings.webhook_available
+            and settings.signing_key is not None
+            and webhook_transport is not None
+            else None
+        )
+        self.dispatcher = NotificationDispatcher(store, audit, metrics, settings, now=now)
+        self.worker = DeliveryWorker(
+            store,
+            audit,
+            metrics,
+            email=self.email,
+            webhook=self.webhook,
+            dashboard_origin=settings.dashboard_origin,
+            now=now,
+        )
+
+    def run_once(self) -> RunResult:
+        """Fan out pending events, then attempt due deliveries."""
+        dispatched = self.dispatcher.dispatch_pending()
+        attempted = self.worker.deliver_due()
+        return RunResult(dispatched, attempted)
+
+    def purge_expired(self) -> int:
+        """Delete notification history older than the notification retention period.
+
+        Events with a delivery still pending are kept; deleting an event removes
+        its inbox entries and delivery records (foreign keys cascade). Audit
+        events about notifications follow the audit retention instead.
+        """
+        cutoff = (self._now() - self.settings.retention).timestamp()
+        with self._store.transaction() as db:
+            removed = db.execute(
+                "DELETE FROM notification_events WHERE last_occurred_at < ? AND dispatched_at "
+                "IS NOT NULL AND NOT EXISTS (SELECT 1 FROM notification_deliveries d WHERE "
+                "d.event_id = notification_events.event_id AND d.status = 'pending')",
+                (cutoff,),
+            ).rowcount
+            db.execute(
+                "DELETE FROM notification_webhooks WHERE removed_at IS NOT NULL AND removed_at < ?",
+                (cutoff,),
+            )
+        if removed:
+            log.info("notification_retention_purge", events=removed)
+        return removed

commitguard/notifications/settings.py

@@ -0,0 +1,167 @@
+"""Notification delivery configuration from the environment.
+
+=============================================  =============================================
+Variable                                       Meaning
+=============================================  =============================================
+``COMMITGUARD_NOTIFICATIONS_MODE``             ``off`` (default): in-app notifications only;
+                                               ``deliver``: e-mail and webhooks are sent;
+                                               ``test``: they are recorded in memory, never
+                                               sent (forced when ``COMMITGUARD_ENV=test``)
+``COMMITGUARD_SMTP_HOST``                      SMTP relay host (enables e-mail)
+``COMMITGUARD_SMTP_PORT``                      default 587
+``COMMITGUARD_SMTP_SECURITY``                  ``starttls`` (default), ``tls``, or ``none``
+                                               (only for localhost outside production)
+``COMMITGUARD_SMTP_USERNAME``                  optional
+``COMMITGUARD_SMTP_PASSWORD``                  optional, *or*
+``COMMITGUARD_SMTP_PASSWORD_FILE``             a file containing it (preferred)
+``COMMITGUARD_SMTP_FROM``                      sender address, e.g. ``commitguard@example.com``
+``COMMITGUARD_NOTIFICATION_SIGNING_KEY``       key from which webhook signing secrets are
+``COMMITGUARD_NOTIFICATION_SIGNING_KEY_FILE``  derived (enables webhooks; 32+ characters)
+``COMMITGUARD_NOTIFICATION_RETENTION_DAYS``    notifications, deliveries (default 90)
+=============================================  =============================================
+
+Links in e-mail and webhook payloads use ``COMMITGUARD_DASHBOARD_URL`` when set.
+"""
+
+import os
+import secrets
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import timedelta
+from enum import StrEnum
+from pathlib import Path
+
+from commitguard.github.errors import AppConfigurationError
+from commitguard.security.secrets import Secret, register_secret
+from commitguard.utils.filesystem import read_bytes_limited
+
+ENV_MODE = "COMMITGUARD_NOTIFICATIONS_MODE"
+ENV_SMTP_HOST = "COMMITGUARD_SMTP_HOST"
+ENV_SMTP_PORT = "COMMITGUARD_SMTP_PORT"
+ENV_SMTP_SECURITY = "COMMITGUARD_SMTP_SECURITY"
+ENV_SMTP_USERNAME = "COMMITGUARD_SMTP_USERNAME"
+ENV_SMTP_PASSWORD = "COMMITGUARD_SMTP_PASSWORD"  # noqa: S105 - variable name
+ENV_SMTP_PASSWORD_FILE = "COMMITGUARD_SMTP_PASSWORD_FILE"  # noqa: S105 - variable name
+ENV_SMTP_FROM = "COMMITGUARD_SMTP_FROM"
+ENV_SIGNING_KEY = "COMMITGUARD_NOTIFICATION_SIGNING_KEY"
+ENV_SIGNING_KEY_FILE = "COMMITGUARD_NOTIFICATION_SIGNING_KEY_FILE"
+ENV_RETENTION_DAYS = "COMMITGUARD_NOTIFICATION_RETENTION_DAYS"
+ENV_DASHBOARD_URL = "COMMITGUARD_DASHBOARD_URL"
+ENV_ENVIRONMENT = "COMMITGUARD_ENV"
+
+MIN_SIGNING_KEY_CHARS = 32
+MAX_SECRET_BYTES = 4096
+DEFAULT_RETENTION_DAYS = 90
+
+
+class NotificationMode(StrEnum):
+    OFF = "off"
+    DELIVER = "deliver"
+    TEST = "test"
+
+
+@dataclass(frozen=True, slots=True)
+class SmtpSettings:
+    host: str
+    port: int
+    security: str
+    sender: str
+    username: str | None = None
+    password: Secret | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationSettings:
+    mode: NotificationMode = NotificationMode.OFF
+    smtp: SmtpSettings | None = None
+    signing_key: Secret | None = None
+    retention: timedelta = timedelta(days=DEFAULT_RETENTION_DAYS)
+    dashboard_origin: str | None = None
+    production: bool = True
+
+    @property
+    def email_available(self) -> bool:
+        return self.mode is NotificationMode.TEST or (
+            self.mode is NotificationMode.DELIVER and self.smtp is not None
+        )
+
+    @property
+    def webhook_available(self) -> bool:
+        return self.mode is NotificationMode.TEST or (
+            self.mode is NotificationMode.DELIVER and self.signing_key is not None
+        )
+
+
+def _secret(env: Mapping[str, str], value_var: str, file_var: str) -> Secret | None:
+    value, path = env.get(value_var), env.get(file_var)
+    if value and path:
+        raise AppConfigurationError(f"set only one of {value_var} and {file_var}")
+    if path:
+        try:
+            value = read_bytes_limited(Path(path), max_bytes=MAX_SECRET_BYTES).decode().strip()
+        except (OSError, UnicodeDecodeError, ValueError):
+            raise AppConfigurationError(f"{file_var} could not be read") from None
+    if not value:
+        return None
+    secret = Secret(value)
+    register_secret(secret)
+    return secret
+
+
+def load_notification_settings(env: Mapping[str, str] | None = None) -> NotificationSettings:
+    source = os.environ if env is None else env
+    environment = source.get(ENV_ENVIRONMENT, "production")
+    raw_mode = source.get(ENV_MODE, NotificationMode.OFF.value)
+    try:
+        mode = NotificationMode(raw_mode)
+    except ValueError:
+        raise AppConfigurationError(f"{ENV_MODE} must be off, deliver or test") from None
+    if environment == "test" and mode is NotificationMode.DELIVER:
+        mode = NotificationMode.TEST  # a test environment never sends real notifications
+    production = environment == "production"
+
+    smtp = None
+    host = source.get(ENV_SMTP_HOST, "").strip()
+    if host:
+        sender = source.get(ENV_SMTP_FROM, "").strip()
+        if "@" not in sender or any(c in sender for c in "\r\n<>"):
+            raise AppConfigurationError(f"{ENV_SMTP_FROM} must be a plain sender address")
+        port_raw = source.get(ENV_SMTP_PORT, "587")
+        if not port_raw.isdigit() or not 0 < int(port_raw) < 65536:
+            raise AppConfigurationError(f"{ENV_SMTP_PORT} must be a TCP port")
+        security = source.get(ENV_SMTP_SECURITY, "starttls")
+        if security not in ("starttls", "tls", "none"):
+            raise AppConfigurationError(f"{ENV_SMTP_SECURITY} must be starttls, tls or none")
+        if security == "none" and (production or host not in ("localhost", "127.0.0.1")):
+            raise AppConfigurationError(
+                f"{ENV_SMTP_SECURITY}=none is only allowed for localhost outside production"
+            )
+        smtp = SmtpSettings(
+            host=host,
+            port=int(port_raw),
+            security=security,
+            sender=sender,
+            username=source.get(ENV_SMTP_USERNAME) or None,
+            password=_secret(source, ENV_SMTP_PASSWORD, ENV_SMTP_PASSWORD_FILE),
+        )
+
+    signing_key = _secret(source, ENV_SIGNING_KEY, ENV_SIGNING_KEY_FILE)
+    if signing_key is not None and len(signing_key) < MIN_SIGNING_KEY_CHARS:
+        raise AppConfigurationError(
+            f"{ENV_SIGNING_KEY} must be at least {MIN_SIGNING_KEY_CHARS} characters"
+        )
+    if mode is NotificationMode.TEST and signing_key is None:
+        signing_key = Secret(secrets.token_hex(32))  # ephemeral: test deliveries only
+
+    retention_raw = source.get(ENV_RETENTION_DAYS, str(DEFAULT_RETENTION_DAYS))
+    if not retention_raw.isdigit() or not 1 <= int(retention_raw) <= 3650:
+        raise AppConfigurationError(f"{ENV_RETENTION_DAYS} must be between 1 and 3650")
+    origin = source.get(ENV_DASHBOARD_URL, "").strip().rstrip("/") or None
+    return NotificationSettings(
+        mode=mode,
+        smtp=smtp,
+        signing_key=signing_key,
+        retention=timedelta(days=int(retention_raw)),
+        dashboard_origin=origin,
+        production=production,
+    )

commitguard/notifications/templates.py

@@ -0,0 +1,108 @@
+"""Rendering notifications for each channel.
+
+Every value that came from a repository or a user (repository names, rule
+titles, reasons, logins) was sanitised when the event was created
+(:func:`commitguard.notifications.models.clean`). Rendering adds only
+channel-appropriate encoding:
+
+* **in-app** - JSON through the API; the dashboard renders text, never HTML;
+* **e-mail** - plain text; header values are passed to ``EmailMessage``;
+* **webhook** - ``json.dumps`` with ASCII escaping, plus ``<``, ``>`` and ``&``
+  escaped as ``\u003c``-style sequences.
+
+No template includes tokens, keys, session data or internal database IDs other
+than the resource ID needed for the dashboard link.
+"""
+
+import json
+from datetime import UTC, datetime
+
+from commitguard.notifications.channels.email import OutgoingEmail
+from commitguard.notifications.models import DEFINITIONS, StoredNotificationEvent
+
+_RESOURCE_PATHS = {
+    "violation": "/violations/{id}",
+    "scan": "/scans/{id}",
+    "policy": "/policies/{id}",
+    "installation": "/github/installations/{id}",
+    "repository": "/repositories/{id}",
+    "exception": "/organization/exceptions/{id}",
+    "draft": "/organization/policies/drafts/{id}",
+    "rollout": "/organization/policies/rollouts/{id}",
+    "organization": "/organization",
+}
+
+
+def resource_path(resource_type: str, resource_id: str) -> str | None:
+    template = _RESOURCE_PATHS.get(resource_type)
+    if template is None or not resource_id.isascii() or not resource_id.isalnum():
+        return None
+    return template.format(id=resource_id)
+
+
+def render_email(
+    stored: StoredNotificationEvent,
+    *,
+    to: str,
+    organization: str,
+    dashboard_origin: str | None,
+) -> OutgoingEmail:
+    event = stored.event
+    definition = DEFINITIONS[event.type]
+    path = resource_path(event.resource_type, event.resource_id)
+    lines = [
+        event.title,
+        "",
+        event.body,
+        "",
+        f"Organization: {organization}",
+        f"Type: {definition.label}",
+        f"Severity: {event.severity.value.upper()}",
+        f"Time: {stored.last_occurred_at.astimezone(UTC).strftime('%Y-%m-%d %H:%M UTC')}",
+    ]
+    if stored.occurrences > 1:
+        lines.append(f"Occurrences: {stored.occurrences}")
+    if dashboard_origin and path:
+        lines += ["", f"Open in CommitGuard: {dashboard_origin}{path}"]
+    lines += [
+        "",
+        "--",
+        "You receive this because an administrator of this organization added this address "
+        "to CommitGuard notifications.",
+        "CommitGuard never rewrites Git history or changes repositories.",
+    ]
+    return OutgoingEmail(
+        to=to,
+        subject=f"[CommitGuard] {event.severity.value.upper()}: {event.title}",
+        text="\n".join(lines) + "\n",
+    )
+
+
+def render_webhook(
+    stored: StoredNotificationEvent,
+    *,
+    organization: str,
+    repository: str | None,
+    dashboard_origin: str | None,
+    now: datetime,
+) -> bytes:
+    event = stored.event
+    path = resource_path(event.resource_type, event.resource_id)
+    document = {
+        "id": event.event_id,
+        "type": event.type.value,
+        "severity": event.severity.value,
+        "title": event.title,
+        "summary": event.body,
+        "organization": organization,
+        "repository": repository,
+        "occurrences": stored.occurrences,
+        "created_at": stored.created_at.astimezone(UTC).isoformat(),
+        "last_occurred_at": stored.last_occurred_at.astimezone(UTC).isoformat(),
+        "sent_at": now.astimezone(UTC).isoformat(),
+        "url": f"{dashboard_origin}{path}" if dashboard_origin and path else None,
+        "details": event.metadata,
+    }
+    text = json.dumps(document, ensure_ascii=True, sort_keys=True, separators=(",", ":"))
+    # Still valid JSON; safe even if a receiver embeds the payload in an HTML page.
+    return text.replace("<", "\\u003c").replace(">", "\\u003e").replace("&", "\\u0026").encode()

commitguard/observability/__init__.py

@@ -0,0 +1,5 @@
+"""Structured logging, correlation IDs and metrics for long-running services.
+
+Used by the GitHub App service. The CLI, hooks and GitHub Action print
+human-readable output instead and do not depend on this package.
+"""

commitguard/observability/logging.py

@@ -0,0 +1,161 @@
+"""Structured JSON logs with correlation IDs and secret redaction.
+
+Every record is one JSON object::
+
+    {"ts": "...", "level": "info", "logger": "commitguard.github.worker",
+     "event": "scan_completed", "delivery_id": "...", "job_id": "...",
+     "repository": "owner/name", "result": "block", "violations": 1}
+
+* correlation fields (``delivery_id``, ``job_id``, ``scan_id``,
+  ``installation_id``, ``repository``) are taken from context variables, so a
+  webhook, its scan, the GitHub API requests and the Check Run update share IDs;
+* field names that look like credentials are replaced with ``[REDACTED]``;
+* every string passes through :func:`commitguard.security.secrets.redact` and
+  is truncated, so untrusted commit data cannot flood the log;
+* exceptions are logged by type and redacted message only - never tracebacks
+  with local variables.
+"""
+
+import json
+import logging
+import sys
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from contextvars import ContextVar
+from datetime import UTC, datetime
+from typing import Any, TextIO
+
+from commitguard.security.secrets import REDACTED, redact
+
+MAX_FIELD_CHARS = 1000
+MAX_FIELDS = 40
+CORRELATION_FIELDS = (
+    "request_id",
+    "delivery_id",
+    "job_id",
+    "scan_id",
+    "notification_event_id",
+    "installation_id",
+    "repository",
+)
+_SENSITIVE_KEY_PARTS = (
+    "token",
+    "secret",
+    "password",
+    "private_key",
+    "privatekey",
+    "authorization",
+    "credential",
+    "jwt",
+    "signature",
+    "cookie",
+)
+
+_correlation: ContextVar[Mapping[str, str | int] | None] = ContextVar(
+    "commitguard_correlation", default=None
+)
+
+
+@contextmanager
+def correlation(**fields: str | int | None) -> Iterator[None]:
+    """Attach correlation fields to every log record emitted inside the block."""
+    unknown = set(fields) - set(CORRELATION_FIELDS)
+    if unknown:
+        raise ValueError(f"unknown correlation field(s): {', '.join(sorted(unknown))}")
+    merged = dict(_correlation.get() or {})
+    merged.update({k: v for k, v in fields.items() if v is not None})
+    token = _correlation.set(merged)
+    try:
+        yield
+    finally:
+        _correlation.reset(token)
+
+
+def current_correlation() -> dict[str, str | int]:
+    return dict(_correlation.get() or {})
+
+
+def _is_sensitive(key: str) -> bool:
+    lowered = key.lower()
+    return any(part in lowered for part in _SENSITIVE_KEY_PARTS)
+
+
+def _clean(value: Any, depth: int = 0) -> Any:
+    if value is None or isinstance(value, bool | int | float):
+        return value
+    if isinstance(value, str):
+        text = redact(value)
+        return text if len(text) <= MAX_FIELD_CHARS else text[:MAX_FIELD_CHARS] + "...[truncated]"
+    if depth < 3 and isinstance(value, Mapping):
+        return {
+            str(k): (REDACTED if _is_sensitive(str(k)) else _clean(v, depth + 1))
+            for k, v in list(value.items())[:MAX_FIELDS]
+        }
+    if depth < 3 and isinstance(value, list | tuple | set | frozenset):
+        return [_clean(v, depth + 1) for v in list(value)[:MAX_FIELDS]]
+    return _clean(str(value), depth)
+
+
+class JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        document: dict[str, Any] = {
+            "ts": datetime.fromtimestamp(record.created, UTC).isoformat(),
+            "level": record.levelname.lower(),
+            "logger": record.name,
+            "event": _clean(record.getMessage()),
+        }
+        document.update(_clean(getattr(record, "correlation", None) or {}))
+        fields = getattr(record, "fields", None) or {}
+        for key, value in list(fields.items())[:MAX_FIELDS]:
+            if key in document:
+                key = f"field_{key}"
+            document[key] = REDACTED if _is_sensitive(key) else _clean(value)
+        if record.exc_info and record.exc_info[1] is not None:
+            exc = record.exc_info[1]
+            document["error_type"] = type(exc).__name__
+            document["error"] = _clean(str(exc))
+        return json.dumps(document, ensure_ascii=True, sort_keys=False, default=str)
+
+
+class StructuredLogger:
+    """Thin wrapper: ``log.info("scan_completed", result="block", violations=1)``."""
+
+    def __init__(self, logger: logging.Logger) -> None:
+        self._logger = logger
+
+    def _log(
+        self, level: int, event: str, fields: Mapping[str, Any], exc: BaseException | None
+    ) -> None:
+        if not self._logger.isEnabledFor(level):
+            return
+        extra = {"fields": dict(fields), "correlation": current_correlation()}
+        exc_info = (type(exc), exc, None) if exc is not None else None
+        self._logger.log(level, event, extra=extra, exc_info=exc_info)
+
+    def debug(self, event: str, **fields: Any) -> None:
+        self._log(logging.DEBUG, event, fields, None)
+
+    def info(self, event: str, **fields: Any) -> None:
+        self._log(logging.INFO, event, fields, None)
+
+    def warning(self, event: str, *, exc: BaseException | None = None, **fields: Any) -> None:
+        self._log(logging.WARNING, event, fields, exc)
+
+    def error(self, event: str, *, exc: BaseException | None = None, **fields: Any) -> None:
+        self._log(logging.ERROR, event, fields, exc)
+
+
+def get_logger(name: str) -> StructuredLogger:
+    return StructuredLogger(logging.getLogger(name))
+
+
+def configure_json_logging(stream: TextIO | None = None, level: int = logging.INFO) -> None:
+    """Send ``commitguard.*`` logs to ``stream`` (default stderr) as JSON lines."""
+    handler = logging.StreamHandler(stream or sys.stderr)
+    handler.setFormatter(JsonFormatter())
+    root = logging.getLogger("commitguard")
+    for existing in list(root.handlers):
+        root.removeHandler(existing)
+    root.addHandler(handler)
+    root.setLevel(level)
+    root.propagate = False

commitguard/observability/metrics.py

@@ -0,0 +1,105 @@
+"""Counters for the GitHub App service.
+
+A deliberately small abstraction: services call ``metrics.increment(name)``
+and a deployment can later bridge :class:`Metrics` to Prometheus, StatsD or
+OpenTelemetry. The in-memory implementation is exposed to the readiness probe
+and tests only; metric labels never contain secrets or commit data.
+"""
+
+import threading
+from collections import Counter
+from typing import Protocol
+
+WEBHOOKS_RECEIVED = "webhooks_received"
+WEBHOOKS_REJECTED = "webhooks_rejected"
+WEBHOOKS_DUPLICATE = "webhooks_duplicate"
+SCANS_QUEUED = "scans_queued"
+SCANS_STARTED = "scans_started"
+SCANS_COMPLETED = "scans_completed"
+SCANS_FAILED = "scans_failed"
+SCANS_CANCELLED = "scans_cancelled"
+POLICY_VIOLATIONS = "policy_violations"
+GITHUB_API_ERRORS = "github_api_errors"
+GITHUB_RATE_LIMITS = "github_rate_limits"
+GITHUB_EVENTS_RECEIVED = "github_events_received"
+GITHUB_EVENTS_FAILED = "github_events_failed"
+GITHUB_EVENTS_REPLAYED = "github_events_replayed"
+MERGE_GROUPS_SCANNED = "merge_groups_scanned"
+MERGE_GROUPS_FAILED = "merge_groups_failed"
+CHECK_RERUNS = "check_reruns"
+SCAN_RETRIES = "scan_retries"
+POLICY_ROLLBACKS = "policy_rollbacks"
+POLICY_ROLLBACK_FAILURES = "policy_rollback_failures"
+NOTIFICATIONS_CREATED = "notifications_created"
+NOTIFICATIONS_SENT = "notifications_sent"
+NOTIFICATIONS_FAILED = "notifications_failed"
+NOTIFICATION_RETRIES = "notification_retries"
+
+KNOWN_METRICS = frozenset(
+    {
+        WEBHOOKS_RECEIVED,
+        WEBHOOKS_REJECTED,
+        WEBHOOKS_DUPLICATE,
+        SCANS_QUEUED,
+        SCANS_STARTED,
+        SCANS_COMPLETED,
+        SCANS_FAILED,
+        SCANS_CANCELLED,
+        POLICY_VIOLATIONS,
+        GITHUB_API_ERRORS,
+        GITHUB_RATE_LIMITS,
+        GITHUB_EVENTS_RECEIVED,
+        GITHUB_EVENTS_FAILED,
+        GITHUB_EVENTS_REPLAYED,
+        MERGE_GROUPS_SCANNED,
+        MERGE_GROUPS_FAILED,
+        CHECK_RERUNS,
+        SCAN_RETRIES,
+        POLICY_ROLLBACKS,
+        POLICY_ROLLBACK_FAILURES,
+        NOTIFICATIONS_CREATED,
+        NOTIFICATIONS_SENT,
+        NOTIFICATIONS_FAILED,
+        NOTIFICATION_RETRIES,
+    }
+)
+
+
+class Metrics(Protocol):
+    def increment(self, name: str, value: int = 1, **labels: str) -> None: ...
+
+
+class NullMetrics:
+    def increment(self, name: str, value: int = 1, **labels: str) -> None:
+        return None
+
+
+class InMemoryMetrics:
+    """Thread-safe counters keyed by metric name and labels."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._counters: Counter[tuple[str, tuple[tuple[str, str], ...]]] = Counter()
+
+    def increment(self, name: str, value: int = 1, **labels: str) -> None:
+        if name not in KNOWN_METRICS:
+            raise ValueError(f"unknown metric {name!r}")
+        key = (name, tuple(sorted(labels.items())))
+        with self._lock:
+            self._counters[key] += value
+
+    def value(self, name: str, **labels: str) -> int:
+        """Sum of a counter over all label sets matching ``labels``."""
+        with self._lock:
+            return sum(
+                count
+                for (metric, metric_labels), count in self._counters.items()
+                if metric == name and set(labels.items()) <= set(metric_labels)
+            )
+
+    def snapshot(self) -> dict[str, int]:
+        with self._lock:
+            totals: Counter[str] = Counter()
+            for (metric, _), count in self._counters.items():
+                totals[metric] += count
+        return dict(sorted(totals.items()))

commitguard/policies/__init__.py

@@ -0,0 +1,6 @@
+"""Policy engine: decides what happens to findings.
+
+Detection and policy are separate on purpose. A detector reports *that* a
+commit lists an AI co-author; the repository's policy decides whether that is
+allowed, merits a warning, or blocks the commit/push.
+"""