Add Settings -> Database viewer (Adminer) for local devs and any admin

Local dev gets an unauthenticated Adminer instance bound to loopback
only. In production, any account with is_admin=true can open it -
the app mints a short-lived token from a live admin session, which
Nginx's new db.ciagent.org block exchanges for a session cookie that
re-checks admin status on every request, instead of a shared static
password that wouldn't scale to multiple admins or revoke live.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

apps/api/app/api/v1/db_viewer.py

@@ -0,0 +1,128 @@
+"""Settings -> Database viewer: lets any admin open a web-based Postgres
+client (Adminer, at db.<domain>) without a separate, shared credential.
+
+The app's own JWT lives only in the browser's localStorage
+(apps/web/lib/api-client.ts) - never a cookie, never sent on a plain
+cross-subdomain navigation - so it can't gate a link to a different
+subdomain the way an in-app API call is gated. Instead: an admin mints a
+short-lived DB_VIEWER_BOOTSTRAP token from their real (live-checked) admin
+session; Nginx's db.<domain> /_auth route exchanges that, one-time, for a
+longer-lived DB_VIEWER_SESSION cookie scoped to that subdomain; Nginx's
+`auth_request` then re-validates that cookie - including a fresh `is_admin`
+check against the database - on every subsequent request. See
+infrastructure/nginx/nginx.conf's db.<domain> server block and
+DEPLOYMENT.md.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response, status
+from fastapi.responses import RedirectResponse
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth.dependencies import require_admin
+from app.core.config import Settings, get_settings
+from app.core.security import (
+    InvalidTokenError,
+    TokenType,
+    create_db_viewer_bootstrap_token,
+    create_db_viewer_session_token,
+    decode_token,
+    get_client_ip,
+)
+from app.db.session import get_db
+from app.models.enums import SecurityEventType
+from app.models.user import User
+from app.repositories.user_repository import UserRepository
+from app.repositories.user_security_event_repository import UserSecurityEventRepository
+
+router = APIRouter(prefix="/db-viewer", tags=["db-viewer"])
+
+SESSION_COOKIE_NAME = "db_viewer_session"
+
+
+class DbViewerSessionResponse(BaseModel):
+    token: str
+
+
+@router.post("/session", response_model=DbViewerSessionResponse)
+async def create_db_viewer_session(
+    request: Request,
+    settings: Settings = Depends(get_settings),
+    db: AsyncSession = Depends(get_db),
+    admin: User = Depends(require_admin),
+) -> DbViewerSessionResponse:
+    """Mints a 2-minute bootstrap token the frontend embeds in a link to
+    https://<db-viewer-host>/_auth?token=... - Nginx proxies that path
+    straight to `bootstrap` below, which exchanges it for a session cookie."""
+    token = create_db_viewer_bootstrap_token(admin.id, settings)
+    await UserSecurityEventRepository(db).create(
+        user_id=admin.id,
+        event_type=SecurityEventType.DB_VIEWER_SESSION_CREATED,
+        ip_address=get_client_ip(request, settings),
+    )
+    await db.commit()
+    return DbViewerSessionResponse(token=token)
+
+
+@router.get("/bootstrap")
+async def bootstrap_db_viewer_session(
+    token: str = Query(...),
+    settings: Settings = Depends(get_settings),
+) -> RedirectResponse:
+    """Reached only via Nginx's db.<domain> /_auth location - never called
+    directly by the frontend. No `require_admin` dependency: the bootstrap
+    token itself, freshly minted by `create_db_viewer_session` above, is the
+    credential here."""
+    try:
+        decoded = decode_token(token, settings, TokenType.DB_VIEWER_BOOTSTRAP)
+    except InvalidTokenError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Invalid or expired token"
+        ) from exc
+
+    session_token = create_db_viewer_session_token(decoded.user_id, settings)
+    response = RedirectResponse(url="/", status_code=status.HTTP_302_FOUND)
+    response.set_cookie(
+        SESSION_COOKIE_NAME,
+        session_token,
+        max_age=60 * 60,
+        httponly=True,
+        secure=True,
+        samesite="lax",
+        # No `domain=` - defaults to the exact host (db.<domain>), not
+        # shared with ciagent.org/api.ciagent.org/git.ciagent.org.
+    )
+    return response
+
+
+@router.get("/verify")
+async def verify_db_viewer_session(
+    request: Request,
+    settings: Settings = Depends(get_settings),
+    db: AsyncSession = Depends(get_db),
+) -> Response:
+    """Reached only via Nginx's `auth_request` subrequest (internal `/_verify`
+    location) - carries just the forwarded Cookie header, no Authorization.
+    Re-checks `is_admin` fresh from the database on every call, not just at
+    token-mint time, so revoking an admin takes effect on their very next
+    request here - same live-check behavior as `require_admin` elsewhere."""
+    token = request.cookies.get(SESSION_COOKIE_NAME)
+    if token is None:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="No session")
+
+    try:
+        decoded = decode_token(token, settings, TokenType.DB_VIEWER_SESSION)
+    except InvalidTokenError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid or expired session"
+        ) from exc
+
+    user = await UserRepository(db).get_by_id(decoded.user_id)
+    if user is None or not user.is_admin:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED, detail="Admin privileges required"
+        )
+
+    return Response(status_code=status.HTTP_200_OK)

apps/api/app/api/v1/router.py

@@ -11,6 +11,7 @@ from app.api.v1 import (
     auth,
     companies,
     dashboard,
+    db_viewer,
     monitoring,
     notification_destinations,
     reports,
@@ -24,6 +25,7 @@ api_v1_router = APIRouter(prefix="/api/v1")
 api_v1_router.include_router(system.router)
 api_v1_router.include_router(auth.router)
 api_v1_router.include_router(admin.router)
+api_v1_router.include_router(db_viewer.router)
 api_v1_router.include_router(user_api_keys.router)
 api_v1_router.include_router(companies.router)
 api_v1_router.include_router(notification_destinations.router)

apps/api/app/core/security.py

@@ -75,6 +75,11 @@ def verify_password(raw_password: str, password_hash: str) -> bool:
 class TokenType(StrEnum):
     ACCESS = "access"
     REFRESH = "refresh"
+    # Settings -> Database viewer: a short-lived token minted from a live
+    # admin session, exchanged (via Nginx's db.ciagent.org /_auth route) for
+    # a longer-lived DB_VIEWER_SESSION cookie. See app/api/v1/db_viewer.py.
+    DB_VIEWER_BOOTSTRAP = "db_viewer_bootstrap"
+    DB_VIEWER_SESSION = "db_viewer_session"
 
 
 @dataclass(frozen=True)
@@ -105,6 +110,14 @@ def create_refresh_token(user_id: uuid.UUID, settings: Settings) -> tuple[str, s
     return token, jti, expires_at
 
 
+def create_db_viewer_bootstrap_token(user_id: uuid.UUID, settings: Settings) -> str:
+    return _encode_token(user_id, TokenType.DB_VIEWER_BOOTSTRAP, timedelta(minutes=2), settings)
+
+
+def create_db_viewer_session_token(user_id: uuid.UUID, settings: Settings) -> str:
+    return _encode_token(user_id, TokenType.DB_VIEWER_SESSION, timedelta(minutes=60), settings)
+
+
 def _encode_token(
     user_id: uuid.UUID,
     token_type: TokenType,

apps/api/app/models/enums.py

@@ -153,6 +153,7 @@ class SecurityEventType(StrEnum):
     EMAIL_VERIFIED = "email_verified"
     SERVER_SECRET_UPDATED = "server_secret_updated"
     API_KEY_UPDATED = "api_key_updated"
+    DB_VIEWER_SESSION_CREATED = "db_viewer_session_created"
 
 
 class ApiKeyProvider(StrEnum):