commitguardian 0.1.0__py3-none-any.whl

commitguard/api/hosting.py

@@ -0,0 +1,196 @@
+"""One process, one origin: webhooks, the dashboard API and the dashboard itself.
+
+::
+
+    /webhooks/github, /health, /ready  -> GitHub App service (Phase 5, unchanged)
+    /api/v1/...                        -> DashboardApi
+    everything else (GET/HEAD)         -> built dashboard files; unknown paths
+                                          without a file extension -> index.html
+                                          (client-side routes, deep links, refresh)
+
+Serving the dashboard from the API's origin keeps cookies ``SameSite`` and
+first-party and needs no CORS. The dashboard is a static bundle: it holds no
+secrets, and its Content Security Policy allows scripts, styles, fonts and
+API calls from the same origin only (no inline scripts, no ``eval``).
+"""
+
+import mimetypes
+from collections.abc import Callable, Iterable
+from datetime import UTC, datetime
+from pathlib import Path
+from wsgiref.types import StartResponse, WSGIEnvironment
+
+from commitguard.api.app import DashboardApi
+from commitguard.api.settings import DashboardSettings, Environment
+from commitguard.controlplane.commands import ControlPlaneCommands
+from commitguard.controlplane.identity import AuthService
+from commitguard.controlplane.members import MembershipService
+from commitguard.controlplane.notifications import NotificationCenter
+from commitguard.controlplane.queries import DashboardQueries
+from commitguard.github.app import GitHubAppService, create_wsgi_app
+from commitguard.github.enforcement_status import EnforcementProbe
+
+type WSGIApp = Callable[[WSGIEnvironment, StartResponse], Iterable[bytes]]
+
+MAX_STATIC_FILE_BYTES = 20 * 1024 * 1024
+
+DASHBOARD_CSP = (
+    "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; "
+    "font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'none'; "
+    "form-action 'self'; frame-ancestors 'none'"
+)
+
+_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".ico": "image/x-icon",
+    ".woff2": "font/woff2",
+    ".woff": "font/woff",
+    ".txt": "text/plain; charset=utf-8",
+    ".webmanifest": "application/manifest+json",
+}
+
+
+class StaticSite:
+    """Serves a built single-page application from a directory, read-only."""
+
+    def __init__(self, root: Path, settings: DashboardSettings) -> None:
+        self._root = root.resolve()
+        self._settings = settings
+
+    def _headers(self, path: Path) -> list[tuple[str, str]]:
+        content_type = _TYPES.get(path.suffix) or mimetypes.guess_type(path.name)[0]
+        immutable = path.parent.name == "assets"
+        headers = [
+            ("Content-Type", content_type or "application/octet-stream"),
+            (
+                "Cache-Control",
+                "public, max-age=31536000, immutable" if immutable else "no-cache",
+            ),
+            ("X-Content-Type-Options", "nosniff"),
+            ("Referrer-Policy", "no-referrer"),
+            ("X-Frame-Options", "DENY"),
+            ("Cross-Origin-Opener-Policy", "same-origin"),
+            ("Permissions-Policy", "camera=(), microphone=(), geolocation=(), payment=()"),
+            ("Content-Security-Policy", DASHBOARD_CSP),
+        ]
+        if self._settings.environment is Environment.PRODUCTION and self._settings.https:
+            headers.append(("Strict-Transport-Security", "max-age=63072000; includeSubDomains"))
+        return headers
+
+    def resolve(self, request_path: str) -> Path | None:
+        """The file for a request path, the SPA entry point, or None (404)."""
+        relative = request_path.lstrip("/")
+        if "\x00" in relative or "\\" in relative:
+            return None
+        parts = [p for p in relative.split("/") if p]
+        if any(p in (".", "..") or p.startswith(".") for p in parts):
+            return None
+        candidate = (self._root.joinpath(*parts) if parts else self._root / "index.html").resolve()
+        if not candidate.is_relative_to(self._root):
+            return None
+        if candidate.is_file():
+            return candidate
+        if parts and "." in parts[-1]:
+            return None  # a missing asset is a 404, not the application shell
+        index = self._root / "index.html"
+        return index if index.is_file() else None
+
+    def __call__(self, environ: WSGIEnvironment, start_response: StartResponse) -> Iterable[bytes]:
+        method = environ.get("REQUEST_METHOD", "GET")
+        if method not in ("GET", "HEAD"):
+            start_response(
+                "405 Method Not Allowed",
+                [("Allow", "GET, HEAD"), ("Content-Type", "text/plain"), ("Content-Length", "0")],
+            )
+            return [b""]
+        path = self.resolve(str(environ.get("PATH_INFO", "/")))
+        if path is None or path.stat().st_size > MAX_STATIC_FILE_BYTES:
+            body = b"Not Found"
+            start_response(
+                "404 Not Found",
+                [
+                    ("Content-Type", "text/plain; charset=utf-8"),
+                    ("Content-Length", str(len(body))),
+                    ("X-Content-Type-Options", "nosniff"),
+                ],
+            )
+            return [body]
+        data = path.read_bytes()
+        headers = self._headers(path)
+        headers.append(("Content-Length", str(len(data))))
+        start_response("200 OK", headers)
+        return [data] if method == "GET" else [b""]
+
+
+def build_dashboard(
+    service: GitHubAppService,
+    settings: DashboardSettings,
+    *,
+    now: Callable[[], datetime] = lambda: datetime.now(UTC),
+) -> DashboardApi:
+    """Wire the dashboard API to the GitHub App service's store, client and workers."""
+    store = service.store
+    queries = DashboardQueries(store, now=now)
+    auth = AuthService(
+        store,
+        service.client,
+        service.audit,
+        client_id=settings.client_id,
+        client_secret=settings.client_secret,
+        redirect_uri=settings.redirect_uri,
+        now=now,
+    )
+    commands = ControlPlaneCommands(
+        store,
+        queries,
+        service.audit,
+        service.installations,
+        EnforcementProbe(service.client, now=now),
+        enqueue=service.queue.put,
+        now=now,
+    )
+    service.add_maintenance_task(auth.purge_expired)
+    return DashboardApi(
+        settings=settings,
+        auth=auth,
+        queries=queries,
+        commands=commands,
+        policies=service.policies,
+        members=MembershipService(store, service.audit, now=now),
+        notifications=NotificationCenter(
+            store, service.audit, service.notifications.settings, now=now
+        ),
+        governance=service.governance,
+        now=now,
+    )
+
+
+def create_server_app(
+    service: GitHubAppService,
+    dashboard: DashboardApi | None = None,
+) -> WSGIApp:
+    webhooks = create_wsgi_app(service)
+    static = (
+        StaticSite(dashboard.settings.static_dir, dashboard.settings)
+        if dashboard is not None and dashboard.settings.static_dir is not None
+        else None
+    )
+
+    def application(environ: WSGIEnvironment, start_response: StartResponse) -> Iterable[bytes]:
+        path = str(environ.get("PATH_INFO", ""))
+        if path == "/api" or path.startswith("/api/"):
+            if dashboard is None:
+                return webhooks(environ, start_response)  # JSON 404
+            return dashboard(environ, start_response)
+        if path in ("/health", "/ready") or path.startswith("/webhooks/"):
+            return webhooks(environ, start_response)
+        if static is not None:
+            return static(environ, start_response)
+        return webhooks(environ, start_response)
+
+    return application

commitguard/api/http.py

@@ -0,0 +1,252 @@
+"""HTTP primitives for the dashboard API: requests, responses, errors, cookies."""
+
+import json
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import parse_qsl
+from wsgiref.types import WSGIEnvironment
+
+from pydantic import BaseModel
+
+from commitguard.controlplane.access import AccessScope, Principal
+from commitguard.controlplane.errors import ControlPlaneError
+
+MAX_BODY_BYTES = 64 * 1024
+MAX_QUERY_CHARS = 4096
+MAX_QUERY_PARAMS = 32
+MAX_COOKIE_HEADER_CHARS = 8192
+MAX_JSON_DEPTH = 16
+
+REASONS = {
+    200: "OK",
+    201: "Created",
+    202: "Accepted",
+    204: "No Content",
+    302: "Found",
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    409: "Conflict",
+    411: "Length Required",
+    413: "Payload Too Large",
+    415: "Unsupported Media Type",
+    422: "Unprocessable Content",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+}
+
+API_SECURITY_HEADERS: tuple[tuple[str, str], ...] = (
+    ("Cache-Control", "no-store"),
+    ("X-Content-Type-Options", "nosniff"),
+    ("Referrer-Policy", "no-referrer"),
+    ("X-Frame-Options", "DENY"),
+    ("Content-Security-Policy", "default-src 'none'; frame-ancestors 'none'; base-uri 'none'"),
+    ("Cross-Origin-Opener-Policy", "same-origin"),
+    ("Cross-Origin-Resource-Policy", "same-origin"),
+)
+
+
+class ApiError(Exception):
+    """An error returned to the client. ``message`` is safe to display."""
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        *,
+        field: str | None = None,
+        headers: Iterable[tuple[str, str]] = (),
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.field = field
+        self.headers = tuple(headers)
+        self.details = details
+
+    @classmethod
+    def from_control_plane(cls, exc: ControlPlaneError) -> "ApiError":
+        changes = getattr(exc, "changes", ())
+        return cls(
+            exc.status,
+            exc.code,
+            str(exc),
+            field=getattr(exc, "field", None),
+            details={"changes": list(changes)} if changes else None,
+        )
+
+
+def bad_request(message: str, field: str | None = None) -> ApiError:
+    return ApiError(400, "VALIDATION_ERROR", message, field=field)
+
+
+NOT_FOUND = "The requested resource was not found."
+
+
+@dataclass
+class Request:
+    method: str
+    path: str
+    query: Mapping[str, str]
+    headers: Mapping[str, str]
+    cookies: Mapping[str, str]
+    body: bytes
+    remote_addr: str
+    request_id: str
+    route: str = "unmatched"
+    params: dict[str, Any] = field(default_factory=dict)
+    principal: Principal | None = None
+    session_token: str | None = None
+    scope: AccessScope | None = None
+
+    def header(self, name: str) -> str | None:
+        return self.headers.get(name.lower())
+
+    def arg(self, name: str) -> str | None:
+        return self.query.get(name)
+
+    def json(self) -> dict[str, Any]:
+        if not self.body:
+            return {}
+        content_type = (self.header("content-type") or "").split(";", 1)[0].strip().lower()
+        if content_type != "application/json":
+            raise ApiError(415, "UNSUPPORTED_MEDIA_TYPE", "Send the request body as JSON.")
+        try:
+            document = json.loads(self.body.decode("utf-8"), object_pairs_hook=_no_duplicates)
+        except (UnicodeDecodeError, ValueError, RecursionError):
+            raise bad_request("The request body is not valid JSON.") from None
+        if not isinstance(document, dict):
+            raise bad_request("The request body must be a JSON object.")
+        if _depth(document) > MAX_JSON_DEPTH:
+            raise bad_request("The request body is nested too deeply.")
+        return document
+
+
+def _no_duplicates(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate key")
+        result[key] = value
+    return result
+
+
+def _depth(value: Any, level: int = 0) -> int:
+    if level > MAX_JSON_DEPTH:
+        return level
+    if isinstance(value, dict):
+        return max((_depth(v, level + 1) for v in value.values()), default=level + 1)
+    if isinstance(value, list):
+        return max((_depth(v, level + 1) for v in value), default=level + 1)
+    return level
+
+
+def parse_query(environ: WSGIEnvironment) -> dict[str, str]:
+    raw = environ.get("QUERY_STRING", "") or ""
+    if len(raw) > MAX_QUERY_CHARS:
+        raise bad_request("The query string is too long.")
+    try:
+        pairs = parse_qsl(raw, keep_blank_values=True, strict_parsing=False, max_num_fields=64)
+    except ValueError:
+        raise bad_request("The query string is invalid.") from None
+    if len(pairs) > MAX_QUERY_PARAMS:
+        raise bad_request("Too many query parameters.")
+    query: dict[str, str] = {}
+    for key, value in pairs:
+        if key in query:
+            raise bad_request(f"Query parameter {key[:40]} is repeated.", field=key[:40])
+        if any(ord(c) < 0x20 for c in key + value):
+            raise bad_request("The query string contains control characters.")
+        query[key] = value
+    return query
+
+
+def parse_cookies(header: str | None) -> dict[str, str]:
+    """Parse a Cookie header without evaluating attributes; malformed parts are ignored."""
+    cookies: dict[str, str] = {}
+    if not header or len(header) > MAX_COOKIE_HEADER_CHARS:
+        return cookies
+    for part in header.split(";"):
+        name, sep, value = part.strip().partition("=")
+        if not sep or not name or not name.isascii():
+            continue
+        value = value.strip()
+        if value.startswith('"') and value.endswith('"') and len(value) >= 2:
+            value = value[1:-1]
+        cookies.setdefault(name, value)
+    return cookies
+
+
+def set_cookie(
+    name: str,
+    value: str,
+    *,
+    max_age: int | None,
+    http_only: bool = True,
+    same_site: str = "Lax",
+) -> tuple[str, str]:
+    """A ``__Host-`` style cookie: Secure, Path=/, no Domain."""
+    parts = [f"{name}={value}", "Path=/", "Secure", f"SameSite={same_site}"]
+    if http_only:
+        parts.append("HttpOnly")
+    if max_age is not None:
+        parts.append(f"Max-Age={max_age}")
+    return ("Set-Cookie", "; ".join(parts))
+
+
+def clear_cookie(name: str) -> tuple[str, str]:
+    return set_cookie(name, "", max_age=0)
+
+
+@dataclass
+class Response:
+    status: int
+    body: bytes = b""
+    headers: list[tuple[str, str]] = field(default_factory=list)
+
+
+def _encode(value: Any) -> Any:
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if isinstance(value, list | tuple):
+        return [_encode(v) for v in value]
+    if isinstance(value, dict):
+        return {k: _encode(v) for k, v in value.items()}
+    return value
+
+
+def json_body(document: Mapping[str, Any]) -> bytes:
+    return json.dumps(_encode(document), ensure_ascii=True, separators=(",", ":")).encode("ascii")
+
+
+def ok(data: Any, meta: Mapping[str, Any] | None = None, *, status: int = 200) -> Response:
+    return Response(
+        status,
+        json_body({"data": data, "meta": dict(meta or {})}),
+        [("Content-Type", "application/json; charset=utf-8")],
+    )
+
+
+def error_response(exc: ApiError, request_id: str) -> Response:
+    error: dict[str, Any] = {"code": exc.code, "message": exc.message, "request_id": request_id}
+    if exc.field:
+        error["field"] = exc.field
+    if exc.details:
+        error["details"] = exc.details
+    return Response(
+        exc.status,
+        json_body({"error": error}),
+        [("Content-Type", "application/json; charset=utf-8"), *exc.headers],
+    )
+
+
+def redirect(location: str, headers: Iterable[tuple[str, str]] = ()) -> Response:
+    return Response(302, b"", [("Location", location), *headers])

commitguard/api/settings.py

@@ -0,0 +1,169 @@
+"""Dashboard configuration from the environment.
+
+======================================================  ======================================
+Variable                                                Meaning
+======================================================  ======================================
+``COMMITGUARD_DASHBOARD_URL``                           public origin of the dashboard, e.g.
+                                                        ``https://commitguard.example.com``;
+                                                        enables the dashboard and its API
+``COMMITGUARD_GITHUB_CLIENT_ID``                        the GitHub App's client ID
+``COMMITGUARD_GITHUB_CLIENT_SECRET``                    the GitHub App's client secret, *or*
+``COMMITGUARD_GITHUB_CLIENT_SECRET_FILE``               a file containing it (preferred)
+``COMMITGUARD_DASHBOARD_STATIC_DIR``                    optional: built dashboard (``web/dist``)
+                                                        served by the same process
+``COMMITGUARD_DASHBOARD_ALLOWED_ORIGINS``               optional: comma-separated extra origins
+                                                        allowed to call the API with credentials
+``COMMITGUARD_ENV``                                     ``production`` (default),
+                                                        ``development`` or ``test``
+======================================================  ======================================
+
+Environments differ only where it matters:
+
+* ``production`` requires an ``https://`` dashboard URL and sends
+  ``Strict-Transport-Security``;
+* ``development`` and ``test`` also accept ``http://localhost`` and
+  ``http://127.0.0.1`` URLs (browsers still honour ``Secure`` cookies there)
+  and omit HSTS so a local HTTP setup is not pinned to HTTPS.
+
+Every other security control - cookie flags, CSRF, CORS allow-list, CSP,
+authorization - is identical in all environments. Test suites generate their
+own keys and secrets; production credentials are never needed to run them.
+"""
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from commitguard.github.errors import AppConfigurationError
+from commitguard.security.secrets import Secret, register_secret
+from commitguard.utils.filesystem import read_bytes_limited
+
+ENV_DASHBOARD_URL = "COMMITGUARD_DASHBOARD_URL"
+ENV_CLIENT_ID = "COMMITGUARD_GITHUB_CLIENT_ID"
+ENV_CLIENT_SECRET = "COMMITGUARD_GITHUB_CLIENT_SECRET"  # noqa: S105 - variable name
+ENV_CLIENT_SECRET_FILE = "COMMITGUARD_GITHUB_CLIENT_SECRET_FILE"  # noqa: S105 - variable name
+ENV_STATIC_DIR = "COMMITGUARD_DASHBOARD_STATIC_DIR"
+ENV_ALLOWED_ORIGINS = "COMMITGUARD_DASHBOARD_ALLOWED_ORIGINS"
+ENV_ENVIRONMENT = "COMMITGUARD_ENV"
+
+CALLBACK_PATH = "/api/v1/auth/callback"
+MAX_CLIENT_SECRET_BYTES = 4096
+
+
+class Environment(StrEnum):
+    PRODUCTION = "production"
+    DEVELOPMENT = "development"
+    TEST = "test"
+
+
+@dataclass(frozen=True, slots=True)
+class DashboardSettings:
+    origin: str  # scheme://host[:port], no path
+    client_id: str
+    client_secret: Secret
+    environment: Environment = Environment.PRODUCTION
+    static_dir: Path | None = None
+    allowed_origins: tuple[str, ...] = ()
+
+    @property
+    def redirect_uri(self) -> str:
+        return self.origin + CALLBACK_PATH
+
+    @property
+    def https(self) -> bool:
+        return self.origin.startswith("https://")
+
+    @property
+    def cors_origins(self) -> frozenset[str]:
+        return frozenset(self.allowed_origins)
+
+    @property
+    def trusted_origins(self) -> frozenset[str]:
+        return frozenset((self.origin, *self.allowed_origins))
+
+
+def normalize_origin(value: str, environment: Environment, variable: str) -> str:
+    parts = urlsplit(value.strip())
+    local = parts.hostname in ("localhost", "127.0.0.1")
+    if parts.scheme not in ("https", "http") or not parts.hostname:
+        raise AppConfigurationError(f"{variable} must be an http(s) origin")
+    if parts.scheme == "http" and not (local and environment is not Environment.PRODUCTION):
+        raise AppConfigurationError(
+            f"{variable} must use https (http is only accepted for localhost outside production)"
+        )
+    if parts.username or parts.password or parts.query or parts.fragment:
+        raise AppConfigurationError(f"{variable} must not contain credentials, query or fragment")
+    if parts.path not in ("", "/"):
+        raise AppConfigurationError(f"{variable} must be an origin without a path")
+    if value.strip() == "*":
+        raise AppConfigurationError(f"{variable} must name explicit origins")
+    port = f":{parts.port}" if parts.port else ""
+    return f"{parts.scheme}://{parts.hostname.lower()}{port}"
+
+
+def _client_secret(env: Mapping[str, str]) -> Secret:
+    value = env.get(ENV_CLIENT_SECRET)
+    path = env.get(ENV_CLIENT_SECRET_FILE)
+    if value and path:
+        raise AppConfigurationError(
+            f"set only one of {ENV_CLIENT_SECRET} and {ENV_CLIENT_SECRET_FILE}"
+        )
+    if path:
+        try:
+            raw = read_bytes_limited(Path(path), max_bytes=MAX_CLIENT_SECRET_BYTES)
+            value = raw.decode("utf-8").strip()
+        except (OSError, UnicodeDecodeError, ValueError):
+            raise AppConfigurationError(f"{ENV_CLIENT_SECRET_FILE} could not be read") from None
+    if not value or len(value) < 16:
+        raise AppConfigurationError(
+            f"{ENV_CLIENT_SECRET} (or {ENV_CLIENT_SECRET_FILE}) is not set or too short"
+        )
+    secret = Secret(value)
+    register_secret(secret)
+    return secret
+
+
+def dashboard_enabled(env: Mapping[str, str] | None = None) -> bool:
+    return bool((os.environ if env is None else env).get(ENV_DASHBOARD_URL))
+
+
+def load_dashboard_settings(env: Mapping[str, str] | None = None) -> DashboardSettings:
+    source = os.environ if env is None else env
+    raw_environment = source.get(ENV_ENVIRONMENT, Environment.PRODUCTION.value)
+    try:
+        environment = Environment(raw_environment)
+    except ValueError:
+        raise AppConfigurationError(
+            f"{ENV_ENVIRONMENT} must be production, development or test"
+        ) from None
+    url = source.get(ENV_DASHBOARD_URL)
+    if not url:
+        raise AppConfigurationError(f"{ENV_DASHBOARD_URL} is not set")
+    origin = normalize_origin(url, environment, ENV_DASHBOARD_URL)
+    client_id = source.get(ENV_CLIENT_ID, "")
+    if not (0 < len(client_id) <= 64) or not client_id.replace(".", "").isalnum():
+        raise AppConfigurationError(f"{ENV_CLIENT_ID} is not set or invalid")
+    static_raw = source.get(ENV_STATIC_DIR)
+    static_dir = None
+    if static_raw:
+        static_dir = Path(static_raw)
+        if not static_dir.is_absolute() or not (static_dir / "index.html").is_file():
+            raise AppConfigurationError(
+                f"{ENV_STATIC_DIR} must be an absolute path to a built dashboard (index.html)"
+            )
+    allowed = tuple(
+        normalize_origin(item, environment, ENV_ALLOWED_ORIGINS)
+        for item in source.get(ENV_ALLOWED_ORIGINS, "").split(",")
+        if item.strip()
+    )
+    return DashboardSettings(
+        origin=origin,
+        client_id=client_id,
+        client_secret=_client_secret(source),
+        environment=environment,
+        static_dir=static_dir,
+        allowed_origins=allowed,
+    )

commitguard/audit/__init__.py

@@ -0,0 +1,13 @@
+"""Audit events: a structured record of what CommitGuard decided and why.
+
+The GitHub App records installation changes, scans, violations, policy
+modifications and errors as :class:`~commitguard.audit.models.AuditEvent`
+objects. Every event is written as a structured log line and, when a storage
+backend is configured, appended to it (the App uses its SQLite state store).
+
+Audit events are deliberately small: IDs, commit SHAs, rule IDs, finding
+fingerprints, counts and decisions - never commit messages, author names or
+e-mail addresses, file contents, tokens or keys. They are retained for a
+bounded period (see docs/github-app.md). The local CLI and Git hooks do not
+record audit events.
+"""

commitguard/audit/logger.py

@@ -0,0 +1,34 @@
+"""Audit logger: structured log line + optional storage for every event."""
+
+from collections.abc import Sequence
+
+from commitguard.audit.models import AuditEvent
+from commitguard.audit.storage import AuditStorage
+from commitguard.observability.logging import get_logger
+
+log = get_logger("commitguard.audit")
+
+
+class AuditLogger:
+    def __init__(self, storages: Sequence[AuditStorage] = ()) -> None:
+        self._storages = tuple(storages)
+
+    def record(self, event: AuditEvent) -> None:
+        self.log(event)
+        for storage in self._storages:
+            storage.append_audit_event(event)
+
+    @staticmethod
+    def log(event: AuditEvent) -> None:
+        log.info(
+            "audit",
+            audit_type=event.type.value,
+            audit_event_id=event.event_id,
+            actor_type=event.actor_type.value,
+            actor_id=event.actor_id,
+            installation=event.installation_id,
+            repository_id=event.repository_id,
+            head_sha=event.head_sha,
+            action=event.action.value if event.action else None,
+            data=event.data,
+        )