cameleer-server/docs/superpowers/plans/2026-04-16-environment-scoping.md

# Environment-scoped config — fixing cross-env data bleed

**Date:** 2026-04-16
**Status:** Not started
**Backwards compatibility:** None (pre-1.0; user will wipe dev DB)

## Problem

Two PostgreSQL tables key per-app state on the application name alone, despite environments (`dev`/`staging`/`prod`) being first-class in the rest of the system:

- `application_config` PK `(application)` — traced processors, taps, route recording, per-app sensitive keys. All env-sensitive.
- `app_settings` PK `(application_id)` — SLA threshold, health warn/crit thresholds. All env-sensitive.

Consequences:

- **Config corruption**: `PUT /api/v1/config/{app}?environment=dev` correctly scopes the SSE fan-out but overwrites the single DB row, so when `prod` agents restart and fetch config they get the `dev` config.
- **Agent startup is env-blind**: `GET /api/v1/config/{app}` reads neither JWT `env` claim nor any request parameter; returns whichever row exists.
- **Dashboard settings ambiguous**: `AppSettings` endpoints have no env parameter; SLA/health displayed without env context.
- Ancillary: `ClickHouseDiagramStore.findProcessorRouteMapping(appId)` doesn't filter by env even though the table has an `environment` column.
- Ancillary: `AgentRegistrationController` accepts registrations without `environmentId` and silently defaults to `"default"` — masks misconfigured agents.

## Non-goals / working correctly (do not touch)

- All ClickHouse observability tables (executions, logs, metrics, stats_1m_*) — already env-scoped.
- `AgentCommandController` / SSE command fan-out — already env-filtered via `AgentRegistryService.findByApplicationAndEnvironment`.
- `SearchController` search path — fixed in commit `e2d9428`.
- RBAC (users/roles/groups/claim mappings) — tenant-wide by design.
- Global sensitive-keys push to all envs (`SensitiveKeysAdminController.fanOutToAllAgents`) — by design; global baseline.
- Admin UI per-page env indicator — not needed, already shown in top-right of the shell.

## Design decisions (fixed)

| Question | Answer |
|---|---|
| Schema migration strategy | Edit `V1__init.sql` in place. User wipes dev DB. |
| Agent config fetch with no/unknown env | Return `404 Not Found`. No `"default"` fallback. |
| `cameleer-common` `ApplicationConfig` model | Add `environment` field in-place; agent team coordinates the bump (SNAPSHOT). |
| Agent registration without `environmentId` | Return `400 Bad Request`. Registration MUST include env. |
| UI per-screen env display | Already covered by top-right global env indicator — no extra UI work. |

## Plan

### Phase 1 — PostgreSQL schema

1. Edit `cameleer-server-app/src/main/resources/db/migration/V1__init.sql`:
   - `application_config`: add `environment TEXT NOT NULL` column; change PK to `(application, environment)`.
   - `app_settings`: add `environment TEXT NOT NULL` column; change PK to `(application_id, environment)`.
2. Commit message MUST call out: "Wipe dev DB before deploying — Flyway V1 checksum changes."

### Phase 2 — Shared model (`cameleer-common`)

3. **`ApplicationConfig` stays untouched on the server side.** The agent team is adding `environment` to the common class separately; the server doesn't depend on it. On the server, `environment` flows as a sidecar parameter through repositories/controllers and as a dedicated `environment` column on `application_config`. The stored JSON body contains only the config content. If/when the field appears in the common class, we'll hydrate it from the DB column into the returned DTO — no code change needed today.
4. Add `environment` field to `AppSettings` record in `cameleer-server-core` (`admin/AppSettings.java`). **Done.**

### Phase 3 — Repositories

5. `PostgresApplicationConfigRepository`:
   - `findByApplicationAndEnvironment(String app, String env)` replaces `findByApplication(app)`.
   - `findAll(String env)` (env required) replaces `findAll()`.
   - `save(String app, String env, ApplicationConfig, String updatedBy)` replaces `save(app, config, updatedBy)`.
   - Keep behaviour identical except for the PK.
6. `AppSettingsRepository` interface (core) and `PostgresAppSettingsRepository` (app) — same treatment with `(applicationId, environment)`.

### Phase 4 — REST controllers

7. `ApplicationConfigController`:
   - `getConfig(@PathVariable app)`: dual-mode by caller role. For AGENT role → env taken from JWT `env` claim, query param ignored (agents cannot spoof env). For non-agent callers (admin UI, with user JWTs whose `env="default"` is a placeholder) → env must be passed via `?environment=` query param. If neither produces a value → **404**.
   - `updateConfig(@PathVariable app, @RequestParam String environment, ...)`: make `environment` required. Forward to repo save. SSE push already env-scoped — keep.
   - `listConfigs(@RequestParam String environment)`: require env; filter.
   - `getProcessorRouteMapping(@PathVariable app, @RequestParam String environment)`: require env; forward to ClickHouse.
   - `testExpression(@PathVariable app, @RequestParam String environment, ...)`: make env required (already accepted as optional — tighten).
8. `AppSettingsController`:
   - `GET /api/v1/admin/app-settings?environment=`: list filtered.
   - `GET /api/v1/admin/app-settings/{appId}?environment=`: require env.
   - `PUT /api/v1/admin/app-settings/{appId}?environment=`: require env.
9. `SensitiveKeysAdminController`: review — global sensitive keys are server-wide (one row in `server_config`), no change needed. Add code comment clarifying env-wide push is intentional.
10. `SearchController.stats`: the SLA threshold lookup `appSettingsRepository.findByApplicationId(app)` becomes env-aware via the existing `environment` query param.

### Phase 5 — Storage

11. `ClickHouseDiagramStore.findProcessorRouteMapping(app)` → `findProcessorRouteMapping(app, env)`. Include `environment = ?` in `WHERE`.

### Phase 6 — JWT surface

12. Expose `env` claim via Spring `Authentication` principal — simplest path is a small custom `AuthenticationPrincipal` or `@RequestAttribute("env")` populated by `JwtAuthenticationFilter`. Keep scope minimal; only `ApplicationConfigController.getConfig` needs it directly for the 404 rule.

### Phase 7 — Agent registration hardening

13. `AgentRegistrationController.register`:
    - If `request.environmentId()` is null or blank → `400 Bad Request` with an explicit error message. Drop the `"default"` fallback on line 122.
    - Log the rejection (agent identity + remote IP) at INFO for diagnostics.
14. `AgentRegistrationController.refreshToken`: remove the `"default"` fallback at line 211 (dead after Phase 7.13, but harmless to clean up).
15. `AgentRegistrationController.heartbeat`: already falls back to JWT claim; after Phase 7.13 every JWT has a real env, so the `"default"` fallback at line 247 is dead code — remove.

### Phase 8 — UI queries

16. `ui/src/api/queries/dashboard.ts`: `useAppSettings(appId)` → `useAppSettings(appId, environment)`; same for `useAllAppSettings()`. Pull env from `useEnvironmentStore`.
17. `ui/src/api/queries/commands.ts`: verify `useApplicationConfig(appId)` / `useUpdateApplicationConfig` already pass env. Add if missing. (Audit pass only, may be no-op.)
18. Verify no other UI hook fetches per-app state without env.

### Phase 9 — Tests

19. Integration: write config for `(app=X, env=dev)`; read for `(app=X, env=prod)` returns empty/default.
20. Integration: agent JWT with `env=dev` calling `GET /api/v1/config/X` returns the dev config row. JWT with no env claim → 404.
21. Integration: `POST /api/v1/agents/register` with no `environmentId` → 400.
22. Unit: `AppSettingsRepository` env-isolation test.

### Phase 10 — Documentation

23. `CLAUDE.md`:
    - "Storage" section: update `application_config` and `app_settings` PK description.
    - Agent lifecycle section: note that registration requires `environmentId` (was optional, defaulted to `"default"`).
    - Remove the "priority: heartbeat `environmentId` > JWT `env` claim > `"default"`" note — after fix, every agent has a real env on every path.
24. `.claude/rules/app-classes.md`:
    - `ApplicationConfigController` — reflect env-required endpoints.
    - `AppSettingsController` — reflect env-required endpoints.
    - `AgentRegistrationController` — note env required.
25. `.claude/rules/core-classes.md`:
    - `PostgresApplicationConfigRepository`, `PostgresAppSettingsRepository` — updated signatures.

## Execution order

Phases are mostly sequential by dependency: 1 → 2 → 3 → (4, 5 in parallel) → 6 → 7 → 8 → 9 → 10. Phase 6 (JWT surfacing) is a small dependency for Phase 4 controller changes; do them together.

## Verification

- `mvn clean verify` passes.
- `detect_changes` scope matches the files touched per phase.
- Manual: spin up two envs (`dev` + `prod`) locally; configure tap in `dev`; confirm `prod` agent doesn't receive it and its DB row is untouched.
- Manual: stop an agent without env in the registration payload; confirm server returns 400.

## Out of scope / follow-ups

- `audit_log` has no `environment` column; filtering audit by env would be nice-to-have but not a correctness issue. Defer.
- Agent bootstrap-token scoping to env (so a dev token can't register as prod) — security hardening for after 1.0.