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):

apps/api/tests/unit/test_db_viewer.py

@@ -0,0 +1,207 @@
+"""Settings -> Database viewer: mint (admin-gated) -> bootstrap (token ->
+session cookie) -> verify (cookie -> live is_admin check) round trip.
+
+Cookies are extracted from Set-Cookie headers and passed explicitly on
+follow-up requests rather than relying on TestClient's cookie jar - the
+session cookie is marked Secure, and TestClient's base_url is plain http,
+so a real cookie jar wouldn't resend it anyway."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime, timedelta
+
+import jwt
+from fastapi.testclient import TestClient
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.config import get_settings
+from app.repositories.user_repository import UserRepository
+
+
+def _unique_email() -> str:
+    return f"user-{uuid.uuid4().hex[:12]}@example.com"
+
+
+async def _register_admin_and_login(client: TestClient, db_session: AsyncSession) -> dict[str, str]:
+    email = f"admin-{uuid.uuid4().hex[:12]}@example.com"
+    client.post(
+        "/api/v1/auth/register",
+        json={"email": email, "password": "correct-horse-1", "display_name": "Admin"},
+    )
+    user = await UserRepository(db_session).get_by_email(email)
+    user.is_admin = True
+    await db_session.commit()
+    tokens = client.post(
+        "/api/v1/auth/login", json={"email": email, "password": "correct-horse-1"}
+    ).json()
+    return {"Authorization": f"Bearer {tokens['access_token']}"}
+
+
+async def _register_non_admin_and_login(client: TestClient) -> dict[str, str]:
+    email = _unique_email()
+    client.post(
+        "/api/v1/auth/register",
+        json={"email": email, "password": "correct-horse-1", "display_name": "T"},
+    )
+    tokens = client.post(
+        "/api/v1/auth/login", json={"email": email, "password": "correct-horse-1"}
+    ).json()
+    return {"Authorization": f"Bearer {tokens['access_token']}"}
+
+
+def _extract_cookie(set_cookie_header: str) -> tuple[str, str]:
+    first_pair = set_cookie_header.split(";", 1)[0]
+    name, value = first_pair.split("=", 1)
+    return name, value
+
+
+# --- /db-viewer/session (mint) --------------------------------------------
+
+
+def test_create_session_requires_auth(client: TestClient):
+    resp = client.post("/api/v1/db-viewer/session")
+    assert resp.status_code == 401
+
+
+async def test_create_session_non_admin_forbidden(client: TestClient):
+    headers = await _register_non_admin_and_login(client)
+    resp = client.post("/api/v1/db-viewer/session", headers=headers)
+    assert resp.status_code == 403
+
+
+async def test_admin_can_mint_a_bootstrap_token(client: TestClient, db_session: AsyncSession):
+    headers = await _register_admin_and_login(client, db_session)
+    resp = client.post("/api/v1/db-viewer/session", headers=headers)
+    assert resp.status_code == 200
+    assert resp.json()["token"]
+
+
+async def test_minting_a_session_is_logged_to_the_admins_account_activity(
+    client: TestClient, db_session: AsyncSession
+):
+    headers = await _register_admin_and_login(client, db_session)
+    client.post("/api/v1/db-viewer/session", headers=headers)
+
+    events = client.get("/api/v1/auth/security-events", headers=headers).json()
+    assert any(e["event_type"] == "db_viewer_session_created" for e in events)
+
+
+# --- /db-viewer/bootstrap (token -> cookie) -------------------------------
+
+
+async def test_bootstrap_with_a_valid_token_sets_a_session_cookie_and_redirects(
+    client: TestClient, db_session: AsyncSession
+):
+    headers = await _register_admin_and_login(client, db_session)
+    token = client.post("/api/v1/db-viewer/session", headers=headers).json()["token"]
+
+    resp = client.get(
+        "/api/v1/db-viewer/bootstrap", params={"token": token}, follow_redirects=False
+    )
+    assert resp.status_code == 302
+    assert resp.headers["location"] == "/"
+    assert "db_viewer_session" in resp.headers["set-cookie"]
+    assert "HttpOnly" in resp.headers["set-cookie"]
+    assert "Secure" in resp.headers["set-cookie"]
+
+
+def test_bootstrap_rejects_a_garbage_token(client: TestClient):
+    resp = client.get(
+        "/api/v1/db-viewer/bootstrap", params={"token": "not-a-real-token"}, follow_redirects=False
+    )
+    assert resp.status_code == 403
+
+
+def test_bootstrap_rejects_an_expired_token(client: TestClient):
+    settings = get_settings()
+    now = datetime.now(UTC)
+    expired_token = jwt.encode(
+        {
+            "sub": str(uuid.uuid4()),
+            "type": "db_viewer_bootstrap",
+            "iat": now - timedelta(minutes=10),
+            "exp": now - timedelta(minutes=5),
+            "jti": "x",
+        },
+        settings.jwt_secret,
+        algorithm="HS256",
+    )
+    resp = client.get(
+        "/api/v1/db-viewer/bootstrap", params={"token": expired_token}, follow_redirects=False
+    )
+    assert resp.status_code == 403
+
+
+def test_bootstrap_rejects_a_session_type_token_used_as_a_bootstrap_token(client: TestClient):
+    """Type confusion guard: a DB_VIEWER_SESSION token must not work as a
+    DB_VIEWER_BOOTSTRAP token, even though both are signed with the same
+    jwt_secret."""
+    settings = get_settings()
+    now = datetime.now(UTC)
+    session_typed_token = jwt.encode(
+        {
+            "sub": str(uuid.uuid4()),
+            "type": "db_viewer_session",
+            "iat": now,
+            "exp": now + timedelta(minutes=2),
+            "jti": "x",
+        },
+        settings.jwt_secret,
+        algorithm="HS256",
+    )
+    resp = client.get(
+        "/api/v1/db-viewer/bootstrap",
+        params={"token": session_typed_token},
+        follow_redirects=False,
+    )
+    assert resp.status_code == 403
+
+
+# --- /db-viewer/verify (cookie -> live is_admin check) --------------------
+
+
+async def test_verify_succeeds_for_a_live_admin_with_a_valid_session_cookie(
+    client: TestClient, db_session: AsyncSession
+):
+    headers = await _register_admin_and_login(client, db_session)
+    token = client.post("/api/v1/db-viewer/session", headers=headers).json()["token"]
+    bootstrap_resp = client.get(
+        "/api/v1/db-viewer/bootstrap", params={"token": token}, follow_redirects=False
+    )
+    cookie_name, cookie_value = _extract_cookie(bootstrap_resp.headers["set-cookie"])
+
+    verify_resp = client.get("/api/v1/db-viewer/verify", cookies={cookie_name: cookie_value})
+    assert verify_resp.status_code == 200
+
+
+def test_verify_rejects_a_missing_cookie(client: TestClient):
+    resp = client.get("/api/v1/db-viewer/verify")
+    assert resp.status_code == 401
+
+
+async def test_verify_rejects_a_session_cookie_once_admin_is_revoked(
+    client: TestClient, db_session: AsyncSession
+):
+    headers = await _register_admin_and_login(client, db_session)
+    token = client.post("/api/v1/db-viewer/session", headers=headers).json()["token"]
+    bootstrap_resp = client.get(
+        "/api/v1/db-viewer/bootstrap", params={"token": token}, follow_redirects=False
+    )
+    cookie_name, cookie_value = _extract_cookie(bootstrap_resp.headers["set-cookie"])
+
+    # Sanity: still works before revocation.
+    assert (
+        client.get("/api/v1/db-viewer/verify", cookies={cookie_name: cookie_value}).status_code
+        == 200
+    )
+
+    admin_email_resp = client.get("/api/v1/auth/me", headers=headers)
+    admin = await UserRepository(db_session).get_by_email(admin_email_resp.json()["email"])
+    admin.is_admin = False
+    await db_session.commit()
+
+    assert (
+        client.get("/api/v1/db-viewer/verify", cookies={cookie_name: cookie_value}).status_code
+        == 401
+    )

apps/web/app/(app)/settings/page.tsx

@@ -5,6 +5,7 @@ import { useState } from "react";
 import {
   Bell,
   CheckCircle2,
+  Database,
   KeyRound,
   Loader2,
   Mail,
@@ -24,6 +25,7 @@ import {
 import { authErrorMessage } from "@/hooks/use-auth";
 import {
   useAcceptUnbanRequest,
+  useCreateDbViewerSession,
   useCreateIpBan,
   useCurrentUser,
   useDeleteIpBan,
@@ -48,6 +50,7 @@ import { FormField } from "@/components/ui/form-field";
 import { Select } from "@/components/ui/select";
 import { SystemSecretRow } from "@/components/ui/system-secret-row";
 import { UserApiKeyRow } from "@/components/ui/user-api-key-row";
+import { isLocalConvenience } from "@/lib/auth";
 import { formatDateTime } from "@/lib/format";
 import {
   SEVERITY_LABELS,
@@ -663,6 +666,60 @@ function IpBansBox() {
   );
 }
 
+function DatabaseViewerBox() {
+  const { data: systemStatus } = useSystemStatus();
+  const createSession = useCreateDbViewerSession();
+  const [error, setError] = useState<string | null>(null);
+  const isLocal = systemStatus ? isLocalConvenience(systemStatus) : false;
+  const dbViewerUrl = process.env.NEXT_PUBLIC_DB_VIEWER_URL;
+
+  const handleOpen = async () => {
+    setError(null);
+    try {
+      const { token } = await createSession.mutateAsync();
+      window.open(`${dbViewerUrl}/_auth?token=${encodeURIComponent(token)}`, "_blank", "noopener,noreferrer");
+    } catch {
+      setError("Couldn't open the database viewer. Try again.");
+    }
+  };
+
+  return (
+    <div className="rounded-lg border border-slate-200 bg-white p-6">
+      <div className="flex items-center gap-2 text-sm font-semibold text-slate-700">
+        <Database className="h-4 w-4" aria-hidden /> Database
+      </div>
+      <p className="mt-1 text-sm text-slate-500">
+        Open a web-based Postgres client (Adminer) in a new tab to view and edit rows directly.
+        Local developers and server admins only.
+      </p>
+
+      <div className="mt-4">
+        {isLocal ? (
+          <a
+            href="http://localhost:8081"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="focus-ring inline-flex items-center gap-1.5 rounded-md bg-slate-800 px-3 py-1.5 text-xs font-semibold text-white transition-colors duration-200 hover:bg-slate-900"
+          >
+            <Database className="h-3.5 w-3.5" aria-hidden /> Open database viewer
+          </a>
+        ) : dbViewerUrl ? (
+          <ActionButton
+            onClick={handleOpen}
+            pending={createSession.isPending}
+            colorClass="bg-slate-800 hover:bg-slate-900"
+            icon={Database}
+            label="Open database viewer"
+          />
+        ) : (
+          <p className="text-sm text-slate-500">Not configured for this deployment.</p>
+        )}
+        {error && <p className="mt-2 text-xs text-red-600">{error}</p>}
+      </div>
+    </div>
+  );
+}
+
 export default function SettingsPage() {
   const { data: user } = useCurrentUser();
   const { data: systemStatus } = useSystemStatus();
@@ -759,6 +816,7 @@ export default function SettingsPage() {
         <>
           <ServerSecretsBox />
           <IpBansBox />
+          <DatabaseViewerBox />
           <LoggingBox />
         </>
       )}

apps/web/hooks/use-auth.ts

@@ -47,6 +47,12 @@ export function useSetSystemSecret() {
   });
 }
 
+export function useCreateDbViewerSession() {
+  return useMutation({
+    mutationFn: () => api.createDbViewerSession(),
+  });
+}
+
 export function useSystemLogs() {
   return useQuery({
     queryKey: ["system-logs"],

apps/web/lib/api-client.ts

@@ -11,6 +11,7 @@ import type {
   CompanyUpdatePayload,
   ConfirmPasswordResetPayload,
   DashboardAnalytics,
+  DbViewerSessionResponse,
   DiscoverCompanyRequest,
   DiscoveredCompanyProfile,
   IpBan,
@@ -166,6 +167,9 @@ export const api = {
 
   listSystemSecrets: () => request<SystemSecretStatus[]>("/api/v1/system/secrets"),
 
+  createDbViewerSession: () =>
+    request<DbViewerSessionResponse>("/api/v1/db-viewer/session", { method: "POST" }),
+
   setSystemSecret: (key: string, payload: SetSystemSecretPayload) =>
     request<SystemSecretStatus>(`/api/v1/system/secrets/${key}`, {
       method: "PUT",

apps/web/lib/types.ts

@@ -29,6 +29,10 @@ export interface SystemSecretStatus {
   value: string | null;
 }
 
+export interface DbViewerSessionResponse {
+  token: string;
+}
+
 export interface SetSystemSecretPayload {
   value: string;
 }

apps/web/tests/settings-database-viewer.test.tsx

@@ -0,0 +1,100 @@
+import { screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import SettingsPage from "@/app/(app)/settings/page";
+import { renderWithQueryClient } from "./test-utils";
+
+const ADMIN_USER = {
+  id: "user-1",
+  email: "[email protected]",
+  display_name: "Admin",
+  timezone: "America/New_York",
+  is_active: true,
+  is_admin: true,
+  auth_mode: "jwt",
+};
+
+function systemStatusBody(isLocalhost: boolean, authMode: "local" | "jwt") {
+  return {
+    app_env: "development",
+    auth_mode: authMode,
+    llm_provider: "mock",
+    search_provider: "mock",
+    sms_enabled: false,
+    sms_provider: "twilio",
+    ninjapear_configured: false,
+    ninjapear_credit_balance: null,
+    ninjapear_estimated_credits_per_company: null,
+    is_localhost: isLocalhost,
+    turnstile_site_key: null,
+    components: [],
+  };
+}
+
+/** Covers every endpoint SettingsPage's admin-gated boxes touch on mount -
+ * empty-list/no-op responses for everything except /system/status, which
+ * each test configures to drive the local-vs-remote branch under test. */
+function mockFetchImplementation(isLocalhost: boolean, authMode: "local" | "jwt" = "jwt") {
+  return vi.fn().mockImplementation((url: string, init?: RequestInit) => {
+    const path = url.replace("http://localhost:8000", "");
+    const ok = (json: unknown, status = 200) =>
+      Promise.resolve({ ok: true, status, json: async () => json });
+
+    if (path === "/api/v1/auth/me") return ok(ADMIN_USER);
+    if (path === "/api/v1/system/status") return ok(systemStatusBody(isLocalhost, authMode));
+    if (path === "/api/v1/notification-destinations") return ok([]);
+    if (path === "/api/v1/companies") return ok([]);
+    if (path === "/api/v1/system/logs") return ok([]);
+    if (path === "/api/v1/user-api-keys") return ok([]);
+    if (path === "/api/v1/system/secrets") return ok([]);
+    if (path === "/api/v1/auth/security-events") return ok([]);
+    if (path === "/api/v1/admin/ip-bans") return ok([]);
+    if (path === "/api/v1/admin/unban-requests") return ok([]);
+    if (path === "/api/v1/db-viewer/session" && init?.method === "POST") {
+      return ok({ token: "mock-bootstrap-token" });
+    }
+    return Promise.resolve({ ok: false, status: 404, json: async () => ({ detail: "not found" }) });
+  });
+}
+
+beforeEach(() => {
+  vi.stubEnv("NEXT_PUBLIC_DB_VIEWER_URL", "https://db.ciagent.org");
+});
+
+describe("Settings - Database viewer box", () => {
+  it("links straight to the local Adminer instance for the local-dev bypass account", async () => {
+    vi.stubGlobal("fetch", mockFetchImplementation(true, "local"));
+    renderWithQueryClient(<SettingsPage />);
+
+    const link = await screen.findByRole("link", { name: /open database viewer/i });
+    expect(link).toHaveAttribute("href", "http://localhost:8081");
+    expect(link).toHaveAttribute("target", "_blank");
+  });
+
+  it("mints a session token and opens the configured remote viewer URL for a real admin", async () => {
+    vi.stubGlobal("fetch", mockFetchImplementation(false, "jwt"));
+    const openSpy = vi.spyOn(window, "open").mockImplementation(() => null);
+    const user = userEvent.setup();
+    renderWithQueryClient(<SettingsPage />);
+
+    const button = await screen.findByRole("button", { name: /open database viewer/i });
+    await user.click(button);
+
+    await waitFor(() => {
+      expect(openSpy).toHaveBeenCalledWith(
+        "https://db.ciagent.org/_auth?token=mock-bootstrap-token",
+        "_blank",
+        "noopener,noreferrer",
+      );
+    });
+  });
+
+  it("shows a not-configured message when NEXT_PUBLIC_DB_VIEWER_URL is unset for a remote admin", async () => {
+    vi.stubEnv("NEXT_PUBLIC_DB_VIEWER_URL", "");
+    vi.stubGlobal("fetch", mockFetchImplementation(false, "jwt"));
+    renderWithQueryClient(<SettingsPage />);
+
+    expect(await screen.findByText(/not configured for this deployment/i)).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: /open database viewer/i })).not.toBeInTheDocument();
+  });
+});