cleanup(basilica): remove dashboard runtime-key injection (closes #245) (#247)

The `_inject_runtime_key_into_dashboard()` helper and the README's
"Dashboard wiring follow-up" caveat promised that
`LLMTRACE_AUTH_RUNTIME_KEY` would be consumed by a future dashboard
change. Post-merge investigation showed the dashboard only calls the
proxy's `/api/v1/*` admin endpoints (`dashboard/src/lib/api.ts`,
`dashboard/src/lib/proxy-helpers.ts`); no code path consumes the
operator key. The injection was dead weight and the note misled future
contributors.

Changes:
- `lifecycle.py`: delete `_inject_runtime_key_into_dashboard()` and its
  call site in `provision()`; update docstrings to describe the actual
  two-tier model (admin key in dashboard env; operator key returned in
  `TenantInstances.api_key` for the tenant's external apps).
- `README.md`: rewrite the bootstrap step 6 and drop the "Dashboard
  wiring follow-up" caveat.
- `configs/examples/starter.yaml`: update the dashboard env comment.
- `tests/test_operator_key_minting.py`: replace the positive runtime-key
  assertion with a negative one (`LLMTRACE_AUTH_RUNTIME_KEY not in
  dash_create["env"]`) and convert the helper-injection test into an
  absence guard (`not hasattr(lifecycle, "_inject_runtime_key_into_dashboard")`)
  so the contract is locked in.

Net deletion: dead code + misleading docs gone. All other lifecycle
behaviour (operator key minted and returned, admin key returned,
tenant bootstrap) is untouched.

Author: epappas

deployments/basilica/README.md

@@ -334,9 +334,13 @@ issues TWO keys with distinct scopes:
 5. Calls `POST /api/v1/auth/keys` (auth: admin key, scoped to that
    tenant UUID) with body `{name: "tenant-runtime", role: "operator",
    tenant_id: <uuid>}` and captures the plaintext operator key.
-6. Adds `LLMTRACE_AUTH_RUNTIME_KEY=<operator_key>` to the dashboard env
-   (informational today; consumed by a follow-up dashboard wiring
-   change) and creates the dashboard deployment.
+6. Creates the dashboard deployment. The dashboard env carries the
+   admin key (its only consumer today is the proxy's `/api/v1/*` admin
+   endpoints — see `dashboard/src/lib/api.ts`,
+   `dashboard/src/lib/proxy-helpers.ts`). The operator key is **not**
+   injected into the dashboard env because no dashboard code path
+   consumes it; it is returned to the caller for the tenant's external
+   apps to use against `/v1/*` runtime traffic.
 7. Returns `TenantInstances(api_key=<operator>, admin_key=<admin>)`.
 
 Both plaintext keys are exposed only at this moment. Persist them
@@ -418,12 +422,6 @@ without any control-plane scope. See
 
 ### Caveats and follow-ups
 
-- **Dashboard wiring follow-up**: the Next.js dashboard
-  (`dashboard/src/lib/api.ts`, `dashboard/src/lib/proxy-helpers.ts`)
-  currently only reads `LLMTRACE_AUTH_ADMIN_KEY`. The lifecycle layer
-  injects `LLMTRACE_AUTH_RUNTIME_KEY` informationally; a separate PR
-  should switch the dashboard to use the runtime key for tenant-facing
-  traffic and the admin key only for admin pages.
 - **Admin key rotation** is opt-in via `rotate_admin_after_bootstrap:
   true` in the tenant config — see the "Admin key rotation" section
   below. Without it the bootstrap admin key lives in the proxy env for

deployments/basilica/configs/examples/starter.yaml

@@ -65,11 +65,11 @@ dashboard:
     NODE_ENV: production
     # LLMTRACE_AUTH_ADMIN_KEY is set by the lifecycle library at provision
     # time to match the proxy's resolved admin key (used by dashboard
-    # server-side handlers for admin endpoints). LLMTRACE_AUTH_RUNTIME_KEY
-    # is set after the operator key is minted — dashboard wiring to
-    # consume the runtime key for tenant-facing traffic is a follow-up.
-    # If you set either var here explicitly, that value wins for the
-    # dashboard env.
+    # server-side handlers for admin endpoints). The operator key minted
+    # for tenant runtime traffic is returned in TenantInstances.api_key
+    # and is NOT injected into the dashboard env — no dashboard code
+    # path consumes it today. If you set LLMTRACE_AUTH_ADMIN_KEY here
+    # explicitly, that value wins for the dashboard env.
 
 # Optional — override if your tenant naming scheme differs.
 # proxy_name_template: "llmtrace-proxy-{tenant_id}"

deployments/basilica/lifecycle.py

@@ -426,9 +426,10 @@ def _apply_proxy_auth(
     can still talk to the proxy's admin endpoints (key management,
     tenant CRUD) on behalf of the portal/self-service UI;
     `LLMTRACE_AUTH_ENABLED` is only defaulted (caller may explicitly turn
-    it off in env). The operator key (`LLMTRACE_AUTH_RUNTIME_KEY`) is
-    injected later in `_inject_runtime_key_into_dashboard` once the proxy
-    is live and the key has been minted.
+    it off in env). The operator key is returned to the caller in
+    `TenantInstances.api_key` for tenant runtime apps to use against
+    `/v1/*`; it is intentionally NOT injected into the dashboard env
+    because no dashboard code path consumes it today.
     """
     proxy_env = {**proxy_spec.env, "LLMTRACE_AUTH_ADMIN_KEY": admin_key}
     proxy_env.setdefault("LLMTRACE_AUTH_ENABLED", "true")
@@ -493,22 +494,6 @@ def _apply_rate_limit(
     return dataclasses.replace(proxy_spec, env=proxy_env)
 
 
-def _inject_runtime_key_into_dashboard(
-    dashboard_spec: ComponentSpec, operator_key: str
-) -> ComponentSpec:
-    """Add `LLMTRACE_AUTH_RUNTIME_KEY=<operator_key>` to the dashboard env.
-
-    NOTE: as of this PR the Next.js dashboard only reads
-    `LLMTRACE_AUTH_ADMIN_KEY` (`dashboard/src/lib/api.ts`,
-    `dashboard/src/lib/proxy-helpers.ts`). The runtime variable is set
-    informationally so the dashboard wiring follow-up (consume the
-    operator key for tenant-facing traffic, fall back to admin only for
-    admin pages) is a pure dashboard change with no platform side.
-    """
-    env = {**dashboard_spec.env, "LLMTRACE_AUTH_RUNTIME_KEY": operator_key}
-    return dataclasses.replace(dashboard_spec, env=env)
-
-
 def _admin_http_request(
     proxy_url: str,
     path: str,
@@ -750,9 +735,10 @@ def provision(
        tenant row (the operator-key mint requires the tenant to exist).
     4. Calls `POST /api/v1/auth/keys` to mint a scoped Operator-role key
        named `tenant-runtime`. This is the key the tenant gets.
-    5. Injects the operator key into the dashboard env as
-       `LLMTRACE_AUTH_RUNTIME_KEY` (informational; dashboard consumption
-       is a follow-up), then deploys the dashboard.
+    5. Deploys the dashboard. Only the admin key is in the dashboard env
+       because the dashboard's only call path today is the proxy's admin
+       endpoints; the operator key is returned to the caller for the
+       tenant's external runtime apps.
 
     Returns both keys: `api_key` is the operator key (runtime traffic);
     `admin_key` is the bootstrap admin key (retained by the caller for
@@ -796,9 +782,6 @@ def provision(
 
         tenant_uuid = _bootstrap_tenant_in_proxy(proxy.url, admin_key, tenant_id)
         operator_key = _mint_operator_key(proxy.url, admin_key, tenant_uuid)
-        dashboard_spec = _inject_runtime_key_into_dashboard(
-            dashboard_spec, operator_key
-        )
 
     if spec.inject_proxy_url_into_dashboard:
         merged_env = {**dashboard_spec.env, spec.proxy_url_env_var: proxy.url}

deployments/basilica/tests/test_operator_key_minting.py

@@ -321,12 +321,15 @@ def _make_dashboard_spec(env: Optional[dict[str, str]] = None) -> lifecycle.Comp
     )
 
 
-def test_inject_runtime_key_adds_var_without_dropping_existing() -> None:
-    spec = _make_dashboard_spec({"HOSTNAME": "0.0.0.0", "LLMTRACE_AUTH_ADMIN_KEY": ADMIN_KEY})
-    updated = lifecycle._inject_runtime_key_into_dashboard(spec, OPERATOR_KEY)
-    assert updated.env["HOSTNAME"] == "0.0.0.0"
-    assert updated.env["LLMTRACE_AUTH_ADMIN_KEY"] == ADMIN_KEY
-    assert updated.env["LLMTRACE_AUTH_RUNTIME_KEY"] == OPERATOR_KEY
+def test_inject_runtime_key_helper_is_absent() -> None:
+    """Lock in that the dashboard does NOT receive the operator key.
+
+    The runtime-key-injection helper was removed (issue #245) because
+    no dashboard call path consumes the operator key; the dashboard
+    only talks to the proxy's admin endpoints with the admin key. This
+    test guards against re-introducing the dead-weight injection.
+    """
+    assert not hasattr(lifecycle, "_inject_runtime_key_into_dashboard")
 
 
 def test_apply_proxy_auth_sets_admin_key_on_both_sides() -> None:
@@ -495,10 +498,11 @@ def responder(method: str, path: str, headers: dict[str, str], body: bytes) -> t
     assert proxy_create["env"]["LLMTRACE_AUTH_ADMIN_KEY"] == ADMIN_KEY
     assert proxy_create["env"]["LLMTRACE_AUTH_ENABLED"] == "true"
 
-    # Verify dashboard was created with BOTH admin and runtime keys in env.
+    # Verify dashboard was created with the admin key in env, and NOT the
+    # operator (runtime) key — no dashboard code path consumes it (issue #245).
     dash_create = next(c for c in fake_client.creates if "dashboard" in c["instance_name"])
     assert dash_create["env"]["LLMTRACE_AUTH_ADMIN_KEY"] == ADMIN_KEY
-    assert dash_create["env"]["LLMTRACE_AUTH_RUNTIME_KEY"] == OPERATOR_KEY
+    assert "LLMTRACE_AUTH_RUNTIME_KEY" not in dash_create["env"]
 
 
 def test_provision_skips_key_flow_when_proxy_auth_disabled(fake_proxy: Any) -> None: