cameleer-server/docs/superpowers/specs/2026-04-11-infrastructure-endpoint-visibility-design.md

# Infrastructure Endpoint Visibility

**Date:** 2026-04-11
**Status:** Approved
**Scope:** cameleer3-server + cameleer-saas

---

## Problem

The server's admin section exposes PostgreSQL and ClickHouse diagnostic
endpoints (connection strings, pool stats, active queries, table sizes, server
versions). In standalone mode this is fine -- the admin user is the platform
owner. In SaaS mode, tenant admins receive `ADMIN` role via OIDC, which grants
them access to infrastructure internals they should not see.

Worse, the current endpoints have cross-tenant data leaks in shared-infra
deployments:

- `GET /admin/database/queries` returns `pg_stat_activity` which is
  database-wide, not schema-scoped. Tenant A can see and kill Tenant B's
  queries.
- `GET /admin/clickhouse/tables`, `/performance`, `/queries` query
  `system.tables`, `system.parts`, and `system.processes` globally -- no
  `tenant_id` filtering.

## Solution

Two complementary changes:

1. **Server**: an explicit flag disables infrastructure endpoints entirely when
   the server is provisioned by the SaaS platform.
2. **SaaS**: the vendor console gains its own infrastructure dashboard that
   queries shared PostgreSQL and ClickHouse directly, with per-tenant breakdown.

---

## Part 1: Server -- Disable Infrastructure Endpoints

### New Property

```yaml
cameleer:
  server:
    security:
      infrastructureendpoints: ${CAMELEER_SERVER_SECURITY_INFRASTRUCTUREENDPOINTS:true}
```

Default `true` (standalone mode -- endpoints available as today). The SaaS
provisioner sets `false` on tenant server containers.

### Bean Removal via @ConditionalOnProperty

Add to both `DatabaseAdminController` and `ClickHouseAdminController`:

```java
@ConditionalOnProperty(
    name = "cameleer.server.security.infrastructureendpoints",
    havingValue = "true",
    matchIfMissing = true
)
```

When `false`:
- Controller beans are not registered by Spring
- Requests to `/api/v1/admin/database/**` and `/api/v1/admin/clickhouse/**`
  return **404 Not Found** (Spring's default for unmapped paths)
- Controllers do not appear in the OpenAPI spec
- No role, no interceptor, no filter -- the endpoints simply do not exist

### Health Endpoint Flag

Add `infrastructureEndpoints` boolean to the health endpoint response
(`GET /api/v1/health`). The value reflects the property. This is a public
endpoint, and the flag itself is not sensitive -- it only tells the UI whether
to render the Database/ClickHouse admin tabs.

Implementation: a custom `HealthIndicator` bean or a `@RestControllerAdvice`
that enriches the health response. The exact mechanism is an implementation
detail.

### UI Changes

`buildAdminTreeNodes()` in `sidebar-utils.ts` currently returns a static list
including Database and ClickHouse nodes. Change it to accept a parameter
(or read from a store) and omit those nodes when `infrastructureEndpoints` is
`false`.

The flag is fetched once from the health endpoint at startup (the UI already
calls health for connectivity). Store it in the auth store or a dedicated
capabilities store.

Router: the `/admin/database` and `/admin/clickhouse` routes remain defined
but are unreachable via navigation. If a user navigates directly, the API
returns 404 and the page shows its existing error state.

### Files Changed (Server)

| File | Change |
|------|--------|
| `application.yml` | Add `cameleer.server.security.infrastructureendpoints: true` |
| `DatabaseAdminController.java` | Add `@ConditionalOnProperty` annotation |
| `ClickHouseAdminController.java` | Add `@ConditionalOnProperty` annotation |
| Health response | Add `infrastructureEndpoints` boolean |
| `ui/src/components/sidebar-utils.ts` | Filter admin tree nodes based on flag |
| `ui/src/components/LayoutShell.tsx` | Fetch and pass flag |

---

## Part 2: SaaS -- Vendor Infrastructure Dashboard

### Architecture

The SaaS platform sits on the same Docker network as PostgreSQL and ClickHouse.
It already has their connection URLs in `ProvisioningProperties` (`datasourceUrl`
for cameleer3 PostgreSQL, `clickhouseUrl` for ClickHouse). It already uses raw
JDBC (`DriverManager.getConnection()`) for tenant data cleanup in
`TenantDataCleanupService`. The infrastructure dashboard uses the same pattern.

The SaaS does NOT call the server's admin endpoints. It queries the shared
infrastructure directly. This means:

- No dependency on server endpoint availability
- Cross-tenant aggregation is natural (the SaaS knows all tenants)
- Per-tenant filtering is explicit (`WHERE tenant_id = ?` for ClickHouse,
  schema-scoped queries for PostgreSQL)
- No new Logto scopes or roles needed

### Backend

**`InfrastructureService.java`** -- new service class. Raw JDBC connections
from `ProvisioningProperties.datasourceUrl()` and `.clickhouseUrl()`. Methods:

PostgreSQL:
- `getPostgresOverview()` -- server version (`SELECT version()`), total DB
  size (`pg_database_size`), active connection count (`pg_stat_activity`)
- `getPostgresTenantStats()` -- per-tenant schema sizes, table counts, row
  counts. Query `information_schema.tables` joined with `pg_stat_user_tables`
  grouped by `table_schema` where schema matches `tenant_%`
- `getPostgresTenantDetail(slug)` -- single tenant: table-level breakdown
  (name, rows, data size, index size) from `pg_stat_user_tables` filtered to
  `tenant_{slug}` schema

ClickHouse:
- `getClickHouseOverview()` -- server version, uptime (`system.metrics`),
  total disk size, total rows, compression ratio (`system.parts` aggregated)
- `getClickHouseTenantStats()` -- per-tenant row counts and disk usage. Query
  actual data tables (executions, logs, etc.) with
  `SELECT tenant_id, count(), sum(bytes) ... GROUP BY tenant_id`
- `getClickHouseTenantDetail(slug)` -- single tenant: per-table breakdown
  (table name, row count, disk size) filtered by `WHERE tenant_id = ?`

Note: ClickHouse `system.parts` does not have a `tenant_id` column (it is a
system table). Per-tenant ClickHouse stats require querying the actual data
tables. For the overview, `system.parts` provides aggregate stats across all
tenants.

**`InfrastructureController.java`** -- new REST controller at
`/api/vendor/infrastructure`. All endpoints require `platform:admin` scope
via `@PreAuthorize("hasAuthority('SCOPE_platform:admin')")`.

| Method | Path | Returns |
|--------|------|---------|
| GET | `/` | Combined PG + CH overview |
| GET | `/postgres` | PG overview + per-tenant breakdown |
| GET | `/postgres/{slug}` | Single tenant PG detail |
| GET | `/clickhouse` | CH overview + per-tenant breakdown |
| GET | `/clickhouse/{slug}` | Single tenant CH detail |

### Frontend

New vendor sidebar entry: **Infrastructure** (icon: `Server` or `Database`
from lucide-react) at `/vendor/infrastructure`.

**Page layout:**
- Two section cards: PostgreSQL and ClickHouse
- Each shows aggregate KPIs at top (version, total size, connections/queries)
- Per-tenant table below: slug, schema size / row count, disk usage
- Click tenant row to expand or navigate to detail view
- Detail view: per-table breakdown for that tenant

The page follows the existing vendor console patterns (card layout, tables,
KPI strips) using `@cameleer/design-system` components.

### SaaS Provisioner Change

`DockerTenantProvisioner.createServerContainer()` adds one env var to the
list passed to tenant server containers:

```java
env.add("CAMELEER_SERVER_SECURITY_INFRASTRUCTUREENDPOINTS=false");
```

### Files Changed (SaaS)

| File | Change |
|------|--------|
| `DockerTenantProvisioner.java` | Add env var to tenant server containers |
| `InfrastructureService.java` | New -- raw JDBC queries for PG + CH stats |
| `InfrastructureController.java` | New -- vendor-facing REST endpoints |
| `Layout.tsx` | Add Infrastructure to vendor sidebar |
| `router.tsx` | Add `/vendor/infrastructure` route |
| `InfrastructurePage.tsx` | New -- overview page with PG/CH cards |

---

## What Does NOT Change

- No new Logto scopes, roles, or API resources
- No new Spring datasource beans (raw JDBC, same as TenantDataCleanupService)
- No changes to SecurityConfig in either repo
- No changes to existing tenant admin endpoints or RBAC
- No changes to ServerApiClient (SaaS queries infra directly, not via server)
- Standalone server deployments are unaffected (flag defaults to `true`)

---

## Data Flow Summary

**Standalone mode (no SaaS):**
1. Admin user logs into server UI
2. Admin sidebar shows Database and ClickHouse tabs
3. Tabs work as today -- full infrastructure visibility

**SaaS managed mode:**
1. SaaS provisions tenant server with `INFRASTRUCTUREENDPOINTS=false`
2. Tenant admin logs into server UI via OIDC
3. Admin sidebar shows Users & Roles, OIDC, Audit, Environments -- no
   Database or ClickHouse tabs
4. Direct navigation to `/admin/database` returns 404
5. Vendor opens SaaS console -> Infrastructure page
6. SaaS queries shared PG + CH directly with per-tenant filtering
7. Vendor sees aggregate stats + per-tenant breakdown

---

## Security Properties

- **Tenant isolation**: tenant admins cannot see any infrastructure data.
  The endpoints do not exist on their server instance.
- **Cross-tenant prevention**: the SaaS infrastructure dashboard queries
  with explicit tenant filtering. No tenant can see another tenant's data.
- **Blast radius**: the flag is set at provisioning time via env var. A tenant
  admin cannot change it. Only someone with access to the Docker container
  config (platform operator) can toggle it.
- **Defense in depth**: even if the flag were somehow bypassed, the server's
  DB/CH admin endpoints expose `pg_stat_activity` and `system.processes`
  globally. The SaaS approach of querying directly with tenant filtering is
  inherently safer.