sediment-api 0.1.0__py3-none-any.whl

sediment_api/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Sediment ingest API."""
+
+# Single source for the API version string — FastAPI's ``app.version``
+# (reported by /health) and GET /v1/me both read it, so the two cannot drift.
+__version__ = "0.1.0"

sediment_api/config.py

@@ -0,0 +1,230 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Runtime configuration via environment variables (``SEDIMENT_`` prefix, .env)."""
+
+import json
+import re
+from typing import Annotated
+
+from pydantic import Field, SecretStr, field_validator
+from pydantic_settings import BaseSettings, NoDecode, SettingsConfigDict
+from sediment_core import ForgeHost, normalize_org_id
+
+# Token values that mean "operator never configured a real secret".
+_INSECURE_DEFAULTS = {
+    "",
+    "changeme",
+    "change-me",
+    "replace-me",
+    "your-token",
+    "your-secret",
+    "password",
+    "secret",
+}
+_CLIENT_ID = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$")
+# ADR 0018: production rejects a hand-edited operator, ingest, or webhook
+# secret shorter than this floor. scripts/create_deploy_env.py generates
+# 64-character secrets; 24 stays well under that while still costing an
+# unthrottled online guesser (see docs/adr/0018) meaningfully more than a
+# short word does.
+_MIN_SECRET_LENGTH = 24
+
+
+class Settings(BaseSettings):
+    # extra="ignore": the .env is shared with the LiteLLM container (e.g.
+    # ANTHROPIC_API_KEY), so tolerate keys this model doesn't own instead of
+    # crashing at startup.
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="SEDIMENT_",
+        extra="ignore",
+        hide_input_in_errors=True,
+    )
+
+    # Tenancy: the org every fact is stamped with. Required — no
+    # default — and normalized at construction, so a missing or invalid
+    # SEDIMENT_ORG_ID fails the boot and two case-variant configs converge
+    # on the same tenant.
+    org_id: str
+
+    # PostgreSQL is the sole active fact store. SecretStr prevents settings
+    # representations and validation diagnostics from echoing credentials.
+    database_url: SecretStr
+
+    # Raw git substrate: base dir for the per-(org, repo) bare mirrors.
+    # None (unset) disables mirror refresh entirely — facts still flow;
+    # the mirror is best-effort substrate (ADR 0001).
+    mirror_path: str | None = None
+    # Clone-host allowlist for the mirror's clone_url confinement, JSON in
+    # the env (SEDIMENT_ALLOWED_CLONE_HOSTS='["github.com"]'). Empty = any
+    # public host. An explicit entry trusts that host, including private
+    # addresses; production still refuses file: URLs.
+    allowed_clone_hosts: list[str] = []
+
+    # Auth
+    api_bearer_token: str = Field(default="", repr=False)
+    operator_token: SecretStr = SecretStr("")
+    ingest_tokens: Annotated[dict[str, SecretStr], NoDecode] = Field(
+        default_factory=dict
+    )
+    github_webhook_secret: str = Field(default="changeme", repr=False)
+
+    # Trusted provider namespace, never derived from webhook headers or URLs.
+    github_host: ForgeHost = "github.com"
+
+    # Fail-closed escape hatch. False (the production default) means
+    # validate_production_security() enforces real secrets; set
+    # SEDIMENT_DEV_MODE=true ONLY for local dev, where the "changeme"
+    # defaults are intentionally tolerated.
+    dev_mode: bool = False
+
+    enable_docs: bool = True
+
+    @field_validator("org_id")
+    @classmethod
+    def _canonical_org(cls, v: str) -> str:
+        return normalize_org_id(v)
+
+    @field_validator("database_url")
+    @classmethod
+    def _strip_database_url(cls, v: SecretStr) -> SecretStr:
+        # A mounted/piped secret often arrives with a trailing newline (see
+        # _strip_secret); rstrip only \r/\n so a percent-encoded space in the
+        # password survives. Reject empty-after-trim so the boot fails fast
+        # at construction with a named-setting message instead of after a
+        # ~30 s retry in lifespan against a newline-corrupted target.
+        cleaned = v.get_secret_value().rstrip("\r\n")
+        if not cleaned:
+            raise ValueError(
+                "database_url is unset or empty; set SEDIMENT_DATABASE_URL "
+                "to a migrated PostgreSQL database."
+            )
+        return SecretStr(cleaned)
+
+    @field_validator("api_bearer_token", "github_webhook_secret")
+    @classmethod
+    def _strip_secret(cls, v: str) -> str:
+        # A mounted/piped secret often arrives with a trailing newline;
+        # stored verbatim it can never match what a client sends, and a
+        # whitespace-only value would sail past the insecure-default check.
+        return v.strip()
+
+    @field_validator("operator_token")
+    @classmethod
+    def _strip_operator_token(cls, value: SecretStr) -> SecretStr:
+        return SecretStr(value.get_secret_value().strip())
+
+    @field_validator("ingest_tokens", mode="before")
+    @classmethod
+    def _parse_ingest_tokens(cls, value):
+        def unique_pairs(pairs):
+            result = {}
+            for key, secret in pairs:
+                if key in result:
+                    raise ValueError(
+                        "ingest_tokens contains duplicate client identifiers"
+                    )
+                result[key] = secret
+            return result
+
+        if isinstance(value, str):
+            try:
+                value = json.loads(value, object_pairs_hook=unique_pairs)
+            except (ValueError, RecursionError):
+                raise ValueError(
+                    "ingest_tokens must be a JSON object with unique client identifiers"
+                ) from None
+        if not isinstance(value, dict):
+            raise ValueError("ingest_tokens must map client identifiers to secrets")
+        normalized = {}
+        for client_id, secret in value.items():
+            if (
+                not isinstance(client_id, str)
+                or not _CLIENT_ID.fullmatch(client_id)
+                or client_id in {"operator", "legacy"}
+            ):
+                raise ValueError(
+                    "ingest_tokens contains an invalid or reserved client identifier"
+                )
+            if isinstance(secret, SecretStr):
+                secret = secret.get_secret_value()
+            if not isinstance(secret, str):
+                raise ValueError("ingest_tokens must map client identifiers to secrets")
+            normalized[client_id] = SecretStr(secret.strip())
+        return normalized
+
+    def validate_production_security(self) -> list[str]:
+        """Return human-readable security problems for a production boot.
+
+        Pure: no I/O, no logging, never echoes a configured secret value. The
+        caller (main.py) is responsible for raising. Returns ``[]`` when
+        ``dev_mode`` is True (local dev opts out of the check).
+        """
+        if self.dev_mode:
+            return []
+
+        problems: list[str] = []
+        operator = self.operator_token.get_secret_value()
+        ingest = [secret.get_secret_value() for secret in self.ingest_tokens.values()]
+        if self.api_bearer_token:
+            ingest.append(self.api_bearer_token)
+        if (
+            operator.lower() in _INSECURE_DEFAULTS
+            or len(operator) < _MIN_SECRET_LENGTH
+            or any(not 33 <= ord(c) <= 126 for c in operator)
+        ):
+            problems.append(
+                "operator_token is unset, invalid, or shorter than "
+                f"{_MIN_SECRET_LENGTH} characters; set SEDIMENT_OPERATOR_TOKEN to a "
+                "strong secret."
+            )
+        if not ingest:
+            problems.append(
+                "ingest credentials are unset; set SEDIMENT_INGEST_TOKENS or the ingest-only api_bearer_token (SEDIMENT_API_BEARER_TOKEN)."
+            )
+        if any(
+            secret.lower() in _INSECURE_DEFAULTS
+            or len(secret) < _MIN_SECRET_LENGTH
+            or any(not 33 <= ord(c) <= 126 for c in secret)
+            for secret in ingest
+        ):
+            problems.append(
+                "ingest_tokens or api_bearer_token contains an empty, invalid, or "
+                f"shorter-than-{_MIN_SECRET_LENGTH}-character secret; configure real "
+                "ingest credentials."
+            )
+        if len(ingest) != len(set(ingest)) or operator in ingest:
+            problems.append(
+                "operator and ingest credentials must be distinct; duplicate secrets are not allowed."
+            )
+        if (
+            self.github_webhook_secret.lower() in _INSECURE_DEFAULTS
+            or len(self.github_webhook_secret) < _MIN_SECRET_LENGTH
+        ):
+            problems.append(
+                "github_webhook_secret is unset, invalid, or shorter than "
+                f"{_MIN_SECRET_LENGTH} characters; set SEDIMENT_GITHUB_WEBHOOK_SECRET "
+                "to a strong secret."
+            )
+        return problems
+
+    def config_warnings(self) -> list[str]:
+        """Advisory (non-fatal) posture warnings for a production boot. Pure:
+        no I/O, no logging. main.py logs each at WARNING. Unlike
+        validate_production_security(), these never block the boot."""
+        warnings: list[str] = []
+        # Mirror mode enforces clone-URL confinement outside dev mode, but an
+        # empty allowlist still admits any *public* host a valid-signature
+        # webhook names (internal/private hosts and file: URLs stay refused).
+        # Surface the open posture at boot so an operator chose it knowingly.
+        if not self.dev_mode and self.mirror_path and not self.allowed_clone_hosts:
+            warnings.append(
+                "SEDIMENT_MIRROR_PATH is set with an empty "
+                "SEDIMENT_ALLOWED_CLONE_HOSTS: any public host a valid-signature "
+                "webhook names will be fetched (internal/private hosts and file: "
+                "URLs are still refused). Set SEDIMENT_ALLOWED_CLONE_HOSTS to your "
+                'forge host(s) to close this, e.g. ["github.com"].'
+            )
+        return warnings
+
+
+settings = Settings()

sediment_api/database.py

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""PostgreSQL composition helpers for one-shot operator processes."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from sediment_core import FactStore
+from sediment_core.postgres_engine import (
+    create_postgres_engine,
+    database_operation_error,
+)
+from sqlalchemy.exc import SQLAlchemyError
+
+
+def add_database_url_argument(parser: argparse.ArgumentParser) -> None:
+    """Add the direct-store PostgreSQL setting to an operator parser."""
+    parser.add_argument(
+        "--database-url",
+        default=os.environ.get("SEDIMENT_DATABASE_URL"),
+        help="PostgreSQL URL (default: $SEDIMENT_DATABASE_URL)",
+    )
+
+
+@contextmanager
+def one_shot_fact_store(
+    database_url: str | None, *, operation: str
+) -> Iterator[FactStore]:
+    """Own and dispose one bounded engine for a one-shot process."""
+    if not database_url:
+        raise ValueError("set SEDIMENT_DATABASE_URL or pass --database-url")
+    engine = None
+    try:
+        engine = create_postgres_engine(database_url)
+        yield FactStore(engine)
+    except SQLAlchemyError:
+        raise database_operation_error(operation, database_url) from None
+    finally:
+        if engine is not None:
+            engine.dispose()

sediment_api/deps.py

@@ -0,0 +1,191 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""
+Shared API plumbing: auth at the two door types and the fact store.
+
+The bearer check and the GitHub "read raw body, verify HMAC, parse JSON"
+step live here once instead of being copied into each router. No org
+derivation lives here or anywhere: every route stamps facts with the
+configured ``settings.org_id``. Query parameters and payload owners cannot
+override deployment tenancy.
+"""
+
+from __future__ import annotations
+
+import json
+import secrets
+from dataclasses import dataclass
+from typing import Literal
+from typing import Any
+
+from fastapi import Depends, Header, HTTPException, Request
+from sediment_capture import verify_signature
+from sediment_core import FactStore
+
+from .config import settings
+
+# The app-wide request-body ceiling, enforced for every door by
+# BodySizeLimitMiddleware. 25 MB because GitHub caps webhook payloads
+# there and refuses to deliver anything larger, and no other door has a
+# legitimate payload anywhere near it. It is a ceiling on a pre-auth
+# allocation, not a tuning parameter — FastAPI reads an envelope route's
+# body before its auth dependency runs, so every door's read is pre-auth.
+# ponytail: fixed constant; make it a setting only if a non-GitHub forge needs it
+MAX_BODY_BYTES = 25 * 1024 * 1024
+
+
+class BodySizeLimitMiddleware:
+    """Bound every request-body read at ``MAX_BODY_BYTES`` (413 past it).
+
+    Pure ASGI, wrapping ``receive``: the running byte total is the only
+    trustworthy number (Content-Length is absent under chunked encoding and
+    attacker-supplied otherwise), and raising during the read stops the
+    allocation at the ceiling instead of after it. The HTTPException
+    surfaces inside whichever handler frame awaited the body — FastAPI's
+    envelope read, ``request.json()``, or ``_read_body_capped``'s stream
+    loop — where the exception middleware turns it into the 413 response.
+
+    One guard for every door, including routers added later — the per-door
+    alternative is how the envelope doors (gateway, vendor CI) ended up
+    uncapped while the webhook door was bounded.
+    """
+
+    def __init__(self, app: Any) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        received = 0
+
+        async def capped_receive() -> Any:
+            nonlocal received
+            message = await receive()
+            if message["type"] == "http.request":
+                received += len(message.get("body", b""))
+                # Module-global lookup on purpose: tests lower the cap by
+                # patching MAX_BODY_BYTES after the app is constructed.
+                if received > MAX_BODY_BYTES:
+                    raise HTTPException(
+                        status_code=413, detail="request body too large"
+                    )
+            return message
+
+        await self.app(scope, capped_receive, send)
+
+
+@dataclass(frozen=True)
+class CredentialIdentity:
+    """Configured authority only; never a tenant or captured developer identity."""
+
+    authority: Literal["ingest", "operator"]
+    client_id: str
+
+
+def verify_token(authorization: str | None = Header(None)) -> CredentialIdentity:
+    """Authenticate either fixed authority without logging credential material."""
+    scheme, _, credential = (authorization or "").partition(" ")
+    credential = credential.strip()
+    if scheme.lower() != "bearer" or not credential:
+        raise HTTPException(status_code=401, detail="Invalid token")
+    supplied = credential.encode()
+    identity = None
+    candidates = [
+        (
+            settings.operator_token.get_secret_value(),
+            CredentialIdentity("operator", "operator"),
+        ),
+        (settings.api_bearer_token, CredentialIdentity("ingest", "legacy")),
+        *(
+            (token.get_secret_value(), CredentialIdentity("ingest", client_id))
+            for client_id, token in settings.ingest_tokens.items()
+        ),
+    ]
+    for token, candidate in candidates:
+        if token and secrets.compare_digest(supplied, token.encode()):
+            identity = candidate
+    if identity is None:
+        raise HTTPException(status_code=401, detail="Invalid token")
+    return identity
+
+
+def verify_ingest_token(
+    identity: CredentialIdentity = Depends(verify_token),
+) -> CredentialIdentity:
+    """Capture accepts ingest clients and explicit operator demonstrations."""
+    return identity
+
+
+def verify_operator_token(
+    identity: CredentialIdentity = Depends(verify_token),
+) -> CredentialIdentity:
+    """Read and inspection routes require operator authority."""
+    if identity.authority != "operator":
+        raise HTTPException(status_code=403, detail="Operator authority required")
+    return identity
+
+
+def get_store(request: Request) -> FactStore:
+    """Borrow the lifespan-owned PostgreSQL fact store for one request."""
+    return request.app.state.fact_store
+
+
+async def _read_body_capped(request: Request, limit: int) -> bytearray:
+    """Buffer the request body, refusing anything over ``limit`` bytes (413).
+
+    ``request.body()`` reads the stream to completion with no cap, and the
+    HMAC check below can only run *after* the body is in hand — so an
+    unauthenticated caller would otherwise choose how much memory this
+    allocates. Streaming stops at the ceiling instead of after it.
+
+    Content-Length is deliberately not consulted: it is absent under chunked
+    encoding and attacker-supplied otherwise. The running total is the only
+    number that can be trusted.
+
+    Accumulating into one ``bytearray`` rather than a chunk list plus
+    ``b"".join`` keeps peak memory at the ceiling instead of twice it: the
+    join holds both the chunks and the joined copy alive at once (measured
+    2.00x vs 1.01x of the limit). Halving the cap would not substitute —
+    the doubling is what makes the ceiling unenforceable. The bytearray is
+    returned as-is for the same reason; ``bytes()`` here would reintroduce
+    the copy. Both consumers (``verify_signature``, ``json.loads``) take
+    bytes-like and produce identical results either way.
+    """
+    buf = bytearray()
+    async for chunk in request.stream():
+        if len(buf) + len(chunk) > limit:
+            raise HTTPException(status_code=413, detail="request body too large")
+        buf.extend(chunk)
+    return buf
+
+
+async def read_verified_webhook(
+    request: Request, signature: str | None
+) -> dict[str, Any]:
+    """Read the raw body, verify its GitHub HMAC signature, return parsed JSON.
+
+    Raises 401 if the signature is missing or invalid (an unsigned request
+    is unauthenticated, not a schema error). This is the one place webhook
+    auth is enforced for every GitHub webhook endpoint — and, because the
+    body must be read before it can be authenticated, the one place the
+    pre-auth read is bounded.
+    """
+    body_bytes = await _read_body_capped(request, MAX_BODY_BYTES)
+    if not verify_signature(
+        body_bytes, signature or "", settings.github_webhook_secret
+    ):
+        raise HTTPException(status_code=401, detail="Invalid webhook signature")
+    try:
+        payload = json.loads(body_bytes)
+    except (ValueError, RecursionError):
+        # Fail-soft on any malformed body from an authenticated caller:
+        # JSONDecodeError and UnicodeDecodeError (non-UTF-8 bytes) are both
+        # ValueError; deeply nested JSON raises RecursionError. None of them
+        # may 500 — they're a bad request (400 below), not a server fault.
+        payload = None
+    if not isinstance(payload, dict):
+        # Signature-valid but not a JSON object: an authenticated caller sent
+        # a malformed body. 400, not 500 — and not 401, the HMAC passed.
+        raise HTTPException(status_code=400, detail="invalid JSON body")
+    return payload

sediment_api/main.py

@@ -0,0 +1,212 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Sediment ingest API — FastAPI entry point."""
+
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from sediment_core import FactStore, RepositoryIdentityConflict
+from sediment_core.postgres_engine import (
+    DatabaseOperationError,
+    DatabaseURLValidationError,
+    create_postgres_engine,
+    database_operation_error,
+    sanitized_database_target,
+    verify_minimum_server_version,
+    wait_for_database,
+)
+from sediment_core.postgres_migrations import (
+    HEAD_REVISION,
+    RevisionState,
+    inspect_engine_revision,
+)
+from sediment_core.postgres_roles import validate_runtime_privileges
+from sqlalchemy.exc import (
+    DisconnectionError,
+    InterfaceError,
+    OperationalError,
+    SQLAlchemyError,
+    TimeoutError as SQLAlchemyTimeoutError,
+)
+
+from . import __version__
+from .config import settings
+from .deps import BodySizeLimitMiddleware
+from .routers import ci_vendor, forge, gateway, otlp, query, reports, v1
+from .workers import WorkerSupervisor
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(name)s %(levelname)s %(message)s",
+)
+logger = logging.getLogger("sediment.api")
+
+# Fail closed: refuse to construct the app with default/empty secrets.
+# SEDIMENT_DEV_MODE=true opts out (local dev only). The message names each
+# offending setting but never its value. A missing or invalid
+# SEDIMENT_ORG_ID already failed the boot at Settings() construction.
+_security_problems = settings.validate_production_security()
+if _security_problems:
+    _enumerated = "\n".join(f"  - {p}" for p in _security_problems)
+    raise RuntimeError(
+        "Refusing to start: insecure configuration detected.\n"
+        f"{_enumerated}\n"
+        "Set the named SEDIMENT_* environment variables to real values, or set "
+        "SEDIMENT_DEV_MODE=true for local development only."
+    )
+
+# Advisory posture warnings (non-fatal): open mirror allowlist, etc. Logged,
+# never raised — the operator may have chosen the posture deliberately.
+for _warning in settings.config_warnings():
+    logger.warning("config_warning: %s", _warning)
+
+
+@asynccontextmanager
+async def lifespan(application: FastAPI):
+    """Own one PostgreSQL engine and verify the exact schema before traffic."""
+    database_url = settings.database_url.get_secret_value()
+    engine = None
+    workers = None
+    try:
+        engine = create_postgres_engine(database_url, api_work=True)
+        wait_for_database(engine)
+        with engine.connect() as connection:
+            verify_minimum_server_version(connection)
+        inspection = inspect_engine_revision(engine)
+        if inspection.state is not RevisionState.AT_HEAD:
+            raise DatabaseOperationError(
+                "verify database schema failed for "
+                f"{sanitized_database_target(database_url)}: expected "
+                f"{HEAD_REVISION}, found {inspection.state.value}"
+            )
+        if not settings.dev_mode:
+            validate_runtime_privileges(engine)
+        application.state.database_engine = engine
+        application.state.fact_store = FactStore(engine)
+        application.state.database_target = sanitized_database_target(database_url)
+        workers = WorkerSupervisor()
+        application.state.workers = workers
+        yield
+    except (DatabaseOperationError, DatabaseURLValidationError):
+        raise
+    except Exception:
+        raise database_operation_error(
+            "verify database startup", database_url
+        ) from None
+    finally:
+        if workers is not None:
+            await workers.close()
+        if engine is not None:
+            engine.dispose()
+
+
+# enable_docs=False must close the whole schema surface: docs_url alone
+# leaves /redoc and /openapi.json publicly served.
+app = FastAPI(
+    title="Sediment API",
+    version=__version__,
+    description="Self-hosted ingest: facts in through three doors (ADR 0001)",
+    docs_url="/docs" if settings.enable_docs else None,
+    redoc_url="/redoc" if settings.enable_docs else None,
+    openapi_url="/openapi.json" if settings.enable_docs else None,
+    lifespan=lifespan,
+)
+
+# Every door's body read is bounded — see the class docstring.
+app.add_middleware(BodySizeLimitMiddleware)
+
+
+@app.exception_handler(SQLAlchemyError)
+async def database_error_response(
+    request: Request, exc: SQLAlchemyError
+) -> JSONResponse:
+    """Return a stable response without exposing driver diagnostics."""
+    target = getattr(request.app.state, "database_target", "configured database")
+    if isinstance(
+        exc,
+        (
+            DisconnectionError,
+            InterfaceError,
+            OperationalError,
+            SQLAlchemyTimeoutError,
+        ),
+    ):
+        logger.error("database_unavailable target=%s", target)
+        return JSONResponse(
+            status_code=503,
+            content={
+                "detail": {
+                    "code": "database_unavailable",
+                    "message": "PostgreSQL fact store unavailable",
+                }
+            },
+        )
+    logger.error("database_operation_failed target=%s", target)
+    return JSONResponse(
+        status_code=500,
+        content={
+            "detail": {
+                "code": "database_operation_failed",
+                "message": "PostgreSQL fact store operation failed",
+            }
+        },
+    )
+
+
+@app.exception_handler(RepositoryIdentityConflict)
+async def repository_identity_conflict_response(
+    request: Request, exc: RepositoryIdentityConflict
+) -> JSONResponse:
+    """Conflicting receipts cannot disclose retained evidence or acknowledge it."""
+    logger.warning("repository_identity_conflict")
+    return JSONResponse(
+        status_code=409,
+        content={
+            "detail": {
+                "code": "repository_identity_conflict",
+                "message": "Repository identity conflicts with retained evidence",
+            }
+        },
+    )
+
+
+@app.exception_handler(RequestValidationError)
+async def validation_error_without_input(
+    request: Request, exc: RequestValidationError
+) -> JSONResponse:
+    """422 that names the failing field but never echoes the input.
+
+    FastAPI's default handler serializes each error's ``input`` through
+    ``jsonable_encoder``, which recurses until the stack gives out on a
+    deeply nested body — a 6 KB request became a 500, and AGENTS.md §API
+    Conventions says malformed bodies from authenticated callers are
+    400/422, never 500. type/loc/msg are what a caller needs to fix the
+    request; the offending input is theirs already.
+    """
+    detail = [
+        {"type": e.get("type", ""), "loc": e.get("loc", ()), "msg": e.get("msg", "")}
+        for e in exc.errors()
+    ]
+    return JSONResponse(status_code=422, content={"detail": detail})
+
+
+app.include_router(gateway.router, prefix="/ingest")
+# The GitHub webhook door is grouped by source: auth (HMAC vs bearer) and
+# payload shape are per-source, and the plain names belong to the
+# vendor-neutral doors — /ingest/ci is ci_vendor's, and /ingest/push stays
+# free for a vendor-neutral push door later.
+app.include_router(forge.router, prefix="/ingest/github")
+app.include_router(ci_vendor.router, prefix="/ingest")
+# OTLP receiver: path fixed by the exporter (<endpoint>/v1/logs), no prefix.
+app.include_router(otlp.router)
+app.include_router(query.router, prefix="/query")
+# Read-only v1 surfaces: remote CLI probes and bounded operational reports.
+app.include_router(v1.router, prefix="/v1")
+app.include_router(reports.router, prefix="/v1/reports")
+
+
+@app.get("/health")
+async def health() -> dict:
+    return {"status": "ok", "version": app.version}