fix(server): route evaluator and observability auth through framework

Author: abhinav-galileo

docs/auth.md

@@ -17,6 +17,9 @@ policies.update
 agents.read
 agents.create
 agents.update
+evaluators.read
+observability.read
+observability.write
 control_bindings.read
 control_bindings.write
 runtime.token_exchange

server/src/agent_control_server/auth_framework/core.py

@@ -55,6 +55,9 @@ class Operation(StrEnum):
     AGENTS_READ = "agents.read"
     AGENTS_CREATE = "agents.create"
     AGENTS_UPDATE = "agents.update"
+    EVALUATORS_READ = "evaluators.read"
+    OBSERVABILITY_READ = "observability.read"
+    OBSERVABILITY_WRITE = "observability.write"
     RUNTIME_USE = "runtime.use"
 
 
@@ -109,8 +112,7 @@ async def authorize(
         request: Request,
         operation: Operation,
         context: dict[str, Any] | None = None,
-    ) -> Principal:
-        ...
+    ) -> Principal: ...
 
 
 _default_authorizer: RequestAuthorizer | None = None

server/src/agent_control_server/auth_framework/providers/header.py

@@ -48,6 +48,9 @@ class AccessLevel(Enum):
     Operation.AGENTS_READ: AccessLevel.AUTHENTICATED,
     Operation.AGENTS_CREATE: AccessLevel.AUTHENTICATED,
     Operation.AGENTS_UPDATE: AccessLevel.ADMIN,
+    Operation.EVALUATORS_READ: AccessLevel.AUTHENTICATED,
+    Operation.OBSERVABILITY_READ: AccessLevel.AUTHENTICATED,
+    Operation.OBSERVABILITY_WRITE: AccessLevel.AUTHENTICATED,
     Operation.RUNTIME_TOKEN_EXCHANGE: AccessLevel.AUTHENTICATED,
     Operation.RUNTIME_USE: AccessLevel.AUTHENTICATED,
 }

server/src/agent_control_server/endpoints/evaluators.py

@@ -3,9 +3,11 @@
 from typing import Any
 
 from agent_control_engine import list_evaluators
-from fastapi import APIRouter
+from fastapi import APIRouter, Depends
 from pydantic import BaseModel, Field
 
+from ..auth_framework import Operation, require_operation
+
 router = APIRouter(prefix="/evaluators", tags=["evaluators"])
 
 
@@ -25,6 +27,7 @@ class EvaluatorInfo(BaseModel):
     response_model=dict[str, EvaluatorInfo],
     summary="List available evaluators",
     response_description="Dictionary of evaluator name to evaluator info",
+    dependencies=[Depends(require_operation(Operation.EVALUATORS_READ))],
 )
 async def get_evaluators() -> dict[str, EvaluatorInfo]:
     """List all available evaluators.

server/src/agent_control_server/endpoints/observability.py

@@ -5,7 +5,7 @@
 2. Event queries (POST /events/query) - Query raw events by trace_id, etc.
 3. Stats (GET /stats) - Aggregated statistics for dashboards
 
-All endpoints require API key authentication.
+All endpoints declare operation-based auth dependencies.
 
 Dependencies are stored on app.state during server lifespan (see main.py):
 - app.state.event_ingestor: EventIngestor
@@ -27,7 +27,7 @@
 )
 from fastapi import APIRouter, Depends, Request
 
-from ..auth import require_api_key
+from ..auth_framework import Operation, require_operation
 from ..observability.ingest.base import EventIngestor
 from ..observability.store.base import (
     EventStore,
@@ -42,7 +42,6 @@
 router = APIRouter(
     prefix="/observability",
     tags=["observability"],
-    dependencies=[Depends(require_api_key)],
 )
 
 
@@ -72,7 +71,12 @@ def get_event_store(request: Request) -> EventStore:
 # =============================================================================
 
 
-@router.post("/events", status_code=202, response_model=BatchEventsResponse)
+@router.post(
+    "/events",
+    status_code=202,
+    response_model=BatchEventsResponse,
+    dependencies=[Depends(require_operation(Operation.OBSERVABILITY_WRITE))],
+)
 async def ingest_events(
     request: BatchEventsRequest,
     ingestor: EventIngestor = Depends(get_event_ingestor),
@@ -121,7 +125,11 @@ async def ingest_events(
 # =============================================================================
 
 
-@router.post("/events/query", response_model=EventQueryResponse)
+@router.post(
+    "/events/query",
+    response_model=EventQueryResponse,
+    dependencies=[Depends(require_operation(Operation.OBSERVABILITY_READ))],
+)
 async def query_events(
     request: EventQueryRequest,
     store: EventStore = Depends(get_event_store),
@@ -158,7 +166,11 @@ async def query_events(
 # =============================================================================
 
 
-@router.get("/stats", response_model=StatsResponse)
+@router.get(
+    "/stats",
+    response_model=StatsResponse,
+    dependencies=[Depends(require_operation(Operation.OBSERVABILITY_READ))],
+)
 async def get_stats(
     agent_name: str,
     time_range: TimeRange = "5m",
@@ -207,7 +219,11 @@ async def get_stats(
     )
 
 
-@router.get("/stats/controls/{control_id}", response_model=ControlStatsResponse)
+@router.get(
+    "/stats/controls/{control_id}",
+    response_model=ControlStatsResponse,
+    dependencies=[Depends(require_operation(Operation.OBSERVABILITY_READ))],
+)
 async def get_control_stats(
     control_id: int,
     agent_name: str,
@@ -266,7 +282,10 @@ async def get_control_stats(
 # =============================================================================
 
 
-@router.get("/status")
+@router.get(
+    "/status",
+    dependencies=[Depends(require_operation(Operation.OBSERVABILITY_READ))],
+)
 async def get_status(request: Request) -> dict:
     """
     Get observability system status.

server/src/agent_control_server/main.py

@@ -17,7 +17,7 @@
 from starlette_exporter import PrometheusMiddleware, handle_metrics
 
 from . import __version__ as server_version
-from .auth import get_api_key_from_header, require_api_key
+from .auth import get_api_key_from_header
 from .config import observability_settings, settings
 from .db import AsyncSessionLocal
 from .endpoints.agents import router as agent_router
@@ -314,17 +314,16 @@ async def attach_version_header(request, call_next):  # type: ignore[no-untyped-
     dependencies=[Depends(get_api_key_from_header)],
 )
 
-# Evaluator discovery still uses the local credential dependency.
 app.include_router(
     evaluator_router,
     prefix=api_v1_prefix,
-    dependencies=[Depends(require_api_key)],
+    dependencies=[Depends(get_api_key_from_header)],
 )
 
-# Observability routes (already has auth dependency in router)
 app.include_router(
     observability_router,
     prefix=api_v1_prefix,
+    dependencies=[Depends(get_api_key_from_header)],
 )
 
 # System routes (config, login, logout) - no auth required

server/tests/test_auth.py

@@ -1,16 +1,36 @@
 """Tests for API key authentication."""
 
 import uuid
+from typing import Any
 
 import pytest
+from fastapi import Request
 from fastapi.testclient import TestClient
 
 from agent_control_server import __version__ as server_version
+from agent_control_server.auth_framework import Operation, Principal, set_authorizer
 from agent_control_server.config import auth_settings
 
 from .utils import VALID_CONTROL_PAYLOAD
 
 
+class _RecordingAuthorizer:
+    """Test authorizer that records the operation requested by a route."""
+
+    def __init__(self) -> None:
+        self.calls: list[tuple[Operation, dict[str, Any] | None]] = []
+
+    async def authorize(
+        self,
+        request: Request,
+        operation: Operation,
+        context: dict[str, Any] | None = None,
+    ) -> Principal:
+        del request
+        self.calls.append((operation, context))
+        return Principal(namespace_key="default")
+
+
 class TestHealthEndpoint:
     """Health endpoint should always be accessible without authentication."""
 
@@ -40,9 +60,7 @@ class TestProtectedEndpoints:
     def test_missing_api_key_returns_401(self, unauthenticated_client: TestClient) -> None:
         """Given no API key, when requesting protected endpoint, then returns 401."""
         # When:
-        response = unauthenticated_client.get(
-            "/api/v1/agents/00000000-0000-0000-0000-000000000000"
-        )
+        response = unauthenticated_client.get("/api/v1/agents/00000000-0000-0000-0000-000000000000")
 
         # Then:
         assert response.status_code == 401
@@ -111,6 +129,20 @@ def test_missing_key_returns_401_on_evaluators(
         # Then:
         assert response.status_code == 401
 
+    def test_evaluators_use_auth_framework_provider(self, app: object) -> None:
+        """Given a custom authorizer, when listing evaluators, then route uses it."""
+        # Given:
+        authorizer = _RecordingAuthorizer()
+        set_authorizer(authorizer)
+        client = TestClient(app, raise_server_exceptions=True)
+
+        # When:
+        response = client.get("/api/v1/evaluators")
+
+        # Then:
+        assert response.status_code == 200
+        assert authorizer.calls == [(Operation.EVALUATORS_READ, None)]
+
 
 class TestAuthDisabled:
     """When auth is disabled, all requests should succeed."""
@@ -120,21 +152,15 @@ def disable_auth(self, monkeypatch: pytest.MonkeyPatch) -> None:
         """Disable auth for tests in this class."""
         monkeypatch.setattr(auth_settings, "api_key_enabled", False)
 
-    def test_no_key_allowed_when_disabled(
-        self, unauthenticated_client: TestClient
-    ) -> None:
+    def test_no_key_allowed_when_disabled(self, unauthenticated_client: TestClient) -> None:
         """Given auth disabled, when requesting without API key, then request succeeds."""
         # When:
-        response = unauthenticated_client.get(
-            "/api/v1/agents/00000000-0000-0000-0000-000000000000"
-        )
+        response = unauthenticated_client.get("/api/v1/agents/00000000-0000-0000-0000-000000000000")
 
         # Then: (404 for non-existent resource, but NOT 401)
         assert response.status_code == 404
 
-    def test_evaluators_accessible_when_disabled(
-        self, unauthenticated_client: TestClient
-    ) -> None:
+    def test_evaluators_accessible_when_disabled(self, unauthenticated_client: TestClient) -> None:
         """Given auth disabled, when listing evaluators without API key, then returns 200."""
         # When:
         response = unauthenticated_client.get("/api/v1/evaluators")
@@ -264,9 +290,7 @@ def test_admin_key_allowed_on_representative_mutations(self, admin_client: TestC
         init_response = admin_client.post("/api/v1/agents/initAgent", json=init_payload)
         assert init_response.status_code == 200
 
-        set_policy_response = admin_client.post(
-            f"/api/v1/agents/{agent_name}/policy/{policy_id}"
-        )
+        set_policy_response = admin_client.post(f"/api/v1/agents/{agent_name}/policy/{policy_id}")
         assert set_policy_response.status_code == 200
 
 
@@ -344,9 +368,7 @@ def setup_no_keys(self, monkeypatch: pytest.MonkeyPatch) -> None:
     def test_misconfigured_returns_500(self, unauthenticated_client: TestClient) -> None:
         """Given auth enabled but no keys configured, when requesting, then returns 500."""
         # When:
-        response = unauthenticated_client.get(
-            "/api/v1/agents/00000000-0000-0000-0000-000000000000"
-        )
+        response = unauthenticated_client.get("/api/v1/agents/00000000-0000-0000-0000-000000000000")
 
         # Then:
         assert response.status_code == 500
@@ -360,6 +382,7 @@ class TestOptionalApiKey:
 
     def _make_optional_app(self) -> TestClient:
         from fastapi import Depends, FastAPI
+
         from agent_control_server.auth import optional_api_key
 
         app = FastAPI()
@@ -374,7 +397,9 @@ def maybe_auth(client=Depends(optional_api_key)) -> dict[str, object]:
 
         return TestClient(app)
 
-    def test_optional_api_key_auth_disabled_returns_none(self, monkeypatch: pytest.MonkeyPatch) -> None:
+    def test_optional_api_key_auth_disabled_returns_none(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
         # Given: auth disabled
         monkeypatch.setattr(auth_settings, "api_key_enabled", False)
 
@@ -386,7 +411,9 @@ def test_optional_api_key_auth_disabled_returns_none(self, monkeypatch: pytest.M
         assert response.status_code == 200
         assert response.json()["auth"] is False
 
-    def test_optional_api_key_missing_header_returns_none(self, monkeypatch: pytest.MonkeyPatch) -> None:
+    def test_optional_api_key_missing_header_returns_none(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
         # Given: auth enabled with configured keys
         monkeypatch.setattr(auth_settings, "api_key_enabled", True)
         monkeypatch.setattr(auth_settings, "api_keys", "user-key")
@@ -402,7 +429,9 @@ def test_optional_api_key_missing_header_returns_none(self, monkeypatch: pytest.
         assert response.status_code == 200
         assert response.json()["auth"] is False
 
-    def test_optional_api_key_invalid_header_returns_none(self, monkeypatch: pytest.MonkeyPatch) -> None:
+    def test_optional_api_key_invalid_header_returns_none(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
         # Given: auth enabled with configured keys
         monkeypatch.setattr(auth_settings, "api_key_enabled", True)
         monkeypatch.setattr(auth_settings, "api_keys", "user-key")
@@ -418,7 +447,9 @@ def test_optional_api_key_invalid_header_returns_none(self, monkeypatch: pytest.
         assert response.status_code == 200
         assert response.json()["auth"] is False
 
-    def test_optional_api_key_admin_header_sets_admin(self, monkeypatch: pytest.MonkeyPatch) -> None:
+    def test_optional_api_key_admin_header_sets_admin(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
         # Given: auth enabled with admin key
         monkeypatch.setattr(auth_settings, "api_key_enabled", True)
         monkeypatch.setattr(auth_settings, "api_keys", "user-key")
@@ -449,6 +480,7 @@ def test_require_admin_key_rejects_non_admin(
 
         # When: requiring admin key on an endpoint
         from fastapi import Depends, FastAPI
+
         from agent_control_server.auth import require_admin_key
 
         local_app = FastAPI()
@@ -483,6 +515,7 @@ def test_authenticated_client_key_id_masks_short_key(self) -> None:
     def test_get_api_key_from_header_extracts_value(self) -> None:
         # Given: a route that returns raw API key header
         from fastapi import Depends, FastAPI
+
         from agent_control_server.auth import get_api_key_from_header
 
         app = FastAPI()
@@ -503,6 +536,7 @@ def raw_key(key: str | None = Depends(get_api_key_from_header)) -> dict[str, str
     def test_get_api_key_from_header_allows_missing(self) -> None:
         # Given: a route that returns raw API key header
         from fastapi import Depends, FastAPI
+
         from agent_control_server.auth import get_api_key_from_header
 
         app = FastAPI()